3    Structures Related to Device Drivers

This chapter describes:

• Conventions for structures that device drivers use

• Structures that device drivers use

3.1    Conventions for Data Structures

The descriptions of the structures related to device drivers are presented in alphabetical order and in reference (man) page style. The descriptions can include the following sections.

Name

This section lists the name of the structure along with a summary description of its purpose.

Include File

This section lists the header file, including the path, where the structure is defined.

Synopsis

This section takes the following approaches when describing structures:

• The C structure definition is shown

  This occurs when you need to understand or need to initialize all of the members of a structure. For example, the declaration of the driver structure is shown because driver writers initialize this structure in their device drivers.

• The structure members are shown in a table

  This occurs when you need to understand or need to reference some of the members of a particular structure. For example, the members of the buf structure are shown in a table because the driver writer references only some of its members.

• No structure declaration or structure table is shown

  This occurs when the data structure is opaque. This means the members of the structure are manipulated by the Digital UNIX operating system. The driver writer does not manipulate or reference any of the members.

Members

This section provides a short description of each member of the structure.

Description

This section gives more details about the purpose of the structure.

Related Information

This section lists related kernel interfaces, structures, system calls, and so forth.

3.2    Data Structures

Table 3-1 summarizes the structures that device drivers use.

Table 3-1: Summary Descriptions of Data Structures

buf

Describes arbitrary I/O

Include File

/usr/sys/include/sys/buf.h

Synopsis

Member Name	Data Type
b_flags	int
b_forw	struct buf *
b_back	struct buf *
av_forw	struct buf *
av_back	struct buf *
b_bcount	int
b_error	short
b_dev	dev_t
b_un.b_addr	caddr_t
b_lblkno	daddr_t
b_blkno	daddr_t
b_resid	int
b_iodone	void (*b_iodone) ()
b_proc	struct proc *

Members

b_flags

Specifies binary status flags. These flags indicate how a request is to be handled and the current status of the request.
The following flags are applicable to device drivers:

Flag	Meaning
B_READ	This flag is set if the operation is read and cleared if the operation is write.
B_DONE	This flag is cleared when a request is passed to a driver strategy interface. The device driver writer must call iodone to mark a buffer as completed.
B_ERROR	This flag specifies that an error occurred on this data transfer. Device drivers set this flag if an error occurs.
B_BUSY	This flag indicates that the buffer is in use.
B_PHYS	This flag indicates that the associated data is in user address space.

b_forw

Specifies a hash chain. Only the entity (driver, buffer cache) that owns the buf structure can use or reference this member. A driver receiving a buf structure from the buffer cache through the strategy interface must not use this member.

b_back

Specifies a hash chain. Only the entity (driver, buffer cache) that owns the buf structure can use or reference this member. A driver receiving a buf structure from the buffer cache through the strategy interface must not use this member.

av_forw

Specifies the position on the free list if the b_flags member is not set to B_BUSY.

av_back

Specifies the position on the free list if the b_flags member is not set to B_BUSY.

b_bcount

Specifies the size of the requested transfer (in bytes).

b_error

Specifies that an error occurred on this data transfer. This member is set to an error code if the b_flags member bit was set.

b_dev

Specifies the special device to which the transfer is directed.

b_un.b_addr

Specifies the address at which to pull or push the data.

b_lblkno

Specifies the logical block number.

b_blkno

Specifies the block number on the partition of a disk or on the file system.

b_resid

Specifies (in bytes) the data not transferred because of some error.

b_iodone

Specifies the interface called by iodone. The device driver calls iodone at the completion of an I/O operation.

b_proc

Specifies a pointer to the proc structure that represents the process performing the I/O.

Description

The buf structures describe arbitrary I/O, but are usually associated with block I/O and physio. A systemwide pool of buf structures exists for block I/O; however, many device drivers also include locally defined buf structures.

Notes

Device drivers written for the ULTRIX operating system set the B_CALL flag in the b_flags member and a completion interface in the b_iodone member. At the completion of an I/O operation, the device driver on the ULTRIX operating system calls the iodone interface, which clears the B_CALL flag and then calls the completion interface set in the b_iodone member.

The Digital UNIX operating system does not define a B_CALL flag. The iodone interface checks the b_iodone member to determine if you specified a completion interface. If so, iodone clears b_iodone and then calls the specified completion interface. If you want to reuse this buf structure, you must reset the b_iodone member to a completion interface. In fact, it is good programming practice to reset all of the referenced members of a buf structure that you plan to reuse.

Related Information

iodone, xxstrategy

bus

Represents an instance of a bus entity to which other buses or controllers are logically attached

Include File

/usr/sys/include/io/common/devdriver.h

Synopsis

Member Name	Data Type
bus_mbox	u_long *
bus_hd	struct bus *
nxt_bus	struct bus *
ctlr_list	struct controller *
bus_list	struct bus *
bus_type	int
bus_name	char *
bus_num	int
slot	int
connect_bus	char *
connect_num	int
confl1	int (*confl1)()
confl2	int (*confl2)()
pname	char *
port	struct port *
intr	int (**intr)()
alive	int
framework	struct bus_framework *
driver_name	char *
bus_bridge_dma	void *
private	void * [8]
conn_priv	void * [8]
rsvd

Members

bus_mbox

Specifies a pointer to the mailbox data structure for hardware platforms that access I/O space through hardware mailboxes. The bus adapter code sets this member.

bus_hd

Specifies a pointer to the bus structure that this bus is connected to.

nxt_bus

Specifies a pointer to the next bus at this level.

ctlr_list

Specifies a linked list of controllers connected to this bus.

bus_list

Specifies a linked list of buses connected to this bus.

bus_type

Specifies the type of bus.

bus_name

Specifies the bus name.

bus_num

Specifies the bus number of this bus.

slot

Specifies the bus slot or node number.

connect_bus

Specifies the name of the bus that this bus is connected to.

connect_num

Specifies the number of the bus that this bus is connected to.

confl1

Specifies a pointer to an entry point of the level 1 bus configuration interface. This interface is not typically used by device driver writers, but by systems engineers who want to implement a configuration procedure for a specific bus.

confl2

Specifies a pointer to an entry point of the level 2 bus configuration interface. This interface is not typically used by device driver writers, but by systems engineers who want to implement a configuration procedure for a specific bus.

pname

Specifies a pointer to the port name for this bus, if applicable.

port

Specifies a pointer to the port structure for this bus, if applicable.

intr

Specifies an array that contains an entry point or points for the bus interrupt handlers.

alive

Specifies a flag word to indicate the current status of the bus. The system sets this member to the bitwise inclusive OR of the valid alive bits defined in devdriver.h.

framework

Specifies a pointer to the bus_framework structure. This structure contains pointers to bus interfaces for loadable device drivers. These interfaces provide dynamic extensions to bus functionality. They are used in the autoconfiguration of loadable drivers to perform bus-specific tasks, such as the registration of interrupt handlers.

driver_name

Specifies the name of the controlling device driver.

bus_bridge_dma

Signifies that the bus adapter has direct memory access (DMA) mapping support.

private

Specifies private storage for use by this bus or bus class.

conn_priv

Specifies private storage for use by the bus that this bus is connected to.

rsvd

This member is reserved for future expansion of the data structure.

Description

The bus structure represents an instance of a bus entity. A bus is a real or imagined entity to which other buses or controllers are logically attached. All systems have at least one bus, the system bus, even though the bus may not actually exist physically. The term controller here refers both to devices that control slave devices (for example, disk or tape controllers) and to devices that stand alone (for example, terminal or network controllers).

Related Information

controller, device, driver, handler_disable, handler_enable

cfg_attr_t

Contains information for managing the loading and unloading of drivers

Include File

/usr/sys/include/sys/sysconfig.h

Synopsis

typedef struct cfg_attr {
  char              name[CFG_ATTR_NAME_SZ];
  uchar             type;
  uchar             operation;
  uint              status;
  long              index;
  union {
      struct {
          caddr_t   val;
          ulong     min_size;
          ulong     max_size;
          void      (*disposal)();
          ulong     val_size;
      } bin;

      struct {
          caddr_t   val;
          ulong     min_len;
          ulong     max_len;
          void      (*disposal)();
      } str;

      struct {
          ulong     val;
          ulong     min_val;
          ulong     max_val;
      } num;
  } attr;
} cfg_attr_t;

Members

name

