OpenCores
URL https://opencores.org/ocsvn/or1k/or1k/trunk

Subversion Repositories or1k

[/] [or1k/] [branches/] [oc/] [gdb-5.0/] [mmalloc/] [mmalloc.info] - Blame information for rev 1765

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 106 markom
This is ./mmalloc.info, produced by Makeinfo version 3.12f from
2
mmalloc.texi.
3
 
4
START-INFO-DIR-ENTRY
5
* Mmalloc: (mmalloc).           The GNU mapped-malloc package.
6
END-INFO-DIR-ENTRY
7
 
8
   This file documents the GNU mmalloc (mapped-malloc) package, written
9
by fnf@cygnus.com, based on GNU malloc written by mike@ai.mit.edu.
10
 
11
   Copyright (C) 1992 Free Software Foundation, Inc.
12
 
13
   Permission is granted to make and distribute verbatim copies of this
14
manual provided the copyright notice and this permission notice are
15
preserved on all copies.
16
 
17
   Permission is granted to copy and distribute modified versions of
18
this manual under the conditions for verbatim copying, provided also
19
that the entire resulting derived work is distributed under the terms
20
of a permission notice identical to this one.
21
 
22
   Permission is granted to copy and distribute translations of this
23
manual into another language, under the above conditions for modified
24
versions.
25
 
26

27
File: mmalloc.info,  Node: Top,  Next: Overview,  Prev: (dir),  Up: (dir)
28
 
29
mmalloc
30
*******
31
 
32
   This file documents the GNU memory-mapped malloc package mmalloc.
33
 
34
* Menu:
35
 
36
* Overview::                    Overall Description
37
* Implementation::              Implementation
38
 
39
 --- The Detailed Node Listing ---
40
 
41
Implementation
42
 
43
* Compatibility::               Backwards Compatibility
44
* Functions::                   Function Descriptions
45
 
46

47
File: mmalloc.info,  Node: Overview,  Next: Implementation,  Prev: Top,  Up: Top
48
 
49
Overall Description
50
*******************
51
 
52
   This is a heavily modified version of GNU `malloc'.  It uses `mmap'
53
as the basic mechanism for obtaining memory from the system, rather
54
than `sbrk'.  This gives it several advantages over the more
55
traditional malloc:
56
 
57
   * Several different heaps can be used, each of them growing or
58
     shinking under control of `mmap', with the `mmalloc' functions
59
     using a specific heap on a call by call basis.
60
 
61
   * By using `mmap', it is easy to create heaps which are intended to
62
     be persistent and exist as a filesystem object after the creating
63
     process has gone away.
64
 
65
   * Because multiple heaps can be managed, data used for a specific
66
     purpose can be allocated into its own heap, making it easier to
67
     allow applications to "dump" and "restore" initialized
68
     malloc-managed memory regions.  For example, the "unexec" hack
69
     popularized by GNU Emacs could potentially go away.
70
 
71

72
File: mmalloc.info,  Node: Implementation,  Prev: Overview,  Up: Top
73
 
74
Implementation
75
**************
76
 
77
   The `mmalloc' functions contain no internal static state.  All
78
`mmalloc' internal data is allocated in the mapped in region, along
79
with the user data that it manages.  This allows it to manage multiple
80
such regions and to "pick up where it left off" when such regions are
81
later dynamically mapped back in.
82
 
83
   In some sense, malloc has been "purified" to contain no internal
84
state information and generalized to use multiple memory regions rather
85
than a single region managed by `sbrk'.  However the new routines now
86
need an extra parameter which informs `mmalloc' which memory region it
87
is dealing with (along with other information).  This parameter is
88
called the "malloc descriptor".
89
 
90
   The functions initially provided by `mmalloc' are:
91
 
92
     void *mmalloc_attach (int fd, void *baseaddr);
93
     void *mmalloc_detach (void *md);
94
     int mmalloc_errno (void *md);
95
     int mmalloc_setkey (void *md, int keynum, void *key);
96
     void *mmalloc_getkey (void *md, int keynum);
97
 
98
     void *mmalloc (void *md, size_t size);
99
     void *mrealloc (void *md, void *ptr, size_t size);
100
     void *mvalloc (void *md, size_t size);
101
     void mfree (void *md, void *ptr);
102
 
103
* Menu:
104
 
105
* Compatibility::               Backwards Compatibility
106
* Functions::                   Function Descriptions
107
 
108

109
File: mmalloc.info,  Node: Compatibility,  Next: Functions,  Prev: Implementation,  Up: Implementation
110
 
