gd(7) gd(7)NAME gd - provides a generic interface to disk devices DESCRIPTION The gd device driver provides a generic interface to a variety of disk devices. Consult the specific hardware manual for an add-on device to see if it uses 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 document SCSI Command Protocol 062-2075 defines characteristics of the common command set. Certain features, such as changing the reporting of soft errors, may not be supported by hardware that does not implement 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. Building A/UX Device Drivers, which is available from APDA, provides technical information on extending the generic disk driver. Device Naming A device controller corresponds to an A/UX major device number. For SCSI devices, a controller corresponds to a SCSI ID. For hardware based on NuBus, the disk controller is a single card. Each controller can have up to seven 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 possible. 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 file system. In the /dev/dsk and /dev/rdsk directories, disk device files are normally named to reflect the SCSI bus number, SCSI ID, and slice number of the logical and physical disk to which they refer. For explicit references to a disk on a known SCSI bus, the SCSI bus number and SCSI ID help determine the three-digit controller number that follows the leading c in the device filename. The first digit following c is the bus number, the second is always 0, and the third is the SCSI ID of the disk. Accordingly, /dev/dsk/c102d0s0 is an absolute reference to slice 0 of the disk connected to SCSI bus 1 that has a SCSI ID of 2. March 1993 1
gd(7) gd(7)There are also bus-independent ways to reference a disk using disk device files. Those device filenames contain a single-digit ``controller'' number that is equal to the SCSI ID number of a disk to be located on any of the SCSI buses. The mapping takes place during system startup only through the devlink program that is called from sysinitrc. Once A/UX is running, the bus mapping of these device files is fixed. Therefore, /dev/dsk/c1d0s0 is a reference to slice 0 of a disk that is set to SCSI ID 1 and that was connected to any of the four SCSI buses prior to system startup. To avoid conflicts, other disks should not be set to SCSI ID 1 on any of the other SCSI buses. You can overcome this restriction for file systems other than a Macintosh HFS by accessing them through a device file that explicitly specifies a bus. The low-level disk device drivers do not access devices by name; instead, they are passed a pair of numbers, called the major and minor device numbers, that are associated with the device file when it is created (see mknod(1M)). A disk controller is assigned a major number either by the autoconfiguration process or by the system designers. For SCSI disks, the major numbers from 24 to 31 are reserved for the first SCSI disk devices found on any one of the four SCSI buses corresponding to SCSI IDs 0 through 7. The search order begins with the internal bus (SCSI bus 1), then the internal DMA bus (SCSI bus 2), then the external bus (SCSI bus 3), then the external DMA bus (SCSI bus 4). These major numbers correspond to the device filenames /dev/dsk/cxd0s*. There are 28 additional device filenames containing controller numbers that explicitly refer to drives with a particular SCSI ID on a particular SCSI bus. To reference SCSI bus 1, a major device number in the range 32 to 39 is needed. To reference SCSI bus 2, a major device number in the range 40 to 47 is needed. To reference SCSI bus 3, a major device number in the range 48 to 55 is needed. To reference SCSI bus 4, a major device number in the range 56 to 63 is needed. The correspondence of the supplied device files to major device numbers is as follows: /dev/dsk/cxd0s* Reference major device numbers in the range 24 to 31. /dev/dsk/c10xd0s* Reference major device numbers in the range 32 to 39. /dev/dsk/c20xd0s* Reference major device numbers in the range 40 to 47. /dev/dsk/c30xd0s* 2 March 1993
gd(7) gd(7)Reference major device numbers in the range 48 to 55. /dev/dsk/c40xd0s* Reference major device numbers in the range 56 to 63. Note, however, that these assignments are subject to change in later releases of the operating 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 seven 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 contains one or more disk partition map entries. (Each physical block is always 512 bytes.) The disk partition map consists of disk partition entries (see dpme(4)) that associate areas of the disk to partitions. Apple HD SC Setup and A/UX can update disk partition entries; A/UX updates each partition entry representing a UNIX file system with the creation date and the latest mount date and time for the file system. This additional information resides in a data structure inside the disk partition entry that is known as the disk-block-zero structure (see bzb(4)). An A/UX disk partition provides three methods of compensation 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 may maintain a pool of spare sectors at the end of the data area of the partition (see dp(1M)). The data structures defining these spares are described in altblk(4). When this alternative is used, a bad sector does not cause mischief on a mounted file system, but the bad sector continues to be present when accessed by other methods, such as through the dd command. Partition Mapping A/UX disk partitioning allows slices of a disk to be allocated to operating systems, users, or applications. A partition is a group of disk blocks that are assigned a name and a type. The dp utility provides one way to create and manipulate partitions. The HD SC Setup program provides a better way. Although any number of partitions can reside on a drive, the number of concurrently available partitions is limited to 32. A set of device control codes has been March 1993 3
gd(7) gd(7)developed to allow partitions to be selectively attached to the minor number of a given drive and then detached when their usefulness is ended. To allow the system to be booted, three partitions are normally assigned (or associated) by default. Slice 0 is associated with the first partition that has the type field set to Apple_UNIX_SVR2 and that has the UNIX Root partition (RFS) bit set in its disk-block- zero structure. Slice 1 is associated with the first partition that has the type field set to Apple_UNIX_SVR2 and that has the Swap partition (SFS) bit set in its disk-block-zero structure. Slice 2 is associated with the the first partition that has the type field set to Apple_UNIX_SVR2 and that has the Usr partition (UFS) bit set in its disk-block-zero structure. You may override any of these default partition-slice mappings using pname (see pname(1M)). You should not reset any partition-slice mappings while a partition is in use. 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 beginning of the disk, the driver provides the following default mapping: Partition 0 A partition that starts at block 204. Its length is the entire disk minus the size of partition 1. This partition is usually used for a Root&Usr file system. Partition 1 A partition that is normally used for swap space. Partition 31 The entire disk. For the partitions that receive these default partition- slice mappings, only the following I/O controls can be used: GD_PARTSIZE GD_UNSETPNAME UIOCEXTE UIOCNEXTE 4 March 1993
gd(7) gd(7)UIOCFORMAT GD_SOFTERR GD_SPARE The complete set of I/O controls are described in the next section. I/O Controls The driver accepts the following I/O controls. The symbol definitions are located in the ioctl.h and ssioctl.h files inside the /usr/include/sys directory. ioctl(fildes,GD_ALTBLK,bool) The alternate block mechanism sets aside a portion of each partition for an alternate block map area. When the third argument 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 allowed throughout the partition. A call using this I/O control may only be performed by a process with an effective user ID of 0, or on a file descriptor that is open for writing. ioctl(fildes,GD_GBZBTMADE,0) ioctl(fildes,GD_GBZBTMOUNT,0) ioctl(fildes,GD_GBZBTUMOUNT,0) Calls using these I/O controls return the value of a time recorded in the disk-block-zero structure for 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. A call using this I/O control returns type time_t (defined in /usr/include/types.h). ioctl(fildes,GD_GETABM,addr) A call using this I/O control 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 partition, errno is set to ENXIO. ioctl(fildes,GD_GETMAP,abmi) A call using this I/O control returns alternate block March 1993 5
gd(7) gd(7)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 */ }; The abmi_buf member specifies the location to place the alternate block map information. The abmi_nbytes member specifies the number of bytes to read. The size of the alternate block map may be determined by the I/O control GD_GETABM. ioctl(fildes,GD_GETPNAME,dpident) ioctl(fildes,GD_SETPNAME,dpident) These I/O controls map named partitions indicated by dpident to A/UX devices indicated by fildes. The notion of partition mapping is discussed earlier. The name and type of a partition are character strings. A typical name would be Swap. The type for A/UX file systems is defined as Apple_UNIX_SVR2. By specification, these strings need not be null terminated if they are DPISTRLEN long. (See dpme(4) for further information.) The dpident parameter references a dpident structure (see /usr/include/apple/dpme.h). Its definition is shown here: struct dpident { char dpiname[32]; /* name of partition */ char dpitype[32]; /* type of partition */ }; The GD_GETPNAME I/O control obtains the partition name by copying partition information for the partition indicated by fildes into the user's dpident buffer. If no partition has been mapped to the device indicated by fildes, or if there are no disk-partition-map entries for the disk, errno is set to ENXIO. The SETPNAME I/O control associates a file descriptor to a partition by searching the disk for the first partition that matches dpident and then maps it to the major and minor device number corresponding to the file descriptor. The I/O control GD_SETPNAME can be performed only by a 6 March 1993
gd(7) gd(7)process with an effective user ID of 0, or on a file descriptor that is open for writing. ioctl(fildes,GD_MKBAD,blocknum) The block number specified by blocknum is entered in the software-maintained alternate block map for the partition. The block numbers are always relative to the beginning of the partition. An alternate block map must be created by disk-formatting software before the block can be added. A call using this I/O control may only be performed by a process with an effective user ID of 0, or on a file descriptor that is open for writing. ioctl(fildes,GD_SBZBTMADE,time) ioctl(fildes,GD_SBZBTMOUNT,time) ioctl(fildes,GD_SBZBTUMOUNT,time) Each of these I/O controls sets a different timestamp value stored within the disk-block-zero structure for a partition, making it equal to the time parameter. These I/O controls can only be called by a process with an effective user ID of 0, or on a file descriptor that is open for writing. The parameter time must be a time_t type of structure. ioctl(fildes,GD_PARTSIZE,0) This I/O control returns a long integer that represents the partition's logical size in blocks. ioctl(fildes,GD_SHUTDOWN,arg) This I/O control performs special shutdown processing. The value of arg is normally one of these values: GD_SHUT_SHIP /* Shutdown and ready for shipping */ GD_SHUT_CLOSE /* Internal driver information */ GD_SHUT_REINIT /* 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 may be used by disk-partitioning software. ioctl(fildes,GD_SOFTERR,bool) When bool is 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 was not corrected and remains an error. For SCSI disks, this I/O control is defined only for devices that adhere to the common command set. (Consult the manufacturer's documentation for non-SCSI disks.) This I/O control is intended for Apple diagnostics and March 1993 7
gd(7) gd(7)should not normally be used. It can only be used on a file descriptor corresponding to partition 31 of the disk. This I/O control may be called only by a process with an effective user ID of 0, or on a file descriptor that is open for writing. ioctl(fildes,GD_SPARE,blocknum) This I/O control causes hardware-specific bad blocking of the block specified by blocknum. The block number is always relative to the start of a partition. This I/O control may be called only by a process with an effective user ID of 0, or on a file descriptor that is open for writing. ioctl(fildes,GD_UNSETPNAME,0) This I/O control causes any partition that might be assigned to fildes to become disassociated from it. If the partition associated with fildes is one that can be mapped by default, the partition name assignment is recalculated when the next access to fildes is attempted. Otherwise, an error (ENXIO) is returned when fildes is subsequently accessed without its prior association to a partition. This I/O control may be called only by a process with an effective user ID of 0, or on a file descriptor that is open for writing. ioctl(fildes,UIOCEXTE,0) This I/O control activates error printing on the system console. The file descriptor may correspond to any character device file associated with the desired controller. This I/O control may be called only by a process with an effective user ID of 0, or on a file descriptor that is open for writing. ioctl(fildes,UIOCFORMAT,diskformat) This I/O control formats the disk. The fildes parameter should be an open file descriptor for a disk device file in the character (unbuffered) mode (that is, /dev/rdsk/c*d*s*). The diskformat parameter is the address of a diskformat type of structure (defined in /usr/include/sys/diskformat.h).The d_secsize member of this structure can be used tospecify 512-byte or 532-byte sector size forformatting. The 532-byte sector size will not besupported in future versions of the driver and shouldnot be used. The other members of the diskformatstructure type are ignored. The I/O control may onlybe applied to partition 31 of a disk. This I/O controlcan be called only by a process with an effective userID of 0, or on a file descriptor that is open forwriting.8 March 1993
gd(7) gd(7)ioctl(fildes,UIOCNEXTE,0) This I/O control deactivates error printing. The file descriptor should correspond to a disk device file in character (unbuffered) mode. When deactivated, device errors continue to be logged by errdemon but do not disturb the display on the console. This I/O control may be called only by a process with an effective user ID of 0, or on a file descriptor that is open for writing. STATUS MESSAGES AND VALUES These I/O controls return -1 upon an error and set the errno variable to one of the following values: EACCES The requested I/O control is only permitted by a process with an effective user ID of 0, or on a file that is open for writing. EBUSY An attempt was made to set the partition name of a minor device that is already in use. EEXIST An attempt was made to set the partition name of a partition already assigned to another minor device. EINVAL An attempt was made to manipulate alternate blocks or partitions on a disk that lacks appropriate disk- partition-map entries. EIO An I/O error occurred. ENOSPC There is no space in the software alternate block map. ENXIO The device or partition could not be found. FILES /dev/dsk/c*d*s* Device files /dev/rdsk/c*d*s* Device files for raw I/O operations /usr/include/apple/abm.h Header file /usr/include/apple/dpme.h Header file /usr/include/sys/diskformat.h Header file /usr/include/sys/gdisk.h March 1993 9
gd(7) gd(7)Header file /usr/include/sys/ioctl.h Header file /usr/include/sys/ssioctl.h Header file /usr/include/types.h Header file SEE ALSO ioctl(2), getptabent(3), altblk(4), bzb(4), dpme(4), ptab(4) badblk(1M), diskformat(1M), dp(1M), exterr(1M), mkfs(1M), mknod(1M), pname(1M), StartupShell(8) in A/UX System Administrator's Reference Building A/UX Device Drivers SCSI Command Protocol 062-2075 10 March 1993