|MGI_START(9E)||Driver Entry Points||MGI_START(9E)|
rh, uint64_t mr_gen);
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
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() 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.
mri_start() entry points should return 0. Otherwise, they should return the appropriate error number.
|July 2, 2022||OmniOS|