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