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 01, 2016 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 "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. For example, if using IPv4 and TCP, this 55would contain the offset from the start of the IPv4 header to the first 56byte 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. When a device driver indicates that it supports the 76.Sy MAC_CAPAB_HCKSUM 77capability as part of its 78.Xr mc_getcapab 9E 79entry point, then it is responsible for calling these functions 80appropriately during the transmit and receive paths. 81.Pp 82While both functions operate on an 83.Sy mblk_t , 84this function should only be called on the first 85.Sy mblk_t 86that begins a given individual frame in a chain. In other words, it only 87works on entries where it is the first of many possible entries linked 88together by the 89.Sy b_cont 90member. The first 91.Sy mblk_t 92received from any 93.Xr mac 9E 94API or pointed to by a 95.Sy b_next 96pointer should be used. 97.Ss Receiving Data 98When a device driver is receiving data, it is its responsibility to 99.Em set 100checksum information when it has indicated that it supports the 101.Sy MAC_CAPAB_HCKSUM 102capability. Device drivers will call the 103.Fn mac_hcksum_set 104function to indicate what checksum information has occurred. 105.Pp 106The proper values to set depend on the flags passed in. The following 107flags are supported when receiving data, note that they may have 108different meanings from when transmitting data. The driver should set 109the 110.Fa flags 111argument to the bitwise inclusive OR of the following values: 112.Bl -tag -width Sy 113.It Sy HCK_IPV4_HDRCKSUM_OK 114This flag indicates that the hardware has verified the IPv4 header is 115correct and that the networking stack does not need to verify it. 116.It Sy HCK_PARTIALCKSUM 117This flag indicates that the hardware has computed a partial checksum. 118When this flag is set, the driver is responsible for passing in the 119partial checksum in the 120.Fa value 121argument as well as the start and ending bytes of the checksum in the 122.Fa start 123and 124.Fa end 125arguments. 126.It Sy HCK_FULLCKSUM 127This flag indicates that the hardware has calculated the full L4 header 128checksum; however, it wants the system to verify it. The checksum should 129be passed in the 130.Fa value 131argument. 132.It Sy HCK_FULLCKSUM_OK 133This flag indicates that the hardware has calculated the full L4 header 134checksum and verified that it is correct. The networking stack does not 135need to verify it. 136.El 137.Pp 138The 139.Sy HCK_PARTIALCKSUM , 140.Sy HCK_FULLCKSUM , 141and 142.Sy HCK_FULLCKSUM_OK 143flags are all mutually exclusive. A device driver should only set one of 144the three flags. 145.Pp 146If one of the arguments is not required based on the specified value of 147.Fa flags , 148then the device driver should set any remaining arguments to 149.Sy 0 . 150.Ss Transmitting Data 151When a device driver is transmitting data and it has advertised that it 152supports the 153.Sy MAC_CAPAB_HCKSUM 154capability, then it must call the 155.Fn mac_hcksum_get 156function to determine what hardware checksumming options are required to 157be performed by the hardware. While the device driver may need the other 158fields, it must check the 159.Fa flags 160argument to determine what it is being requested to do. The following 161values may be set in 162.Fa flags : 163.Bl -tag -width Sy 164.It Sy HCK_IPV4_HDRCKSUM 165The device driver must compute the IPv4 header checksum. No other fields 166have been filled in. 167.It Sy HCK_PARTIALCKSUM 168The device driver needs to compute the partial ones' complement of the 169checksum. The system has filled in the 170.Fa start , 171.Fa stuff , 172and 173.Fa end 174arguments to assist the device driver. 175.It Sy HCK_FULLCKSUM 176The device driver should compute the full L4 checksum. No other fields 177have been filled in for the device driver. 178.El 179.Pp 180The flags that the device driver will get will depend on what the device 181driver has advertised that it supports in response to the 182.Xr mc_getcapab 9E 183query for the 184.Sy MAC_CAPAB_HCKSUM 185capability. 186.Pp 187The 188.Sy HCK_PARTIALCKSUM 189and 190.Sy HCK_FULLCKSUM 191flags are mutually exclusive. 192.Sh CONTEXT 193The 194.Fn mac_hcksum_get 195and 196.Fn mac_hcksum_set 197functions may be called from any context. 198.Sh SEE ALSO 199.Xr mac 9E , 200.Xr mac_getcapab 9E , 201.Xr mblk 9S 202