|
|
United States-English | |
|
|
 |
|
HP DLPI Programmer's Guide: HP-UX 11i v2 > Chapter 2 DLPI
Primitives
Local Management Primitives |
|
|
This section describes the local management service primitives. These primitives support the information reporting, Attach, and Bind. Once a stream has been opened by a DLS user, these primitives initialize the stream, preparing it for use. The PPA associated with each stream must be initialized before the DLS provider can transfer data over the medium. The initialization and de-initialization of the PPA is a network management issue, but DLPI must address the issue because of the impact such actions have on a DLS user. More specifically, DLPI requires the DLS provider to initialize the PPA associated with a stream at some point before it completes the processing of the DL_BIND_REQ. Guidelines for initialization and de-initialization of a PPA by a DLS provider are presented here. A DLS provider may initialize a PPA using one of the following methods:
A specific DLS provider may support either of these methods, or possibly combination of the two, but the method implemented has no impact on the DLS user. From the DLS user’s viewpoint, the PPA is guaranteed to be initialized on receipt of a DL_BIND_ACK. For automatic initialization, it implies that the DL_BIND_ACK may not be issued until the initialization is complete. If pre-initialization is not performed and/or automatic initialization fails, the DLS provider will fail the DL_BIND_REQ. Two errors, DL_INITFAILED and DL_NOTINIT, may be returned in the DL_ERROR_ACK response to a DL_BIND_REQ if PPA initialization fails. DL_INITFAILED is returned when a DLS provider supports automatic PPA initialization, but the initialization attempt failed. DL_NOTINIT is returned when the DLS provider requires pre-initialization, but the PPA is not initialized before the DL_BIND_REQ is received. A DLS provider may handle PPA de-initialization using one of the following methods:
A specific DLS provider may support any of these methods, or possibly combination of them, but the method implemented has no impact on the DLS user. From the DLS user’s viewpoint, the PPA is guaranteed to be initialized and available for transmission until it closes or unbinds the stream associated with the PPA. DLS provider specific addendum documentation should describe the method chosen for PPA initialization and de-initialization. This primitive is used to obtain a list of all the valid PPAs currently installed in the system. This message consists of one M_PCPROTO message block which contains the following structure. Format typedef struct { Parameters dl_primitive
State The message is valid in any State in which a local acknowledgment is not pending, as described in Appendix B, Allowable Sequence of DLPI Primitives, of the DLPI 2.0 specification. New State The resulting state is unchanged. Response The DLPI driver responds to this request with a DL_HP_PPA_ACK. This primitive is sent in response to a DL_HP_PPA_REQ; it conveys information on each valid PPA currently installed in the system. This message consists of one M_PCPROTO message block, which contains the following structure and information: Format typedef struct { Parameters dl_primitive
dl_length
dl_count
dl_offset
dl_next_offset
dl_ppa
dl_hw_path
dl_mac_type
dl_phys_addr
dl_addr_length
dl_mjr_num
dl_name
dl_instance_num
dl_mtu
dl_hdw_state
dl_module_id_1
dl_module_id_2
dl_arpmod_name
dl_nmid
dl_reserved[1,2]
State The message is valid in any State in response to a DL_PPA_REQ. New State The resulting state is unchanged. Requests information of the DLS provider about the DLPI stream. This information includes a set of provider-specific parameters, as well as the current state of the interface. The message consists of one M_PCPROTO message block, which contains the following structure. Format typedef struct { Parameters dl_primitive
State The message is valid in any state in which a local acknowledgment is not pending, as described in Appendix B, Allowable Sequence of DLPI Primitives, of the DLPI 2.0 specification. New State The resulting state is unchanged. This message is sent in response to DL_INFO_REQ; it conveys information about the DLPI stream to the DLS user. This message consists of one M_PCPROTO message block, which contains the following structure. Format typedef struct { Parameters dl_primitive
dl_max_sdu
dl_min_sdu
dl_addr_length
dl_mac_type
dl_reserved
dl_current_state
dl_sap_length
dl_service_mode
dl_qos_length
dl_qos_offset
dl_qos_range_length
dl_qos_range_offset
dl_provider_style
dl_addr_offset
dl_version
dl_brdcst_addr_length
dl_brdcst_addr_offset
dl_growth
State The message is valid in any state in response to a DL_INFO_REQ. New State The resulting state is unchanged. DL_HP_NOTIFY_EVENT_REQ requests for notification of link DOWN and link UP events. The DLS user who requests for DL_HP_LINK_STATE_CHANGE receives DL_LINK_DOWN_IND and DL_LINK_UP_IND when the link state changes. For more information on DL_LINK_DOWN_IND and DL_LINK_UP_IND, refer to “DL_LINK_DOWN_IND” and “DL_LINK_UP_IND”, respectively. This message consists of one M_PROTO message block, which contains the following structure: typedef struct { uint32_t dl_primitive; dl_hp_event_t dl_event; uint32_t dl_reserved1; uint32_t dl_reserved2;} dl_hp_notify_event_req_t; Parameters dl_primitive
dl_event
Table 2-1 dl_hp_event_t Enumeration
dl_reserved1
dl_reserved2
State The message is valid in DL_IDLE or DL_UNBOUND state. New State The resulting state is unchanged. Response If the notify request is successful, DL_OK_ACK is sent to the DLS user. If the request fails, DL_ERROR_ACK is returned, and the resulting state is unchanged. Reason for Failure DL_OUTSTATE
DL_SYSERR
DLPI sends this event upstream to the streams that have requested for the link state change notifications using the DL_NOTIFY_LINK_STATE_REQ primitive. The receipt of this event indicates that the physical driver instance has entered the DOWN operational state. This message consists of one M_PCPROTO message block, which contains the following structure: typedef struct{ Parameters dl_primitive
DLPI sends this event upstream to the streams that have requested for the link state change notifications using the DL_NOTIFY_LINK_STATE_REQ primitive. The receipt of this event indicates that the physical driver instance has entered the UP operational state. This message consists of one M_PCPROTO message block, which contains the following structure. typedef struct { Parameters dl_primitive
Requests the DLS provider to associate a physical point of attachment (PPA) with a stream. The message consists of one M_PROTO message block, which contains the following structure. Format typedef struct { Parameters dl_primitive
dl_ppa
State The message is valid in state DL_UNATTACHED. New State The resulting state is DL_ATTACH_PENDING. Response If the attach request is successful, DL_OK_ACK is sent to the DLS user resulting in state DL_UNBOUND. If the request fails, DL_ERROR_ACK is returned and the resulting state is unchanged. Reasons for Failure DL_BADPPA
DL_ACCESS
DL_OUTSTATE
DL_SYSERR
Table 2-2 Error Return Values
Requests the DLS provider to disassociate a physical point of attachment (PPA) with a stream. The message consists of one M_PROTO message block, which contains the following structure. Format typedef struct { Parameters dl_primitive
State The message is valid in state DL_UNBOUND. New State The resulting state is DL_DETACH_PENDING. Response If the detach request is successful, DL_OK_ACK is sent to the DLS user resulting in state DL_UNATTACHED. If the request fails, DL_ERROR_ACK is returned and the resulting state is unchanged. Reasons for Failure DL_OUTSTATE
DL_SYSERR
Requests the DLS provider to bind a DLSAP to the stream. The DLS user must identify the address of the DLSAP to be bound to the stream. The DLS user also indicates whether it will accept incoming connection requests on the stream. Finally, the request directs the DLS provider to activate the stream associated with the DLSAP. The message consists of one M_PROTO message block, which contains the following structure. Format typedef struct { Parameters dl_primitive
dl_sap
dl_max_conind
dl_service_mode
dl_conn_mgmt
dl_xidtest_flg
State The message is valid in state DL_UNBOUND. New State The resulting state is DL_BIND_PENDING. Response If the bind request is successful, DL_BIND_ACK is sent to the DLS user resulting in state DL_IDLE. If the request fails, DL_ERROR_ACK is returned and the resulting state is unchanged. Reasons for Failure DL_BADADDR
DL_INITFAILED
DL_NOTINIT
DL_ACCESS
DL_BOUND
DL_OUTSTATE
DL_NOADDR
DL_UNSUPPORTED
DL_SYSERR
DL_NOAUTO
DL_NOXIDAUTO
DL_OUTSTATE
Security Containment With the Security Containment product version B.11.23.01 or later, HP DLPI will perform additional checks for DL_BIND_REQ primitive, namely:
See “Fine-grained Privileges with Security Containment Release” for more details. Reports the successful bind of a DLSAP to a stream, and returns the bound DLSAP address to the DLS user. This primitive is generated in response of a DL_BIND_REQ. The message consists of one M_PCPROTO message block, which contains the following structure. Format typedef struct { Parameters dl_primitive
dl_sap
dl_addr_length
dl_addr_offset
dl_max_conind
dl_xidtest_flg
State The message is valid in state DL_BIND_PENDING. New State The resulting state is DL_IDLE. Requests the DLS provider to unbind the DLSAP that had been bound by a previous DL_BIND_REQ from this stream. The message consists of one M_PROTO message block, which contains the following structure. Format typedef struct { Parameters dl_primitive
State The message is valid in state DL_IDLE. New State The resulting state is DL_UNBIND_PENDING. Response If the unbind request is successful, DL_OK_ACK is sent to the DLS user resulting in state DL_UNBOUND. If the request fails, DL_ERROR_ACK is returned and the resulting state is unchanged. Reasons for Failure DL_OUTSTATE
DL_SYSERR
Requests the DLS provider bind a subsequent DLSAP to the stream. The DLS user must identify the address of the subsequent DLSAP to be bound to the stream. Format The message consists of one M_PROTO message block, which contains the following structure. typedef struct { Parameters dl_primitive
dl_subs_sap_offset
dl_subs_sap_length
dl_subs_bind_class
State The message is valid in state DL_IDLE. New State The resulting state is DL_SUBS_BIND_PND. Response If the subsequent bind request is successful, DL_SUBS_BIND_ACK is sent to the DLS user resulting in state DL_IDLE. Reasons for Failure DL_BADADDR
DL_ACCESS
DL_OUTSTATE
DL_SYSERR
DL_UNSUPPORTED
DL_TOOMANY
Security Containment With the Security Containment release, DLPI will perform additional checks for DL_SUBS_BIND_REQ primitive, namely:
See “Fine-grained Privileges with Security Containment Release” for more details. Reports the successful bind of a subsequent DLSAP to a stream, and returns the bound DLSAP address to the DLS user. This primitive is generated in response to a DL_SUBS_BIND_REQ. Format The message consists of one M_PROTO message block, which contains the following structure. typedef struct { Parameters dl_primitive
dl_subs_sap_offset
dl_subs_sap_length
State The message is valid in state DL_SUBS_BIND_PND. New State The resulting state is DL_IDLE. Requests the DLS provider to unbind the DLSAP that had been bound by a previous DL_SUBS_BIND_REQ from this stream. Format The message consists of one M_PROTO message block, which contains the following structure. typedef struct { Parameters dl_primitive
dl_subs_sap_offset
dl_subs_sap_length
State The message is valid in state DL_IDLE. New State The resulting state is DL_SUBS_UNBIND_PND. Response If the unbind request is successful, a DL_OK_ACK is sent to the DLS User. The resulting state is DL_IDLE. If the request fails, DL_ERROR_ACK is returned and the resulting state is unchanged. Reasons for Failure DL_OUTSTATE
DL_SYSERR
DL_BADADDR
Requests the DLS Provider to enable specific multicast addresses on a per Stream basis. It is invalid for a DLS Provider to pass upstream messages that are destined for any address other than those explicitly enabled on that Stream by the DLS User. Format The message consists of one M_PROTO message block, which contains the following structure: typedef struct { Parameters dl_primitive
dl_addr_length
dl_addr_offset
State This message is valid in any state in which a local acknowledgment is not pending with the exception of DL_UNATTACHED. New State The resulting state is unchanged. Response If the enable request is successful, a DL_OK_ACK is sent to the DLS user. If the request fails, DL_ERROR_ACK is returned and the resulting state is unchanged. Reasons for Failure DL_BADADDR
DL_TOOMANY
DL_OUTSTATE
DL_NOTSUPPORTED
DL_SYSERR
Requests the DLS Provider to disable specific multicast addresses on a per Stream basis. Format The message consists of one M_PROTO message block, which contains the following structure: typedef struct { Parameters dl_primitive
dl_addr_length
dl_addr_offset
State This message is valid in any state in which a local acknowledgment is not pending with the exception of DL_UNATTACHED. New State The resulting state is unchanged. Response If the disable request is successful, a DL_OK_ACK is sent to the DLS user. If the request fails, DL_ERROR_ACK is returned and the resulting state is unchanged. Reasons for Failure DL_BADADDR
DL_NOTENAB
DL_OUTSTATE
DL_NOTSUPPORTED
DL_SYSERR
This primitive requests the DLS Provider to enable promiscuous mode on a per Stream basis, either at the physical level or at the SAP level. The DL Provider will route all received messages on the media to the DLS User until either a DL_DETACH_REQ or a DL_PROMISCOFF_REQ is received or the Stream is closed.
Format The message consists of one M_PROTO message block, which contains the following structure. typedef struct { Parameters dl_primitive
dl_level
State The message is valid in any state when there is no pending acknowledgment. New State The resulting state is unchanged. Response If enabling of promiscuous mode is successful, a DL_OK_ACK is returned. Otherwise, a DL_ERROR_ACK is returned. Reasons for Failure DL_OUTSTATE
DL_SYSERR
DL_NOTSUPPORTED
DL_UNSUPPORTED
Security Containment With the Security Containment product version B.11.23.01 or later, HP DLPI will allow enabling and disabling of promisucous mode only for users with PRIV_NETPROMISCUOUS privilege. See “Fine-grained Privileges with Security Containment Release” for more details. This primitive requests the DLS Provider to disable promiscuous mode on a per Stream basis, either at the physical level or at the SAP level.
Format The message consists of one M_PROTO message block, which contains the following structure. typedef struct { Parameters dl_primitive
dl_level
State The message is valid in any state in which the promiscuous mode is enabled and there is no pending acknowledgment. New State The resulting state is unchanged. Response If the promiscuous mode disabling is successful, a DL_OK_ACK is returned. Otherwise, a DL_ERROR_ACK is returned. Reasons for Failure DL_OUTSTATE
DL_SYSERR
DL_NOTSUPPORTED
DL_NOTENAB
Security Containment With the Security Containment product version B.11.23.01 or later, HP DLPI will allow enabling and disabling of promiscuous mode only for users with PRIV_NETPROMISCUOUS privilege. See “Fine-grained Privileges with Security Containment Release” for more details. DL_HP_HW_RESET_REQ resets the physical interface. Format The message consists of one M_PROTO message block, which contains the following structure: typedef struct { Parameters dl_primitive
State The message is valid in DL_IDLE or DL_UNBOUND state. New State The resulting state is unchanged. Response If the request is successful, DL_OK_ACK is returned. If the request fails, DL_ERROR_ACK is returned. Reason for Failure DL_OUTSTATE
DL_BADPRIM
DL_SYSERR
Security Containment With the Security Containment product version B.11.23.01 or later, HP DLPI will allow network related administrative tasks such as resetting the statistics on the interface only for users with PRIV_NETADMIN privilege. See “Fine-grained Privileges with Security Containment Release” for more details.
DL_HP_RESET_STATS_REQ resets the statistics of an interface (physical or logical). Format The message consists of one M_PROTO message block, which contains the following structure: typedef struct { Parameters dl_primitive
State The message is valid in DL_IDLE or DL_UNBOUND state. New State The resulting state is unchanged. Response If the request is successful, DL_OK_ACK is returned. If the request fails, DL_ERROR_ACK is returned. Reason for Failure DL_OUTSTATE
DL_BADPRIM
DL_SYSERR
Security Containment With the Security Containment product version B.11.23.01 or later, HP DLPI will allow network related administrative tasks such as resetting the statistics on the interface only for users with PRIV_NETADMIN privilege. See “Fine-grained Privileges with Security Containment Release” for more details. Acknowledges to the DLS user that a previously issued request primitive was received successfully. It is only initiated for those primitives that require a positive acknowledgment. Format The message consists of one M_PCPROTO message block, which contains the following structure. typedef struct { Parameters dl_primitive
dl_correct_primitive
State The message is valid in response to a DL_ATTACH_REQ, DL_DETACH_REQ, DL_UNBIND_REQ, DL_CONNECT_RES, DL_RESET_RES, DL_DISCON_REQ, DL_SUBS_UNBIND_REQ, DL_PROMISCON_REQ, DL_ENABMULTI_REQ, DL_DISADMULTI_REQ, DL_HP_HW_RESET_REQ, DL_HP_RESET_STATS_REQ, or DL_PROMISCOFF_REQ from any of several states as defined in Appendix B, Allowable Sequence of DLPI Primitives, of the DLPI 2.0 specification. New State The resulting state depends on the current state and is defined fully in Appendix B, Allowable Sequence of DLPI Primitives, of the DLPI 2.0 specification. Informs the DLS user that the previous request or response was invalid. Format The message consists of one M_PCPROTO message block, which contains the following structure: typedef struct { Parameters dl_primitive
dl_error_primitive
dl_errno
dl_unix_errno
State The message is valid in every state where an acknowledgement or confirmation of a previous request or response is pending. New State The resulting state is that from which the acknowledged request or response was generated. This section describes optional primitives. Some of these primitives may not be supported by the DLS provider. Requests the DLS provider to return the physical address associated with the stream depending upon the value of the address type selected in the request. Format The message consists one M_PROTO message block containing the structure shown below. typedef struct { Parameters dl_primitive
dl_addr_type
State The message is valid in any attached state in which a local acknowledgement is not pending. For a style 2 provider, this would be after a PPA is attached using the DL_ATTACH_REQ. For a style 1 provider, the PPA is implicitly attached after the stream is opened. New State The resulting state is unchanged. Response The provider responds to the request with a DL_PHYS_ADDR_ACK if the request is supported. Otherwise, a DL_ERROR_ACK is returned. Reasons for Failure DL_NOTSUPPORTED
DL_OUTSTATE
This primitive returns the value for the physical address to the link user in response to a DL_PHYS_ADDR_REQ. Format The message consists one M_PROTO message block containing the structure shown below. typedef struct { Parameters dl_primitive
dl_addr_length
dl_addr_offset
State The message is valid in any state in response to a DL_PHYS_ADDR_REQ. New State The resulting state is unchanged. Sets the physical address value for all streams for that provider for a particular PPA. DLPI requires applications using this exported API to run as root. Format The message consists one M_PROTO message block containing the structure shown below. typedef struct { Parameters dl_primitive
dl_addr_length
dl_addr_offset
State The message is valid in any attached state in which a local acknowledgement is not pending. For a style 2 provider, this would be after a PPA is attached using the DL_ATTACH_REQ. For a style 1 provider, the PPA is implicitly attached after the stream is opened. New State The resulting state is unchanged. Response The provider responds to the request with a DL_OK_ACK on successful completion. Otherwise, a DL_ERROR_ACK is returned. Reasons for Failure DL_BADADDR
DL_NOTSUPPORTED
DL_SYSERR
DL_OUTSTATE
DL_BUSY
Security Containment With the Security Containment product version B.11.23.01 or later, HP DLPI will allow network related administrative tasks such as setting the physical address of an interface only for users with PRIV_NETADMIN privilege. See “Fine-grained Privileges with Security Containment Release” for more details.
Directs the DLS provider to return statistics. Format The message consists one M_PROTO message block containing the structure shown below. typedef struct { Parameters dl_primitive
State The message is valid in any attached state in which a local acknowledgement is not pending. New State The resulting state is unchanged. Response The DLS provider responds to the request with a DL_GET_STATISTICS_ACK if the primitive is supported. Otherwise, a DL_ERROR_ACK is returned. Reasons for Failure DL_NOTSUPPORTED
Returns statistics in response to the DL_GET_STATISTICS_REQ. The content of this statistics block is the following: Format The message consists one M_PROTO message block containing the structure shown below. typedef struct { Parameters dl_primitive
dl_stat_length
dl_stat_offset
State The message is valid in any state in response to a DL_GET_STATISTICS_REQ. New State The resulting state is unchanged. The DL_GET_STATISTICS_ACK returns standard mib and optionally extended mib information for all HP supported networking interfaces. It is up to the DLPI user to check the interface-specific field of the Interface MIB to determine whether there is a transmission MIB. Directs the DLS provider to return 64-bit statistics. Format The message consists one M_PROTO message block that contains the following structure:
Parameters dl_primitive
dl_reserved1
dl_reserved2
State The message is valid in any attached state in which a local acknowledgement is not pending. New State The resulting state is unchanged. Response The DLS provider responds to the request with DL_HP_GET_64BIT_STATS_ACK if the primitive is supported and successful; otherwise, DL_ERROR_ACK is returned. Reasons for Failure DL_NOTSUPPORTED
DL_SYSERR
DL_OUTSTATE
Returns 64-bit statistics in response to the DL_HP_GET_64BIT_STATS_REQ request. Format The message consists one M_PCPROTO message block that contains the following structure:
Parameters dl_primitive
dl_stat_length
dl_stat_offset
dl_reserved1
dl_reserved2
dl_reserved3
State The message is valid in any state in response to a DL_HP_GET_64BIT_STATS_REQ request. New State The resulting state is unchanged. DL_HP_GET_64BIT_STATS_ACK returns standard 64-bit statistics and 32-bit MIB-II statistics. In addition, it returns optionally extended interface-specific MIB information for all the interfaces that support the DL_HP_GET_64BIT_STATS_REQ request. The statistics is structured as Ext_64bit_mib_t, which is defined in <sys/mib.h>. DLPI users can determine whether it includes an interface-specific MIB. Normally, if an interface does not support interface-specific MIB, that part of the statistics is zero.
Requests the DLS Provider to return a list of all currently enabled multicast addresses on a specific LAN interface. Format The message consists one M_PROTO message block containing the structure shown below. typedef struct { Parameters dl_primitive
State The message is valid in any state in which there is not a local acknowledgment pending with the exception of DL_UNATTACHED. New State The resulting state is unchanged. Response If the multicast request is successful, a DL_HP_MULTICAST_LIST_ACK is sent to the DLS user. If the requests fails, DL_ERROR_ACK is returned and the resulting state is unchanged. Reasons for Failure DL_OUTSTATE
DL_SYSERR
Reports the successful completion of a DL_HP_MULTICAST_LIST_REQ primitive. A complete list of the multicast addresses for a specific LAN interface are returned after the control message header. Format The message consists one M_PROTO message block containing the structure shown below. typedef struct { Parameters dl_primitive
dl_offset
dl_length
dl_count
State The message is valid in any state in response to a DL_HP_MULTICAST_LIST_REQ. New State The resulting state is unchanged. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
 Printable version |
|
|
|
|
|
|||||||||||||||
|
|||||||||||||||
