| blob | 625587cd761078df52dae2b5e446c54c0df2e392 |
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
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 messge 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