Specifies the ASCII name of the attribute. The name must be between two and CFG_ATTR_NAME_SZ characters in length, including the terminating null character. Do not begin the ASCII name of the attribute with the Method_ or Device_ characters. The cfgmgr framework reserves certain names that begin with the Method_ and Device_ characters.

type

Specifies the data type associated with the name attribute. You must set the type member to one of the following constants:

Value	Meaning
CFG_ATTR_STRTYPE	Data type is a null-terminated array of characters.
CFG_ATTR_INTTYPE	Data type is a 32-bit signed integer.
CFG_ATTR_UINTTYPE	Data type is a 32-bit unsigned integer.
CFG_ATTR_LONGTYPE	Data type is a 64-bit signed integer.
CFG_ATTR_ULONGTYPE	Data type is a 64-bit unsigned integer.
CFG_ATTR_BINTYPE	Data type is an array of bytes.
CFG_ATTR_UCHARTYPE	Data type is an 8-bit unsigned character.
CFG_ATTR_USHORTTYPE	Data type is a 16-bit unsigned short integer.

operation

Specifies the operations that the cfgmgr framework can perform on the attribute. You can set this member to one of the following constants: CFG_OP_CONFIGURE, CFG_OP_QUERY, and CFG_OP_RECONFIGURE.

The following table describes the meaning of these constants.

Value	Meaning
CFG_OP_CONFIGURE	The cfgmgr framework configures the attribute. This means the cfgmgr framework obtains a data value for the attribute from the /etc/sysconfigtab database. The configure operation occurs when the cfgmgr framework calls the driver's configure interface at its CFG_OP_CONFIGURE entry point. (That is, the optype argument of the driver's configure interface evaluates to the CFG_OP_CONFIGURE constant.)
CFG_OP_QUERY	The cfgmgr framework queries (reads) the attribute. This means the driver cooperates with the cfgmgr framework to provide the value associated with the attribute as a result of user-initiated query requests. These requests are typically the result of the sysconfig -q command. The query operation occurs when the cfgmgr framework calls the driver's configure interface at its CFG_OP_QUERY entry point. (That is, the optype argument of the driver's configure interface evaluates to the CFG_OP_QUERY constant.)
CFG_OP_RECONFIGURE	The cfgmgr framework reconfigures the attribute. This means the cfgmgr framework reconfigures the data value for the attribute. This functionality allows a user to modify the attribute. A reconfigure request is typically the result of the sysconfig -r command. The reconfigure operation occurs when the cfgmgr framework calls the driver's configure interface at its CFG_OP_RECONFIGURE entry point. (That is, the optype argument of the driver's configure interface evaluates to the CFG_OP_RECONFIGURE constant.)

status

Stores the return code from operations (configure, unconfigure, query) that the cfgmgr framework performs. The cfgmgr framework can return one of the following operation codes:

Value	Meaning
CFG_ATTR_SUCCESS	Successful operation.
CFG_ATTR_EEXISTS	The attribute you specified in the name member does not exist.
CFG_ATTR_EOP	The attribute you specified in the name member does not support the operation.
CFG_ATTR_ESUBSYS	The subsystem failed.
CFG_ATTR_ESMALL	The value or size of the attribute you specified in the name member is too small.
CFG_ATTR_ELARGE	The value or size of the attribute you specified in the name member is too large.
CFG_ATTR_ETYPE	The data type that you specified for the attribute you specified in the name member is invalid or is a mismatch.
CFG_ATTR_EINDEX	The index associated with the attribute that you specified in the name member is invalid.
CFG_ATTR_EMEM	The cfgmgr framework could not allocate memory for the specified attribute.
CFG_ATTR_ENOTNUMBER	The attribute that you specified in the member cannot be converted to a number.

index

Stores a value that scopes the target for indexed attributes.

attr

Specifies a union of the possible attribute types used for storing values, kernel locations, validation criteria, and disposal interfaces. The cfgmgr framework uses the appropriate union element according to the attribute type. For example, attributes of type CFG_ATTR_ULONGTYPE use the union element num.

Description

The cfg_attr_t data structure contains information for managing the configuring and unconfiguring of device drivers. The cfgmgr framework passes a pointer to this data structure to the device driver's configure interface. The device driver can parse this structure pointer to check the validity of the values associated with the driver's associated sysconfigtab file fragment and the /etc/sysconfigtab database.

Related Information

cfg_subsys_attr_t, sysconfig.h, xxconfigure

cfg_subsys_attr_t

Contains attribute information for drivers

Include File

/usr/sys/include/sys/sysconfig.h

Synopsis

typedef struct {
  char     name[CFG_ATTR_NAME_SZ];
  uchar    type;
  uchar    operation;
  caddr_t  addr;
  ulong    min_val;
  ulong    max_val;
  ulong    val_size;
} cfg_subsys_attr_t;

Members

name

Specifies the ASCII name of the attribute. The name must be between two and CFG_ATTR_NAME_SZ characters in length, including the terminating null character. Do not begin the ASCII name of the attribute with the Method_ or Device_ characters. The cfgmgr framework reserves certain names that begin with the Method_ and Device_ characters.

type

Specifies the data type associated with the name attribute. You must set the type member to one of the following constants:

Value	Meaning
CFG_ATTR_STRTYPE	Data type is a null-terminated array of characters.
CFG_ATTR_INTTYPE	Data type is a 32-bit signed integer.
CFG_ATTR_UINTTYPE	Data type is a 32-bit unsigned integer.
CFG_ATTR_LONGTYPE	Data type is a 64-bit signed integer.
CFG_ATTR_ULONGTYPE	Data type is a 64-bit unsigned integer.
CFG_ATTR_BINTYPE	Data type is an array of bytes.
CFG_ATTR_UCHARTYPE	Data type is an 8-bit unsigned character.
CFG_ATTR_USHORTTYPE	Data type is a 16-bit unsigned short integer.

operation

Specifies the operations that the cfgmgr framework can perform on the attribute. You can set this member to one of the following constants: CFG_OP_CONFIGURE, CFG_OP_QUERY, and CFG_OP_RECONFIGURE.

The following table describes the meaning of these constants.

Value	Meaning
CFG_OP_CONFIGURE	The cfgmgr framework configures the attribute. This means the cfgmgr framework obtains a data value for the attribute from the /etc/sysconfigtab database. The configure operation occurs when the cfgmgr framework calls the driver's configure interface at its CFG_OP_CONFIGURE entry point. (That is, the optype argument of the driver's configure interface evaluates to the CFG_OP_CONFIGURE constant.)
CFG_OP_QUERY	The cfgmgr framework queries (reads) the attribute. This means the driver cooperates with the cfgmgr framework to provide the value associated with the attribute as a result of user-initiated query requests. These requests are typically the result of the sysconfig -q command. The query operation occurs when the cfgmgr framework calls the driver's configure interface at its CFG_OP_QUERY entry point. (That is, the optype argument of the driver's configure interface evaluates to the CFG_OP_QUERY constant.)
CFG_OP_RECONFIGURE	The cfgmgr framework reconfigures the attribute. This means the cfgmgr framework reconfigures the data value for the attribute. This functionality allows a user to modify the attribute. A reconfigure request is typically the result of the sysconfig -r command. The reconfigure operation occurs when the cfgmgr framework calls the driver's configure interface at its CFG_OP_RECONFIGURE entry point. (That is, the optype argument of the driver's configure interface evaluates to the CFG_OP_RECONFIGURE constant.)

addr

Specifies the address of the data value associated with the attribute. The cfgmgr framework obtains the data value for this attribute from the /etc/sysconfigtab database and stores it at this address. The cfgmgr framework performs this storage operation if the following occurs:

• The attribute appears in the cfg_subsys_attr_t table (declared and initialized in the driver) with an operation code of CFG_OP_CONFIGURE.

• The driver writer passes the CFG_OP_CONFIGURE constant to the optype argument of the driver's configure interface. This is the driver's configuration entry point for handling static or dynamic configuration requests.

Although the device driver's configure interface can initialize attributes that appear in the array with an operation code of CFG_OP_CONFIGURE, the cfgmgr framework overrides this initialization with the value specified in the /etc/sysconfigtab database.

min_val

Specifies the minimum length of a string data value. If the data type for the attribute is numeric, specifies the minimum range.

max_val

Specifies the maximum length of a string data value. If the data type for the attribute is numeric, specifies the maximum range.

val_size

Specifies the binary data size.

Description

The cfg_subsys_attr_t data structure contains information that device drivers use to describe a variety of attributes. Device driver writers declare and initialize an array of cfg_subsys_attr_t structures in their device drivers. The cfg_subsys_attr_t structure is a simplified version of the cfg_attr_t structure and is designed to save space in the kernel.