111
Backwards Compatibility
112
=======================
113
 
114
   To allow a single malloc package to be used in a given application,
115
provision is made for the traditional `malloc', `realloc', and `free'
116
functions to be implemented as special cases of the `mmalloc'
117
functions.  In particular, if any of the functions that expect malloc
118
descriptors are called with a `NULL' pointer rather than a valid malloc
119
descriptor, then they default to using an `sbrk' managed region.  The
120
`mmalloc' package provides compatible `malloc', `realloc', and `free'
121
functions using this mechanism internally.  Applications can avoid this
122
extra interface layer by simply including the following defines:
123
 
124
     #define malloc(size)               mmalloc ((void *)0, (size))
125
     #define realloc(ptr,size)  mrealloc ((void *)0, (ptr), (size));
126
     #define free(ptr)          mfree ((void *)0, (ptr))
127
 
128
or replace the existing `malloc', `realloc', and `free' calls with the
129
above patterns if using `#define' causes problems.
130
 
131

132
File: mmalloc.info,  Node: Functions,  Prev: Compatibility,  Up: Implementation
133
 
134
Function Descriptions
135
=====================
136
 
137
   These are the details on the functions that make up the `mmalloc'
138
package.
139
 
140
`void *mmalloc_attach (int FD, void *BASEADDR);'
141
     Initialize access to a `mmalloc' managed region.
142
 
143
     If FD is a valid file descriptor for an open file, then data for
144
     the `mmalloc' managed region is mapped to that file.   Otherwise
145
     `/dev/zero' is used and the data will not exist in any filesystem
146
     object.
147
 
148
     If the open file corresponding to FD is from a previous use of
149
     `mmalloc' and passes some basic sanity checks to ensure that it is
150
     compatible with the current `mmalloc' package, then its data is
151
     mapped in and is immediately accessible at the same addresses in
152
     the current process as the process that created the file.
153
 
154
     If BASEADDR is not `NULL', the mapping is established starting at
155
     the specified address in the process address space.  If BASEADDR
156
     is `NULL', the `mmalloc' package chooses a suitable address at
157
     which to start the mapped region, which will be the value of the
158
     previous mapping if opening an existing file which was previously
159
     built by `mmalloc', or for new files will be a value chosen by
160
     `mmap'.
161
 
162
     Specifying BASEADDR provides more control over where the regions
163
     start and how big they can be before bumping into existing mapped
164
     regions or future mapped regions.
165
 
166
     On success, returns a malloc descriptor which is used in subsequent
167
     calls to other `mmalloc' package functions.  It is explicitly
168
     `void *' (`char *' for systems that don't fully support `void') so
169
     that users of the package don't have to worry about the actual
170
     implementation details.
171
 
172
     On failure returns `NULL'.
173
 
174
`void *mmalloc_detach (void *MD);'
175
     Terminate access to a `mmalloc' managed region identified by the
176
     descriptor MD, by closing the base file and unmapping all memory
177
     pages associated with the region.
178
 
179
     Returns `NULL' on success.
180
 
181
     Returns the malloc descriptor on failure, which can subsequently
182
     be used for further action (such as obtaining more information
183
     about the nature of the failure).
184
 
185
`void *mmalloc (void *MD, size_t SIZE);'
186
     Given an `mmalloc' descriptor MD, allocate additional memory of
187
     SIZE bytes in the associated mapped region.
188
 
189
`*mrealloc (void *MD, void *PTR, size_t SIZE);'
190
     Given an `mmalloc' descriptor MD and a pointer to memory
191
     previously allocated by `mmalloc' in PTR, reallocate the memory to
192
     be SIZE bytes long, possibly moving the existing contents of
193
     memory if necessary.
194
 
195
`void *mvalloc (void *MD, size_t SIZE);'
196
     Like `mmalloc' but the resulting memory is aligned on a page
197
     boundary.
198
 
199
`void mfree (void *MD, void *PTR);'
200
     Given an `mmalloc' descriptor MD and a pointer to memory previously
201
     allocated by `mmalloc' in PTR, free the previously allocated
202
     memory.
203
 
204
`int mmalloc_errno (void *MD);'
205
     Given a `mmalloc' descriptor, if the last `mmalloc' operation
206
     failed for some reason due to a system call failure, then returns
207
     the associated `errno'.  Returns 0 otherwise.  (This function is
208
     not yet implemented).
209
 
210
 
211

212
Tag Table:
213
Node: Top939
214
Node: Overview1375
215
Node: Implementation2403
216
Node: Compatibility3796
217
Node: Functions4870
218

219
End Tag Table

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.