Manpage of DLPI-IOCTL

DLPI-IOCTL

Section: OpenSS7 XNS Networking Devices (4)
Updated: 2008-10-31
Index Return to Main Contents

NAME

dlpi_ioctl - common IO controls for DLPI devices

SYNOPSIS

#include <sys/stropts.h>
#include <sys/dlpi_ioctl.h>

int retval = ioctl(dlpi_stream, cmd, arg);

DESCRIPTION

This manual page description the input-output controls that are associated with the DLPI[1].

IOCTLS

The following are Solaris®-specific input-output controls[2]:

DLIOCRAW

The DLIOCRAW input-output control is used by some DLPI applications, such as snoop(8). The DLIOCRAW command puts the stream into a raw mode, which, upon receive, causes the full MAC-level packet to be sent upstream in an M_DATA(9) message instead of it being transformed into the DL_UNITDATA_IND(7) form normally used for reporting incoming packets in accordance with the DLPI specification[1]. Packet SAP filtering is still performed on Streams that are in raw mode. If a Stream user wants to receive all incoming packets it must also select the appropriate promiscuous modes using the DL_PROMISCON_REQ(7) DLPI primitive. After successfully selecting raw mode, the application is also allowed to send fully formatted packets to the driver as M_DATA(9) messages for transmission. DLIOCRAW takes no arguments. Once enabled, the Stream remains in this mode until closed.

DLIOCNATIVE

Some DLPI providers may be able to represent their link layer using more than on link-layer format. In this case, the default link-layer format may minimize impact to applications, but may not allow truly "native" link-layer headers to be sent or received. DLS users who wish to use the native link-layer format can use DLIOCNATIVE to transition the Stream. DLIOCNATIVE takes no arguments and returns the DLPI MAC type associated with the new link-layer format upon success. Once enabled, the Stream remains in this mode until closed. Note that DLIOCNATIVE does not enable transition between dissimilar DLPI MAC types and (aside from the link-layer format), the new DLPI MAC type is guaranteed to be semantically identical. In particular, the SAP space and addressing format are not affected and the effect of DLIOCNATIVE is only visible when in raw mode, though any subsequent DL_INFO_REQ(7) requests generate response with dl_mac_type set to the native DLPI type.

DLIOCMARGININFO

The DLIOCMARGININFO input-output control takes a 32-bit integer (pointer) argument that is used for each DLS provider to return the margin size it supports. For example, if an Ethernet DLS provider cannot handle packets whose payload section are greater than 1522 bytes, and the maximum SDU size it reports through DL_INFO_ACK(7) is 1500, then the margin size of this DLPI provider is 22 (1522-1500), and the maximum packet size it can handle is 1536 (1522+14, where 14 is the Ethernet header).

DLIOCHDRINFO

DLIOCHDRINFO is used by DLS users that wish to cache link-layer headers for "fast path" operation.

The IP module uses a fast-path mechanism that caches link-layer headers for use with each on-link neighbor. Link-layer interfaces can use the DL_NOTIFY_IND(7) pirmitive with the DL_NOTE_FASTPATH_FLUSH mechanism to notify the IP module that the link-layer header has been modified, and for IP to flush its cached headers. This should cause the module to request new headers form the DLS provider using the DLIOCHDRINFO ioctl.

Note that this input-output control cannot be issued by user-space DLS users.

The argument to the input-output control is a pointer to an extent that, on call, contains a dl_unitdata_req_t(7) structure with the dl_primitive field properly set to DL_UNITDATA_REQ, and the link-layer address of the neighbor contained in the dl_dest_addr_offset and dl_dest_addr_length fields. On successful returns, the DLS provider will return in the memory extent the link-layer header including MAC addresses, LSAP, and any additional headers such as SNAP or VLAN headers necessary to address packets to the destination. The upper layer can use this information for sending messages in raw mode to the upper layer peer.

Issuing this input-output control also places the DLS provider into fast-path mode, if it was not already in fast-path mode.

IOCTLS

The following are HP-UX® input-output controls[3]:

DL_IOC_DRIVER_OPTIONS

This input-output control negotiates options between the DLS Provider and DLS User.

The input-output contorl is valid for in-kernel STREAMS DLPI users only.

The DLS user sets bits to enquire about features. The DLS provider compares the DLS user's request with the DLS provider's capabilties and clears bits corresponding to features requested by the DLS user that the DLS provider cannot support.

The DLS user that negotiates the and header template feature must also reqeust link event notifications using the DL_HP_NOTIFY_EVENT_REQ(7) primitive.

The agument to the input-output control is a pointer to a driver_ops_t structure, defined as follows:

typedef struct {
    uint32_t driver_ops_type;
    uint32_t driver_ops_type_1;
    uint32_t driver_ops_type_2;
} driver_ops_t;

where the members are defined as follows:

driver_ops_type

This member contains features supported by XPORT. The features are bit-wise flags defined as follows:

DRIVER_CKO_IN: Driver support for checksum offload on incoming packets.
DRIVER_CKO_OUT: Driver support for checksum offload on outgoing packets.
DRIVER_CKO_OUT_DF: Driver support for checksum offload on outgoing fragmented packets.
DRIVER_COW: Driver support for copy-on-write.
DRIVER_LFP: Not supported.
DRIVER_LNP: Not supported.
DRIVER_PRI: Reserved for future use.
DRIVER_TRAIN: Driver support for packet trains.
DRIVER_LLC: Reserved for future use.
DRIVER_FASTPATH_IN: Driver support for inbound fastpath.

driver_ops_type_1

This member is reserved. It must be set to zero (0).

driver_ops_type_2

This member is reserved. It must be set to zero (0).

ERRORS

Any of the following errors can be returned by this specific intput-output control in addition to those errors listed in the ioctl(2s) and streamio(7) manual pages:

[EBUSY]: This input-output control is only valid in the DL_IDLE or DL_UNBOUND states. If the message is not in either of these states, the input-output control returns minus one (-1) and sets errno(3) to [EBUSY].
[EOPNOTSUPP]: If the drivers does not support any of the options requested by the transport layer, this error code is returned.
[EINVAL]: If the associated information is invalid, this error code is returned.

