Tribblix: manual page: mgi

MGI_START(9E) Driver Entry Points MGI_START(9E)

NAME

mgi_start, mgi_stop, mri_start, mri_stop - MAC group and ring start and
stop entry points

SYNOPSIS

#include <sys/mac_provider.h>

int
prefix_group_start(mac_group_driver_t gh);

void
prefix_group_stop(mac_group_driver_t gh);

int
prefix_ring_start(mac_ring_driver_t rh, uint64_t mr_gen);

void
prefix_ring_stop(mac_ring_driver_t rh);

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 mgi_driver member of the mac_group_info(9S)
structure as part of the mr_gget(9E) entry point.

rh 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.

mr_gen A 64-bit generation number.

DESCRIPTION

The mgi_start(), mgi_stop(), mri_start(), and mri_stop() entry points
are used to start and stop MAC rings and groups. The group entry
points are optional, while the ring entry points are required. The
group start entry point will be called before any rings and similarly,
the ring stop entry point will be called for all rings before the group
stop entry point. In the group case, the group is identified by gh,
while the ring entry points use rh to identify the specific ring.
These are opaque pointers to data that was set in the
mac_group_info(9S) and mac_ring_info(9S) structures during the
mr_gget(9E) and mr_rget(9E) entry points respectively.

These entry points give the driver a chance to take action prior to
actually transmitting or receiving any data. The amount of work that
is required will vary based on the driver and its design. At a
minimum, during the mri_start() entry point, a driver is required to
save the value of mr_gen for later use, in particular when calling
mac_rx_ring(9F). This is used by the system to discriminate between
generations of the device's configuration and its operation. The
operating system will check that all received packets are called with
the value of mr_gen that it expects. If they do not match, then they
received packets will be dropped.

In general, it is recommended that descriptor rings are allocated
during the driver's initial attach(9E). In contrast, allocating and
freeing the actual memory associated with the descriptor entries during
ring start and stop can be a reasonable way to try and reduce memory
overhead of the driver. For example, a receive ring generally needs to
allocate one DMA buffer for each entry in its receive ring that covers
the maximum frame size that the device can receive. This is something
that could be deferred to the mri_start() entry point and then freed in
the mri_stop() entry point.

It's worth noting that the mgi_stop() and mri_stop() entry points
purposefully return void. In particular, this means that the driver
must be careful about doing things which might fail, such as
asynchronous communication to a device. If that is necessary and such
communication fails, the device should be marked as faulted and attempt
to recover via a reset or similar mechanism in another context.

RETURN VALUES