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