diff --git a/doc/kernel/microkernel/microkernel_mailboxes.rst b/doc/kernel/microkernel/microkernel_mailboxes.rst index ebc2b90017a..de92bf7a4fe 100644 --- a/doc/kernel/microkernel/microkernel_mailboxes.rst +++ b/doc/kernel/microkernel/microkernel_mailboxes.rst @@ -84,42 +84,43 @@ A message descriptor is a structure of type :c:type:`struct k_msg`. The fields listed below are available for application use; all other fields are for kernel use only. - :c:option:`info` + *info* + A 32-bit value that is exchanged by the message sender and receiver, and whose meaning is defined by the application. This exchange is bi-directional, allowing the sender to pass a value to the receiver during any message exchange, and allowing the receiver to pass a value to the sender during a synchronous message exchange. - :c:option:`size` + *size* The message data size, in bytes. Set it to zero when sending an empty message, or when discarding the message data of a received message. The mailbox updates this field with the actual number of data bytes exchanged once the message is received. - :c:option:`tx_data` + *tx_data* A pointer to the sending task's message data buffer. Set it to :c:macro:`NULL` when sending a memory pool block, or when sending an empty message. (Not used when receiving a message.) - :c:option:`tx_block` + *tx_block* The descriptor for the memory pool block containing the sending task's message data. (Not used when sending a message data buffer, or when sending an empty message. Not used when receiving a message.) - :c:option:`rx_data` + *rx_data* A pointer to the receiving task's message data buffer. Set it to :c:macro:`NULL` when the message's data is not wanted, or when it will be retrieved by a subsequent mailbox operation. (Not used when sending a message.) - :c:option:`tx_task` + *tx_task* The name of the sending task. Set it to :c:macro:`ANYTASK` to receive a message sent by any task. The mailbox updates this field with the actual sender's name once the message is received. (Not used when sending a message.) - :c:option:`rx_task` + *rx_task* The name of the receiving task. Set it to :c:macro:`ANYTASK` to allow any task to receive the message. The mailbox updates this field with the actual receiver's name once the message is received, but only if @@ -254,13 +255,13 @@ The receiving task must then respond as follows: * If the message descriptor size is non-zero and the receiving task still wants to retrieve the data, the task must supply a buffer large enough to hold the data. The task first sets the message descriptor's - :c:option:`rx_data` field to the address of the buffer, then calls + *rx_data* field to the address of the buffer, then calls :c:func:`task_mbox_data_get()`. This instructs the mailbox to copy the data and delete the message. * If the message descriptor size is non-zero and the receiving task does *not* want to retrieve the data, the task sets the message descriptor's - :c:option:`size` field to zero and calls :c:func:`task_mbox_data_get()`. + *size* field to zero and calls :c:func:`task_mbox_data_get()`. This instructs the mailbox to delete the message without copying the data. The subsequent data retrieval technique is suitable for applications where @@ -641,4 +642,4 @@ The following APIs for mailbox operations are provided by the kernel: Retrieve message data into a buffer. :cpp:func:`task_mbox_data_block_get()` - Retrieve message data into a block, with time limited waiting. \ No newline at end of file + Retrieve message data into a block, with time limited waiting. diff --git a/doc/kernel/microkernel/microkernel_pipes.rst b/doc/kernel/microkernel/microkernel_pipes.rst index 944ffa4e86a..76b5226acf7 100644 --- a/doc/kernel/microkernel/microkernel_pipes.rst +++ b/doc/kernel/microkernel/microkernel_pipes.rst @@ -31,14 +31,19 @@ to be sent. It also specifies both the number of data bytes available and a :dfn:`pipe option` that indicates the minimum number of data bytes the pipe must accept. The following pipe option values are supported: - :option:`_ALL_N` + ``_ALL_N`` + Specifies that **all** available data bytes must be accepted by the pipe. When this requirement is not fulfilled, the send request either fails or performs a partial send. - :option:`_1_TO_N` + + ``_1_TO_N`` + Specifies that **at least one** data byte must be accepted by the pipe. When this requirement is not fulfilled, the send request fails. - :option:`_0_TO_N` + + ``_0_TO_N`` + Specifies that **any number** of data bytes, including zero, may be accepted by the pipe; the send request never fails. @@ -65,11 +70,11 @@ Incomplete Send Requests ------------------------ Although a pipe endeavors to accept all available data bytes when the -:option:`_ALL_N` pipe option is specified, it does not guarantee that the +``_ALL_N`` pipe option is specified, it does not guarantee that the data bytes will be accepted in an "all or nothing" manner. When the pipe -is able to accept at least one data byte, it returns :option:`RC_INCOMPLETE` +is able to accept at least one data byte, it returns :c:macro:`RC_INCOMPLETE` to notify the sending task that its request was not fully satisfied. When -the pipe is unable to accept any data bytes, it returns :option:`RC_FAIL`. +the pipe is unable to accept any data bytes, it returns :c:macro:`RC_FAIL`. One example of a situation that can result in an incomplete send is a time-limited send request through an unbuffered pipe. If the receiving task @@ -101,14 +106,19 @@ of data bytes and a :dfn:`pipe option` that indicates the minimum number of data bytes the pipe must deliver. The following pipe option values are supported: - :option:`_ALL_N` + ``_ALL_N`` + Specifies that all desired number of data bytes must be received. When this requirement is not fulfilled, the receive request either fails or performs a partial receive. - :option:`_1_TO_N` + + ``_1_TO_N`` + Specifies that at least one data byte must be received. When this requirement is not fulfilled, the receive request fails. - :option:`_0_TO_N` + + ``_0_TO_N`` + Specifies that any number of data bytes (including zero) may be received; the receive request never fails. @@ -128,11 +138,11 @@ Incomplete Receive Requests --------------------------- Although a pipe endeavors to deliver all desired data bytes when the -:option:`_ALL_N` pipe option is specified, it does not guarantee that the +``_ALL_N`` pipe option is specified, it does not guarantee that the data bytes will be delivered in an "all or nothing" manner. When the pipe -is able to deliver at least one data byte, it returns :option:`RC_INCOMPLETE` +is able to deliver at least one data byte, it returns :c:macro:`RC_INCOMPLETE` to notify the receiving task that its request was not fully satisfied. When -the pipe is unable to deliver any data bytes, it returns :option:`RC_FAIL`. +the pipe is unable to deliver any data bytes, it returns :c:macro:`RC_FAIL`. An example of a situation that can result in an incomplete receive is a time-limited receive request through an unbuffered pipe. If the sending task @@ -155,7 +165,7 @@ tasks or multiple receiving tasks. Care must be taken when a pipe is shared by multiple sending tasks to ensure the data bytes they send do not become interleaved unexpectedly; -using the :option:`_ALL_N` pipe option helps to ensure that each data chunk is +using the ``_ALL_N`` pipe option helps to ensure that each data chunk is transferred in a single operation. The same is true when multiple receiving tasks are reading from the same pipe.