RFC: connectionless Data Link Metalanguage Burkhard Daniel

RFC: connectionless Data Link Metalanguage Burkhard Daniel (burk@stg.com) This RFC details a specification draft for a UDI metalanguage interfacing UDI Network Protocol drivers to UDI Data Link drivers. The metalanguage proposed here provides connectionless data link service to the network protocol driver. cldl Metalanguage Model This document identifies two entities: The Data Link Provider (DLP) and the Data Link Service User (DLU) (usually the network protocol driver). A DLP provides connectionless Data Link functionality above the MAC level. DLUs are children of the DLP. Any DLP can have multiple children, and any DLU can have multiple parents. A DLP instance enumerates all its children at the time it is instantiated by the MA. A DLU can then bind to the DLP by issuing the udi_dlp_bind_req operation over the initial bind channel established by the MA between the DLU and the DLP. A DLP acts as or using a separate communication mechanism -- interfaces with the NSR (Network Service Requestor) as defined by the UDI Network Interface Metalanguage. There is one DLP instance per network interface for any one distinct Data Link protocol. There is one DLU instance for any one distinct network protocol (or entity providing network-level protocol functionality). Any network protocol for which operation over a given data link protocol is defined and desirable can be bound to the corresponding DLP. Consequently, a DLU can utilize various DLPs, according to the desired operation (i.e. IP over Ethernet vs. IP over Wireless LAN). Likewise, one DLP can be used by various DLUs (i.e. IP over Ethernet vs. IPX over Ethernet on the same interface). An external configuration mechanism is needed to set up legal bindings between DLPs and DLUs. Each DLP instance will enumerate one child for each such binding. These bindings shall be based on a system-specific description of the network-level protocol entities (DLUs). DLPs and DLUs implicitly agree on an addressing format for the udi_dl_tx_req operation by binding to one another. The addr_type enumeration attribute contains a description of the addressing format a DLP understands. If the DLU understands the same addressing format, they can bind and that addressing format is used to describe destination endpoints. The addressing format also determines the format of the SAP address that the DLU specifies in the udi_dlp_rx_chan_req operation. During the bind operation, the DLP informs the DLU about the QoS guarantees it can make. When creating a transmit channel, the DLU can then specify a default set of QoS constraints to be used for transmission over that channel. However, each packet can also carry its own set of QoS constraints. The Data Link Metalanguage exposes a subset of the network device control operations defined in the UDI NIC metalanguage to the DLU in order to allow for protocols that need specific hardware support. The DLP can handle these control operations itself, if the NIC device does not support them or if the DLP provides overloaded functionality for these operations, or it can pass the operations to the ND for execution. Flow control is achieved in a manner similar to that of the NIC Metalanguage. The DLP allocates a pool of control blocks to be used for packet transmission, which it then passes to the DLU using the udi_dlu_tx_rdy operation. Similarly, the DLU allocates a supply of control blocks to be used for packet reception, which is made available to the DLP using the udi_dlp_rx_rdy operation. Page 1 of 35

Connectionless DL Metalanguage Definitions NAME udi_dlp_ctrl_ops_t typedef const struct { udi_channel_event_ind_op_t *channel_event_ind_op; udi_dlp_bind_req_op_t *dlp_bind_req_op; udi_dlp_unbind_req_op_t *dlp_unbind_req_op; udi_dlp_unbind_ack_op_t *dlp_unbind_ack_op; udi_dlp_rx_chan_req_op_t *dlp_rx_chan_req_op; udi_dlp_tx_chan_req_op_t *dlp_tx_chan_req_op; udi_dlp_ctrl_req_op_t *dlp_ctrl_req_opt; } udi_dlp_ctrl_ops_t; /* DLP control Ops Vector Number */ #define UDI_DLP_CTRL_OPS_NUM 1 DESCRIPTION A Data Link Driver uses the udi_dlp_ctrl_ops_t structure in a udi_dlp_ctrl_ops_t in a udi_ops_init_t as part of its udi_init_info in order to register its entry points for the Data Link Metalanguage operations delivered via the initial bind channel between the DLU and the DLP. Page 2 of 35

NAME udi_dlp_tx_ops_t typedef const struct { udi_channel_event_ind_op_t *channel_event_ind_op; udi_dlp_tx_req_op_t *dlp_tx_req_op; udi_dlp_tx_qos_req_op_t *dlp_tx_qos_req_op; udi_dlp_qos_modify_req_op_t *dlp_tx_qos_modify_req_op; } udi_dlp_tx_ops_t; /* DLP TX Ops Vector Number */ #define UDI_DLP_TX_OPS_NUM 2 DESCRIPTION A Data Link Driver uses the udi_dlp_tx_ops_t structure in a udi_ops_init_t as part of its udi_init_info in order to register its entry points for operations over a Data Link Metalanguage transmit channel. Page 3 of 35