DL_IOC_HDR_INFO

This input-output control permits the transportlayer (like TCP/IP) to request a link layer header template from the DLS provider on a per-stream basis, thus avoiding the construction of a header every time that a packet is issued for transmission.

This input-output control is valid only for the in-kernel STREAMS DLS users only.

The header template enables the transport layer to add the link layer header before sending the packet to the DLS provider.

After receiving the DL_IOC_HDR_INFO input-output control, the DLS provider constructs the MAC plus LLC header template with out-of-packet (OOP) data template. The OOP data template can be used by the transport layer to communicate additiona information to the DLS provider.

In response to the input-output control, the DLS provider returns the OOP header and link layer header template. The mblk_t(9) containing the MAC plus LLC and OOP header is the last (third) mblk_t(9) in the M_IOCACK(9) response.

The DLS user must renegotiate the feature and request the DLS provider to build a new header template when it receives a DL_HP_LINK_UP_IND(7) from the DLS provider, because the link state changes may be due to the driver feature changes. These changes can impact the header template.

Note: The Stream must register fr receiving link event notifications in addition, the stream must rebuild the MAC plus LLC link layer header templates on every DL_HP_LINK_UP_IND(7) event.

The M_IOCTL message block that contains DL_IOCL_HDR_INFO is followed by one M_PROTO message block containing the following structure:

typedef struct {
    t_uscalar_t dl_primitive;
    t_uscalar_t dl_dest_addr_length;
    t_uscalar_t dl_dest_addr_offset;
    t_uscalar_t dl_priority;
} dl_unitdata_req_t;

which contains the following members:

dl_primitive: always set to DL_UNITDATA_REQ.
dl_dest_addr_lenth: specifies the length of the DLSAP address of the destination DLS user. If the destination user is implemented using DLPI, this address is the full DLSAP address returned on the DL_BIND_ACK(7) primitive.
dl_dest_addr_offset: specifies the offset from the beginning of the M_PROTO(9) message block where the destination DLSAP address begins.
dl_priority: specifies the pririty value with the supported range for the specified DLSDU.

This input-output control is valid in the DL_IDLE or DL_UNBOUND state.

ERRORS

If the driver does not support fastpath, [EINVAL] is returned.

If the dl_unitdata_req_t(7) structure in the b_cont of the M_IOCTL(9) message block is invalid (e.g. b_cont is NULL), [EINVAL] is returned.

DL_HP_SET_DRV_PARAM_IOCTL

This input-output control is a DLPI defined transparent input-output contorl. It can be use to set the driver parameters. This input-output control provides an interface to set Speed, Duplex mode, auto-negotiation/auto-sense, and Maximum Transfer Unit (MTU). Also, it may be used to reset the MTU of an interface.

Notes:

*

DLPI does not interpret the request of this input-output control: the request is used between the driver's user-space application and the driver.

*

The driver user space application can request DLPI to serialize this requires by setting the DL_HP_SERIALIZE bit in the dl_request element, if another DL_HP_SET_DRV_PARAM_IOCTL input-output control on the same interface is in progress.

*

The drivers can define their own dl_request by using other bits that are not defined by DLPI.

*

If the input-output contol fails, DLPI fress the b_cont mblk_t(9) that contains the data associated with the input-output control.

The input-output control argument is a pointer to a structure, formatted as follows:

typedef struct dl_hp_set_drv_param_ioctl {
    uint32_t dl_request;
    uint32_t dl_speed;
    uint32_t dl_duplex;
    uint32_t dl_autoneg;
    uint32_t dl_mtu;
    uint64_t dl_value1;
    uint64_t dl_value2;
    uint64_t dl_value3;
    uint32_t dl_reserved1[2];
    uint32_t dl_reserved2[2];
} dl_hp_set_drv_param_ioctl_t;

where the structure contains the following members:

dl_request

The request type. The value can be one of the following values:

DL_HP_DRV_SPEED: The dl_speed value is valid.
DL_HP_DRV_DUPLEX: The dl_duplex value is valid.
DL_HP_DRV_AUTONEG: The dl_autoneg value is valid.
DL_HP_DRV_MTU: The dl_mtu value is valid.
DL_HP_DRV_RESET_MTU: Resets the MTU.
DL_HP_VALUE1: The dl_value1 value is valid.
DL_HP_VALUE2: The dl_value2 value is valid.
DL_HP_VALUE3: The dl_value3 value is valid.
DL_HP_RESERVED1: The dl_reserved1[0] value is valid.
DL_HP_RESERVED2: The dl_reserved1[1] value is valid.
DL_HP_RESERVED3: The dl_reserved2[0] value is valid.
DL_HP_RESERVED4: The dl_reserved2[1] value is valid.
DL_HP_SERIALIZE: Requests DLPI to serialize requests.

dl_speed

The speed of the underlying link in Mbits/sec.

dl_duplex

The duplex mode (full or half). This can be one of the following values:

DL_HP_HALF_DUPLEX: The driver is half-duplex.
DL_HP_FULL_DUPLEX: The driver is full-duplex.

dl_autoneg

The auto-negotiation/auto-sense state. This can be one of the following values:

DL_HP_AUTONEG_SENSE_ON: Auto-negotiation/auto-sense is on.
DL_HP_AUTONEG_SENSE_OFF: Auto-negotiation/auto-sense is off.

dl_mtu

The MTU of the interface (in octets).

dl_value1

A 64-bit value for driver extension.

dl_value2

A 64-bit value for driver extension.

dl_value3

A 64-bit value for driver extension.

dl_reserved1

Two 32-bit values for driver extension.

dl_reserved2

Two 32-bit values for driver extension.

This input-output control can only be issued in the DL_IDLE or DL_UNBOUND state.

DL_HP_GET_DRV_PARAM_IOCTL

This input-output control is a DLPI defined transparent input-output control that retrieves the driver parameters.

Note:

*: DLPI does not interpret the request of this input-output control. You must pass this request between the driver's user-space application and the driver.
*: The DL_HP_SERIALIZE bit is ignored for this input-output control.
*: The driver can define its own dl_request by using other bits that are not defined by DLPI.

