1.\" $OpenBSD: mbuf_tags.9,v 1.18 2003/12/08 07:07:35 mcbride Exp $ 2.\" 3.\" The authors of this manual page are Angelos D. Keromytis 4.\" (angelos@cis.upenn.edu), Gleb Smirnoff <glebius@FreeBSD.org>, and 5.\" Robert Watson <rwatson@FreeBSD.org> 6.\" 7.\" Copyright (c) 2004 Robert N. M. Watson 8.\" Copyright (c) 2001 Angelos D. Keromytis 9.\" 10.\" Permission to use, copy, and modify this software with or without 11.\" fee is hereby granted, provided that this entire notice is included 12.\" in all source code copies of any software which is or includes a copy 13.\" or modification of this software. 14.\" 15.\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR 16.\" IMPLIED WARRANTY. IN PARTICULAR, NONE OF THE AUTHORS MAKES ANY 17.\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE 18.\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR 19.\" PURPOSE. 20.\" 21.\" $FreeBSD$ 22.\" 23.Dd December 28, 2021 24.Dt MBUF_TAGS 9 25.Os 26.Sh NAME 27.Nm mbuf_tags 28.Nd a framework for generic packet attributes 29.Sh SYNOPSIS 30.In sys/mbuf.h 31.Ft "struct m_tag *" 32.Fn m_tag_alloc "uint32_t cookie" "uint16_t type" "int len" "int wait" 33.Ft "struct m_tag *" 34.Fn m_tag_copy "struct m_tag *t" "int how" 35.Ft int 36.Fn m_tag_copy_chain "struct mbuf *to" "const struct mbuf *from" "int how" 37.Ft void 38.Fn m_tag_delete "struct mbuf *m" "struct m_tag *t" 39.Ft void 40.Fn m_tag_delete_chain "struct mbuf *m" "struct m_tag *t" 41.Ft void 42.Fn m_tag_delete_nonpersistent "struct mbuf *m" 43.Ft "struct m_tag *" 44.Fn m_tag_find "struct mbuf *m" "uint16_t type" "struct m_tag *start" 45.Ft "struct m_tag *" 46.Fn m_tag_first "struct mbuf *m" 47.Ft void 48.Fn m_tag_free "struct m_tag *t" 49.Ft "struct m_tag *" 50.Fn m_tag_get "uint16_t type" "int len" "int wait" 51.Ft void 52.Fn m_tag_init "struct mbuf *m" 53.Ft struct m_tag * 54.Fn m_tag_locate "struct mbuf *m" "uint32_t cookie" "uint16_t type" "struct m_tag *t" 55.Ft "struct m_tag *" 56.Fn m_tag_next "struct mbuf *m" "struct m_tag *t" 57.Ft void 58.Fn m_tag_prepend "struct mbuf *m" "struct m_tag *t" 59.Ft void 60.Fn m_tag_unlink "struct mbuf *m" "struct m_tag *t" 61.Sh DESCRIPTION 62Mbuf tags allow additional meta-data to be associated with in-flight packets 63by providing a mechanism for the tagging of additional kernel memory onto 64packet header mbufs. 65Tags are maintained in chains off of the 66.Xr mbuf 9 67header, and maintained using a series of API calls to allocate, search, and 68delete tags. 69Tags are identified using an ID and cookie that uniquely identify a class 70of data tagged onto the packet, and may contain an arbitrary amount of 71additional storage. 72Typical uses of mbuf tags include Mandatory Access Control (MAC) labels as 73described in 74.Xr mac 9 , 75IPsec policy information as described in 76.Xr ipsec 4 , 77and packet filter tags used by 78.Xr pf 4 . 79.Pp 80Tags will be maintained across a variety of operations, including the copying 81of packet headers using facilities such as 82.Fn M_COPY_PKTHDR 83and 84.Fn M_MOVE_PKTHDR . 85Any tags associated with an mbuf header will be automatically freed when the 86mbuf is freed, although some subsystems will wish to delete the tags prior 87to that time. 88.Pp 89Packet tags are used by different kernel APIs 90to keep track of operations done or 91scheduled to happen to packets. 92Each packet tag can be distinguished by its type and cookie. 93The cookie is used to identify a specific module or API. 94The packet tags are attached to mbuf packet headers. 95.Pp 96The first 97.Fn sizeof "struct m_tag" 98bytes of a tag contain a 99.Vt "struct m_tag" : 100.Bd -literal 101struct m_tag { 102 SLIST_ENTRY(m_tag) m_tag_link; /* List of packet tags */ 103 uint16_t m_tag_id; /* Tag ID */ 104 uint16_t m_tag_len; /* Length of data */ 105 uint32_t m_tag_cookie; /* ABI/Module ID */ 106 void (*m_tag_free)(struct m_tag *); 107}; 108.Ed 109.Pp 110The 111.Va m_tag_link 112field is used to link tags together (see 113.Xr queue 3 114for more details). 115The 116.Va m_tag_id , m_tag_len 117and 118.Va m_tag_cookie 119fields are set to type, length, 120and 121cookie, respectively. 122.Va m_tag_free 123points to 124.Fn m_tag_free_default . 125Following this structure are 126.Va m_tag_len 127bytes of space that can be used to store tag-specific information. 128Addressing this data region may be tricky. 129A safe way is embedding 130.Vt "struct m_tag" 131into a private data structure, as follows: 132.Bd -literal -offset indent 133struct foo { 134 struct m_tag tag; 135 ... 136}; 137struct foo *p = (struct foo *)m_tag_alloc(...); 138struct m_tag *mtag = &p->tag; 139.Ed 140.Pp 141Note that 142.Ox 143does not support cookies, it needs 144.Va m_tag_id 145to be globally unique. 146To keep compatibility with 147.Ox , 148a cookie 149.Dv MTAG_ABI_COMPAT 150is provided along with some compatibility functions. 151When writing an 152.Ox 153compatible code, one should be careful not to take already 154used tag type. 155Tag types are defined in 156.In sys/mbuf.h . 157.Ss Packet Tag Manipulation Functions 158.Bl -ohang -offset indent 159.It Fn m_tag_alloc cookie type len wait 160Allocate a new tag of type 161.Fa type 162and cookie 163.Fa cookie 164with 165.Va len 166bytes of space following the tag header itself. 167The 168.Fa wait 169argument is passed directly to 170.Xr malloc 9 . 171If successful, 172.Fn m_tag_alloc 173returns a memory buffer of 174.Pq Va len No + Fn sizeof "struct m_tag" 175bytes. 176Otherwise, 177.Dv NULL 178is returned. 179A compatibility function 180.Fn m_tag_get 181is also provided. 182.It Fn m_tag_copy tag how 183Allocate a copy of 184.Fa tag . 185The 186.Fa how 187argument is passed directly to 188.Fn m_tag_alloc . 189The return values are the same as in 190.Fn m_tag_alloc . 191.It Fn m_tag_copy_chain tombuf frommbuf how 192Allocate and copy all tags from mbuf 193.Fa frommbuf 194to mbuf 195.Fa tombuf . 196Returns 1 on success, and 0 on failure. 197In the latter case, mbuf 198.Fa tombuf 199loses all its tags, even previously present. 200.It Fn m_tag_delete mbuf tag 201Remove 202.Fa tag 203from 204.Fa mbuf Ns 's 205list and free it. 206.It Fn m_tag_delete_chain mbuf tag 207Remove and free a packet tag chain, starting from 208.Fa tag . 209If 210.Fa tag 211is 212.Dv NULL , 213all tags are deleted. 214.It Fn m_tag_delete_nonpersistent mbuf 215Traverse 216.Fa mbuf Ns 's 217tags and delete those which do not have the 218.Dv MTAG_PERSISTENT 219flag set. 220.It Fn m_tag_first mbuf 221Return the first tag associated with 222.Fa mbuf . 223.It Fn m_tag_free tag 224Free 225.Fa tag 226using its 227.Va m_tag_free 228method. 229The 230.Fn m_tag_free_default 231function 232is used by default. 233.It Fn m_tag_init mbuf 234Initialize the tag storage for packet 235.Fa mbuf . 236.It Fn m_tag_locate mbuf cookie type tag 237Search for a tag defined by 238.Fa type 239and 240.Fa cookie 241in 242.Fa mbuf , 243starting from position specified by 244.Fa tag . 245If the latter is 246.Dv NULL , 247then search through the whole list. 248Upon success, a pointer to the first found tag is returned. 249In either case, 250.Dv NULL 251is returned. 252A compatibility function 253.Fn m_tag_find 254is also provided. 255.It Fn m_tag_next mbuf tag 256Return tag next to 257.Fa tag 258in 259.Fa mbuf . 260If absent, 261.Dv NULL 262is returned. 263.It Fn m_tag_prepend mbuf tag 264Add the new tag 265.Fa tag 266at the head of the tag list for packet 267.Fa mbuf . 268.It Fn m_tag_unlink mbuf tag 269Remove tag 270.Fa tag 271from the list of tags of packet 272.Fa mbuf . 273.El 274.Sh CODE REFERENCES 275The tag-manipulating code is contained in the file 276.Pa sys/kern/uipc_mbuf2.c . 277Inlined functions are defined in 278.In sys/mbuf.h . 279.Sh SEE ALSO 280.Xr queue 3 , 281.Xr mbuf 9 282.Sh HISTORY 283The packet tags first appeared in 284.Ox 2.9 285and were written by 286.An Angelos D. Keromytis Aq Mt angelos@openbsd.org . 287