NAME udi_dlp_rx_ops_t typedef const struct { udi_channel_event_ind_op_t *channel_event_ind_op; udi_dlp_rx_rdy_op_t *dlp_rx_rdy_op; } udi_dlp_rx_ops_t; /* DLP TX Ops Vector Number */ #define UDI_DLP_RX_OPS_NUM 3 DESCRIPTION A Data Link Driver uses the udi_dlp_rx_ops_t structure in a udi_ops_init_t as part of its udi_init_info in order to register its entry points for operations over a Data Link Metalanguage receive channel. Page 4 of 35

NAME udi_dlu_ctrl_ops_t typedef const struct { udi_channel_event_ind_op_t *channel_event_ind_op; udi_dlu_bind_ack_op_t *dlu_bind_ack_op; udi_dlu_unbind_ack_op_t *dlu_unbind_ack_op; udi_dlu_unbind_req_op_t *dlu_unbind_req_op; udi_dlu_rx_chan_ack_op_t *dlu_rx_chan_ack_op; udi_dlu_tx_chan_ack_op_t *dlu_tx_chan_ack_op; udi_dlu_ctrl_ack_op_t *dlu_ctrl_ack_op; } udi_dlu_ctrl_ops_t; /* DLU control Ops Vector Number */ #define UDI_DLU_CTRL_OPS_NUM 4 DESCRIPTION A Network Protocol Driver uses the udi_dlu_ctrl_ops_t structure in a udi_dlp_ctrl_ops_t in a udi_ops_init_t as part of its udi_init_info in order to register its entry points for the Data Link Metalanguage control operations. Page 5 of 35

NAME udi_dlu_tx_ops_t typedef const struct { udi_channel_event_ind_op_t *channel_event_ind_op; udi_dlu_tx_rdy_op_t *dlu_tx_rdy_op; udi_dlu_tx_qos_modify_ack_op_t *dlu_tx_qos_modify_ack_op; } udi_dlu_tx_ops_t; /* DLU TX Ops Vector Number */ #define UDI_DLU_TX_OPS_NUM 5 DESCRIPTION A Network Protocol Driver uses the udi_dlu_tx_ops_t structure in a udi_ops_init_t as part of its udi_init_info in order to register its entry points for operations over a Data Link Metalanguage transmit channel. Page 6 of 35

NAME udi_dlu_rx_ops_t typedef const struct { udi_channel_event_ind_op_t *channel_event_ind_op; udi_dlu_rx_ind_op_t *dlu_rx_ind_op; } udi_dlu_tx_ops_t; /* DLP RX Ops Vector Number */ #define UDI_DLU_RX_OPS_NUM 6 DESCRIPTION A Network Protocol Driver uses the udi_dlu_rx_ops_t structure in a udi_ops_init_t as part of its udi_init_info in order to register its entry points for operations over a Data Link Metalanguage receive channel. Page 7 of 35

NAME udi_dl_cb_t typedef struct { udi_cb_t gcb; } udi_dl_cb_t; /* Data Link Standard Control Block Number */ #define UDI_DL_STD_CB_NUM 1 DESCRIPTION The udi_dl_cb_t structure is used for channel operations between a child (DLU) and its parent (DLP) where there is no additional metalanguage information needed in the control block. This control block must be declared by specifying the control block index value UDI_DL_STD_CB_NUM in a udi_cb_init_t in the driver s udi_init_info. Page 8 of 35

NAME udi_dl_bind_cb_t typedef struct { udi_cb_t gcb; udi_ubit32_t min_dlpdu_size; udi_ubit32_t max_dlpdu_size; udi_ubit8_t max_perfect_multicast; udi_ubit8_t max_total_multicast; udi_ubit8_t mac_addr_len; void *qos_caps; } udi_dl_bind_cb_t; /* Data Link Bind Control Block Number */ #define UDI_DL_BIND_CB_NUM 2 MEMBERS gcb is the generic control block header which includes a pointer to the scratch space associated with this block and the channel context for the associated channel. The driver may use the scratch space while it owns the control block, but the values are not guaranteed to persist across channel operations. min_dlpdu_size is the minimum size of a Data Link Protocol Data Unit. This represents the minimum number of bytes that make up one packet sent or received by the DLP, including the data link header attached by the DLP. The DLP sets this value in the bind ack operation. max_dlpdu_size is the maximum size of a Data Link Protocol Data Unit. This represents the maximum number of bytes that make up one packet sent or received by the DLP, including the data link header attached by the DLP. The DLP sets this value in the bind ack operation. max_total_multicast is the maximum number of multicast addresses that can be matched by the Network Driver and associated hardware. This is used to allow the DLU to determine how to handle situations where more multicast addresses are desired beyond hardware capabilities. The DLU not, in any situation, issue a DLP trol request that would set the total number of multicast addresses to be matched above this number. mac_addr_len is the number of bytes to be used for MAC addresses for the network adapter hardware. The DLU needs to know the size of hardware MAC addresses if it intends to change or query the MAC addresses of the interface using DLP control operations. qos_caps is a pointer to an inline memory structure specifying the quality of service parameters the DLP supports. The DLP sets the contents of this structure before calling the bind ack operation. If NULL, the DLP does not make any Quality-of-Service guarantees and any constraints specified for packet transmission will be ignored by the DLP. The pointer itself is set by the environment and must not be modified by either the DLP or the DLU. Page 9 of 35

