mirror of
https://github.com/OpenVPN/openvpn.git
synced 2024-09-20 03:52:28 +02:00
Added memory management documentation
Signed-off-by: Adriaan de Jong <dejong@fox-it.com> Acked-by: James Yonan <james@openvpn.net> Signed-off-by: David Sommerseth <dazo@users.sourceforge.net>
This commit is contained in:
parent
0332b951ce
commit
5959e9def6
57
buffer.h
57
buffer.h
@ -42,14 +42,30 @@
|
||||
#define BUF_INIT_TRACKING
|
||||
#endif
|
||||
|
||||
/* basic buffer class for OpenVPN */
|
||||
|
||||
/**************************************************************************/
|
||||
/**
|
||||
* Wrapper structure for dynamically allocated memory.
|
||||
*
|
||||
* The actual content stored in a \c buffer structure starts at the memory
|
||||
* location \c buffer.data \c + \c buffer.offset, and has a length of \c
|
||||
* buffer.len bytes. This, together with the space available before and
|
||||
* after the content, is represented in the pseudocode below:
|
||||
@code
|
||||
uint8_t *content_start = buffer.data + buffer.offset;
|
||||
uint8_t *content_end = buffer.data + buffer.offset + buffer.len;
|
||||
int prepend_capacity = buffer.offset;
|
||||
int append_capacity = buffer.capacity - (buffer.offset + buffer.len);
|
||||
@endcode
|
||||
*/
|
||||
struct buffer
|
||||
{
|
||||
int capacity; /* size of buffer allocated by malloc */
|
||||
int offset; /* data starts at data + offset, offset > 0 to allow for efficient prepending */
|
||||
int len; /* length of data that starts at data + offset */
|
||||
uint8_t *data;
|
||||
int capacity; /**< Size in bytes of memory allocated by
|
||||
* \c malloc(). */
|
||||
int offset; /**< Offset in bytes of the actual content
|
||||
* within the allocated memory. */
|
||||
int len; /**< Length in bytes of the actual content
|
||||
* within the allocated memory. */
|
||||
uint8_t *data; /**< Pointer to the allocated memory. */
|
||||
|
||||
#ifdef BUF_INIT_TRACKING
|
||||
const char *debug_file;
|
||||
@ -57,18 +73,41 @@ struct buffer
|
||||
#endif
|
||||
};
|
||||
|
||||
/* for garbage collection */
|
||||
|
||||
/**************************************************************************/
|
||||
/**
|
||||
* Garbage collection entry for one dynamically allocated block of memory.
|
||||
*
|
||||
* This structure represents one link in the linked list contained in a \c
|
||||
* gc_arena structure. Each time the \c gc_malloc() function is called,
|
||||
* it allocates \c sizeof(gc_entry) + the requested number of bytes. The
|
||||
* \c gc_entry is then stored as a header in front of the memory address
|
||||
* returned to the caller.
|
||||
*/
|
||||
struct gc_entry
|
||||
{
|
||||
struct gc_entry *next;
|
||||
struct gc_entry *next; /**< Pointer to the next item in the
|
||||
* linked list. */
|
||||
};
|
||||
|
||||
|
||||
/**
|
||||
* Garbage collection arena used to keep track of dynamically allocated
|
||||
* memory.
|
||||
*
|
||||
* This structure contains a linked list of \c gc_entry structures. When
|
||||
* a block of memory is allocated using the \c gc_malloc() function, the
|
||||
* allocation is registered in the function's \c gc_arena argument. All
|
||||
* the dynamically allocated memory registered in a \c gc_arena can be
|
||||
* freed using the \c gc_free() function.
|
||||
*/
|
||||
struct gc_arena
|
||||
{
|
||||
struct gc_entry *list;
|
||||
struct gc_entry *list; /**< First element of the linked list of
|
||||
* \c gc_entry structures. */
|
||||
};
|
||||
|
||||
|
||||
#define BPTR(buf) (buf_bptr(buf))
|
||||
#define BEND(buf) (buf_bend(buf))
|
||||
#define BLAST(buf) (buf_blast(buf))
|
||||
|
99
doc_memory_management.h
Normal file
99
doc_memory_management.h
Normal file
@ -0,0 +1,99 @@
|
||||
/*
|
||||
* OpenVPN -- An application to securely tunnel IP networks
|
||||
* over a single TCP/UDP port, with support for SSL/TLS-based
|
||||
* session authentication and key exchange,
|
||||
* packet encryption, packet authentication, and
|
||||
* packet compression.
|
||||
*
|
||||
* Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com>
|
||||
*
|
||||
*
|
||||
* This program is free software; you can redistribute it and/or modify
|
||||
* it under the terms of the GNU General Public License version 2
|
||||
* as published by the Free Software Foundation.
|
||||
*
|
||||
* This program is distributed in the hope that it will be useful,
|
||||
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
* GNU General Public License for more details.
|
||||
*
|
||||
* You should have received a copy of the GNU General Public License
|
||||
* along with this program (see the file COPYING included with this
|
||||
* distribution); if not, write to the Free Software Foundation, Inc.,
|
||||
* 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
||||
*/
|
||||
|
||||
/**
|
||||
* @file
|
||||
* Memory management strategies documentation file.
|
||||
*/
|
||||
|
||||
/**
|
||||
* @page memory_management OpenVPN's memory management strategies
|
||||
*
|
||||
* This section describes several implementation details relating to
|
||||
* OpenVPN's memory management strategies.
|
||||
*
|
||||
* During operation, the OpenVPN process performs all kinds of operations
|
||||
* on blocks of data. Receiving packets, encrypting content, prepending
|
||||
* headers, etc. To make the programmer's job easier and to decrease the
|
||||
* likelihood of memory-related bugs, OpenVPN uses its own memory %buffer
|
||||
* library and garbage collection facilities. These are described in
|
||||
* brief here.
|
||||
*
|
||||
* @section memory_management_buffer The buffer structure
|
||||
*
|
||||
* The \c buffer structure is a wrapper around a block of dynamically
|
||||
* allocated memory which keeps track of the block's capacity \c
|
||||
* buffer.capacity and location in memory \c buffer.data. This structure
|
||||
* supports efficient prepending and appending within the allocated memory
|
||||
* through the use of offset \c buffer.offset and length \c buffer.len
|
||||
* fields. See the \c buffer documentation for more details on the
|
||||
* structure itself.
|
||||
*
|
||||
* OpenVPN's %buffer library, implemented in the \c buffer.h and \c
|
||||
* buffer.c files, contains many utility functions for working with \c
|
||||
* buffer structures. These functions facilitate common operations, such
|
||||
* as allocating, freeing, reading and writing to \c buffer structures,
|
||||
* and even offer several more advanced operations, such as string
|
||||
* matching and creating sub-buffers.
|
||||
*
|
||||
* Not only do these utility functions make working with \c buffer
|
||||
* structures easy, they also perform extensive error checking. Each
|
||||
* function, where necessary, checks whether enough space is available
|
||||
* before performing its actions. This minimizes the chance of bugs
|
||||
* leading to %buffer overflows and other vulnerabilities.
|
||||
*
|
||||
* @section memory_management_frame The frame structure
|
||||
*
|
||||
* The \c frame structure keeps track of the maximum allowed packet
|
||||
* geometries of a network connection.
|
||||
*
|
||||
* It is used, for example, to determine the size of \c buffer structures
|
||||
* in which to store data channel packets. This is done by having each
|
||||
* data channel processing module register the maximum amount of extra
|
||||
* space it will need for header prepending and content expansion in the
|
||||
* \c frame structure. Once these parameters are known, \c buffer
|
||||
* structures can be allocated, based on the \c frame parameters, so that
|
||||
* they are large enough to allow efficient prepending of headers and
|
||||
* processing of content.
|
||||
*
|
||||
* @section memory_management_garbage Garbage collection
|
||||
*
|
||||
* OpenVPN has many sizable functions which perform various actions
|
||||
* depending on their %context. This makes it difficult to know in advance
|
||||
* exactly how much memory must be allocated. The garbage collection
|
||||
* facilities are used to keep track of dynamic allocations, thereby
|
||||
* allowing easy collective freeing of the allocated memory.
|
||||
*
|
||||
* The garbage collection system is implemented by the \c gc_arena and \c
|
||||
* gc_entry structures. The arena represents a garbage collecting unit,
|
||||
* and contains a linked list of entries. Each entry represents one block
|
||||
* of dynamically allocated memory.
|
||||
*
|
||||
* The garbage collection system also contains various utility functions
|
||||
* for working with the garbage collection structures. These include
|
||||
* functions for initializing new arenas, allocating memory of a given
|
||||
* size and registering the allocation in an arena, and freeing all the
|
||||
* allocated memory associated with an arena.
|
||||
*/
|
Loading…
Reference in New Issue
Block a user