illumos: manual page: mac_hcksum

MAC_HCKSUM_GET(9F) Kernel Functions for Drivers MAC_HCKSUM_GET(9F)

NAME

mac_hcksum_get, mac_hcksum_set - get and set checksum information on
message blocks

SYNOPSIS

#include <sys/mac_provider.h>

void
mac_hcksum_get(const mblk_t *mp, uint32_t *start, uint32_t *stuff,
uint32_t *end, uint32_t *value, uint32_t *flags);

void
mac_hcksum_set(mblk_t *mp, uint32_t start, uint32_t stuff, uint32_t end,
uint32_t value, uint32_t flags);

INTERFACE LEVEL

illumos DDI specific

PARAMETERS

mp A pointer to a mblk(9S) structure that contains a frame.

start The value or a pointer to it that contains the offset from
the L3 header, generally IP, of the first byte that's covered
by the checksum.

stuff The value or a pointer to it that contains the offset from
the L3 header of where the L4 checksum is. For example, if
using IPv4 and TCP, this would contain the offset from the
start of the IPv4 header to the first byte of the TCP
checksum.

end The value or a pointer to it that contains the offset from
the L3 header, generally IP, of the last byte that's covered
by the checksum.

value The value or a pointer to it that contains the actual value
of the checksum.

flags A series of one or more flags that have bitwise inclusive
ORed together. The set of flags have different meanings
depending on whether mp is being transmitted or received.

DESCRIPTION

The mac_hcksum_get() and mac_hcksum_set() functions are provided to device
drivers to get and set checksum related information. When a device driver
indicates that it supports the MAC_CAPAB_HCKSUM capability as part of its
mc_getcapab(9E) entry point, then it is responsible for calling these
functions appropriately during the transmit and receive paths.

While both functions operate on an mblk_t, this function should only be
called on the first mblk_t that begins a given individual frame in a chain.
In other words, it only works on entries where it is the first of many
possible entries linked together by the b_cont member. The first mblk_t
received from any mac(9E) API or pointed to by a b_next pointer should be
used.

Receiving Data

When a device driver is receiving data, it is its responsibility to set
checksum information when it has indicated that it supports the
MAC_CAPAB_HCKSUM capability. Device drivers will call the mac_hcksum_set()
function to indicate what checksum information has occurred.

The proper values to set depend on the flags passed in. The following
flags are supported when receiving data, note that they may have different
meanings from when transmitting data. The driver should set the flags
argument to the bitwise inclusive OR of the following values:

HCK_IPV4_HDRCKSUM_OK
This flag indicates that the hardware has verified the IPv4 header
is correct and that the networking stack does not need to verify
it.

HCK_PARTIALCKSUM
This flag indicates that the hardware has computed a partial
checksum. When this flag is set, the driver is responsible for
passing in the partial checksum in the value argument as well as
the start and ending bytes of the checksum in the start and end
arguments.

HCK_FULLCKSUM
This flag indicates that the hardware has calculated the full L4
header checksum; however, it wants the system to verify it. The
checksum should be passed in the value argument.

HCK_FULLCKSUM_OK
This flag indicates that the hardware has calculated the full L4
header checksum and verified that it is correct. The networking
stack does not need to verify it.

The HCK_PARTIALCKSUM, HCK_FULLCKSUM, and HCK_FULLCKSUM_OK flags are all
mutually exclusive. A device driver should only set one of the three
flags.

If one of the arguments is not required based on the specified value of
flags, then the device driver should set any remaining arguments to 0.

Transmitting Data

When a device driver is transmitting data and it has advertised that it
supports the MAC_CAPAB_HCKSUM capability, then it must call the
mac_hcksum_get() function to determine what hardware checksumming options
are required to be performed by the hardware. While the device driver may
need the other fields, it must check the flags argument to determine what
it is being requested to do. The following values may be set in flags:

HCK_IPV4_HDRCKSUM
The device driver must compute the IPv4 header checksum. No other
fields have been filled in.

HCK_PARTIALCKSUM
The device driver needs to compute the partial ones' complement of
the checksum. The system has filled in the start, stuff, and end
arguments to assist the device driver.

HCK_FULLCKSUM
The device driver should compute the full L4 checksum. No other
fields have been filled in for the device driver.

The flags that the device driver will get will depend on what the device
driver has advertised that it supports in response to the mc_getcapab(9E)
query for the MAC_CAPAB_HCKSUM capability.

The HCK_PARTIALCKSUM and HCK_FULLCKSUM flags are mutually exclusive.

CONTEXT

The mac_hcksum_get() and mac_hcksum_set() functions may be called from any
context.