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