DLCTOKEN Programming Interfaces

AIX Version 4.3 Communications Programming Concepts

DLCTOKEN Programming Interfaces

The token-ring data link control (DLCTOKEN) conforms to the generic data link control (GDLC) guidelines except where noted below. Additional structures and definitions for DLCTOKEN can be found in the /usr/include/sys/trlextcb.h file.

Note: The dlc prefix is replaced with the trl prefix for DLCTOKEN.

trlclose	DLCTOKEN is fully compatible with the dlcclose GDLC interface.
trlconfig	DLCTOKEN is fully compatible with the dlcconfig GDLC interface. No initialization parameters are required.
trlmpx	DLCTOKEN is fully compatible with the dlcmpx GDLC interface.
trlopen	DLCTOKEN is fully compatible with the dlcopen GDLC interface.
trlread	DLCTOKEN is compatible with the dlcread GDLC interface with the following conditions: The readx subroutines can have DLCTOKEN data link header information prefixed to the I-field being passed to the application. This is optional based on the readx subroutine data link header length extension parameter in the gdl_io_ext structure. If this field is nonzero, DLCTOKEN copies the data link header and the I-field to user space and sets the actual length of the data link header into the length field. If the field is 0, no data link header information is copied to user space. See the DLCTOKEN Frame Encapsulation figure for more details.

The following kernel receive packet function handlers always have the DLCTOKEN data link header information within the communications memory buffer (mbuf) and can locate it by subtracting the length passed (in the gdl_io_ext structure) from the data offset field of the mbuf structure.

trlselect

DLCTOKEN is fully compatible with the dlcselect GDLC interface.

trlwrite

DLCTOKEN is compatible with the dlcwrite GDLC interface, with the exception that network data can only be written as an unnumbered information (UI) packet and must have the complete data link header prefixed to the data. DLCTOKEN verifies that the local (source) service access point (SAP) is enabled and that the control byte is UI (0x03). See the DLCTOKEN Frame Encapsulation figure for more details.

trlioctl

DLCTOKEN is compatible with the dlcioctl GDLC interface, with conditions on the following operations:

The following sections describe these conditions in detail.

DLC_ENABLE_SAP

The ioctl subroutine argument structure for enabling a SAP (dlc_esap_arg) has the following specifics:

The grp_addr (group address) field for the token ring contains the four least significant bytes of the desired six-byte group address. Only bits 1 through 31 are valid. Bit 0 is ignored. The most significant two bytes are automatically compared for 0xC000 by the adapter.
The func_addr_mask (functional address mask) field must be the logical OR operation with the functional address on the adapter, which allows packets that are destined for specified functions to be received by the local adapter. Only bits 1 through 29 are valid. Bits 0, 30, and 31 are ignored. The most significant two bytes of the full six-byte functional address are automatically compared for 0xC000 by the adapter.
The following is an example of a Network Basic Input/Output System (NetBIOS) functional address:
```
To select the NETBIOS functional address of 0xC000_0000_0080,
the functional address mask is set to 0x0000_0080.
```
Note: DLCTOKEN does not check to determine whether a received packet was accepted by the adapter due to a preset network address, group address, or functional address.
The max_ls (maximum link stations) field cannot exceed 255 bytes.

The following common SAP flags are not supported:

ENCD	Specifies a synchronous data link control (SDLC) serial encoding.
NTWK	Indicates a teleprocessing network type.
LINK	Indicates a teleprocessing link type.
PHYC	Indicates a physical network call (teleprocessing).
ANSW	Indicates a teleprocessing autocall and autoanswer.

