Chapter 33
Disk Partition Interpreter: liboskit_diskpart.a

33.1 Introduction

The OSKit includes code that understands the various partitioning schemes used to divide disk drives into smaller pieces for use by filesystems. This code enables the use of various (possibly nested) partitioning schemes in an easy manner without requiring knowledge of which partitioning scheme was used, or how these partitioning schemes work. E.g., you don’t need to understand or know the format of a VTOC to use the partitioning, as the library does all of it for you.

33.2 Supported Partitioning Schemes

Supported partitioning schemes are:

33.3 Example Use

33.3.1 Reading the partition table

This shows how the partitioning information can be extracted in user-mode (running under Unix). In the kernel, it would likely be necessary to pass a driver_info structure to a device-specific read function. In this case, driver_info is simply a filename string.

 /* This is the testing program for the partitioning code. */
 #include <oskit/diskpart/diskpart.h>
 #include <stdio.h>
 #include <fcntl.h>
 
 #define FILENAME "/dev/sd0c"
 
 /* We pass in a fixed-size table; this defines how big we want it. */
 #define MAX_PARTS 30
 diskpart_t part_array[MAX_PARTS];
 
 /*
  * In this case, we are defining the disk size to be 10000 sectors.
  * Normally, this would be the number of physical sectors on the
  * disk.  If the `disk' is a `file', it would be better to get the
  * equivalent number of sectors from the file size.
  * This is only used to fill in the whole-drive partition entry.
  */
 #define DISK_SIZE 10000
 
 /*
  * This is the function pointer I pass to the partition code
  * to read sectors on the drive.
  */
 int my_read_fun(void *driver_info, int sector, char *buf);
 
 
 int
 main(int argc, char *argv[])
 {
         int numparts;
         char *filename;
 
         if (argc == 2)
                 filename = argv[1];
         else
                 filename = FILENAME;
 
         /* call the partition code */
         numparts = diskpart_get_partition(filename, my_read_fun, part_array,
                 MAX_PARTS, DISK_SIZE);
 
         printf("%d partitions found\n",numparts);
         /* diskpart_dump(part_array, 0); */
 }
 
 static int
 my_read_fun(void *driver_info, int sector, char *buf)
 {
         char *filename = driver_info;
 
                                                                                         
                                                                                         
         int fd = open(filename, O_RDONLY, 0775);
 
         lseek(fd, SECTOR_SIZE * sector, SEEK_SET);
         read(fd, buf, SECTOR_SIZE);
         close(fd);
 
         /* Should bzero the result if read error occurs */
         return(0);
 }

33.3.2 Using Partition Information

The routine diskpart_lookup_bsd_compat is an example of how the old partition naming can be used even with the new nested structure. This takes two integers representing the slice and partition. The behavior is intended to be similar to diskpart_lookup_bsd_string (below), using integers as parameters.

While this ‘hack’ allows two levels of nesting (slice and partition), it is not general enough to support arbitrary nesting. Arbitrary nesting support is most easily achieved by passing string names to a lookup function which can follow the structure down the partition specifications. For example, ‘sd0eab’ would be used to specify the second partition in the first partition inside the fifth top-level partition on the first SCSI disk. Since the lookup routine doesn’t need to know about the disk, ‘eab’ would be the partition name passed to the lookup routine. This naming scheme would work well as long as there are not more than 26 partitions at any nesting layer.

diskpart_lookup_bsd_string does a string lookup using the FreeBSD style slice names. FreeBSD considers the DOS partitioning to be slices. A slice can contain a BSD disklabel, and if it does, then partitions can be inside the slice. If the third DOS partition contains a disklabel, then ‘s3a’ would be partition ‘a’ inside the disklabel. The slice name without a partition would mean the entire slice. Note also that ‘a’ would alias to partition ‘a’ in the first BSD slice. If there is no BSD slice, then ‘a’ would be aliased to ‘s1’ instead. However, to avoid confusion, if slice-naming is used, aliases should only be used to point inside a BSD slice.

33.4 Restrictions

This is a list of known restrictions/limitations of the partitioning library.

33.4.1 Endian

The partitioning code only recognizes labels created with the same endian-ness as the machine it is running on. While it is quite possible to detect an endian conflict and interpret the information in the label, the information stored in the partitions will probably not be very useful, as most filesystems expect the numeric representations to remain constant.

33.4.2 Nesting

Strict nesting, in which a child is not allowed to extend outside the parent, is not enforced, or even checked by the library. This allows greater flexibility in the use of nested partitions, while also placing greater responsibility on the user’s shoulders to ensure that the partition information on the disk is correct. Enforcement of strict nesting, should it be desired, is left to the user.