The input-output control argument is a pointer to a structure, formatted as follows:

typedef struct dl_hp_get_drv_param_ioctl {
    uint32_t dl_request;
    uint32_t dl_speed;
    uint32_t dl_duplex;
    uint32_t dl_autoneg;
    uint32_t dl_mtu;
    uint64_t dl_value1;
    uint64_t dl_value2;
    uint64_t dl_value3;
    uint32_t dl_reserved1[2];
    uint32_t dl_reserved2[2];
} dl_hp_get_drv_param_ioctl_t;

where the structure contains the following members:

dl_request: The request type. This can be an of the values for the corresponding field in the dl_hp_set_drv_param_ioctl defined in the previous section.
dl_speed: The speed of the underlying link in Mbits/sec.
dl_duplex: Duplex mode (full or half). The value is the same as the corresponding field in the dl_hp_set_drv_param_ioctl defined in the previous section.
dl_autoneg: Auto-negotiation/auto-sense. The value is the same as the corresponding field in the dl_hp_set_drv_param_ioctl defined in the previous section.
dl_mtu: The MTU of the interface in octets.
dl_value1: A 64-bit value for driver extension.
dl_value2: A 64-bit value for driver extension.
dl_value3: A 64-bit value for driver extension.
dl_reserved1: Two 32-bit values for driver extension.
dl_reserved2: Two 32-bit values for driver extension.

This input-output control may be invoked while the DLS provider is in the DL_IDLE or DL_UNBOUND states.

DLPI_SET_NOLOOPBACK

This input-ouput control contains an M_IOCTL(9) message block with ioc_cmd set to DLPI_SET_NOLOOPBACK, and the b_cont of the M_IOCTL(9) message block contains a uint32_t value.

When the uint32_t value is set to one (1), the DLS provider does not loopback multicast and broadcast packets for this stream. When the uint32_t value is set to zero (0), the input-output control enables loopback multicast and broadcast packets.

IOCTLS

These are additional Solaris®-specific input-output controls for use with LLC2 and LAPB. These input-output controls are specific to X.25 LAPB[4] and LLC2[5]. These input-output controls are documented in the Solstic X.25 9.2 Developer's Guide[6].

L_SETTUNE, L_GETTUNE

The L_SETTUNE input-output control sets the tunable parameters for a PPA, and is appliable both to LAPB and LLC2. The L_GETTUNE input-output control retrieves the tunable parameters for a PPA, and is appliable both to LAPB and LLC2.

Both the L_SETTUNE and L_GETTUNE input-output controls take an argument that is a pointer to a input-output control tuning structure. For LLC2 PPAs, the llc2_tnioc structure is used. For LAPB PPAs, the lapb_tnioc structure is used. These structures are detailed as follows:

The llc2_tnioc tuning table structure for LLC2 is formatted as follows:

struct llc2_tnioc {
    uchar lli_type;
    uchar lli_spare[3];
    uint lli_ppa;
    llc2tune_t llc2_tune;
};

The members of the llc2_tnioc structure are as follows:

lli_type: specifies the type of the structure: always LI_LLC2TUNE.
lli_spare: provides spare bytes for alignment.
lli_ppa: specifies the Physical Point of Attachment (PPA). The value, 0xff, specifies all PPAs.
llc2_tune: a table of tuning values.

The ll2tune tuning value structure for LLC2 is formatted as follows:

typedef struct llc2tune {
    ushort N2;
    ushort T1;
    ushort Tpf;
    ushort Trej;
    ushort Tbusy;
    ushort Tidle;
    ushort ack_delay;
    ushort notack_max;
    ushort tx_window;
    ushort tx_probe;
    ushort max_I_len;
    ushort xid_window;
    ushort xid_Ndup;
    ushort xid_Tdup;
} llc2tune_t;

The members of the llc2tune structure are as follows:

N2: specifies the maximum number of retries. This is the value ``N2'' from ISO/IEC 8802-2[5].
T1: specifies the acknowlegement timeout in tenths of a second.
Tpf: specifies the P/F-bit cycle retry timeout in tenths of a second.
Trej: specifies the reject retry timeout in tenths of a second.
Tbusy: specifies the remote busy check time in tenths of a second.
Tidle: specifies the idle P/F-bit cycle timeout in tenths of a second.
ack_delay: specifies the RR delay timeout in tenths of a second.
notack_max: specifies the maximum number of unacknowledged received I-frames.
tx_window: specifies the transmit window (remote receive window) if no XID frame is received containing the remote receive window.
tx_probe: specifies the F-bit position before the end of the transmit window.
max_I_len: specifies the maximum I-frame length in octets.
xid_window: specifies the XID window size (receive window).
xid_Ndup: specifies the duplicate MAC XID count (zero (0) implies no test).
xid_Tdup: specifies the duplicate MAC XID timeout in tenths of a second.

The lapb_tnioc tunig table structure for LAPB is formatted as follows:

struct lapb_tnioc {
    uchar lli_type;
    uchar lli_spare[3];
    uint lli_ppa;
    lapbtune_t lapb_tune;
};

The members of the lapb_tnioc structure are as follows:

lli_type: specifies the type of the structure: always LI_LLAPBTUNE.
lli_spare: provides spare bytes for alignment.
lli_ppa: specifies the Physical Point of Attachment (PPA). The value, 0xff, specifies all PPAs.
lapb_tune: a table of tuning values.

The lapb_tune tuning value structure for LAPB is formatted as follows:

typedef struct lapb_tune {
    ushort N2;
    ushort T1;
    ushort Tpf;
    ushort Trej;
    ushort Tbusy;
    ushort Tidle;
    ushort ack_delay;
    ushort notack_max;
    ushort tx_window;
    ushort tx_probe;
    ushort max_I_len;
    ushort llconform;
};

The members of the lapb_tune structure are as follows:

N2: specifies the maximum number of retries. This is the value ``N2'' from ISO/IEC 8208[4].
T1: specifies the acknowlegement timeout in tenths of a second.
Tpf: specifies the P/F-bit cycle retry timeout in tenths of a second.
Trej: specifies the reject retry timeout in tenths of a second.
Tbusy: specifies the remote busy check time in tenths of a second.
Tidle: specifies the idle P/F-bit cycle timeout in tenths of a second.
ack_delay: specifies the RR delay timeout in tenths of a second.
notack_max: specifies the maximum number of unacknowledged received I-frames.
tx_window: specifies the transmit window (remote receive window) if no XID frame is received containing the remote receive window.
tx_probe: specifies the F-bit position before the end of the transmit window.
max_I_len: specifies the maximum I-frame length in octets.
llconform: specifies LAPB conformance.

L_GETGSTATS

This input-output control reads the global layer two statistics for the LAPB driver, and is only applicable to LAPB. The input-output control argument is a pointer to a lapb_gstioc structure, formatted as follows:

#define frames_tx    0
#define frames_rx    1
#define sabme_tx     2
#define sabme_rx     3
#define bytes_tx     4
#define bytes_rx     5
#define globstatmax  6
struct lapb_gstioc {
    uint8_t lli_type;
    uint8_t lli_spare[3];
    uint32_t lapbgstats[globstatmax];
};

The lapb_gstioc structure contains the following members:

lli_type

the type of the structure: always LI_GSTATS.

lli_spare

spare bytes for alignment.

lapbgstats

a global statistics array of globstatmax uint32_t elements. These elements are defined as follows:

frames_tx: contains a count of the number of frames transmitted.
frames_rx: contains a count of the number of frames received.
sabme_tx: contains a count of the number of SABM/SABME/SM frames transmitted.
sabme_rx: contains a count of the number of SABM/SABME/SM frames received.
bytes_tx: contains a count of the number of bytes (octets) transmitted.
bytes_rx: contains a count of the number of bytes (octets) received.

L_GETSTATS

This input-output control reads the per-link statistics, and is only applicable to LAPB. The input-output control takes an argument that is a pointer to a lapb_stioc structure, formatted as follows:

struct lapb_stioc {
    uint8_t lli_type;
    uint8_t lli_spare[3];
    uint32_t lli_ppa;
    lapbstats_t lli_stats;
};

The lapb_stioc structure contains the following members:

lli_type: specifies the type of the structure: always LI_STATS.
lli_spare: specifies spare bytes for alignment.
lli_ppa: specifies the Physical Point of Attachment (PPA) to which the statistics apply.
lli_stats: specifies a table of statistics.

The lli_stats member contains a lapb2_stats structure, formatted as follows:

#define lapbstatmax    49
typedef struct lapb2_stats {
    uint32_t lapbmonarray[lapbstatmax];
} lapbstats_t;
#define tx_ign          0
#define rx_badlen       1
#define rx_unknown      2
#define t1_exp          3
#define t4_exp          4
#define t4_n2_exp       5
#define RR_rx_cmd       6
#define RR_rx_rsp       7
#define RR_tx_cmd       8
#define RR_tx_rsp       9
#define RR_tx_cmd_p    10
#define RNR_rx_cmd     11
#define RNR_rx_rsp     12
#define RNR_tx_cmd     13
#define RNR_tx_rsp     14
#define RNR_tx_cmd_p   15
#define REJ_rx_cmd     16
#define REJ_rx_rsp     17
#define REJ_tx_cmd     18
#define REJ_tx_rsp     19
#define REJ_tx_cmd_p   20
#define SABME_rx_cmd   21
#define SABME_tx_cmd   22
#define DISC_rx_cmd    23
#define DISC_tx_cmd    24
#define UA_rx_rsp      25
#define UA_tx_rsp      26
#define DM_rx_rsp      27
#define DM_tx_rsp      28
#define I_rx_cmd       29
#define I_tx_cmd       30
#define FRMR_rx_rsp    31
#define FRMR_tx_rsp    32
#define tx_rtr         33
#define rx_bad         34
#define rx_dud         35
#define rx_ign         36
#define I_rx_rsp       37
#define I_tx_rsp       38
#define UI_rx_cmd      39
#define UI_tx_cmd      40
#define XID_rx_cmd     41
#define XID_rx_rsp     42
#define XID_tx_cmd     43
#define XID_tx_rsp     44
#define TEXT_rx_cmd    45
#define TEXT_rx_rsp    46
#define TEXT_tx_cmd    47
#define TEXT_tx_rsp    48

The lapb2_stats structure contains an array with the following elements, each of which contains a count of the associated event:

tx_ign: tranmissions ignored and not set.
rx_badlen: bad length frames received.
rx_unknown: unknown frames received.
t1_exp: expirations of the T1 timer.
t4_exp: expirations of the T4 timer.
t4_n2_exp: expirations of the T4 timer after N2 retries.
RR_rx_cmd: RR commands received.
RR_rx_rsp: RR responses received.
RR_tx_cmd: RR commands transmitted.
RR_tx_rsp: RR responses transmitted.
RR_tx_cmd_p: RR commands with the P-bit set transmitted.
RNR_rx_cmd: RNR command S-frames received.
RNR_rx_rsp: RNR response S-frames received.
RNR_tx_cmd: RNR command S-frames transmitted.
RNR_tx_rsp: RNR response S-frames transmitted.
RNR_tx_cmd_p: RNR command S-frames with the P-bit set transmitted.
REJ_rx_cmd: REJ command S-frames received.
REJ_rx_rsp: REJ response S-frames received.
REJ_tx_cmd: REJ command S-frames transmitted.
REJ_tx_rsp: REJ response S-frames transmitted.
REJ_tx_cmd_p: REJ command S-frames with the P-bit set transmitted.
SABME_rx_cmd: SABM/SABME/SM command U-frames received.
SABME_tx_cmd: SABM/SABME/SM command U-frames transmitted.
DISC_rx_cmd: DISC command frames received.
DISC_tx_cmd: DISC command frames transmitted.
UA_rx_rsp: UA response frames received.
UA_tx_rsp: UA response frames transmitted.
DM_rx_rsp: DM response frames received.
DM_tx_rsp: DM response frames transmitted.
I_rx_cmd: command I-frames received.
I_tx_cmd: command I-frames transmitted.
FRMR_rx_rsp: FRMR response frames received.
FRMR_tx_rsp: FRMR response frames transmitted.
tx_rtr: retransmitted frames.
rx_bad: erroneous frames received.
rx_dud: frames received and discarded.
rx_ign: frames received and ignored.
I_rx_rsp: response I-frames received.
I_tx_rsp: command I-frames received.
UI_rx_cmd: command U-frames received.
UI_tx_cmd: command U-frames transmitted.
XID_rx_cmd: command XID frames received.
XID_rx_rsp: response XID frames received.
XID_tx_cmd: command XID frames transmitted.
XID_tx_rsp: response XID frames transmitted.
TEXT_rx_cmd: command TEST frames received.
TEXT_rx_rsp: response TEST frames received.
TEXT_tx_cmd: command TEST frames transmitted.
TEXT_tx_rsp: response TEST frames transmitted.