Related Information

cfg_attr_t, xxconfigure

controller

Contains members that store information about hardware resources and store data for communication between the kernel and the device driver

Include File

/usr/sys/include/io/common/devdriver.h

Synopsis

Member Name	Data Type
ctlr_mbox	u_long *
bus_hd	struct bus *
nxt_ctlr	struct controller *
dev_list	struct device *
driver	struct driver *
ctlr_type	int
ctlr_name	char *
ctlr_num	int
bus_name	char *
bus_num	int
rctlr	int
slot	int
alive	int
pname	char *
port	struct port *
intr	int (**intr)()
addr	caddr_t
addr2	caddr_t
flags	int
bus_priority	int
ivnum	int
priority	int
cmd	int
physaddr	caddr_t
physaddr2	caddr_t
private	void * [8]
conn_priv	void * [8]
rsvd	void * [8]

Members

ctlr_mbox

Specifies a pointer to the mailbox data structure for hardware platforms that access I/O space through hardware mailboxes. The bus adapter code sets this member.

bus_hd

Specifies a pointer to the bus structure that this controller is connected to.

nxt_ctlr

Specifies a pointer to the next controller at this level.

dev_list

Specifies a linked list of devices connected to this controller.

driver

Specifies a pointer to the driver structure for this controller.

ctlr_type

Specifies the controller type.

ctlr_name

Specifies the controller name.

ctlr_num

Specifies the controller number.

bus_name

Specifies the name of the bus to which this controller is connected.

bus_num

Specifies the number of the bus to which the controller is connected.

rctlr

Specifies the remote controller number (for example, the SCSI ID).

slot

Specifies the bus slot or node number.

alive

Specifies a flag word to indicate the current status of the controller.

pname

Specifies a pointer to the port name for this controller, if applicable.

port

Specifies a pointer to the port structure for this controller, if applicable.

intr

Specifies an array that contains one or more entry points for the controller interrupt service interfaces.

addr

Specifies the address of the device registers or memory.

addr2

Specifies an optional second virtual address for this controller. This member is set if there are two CSR spaces.

flags

Specifies controller-specific flags.

bus_priority

Specifies the configured VMEbus priority level of the device. Only drivers operating on the VMEbus use this member.

ivnum

Specifies an interrupt vector number. Only drivers operating on the VMEbus use this member.

priority

Specifies the system priority level (spl) to block interrupts from this device. Only drivers operating on the VMEbus use this member.

cmd

Specifies a field that is not currently used.

physaddr

Specifies the physical address that corresponds to the virtual address set in the addr member.

physaddr2

Specifies the physical address that corresponds to the virtual address set in the addr2 member.

private

Specifies private storage for use by this controller or controller type.

conn_priv

Specifies private storage for use by the bus that this controller is connected to.

rsvd

This member is reserved for future expansion of the data structure.

Description

The controller structure represents an instance of a controller entity, one that connects logically to a bus. A controller can control devices that are directly connected or can perform some other controlling operation, such as a network interface or terminal controller operation.

Related Information

bus, device, driver

controller_config

Contains information needed to create a controller structure

Include File

/usr/sys/include/io/common/devdriver.h

Synopsis

struct controller_config {
 long    revision;
 char    subsystem_name[NAME_SIZE_REG];
 char    bus_name[NAME_SIZE_REG];
 struct  driver * devdriver;
};

Members

revision

Specifies the version number of the controller_config structure. You set this member to the constant CTLR_CONFIG_REVISION. Digital defines this constant to the appropriate version number in the /usr/sys/include/io/common/devdriver.h file.

subsystem_name

Specifies the name of the device driver. This name is a string that matches the string you specified for the entry_name item in the /etc/sysconfigtab database. Typically, third-party driver writers specify the driver name (followed by a colon) in the sysconfigtab file fragment, which gets appended to the /etc/sysconfigtab database during the driver product installation.

bus_name

Specifies the name of the bus to which the controller is connected. You can pass any string (maximum thirty characters). You can pass the constant DRIVER_WILDNAME to indicate a wildcard (this bus can be any Digital-supported bus). For buses supported by Digital, the bus name is one of the valid device definition keywords associated with the bus. For example, the keyword tc represents a TURBOchannel bus. See the System Administration guide (specifically, the section that discusses how to build the kernel to add support for a new device) for information on how to obtain the device definition keywords asssociated with Digital-supported devices.

Third-party driver writers who write drivers that operate on non-Digital buses can select a string that might include the vendor and product names. The string could also include version and release numbers. This type of naming scheme reduces the chance of name conflicts with other vendors.

devdriver

Specifies a pointer to the driver's driver structure. You set this member to the name of the filled in driver structure for this device driver.

Description

The controller_config structure contains the information needed to create a controller structure and integrate it into the system (hardware) configuration tree. To create a controller structure, you set the members of the controller_config structure to appropriate values and call the create_controller_struct interface. This interface takes as an argument a pointer to the filled-in controller_config structure.

Related Information

controller, create_controller_struct, device_config, driver

DEVGEOMST

Stores disk device geometry

Include File

/usr/sys/include/io/common/devio.h

Synopsis

typedef union devgeom {
 struct {
     unsigned long   dev_size;
     unsigned short  ntracks;
     unsigned short  nsectors;
     unsigned short  ncylinders;
     unsigned long   attributes;
     unsigned long   sector_size;
     unsigned long   min_trans;
     unsigned long   max_trans;
     unsigned long   prefer_trans;
    } geom_info;
    unsigned char       pad[108];
} DEVGEOMST;

Members

dev_size

Specifies the total number of sectors/blocks on the device available for use.

ntracks

Specifies the number of tracks per cylinder. This number may not actually reflect the number of tracks per cylinder but is an estimate (RAID devices).

nsectors

Specifies an average number of sectors per track.

ncylinders

Specifies an average number of cylinders per track.

attributes

Specifies one of the following device attributes: DEVGEOM_REMOVE (a removable device) or DEVGEOM_DYNAMIC (a dynamic geometry device).

sector_size

Specifies the number of bytes in the sector.

min_trans

Specifies the minimum number of bytes for the transfer size.

max_trans

Specifies the maximum number of bytes for the transfer size.

prefer_trans

Specifies the preferred number of bytes for the transfer size.

Description

The DEVGEOMST structure defines the size of tracks, cylinders, and sectors on the disk, plus device attributes and the number of bytes that can be transferred during a single I/O operation.

The DEVGETGEOM ioctl command uses this structure to return geometry information to the user data buffer. The device driver's open interface and the DEVGDEFPT ioctl command use DEVGEOMST to create a default partition map.

Related Information

DEVGETGEOM, get_def_partitionmap

devget

Contains information about a device

Include File

/usr/sys/include/io/common/devio.h

Synopsis

struct  devget  {
        short      category;
        short      bus;
        char       interface[DEV_SIZE];
        char       device[DEV_SIZE];
        short      adpt_num;
        short      nexus_num;
        short      bus_num;
        short      ctlr_num;
        short      rctlr_num;
        short      slave_num;
        char       dev_name[DEV_SIZE];
        short      unit_num;
        unsigned   soft_count;
        unsigned   hard_count;
        long       stat;
        long       category_stat;
};

Members

category

Specifies the general class of the device. This member can be set to one of the following values: DEV_TAPE (tape category), DEV_DISK (disk category), DEV_TERMINAL (terminal category), DEV_PRINTER (printer category), or DEV_SPECIAL (special category).

bus

Specifies the communications bus type. For example, this member would be set to the value DEV_SCSI for SCSI devices.

interface

Specifies a string of up to eight characters that identifies the controller interface type.

device

This member is set to the device string.

adpt_num

This member is set to the adapter number.

nexus_num

This member is set to the nexus, or node, on the adapter number.

bus_num

This member is set to the bus number that the device controller resides on.

ctlr_num

This member is set to the specific controller number for the controller of this device. This controller number is the specific controller number on this bus.

rctlr_num

This member is set to the remote controller number.

slave_num

This member is set to the device unit number. For a disk device, this unit number is the physical device unit number. For a terminal device, this number is the terminal line number.

dev_name

This member is set to the device name type, which is a string of up to eight characters. For example, Digital defines the strings rz and tz to represent disk and tape devices, respectively.

unit_num

This member is set to the kernel configuration representation of a device unit number. The value in this member is frequently the same as the slave_num member. The difference is that slave_num represents the physical unit number, while the unit_num member represents a logical unit number for the device.