DESCRIPTION The udi_dl_bind_cb_t structure is used for the udi_dlp_bind_req and udi_dlu_bind_ack operations between a child (DLU) and its parent (DLP). This structure is empty for the udi_dlp_bind_req operation, and its members are filled in by the DLP for the corresponding udi_dlu_bind_ack operation. This control block must be declared by specifying the control block index value UDI_DL_BIND_CB_NUM in a udi_cb_init_t in the driver s udi_init_info. The qos_caps member points to a structure of type udi_qos_capabilities_t, which is defined in the UDI Quality of Service Library. Page 10 of 35

NAME udi_dl_ctrl_cb_t typedef struct { udi_cb_t gcb; udi_ubit8_t command; udi_ubit32_t indicator; udi_buf_t *data_buf; } udi_dl_ctrl_cb_t; /* Data Link Control Op Control Block Number */ #define UDI_DL_CTRL_CB_NUM 3 MEMBERS gcb is the generic control block header which includes a pointer to the scratch space associated with this block and the channel context for the associated channel. The driver may use the scratch space while it owns the control block, but the values are not guaranteed to persist across channel operations. command is the control command the DLP must execute or forward to the NIC driver for processing, as appropriate for the protocol implementation. The following control commands have been identified: UDI_NIC_ADD_MULTI Configures the multicast addresses specified in the supplied buffer. The data_buf contains the array of MAC addresses to be added to the existing filter (the number of addresses being specified is indicated by the indicator field). The remaining portion of the data_buf contains the new filter table including the newly added addresses. Devices which can modify their address filtering simply by knowing the addresses which are to be added or removed can use the initial indicator number of addresses to modify their filter. Other devices require access to the full table of addresses to be filtered to recompute the filter and may use the latter portion of the data_buf. It is possible for the DLU to register multiple times for a specific multicast address, and the DLP is responsible for handling this redundancy. The DLP must also validate the multicast addresses. The contents of the data buffer are guaranteed to be preserved across a channel for the request but not for the response. UDI_NIC_DEL_MULTI Removes the multicast addresses specified in the supplied buffer. In a manner similar to the UDI_NIC_ADD_MULTI operation, the initial indicator number of addresses in the data_buf lists the addresses to be removed, and the latter portion of the data_buf lists the new filter set after removing the specified addresses. The contents of the data buffer are guaranteed to be preserved across a channel Page 11 of 35

for the request but not for the response. UDI_NIC_ALLMULTI_ON Instructs the DLP to enable the network adapter to receive all multicast addressed packets. The indicator field is unused and the data_buf field must be NULL. This operation additionally indicates that any specific multicast addresses registered (via UDI_NIC_ADD_MULTI) must be removed. UDI_NIC_ALLMULTI_OFF Disables the reception of all multicast addresses. The indicator and data_buf arguments are used in the same manner as in the UDI_NIC_ADD_MULTI operation to specify the new list of specific multicast addresses (if any) that are to be passed to the DLP. The DLP must ensure that the adapter hardware is returned to the standard reception mode with no multicast addresses being received unless UDI_PROMISC_ON is in effect or unless specifically registered via this operation. The contents of the data buffer are guaranteed to be preserved across a channel for the request but not for the response. UDI_NIC_GET_CURR_MAC Reads the network adapter card s current physical MAC address or addresses. The array of MAC addresses is placed into the data_buf and the number of MAC addresses is placed into the indicator field in the same manner as described for the UDI_NIC_SET_CURR_MAC command. The buf_size in the data_buf divided by the indicator value should yield the same MAC address size as specified in the bind operation. The contents of the data buffer are guaranteed to be preserved across a channel for the response but not for the request. UDI_NIC_SET_CURR_MAC Configures the network adapter card s current physical MAC address or addresses. A typical card will have only a single unicast MAC address, but some configurations and hardware support the registration of multiple unicast MAC addresses for a network interface. The DLP may be instructed to register for multiple unicast MAC addresses by specifying an array of addresses in the associated buffer. All unicast addresses beyond the first address will be accrued against the NIC driver s max_perfect_multicast address count limit as specified in the bind operation; the total number of multicast and unicast addresses (excluding the first) registered by the DLU must not exceed the max_perfect_multicast value. The array of MAC addresses to be set is contained in the data_buf and the number of MAC addresses is in the indicator field. The buf_size in the data_buf divided by the indicator value should yield the same MAC address size as specified in the bind operation. The contents of the data buffer are guaranteed to be preserved across a channel for the request but not for the response. UDI_NIC_GET_FACT_MAC Reads the network adapter card s factory installed physical MAC address. The factory MAC address is specified as the single Page 12 of 35

