| MGI_START(9E) | Driver Entry Points | MGI_START(9E) |
mgi_start, mgi_stop,
mri_start, mri_stop —
#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);
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(9E).
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 mrg_stop() and
mrg_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.
mgi_start() and
mri_start() entry points should return
0. Otherwise, they should return the appropriate error
number.
| July 2, 2022 | OmniOS |