e1x7(7) — SPECIAL FILES AND DEVICES

NAME

e1x7 − MVME1X7 Local Area Network Interface

SYNOPSIS

#include <sys/dlpi.h>
#include <sys/macioctl.h>
#include <sys/e1x7.h>
fd = open("/dev/e1x7_c0", O_RDWR);

DESCRIPTION

The MVME1X7 on-board Intel LANC chip (82596CA) is a Local Area Network Controller for Ethernet and IEEE 802.3 compatible networks. The LANC can handle all IEEE 802.3 Medium Access Control and channel interface functions.

The e1x7 is a STREAMS-based driver used with MVME1X7 cpu boards. The e1x7 interface conforms to the Data Link Provider Interface (DLPI) Version 2.0. To account for possible cpu board expansion, the driver data structures are designed to accomodate more than one LANC controller on a single cpu board via changes to the edt_data and master.d files.

The e1x7 driver can be opened from the clone device driver. The mvmecpu namer program creates or deletes the device special files for the e1x7 driver at boot time. The device special filenames, representing the clone devices, are composed of the string e1x7_cy, where y is the controller number. Controllers are numbered beginning at 0. The device special filename for the first controller in the system is /dev/e1x7_c0. If the MVME1X7 board has a second LANC controller, then its device filename would be /dev/e1x7_c1. The default maximum number of controllers supported by the driver is one (from the /etc/master.d/enet1x7 file).

An e1x7 device special file major device number is the major device number of the clone device driver. An e1x7 minor device number follows the format described in the intro(7) man page, i.e., bits 17 through 15 contain the controller number, bit 14 is set, and bits 13 through 0 contain the real major number, which is found in the file /etc/master.d/enet1x7.

Besides the device special filename, the driver prefix, e1x7, is also used as part of the Ethernet network interface name by both cenet in the network database file /etc/strcf and ifconfig in the script /etc/inet/rc.inet.

USAGE

STREAM Message Processing

The following are the types of STREAMS messages the driver can process:

M_PROTO/M_PCPROTO
Fifteen DLPI protocol message types are supported: DL_INFO_REQ, DL_UNITDATA_REQ, DL_BIND_REQ, DL_UNBIND_REQ, DL_SUBS_BIND_REQ, DL_SUBS_UNBIND_REQ, DL_ENABMULTI_REQ, DL_DISABMULTI_REQ, DL_PROMISCON_REQ, DL_PROMISCOFF_REQ, DL_TEST_REQ, DL_TEST_RES, DL_XID_REQ, DL_XID_RES, and DL_PHYS_ADDR_REQ. Unsupported message types that are received cause an error message of type dl_error_ack_t with dl_errno set to DL_NOTSUPPORTED to be sent back up the stream.

DL_INFO_REQ is a request for driver information. Driver information is passed back up the stream in a message of type dl_info_ack_t with dl_primitive set to DL_INFO_ACK. However, if enough memory is not available for the driver information, an error message of type dl_error_ack_t is sent back up the stream with dl_primitive set to DL_ERROR_ACK.

DL_UNITDATA_REQ is a request to transmit data. The message is in the dl_unitdata_req_t format. The driver will process this message and send data to the appropriate destination address. Errors that can occur during this message are turned around in the message itself and sent back up stream in a message with dl_primitive set to DL_UDERROR_IND.

DL_BIND_REQ is a request to bind a service access point (SAP) to the current stream. The request message is of type dl_bind_req_t. The dl_sap field of the dl_bind_req_t structure must contain a valid Ethernet type or a valid IEEE 802.2 DSAP. Once the stream has been bound, an acknowledgement message of type dl_bind_ack_t is sent back up the stream. Errors generated during the processing of this message that cause an error message of type dl_error_ack_t to be sent back up the stream are: DL_OUTSTATE, DL_BADADDR, and DL_SYSERR.

DL_UNBIND_REQ is a request to unbind the current stream. Errors generated during message processing that cause an error message of type dl_error_ack_t are: DL_OUTSTATE and DL_SYSERRR. An acknowledgement message of type dl_ok_ack_t is generated when the stream has been unbound.

