1 .\" Copyright (c) 2000 FreeBSD Inc.
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL [your name] OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .Nd "memory management in the kernel IPC subsystem"
40 .Ss Mbuf allocation macros
41 .Fn MGET "struct mbuf *mbuf" "int how" "short type"
42 .Fn MGETHDR "struct mbuf *mbuf" "int how" "short type"
43 .Fn MCLGET "struct mbuf *mbuf" "int how"
45 .Fa "struct mbuf *mbuf"
48 .Fa "void (*free)(void *opt_arg1, void *opt_arg2)"
54 .Fn MEXTFREE "struct mbuf *mbuf"
55 .Fn MFREE "struct mbuf *mbuf" "struct mbuf *successor"
57 .Ss Mbuf utility macros
58 .Fn mtod "struct mbuf *mbuf" "type"
59 .Fn M_ALIGN "struct mbuf *mbuf" "u_int len"
60 .Fn MH_ALIGN "struct mbuf *mbuf" "u_int len"
62 .Fn M_LEADINGSPACE "struct mbuf *mbuf"
64 .Fn M_TRAILINGSPACE "struct mbuf *mbuf"
65 .Fn M_MOVE_PKTHDR "struct mbuf *to" "struct mbuf *from"
66 .Fn M_PREPEND "struct mbuf *mbuf" "int len" "int how"
67 .Fn MCHTYPE "struct mbuf *mbuf" "u_int type"
69 .Fn M_WRITABLE "struct mbuf *mbuf"
71 .Ss Mbuf allocation functions
73 .Fn m_get "int how" "int type"
75 .Fn m_getm "struct mbuf *orig" "int len" "int how" "int type"
77 .Fn m_getcl "int how" "short type" "int flags"
79 .Fn m_getclr "int how" "int type"
81 .Fn m_gethdr "int how" "int type"
83 .Fn m_free "struct mbuf *mbuf"
85 .Fn m_freem "struct mbuf *mbuf"
87 .Ss Mbuf utility functions
89 .Fn m_adj "struct mbuf *mbuf" "int len"
91 .Fn m_align "struct mbuf *mbuf" "int len"
93 .Fn m_append "struct mbuf *mbuf" "int len" "c_caddr_t cp"
95 .Fn m_prepend "struct mbuf *mbuf" "int len" "int how"
97 .Fn m_copyup "struct mbuf *mbuf" "int len" "int dstoff"
99 .Fn m_pullup "struct mbuf *mbuf" "int len"
101 .Fn m_pulldown "struct mbuf *mbuf" "int offset" "int len" "int *offsetp"
103 .Fn m_copym "struct mbuf *mbuf" "int offset" "int len" "int how"
105 .Fn m_copypacket "struct mbuf *mbuf" "int how"
107 .Fn m_dup "struct mbuf *mbuf" "int how"
109 .Fn m_copydata "const struct mbuf *mbuf" "int offset" "int len" "caddr_t buf"
111 .Fn m_copyback "struct mbuf *mbuf" "int offset" "int len" "caddr_t buf"
117 .Fa "struct ifnet *ifp"
118 .Fa "void (*copy)(char *from, caddr_t to, u_int len)"
121 .Fn m_cat "struct mbuf *m" "struct mbuf *n"
123 .Fn m_fixhdr "struct mbuf *mbuf"
125 .Fn m_dup_pkthdr "struct mbuf *to" "struct mbuf *from"
127 .Fn m_move_pkthdr "struct mbuf *to" "struct mbuf *from"
129 .Fn m_length "struct mbuf *mbuf" "struct mbuf **last"
131 .Fn m_split "struct mbuf *mbuf" "int len" "int how"
133 .Fn m_apply "struct mbuf *mbuf" "int off" "int len" "int (*f)(void *arg, void *data, u_int len)" "void *arg"
135 .Fn m_getptr "struct mbuf *mbuf" "int loc" "int *off"
137 .Fn m_defrag "struct mbuf *m0" "int how"
139 .Fn m_unshare "struct mbuf *m0" "int how"
144 is a basic unit of memory management in the kernel IPC subsystem.
145 Network packets and socket buffers are stored in
147 A network packet may span multiple
152 which allows adding or trimming
153 network headers with little overhead.
155 While a developer should not bother with
157 internals without serious
158 reason in order to avoid incompatibilities with future changes, it
159 is useful to understand the general structure of an
164 consists of a variable-sized header and a small internal
169 is a constant defined in
175 .Bl -tag -width "m_nextpkt" -offset indent
178 A pointer to the next
184 A pointer to the next
189 A pointer to data attached to this
193 The length of the data.
196 The type of the data.
206 flag bits are defined as follows:
209 #define M_EXT 0x0001 /* has associated external storage */
210 #define M_PKTHDR 0x0002 /* start of record */
211 #define M_EOR 0x0004 /* end of record */
212 #define M_RDONLY 0x0008 /* associated data marked read-only */
213 #define M_PROTO1 0x0010 /* protocol-specific */
214 #define M_PROTO2 0x0020 /* protocol-specific */
215 #define M_PROTO3 0x0040 /* protocol-specific */
216 #define M_PROTO4 0x0080 /* protocol-specific */
217 #define M_PROTO5 0x0100 /* protocol-specific */
218 #define M_PROTO6 0x4000 /* protocol-specific (avoid M_BCAST conflict) */
219 #define M_FREELIST 0x8000 /* mbuf is on the free list */
221 /* mbuf pkthdr flags (also stored in m_flags) */
222 #define M_BCAST 0x0200 /* send/received as link-level broadcast */
223 #define M_MCAST 0x0400 /* send/received as link-level multicast */
224 #define M_FRAG 0x0800 /* packet is fragment of larger packet */
225 #define M_FIRSTFRAG 0x1000 /* packet is first fragment */
226 #define M_LASTFRAG 0x2000 /* packet is last fragment */
231 types are defined as follows:
234 #define MT_DATA 1 /* dynamic (data) allocation */
235 #define MT_HEADER MT_DATA /* packet header */
236 #define MT_SONAME 8 /* socket name */
237 #define MT_CONTROL 14 /* extra-data protocol message */
238 #define MT_OOBDATA 15 /* expedited data */
244 .Vt struct pkthdr Va m_pkthdr
248 It contains a pointer to the interface
249 the packet has been received from
250 .Pq Vt struct ifnet Va *rcvif ,
251 and the total packet length
253 Optionally, it may also contain an attached list of packet tags
254 .Pq Vt "struct m_tag" .
258 Fields used in offloading checksum calculation to the hardware are kept in
262 .Sx HARDWARE-ASSISTED CHECKSUM CALCULATION
265 If small enough, data is stored in the internal data buffer of an
267 If the data is sufficiently large, another
271 or external storage may be associated with the
274 bytes of data can fit into an
282 If external storage is being associated with an
286 header is added at the cost of losing the internal data buffer.
287 It includes a pointer to external storage, the size of the storage,
288 a pointer to a function used for freeing the storage,
289 a pointer to an optional argument that can be passed to the function,
290 and a pointer to a reference counter.
293 using external storage has the
297 The system supplies a macro for allocating the desired external storage
301 The allocation and management of the reference counter is handled by the
304 The system also supplies a default type of external storage buffer called an
307 can be allocated and configured with the use of the
314 in size, where MCLBYTES is a machine-dependent constant.
315 The system defines an advisory macro
317 which is the smallest amount of data to put into an
319 It is equal to the sum of
323 It is typically preferable to store data into the data region of an
325 if size permits, as opposed to allocating a separate
327 to hold the same data.
329 .Ss Macros and Functions
330 There are numerous predefined macros and functions that provide the
331 developer with common utilities.
333 .Bl -ohang -offset indent
334 .It Fn mtod mbuf type
337 pointer to a data pointer.
338 The macro expands to the data pointer cast to the pointer of the specified
341 It is advisable to ensure that there is enough contiguous data in
346 .It Fn MGET mbuf how type
349 and initialize it to contain internal data.
351 will point to the allocated
353 on success, or be set to
358 argument is to be set to
362 It specifies whether the caller is willing to block if necessary.
367 a failed allocation will result in the caller being put
368 to sleep for a designated
373 A number of other functions and macros related to
375 have the same argument because they may
376 at some point need to allocate new
379 Programmers should be careful not to confuse the
387 They are not the same.
388 .It Fn MGETHDR mbuf how type
391 and initialize it to contain a packet header
396 .It Fn MCLGET mbuf how
397 Allocate and attach an
401 If the macro fails, the
403 flag will not be set in
405 .It Fn M_ALIGN mbuf len
408 to place an object of the size
410 at the end of the internal data area of
415 is newly allocated with
419 .It Fn MH_ALIGN mbuf len
420 Serves the same purpose as
432 .It Fn m_align mbuf len
433 Services the same purpose as
435 but handles any type of mbuf.
436 .It Fn M_LEADINGSPACE mbuf
437 Returns the number of bytes available before the beginning
440 .It Fn M_TRAILINGSPACE mbuf
441 Returns the number of bytes available after the end of data in
443 .It Fn M_PREPEND mbuf len how
444 This macro operates on an
446 It is an optimized wrapper for
448 that can make use of possible empty space before data
449 (e.g.\& left after trimming of a link-layer header).
457 .It Fn M_MOVE_PKTHDR to from
458 Using this macro is equivalent to calling
459 .Fn m_move_pkthdr to from .
460 .It Fn M_WRITABLE mbuf
461 This macro will evaluate true if
467 does not contain external storage or,
469 then if the reference count of the storage is not greater than 1.
474 This can be achieved during setup of the external storage,
481 macro, or can be directly set in individual
483 .It Fn MCHTYPE mbuf type
488 This is a relatively expensive operation and should be avoided.
492 .Bl -ohang -offset indent
493 .It Fn m_get how type
494 A function version of
496 for non-critical paths.
497 .It Fn m_getm orig len how type
504 if necessary and append the resulting allocated
510 .No non- Ns Dv NULL .
511 If the allocation fails at any point,
512 free whatever was allocated and return
517 .No non- Ns Dv NULL ,
518 it will not be freed.
519 It is possible to use
527 (for example, one which may be sitting in a pre-allocated ring)
528 or to simply perform an all-or-nothing
533 .It Fn m_gethdr how type
534 A function version of
536 for non-critical paths.
537 .It Fn m_getcl how type flags
543 If one of the allocations fails, the entire allocation fails.
544 This routine is the preferred way of fetching both the
548 together, as it avoids having to unlock/relock between allocations.
552 .It Fn m_getclr how type
555 and zero out the data region.
565 The functions below operate on
567 .Bl -ohang -offset indent
571 including any external storage.
573 .It Fn m_adj mbuf len
576 bytes from the head of an
580 is positive, from the tail otherwise.
582 .It Fn m_append mbuf len cp
589 Extend the mbuf chain if the new data does not fit in
592 .It Fn m_prepend mbuf len how
595 and prepend it to the
601 It does not allocate any
613 .It Fn m_copyup mbuf len dstoff
618 bytes of data into a new mbuf at
623 argument aligns the data and leaves room for a link layer header.
633 The function does not allocate
640 .It Fn m_pullup mbuf len
641 Arrange that the first
645 are contiguous and lay in the data area of
647 so they are accessible with
649 It is important to remember that this may involve
650 reallocating some mbufs and moving data so all pointers
651 referencing data within the old mbuf chain
652 must be recalculated or made invalid.
660 is freed in this case).
662 It does not allocate any
669 .It Fn m_pulldown mbuf offset len offsetp
678 are contiguous and lay in the data area of
680 so they are accessible with
682 .Fa len must be smaller than, or equal to, the size of an
684 Return a pointer to an intermediate
686 in the chain containing the requested region;
687 the offset in the data region of the
689 to the data contained in the returned mbuf is stored in
693 is NULL, the region may be accessed using
697 is non-NULL, the region may be accessed using
698 .Fn mtod mbuf uint8_t + *offsetp .
699 The region of the mbuf chain between its beginning and
701 is not modified, therefore it is safe to hold pointers to data within
702 this region before calling
705 .It Fn m_copym mbuf offset len how
710 bytes from the beginning, continuing for
717 copy to the end of the
720 The copy is read-only, because the
722 are not copied, only their reference counts are incremented.
724 .It Fn m_copypacket mbuf how
725 Copy an entire packet including header, which must be present.
726 This is an optimized version of the common case
727 .Fn m_copym mbuf 0 M_COPYALL how .
729 the copy is read-only, because the
731 are not copied, only their reference counts are incremented.
733 .It Fn m_dup mbuf how
736 into a completely new
738 including copying any
742 when you need a writable copy of an
745 .It Fn m_copydata mbuf offset len buf
750 bytes from the beginning, continuing for
752 bytes, into the indicated buffer
755 .It Fn m_copyback mbuf offset len buf
758 bytes from the buffer
760 back into the indicated
764 bytes from the beginning of the
770 It does not allocate any
782 will be allocated to fill the space.
784 .It Fn m_length mbuf last
785 Return the length of the
787 and optionally a pointer to the last
790 .It Fn m_dup_pkthdr to from how
791 Upon the function's completion, the
794 will contain an identical copy of
796 and the per-packet attributes found in the
806 must be empty on entry.
808 .It Fn m_move_pkthdr to from
811 and the per-packet attributes from the
824 must be empty on entry.
825 Upon the function's completion,
829 and the per-packet attributes cleared.
832 Set the packet-header length to the length of the
835 .It Fn m_devget buf len offset ifp copy
836 Copy data from a device local memory pointed to by
840 The copy is done using a specified copy routine
856 must be of the same type.
858 is still valid after the function returned.
864 .It Fn m_split mbuf len how
867 in two pieces, returning the tail:
871 In case of failure, it returns
873 and attempts to restore the
875 to its original state.
877 .It Fn m_apply mbuf off len f arg
878 Apply a function to an
885 Typically used to avoid calls to
887 which would otherwise be unnecessary or undesirable.
889 is a convenience argument which is passed to the callback function
894 is called, it will be passed
898 in the current mbuf, and the length
900 of the data in this mbuf to which the function should be applied.
902 The function should return zero to indicate success;
903 otherwise, if an error is indicated, then
905 will return the error and stop iterating through the
908 .It Fn m_getptr mbuf loc off
909 Return a pointer to the mbuf containing the data located at
911 bytes from the beginning of the
913 The corresponding offset into the mbuf will be stored in
915 .It Fn m_defrag m0 how
916 Defragment an mbuf chain, returning the shortest possible
917 chain of mbufs and clusters.
918 If allocation fails and this can not be completed,
920 will be returned and the original chain will be unchanged.
921 Upon success, the original chain will be freed and the new
922 chain will be returned.
928 depending on the caller's preference.
930 This function is especially useful in network drivers, where
931 certain long mbuf chains must be shortened before being added
932 to TX descriptor lists.
933 .It Fn m_unshare m0 how
934 Create a version of the specified mbuf chain whose
935 contents can be safely modified without affecting other users.
936 If allocation fails and this operation can not be completed,
939 The original mbuf chain is always reclaimed and the reference
940 count of any shared mbuf clusters is decremented.
946 depending on the caller's preference.
947 As a side-effect of this process the returned
948 mbuf chain may be compacted.
950 This function is especially useful in the transmit path of
951 network code, when data must be encrypted or otherwise
952 altered prior to transmission.
954 .Sh HARDWARE-ASSISTED CHECKSUM CALCULATION
955 This section currently applies to TCP/IP only.
956 In order to save the host CPU resources, computing checksums is
957 offloaded to the network interface hardware if possible.
960 member of the leading
962 of a packet contains two fields used for that purpose,
963 .Vt int Va csum_flags
965 .Vt int Va csum_data .
966 The meaning of those fields depends on the direction a packet flows in,
967 and on whether the packet is fragmented.
973 will denote the corresponding field of the
975 member of the leading
979 containing the packet.
981 On output, checksum offloading is attempted after the outgoing
982 interface has been determined for a packet.
983 The interface-specific field
984 .Va ifnet.if_data.ifi_hwassist
987 is consulted for the capabilities of the interface to assist in
991 field of the packet header is set to indicate which actions the interface
992 is supposed to perform on it.
993 The actions unsupported by the network interface are done in the
994 software prior to passing the packet down to the interface driver;
995 such actions will never be requested through
998 The flags demanding a particular action from an interface are as follows:
999 .Bl -tag -width ".Dv CSUM_TCP" -offset indent
1001 The IP header checksum is to be computed and stored in the
1002 corresponding field of the packet.
1003 The hardware is expected to know the format of an IP header
1004 to determine the offset of the IP checksum field.
1006 The TCP checksum is to be computed.
1009 The UDP checksum is to be computed.
1013 Should a TCP or UDP checksum be offloaded to the hardware,
1016 will contain the byte offset of the checksum field relative to the
1017 end of the IP header.
1018 In this case, the checksum field will be initially
1019 set by the TCP/IP module to the checksum of the pseudo header
1020 defined by the TCP and UDP specifications.
1022 For outbound packets which have been fragmented
1023 by the host CPU, the following will also be true,
1024 regardless of the checksum flag settings:
1025 .Bl -bullet -offset indent
1027 all fragments will have the flag
1033 the first and the last fragments in the chain will have
1041 the first fragment in the chain will have the total number
1042 of fragments contained in its
1047 The last rule for fragmented packets takes precedence over the one
1048 for a TCP or UDP checksum.
1049 Nevertheless, offloading a TCP or UDP checksum is possible for a
1050 fragmented packet if the flag
1053 .Va ifnet.if_data.ifi_hwassist
1054 associated with the network interface.
1055 However, in this case the interface is expected to figure out
1056 the location of the checksum field within the sequence of fragments
1059 contains a fragment count instead of a checksum offset value.
1061 On input, an interface indicates the actions it has performed
1062 on a packet by setting one or more of the following flags in
1064 associated with the packet:
1065 .Bl -tag -width ".Dv CSUM_IP_CHECKED" -offset indent
1066 .It Dv CSUM_IP_CHECKED
1067 The IP header checksum has been computed.
1068 .It Dv CSUM_IP_VALID
1069 The IP header has a valid checksum.
1070 This flag can appear only in combination with
1071 .Dv CSUM_IP_CHECKED .
1072 .It Dv CSUM_DATA_VALID
1073 The checksum of the data portion of the IP packet has been computed
1074 and stored in the field
1076 in network byte order.
1077 .It Dv CSUM_PSEUDO_HDR
1078 Can be set only along with
1080 to indicate that the IP data checksum found in
1082 allows for the pseudo header defined by the TCP and UDP specifications.
1083 Otherwise the checksum of the pseudo header must be calculated by
1084 the host CPU and added to
1086 to obtain the final checksum to be used for TCP or UDP validation purposes.
1089 If a particular network interface just indicates success or
1090 failure of TCP or UDP checksum validation without returning
1091 the exact value of the checksum to the host CPU, its driver can mark
1101 hexadecimal to indicate a valid checksum.
1102 It is a peculiarity of the algorithm used that the Internet checksum
1103 calculated over any valid packet will be
1105 as long as the original checksum field is included.
1107 For inbound packets which are IP fragments, all
1109 fields will be summed during reassembly to obtain the final checksum
1110 value passed to an upper layer in the
1112 field of the reassembled packet.
1115 fields of all fragments will be consolidated using logical AND
1116 to obtain the final value for
1118 Thus, in order to successfully
1119 offload checksum computation for fragmented data,
1120 all fragments should have the same value of
1123 When running a kernel compiled with the option
1124 .Dv MBUF_STRESS_TEST ,
1127 -controlled options may be used to create
1128 various failure/extreme cases for testing of network drivers
1129 and other parts of the kernel that rely on
1131 .Bl -tag -width ident
1132 .It Va net.inet.ip.mbuf_frag_size
1135 to fragment outgoing
1137 into fragments of the specified size.
1138 Setting this variable to 1 is an excellent way to
1141 handling ability of network drivers.
1142 .It Va kern.ipc.m_defragrandomfailures
1145 to randomly fail, returning
1147 Any piece of code which uses
1149 should be tested with this feature.
1157 .\" Please correct me if I'm wrong
1159 appeared in an early version of
1161 Besides being used for network packets, they were used
1162 to store various dynamic structures, such as routing table
1163 entries, interface addresses, protocol control blocks, etc.
1168 is almost entirely limited to packet storage, with
1170 zones being used directly to store other network-related memory.
1174 allocator has been a special-purpose memory allocator able to run in
1175 interrupt contexts and allocating from a special kernel address space map.
1180 allocator is a wrapper around
1186 + cluster pairs in per-CPU caches, as well as bringing other benefits of
1191 manual page was written by Yar Tikhiy.
1195 allocator was written by Bosko Milekic.
projects / FreeBSD / FreeBSD.git / blob