xref: /freebsd/sys/sys/mbuf.h (revision 41466b50c1d5bfd1cf6adaae547a579a75d7c04e)
1 /*
2  * Copyright (c) 1982, 1986, 1988, 1993
3  *	The Regents of the University of California.  All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  *    notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  *    notice, this list of conditions and the following disclaimer in the
12  *    documentation and/or other materials provided with the distribution.
13  * 3. All advertising materials mentioning features or use of this software
14  *    must display the following acknowledgement:
15  *	This product includes software developed by the University of
16  *	California, Berkeley and its contributors.
17  * 4. Neither the name of the University nor the names of its contributors
18  *    may be used to endorse or promote products derived from this software
19  *    without specific prior written permission.
20  *
21  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
22  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24  * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
25  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31  * SUCH DAMAGE.
32  *
33  *	@(#)mbuf.h	8.5 (Berkeley) 2/19/95
34  * $FreeBSD$
35  */
36 
37 #ifndef _SYS_MBUF_H_
38 #define	_SYS_MBUF_H_
39 
40 /*
41  * Mbufs are of a single size, MSIZE (machine/param.h), which
42  * includes overhead.  An mbuf may add a single "mbuf cluster" of size
43  * MCLBYTES (also in machine/param.h), which has no additional overhead
44  * and is used instead of the internal data area; this is done when
45  * at least MINCLSIZE of data must be stored. Additionally, it is possible
46  * to allocate a separate buffer externally and attach it to the mbuf in
47  * a way similar to that of mbuf clusters.
48  */
49 #define	MLEN		(MSIZE - sizeof(struct m_hdr))	/* normal data len */
50 #define	MHLEN		(MLEN - sizeof(struct pkthdr))	/* data len w/pkthdr */
51 #define	MINCLSIZE	(MHLEN + 1)	/* smallest amount to put in cluster */
52 #define	M_MAXCOMPRESS	(MHLEN / 2)	/* max amount to copy for compression */
53 
54 #ifdef _KERNEL
55 /*
56  * Macros for type conversion
57  * mtod(m, t)	- convert mbuf pointer to data pointer of correct type
58  * dtom(x)	- convert data pointer within mbuf to mbuf pointer (XXX)
59  */
60 #define	mtod(m, t)	((t)((m)->m_data))
61 #define	dtom(x)		((struct mbuf *)((intptr_t)(x) & ~(MSIZE-1)))
62 #endif /* _KERNEL */
63 
64 /*
65  * Header present at the beginning of every mbuf.
66  */
67 struct m_hdr {
68 	struct	mbuf *mh_next;		/* next buffer in chain */
69 	struct	mbuf *mh_nextpkt;	/* next chain in queue/record */
70 	caddr_t	mh_data;		/* location of data */
71 	int	mh_len;			/* amount of data in this mbuf */
72 	short	mh_type;		/* type of data in this mbuf */
73 	short	mh_flags;		/* flags; see below */
74 };
75 
76 /*
77  * Record/packet header in first mbuf of chain; valid only if M_PKTHDR is set.
78  */
79 struct pkthdr {
80 	struct	ifnet *rcvif;		/* rcv interface */
81 	int	len;			/* total packet length */
82 	/* variables for ip and tcp reassembly */
83 	void	*header;		/* pointer to packet header */
84 	/* variables for hardware checksum */
85 	int	csum_flags;		/* flags regarding checksum */
86 	int	csum_data;		/* data field used by csum routines */
87 	struct	mbuf *aux;		/* extra data buffer; ipsec/others */
88 };
89 
90 /*
91  * Description of external storage mapped into mbuf; valid only if M_EXT is set.
92  */
93 struct m_ext {
94 	caddr_t	ext_buf;		/* start of buffer */
95 	void	(*ext_free)		/* free routine if not the usual */
96 		    (caddr_t, void *);
97 	void	*ext_args;		/* optional argument pointer */
98 	u_int	ext_size;		/* size of buffer, for ext_free */
99 	u_int	*ref_cnt;		/* pointer to ref count info */
100 	int	ext_type;		/* type of external storage */
101 };
102 
103 /*
104  * The core of the mbuf object along with some shortcut defines for
105  * practical purposes.
106  */
107 struct mbuf {
108 	struct	m_hdr m_hdr;
109 	union {
110 		struct {
111 			struct	pkthdr MH_pkthdr;	/* M_PKTHDR set */
112 			union {
113 				struct	m_ext MH_ext;	/* M_EXT set */
114 				char	MH_databuf[MHLEN];
115 			} MH_dat;
116 		} MH;
117 		char	M_databuf[MLEN];		/* !M_PKTHDR, !M_EXT */
118 	} M_dat;
119 };
120 #define	m_next		m_hdr.mh_next
121 #define	m_len		m_hdr.mh_len
122 #define	m_data		m_hdr.mh_data
123 #define	m_type		m_hdr.mh_type
124 #define	m_flags		m_hdr.mh_flags
125 #define	m_nextpkt	m_hdr.mh_nextpkt
126 #define	m_act		m_nextpkt
127 #define	m_pkthdr	M_dat.MH.MH_pkthdr
128 #define	m_ext		M_dat.MH.MH_dat.MH_ext
129 #define	m_pktdat	M_dat.MH.MH_dat.MH_databuf
130 #define	m_dat		M_dat.M_databuf
131 
132 /*
133  * mbuf flags
134  */
135 #define	M_EXT		0x0001	/* has associated external storage */
136 #define	M_PKTHDR	0x0002	/* start of record */
137 #define	M_EOR		0x0004	/* end of record */
138 #define M_RDONLY	0x0008	/* associated data is marked read-only */
139 #define	M_PROTO1	0x0010	/* protocol-specific */
140 #define	M_PROTO2	0x0020	/* protocol-specific */
141 #define	M_PROTO3	0x0040	/* protocol-specific */
142 #define	M_PROTO4	0x0080	/* protocol-specific */
143 #define	M_PROTO5	0x0100	/* protocol-specific */
144 
145 /*
146  * mbuf pkthdr flags (also stored in m_flags)
147  */
148 #define	M_BCAST		0x0200	/* send/received as link-level broadcast */
149 #define	M_MCAST		0x0400	/* send/received as link-level multicast */
150 #define	M_FRAG		0x0800	/* packet is a fragment of a larger packet */
151 #define	M_FIRSTFRAG	0x1000	/* packet is first fragment */
152 #define	M_LASTFRAG	0x2000	/* packet is last fragment */
153 
154 /*
155  * External buffer types: identify ext_buf type
156  */
157 #define	EXT_CLUSTER	1	/* mbuf cluster */
158 #define	EXT_SFBUF	2	/* sendfile(2)'s sf_bufs */
159 #define	EXT_NET_DRV	100	/* custom ext_buf provided by net driver(s) */
160 #define	EXT_MOD_TYPE	200	/* custom module's ext_buf type */
161 
162 /*
163  * Flags copied when copying m_pkthdr
164  */
165 #define	M_COPYFLAGS	(M_PKTHDR|M_EOR|M_PROTO1|M_PROTO1|M_PROTO2|M_PROTO3 | \
166 			    M_PROTO4|M_PROTO5|M_BCAST|M_MCAST|M_FRAG|M_RDONLY)
167 
168 /*
169  * Flags indicating hw checksum support and sw checksum requirements
170  */
171 #define CSUM_IP			0x0001		/* will csum IP */
172 #define CSUM_TCP		0x0002		/* will csum TCP */
173 #define CSUM_UDP		0x0004		/* will csum UDP */
174 #define CSUM_IP_FRAGS		0x0008		/* will csum IP fragments */
175 #define CSUM_FRAGMENT		0x0010		/* will do IP fragmentation */
176 
177 #define CSUM_IP_CHECKED		0x0100		/* did csum IP */
178 #define CSUM_IP_VALID		0x0200		/*   ... the csum is valid */
179 #define CSUM_DATA_VALID		0x0400		/* csum_data field is valid */
180 #define CSUM_PSEUDO_HDR		0x0800		/* csum_data has pseudo hdr */
181 
182 #define CSUM_DELAY_DATA		(CSUM_TCP | CSUM_UDP)
183 #define CSUM_DELAY_IP		(CSUM_IP)	/* XXX add ipv6 here too? */
184 
185 /*
186  * mbuf types
187  */
188 #define	MT_NOTMBUF	0	/* USED INTERNALLY ONLY! Object is not mbuf */
189 #define	MT_DATA		1	/* dynamic (data) allocation */
190 #define	MT_HEADER	2	/* packet header */
191 #if 0
192 #define	MT_SOCKET	3	/* socket structure */
193 #define	MT_PCB		4	/* protocol control block */
194 #define	MT_RTABLE	5	/* routing tables */
195 #define	MT_HTABLE	6	/* IMP host tables */
196 #define	MT_ATABLE	7	/* address resolution tables */
197 #endif
198 #define	MT_SONAME	8	/* socket name */
199 #if 0
200 #define	MT_SOOPTS	10	/* socket options */
201 #endif
202 #define	MT_FTABLE	11	/* fragment reassembly header */
203 #if 0
204 #define	MT_RIGHTS	12	/* access rights */
205 #define	MT_IFADDR	13	/* interface address */
206 #endif
207 #define	MT_CONTROL	14	/* extra-data protocol message */
208 #define	MT_OOBDATA	15	/* expedited data  */
209 #define	MT_NTYPES	16	/* number of mbuf types for mbtypes[] */
210 
211 /*
212  * Mbuf and cluster allocation statistics PCPU structure.
213  */
214 struct mbpstat {
215 	u_long	mb_mbfree;
216 	u_long	mb_mbpgs;
217 	u_long	mb_clfree;
218 	u_long	mb_clpgs;
219 	long	mb_mbtypes[MT_NTYPES];
220 	short	mb_active;
221 };
222 
223 /*
224  * General mbuf allocator statistics structure.
225  * XXX: Modifications of these are not protected by any mutex locks nor by
226  *	any atomic() manipulations. As a result, we may occasionally lose
227  *	a count or two. Luckily, not all of these fields are modified at all
228  *	and remain static, and those that are manipulated are only manipulated
229  *	in failure situations, which do not occur (hopefully) very often.
230  */
231 struct mbstat {
232 	u_long	m_drops;	/* times failed to allocate */
233 	u_long	m_wait;		/* times succesfully returned from wait */
234 	u_long	m_drain;	/* times drained protocols for space */
235 	u_long	m_mcfail;	/* XXX: times m_copym failed */
236 	u_long	m_mpfail;	/* XXX: times m_pullup failed */
237 	u_long	m_msize;	/* length of an mbuf */
238 	u_long	m_mclbytes;	/* length of an mbuf cluster */
239 	u_long	m_minclsize;	/* min length of data to allocate a cluster */
240 	u_long	m_mlen;		/* length of data in an mbuf */
241 	u_long	m_mhlen;	/* length of data in a header mbuf */
242 	short	m_numtypes;	/* number of mbtypes (gives # elems in mbpstat's
243 				   mb_mbtypes[] array. */
244 };
245 
246 /*
247  * Flags specifying how an allocation should be made.
248  * M_DONTWAIT means "don't block if nothing is available" whereas
249  * M_TRYWAIT means "block for mbuf_wait ticks at most if nothing is
250  * available."
251  */
252 #define	M_DONTWAIT	1
253 #define	M_TRYWAIT	0
254 #define	M_WAIT		M_TRYWAIT	/* XXX: Deprecated. */
255 
256 #ifdef _KERNEL
257 /*
258  * mbuf external reference count management macros
259  *
260  * MEXT_IS_REF(m): true if (m) is not the only mbuf referencing
261  *     the external buffer ext_buf
262  *
263  * MEXT_REM_REF(m): remove reference to m_ext object
264  *
265  * MEXT_ADD_REF(m): add reference to m_ext object already
266  *     referred to by (m)
267  */
268 #define MEXT_IS_REF(m)	(*((m)->m_ext.ref_cnt) > 1)
269 
270 #define MEXT_REM_REF(m) do {						\
271 	KASSERT(*((m)->m_ext.ref_cnt) > 0, ("m_ext refcnt < 0"));	\
272 	atomic_subtract_int((m)->m_ext.ref_cnt, 1);			\
273 } while(0)
274 
275 #define MEXT_ADD_REF(m)	atomic_add_int((m)->m_ext.ref_cnt, 1)
276 
277 /*
278  * mbuf, cluster, and external object allocation macros
279  * (for compatibility purposes)
280  */
281 #define MGET(m, how, type) 						\
282 	(m) = m_get((how), (type))
283 
284 #define MGETHDR(m, how, type)		 				\
285 	(m) = m_gethdr((how), (type))
286 
287 #define	MCLGET(m, how)							\
288 	m_clget((m), (how))
289 
290 #define MEXTADD(m, buf, size, free, args, flags, type) 			\
291     m_extadd((m), (caddr_t)(buf), (size), (free), (args), (flags), (type))
292 
293 #define	MFREE(m, n) do {						\
294 	(n) = m_free((m));						\
295 	(m) = NULL;							\
296 } while (0)
297 
298 #define	m_getclr	m_get_clrd
299 
300 /*
301  * MEXTFREE(m): disassociate (and possibly free) an external object from `m'
302  *
303  * If the atomic_cmpset_int() returns 0, then we effectively do nothing
304  * in terms of "cleaning up" (freeing the ext buf and ref. counter) as
305  * this means that either there are still references, or another thread
306  * is taking care of the clean-up.
307  */
308 #define	MEXTFREE(m) do {						\
309 	struct mbuf *_mb = (m);						\
310 									\
311 	MEXT_REM_REF(_mb);						\
312 	if (atomic_cmpset_int(_mb->m_ext.ref_cnt, 0, 1))		\
313 		_mext_free(_mb);					\
314 	_mb->m_flags &= ~M_EXT;						\
315 } while (0)
316 
317 /*
318  * M_WRITABLE(m)
319  * Evaluate TRUE if it's safe to write to the mbuf m's data region (this
320  * can be both the local data payload, or an external buffer area,
321  * depending on whether M_EXT is set).
322  */
323 #define M_WRITABLE(m)	(!((m)->m_flags & M_RDONLY) && (!((m)->m_flags  \
324 			    & M_EXT) || !MEXT_IS_REF(m)))
325 
326 /*
327  * Copy mbuf pkthdr from "from" to "to".
328  * from must have M_PKTHDR set, and to must be empty.
329  * aux pointer will be moved to `to'.
330  */
331 #define	M_COPY_PKTHDR(to, from) do {					\
332 	struct	mbuf *_mfrom = (from);					\
333 	struct	mbuf *_mto = (to);					\
334 									\
335 	_mto->m_data = _mto->m_pktdat;					\
336 	_mto->m_flags = _mfrom->m_flags & M_COPYFLAGS;			\
337 	_mto->m_pkthdr = _mfrom->m_pkthdr;				\
338 	_mfrom->m_pkthdr.aux = NULL;					\
339 } while (0)
340 
341 /*
342  * Set the m_data pointer of a newly-allocated mbuf (m_get/MGET) to place
343  * an object of the specified size at the end of the mbuf, longword aligned.
344  */
345 #define	M_ALIGN(m, len) do {						\
346 	(m)->m_data += (MLEN - (len)) & ~(sizeof(long) - 1);		\
347 } while (0)
348 
349 /*
350  * As above, for mbufs allocated with m_gethdr/MGETHDR
351  * or initialized by M_COPY_PKTHDR.
352  */
353 #define	MH_ALIGN(m, len) do {						\
354 	(m)->m_data += (MHLEN - (len)) & ~(sizeof(long) - 1);		\
355 } while (0)
356 
357 /*
358  * Compute the amount of space available
359  * before the current start of data in an mbuf.
360  */
361 #define	M_LEADINGSPACE(m)						\
362 	((m)->m_flags & M_EXT ?						\
363 	    /* (m)->m_data - (m)->m_ext.ext_buf */ 0 :			\
364 	    (m)->m_flags & M_PKTHDR ? (m)->m_data - (m)->m_pktdat :	\
365 	    (m)->m_data - (m)->m_dat)
366 
367 /*
368  * Compute the amount of space available
369  * after the end of data in an mbuf.
370  */
371 #define	M_TRAILINGSPACE(m)						\
372 	((m)->m_flags & M_EXT ? (m)->m_ext.ext_buf +			\
373 	    (m)->m_ext.ext_size - ((m)->m_data + (m)->m_len) :		\
374 	    &(m)->m_dat[MLEN] - ((m)->m_data + (m)->m_len))
375 
376 /*
377  * Arrange to prepend space of size plen to mbuf m.
378  * If a new mbuf must be allocated, how specifies whether to wait.
379  * If the allocation fails, the original mbuf chain is freed and m is
380  * set to NULL.
381  */
382 #define	M_PREPEND(m, plen, how) do {					\
383 	struct	mbuf **_mmp = &(m);					\
384 	struct	mbuf *_mm = *_mmp;					\
385 	int	_mplen = (plen);					\
386 	int	__mhow = (how);						\
387 									\
388 	if (M_LEADINGSPACE(_mm) >= _mplen) {				\
389 		_mm->m_data -= _mplen;					\
390 		_mm->m_len += _mplen;					\
391 	} else								\
392 		_mm = m_prepend(_mm, _mplen, __mhow);			\
393 	if (_mm != NULL && _mm->m_flags & M_PKTHDR)			\
394 		_mm->m_pkthdr.len += _mplen;				\
395 	*_mmp = _mm;							\
396 } while (0)
397 
398 /*
399  * Change mbuf to new type.
400  * This is a relatively expensive operation and should be avoided.
401  */
402 #define	MCHTYPE(m, t)	m_chtype((m), (t))
403 
404 /* length to m_copy to copy all */
405 #define	M_COPYALL	1000000000
406 
407 /* compatibility with 4.3 */
408 #define	m_copy(m, o, l)	m_copym((m), (o), (l), M_DONTWAIT)
409 
410 /*
411  * pkthdr.aux type tags.
412  */
413 struct mauxtag {
414 	int	af;
415 	int	type;
416 	void*	p;
417 };
418 
419 extern	int		max_datalen;	/* MHLEN - max_hdr */
420 extern	int		max_hdr;	/* largest link + protocol header */
421 extern	int		max_linkhdr;	/* largest link-level header */
422 extern	int		max_protohdr;	/* largest protocol header */
423 extern	struct mbpstat	mb_statpcpu[];	/* Per-CPU allocation stats. */
424 extern	struct mbstat	mbstat;		/* General mbuf stats/infos. */
425 extern	int		nmbclusters;	/* Maximum number of clusters */
426 extern	int		nmbcnt;		/* Scale kmem_map for counter space */
427 extern	int		nmbufs;		/* Maximum number of mbufs */
428 extern	int		nsfbufs;	/* Number of sendfile(2) bufs */
429 
430 void		 m_adj(struct mbuf *, int);
431 struct	mbuf 	*m_aux_add(struct mbuf *, int, int);
432 struct	mbuf 	*m_aux_add2(struct mbuf *, int, int, void *);
433 void		 m_aux_delete(struct mbuf *, struct mbuf *);
434 struct	mbuf 	*m_aux_find(struct mbuf *, int, int);
435 struct	mbuf 	*m_aux_find2(struct mbuf *, int, int, void *);
436 void		 m_cat(struct mbuf *, struct mbuf *);
437 void		 m_chtype(struct mbuf *, short);
438 void		 m_clget(struct mbuf *, int);
439 void		 m_extadd(struct mbuf *, caddr_t, u_int,
440 		    void (*free)(caddr_t, void *), void *, short, int);
441 void		 m_copyback(struct mbuf *, int, int, caddr_t);
442 void		 m_copydata(const struct mbuf *, int, int, caddr_t);
443 struct	mbuf 	*m_copym(struct mbuf *, int, int, int);
444 struct	mbuf 	*m_copypacket(struct mbuf *, int);
445 struct	mbuf 	*m_devget(char *, int, int, struct ifnet *,
446 		    void (*copy)(char *, caddr_t, u_int));
447 struct	mbuf	*m_dup(struct mbuf *, int);
448 struct	mbuf	*m_free(struct mbuf *);
449 void		 m_freem(struct mbuf *);
450 struct	mbuf 	*m_get(int, int);
451 struct	mbuf 	*m_get_clrd(int, int);
452 struct	mbuf 	*m_gethdr(int, int);
453 struct	mbuf	*m_gethdr_clrd(int, int);
454 struct	mbuf 	*m_getm(struct mbuf *, int, int, int);
455 struct	mbuf 	*m_prepend(struct mbuf *, int, int);
456 void		 m_print(const struct mbuf *m);
457 struct	mbuf 	*m_pulldown(struct mbuf *, int, int, int *);
458 struct	mbuf 	*m_pullup(struct mbuf *, int);
459 struct	mbuf 	*m_split(struct mbuf *, int, int);
460 #endif /* _KERNEL */
461 
462 #endif /* !_SYS_MBUF_H_ */
463