Due to previous constraints, the search routine does not yet do a recursive search for all possible nestings, although all ‘sensible’ ones are searched manually. This is a change that will be incorporated as soon as nesting of this type exists and it can be utilized by something.

33.4.3 Lookup

A general lookup routine is not yet part of the library. The diskpart_lookup routine is only able to do one layer of nesting. More general support may be added in the future, or it may be left to the user to determine a naming scheme to access the subpartitions.

Also, the lookup routines currently assume a sector size of 512 bytes.

33.5 API reference

33.5.1 diskpart_get_partition: initialize an array of partition entries

SYNOPSIS

#include <oskit/diskpart/diskpart.h>

int diskpart_get_partition(void *driver_info, int (*diskpart_read_func)(), struct diskpart *array, int array_size, int disk_size);

DESCRIPTION

This function initializes an array of struct diskpart entries. The caller must provide a pointer to a struct diskpart array, and a function to read the disk.

PARAMETERS
driver_info:
A pointer to an initialized structure of user-defined type which is passed unmodified to diskpart_read_func.
diskpart_read_func:
A function pointer provided by the user which can read a sector given driver_info.
array:
Array of struct diskpart.
array_size:
integer containing the number of allocated entries in the array.
disk_size:
Size of the whole disk, in sectors.
RETURNS

Returns an integer count of the number of partition entries that were filled by the library. If there were more partitions found than space available, this will be array_size. Empty partitions (unused entries in a BSD disklabel, for example) occupy an entry the same as ‘used’ entries.

For example, a PC-DOS partition with a single filled entry would still report 4 partitions, as that is the size of the DOS partition table.

RELATED INFORMATION

diskpart_read_func

33.5.2 diskpart_read_func: read a disk sector (user-provided callout)

SYNOPSIS

#include <oskit/diskpart/diskpart.h>

int diskpart_read_func(void *driver_info, int sector, char *buf);

DESCRIPTION

This function is called from diskpart_get_partition and diskpart_get_type whenever they need to read data from the target disk.

PARAMETERS
driver_info:
The parameter passed to diskpart_get_partition and diskpart_get_type . Used to pass data through the diskpart library to this read routine.
sector:
The sector to read.
buf :
Memory location where the sector should be read in to. The buffer must be at least SECTOR_SIZE bytes.
RETURNS

Returns zero on success, non-zero to indicate an error.

33.5.3 diskpart_blkio_get_partition: initialize an array of partition entries

SYNOPSIS

#include <oskit/diskpart/diskpart.h>

int diskpart_blkio_get_partition(oskit_blkio_t *block_io, struct diskpart *array, int array_size);

DESCRIPTION

This function initializes an array of struct diskpart entries. The caller must provide a pointer to a struct diskpart array.

This function is a version of diskpart_get_partition using an OSKit “Block I/O” interface in place of an explicit callback function.

PARAMETERS
block_io:
An oskit_blkio_t that represents the disk whose partitions we are interested in.
array:
Array of struct diskpart.
array_size:
integer containing the number of allocated entries in the array.
RETURNS

Returns an integer count of the number of partition entries that were filled by the library. If there were more partitions found than space available, this will be array_size. Empty partitions (unused entries in a BSD disklabel, for example) occupy an entry the same as ‘used’ entries.

For example, a PC-DOS partition with a single filled entry would still report 4 partitions, as that is the size of the DOS partition table.

RELATED INFORMATION

The OSKit Block I/O Interface (section 7.3).

33.5.4 diskpart_fill_entry: initialize a single partition entry

SYNOPSIS

#include <oskit/diskpart/diskpart.h>

void diskpart_fill_entry(struct diskpart *array, int start, int size, struct diskpart *subs, int nsubs, short type, short fsys);

DESCRIPTION

This function initializes a single partition entry.

PARAMETERS
array:
Pointer to the struct diskpart entry to be filled
start:
Starting sector on the disk for the partition.
size:
Number of sectors in the partition.
subs:
Pointer to its first child partition.
nsubs:
Number of sub-partitions.
type:
Partition type, as defined in diskpart.h
fsys:
Filesystem in the partition (if known), as defined in diskpart.h

33.5.5 diskpart_dump: print a partition entry to stdout

SYNOPSIS

#include <oskit/diskpart/diskpart.h>

void diskpart_dump(struct diskpart *array, int level);

DESCRIPTION

This function prints a partition entry with indentation and labeling corresponding to its nesting level. It also recursively prints any child partitions on separate lines, with level+1.