soft_count

This member is set to a driver counter of soft (noncritical) errors.

hard_count

This member is set to a driver counter of hardware errors.

stat

This member is set to the device status. This member is used primarily to represent drive status for tape devices. Some examples of drive status include the following: the drive is at the bottom or end of tape, or the drive is write-protected.

category_stat

This member is set to generic device status values, which are defined in /usr/sys/include/io/common/devio.h. The values are organized according to the following device types: tapes, disks, and communications devices.

Description

The devget data structure contains information about a device. This information includes the general class of the device, the bus type associated with the device, and other device-related information. The DEVIOCGET ioctl command uses the devget structure to obtain generic device information.

Related Information

devio.h, DEVIOCGET

device

Contains information that identifies the device. There is one device data structure for each device connected to the controller.

Include File

/usr/sys/include/io/common/devdriver.h

Synopsis

Member Name	Data Type
nxt_dev	struct device *
ctlr_hd	struct controller *
dev_type	char *
dev_name	char *
logunit	int
unit	int
ctlr_name	char *
ctlr_num	int
alive	int
private	void * [8]
conn_priv	void * [8]
rsvd	void * [8]

Members

nxt_dev

Specifies a pointer to the next device at this level.

ctlr_hd

Specifies a pointer to the controller structure that this device is connected to.

dev_type

Specifies the device type (for example, disk or tape).

dev_name

This member is set to the device name type, which is a string of up to eight characters. For example, Digital defines the strings rz and tz to represent disk and tape devices, respectively.

logunit

Specifies the device logical unit number.

unit

Specifies the device physical unit number.

ctlr_name

Specifies the name of the controller that this device is connected to.

ctlr_num

Specifies the number of the controller that this device is connected to.

alive

Specifies a flag word to indicate the current status of the device.

private

Specifies private storage for use by this device or device class.

conn_priv

Specifies private storage for use by the controller that this device is connected to.

rsvd

This member is reserved for future expansion of the data structure.

Description

The device structure represents an instance of a device entity. A device is an entity that connects to and is controlled by a controller. A device does not connect directly to a bus.

Related Information

bus, controller, driver

device_config

Contains information needed to create a device structure

Include File

/usr/sys/include/io/common/devdriver.h

Synopsis

struct device_config {
 long    revision;
 char    device_type[NAME_SIZE_REG];
 char    device_name[NAME_SIZE_REG];
 char    controller_name[NAME_SIZE_REG];
 int     phys_unit_num;
 int     logical_unit_number;
 int     controller_num;
};

Members

revision

Specifies the version number of the device_config structure. You set this member to the constant DEVICE_CONFIG_REVISION. Digital defines this constant to the appropriate version number in the /usr/sys/include/io/common/devdriver.h file.

device_type

Specifies the device type (for example, disk or tape). You can set this member to the strings disk and tape to represent disk and tape devices. However, you can set this member to any string to represent other device types. The device type can be a maximum of thirty characters.

device_name

Specifies the name associated with the device type. You can set this member to any string (maximum eight characters). For devices that Digital supports, the device name is one of the valid device definition keywords associated with the device. For example, the keywords ra and tz represent SCSI disk and tape devices, respectively. See the System Administration guide (specifically, the section that discusses how to build the kernel to add support for a new device) for information on how to obtain the device definition keywords asssociated with Digital-supported devices.

Third-party driver writers who write drivers that operate on non-Digital devices can select a string that might include the vendor and product names. The string could also include version and release numbers. This type of naming scheme reduces the chance of name conflicts with other vendors. For example, the driver writers at EasyDriver Incorporated might specify edgd for an internally developed disk device.

controller_name

Specifies the name of the controller to which this device (the device associated with this device_config structure) is connected. You can pass any string (maximum thirty characters). For controllers that Digital supports, the controller name is one of the valid controller definition keywords associated with the controller. For example, the keyword hsc represents an HSC controller. See the System Administration guide (specifically, the section that discusses how to build the kernel to add support for a new device) for information on how to obtain the device definition keywords asssociated with Digital-supported devices.

Third-party driver writers who write drivers for non-Digital controllers can select a string that might include the vendor and product names. The string could also include version and release numbers. This type of naming scheme reduces the chance of name conflicts with other vendors. For example, the driver writers at EasyDriver Incorporated might specify edgc for an internally developed controller.

phys_unit_num

Specifies the device physical unit number.

logical_unit_number

Specifies the device logical unit number. The logical unit number for a disk drive is any positive integer, for example, 0 or 1.

controller_num

Specifies the number of the controller to which this device (the device associated with this device_config structure) is connected. Typically, you set this member to the constant LDBL_WILDNUM.

Description

The device_config structure contains the information needed to create a device structure and integrate it into the system (hardware) configuration tree. To create a device structure, you set the members of the device_config structure to appropriate values and call the create_device_struct interface. This interface takes as an argument a pointer to the filled-in device_config structure.

Related Information

controller, controller_config, create_device_struct, device

device_info_t

Is the top-level union that stores bus- and device-type information

Include File

/usr/sys/include/io/common/devgetinfo.h

Synopsis

typedef union device_info {
    int version;
    v1_device_info_t v1;
    uchar_t pad[1024];
} device_info_t;

Members

version

Specifies the version number of the union definition. Currently, Digital UNIX supports only Version 1.

v1

Specifies a structure that contains bus-type and device-type information, such as the v1_device_info_t structure.

pad

Specifies a reserved member.

Description

The device_info_t union is the top-level definition of the information returned by the DEVGETINFO ioctl command. The first byte of the union stores the version number of the union definition. Currently, only Version 1 is supported.

The DEVGETINFO ioctl command queries the device for as much information as it can, initializes members of the appropriate data structures within the device_info_t union, then assigns the address of this union to the user's data buffer.

Related Information

v1_device_info_t

disklabel

Stores disk device label information

Include File

/usr/sys/include/sys/disklabel.h

Synopsis

struct disklabel {
    u_int d_magic;
    short d_type;
    short d_subtype;
    char d_typename[16];
    union {
        char un_d_packname[16];
        struct {
            char *un_d_boot0;
            char *un_d_boot1;
        } un_b;
    } d_un;
    u_int d_secsize;
    u_int d_nsectors;
    u_int d_ntracks;
    u_int d_ncylinders;
    u_int d_secpercyl;
    u_int d_secperunit;
    u_short d_sparespertrack;
    u_short d_sparespercyl;
    u_int d_acylinders;
    u_short d_rpm;
    u_short d_interleave;
    u_short d_trackskew;
    u_short d_cylskew;
    u_int d_headswitch;
    u_int d_trkseek;
    u_int d_flags;
    u_int d_drivedata[NDDATA];
    u_int d_spare[NSPARE];
    u_int d_magic2;
    u_short d_checksum;
    u_short d_npartitions;
    u_int d_bbsize;
    u_int d_sbsize;
    struct partition {
        u_int p_size;
        u_int p_offset;
        u_int p_fsize;
        u_char p_fstype;
        u_char p_frag;
        u_short p_cpg;
    } d_partitions[MAXPARTITIONS];
};

Members

d_magic

The magic number DISKMAGIC identifies this as a disklabel structure.

d_type

One of the following drive types:

Value	Meaning
DTYPE_SMD	SMD, XSMD, VAX hp/up
DTYPE_MSCP	MSCP
DTYPE_DEC	DEC (rk, rl)
DTYPE_SCSI	SCSI
DTYPE_ESDI	ESDI interface
DTYPE_ST506	ST506 etc.
DTYPE_FLOPPY	floppy diskette
DTYPE_SWXCR	StorageWorks (RAID)

d_subtype

Specifies the device subtype specific to the controller or device type.

d_typename

Specifies up to a 16-character string array that gives the type name. The following type name strings are recognized: unknown, SMD, MSCP, old DEC, SCSI, ESDI, type 6, type 7, type 8, type 9, floppy, and SWXCR.

d_packname

Specifies the pack identifier returned when the disklabel is read off the disk or in-core copy. The d_boot0 and d_boot1 #defines are the (optional) names of the primary (block 0) and secondary (block 1-15) bootstraps as found in /usr/mdec. These are returned when using getdiskbyname to retrieve the values from /etc/disktab.

d_secsize

Specifies the number of bytes per sector.

d_nsectors

Specifies the number of data sectors per track.

d_ntracks

Specifies the number of tracks per cylinder.

d_ncylinders

Specifies the number of data cylinders per unit.

