Tribblix: manual page: mri

MRI_POLL(9E) Driver Entry Points MRI_POLL(9E)

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