share/doc/smm/18.net/5.t

   1 .\" Copyright (c) 1983, 1986, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   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.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)5.t 8.1 (Berkeley) 6/8/93
  33 .\"
  34 .nr H2 1
  35 .\".ds RH "Memory management
  36 .br
  37 .ne 2i
  38 .NH
  39 \s+2Memory management\s0
  40 .PP
  41 A single mechanism is used for data storage: memory buffers, or
  42 \fImbuf\fP's.  An mbuf is a structure of the form:
  43 .DS
  44 ._f
  45 struct mbuf {
  46         struct  mbuf *m_next;           /* next buffer in chain */
  47         u_long  m_off;                  /* offset of data */
  48         short   m_len;                  /* amount of data in this mbuf */
  49         short   m_type;                 /* mbuf type (accounting) */
  50         u_char  m_dat[MLEN];            /* data storage */
  51         struct  mbuf *m_act;            /* link in higher-level mbuf list */
  52 };
  53 .DE
  54 The \fIm_next\fP field is used to chain mbufs together on linked
  55 lists, while the \fIm_act\fP field allows lists of mbuf chains to be
  56 accumulated.  By convention, the mbufs common to a single object
  57 (for example, a packet) are chained together with the \fIm_next\fP
  58 field, while groups of objects are linked via the \fIm_act\fP
  59 field (possibly when in a queue).
  60 .PP
  61 Each mbuf has a small data area for storing information, \fIm_dat\fP.
  62 The \fIm_len\fP field indicates the amount of data, while the \fIm_off\fP
  63 field is an offset to the beginning of the data from the base of the
  64 mbuf.  Thus, for example, the macro \fImtod\fP, which converts a pointer
  65 to an mbuf to a pointer to the data stored in the mbuf, has the form
  66 .DS
  67 ._d
  68 #define mtod(\fIx\fP,\fIt\fP)   ((\fIt\fP)((int)(\fIx\fP) + (\fIx\fP)->m_off))
  69 .DE
  70 (note the \fIt\fP parameter, a C type cast, which is used to cast
  71 the resultant pointer for proper assignment).
  72 .PP
  73 In addition to storing data directly in the mbuf's data area, data
  74 of page size may be also be stored in a separate area of memory.
  75 The mbuf utility routines maintain
  76 a pool of pages for this purpose and manipulate a private page map
  77 for such pages.
  78 An mbuf with an external data area may be recognized by the larger
  79 offset to the data area;
  80 this is formalized by the macro M_HASCL(\fIm\fP), which is true
  81 if the mbuf whose address is \fIm\fP has an external page cluster.
  82 An array of reference counts on pages is also maintained
  83 so that copies of pages may be made without core to core
  84 copying  (copies are created simply by duplicating the reference to the data
  85 and incrementing the associated reference counts for the pages).
  86 Separate data pages are currently used only
  87 when copying data from a user process into the kernel,
  88 and when bringing data in at the hardware level.  Routines which
  89 manipulate mbufs are not normally aware whether data is stored directly in
  90 the mbuf data array, or if it is kept in separate pages.
  91 .PP
  92 The following may be used to allocate and free mbufs:
  93 .LP
  94 m = m_get(wait, type);
  95 .br
  96 MGET(m, wait, type);
  97 .IP
  98 The subroutine \fIm_get\fP and the macro \fIMGET\fP
  99 each allocate an mbuf, placing its address in \fIm\fP.
 100 The argument \fIwait\fP is either M_WAIT or M_DONTWAIT according
 101 to whether allocation should block or fail if no mbuf is available.
 102 The \fItype\fP is one of the predefined mbuf types for use in accounting
 103 of mbuf allocation.
 104 .IP "MCLGET(m);"
 105 This macro attempts to allocate an mbuf page cluster
 106 to associate with the mbuf \fIm\fP.
 107 If successful, the length of the mbuf is set to CLSIZE,
 108 the size of the page cluster.
 109 .LP
 110 n = m_free(m);
 111 .br
 112 MFREE(m,n);
 113 .IP
 114 The routine \fIm_free\fP and the macro \fIMFREE\fP
 115 each free a single mbuf, \fIm\fP, and any associated external storage area,
 116 placing a pointer to its successor in the chain it heads, if any, in \fIn\fP.
 117 .IP "m_freem(m);"
 118 This routine frees an mbuf chain headed by \fIm\fP.
 119 .PP
 120 The following utility routines are available for manipulating mbuf
 121 chains:
 122 .IP "m = m_copy(m0, off, len);"
 123 .br
 124 The \fIm_copy\fP routine create a copy of all, or part, of a
 125 list of the mbufs in \fIm0\fP.  \fILen\fP bytes of data, starting
 126 \fIoff\fP bytes from the front of the chain, are copied.
 127 Where possible, reference counts on pages are used instead
 128 of core to core copies.  The original mbuf chain must have at
 129 least \fIoff\fP + \fIlen\fP bytes of data.  If \fIlen\fP is
 130 specified as M_COPYALL, all the data present, offset
 131 as before, is copied.
 132 .IP "m_cat(m, n);"
 133 .br
 134 The mbuf chain, \fIn\fP, is appended to the end of \fIm\fP.
 135 Where possible, compaction is performed.
 136 .IP "m_adj(m, diff);"
 137 .br
 138 The mbuf chain, \fIm\fP is adjusted in size by \fIdiff\fP
 139 bytes.  If \fIdiff\fP is non-negative, \fIdiff\fP bytes
 140 are shaved off the front of the mbuf chain.  If \fIdiff\fP
 141 is negative, the alteration is performed from back to front.
 142 No space is reclaimed in this operation; alterations are
 143 accomplished by changing the \fIm_len\fP and \fIm_off\fP
 144 fields of mbufs.
 145 .IP "m = m_pullup(m0, size);"
 146 .br
 147 After a successful call to \fIm_pullup\fP, the mbuf at
 148 the head of the returned list, \fIm\fP, is guaranteed
 149 to have at least \fIsize\fP
 150 bytes of data in contiguous memory within the data area of the mbuf
 151 (allowing access via a pointer, obtained using the \fImtod\fP macro,
 152 and allowing the mbuf to be located from a pointer to the data area
 153 using \fIdtom\fP, defined below).
 154 If the original data was less than \fIsize\fP bytes long,
 155 \fIlen\fP was greater than the size of an mbuf data
 156 area (112 bytes), or required resources were unavailable,
 157 \fIm\fP is 0 and the original mbuf chain is deallocated.
 158 .IP
 159 This routine is particularly useful when verifying packet
 160 header lengths on reception.  For example, if a packet is
 161 received and only 8 of the necessary 16 bytes required
 162 for a valid packet header are present at the head of the list
 163 of mbufs representing the packet, the remaining 8 bytes
 164 may be ``pulled up'' with a single \fIm_pullup\fP call.
 165 If the call fails the invalid packet will have been discarded.
 166 .PP
 167 By insuring that mbufs always reside on 128 byte boundaries,
 168 it is always possible to locate the mbuf associated with a data
 169 area by masking off the low bits of the virtual address.
 170 This allows modules to store data structures in mbufs and
 171 pass them around without concern for locating the original
 172 mbuf when it comes time to free the structure.
 173 Note that this works only with objects stored in the internal data
 174 buffer of the mbuf.
 175 The \fIdtom\fP macro is used to convert a pointer into an mbuf's
 176 data area to a pointer to the mbuf,
 177 .DS
 178 #define dtom(x) ((struct mbuf *)((int)x & ~(MSIZE-1)))
 179 .DE
 180 .PP
 181 Mbufs are used for dynamically allocated data structures such as
 182 sockets as well as memory allocated for packets and headers.  Statistics are
 183 maintained on mbuf usage and can be viewed by users using the
 184 \fInetstat\fP\|(1) program.