4    Device Driver Interface

The ATM device driver interface enables ATM device drivers to communicate with the ATM subsystem. It is a registration-based interface that dynamically configures itself at system boot time. The ATM device drivers resemble other DIGITAL UNIX device drivers, with the following exceptions:

• The interface to the ATM subsystem is different than the current character, block, or networking device driver interfaces.

• ATM drivers must register with the ATM Connection Management Module (CMM).

• ATM drivers provide no read, write, ioctl, or select routine since all these functions are handled through the CMM.

• ATM drivers must provide a probe and attach routine for the operating system to call to determine if the device is present and to attach the device to the operating system.

Like networking drivers, ATM device drivers do not require an entry in the system's cdevsw table.

The ATM device driver interface enables device drivers to:

• Register the device driver

• Receive data packets and cells

• Report errors

This chapter describes each of these tasks, the function calls involved, and the relevant data structures that device driver writers can use. Appendix A contains a reference page for each device driver interface routine.

4.1    Registering the Device Driver

When a DIGITAL UNIX system is booted, it calls each device driver's probe routine to determine if the device that the device driver controls is present on the system and is functional. If the probe routine finds a device, it uses the return value to indicate this to the kernel. The kernel then calls the device's attach routine to attach itself to the system.

When a device driver's attach routine is called, it calls the atm_cmm_register_dd routine before returning from the attach. This registers the device driver with the CMM.

4.2    Receiving Data Packets and Cells

When an ATM device driver receives data packets and cells from the ATM network, it calls the atm_cmm_receive routine to pass the data to the CMM. When the CMM receives the data, it immediately passes the data to the convergence module that owns the virtual circuit (VC). The CMM does not queue the data. That way, the convergence modules receive the data at their input functions in the interrupt context; the driver should do all receive processing in interrupt context for efficiency.

After passing data to the CMM, the driver must not reference any mbufs in the mbuf chain again. If the driver must allocate private storage for data (rather than allocating from the system mbuf pool), the driver must provide an appropriate free routine and set the m_ext structure in the mbuf appropriately. The data mbuf chain is deallocated only when the protocol stack has finished referencing the data.

When an ATM device driver receives operations and maintenance (OAM) cells (nondata cells) from the ATM network, it calls the atm_cmm_oam_receive routine to pass the cells to the CMM for processing. Device drivers should pass all OAM cells to the CMM.

4.3    Reporting Errors

When an ATM device driver detects errors on VCs or other interface failures, it calls the atm_cmm_error routine to report the error to the CMM. When the CMM receives the error report, it recovers or shuts down the VC in error. The driver does not need to perform any other actions. If the VC must be destroyed, the CMM calls the driver through the driver management interface to deactivate or destroy the VC. If the error indicates an interface failure, the CMM tears down VCs on the interface.

4.4    Using ATM Device Driver Interface Structures

The ATM device driver interface uses the following structures exclusively:

• atm_drv_params -- The device parameters and statistics structure

• atm_queue_param -- The queue parameter structure

4.4.1    The atm_drv_params Structure

The CMM and convergence modules need to know the capabilities of each physical interface. Since this information is maintained by the driver for each interface, the system uses the atm_drv_params structure to communicate interface parameters and statistics between modules. The CMM typically queries this information from device drivers and then passes it to other ATM modules on request. The CMM and convergence modules can request this information at any time, and there is no limit on the number of times the information can be queried. Table 4-1 lists those members of the atm_drv_params structure, with their associated data types, that device drivers might reference.

Table 4-1:  The atm_drv_params Structure Members

Member Name	Data Type
name	char *
unit	unsigned int
type	atm_interface_t
num_vc	unsigned int
max_vcib	unsigned int
max_vpib	unsigned int
max_vci	unsigned int
max_vpi	unsigned int
sent	unsigned long
received	unsigned long
dropped	unsigned long
num_vci	unsigned int
num_vpi	unsigned int
hard_mtu	unsigned int
nqueue	unsigned int
flowcontrol	unsigned int
rates	atm_vc_services_t
capabilities	unsigned int
numid	unsigned char
ids[6][1]	unsigned char

4.4.1.1    The name member

The name member specifies a character string that represents the name by which the device is known to the system. Management programs use this string when displaying information about the device. Do not include the character representation of the unit number in this name (for example, specify ATM rather than ATM0).

4.4.1.2    The unit Member

