1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* Copyright by The HDF Group. *
* All rights reserved. *
* *
* This file is part of HDF5. The full HDF5 copyright notice, including *
* terms governing use, modification, and redistribution, is contained in *
* the COPYING file, which can be found at the root of the source code *
* distribution tree, or in https://support.hdfgroup.org/ftp/HDF5/releases. *
* If you do not have access to either file, you may request a copy from *
* help@hdfgroup.org. *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/* Purpose: The public header file for the subfiling driver. */
#ifndef H5FDsubfiling_H
#define H5FDsubfiling_H
#include "H5FDioc.h"
#ifdef H5_HAVE_SUBFILING_VFD
#define H5FD_SUBFILING (H5FDperform_init(H5FD_subfiling_init))
#else
#define H5FD_SUBFILING (H5I_INVALID_HID)
#endif
#define H5FD_SUBFILING_NAME "subfiling"
#ifdef H5_HAVE_SUBFILING_VFD
#ifndef H5FD_SUBFILING_FAPL_MAGIC
#define H5FD_CURR_SUBFILING_FAPL_VERSION 1
#define H5FD_SUBFILING_FAPL_MAGIC 0xFED01331
#endif
/****************************************************************************
*
* Structure: H5FD_subfiling_config_t
*
* Purpose:
*
* H5FD_subfiling_config_t is a public structure that is used to pass
* subfiling configuration data to the appropriate subfiling VFD via
* the FAPL. A pointer to an instance of this structure is a parameter
* to H5Pset_fapl_subfiling() and H5Pget_fapl_subfiling().
*
* `magic` (uint32_t)
*
* Magic is a somewhat unique number which identifies this VFD from
* other VFDs. Used in combination with a version number, we can
* validate a user generated file access property list (fapl).
* This field should be set to H5FD_SUBFILING_FAPL_MAGIC.
*
* `version` (uint32_t)
*
* Version number of the H5FD_subfiling_config_t structure. Any instance
* passed to the above calls must have a recognized version number, or
* an error will be flagged.
*
* This field should be set to H5FD_CURR_SUBFILING_FAPL_VERSION.
*
*** IO Concentrator Info ***
*** These fields will be replicated in the stacked IOC VFD which
*** provides the extended support for aggregating reads and writes
*** and allows global file access to node-local storage containers.
*
* `stripe_count` (int32_t)
*
* The integer value which identifies the total number of
* subfiles that have been algorithmically been selected to
* to contain the segments of raw data which make up an HDF5
* file. This value is used to implement the RAID-0 functionality
* when reading or writing datasets.
*
* `stripe_depth` (int64_t)
*
* The stripe depth defines a limit on the maximum number of contiguous
* bytes that can be read or written in a single operation on any
* selected subfile. Larger IO operations can exceed this limit
* by utilizing MPI derived types to construct an IO request which
* gathers additional data segments from memory for the IO request.
*
* `ioc_selection` (enum io_selection datatype)
*
* The io_selection_t defines a specific algorithm by which IO
* concentrators (IOCs) and sub-files are identified. The available
* algorithms are: SELECT_IOC_ONE_PER_NODE, SELECT_IOC_EVERY_NTH_RANK,
* SELECT_IOC_WITH_CONFIG, and SELECT_IOC_TOTAL.
*
*** STACKING and other VFD support
*** i.e. FAPL caching
***
*
* `ioc_fapl_id` (hid_t)
*
* A valid file access property list (fapl) is cached on each
* process and thus enables selection of an alternative provider
* for subsequent file operations.
* By default, Sub-filing employs an additional support VFD that
* provides file IO proxy capabilities to all MPI ranks in a
* distributed parallel application. This IO indirection
* thus allows application access all sub-files even while
* these may actually be node-local and thus not directly
* accessible to remote ranks.
*
****************************************************************************/
/*
* In addition to the common configuration fields, we can have
* VFD specific fields. Here's one for the subfiling VFD.
*
* `require_ioc` (hbool_t)
*
* Require_IOC is a boolean flag with a default value of TRUE.
* This flag indicates that the stacked H5FDioc VFD should be
* employed for sub-filing operations. The default flag can be
* overridden with an environment variable: H5_REQUIRE_IOC=0
*
*/
//! <!-- [H5FD_subfiling_config_t_snip] -->
/**
* Configuration structure for H5Pset_fapl_subfiling() / H5Pget_fapl_subfiling()
*/
typedef struct H5FD_subfiling_config_t {
uint32_t magic; /* set to H5FD_SUBFILING_FAPL_MAGIC */
uint32_t version; /* set to H5FD_CURR_SUBFILING_FAPL_VERSION */
int32_t stripe_count; /* How many io concentrators */
int64_t stripe_depth; /* Max # of bytes in contiguous IO to an IOC */
ioc_selection_t ioc_selection; /* Method to select IO Concentrators */
hid_t ioc_fapl_id; /* The hid_t value of the stacked VFD */
hbool_t require_ioc;
} H5FD_subfiling_config_t;
//! <!-- [H5FD_subfiling_config_t_snip] -->
#ifdef __cplusplus
extern "C" {
#endif
H5_DLL hid_t H5FD_subfiling_init(void);
/**
* \ingroup FAPL
*
* \brief Modifies the file access property list to use the #H5FD_SUBFILING driver
*
* \fapl_id
* \param[in] vfd_config #H5FD_SUBFILING driver specific properties. If NULL, then
* the IO concentrator VFD will be used.
* \returns \herr_t
*
* \details H5Pset_fapl_core() modifies the file access property list to use the
* #H5FD_SUBFILING driver.
*
* \todo Expand details!
*
* \since 1.14.0
*
*/
H5_DLL herr_t H5Pset_fapl_subfiling(hid_t fapl_id, H5FD_subfiling_config_t *vfd_config);
/**
* \ingroup FAPL
*
* \brief Queries subfiling file driver properties
*
* \fapl_id
* \param[out] config_out The subfiling fapl data.
*
* \returns \herr_t
*
* \details H5Pget_fapl_subfiling() queries the #H5FD_SUBFILING driver properties as set
* by H5Pset_fapl_subfiling(). If the #H5FD_SUBFILING driver has not been set on
* the File Access Property List, a default configuration is returned.
*
* \since 1.14.0
*
*/
H5_DLL herr_t H5Pget_fapl_subfiling(hid_t fapl_id, H5FD_subfiling_config_t *config_out);
#ifdef __cplusplus
}
#endif
#endif /* H5_HAVE_SUBFILING_VFD */
#endif /* H5FDsubfiling_H */
|
