NAME

lan − network I/O card access information

SYNOPSIS

#include <netio.h>
int ioctl ( fildes,request,arg );
int fildes,request;
struct fis *arg;

DESCRIPTION

For the remainder of this document, “IEEE802” refers to the IEEE802.2/IEEE802.3 specification. 

The networking terminology used in the remainder of the discussion is defined as follows:

Packet refers to user data with specific Ethernet/IEEE802 header information attached. The header contains the target node’s network station address (destination address), the transmitting node’s network station address (source address), the user’s logged-in addresses (see LOG_TYPE_FIELD and LOG_SSAP below) and specifically for IEEE802, length, dsap and control fields (explained later). 

Network station address or address, for the Ethernet/IEEE802 device is a 6-byte binary value read from/written into arg.value.s for ioctl commands.  For example, the ASCII form “0x00DD00020A50” has the 6-byte binary representation “\000\335\000\002\012\120.” See net_aton(3N) for utilities to convert between the ASCII and binary forms of a network station address. 

Multicast refers to destination addresses normally used to send data to more than one node on a network. See ADD_MULTICAST below.  A multicast address is signified by setting the least significant bit of the first (high order) byte of the address (e.g. “0x00DD0002AD00” is unique, “0x01DD0002AD00” is multicast). 

A broadcast address is a reserved (all bits on) multicast address normally used to send data to ALL nodes on a network. 

Ethernet/IEEE802 device files indicate the drivers for the Ethernet/IEEE802 cards.  There should be one device file for each Ethernet/IEEE802 card connected to a system.  For those network I/O cards which support both Ethernet and IEEE802 simultaneously, there should be two device files, one for each protocol. 

To create an Ethernet/IEEE802 device file, the super-user must use the mknod command:

mknod devicefilename c major minor

The major number indicates the protocol driver to be used. The possible values are:

Protocol	Computer	Interface	Major Number
Ethernet	Series 500	2285A LAN Unit	34
IEEE802	Series 500	2285A LAN Unit	40
Ethernet	Series 500	27125A LAN Card	38
IEEE802	Series 500	27125A LAN Card	39
Ethernet	Series 300	98643A LAN Card	19
IEEE802	Series 300	98643A LAN Card	18

The minor number indicates the select code of the interface card. This is encoded in the format:

0xss0000 where ss is the select code of the interface card (or of the HP-IB card for 2285A Interface Units). 

After creating the device file, the super-user is encouraged to limit read/write access to the driver, because uncontrolled access could lead to throughput degradation and even more serious problems. The suggested access is owner-only read/write (chmod 600 devicefilename). 

A user with the proper access rights can open, close and read status information from an Ethernet/IEEE802 device connected to an active network environment.  After executing required NETCTRL setup operations (explained below), the user can read from and write to the device. The super-user can send additional NETCTRL control information to the device. 

The maximum number of bytes that can be transferred per read or write call is 1500 for Ethernet and 1497 for IEEE802. Requests to write more than the maximum number of bytes will fail.  Due to hardware limitations, the minimum packet size is 46 data bytes for Ethernet and 43 data bytes for IEEE802 (i.e. 64 bytes total for both header and data).  Any write requests of less than the minimum number of bytes will be padded with undefined characters. A read issued to an IEEE802 device file automatically strips these undefined characters. A read issued to an Ethernet device file does not.  If a received packet is too large for a buffer on a posted read, the packet is truncated to fit.

The behavior of Ethernet/IEEE802 device file descriptors across fork/exec calls is similar to the behavior of other file descriptors across these calls. 

The user is cautioned that multiple processes sharing a file descriptor can interfere with each other, especially with respect to the commands LOG_READ_TIMEOUT, LOG_READ_CACHE and LOG_DEST_ADDR, which are described below. 

The user is cautioned that the network driver does not guarantee data delivery; on a successful write, the only guarantee is that the data have been queued for transmission by the network I/O card.  Likewise, there is no guarantee that once transmitted, data are received by the target node. The desired degree of reliability must be coded into the user program.

