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 2018 Joyent, Inc.
13.\"
14.Dd March 15, 2018
15.Dt MAC_HCKSUM_GET 9F
16.Os
17.Sh NAME
18.Nm mac_hcksum_get ,
19.Nm mac_hcksum_set
20.Nd get and set checksum information on message blocks
21.Sh SYNOPSIS
22.In sys/mac_provider.h
23.Ft void
24.Fo mac_hcksum_get
25.Fa "const mblk_t *mp"
26.Fa "uint32_t *start"
27.Fa "uint32_t *stuff"
28.Fa "uint32_t *end"
29.Fa "uint32_t *value"
30.Fa "uint32_t *flags"
31.Fc
32.Ft void
33.Fo mac_hcksum_set
34.Fa "mblk_t *mp"
35.Fa "uint32_t start"
36.Fa "uint32_t stuff"
37.Fa "uint32_t end"
38.Fa "uint32_t value"
39.Fa "uint32_t flags"
40.Fc
41.Sh INTERFACE LEVEL
42illumos DDI specific
43.Sh PARAMETERS
44.Bl -tag -width Fa
45.It Fa mp
46A pointer to a
47.Xr mblk 9S
48structure that contains a frame.
49.It Fa start
50The value or a pointer to it that contains the offset from the L3
51header, generally IP, of the first byte that's covered by the checksum.
52.It Fa stuff
53The value or a pointer to it that contains the offset from the L3 header
54of where the L4 checksum is.
55For example, if using IPv4 and TCP, this would contain the offset from the start
56of the IPv4 header to the first byte of the TCP checksum.
57.It Fa end
58The value or a pointer to it that contains the offset from the L3
59header, generally IP, of the last byte that's covered by the checksum.
60.It Fa value
61The value or a pointer to it that contains the actual value of the
62checksum.
63.It Fa flags
64A series of one or more flags that have bitwise inclusive ORed together.
65The set of flags have different meanings depending on whether
66.Fa mp
67is being transmitted or received.
68.El
69.Sh DESCRIPTION
70The
71.Fn mac_hcksum_get
72and
73.Fn mac_hcksum_set
74functions are provided to device drivers to get and set checksum related
75information.
76When a device driver indicates that it supports the
77.Sy MAC_CAPAB_HCKSUM
78capability as part of its
79.Xr mc_getcapab 9E
80entry point, then it is responsible for calling these functions
81appropriately during the transmit and receive paths.
82.Pp
83While both functions operate on an
84.Sy mblk_t ,
85this function should only be called on the first
86.Sy mblk_t
87that begins a given individual frame in a chain.
88In other words, it only works on entries where it is the first of many possible
89entries linked together by the
90.Sy b_cont
91member.
92The first
93.Sy mblk_t
94received from any
95.Xr mac 9E
96API or pointed to by a
97.Sy b_next
98pointer should be used.
99.Ss Receiving Data
100When a device driver is receiving data, it is its responsibility to
101.Em set
102checksum information when it has indicated that it supports the
103.Sy MAC_CAPAB_HCKSUM
104capability.
105Device drivers will call the
106.Fn mac_hcksum_set
107function to indicate what checksum information has occurred.
108.Pp
109The proper values to set depend on the flags passed in.
110The following flags are supported when receiving data, note that they may have
111different meanings from when transmitting data.
112The driver should set the
113.Fa flags
114argument to the bitwise inclusive OR of the following values:
115.Bl -tag -width Sy
116.It Sy HCK_IPV4_HDRCKSUM_OK
117This flag indicates that the hardware has verified the IPv4 header is
118correct and that the networking stack does not need to verify it.
119.It Sy HCK_PARTIALCKSUM
120This flag indicates that the hardware has computed a partial checksum.
121When this flag is set, the driver is responsible for passing in the
122partial checksum in the
123.Fa value
124argument as well as the start and ending bytes of the checksum in the
125.Fa start
126and
127.Fa end
128arguments.
129.It Sy HCK_FULLCKSUM
130This flag indicates that the hardware has calculated the full L4 header
131checksum; however, it wants the system to verify it.
132The checksum should be passed in the
133.Fa value
134argument.
135.It Sy HCK_FULLCKSUM_OK
136This flag indicates that the hardware has calculated the full L4 header
137checksum and verified that it is correct.
138The networking stack does not need to verify it.
139.El
140.Pp
141The
142.Sy HCK_PARTIALCKSUM ,
143.Sy HCK_FULLCKSUM ,
144and
145.Sy HCK_FULLCKSUM_OK
146flags are all mutually exclusive.
147A device driver should only set one of the three flags.
148.Pp
149If one of the arguments is not required based on the specified value of
150.Fa flags ,
151then the device driver should set any remaining arguments to
152.Sy 0 .
153.Ss Transmitting Data
154When a device driver is transmitting data and it has advertised that it
155supports the
156.Sy MAC_CAPAB_HCKSUM
157capability, then it must call the
158.Fn mac_hcksum_get
159function to determine what hardware checksumming options are required to
160be performed by the hardware.
161While the device driver may need the other fields, it must check the
162.Fa flags
163argument to determine what it is being requested to do.
164The following values may be set in
165.Fa flags :
166.Bl -tag -width Sy
167.It Sy HCK_IPV4_HDRCKSUM
168The device driver must compute the IPv4 header checksum.
169No other fields have been filled in.
170.It Sy HCK_PARTIALCKSUM
171The device driver needs to compute the partial ones' complement of the
172checksum.
173The system has filled in the
174.Fa start ,
175.Fa stuff ,
176and
177.Fa end
178arguments to assist the device driver.
179.It Sy HCK_FULLCKSUM
180The device driver should compute the full L4 checksum.
181No other fields have been filled in for the device driver.
182.El
183.Pp
184The flags that the device driver will get will depend on what the device
185driver has advertised that it supports in response to the
186.Xr mc_getcapab 9E
187query for the
188.Sy MAC_CAPAB_HCKSUM
189capability.
190.Pp
191The
192.Sy HCK_PARTIALCKSUM
193and
194.Sy HCK_FULLCKSUM
195flags are mutually exclusive.
196.Sh CONTEXT
197The
198.Fn mac_hcksum_get
199and
200.Fn mac_hcksum_set
201functions may be called from any context.
202.Sh SEE ALSO
203.Xr mac 9E ,
204.Xr mc_getcapab 9E ,
205.Xr mblk 9S
206