gd(7) gd(7)NAME gd - generic disk interface DESCRIPTION The gd device driver provides a generic interface to disk devices. A variety of devices are supported, and support for new hardware may be added via autoconfiguration utili- ties. Consult the specific hardware manual for add-on dev- ices to see if they use the generic disk interface. For SCSI devices, the driver makes a distinction between disks that support the SCSI common command set and those that don't. The Apple(Reg.) document SCSI Command Protocol 062-2075 defines characteristics of the common command set. Certain features, such as changing the reporting of soft er- rors, may not be supported by hardware that does not imple- ment the common command set. The SCSI driver depends on the controller's ability to save configuration information when the drive is turned off. Hardware that does not save this information requires additional device-specific software. The document Building A/UX Device Drivers supplies technical information on extending the generic disk driver. Device Naming A device controller corresponds to an A/UX(Reg.) major dev- ice number. For SCSI devices, a controller corresponds to a SCSI ID. For NuBus based hardware, the disk controller is a single card. Each controller may have up to eight drives associated with it. For most devices, each drive would be a separate spindle with its own set of platters. For SCSI devices, each drive is a SCSI logical unit. For many SCSI devices with integral controllers, only one drive is possi- ble. A drive is further divided into slices (or partitions). A slice is a group of blocks used for a single purpose on a single drive. Most often, a slice corresponds to a file system. Slice 1 on the disk with the root file system is assumed to be a swap area at boot time. Slice 30 is assumed to contain a Macintosh(Reg.) file system. In the /dev/dsk and /dev/rdsk directories, devices are named according to their controller, disk, and slice number. /dev/dsk/c0d0s0 would be SCSI ID 0, the first drive, and the first partition. /dev/dsk/c9d0s0 might be assigned to NuBus slot nine. However, the low-level operating-system drivers do not access devices by name; instead, they use a pair of numbers called the major and minor device number. A disk controller is assigned a major number by either the autocon- figuration process or by the system designers. For SCSI disks, the major numbers from 24 through 31 are reserved for SCSI disk-device IDs 0 through 7. However, these assign- April, 1990 1
gd(7) gd(7)ments are subject to change in later releases of the operat- ing system. A minor number is calculated from the drive and the slice number: minor = drive * 32 + slice There are a maximum of 256 minor numbers for each major number. There may be as many as eight drives per controller and 32 slices per drive. Data Structures on Disk The first block of the physical disk (block 0) is reserved by the Macintosh Operating System. Block 1 of a disk used by A/UX (each physical block is always 512 bytes) contains one or more disk partition map entries. This data structure defined in dpme(4) assigns areas of the disk to the various available operating systems. A/UX maintains specific operating information that further describes each partition. This data structure resides in the dpme_boot_args field of dpme. It is defined by the A/UX bzb(4) data structure. In- formation in bzb is used by autorecovery(8), the kernel, and other utilities to further define the use of a partition. An A/UX disk partition provides three methods of compensa- tion for flawed or bad sectors on the disk. In most cases, disk hardware or firmware remaps the bad sector without further involvement by the operating system. If the disk hardware is deficient, however, A/UX maintains a pool of spare sectors at the end of the data area of the partition. The data structures defining these spares are described in altblk(4). If neither of these methods is available, the autorecovery program may be used to assign the bad sector to an unused inode. When this alternative is used, a bad sec- tor does not cause mischief on a mounted file system, but the bad sector continues to be present when accessed by oth- er methods, such as an image copy via dd(1). Partition Mapping A/UX disk partitioning allows slices of a disk to be allo- cated to operating systems, users, or applications. A par- tition is a group of disk blocks that are assigned a name and a type. The utility dp(1M) is one way partitions may be created and manipulated. Although any number of partitions may reside on a drive, the number of concurrently available partitions is limited to 32. A set of device control codes have been developed to allow partitions to be selectively attached to the minor number of a given drive and then de- tached when their usefulness is ended. 2 April, 1990
gd(7) gd(7)To allow the system to be booted, three partitions are nor- mally assigned (or associated) by default. When slice 0 is first accessed, the first partition which has the type field set to Apple_UNIX_SVR2, which has the root file system bit set in the block 0 block data structure, and whose au- torecovery(8) cluster number matches the autorecovery clus- ter number requested by the A/UX Startup Shell booter (or matches the default cluster number of 0) is associated. When slice 1 is first accessed, a partition is associated that matches the A/UX type name, includes the swap file- system type, and matches the autorecovery cluster number. When slice 2 is opened as a usr file system, the first par- tition that matches the A/UX type name, includes the identi- fying bit of a usr file system, and matches the autorecovery cluster number is associated. Any of these default file- system assignments may be overridden by explicitly setting a partition name for the partition. The partitioning should not be reset on an active file system. Slice 31 is always assigned to the entire physical drive. Slice 31 cannot be reassigned to another partition. If the partition-map information is missing from the begin- ning of the disk, the driver provides the following default mapping: Partition 0 A partition that starts at block 204. Length is the entire disk minus the size of partition 1. This partition is usually used for a Root&Usr file system. Partition 1 One quarter of the disk or up to 10 megabytes, whichever is less. This partition is normally used for swap. Partition 31 Entire disk. Only a subset of the following ioctls are allowed on these default partitions and they are the following: GD_PARTSIZE, GD_UNSETPNAME, UIOCEXTE, UIOCNEXTE, UIOCFORMAT, GD_SOFTERR, and GD_SPARE. IOCTLS The driver accepts the following ioctls (the symbol defini- tions are located in /usr/include/sys/ioctl.h or /usr/include/sys/ssioctl.h): ioctl(fd, GD_ALTBLK, bool) April, 1990 3
gd(7) gd(7)The alternate block mechanism sets aside a portion of each partition for an alternate block map area. When the boolean value used as the third argument to this function is TRUE, alternate block mapping occurs, and accesses are limited to the logical data area of the partition. When the third argument is FALSE, alternate block mapping is disabled, and reads and writes are al- lowed throughout the partition. This ioctl may only be performed by the superuser, or on a file descriptor that is open for writing. ioctl(fd, GD_GBZBTMADE, 0) ioctl(fd, GD_GBZBTMOUNT, 0) ioctl(fd, GD_GBZBTUMOUNT, 0) These ioctls return the value of the time field stored in the block 0 block of the partition. The times correspond to the time the file system was made, the last time the file system was mounted, and the last time the file system was unmounted. The ioctl returns type time_t (defined in /usr/include/types.h). ioctl(fd, GD_GETABM, addr) This ioctl returns a description of the alternate block map for the partition. The abm data structure (defined in /usr/include/apple/abm.h) is comprised of: struct abm { int abm_size; /* size of map (bytes) */ int abm_ents; /* number used (bytes) */ daddr_t abm_start; /* start of map (blk num) */ }; If alternate block mapping is not applied to the parti- tion, the system call errno is set to ENXIO. ioctl(fd, GD_GETMAP, abmi) This ioctl returns alternate block information for the partition. The return of data is controlled by a pointer to the abmi data structure passed as the third argument to the function. The abmi data structure is defined in /usr/include/apple/abm.h. struct abmi { caddr_t abmi_buf; /* read buffer */ int abmi_nbytes; /* read count */ }; abmi_buf is the location to place the alternate block map information. abmi_nbytes is the number of bytes to read. The size of the alternate block map may be determined by the ioctl GD_GETABM. ioctl(fd, GD_GETPNAME, dpident) 4 April, 1990
gd(7) gd(7)ioctl(fd, GD_SETPNAME, dpident) struct dpident { char dpiname[32]; /* name of partition */ char dpitype[32]; /* type of partition */ }; These ioctls map named partitions (named by dpident) to A/UX devices (fd). The notion of partition mapping is discussed earlier. The name and type of a partition are character strings. A typical name would be parti- tion00. The type name for A/UX file systems is defined as Apple_UNIX_SVR2. By specification, the names need not be null terminated if they are DPISTRLEN long (see dpme(4) for further information). The ioctl to get the name copies the current partition information corresponding to the file descriptor into the user's buffer. errno is set to ENXIO if there is no partition assigned or if there are no disk-partition-map entries for the disk. The ioctl to set the name searches the disk for the first partition that matches dpident, and assigns it to the major and minor device number corresponding to the file descriptor. The dpident structure is defined in /usr/include/apple/dpme.h. The ioctl GD_SETPNAME may only be performed by the su- peruser, or on a file descriptor that is open for writ- ing. ioctl(fd, GD_MKBAD, blocknum) The block number given as the third argument (blocknum) to the call is entered in the software-maintained al- ternate block map for the partition. The block numbers are always relative to the start of the partition. An alternate block map must be created by application- formatting software before the block is added. This ioctl may only be performed by the superuser, or on a file descriptor that is open for writing. ioctl(fd, GD_SBZBTMADE, time) ioctl(fd, GD_SBZBTMOUNT, time) ioctl(fd, GD_SBZBTUMOUNT, time) These ioctls set time fields stored in the block 0 block for the partition to the third argument (time) of the function. These ioctls may only be performed by the superuser, or on a file descriptor that is open for writing. The parameter time is type time_t. ioctl(fd, GD_PARTSIZE, 0) The return value of the function is the size of the partition. This ioctl returns a long integer that represents the partition's logical size in blocks. April, 1990 5
gd(7) gd(7)ioctl(fd, GD_SHUTDOWN, arg) Special shutdown processing is performed. The argument is normally one of these values: GD_SHUT_SHIP 1 /* Shutdown and ready for shipping*/ GD_SHUT_CLOSE 2 /* Internal driver information*/ GD_SHUT_REINIT 3 /* Reinitialize the driver*/ The first two values are implemented by device-specific software and may or may not have an effect on any given device. The last value causes drive data structures to be reinitialized and is used by utility software that updates disk-partition information. ioctl(fd, GD_SOFTERR, bool) If the third argument to this function is a Boolean value of TRUE, soft errors on the disk return as hard errors to applications. In general, this means that an error that could be corrected in hardware is not corrected and remains an error. For SCSI disks, this ioctl is only defined for devices that adhere to the common command set. Consult the manufacturer's docu- mentation for non-SCSI disks. This ioctl is intended for Apple diagnostics and should not normally be used. The ioctl may only be used on a file descriptor corresponding to partition 31 of the disk. It may only be used by the superuser, or if the file descriptor is open for writing. ioctl(fd, GD_SPARE, blocknum) This ioctl causes hardware-specific bad blocking of the block number given as the third argument (blocknum) to the function. The block number is always relative to the start of a partition. This ioctl call may only be used by the superuser, or if the file descriptor is open for writing. ioctl(fd, GD_UNSETPNAME, 0) The partition name, if any, assigned to the minor dev- ice number is removed. If the minor number is assigned a partition by default, the partition name assignment is recalculated on next access. Otherwise, an error (ENXIO) is returned on next access. This function may only be invoked by the superuser, or if the file descriptor is open for writing. ioctl(fd, UIOCEXTE, 0) This ioctl activates error printing on the system con- sole. The file descriptor may correspond to any char- acter device file associated with the desired controll- er. This ioctl may only be performed by the superuser, or on a file descriptor that is open for writing. 6 April, 1990
gd(7) gd(7)ioctl(fd, UIOCFORMAT, diskformat) This ioctl formats the disk. The placeholder fd should be an open file descriptor of the character device (that is, /dev/rdsk/c?d?s?). The third parameter to the ioctl function call contains the address of a disk- format structure (defined in /usr/include/sys/diskformat.h).The d_secsize field of this structure may be used tospecify 512-byte or 532-byte sector size for format-ting. The 532-byte sector size will not be supportedin future versions of the driver and should not beused. The other fields of the disk-format structureare ignored. The ioctl may only be applied to parti-tion 31 of a disk. The ioctl may only be used by thesuperuser, or if the file descriptor is open for writ-ing.ioctl(fd, UIOCNEXTE, 0)This ioctl deactivates error printing. The filedescriptor may correspond to any character device fileassociated with the desired controller. When deac-tivated, device errors continue to be logged byerrdemon(1M) but do not disturb the display on the con-sole. This ioctl may only be performed by the su-peruser, or on a file descriptor that is open for writ-ing.ERRORSThe following error values may be returned:[ENXIO] The device or partition could not be found.[EACCES] The requested ioctl is only permitted by thesuperuser, or on a file open for writing.[EINVAL] An ioctl to perform alternate block or parti-tion manipulation was performed on a disk lack-ing appropriate disk partition map entries.[EBUSY] An attempt was made to set the partition nameof a minor device that is already in use.[EEXIST] An attempt was made to set the partition nameof a partition already assigned to anotherminor device.[EIO] An I/O error has occurred.[ENOSPC] There is no space in the software alternateblock map.April, 1990 7
gd(7) gd(7)FILES /dev/dsk/c?d[0-7]s* /dev/rdsk/c?d[0-7]s* /usr/include/sys/gdisk.h /usr/include/sys/ioctl.h /usr/include/sys/ssioctl.h /usr/include/apple/abm.h SEE ALSO exterr(1), badblk(1M), diskformat(1M), dp(1M), mkfs(1M), mknod(1M), pname(1M), ioctl(2), getptabent(3), altblk(4), bzb(4), dpme(4), ptab(4), au- torecovery(8), boot(8), StartupShell(8). 8 April, 1990