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