DL_SUBS_BIND_REQ is a request to bind a subsequent SAP to the current stream. The request message is of type dl_subs_bind_req_t. Both classes of DL_SUBS_BIND_REQ are supported (DL_PEER_BIND and DL_HIERARCHICAL_BIND) with the following sematics. A DL_PEER_BIND allows the current stream to bind to another SAP in order to receive packets addressed to that SAP. The peer SAP must be a valid Ethernet type or a valid IEEE 802.2 DSAP. The dl_subs_sap_length field of the dl_subs_bind_req_t must be equal to the sizeof(ulong) (4). A DL_HIERARCHICAL_BIND allows the current stream to bind to a SAP which is logically encapsulated within the SAP which was originally bound to the current stream. This functionality is used to support the SNAP protocol. In order to use the DL_HIERARCHICAL_BIND functionality the current stream must already be bound to the SNAP IEEE 802.2 DSAP (0xAA). The hierarchical SAP contained within the dl_subs_bind_req_t should be a valid SNAP header. The dl_subs_sap_length field of the dl_subs_bind_req_t must be equal to the length of the SNAP header (5). Once the stream has been subsequently bound, an acknowledgement message of type dl_subs_bind_ack_t is sent back up the stream. Errors generated during the processing of the message that cause a error message of type dl_error_ack_t to be sent back up the stream are: DL_OUTSTATE, DL_BADADDR, and DL_SYSERR.

DL_SUBS_UNBIND_REQ is a request to unbind a subsequent SAP from the current stream. The request message is of type dl_subs_unbind_req_t. The length of the dl_subs_sap_length field of the dl_subs_unbind_req_t must be either sizeof(ulong) (4) or the length of the SNAP header (5). Errors generated during message processing that cause an error message of type dl_error_ack_t are: DL_OUTSTATE, DL_BADADDR and DL_SYSERRR. An acknowledgement message of type dl_ok_ack_t is generated when the unbind of the subsequent SAP succeeds.

DL_ENABMULTI_REQ is a request to enable a multicast address on a per-stream basis. The request message is of type dl_enabmulti_req_t. An individual stream may have a maximum of two hundred fifty-five multicast addresses in its table. Each controller may have a maximum of two hundred fifty-five multicast addresses configured for all open streams. An acknowledgement message of type dl_ok_ack_t is generated if the request is valid. A message of type dl_error_ack_t is generated with dl_errno set to DL_BADADDR if the multicast address is invalid or dl_errno set to DL_TOOMANY if there is no space left in the controller’s multicast table.

DL_DISABMULTI_REQ is a request to disable a multicast address on a per-stream basis. An acknowledgement message of type dl_ok_ack_t is generated if the request is valid. A message of type dl_error_ack_t is generated with dl_errno set to DL_BADADDR if the multicast address is invalid or dl_errno set to DL_NOTENAB if the requested address is not currently enabled.

DL_PROMISCON_REQ is a request to enable promiscuous service on a per-stream basis. The request message is of type dl_promiscon_req_t. The dl_level field must be one of DL_PROMISC_PHYS, DL_PROMISC_SAP, DL_PROMISC_MULTI or DL_PROMISC_TRANS. DL_PROMISC_TRANS is an extension of DLPI 2.0 which allows a stream to receive all packets transmitted by the current controller. A message of type dl_error_ack_t is generated with dl_errno set to DL_SYSERR if the request fails. A message of type dl_ok_ack_t is generated if the request succeeds.

DL_PROMISCOFF_REQ is a request to disable promiscuous service on a per-stream basis. The request message is of type dl_promiscoff_req_t. The dl_level field must be one of DL_PROMISC_PHYS, DL_PROMISC_SAP, DL_PROMISC_MULTI or DL_PROMISC_TRANS. A message of type dl_error_ack_t is generated with dl_errno set to DL_OUTSTATE or DL_SYSERR if the request fails. If the request succeeds a message of type dl_ok_ack_t is generated.

DL_TEST_REQ is a request to transmit an IEEE 802.2 Test Request message. The request message is of type dl_test_req_t. On failure a message of type dl_error_ack_t is returned with dl_errno set to DL_BADADDR, DL_OUTSTATE or DL_SYSERR. On success the controller will transmit an IEEE 802.2 Test Request to the address specified in the dl_test_req_t message.

DL_TEST_RES is a request to transmit an IEEE 802.2 Test Response message. The request message is of type dl_test_res_t. On failure a message of type dl_error_ack_t is returned with dl_errno set to DL_BADADDR, DL_OUTSTATE or DL_SYSERR. On success the controller will transmit an IEEE 802.2 Test Response to the address specified in the dl_test_res_t message.

DL_XID_REQ is a request to transmit an IEEE 802.2 XID Request message. The request message is of type dl_xid_req_t. On failure a message of type dl_error_ack_t is returned with dl_errno set to DL_BADADDR, DL_OUTSTATE or DL_SYSERR. On success the controller will transmit an IEEE 802.2 XID Request to the address specified in the dl_xid_req_t message.