d_secpercyl

Specifies the number of data sectors per cylinder.

d_secperuniit

Specifies the number of data sectors per unit.

d_sparespertrack

Specifies the number of spare sectors per track. Spares are used for bad sector replacements and are not counted in d_nsectors or d_secpercyl. Spare sectors are assumed to be physical sectors occupying space at the end of each track, cylinder, or both.

d_sparespercyl

Specifies the number of spare sectors per cylinder. Spares are used for bad sector replacements and are not counted in d_nsectors or d_secpercyl. Spare sectors are assumed to be physical sectors occupying space at the end of each track, cylinder, or both.

d_acylinders

Specifies the number of alternate cylinders per unit. Alternate cylinders include maintenance, replacement, and configuration description areas.

d_rpm

Specifies rotational speed.

d_interleave

Specifies the physical sector interleave set up by the formatter or controller when formatting. When interleaving is in use, logically adjacent sectors are separated by some number of sectors, specified as the ratio of physical sectors traversed per logical sector. Thus, an interleave of 1:1 implies contiguous layout, while 2:1 implies that logical sector 0 is separated by one sector from logical sector 1. This member is used to compensate for a slow controller.

d_trackskew

Specifies the offset of sector 0 on a particular track relative to sector 0 on the previous track on the same cylinder. This member is used to compensate for a slow controller.

d_cylskew

Specifies the offset of sector 0 on a particular cylinder relative to sector 0 on the previous cylinder. This member is used to compensate for a slow controller.

d_headswitch

Specifies the head switch time in microseconds.

d_trkseek

Specifies track-to-track seek time in microseconds.

d_flags

Specifies the following generic flags shared by various drives:

Flag	Description
D_REMOVABLE	Removable media
D_ECC	Supports ECC
D_RAMDISK	Disk emulator
D_CHAIN	Supports back-to-back transfers
D_DYNAM_GEOM	Dynamic geometry device

d_drivedata

Specifies an array of integers for storing information specific to the drive type.

d_magic2

Specifies the magic number.

d_checksum

Specifies bitwise exclusive OR (XOR) of the data, including partitions.

d_npartitions

Specifies the number of partitions in the partition map.

d_bbsize

Specifies the size of the boot area in bytes.

d_sbsize

Specifies the size of the superblock in bytes.

d_partition

Specifies an array of structures, one per partition, containing the following members:

• p_size

  Number of sectors in the partition

• p_offset

  Starting offset of the sector
  

• p_fsize

  File system basic fragment size

• p_fstype

  One of the following file system types:

  Type	Description
  FS_UNUSED	Unused
  FS_SWAP	Swap
  FS_V6	Sixth edition
  FS_V7	Seventh edition
  FS_SYSV	System V
  FS_V71K	Version 7, 1K blocks
  FS_V8	8th edition, 4K blocks
  FS_BSDFFS	4.2BSD, fast file system
  FS_ADVFS	Digital Advanced File System
  FS_LSMpubl	Digital Logical Storage, public region
  FS_LSMpriv	Digital Logical Storage, private region
  FS_LSMsimp	Digital Logical Storage, simple disk

• p_frag - File system fragments per block

• p_cpg - File system cylinders per group

Description

Each disk has a label that includes information about the hardware disk geometry, file system partitions, and drive-specific information. The label is in block 0 or 1, possibly offset from the beginning to leave room for bootstrap information. A device driver uses the LABELSECTOR and LABELOFFSET constants to refer to the location of the label.

The disklabel structure is accessed by the disk device driver's open interface to set up the default geometry and partition 0 on the disk. The DIOCGDINFO and DIOCGPART ioctl commands use this structure to return the disklabel and partition structures; the DIOCSDINFO and DIOCWDINFO ioctl commands to set or write the contents of the structure.

Related Information

DIOCGDINFO, DIOCGPART, DIOCSDINFO, DIOCWDINFO, readdisklabel, setdisklabel, writedisklabel

driver

Defines driver entry points and other driver-specific information

Include File

/usr/sys/include/io/common/devdriver.h

Synopsis

struct driver {
  int     (*probe)();
  int     (*slave)();
  int     (*cattach)();
  int     (*dattach)();
  int     (*go)();
  caddr_t *addr_list;
  char    *dev_name;
  struct  device **dev_list;
  char    *ctlr_name;
  struct  controller **ctlr_list;
  short   xclu;
  int     addr1_size;
  int     addr1_atype;
  int     addr2_size;
  int     addr2_atype;
  int     (*ctlr_unattach)();
  int     (*dev_unattach)();
};

Members

probe

Specifies a pointer to the driver's probe interface, which is called to verify that the controller exists.

slave

Specifies a pointer to the driver's slave interface, which is called once for each device connected to the controller.

cattach

Specifies a pointer to the driver's controller attach interface, which is called to allow controller-specific initialization. You can set this pointer to NULL.

dattach

Specifies a pointer to the driver's device attach interface, which is called once for each slave call that returns success. You use the device attach interface for device-specific initialization. You can set this pointer to NULL.

go

Specifies a pointer to the driver's go interface, which is not currently used.

addr_list

Specifies a list of optional CSR addresses.

dev_name

Specifies the name of the device connected to this controller.

dev_list

Specifies an array of pointers to device structures currently connected to this controller. This member is indexed through the logunit member of the device structure associated with this device.

ctlr_name

Specifies the controller name.

ctlr_list

Specifies an array of pointers to controller structures. The system uses this member when multiple controllers are controlled by a single device driver. This member is indexed through the ctlr_num member of the controller structure associated with this device.

xclu

Specifies a field that is not currently used.

addr1_size

Specifies the size (in bytes) of the first CSR area. This area is usually the control status register of the device. Only drivers operating on the VMEbus use this member.

addr1_atype

Specifies the address space, access mode, transfer size, and swap mode of the first CSR area. Note that not all bus adapters use the transfer size. Only drivers operating on the VMEbus use this member.

addr2_size

Specifies the size (in bytes) of the second CSR area. This area is usually the data area that the system uses with devices that have two separate CSR areas. Only drivers operating on the VMEbus use this member.

addr2_atype

Specifies the address space, access mode, transfer size, and swap mode of the second CSR area. Note that not all bus adapters use the transfer size. Only drivers operating on the VMEbus use this member.

ctlr_unattach

Specifies a pointer to the controller's unattach interface. Dynamically configured drivers use the controller unattach interface.

dev_unattach

Specifies a pointer to the device's unattach interface. Dynamically configured drivers use the device unattach interface.

Description

The driver structure defines driver entry points and other driver-specific information. You declare and initialize an instance of this structure in the declarations section of the device driver. The bus configuration code uses the entry points defined in this structure during device autoconfiguration. The bus configuration code fills in the dev_list and ctlr_list arrays. The driver interfaces use these arrays (members of the device and controller structures) to get the structures for specific devices or controllers.

Related Information

bus, controller, device

dsent

Defines a device driver's entry points and other information

Include File

/usr/sys/include/sys/conf.h

Synopsis

struct dsent
{
  int (*d_open)();
  int (*d_close)();
  int (*d_strategy)();
  int (*d_read)();
  int (*d_write)();
  int (*d_ioctl)();
  int (*d_dump)();
  int (*d_psize)();
  int (*d_stop)();
  int (*d_reset)();
  int (*d_select)();
  int (*d_mmap)();
  int (*d_segmap)();
  struct tty *d_ttys;
  int d_funnel;
  int d_bflags;
  int d_cflags;
};

Members

d_open

Specifies a pointer to an entry point for the block and character driver's open interface, which opens a device.

d_close

Specifies a pointer to an entry point for the block and character driver's close interface, which closes a device.

d_strategy

Specifies a pointer to an entry point for the block driver's strategy interface, which reads and writes block data.

d_read

Specifies a pointer to an entry point for the character driver's read interface, which reads characters or raw data.

d_write

Specifies a pointer to an entry point for the character driver's write interface, which writes characters or raw data.

d_ioctl

Specifies a pointer to an entry point for the block and character driver's ioctl interface, which performs special functions or I/O control.

d_dump

Specifies a pointer to an entry point for a block driver's dump interface, which is used for panic dumps of the system image.

d_psize

Specifies a pointer to an entry point for the block driver's psize interface, which returns the size in physical blocks of a device (disk partition).

d_stop

Specifies a pointer to an entry point for the driver's stop interface, which suspends other processing on behalf of the current process. You typically use the d_stop member only for terminal (character) drivers.

d_reset

