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