usr/src/man/man9f/mac_hcksum_get.9f

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