For an Ethernet/IEEE802 device, ioctl uses these parameters:

fildes File descriptor of the Ethernet/IEEE802 device, which has been opened in read/write mode.  The only applicable option is O_NDELAY. The effects of O_NDELAY are explained under the discussion on LOG_READ_TIMEOUT. For example,
fildes=open("/dev/lan", O_RDWR) or,
fildes=open("/dev/lan", O_RDWR|O_NDELAY)

request Specifies whether a control or status function is to be executed.  The valid request values are:

NETCTRL
Write control information to the device.

NETSTAT
Read statistics/status information from the device.

arg Address of the (fis) data structure.  Arg.reqtype contains the command to be executed.  Each reqtype has a corresponding set of subcommands. The command descriptions are detailed below. 

The following NETCTRL arg.reqtype arguments control the read/write activities of the network device on a per file descriptor basis:

LOG_TYPE_FIELD
NOTE: This command is restricted to the Ethernet protocol, and corresponds to the type field of the Ethernet header. When co-existing on a multi-vendor network or catenet, the user should contact Xerox for authorization to use a given type field. See LOG_DSAP and LOG_SSAP below for the corresponding IEEE802 commands. 
 
Before read and write operations are allowed, a user must log a type field with the driver. This type field is the effective user address for the network connection being established, and must be unique among all open network connections on the same interface card, or an error results.  Only one type field may be declared per (open) file descriptor; once logged, it cannot be changed. 
 
The format of the type field required by ioctl is an integer in the range 0..65535 for those devices supporting only Ethernet, and 2049..65535 for those devices supporting both Ethernet and IEEE802 simultaneously. 
 
LOG_TYPE_FIELD is the first call made in establishing a network connection; the call will fail if memory needed to log the type field is unavailable. 
 
The device header prefixed to the user data by the driver on each write call will contain this type field.  Read calls will return the data portion of only those packets whose type field in the device header matches the logged type field. 
 
The following type fields are reserved by Hewlett-Packard Company for its network operations: 0x8005, 0x0800, 0x0805, 0x0806. 
 
The following parameters must be set prior to calling ioctl:

arg.vtype   = INTEGERTYPE;
arg.value.i = <type field>, range 0..65535 (2049..65535);

LOG_SSAP
NOTE: This command applies only to the IEEE802 protocol. 
 
Before read and write operations are allowed, a user must log a source sap, or ssap, with the driver. This value is the effective user address for the network connection being established, and must be unique among all open network connections on the same interface card, or an error results.  Only one ssap may be declared per (open) file descriptor; once logged, it cannot be changed. 
 
The format of the ssap required by ioctl is an even integer in the range 2..254. 
 
LOG_SSAP is the first call made in establishing a network connection; the call will fail if memory needed to log the ssap is unavailable. 
 
LOG_SSAP sets the destination sap (dsap) value to the ssap value; under normal circumstances, dsap and ssap should remain equal. 
 
The following sap values are reserved by Hewlett-Packard Company for its network operations: 0x06, 0xF8, 0xFC. 
 
The device header prepended to the user data by the driver on each write call will contain this ssap(dsap). Read calls return the data portion of only those received packets whose dsap value in the device header matches the logged ssap value. 
 
The following parameters must be set prior to calling ioctl:

arg.vtype   = INTEGERTYPE;
arg.value.i = <source sap>, even integer in the range 2..254;

LOG_DSAP
NOTE: This command applies only to the IEEE802 protocol. 
 
LOG_DSAP can be called to change the default destination sap (dsap) value set up by LOG_SSAP. The dsap value can be changed any time after the LOG_SSAP call and can be changed any number of times. 
 
The format of the dsap required by ioctl is an integer in the range 0..255. 
 
The device header prepended to the user data by the driver on each write call will contain this dsap.
 
