Everything

CHAPTER 6 MEMORY POOL MANAGEMENT FUNCTIONS


This chapter describes the memory pool management functions performed by the RI78V4.
6.1 Outline
The statically secured memory areas in the Kernel Initialization Module are subject to management by the memory pool management functions of the RI78V4.
In the RI78V4, the allocation destinations (section names) of management objects modularized for each function are specified.
The following lists the section names prescribed in the RI78V4.
- .kernel_system section
Area where the RI78V4's core processing part and main processing part of service calls provided by the RI78V4 are to be allocated.
- .kernel_system_timer_n section
Area where the interrupt fo system timer and information of FAR branch are to be allocated.
- .kernel_info section
Area where information items such as the RI78V4 version are to be allocated.
- .kernel_const / .kernel_const_f section
Area where initial information items related to OS resources that do not change dynamically are allocated as system information tables and interrupt information definition file.
- .kernel_stack section
Area where the system stack and the task stack are to be allocated.
- .kernel_data section
Area where information items required to implement the functionalities provided by the RI78V4 and information items related to OS resources that change dynamically are allocated as management objects.
- .kernel_data_init section
Area where initial information items of RI78V4 are to be allocated.
- .kernel_work0, .kernel_work1, .kernel_work2, .kernel_work3 section
Area where data of data queue and fixed-sized memory pools are to be allocated.
- .kernel_data_trace_n section
Area where the trace data are to be allocated.
- .kernel_const_trace_f section
Area where information items to get trace data are to be allocated.
- .kernel_system_trace_f section
Area where the processing part to get trace data are to be allocated.
- .kernel_sbss section
SADDR area where the RI78V4's core processing are to be allocated.
6.2 Fixed-Sized Memory Pool
When a dynamic memory manipulation request is issued from a processing program in the RI78V4, the fixed-sized memory pool is provided as a usable memory area.
Dynamic memory manipulation of the fixed-sized memory pool is executed in fixed size memory block units.
6.2.1 Create fixed-sized memory pool
In the RI78V4, the method of creating a fixed-sized memory pool is limited to "static creation by the Kernel Initialization Module".
Fixed-sized memory pools therefore cannot be created dynamically using a method such as issuing a service call from a processing program.
- Static create
Static fixed-sized memory pool creation is realized by defining Fixed-sized memory pool information in the system configuration file.
The RI78V4 executes fixed-sized memory pool creation processing based on data stored in information files, using the Kernel Initialization Module, and handles the created fixed-sized memory pools as management targets.
6.2.2 Delete fixed-sized memory pool
In the RI78V4, fixed-sized memory pools created statically by the Kernel Initialization Module cannot be deleted dynamically using a method such as issuing a service call from a processing program.
6.2.3 Acquire fixed-sized memory block
A memory block is acquired (waiting forever, polling, or with timeout) by issuing the following service call from the processing program.
- get_mpf
This service call acquires the memory block from the fixed-sized memory pool specified by parameter mpfid and stores the start address in the area specified by parameter p_blk.
If a memory block could not be acquired from the target fixed-sized memory pool (no available memory blocks exist) when this service call is issued, memory block acquisition processing is not performed but the invoking task is queued to the target fixed-sized memory pool wait queue in the order of memory block acquisition request (FIFO order).
As a result, the invoking task is unlinked from the ready queue and is moved from the RUNNING state to the WAITING state (waiting state for a fixed-sized memory block).
The waiting state for a fixed-sized memory block is cancelled in the following cases, and then moved to the READY state.
Waiting State for a Fixed-sized Memory Block Cancel Operation
Return Value
A memory block was returned to the target fixed-sized memory pool as a result of issuing rel_mpf.
E_OK
Forced release from waiting (accept rel_wai while waiting).
E_RLWAI
Forced release from waiting (accept irel_wai while waiting).
E_RLWAI

The following describes an example for coding this service call.
 #include    <kernel.h>          /*Standard header file definition*/
 #include    <kernel_id.h>       /*System information header file definition*/
 
 void
 func_task ( VP_INT exinf )
 {
     ER      ercd;               /*Declares variable*/
     ID      mpfid = ID_mpfA;    /*Declares and initializes variable*/
     VP      p_blk;              /*Declares variable*/
 
     /* ............ */
 
                                 /*Acquire fixed-sized memory block (wait
                                   forever)*/
     ercd = get_mpf ( mpfid, &p_blk );
 
     if ( ercd == E_OK ) {
         /* ............ */      /*Normal termination processing*/
 
                                 /*Release fixed-sized memory block*/
         rel_mpf ( mpfid, p_blk );
     } else if ( ercd == E_RLWAI ) {
         /* ............ */      /*Forced termination processing*/
     }
 
     /* ............ */
 }

- pget_mpf
This service call acquires the memory block from the fixed-sized memory pool specified by parameter mpfid and stores the start address in the area specified by parameter p_blk.
If a memory block could not be acquired from the target fixed-sized memory pool (no available memory blocks exist) when this service call is issued, memory block acquisition processing is not performed but "E_TMOUT" is returned.
The following describes an example for coding this service call.
 #include    <kernel.h>          /*Standard header file definition*/
 #include    <kernel_id.h>       /*System information header file definition*/
 
 void
 func_task ( VP_INT exinf )
 {
     ER      ercd;               /*Declares variable*/
     ID      mpfid = ID_mpfA;    /*Declares and initializes variable*/
     VP      p_blk;              /*Declares variable*/
 
     /* ............ */
 
                                 /*Acquire fixed-sized memory block (polling)*/
     ercd = pget_mpf ( mpfid, &p_blk );
 
     if ( ercd == E_OK ) {
         /* ............ */      /*Polling success processing*/
 
                                 /*Release fixed-sized memory block*/
         rel_mpf ( mpfid, p_blk );
     } else if ( ercd == E_TMOUT ) {
         /* ............ */      /*Polling failure processing*/
     }
 
     /* ............ */
 }

