| blob | bb8907b8c7c9d055c2aa0a2c45e12fef03cb46d8 |
1 This file forms part of PFS3 (Professional File System 3)
2 Written by Michiel Pelt
3 Copyright 1999 by GREat Effects Development
4 $Id: Proginfo 1.7 1999/06/30 18:38:08 Michiel Exp Michiel $
6 13 May 1999
8 PFS3 disk structure
9 -------------------
11 This document describes the blocks and structures used by PFS. Only the
12 new harddisk version will be described here. For the floppy version you
13 can refer to previous releases.
15 *********************
16 * the bootblocks
17 *********************
19 The first two blocks are the bootblocks, as required by AmigaDOS. The
20 first longword of the first bootblock contains the dostype: PFS\1. The
21 rest is empty. So the first bootblock looks like this:
23 ___________________
24 | |
25 000 | disktype |
26 |___________________|
27 004 | |
28 | |
29 | . |
30 | . |
31 200 |___________________|
34 ********************
35 * the rootblock
36 ********************
38 Directly behind the bootblocks you can find the rootblock, on block 2.
39 This is the most important block of a PFS disk. PFS keeps this block
40 cached at all times. It looks like this:
42 ___________________
43 | |
44 000 | disktype | 'PFS\1'
45 004 | options | see below
46 008 | datestamp |
47 |___________________|
48 | | |
49 00c | cday | cminute | creation date (DOS format)
50 010 | ctick | prot | protection
51 |_________|_________|
52 | | 32 character diskname. Size of string followed
53 014 | diskname | by that number of characters
54 | |
55 |___________________|
56 | |
57 034 | last reserved | first and last reserved block (blocknumbers)
58 038 | first reserved |
59 03c | reserved free | number of reserved blocks free
60 |___________________|
61 | | |
62 040 | blksize | rblkclt | reserved blocksize; rootblock cluster
63 |_________|_________|
64 | |
65 044 | blocks free | number of blocks free
66 048 | always free | number of blocks always kept free
67 04c | roving pointer | used for allocation
68 050 | deldir | (<4.3) the location of the delete directory
69 054 | disksize | size of the disk in blocks
70 058 | rblk extension | reference to rootblock extension
71 05c | reserved_2 |
72 |___________________|
73 060 | |
74 | bitmap index | reference to bitmap index blocks
75 | |
76 |___________________|
77 074 | |
78 | anode index | reference to anode index blocks
79 | | (not if MODE_SUPERINDEX enabled)
80 200 |___________________|
83 With the disktype field PFS3 recognizes that the disk is a PFS disk. It is
84 the same as what can be found in the bootblock.
86 Options is a 32 bit field which specifies which PFS3 extensions are enabled.
87 The table below states the bit number, the symbolic name, the release in
88 which the option was introduced and its meaning.
90 bit | name | rel | function
91 ----|----------------------|-----|-----------------------------------------
92 0 | MODE_HARDDISK | 4.1 | harddisk mode if 1; currently always 1
93 1 | MODE_SPLITTED_ANODES | 4.1 | anodes splitted in block/offset if 1
94 2 | MODE_DIR_EXTENSION | 4.1 | enables directory-entry extension
95 3 | MODE_DELDIR | 4.1 | deldir enabled if 1
96 4 | MODE_SIZEFIELD | 4.1 | the disksize field (offset 0x54) is valid
97 5 | MODE_EXTENSION | 4.1 | the rootblock extension is enabled
98 6 | MODE_DATESTAMP | 4.1 | block datestamps enabled if 1
99 7 | MODE_SUPERINDEX | 4.2 | extension that makes disks >5G possible
100 8 | MODE_SUPERDELDIR | 5.0 | extension that makes larger deldir possible
101 9 | MODE_EXTROVING | 5.0 | reserved roving pointer is per block (was 32)
102 10 | MODE_LONGFN | 5.0 | support for long filenames
104 PFS3 has, by default, all options enabled. One exception to this is
105 MODE_SUPERINDEX, which is only enabled for disks larger than 5G. If
106 MODE_SUPERINDEX is enabled, the list of bitmap index blocks is larger
107 and covers offset 060 to 200 of the rootblock. The anodeindex blocks
108 are referenced by a new blocktype: the superblock which can be reached
109 from the rootblock extension.
111 PFS3 checks the options when the volume is mounted. If MODE_DELDIR is
112 cleared, PFS3 will automatically create a delete directory and set
113 MODE_DELDIR. The rootblock extension is also automatically created if not
114 present.
116 If future versions of PFS3 extend the diskstructure this will be reflected by
117 a new option bit.
119 All 'not_used' fields are reserved for future use and must be set to 0.
121 First and last reserved indicate the 'reserved area'. All disk
122 information, like directories, allocation data etc are stored in this
123 reserved area. The rest of the disk is available for data. Currently
124 firstreserved always is 2, so the reserved area starts with the rootblock.
125 'Reserved free' indicates the number of reserved blocks that are
126 unoccupied.
128 The 'datestamp' is an update counter. When the disk is formatted, all blocks
129 will have a datestamp of 0. Every time the disk is updated (goes from one
130 state to the next using atomic commit), the datestamp is increased by one.
131 Using the datestamp all blocks in the reserved area can be ordered in time.
132 This is usefull for repair tools enabling easier and more reliable recovery
133 of a broken volume.
135 'Blksize' indicates the size of reserved blocks in bytes. Currently this
136 is always 1024 (1K), independent of the actual blocksize. The actual
137 blocksize (as specified in the mountlist) can be either 512 or 1024 byte.
138 So if blocks are 512 byte, which is the normal case, each reserved block
139 takes two blocks on disk. BTW: the before mentioned first and last
140 reserved indicate real blocknumbers, not reserved block numbers. However,
141 'reserved free' does refer to reserved blocks. It indicates the number of
142 reserved blocks that can be allocated before the reserved area is full.
144 Blocks free indicates the number of free blocks. It is equal to the total
145 number of blocks on the disk - the number of reserved blocks - 2 - the
146 number of blocks taken by data. PFS always keeps a small part of the data
147 area free. This is indicated by 'always free'.
149 The roving pointer is used for allocation. If you change any bitmap blocks
150 it is wise to set this pointer to zero. This will never hurt.
152 ********************
153 * Block ID
154 ********************
156 The following blocks each have a 2 byte block id field. This indicates the
157 blocktype. Currenly used IDs are:
159 DB -- dirblock
160 AB -- anodeblock
161 IB -- anode index block
162 BM -- bitmap block
163 MI -- bitmap index block
164 DD -- deldir block
165 EX -- rootblock extension
166 SB -- super block
168 ********************
169 * Bitmap blocks
170 ********************
172 To keep track of which blocks are occupied and which are not, PFS uses
173 bitmap blocks. Such a block looks like this:
175 ___________________
176 | | |
177 000 | id | x |
178 |_________|_________|
179 | |
180 004 | datestamp |
181 008 | sequence number |
182 |___________________|
183 00c | |
184 | the bitmap |
185 | |
186 400 |___________________|
189 Each block has room for 253 longwords allocating 8096 blocks. Each bit
190 represents a block and a bit is set if it is available, and clear when it
191 is taken.
193 There are two bitmaps, one for the reserved area and one for the data area.
194 For the data area several bitmap blocks are needed. They are numbered with
195 the sequence number field, starting with 0. The first bit of the first
196 bitmap block represents the first data block (the block directly behind the
197 last reserved block)
199 The bitmap for the reserved area is directly behind the rootblock. The
200 rootblock cluster field in the rootblock (rblkclt) indicates the number of
201 blocks occupied by the rootblock together with the reserved bitmap. The
202 reserved bitmap has the same header as the data bitmap, but has a different
203 size. The rootblock cluster is chosen such, that it can contain the
204 rootblock itself and the entire reserved bitmap, and it is rounded up to a
205 multiple of 1024 byte blocks.
207 The first bit of the reserved bitmap represents the first reserved block
208 (usually 2). Each bit represents a 1024 byte reserved block.
211 ********************
212 * Index blocks
213 ********************
215 PFS refers to bitmap and anode blocks by using index blocks. These blocks
216 look like this:
218 ___________________
219 | | |
220 000 | id | x |
221 |_________|_________|
222 | |
223 004 | datestamp |
224 008 | sequence number |
225 |___________________|
226 00c | |
227 | 253 indices |
228 | |
229 400 |___________________|
233 Each block contains references to 253 anode or bitmap blocks. For large
234 disks several index blocks will be needed. They are numbered with the
235 sequence number, starting with 0.
237 There is a maximum of 5 bitmap index blocks and 99 anode index blocks. The
238 rootblock contains the pointers to these blocks.
240 An anode or bitmap block of a certain sequence number doesn't exist if the
241 corresponding field in the index is zero. Holes in the index are allowed
242 (e.g. it is possible for anode block 5 to exist, while 4 doesn't).
244 ********************
245 * Anode blocks
246 ********************
248 Files and directories take space on the disk. PFS keeps track of which
249 objects takes which blocks by means of so called anodes. Anodes are stored
250 in anode blocks, which look like this:
252 ___________________
253 | | |
254 000 | id | x |
255 |_________|_________|
256 | |
257 004 | datestamp |
258 |___________________|
259 | |
260 008 | sequence number |
261 |___________________|
262 | |
263 00c | reserved |
264 |___________________|
265 010 | |
266 | 84 anodes |
267 | |
268 400 |___________________|
270 The way anodes are numbered depends on the MODE_SPLITTED_ANODES:
272 MODE_SPLITTED_ANODES disabled:
273 The anodes are numbered starting with 0. The first 84 are in anodeblock 0,
274 the next 84 in anodeblock 1 etc. Each object (file or directory) is
275 identified by such an anode number.
277 MODE_SPLITTED_ANODES enabled:
278 The first 16 bit of the anode indicate the anodeblock by sequence number.
279 The following 16 bit indicate the offset within the anodeblock. So anode
280 0x00010004 is the fifth anode in the second anodeblock.
283 An anode looks like this:
285 ___________________
286 | |
287 000 | clustersize |
288 004 | blocknr |
289 008 | next |
290 |___________________|
292 The clustersize indicates how many blocks are allocated by this anode. The
293 blocknr is the first block allocated. So an unfragmented file can always
294 be allocated by a single anode. A fragmented file, however, needs one
295 anode for each fragment. For that purpose is the next field. It indicates
296 the anode number of the next fragment. If this is the last fragment, the
297 next field will be zero.
299 The clustersize and blocknr in an anode always refer to real block numbers,
300 even if the blocks are in the reserved area.
302 If all fields of the anode are zero, it is considered free and can be
303 reused.
305 It is possible to associate an anode with a file without allocation any
306 blocks. This can be done by setting the clustersize and next fields to 0
307 and the blocknr field to -1.
309 The first six anodes have a special meaning:
311 anode name use
312 ----------------------------------------------
313 0 ANODE_EOF should always be 0
314 1 not used, set to 0
315 2 not used, set to 0
316 3 not used, set to 0
317 4 ANODE_BADBLOCKS Bad block list. Not used by PFS3. Repair
318 tools can chain bad blocks to this anode
319 5 ANODE_ROOTDIR The anode of the root directory. You can find
320 the root directory by looking at this anode
322 All anodes from 6 and higher are used for directory and file allocation.
325 ********************
326 * dirblocks
327 ********************
329 Directories have an anode number, just like files. Each anode points to
330 one directory block of 1024 byte (so, with 512 byte blocks, the clustersize
331 field of an anode belonging to a directory is always 2). If 1024 byte is
332 not enough for the directory, a new block with a new anode is allocated and
333 chained to the first. Two anodes belonging to the same directory are never
334 joined to form one (by increasing the clustersize).
336 A dirblock looks like this.
338 ___________________
339 | | |
340 000 | id | x |
341 |_________|_________|
342 004 | |
343 | datestamp |
344 |___________________|
345 | |
346 008 | reserved |
347 |___________________|
348 | |
349 00c | anodenr |
350 010 | parent |
351 |___________________|
352 014 | |
353 | directory entries |
354 400 |___________________|
357 The anodenr (anode number) refers to the anode belonging to the directory,
358 not the anode belonging to the block. So it always points to the head of
359 the anode chain, and is the same for all blocks of the same directory.
361 The parent is the anode number of the parent of this directory, or 0 if
362 this is the rootdirectory (which doesn't have a parent).
365 A directory entry looks like this:
367 ___________________
368 | | |
369 000 | next | type |
370 |_________|_________|___________________
371 | |
372 002 | anode number |
373 006 | size |
374 |_______________________________________|
375 | |
376 00a | creation day |
377 00c | creation minute |
378 00e | creation tick |
379 |___________________|
380 | | |
381 010 | prot | nlength |
382 |_________|_________|
383 | |
384 012 | name |
385 | |
386 |___________________|
387 012 + | |
388 nlength | flength |
389 |_________|_________
390 013 + | |
391 nlength | filenote |
392 | |
393 |___________________|
395 | | MODE_DIREXTENSION only
396 | extension |
398 | |
400 |___________________|
403 The next field indicates the length of this directory entry in bytes. This
404 must always be even.
406 The type is the type of direntry, just like FFS: ST_FILE, ST_USERDIR etc.
407 See include file <dos/dosextens.h> for details.
409 The anode number is the head of the anode chain for this object. The size
410 is the filesize in bytes. The number of blocks in the anode chain must
411 correspond to the number of blocks needed to store 'size' bytes.
413 The creation day, minute and tick is the DOS timestamp of the object. The
414 protection are the lower 8 file protection bits, like FFS.
416 The name and the filenote are pascal strings (length followed by that
417 number of characters). They are placed directly behind each other and are
418 byte aligned. If the file has no filenote, flength will be zero.
420 Each directory entry is padded if that is needed to word align the next
421 directory entry.
423 The end of the directory block is indicated by appending a zero at the end
424 of the last entry. The directory ends with the last entry in the last
425 block, where the blocks are chained by anodes.
427 ********************
428 * dirextension
429 ********************
431 If MODE_DIREXTENSION is enabled some optional extra WORD size fields are
432 added after the word align pad. The last extension field is a WORD size
433 bitfield that indicates which fields are present.
435 Currently the extra fields include:
437 ___________________
438 | |
439 | link (high) | Anodenr of link
440 |___________________|
441 | |
442 | link (low) |
443 |___________________|
444 | |
445 | uid | User ID
446 |___________________|
447 | |
448 | gid | Group ID
449 |___________________|
450 | |
451 | prot (high) | 32 bit protection field
452 |___________________|
453 | |
454 | prot (low) |
455 |___________________|
456 | |
457 | virtualsize (high)| 32 bit virtual size (for rollover files)
458 |___________________|
459 | |
460 | virtualsize (low) |
461 |___________________|
462 | |
463 | rollpointer (high)| 32 bit rollpointer (for rollover files)
464 |___________________|
465 | |
466 | rollpointer (low) |
467 |___________________|
468 | |
469 | flagfield | Only field that always is present
470 |___________________|
472 'Link' is for links, described later. The prot field is combined with the
473 8 bit protection field direntry->protection (OR operation) to form a 32 bit
474 protection value. If the upper 24 bit are zero, this prot field will not
475 be used. The filesystem only checks direntry->protection when accessing
476 files.
478 The following code fragments show how to extract and make extrafields. Used
479 macros and types can be found in 'pfs.h'.
481 void GetExtraFields (struct direntry *direntry, struct extrafields *extrafields)
482 {
483 UWORD *extra = (UWORD *)extrafields;
484 UWORD *fields = (UWORD *)(((UBYTE *)direntry)+direntry->next);
485 UWORD flags, i;
487 flags = *(--fields);
488 for (i=0; i < sizeof(struct extrafields)/2; i++, flags>>=1)
489 *(extra++) = (flags&1) ? *(--fields) : NULL;
490 }
492 static void AddExtraFields (struct direntry *direntry, struct extrafields *extra)
493 {
494 UWORD offset, *dirext;
495 UWORD array[16], i=0, j=0;
496 UWORD flags = 0, orvalue;
497 UWORD *fields = (UWORD *)extra;
499 offset = (sizeof(struct direntry) + (direntry->nlength) + *FILENOTE(direntry))&0xfffe;
500 dirext = (UWORD *)((UBYTE *)(direntry) + (UBYTE)offset);
502 orvalue = 1;
503 /* fill packed field array */
504 for (i=0; i < sizeof(struct extrafields)/2; i++)
505 {
506 if (*fields)
507 {
508 array[j++] = *fields++;
509 flags |= orvalue;
510 }
511 else
512 {
513 fields++;
514 }
516 orvalue <<= 1;
517 }
519 /* add fields to direntry */
520 i=j;
521 while (i)
522 *dirext++ = array[--i];
523 *dirext++ = flags;
525 direntry->next = offset + 2*j + 2;
526 }
528 BTW: if MODE_DIREXTENSION is enabled, the flags field must always be
529 present, even if none of the other fields are used. An unused field is
530 assumed to be zero.
532 ********************
533 * hard links
534 ********************
536 The main object (the object that is linked to) has type ST_FILE (ST_DIR)
537 like an ordinary file (dir). Its anodenr points to the object data, as
538 usual. The link field in the directory extension points to the head of the
539 LINK LIST.
541 The LINK LIST is mapped on an anode list. The 'link' is nothing more than
542 an anode number. The fields have been redefined, however:
544 ___________________
545 | |
546 000 | object dir |
547 004 | link dir |
548 008 | next |
549 |___________________|
551 Each entry in the LINK LIST represents a link (the object itself doesn't
552 have a LINK LIST node).
554 The 'object dir' is the anode number of the directory where the object can
555 be found. The 'link dir' is the anodenr of the directory where the link
556 can be found. 'Next' is the anodenr of the next LIST NODE or 0 for end of
557 list.
559 A link has type ST_LINKFILE (ST_LINKDIR). Its anode number points to its
560 LINK LIST element. The link entry in the directory extension is the
561 anode number of the object.
563 A link can be resolved as follows:
564 · Get LINK LIST element (anodenr in directory)
565 · Get object dir (object dir field)
566 · Locate object by looking for anodenr as stated in the directory extension
567 link field.
569 BTW: the anode number as stated in the directory is an unique directory
570 entry identifier, even for links.
572 ********************
573 * soft links
574 ********************
576 A softlink is a file of length strlen(target) and type ST_SOFTLINK. The
577 block containing the name of the target can be located by reading the link
578 as a file (anode.blocknr).
580 ********************
581 * deldir
582 ********************
584 The deldir is a hidden directory that contains the 31 most recently deleted
585 and overwritten files. It can be accessed from the root by its name
586 '.deldir'.
588 The delete directory looks like this:
590 ___________________
591 | | |
592 000 | id | x |
593 |_________|_________|
594 | |
595 004 | datestamp |
596 |___________________|
597 | |
598 010 | roving | (<4.3) current delete position
599 012 | uid | (<4.3) deldir user id
600 014 | gid | (<4.3) deldir group id
601 016 | protection | (<4.3) deldir protection (LW)
602 01a | creationday | (<4.3)
603 01c | creationminute | (<4.3)
604 01e | creationtick | (<4.3)
605 |___________________|
606 020 | |
607 | |
608 | 31 deldirentries |
609 | |
610 400 |___________________|
613 The deldir contains 31 slots containing deldirentries. These slots are
614 filled in a round-robin manner, using 'roving' as position pointer.
616 A deldirentry looks like this:
618 ___________________
619 | |
620 000 | anodenr |
621 004 | size | size in bytes
622 008 | creationday | datestamp (copied from original file)
623 00a | creationminute |
624 00c | creationtick |
625 |___________________|
626 00e | |
627 | filename | filename, truncated to 17 characters
628 020 |___________________|
631 'filename' is a pascal string; length followed by 17 characters.
633 When a file is deleted or overwritten it is added to the deldir in the slot
634 indicated by 'roving'. Only files are put in the deldir, no directories or
635 links. The diskspace taken by these files is freed at the moment the
636 original file is deleted, so an entry in the deldir can become invalid at
637 any time data is written to the disk. When the deldir is scanned (e.g. by
638 calling "dir pfs:.deldir") PFS will check the vadility of each entry and
639 will return only the valid entries. The scan routine adds the deldir slot
640 number to each entry (e.g. foo@003) to make sure each entry has an unique
641 name. Files in the deldir should also be accessed by that name.
643 The anodechain taken by a deldirentry is not freed until the deldirentry is
644 reused.
646 ********************
647 * rootblock extension
648 ********************
650 AFS version 16.4 introduced the rootblock extension. This is a reserved
651 area block that contains general information about the disk that didn't fit
652 in the rootblock. The block is referenced by the 'extension' field in the
653 rootblock. Its presence is indicated by the MODE_EXTENSION bit in the
654 rootblock options field. PFS3 automatically creates the rootblock
655 extension on older disks, so every disks that is operated on PFS3 should
656 have an extension block.
658 The rootblock extension looks like this:
660 ___________________
661 | | |
662 000 | id | x |
663 |_________|_________|
664 | |
665 004 | ext. options | flags for (future) options. Currently 0.
666 008 | datestamp |
667 00c | pfsversion | PFS revision id.
668 |___________________|
669 | |
670 010 | rootdate day, min | the root directory datestamp
671 |___________________|
672 | |
673 014 | tick |
674 |_________|_________
675 | |
676 016 | voldate day, min | the volume datestamp
677 |___________________|
678 | |
679 01a | tick |
680 |_________|_________
681 | |
682 01c | postponed - |
683 | operation |
684 |___________________|
685 | |
686 02c | reserved roving | reserved area roving pointer
687 |___________________|
688 | |
689 030 | roving bit | roving pointer bitnumber (normal area)
690 |___________________|
691 | |
692 032 | current anode seq | roving pointer for anode allocation
693 |___________________|
694 | | |
695 034 | dd_rov | dd_size | roving pointer and size of deldir
696 |_________|_________|
697 | |
698 038 | fnsize | filename size (18 +)
699 |_________|_________
700 | |
701 03a | x |
702 |___________________|
703 | |
704 040 | superindex | MODE_SUPERINDEX only: upto 16 superblocks
705 | |
706 | · |
707 | · |
708 |___________________|
709 | | |
710 080 | dd_uid | dd_gid | uid and gid of delete directory
711 |_________|_________|
712 | |
713 084 | dd_protection | protection of delete directory
714 |___________________|
715 | |
716 088 | deldir day, min | deldir datestamp
717 |___________________|
718 | | |
719 08c | tick | x |
720 |_________|_________|
721 | |
722 090 | deldir | upto 32 deldir blocks
723 | |
724 | · |
725 | · |
726 |___________________|
727 110 | . |
728 | . |
729 | . |
730 400 |___________________|
733 PFS stores the current revision id (version number in high word, revision
734 number in low word, e.g. $00100004 for version 16.4) in the 'pfsversion' field
735 when formatting a disk. This way the oldest PFS revision that accessed the
736 volume can be identified. The two new dates, rootdate and volumedate,
737 complement the creationdate in the rootblock. The three datestamps are used as
738 follows:
740 Volume creation date (rootblock): Only set by format and by
741 ACTION_SERIALIZE_DISK.
743 Volume date (extension): Zerod by format. Touched each update.
745 Root date (extension): Root directory datestamp.
747 The postponed operation is a 4 longword field used internally by PFS3. It is to
748 be considered an error if these fields are non-zero on an inhibited PFS3 volume.
750 The superindex is for MODE_SUPERINDEX only. The longwords in the superindex are
751 references to superblocks. A superblock is an indexblock which indexes anodeindex
752 blocks.
755 ********************
756 * rollover files
757 ********************
759 Rollover files are files with a filesystem enforced maximum size. When the file
760 is appended to it will be trimmed to keep the size under the maximum.
762 Rollover files are identified by the filetype ST_ROLLOVERFILE (== -16). The
763 size field in the directory specifies how much diskspace is allocated for the
764 rollover file. The virtualsize field in the extrafields indicates how much of
765 the allocated diskspace currently is in use. This will initially be 0 and grow
766 until it is equal to the allocated diskspace (extrafields->vitualsize ==
767 direntry->size). The virtual size can never be larger than the allocated size.
768 The rollpointer field in the extrafields specifies the location in the
769 allocated area where the rollover file starts. Rollover files are read
770 circular, starting and ending at the rollover pointer.
772 Example rollover file with 2048 allocated bytes:
774 0 real offsets 2047
775 ______________________________________________________________
776 | | | |
777 | L|N|F |
778 |____________________________|_|_______________________________|
780 virtual offsets 2046 0
782 <-------------------------------------------------------------->
783 allocated area
784 2048 bytes
786 L = last byte of file
787 N = end of file
788 F = first byte of file
790 The usable size of rollover files always is a multiple of the blocksize
791 minus one.