nephele
/
haiku-website
0
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
haiku-website/static/legacy-docs/bebook/DeviceDrivers_area_malloc.html

49 lines
13 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>The Be Book - Special Topics - Device Drivers</title><link rel="stylesheet" href="be_book.css" type="text/css" media="all" /><link rel="shortcut icon" type="image/vnd.microsoft.icon" href="./images/favicon.ico" /><!--[if IE]>
<link rel="stylesheet" type="text/css" href="be_book_ie.css" />
<![endif]--><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="Access, BeOS, BeBook, API" /><link rel="start" href="index.html" title="The Be Book" /><link rel="up" href="DeviceDrivers.html" title="Device Drivers" /><link rel="prev" href="DeviceDrivers_UsingModules.html" title="Using Modules" /><link rel="next" href="DeviceDrivers_DriverSettingsAPI.html" title="Driver Settings API" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="DeviceDrivers_UsingModules.html" title="Using Modules"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a accesskey="u" href="DeviceDrivers.html" title="Device Drivers"><img src="./images/navigation/up.png" alt="Up" /></a> <a accesskey="n" href="DeviceDrivers_DriverSettingsAPI.html" title="Driver Settings API"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="headerTR"><div id="navigpeople"><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div><div class="navigboxed" id="navigindex"><a accesskey="i" href="ClassIndex.html" title="Index">I</a></div><div class="navigboxed" id="naviglang" title="English">en</div></div><div id="headerTC">The Be Book - Special Topics - Device Drivers</div></div><div id="headerB">Prev: <a href="DeviceDrivers_UsingModules.html">Using Modules</a>  Up: <a href="DeviceDrivers.html">Device Drivers</a>  Next: <a href="DeviceDrivers_DriverSettingsAPI.html">Driver Settings API</a></div><hr /></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h2 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="DeviceDrivers_area_malloc"></a>The area_malloc Module</h2></div></div></div><p>Declared in: <code class="filename">drivers/area_malloc.h</code></p><p>The area_malloc module provides a means for your driver to allocate
memory in areas instead of on the heap. It provides
<a class="link" href="DeviceDrivers_area_malloc.html#area_malloc_malloc" title="malloc(), calloc(), realloc()"><code class="function">malloc()</code></a>,
<a class="link" href="DeviceDrivers_area_malloc.html#area_malloc_calloc"><code class="function">calloc()</code></a>,
<a class="link" href="DeviceDrivers_area_malloc.html#area_malloc_realloc"><code class="function">realloc()</code></a>,
and <a class="link" href="DeviceDrivers_area_malloc.html#area_malloc_free" title="free()"><code class="function">free()</code></a>
functions that work just like their POSIX
counterparts, except they require a pool argument as their first input.</p><div class="admonition warning"><div class="title">Warning</div><div class="graphic"><img class="icon" alt="Warning" width="32" src="./images/admonitions/Stop_32.png" /><div class="text"><p>These functions aren't safe to call from interrupt handlers; they may
block on semaphores.</p></div></div></div><p>The area_malloc functions are thread-safe in relation to one another, but
not in relation to
<a class="link" href="DeviceDrivers_area_malloc.html#delete_pool"><code class="function">delete_pool()</code></a>.
Be sure you don't call
<a class="link" href="DeviceDrivers_area_malloc.html#delete_pool"><code class="function">delete_pool()</code></a>
on the pool you're using until you know none of the other functions might be
called.
<a class="link" href="DeviceDrivers_area_malloc.html#create_pool" title="create_pool(), delete_pool()"><code class="function">create_pool()</code></a>
and <a class="link" href="DeviceDrivers_area_malloc.html#delete_pool"><code class="function">delete_pool()</code></a>
are safe in relation to each other.</p><p>When the last user of the module puts it away, any remaining pools are
automatically deleted.</p><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="area_malloc_ModuleFunctions"></a>Module Functions</h3></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="create_pool"></a><a id="delete_pool"></a>
create_pool(), delete_pool()</h4></div></div></div><a id="id916714" class="indexterm"></a><a id="id916721" class="indexterm"></a><code class="methodsynopsis c"><span class="type">const void* </span><span class="methodname">create_pool</span>(<span class="methodparam"><span class="type">uint32 </span><span class="parameter">addressSpec</span></span>,<br />                        <span class="methodparam"><span class="type">size_t </span><span class="parameter">size</span></span>,<br />                        <span class="methodparam"><span class="type">uint32 </span><span class="parameter">lockSpec</span></span>,<br />                        <span class="methodparam"><span class="type">uint32 </span><span class="parameter">protection</span></span>);</code><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">delete_pool</span>(<span class="methodparam"><span class="type">const void* </span><span class="parameter">poolID</span></span>);</code><p><code class="function">create_pool()</code> creates a new pool of memory from which to allocate. The
parameters are the same as those used by
<a class="link" href="TheKernelKit_Areas.html#create_area" title="create_area()"><code class="function">create_area()</code></a>,
so you have complete control over the area's characteristics (except for its name).
Returns an opaque pool idenfityer, or <code class="constant">NULL</code> if the creation failed. The
ability to share resources allocated from the pool is determined by the
permissions and protections used to create the area.</p><p><code class="function">delete_pool()</code> deletes the pool specified by the
opaque <code class="parameter">poolID</code> given. Any pointers returned by the
other functions in the module are immediately invalid. Returns
<code class="constant">B_OK</code> if the pool was deleted, otherwise
<code class="constant">B_ERROR</code>.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="area_malloc_malloc"></a><a id="area_malloc_calloc"></a>
<a id="area_malloc_realloc"></a>
malloc(), calloc(), realloc()</h4></div></div></div><a id="id916858" class="indexterm"></a><a id="id916865" class="indexterm"></a><a id="id916872" class="indexterm"></a><code class="methodsynopsis c"><span class="type">void* </span><span class="methodname">malloc</span>(<span class="methodparam"><span class="type">const void* </span><span class="parameter">poolID</span></span>,<br />             <span class="methodparam"><span class="type">size_t </span><span class="parameter">size</span></span>);</code><code class="methodsynopsis c"><span class="type">void* </span><span class="methodname">calloc</span>(<span class="methodparam"><span class="type">const void* </span><span class="parameter">poolID</span></span>,<br />             <span class="methodparam"><span class="type">size_t </span><span class="parameter">numMembers</span></span>,<br />             <span class="methodparam"><span class="type">size_t </span><span class="parameter">size</span></span>);</code><code class="methodsynopsis c"><span class="type">void* </span><span class="methodname">realloc</span>(<span class="methodparam"><span class="type">const void* </span><span class="parameter">poolID</span></span>,<br />              <span class="methodparam"><span class="type">void* </span><span class="parameter">ptr</span></span>,<br />              <span class="methodparam"><span class="type">size_t </span><span class="parameter">size</span></span>);</code><p><code class="function">malloc()</code> allocates a block of
<code class="parameter">size</code> bytes and returns a pointer to it.</p><p><code class="function">calloc()</code> allocates a block that can contain
<code class="parameter">numMembers</code> items of the specified
<code class="parameter">size</code> and returns a poiner to it.</p><p><code class="function">realloc()</code> resizes the memory block pointed to by
<code class="parameter">ptr</code> to the indicated <code class="parameter">size</code>.
Resizing a block can require that the memory be relocated, so this function
returns the new pointer.</p><p>Each of these operations functions in the pool specified by
<code class="parameter">poolID</code>.</p><p>If there's not enough memory to allocate the requested block, these
functions return <code class="constant">NULL</code>.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="area_malloc_free"></a>free()</h4></div></div></div><a id="id917055" class="indexterm"></a><code class="methodsynopsis c"><span class="type">void* </span><span class="methodname">free</span>(<span class="methodparam"><span class="type">const void* </span><span class="parameter">poolID</span></span>,<br />           <span class="methodparam"><span class="type">void* </span><span class="parameter">ptr</span></span>);</code><p>Releases the memory block pointed to by <code class="parameter">ptr</code> from the pool specified by
<code class="parameter">poolID</code>.</p></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="area_malloc_Constants"></a>Constants</h3></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="B_AREA_MALLOC_MODULE_NAME"></a>B_AREA_MALLOC_MODULE_NAME</h4></div></div></div><a id="id917125" class="indexterm"></a><pre class="programlisting cpp">#define <code class="constant">B_AREA_MALLOC_MODULE_NAME</code> "generic/area_malloc/v1"</pre><p>The <code class="constant">B_AREA_MALLOC_MODULE_NAME</code> constant
identifies the area_malloc module; use this constant to open the module.</p></div></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="DeviceDrivers_UsingModules.html">Using Modules</a>  Up: <a href="DeviceDrivers.html">Device Drivers</a>  Next: <a href="DeviceDrivers_DriverSettingsAPI.html">Driver Settings API</a> </div><div id="footerB"><div id="footerBL"><a href="DeviceDrivers_UsingModules.html" title="Using Modules"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a href="DeviceDrivers.html" title="Device Drivers"><img src="./images/navigation/up.png" alt="Up" /></a> <a href="DeviceDrivers_DriverSettingsAPI.html" title="Driver Settings API"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="footerBR"><div><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div></div><div id="footerBC"><a href="http://www.access-company.com/home.html" title="ACCESS Co."><img alt="Access Company" src="./images/access_logo.png" /></a></div></div></div><div id="licenseFooter"><div id="licenseFooterBL"><a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/" title="Creative Commons License"><img alt="Creative Commons License" style="border-width:0" src="https://licensebuttons.net/l/by-nc-nd/3.0/88x31.png" /></a></div><div id="licenseFooterBR"><a href="./LegalNotice.html">Legal Notice</a></div><div id="licenseFooterBC"><span id="licenseText">This work is licensed under a
<a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/">Creative
Commons Attribution-Non commercial-No Derivative Works 3.0 License</a>.</span></div></div></body></html>
Reference in New Issue View Git Blame Copy Permalink