- tget_mpf
This service call acquires the memory block from the fixed-sized memory pool specified by parameter mpfid and stores the start address in the area specified by parameter p_blk.
If a memory block could not be acquired from the target fixed-sized memory pool (no available memory blocks exist) when this service call is issued, memory block acquisition processing is not performed but the invoking task is queued to the target fixed-sized memory pool wait queue in the order of memory block acquisition request (FIFO order).
As a result, the invoking task is unlinked from the ready queue and is moved from the RUNNING state to the WAITING state (waiting state for a fixed-sized memory block).
The waiting state for a fixed-sized memory block is cancelled in the following cases, and then moved to the READY state.
Waiting State for a Fixed-sized memory Block Cancel Operation
Return Value
A memory block was returned to the target fixed-sized memory pool as a result of issuing rel_mpf.
E_OK
Forced release from waiting (accept rel_wai while waiting).
E_RLWAI
Forced release from waiting (accept irel_wai while waiting).
E_RLWAI
Polling failure or timeout.
E_TMOUT

The following describes an example for coding this service call.
 #include    <kernel.h>          /*Standard header file definition*/
 #include    <kernel_id.h>       /*System information header file definition*/
 
 void
 func_task ( VP_INT exinf )
 {
     ER      ercd;               /*Declares variable*/
     ID      mpfid = ID_mpfA;    /*Declares and initializes variable*/
     VP      p_blk;              /*Declares variable*/
     TMO     tmout = 3600;       /*Declares and initializes variable*/
 
     /* ............ */
 
                                 /*Acquire fixed-sized memory block (with
                                   timeout)*/
     ercd = tget_mpf ( mpfid, &p_blk, tmout );
 
     if ( ercd == E_OK ) {
         /* ............ */      /*Normal termination processing*/
 
                                 /*Release fixed-sized memory block*/
         rel_mpf ( mpfid, p_blk );
     } else if ( ercd == E_RLWAI ) {
         /* ............ */      /*Forced termination processing*/
     } else if ( ercd == E_TMOUT ) {
         /* ............ */      /*Timeout processing*/
     }
 
     /* ............ */
 }

Note When TMO_FEVR is specified for wait time tmout, processing equivalent to get_mpf will be executed. When TMO_POL is specified, processing equivalent to pget_mpf will be executed.
6.2.4 Release fixed-sized memory block
A memory block is returned by issuing the following service call from the processing program.
- rel_mpf
This service call returns the memory block specified by parameter blk to the fixed-sized memory pool specified by parameter mpfid.
If a task is queued to the target fixed-sized memory pool wait queue when this service call is issued, memory block return processing is not performed but memory blocks are returned to the relevant task (first task of wait queue).
As a result, the relevant task is unlinked from the wait queue and is moved from the WAITING state (waiting state for a fixed-sized memory block) to the READY state, or from the WAITING-SUSPENDED state to the SUSPENDED state.
The following describes an example for coding this service call.
 #include    <kernel.h>          /*Standard header file definition*/
 #include    <kernel_id.h>       /*System information header file definition*/
 
 void
 func_task ( VP_INT exinf )
 {
     ER      ercd;               /*Declares variable*/
     ID      mpfid = ID_mpfA;    /*Declares and initializes variable*/
     VP      blk;                /*Declares variable*/
 
     /* ............ */
 
                                 /*Acquire fixed-sized memory block*/
     ercd = get_mpf ( mpfid, &blk );
 
     if ( ercd == E_OK ) {
         /* ............ */      /*Normal termination processing*/
 
                                 /*Release fixed-sized memory block*/
         rel_mpf ( mpfid, blk );
     } else if ( ercd == E_RLWAI ) {
         /* ............ */      /*Forced termination processing*/
     }
 
     /* ............ */
 }

Note 1 If the first task of the wait queue is moved to the READY state after this service call is issued, this service call also re-queues the task at the end of the ready queue corresponding to the priority of the task.
Note 2 The RI78V4 does not clear the memory blocks before returning them. The contents of the returned memory blocks are therefore undefined.
6.2.5 Reference fixed-sized memory pool state
A fixed-sized memory pool status is referenced by issuing the following service call from the processing program.
- ref_mpf
Stores fixed-sized memory pool state packet (such as existence of waiting tasks) of the fixed-sized memory pool specified by parameter mpfid in the area specified by parameter pk_rmpf.
The following describes an example for coding this service call.
 #include    <kernel.h>          /*Standard header file definition*/
 #include    <kernel_id.h>       /*System information header file definition*/
 
 void
 func_task ( VP_INT exinf )
 {
     ID      mpfid = ID_mpfA;    /*Declares and initializes variable*/
     T_RMPF  pk_rmpf;            /*Declares data structure*/
     ID      wtskid;             /*Declares variable*/
     UINT    fblkcnt;            /*Declares variable*/
 
     /* ............ */
 
     ref_mpf ( mpfid, &pk_rmpf );/*Reference fixed-sized memory pool state*/
 
     wtskid = pk_rmpf.wtskid;    /*Reference ID number of the task at the head of
                                   the wait queue*/
     fblkcnt = pk_rmpf.fblkcnt;  /*Reference number of free memory blocks*/
 
     /* ............ */
 }

Note For details about the fixed-sized memory pool state packet, refer to "12.5.7 Fixed-sized memory pool state packet".