bsd/hfs/hfscommon/headers/BTreesPrivate.h

   1 /*
   2  * Copyright (c) 2000-2003 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25 /*
  26         File:           BTreesPrivate.h
  27
  28         Contains:       Private interface file for the BTree Module.
  29
  30         Version:        xxx put the technology version here xxx
  31
  32         Written by:     Gordon Sheridan and Bill Bruffey
  33
  34         Copyright:      © 1992-1999 by Apple Computer, Inc., all rights reserved.
  35
  36         File Ownership:
  37
  38                 DRI:                            Don Brady
  39
  40                 Other Contact:          Mark Day
  41
  42                 Technology:                     File Systems
  43
  44         Writers:
  45
  46                 (msd)   Mark Day
  47                 (DSH)   Deric Horn
  48                 (djb)   Don Brady
  49                 (ser)   Scott Roberts
  50                 (dkh)   Dave Heller
  51
  52         Change History (most recent first):
  53            <MacOSX>      3/19/99        djb             Disable MoveRecordsLeft/Right macros since bcopy is broken.
  54
  55            <MacOSX>      8/10/98        djb             Removed unused BTreeIterator from BTreeControlBlock, fixed alignment.
  56
  57            <CS5>          9/4/97        djb             Convert MoveRecordsLeft and GetLeftSiblingNode to macros.
  58            <CS4>         7/24/97        djb             Add macro for GetRecordAddress (was a function before).
  59            <CS3>         7/21/97        msd             GetRecordByIndex now returns an OSStatus.
  60            <CS2>         7/16/97        DSH             FilesInternal.i renamed FileMgrInternal.i to avoid name
  61                                                                         collision
  62            <CS1>         4/23/97        djb             first checked in
  63
  64           <HFS6>         3/17/97        DSH             Added a refCon field to BTreeControlBlock, for DFA use, to point
  65                                                                         to additional data.  Fixed Panic macros for use with SC.
  66           <HFS5>         2/19/97        djb             Add InsertKey struct. Moved on-disk definitions to
  67                                                                         HFSBTreesPriv.h
  68           <HFS4>         1/27/97        djb             InsertTree and DeleteTree are now recursive and support variable
  69                                                                         sized index keys.
  70           <HFS3>         1/15/97        djb             Move GetFileRefNumFromFCB macro to FilesInternal.h. Added
  71                                                                         kBTVariableIndexKeysMask.
  72           <HFS2>          1/3/97        djb             Added support for large keys.
  73           <HFS1>        12/19/96        djb             first checked in
  74
  75         History applicable to original Scarecrow Design:
  76
  77                  <7>    10/25/96        ser             Changing for new VFPI
  78                  <6>    10/18/96        ser             Converting over VFPI changes
  79                  <5>     9/17/96        dkh             More BTree statistics
  80                  <4>     9/16/96        dkh             Revised BTree statistics
  81                  <3>     6/20/96        dkh             Radar #1358740. Switch from using Pools to debug MemAllocators.
  82                  <2>     12/7/95        dkh             D10E2 build. Changed usage of Ref data type to LogicalAddress.
  83                  <1>    10/18/95        rst             Moved from Scarecrow project.
  84
  85                 <19>    11/22/94        djb             Add prototype for GetMapNode
  86                 <18>    11/16/94        prp             Add IsItAHint routine prototype.
  87                 <17>     9/30/94        prp             Get in sync with D2 interface changes.
  88                 <16>     7/25/94        wjk             Eliminate usage of BytePtr in favor of UInt8 *.
  89                 <15>     7/22/94        wjk             Convert to the new set of header files.
  90                 <14>     5/31/94        srs             Moved Btree types to public interface
  91                 <13>     12/9/93        wjk             Add 68k alignment pragma's around persistent structures.
  92                 <12>    11/30/93        wjk             Move from Makefiles to BuildFiles. Fit into the ModernOS and
  93                                                                         NRCmds environments.
  94                 <11>    11/23/93        wjk             Changes required to compile on the RS6000.
  95                 <10>     8/30/93        CH              Removed the M_ExitOnError and M_ReturnErrorIf macros which were
  96                                                                         already defined in FileSystemPriv.h (included here).
  97                  <9>     8/30/93        CH              Added parens around the M_ReturnErrorIf macro.
  98                  <8>     5/21/93        gs              Add kBadClose flag. Add some prototypes for internal routines.
  99                  <7>     5/10/93        gs              Change Ptr to BytePtr. Move BTreeTypes to BTree.h. Add
 100                                                                         DeleteTree prototype.
 101                  <6>     3/23/93        gs              Remove mysterious "flags" field from HeaderRec structure. Move
 102                                                                         prototypes of private functions to top of respective source
 103                                                                         files.
 104                  <5>      2/8/93        gs              Update to use FSAgent.h Get/Release/SetEOF/SetBlockSize
 105                                                                         procPtrs. Add UpdateNode routine.
 106                  <4>    12/10/92        gs              Add Key Descriptor function declarations.
 107                  <3>     12/8/92        gs              Add HeaderRec structure and incorporate review feedback.
 108                  <2>     12/2/92        gs              Add GetNode and ReleaseNode callback procptrs to BTree CB, and
 109                                                                         add internal function declarations.
 110                  <1>    11/15/92        gs              first checked in
 111
 112 */
 113
 114 #ifndef __BTREESPRIVATE__
 115 #define __BTREESPRIVATE__
 116
 117 #include <sys/appleapiopts.h>
 118
 119 #ifdef KERNEL
 120 #ifdef __APPLE_API_PRIVATE
 121
 122 #include "../../hfs_macos_defs.h"
 123
 124 #ifndef __FILEMGRINTERNAL__
 125 #include "FileMgrInternal.h"
 126 #endif
 127
 128 #ifndef __BTREESINTERNAL__
 129 #include "BTreesInternal.h"
 130 #endif
 131
 132
 133 /////////////////////////////////// Constants ///////////////////////////////////
 134
 135 #define         kBTreeVersion             1
 136 #define         kMaxTreeDepth            16
 137
 138
 139 #define         kHeaderNodeNum            0
 140 #define         kKeyDescRecord            1
 141
 142
 143 // Header Node Record Offsets
 144 enum {
 145         kHeaderRecOffset        =       0x000E,
 146         kKeyDescRecOffset       =       0x0078,
 147         kHeaderMapRecOffset     =       0x00F8
 148 };
 149
 150 #define         kMinNodeSize            512
 151
 152 #define         kMinRecordSize            6
 153                                                                                 // where is minimum record size enforced?
 154
 155 // miscellaneous BTree constants
 156 enum {
 157                         kOffsetSize                             = 2
 158 };
 159
 160 // Insert Operations
 161 typedef enum {
 162                         kInsertRecord                   = 0,
 163                         kReplaceRecord                  = 1
 164 } InsertType;
 165
 166 // illegal string attribute bits set in mask
 167 #define         kBadStrAttribMask               0xCF
 168
 169
 170
 171 //////////////////////////////////// Macros /////////////////////////////////////
 172
 173 #define         M_NodesInMap(mapSize)                           ((mapSize) << 3)
 174
 175 #define         M_ClearBitNum(integer,bitNumber)        ((integer) &= (~(1<<(bitNumber))))
 176 #define         M_SetBitNum(integer,bitNumber)          ((integer) |= (1<<(bitNumber)))
 177 #define         M_IsOdd(integer)                                        (((integer) & 1) != 0)
 178 #define         M_IsEven(integer)                                       (((integer) & 1) == 0)
 179 #define         M_BTreeHeaderDirty(btreePtr)            btreePtr->flags |= kBTHeaderDirty
 180
 181 #define         M_MapRecordSize(nodeSize)                       (nodeSize - sizeof (BTNodeDescriptor) - 6)
 182 #define         M_HeaderMapRecordSize(nodeSize)         (nodeSize - sizeof(BTNodeDescriptor) - sizeof(BTHeaderRec) - 128 - 8)
 183
 184 #define         M_SWAP_BE16_ClearBitNum(integer,bitNumber)  ((integer) &= SWAP_BE16(~(1<<(bitNumber))))
 185 #define         M_SWAP_BE16_SetBitNum(integer,bitNumber)    ((integer) |= SWAP_BE16(1<<(bitNumber)))
 186
 187 ///////////////////////////////////// Types /////////////////////////////////////
 188
 189 typedef struct BTreeControlBlock {                                      // fields specific to BTree CBs
 190
 191         UInt8           keyCompareType;   /* Key string Comparison Type */
 192         UInt8                                            btreeType;
 193         UInt16                                           treeDepth;
 194         FileReference                            fileRefNum;            // refNum of btree file
 195         KeyCompareProcPtr                        keyCompareProc;
 196         UInt32                                           rootNode;
 197         UInt32                                           leafRecords;
 198         UInt32                                           firstLeafNode;
 199         UInt32                                           lastLeafNode;
 200         UInt16                                           nodeSize;
 201         UInt16                                           maxKeyLength;
 202         UInt32                                           totalNodes;
 203         UInt32                                           freeNodes;
 204
 205         UInt16                                           reserved3;                     // 4-byte alignment
 206
 207         // new fields
 208         SInt16                                           version;
 209         UInt32                                           flags;                         // dynamic flags
 210         UInt32                                           attributes;            // persistent flags
 211         UInt32                                           writeCount;
 212         UInt32                                           lastfsync;             /* Last time that this was fsynced  */
 213
 214         GetBlockProcPtr                          getBlockProc;
 215         ReleaseBlockProcPtr                      releaseBlockProc;
 216         SetEndOfForkProcPtr                      setEndOfForkProc;
 217
 218         // statistical information
 219         UInt32                                           numGetNodes;
 220         UInt32                                           numGetNewNodes;
 221         UInt32                                           numReleaseNodes;
 222         UInt32                                           numUpdateNodes;
 223         UInt32                                           numMapNodesRead;       // map nodes beyond header node
 224         UInt32                                           numHintChecks;
 225         UInt32                                           numPossibleHints;      // Looks like a formated hint
 226         UInt32                                           numValidHints;         // Hint used to find correct record.
 227         UInt32                                  reservedNodes;
 228 } BTreeControlBlock, *BTreeControlBlockPtr;
 229
 230
 231 UInt32 CalcKeySize(const BTreeControlBlock *btcb, const BTreeKey *key);
 232 #define CalcKeySize(btcb, key)                  ( ((btcb)->attributes & kBTBigKeysMask) ? ((key)->length16 + 2) : ((key)->length8 + 1) )
 233
 234 UInt32 KeyLength(const BTreeControlBlock *btcb, const BTreeKey *key);
 235 #define KeyLength(btcb, key)                    ( ((btcb)->attributes & kBTBigKeysMask) ? (key)->length16 : (key)->length8 )
 236
 237
 238
 239 typedef enum {
 240                                         kBTHeaderDirty  = 0x00000001
 241 }       BTreeFlags;
 242
 243
 244 typedef SInt8                           *NodeBuffer;
 245 typedef BlockDescriptor          NodeRec, *NodePtr;             //\80\80 remove this someday...
 246
 247
 248
 249
 250 //// Tree Path Table - constructed by SearchTree, used by InsertTree and DeleteTree
 251
 252 typedef struct {
 253         UInt32                          node;                           // node number
 254         UInt16                          index;
 255         UInt16                          reserved;                       // align size to a power of 2
 256 } TreePathRecord, *TreePathRecordPtr;
 257
 258 typedef TreePathRecord          TreePathTable [kMaxTreeDepth];
 259
 260
 261 //// InsertKey - used by InsertTree, InsertLevel and InsertNode
 262
 263 struct InsertKey {
 264         BTreeKeyPtr             keyPtr;
 265         UInt8 *                 recPtr;
 266         UInt16                  keyLength;
 267         UInt16                  recSize;
 268         Boolean                 replacingKey;
 269         Boolean                 skipRotate;
 270 };
 271
 272 typedef struct InsertKey InsertKey;
 273
 274
 275 //// For Notational Convenience
 276
 277 typedef BTNodeDescriptor*        NodeDescPtr;
 278 typedef UInt8                           *RecordPtr;
 279 typedef BTreeKeyPtr                      KeyPtr;
 280
 281
 282 //////////////////////////////////// Globals ////////////////////////////////////
 283
 284
 285 //////////////////////////////////// Macros /////////////////////////////////////
 286
 287 #if DEBUG_BUILD
 288         #define Panic( message )                                        DebugStr( (ConstStr255Param) message )
 289         #define PanicIf( condition, message )           if ( condition != 0 )   DebugStr( message )
 290 #else
 291         #define Panic( message )
 292         #define PanicIf( condition, message )
 293 #endif
 294
 295 //      Exit function on error
 296 #define M_ExitOnError( result ) if ( ( result ) != noErr )      goto ErrorExit; else ;
 297
 298 //      Test for passed condition and return if true
 299 #define M_ReturnErrorIf( condition, error )     if ( condition )        return( error )
 300
 301 //////////////////////////////// Key Operations /////////////////////////////////
 302
 303 SInt32          CompareKeys                             (BTreeControlBlockPtr    btreePtr,
 304                                                                          KeyPtr                                  searchKey,
 305                                                                          KeyPtr                                  trialKey );
 306
 307 //////////////////////////////// Map Operations /////////////////////////////////
 308
 309 OSStatus        AllocateNode                    (BTreeControlBlockPtr    btreePtr,
 310                                                                          UInt32                                 *nodeNum);
 311
 312 OSStatus        FreeNode                                (BTreeControlBlockPtr    btreePtr,
 313                                                                          UInt32                                  nodeNum);
 314
 315 OSStatus        ExtendBTree                             (BTreeControlBlockPtr    btreePtr,
 316                                                                          UInt32                                  nodes );
 317
 318 UInt32          CalcMapBits                             (BTreeControlBlockPtr    btreePtr);
 319
 320 SInt32          BTAvailableNodes                        (BTreeControlBlock *btree);
 321
 322 void            BTUpdateReserve                         (BTreeControlBlockPtr btreePtr,
 323                                                          int nodes);
 324
 325 //////////////////////////////// Misc Operations ////////////////////////////////
 326
 327 UInt16          CalcKeyRecordSize               (UInt16                                  keySize,
 328                                                                          UInt16                                  recSize );
 329
 330 OSStatus        VerifyHeader                    (FCB                                    *filePtr,
 331                                                                          BTHeaderRec                            *header );
 332
 333 OSStatus        UpdateHeader                    (BTreeControlBlockPtr    btreePtr,
 334                                                  Boolean forceWrite );
 335
 336 OSStatus        FindIteratorPosition    (BTreeControlBlockPtr    btreePtr,
 337                                                                          BTreeIteratorPtr                iterator,
 338                                                                          BlockDescriptor                *left,
 339                                                                          BlockDescriptor                *middle,
 340                                                                          BlockDescriptor                *right,
 341                                                                          UInt32                                 *nodeNum,
 342                                                                          UInt16                                 *index,
 343                                                                          Boolean                                *foundRecord );
 344
 345 OSStatus        CheckInsertParams               (FCB                                    *filePtr,
 346                                                                          BTreeIterator                  *iterator,
 347                                                                          FSBufferDescriptor             *record,
 348                                                                          UInt16                                  recordLen );
 349
 350 OSStatus        TrySimpleReplace                (BTreeControlBlockPtr    btreePtr,
 351                                                                          NodeDescPtr                     nodePtr,
 352                                                                          BTreeIterator                  *iterator,
 353                                                                          FSBufferDescriptor             *record,
 354                                                                          UInt16                                  recordLen,
 355                                                                          Boolean                                *recordInserted );
 356
 357 OSStatus        IsItAHint                               (BTreeControlBlockPtr    btreePtr,
 358                                                                          BTreeIterator                  *iterator,
 359                                                                          Boolean                                *answer );
 360
 361 //////////////////////////////// Node Operations ////////////////////////////////
 362
 363 //// Node Operations
 364
 365 OSStatus        GetNode                                 (BTreeControlBlockPtr    btreePtr,
 366                                                                          UInt32                                  nodeNum,
 367                                                                          NodeRec                                *returnNodePtr );
 368
 369 OSStatus        GetLeftSiblingNode              (BTreeControlBlockPtr    btreePtr,
 370                                                                          NodeDescPtr                     node,
 371                                                                          NodeRec                                *left );
 372
 373 #define         GetLeftSiblingNode(btree,node,left)                     GetNode ((btree), ((NodeDescPtr)(node))->bLink, (left))
 374
 375 OSStatus        GetRightSiblingNode             (BTreeControlBlockPtr    btreePtr,
 376                                                                          NodeDescPtr                     node,
 377                                                                          NodeRec                                *right );
 378
 379 #define         GetRightSiblingNode(btree,node,right)           GetNode ((btree), ((NodeDescPtr)(node))->fLink, (right))
 380
 381
 382 OSStatus        GetNewNode                              (BTreeControlBlockPtr    btreePtr,
 383                                                                          UInt32                                  nodeNum,
 384                                                                          NodeRec                                *returnNodePtr );
 385
 386 OSStatus        ReleaseNode                             (BTreeControlBlockPtr    btreePtr,
 387                                                                          NodePtr                                 nodePtr );
 388
 389 OSStatus        TrashNode                               (BTreeControlBlockPtr    btreePtr,
 390                                                                          NodePtr                                 nodePtr );
 391
 392 // XXXdbg
 393 void ModifyBlockStart(FileReference vp, BlockDescPtr blockPtr);
 394 // XXXdbg
 395
 396 OSStatus        UpdateNode                              (BTreeControlBlockPtr    btreePtr,
 397                                                                          NodePtr                                 nodePtr,
 398                                                                          UInt32                                  transactionID,
 399                                                                          UInt32                                  flags );
 400
 401 OSStatus        GetMapNode                              (BTreeControlBlockPtr    btreePtr,
 402                                                                          BlockDescriptor                 *nodePtr,
 403                                                                          UInt16                                  **mapPtr,
 404                                                                          UInt16                                  *mapSize );
 405
 406 //// Node Buffer Operations
 407
 408 OSStatus        CheckNode                               (BTreeControlBlockPtr    btreePtr,
 409                                                                          NodeDescPtr                     node );
 410
 411 void            ClearNode                               (BTreeControlBlockPtr    btreePtr,
 412                                                                          NodeDescPtr                     node );
 413
 414 UInt16          GetNodeDataSize                 (BTreeControlBlockPtr    btreePtr,
 415                                                                          NodeDescPtr                     node );
 416
 417 UInt16          GetNodeFreeSize                 (BTreeControlBlockPtr    btreePtr,
 418                                                                          NodeDescPtr                     node );
 419
 420
 421 //// Record Operations
 422
 423 Boolean         InsertRecord                    (BTreeControlBlockPtr    btreePtr,
 424                                                                          NodeDescPtr                     node,
 425                                                                          UInt16                                  index,
 426                                                                          RecordPtr                               recPtr,
 427                                                                          UInt16                                  recSize );
 428
 429 Boolean         InsertKeyRecord                 (BTreeControlBlockPtr    btreePtr,
 430                                                                          NodeDescPtr                     node,
 431                                                                          UInt16                                  index,
 432                                                                          KeyPtr                                  keyPtr,
 433                                                                          UInt16                                  keyLength,
 434                                                                          RecordPtr                               recPtr,
 435                                                                          UInt16                                  recSize );
 436
 437 void            DeleteRecord                    (BTreeControlBlockPtr   btree,
 438                                                                          NodeDescPtr                    node,
 439                                                                          UInt16                                 index );
 440
 441
 442 Boolean         SearchNode                              (BTreeControlBlockPtr    btree,
 443                                                                          NodeDescPtr                     node,
 444                                                                          KeyPtr                                  searchKey,
 445                                                                          UInt16                                 *index );
 446
 447 OSStatus        GetRecordByIndex                (BTreeControlBlockPtr    btree,
 448                                                                          NodeDescPtr                     node,
 449                                                                          UInt16                                  index,
 450                                                                          KeyPtr                                 *keyPtr,
 451                                                                          UInt8 *                                *dataPtr,
 452                                                                          UInt16                                 *dataSize );
 453
 454 UInt8 *         GetRecordAddress                (BTreeControlBlockPtr    btree,
 455                                                                          NodeDescPtr                     node,
 456                                                                          UInt16                                  index );
 457
 458 #define GetRecordAddress(btreePtr,node,index)           ((UInt8 *)(node) + (*(short *) ((UInt8 *)(node) + (btreePtr)->nodeSize - ((index) << 1) - kOffsetSize)))
 459
 460
 461 UInt16          GetRecordSize                   (BTreeControlBlockPtr    btree,
 462                                                                          NodeDescPtr                     node,
 463                                                                          UInt16                                  index );
 464
 465 UInt32          GetChildNodeNum                 (BTreeControlBlockPtr    btreePtr,
 466                                                                          NodeDescPtr                     nodePtr,
 467                                                                          UInt16                                  index );
 468
 469 void            MoveRecordsLeft                 (UInt8 *                                 src,
 470                                                                          UInt8 *                                 dst,
 471                                                                          UInt16                                  bytesToMove );
 472
 473 #define         MoveRecordsLeft(src,dst,bytes)                  bcopy((src),(dst),(bytes))
 474
 475 void            MoveRecordsRight                (UInt8 *                                 src,
 476                                                                          UInt8 *                                 dst,
 477                                                                          UInt16                                  bytesToMove );
 478
 479 #define         MoveRecordsRight(src,dst,bytes)                 bcopy((src),(dst),(bytes))
 480
 481
 482 //////////////////////////////// Tree Operations ////////////////////////////////
 483
 484 OSStatus        SearchTree                              (BTreeControlBlockPtr    btreePtr,
 485                                                                          BTreeKeyPtr                     keyPtr,
 486                                                                          TreePathTable                   treePathTable,
 487                                                                          UInt32                                 *nodeNum,
 488                                                                          BlockDescriptor                *nodePtr,
 489                                                                          UInt16                                 *index );
 490
 491 OSStatus        InsertTree                              (BTreeControlBlockPtr    btreePtr,
 492                                                                          TreePathTable                   treePathTable,
 493                                                                          KeyPtr                                  keyPtr,
 494                                                                          UInt8 *                                 recPtr,
 495                                                                          UInt16                                  recSize,
 496                                                                          BlockDescriptor                *targetNode,
 497                                                                          UInt16                                  index,
 498                                                                          UInt16                                  level,
 499                                                                          Boolean                                 replacingKey,
 500                                                                          UInt32                                 *insertNode );
 501
 502 OSStatus        DeleteTree                              (BTreeControlBlockPtr    btreePtr,
 503                                                                          TreePathTable                   treePathTable,
 504                                                                          BlockDescriptor                *targetNode,
 505                                                                          UInt16                                  index,
 506                                                                          UInt16                                  level );
 507
 508 #endif /* __APPLE_API_PRIVATE */
 509 #endif /* KERNEL */
 510 #endif //__BTREESPRIVATE__