Specifies a pointer to an entry point for the character driver's reset interface, which stops all current work and places the device connected to the controller in a known, quiescent state.

d_select

Specifies a pointer to an entry point for the character driver's select interface, which determines if a call to a read or write interface will block.

d_mmap

Specifies a pointer to an entry point for the character driver's mmap interface, which maps kernel memory to user address space.

d_segmap

Specifies the character driver's segmap entry point.

d_ttys

Specifies a pointer to the character driver's private data.

d_funnel

Schedules block and character device drivers onto a CPU in a multiprocessor configuration. You set this member to one of the following constants:

Value	Meaning
DEV_FUNNEL	Specifies that you want to funnel the device driver because you have not made it SMP safe. This means that the driver is forced to execute on a single (the master) CPU. Even if you funnel your device driver, you must follow the SMP locking conventions when accessing kernel data structures external to the driver. Typically, you use kernel interfaces that Digital supplies to indirectly access kernel data structures outside the driver.
DEV_FUNNEL_NULL	Specifies that you do not want to funnel the device driver because you have made it SMP safe. This means that the driver can execute on multiple CPUs. You make a device driver SMP safe by using the simple or complex lock mechanism.

d_bflags

Specifies a block driver's device-related and other flags. You set this member to the bitwise inclusive OR of the device-related and other flags. One example of a device-related flag is B_TAPE. This flag is set in the b_flags member of the buf structure. The B_TAPE flag determines whether to use delayed writes, which are not allowed for tape devices. For all other drivers, this member is set to the value zero (0).

Another flag specifies whether this character driver is an SVR4 DDI/DKI-compliant device driver. You set this member to the B_DDIDKI flag to indicate that this is an SVR4 DDI/DKI-compliant device driver.

d_cflags

Specifies whether this character driver is an SVR4 DDI/DKI-compliant device driver. Set this member to the C_DDIDKI constant to indicate that this is an SVR4 DDI/DKI-compliant device driver.

Description

The dsent data structure contains pointers to entry points for a specific driver's I/O services interfaces and other information. The system maintains a table (array) of these dsent structures (referred to as the device switch table) that contains pointers to entry points for the associated driver's I/O services interfaces for each block and character mode device that the system supports. In addition, the table can contain stubs for device driver entry points for block and character mode devices that do not exist or entry points not used by a device driver.

Both block and character device special files can access the same device driver entry. If the device driver does not support access by both block and character device special files, then the driver must perform the appropriate check in its open interface and return an error for the devices it does not support.

Related Information

devsw_add, devsw_del, devsw_get

handler_intr_info

Contains interrupt handler information

Include File

/usr/sys/include/io/common/handler.h

Synopsis

Member Name	Data Type
configuration_st	caddr_t
intr	int (*intr) ()
param	caddr_t
config_type	unsigned int

Members

configuration_st

Specifies a pointer to the bus or controller structure for which an associated interrupt handler is written.

intr

Specifies the name of the interrupt handler for the specified bus or controller.

param

Specifies a parameter that you want passed to the specified interrupt handler.

config_type

Specifies the driver type and whether the driver's interrupt handler can handle shared interrupts. If your device driver's interrupt handler cannot handle shared interrupts, you set this member to one of the following interrupt handler type bit values defined in handler.h: CONTROLLER_CONFIG_TYPE (the interrupt handler is for a controller) or ADAPTER_CONFIG_TYPE (the interrupt handler is for a bus adapter). If your device driver's interrupt handler can handle shared interrupts, you set this member to the bitwise inclusive OR of the interrupt handler type bit value and the shared interrupt bit value SHARED_INTR_CAPABLE.

Description

The handler_intr_info structure contains interrupt handler information for device controllers connected to a bus. This generic structure makes device drivers more portable across different buses because it contains all of the necessary information to add an interrupt handler for any bus. Device driver writers set the ih_bus_info member of the ihandler_t structure to the filled-in handler_intr_info structure, usually in the driver's probe interface.

The bus and controller structures contain the bus- and controller-specific information that is not provided in handler_intr_info.

Notes

The handler_intr_info data structure is a direct copy of the tc_intr_info data structure that TURBOchannel bus device drivers use. The handler_intr_info structure provides binary compatibility with previously written TURBOchannel device drivers and source code compatibility across device drivers that operate on a variety of buses including TURBOchannel, PCI, EISA, and ISA buses.

Related Information

handler_add, handler_del, handler_disable, handler_enable, ihandler_t

ihandler_t

Contains information associated with device driver interrupt handling

Include File

/usr/sys/include/io/common/handler.h

Synopsis

Member Name	Data Type
ih_id	ihandler_id_t
ih_bus	struct bus *
ih_bus_info	char *

Members

ih_id

Specifies a unique ID. Device drivers do not use this member.

ih_bus

Specifies a pointer to the bus structure associated with this device driver. This member is needed because the interrupt dispatching methodology requires that the bus be responsible for dispatching interrupts in a bus-specific manner.

ih_bus_info

Specifies bus registration information.

Description

The ihandler_t structure contains information associated with device driver interrupt handling. This model of interrupt dispatching uses the bus as the means of interrupt dispatching for all drivers. For this reason, all of the information needed to register an interrupt is considered to be bus specific. As a result, no attempt is made to represent all the possible permutations within the ihandler_t data structure.

Device driver writers pass the ihandler_t structure to the handler_add interface in the driver's probe interface to specify how interrupt handlers are to be registered with the bus-specific interrupt dispatcher.

Device driver writers set the ih_bus_info member to the filled-in handler_intr_info structure, which contains the bus-specific information.

Related Information

bus, handler_add

item_list

Contains hardware platform-specific information

Include File

/usr/sys/include/io/common/devdriver.h

Synopsis

Member Name	Data Type
function	u_long
out_flags	u_int
in_flags	u_int
rtn_status	u_long
next_function	struct item_list *
input_data	u_long
output_data	u_long

Members

function

Stores the function code that represents the system item for which you want to obtain specific information. You can pass one of the following constants defined in devdriver.h to the function member:

Constant	Meaning
GET_TC_SPEED	Requests that get_info return the TURBOchannel bus clock speed (in kilohertz) for this system. For example, get_info returns 250 for a 25-megahertz clock speed. You pass this constant only if a TURBOchannel bus is hardwired to the hardware platform.
MOP_SYSID	Requests that get_info return the MOP system ID for the system that the drivier operates on.
CONSOLE_2_DEV	Requests that get_info return the controller number associated with the controller that the system booted from. The get_info interface locates this controller by traversing the array of bus structures.
DEV_2_CONSOLE	Requests that get_info return the boot device string for the console. The get_info interface constructs the boot device string from information contained in the devget structure.
DEV_2_USER	Requests that get_info return the string that a user enters at the console terminal to boot the system.

out_flags

Stores flags for output data. This member is for future use.

in_flags

Stores flags for input data. This member is for future use.

rtn_status

Stores the status code for the function code you passed to the function member. The get_info interface can set this member to one of the following status codes:

Status Code	Meaning
INFO_RETURNED	The CPU platform that the driver operates on supports the system item associated with the function code you passed to the function member. This value indicates that the system item returned by get_info to the output_data member is valid.
NOT_SUPPORTED	The CPU platform that the driver operates on does not support the system item associated with the code you passed to the function member; or, the CPU platform does not support the get_info interface.

next_function

Specifies a pointer to the next item_list structure in the linked list. This item_list structure stores the function code that represents the next system item for which you want to obtain specific information. You set this member to the value NULL to indicate the last item_list structure in the linked list.

input_data

Specifies a pointer to input data for the function associated with the function code that you specified in the function member.

output_data

Stores the specific information for the system item associated with the function code that you passed to the function member. The get_info interface returns CPU-specific values to the output_data member. These values are for the function associated with the function code that you specified in the function member.

Description

The item_list data structure contains platform-specific information. Device drivers obtain this platform-specific information by calling the get_info interface.

Related Information

get_info

lock

Contains complex lock-specific information

Include File

/usr/sys/include/kern/lock.h

Synopsis

The lock structure is an opaque data structure; that is, its associated members are referenced and manipulated by the Digital UNIX operating system and not by the user of the complex lock mechanism. Therefore, this reference page omits a description of the lock structure's associated members.

Description

The lock data structure is the complex lock structure that contains complex lock-specific information. A device driver writer using the complex lock method declares a pointer to a lock structure and passes its address to the associated lock interfaces.

Notes