element array in the data_buf in the same manner as for the UDI_NIC_GET_CURR_MAC command. This is the initial MAC address used to operate the NIC until changed via UDI_NIC_SET_CURR_MAC. The contents of the data buffer are guaranteed to be preserved across a channel for the response but not for the request. UDI_NIC_PROMISC_ON Instructs the DLP to enable the promiscuous mode on the network adapter card. The indicator field is unused and the data_buf field must be NULL. When promiscuous mode is enabled, the hardware should be configured such that no destination address matching is performed and all packets should be received and sent to the DLU. Error packets will still be discarded by the DLP. UDI_NIC_PROMISC_OFF Disables the promiscuous mode on the network adapter card. The indicator field is unused and the data_buf field must be NULL. The DLU must now be passed only unicast addresses specific to this adapter or any multicast addresses enabled by any previous UDI_NIC_ADD_MULTI or UDI_NIC_ALLMULTI_ON operations. UDI_NIC_HW_RESET Resets the network adapter card. The indicator field is unused and the data_buf field must be NULL. This operation should cause the hardware to be physically reset if possible. Any operations pending on the hardware should be cancelled and cleaned up; any operations pending in the driver that have not yet been delivered to the hardware (or which have already been completed by the hardware) should be processed as normal following the reset. All other activity should be suspended during the reset operation and the driver should restore the hardware to the same operational state that it had before the reset was issued with the following exceptions: promiscuous mode is disabled, no multicast addresses are registered, the current MAC address must be reprogrammed (i.e. the factory MAC address does not override the current setting), and link status should be established if the NIC driver s state is ENABLED or ACTIVE when this request is received. DESCRIPTION The udi_dl_ctrl_cb_t structure is used by the DLU to configure the NIC driver and the hardware via the DLP. The DLU must fill in its fields prior to initiating a udi_dlp_ctrl_req operation over the initial bind channel between the DLU and the DLP according to the requested operation. The commands that can be used with this control block are those available in the UDI NIC metalanguage. In executing (or forwarding) a control command as specified above, the DLP assumes the role of the NSR, i.e. it acts as the initiator for device control operations. Control functionality is exposed to the DLU to enable protocol-specific features that need special support from the underlying hardware. Page 13 of 35

NAME udi_dlp_bind_req void udi_dlp_bind_req ( udi_dl_bind_cb_t *cb); is a pointer to a Data Link Metalanguage bind control block. The fields of this control block are to be initialized by the binding DLP, which will return the control block to the DLU in a subsequent udi_dlu_bind_ack operation. TARGET CHANNEL The udi_dlp_bind_req operation is issued over the Data Link Metalanguage control channel, which is also the primary channel initially established by the MA to bind the primary region of the DLP to the primary region of the DLU. DESCRIPTION udi_dlp_bind_req is used to associate, or bind a channel between the DLU and the DLP. Page 14 of 35

NAME udi_dlu_bind_ack void udi_dlu_bind_ack ( udi_dl_bind_cb_t *cb, udi_status_t status); is a pointer to a Data Link Metalanguage bind control block. status indicates the success or failure of the data link bind request. TARGET CHANNEL The udi_dlu_bind_ack operation is issued over the Data Link Metalanguage control channel over which the corresponding udi_dlp_bind_req operation was received. DESCRIPTION Response to a udi_dlp_bind_req operation. The DLP uses this to acknowledge the bind operation to the DLU and to signal the success of the bind operation. TODO: Explain Status codes. Page 15 of 35

NAME udi_dlp_unbind_req void udi_dlp_unbind_req ( udi_dl_cb_t *cb); is a pointer to a Data Link Metalanguage standard control block. TARGET CHANNEL The udi_dlp_unbind_req operation is issued over the Data Link Metalanguage control channel. DESCRIPTION The udi_dlp_unbind_req operation is used when the DLU wishes to close down an active binding between itself and the DLP. All data transfer ceases, any queued data is discarded, and the data channel(s) are closed. The control channel may be used to issue a subsequent udi_dlp_bind_req to the DLP if desired or it may also be closed. Page 16 of 35

NAME udi_dlu_unbind_ack void udi_dlu_unbind_ack ( udi_dl_cb_t *cb, udi_status_t status); is a pointer to a Data Link Metalanguage standard control block. status indicates the success or failure of the data link unbind request. TARGET CHANNEL The udi_dlu_unbind_ack operation is issued over the Data Link Metalanguage control channel over which the corresponding udi_dlp_unbind_req operation was received. DESCRIPTION Response to a udi_dlp_unbind_req operation. After this operation is performed, the DLU will no longer attempt to transmit packets or to establish additional data transfer channels between itself and the DLP unless another udi_dlp_bind_req has been issued and handshaked before. Likewise, the DLP will stop delivering incoming packets to the DLU unless it has been bound again. TODO: Explain Status codes. Page 17 of 35

NAME udi_dlu_unbind_req void udi_dlu_unbind_req ( udi_dl_cb_t *cb); is a pointer to a Data Link Metalanguage standard control block. TARGET CHANNEL The udi_dlu_unbind_req operation is issued over the Data Link Metalanguage control channel. DESCRIPTION The udi_dlu_unbind_req operation is used when the DLP wishes to close down an active binding between itself and the DLU. All data transfer ceases, any queued data is discarded, and the data channel(s) are closed. The control channel may be used by the DLU to issue a subsequent udi_dlp_bind_req to the DLP if desired or it may also be closed. Page 18 of 35