The following parameters must be set prior to calling ioctl :

arg.vtype   = INTEGERTYPE;
arg.value.i = <destination sap>, integer in the range 0..255;

LOG_DEST_ADDR
Before write operations are allowed, a user must log a destination address with the driver.  This address is the network station address of the remote Ethernet/IEEE802 device which is to receive the data.  LOG_DEST_ADDR can be called any time after the LOG_TYPE_FIELD/LOG_SSAP call and can be called any number of times. 
 
A header prepended to the user data on each write call will contain this destination address.
 
The following parameters must be set prior to calling ioctl:

arg.vtype   = <length of arg.value.s>; /* 6 */
arg.value.s = <destination address>;

LOG_READ_TIMEOUT
The default (0) timeout value blocks a user process executing a read until data are available (see LOG_TYPE_FIELD). A positive timeout value causes the read to fail after the specified time has elapsed, if no data are available.  A negative timeout value is treated as the default (0) timeout.  If the O_NDELAY flag is set, the timeout mechanism is overridden and zero (bytes read) is returned immediately if no data are available. 
 
This command is called after logging a user-address (LOG_TYPE_FIELD, LOG_DSAP).
 
NOTE: Due to race conditions caused by asynchronous interrupts, the accuracy of the timer is guaranteed only to the extent that it will not timeout sooner than the given value. 
 
The following parameters must be set prior to calling ioctl:

arg.vtype   = INTEGERTYPE;
arg.value.i = <timeout value in milliseconds>;

LOG_READ_CACHE
By default, only one packet received on an (open) file descriptor is cached, pending a read to the file descriptor.  Subsequent packets received for that file descriptor are discarded.  A one-packet cache is suitable for request/reply protocols.  For other protocols, up to 4 additional packets can be cached, pending read calls. A request for additional packets which would result in more than 4 additional packets being cached is truncated to 4.  This command will fail if requested memory is unavailable, or if called prior to logging a user-address (LOG_SSAP, LOG_TYPE_FIELD).
 
The following parameters must be set prior to calling ioctl:

arg.vtype   = INTEGERTYPE;
arg.value.i = <additional packets to cache>;

LOG_CONTROL
NOTE: This command applies only to the IEEE802 protocol. 
 
The super-user can override the default unnumbered information (UI) control field of the IEEE802 header by using the following values:

The UI value is used for normal communications. 
 
When using the XID control field, any data written to the network device are ignored; an XID request packet is transmitted instead, and any response is returned via the read call. 
 
When using the TEST control field, any data written to the network device cause a TEST packet containing the data to be transmitted; any response is returned via the read call. 

This command is called after logging a destination sap (LOG_DSAP).
 
The following parameters, defined in netio.h, must be set prior to calling ioctl:

arg.vtype   = INTEGERTYPE;
arg.value.i = UI_CONTROL;
         XID_CONTROL;
         TEST_CONTROL;

The following are global super-user-only NETCTRL arg.reqtype arguments which affect the Ethernet/IEEE802 device itself, as opposed to a particular open file descriptor associated with the device. 

RESET_INTERFACE
Resets the Ethernet/IEEE802 device, forcing a complete hardware self-test. No parameters are necessary.  The current multicast state is retained. 
 
NOTE: A reset may destroy any currently active network connections at the local node.

ADD_MULTICAST
Adds a multicast address to the device’s list of accepted multicast addresses.  A received packet is discarded if its multicast address is not in the current list of accepted multicast addresses. A multicast address list can contain up to 16 addresses.
 
The broadcast address is not handled as a typical multicast address and is documented below under ENABLE_BROADCAST/DISABLE_BROADCAST.
 
NOTE: On a Series 500 computer, the card may lose packets when adding to the multicast list.
 
The following parameters must be set prior to calling ioctl:

arg.vtype   = <length of arg.value.s>; /* 6 */
arg.value.s = <multicast address>;

