Chapter 11 DLPI Reference

The DLPI message primitives and Sun specific ioctls described in this chapter act as an interface to LAPB, or to both LAPB and LLC2. LAPB provides a connection-oriented service only, so the connectionless primitives cannot be used with LAPB. For information on ioctls exclusive to LLC2, refer to the llc2 man page. LLC2 provides both connection-oriented and connectionless services. The connectionless service is generally referred to as LLC1 and is not a supported part of the Solstice X.25 product.

The primitives and ioctls are described in alphabetical order. Refer to the summary tables at the start of each section for functional groupings.

The header files used by the message primitives and ioctls described in this chapter are contained in the /usr/include/netdlc, /usr/include/netx25 and /usr/include/sys directories.

All of the message primitives listed conform to the DLPI standard. They must be used with the getmsg(2) and putmsg(2) system calls. For more information, see the STREAM's Programmer Guide.

11.1 DLPI Specific Message Primitives

These message primitives are related to local management services:

Table 11-1 Local Management Service Message Primitives

name	summary
DL_INFO_REQ	requests information
DL_INFO_ACK	acknowledges a request for information
DL_ATTACH_REQ	identifies the physical link to attach to
DL_BIND_ACK	acknowledges a bind request
DL_DETACH_REQ	identifies the physical link to detach from
DL_BIND_REQ	specifies whether connectionless or connection oriented mode is to be use, and supplies the LSAP to bind to
DL_UNBIND_REQ	requests an unbind
DL_OK_ACK	positively acknowledges a previous primitive
DL_ERROR_ACK	negatively acknowledges a previous primitive

These message primitives are related to connection mode services:

Table 11-2 Connection Mode Service Message Primitives

name	summary
DL_CONNECT_REQ	establishes a connection
DL_CONNECT_IND	indicates that a remote user wants to establish a connection
DL_CONNECT_RES	accepts a connect request from a remote user
DL_CONNECT_CON	acknowledges a connect request
DL_TOKEN_REQ	determines the token associated with a stream (LLC2 only)
DL_TOKEN_ACK	acknowledges a token (LLC2 only)

These message primitives are related to connection release:

Table 11-3 Connection Release Message Primitives

name	summary
DL_DISCONNECT_REQ	disconnects a connection
DL_DISCONNECT_IND	informs that a connection has been disconnected or not established

The following non-DLPI message primitive is related to data transfer:

Table 11-4 Data Transfer Message Primitive

name	summary
M_DATA	carries data within a stream, and between a stream and a user process

These message primitives are related to connection resynchronization.

Table 11-5 Data Resynchronization Message Primitives

DL_RESET_REQ	resynchronizes a connection
DL_RESET_IND	indicates that the remote end is resynchronizing the connection
DL_RESET_RES	completes reset processing
DL_RESET_CON	confirms that reset processing is complete

11.1.1 Address Structures

DLPI uses data link service access point (DLSAP) addresses. These are used when connecting to a given address by the DL_CONNECT_REQ, DL_CONNECT_CON and DL_CONNECT_IND primitives. Addressing is handled differently for LLC2 and LAPB.

11.1.1.1 LLC2 Address Structure

The LLC2 DLSAP is contained in the following structure:

struct llc_dladdr {
    u_char   dl_mac[6];      /* MAC address */
    u_char   dl_sap;         /* LLC SAP */
 };

The file /usr/include/netdlc/llc2.h contains the structure definition.

The members of the llc_dladdr structure are:

Table 11-6 Members of llc_dladdr structure

Members	Description
dl_mac	The MAC address
dl_sap	The LLC SAP (service access point).

11.1.1.2 LAPB Address Structure

The address field is only required when LAPB is being used over a Public Switched Telephone Network (PSTN). In this case, the dl_address fields contain the PSTN address, in the format defined by the pstnformat structure:

struct pstnformat {
   uint8   pstn_len;               /* Address length in octets */
   uint8   pstn_add[20];  /* LAPB Address in hexadecimal */
 };

The members of the pstnformat structure are:

Table 11-7 Members of pstnformat structure

Members	Description
pstn_len	The length of the address as bytes.
pstn_add	The LSAP in hexadecimal format. This can be up to 20 digits long.

The file /usr/include/netx25/sdlpi.h contains the structure definition.

11.1.2 Message Primitive Sequence Summary

LLC2

The diagram below summarizes the order that the DLPI message primitives are used to establish a connection and transfer data in connection oriented mode when LLC2 is used:

The file /opt/SUNWconn/x25/samples.dlpi/llc2.c contains an example.

LAPB

The diagram below summarizes the order that the DLPI message primitives are used to establish a connection and transfer data in connection oriented mode when LAPB is used:

When using LAPB, the connect phase is handled automatically by the network. The LAPB protocol automatically establishes the connection as soon as the cable has been plugged in. The connect indicator CONNECT_IND will automatically notify the user when the connection has been established.

The file /opt/SUNWconn/x25/samples.dlpi/lapb.c contains an example.

11.1.3 DL_ATTACH_REQ--Identifies Physical Link to use

This primitive is sent in an M_PROTO message block. It identifies the physical link to be used. In most cases this is a card or a port plus a card. The physical link is identified by a Physical Point of Attachment (PPA).

Associated Structure:

typedef struct {
        t_uscalar_t     dl_primitive;           /* set to DL_ATTACH_REQ */
        t_uscalar_t     dl_ppa;                 /* id of the PPA */
} dl_attach_req_t;

The members of the dl_attach_req_t structure are:

Table 11-8 Members of the dl_attach_req_t structure

Member	Description
dl_primitive	Should be set to the name of this primitive.
dl_ppa	Contains the PPA (or hardware device) the stream should be bound to. The PPA values are defined at system configuration time with the L_SETPPA ioctl. This applies to LAPB only. For LLC2 the PPA is associated with the hardware at system boot time.

Errors

Table 11-9 DL_ATTACH_REQ errors

Error	Description
DL_OUTSTATE	Primitive issued from an invalid state.
DL_BADPPA	The specified PPA was invalid (was not configured with the L_SETPPA ioctl).
DL_SYSERR	Could not allocate memory to handle the connection.

11.1.4 DL_BIND_ACK--Acknowledges Bind Request

If a bind request is successful, a DL_BIND_ACK message will be sent upstream to acknowledge the request. This message is sent in an M_PCPROTO message block.

Associated Structure

typedef struct {
        t_uscalar_t     dl_primitive;   /* DL_BIND_ACK */
        t_uscalar_t     dl_sap;         /* DLSAP addr info */
        t_uscalar_t     dl_addr_length; /* length of complete DLSAP addr */
        t_uscalar_t     dl_addr_offset; /* offset from start of M_PCPROTO */
        t_uscalar_t     dl_max_conind;  /* allowed max. # of con-ind */
        t_uscalar_t     dl_xidtest_flg; /* responses supported by provider */
} dl_bind_ack_t;

The members of the dl_bind_ack_t structure are:

Table 11-10 Members of the dl_bind_ack_t structure

Member	Description
dl_primitive	Should be set to the name of this primitive.
dl_sap	Contains the SSAP.
dl_addr_length	The length of the DLSAP. When interfacing to LLC2, this is 7. For LAPB it is 0.
dl_addr_offset	Offset of DLSAP address, in bytes, from the beginning of the M_PCPROTO message block. The DLSAP address is stored as an struct llc_dladdr structure when working with LLC2 and as a pstnformat structure when working with LAPB. See "11.1.1 Address Structures" for more information.
dl_max_conind	Equals the value of max_conind passed down in the DL_BIND_REQ message.
dl_xidtest_flg	Valid for LLC2 only. Contains the value (DL_AUTO_XID | DL_AUTO_TEST), because the LLC2 driver has the capability of responding automatically to TEST and XID commands.

11.1.5 DL_BIND_REQ--Specifies CLNS or CONS Service

This primitive is sent in an M_PROTO message block. It specifies whether the connectionless or connection oriented service should be used and provides the LSAP if required.

This message primitive must be set to connection oriented mode when used with either LAPB or LLC2. Connectionless mode is not supported.

The LSAP is one octet long and can be any value.

Associated Structure:

typedef struct {
        t_uscalar_t     dl_primitive;   /* set to DL_BIND_REQ */
        t_uscalar_t     dl_sap;         /* info to identify dlsap addr */
        t_uscalar_t     dl_max_conind;  /* max # of outstanding con_ind */
        uint16_t        dl_service_mode;        /* CO, CL or ACL */
        uint16_t        dl_conn_mgmt;   /* if non-zero, is con-mgmt stream */
        t_uscalar_t     dl_xidtest_flg; /* auto init. of test and xid */
} dl_bind_req_t;

The members of the dl_bin_req_t structure:

Table 11-11 Members of the dl_bin_req_t structure

Member	Description
dl_primitive	Should be set to the name of this primitive.
dl_sap	One byte SSAP. For LLC2, this parameter must be set to an even value other than 0. For LAPB, this parameter must be set to 0. The full DLSAP is returned in the DL_BIND_ACK response.
dl_max_conind	The maximum number of outstanding DL_CONNECT_IND messages allowed on the stream. A value of zero prevents the stream from accepting any DL_CONNECT_IND messages. When using LAPB, set this parameter to 1. When using with LLC2, set the calling side to 0 and the called side to >0.
dl_service_mode	Set to DL_CODLS to indicate that connection-oriented service (LLC2 or LAPB) is desired.
dl_conn_mgmt	Set to non-zero to use this stream as the "connection management" stream for the PPA. When set to a non-zero value, this handles incoming DL_CONNECT_IND messages that do not match any other stream, or where the maximum number of outstanding connection messages specified in dl_max_conind has been exceeded.
dl_xidtest_flg	Valid for LLC2 only. Specifies whether or not the LLC2 driver is to automatically reply to XID/TEST commands. It is a bit-mask of the following two flags: DL_AUTO_XID--Respond to XID commands. DL_AUTO_TEST--Respond to TEST commands.If this field is zero, the LLC2 client will receive all incoming TEST and XID commands, and will be expected to respond to them.

---

Note -

Multiple LLC2 streams may be bound to the same SAP, but only one listen stream is allowed per SAP.

---

Errors

Table 11-12 DL_BIND_REQ errors

Error	Description
DL_OUTSTATE	Primitive issued from an invalid state.
DL_UNSUPPORTED	The requested service mode is not supported (only DL_CODLS and DL_CLDLS are supported).
DL_BOUND	Attempt to bind a second listen stream, or a second "connection management" stream.
DL_BADADDR	Attempt to bind to a zero or odd SAP.
DL_SYSERR	Could not allocate STREAMS resources.

11.1.6 DL_CONNECT_CON--Acknowledge DL_CONNECT_REQ

Positively acknowledges a previous DL_CONNECT_REQ primitive. Is sent upstream when a UA frame arrives to ack a previously sent SABME or SABM frame. This message consists of one M_PROTO message block containing the following structure:

typedef struct {
        t_uscalar_t     dl_primitive;           /* DL_CONNECT_CON */
        t_uscalar_t     dl_resp_addr_length;    /* responder's address len */
        t_uscalar_t     dl_resp_addr_offset;    /* offset from start of block */
        t_uscalar_t     dl_qos_length;          /* length of qos structure */
        t_uscalar_t     dl_qos_offset;          /* offset from start of block */
        t_uscalar_t     dl_growth;              /* set to zero */
} dl_connect_con_t;

The members of the dl_connect_con_t structure are:

Table 11-13 Members of the dl_connect_con_t structure

Member	Description
dl_primitive	Should be set to the name of this primitive.
dl_resp_addr_length	The length of the DLSAP. This is 7 when working with LLC2 and 0 or 21 when working with LAPB.
dl_resp_addr_offset	Offset to the responder (destination) address, stored in struct llc_dladdr or struct pstnformat format.
dl_qos_length	Always set to 0.
dl_qos_offset	Always set to 0.

11.1.7 DL_CONNECT_IND--Indicate Incoming Connection

Indicates that a remote user wants to establish a connection. This primitive is sent upstream when a SABME or SABM is received from the network.

Associated Structure

This message consists of one M_PROTO message block containing the following structure:

typedef struct {
        t_uscalar_t     dl_primitive;           /* DL_CONNECT_IND */
        t_uscalar_t     dl_correlation;         /* provider's correl. token */
        t_uscalar_t     dl_called_addr_length;  /* length of called address */
        t_uscalar_t     dl_called_addr_offset;  /* offset from start of block */
        t_uscalar_t     dl_calling_addr_length; /* length of calling address */
        t_uscalar_t     dl_calling_addr_offset; /* offset from start of block */
        t_uscalar_t     dl_qos_length;          /* length of qos structure */
        t_uscalar_t     dl_qos_offset;          /* offset from start of block */
        t_uscalar_t     dl_growth;              /* set to zero */
} dl_connect_ind_t;

The members of the dl_connect_ind_t structure are:

Table 11-14 Members of the dl_connect_ind_t structure

Member	Description
dl_primitive	Should be set to the name of this primitive.
dl_correlation	Unique identifier for the connection, to be passed back downstream in a DL_CONNECT_RES or DL_DISCONNECT_RES message later on. Can also be passed upstream in a subsequent DL_DISCONNECT_IND message.
dl_called_addr_length	Set to 7 when interfacing with LLC2 and 21 when interfacing with LAPB.
dl_called_addr_offset	Offset to the called (destination) address, which is stored in struct llc_dladdr or struct lapbformat format.
dl_calling_addr_length	Set to 7 when working with LLC2 and 0 when working with LAPB.
dl_calling_addr_offset	Offset to the calling (source) address, which is stored in struct llc_dladdr or struct pstnformat format.
dl_qos_length	Always set to 0.
dl_qos_offset	Always set to 0.

11.1.8 DL_CONNECT_REQ--Establish a Connection

Used to establish a connection. When the user issues this primitive, a SABME or SABM frame is sent across the network to the destination.

Associated Structure

This message consists of one M_PROTO message block containing the following structure:

typedef struct {
        t_uscalar_t     dl_primitive;           /* DL_CONNECT_REQ */
        t_uscalar_t     dl_dest_addr_length;    /* len. of dlsap addr */
        t_uscalar_t     dl_dest_addr_offset;    /* offset */
        t_uscalar_t     dl_qos_length;          /* len. of QOS parm val */
        t_uscalar_t     dl_qos_offset;          /* offset */
        t_uscalar_t     dl_growth;              /* set to zero */
} dl_connect_req_t;

The members of the dl_connect_req_t structure are:

Table 11-15 Members of the dl_connect_req_t structure

Member	Description
dl_primitive	Should be set to the name of this primitive.
dl_dest_addr_length	Set to 7 when working with LLC2 and 21 when working with LAPB.
dl_dest_addr_offset	Offset, in bytes, from beginning of M_PROTO message block. The destination DLSAP address should be encoded as a struct llc_dladdr. This field and dl_dest_addr_length combined give the remote address if you are working with LLC2 and the PSTN address if you are working with dial-up LAPB. They are not used if you are working with non dial-up LAPB.
dl_qos_length	Will be ignored.
dl_qos_offset	Will be ignored.

This primitive is positively acknowledged with a DL_CONNECT_CON primitive. If there is a local error, this primitive is nack'ed with a DL_ERROR_ACK, with the possible error codes listed below. If the destination cannot be reached, this primitive is nack'ed with a DL_DISCONNECT_IND primitive.

Errors

Table 11-16 DL_CONNECT_REQ errors

Error	Description
DL_OUTSTATE	Primitive issued from an invalid state.
DL_BADADDR	The destination DLSAP address was invalid, for one of the following reasons: dl_dest_addr_length is incorrect, zero or, odd SAP (when using LLC2) loopback connection to the same SAP
DL_ACCESS	Attempt to connect a second LLC2 stream, bound to the same SAP, to the same destination DLSAP (really need to return an "address already in use" error in this case, but no such error exists in DLPI).
DL_SYSERR	Could not allocate memory.

11.1.9 DL_CONNECT_RES--Accept a Connect Request

Accept a connect request from a remote user. Causes a UA frame to be sent over the network (to ack the SABME or SABM that was received earlier). This message consists of one M_PROTO message block containing the following structure:

typedef struct {
        t_uscalar_t     dl_primitive;   /* DL_CONNECT_RES */
        t_uscalar_t     dl_correlation; /* provider's correlation token */
        t_uscalar_t     dl_resp_token;  /* token of responding stream */
        t_uscalar_t     dl_qos_length;  /* length of qos structure */
        t_uscalar_t     dl_qos_offset;  /* offset from start of block */
        t_uscalar_t     dl_growth;      /* set to zero */
} dl_connect_res_t;

The members of the dl_connect_res_t structure are:

Table 11-17 Members of the dl_connect_res_t structure

Member	Description
dl_primitive	Should be set to the name of this primitive.
dl_correlation	Contains the correlation number passed upstream in the DL_CONNECT_IND message.
dl_resp_token	Contains the token of the stream that will accept the connection, if the accepting stream is not the listen stream (applies to LLC2 only).
dl_qos_length	Will be ignored.
dl_qos_offset	Will be ignored.

Errors

Table 11-18 DL_CONNECT_RES errors

Error	Description
DL_OUTSTATE	Primitive issued from an invalid state, or the accepting stream is not in state DL_IDLE (attached and bound) or is not attached to the same PPA.
DL_BADCORR	The dl_correlation parameter does not correspond to the ID of a pending connection.
DL_BADTOKEN	The dl_resp_token parameter does not correspond to a currently open stream.
DL_ACCESS	Accepting stream is not bound to the same SAP as the listen stream.
DL_PENDING	Attempt to accept a connection on the listen stream when there are other outstanding connect indications on the listen stream, or an attempt to accept a connection on the "connection management" stream.
DL_SYSERR	Could not allocate STREAMS resources.

11.1.10 DL_DETACH_REQ--Undoes a Previous DL_ATTACH_REQ

Undoes a previous DL_ATTACH_REQ. This primitive is sent in an M_PROTO message block.

Associated Structure

typedef struct {
  t_uscalar_t dl_primitive;   /* set to DL_DETACH_REQ */
 } dl_detach_req_t;

The members of the dl_detach_req_t structure are:

Table 11-19 Members of the dl_detach_req_t structure

Member	Description
dl_primitive	Should be set to the name of this primitive.

Errors:

Table 11-20 DL_DETACH_REQ errors

Error	Description
DL_OUTSTATE	Primitive issued from an invalid state.

11.1.11 DL_DISCONNECT_IND--Indicates Connection Disconnect

Informs the user that the connection has been disconnected, or that a pending connection has been aborted. This message is passed upstream when a DISC frame is received from the network, or if the ack timer expires (because either the remote end didn't respond to a SABME/ DL_CONNECT_REQ, or to a SABM, or because during data transfer the connection went down).

Associated Structure

This message consists of one M_PROTO message block containing the following structure:

typedef struct {
    t_uscalar_t   dl_primitive;    /* DL_DISCONNECT_IND */
    t_uscalar_t   dl_originator;   /* USER or PROVIDER */
    t_uscalar_t   dl_reason;       /* permanent or transient */
    t_uscalar_t   dl_correlation;  /* association with connect_ind */
 } dl_disconnect_ind_t;

The dl_disconnect_ind_t structure has the following members:

Table 11-21 Members of dl_disconnect_ind structure

Member	Description
dl_primitive	Should be set to the name of this primitive.
dl_originator	Set to either:  DL_USER--a DISC frame was received from the network. DL_PROVIDER--the ack timer expired.
dl_reason	Set to:  DL_CONREJ_DEST_UNREACH_TRANSIENT--a pending connection was aborted. DL_DISC_TRANSIENT_CONDITION--an active connection was disconnected. DL_DISC_PERMANENT_CONDITION-- the physical level is not connected.
dl_correlation	If a pending incoming call is being aborted, this contains the correlation value that was passed in the DL_CONNECT_IND primitive.

11.1.12 DL_DISCONNECT_REQ--Disconnects a Connection

Used to disconnect a connection. Can be used to disconnect an active connection (in state DL_DATAXFER), to refuse an incoming connection (which was indicated by the reception of a DL_CONNECT_IND primitive), or to cancel a previous DL_CONNECT_REQ primitive before the DL_CONNECT_CON acknowledgment is received back from the other end.

When the user issues this primitive, one of two things will happen, depending on the state that the stream is in:

1. In state DL_DATAXFER or if cancelling a previous DL_CONNECT_REQ, a DISC command frame is sent across the network to the destination.

2. If refusing an incoming connection, a DM response frame is sent (in response to the SABME that was received earlier).

Associated Structure

This message consists of one M_PROTO message block containing the following structure:

typedef struct {
        t_uscalar_t     dl_primitive;   /* DL_DISCONNECT_REQ */
        t_uscalar_t     dl_reason;      /* norm., abnorm., perm. or trans. */
        t_uscalar_t     dl_correlation; /* association with connect_ind */
} dl_disconnect_req_t;

The fields associated with the dl_disconnect_req_t structure are:

Table 11-22 Members of the dl_disconnect_req_t structure

Member	Description
dl_primitive	Should be set to the name of this primitive.
dl_reason	Any value passed here will be ignored, as LLC2 and LAPB have no means of carrying a "disconnect reason" across the network.
dl_correlation	If the user is rejecting an incoming call, this needs to be set to the correlation value supplied in the received DL_CONNECT_IND primitive. Otherwise, this parameter should be set to 0.

Errors

Table 11-23 DL_DISCONNECT_REQ errors

Error	Description
DL_OUTSTATE	Primitive issued from an invalid state.
DL_BADCORR	Non-zero correlation value supplied when not rejecting an incoming call, or invalid correlation value supplied when rejecting an incoming call.

11.1.13 DL_ERROR_ACK--Negative Acknowledgment

This primitive is sent upstream to negatively acknowledge a previous primitive.

Associated Structure

It is sent in an M_PCPROTO message block, with the following structure:

typedef struct {
        t_uscalar_t     dl_primitive;           /* DL_ERROR_ACK */
        t_uscalar_t     dl_error_primitive;     /* primitive in error */
        t_uscalar_t     dl_errno;               /* DLPI error code */
        t_uscalar_t     dl_unix_errno;          /* UNIX system error code */
} dl_error_ack_t;

The members of the dl_error_ack_t structure are:

Table 11-24 Members of the dl_error_ack_t structure

Member	Description
dl_primitive	Should be set to the name of this primitive.
dl_error_primitive	Set to the name of the primitive in error.
dl_unix_errno	Unix error code, if dl_errno is equal to DL_SYSERR
dl_errno	Contains the DLPI error code.

11.1.14 DL_INFO_ACK--Convey Info Summary

The LLC2 and LAPB drivers respond to the DL_INFO_REQ with a DL_INFO_ACK message.

Associated Structure

This message consists of one M_PCPROTO message block, with the following structure:

typedef struct {
        t_uscalar_t     dl_primitive;           /* set to DL_INFO_ACK */
        t_uscalar_t     dl_max_sdu;             /* Max bytes in a DLSDU */
        t_uscalar_t     dl_min_sdu;             /* Min bytes in a DLSDU */
        t_uscalar_t     dl_addr_length;         /* length of DLSAP address */
        t_uscalar_t     dl_mac_type;            /* type of medium supported */
        t_uscalar_t     dl_reserved;            /* value set to zero */
        t_uscalar_t     dl_current_state;       /* state of DLPI interface */
        t_scalar_t      dl_sap_length;          /* length of dlsap SAP part */
        t_uscalar_t     dl_service_mode;        /* CO, CL or ACL */
        t_uscalar_t     dl_qos_length;          /* length of qos values */
        t_uscalar_t     dl_qos_offset;          /* offset from start of block */
        t_uscalar_t     dl_qos_range_length;    /* available range of qos */
        t_uscalar_t     dl_qos_range_offset;    /* offset from start of block */
        t_uscalar_t     dl_provider_style;      /* style1 or style2 */
        t_uscalar_t     dl_addr_offset;         /* offset of the dlsap addr */
        t_uscalar_t     dl_version;             /* version number */
        t_uscalar_t     dl_brdcst_addr_length;  /* length of broadcast addr */
        t_uscalar_t     dl_brdcst_addr_offset;  /* offset from start of block */
        t_uscalar_t     dl_growth;              /* set to zero */
} dl_info_ack_t;

The members of the dl_info_ack_t structure are:

Table 11-25 members of the dl_info_ack_t structure

Member	Description
dl_primitive	Should be set to the name of this primitive.
dl_mac_type	Valid for LLC2 only. Set to the value returned by the hardware driver underneath LLC2.
dl_mdlc_type	Valid for LAPB only. Set to the value returned by the hardware driver underneath LAPB.
dl_current_state	Indicates the current DLPI state of the interface.
dl_sap_length	For LLC2, set to 1, which indicates that the SAP is one byte long, and follows the physical address in the DLSAP address. For LAPB, set to 0.
dl_addr_offset	Offset to the DLSAP address of this stream.
dl_brdcst_addr_off	Offset to the hardware broadcast address.

The QOS fields are always set to 0 when used over Ethernet/802.3. (dl_qos_length, dl_qos_offset, dl_qos_range_length, dl_qos_range_offset). Their settings above other media (FDDI, Token Ring, etc.) is to be defined. For descriptions of the other parameters, refer to the DLPI specifications.

11.1.15 DL_INFO_REQ--Request Info Summary

This primitive requests information about the stream.

Associated Structure

This primitive is sent in an M_PROTO message block, with the following structure:

typedef struct {
        t_uscalar_t     dl_primitive;                   /* set to DL_INFO_REQ */
} dl_info_req_t;

The members of the dl_info_req_t structure are:

Table 11-26 Members of the dl_info_req_t structure

Member	Description
dl_primitive	The name of this primitive.

11.1.16 DL_OK_ACK--Acknowledge Previous Primitive

This primitive is sent upstream to positively acknowledge a previous primitive. It is sent in an M_PCPROTO message block

Associated Structure

typedef struct {
        t_uscalar_t     dl_primitive;           /* DL_OK_ACK */
        t_uscalar_t     dl_correct_primitive;   /* primitive acknowledged */
} dl_ok_ack_t;

The members of the dl_ok_ack_t structure are:

Table 11-27 Members of the dl_ok_ack_t structure

Members	Description
dl_primitive	Should be set to the name of this primitive.
dl_correct_primitive	Set to the name of the primitive being acknowledged.

11.1.17 DL_RESET_CON--Acknowledges DL_RESET_REQ

Positively acknowledges a previous DL_RESET_REQ primitive. This primitive is sent upstream when a UA frame arrives to ack a previously sent SABME frame.

Associated Structure

This message consists of one M_PROTO message block containing the following structure:

typedef struct {
        t_uscalar_t     dl_primitive;           /* DL_RESET_CON */
} dl_reset_con_t;

The members of the dl_reset_con_t structure are:

Table 11-28 Members of the dl_reset_con_t structure

Member	Description
dl_primitive	Should be set to the name of this primitive.

11.1.18 DL_RESET_IND--Indicates Remote Reset

Indicates that the remote user is resynchronizing the connection. This primitive is sent upstream when a SABME or SABM is received from the network, while in state DL_DATAXFER.

Associated Structure

This message consists of one M_PROTO message block containing the following structure:

typedef struct {
        t_uscalar_t     dl_primitive;   /* DL_RESET_IND */
        t_uscalar_t     dl_originator;  /* Provider or User */
        t_uscalar_t     dl_reason;      /* flow control, link error, resync */
} dl_reset_ind_t;

The members of the dl_reset_ind_structure are:

Table 11-29 Members of the dl_reset_ind_structure

Member	Description
dl_primitive	Should be set to the name of this primitive.
dl_originator	Always set to DL_USER.
dl_reason	Always set to DL_RESET_RESYNCH (there is no means of carrying a "reset reason" across the network).

11.1.19 DL_RESET_REQ--Request Connection Reset

Used to resynchronize a connection. When the user issues this primitive while the stream is in state DL_DATAXFER, a SABME or SABM frame is sent across the network to the destination.

Associated Structure

This message consists of one M_PROTO message block containing the following structure:

typedef struct {
        t_uscalar_t     dl_primitive;   /* DL_RESET_REQ */
} dl_reset_req_t;

This primitive is positively acknowledged with a DL_RESET_CON primitive. If there is a local error, this primitive is negatively acknowledged with a DL_ERROR_ACK, with the possible error codes listed below.

The members of the dl_reset_req_t structure are:

Table 11-30 Members of the dl_reset_req_t structure

Member	Description
dl_primitive	Should be set to the name of this primitive.

Errors

Table 11-31 DL_RESET_REQ errors

Error	Description
DL_OUTSTATE	Primitive issued from an invalid state.

11.1.20 DL_RESET_RES--Respond to Reset Request

Respond to a reset request (an incoming DL_RESET_IND). Causes a UA frame to be sent over the network (to ack the SABME or SABM that was received earlier).

Associated Structure

This message consists of one M_PROTO message block containing the following structure:

typedef struct {
        t_uscalar_t     dl_primitive;           /* DL_RESET_RES */
} dl_reset_res_t;

The members of the dl_reset_res_t structure are:

Table 11-32 Members of the dl_reset_res_t structure

Member	Description
dl_primitive	Should be set to the name of this primitive.

Errors

Table 11-33 DL_RESET_RES errors

Error	Description
DL_OUTSTATE	Primitive issued from an invalid state.
DL_SYSERR	Could not allocate STREAMS resources.

11.1.21 DL_TOKEN_ACK--Acknowledges DL_TOKEN_REQ

The DL_TOKEN_REQ primitive is positively acknowledged with a DL_TOKEN_ACK primitive, which is encoded in an M_PCPROTO message block containing the following structure:

typedef struct {
        t_uscalar_t     dl_primitive;   /* DL_TOKEN_ACK */
        t_uscalar_t     dl_token;       /* Connection response token */
}dl_token_ack_t;

The members of the dl_token_ack_t structure are:

Table 11-34 Members of the dl_token_ack_t structure

Member	Description
dl_primitive	Should be set to the name of this primitive.
dl_token	Contains the connection response token.

11.1.22 DL_TOKEN_REQ--Assigns Token to Stream

Used to determine the token associated with a LLC2 stream (LAPB does not support). This token can then be supplied in the DL_CONNECT_RES primitive to indicate that the connection should be accepted on a different stream from the listen stream. The accepting stream must be attached and bound to the same PPA and SAP as the listen stream.

---

Note -

This primitive is not supported by LAPB.

---

Associated Structure

This message consists of one M_PROTO message block containing the following structure:

typedef struct {
        t_uscalar_t     dl_primitive;   /* DL_TOKEN_REQ */
} dl_token_req_t;

The members of the dl_token_req_t structure are:

Table 11-35 Members of the dl_token_req_t structure

Member	Description
dl_primitive	Should be set to the name of this primitive.

11.1.23 DL_UNBIND_REQ--Summary

This primitive unbinds the STREAM that was bound by a previous DL_BIND_REQ. It is sent in an M_PROTO message block.

Associated Structure:

typedef struct {
        t_uscalar_t     dl_primitive;   /* DL_UNBIND_REQ */
} dl_unbind_req_t;

The members of the dl_unbind_req_t structure are:

Table 11-36 Members of the dl_unbind_req_t structure

Member	Description
dl_primitive	Should be set to the name of this primitive.

11.2 Sun-Specific ioctls

The following ioctls are specific to Sun. Take care when using them in programs that interwork with other versions of X.25.

These ioctls must be used with the ioctl(2) system call.

The following ioctls are related to statistics:

Table 11-37 Statistics Ioctls

name	summary
L_GETSTATS	reads per-link statistics (LAPB only)
L_ZEROSTATS	zeros per-link statistics (LAPB only)
L_GETGSTATS	reads global layer two statistics (LAPB only)

These ioctls are related to configuring a stream:

Table 11-38 Stream Configuration Ioctls

name	summary
L_SETPPA	sets the PPA. (LAPB only)
L_GETPPA	retrieves the PPA (LAPB only)
L_SETTUNE	sets tunable parameters for a PPA
L_GETTUNE	retrieves the tunable parameters for a PPA
W_SETTUNE	sets wanmod tunable parameters for a PPA (LAPB only)

11.2.1 Common ioctls

The ioctles described in this section can be used over both LAPB and LLC2.

11.2.1.1 L_GETTUNE--Retrieves Tunable Parameters for a PPA

The L_GETTUNE ioctl retrieves the tunable parameters in the LLC2 and LAPB drivers for a given PPA.

Associated Structures

LLC2 uses the llc2_tnioc structure.

/* Ioctl block for LLC2 L_GETTUNE command */
 struct llc2_tnioc {
   u_char   lli_type;       /* Table type = LI_LLC2TUNE */
   u_char   lli_spare[3];   /*   (for alignment)        */
   u_int    lli_ppa;        /* PPA (0xff for all PPAs) */
   llc2tune_t    llc2_tune; /* Table of tuning values   */
 };

 /* LLC2 tuning structure */
 typedef struct llc2tune {
   u_short   N2;         /* Maximum number of retries */
   u_short   T1;         /* Acknowledgment time (unit 0.1 sec)  */
   u_short   Tpf;        /* P/F cycle retry time (unit 0.1 sec)  */
   u_short   Trej;       /* Reject retry time (unit 0.1 sec)  */
   u_short   Tbusy;      /* Remote busy check time   (unit 0.1 sec)  */
   u_short   Tidle;      /* Idle P/F cycle time (unit 0.1 sec)  */
   u_short   ack_delay;  /* RR delay time (unit 0.1 sec)  */
   u_short   notack_max; /* Maximum number of unack'ed Rx I-frames */
   u_short   tx_window;  /* Transmit window (if no XID received) */
   u_short   tx_probe;   /* P-bit position before end of Tx window  */
   u_short   max_I_len;  /* Maximum I-frame length */
   u_short   xid_window  /* XID window size (receive window) */
   u_short   xid_Ndup;   /* Duplicate MAC XID count (0 => no test) */
   u_short   xid_Tdup;   /* Duplicate MAC XID time   (unit 0.1 sec) */
 } llc2tune_t;

The members of the llc2_tnoic structure are:

Table 11-39 Members of the llc2_tnoic structure

Member	Description
lli_type	The table type
lli_ppa	The PPA
llc2_tune	A table of tuning values

LAPB uses the lapb_tnioc structure

/* Ioctl block for LAPB L_GETTUNE command */
 struct lapb_tnioc {
   u_char   lli_type;     /* Table type = LI_LLAPBTUNE */
   u_char   lli_spare[3]; /*   (for alignment)        */
   u_int    lli_ppa;      /* PPA (0xff for all PPAs) */
   lapbtune_t  lapb_tune; /* Table of tuning values   */
 };

 /* LAPB tuning structure */
 typedef struct lapb_tune {
   uint16  N2;         /* Maximum number of retries                */
   uint16  T1;         /* Acknowledgment time     (unit 0.1 sec)   */
   uint16  Tpf;        /* P/F cycle retry time     (unit 0.1 sec)  */
   uint16  Trej;       /* Reject retry time        (unit 0.1 sec)  */
   uint16  Tbusy;      /* Remote busy check time   (unit 0.1 sec)  */
   uint16  Tidle;      /* Idle P/F cycle time      (unit 0.1 sec)  */
   uint16  ack_delay;  /* RR delay time            (unit 0.1 sec)  */
   uint16  notack_max; /* Maximum number of unack'ed Rx I-frames   */
   uint16  tx_window;  /* Transmit window size                     */
   uint16  tx_probe;   /* P-bit position before end of Tx window   */
   uint16  max_I_len;  /* Maximum I-frame length                   */
   uint16  llconform;  /* LAPB conformance                         */
 } lapbtune_t;

The members of the lapb_tnoic structure are:

Table 11-40 Members of the lapb_tnoic structure

Member	Description
lli_type	The table type
lli_ppa	The PPA
lapb_tune	A table of tuning values

11.2.1.2 L_SETTUNE--Sets Tunable Parameters for a PPA

The L_SETTUNE ioctl sets tunable parameters in the LLC2 and LAPB drivers for a given PPA.

Associated Structures

LLCS uses the llc2_tnioc structure

/* Ioctl block for LLC2 L_SETTUNE command */
 struct llc2_tnioc {
   u_char  lli_type;       /* Table type = LI_LLC2TUNE */
   u_char  lli_spare[3];   /*   (for alignment)        */
   u_int   lli_ppa;        /* PPA (0xff for all PPAs) */
   llc2tune_t  llc2_tune;  /* Table of tuning values   */
 };

 /* LLC2 tuning structure */
 typedef struct llc2tune {
   u_short  N2;          /* Maximum number of retries */
   u_short  T1;          /* Acknowledgment time (unit 0.1 sec)  */
   u_short  Tpf;         /* P/F cycle retry time (unit 0.1 sec)  */
   u_short  Trej;        /* Reject retry time (unit 0.1 sec)  */
   u_short  Tbusy;       /* Remote busy check time   (unit 0.1 sec)  */
   u_short  Tidle;       /* Idle P/F cycle time (unit 0.1 sec)  */
   u_short  ack_delay;   /* RR delay time (unit 0.1 sec)  */
   u_short  notack_max;  /* Maximum number of unack'ed Rx I-frames */
   u_short  tx_window;   /* Transmit window (if no XID received) */
   u_short  tx_probe;    /* P-bit position before end of Tx window  */
   u_short  max_I_len;   /* Maximum I-frame length */
   u_short  xid_window;  /* XID window size (receive window) */
   u_short  xid_Ndup;    /* Duplicate MAC XID count (0 => no test) */
   u_short  xid_Tdup;    /* Duplicate MAC XID time   (unit 0.1 sec) */
 } llc2tune_t;

The members of the llc2_tnoic structure are:

Table 11-41 Members of the llc2_tnoic structure

Member	Description
lli_type	The table type
lli_ppa	The PPA
llc2_tune	A table of tuning values

LAPB uses the lapb_tnioc structure

/* Ioctl block for LAPB L_SETTUNE command */
 struct lapb_tnioc {
   u_char  lli_type;       /* Table type = LI_LLAPBTUNE */
   u_char  lli_spare[3];   /*   (for alignment)        */
   u_int   lli_ppa;        /* PPA (0xff for all PPAs) */
   lapbtune_t    lapb_tune;/* Table of tuning values   */
 };

 /* LAPB tuning structure */
 typedef struct lapb_tune {
   uint16  N2;         /* Maximum number of retries               */
   uint16  T1;         /* Acknowledgment time     (unit 0.1 sec)  */
   uint16  Tpf;        /* P/F cycle retry time     (unit 0.1 sec)  */
   uint16  Trej;       /* Reject retry time        (unit 0.1 sec)  */
   uint16  Tbusy;      /* Remote busy check time   (unit 0.1 sec)  */
   uint16  Tidle;      /* Idle P/F cycle time      (unit 0.1 sec)  */
   uint16  ack_delay;  /* RR delay time            (unit 0.1 sec)  */
   uint16  notack_max; /* Maximum number of unack'ed Rx I-frames   */
   uint16  tx_window;  /* Transmit window size                     */
   uint16  tx_probe;   /* P-bit position before end of Tx window   */
   uint16  max_I_len;  /* Maximum I-frame length                   */
   uint16  llconform;  /* LAPB conformance                         */
 } lapbtune_t;

The members of the lapb_tnoic structure are:

Table 11-42 Members of the lapb_tnoic structure

Member	Description
lli_type	The table type
lli_ppa	The PPA
lapb_tune	A table of tuning values

11.2.2 LAPB ioctls

The ioctls described in this section can only be used over LAPB.

11.2.2.1 L_GETGSTATS--Reads Global Layer 2 Statistics

The L_GETGSTATS ioctl reads global layer 2 statistics from the LAPB driver.

Associated Structures

The lapb_gstioc structure is used.

/* Ioctl block for L_GETGSTATS ioctl */
 struct lapb_gstioc {
     uint8         lli_type;      /* Table type = LI_GSTATS  */
     uint8         lli_spare[3];  /*   (for alignment)   */
     uint32        lapbgstats[globstatmax];
        /* global statistics table           */
 };

 /* Global L2 statistics */
 #define frames_tx     0 /* frames transmitted  */
 #define frames_rx     1 /* frames received  */
 #define sabme_tx      2 /* SABMEs transmitted  */
 #define sabme_rx      3 /* SABMEs received  */
 #define bytes_tx      4 /* data bytes transmitted */
 #define bytes_rx      5 /* data bytes received  */
 #define globstatmax   6 /* size of global stats array */

The members of the lapb_gstioc structure are:

Table 11-43 Members of the lapb_gstioc structure

Member	Description
lli_type	The table type
lapbgstats	The global statistics table

11.2.2.2 L_GETPPA--Returns the PPA Associated With a Stream

This ioctl returns the PPA and link index associated with the stream.

Associated Structure:

/* Ioctl block for L_SETPPA and L_GETPPA commands */
 struct ll_snioc {
     uint8        lli_type;     /* Table type = LI_SPPA            */
     uint8        lli_class;    /* DTE/DCE/extended                */
     uint16       lli_slp_pri;  /* SLP priority                    */
     uint32       lli_ppa;      /* PPA/ Subnetwork ID character    */
     uint32       lli_index;    /* Link index                      */
 };

The members of the ll_snioc structure are:

Table 11-44 Members of the ll_snioc structure

Member	Description
lli_type	The table type. This should always be LI_SPPA.
lli_class	This indicates the type of link. LC_LLC2 must be used for LLC2; LC__LAPBDTE or LC_LAPBDCE must be used for LAPB. The file /usr/include/netdlc/ll_proto.h contains a complete list of values.
lli_slp_pri	This determines the priority of SLP when MLP is used.
lli_ppa	The PPA identifier
lli_index	The link index. This must be set with the muxid value returned by the I-LINK ioctl when LAPB is placed over a serial driver.

Errors

Table 11-45 L_GETPPA errors

Error	Description
ENODEV	No such device or a DL_ATTACH_REQ has not been sent.

11.2.2.3 L_GETSTATS--Retrieves Per-Link Statistics

The L_GETSTATS ioctl reads per-link (i.e., per-PPA) statistics from the LAPB driver.

Associated Structures

The lapb_stioc structure is used

/* Ioctl block for L_GETSTATS ioctl */
 struct lapb_stioc {
     uint8           lli_type;      /* Table type = LI_STATS  */
     uint8           lli_spare[3];  /*   (for alignment)   */
     uint32          lli_ppa;       /* PPA    */
     lapbstats_t     lli_stats;     /* Table of stats values  */
 };

The lapbstats_t structure needed for L_GETSTATS is defined as follows:

---

Example 11-1 lapbstats_t structure

typedef struct lapb2_stats {
  uint32 lapbmonarray[laphstatmax]; /* array of LAPB stats */
 } lapbstats_t;

 /* Statistics table definitions  */
 #define tx_ign              0 /* no. ignored + not sent */
 #define rx_badlen           1 /* bad length frames received */
 #define rx_unknown          2 /* unknown frames received */
 #define t1_exp              3 /* no. of T1 timeouts  */
 #define t4_exp              4 /* no. of T4 timeouts  */
 #define t4_n2_exp           5 /* T4 timeouts after N2 times */

 #define RR_rx_cmd           6 /* RR = Receive Ready  */
 #define RR_rx_rsp           7 /* tx = transmitted  */
 #define RR_tx_cmd           8 /* rx = received  */
 #define RR_tx_rsp           9 /* cmd/rsp = command/response */
 #define RR_tx_cmd_p        10 /* p = p-bit set        */

 #define RNR_rx_cmd         11 /* RNR = Receive Not Ready */
 #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 /* REJ = Reject   */
 #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 /* SABME = Set Asynchronous  */
 #define SABME_tx_cmd       22 /*  Balanced Mode Extended */

 #define DISC_rx_cmd        23 /* DISC = Disconnect  */
 #define DISC_tx_cmd        24

 #define UA_rx_rsp          25 /* UA = Unnumbered   */
 #define UA_tx_rsp          26 /* Acknowledgment  */

 #define DM_rx_rsp          27 /*    */
 #define DM_tx_rsp          28

 #define I_rx_cmd           29 /* I = Information  */
 #define I_tx_cmd           30

 #define FRMR_rx_rsp        31 /* FRMR = Frame Reject  */
 #define FRMR_tx_rsp        32

 #define tx_rtr             33 /* no. of retransmitted frames  */
 #define rx_bad             34 /* erroneous frames received    */
 #define rx_dud             35 /* received and discarded      */
 #define rx_ign             36 /* received and ignored         */

 #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 TEST_rx_cmd        45
 #define TEST_rx_rsp        46
 #define TEST_tx_cmd        47
 #define TEST_tx_rsp        48

 #define llc2statmax        40

---

11.2.2.4 L_SETPPA--Associates a PPA With a Physical Device

This ioctl associates a PPA with a physical device underneath the layer two provider.

Associated Structure:

/* Ioctl block for L_SETPPA and L_GETPPA commands */
 struct ll_snioc {
     uint8        lli_type;     /* Table type = LI_SPPA            */
     uint8        lli_class;    /* DTE/DCE/extended                */
     uint16       lli_slp_pri;  /* SLP priority                    */
     uint32       lli_ppa;      /* PPA/ Subnetwork ID character    */
     uint32       lli_index;    /* Link index                      */
 };

The members are:

Table 11-46 Members of the ll_snioc structure

Member	Description
lli_type	The table type. This should always be LI_SPPA.
lli_class	This indicates the type of link. LC_LAPBDTE or LC_LAPBDCE must be used for LAPB. The file /usr/include/netdlc/ll_proto.h contains a complete list of values.
lli_slp_pri	This determines the priority of SLP when MLP is used.
lli_ppa	The PPA identifier
lli_index	The link index. This must be set with the muxid value returned by the I-LINK ioctl when LAPB is placed over a serial driver.

Errors

Table 11-47 L_SETPPA errors

Error	Description
EBUSY	The PPA is already being used by another stream.
ENODEV	The specified lli_index has not been found.

11.2.2.5 L_ZEROSTATS--Clears the Per-Link Statistics Count

The L_ZEROSTATS ioctl clears per-link statistics in the LLC2 and LAPB drivers.

Associated Structure

/* Ioctl block for L_ZEROSTATS ioctl */
 struct ll_hdioc {
     uint8           lli_type;      /* Table type = LI_PLAIN */
     uint8           lli_spare[3];  /*   (for alignment)  */
     uint32          lli_ppa;       /* PPA (0xff for all links) */
 };

11.2.2.6 W_SETTUNE--Sets wanmod Tunable Parameters

The W_SETTUNE ioctl sets the tunable parameters of the LAPB wanmod module. This controls physical parameters such as the maximum frame length and line speed.

Associated Structure

The following is from the file /usr/include/netx25/wan_control.h.

/*    Ioctl block for WAN W_SETTUNE command  
*/  
struct wan_tnioc {    
   uint8     w_type;     /* Always = WAN_TUNE                      */    
   uint8     w_spare[3]; /* (for alignment)                        */    
   uint32    w_snid;     /* subnetwork id character ('*' => 'all') */    
   wantune_t wan_tune;   /* Table of tuning values        
         */  
};   
/*    WAN tuning structure  */  
typedef struct wantune  {    
   uint16            WAN_options;  /* WAN options       */    
   struct WAN_hddef  WAN_hd;       /* HD information.   */  
   } wantune_t;   
/*        
This is the structure which contains all tuneable information  
*/  
struct  WAN_hddef  {        
   uint16      WAN_maxframe;    /* WAN maximum frame size       */        
   int         WAN_baud;        /* WAN baud rate                */        
   uint16      WAN_interface ;  /* WAN physical interface       */   
} 
union {        
   uint16         WAN_cptype;      /* Variant type */        
   struct WAN_x21 WAN_x21def;        
   struct WAN_v25 WAN_v25def;        
   } WAN_cpdef ;                   /* WAN call procedural definition *                                                      											 																						       												* for hardware interface.        */  
};   
/*
This contains all of the national network specific timeouts.  
*/  
struct  WAN_v25  {    
   uint16 WAN_cptype;   /* Variant type.        */    
   uint16 callreq;      /* Abort time for call request command  *                          																* if network does not support CFI.     */
};

The members of the wan_tnioc structure are:

Table 11-48 Members of the wan_tnioc structure

Member	Description
w_snid	The link id. It should be set to the same value as lli_ppa in the L_SETPPA L_SETTUNE ioctls.
WAN_options	Reserved for future use. Must be set to 0.
WAN_maxframe	The maximum frame size to be used on this interface (unit is octet).
WAN_baud	The speed of the line (unit is baud, 0 is used for external clocking).
WAN_interface	The type of interface. Should always be set to WAN_V28
WAN_cptype	The type of interface. Set this to WAN_NONE if no calling procedures are used (the most frequent case), or to WAN_V25bis if a calling procedure and V25bis modem are used. In this instance, the WAN_v25 structure must be filled.