tk_cre_mbf
Create Message Buffer
ID mbfid = tk_cre_mbf ( T_CMBF *pk_cmbf ) ;
T_CMBF* pk_cmbf Information about the message buffer to be created
pk_cmbf detail:
VP exinf Extended information
ATR mbfatr Message buffer attributes
W bufsz Message buffer size (in bytes)
INT maxmsz Maximum message 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 mbfid Message buffer ID
or Error Code
E_NOMEM Insufficient memory (memory for control block or ring buffer area cannot be allocated)
E_LIMIT Number of message buffers exceeds the system limit
E_RSATR Reserved attribute (mbfatr is invalid or cannot be used)
E_PAR Parameter error (pk_cmbf is invalid, or bufsz or maxmsz is negative or invalid)
Creates a message buffer, assigning to it a message buffer ID.
This system call allocates a control block to the created message buffer. Based on the information specified in bufsz, it allocates a ring buffer area for message queue use (for messages waiting to be received).
A message buffer is an object for managing the sending and receiving of variable-size messages. It differs from a mailbox (mbx) in that the contents of the variable-size messages are copied when the message is sent and received. It also has a function for putting the sending task in WAIT state when the buffer is full.
exinf can be used freely by the user to store miscellaneous information about the created message buffer. The information set in this parameter can be referenced by tk_ref_mbf. If a larger area is needed for indicating user information, or if the information needs to be changed after the message buffer 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.
mbfatr indicates system attributes in its low bits and implementation-dependent information in the high bits. The system attributes part of mbfatr is as follows.
mbfatr := (TA_TFIFO || TA_TPRI) | TA_USERBUF | TA_DSNAME
TA_TFIFO Waiting tasks are queued in FIFO order
TA_TPRI Waiting tasks are queued in priority order
TA_USERBUF Indicates that the task uses an area specified by the user as a buffer
TA_DSNAME Specifies DS object name
The queuing order of tasks waiting for a message to be sent when the buffer is full 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. Messages themselves are queued in FIFO order only. Tasks waiting for message receipt from a message buffer are likewise queued in FIFO order only.
If TA_USERBUF is specified, bufptr becomes valid and the memory area of bufsz bytes with bufptr at the head is used as a message buffer area. In this case, the message buffer area is not prepared by OS. If TA_USERBUF is not specified, bufptr is ignored, and a message buffer area is allocated by 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.
#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 */
When there are multiple tasks waiting to send messages, the order in which the messages are sent when buffer space becomes available is always in their queued order. If, for example, a Task A wanting to send a 30-byte message is queued with a Task B wanting to send a 10-byte message, in the order A-B, even if 20 bytes of message buffer space becomes available, Task B never sends its message before Task A.
The ring buffer in which messages are queued also contains information for managing each message. For this reason, the total size of queued messages will ordinarily not be identical to the ring buffer size specified in bufsz. Normally the total message size will be smaller than bufsz. In this sense, bufsz does not strictly represent the total message capacity.
It is possible to create a message buffer with bufsz = 0. In this case communication using the message buffer is completely synchronous between the sending and receiving tasks. That is, if either tk_snd_mbf or tk_rcv_mbf is executed ahead of the other; the task executing the first system call goes to WAIT state. When the other system call is executed, the message is passed (copied) and both tasks resume running.
In the case of a bufsz = 0 message buffer, the specific functioning is as follows.
- In Figure 4.4, Task A and Task B operate asynchronously. If Task A arrives at point (1) first and executes
tk_snd_mbf, Task A goes to send wait state until Task B arrives at point (2). If tk_ref_tsk is issued for Task A in this state,tskwait=TTW_SMBFis returned. If, on the other hand, Task B gets to point (2) first and callstk_rcv_mbf, Task B goes to receive wait state until Task A gets to point (1). If tk_ref_tsk is issued for Task B in this state,tskwait=TTW_RMBF is returned. - At the point where both Task A has executed
tk_snd_mbfand Task B has executedtk_rcv_mbf, a message is passed from Task A to Task B, their wait states are released and both tasks resume running.
Figure 4.4: Synchronous Communication Using Message Buffer of bufsz =0
TA_NODISWAI does not exist in the attribute for mbfatr. This is because, in µT-Kernel, there is no wait-disabled function.
TA_USERBUF and bufptr are added.
bufsz, the member of T_CMBF, is of W type instead of INT type.
Note that maxmsz, the member of T_CMBF, is of INT type, and the range of values that can be specified may vary depending on the system. For example, in 16 bit environments, the maximum length of message that can be transmitted at a time may be limited to 32767 (approximately 32KB).
There is neither TA_USERBUF nor bufptr in T-Kernel. So, when using this function, modification is required when porting it to T-Kernel. However, if bufsz is set correctly, you can port it by simply deleting TA_USERBUF and bufptr.
Comments
Click here to Post a Comment