DELETE_MULTICAST
NOTE: Deletion of any HP-special multicast address may prove catastrophic to an active HP network. The HP multicast addresses are: 0x090009000001, 0x090009000002.
 
Removes a specified multicast address from the current list of accepted multicast addresses.
 
The following parameters must be set prior to calling ioctl:

arg.vtype   = <length of arg.value.s>; /* 6 */
arg.value.s = <multicast address>;

ENABLE_BROADCAST
Allows broadcast packets to be received by the network device. No parameters are needed.

DISABLE_BROADCAST
NOTE: The super-user is cautioned that the use of this command may be catastrophic to an active HP network.
 
Disallows broadcast packets from being received by the network device. No parameters are needed.

The following NETCTRL control commands reset specified statistics kept by the Ethernet/IEEE802 device.  No parameters are needed for these. 

RX_FRAME_COUNT
Set to zero the count of packets received without error.

TX_FRAME_COUNT
Set to zero the count of packets transmitted without error.

UNTRANS_FRAMES
Set to zero the count of packets that could not be transmitted due to error.

UNDEL_RX_FRAMES
Set to zero the count of received but undeliverable packets.
 
NOTE: Series 500 computers with 2285A LAN Units combine the statistic UNKNOWN_PROTOCOL with the UNDEL_RX_FRAMES errors. 

RX_BAD_CRC_FRAMES
Set to zero the count of packets received with a bad cyclical redundancy check (CRC).

COLLISIONS
Set to zero the count of transmit collisions. This statistic is kept by Series 300 computers and Series 500 computers with 2285A LAN Units only.

RESET_STATISTICS
Set to zero all statistics counters.
 

The following NETCTRL statistics are not kept on Series 500 computers with the 2285A LAN Unit. 

DEFERRED
Set to zero the count of transmit packets for which the card had to defer to other network traffic before transmitting.

ONE_COLLISION
Set to zero the count of transmit packets for which the card had to retransmit exactly one time due to a collision.

MORE_COLLISIONS
Set to zero the count of transmit packets for which the card had to retransmit between 2 and 15 times due to collisions.

EXCESS_RETRIES
Set to zero the count of transmit packets that could not be transmitted due to excessive collisions (16 or more).

LATE_COLLISIONS
Set to zero the count of transmit packets for which the card detected a late collision.

CARRIER_LOST
Set to zero the count of transmit packets that failed due to loss of the carrier during transmission.

NO_HEARTBEAT
Set to zero the count of transmit packets for which no heartbeat was detected.

ALIGNMENT_ERRORS
Set to zero the count of received packets that were misaligned and had a bad cyclic redundancy check (CRC).
 
NOTE: These packets are also counted in the RX_BAD_CRC_FRAMES count. 

MISSED_FRAMES
Set to zero the count of times that the card missed packet(s) due to lack of resources.

BAD_CONTROL_FIELD
Set to zero the count of IEEE802 packets received with invalid control field values. 

UNKNOWN_PROTOCOL
Set to zero the count of packets dropped because the type field or dsap field referenced an unknown protocol.

The following NETCTRL statistics are only kept by Series 500 computers with the 27125A LAN Card. 

RX_XID
Set to zero the count of XID requests received.

RX_TEST
Set to zero the count of TEST requests received.

RX_SPECIAL_DROPPED
Set to zero the count of XID and TEST requests that were received but not responded to due to lack of resources.

RX_ERRORS
Set to zero the count of packets received with some error.

NO_TX_SPACE
Set to zero the count of times that the card exhausted its transmit buffer space.

LITTLE_RX_SPACE
Set to zero the count of times that the card had little or no receive buffer space available.

ILLEGAL_FRAME_SIZE
Set to zero the count of packets seen by the card that were illegal in size.

 

If request is NETSTAT, statistics are returned. The value returned is the value since the last counter reset. This value applies to the device as opposed to an open file descriptor associated with the device.  The result is returned in arg.value in the appropriate field for its type, which is designated by arg.vtype.  The values for arg.vtype are:
 

