tget_mpl

Outline

Acquire variable-sized memory block (with time-out).

C format

 ER      tget_mpl (ID mplid, UINT blksz, VP *p_blk, TMO tmout);

Parameter(s)

I/O	Parameter	Description
I	ID mplid;	ID number of the variable-sized memory pool.
I	UINT blksz;	Memory block size to be acquired (in bytes).
O	VP *p_blk;	Start address of the acquired memory block.
I	TMO tmout;	Specified time-out (in millisecond). TMO_FEVR: Waiting forever. TMO_POL: Polling. Value: Specified time-out.

Explanation

This service call acquires a variable-size memory block of the size specified by parameter blksz from the variable-size memory pool specified by parameter mplid, and stores its start address into the area specified by parameter p_blk.

If no variable-size memory blocks could be acquired from the target variable-size memory pool (no successive areas equivalent to the requested size were available) when this service call is issued, this service call does not acquire variable-size memory blocks but queues the invoking task to the target variable-size memory pool wait queue and moves it from the RUNNING state to the WAITING state with time-out (variable-size memory block acquisition wait state).

The WAITING state for a variable-sized memory block is cancelled in the following cases.

WAITING State for a Variable-sized Memory Block Cancel Operation	Return Value
The variable-size memory block that satisfies the requested size was returned to the target variable-size memory pool as a result of issuing rel_mpl.	E_OK
The task at the top of the transmission wait queue was forcedly released from waiting by following either. - Forced release from waiting (accept rel_wai while waiting). - Forced release from waiting (accept irel_wai while waiting). - Forced release from waiting (accept ter_tsk while waiting). - The time specified by tmout for tget_mpl has elapsed.	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 variable-sized memory pool is reset as a result of issuing vrst_mpl.	EV_RST
The time specified by tmout has elapsed.	E_TMOUT
Forced release from waiting (accept del_mpl while waiting).	E_DLT

Note 1 For the size of the memory block, refer to "9.3.1 Size of Variable-sized memory block".

Note 2 Invoking tasks are queued to the target variable-size memory pool wait queue in the FIFO order.

Note 3 The contents of the block are undefined.

Note 4 The alignment number of memory blocks changes with creation method of the variable-sized memory pool.

- Created by system configuration file
The alignment number is 1. To enlarge the alignment number to 4, specify unique section to Section name assigned to the memory pool area (mpl_section) in Variable-sized Memory Pool Information (variable_memorypool[]) and locate the section to 4-bytes boundary address when linking.

- Created by cre_mpl or acre_mpl
The alignment number is 4.

Note 5 TMO_FEVR is specified for wait time tmout, processing equivalent to get_mpl will be executed. When TMO_POL is specified, processing equivalent to pget_mpl will be executed.

Return value

Macro	Value	Description
E_OK	0	Normal completion.
E_PAR	-17	Parameter error. - blksz == 0 - blksz exceeds the maximum size that can be acquired. - p_blk == NULL - tmout < -1 - tmout > (0x7FFFFFFF - TIC_NUME) / TIC_DENO
E_ID	-18	Invalid ID number. - mplid < 0 - mplid > VTMAX_MPL
E_CTX	-25	Context error. - This service call was issued from a non-task. - This service call was issued in the CPU locked state. - This service call was issued in the dispatching disabled state. - This service call was issued in the status "PSW.IPL > kernel interrupt mask level".
E_MACV	-26	Memory access violation. - Stack pointer points out of user stack for invoking task. - The operand-write access to the area indicated by p_blk has not been permitted to the invoking task.
E_NOEXS	-42	Non-existent object. - The variable-sized memory pool specified by mplid does not exist.
E_RLWAI	-49	Forced release from the WAITING state. - Accept rel_wai/irel_wai while waiting.
E_TMOUT	-50	Polling failure or specified time has elapsed.
E_DLT	-51	Waiting object deleted. - Accept del_mpl while waiting.
EV_RST	-127	Released from WAITING state by the object reset (vrst_mpl)