NAME udi_dlp_unbind_ack void udi_dlp_unbind_ack ( udi_dl_cb_t *cb, udi_status_t status); is a pointer to a Data Link Metalanguage standard control block. status indicates the success or failure of the data link unbind request. TARGET CHANNEL The udi_dlp_unbind_ack operation is issued over the same Data Link Metalanguage control channel through which the corresponding udi_dlu_unbind_req operation was received. DESCRIPTION Response to a udi_dlu_unbind_req operation. After this operation is performed, the DLU will no longer attempt to transmit packets or to establish additional data transfer channels between itself and the DLP unless another udi_dlp_bind_req has been issued and handshaked before. Likewise, the DLP will stop delivering incoming packets to the DLU unless it has been bound again. TODO: Explain Status codes. Page 19 of 35

NAME udi_dlp_ctrl_req void udi_dlp_ctrl_ack ( udi_dl_ctrl_cb_t *cb ); is a pointer to a Data Link Metalanguage control operation control block. TARGET CHANNEL The udi_dlp_ctrl_req operation is issued over the Data Link Metalanguage control channel. DESCRIPTION The udi_dlp_ctrl_req operation is used to configure operation of the DLP, the NIC driver and the network hardware. The network configuration operations are explained in more detail in the description of the udi_dl_ctrl_cb_t structure. This request cannot be aborted. Page 20 of 35

NAME udi_dlu_ctrl_ack void udi_dlu_ctrl_ack ( udi_dl_ctrl_cb_t *cb, udi_status_t status ); is a pointer to a Data Link Metalanguage control operation control block. status indicates success or failure of the corresponding control request. TARGET CHANNEL The udi_dlu_ctrl_ack operation is issued over the Data Link Metalanguage control channel in response to a corresponding udi_dlp_ctrl_req operation. DESCRIPTION The udi_dlu_ctrl_ack operation confirms a previous udi_dlp_ctrl_req operation and delivers status information. STATUS VALUES UDI_OK indicates that the network control operation succeeded. UDI_STAT_NOT_UNDERSTOOD indicates that the control operation parameters were invalid. UDI_STAT_RESOURCE_UNAVAIL indicates that the DLP or ND did not have and could not obtain the necessary resources to satisfy the request. UDI_STAT_HW_PROBLEM indicates that the request could not be satisfied due to hardware problems or limitations. Page 21 of 35

NAME udi_dlp_rx_chan_req void udi_dlp_rx_chan_req ( udi_dl_cb_t *cb, udi_index_t rx_chan_index, void *dlp_sap_addr, udi_boolean_t pass_whole_pkt ); is a pointer to a Data Link Metalanguage standard control block. rx_chan_index is the index of the data receive channel to be created between the DLP and the DLU by synchronizing via udi_channel_spawn operations. dlp_sap_addr is a protocol-specific description of a service access point address to be used for that receive channel. The service access point address specifies which data link packet should be forwarded over the requested receive channel. The pointer itself is set by the environment, and must not be modified by the driver. pass_whole_pkt is a flag that if set to TRUE instructs the DLP to pass the entire data link PDU (instead of the SDU) up to the DLU. TARGET CHANNEL The udi_dlp_rx_chan_req operation is issued over the Data Link Metalanguage control channel. DESCRIPTION The udi_dlp_rx_chan_req operation is used to establish a receive data transfer channel between the DLP and the DLU. The DLU spawns one end of the data transfer channel and then issues this request, which causes the DLP to create its end of the same channel (using the rx_chan_index parameter to identify the channel being spawned). The channel will then be used by the DLP to report incoming packets to the DLU. The dlp_sap_addr parameter encodes the address of a service access point (or service user) in a protocol-specific manner. This parameter allows the DLP to decide which incoming packets should be indicated to the service user over the receive channel. The size and layout of the dlp_sap_addr structure must be specified using the inline_size and inline_layout members of the udi_cb_init_t structure used to associate this control block to a control block index (i.e. dlp_sap_addr is a UDI_DL_INLINE_DRIVER_TYPED field). TODO: Better explain SAP address. Rename SAP address, as this is probably a misnomer. What s a better name? Page 22 of 35

NAME udi_dlu_rx_chan_ack void udi_dlu_rx_chan_ack ( udi_dl_cb_t *cb, udi_status_t status ); is a pointer to a Data Link Metalanguage standard control block. status indicates the success or failure of the channel allocation request. TARGET CHANNEL The udi_dlu_rx_chan_ack operation is issued over the same Data Link Metalanguage control channel that the corresponding udi_dlp_rx_chan_req was delivered over. DESCRIPTION Response to udi_dlp_rx_chan_req. The udi_dlu_rx_chan_ack operation acknowledges the channel creation request and informs the DLU about the success of the request. If the operation was successful, the DLP will henceforward deliver incoming packets over the newlybound channel that match the SAP specification identified by the dlp_sap parameter in the udi_dlp_chan_req operation. TODO: Explain Status codes. Page 23 of 35

