.\"	$FabBSD$
.\"	$OpenBSD: mbuf_tags.9,v 1.24 2007/05/31 19:20:00 jmc Exp $
.\"
.\" The author of this man page is Angelos D. Keromytis (angelos@cis.upenn.edu)
.\"
.\" Copyright (c) 2001 Angelos D. Keromytis
.\"
.\" Permission to use, copy, and modify this software with or without
.\" fee is hereby granted, provided that this entire notice is included
.\" in all source code copies of any software which is or includes a copy
.\" or modification of this software.
.\"
.\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR
.\" IMPLIED WARRANTY. IN PARTICULAR, NONE OF THE AUTHORS MAKES ANY
.\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE
.\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR
.\" PURPOSE.
.\"
.Dd $Mdocdate: May 31 2007 $
.Dt MBUF_TAGS 9
.Os
.Sh NAME
.Nm mbuf_tags
.Nd a framework for generic packet attributes
.Sh SYNOPSIS
.Fd #include <sys/mbuf.h>
.Ft "struct m_tag *"
.Fn m_tag_get "int type" "int len" "int flags"
.Ft "struct m_tag *"
.Fn m_tag_find "struct mbuf *mbuf" "int type" "struct m_tag *tag"
.Ft void
.Fn m_tag_prepend "struct mbuf *mbuf" "struct m_tag *tag"
.Ft void
.Fn m_tag_delete "struct mbuf *mbuf" "struct m_tag *tag"
.Ft "struct m_tag *"
.Fn m_tag_copy "struct m_tag *tag"
.Ft void
.Fn m_tag_delete_chain "struct mbuf *mbuf"
.Ft void
.Fn m_tag_init "struct mbuf *mbuf"
.Ft int
.Fn m_tag_copy_chain "struct mbuf *mbuf" "struct mbuf *mbuf2"
.Ft "struct m_tag *"
.Fn m_tag_first "struct mbuf *mbuf"
.Ft "struct m_tag *"
.Fn m_tag_next "struct mbuf *mbuf" "struct m_tag *tag"
.Sh DESCRIPTION
These functions allow the manipulation of generic packet attributes.
They are used by the kernel to keep track of operations done or
scheduled to happen to packets.
These attributes are attached to mbuf packet headers.
.Pp
Mbuf tags get allocated using
.Xr malloc 9 ,
thus, due to the performance impact, mbuf tags should be used with care.
.Pp
.Fn m_tag_get
allocates a new tag of type
.Va type
with
.Va len
bytes of space following the tag header itself.
The
.Va flag
argument is passed directly to
.Xr malloc 9 .
If successful,
.Fn m_tag_get
returns a memory buffer of (len + sizeof (struct m_tag)) bytes.
The first sizeof(struct m_tag) bytes contain a struct m_tag:
.Bd -literal -offset 0i
struct m_tag {
	SLIST_ENTRY(m_tag)	m_tag_link;	/* List of packet tags */
	u_int16_t		m_tag_id;	/* Tag ID */
	u_int16_t		m_tag_len;	/* Length of data */
};
.Ed
.Pp
The
.Va m_tag_link
field is used to link tags together (see
.Xr queue 3
for more details).
The
.Va m_tag_id
and
.Va m_tag_len
fields are set to
.Va type
and
.Va len
respectively.
Following this structure are
.Va len
bytes of space that can be used to store tag-specific information.
.Pp
The currently defined tag types are:
.Bl -tag -width "111111111111"
.It PACKET_TAG_NONE
This should never be used.
.It PACKET_TAG_IPSEC_IN_DONE
Used by
.Xr ipsec 4
to indicate successful processing performed on an input packet.
The tag contains a
.Va struct tdb_ident ,
as defined in
.Pa sys/netinet/ip_ipsp.h ,
identifying the security association under which the packet arrived.
.It PACKET_TAG_IPSEC_OUT_DONE
Used by IPsec to indicate that an output packet has been
IPsec-processed.
The tag contains a
.Va struct tdb_ident
identifying the security association applied to the packet.
This tag is primarily used to detect and avoid loops in IPsec
processing on output.
.It PACKET_TAG_IPSEC_IN_CRYPTO_DONE
Used by network cards that implement on-board IPsec processing to
indicate that the crypto processing of an IPsec packet has been done.
The tag contains a
.Va struct tdb_ident
identifying the security association under which the packet arrived.
.It PACKET_TAG_IPSEC_OUT_CRYPTO_NEEDED
Used by the IPsec stack to signal to network cards that implement
on-board IPsec processing that such processing is needed.
The tag contains a
.Va struct tdb_ident
identifying the security association that should be applied.
The packet is already formatted for the appropriate security
protocol.
.It PACKET_TAG_IPSEC_IN_COULD_DO_CRYPTO
Used by network cards that implement on-board IPsec
processing to indicate to the IPsec stack that cryptographic
processing could be deferred to hardware.
The tag contains a
.Va struct tdb_ident
identifying the security association that could be offloaded to the
network card.
.It PACKET_TAG_IPSEC_PENDING_TDB
Used by the IPsec stack to keep track of IPsec processing that should
happen to the packet on output.
The tag contains a
.Va struct tdb_ident
identifying the security association that should be applied at the
next loop of IPsec processing.
.It PACKET_TAG_GIF
Used by the
.Xr gif 4
interface to detect loops in processing.
The tag contains a pointer to the gif interface that already processed
the packet.
.It PACKET_TAG_GRE
Used by the
.Xr gre 4
interface to detect loops in processing.
The tag contains a pointer to the gre interface that already processed
the packet.
.It PACKET_TAG_IN_PACKET_CHECKSUM
Used by network cards that can compute complete packet checksums to
pass that information to higher-level protocols.
The tag contains the 2 byte checksum of the packet.
.El
.Pp
.Fn m_tag_find
finds an instance of a tag of type
.Va type
attached to packet
.Va mbuf .
If
.Va tag
is
.Dv NULL ,
the first such tag is returned.
Otherwise, the first tag of type
.Va type
after
.Va tag
is returned.
If no such tag is found,
.Dv NULL
is returned.
.Pp
.Fn m_tag_prepend
adds the new tag
.Va tag
at the head of the tag list for packet
.Va mbuf .
.Pp
.Fn m_tag_delete
removes and then de-allocates tag
.Va tag
from the list of tags of packet
.Va mbuf .
.Pp
.Fn m_tag_copy
creates an unlinked copy of tag
.Va tag .
.Pp
.Fn m_tag_delete_chain
deletes all tags attached to packet
.Va mbuf .
.Pp
.Fn m_tag_init
initializes the tag storage for packet
.Va mbuf .
.Pp
.Fn m_tag_copy_chain
copies all tags from packet
.Va mbuf
to packet
.Va mbuf2 .
On success, it returns 1.
Otherwise, it returns 0.
.Pp
.Fn m_tag_first
returns the first tag attached to packet
.Va mbuf .
.Pp
.Fn m_tag_next
returns the tag following
.Va tag
in packet
.Va mbuf .
.Pp
The
.Fn M_MOVE_PKTHDR
and
.Fn M_MOVE_HDR
macros defined in
.Pa sys/sys/mbuf.h
move the tags from the old to the new mbuf.
The
.Fn M_DUP_PKTHDR
and
.Fn M_DUP_HDR
macros create copies of the tag chain for the new mbuf.
.Sh CODE REFERENCES
The tag-manipulating code is contained in the file
.Pa sys/kern/uipc_mbuf2.c .
.Sh SEE ALSO
.Xr gif 4 ,
.Xr gre 4 ,
.Xr ipsec 4 ,
.Xr malloc 9
.Sh HISTORY
The packet tags first appeared in
.Ox 2.9
and were written by
.An Angelos D. Keromytis Aq angelos@openbsd.org .