share/man/man9e/mc_tx.9e

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