Disk — C Library Procedures

NAME

Disk_ReadLabel, Disk_WriteLabel, Disk_EraseLabel, Disk_NewLabel, Disk_ReadDecLabel, Disk_WriteDecLabel, Disk_ReadSunLabel, Disk_WriteSunLabel, Disk_HasFilesystem, Disk_ReadLfsSuperBlock, Disk_WriteLfsSuperBlock, Disk_ReadLfsCheckpointHdr, Disk_WriteLfsCheckPointHdr, Disk_WriteLfsCheckPointArea, Disk_LfsCheckpointTrailer, Disk_ForEachCheckpointRegion, Disk_ReadDomainHeader, Disk_WriteDomainHeader, Disk_ReadSummaryInfo, Disk_WriteSummaryInfo, Disk_SectorRead, Disk_SectorWrite, Disk_BlockRead, Disk_BlockWrite, Disk_BadBlockRead, Disk_FragRead, Disk_FragWrite, Disk_PrintDomainHeader, Disk_PrintSummaryInfo, Disk_PrintFileDescBitmap, Disk_PrintDataBlockBitmap, Disk_PrintDirEntry, Disk_PrintLabel, Disk_PrintLfsSuperBlock, Disk_PrintLfsSuperBlockHdr, Disk_PrintLfsDescMapParams, Disk_PrintLfsSegUsageParams, Disk_PrintLfsFileLayoutParams, Disk_PrintLfsStableMemParams, Disk_PrintLfsCheckpointHdr, Disk_PrintLfsCheckpointRegion, Disk_PrintLfsCheckpointTrailer − Package for accessing OFS and LFS file systems via raw disks

SYNOPSIS

#include <disk.h>
Disk_Label ∗
Disk_ReadLabel(fileID)
int
Disk_WriteLabel(fileID, labelPtr)
Disk_Label ∗
Disk_NewLabel(labelType)
int
Disk_EraseLabel(fileID, labelType)
Dec_DiskLabel ∗
Disk_ReadDecLabel(fileID)
int
Disk_WriteDecLabel(fileID, decLabelPtr)
Sun_DiskLabel ∗
Disk_ReadSunLabel(fileID)
int
Disk_WriteSunLabel(fileID, sunLabelPtr)
Ofs_DomainHeader ∗
Disk_ReadDomainHeader(fileID, labelPtr)
int
Disk_WriteDomainHeader(fileID, labelPtr, headerPtr)
Ofs_SummaryInfo ∗
Disk_ReadSummaryInfo(fileID, labelPtr)
int
Disk_WriteSummaryInfo(fileID, labelPtr, summaryPtr)
int
Disk_SectorRead(fileID, index, count, buffer)
int
Disk_SectorWrite(fileID, index, count, buffer)
int
Disk_BlockRead(fileID, headerPtr, index, count, buffer)
int
Disk_BlockWrite(fileID, headerPtr, index, count, buffer)
int
Disk_BadBlockRead(fileID, headerPtr, index, buffer)
int
Disk_FragRead(fileID, headerPtr, index, count, buffer)
int
Disk_FragWrite(fileID, headerPtr, index, count, buffer)
void
Disk_PrintDomainHeader(headerPtr)
void
Disk_PrintSummaryInfo(summaryPtr)
Disk_PrintLabel(labelPtr)
void
Disk_PrintFileDescBitmap(headerPtr, bitmap)
void
Disk_PrintDataBlockBitmap(headerPtr, bitmap)
void
Disk_PrintDirEntry(dirEntryPtr)
int
Disk_HasFilesystem(fileID, labelptr)
LfsSuperBlock∗
Disk_ReadLfsSuperBlock(fileId, labelPtr)
ReturnStatus
Disk_WriteLfsSuperBlock(fileId, lfsSuperPtr)
LfsCheckPointHdr∗
Disk_ReadLfsCheckPointHdr(fileId, labelPtr, areaPtr)
ReturnStatus
Disk_WriteLfsCheckPointHdr(fileId, headerPtr, area, labelPtr)
ReturnStatus
Disk_WriteLfsCheckPointArea(fileId, headerPtr, area, labelPtr)
LfsCheckPointTrailer∗
Disk_LfsCheckPointTrailer(checkPointHdrPtr)
ReturnStatus
Disk_ForEachCheckPointRegion(checkPointHdrPtr, regionProc)
void
Disk_PrintLfsSuperBlockHdr(lfsSuperHdrPtr)
void
Disk_PrintLfsStableMemParams(stableMemPtr)
void
Disk_PrintLfsDescMapParams(descMapPtr)
void
Disk_PrintLfsSegUsageParams(segUsagePtr)
void
Disk_PrintLfsFileLayoutParams(fileLayoutPtr)
void
Disk_PrintLfsSuperBlock(lfsSuperPtr)
void
Disk_PrintLfsCheckPointHdr(checkPointHdr)
void
Disk_PrintLfsCheckPointRegion(regionPtr)
void
Disk_PrintLfsCheckPointTrailer(trailerPtr)