The header file lock.h shows typedef statements that assign the alternate name lock_data_t for the complex lock structure and lock_t for a pointer to the complex lock structure.

Related Information

lock_done, lock.h, lock_init, lock_read, lock_terminate, lock_try_read, lock_try_write, lock_write, slock

port

Contains information about a port

Include File

/usr/sys/include/io/common/devdriver.h

Synopsis

Member Name	Data Type
conf	int (*conf) ()

Members

conf

Specifies a pointer to the configuration interface for this port.

Description

The port structure contains information about a port.

Related Information

bus, controller

pt_tbl

Stores a disk partition map

Include File

/usr/sys/include/sys/disklabel.h

Synopsis

struct pt_tbl {
        struct partition d_partitions[MAXPARTITIONS];
};

Members

d_partitions

Specifies an array of partition structures, up to the maximum number of partitions allowed on the disk. The partition structure is defined by the disklabel structure. It contains the block size and offset of the partition, plus file system information.

Description

The pt_tbl structure contains a disk's partition map, which describes the partitions on the disk. The disk driver's open interface and the DIOCGDEFPT ioctl command use the pt_tbl structure to hold the disk's default partition map created by those interfaces. The disk driver's DIOCGCURPT and DIOCGDEFPT ioctl commands use the pt_tbl structure to return the current and default partition maps.

Related Information

DIOCGCURPT, DIOCGDEFPT, disklabel

sel_queue

Defines a queue of select events

Include File

/usr/sys/include/sys/select.h

Synopsis

Member Name	Data Type
links	struct queue_entry
event	struct event *

Members

links

Specifies a queue_entry structure. This structure contains a generic doubly linked list (queue).

event

Specifies a pointer to an event structure. This structure is an opaque structure; that is, you do not reference it in your device driver.

Description

The sel_queue data structure provides device driver writers with a generic queue of select events. You must initialize the links member by calling the queue_init interface prior to using the select_enqueue and select_dequeue interfaces.

Related Information

select.h, select_dequeue, select_enqueue

sg_entry

Contains bus address/byte count pairs

Include File

/usr/sys/include/io/common/devdriver.h

Synopsis

Member Name	Data Type
ba	bus_addr_t
bc	long

Members

ba

Stores an I/O bus address.

bc

Stores the byte count associated with the I/O bus address. This byte count indicates the contiguous addresses that are valid on this bus.

Description

The sg_entry data structure contains two members: ba and bc. These members represent a bus address/byte count pair for a contiguous block of an I/O buffer mapped onto a controller's bus memory space. The byte count indicates the number of bytes that the address is contiguously valid for on the controller's bus address space. Consider a list entry that has its ba member set to aaaa and its bc member set to nnnn. In this case, the device can perform a contiguous DMA data transfer starting at bus address aaaa and ending at bus address aaaa+nnnn-1.

Notes

The header file devdriver.h shows a typedef statement that assigns the alternate name sg_entry_t for a pointer to the sg_entry structure.

Related Information

dma_get_curr_sgentry, dma_get_next_sgentry, dma_put_curr_sgentry, dma_put_prev_sgentry

slock

Contains simple lock-specific information

Include File

/usr/sys/include/kern/lock.h

Synopsis

The slock structure is an opaque data structure; that is, its associated members are referenced and manipulated by the Digital UNIX operating system and not by the user of the simple lock method. Therefore, this reference page omits a description of the slock structure's associated members.

Description

The slock data structure is the simple spin lock structure that contains simple lock-specific information. The user of the simple lock method declares a slock structure by calling the decl_simple_lock_data interface. In subsequent calls to simple_lock, simple_lock_init, simple_lock_try, and simple_unlock, the caller passes the address of the previously declared slock structure.

Notes

The header file lock.h shows typedef statements that assign the alternate name simple_lock_data_t for the simple spin lock structure and simple_lock_t for a pointer to the simple spin lock structure.

Related Information

decl_simple_lock_data, lock.h, lock, simple_lock, simple_lock_init, simple_lock_terminate, simple_lock_try, simple_unlock

task

Contains task-specific information

Include File

/usr/sys/include/kern/task.h

Synopsis

The task structure is an opaque data structure; that is, all of its associated members are referenced and manipulated by the Digital UNIX operating system and not by the user of kernel threads. Therefore, this reference page omits a description of the task structure's associated members.

Description

The task data structure contains task-related information.

Notes

The header file task.h shows a typedef statement that assigns the alternate name task_t for a pointer to the task structure. Some of the kernel threads-related interfaces require that you pass a pointer to the task structure.

Related Information

task.h, kernel_thread_w_arg

thread

Contains kernel threads-related information

Include File

/usr/sys/include/kern/thread.h

Synopsis

Member Name	Data Type
wait_result	kern_return_t

Members

wait_result

Specifies the outcome of the wait. The kernel can set this member to one of the following values: THREAD_AWAKENED, THREAD_INTERRUPTED, THREAD_TIMED_OUT, THREAD_SHOULD_TERMINATE, and THREAD_RESTART.

Description

The thread data structure contains kernel threads-related information. Device drivers typically use the wait_result member (along with the current_thread interface) to check for the result of the wait. The values associated with the member have the following meanings:

Value	Meaning
THREAD_AWAKENED	The result of the assert wait is a normal wakeup.
THREAD_TIMED_OUT	The specified timeout has expired.
THREAD_INTERRUPTED	The wait condition was interrupted by the clear_wait interface.
THREAD_SHOULD_TERMINATE	The result of the assert wait is that the current kernel thread should terminate.
THREAD_RESTART	The current kernel thread should be restarted.

Notes

The header file thread.h shows a typedef statement that assigns the alternate name thread_t for a pointer to the thread structure. Many of the kernel threads-related interfaces operate on these pointers to thread structures.

The thread structure is an opaque data structure; that is, all of its associated members (except for the wait_result member) are referenced and manipulated by the Digital UNIX operating system and not by the user of kernel threads.

Related Information

clear_wait, current_thread, thread.h, thread_block, thread_set_timeout, thread_wakeup, thread_wakeup_one

uio

Describes I/O, either single vector or multiple vectors

Include File

/usr/sys/include/sys/uio.h

Synopsis

Member Name	Data Type
uio_iov	struct iovec *
uio_iovcnt	int
uio_offset	off_t
uio_segflg	enum uio_seg
uio_resid	int
uio_rw	enum uio_rw

Members

uio_iov

Specifies a pointer to the first iovec structure. The iovec structure has two members: one that specifies the address of the segment and another that specifies the size of the segment. The system allocates contiguous iovec structures for a given transfer.

uio_iovcnt

Specifies the number of iovec structures for this transfer.

uio_offset

Specifies the offset within the file.

uio_segflg

Specifies the segment type. This member can be set to one of the following values: UIO_USERSPACE (the segment is from the user data space), UIO_SYSSPACE (the segment is from the system space), or UIO_USERISPACE (the segment is from the user I space).

uio_resid

Specifies the number of bytes that still need to be transferred.

uio_rw

Specifies whether the transfer is a read or a write. This member is set by read and write system calls according to the corresponding field in the file descriptor. This member can be set to one of the following values: UIO_READ (read transfer), UIO_WRITE (write transfer), or UIO_AIORW (Alpha I/O read/write transfer).

Description

The uio structure describes I/O, either single vector or multiple vectors. Typically, device drivers do not manipulate the members of this structure. However, the structure is presented here for the purpose of understanding the uiomove kernel interface, which operates on the members of the uio structure.

Related Information

uiomove

v1_bustype_info_t

Stores bus information

Include File

/usr/sys/include/io/common/devgetinfo.h

Synopsis

typedef struct v1_bustype_info {
    int adpt_num;
    int nexus_num;
    int bus_num;
    int ctlr_num;
    int rctlr_num;
    int slave_num;
    int unit_num;
    int pad0;
    union {
        v1_scsi_bus_info_t scsi;
        uchar_t busdata[DEV_BUS_LEN];
    } bus;
} v1_bustype_info_t;

Members

adpt_num

Specifies the controller chip relative to the current adaptor. For example, if an adaptor has two controller chips, chip A is instance 0 and chip B is instance 1.

nexus_num

Specifies the slot that the adaptor is using.

bus_num

Specifies the logical bus number that the adaptor is plugged into.

ctlr_num

Specifies the system-wide instance number of the current adaptor. For example, two adaptors with two controller chips result in instances 0, 1, 2, and 3, corresponding to adaptor 0, chip A; adaptor 0, chip B; adaptor 1 chip A; adaptor 1, chip B.

