1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright (c) 2017, Joyent, Inc. 13.\" Copyright 2022 Oxide computer Company 14.\" 15.Dd July 2, 2022 16.Dt MGI_START 9E 17.Os 18.Sh NAME 19.Nm mgi_start , 20.Nm mgi_stop , 21.Nm mri_start , 22.Nm mri_stop 23.Nd MAC group and ring start and stop entry points 24.Sh SYNOPSIS 25.In sys/mac_provider.h 26.Ft int 27.Fo prefix_group_start 28.Fa "mac_group_driver_t gh" 29.Fc 30.Ft void 31.Fo prefix_group_stop 32.Fa "mac_group_driver_t gh" 33.Fc 34.Ft int 35.Fo prefix_ring_start 36.Fa "mac_ring_driver_t rh" 37.Fa "uint64_t mr_gen" 38.Fc 39.Ft void 40.Fo prefix_ring_stop 41.Fa "mac_ring_driver_t rh" 42.Fc 43.Sh INTERFACE LEVEL 44.Sy Uncommitted - 45This interface is still evolving. 46API and ABI stability is not guaranteed. 47.Sh PARAMETERS 48.Bl -tag -width Fa 49.It Fa driver 50A pointer to the ring's private data that was passed in via the 51.Vt mgi_driver 52member of the 53.Xr mac_group_info 9S 54structure as part of the 55.Xr mr_gget 9E 56entry point. 57.It Fa rh 58A pointer to the ring's private data that was passed in via the 59.Vt mri_driver 60member of the 61.Xr mac_ring_info 9S 62structure as part of the 63.Xr mr_rget 9E 64entry point. 65.It Fa mr_gen 66A 64-bit generation number. 67.El 68.Sh DESCRIPTION 69The 70.Fn mgi_start , 71.Fn mgi_stop , 72.Fn mri_start , 73and 74.Fn mri_stop 75entry points are used to start and stop MAC rings and groups. 76The group entry points are optional, while the ring entry points are 77required. 78The group start entry point will be called before any rings and 79similarly, the ring stop entry point will be called for all rings before 80the group stop entry point. 81In the group case, the group is identified by 82.Fa gh , 83while the ring entry points use 84.Fa rh 85to identify the specific ring. 86These are opaque pointers to data that was set in the 87.Xr mac_group_info 9S 88and 89.Xr mac_ring_info 9S 90structures during the 91.Xr mr_gget 9E 92and 93.Xr mr_rget 9E 94entry points respectively. 95.Pp 96These entry points give the driver a chance to take action prior to 97actually transmitting or receiving any data. 98The amount of work that is required will vary based on the driver and 99its design. 100At a minimum, during the 101.Fn mri_start 102entry point, a driver is required to save the value of 103.Fa mr_gen 104for later use, in particular when calling 105.Xr mac_rx_ring 9E . 106This is used by the system to discriminate between generations of the 107device's configuration and its operation. 108The operating system will check that all received packets are called 109with the value of 110.Fa mr_gen 111that it expects. 112If they do not match, then they received packets will be dropped. 113.Pp 114In general, it is recommended that descriptor rings are allocated during 115the driver's initial 116.Xr attach 9E . 117In contrast, allocating and freeing the actual memory associated with 118the descriptor entries during ring start and stop can be a reasonable 119way to try and reduce memory overhead of the driver. 120For example, a receive ring generally needs to allocate one DMA buffer 121for each entry in its receive ring that covers the maximum frame size 122that the device can receive. 123This is something that could be deferred to the 124.Fn mri_start 125entry point and then freed in the 126.Fn mri_stop 127entry point. 128.Pp 129It's worth noting that the 130.Fn mrg_stop 131and 132.Fn mrg_stop 133entry points purposefully return 134.Ft void . 135In particular, this means that the driver must be careful about doing 136things which might fail, such as asynchronous communication to a device. 137If that is necessary and such communication fails, the device should be 138marked as faulted and attempt to recover via a reset or similar 139mechanism in another context. 140.Sh RETURN VALUES 141Upon successful completion, the 142.Fn mgi_start 143and 144.Fn mri_start 145entry points should return 146.Sy 0 . 147Otherwise, they should return the appropriate error number. 148.Sh SEE ALSO 149.Xr mac 9E , 150.Xr mac_capab_rings 9E , 151.Xr mr_gget 9E , 152.Xr mac_group_info 9S 153