ARGUMENTS

int fileID (in) File descriptor from open of raw disk.

int partition (in) Index of partition to access, 0-7.

Disk_Label ∗labelPtr (in) Basic disk information from Disk_ReadLabel.

Disk_NativeLabelType labelType (in) Type of machine-specific (native) disk label on the disk.

Dec_DiskLabel ∗decLabelPtr Native disk label for ds3100s.

Sun_DiskLabel ∗sunLabelPtr Native disk label for Suns.

int index (in) Index of first (sector/block/fragment) to transfer.

int count (in) Number of (sectors/blocks/fragments) to transfer.

char ∗buffer (in) Buffer for data transferred.

Ofs_DomainHeader ∗headerPtr (in) Disk header information from Disk_ReadDiskHeader.

Ofs_SummaryInfo ∗summaryPtr (in) Disk summary information sector.

char ∗bitmap (in) Array of bitmap bytes.

Fslcl_DirEntry ∗dirEntryPtr (in) Directory entry structure.

LfsSuperBlock ∗lfsSuperPtr (in) LFS Super Block structure.

LfsSuperBlockHdr ∗lfsSuperHdrPtr (in) Static parameters describing LFS layout on disk.

LfsCheckPointHdr ∗checkPointHdrPtr (in)
Structure describing and heading a LFS checkpoint area.

int areaPtr (out) If non-NULL, returns the checkpoint the header is for.

int area (in) Flag determining the checkpoint area (0 or 1).

LfsCheckPointTrailer ∗trailerPtr (in) Structure capping a LFS checkpoinit area.

int proc(LfsCheckPointRegion∗) regionProc (in)
Procedure used to iterate over the various checkpoint regions between the lfsCheckPointHdr and the lfsChecpointTrailer.

LfsStableMemParams ∗stableMemPtr (in)
Configuration parameters for stable memory data structures.

LfsDescMapParams ∗descMapPtr (in) LFS descriptor map layout on disk.

LfsSegUsageParams ∗segUsagePtr (in) LFS segment usage array layout description on disk.

LfsFileLayoutParams ∗fileLayoutPtr (in) Number of file descriptors to pack together per block.

INTRODUCTION

The Disk package is used to read and write raw disks that are formatted to contain Sprite file systems. To use these routines correctly it is important to understand disk partitions, file system header information, file system blocks, and file system block fragments.

Each physical disk is divided into as many as 8 partitions. The letters ’a’ through ’h’ are used to distinguish these different partitions in the names of the special device files that are used to access them. Thus “/dev/rsd0a” references the first (zero’th) partition on disk rsd0. The partitioning information is stored on the disk in the “disk label”. This label is in a machine-dependent format, and is referred to as the “native disk label”. Native disk labels are kept in a machine-dependent location on the disk. This is usually in sector 0 or some other sector near the start of the first partition. The fsmake program also copies the label to a partition when it formats it into a file system. The routines Disk_ReadSunLabel and Disk_ReadDecLabel can be used to read the native disk labels.

It is not always convenient to deal with native disk labels. For this reason a generic label type and associated routines have been provided. The type Disk_Label is a standard format for disk labels. The routine Disk_ReadLabel is used to read a native disk label off the disk and convert it into a Disk_Label. The routine Disk_WriteLabel will convert a Disk_Label into a native disk label and write it on the disk. Two more procedures are provided for manipulating disk labels. Disk_EraseLabel will erase a native disk label from the disk, and Disk_NewLabel is used to create a new label if the disk does not have one already. The contents of a Disk_Label are defined in <disk.h>.

Disk_HasFilesystem returns the type of file system on the disk. If the disk has a LFS file system, DISK_HAS_LFS is returned; if the disk has an OFS file system, DISK_HAS_OFS is returned; otherwise, DISK_HAS_NO_FS is returned.

The detailed structure of the old sprite file system is defined by a Ofs_DomainHeader structure that is located on the disk according to the Disk_Label. This can be obtained with the Disk_ReadDomainHeader procedure. The Ofs_DomainHeader structure is defined in <kernel/fsdm.h>, and is passed to the block and fragment I/O routines so they can correctly locate blocks and fragments.

A secondary data structure called the summary information is kept on disk following the domain header. The summary information consists of a single sector and contains such information as the number of free blocks and file descriptors. The Ofs_SummaryInfo structure is defined in <kernel/fsdm.h>. The location of the summary sector is stored in the Disk_Label. The summary sector can be read and written using the Disk_ReadSummaryInfo and Disk_WriteSummaryInfo procedures.

The detailed structure of a log structured file system is defined by a LfsSuperBlock structure whose location on disk is determined in <kernel/lfsSuperBlock.h>. This structure can be read off of a disk using Disk_ReadLfsSuperBlock, and written using Disk_WriteSuperBlock.