L_ZEROSTATS

This input-output control zeros the per-link statistics, and is only applicable to LAPB. The argument to the input-output control is a pointer to a ll_hdioc structure, formatted as follows:

struct ll_hdioc {
    uint8_t lli_type;
    uint8_t lli_spare[3];
    uint32_t lli_ppa;
};

The ll_hdioc structure contains the following members:

lli_type: specifies the structure type: always LI_PLAIN.
lli_spare: specifies spare bytes for alignment.
lli_ppa: specifies the Physical Point of Attachment (PPA) of the link for which to reset (zero) statistics. When specified as 0xff, it specifies that all PPAs are to have their statistics reset (zeroed).

L_GETPPA, L_SETPPA

The L_SETPPA input-output control sets the PPA information associated with the indexed linked Stream, and is only applicable to LAPB. The L_GETPPA input-output control retrieves the PPA information associated with the indexed linked Stream, and is only applicable to LAPB.

These input-output controls are used to initialize (L_SETPPA) and interrogate (L_GETPPA) the configuration of Streams linked beneath the multiplexing driver. Once a Stream has been linked beneath the multiplexing driver using the I_LINK(7) or I_PLINK(7) STREAMS input-output controls, the linked Stream is assigned a default link class, SLP priority, and PPA. If the management program linking the Stream wishes to assign a non-default link class, SLP priority, or PPA, the L_SETPPA input-output control must be issued.

The argument to either input-output control is a pointer to a ll_snioc structure, formatted as follows:

struct ll_snioc {
    uint8_t lli_type;
    uint8_t lli_class;
    uint16_t lli_slp_pri;
    uint32_t lli_ppa;
    uint32_t lli_index;
};

The ll_snioc structure contains the following members:

lli_type

specifies the type of the structure: always LI_SPPA.

lli_class

specifies the class of the PPA, that is, the type of the link. This can be LAPB-DTE, LAPB-DCE or Extended (LLC2). This field can have one of the following values:

LC_LLC2: specifies that the link is an LLC2 link.
LC_LAPBDTE: specifies that the link is a LAPB-DTE link.
LC_LAPBDCE: specifies that the link is a LAPB-DCE link.

lli_slp_pri

specifies the SLP priority. This the priority of this SLP link within a MLP aggregate.

lli_ppa

specifies the Physical Point of Attachment (PPA) or the subnetwork identification character.

lli_index

specifies the link index. This is the multiplexor identification (muxid) returned from the I_LINK(7) or I_PLINK(7) input-output control when the serial driver was linked beneath the DLPI multiplexing driver.

When this input-ouput control is attempted on a device that is not in an attached state (e.g. DL_UNATTACHED), the input-output control will indicate the error code [ENODEV].

When the PPA specified in a L_SETPPA input-output control is already in use by another device, the input-output control will indicate the error code [EBUSY].

When the index specified in a L_SETPPA input-output control is not asociated with a linked Stream, the input-output control will indicate the error code, [ENODEV].

It may require privilege to set or retrieve the PPA information associated with a Stream other than the one for which the input-output control was issued (that is, the lower multiplex Stream attached to the open upper multiplex Stream). When the caller does not have sufficient priviledge to perform the operation, [EPERM] is returned.

W_SETTUNE

This input-output control sets wanmod tunable parameters for a PPA, and is only applicable to specific WAN hardware devices. The argument to the input-output control is a pointer to a wan_tnioc structure formatted as follows:

struct wan_tnioc {
    uint8_t w_type;
    uint8_t w_spare[3];
    uint32_t w_snid;
    wantune_t wan_tune;
};

The wan_tnioc structure contains the following members:

w_type: specifies the structure type: always WAN_TUNE.
w_spare: specifies spare bytes for alignment.
w_snid: specifies the single character subnetwork identifier. The character ``*'' indicates all subnetworks.
wan_tune: specifies a table of tuning values.

The wan_tune member is a table of tuning values. It comprises a wantune structure, formatted as follows:

struct WAN_hddef {
    uint16_t WAN_maxframe;
    int32_t WAN_baud;
    uint16_t WAN_interface;
};
typedef struct wantune {
    uint16_t WAN_options;
    struct WAN_hddef WAN_hd;
} wantune_t;

IOCTLS

These are DLPI input-output controls from AIX:

DL_PKT_FORMAT

The DL_PKT_FORMAT input-output control permits the DLS user to control in the format of the link-layer headers included in the control and data portions of requested and indicated DLPI connectionless packets. It is a transparent input-output control and takes a single argument that may contain one of the following values:

NS_PROTO

This is the default value on newly opened Streams. Strip link-layer headers, but not Sub-Network Access Protocol (SNAP) headers. Medium Access Control (MAC) and Logical Link Control (LLC) are included in the DL_UNITDATA_REQ(7) and DL_UNITDATA_IND(7) control block, and the data portion of the message contains only data. The NS_PROTO header does not include SNAP: that is, any SNAP header is considered part of the data and included in the data. Destination addresses are formatted as the MAC[+DSAP] address and source addresses are formatted as the MAC+SSAP+DSAP+CTRL.

: For the DL_UNITDATA_REQ(7) primitive, the DLPI user must provide the destination address and an optional destination service access point (DSAP) in the M_PROTO(9) control block. If the DLS User does not specify the DSAP, the LSAP specified at bind time is used.

