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 interface 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:

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 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 is willing to 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:

Capability Description

ATM_DC_DOESPTI Indicates whether the driver keeps track of the Payload Type Indicator (PTI) bits across all cells of cooked packets (when the driver or hardware reassemble the packets from ATM cells). This capability keeps track of the congestion indication bit in the PTI field of the ATM cell header. If this bit is set, the CMM expects the PTI information provided to the atm_cmm_receive call to be valid. If this bit is clear, the CMM ignores the PTI information on received packets.

ATM_DC_DOESGFC Indicates whether the device driver supports passing Generic Flow Control (GFC) bits to the CMM and to convergence layers through the CMM. The use of the GFC bits is not finalized. Therefore, the CMM ignores any GFC bits.

ATM_DC_DOES_AAL5 Indicates that the driver or adapter directly implements AAL5. The driver or adapter adds the AAL5 trailer to outgoing packets (including cyclical redundancy check (CRC) generation) and splits the packets into cells. The driver or adapter will reassemble incoming cells into an AAL5 packet and check the AAL5 trailer CRC. If this bit is set, convergence modules can send or receive packets and do not have to implement the AAL5 SAR functions. If this bit is not set, convergence modules must implement all AAL5 SAR functions and send or receive full ATM cells, if they want to send and receive AAL5 cells.

ATM_DC_DOES_AAL3 Indicates that the driver or adapter directly supports AAL3/4. The driver or adapter adds the AAL3/4 headers and trailers (including CRC) and splits the packets into cells. The driver or adapter reassembles incoming cells into an AAL3/4 packet and checks the CRC. If this bit is set, convergence modules can send or receive packets and do not have to implement the AAL3/4 SAR functions. If this bit is not set, convergence modules must implement all AAL3/4 SAR functions and send or receive full ATM cells, if they want to send and receive AAL3/4 cells.

ATM_DC_DOES_RAW Indicates that the driver or adapter is capable of sending and receiving raw ATM cells. The driver or adapter accepts raw ATM cells (full 53-byte cells) for transmission and passes incoming cells to the CMM as received. A driver can support both raw and AAL5 or AAL3/4 handling simultaneously. If a driver does not support raw cells, convergence modules cannot send arbitrary cells through the interface controlled by the driver. Since most drivers do not support AAL1, AAL2, or AAL3/4 directly, these must be handled by convergence modules as raw cells; the convergence modules must perform any needed SAR functions.

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 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:

Behavior Definition

ATM_QP_STAMP Instructs the driver to time-stamp all incoming cells and place the time-stamp immediately after the cell data in the mbuf. The time is a 64-bit value taken from the systems free-running clock and has a resolution of 10 nanoseconds. These values are useful only for determining the approximate cell interarrival time, by subtracting the time-stamp of cell n from the time-stamp of cell n+1. The time-stamp length is included in the mbuf length (time-stamped cells have an mbuf length of 61 rather than 53). See Section 3.4 for more information on data formats.

ATM_QP_EFLAG Instructs the driver to insert 0-length mbufs to indicate that a cell was dropped due to an error or insufficient resources. If time-stamping is also enabled, the mbuf contains only a 64-bit time-stamp (the mbuf length is 8 bytes). Only cells lost in a manner detectable by the driver are flagged. Cells lost on the network are not tagged. Protocols using continuous bit rate (CBR) can determine if a cell was lost on the network or at the sending station by a gap in the cell interarrival time. See Section 3.4 for more information on data formats.

Capability	Description
`ATM_DC_DOESPTI`	Indicates whether the driver keeps track of the Payload Type Indicator (PTI) bits across all cells of cooked packets (when the driver or hardware reassemble the packets from ATM cells). This capability keeps track of the congestion indication bit in the PTI field of the ATM cell header. If this bit is set, the CMM expects the PTI information provided to the `atm_cmm_receive` call to be valid. If this bit is clear, the CMM ignores the PTI information on received packets.
`ATM_DC_DOESGFC`	Indicates whether the device driver supports passing Generic Flow Control (GFC) bits to the CMM and to convergence layers through the CMM. The use of the GFC bits is not finalized. Therefore, the CMM ignores any GFC bits.
`ATM_DC_DOES_AAL5`	Indicates that the driver or adapter directly implements AAL5. The driver or adapter adds the AAL5 trailer to outgoing packets (including cyclical redundancy check (CRC) generation) and splits the packets into cells. The driver or adapter will reassemble incoming cells into an AAL5 packet and check the AAL5 trailer CRC. If this bit is set, convergence modules can send or receive packets and do not have to implement the AAL5 SAR functions. If this bit is not set, convergence modules must implement all AAL5 SAR functions and send or receive full ATM cells, if they want to send and receive AAL5 cells.
`ATM_DC_DOES_AAL3`	Indicates that the driver or adapter directly supports AAL3/4. The driver or adapter adds the AAL3/4 headers and trailers (including CRC) and splits the packets into cells. The driver or adapter reassembles incoming cells into an AAL3/4 packet and checks the CRC. If this bit is set, convergence modules can send or receive packets and do not have to implement the AAL3/4 SAR functions. If this bit is not set, convergence modules must implement all AAL3/4 SAR functions and send or receive full ATM cells, if they want to send and receive AAL3/4 cells.
`ATM_DC_DOES_RAW`	Indicates that the driver or adapter is capable of sending and receiving raw ATM cells. The driver or adapter accepts raw ATM cells (full 53-byte cells) for transmission and passes incoming cells to the CMM as received. A driver can support both raw and AAL5 or AAL3/4 handling simultaneously. If a driver does not support raw cells, convergence modules cannot send arbitrary cells through the interface controlled by the driver. Since most drivers do not support AAL1, AAL2, or AAL3/4 directly, these must be handled by convergence modules as raw cells; the convergence modules must perform any needed SAR functions.

Behavior	Definition
`ATM_QP_STAMP`	Instructs the driver to time-stamp all incoming cells and place the time-stamp immediately after the cell data in the mbuf. The time is a 64-bit value taken from the systems free-running clock and has a resolution of 10 nanoseconds. These values are useful only for determining the approximate cell interarrival time, by subtracting the time-stamp of cell `n` from the time-stamp of cell `n+1`. The time-stamp length is included in the mbuf length (time-stamped cells have an mbuf length of 61 rather than 53). See Section 3.4 for more information on data formats.
`ATM_QP_EFLAG`	Instructs the driver to insert 0-length mbufs to indicate that a cell was dropped due to an error or insufficient resources. If time-stamping is also enabled, the mbuf contains only a 64-bit time-stamp (the mbuf length is 8 bytes). Only cells lost in a manner detectable by the driver are flagged. Cells lost on the network are not tagged. Protocols using continuous bit rate (CBR) can determine if a cell was lost on the network or at the sending station by a gap in the cell interarrival time. See Section 3.4 for more information on data formats.