Rtndloctl

RtndIoctl is used to configure certain NIC modes or characteristics.

Syntax

INT RtndIoctl(
    VOID *ndp,
    INT cmd,
    CHAR *pArg
);

Parameters

ndp

Network Device Pointer. Opaque network device identifier.

cmd

Control code to execute.

Arg

Pointer to a control code value. This value may be NULL for some codes.

Return Value

A return value of 0 indicates Success, -1 indicates Failure. The possible error codes are:

Error Code	Meaning
ERROR_BAD_ARGUMENTS	Invalid interface index or queue number.
ERROR_DEVICE_FEATURE_NOT_SUPPORTED	The control code is not supported

IOCTL-specific Error Codes

IOCTL	Error Code	Meaning
RTNAL_IOCTL_SET_INTERRUPT_MODERATION	ERROR_INVALID_PARAMETER	The interval is invalid.
RTNAL_IOCTL_READ_RX_HW_TIMESTAMP	ERROR_INVALID_DATA	The device has no valid recorded receive timestamp.
RTNAL_IOCTL_READ_TX_HW_TIMESTAMP	ERROR_INVALID_DATA	The device has no valid recorded transmit timestamp.
RTNAL_IOCTL_GET_RX_ETHERTYPE_FILTER	ERROR_INVALID_INDEX	The filter index is invalid.
RTNAL_IOCTL_CLEAR_RX_ETHERTYPE_FILTER	ERROR_INVALID_INDEX	The filter index is invalid.
	ERROR_NOT_OWNER	The filter at the specified index belongs to another queue.
RTNAL_IOCTL_SET_RX_ETHERTYPE_FILTER	ERROR_INVALID_INDEX	The filter index is invalid.
	ERROR_NOT_OWNER	The filter at the specified index belongs to another queue.
	ERROR_ALREADY_ASSIGNED	The specified Ethernet type is used by another filter entry.

Remarks

The driver should call RtnGetDataLong with offset 0 to get the driver interface index.

The control codes with names starting with RTNAL are used by NAL and must not be used directly by NAL client applications.

The following commands (passed in the cmd parameter) are possible.

Neither RTX64 NIC drivers nor the RT-TCP/IP Stack support multicast hash tables or address arguments in ENIOADDMULTI and ENIODELMULTI IOCTLs. ENIOADDMULTI, when any address is specified, enables multicast promiscuous mode for a receive queue. When a NULL address is specified for ENIODELMULTI, it removes the driver multicast flag. The driver disables multicast promiscuous mode when no receive queues require multicast.

Command	Description
ENIOCPROMISC	(Optional) Turn on promiscuous mode
ENIOCALL	(Optional) Receive good and bad packets. Non-promisc.
ENIOCNORMAL	(Optional) Receive only good packets. Default mode.
ENIOADDMULTI	(Required) Add multicast route to this NIC (required command, should be implemented). The addr parameter points to an Ethernet address byte string (6 bytes), which indicates the multicast group Ethernet address. RTX64 NIC drivers don’t implement address-based multicast. Instead, ENIOADDMULTI sets a pass all multicast flag for the corresponding Receive Queue. The driver enables the multicast-promiscuous mode if, and only if, at least one Receive Queue has the pass all multicast flag set. Multicast-promiscuous mode is a global NIC setting, not a queue-specific setting. When multicast-promiscuous mode is enabled, all Receive Queues accept multicast packets. When multicast-promiscuous mode is disabled, all Receive Queues reject multicast packets.
ENIODELMULTI	(Required) Delete multicast route from this NIC (required command, should be implemented). The addr parameter points to an Ethernet address byte string (6 bytes), which indicates the multicast group Ethernet address. A NULL buffer argument is used to notify the driver that the receive queue does not need to receive multicast packets. RTX64 NIC drivers don’t implement address-based multicast. Instead, ENIODELMULTI, called with NULL buffer argument, clears the pass all multicast flag of the corresponding Receive Queue. The driver disables multicast-promiscuous mode if, and only if, all Receive Queues have the pass all multicast flag cleared (which is the default state). Mutlicast-promiscuous mode is a global NIC setting, not a queue-specific setting. When multicast-promiscuous mode is enabled, all Receive Queues accept multicast packets. When multicast-promiscuous mode is disabled, all Receive Queues reject multicast packets.
ENIOLINKSTATUS	(Optional) Reports link status. Returns a value of type RTND_MEDIA_CONNECT_STATE.
RTNAL_IOCTL_GET_PCI_BUS_LOCATION	(Required) Reports binary PCI Bus location in the structure of type PRTNAL_PCI_LOCATION pointed by pArg.
RTNAL_IOCTL_SET_INTERRUPT_MODERATION	(Optional) Sets interrupt moderation to the integer value pointed by pArg. Interrupt moderation is the minimal amount of time in nanosecond units between interrupts. Used by RtNalSetInterruptModeration.
RTNAL_IOCTL_GET_SYSTEM_TIMER	(Optional) Reports the value of the NIC's system timer in the structure of RTNAL_HW_TIME type pointed by pArg. Used by RtNalGetDeviceSystemTimer
RTNAL_IOCTL_SET_RX_MESSAGE_TYPE_TO_TIMESTAMP	(Optional) Tells the NIC which type receive packets to time stamp. pArg must point to the structure of RTNAL_PTP_SET_TIMESTAMP_TYPE. Used by RtNalSetReceiveTimeStampType
RTNAL_IOCTL_SET_TX_MESSAGE_TYPE_TO_TIMESTAMP	(Optional) Tells the NIC which type transmit packets to time stamp. pArg must point to the structure of RTNAL_PTP_SET_TIMESTAMP_TYPE. Used by RtNalSetTransmitTimeStampType
RTNAL_IOCTL_READ_RX_HW_TIMESTAMP	(Optional) Reports the recorded time-stamp of the last packet received which was of the type to be time-stamped in the structure of RTNAL_HW_TIME type pointed by pArg. Used by RtNalGetReceiveTimeStamp.
RTNAL_IOCTL_READ_TX_HW_TIMESTAMP	(Optional) Reports the recorded time-stamp of the last packet transmitted which was of the type to be time-stamped in the structure of RTNAL_HW_TIME type pointed by pArg. Used by RtNalGetTransmitTimeStamp.
RTNAL_IOCTL_USE_RX_NOTIFICATIONS	(Required) Enables notifications of received packets from the driver IST. Call RtnGetDataLong with offset 1 to get the queue number. The receive notifications remain enabled while the receive queue is attached to the NAL client application.
RTNAL_IOCTL_SET_RX_POLLING	(Optional) Enables polling on a receive queue, which is configured to poll. The queue number must be retrieved by calling RtnGetDataLong with offset 1. Used by RtNalEnableReceivePolling.
RTNAL_IOCTL_CLEAR_RX_POLLING	(Optional) Disables polling on a receive queue. The queue number must be retrieved by calling RtnGetDataLong with offset 1. The receive packets are dropped when the polling is disabled for the receive queue, configured to poll. Used by RtNalDisableReceivePolling.
RTNAL_IOCTL_GET_RX_ETHERTYPE_FILTER	(Optional) Reports a receive Ethernet type filter with the specified index. pArg points to a structure of RTNAL_ETHERTYPE_FILTER type. filterIndex field is an input, the rest are output. Used by RtNalGetReceiveFilterEntryEthertype.
RTNAL_IOCTL_SET_RX_ETHERTYPE_FILTER	(Optional) Sets a receive Ethernet type filter with the specified index to the specified queue. pArg points to a structure of RTNAL_ETHERTYPE_FILTER type. All fields are input. Used by RtNalSetReceiveFilterEntryEthertype.
RTNAL_IOCTL_CLEAR_RX_ETHERTYPE_FILTER	(Optional) Sets a receive Ethernet type filter with the specified index for the specified queue. pArg points to a structure of RTNAL_ETHERTYPE_FILTER type. Fields filterIndex and queueNumber are input, the rest are ignored. Used by RtNalClearReceiveFilterEntryEthertype.
RTNAL_IOCTL_RX_MONITOR	(Optional) Enables or disables NAL monitor for the receive queue. pArg points to BOOL. The queue number must be retrieved by calling RtnGetDataLong with offset 1.
RTNAL_IOCTL_TX_MONITOR	(Optional) Enables or disables NAL monitor for the transmit queue. pArg points to BOOL. The queue number must be retrieved by calling RtnGetDataLong with offset 1.

Process Context

RtndIoctl is not called from a pre-determined process context. Do NOT use RTX64 handles in this routine.

Requirements

Minimum Supported Version	RTX64 4.0
Header	RtnApi.h
Library	RTX64Nal.lib