- INTEGERTYPE
 
- FLOATTYPE
 
- any non-negative value up to and including 100, which indicates the length of the string in arg.value.s.  The string can contain nulls. 

NOTE: Except where noted below, the result is of type INTEGERTYPE and is contained in arg.value.i.

The valid arg.reqtype arguments for a NETSTAT request are:

FRAME_HEADER
Return the Ethernet/IEEE802 device header associated with the previous read call. 
 
For Ethernet, arg.vtype is 14, and arg.value.s holds the following information:

s[0]..s[5] holds the destination address, as determined by the sender;  this address could be the local Ethernet device’s network station address, or a multicast/broadcast address;

s[6]..s[11] holds the network station address of the sender’s Ethernet device (i.e. source address);

s[12]..s[13] holds the type field (user’s address) as a 16-bit unsigned integer. 

 
For IEEE802, arg.vtype is 17, and arg.value.s holds the following information:

s[0]..s[5] holds the destination address, as determined by the sender;  this address could be the local IEEE802 device’s network station address, or a multicast/broadcast address;

s[6]..s[11] holds the network station address of the sender’s IEEE802 device (i.e. source address);

s[12]..s[13] holds the received packet’s length, including 3 bytes for the ssap/dsap and the control field;

s[14] holds the destination sap value;

s[15] holds the source sap value;

s[16] holds the control field value. 

LOCAL_ADDRESS
Return the address of the local Ethernet/IEEE802 device in arg.value.s. For those devices supporting Ethernet and IEEE802 simultaneously, the Ethernet and IEEE802 addresses are identical.  Arg.vtype is 6 (length of arg.value.s). Any byte of the address may be NULL.

DEVICE_STATUS
Return the current status of the Ethernet/IEEE802 device. Possible return values are INACTIVE, INITIALIZING, ACTIVE and FAILED.

RX_FRAME_COUNT
Return the number of packets received without error.

TX_FRAME_COUNT
Return the number of packets transmitted without error.

UNDEL_RX_FRAMES
Return the number of undeliverable packets received.
 

UNTRANS_FRAMES
Return the number of packets that could not be transmitted due to an error.

RX_BAD_CRC_FRAMES
Return the number of packets received with a bad cyclical redundancy check (CRC).

COLLISIONS
Return the number of transmit attempts which were retransmitted due to collision(s).
 

 

The following NETSTAT statistics are not kept on Series 500 computers with the 2285A LAN Unit. 

MULTICAST_ADDRESSES
Return the current number of accepted multicast addresses.

DEFERRED
Return the number of transmit packets for which the card had to defer to other network traffic before transmitting.

ONE_COLLISION
Return the number of transmit packets that had to be retransmitted exactly once due to a collision.

MORE_COLLISIONS
Return the number of transmit packets that had to be retransmitted between 2 and 15 times due to collisions.

EXCESS_RETRIES
Return the number of packets that were not transmitted due to excessive collisions (16 or more).

LATE_COLLISIONS
Return the number of transmit packets for which the card detected a late collision.

CARRIER_LOST
Return the number of transmit packets that failed due to loss of the carrier during transmission.

NO_HEARTBEAT
Return the number of transmit packets for which no heartbeat was detected.

ALIGNMENT_ERRORS
Return the number of received packets that were misaligned and had a bad cyclic redundancy check (CRC).
 
NOTE: These packets are also reflected in the RX_BAD_CRC_FRAMES count. 

MISSED_FRAMES
Return the number of times that the card missed packet(s) due to lack of resources.

BAD_CONTROL_FIELD
Return the number of IEEE802 packets received with an invalid control field. 

UNKNOWN_PROTOCOL
Return the number of packets dropped because the type field or dsap field referenced an invalid protocol.

 