rctlr_num

Specifies the remote ID for the adaptor, usually 0.

slave_num

Specifies the number of the device relative to the controlling hardware. For example, if there are two disk devices off of chip A, one is slave 0 and the other is slave 1.

unit_num

Specifies the system-wide number of this device.

bus

Specifies a union of architecture-specific bus information, either a scsi_bus_info_t structure or an array of characters.

Description

The v1_bustype_info_t contains information about the bus type that is returned by the DEVGETINFO ioctl command.

Related Information

v1_device_info_t

v1_device_info_t

Stores device information

Include File

/usr/sys/include/io/common/devgetinfo.h

Synopsis

typedef struct v1_device_info  {
    int version;
    short category;
    short bus;
    char interface[DEV_STRING_SIZE];
    char device[DEV_STRING_SIZE];
    char dev_name[DEV_STRING_SIZE];
    ulong_t soft_count;
    ulong_t hard_count;
    v1_devtype_info_t devinfo;
    v1_bustype_info_t businfo;
    uchar_t private[DEV_PRIVATE_LEN];
} v1_device_info_t;

Members

version

Specifies the version number of the structure definition.

category

Specifies the category of the device, such as disk or tape.

bus

Specifies the device's bus type, for example, BUS_PCI, BUS_EISA, and BUS_EISA. The /usr/sys/include/io/common/devdriver.h file defines the different bus types.

interface

Specifies a string that describes the interface of this device, such as an AIO disk controller or an HSC40 controller.

device

Specifies a string that describes this device.

dev_name

Specifies a string that gives the device name.

soft_count

Specifies the number of soft errors that have occurred on the device.

hard_count

Specifies the number of hard errors that have occurred on the device.

devinfo

Specifies a structure that contains information specific to this category of device, such as a v1_disk_dev_info_t structure for a disk device or v1_tape_dev_info_t structure for a tape device.

businfo

Specifies a structure that contains information specific to this type of bus, such as a v1_bustype_info_t structure.

private

Specifies an area to be used by the device driver for its own purposes.

Description

The v1_device_info_t structure contains all the information returned to the user data buffer by the DEVGETINFO ioctl command. This structure is contained within the device_info_t structure so that the same interface can be used for various versions of the data structures.

Related Information

device_info_t, v1_devtype_info_t, v1_bustype_info_t

v1_devtype_info_t

Stores device-type information

Include File

/usr/sys/include/io/common/devgetinfo.h

Synopsis

typedef union v1_devtype_info {
    v1_disk_dev_info_t disk;
    v1_tape_dev_info_t tape;
    uchar_t devdata[DEV_TYPE_LEN];
} v1_devtype_info_t;

Members

disk

Specifies a structure that contains disk status information.

tape

Specifies a structure that contains tape status information.

devdata

Specifies an array of 256 bytes of data. This array is used for returning device-specific information for which no structure is defined.

Description

The v1_devtype_info_t union contains device-specific information returned by the DEVGETINFO ioctl command. It is a member of the device_info_t union, the top-level definition of the information returned to the user data buffer. The type of information in the union depends on the device type either disk, tape, or some other type of device for which no device-specific structure has been defined.

Related Information

device_info_t, v1_disk_dev_info_t, v1_tape_dev_info_t

v1_disk_dev_info_t

Stores disk information

Include File

/usr/sys/include/io/common/devgetinfo.h

Synopsis

typedef struct v1_disk_dev_info {
    ulong_t status;
    ulong_t capacity;
    ulong_t blocksz;
    uchar_t class;
    uchar_t part_num;
    uchar_t raid_level;
    uchar_t pad0;
    ushort_t media_changes;
    ushort_t pad1;
    union {
        struct {
            uchar_t density_code;
            uchar_t flags;
        } scsi;
        uchar_t archdata[DEV_ARCH_LEN];
    } arch;
} v1_disk_dev_info_t;

Members

status

Specifies the device status, such as ready, off line, or removable.

capacity

Specifies the number of blocks on the device.

blocksz

Specifies the number of bytes per block.

class

Specifies the disk class. The following classes are defined for disks:

Class	Description
DKDEV_CLS_UNKNOWN	Unknown class
DKDEV_CLS_HARDDISK	Hard disk
DKDEV_CLS_FLPY_GENERIC	Floppy diskette with no known density
DKDEV_CLS_FLPY_3_DD2S	3.5", 720KB, DD, 2-sided, 9 sectors
DKDEV_CLS_FLPY_3_HD2S	3.5", 1.44MB, HD, 2-sided, 18 sectors
DKDEV_CLS_FLPY_3_ED2S	3.5", 2.88MB, ED, 2-sided, 36 sectors
DKDEV_CLS_FLPY_5_LD2S	5.25", 360KB, LD, 2-sided, 9 sectors
DKDEV_CLS_FLPY_5_DD1S	5.25", 400KB, DD, 1-sided, 10 sectors
DKDEV_CLS_FLPY_5_DD2S	5.25", 720KB, DD, 2-sided, 9 sectors
DKDEV_CLS_FLPY_5_HD2S	5.25", 1.2MB, HD, 2-side, 15 sectors
DKDEV_CLS_CDROM	CD-ROM
DKDEV_CLS_WORM	Write once, read many times

part_num

Specifies the partition number on the disk.

raid_level

Specifies the raid level of the media.

pad0

Specifies a reserved member.

media_changes

Specifies the number of times the media has changed (for removable media only).

pad1

Specifies a reserved member.

arch

Defines a union of architecture-specific information, either SCSI-specific information or a character string.

Description

The v1_disk_dev_info_t structure contains information regarding the status of the device that is passed to the DEVGETINFO ioctl command.

Related Information

v1_devtype_info_t

v1_tape_dev_info_t

Stores tape information

Include File

/usr/sys/include/io/common/devgetinfo.h

Synopsis

typedef struct v1_tape_dev_info {
    uint_t  media_status;
    uint_t  unit_status;
    long    recordsz;
    long    density_bpi;
    long    density_bpi_wrt;
    long    position;
    long    fm_cnt;
    uchar_t class;
    uchar_t pad[7];
    union {
        struct {
            uint_t  blocking_factor;
            uchar_t valid_flags;
            uchar_t density_code;
            uchar_t buffered_mode;
            uchar_t speed;
            uchar_t compression_code;
        } scsi;
        uchar_t archdata[DEV_ARCH_LEN];
    } arch;
} v1_tape_dev_info_t;

Members

media_status

Specifies the status of the media. The following status values are defined:

Status Code	Meaning
TPDEV_BOM	Beginning of medium (BOM)
TPDEV_EOM	End of medium (EOM)
TPDEV_RESERVED1	Reserved
TPDEV_WRTPROT	Write-protected
TPDEV_BLANK	Blank media
TPDEV_WRITTEN	Written since opened
TPDEV_RESERVED2	Reserved
TPDEV_SOFTERR	Device soft error
TPDEV_HARDERR	Device hard error
TPDEV_DONE	Operation complete/Online
TPDEV_RETRY	Retry
TPDEV_ERASED	Erased
TPDEV_TPMARK	Unexpected tape mark
TPDEV_SHRTREC	Short record
TPDEV_RDOPP	Read opposite
TPDEV_RWDING	Rewinding
TPDEV_POS_VALID	Tape position information is valid

unit_status

Specifies the current status of the unit. The following status values are defined:

Status Code	Meaning
TPDEV_READY	Device online and ready
TPDEV_OFFLINE	Device not ready
TPDEV_NO_EOM	No warning on EOM
TPDEV_HAS_LOADER	Device has integral loader
TPDEV_1FM_ONCLOSE	Write 1 filemark on close
TPDEV_REW_ONCLOSE	Rewind on close
TPDEV_COMPACTING	Density is compacted
TPDEV_COMPRESSING	Compression enabled
TPDEV_BUFFERED	Device is buffering data

recordsz

Specifies the record size, or 0 for variable-sized records.

density_bpi

Specifies the current density setting.

density_bpi_wrt

Specifies the density used for write operations.

position

Specifies the number of records that have been written since the last file mark.

fm_cnt

Specifies the number of file marks that have been encountered since the beginning of the tape.

class

Specifies the tape device class, such as 9-track or QIC.

pad

Specifies a reserved member.

arch

Specifies architecture-specific information, either a SCSI-specific structure or a character string.

Description

The v1_tape_dev_info_t structure contains information about the tape device that is returned by the DEVGETINFO ioctl command.

Related Information

v1_devtype_info_t