forked from Imagelibrary/rtems
Final update from Santanu Mitra <smitra@cs.uah.edu>, T.N.S. Prasad
<ptelukun@cs.uah.edu>, and Wei He <whe@cs.uah.edu> on the Fixed Block and Memory Pool Managers.
This commit is contained in:
Joel Sherrill
@@ -1,248 +1,379 @@
|
||||
@c
|
||||
@c This is the chapter from the RTEMS ITRON User's Guide that
|
||||
@c documents the services provided by the fixed block
|
||||
@c manager.
|
||||
@c
|
||||
@c $Id$
|
||||
@c
|
||||
|
||||
@chapter Fixed Block Manager
|
||||
|
||||
@section Introduction
|
||||
|
||||
The
|
||||
fixed block manager is ...
|
||||
|
||||
The services provided by the fixed block manager are:
|
||||
|
||||
@itemize @bullet
|
||||
@item @code{cre_mpf} - Create Fixed-Size Memorypool
|
||||
@item @code{del_mpf} - Delete Fixed-Size Memorypool
|
||||
@item @code{get_blf} - Get Fixed-Size Memory Block
|
||||
@item @code{pget_blf} - Poll and Get Fixed-Size Memory Block
|
||||
@item @code{tget_blf} - Get Fixed-Size Memory Block with Timeout
|
||||
@item @code{rel_blf} - Release Fixed-Size Memory Block
|
||||
@item @code{ref_mpf} - Reference Fixed-Size Memorypool Status
|
||||
@end itemize
|
||||
|
||||
@section Background
|
||||
|
||||
@section Operations
|
||||
|
||||
@section System Calls
|
||||
|
||||
This section details the fixed block manager's services.
|
||||
A subsection is dedicated to each of this manager's services
|
||||
and describes the calling sequence, related constants, usage,
|
||||
and status codes.
|
||||
|
||||
|
||||
@c
|
||||
@c cre_mpf
|
||||
@c
|
||||
|
||||
@page
|
||||
@subsection cre_mpf - Create Fixed-Size Memorypool
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@example
|
||||
ER cre_mpf(
|
||||
ID mpfid,
|
||||
T_CMPF *pk_cmpf
|
||||
);
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@ifset is-Ada
|
||||
@end ifset
|
||||
|
||||
@subheading STATUS CODES:
|
||||
|
||||
@code{EXXX} -
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
|
||||
@c
|
||||
@c del_mpf
|
||||
@c
|
||||
|
||||
@page
|
||||
@subsection del_mpf - Delete Fixed-Size Memorypool
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@example
|
||||
ER del_mpf(
|
||||
ID mpfid
|
||||
);
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@ifset is-Ada
|
||||
@end ifset
|
||||
|
||||
@subheading STATUS CODES:
|
||||
|
||||
@code{EXXX} -
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
|
||||
@c
|
||||
@c get_blf
|
||||
@c
|
||||
|
||||
@page
|
||||
@subsection get_blf - Get Fixed-Size Memory Block
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@example
|
||||
ER get_blf(
|
||||
VP *p_blf,
|
||||
ID mpfid
|
||||
);
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@ifset is-Ada
|
||||
@end ifset
|
||||
|
||||
@subheading STATUS CODES:
|
||||
|
||||
@code{EXXX} -
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
|
||||
@c
|
||||
@c pget_blf
|
||||
@c
|
||||
|
||||
@page
|
||||
@subsection pget_blf - Poll and Get Fixed-Size Memory Block
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@example
|
||||
ER ercd =pget_blf(
|
||||
VP *p_blf,
|
||||
ID mpfid
|
||||
);
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@ifset is-Ada
|
||||
@end ifset
|
||||
|
||||
@subheading STATUS CODES:
|
||||
|
||||
@code{EXXX} -
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
|
||||
@c
|
||||
@c tget_blf
|
||||
@c
|
||||
|
||||
@page
|
||||
@subsection tget_blf - Get Fixed-Size Memory Block with Timeout
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@example
|
||||
ER ercd =tget_blf(
|
||||
VP *p_blf,
|
||||
ID mpfid,
|
||||
TMO tmout
|
||||
);
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@ifset is-Ada
|
||||
@end ifset
|
||||
|
||||
@subheading STATUS CODES:
|
||||
|
||||
@code{EXXX} -
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
|
||||
@c
|
||||
@c rel_blf
|
||||
@c
|
||||
|
||||
@page
|
||||
@subsection rel_blf - Release Fixed-Size Memory Block
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@example
|
||||
ER rel_blf(
|
||||
ID mpfid,
|
||||
VP blf
|
||||
);
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@ifset is-Ada
|
||||
@end ifset
|
||||
|
||||
@subheading STATUS CODES:
|
||||
|
||||
@code{EXXX} -
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
|
||||
@c
|
||||
@c ref_mpf
|
||||
@c
|
||||
|
||||
@page
|
||||
@subsection ref_mpf - Reference Fixed-Size Memorypool Status
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@example
|
||||
ER ref_mpf(
|
||||
T_RMPF *pk_rmpf,
|
||||
ID mpfid
|
||||
);
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@ifset is-Ada
|
||||
@end ifset
|
||||
|
||||
@subheading STATUS CODES:
|
||||
|
||||
@code{EXXX} -
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
@c
|
||||
|
||||
@c This is the chapter from the RTEMS ITRON User's Guide that
|
||||
|
||||
@c documents the services provided by the fixed block
|
||||
|
||||
@c manager.
|
||||
|
||||
@c
|
||||
|
||||
@c $Id$
|
||||
|
||||
@c
|
||||
|
||||
|
||||
|
||||
@chapter Fixed Block Manager
|
||||
|
||||
|
||||
|
||||
@section Introduction
|
||||
|
||||
|
||||
|
||||
The fixed block manager provides functions for creating, deleting, getting, polling, getting with timeout, releasing, and referencing the fixed-sized memorypool. This manager is based on ITRON 3.0 standard.
|
||||
|
||||
|
||||
|
||||
The services provided by the fixed block manager are:
|
||||
|
||||
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item @code{cre_mpf} - Create Fixed-Size Memorypool
|
||||
|
||||
@item @code{del_mpf} - Delete Fixed-Size Memorypool
|
||||
|
||||
@item @code{get_blf} - Get Fixed-Size Memory Block
|
||||
|
||||
@item @code{pget_blf} - Poll and Get Fixed-Size Memory Block
|
||||
|
||||
@item @code{tget_blf} - Get Fixed-Size Memory Block with Timeout
|
||||
|
||||
@item @code{rel_blf} - Release Fixed-Size Memory Block
|
||||
|
||||
@item @code{ref_mpf} - Reference Fixed-Size Memorypool Status
|
||||
|
||||
@end itemize
|
||||
|
||||
|
||||
|
||||
@section Background
|
||||
|
||||
|
||||
|
||||
@section Operations
|
||||
|
||||
|
||||
|
||||
@section System Calls
|
||||
|
||||
|
||||
|
||||
This section details the fixed block manager's services.
|
||||
|
||||
A subsection is dedicated to each of this manager's services
|
||||
|
||||
and describes the calling sequence, related constants, usage,
|
||||
|
||||
and status codes.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@c
|
||||
|
||||
@c cre_mpf
|
||||
|
||||
@c
|
||||
|
||||
|
||||
|
||||
@page
|
||||
|
||||
@subsection cre_mpf - Create Fixed-Size Memorypool
|
||||
|
||||
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
|
||||
|
||||
@ifset is-C
|
||||
|
||||
@example
|
||||
|
||||
ER cre_mpf(
|
||||
|
||||
ID mpfid,
|
||||
|
||||
T_CMPF *pk_cmpf
|
||||
|
||||
);
|
||||
|
||||
@end example
|
||||
|
||||
@end ifset
|
||||
|
||||
|
||||
|
||||
@ifset is-Ada
|
||||
|
||||
@end ifset
|
||||
|
||||
|
||||
|
||||
@subheading STATUS CODES:
|
||||
|
||||
|
||||
|
||||
@code{E_OK} - Normal Completion
|
||||
|
||||
|
||||
|
||||
@code{E_NOMEM} - Insufficient memory (Memory for control block and/or for
|
||||
|
||||
memorypool cannot be allocated)
|
||||
|
||||
|
||||
|
||||
@code{E_ID} - Invalid ID number (mpfid was invalid or could not be used)
|
||||
|
||||
|
||||
|
||||
@code{E_RSATR} - Reserved attribute (mpfatr was invalid or could not be used)
|
||||
|
||||
|
||||
|
||||
@code{E_OBJ} - Invalid object state (a memorypool of the same ID already exists)
|
||||
|
||||
|
||||
|
||||
@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from
|
||||
|
||||
a user task. This is implementation dependent.)
|
||||
|
||||
|
||||
|
||||
@code{E_PAR} - Parameter error (pk_cmpf is invalid or mpfsz and/or blfsz is
|
||||
|
||||
negative or invalid)
|
||||
|
||||
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
|
||||
|
||||
This system call creates a fixed-size memorypool having the ID number specified by mpfid. Specifically, a memory area of a size based on values of mpfcnt and blfsz is reserved for use as a memorypool. A control block for the memorypool being created is also allocated. The get_blf system call specifying the memorypool created by this call can be issued to allocate memory blocks of the size given by blfsz (in bytes).
|
||||
|
||||
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
|
||||
|
||||
The memory area required for creating memorypools and for allocating control blocks for each object is allocated while system initialization. Associated parameters are therefore specified at system configuration.
|
||||
|
||||
|
||||
|
||||
@c
|
||||
|
||||
@c del_mpf
|
||||
|
||||
@c
|
||||
|
||||
|
||||
|
||||
@page
|
||||
|
||||
@subsection del_mpf - Delete Fixed-Size Memorypool
|
||||
|
||||
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
|
||||
|
||||
@ifset is-C
|
||||
|
||||
@example
|
||||
|
||||
ER del_mpf(
|
||||
|
||||
ID mpfid
|
||||
|
||||
);
|
||||
|
||||
@end example
|
||||
|
||||
@end ifset
|
||||
|
||||
|
||||
|
||||
@ifset is-Ada
|
||||
|
||||
@end ifset
|
||||
|
||||
|
||||
|
||||
@subheading STATUS CODES:
|
||||
|
||||
|
||||
|
||||
@code{E_OK} - Normal Completion
|
||||
|
||||
|
||||
|
||||
@code{E_ID} - Invalid ID number (mpfid was invalid or could not be used)
|
||||
|
||||
|
||||
|
||||
@code{E_NOEXS} - Object does not exist (the memorypool specified by mpfid does not exist)
|
||||
|
||||
|
||||
|
||||
@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from a user task. This is implementation dependent.)
|
||||
|
||||
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
|
||||
|
||||
This system call deletes the fixed-size memorypool specified by mpfid. No check or error report is performed even if there are tasks using memory from the memorypool to be deleted. This system call completes normally even if some of the memory blocks are not returned. Issuing this system call causes memory used for the control block of the associated memorypool and the memory area making up the memorypool itself to be released. After this system call is invoked, another memorypool having the same ID number can be created. This system call will complete normally even if there are tasks waiting to get memory blocks from the memorypool. In that case, an E_DLT error will be returned to each waiting task.
|
||||
|
||||
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
|
||||
|
||||
When a memorypool being waited for by more than one tasks is deleted, the order of tasks on the ready queue after the WAIT state is cleared is implementation dependent in the case of tasks having the same priority.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@c
|
||||
|
||||
@c get_blf
|
||||
|
||||
@c
|
||||
|
||||
|
||||
|
||||
@page
|
||||
|
||||
@subsection get_blf - Get Fixed-Size Memory Block
|
||||
|
||||
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
|
||||
|
||||
@ifset is-C
|
||||
|
||||
@example
|
||||
|
||||
ER get_blf(
|
||||
|
||||
VP *p_blf,
|
||||
|
||||
ID mpfid
|
||||
|
||||
);
|
||||
|
||||
@end example
|
||||
|
||||
@end ifset
|
||||
|
||||
|
||||
|
||||
@ifset is-Ada
|
||||
|
||||
@end ifset
|
||||
|
||||
|
||||
|
||||
@subheading STATUS CODES:
|
||||
|
||||
|
||||
|
||||
@code{E_OK} - Normal Completion
|
||||
|
||||
|
||||
|
||||
@code{E_ID} - Invalid ID number (mpfid was invalid or could not be used)
|
||||
|
||||
|
||||
|
||||
@code{E_NOEXS} - Object does not exist (the memorypool specified by mpfid does not exist)
|
||||
|
||||
|
||||
|
||||
@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from
|
||||
|
||||
a user task. This is implementation dependent.)
|
||||
|
||||
|
||||
|
||||
@code{E_PAR} - Parameter error (tmout is -2 or less)
|
||||
|
||||
|
||||
|
||||
@code{E_DLT} - The object being waited for was deleted (the specified memorypool
|
||||
|
||||
was deleted while waiting)
|
||||
|
||||
|
||||
|
||||
@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
|
||||
|
||||
waiting)
|
||||
|
||||
|
||||
|
||||
@code{E_TMOUT} - Polling failure or timeout exceeded
|
||||
|
||||
|
||||
|
||||
@code{E_CTX} - Context error (issued from task-independent portions or a
|
||||
|
||||
task in dispatch disabled state; implementation dependent for pget_blf and tget_blf(tmout=TMO_POL))
|
||||
|
||||
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
|
||||
|
||||
A memory block is allocated from the fixed-size memorypool specified by mpfid. The start address of the memory block allocated is returned to blf. The size of the memory block allocated is specified by the blfsz parameter when the fixed-size memorypool was created. The allocated memory block is not cleared to zero. The contents of the allocated memory block are undefined. If the memory block cannot be obtained from the specified memorypool when get_blf is issued, the task issuing get_blf will be placed on the memory allocation queue of the specified memorypool, and wait until it can get the memory it requires. If the object being waited for is deleted (the specified memorypool is deleted while waiting), an E_DLT error will be returned.
|
||||
|
||||
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@c
|
||||
|
||||
@c pget_blf
|
||||
|
||||
@c
|
||||
|
||||
|
||||
|
||||
@page
|
||||
|
||||
@subsection pget_blf - Poll and Get Fixed-Size Memory Block
|
||||
|
||||
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
|
||||
|
||||
@ifset is-C
|
||||
|
||||
@example
|
||||
|
||||
ER ercd =pget_blf(
|
||||
|
||||
VP *p_blf,
|
||||
|
||||
@@ -1,251 +1,393 @@
|
||||
@c
|
||||
@c This is the chapter from the RTEMS ITRON User's Guide that
|
||||
@c documents the services provided by the memory pool
|
||||
@c manager.
|
||||
@c
|
||||
@c $Id$
|
||||
@c
|
||||
|
||||
@chapter Memory Pool Manager
|
||||
|
||||
@section Introduction
|
||||
|
||||
The
|
||||
memory pool manager is ...
|
||||
|
||||
The services provided by the memory pool manager are:
|
||||
|
||||
@itemize @bullet
|
||||
@item @code{cre_mpl} - Create Variable-Size Memorypool
|
||||
@item @code{del_mpl} - Delete Variable-Size Memorypool
|
||||
@item @code{get_blk} - Get Variable-Size Memory Block
|
||||
@item @code{pget_blk} - Poll and Get Variable-Size Memory Block
|
||||
@item @code{tget_blk} - Get Variable-Size Memory Block with Timeout
|
||||
@item @code{rel_blk} - Release Variable-Size Memory Block
|
||||
@item @code{ref_mpl} - Reference Variable-Size Memorypool Status
|
||||
@end itemize
|
||||
|
||||
@section Background
|
||||
|
||||
@section Operations
|
||||
|
||||
@section System Calls
|
||||
|
||||
This section details the memory pool manager's services.
|
||||
A subsection is dedicated to each of this manager's services
|
||||
and describes the calling sequence, related constants, usage,
|
||||
and status codes.
|
||||
|
||||
|
||||
@c
|
||||
@c cre_mpl
|
||||
@c
|
||||
|
||||
@page
|
||||
@subsection cre_mpl - Create Variable-Size Memorypool
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@example
|
||||
ER cre_mpl(
|
||||
ID mplid,
|
||||
T_CMPL *pk_cmpl
|
||||
);
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@ifset is-Ada
|
||||
@end ifset
|
||||
|
||||
@subheading STATUS CODES:
|
||||
|
||||
@code{EXXX} -
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
|
||||
@c
|
||||
@c del_mpl
|
||||
@c
|
||||
|
||||
@page
|
||||
@subsection del_mpl - Delete Variable-Size Memorypool
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@example
|
||||
ER del_mpl(
|
||||
ID mplid
|
||||
);
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@ifset is-Ada
|
||||
@end ifset
|
||||
|
||||
@subheading STATUS CODES:
|
||||
|
||||
@code{EXXX} -
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
|
||||
@c
|
||||
@c get_blk
|
||||
@c
|
||||
|
||||
@page
|
||||
@subsection get_blk - Get Variable-Size Memory Block
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@example
|
||||
ER get_blk(
|
||||
VP *p_blk,
|
||||
ID mplid,
|
||||
INT blksz
|
||||
);
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@ifset is-Ada
|
||||
@end ifset
|
||||
|
||||
@subheading STATUS CODES:
|
||||
|
||||
@code{EXXX} -
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
|
||||
@c
|
||||
@c pget_blk
|
||||
@c
|
||||
|
||||
@page
|
||||
@subsection pget_blk - Poll and Get Variable-Size Memory Block
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@example
|
||||
ER ercd =pget_blk(
|
||||
VP *p_blk,
|
||||
ID mplid,
|
||||
INT blksz
|
||||
);
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@ifset is-Ada
|
||||
@end ifset
|
||||
|
||||
@subheading STATUS CODES:
|
||||
|
||||
@code{EXXX} -
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
|
||||
@c
|
||||
@c tget_blk
|
||||
@c
|
||||
|
||||
@page
|
||||
@subsection tget_blk - Get Variable-Size Memory Block with Timeout
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@example
|
||||
ER ercd =tget_blk(
|
||||
VP *p_blk,
|
||||
ID mplid,
|
||||
INT blksz,
|
||||
TMO tmout
|
||||
);
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@ifset is-Ada
|
||||
@end ifset
|
||||
|
||||
@subheading STATUS CODES:
|
||||
|
||||
@code{EXXX} -
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
|
||||
@c
|
||||
@c rel_blk
|
||||
@c
|
||||
|
||||
@page
|
||||
@subsection rel_blk - Release Variable-Size Memory Block
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@example
|
||||
ER rel_blk(
|
||||
ID mplid,
|
||||
VP blk
|
||||
);
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@ifset is-Ada
|
||||
@end ifset
|
||||
|
||||
@subheading STATUS CODES:
|
||||
|
||||
@code{EXXX} -
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
|
||||
@c
|
||||
@c ref_mpl
|
||||
@c
|
||||
|
||||
@page
|
||||
@subsection ref_mpl - Reference Variable-Size Memorypool Status
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@example
|
||||
ER ref_mpl(
|
||||
T_RMPL *pk_rmpl,
|
||||
ID mplid
|
||||
);
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@ifset is-Ada
|
||||
@end ifset
|
||||
|
||||
@subheading STATUS CODES:
|
||||
|
||||
@code{EXXX} -
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
@c
|
||||
|
||||
@c This is the chapter from the RTEMS ITRON User's Guide that
|
||||
|
||||
@c documents the services provided by the memory pool
|
||||
|
||||
@c manager.
|
||||
|
||||
@c
|
||||
|
||||
@c $Id$
|
||||
|
||||
@c
|
||||
|
||||
|
||||
|
||||
@chapter Memory Pool Manager
|
||||
|
||||
|
||||
|
||||
@section Introduction
|
||||
|
||||
|
||||
|
||||
The
|
||||
|
||||
memory pool manager is ...
|
||||
|
||||
|
||||
|
||||
The services provided by the memory pool manager are:
|
||||
|
||||
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item @code{cre_mpl} - Create Variable-Size Memorypool
|
||||
|
||||
@item @code{del_mpl} - Delete Variable-Size Memorypool
|
||||
|
||||
@item @code{get_blk} - Get Variable-Size Memory Block
|
||||
|
||||
@item @code{pget_blk} - Poll and Get Variable-Size Memory Block
|
||||
|
||||
@item @code{tget_blk} - Get Variable-Size Memory Block with Timeout
|
||||
|
||||
@item @code{rel_blk} - Release Variable-Size Memory Block
|
||||
|
||||
@item @code{ref_mpl} - Reference Variable-Size Memorypool Status
|
||||
|
||||
@end itemize
|
||||
|
||||
|
||||
|
||||
@section Background
|
||||
|
||||
|
||||
|
||||
Memorypool management functions manage memorypools and allocate memory blocks.
|
||||
|
||||
There are two types of memorypool: fixed-size memorypools and variable-size
|
||||
|
||||
memorypools. Both are considered separate objects and require different
|
||||
|
||||
system calls for manipulation. While the size of memory blocks allocated
|
||||
|
||||
from fixed-size memorypools are all fixed, blocks of any size may be
|
||||
|
||||
specified when allocating memory blocks from variable-size memorypools.
|
||||
|
||||
|
||||
|
||||
@section Operations
|
||||
|
||||
|
||||
|
||||
@section System Calls
|
||||
|
||||
|
||||
|
||||
This section details the memory pool manager's services.
|
||||
|
||||
A subsection is dedicated to each of this manager's services
|
||||
|
||||
and describes the calling sequence, related constants, usage,
|
||||
|
||||
and status codes.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@c
|
||||
|
||||
@c cre_mpl
|
||||
|
||||
@c
|
||||
|
||||
|
||||
|
||||
@page
|
||||
|
||||
@subsection cre_mpl - Create Variable-Size Memorypool
|
||||
|
||||
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
|
||||
|
||||
@ifset is-C
|
||||
|
||||
@example
|
||||
|
||||
ER cre_mpl(
|
||||
|
||||
ID mplid,
|
||||
|
||||
T_CMPL *pk_cmpl
|
||||
|
||||
);
|
||||
|
||||
@end example
|
||||
|
||||
@end ifset
|
||||
|
||||
|
||||
|
||||
@ifset is-Ada
|
||||
|
||||
@end ifset
|
||||
|
||||
|
||||
|
||||
@subheading STATUS CODES:
|
||||
|
||||
|
||||
|
||||
@code{E_OK} - Normal Completion
|
||||
|
||||
|
||||
|
||||
@code{E_NOMEM} - Insufficient memory (Memory for control block and/or for
|
||||
|
||||
memorypool cannot be allocated)
|
||||
|
||||
|
||||
|
||||
@code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
|
||||
|
||||
|
||||
|
||||
@code{E_RSATR} - Reserved attribute (mplatr was invalid or could not be used)
|
||||
|
||||
|
||||
|
||||
@code{E_OBJ} - Invalid object state (a memorypool of the same ID already exists)
|
||||
|
||||
|
||||
|
||||
@code{E_OACV} - Object access violation (A mplid less than -4 was specified from
|
||||
|
||||
a user task. This is implementation dependent.)
|
||||
|
||||
|
||||
|
||||
@code{E_PAR} - Parameter error (pk_cmpl is invalid or mplsz is negative or
|
||||
|
||||
invalid)
|
||||
|
||||
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
|
||||
|
||||
The cre_mpl directive creates a variable-size memorypool having the ID number specified by mplid. Specifically, a memory area of the size determined by mplsz is allocated for use as a memorypool. A control block for the memorypool being created is also allocated. User memorypools have positive ID numbers, while system memorypools have negative ID numbers. User tasks (tasks having positive task IDs) cannot access system memorypools (memorypools having negative ID numbers).
|
||||
|
||||
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
|
||||
|
||||
The memory required for creating memorypools and for allocating control blocks for each object is reserved while system initialization. Associated parameters are therefore specified at system configuration.
|
||||
|
||||
|
||||
|
||||
@c
|
||||
|
||||
@c del_mpl
|
||||
|
||||
@c
|
||||
|
||||
|
||||
|
||||
@page
|
||||
|
||||
@subsection del_mpl - Delete Variable-Size Memorypool
|
||||
|
||||
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
|
||||
|
||||
@ifset is-C
|
||||
|
||||
@example
|
||||
|
||||
ER del_mpl(
|
||||
|
||||
ID mplid
|
||||
|
||||
);
|
||||
|
||||
@end example
|
||||
|
||||
@end ifset
|
||||
|
||||
|
||||
|
||||
@ifset is-Ada
|
||||
|
||||
@end ifset
|
||||
|
||||
|
||||
|
||||
@subheading STATUS CODES:
|
||||
|
||||
|
||||
|
||||
@code{E_OK} - Normal Completion
|
||||
|
||||
|
||||
|
||||
@code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
|
||||
|
||||
|
||||
|
||||
@code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist)
|
||||
|
||||
|
||||
|
||||
@code{E_OACV} - Object access violation (A mplid less than -4 was specified from
|
||||
|
||||
a user task. This is implementation dependent.)
|
||||
|
||||
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
|
||||
|
||||
This system call deletes the variable-size memorypool specified by mplid. No check or error report is performed even if there are tasks using memory from the memorypool to be deleted. This system call completes normally even if some of the memory blocks are not returned. Issuing this system call causes memory used for the control block of the associated memorypool and the memory area making up the memorypool itself to be released. After this system call is invoked, another memorypool having the same ID number can be created.
|
||||
|
||||
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
|
||||
|
||||
When a memorypool being waited for by more than one tasks is deleted, the order of tasks on the ready queue after the WAIT state is cleared is implementation dependent in the case of tasks having the same priority.
|
||||
|
||||
|
||||
|
||||
@c
|
||||
|
||||
@c get_blk
|
||||
|
||||
@c
|
||||
|
||||
|
||||
|
||||
@page
|
||||
|
||||
@subsection get_blk - Get Variable-Size Memory Block
|
||||
|
||||
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
|
||||
|
||||
@ifset is-C
|
||||
|
||||
@example
|
||||
|
||||
ER get_blk(
|
||||
|
||||
VP *p_blk,
|
||||
|
||||
ID mplid,
|
||||
|
||||
INT blksz
|
||||
|
||||
);
|
||||
|
||||
@end example
|
||||
|
||||
@end ifset
|
||||
|
||||
|
||||
|
||||
@ifset is-Ada
|
||||
|
||||
@end ifset
|
||||
|
||||
|
||||
|
||||
@subheading STATUS CODES:
|
||||
|
||||
|
||||
|
||||
@code{E_OK} - Normal Completion
|
||||
|
||||
|
||||
|
||||
@code{E_ID} - Invalid ID number (mplid was invalid or could not be used)
|
||||
|
||||
|
||||
|
||||
@code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist)
|
||||
|
||||
|
||||
|
||||
@code{E_OACV} - Object access violation (A mplid less than -4 was specified from
|
||||
|
||||
a user task. This is implementation dependent.)
|
||||
|
||||
|
||||
|
||||
@code{E_PAR} - Parameter error (tmout is -2 or less, blksz is negative or invalid)
|
||||
|
||||
|
||||
|
||||
@code{E_DLT} - The object being waited for was deleted (the specified memorypool
|
||||
|
||||
was deleted while waiting)
|
||||
|
||||
|
||||
|
||||
@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while
|
||||
|
||||
waiting)
|
||||
|
||||
|
||||
|
||||
@code{E_TMOUT} - Polling failure or timeout
|
||||
|
||||
|
||||
|
||||
@code{E_CTX} - Context error (issued from task-independent portions or a
|
||||
|
||||
task in dispatch disabled state; implementation dependent for
|
||||
|
||||
pget_blk and tget_blk(tmout=TMO_POL))
|
||||
|
||||
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
|
||||
|
||||
A memory block of the size in bytes given by blksz is allocated from the variable-size memorypool specified by mplid. The start address of the memory block allocated is returned in blk. The allocated memory block is not cleared to zero. The contents of the memory block allocated are undefined. If the memory block cannot be obtained from the specified memorypool when get_blk is issued, the task issuing get_blk will be placed on the memory allocation queue of the specified memorypool, and wait until it can get the memory it requires.
|
||||
|
||||
|
||||
|
||||
The order in which tasks wait on the queue when waiting to be allocated memory blocks is according to either FIFO or task priority. The specification whereby tasks wait according to task priority is considered an extended function [level X] for which compatibility is not guaranteed. Furthermore, when tasks form a memory allocation queue, it is implementation dependent whether priority is given to tasks requesting the smaller size of memory or those at the head of the queue.
|
||||
|
||||
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
|
||||
|
||||
Pget_blk and get_blk represent the same processing as specifying certain values (TMO_POL or TMO_FEVR) to tget_blk for tmout. It is allowed that only tget_blk is implemented in the kernel and that pget_blk and get_blk are implemented as macros which call tget_blk.
|
||||
|
||||
|
||||
|
||||
@c
|
||||
|
||||
@c pget_blk
|
||||
|
||||
@c
|
||||
|
||||
|
||||
|
||||
@page
|
||||
|
||||
@subsection pget_blk - Poll and Get Variable-Size Memory Block
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user