The following NETSTAT statistics are only kept by the Series 500 computers with the 27125A LAN Card. 

RX_XID
Return the number of XID request packets received.

RX_TEST
Return the number of TEST request packets received.

RX_SPECIAL_DROPPED
Return the number of XID and TEST requests received but not responded to due to lack of resources.

RX_ERRORS
Return the number of packets received with some error.

NO_TX_SPACE
Return the number of times that the card exhausted its transmit buffer space.

LITTLE_RX_SPACE
Return the number of times that the card had little or no receive buffer space available.

TDR Return the last TDR result generated by the network chip on the card. 

ILLEGAL_FRAME_SIZE
Return the number of packets seen by the card that were illegal in size.

DIAGNOSTICS

If an error occurs, the error value is given in errno.

[EIO] Read/write failure (includes timeout conditions). 

[EPERM] A non-super-user attempted to call a super-user-only command. 

[ENOMEM] One of the following:
 
Memory requested by LOG_READ_CACHE is unavailable. 
Memory requested by LOG_TYPE_FIELD is unavailable. 
Memory requested by LOG_SSAP is unavailable. 
Memory requested by a write call is unavailable. 

[EBUSY] An attempt was made to log a user-level address that is already in use. 

[EFBIG] An attempt was made to write more than the maximum bytes or a negative number of bytes. (Series 500 only.) 

[ENXIO] One of the following:
 
An attempt was made to open lan device with bad select code.
Read/write call preceded a LOG_TYPE_FIELD or LOG_SSAP call. 
Write call preceded a LOG_DEST_ADDR call. 

[EINVAL] One of the following:
 
An attempt was made to write more than the maximum bytes or a negative number of bytes. (Series 300 only.)
An attempt was made to open with bad oflag value.
 
LOG_READ_CACHE call preceded a LOG_SSAP or LOG_TYPE_FIELD call. 
 
LOG_READ_TIMEOUT call preceded a LOG_SSAP or LOG_TYPE_FIELD call. 
 
LOG_DSAP call preceded a LOG_SSAP call. 
 
LOG_DEST_ADDR call preceded a LOG_SSAP or LOG_TYPE_FIELD call. 
 
LOG_CONTROL call preceded a LOG_SSAP call. 
 
LOG_TYPE_FIELD call was sent to an IEEE802 device. 
 
LOG_SSAP/LOG_DSAP/LOG_CONTROL call was sent to an Ethernet device. 
 
An attempt was made to change a type_field or ssap (user-level address).
 
Improper address format in an ioctl call involving an address. 
 
Address was/was not in the list of accepted addresses in a call to ADD_MULTICAST/ DELETE_MULTICAST. Already 16 multicast addresses. 
 
Timeout value passed to LOG_READ_TIMEOUT was too large. 
 
Unknown arg.reqtype.
 
Incorrect arg.vtype.
 
Fildes does not specify an active network I/O device. 

[ENOBUFS] An OPEN, READ, WRITE, or IOCTL call could not get enough memory. (Series 300 only.) 

The result of a FRAME_HEADER call is undefined if there has been no previous read.

DEPENDENCIES

Implemented on the Series 300 and 500 only. 

AUTHOR

HP

SEE ALSO

close(2), fcntl(2), ioctl(2), ncontrol(1), npowerup(1), nstatus(1), open(2), read(2), write(2), net_aton(3N), ifconfig(1M). 

DEPENDENCIES

Series 300

Until an internet address has been logged on the interface of interest (see ifconfig(1M)), any write request will return an error and any read request will hang since no data are being received.

Series 500

User-level access to the 2285A Interface device is limited to its supported statistics. 
 
The COLLISIONS statistic is not kept by the Series 500 computers with 27125A LAN cards.
 
Series 500 computers with the 2285A LAN Unit include UNKNOWN_PROTOCOL errors in the UNDEL_RX_FRAMES count. 
 
 
 

Hewlett-Packard Company  —  May 11, 2021