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 December 11, 2022 16.Dt MC_TX 9E 17.Os 18.Sh NAME 19.Nm mc_tx , 20.Nm mri_tx 21.Nd transmit a message block chain 22.Sh SYNOPSIS 23.In sys/mac_provider.h 24.Ft "mblk_t *" 25.Fo prefix_m_tx 26.Fa "void *driver" 27.Fa "mblk_t *mp_chain" 28.Fc 29.Ft "mblk_t *" 30.Fo prefix_ring_tx 31.Fa "void *driver_rh" 32.Fa "mblk_t *mp_chain" 33.Fc 34.Sh INTERFACE LEVEL 35illumos DDI specific 36.Pp 37The 38.Fn mri_tx 39entry point is 40.Sy Uncommitted - 41API and ABI stability is not guaranteed. 42.Sh PARAMETERS 43.Bl -tag -width Fa 44.It Fa driver 45A pointer to the driver's private data that was passed in via the 46.Fa m_pdata 47member of the 48.Xr mac_register 9S 49structure to the 50.Xr mac_register 9F 51function. 52.It Fa driver_rh 53A pointer to the driver's private data for the ring that was passed in 54via the 55.Fa mri_driver 56member of the 57.Xr mac_ring_info 9S 58structure. 59This is initialized by the driver when its 60.Xr mr_rget 9E 61is called by MAC. 62.It Fa mp_chain 63A series of 64.Xr mblk 9S 65structures that may have multiple independent packets linked together on 66their 67.Fa b_next 68member. 69.El 70.Sh DESCRIPTION 71The 72.Fn mc_tx 73entry point is called when the system requires a device driver to 74transmit data. 75The device driver will receive a chain of message blocks. 76The 77.Fa mp_chain 78argument represents the first frame. 79The frame may be spread out across one or more 80.Xr mblk 9S 81structures that are linked together by the 82.Fa b_cont 83member. 84There may be multiple frames, linked together by the 85.Fa b_next 86pointer of the 87.Xr mblk 9S . 88.Pp 89For each frame, the driver should allocate the required resources and 90prepare it for being transmitted on the wire. 91The driver may opt to copy those resources to a DMA buffer or it may bind them. 92For more information on these options, see the 93.Sx MBLKS AND DMA 94section of 95.Xr mac 9E . 96.Pp 97As it processes each frame in the chain, if the device driver has 98advertised either of the 99.Dv MAC_CAPAB_HCKSUM 100or 101.Dv MAC_CAPAB_LSO 102flags, it must check whether either apply for the given frame using the 103.Xr mac_hcksum_get 9F 104and 105.Xr mac_lso_get 9F 106functions respectively. 107If either is enabled for the given frame, the hardware must arrange for that to 108be taken care of. 109.Pp 110For each frame that the device driver processes it is responsible for 111doing one of three things with it: 112.Bl -enum 113.It 114Transmit the frame. 115.It 116Drop the frame by calling 117.Xr freemsg 9F 118on the individual mblk_t. 119.It 120Return the frames to indicate that resources are not available. 121.El 122.Pp 123The device driver is in charge of the memory associated with 124.Fa mp_chain . 125If the device driver does not return the message blocks to the MAC 126framework, then it must call 127.Xr freemsg 9F 128on the frames. 129If it does not, the memory associated with them will be leaked. 130When a frame is being transmitted, if the device driver performed DMA binding, 131it should not free the message block until after it is guaranteed that the frame 132has been transmitted. 133If the message block was copied to a DMA buffer, then it is allowed to call 134.Xr freemsg 9F 135at any point. 136.Pp 137In general, the device driver should not drop frames without 138transmitting them unless it has no other choice. 139Times when this happens may include the device driver being in a state where it 140can't transmit, an error was found in the frame while trying to establish the 141checksum or LSO state, or some other kind of error that represents an issue with 142the passed frame. 143.Pp 144The device driver should not free the chain when it does not have enough 145resources. 146For example, if entries in a device's descriptor ring fill up, then it should 147not drop those frames and instead should return all of the frames that were not 148transmitted. 149This indicates to the stack that the device is full and that flow control should 150be asserted. 151Back pressure will be applied to the rest of the stack, allowing most systems 152to behave better. 153.Pp 154Once a device driver has returned unprocessed frames from its 155.Fn mc_tx 156entry point, then the device driver will not receive any additional 157calls to its 158.Fn mc_tx 159entry point until it calls the 160.Xr mac_tx_update 9F 161function to indicate that resources are available again. 162Note that because it is the device driver that is calling this function to 163indicate resources are available, it is very important that it only return 164frames in cases where the device driver itself will be notified that resources 165are available again. 166For example, when it receives an interrupt indicating that the data that it 167transmitted has been completed so it can use entries in its descriptor ring or 168other data structures again. 169.Pp 170The device driver can obtain access to its soft state through the 171.Fa driver 172member. 173It should cast it to the appropriate structure. 174The device driver should employ any necessary locking to access the transmit 175related data structures. 176Note that the device driver should expect that it may have its transmit 177endpoints called into from other threads while it's servicing device interrupts 178related to them. 179.Pp 180The 181.Fn mri_tx 182entry point is similar to the 183.Fn mc_tx 184entry point, except that it is used by device drivers that have 185negotiated the 186.Dv MAC_CAPAB_RINGS 187capability with transmit rings. 188The driver should follow all of the same rules described earlier, except 189that it will access a ring-specific data structure through 190.Fa driver_rh 191and when it needs to update that there is additional space available, it 192must use 193.Xr mac_tx_ring_update 9F 194and not 195.Xr mac_tx_update 9F . 196.Pp 197When the 198.Fn mri_tx 199entry point is called, the ring that should be used has been specified. 200The driver must not attempt to use any other ring than the one specified 201by 202.Fa driver_rh 203for any reason, including a lack of resources or an attempt to perform 204its own hashing. 205.Sh CONTEXT 206The 207.Fn mc_tx 208entry point may be called from 209.Sy kernel 210or 211.Sy interrupt 212context. 213.Sh RETURN VALUES 214Upon successful completion, the device driver should return 215.Dv NULL . 216Otherwise, it should return all unprocessed message blocks and ensure 217that it calls either 218.Xr mac_tx_update 9F 219or 220.Xr mac_tx_ring_update 9F 221some time in the future. 222.Sh SEE ALSO 223.Xr mac 9E , 224.Xr mac_capab_rings 9E , 225.Xr mr_rget 9E , 226.Xr freemsg 9F , 227.Xr mac_hcksum_get 9F , 228.Xr mac_lso_get 9F , 229.Xr mac_register 9F , 230.Xr mac_tx_ring_update 9F , 231.Xr mac_tx_update 9F , 232.Xr mac_register 9S , 233.Xr mac_ring_info 9S , 234.Xr mblk 9S 235