NS_PROTO_SNAP

Strip link-layer headers, including Sub-Network Access Protocol (SNAP) headers. Medium Access Control (MAC) and Logical Link Control (LLC) are included in the DL_UNITDATA_REQ(7) and DL_UNITDATA_IND(7) control block, and the data portion of the message contains only data. The NS_PROTO_SNAP header includes SNAP: that is, any SNAP header is considered part of the link-layer headers. Destination addresses are formatted as the MAC[+DSAP] address and source addresses are formatted as the MAC+SSAP+DSAP+CTRL+[SNAP].

: For the DL_UNITDATA_REQ(7) primitive, the DLPI user must provide the destination address and an optional destination service access point (DSAP) in the M_PROTO(9) control block. If the DLS User does not specify the DSAP, the LSAP specified at bind time is used.

NS_PROTO_DONTCARE

The driver does not place addresses in the DL_UNITDATA_IND(7) message, but addresses are still required in the DL_UNITDATA_REQ(7) primitive from the DLS user.

NS_PROTO_DL_COMPAT

Addresses are compatible with AIX 3.2.5. Addresses are included both in DL_UNITDATA_IND(7) and DL_UNITDATA_REQ(7) primitives. Both destination and source addresses are formatted as MAC+DSAP[+SNAP].

NS_INCLUDE_LLC

The Logical Link Control (LLC) portion of the link-layer header is treated as data. Only the MAC portion of the address is included in the control block and the LLC headers (DSAP+SSAP+CTRL[+SNAP]) is included in the data. Both destination and source addresses are formatted as simply the MAC address.

: For the DL_UNITDATA_REQ(7) primitive, the DLS user must provide the destination address and an optional DSAP in the control block. If the DLS User does not specify the DSAP, the LSAP specified at bind time is used.

NS_INCLUDE_MAC

Both the MAC and the LLC link-layer headers are considered data and are placed in the data portion of the message. Thus the DLS user must have knowledge of the MAC header and LLC architecture for a specific interface to retrieve the MAC header and LLC from the data portion of th emessage. This format sets the Stream to raw mode, which does not process incoming or outgoing messages.

For the DL_UNITDATA_REQ(7) primitive, the DLS user must provide the destination address and an optional DSAP in the control block. If the user does not specify the DSAP, the DSAP sepcified at bind time is used.

Downstream messages do not require the DL_UNITDATA_REQ(7) header and must be received as M_DATA(9) messages, see DL_DATA_REQ(7). Downstream messages must contain a completed MAC header that will be copied to the medium without further translation.

DL_ROUTE

The DL_ROUTE input-output control disables the source routing on the current Stream, queries dynamic route discovery for a source route, or statically assigns a source route to this Stream. The input-output control is only valid when the DLS Provider is in the DL_IDLE state.

The argument is variable length and this input-output control can only be invoked using the I_STR(7) STREAMS input-output control. The length of the argument is interpreted as follows:

*: If the argument is of zero length, no source route is used on outgoing frames.
*: If the argument length is equal to the length of the MAC address for the current medium, the dynamic route discovery algorithm is used to obtain the source route for the address specified in the argument. The MAC address is replaced with the source route on return from the input-output control.
*: Otherwise, the argument is assumed to contain an address of the form MAC+SRTE, and the SRTE (source route) portion is used as the source route for this stream in all communications.

DL_TUNE_LLC

Provides a mechanism whereby the DLS user may change tunable default LLC parameters. The argument must point to a llctune_t data structure.

The flags field is examined to determine which, if any, parameters should be changed. Each bit in the flags field corresponds to a similarly named field in the llctune_t structure. If the bit is set, the corresponding parameter is valid and set to the value in the llctune_t structure. Only the current Stream is affected, and changes are discarded when the Stream is closed.

If the F_LLC_SET flag is set and the user has root authority, the altered parameters are saved as the new default parameters for all new streams.

This command returns as its argument an update of the current tunable parameters. To query the tunables, issue the DL_TUNE_LLC with the flags field set to zero. This will alter no parameters and return the current tunable values.

DL_ZERO_STATS

The DL_ZERO_STATS input-output control resets the statistics counters to zero. The driver maintains two independent sets of statistics, one for each Stream (local) and another that is the cumulative statistics for all Streams (global). This input-output control command access a simple boolean argument. If the argument is true (non-zero), the global statistics are zeroed; if false (zero), the local statistics are zeroed.

This input-output control can be issued as a transparent ioctl. The argument is the boolean flag.

DL_SET_REMADDR

The DL_SET_REMADDR allows the DLS user to perform an XID/TEST exchange on an LLC (or point-to-multipoint) connection-oriented Stream while still in the DL_IDLE state.

The DLS provider uses both the source (remote) address and the dl_sap from the DL_BIND_REQ(7) and DL_BIND_ACK(7) to determine where to route incoming messages for connection-oriented streams. The remote address is ordinarily specified in the DL_CONNECT_REQ(7) primitive. If the DLS user needs to exchange XID or TEST messages before connecting to the remote station, DL_SET_REMADDR must be used.

The argument to this input-output control is the MAC address of the remote station.

IOCTLS

These are generic Data Link control (GDLC) input-output controls from AIX[7].

DLC_ENABLE_SAP

This input-output control enables a service access point (SAP).

DLC_DISABLE_SAP

This input-output control disables a service access point (SAP).

A service access point (SAP) identifies a particular user service that sends and receives a specific class of data. This user service allows different classes of data to be routed separately to their corresponding service handlers. Those DLCs that support multiple concurrent SAPs have addresses knowns as detination SAP and source SAP embedded in thier packet headers. DLCs that can only support a single SAP do no need or use SAP addressing, but still have the concept of enabling the one SAP. In general, SAP is enabled for each DLC on each port.

Most SAP address values are defined by IEEE standardized network-management etitites or user-defined values are specified. Some of the common SAP addresses are:

null SAP (0x00): Provides some ability to respond to remote nodes even when no SAP has been enabled. This SAP supports only connectionless service and response only to exchange identification (XID) and TEST PDUs.
SNAP path control (0x04): Denotes the default individual SAP address used by Systems Network Architecutre (SNA) nodes.
PC network NETBIOS (0xF0): Used for all DLC communication that is driven by Network Basic I/O System (NETBIOS) emulation.
discovery SAP (0xFC): Use dby the local area network (LAN) name-discovery services.
global SAP (0xFF): Identifies all active SAPs.

DLC_START_LS

This input-output control starts a link station (LS) on a particular SAP as a initiator or responder.

A link station (LS) identifies an attachment between two nodes for a particular SAP pair. This attachment can operate as a connectionless service (datagram) or connection-oriented service (fully sequenced data transfer with error recovery). In general, one LS is started for each remote attachment.

DLC_HALT_LS

This input-output control halts a link station (LS) for a particular SAP.

DLC_TRACE

This input-output control traces a link station's activity for short or long activities.

To trace a link, line data and special events (such as station activation, termination, and timeouts) can be logged in the generic trace facility for each LS. This function helps determine the cause of certain communications attachment problems. The GDLC user can select either short or long entries to be traced.

Short entries consist of up to 80 bytes of line data, while long entries allow full packets of data to be traced.

Tracing can be activated with an LS is started, or it can be dynamically activated or terminated at any time afterward.

DLC_TEST

This input-output control contacts a remote station for a particular local link station.

To test an attachment between two stations, instruct an LS to send a test packet from the local station. This packet is echoed back from the remote station if the attachment is operating correctly.

Some data links are limited in their support of this function due to protool constraints. Synchronous data link contrl (SDLC), for example, only generates the test packet from the host or primary station. Most other protocols, however, allow test packets to be initiated from either station.

DLC_ALTER

This input-output control alters a link station's configuration parameters.

DLC_QUERY_SAP

This input-output control queries statistics associated with a particular SAP.

Both SAP and LS statistics can be queried by a GDLC user. The statistics for a SAP consist of the current SAP state and information about the device handler.

DLC_QUERY_LS

This input-output control queries statistics associated with a particular LS.

Both SAP and LS statistics can be queried by a GDLC user. LS statistics consist of the current station states and various reliability, availability, and servicability counters that monitor the activity of the station from the time it is started.

DLC_ENTER_LBUSY

This input-output control causes the link station to enter the local busy mode.

When an LS operates in a connection-oriented mode, it needs to stop the remote station's sending of information packets for reasons such as resource outgage. Notification can then be sent to the remote station to cause the local ststaion to enter local-busy mode. This is performed with an RNR Supervisory Frame under LAPB[4], LLC2[5], LAPD[8], and LAPF[9]. Only sequence information packets (Information Frames) are halted with local-busy mode. All other types of data (e.g. Unnumbered Information Frames) are unaffected.

DLC_EXIT_LBUSY

This input-output control causes the link station to exit the local busy mode.

Once resources become available, the local station notifies the remote that it is no longer busy and that information packets can flow again. This is performed with an RR Supervisory Frame under LAPB[4], LLC2[5], LAPD[8], and LAPF[9]. Only sequence information packets (Information Frames) are halted with local-busy mode. All other types of data (e.g. Unnumbered Information Frames) are unaffected.

DLC_ENTER_SHOLD

This input-output control enters short hold mode on a particular link station.

User the short-hold mode of operation when operating over data networks with the following characteristics:

*: short call setup times; and,
*: tariff structure that specifies a relatively small fee for the call setup compared to the charge for connect time.

During short-hold mode, an attachment between two stations is maintained only to transfer data available between the two stations. When no data is sent, the attchment is cleared after a specified time-out period and is only reestablished to trasnfer new data.

DLC_EXIT_SHOLD

This input-output control exits short hold mode on a particular link station.

DLC_GET_EXCP

This input-output control returns asyncrhonous exception notifications to the application user. Note: This input-output control subroutine operation is not used by the kernel user since all exception conditions are passed to the kenrel user by way of their exception handler.

DLC_ADD_GRP

This input-output control adds a group or multicast receive address to a port.

DLC_ADD_FUNC_ADDR

This input-output control adds a group or multicast receive functional address to a port.

DLC_DEL_FUNC_ADDR

This input-output control removes a group or multicast receive function address from a port.

DLC_DEL_GRP

This input-output control removes a group or multicast address from a port.

IOCINFO

This input-output control returns a structure that describes the GDLC device manager.

IOCTLS

These are DLPI input-output controls from SVR4.2MP and UnixWare 2:

DLIOCSMIB

Allows a privileged process to initialize the values in the MIB (the DL_mib_t structure). A process cannot use this input-output control to change the ifPhyAddress, the ifDescrLen, or the text of the description fields.

DLIOCGENADDR

Returns the Ethernet address in network order.

DLIOCGLPCFLG

Returns the state of the local packet copy flags in the ioc_rval of the iocblk(9) structure. The local copy flag determines if packets looped back by the driver should also be sent to the network. A non-zero value indicates that frames should also be sent to the network after being looped back. The default value of this flag is zero.

DLIOCSLPCFLG

Allows a privileged process to set the local packet copy flag, causing all packets looped back by the driver to be sent to the network as well.

DLIOCGPROMISC

Returns the value of the promiscuous flag in the ioc_rval of the iocblk(9) structure. A non-zero value indicates that the Ethernet interface will receive all frames on the network. The default value of this flag is zero.

DLIOCSPROMISC

Allows a privileged process to toggle the current state of the promiscuous flag. When the flag is set, the driver captures all frames from the network. Processes that are bound to a promiscuous SAP, or to a SAP that matches the type field of the received frame, receive a copy of the frame.

DLIOCGETMULTI

Returns a list of multicast addresses (if it exists).

DLIOCADDMULTI

Allows a privileged process to add a new multicast address and enable its reception. A 6-byte buffer pointing to the multicast address must be passed as the parameter.

DLIOCDELMULTI

Allows a privileged process to delete a multicast address by passing a 6-byte multicast address as the parameter.

DLIOCRAWMODE

Allows a Token Ring privileged process to identify itself as a raw upstream module. This allows an upstream module to transmit a valid MAC frame using a DL_UNITDATA_REQ(7) or DL_UNITDATA_IND(7) primitive.