DL_XID_RES is a request to transmit an IEEE 802.2 XID Response message. The request message is of type dl_xid_res_t. On failure a message of type dl_error_ack_t is returned with dl_errno set to DL_BADADDR, DL_OUTSTATE or DL_SYSERR. On success the controller will transmit an IEEE 802.2 XID Response to the address specified in the dl_xid_res_t message.

DL_PHYS_ADDR_REQ is a request to retrieve the current or factory configured physical address of the controller associated with the current stream. The request message is of type dl_phys_addr_req_t. On success a message of type dl_phys_addr_ack_t is returned. On failure a message of type dl_error_ack_t is returned with dl_errno set to DL_SYSERR.

M_IOCTL
ioctl(2) commands are received in messages of type iocblk. Command data, as specified in each command description, must be stored in a connected message block of type M_DATA. Data passed back upstream is always contained in an M_DATA block. All of the ioctl #defines used can be found in the files sys/macioctl.h and sys/e1x7.h. A description of user ioctl stream messages can be found under the I_STR command in streamio(7).

DLIOCRAW is a request which puts the current stream in raw mode. Raw mode allows the user to transmit and receive raw Ethernet packets with no DLPI headers. This functionality is available in order to support applications which have sufficient knowledge of the underlying media to handle the transmission and reception of raw frames.

DL_IOC_HDR_INFO is a request which allows the user to negotiate a fast path for a specific destination address. The request requires a M_DATA block to be attached to the M_IOCTL block. The M_DATA block should contain a message of type dl_unitdata_req_t. If the request succeeds a M_IOCACK block will be returned up stream with the original M_DATA block attached. Attached to the original M_DATA block will be an M_DATA block which contains the Ethernet header corresponding to the destination contained in the dl_unitdata_req_t message. A copy of this new M_DATA block can be prepended to packets bound for the destination address. This frees the driver from the need to parse DLPI headers on every packet and can provide significant performance improvement. This functionality works for both Ethernet types and IEEE 802.2 DSAP’s, however, it is very important that the new M_DATA always be copied rather than duped. The driver assumes that it can write in the header of fast path packets and this is could lead to serious problems if the M_DATA block is duped rather than copied. If the DL_IOC_HDR_INFO request fails a M_IOCNAK block is returned with original M_DATA block attached.

MACIOC_GETMIB2STATS is a request which allows the caller to retrieve the interface portion of the MIB-II statistics described in RFC 1213. The request requires an M_DATA block large enough to hold a structure of type mib2_ifEntry_t. This structure is defined in sys/macioctl.h.

MACIOC_GETETHERSTATS is a request which allows the caller to retrieve the Ethernet MIB statistics described in RFC 1398. The request requires an M_DATA block large enough to hold a structure of type mib2_ether_t. This structure is defined in sys/macioctl.h.

MACIOC_CLEARSTATS is a request which allows the caller to clear all the drivers hardware and software statistics. The request does not require any M_DATA blocks.

MACIOC_GETSTATS is a request to have the driver return one or more statistics to the caller in an M_DATA block. The command requires the caller to send an M_DATA block containing an array of maciocstat structures. The structure (as defined in sys/macioctl.h) is shown below:

        struct maciocstat
        {
                unsigned int code;
                unsigned int value;
        }

The user must place a statistic’s code in the code field for each maciocstat structure in the array. The driver will place the respective value for that statistic in the value field. It will then return the filled-in structures back to the caller in the same format received. The codes supported by the driver are enumerated in its header file sys/e1x7.h, and the #define symbols all begin with the string E1X7IOC_STAT_. The code field in the above structure is to be initialized to one of the values defined, in order to get its value returned by the driver. Examine the sys/macioctl.h file for a discussion on the format of the code value. Examine the man page and output from the ifstat(1M) utility to get a description of the value associated with each statistical code. Some codes of particular interest are described here. E1X7IOC_STAT_EADDRHI and E1X7IOC_STAT_EADDRLO will return the upper 4 bytes of the controller’s Hardware Address and the lower 2 bytes of the controller’s Hardware Address, respectively.

M_DATA
See the description of the M_IOCTL messages DLIOCRAW and DL_IOC_HDR_INFO.

M_FLUSH
If the command is a read queue flush, the read queue of the driver is flushed and the message is passed back up stream. If the command is a write queue flush, the write queue of the driver is flushed.

FILES

/dev/e1x7∗
/etc/ifstat.conf/e1x7∗
/usr/include/sys/dlpi.h
/usr/include/sys/e1x7.h
/usr/include/sys/macioctl.h

Museum

Related Articles