This provides valuable diagnostic messages for debugging disk or filesystem problems.

PARAMETERS
array:
A pointer to the first entry to be printed. It and any sub-partitions are printed.
level:
int representing current level. This controls indentation and naming of the output. diskpart_dump called with the root struct diskpart entry and 0 will print the entire table.
RETURNS

Returns nothing, but does write to stdout.

33.5.6 diskpart_lookup_bsd_compat: search for a partition entry

SYNOPSIS

#include <oskit/diskpart/diskpart.h>

struct diskpart *diskpart_lookup_bsd_compat(struct diskpart *array, short slice, short part);

DESCRIPTION

This function is a sample lookup routine which finds a partition given a slice number and partition number.

This demonstrates how a two-level naming scheme can be implemented using integers. This was first used in Mach 4 (UK22) to provide support for FreeBSD slices as well as backwards-compatibility with previous naming methods.

PARAMETERS
array:
This should be the pointer to the start of the array.
slice:
Slice 0 is used as a ‘compatibility slice’, in that it is aliased to a BSD partition, if it exists. This allows users to not specify the slice for compatibility.
part:
Partition 0 is used to represent the whole slice, and Partition 0, Slice 0 is the whole drive.
RETURNS

Returns a pointer to the corresponding partition entry, or zero if it is invalid.

33.5.7 diskpart_lookup_bsd_string: search for a partition entry

SYNOPSIS

#include <oskit/diskpart/diskpart.h>

struct diskpart *diskpart_lookup_bsd_string(struct diskpart *array, char *name);

DESCRIPTION

This function is a sample lookup routine which finds a partition given a FreeBSD style slice string. If no slice number is given, it defaults to the first BSD partition, and then to the whole disk if no BSD partition is found.

PARAMETERS
array:
This should be the pointer to the start of the array.
name:
A case-insensitive, NULL-terminated, ASCII string containing an optional Slice specifier followed by an optional partition. [s<num>][<part>], where part is a valid partition in the BSD slice specified by num (or default).
RETURNS

Returns a pointer to the corresponding partition entry, or zero if it is invalid.

33.5.8 diskpart_blkio_lookup_bsd_string: search for a partition entry

SYNOPSIS

#include <oskit/diskpart/diskpart.h>

struct diskpart *diskpart_blkio_lookup_bsd_string(struct diskpart *array, char *name, oskit_blkio_t *block_io, [out] oskit_blkio_t **out_block_io);

DESCRIPTION

This is similar to (and uses) diskpart_lookup_bsd_string but returns an OSKit “Block I/O” interface for the partition; i.e., operations on the returned oskit_blkio_t are restricted to the bounds of the partition.

PARAMETERS
array:
This should be the pointer to the start of the array.
name:
A case-insensitive, NULL-terminated, ASCII string containing an optional Slice specifier followed by an optional partition. [s<num>][<part>], where part is a valid partition in the BSD slice specified by num (or default).
block_io:
The oskit_blkio_t whose partitions we are interested in.
out_block_io:
A pointer to the new oskit_blkio_t.
RETURNS

Returns a pointer to the corresponding partition entry, or zero if it is invalid.

RELATED INFORMATION

diskpart_lookup_bsd_string, the OSKit Block I/O Interface (section 7.3).

33.5.9 diskpart_get_type : Search for type type partitions

SYNOPSIS

#include <oskit/diskpart/diskpart.h>

int diskpart_get_type(struct diskpart *array, char *buf, int start, void *driver_info, int (*diskpart_read_func)(), int max_part);

DESCRIPTION

This function finds type type partitions if they are on the disk. These routines would not normally be invoked directly. However, the API is documented here so that diskpart_lookup can be extended easily for future or additional labeling schemes.

Currently defined functions are: pcbios, disklabel, vtoc, dec, and omron.

They should return immediately if diskpart_read_func returns non-zero, and return that error code.

PARAMETERS
array:
Pointer to the start of preallocated storage.
buf :
Pointer to a sector-sized scratch area.
start:
Offset from start of disk the partition starts.
driver_info:
A pointer to an initialized structure of user-defined type which is passed unmodified to diskpart_read_func.
diskpart_read_func:
A function pointer provided by the user which can read a sector given driver_info.
max_part:
Maximum number of partition entries that can be filled. This will generally be equal to the number of pre-allocated entries that are available.
RETURNS

Returns the number of partition entries of that type found. If none were found, it returns 0.

If the return value is equal to max_part then it is possible that there were more partitions than space for them. It is up to the user to ensure that adequate storage is passed to diskpart_get_partitions.

RELATED INFORMATION

diskpart_read_func