DLIOCLLC2MODE

Allows a privileged process to identify itself as an llc2 upstream module. This allows an upstream module to transmit a valid LLC Type 2 (connection oriented) frame via a DL_UNITDATA_REQ(7) or DL_UNITDATA_IND(7) message.

Some additional IOCTLS from the UnixWare Intro(D7dlpi) manual page.

DLIOCCSMACDMODE

Switch SAP type to RAW.

DLIOCDISABLE

Disable controller.

DLIOCENABLE

Enable controller.

DLIOCGMIB

Get MIB statistics (DL_mib_t).

DLIOCRESET

Reset controller.

DLIOCSENADDR

Set ethernet address.

DLGADDR

Return ethernet (MAC) address.

DLGBROAD

Get broadcast address.

DLSLLC2

Toggle LLC2 mode (Token-Ring adapters).

DLSRAW

Toggle RAW mode (Token-Ring adapters).

IOCTL

UnixWare 7 input-output controls:

DLPID_REGISTER

An input-output control that the UnixWare dlpid(1M) daemon uses to register with the module before linking it with an MDI driver. It also handles the I_LINK(7), I_PLINK(7), I_UNLINK(7), I_PUNLINK(7), input-output control commands described in streamio(7).

The DLPI driver intercepts and responds to the following MACIOC input-output control commands.

MACIOC_CLRMCA

MACIOC_DIAG

MACIOC_GETADDR

Return MAC address.

MACIOC_GETIFSTAT

MACIOC_GETRADDR

Return factory MAC address.

MACIOC_GETSTAT

Return statistics.

MACIOC_LOCALSTAT

MACIOC_PROMISC

Enable promiscuous mode.

MACIOC_SETADDR

Set MAC address.

MACIOC_UNITSEL

The DLPI driver passes all other MACIOC input-output control commands to the MDI driver beneath it. Other MACIOC input-output control commands are as follows:

MACIOC_CLRSTAT

Clear statistics structure.

MACIOC_DELALLMCA

Stop receiving multicast frames.

MACIOC_DELMCA

Stop receiving MAC frames.

MACIOC_GETADDR

Return MAC address.

MACIOC_GETMCA

Return active multicast addresses.

MACIOC_GETMCSIZ

Return multicast address table size.

MACIOC_GETRADDR

Return factory MAC address.

MACIOC_GETSTAT

Return statistics.

MACIOC_PROMISC

Enable promiscuous mode.

MACIOC_SETADDR

Set MAC address.

MACIOC_SETALLMCA

Deliver multicast frames.

MACIOC_SETMCA

Receive MAC frames.

MACIOC_SETSTAT

Modify MIB attributes.

BUGS

The DLPI input-output controls implementations have no known bugs.

COMPATIBILITY

---: Megatbits per second was an etremely bad choice for the units of the dl_speed field.
---: The AIX®-specific DL_SET_REMADDR input-output control is unnecessary with DLPI Revision 2.0.0[1]. Under DLPI Revision 2.0.0, the DL_XID_REQ(7), DL_XID_IND(7), DL_TEST_REQ(7), and DL_TEST_IND(7) primitives contain the destination address and source address, and are valid in both the DL_IDLE and DL_DATAXFER states. This is all that is necessary.

CONFORMANCE

This interface conforms to DLPI Revision 2[1]. Solaris® and AIX® documentation.

HISTORY

The Data Link Provider Interface first appeared in SVR 4[10].

REFERENCES

[1]: DLPI, Data Link Provider Interface (DLPI) Specification, Revision 2.0.0, Draft 2, August 20, 1991, (Parsippany, New Jersey), UNIX. International,Inc., UNIX International Press. <http://www.openss7.org/doc/dlpi.pdf>
[2]: Solaris® 11, Solaris 11 Docmentation, 2008, (Santa Clara, California), Sun Microsystems, Inc., Sun. <http://docs.sun.com/>
[3]: HP-UX DLPI, HP DLPI Programmer's Guide -- HP-UX 11i v3, February 2007, (Palo Alto, California), Hewlett-Packard Development Company L.P., HP. [Part No: 5991-7498] <http://docs.hp.com/>
[4]: ISO/IEC 8208:2000, Information Technology --- Data Communications --- X.25 Packet Layer Protocol For Data Terminal Equipment, Fourth Edition, November 1, 2000, (Geneva), ISO, International Organization for Standardization. <http://www.iso.org/>
[5]: ANSI/IEEE Std. 802.2-1998 [ISO/IEC 8802-2:1998], IEEE Standard for Information Technology --- Telecommunications and Information Exchange Between Systems --- Local and Metropolitan Area Networks --- Specific Requirements --- Part 2: Logical Link Control, May 7, 1998, (New York), ANSI/IEEE, IEEE Computer Society. [ISBN 1-55937-959-6]
[6]: Solstice® X.25, Solstice X.25 9.2 Developer's Guide, October 1999, (Palo Alto, California), Sun Microsystems, Inc., Sun. [Part No: 806-1235-10] <http://docs-pdf.sun.com/>
[7]: AIX Version 6.1, AIX Version 6.1 Technical Reference: Communications, Volume 1, First Edition, November 2007, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. [SC23-6610-00] <http://publib.boulder.ibm.com/>
[8]: ITU-T Recommendation Q.921, Digital Subscriber Signalling System No. 1 --- ISDN User-Network Interface --- Data Link Layer Specification, March 1993, (Geneva), ITU, ITU-T Telecommunication Standardization Sector of ITU. (Previously "CCITT Recommendation") <http://www.itu.int/rec/T-REC-Q.921/>
[9]: ITU-T Recommendation Q.922, Digital Subscriber Signalling System No. 1 --- Data Link Layer --- ISDN Data Link Layer Specification for Frame Mode Bearer Services, February 1992, (Geneva), ITU, ITU-T Telecommunication Standardization Sector of ITU. (Previously "CCITT Recommendation") <http://www.itu.int/rec/T-REC-Q.922/>
[10]: SVR 4, UNIX® System V Release 4 Programmer's Manual, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.