Group SAPs are not supported, so the num_grp_saps (number of group SAPs) field must be set to 0.
The laddr_name (local address and name) field and its associated length are only used for name discovery when the common SAP flag ADDR is set to 0. When resolve procedures are used (that is, the ADDR flag is set to 1), DLCTOKEN obtains the local network address from the device handler and not from the dlc_esap_arg structure.
The local_sap (local service access point) field can be set to any value except null SAP (0x00) or discovery SAP (0xFC). Also, the low-order bit must be set to 0 (B`nnnnnnn0') to indicate an individual address.
No protocol-specific data area is required for DLCTOKEN to enable a SAP.

DLC_START_LS

The ioctl subroutine argument structure for starting a link station (dlc_sls_arg) has the following specifics:

These following common link station (LS) flags are not supported:
STAT Specifies a station type for SDLC.

NEGO Specifies a negotiable station type for SDLC.
The raddr_name (remote address and name) field is only used for outgoing calls when the DLC_SLS_LSVC common LS flag is active.
The maxif (maximum I-field length) field can be set to any value greater than 0. See the DLCTOKEN frame encapsulation figure for more details. DLCTOKEN adjusts this value to a maximum of 4060 bytes if set too large.
The rcv_wind (receive window) field can be set to any value between 1 and 127 inclusive. The recommended value is 127.
The xmit_wind (transmit window) field can be set to any value between 1 and 127 inclusive. The recommended value is 26.
The rsap (remote SAP) field can be set to any value except null SAP (0x00) or name-discovery SAP (0xFC). Also, the low-order bit must be set to 0 (B`nnnnnnn0') to indicate an individual address.
The max_repoll field can be set to any value from 1 to 255. The recommended value is 8.
The repoll_time field is defined in increments of 0.5 seconds and can be set to any value from 1 to 255, inclusive. The recommended value is 2, giving a time-out duration of 1 to 1.5 seconds.
The ack_time (acknowledgment time) field is defined in increments of 0.5 seconds, and can be set to any value between 1 and 255, inclusive. The recommended value is 1, giving a time-out duration of 0.5 to 1 second.
The inact_time (inactivity time) field is defined in increments of 1 second and can be set to any value between 1 and 255 inclusive. The recommended value is 48, giving a time-out duration of 48 to 48.5 seconds.
The force_time (force halt time) field is defined in increments of 1 second and can be set to any value between 1 and 16383, inclusive. The recommended value is 120, giving a time-out duration of approximately 2 minutes.

A protocol-specific data area must be appended to the generic start link station argument (dlc_sls_arg). This structure provides DLCTOKEN with additional protocol-specific configuration parameters:

   struct trl_start_psd
{
   uchar_t    pkt_prty;   /* ring access packet priority   */
   uchar_t    dyna_wnd;   /* dynamic window increment      */
   ushort_t   reserved;   /* currently not used            */
};

The protocol-specific parameters are:

pkt_prty

Specifies the ring access priority that the user wishes to reserve on transmit packets. Values of 0 to 3 are supported, where 0 is the lowest priority and 3 is the highest priority.

dyna_wnd

Specifies the number of consecutive sequenced packets that must be acknowledged by the remote station before the local transmit window count can be incremented. Network congestion causes the local transmit window count to drop automatically to a value of 1. The dynamic window increment allows a gradual increase in network traffic after a period of congestion. This field can be set to any value between 1 and 255, inclusive. The recommended value is 1.

DLC_ALTER

The ioctl subroutine argument structure for altering an LS (dlc_alter_arg) has the following specifics:

The following alter flags are not supported:
RTE Alters routing.

SM1, SM2 Sets SDLC control mode.

A protocol-specific data area must be appended to the generic alter link station argument structure (dlc_alter_arg). This structure provides DLCTOKEN with additional protocol-specific alter parameters.

#define TRL_ALTER_PRTY 0x80000000 /* alter packet priority     */
#define TRL_ALTER_DYNA 0x40000000 /* alter dynamic window incr.*/
   struct trl_start_psd
{
   ulong_t   flags;      /* specific alter flags               */
   uchar_t   pkt_prty;   /* ring access packet priority value  */
   uchar_t   dyna_wnd;   /* dynamic window increment value     */
   ushort_t  reserved;   /* currently not used                 */
};

Specific alter flags are:

TRL_ALTER_PRTY	Specifies alter priority. If this flag is set to 1, the `pkt_prty` value field replaces the current priority value being used by the LS. The LS must be started for this alter command to be valid.
TRL_ALTER_DYNA	Specifies alter dynamic window. If this flag is set to 1, the `dyna_wnd` value field replaces the current dynamic window value being used by the LS. The LS must be started for this alter command to be valid.

The protocol-specific parameters are:

`pkt_prty`	Specifies the new priority reservation value for transmit packets.
`dyna_wnd`	Specifies the new dynamic window value to control network congestion.

DLC_QUERY_SAP

The device driver-dependent data returned from DLCTOKEN for this ioctl operation is the tok_ndd_stats_t structure defined in the /usr/include/sys/cdli_tokuser.h file.

DLC_QUERY_LS

There is no protocol-specific data area supported by DLCTOKEN for this ioctl operation.

DLC_ENTER_SHOLD

The enter_short_hold option is not supported by DLCTOKEN.

DLC_EXIT_SHOLD

The exit_short_hold option is not supported by DLCTOKEN.

DLC_ADD_GROUP

The add_group, or multicast address, option is supported by the DLCTOKEN device manager. This ioctl operation is a four-byte value as described in the DLC_ENABLE_SAP ioctl operation definition.

DLC_ADD_FUNC_ADDR

The len_func_addr_mask (functional address mask length) field must be set to 4, and the func_addr_mask (functional address mask) field must be the logical OR operation with the functional address on the adapter. Only bits 1 through 29 are valid. Bits 0, 30, and 31 are ignored. The most significant two bytes of the full six-byte functional address are automatically compared for 0xC000 by the adapter and cannot be added.

DLC_DEL_FUNC_ADDR

The len_func_addr_mask (functional address mask length) field must be set to 4, and the func_addr_mask (functional address mask) field must have each bit that you wish to reset set to 1 within the functional address on the adapter. Only bits 1 through 29 are valid. Bits 0, 30, and 31 are ignored. The most significant two bytes of the full six-byte functional address are automatically compared for 0xC000 by the adapter and cannot be deleted.

DLC_DEL_GRP

The delete group or multicast option is supported by the DLCTOKEN device manager. The address being removed must match an address that was added with a DLC_ENABLE_SAP or DLC_ADD_GRP ioctl operation.

IOCINFO

The ioctype variable returned is defined as a DD_DLC definition, and the subtype returned is DS_DLCTOKEN.

STAT	Specifies a station type for SDLC.
NEGO	Specifies a negotiable station type for SDLC.

RTE	Alters routing.
SM1, SM2	Sets SDLC control mode.