Disk_ReadLfsCheckpointHdr returns the current LFS checkpoint header, which is also a front for the current checkpoint area whose bulk is hidden behind the LfsCheckPointHdr. If areaPtr is non-NULL, the area number that the header is for gets returned through the pointer. (The area can be either zero or one, and only makes a difference if the checkpoint header is going to be written back out to disk.) Disk_CheckPointTrailer accesses the tail of the checkpoint area from a LfsCheckPointHdr returned from Disk_ReadLfsCheckPointHdr. Disk_WriteLfsCheckPointHdr will write to disk only the LfsCheckPointHdr structure of the specified checkpoint area; Disk_WriteLfsCheckPointArea will write to disk the entire checkpoint area headed by a LfsCheckPointHdr, which is larger than just the structure itself (such as is returned by Disk_ReadLfsCheckPointHdr). Disk_ForEachCheckPointRegions takes a procedural argument and iterates over the LfsCheckPointRegions in the checkpoint area headed by a LfsCheckPointHdr, applying the procedural argument to every region in the checkpoint area. If the procedure returns a non-zero value, then the iteration halts and that value is returned from Disk_ForEachCheckPointRegion.

SECTOR I/O

Disk_SectorRead and Disk_SectorWrite read and write sectors from the disk without regard to the underlying block structure. Their index argument specifies the first sector (starting from zero) to transfer, relative to the start of the partition. The sector offsets given in the Disk_Label structure are useful with this routine.

BLOCK I/O

The file system is arranged in block-sized chunks on the disk. FS_BLOCK_SIZE defines how many bytes this is (currently 4 Kbytes). Due to disk geometry considerations consecutive blocks may or may not be contiguous on disk. Disk_BlockRead and Disk_BlockWrite use geometry and block layout information in the Ofs_DomainHeader to correctly locate disk blocks. The index argument to these routines is a block index, counting from the beginning of the partition (see the warning below!).

Disk_BadBlockRead is used to re-read a bad file system block and determine which sectors are bad. It returns a bitmask with bits set to indicate which of the sectors were successfully read. Bit i in the mask corresponds to sector i in the block. DISK_SECTORS_PER_BLOCK defines how many sector there are in each file system block.

FRAGMENT I/O

Each file system block is sub-divided into fragments to optimize allocation of small files. Currently the fragment size is 1 Kbyte, so there are 4 fragments to each block. Disk_FragRead and Disk_FragWrite are used to read and write fragments. The index argument to these routines is a fragment index, counting from the beginning of the partition (see the warning below!). The count argument to these routines should not be greater than the number of fragments per file system block.

BLOCK AND FRAGMENT INDEXES

WARNING: there are several caveats about block numbers and fragment numbers as used by the Sprite file system. A partition is divided into areas for bitmaps, file descriptors, and data blocks. These divisions are specified in the Ofs_DomainHeader structure in terms of block offsets and number of blocks. However, block numbers are not kept in disk maps, only fragment numbers. When traversing the direct and indirect blocks that define where a file’s blocks are, fragment indexes must be converted to block indexes before using either Disk_BlockRead or Disk_BlockWrite. Also, direct block pointers in the maps are fragment indexes relative to the start of the data block area of the file system. Thus to convert from a direct block pointer to a physical fragment index: fragIndex = blockPointer + (headerPtr->dataOffset ∗ FS_FRAGMENTS_PER_BLOCK); blockIndex = fragIndex / FS_FRAGMENTS_PER_BLOCK;

The last main caveat is that indirect block pointers are physical fragment indexes. They do not need to be offset in the same way as direct block pointers. This applies to any block pointer that points to an indirect block, never to a block pointer that points to a data block.

PRINTING UTILITIES

The last set of procedures in this package are used to print out contents of the file system. Disk_PrintDomainHeader prints out the domain header information. Disk_PrintSummaryInfo prints out the summary disk sector. This sector is used to keep the prefix under which the disk is exported, the current number of blocks allocated and free, and whether or not the disk was safely sync’ed at last reboot. Disk_PrintFileDescBitmap and Disk_PrintDataBlockBitmap print out the file descriptor and data block bitmaps in hex. A zero bit represents a free descriptor or block. Disk_PrintDirEntry prints out a directory entry. Disk_PrintLfsSuperBlock prints out the contents of a LFS Super Block structure. Disk_PrintLfsSuperBlockHdr prints out the static parameters describing the LFS layout on disk. Disk_PrintLfsCheckPointHdr prints out the structure describing and heading a LFS checkpoint area. Disk_PrintLfsCheckPointTrailer prints out the structure capping a LFS checkpoinit area. Disk_PrintLfsStableMemParams prints out the configuration parameters for LFS stable memory data structures. Disk_PrintLfsDescMapParams prints out the LFS descriptor map layout on disk. Disk_PrintLfsSegUsageParams prints out the LFS segment usage array layout description on disk. Disk_PrintLfsFileLayoutParams prints out the number of file descriptors packed together per block.

KEYWORDS

disk, block, sector, fragment

Sprite version 1.0 — August 31, 1992

Museum