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

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

#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);

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

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.

The (), 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 () 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 () entry point and then freed in the () entry point.

It's worth noting that the () and () 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.

Upon successful completion, the mgi_start() and mri_start() entry points should return . Otherwise, they should return the appropriate error number.

mac(9E), mac_capab_rings(9E), mr_gget(9E), mac_rx_ring(9F), mac_group_info(9S)

July 17, 2023 OmniOS