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: Quincey Koziol <koziol@ncsa.uiuc.edu> 18 * Thursday, September 28, 2000 19 * 20 * Purpose: This file contains declarations which are visible only within 21 * the H5F package. Source files outside the H5F package should 22 * include H5Fprivate.h instead. 23 */ 24 #ifndef H5F_PACKAGE 25 #error "Do not include this file outside the H5F package!" 26 #endif 27 28 #ifndef _H5Fpkg_H 29 #define _H5Fpkg_H 30 31 /* Get package's private header */ 32 #include "H5Fprivate.h" 33 34 /* Other public headers needed by this file */ 35 #include "H5Bpublic.h" /* B-tree header, for H5B_NUM_BTREE_ID */ 36 37 /* Other private headers needed by this file */ 38 #include "H5private.h" /* Generic Functions */ 39 #include "H5ACprivate.h" /* Metadata cache */ 40 #include "H5FLprivate.h" /* Free Lists */ 41 #include "H5FOprivate.h" /* File objects */ 42 #include "H5FSprivate.h" /* File free space */ 43 #include "H5Gprivate.h" /* Groups */ 44 #include "H5Oprivate.h" /* Object header messages */ 45 #include "H5RCprivate.h" /* Reference counted object functions */ 46 47 48 /* 49 * Feature: Define this constant on the compiler command-line if you want to 50 * see some debugging messages on the debug stream. 51 */ 52 #ifdef NDEBUG 53 # undef H5F_DEBUG 54 #endif 55 56 /* Define the HDF5 file signature */ 57 #define H5F_SIGNATURE "\211HDF\r\n\032\n" 58 #define H5F_SIGNATURE_LEN 8 59 60 /* Superblock status flags */ 61 #define H5F_SUPER_WRITE_ACCESS 0x01 62 #define H5F_SUPER_FILE_OK 0x02 63 #define H5F_SUPER_ALL_FLAGS (H5F_SUPER_WRITE_ACCESS | H5F_SUPER_FILE_OK) 64 65 /* Mask for removing private file access flags */ 66 #define H5F_ACC_PUBLIC_FLAGS 0x001fu 67 68 /* Free space section+aggregator merge flags */ 69 #define H5F_FS_MERGE_METADATA 0x01 /* Section can merge with metadata aggregator */ 70 #define H5F_FS_MERGE_RAWDATA 0x02 /* Section can merge with small 'raw' data aggregator */ 71 72 /* Macro to abstract checking whether file is using a free space manager */ 73 #define H5F_HAVE_FREE_SPACE_MANAGER(F) TRUE /* Currently always have a free space manager */ 74 75 /* Macros for encoding/decoding superblock */ 76 #define H5F_MAX_DRVINFOBLOCK_SIZE 1024 /* Maximum size of superblock driver info buffer */ 77 #define H5F_DRVINFOBLOCK_HDR_SIZE 16 /* Size of superblock driver info header */ 78 79 /* Superblock sizes for various versions */ 80 #define H5F_SIZEOF_CHKSUM 4 /* Checksum size in the file */ 81 82 /* Fixed-size portion at the beginning of all superblocks */ 83 #define H5F_SUPERBLOCK_FIXED_SIZE ( H5F_SIGNATURE_LEN \ 84 + 1) /* superblock version */ 85 86 /* Macros for computing variable-size superblock size */ 87 #define H5F_SUPERBLOCK_VARLEN_SIZE_COMMON \ 88 (2 /* freespace, and root group versions */ \ 89 + 1 /* reserved */ \ 90 + 3 /* shared header vers, size of address, size of lengths */ \ 91 + 1 /* reserved */ \ 92 + 4 /* group leaf k, group internal k */ \ 93 + 4) /* consistency flags */ 94 #define H5F_SUPERBLOCK_VARLEN_SIZE_V0(f) \ 95 ( H5F_SUPERBLOCK_VARLEN_SIZE_COMMON /* Common variable-length info */ \ 96 + H5F_SIZEOF_ADDR(f) /* base address */ \ 97 + H5F_SIZEOF_ADDR(f) /* <unused> */ \ 98 + H5F_SIZEOF_ADDR(f) /* EOF address */ \ 99 + H5F_SIZEOF_ADDR(f) /* driver block address */ \ 100 + H5G_SIZEOF_ENTRY(f)) /* root group ptr */ 101 #define H5F_SUPERBLOCK_VARLEN_SIZE_V1(f) \ 102 ( H5F_SUPERBLOCK_VARLEN_SIZE_COMMON /* Common variable-length info */ \ 103 + 2 /* indexed B-tree internal k */ \ 104 + 2 /* reserved */ \ 105 + H5F_SIZEOF_ADDR(f) /* base address */ \ 106 + H5F_SIZEOF_ADDR(f) /* <unused> */ \ 107 + H5F_SIZEOF_ADDR(f) /* EOF address */ \ 108 + H5F_SIZEOF_ADDR(f) /* driver block address */ \ 109 + H5G_SIZEOF_ENTRY(f)) /* root group ptr */ 110 #define H5F_SUPERBLOCK_VARLEN_SIZE_V2(f) \ 111 ( 2 /* size of address, size of lengths */ \ 112 + 1 /* consistency flags */ \ 113 + H5F_SIZEOF_ADDR(f) /* base address */ \ 114 + H5F_SIZEOF_ADDR(f) /* superblock extension address */ \ 115 + H5F_SIZEOF_ADDR(f) /* EOF address */ \ 116 + H5F_SIZEOF_ADDR(f) /* root group object header address */ \ 117 + H5F_SIZEOF_CHKSUM) /* superblock checksum (keep this last) */ 118 #define H5F_SUPERBLOCK_VARLEN_SIZE(v, f) ( \ 119 (v == 0 ? H5F_SUPERBLOCK_VARLEN_SIZE_V0(f) : 0) \ 120 + (v == 1 ? H5F_SUPERBLOCK_VARLEN_SIZE_V1(f) : 0) \ 121 + (v == 2 ? H5F_SUPERBLOCK_VARLEN_SIZE_V2(f) : 0)) 122 123 /* Total size of superblock, depends on superblock version */ 124 #define H5F_SUPERBLOCK_SIZE(v, f) ( H5F_SUPERBLOCK_FIXED_SIZE \ 125 + H5F_SUPERBLOCK_VARLEN_SIZE(v, f)) 126 127 128 /* Forward declaration external file cache struct used below (defined in 129 * H5Fefc.c) */ 130 typedef struct H5F_efc_t H5F_efc_t; 131 132 /* Structure for metadata & "small [raw] data" block aggregation fields */ 133 struct H5F_blk_aggr_t { 134 unsigned long feature_flag; /* Feature flag type */ 135 hsize_t alloc_size; /* Size for allocating new blocks */ 136 hsize_t tot_size; /* Total amount of bytes aggregated into block */ 137 hsize_t size; /* Current size of block left */ 138 haddr_t addr; /* Location of block left */ 139 }; 140 141 /* Structure for metadata accumulator fields */ 142 typedef struct H5F_meta_accum_t { 143 unsigned char *buf; /* Buffer to hold the accumulated metadata */ 144 haddr_t loc; /* File location (offset) of the accumulated metadata */ 145 size_t size; /* Size of the accumulated metadata buffer used (in bytes) */ 146 size_t alloc_size; /* Size of the accumulated metadata buffer allocated (in bytes) */ 147 size_t dirty_off; /* Offset of the dirty region in the accumulator buffer */ 148 size_t dirty_len; /* Length of the dirty region in the accumulator buffer */ 149 hbool_t dirty; /* Flag to indicate that the accumulated metadata is dirty */ 150 } H5F_meta_accum_t; 151 152 /* Enum for free space manager state */ 153 typedef enum H5F_fs_state_t { 154 H5F_FS_STATE_CLOSED, /* Free space manager is closed */ 155 H5F_FS_STATE_OPEN, /* Free space manager has been opened */ 156 H5F_FS_STATE_DELETING /* Free space manager is being deleted */ 157 } H5F_fs_state_t; 158 159 /* A record of the mount table */ 160 typedef struct H5F_mount_t { 161 struct H5G_t *group; /* Mount point group held open */ 162 struct H5F_t *file; /* File mounted at that point */ 163 } H5F_mount_t; 164 165 /* 166 * The mount table describes what files are attached to (mounted on) the file 167 * to which this table belongs. 168 */ 169 typedef struct H5F_mtab_t { 170 unsigned nmounts;/* Number of children which are mounted */ 171 unsigned nalloc; /* Number of mount slots allocated */ 172 H5F_mount_t *child; /* An array of mount records */ 173 } H5F_mtab_t; 174 175 /* Structure specifically to store superblock. This was originally 176 * maintained entirely within H5F_file_t, but is now extracted 177 * here because the superblock is now handled by the cache */ 178 typedef struct H5F_super_t { 179 H5AC_info_t cache_info; /* Cache entry information structure */ 180 unsigned super_vers; /* Superblock version */ 181 uint8_t status_flags; /* File status flags */ 182 unsigned sym_leaf_k; /* Size of leaves in symbol tables */ 183 unsigned btree_k[H5B_NUM_BTREE_ID]; /* B-tree key values for each type */ 184 haddr_t base_addr; /* Absolute base address for rel.addrs. */ 185 /* (superblock for file is at this offset) */ 186 haddr_t ext_addr; /* Relative address of superblock extension */ 187 haddr_t driver_addr; /* File driver information block address */ 188 haddr_t root_addr; /* Root group address */ 189 H5G_entry_t *root_ent; /* Root group symbol table entry */ 190 } H5F_super_t; 191 192 /* 193 * Define the structure to store the file information for HDF5 files. One of 194 * these structures is allocated per file, not per H5Fopen(). That is, set of 195 * H5F_t structs can all point to the same H5F_file_t struct. The `nrefs' 196 * count in this struct indicates the number of H5F_t structs which are 197 * pointing to this struct. 198 */ 199 struct H5F_file_t { 200 H5FD_t *lf; /* Lower level file handle for I/O */ 201 H5F_super_t *sblock; /* Pointer to (pinned) superblock for file */ 202 unsigned nrefs; /* Ref count for times file is opened */ 203 unsigned flags; /* Access Permissions for file */ 204 H5F_mtab_t mtab; /* File mount table */ 205 H5F_efc_t *efc; /* External file cache */ 206 207 /* Cached values from FCPL/superblock */ 208 uint8_t sizeof_addr; /* Size of addresses in file */ 209 uint8_t sizeof_size; /* Size of offsets in file */ 210 haddr_t sohm_addr; /* Relative address of shared object header message table */ 211 unsigned sohm_vers; /* Version of shared message table on disk */ 212 unsigned sohm_nindexes; /* Number of shared messages indexes in the table */ 213 unsigned long feature_flags; /* VFL Driver feature Flags */ 214 haddr_t maxaddr; /* Maximum address for file */ 215 216 H5AC_t *cache; /* The object cache */ 217 H5AC_cache_config_t 218 mdc_initCacheCfg; /* initial configuration for the */ 219 /* metadata cache. This structure is */ 220 /* fixed at creation time and should */ 221 /* not change thereafter. */ 222 hid_t fcpl_id; /* File creation property list ID */ 223 H5F_close_degree_t fc_degree; /* File close behavior degree */ 224 size_t rdcc_nslots; /* Size of raw data chunk cache (slots) */ 225 size_t rdcc_nbytes; /* Size of raw data chunk cache (bytes) */ 226 double rdcc_w0; /* Preempt read chunks first? [0.0..1.0]*/ 227 size_t sieve_buf_size; /* Size of the data sieve buffer allocated (in bytes) */ 228 hsize_t threshold; /* Threshold for alignment */ 229 hsize_t alignment; /* Alignment */ 230 unsigned gc_ref; /* Garbage-collect references? */ 231 hbool_t latest_format; /* Always use the latest format? */ 232 hbool_t store_msg_crt_idx; /* Store creation index for object header messages? */ 233 unsigned ncwfs; /* Num entries on cwfs list */ 234 struct H5HG_heap_t **cwfs; /* Global heap cache */ 235 struct H5G_t *root_grp; /* Open root group */ 236 H5FO_t *open_objs; /* Open objects in file */ 237 H5RC_t *grp_btree_shared; /* Ref-counted group B-tree node info */ 238 239 /* File space allocation information */ 240 hbool_t use_tmp_space; /* Whether temp. file space allocation is allowed */ 241 haddr_t tmp_addr; /* Next address to use for temp. space in the file */ 242 unsigned fs_aggr_merge[H5FD_MEM_NTYPES]; /* Flags for whether free space can merge with aggregator(s) */ 243 H5F_fs_state_t fs_state[H5FD_MEM_NTYPES]; /* State of free space manager for each type */ 244 haddr_t fs_addr[H5FD_MEM_NTYPES]; /* Address of free space manager info for each type */ 245 H5FS_t *fs_man[H5FD_MEM_NTYPES]; /* Free space manager for each file space type */ 246 H5FD_mem_t fs_type_map[H5FD_MEM_NTYPES]; /* Mapping of "real" file space type into tracked type */ 247 H5F_blk_aggr_t meta_aggr; /* Metadata aggregation info */ 248 /* (if aggregating metadata allocations) */ 249 H5F_blk_aggr_t sdata_aggr; /* "Small data" aggregation info */ 250 /* (if aggregating "small data" allocations) */ 251 252 /* Metadata accumulator information */ 253 H5F_meta_accum_t accum; /* Metadata accumulator info */ 254 }; 255 256 /* 257 * This is the top-level file descriptor. One of these structures is 258 * allocated every time H5Fopen() is called although they may contain pointers 259 * to shared H5F_file_t structs. 260 */ 261 struct H5F_t { 262 char *open_name; /* Name used to open file */ 263 char *actual_name; /* Actual name of the file, after resolving symlinks, etc. */ 264 char *extpath; /* Path for searching target external link file */ 265 H5F_file_t *shared; /* The shared file info */ 266 unsigned nopen_objs; /* Number of open object headers*/ 267 H5FO_t *obj_count; /* # of time each object is opened through top file structure */ 268 hid_t file_id; /* ID of this file */ 269 hbool_t closing; /* File is in the process of being closed */ 270 struct H5F_t *parent; /* Parent file that this file is mounted to */ 271 unsigned nmounts; /* Number of children mounted to this file */ 272 }; 273 274 275 /*****************************/ 276 /* Package Private Variables */ 277 /*****************************/ 278 279 /* Declare a free list to manage the H5F_t struct */ 280 H5FL_EXTERN(H5F_t); 281 282 /* Declare a free list to manage the H5F_file_t struct */ 283 H5FL_EXTERN(H5F_file_t); 284 285 H5_DLLVAR const H5AC_class_t H5AC_SUPERBLOCK[1]; 286 287 288 /******************************/ 289 /* Package Private Prototypes */ 290 /******************************/ 291 292 /* General routines */ 293 H5_DLL herr_t H5F_init(void); 294 H5_DLL herr_t H5F__term_deprec_interface(void); 295 H5_DLL herr_t H5F_locate_signature(H5FD_t *file, hid_t dxpl_id, haddr_t *sig_addr); 296 H5_DLL herr_t H5F_flush(H5F_t *f, hid_t dxpl_id, hbool_t closing); 297 298 /* File mount related routines */ 299 H5_DLL herr_t H5F_close_mounts(H5F_t *f); 300 H5_DLL int H5F_term_unmount_cb(void *obj_ptr, hid_t obj_id, void *key); 301 H5_DLL herr_t H5F_mount_count_ids(H5F_t *f, unsigned *nopen_files, unsigned *nopen_objs); 302 303 /* Superblock related routines */ 304 H5_DLL herr_t H5F_super_init(H5F_t *f, hid_t dxpl_id); 305 H5_DLL herr_t H5F_super_read(H5F_t *f, hid_t dxpl_id); 306 H5_DLL herr_t H5F_super_size(H5F_t *f, hid_t dxpl_id, hsize_t *super_size, 307 hsize_t *super_ext_info); 308 H5_DLL herr_t H5F_super_free(H5F_super_t *sblock); 309 310 /* Superblock extension related routines */ 311 H5_DLL herr_t H5F_super_ext_open(H5F_t *f, haddr_t ext_addr, H5O_loc_t *ext_ptr); 312 H5_DLL herr_t H5F_super_ext_write_msg(H5F_t *f, hid_t dxpl_id, void *mesg, unsigned id, hbool_t may_create); 313 H5_DLL herr_t H5F_super_ext_close(H5F_t *f, H5O_loc_t *ext_ptr, hid_t dxpl_id, 314 hbool_t was_created); 315 316 /* Metadata accumulator routines */ 317 H5_DLL herr_t H5F_accum_read(const H5F_t *f, hid_t dxpl_id, H5FD_mem_t type, 318 haddr_t addr, size_t size, void *buf); 319 H5_DLL herr_t H5F_accum_write(const H5F_t *f, hid_t dxpl_id, H5FD_mem_t type, 320 haddr_t addr, size_t size, const void *buf); 321 H5_DLL herr_t H5F_accum_free(H5F_t *f, hid_t dxpl_id, H5FD_mem_t type, 322 haddr_t addr, hsize_t size); 323 H5_DLL herr_t H5F_accum_flush(const H5F_t *f, hid_t dxpl_id); 324 H5_DLL herr_t H5F_accum_reset(const H5F_t *f, hid_t dxpl_id, hbool_t flush); 325 326 /* Shared file list related routines */ 327 H5_DLL herr_t H5F_sfile_add(H5F_file_t *shared); 328 H5_DLL H5F_file_t * H5F_sfile_search(H5FD_t *lf); 329 H5_DLL herr_t H5F_sfile_remove(H5F_file_t *shared); 330 331 /* External file cache routines */ 332 H5_DLL H5F_efc_t *H5F_efc_create(unsigned max_nfiles); 333 H5_DLL unsigned H5F_efc_max_nfiles(H5F_efc_t *efc); 334 H5_DLL herr_t H5F_efc_release(H5F_efc_t *efc); 335 H5_DLL herr_t H5F_efc_destroy(H5F_efc_t *efc); 336 H5_DLL herr_t H5F_efc_try_close(H5F_t *f); 337 338 /* Testing functions */ 339 #ifdef H5F_TESTING 340 H5_DLL herr_t H5F_get_sohm_mesg_count_test(hid_t fid, unsigned type_id, 341 size_t *mesg_count); 342 H5_DLL herr_t H5F_check_cached_stab_test(hid_t file_id); 343 H5_DLL herr_t H5F_get_maxaddr_test(hid_t file_id, haddr_t *maxaddr); 344 #endif /* H5F_TESTING */ 345 346 #endif /* _H5Fpkg_H */ 347 348