152d2369aSRobert Mustacchi.\" 252d2369aSRobert Mustacchi.\" This file and its contents are supplied under the terms of the 352d2369aSRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0. 452d2369aSRobert Mustacchi.\" You may only use this file in accordance with the terms of version 552d2369aSRobert Mustacchi.\" 1.0 of the CDDL. 652d2369aSRobert Mustacchi.\" 752d2369aSRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this 852d2369aSRobert Mustacchi.\" source. A copy of the CDDL is also available via the Internet at 952d2369aSRobert Mustacchi.\" http://www.illumos.org/license/CDDL. 1052d2369aSRobert Mustacchi.\" 1152d2369aSRobert Mustacchi.\" 122c0ebdeeSRobert Mustacchi.\" Copyright (c) 2017, Joyent, Inc. 132c0ebdeeSRobert Mustacchi.\" Copyright 2022 Oxide Compuer Company 14*496cffd8SPeter Tribble.\" Copyright 2023 Peter Tribble 1552d2369aSRobert Mustacchi.\" 16*496cffd8SPeter Tribble.Dd July 17, 2023 1752d2369aSRobert Mustacchi.Dt MAC_RX 9F 1852d2369aSRobert Mustacchi.Os 1952d2369aSRobert Mustacchi.Sh NAME 202c0ebdeeSRobert Mustacchi.Nm mac_rx , 21*496cffd8SPeter Tribble.Nm mac_rx_ring 2252d2369aSRobert Mustacchi.Nd deliver frames from a driver to the system 2352d2369aSRobert Mustacchi.Sh SYNOPSIS 2452d2369aSRobert Mustacchi.In sys/mac_provider.h 2552d2369aSRobert Mustacchi.Ft void 2652d2369aSRobert Mustacchi.Fo mac_rx 2752d2369aSRobert Mustacchi.Fa "mac_handle_t mh" 2852d2369aSRobert Mustacchi.Fa "mac_resource_handle_t mrh" 2952d2369aSRobert Mustacchi.Fa "mblk_t *mp_chain" 3052d2369aSRobert Mustacchi.Fc 312c0ebdeeSRobert Mustacchi.Ft void 322c0ebdeeSRobert Mustacchi.Fo mac_rx_ring 332c0ebdeeSRobert Mustacchi.Fa "mac_handle_t mh" 342c0ebdeeSRobert Mustacchi.Fa "mac_ring_handle_t mring" 352c0ebdeeSRobert Mustacchi.Fa "mblk_t *mp_chain" 362c0ebdeeSRobert Mustacchi.Fa "uint64_t mr_gen" 372c0ebdeeSRobert Mustacchi.Fc 3852d2369aSRobert Mustacchi.Sh INTERFACE LEVEL 3952d2369aSRobert Mustacchiillumos DDI specific 402c0ebdeeSRobert Mustacchi.Pp 412c0ebdeeSRobert MustacchiThe 422c0ebdeeSRobert Mustacchi.Fn mac_rx_ring 432c0ebdeeSRobert Mustacchifunction point is 442c0ebdeeSRobert Mustacchi.Sy Uncommitted - 452c0ebdeeSRobert MustacchiAPI and ABI stability is not guaranteed. 4652d2369aSRobert Mustacchi.Sh PARAMETERS 4752d2369aSRobert Mustacchi.Bl -tag -width Fa 4852d2369aSRobert Mustacchi.It Fa mh 4952d2369aSRobert MustacchiThe MAC handle obtained from a call to 5052d2369aSRobert Mustacchi.Xr mac_register 9F . 5152d2369aSRobert Mustacchi.It Fa mrh 5252d2369aSRobert MustacchiA reserved parameter that should be passed as 5352d2369aSRobert Mustacchi.Dv NULL . 542c0ebdeeSRobert Mustacchi.It Fa mring 552c0ebdeeSRobert MustacchiA pointer to the ring handle that was passed to the driver in the 562c0ebdeeSRobert Mustacchi.Xr mr_rget 9E 572c0ebdeeSRobert Mustacchientry point. 5852d2369aSRobert Mustacchi.It Fa mp_chain 5952d2369aSRobert MustacchiA series of one or more 6052d2369aSRobert Mustacchi.Xr mblk 9S 6152d2369aSRobert Mustacchistructures chained together by their 6252d2369aSRobert Mustacchi.Sy b_next 6352d2369aSRobert Mustacchimember. 642c0ebdeeSRobert Mustacchi.It Fa mr_gen 652c0ebdeeSRobert MustacchiThe generation number for the current ring. 662c0ebdeeSRobert MustacchiThe generation comes from the 672c0ebdeeSRobert Mustacchi.Xr mri_start 9E 682c0ebdeeSRobert Mustacchientry point. 6952d2369aSRobert Mustacchi.El 7052d2369aSRobert Mustacchi.Sh DESCRIPTION 7152d2369aSRobert MustacchiThe 7252d2369aSRobert Mustacchi.Fn mac_rx 7352d2369aSRobert Mustacchifunction is used by device drivers to deliver frames that a device 7472d3dbb9SYuri Pankovdriver has received to the rest of the operating system. 7572d3dbb9SYuri PankovThis will generally be called at the end of a device driver's interrupt handler 7652d2369aSRobert Mustacchiafter it is has converted all of the incoming data into a chain of 7752d2369aSRobert Mustacchi.Xr mblk 9S 7872d3dbb9SYuri Pankovstructures. 7972d3dbb9SYuri PankovFor a full description of the process that the device driver should take as part 8072d3dbb9SYuri Pankovof receiving data, see the 8152d2369aSRobert Mustacchi.Sx Receiving Data 8252d2369aSRobert Mustacchisection of 8352d2369aSRobert Mustacchi.Xr mac 9E . 8452d2369aSRobert Mustacchi.Pp 8552d2369aSRobert MustacchiDevice drivers should ensure that they are not holding any of their own 8652d2369aSRobert Mustacchilocks when they call the 8752d2369aSRobert Mustacchi.Fn mac_rx 8852d2369aSRobert Mustacchifunction. 8952d2369aSRobert Mustacchi.Pp 9052d2369aSRobert MustacchiDevice drivers should not call the 9152d2369aSRobert Mustacchi.Fn mac_rx 9272d3dbb9SYuri Pankovfunction after each individual mblk_t is assembled. 9372d3dbb9SYuri PankovRather, the device driver should batch up as many frames as it is willing to 942c0ebdeeSRobert Mustacchiprocess in a given interrupt or are available. 952c0ebdeeSRobert Mustacchi.Pp 962c0ebdeeSRobert MustacchiThe 972c0ebdeeSRobert Mustacchi.Fn mac_rx_ring 982c0ebdeeSRobert Mustacchifunction is similar to the 992c0ebdeeSRobert Mustacchi.Fa mac_rx 1002c0ebdeeSRobert Mustacchifunction; however, it should be called by device drivers that have 1012c0ebdeeSRobert Mustacchinegotiated the 1022c0ebdeeSRobert Mustacchi.Dv MAC_CAPAB_RINGS 1032c0ebdeeSRobert Mustacchicapability and indicated that it supports receive groups. 1042c0ebdeeSRobert MustacchiDevice drivers that have negotiated this capability must not call the 1052c0ebdeeSRobert Mustacchi.Fn mac_rx 1062c0ebdeeSRobert Mustacchifunction, but use the 1072c0ebdeeSRobert Mustacchi.Fn mac_rx_ring 1082c0ebdeeSRobert Mustacchifunction instead. 1092c0ebdeeSRobert MustacchiThe driver should pass the ring handle in 1102c0ebdeeSRobert Mustacchi.Fa mring 1112c0ebdeeSRobert Mustacchifor the ring in question that it processed. 1122c0ebdeeSRobert MustacchiIf more than one ring was processed during an interrupt, then the driver 1132c0ebdeeSRobert Mustacchimust call 114*496cffd8SPeter Tribble.Fn mac_rx_ring 1152c0ebdeeSRobert Mustacchionce for each ring and ensure that the 1162c0ebdeeSRobert Mustacchi.Fa mr_gen 1172c0ebdeeSRobert Mustacchiargument matches what was passed to the driver during the 1182c0ebdeeSRobert Mustacchi.Xr mri_start 9E 1192c0ebdeeSRobert Mustacchientry point for each ring. 1202c0ebdeeSRobert MustacchiIf the value of 1212c0ebdeeSRobert Mustacchi.Fa mr_gen 1222c0ebdeeSRobert Mustacchidoes not match what the operating system expects, all of the packets 1232c0ebdeeSRobert Mustacchiwill be dropped. 1242c0ebdeeSRobert MustacchiThis is used to make sure that the system is receiving what it considers 1252c0ebdeeSRobert Mustacchivalid data from the device driver. 1262c0ebdeeSRobert Mustacchi.Pp 1272c0ebdeeSRobert MustacchiWhen a driver supporting the 1282c0ebdeeSRobert Mustacchi.Dv MAC_CAPAB_RINGS 1292c0ebdeeSRobert Mustacchicapability is asked to poll via their 1302c0ebdeeSRobert Mustacchi.Xr mri_poll 9E 1312c0ebdeeSRobert Mustacchientry point, then the driver should not call the 132*496cffd8SPeter Tribble.Fn mac_rx_ring 1332c0ebdeeSRobert Mustacchifunction to deliver packets and instead returns them during the 1342c0ebdeeSRobert Mustacchi.Xr mri_poll 9E 1352c0ebdeeSRobert Mustacchicall. 13652d2369aSRobert Mustacchi.Sh CONTEXT 13752d2369aSRobert MustacchiThe 13852d2369aSRobert Mustacchi.Fn mac_rx 13952d2369aSRobert Mustacchifunction can be called from 14052d2369aSRobert Mustacchi.Sy user , 14152d2369aSRobert Mustacchi.Sy kernel , 14252d2369aSRobert Mustacchior 14352d2369aSRobert Mustacchi.Sy interrupt 14452d2369aSRobert Mustacchicontext. 14552d2369aSRobert Mustacchi.Sh SEE ALSO 14652d2369aSRobert Mustacchi.Xr mac 9E , 1472c0ebdeeSRobert Mustacchi.Xr mac_capab_rings 9E , 1482c0ebdeeSRobert Mustacchi.Xr mr_rget 9E , 1492c0ebdeeSRobert Mustacchi.Xr mri_poll 9E , 1502c0ebdeeSRobert Mustacchi.Xr mri_start 9E , 15152d2369aSRobert Mustacchi.Xr mac_register 9F , 15252d2369aSRobert Mustacchi.Xr mblk 9S 153