1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 2 * Copyright by The HDF Group. * 3 * Copyright by the Board of Trustees of the University of Illinois. * 4 * All rights reserved. * 5 * * 6 * This file is part of HDF5. The full HDF5 copyright notice, including * 7 * terms governing use, modification, and redistribution, is contained in * 8 * the files COPYING and Copyright.html. COPYING can be found at the root * 9 * of the source code distribution tree; Copyright.html can be found at the * 10 * root level of an installed copy of the electronic HDF5 document set and * 11 * is linked from the top-level documents page. It can also be found at * 12 * http://hdfgroup.org/HDF5/doc/Copyright.html. If you do not have * 13 * access to either file, you may request a copy from help@hdfgroup.org. * 14 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 15 16 /* 17 * Programmer: Robb Matzke <matzke@llnl.gov> 18 * Monday, July 26, 1999 19 */ 20 #ifndef _H5FDpublic_H 21 #define _H5FDpublic_H 22 23 #include "H5public.h" 24 #include "H5Fpublic.h" /*for H5F_close_degree_t */ 25 26 #define H5_HAVE_VFL 1 /*define a convenient app feature test*/ 27 #define H5FD_VFD_DEFAULT 0 /* Default VFL driver value */ 28 29 /* Types of allocation requests: see H5Fpublic.h */ 30 typedef enum H5F_mem_t H5FD_mem_t; 31 32 /* Map "fractal heap" header blocks to 'ohdr' type file memory, since its 33 * a fair amount of work to add a new kind of file memory and they are similar 34 * enough to object headers and probably too minor to deserve their own type. 35 * 36 * Map "fractal heap" indirect blocks to 'ohdr' type file memory, since they 37 * are similar to fractal heap header blocks. 38 * 39 * Map "fractal heap" direct blocks to 'lheap' type file memory, since they 40 * will be replacing local heaps. 41 * 42 * Map "fractal heap" 'huge' objects to 'draw' type file memory, since they 43 * represent large objects that are directly stored in the file. 44 * 45 * -QAK 46 */ 47 #define H5FD_MEM_FHEAP_HDR H5FD_MEM_OHDR 48 #define H5FD_MEM_FHEAP_IBLOCK H5FD_MEM_OHDR 49 #define H5FD_MEM_FHEAP_DBLOCK H5FD_MEM_LHEAP 50 #define H5FD_MEM_FHEAP_HUGE_OBJ H5FD_MEM_DRAW 51 52 /* Map "free space" header blocks to 'ohdr' type file memory, since its 53 * a fair amount of work to add a new kind of file memory and they are similar 54 * enough to object headers and probably too minor to deserve their own type. 55 * 56 * Map "free space" serialized sections to 'lheap' type file memory, since they 57 * are similar enough to local heap info. 58 * 59 * -QAK 60 */ 61 #define H5FD_MEM_FSPACE_HDR H5FD_MEM_OHDR 62 #define H5FD_MEM_FSPACE_SINFO H5FD_MEM_LHEAP 63 64 /* Map "shared object header message" master table to 'ohdr' type file memory, 65 * since its a fair amount of work to add a new kind of file memory and they are 66 * similar enough to object headers and probably too minor to deserve their own 67 * type. 68 * 69 * Map "shared object header message" indices to 'btree' type file memory, 70 * since they are similar enough to B-tree nodes. 71 * 72 * -QAK 73 */ 74 #define H5FD_MEM_SOHM_TABLE H5FD_MEM_OHDR 75 #define H5FD_MEM_SOHM_INDEX H5FD_MEM_BTREE 76 77 /* 78 * A free-list map which maps all types of allocation requests to a single 79 * free list. This is useful for drivers that don't really care about 80 * keeping different requests segregated in the underlying file and which 81 * want to make most efficient reuse of freed memory. The use of the 82 * H5FD_MEM_SUPER free list is arbitrary. 83 */ 84 #define H5FD_FLMAP_SINGLE { \ 85 H5FD_MEM_SUPER, /*default*/ \ 86 H5FD_MEM_SUPER, /*super*/ \ 87 H5FD_MEM_SUPER, /*btree*/ \ 88 H5FD_MEM_SUPER, /*draw*/ \ 89 H5FD_MEM_SUPER, /*gheap*/ \ 90 H5FD_MEM_SUPER, /*lheap*/ \ 91 H5FD_MEM_SUPER /*ohdr*/ \ 92 } 93 94 /* 95 * A free-list map which segregates requests into `raw' or `meta' data 96 * pools. 97 */ 98 #define H5FD_FLMAP_DICHOTOMY { \ 99 H5FD_MEM_SUPER, /*default*/ \ 100 H5FD_MEM_SUPER, /*super*/ \ 101 H5FD_MEM_SUPER, /*btree*/ \ 102 H5FD_MEM_DRAW, /*draw*/ \ 103 H5FD_MEM_SUPER, /*gheap*/ \ 104 H5FD_MEM_SUPER, /*lheap*/ \ 105 H5FD_MEM_SUPER /*ohdr*/ \ 106 } 107 108 /* 109 * The default free list map which causes each request type to use it's own 110 * free-list. 111 */ 112 #define H5FD_FLMAP_DEFAULT { \ 113 H5FD_MEM_DEFAULT, /*default*/ \ 114 H5FD_MEM_DEFAULT, /*super*/ \ 115 H5FD_MEM_DEFAULT, /*btree*/ \ 116 H5FD_MEM_DEFAULT, /*draw*/ \ 117 H5FD_MEM_DEFAULT, /*gheap*/ \ 118 H5FD_MEM_DEFAULT, /*lheap*/ \ 119 H5FD_MEM_DEFAULT /*ohdr*/ \ 120 } 121 122 123 /* Define VFL driver features that can be enabled on a per-driver basis */ 124 /* These are returned with the 'query' function pointer in H5FD_class_t */ 125 /* 126 * Defining the H5FD_FEAT_AGGREGATE_METADATA for a VFL driver means that 127 * the library will attempt to allocate a larger block for metadata and 128 * then sub-allocate each metadata request from that larger block. 129 */ 130 #define H5FD_FEAT_AGGREGATE_METADATA 0x00000001 131 /* 132 * Defining the H5FD_FEAT_ACCUMULATE_METADATA for a VFL driver means that 133 * the library will attempt to cache metadata as it is written to the file 134 * and build up a larger block of metadata to eventually pass to the VFL 135 * 'write' routine. 136 * 137 * Distinguish between updating the metadata accumulator on writes and 138 * reads. This is particularly (perhaps only, even) important for MPI-I/O 139 * where we guarantee that writes are collective, but reads may not be. 140 * If we were to allow the metadata accumulator to be written during a 141 * read operation, the application would hang. 142 */ 143 #define H5FD_FEAT_ACCUMULATE_METADATA_WRITE 0x00000002 144 #define H5FD_FEAT_ACCUMULATE_METADATA_READ 0x00000004 145 #define H5FD_FEAT_ACCUMULATE_METADATA (H5FD_FEAT_ACCUMULATE_METADATA_WRITE|H5FD_FEAT_ACCUMULATE_METADATA_READ) 146 /* 147 * Defining the H5FD_FEAT_DATA_SIEVE for a VFL driver means that 148 * the library will attempt to cache raw data as it is read from/written to 149 * a file in a "data seive" buffer. See Rajeev Thakur's papers: 150 * http://www.mcs.anl.gov/~thakur/papers/romio-coll.ps.gz 151 * http://www.mcs.anl.gov/~thakur/papers/mpio-high-perf.ps.gz 152 */ 153 #define H5FD_FEAT_DATA_SIEVE 0x00000008 154 /* 155 * Defining the H5FD_FEAT_AGGREGATE_SMALLDATA for a VFL driver means that 156 * the library will attempt to allocate a larger block for "small" raw data 157 * and then sub-allocate "small" raw data requests from that larger block. 158 */ 159 #define H5FD_FEAT_AGGREGATE_SMALLDATA 0x00000010 160 /* 161 * Defining the H5FD_FEAT_IGNORE_DRVRINFO for a VFL driver means that 162 * the library will ignore the driver info that is encoded in the file 163 * for the VFL driver. (This will cause the driver info to be eliminated 164 * from the file when it is flushed/closed, if the file is opened R/W). 165 */ 166 #define H5FD_FEAT_IGNORE_DRVRINFO 0x00000020 167 /* 168 * Defining the H5FD_FEAT_DIRTY_SBLK_LOAD for a VFL driver means that 169 * the library will mark the superblock dirty when the file is opened 170 * R/W. This will cause the driver info to be re-encoded when the file 171 * is flushed/closed. 172 */ 173 #define H5FD_FEAT_DIRTY_SBLK_LOAD 0x00000040 174 /* 175 * Defining the H5FD_FEAT_POSIX_COMPAT_HANDLE for a VFL driver means that 176 * the handle for the VFD (returned with the 'get_handle' callback) is 177 * of type 'int' and is compatible with POSIX I/O calls. 178 */ 179 #define H5FD_FEAT_POSIX_COMPAT_HANDLE 0x00000080 180 181 182 /* Forward declaration */ 183 typedef struct H5FD_t H5FD_t; 184 185 /* Class information for each file driver */ 186 typedef struct H5FD_class_t { 187 const char *name; 188 haddr_t maxaddr; 189 H5F_close_degree_t fc_degree; 190 hsize_t (*sb_size)(H5FD_t *file); 191 herr_t (*sb_encode)(H5FD_t *file, char *name/*out*/, 192 unsigned char *p/*out*/); 193 herr_t (*sb_decode)(H5FD_t *f, const char *name, const unsigned char *p); 194 size_t fapl_size; 195 void * (*fapl_get)(H5FD_t *file); 196 void * (*fapl_copy)(const void *fapl); 197 herr_t (*fapl_free)(void *fapl); 198 size_t dxpl_size; 199 void * (*dxpl_copy)(const void *dxpl); 200 herr_t (*dxpl_free)(void *dxpl); 201 H5FD_t *(*open)(const char *name, unsigned flags, hid_t fapl, 202 haddr_t maxaddr); 203 herr_t (*close)(H5FD_t *file); 204 int (*cmp)(const H5FD_t *f1, const H5FD_t *f2); 205 herr_t (*query)(const H5FD_t *f1, unsigned long *flags); 206 herr_t (*get_type_map)(const H5FD_t *file, H5FD_mem_t *type_map); 207 haddr_t (*alloc)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, hsize_t size); 208 herr_t (*free)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, 209 haddr_t addr, hsize_t size); 210 haddr_t (*get_eoa)(const H5FD_t *file, H5FD_mem_t type); 211 herr_t (*set_eoa)(H5FD_t *file, H5FD_mem_t type, haddr_t addr); 212 haddr_t (*get_eof)(const H5FD_t *file); 213 herr_t (*get_handle)(H5FD_t *file, hid_t fapl, void**file_handle); 214 herr_t (*read)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl, 215 haddr_t addr, size_t size, void *buffer); 216 herr_t (*write)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl, 217 haddr_t addr, size_t size, const void *buffer); 218 herr_t (*flush)(H5FD_t *file, hid_t dxpl_id, unsigned closing); 219 herr_t (*truncate)(H5FD_t *file, hid_t dxpl_id, hbool_t closing); 220 herr_t (*lock)(H5FD_t *file, unsigned char *oid, unsigned lock_type, hbool_t last); 221 herr_t (*unlock)(H5FD_t *file, unsigned char *oid, hbool_t last); 222 H5FD_mem_t fl_map[H5FD_MEM_NTYPES]; 223 } H5FD_class_t; 224 225 /* A free list is a singly-linked list of address/size pairs. */ 226 typedef struct H5FD_free_t { 227 haddr_t addr; 228 hsize_t size; 229 struct H5FD_free_t *next; 230 } H5FD_free_t; 231 232 /* 233 * The main datatype for each driver. Public fields common to all drivers 234 * are declared here and the driver appends private fields in memory. 235 */ 236 struct H5FD_t { 237 hid_t driver_id; /*driver ID for this file */ 238 const H5FD_class_t *cls; /*constant class info */ 239 unsigned long fileno; /* File 'serial' number */ 240 unsigned long feature_flags; /* VFL Driver feature Flags */ 241 haddr_t maxaddr; /* For this file, overrides class */ 242 haddr_t base_addr; /* Base address for HDF5 data w/in file */ 243 244 /* Space allocation management fields */ 245 hsize_t threshold; /* Threshold for alignment */ 246 hsize_t alignment; /* Allocation alignment */ 247 }; 248 249 #ifdef __cplusplus 250 extern "C" { 251 #endif 252 253 /* Function prototypes */ 254 H5_DLL hid_t H5FDregister(const H5FD_class_t *cls); 255 H5_DLL herr_t H5FDunregister(hid_t driver_id); 256 H5_DLL H5FD_t *H5FDopen(const char *name, unsigned flags, hid_t fapl_id, 257 haddr_t maxaddr); 258 H5_DLL herr_t H5FDclose(H5FD_t *file); 259 H5_DLL int H5FDcmp(const H5FD_t *f1, const H5FD_t *f2); 260 H5_DLL int H5FDquery(const H5FD_t *f, unsigned long *flags); 261 H5_DLL haddr_t H5FDalloc(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, hsize_t size); 262 H5_DLL herr_t H5FDfree(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, 263 haddr_t addr, hsize_t size); 264 H5_DLL haddr_t H5FDget_eoa(H5FD_t *file, H5FD_mem_t type); 265 H5_DLL herr_t H5FDset_eoa(H5FD_t *file, H5FD_mem_t type, haddr_t eoa); 266 H5_DLL haddr_t H5FDget_eof(H5FD_t *file); 267 H5_DLL herr_t H5FDget_vfd_handle(H5FD_t *file, hid_t fapl, void**file_handle); 268 H5_DLL herr_t H5FDread(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, 269 haddr_t addr, size_t size, void *buf/*out*/); 270 H5_DLL herr_t H5FDwrite(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, 271 haddr_t addr, size_t size, const void *buf); 272 H5_DLL herr_t H5FDflush(H5FD_t *file, hid_t dxpl_id, unsigned closing); 273 H5_DLL herr_t H5FDtruncate(H5FD_t *file, hid_t dxpl_id, hbool_t closing); 274 275 #ifdef __cplusplus 276 } 277 #endif 278 #endif 279 280