NAME udi_dlp_tx_chan_req void udi_dlp_tx_chan_req ( udi_dl_cb_t *cb, udi_index_t tx_chan_index, void *default_qos ); is a pointer to a Data Link Metalanguage standard control block. tx_chan_index is the index of the data transmit channel to be created between the DLP and the DLU by synchronizing via udi_channel_spawn operations. default_qos is a pointer to a memory structure describing the default Quality-of-Service constraints to be used for transmitting on the transmit channel to be created. This parameter can be NULL, indicating that the DLU does not request default QoS constraints for this channel. TARGET CHANNEL The udi_dlp_tx_chan_req operation is issued over the Data Link Metalanguage control channel. DESCRIPTION The udi_dlp_tx_chan_req operation is used to establish a transmit data transfer channel between the DLP and the DLU. The DLU spawns one end of the data transfer channel and then issues this request, which causes the DLP to create its end of the same channel (using the tx_chan_index parameter to identify the channel). The newly created channel will then be used by the DLU to transmit data to the DLP. If non-null, the memory pointed to by the default_qos member must have been allocated as moveable, and must point to a valid structure of type udi_qos_constraints_t. Page 24 of 35

NAME udi_dlu_tx_chan_ack void udi_dlu_tx_chan_ack ( udi_dl_cb_t *cb, udi_status_t status ); is a pointer to a Data Link Metalanguage standard control block. status indicates the success or failure of the channel allocation request. TARGET CHANNEL The udi_dlu_tx_chan_ack operation is issued over the same Data Link Metalanguage control channel that the corresponding udi_dlp_tx_chan_req was delivered over. DESCRIPTION Response to udi_dlp_tx_chan_req. The udi_dlu_tx_chan_ack operation acknowledges the channel creation request and informs the DLU about the success of the request. If the operation was successful, the DLU can start transmitting packets over the newly-bound channel. TODO: Explain Status codes. Page 25 of 35

NAME udi_dl_tx_cb_t typedef struct ( udi_cb_t gcb; udi_dl_tx_cb_t *chain; udi_buf_t *tx_buf; void *tx_addr; } udi_dl_tx_cb_t; /* Data Link Transmit Control Block Group Number */ #define UDI_DL_TX_CB_NUM 4 MEMBERS gcb chain is the generic control block which includes a pointer to the scratch space associated with this block and the channel context for the associated channel. The driver may use the scratch space while it owns the control block, but the values are not guaranteed to persist across channel operations. is a pointer to the next udi_dl_tx_cb_t structure (and associated SDU buffer) for this operation. The DLP and DLU will use this field to batch a number of transmit requests or ready s into a single metalanguage operation. The DLP, DLU, or environment are free to divide a chain at any point and implement explicit operations for each resulting portion of the chain, but performance concerns would indicate that processing the entire chain as a batch is highly desirable. The end of a chain is indicated by a NULL pointer. tx_buf is the buffer describing the SDU to be transmitted. This field must be NULL for the udi_dlu_tx_rdy operation and is used only for the udi_dlp_tx_req operation, for which the contents of the buffer are guaranteed to be preserved across a channel. tx_addr is a pointer to an inline memory structure describing the address to which the attached SDU should be sent. The format of this structure is protocol-specific. The pointer itself is set by the environment when the control block is allocated, and must not be modified by the driver. DESCRIPTION The udi_dl_tx_cb_t structure is passed from the DLP to the DLU to indicate its capability for transmitting a SDU; the DLU subsequently attaches an SDU buffer to this control block and returns it to the DLP for transmission. The DLU can only pass SDUs to the DLP when it has available control blocks. This mechanism implements flow control between the DLP and the DLU by requiring the DLP to supply the DLU with all usable udi_dl_tx_cb_t structures (i.e. the DLU must not allocate structures of this type). This control block must be declared by specifying the control block index value UDI_DL_TX_CB_NUM in a udi_cb_init_t in the driver s udi_init_info. The size and layout of the tx_addr structure must be specified using the inline_size and inline_layout members of that udi_cb_init_t structure (i.e. tx_addr is a UDI_DL_INLINE_DRIVER_TYPED field). Page 26 of 35

NAME udi_dlu_tx_rdy void udi_dlu_tx_rdy ( udi_dl_tx_cb_t *cb ); is a pointer to a Data Link Metalanguage transmit control block. TARGET CHANNEL The udi_dlu_tx_rdy operation is issued over a Data Link Metalanguage transmit channel that was previously established using the udi_dlp_tx_chan_req and udi_dlu_tx_chan_ack operations. DESCRIPTION The udi_dlu_tx_rdy operation is used to indicate to the DLU that the DLP can transmit a SDU when the DLU has one available. The DLU maintains a pool of control blocks of type udi_dl_tx_cb_t for SDU transmission. The udi_dlu_tx_rdy operation makes an additional control block available to the DLU, which can then start or continue transmitting over the channel associated with the control block. This is used to perform flow control. Multiple udi_dl_tx_cb_t structures can be chained together (using the chain pointer). Single control blocks as well as a chain of control blocks can be passed using this operation. Page 27 of 35

