Return to 5.t CVS log

Up to [CSRG BSD Unix] / 43BSDReno / share / doc / smm / 15.net

Annotation of 43BSDReno/share/doc/smm/15.net/5.t, revision 1.1

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

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.