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 Compuer Company 14.\" Copyright 2023 Peter Tribble 15.\" 16.Dd July 17, 2023 17.Dt MAC_RX 9F 18.Os 19.Sh NAME 20.Nm mac_rx , 21.Nm mac_rx_ring 22.Nd deliver frames from a driver to the system 23.Sh SYNOPSIS 24.In sys/mac_provider.h 25.Ft void 26.Fo mac_rx 27.Fa "mac_handle_t mh" 28.Fa "mac_resource_handle_t mrh" 29.Fa "mblk_t *mp_chain" 30.Fc 31.Ft void 32.Fo mac_rx_ring 33.Fa "mac_handle_t mh" 34.Fa "mac_ring_handle_t mring" 35.Fa "mblk_t *mp_chain" 36.Fa "uint64_t mr_gen" 37.Fc 38.Sh INTERFACE LEVEL 39illumos DDI specific 40.Pp 41The 42.Fn mac_rx_ring 43function point is 44.Sy Uncommitted - 45API and ABI stability is not guaranteed. 46.Sh PARAMETERS 47.Bl -tag -width Fa 48.It Fa mh 49The MAC handle obtained from a call to 50.Xr mac_register 9F . 51.It Fa mrh 52A reserved parameter that should be passed as 53.Dv NULL . 54.It Fa mring 55A pointer to the ring handle that was passed to the driver in the 56.Xr mr_rget 9E 57entry point. 58.It Fa mp_chain 59A series of one or more 60.Xr mblk 9S 61structures chained together by their 62.Sy b_next 63member. 64.It Fa mr_gen 65The generation number for the current ring. 66The generation comes from the 67.Xr mri_start 9E 68entry point. 69.El 70.Sh DESCRIPTION 71The 72.Fn mac_rx 73function is used by device drivers to deliver frames that a device 74driver has received to the rest of the operating system. 75This will generally be called at the end of a device driver's interrupt handler 76after it is has converted all of the incoming data into a chain of 77.Xr mblk 9S 78structures. 79For a full description of the process that the device driver should take as part 80of receiving data, see the 81.Sx Receiving Data 82section of 83.Xr mac 9E . 84.Pp 85Device drivers should ensure that they are not holding any of their own 86locks when they call the 87.Fn mac_rx 88function. 89.Pp 90Device drivers should not call the 91.Fn mac_rx 92function after each individual mblk_t is assembled. 93Rather, the device driver should batch up as many frames as it is willing to 94process in a given interrupt or are available. 95.Pp 96The 97.Fn mac_rx_ring 98function is similar to the 99.Fa mac_rx 100function; however, it should be called by device drivers that have 101negotiated the 102.Dv MAC_CAPAB_RINGS 103capability and indicated that it supports receive groups. 104Device drivers that have negotiated this capability must not call the 105.Fn mac_rx 106function, but use the 107.Fn mac_rx_ring 108function instead. 109The driver should pass the ring handle in 110.Fa mring 111for the ring in question that it processed. 112If more than one ring was processed during an interrupt, then the driver 113must call 114.Fn mac_rx_ring 115once for each ring and ensure that the 116.Fa mr_gen 117argument matches what was passed to the driver during the 118.Xr mri_start 9E 119entry point for each ring. 120If the value of 121.Fa mr_gen 122does not match what the operating system expects, all of the packets 123will be dropped. 124This is used to make sure that the system is receiving what it considers 125valid data from the device driver. 126.Pp 127When a driver supporting the 128.Dv MAC_CAPAB_RINGS 129capability is asked to poll via their 130.Xr mri_poll 9E 131entry point, then the driver should not call the 132.Fn mac_rx_ring 133function to deliver packets and instead returns them during the 134.Xr mri_poll 9E 135call. 136.Sh CONTEXT 137The 138.Fn mac_rx 139function can be called from 140.Sy user , 141.Sy kernel , 142or 143.Sy interrupt 144context. 145.Sh SEE ALSO 146.Xr mac 9E , 147.Xr mac_capab_rings 9E , 148.Xr mr_rget 9E , 149.Xr mri_poll 9E , 150.Xr mri_start 9E , 151.Xr mac_register 9F , 152.Xr mblk 9S 153