NAME

mri_poll — Poll a ring for received network data

SYNOPSIS

#include <sys/mac_provider.h>

mblk_t *
prefix_ring_poll(void *driver, int poll_bytes);

INTERFACE LEVEL

Uncommitted - This interface is still evolving. API and ABI stability is not guaranteed.

PARAMETERS

driver: A pointer to the ring's private data that was passed in via the mri_driver member of the mac_ring_info(9S) structure as part of the mr_rget(9E) entry point.
poll_bytes: The maximum number of bytes that the driver should poll in a given call.

DESCRIPTION

The mri_poll() entry point is called by the MAC framework when it wishes to have the driver check the ring specified by driver for available data.

The device driver should perform the same logic that it would when it's processing an interrupt and as described in the Receiving Data section of mac(9E). The main difference is that instead of calling mac_rx_ring(9F), it should instead return that data as a mblk_t chain. Also, while an interrupt may map to more than one ring in some drivers, the driver should only process the ring indicated by driver. The MAC framework can be polling some rings that are receiving a lot of traffic while still relying on interrupts for others.

Drivers should exercise caution with the locking between the polling, interrupt disabling routines, and the interrupt handler. This mutex is generally scoped to a receive ring and is used to synchronize the act of transitioning between polling and handling interrupts. That means that in addition to the mri_poll() entry point, the mi_enable(9E) and mi_disable(9E) entry points should synchronize on the same mutex when transitioning the device. This is the same mutex that would be used when processing this ring during an interrupt handler, though that mutex should only be used while processing a specific ring and not held for the duration of the entire interrupt handler.

The driver should limit the number of frames it collects based on the size value present in the poll_bytes argument. The driver should sum up the total size of each processed frame and compare that running total to poll_bytes. If there are fewer frames than, poll_bytes, the driver should not wait and can instead return right away. Similarly, if the driver has iterated around its entire descriptor ring and still does not have enough enough, it is OK to return early. Importantly, the framework is not asking the driver to block until it has poll_bytes available .

RETURN VALUES

Upon successful completion, the device driver should return a message block chain of collected frames. If no frames are available or it encountered an error while processing data, then it should return NULL.