NAME udi_dlp_tx_req void udi_dlp_tx_req ( udi_dl_tx_cb_t *cb ); is a pointer to a Data Link Metalanguage transmit control block. TARGET CHANNEL The udi_dlp_tx_req operation is issued over a Data Link Metalanguage transmit channel that was previously established using the udi_dlp_tx_chan_req and udi_dlu_tx_chan_ack operations. DESCRIPTION The udi_dlp_tx_req operation is called by the DLU to pass one or more SDU buffers to the DLP for transmission over the DLP's associated interface. Each SDU buffer is attached to a separate udi_dl_tx_cb_t control block. Multiple packet buffers may be passed by chaining control blocks together (using the chain field in the udi_dl_tx_cb_t structure). Each packet buffer represents one Data Link SDU (Service Data Unit), i.e. usually one higher-level PDU (Protocol Data Unit). The DLP will perform transmission of the packet according to the default Quality-of-Service constraints associated with the transmit channel used for the operation. If no default QoS constraints are associated with the channel, the DLP will provide an implementation-dependent suitable default service. Page 28 of 35

NAME udi_dlp_tx_qos_req void udi_dlp_tx_qos_req ( udi_dl_tx_cb_t *cb, void *tx_qos ); is a pointer to a Data Link Metalanguage transmit control block. tx_qos is a pointer to a memory structure describing the Quality-of-Service constraints associated with the attached SDU. For the format of this structure pointed to by this member, refer to the description of udi_dl_qos_constraints_t. Must not be NULL. TARGET CHANNEL The udi_dlp_tx_qos_req operation is issued over a Data Link Metalanguage transmit channel that was previously established using the udi_dlp_tx_chan_req and udi_dlu_tx_chan_ack operations. DESCRIPTION The udi_dlp_tx_qos_req operation is called by the DLU to pass one or more SDU buffers to the DLP for transmission over the DLP's associated interface. Each SDU buffer is attached to a separate udi_dl_tx_cb_t control block. Multiple packet buffers may be passed by chaining control blocks together (using the chain field in the udi_dl_tx_cb_t structure). Each packet buffer represents one Data Link SDU (Service Data Unit), i.e. usually one higher-level PDU (Protocol Data Unit). The DLP will perform transmission of the packet according to the Quality-of-Service constraints specified in tx_qos. The memory pointed to by tx_qos must have been allocated as moveable, and must point to a valid structure of type udi_dl_qos_constraints_t. Page 29 of 35

NAME udi_dlp_tx_qos_modify_req void udi_dlp_tx_qos_modify_req ( udi_dl_cb_t *cb, void *new_default_qos ); is a pointer to a Data Link Metalanguage standard control block. new_default_qos is a pointer to a memory structure describing the Quality-of-Service constraints associated with the attached SDU. For the format of the structure pointed to by this member, refer to the description of udi_dl_qos_constraints_t. Must not be NULL. TARGET CHANNEL The udi_dlp_tx_qos_modify_req operation is issued over a Data Link Metalanguage transmit channel that was previously established using the udi_dlp_tx_chan_req and udi_dlu_tx_chan_ack operations. DESCRIPTION The udi_dlp_tx_qos_modify_req operation is called by the DLU to change the default Quality-of-Service constraints associated with the transmit channel associated with the control block cb. After issuing this operation, no udi_dlp_tx_req operation should be issued over the same transmit channel until the corresponding udi_dlu_tx_qos_modify_ack operation is delivered to the DLU. The memory pointed to by new_default_qos must have been allocated as moveable, and must point to a valid structure of type udi_dl_qos_constraints_t. Page 30 of 35

NAME udi_dlu_tx_qos_modify_ack void udi_dlu_tx_qos_modify_ack ( udi_dl_cb_t *cb, udi_status_t status ); is a pointer to a Data Link Metalanguage standard control block. status indicates the completion status of the corresponding udi_dlp_tx_qos_modify_req operation. TARGET CHANNEL The udi_dlu_tx_qos_modify_ack operation is issued over the same Data Link Metalanguage transmit channel that was used to deliver the corresponding udi_dlp_tx_qos_modify_req operation. DESCRIPTION The udi_dlu_tx_qos_modify_ack operation is called by the DLP to complete changing the default Quality-of-Service constraints associated with the transmit channel over which the operation was delivered. The DLU can resume transmitting over the associated transmit channel as soon as this operation has been delivered. Page 31 of 35