The unit member specifies a unit number for the device for those instances where the driver controls more than one device. The unit numbers start at 0.

4.4.1.3    The type Member

The type member specifies the type of interface that the device uses.

4.4.1.4    The num_vc Member

The num_vc member specifies the maximum number of VCs the driver can have open simultaneously.

4.4.1.5    The max_vcib and max_vpib Members

The max_vcib and max_vpib members specify the largest value the driver permits for VCI and VPI values, respectively.

4.4.1.6    The max_vci and max_vpi Members

The max_vci and max_vpi members specify the maximum number of VCIs and VPIs, respectively, that the driver can support.

4.4.1.7    The sent Member

The sent member is a counter of the total number of cells sent by the driver since it was last brought on line.

4.4.1.8    The received Member

The received member specifies the total number of cells received by the driver since it was last brought on line.

4.4.1.9    The dropped Member

The dropped member specifies the total number of cells dropped by the driver since it was last brought on line.

4.4.1.10    The num_vci and num_vpi Members

The num_vci and num_vpi members specify the number of VCIs and VPIs, respectively, that the interface is currently configured to process.

4.4.1.11    The hard_mtu Member

The hard_mtu member specifies the maximum packet size (in bytes) the driver can accommodate when processing cooked packets (for AAL3/4 and AAL5 only).

4.4.1.12    The nqueue Member

The nqueue member specifies the total number of queues that the interface supports. If the driver supports more than one queue, the CMM assumes the driver is capable of permanently associating VCs to queues for the lifetime of the VC.

4.4.1.13    The flowcontrol Member

The flowcontrol member specifies the types of flow control the driver supports. Valid values are ATM_FLOW_NONE, ATM_FLOW_STD, and ATM_FLOW_VENDOR. The CMM uses this information to assign VCs to multiple queues based on connection service parameters to achieve the best performance and fairness in cell transmission.

4.4.1.14    The rates Member

The rates member specifies an atm_vc_services structure that the driver has set to indicate the maximum cell rates that the interface supports for each cell rate class. These values include any amount the driver can overcommit for the interface. The CMM uses these values to determine if a connection can be granted its requested bandwidth. The other members of the atm_vc_services structure are unused in this context.

4.4.1.15    The capabilities Member

The capabilities member specifies miscellaneous driver capabilities. It is a bit mask that the driver uses to specify functions that the driver can or cannot perform.

The CMM currently uses the following capabilities:

4.4.1.16    The numid Member

The numid member specifies the number of 48-bit Media Access Control (MAC) addresses configured on the device's address read-only memory (ROM). The driver must allocate an atm_drv_params structure large enough to hold all the 48-bit MAC addresses by allocating space as follows:

sizeof(struct atm_drv_params) + numid*6 bytes

4.4.1.17    The ids Member

The ids member specifies an array that holds the 48-bit MAC addresses. Each address appears in the array sequentially starting at ids[6*n ], where n is the address number. The CMM uses these addresses as the end system identifiers (ESI) when registering with the switch.

4.4.2    The atm_queue_param Structure

The atm_queue_param structure is an argument to the ATM_DRVMGMT_RAWPARAM ATM management command. See the description for the atm_cmm_register_dd routine in Appendix A for more information.

Table 4-2 lists those members of the atm_queue_param structure, with their associated data types, that device drivers might reference.

Table 4-2:  The atm_queue_param Structure Members

Member Name	Data Type
vc	atm_vc_p
qlength	unsigned int
qtime	unsigned int
flags	unsigned int

4.4.2.1    The vc Member

The vc member specifies the VC for which the parameters are being set.

4.4.2.2    The qlength Member

The qlength member specifies the number of cells to be queued for passing in a single mbuf chain. The driver waits until this number of cells has been received before passing the cells to the CMM. Larger values reduce the per-cell overhead, but increase latency and the amount of memory consumed to buffer the cells.

4.4.2.3    The qtime Member

The qtime member specifies the maximum interval between cells (in 10-millisecond intervals) before queued cells are passed to the CMM. This value enables the driver to control latency. A value of 0 specifies an infinite amount of time between cells. The interaction between the qlength and qtime values is similar to that in the TTY subsystem. Basically, the driver accumulates cells until qlength cells are received or until there has been more than qtime ticks since the last cell was received.

4.4.2.4    The flags Member

The flags member specifies one of the following behaviors from the driver: