RtNalIoctl

RtNalIoctl is called when an application requires that the driver configures certain NIC modes or characteristics.

Syntax

BOOL RtNalIoctl(
	RTNAL_QUEUE_HANDLE queueHandle,
	INT cmd,
	PVOID * buffer
);

Parameters

queueHandle

Network queue handle returned by RtNalAcquireQueue.

cmd

Control code to execute. The following commands are supported:

Command	Description
ENIOCPROMISC	(Optional) Turn on promiscuous mode
ENIOCALL	(Optional) Receive good and bad frames. Non-promiscuous.
ENIOCNORMAL	(Optional) Receive only good frames. Default mode.
ENIOADDMULTI	(Required) Add multicast route to this NIC (required command, should be implemented). The buffer 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 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 buffer 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) Gets the link status of this NIC. 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.

*buffer

Pointer to a data buffer for passing information to/from the driver. It can be NULL for control codes which don't require an information buffer.

Return Value

Returns TRUE if the call succeeds. Otherwise it returns FALSE. Call GetLastError to obtain an error code. The possible error codes are listed below:

Error Code	Meaning
ERROR_INVALID_PARAMETER	Indicates one of the following: queueHandle is NULL Buffer is NULL for the cmd that returns the information the command is invalid the information passed for a particular command was invalid
ERROR_INVALID_HANDLE	queueHandle is invalid. This might be occur if the queue was released in another thread or on process exit, as if by RtssKill.
ERROR_NOT_READY	RtNalInit has not completed successfully.
ERROR_DEVICE_FEATURE_NOT_SUPPORTED	The driver does not support the specified control code cmd.

Remarks

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.

Requirements

Minimum Supported Version	RTX64 4.0
Header	rtnapi.h, RtNalApi.h
Library	RtNal.lib