NAME udi_dl_rx_cb_t typedef struct ( udi_cb_t gcb; udi_dl_rx_cb_t *chain; udi_buf_t *rx_buf; void *rx_qos; TODO: Do we need rx_status or anything else? Do we even need qos_constraints? } udi_dl_rx_cb_t; /* Data Link Transmit Control Block Group Number */ #define UDI_DL_RX_CB_NUM 5 MEMBERS gcb chain is the generic control block which includes a pointer to the scratch space associated with this block and the channel context for the associated channel. The driver may use the scratch space while it owns the control block, but the values are not guaranteed to persist across channel operations. is a pointer to the next udi_dl_rx_cb_t structure (and associated SDU buffer) for this operation. The DLP and DLU will use this field to batch a number of transmit requests or ready s into a single metalanguage operation. The DLP, DLU, or environment are free to divide a chain at any point and implement explicit operations for each resulting portion of the chain, but performance concerns would indicate that processing the entire chain as a batch is highly desirable. The end of a chain is indicated by a NULL pointer. rx_buf is the buffer containing the SDU that has been received. This field is used to pass an empty buffer to the DLP (rx_buf->buf_size == 0) in the udi_dlp_rx_rdy operation. It is filled in with the actual SDU for each udi_dlu_rx_ind operation. rx_qos is a pointer to an inline memory structure describing the Quality-of-Service constraints associated with the attached SDU. The pointer itself is set by the environment and must not be modified by the driver. This member points to a udi_qos_constraints_t structure. DESCRIPTION The udi_dl_rx_cb_t structure is passed from the DLU to the DLP to indicate a capability for receiving a SDU; the DLP subsequently attaches SDU and QoS-constraint buffers to this control block and returns it to the DLU upon valid reception of a relevant SDU. Only successfully received SDUs will be processed and reported to the DLU. This control block must be declared by specifying the control block index value UDI_DL_RX_CB_NUM in a udi_cb_init_t in the driver s udi_init_info. Page 32 of 35

NAME udi_dlp_rx_rdy void udi_dlp_rx_rdy ( udi_dl_rx_cb_t *cb ); is a pointer to a Data Link Metalanguage receive control block. TARGET CHANNEL The udi_dlp_rx_rdy operation is issued over a Data Link Metalanguage receive channel that was previously established using the udi_dlp_rx_chan_req and udi_dlu_rx_chan_ack operations. DESCRIPTION The udi_dlp_rx_rdy operation is used to indicate to the DLP that the DLU can process a SDU when the DLP receives one from the underlying interface. The DLP maintains a pool of control blocks of type udi_dl_rx_cb_t for SDU reception. The udi_dlp_rx_rdy operation makes an additional colntrol block available to the DLU, which can then start or continue transmitting over the channel associated with the control block. This is used to perform flow control. Multiple udi_dl_rx_cb_t structures can be chained together (using the chain pointer). Single control blocks as well as a chain of control blocks can be passed using this operation. Page 33 of 35

NAME udi_dlu_rx_ind void udi_dlu_rx_ind ( udi_dl_rx_cb_t *cb ); is a pointer to a Data Link Metalanguage receive control block. TARGET CHANNEL The udi_dlu_rx_ind operation is issued over a Data Link Metalanguage receive channel that was previously established using the udi_dlp_rx_chan_req and udi_dlu_rx_chan_ack operations. DESCRIPTION The udi_dlu_rx_ind operation is called by the DLP to indicate to the DLU that the data link driver has received a relevant network-level SDU. Only SDUs that match the SAP address specified when the receive channel was created will be reported over that receive channel. Only valid SDUs will be reported, erroneous data link packets will be silently dropped. The cb can point to a single udi_dl_rx_cb_t structure, or multiple structures can be chained together using the chain pointer in the structure. Once the DLU is done processing the SDU contained in this (these) control block s (blocks ) rx_buf field, the control block (blocks) are returned to the DLP using the udi_dlp_rx_rdy operation. If the pass_whole_pkt argument in the udi_dlp_rx_chan_req operation used to create the receive channel over which the packet is to be delivered was set to TRUE, the DLP will not perform any decapsulation of the data link PDU, but will pass the original PDU to the DLU. Note that this requires the DLU to understand the format of the DLP s protocol format. Page 34 of 35

Enumeration Attributes Note: For all attributes of type UDI_ATTR_TYPE_STRING in the following table, the size range indication includes the terminating NUL character. ATTRIBUTE NAME TYPE SIZE DESCRIPTION dl_name UDI_ATTR_STRING 1..33 Name of the Data Link Protocol supported by this DLP. TODO: Define known names in this spec. dl_rev UDI_ATTR_UBIT32 4 addr_type UDI_ATTR_STRING 1..33 np_name UDI_ATTR_STRING 1..33 Revision of the Data Link Protocol supported by this DLP. Name identifying a format for addressing information understood by this DLP. System name of a network-level protocol entity that can be bound to this DLP. TODO: Do we need this? Shouldn t bindings be enforced through directed enumeration? if_name UDI_ATTR_STRING 1..11 System Interface name this DLP is bound to. if_media UDI_ATTR_STRING 1..8 Media type string as defined in NIC meta. identifier UDI_ATTR_STRING 1..41 physical_label UDI_ATTR_STRING 1..64 String representation of the Factory MAC address of the interface that this DLP supports, encoded in the same way as the attribute with the same name in the NIC meta. Driver-specified string uniquely identifying this DLP instance (optional). TODO: Define Attribute Ranking. Page 35 of 35