tk_cre_mpl
Create Variable-size Memory Pool
See Also
ID mplid = tk_cre_mpl ( T_CMPL *pk_cmpl ) ;
T_CMPL* pk_cmpl Information about the variable-size memory pool to be created
pk_cmpf detail:
VP exinf Extended information
ATR mplatr Memory pool attributes
W mplsz Memory pool size (in bytes)
UB dsname[8] DS object name
VP bufptr User buffer pointer
(Other implementation-dependent parameters may be added beyond this point.)
ID mplid Variable-size memory pool ID
or Error Code
E_NOMEM Insufficient memory (memory for control block or memory pool area cannot be allocated)
E_LIMIT Number of variable-size memory pools exceeds the system limit
E_RSATR Reserved attribute (mplatr is invalid or cannot be used)
E_PAR Parameter error (pk_cmpl is invalid, or mplsz is negative or invalid)
Creates a variable-size memory pool, assigning to it a variable-size memory pool ID.
This system call allocates a memory space for use as a memory pool, based on the information in parameter mplsz, and allocates a control block to the created memory pool.
exinf can be used freely by the user to store miscellaneous information about the created memory pool. The information set in this parameter can be referenced by tk_ref_mpl. If a larger area is needed for indicating user information, or if the information needs to be changed after the memory pool is created, this can be done by allocating separate memory for this purpose and putting the memory packet address in exinf. The OS pays no attention to the contents of exinf.
mplatr indicates system attributes in its low bits and implementation-dependent information in the high bits.
The system attributes part of mplatr is as follows.
mplatr:= (TA_TFIFO || TA_TPRI) | TA_USERBUF | TA_DSNAME | (TA_RNG0 || TA_RNG1 || TA_RNG2 || TA_RNG3)
TA_TFIFO Tasks waiting for memory allocation are queued in FIFO order
TA_TPRI Tasks waiting for memory allocation are queued in priority order
TA_RNGn Memory access privilege is set to protection level n
TA_USERBUF Indicates that an area specified by the user is used as the buffer
TA_DSNAME Specifies DS object name
#define TA_TFIFO 0x00000000 /* manage task queue by FIFO */
#define TA_TPRI 0x00000001 /* manage task queue by priority */
#define TA_USERBUF 0x00000020 /* User buffer */
#define TA_DSNAME 0x00000040 /* DS object name */
#define TA_RNG0 0x00000000 /* protection level 0 */
#define TA_RNG1 0x00000100 /* protection level 1 */
#define TA_RNG2 0x00000200 /* protection level 2 */
#define TA_RNG3 0x00000300 /* protection level 3 */
The queuing order of tasks waiting to acquire memory from a memory pool can be specified in TA_TFIFO or TA_TPRI. If the attribute is TA_TFIFO, tasks are ordered by FIFO, whereas TA_TPRI specifies queuing of tasks in order of their priority setting.
When tasks are queued waiting for memory allocation, memory is allocated in the order of queuing. Even if other tasks in the queue are requesting smaller amounts of memory than the task at the head of the queue, they do not acquire memory blocks before the first task. If, for example, Task A requesting a 400-byte memory block from a variable-size memory pool is queued along with Task B requesting a 100-byte block, in A-B order, then even if 200 bytes of space are free, Task B is made to wait until Task A has acquired the requested memory block.
For TA_RNGn, a protection level shall be specified to restrict memory access. However, in µT-Kernel, systems without MMU are assumed. So, all the specified protection levels behave the same as protection level 0.
If TA_USERBUF is specified, bufptr becomes valid, and the memory area of mplsz bytes with bufptr at the head is used as a memory pool area. In this case, the memory pool area is not prepared by the OS. If TA_USERBUF is not specified, bufptr is ignored, and a memory pool area is allocated by the OS.
When TA_DSNAME is specified, dsname is valid and specifies the DS object name. DS object name is used by the debugger to identify objects and is handled only by debugger support functions API, td_ref_dsname and td_set_dsname. For more details, refer to td_ref_dsname and td_set_dsname. If TA_DSNAME is not specified, dsname is ignored. Then td_ref_dsname and td_set_dsname return E_OBJ error.
If the task at the head of the queue waiting for memory allocation has its WAIT state forcibly released or if a different task becomes the first in the queue as a result of a change in task priority, allocation of memory to that task is attempted. If memory can be allocated, the WAIT state of that task is released.
In this way, it is possible under some circumstances for memory allocation to take place and task WAIT state to be released even when memory is not released by tk_rel_mpl.
Systems without MMU are assumed for µT-Kernel. However, in order to ensure portability to the T-Kernel, the TA_RNGn attribute shall be accepted.
It is possible, for example, to treat all TA_RNGn as equivalent to TA_RNG0 but no error must be returned.
The capability of creating multiple memory pools can be used for memory allocation as needed for error handling or in emergencies, etc.
TA_NODISWAI does not exist in the attribute for mplatr. This is because in µT-Kernel, there is no wait disabled function.
TA_USERBUF and bufptr have been added.
In µT-Kernel, systems without MMU are assumed. So the functions relating to protection levels are not supported. However, the TA_RNGn attribute has been retained to maintain compatibility with the T-Kernel.
mplsz, the member of T_CMPL, is of W type instead of INT type.
There is neither TA_USERBUF nor bufptr in T-Kernel. So, when using this function, modification is required when porting it to the T-Kernel. However if mplsz is set correctly, you can port it by simply deleting TA_USERBUF and bufptr.
Comments
Click here to Post a Comment