doc: fix warnings due to :c:option: and :option:
:c:option:`xyz` is non usable without a . c:option:: declaration, so moved to *xyz`; likewise :option:`xyz` where no .. option:: xyz is declared. Change-Id: I011ccf2aac244125dbe2d09d197e443bd4c12fe2 Signed-off-by: Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
This commit is contained in:
parent
54f143b8e8
commit
9795410a62
2 changed files with 34 additions and 23 deletions
|
@ -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
|
listed below are available for application use; all other fields are for
|
||||||
kernel use only.
|
kernel use only.
|
||||||
|
|
||||||
:c:option:`info`
|
*info*
|
||||||
|
|
||||||
A 32-bit value that is exchanged by the message sender and receiver,
|
A 32-bit value that is exchanged by the message sender and receiver,
|
||||||
and whose meaning is defined by the application. This exchange is
|
and whose meaning is defined by the application. This exchange is
|
||||||
bi-directional, allowing the sender to pass a value to the receiver
|
bi-directional, allowing the sender to pass a value to the receiver
|
||||||
during any message exchange, and allowing the receiver to pass a value
|
during any message exchange, and allowing the receiver to pass a value
|
||||||
to the sender during a synchronous message exchange.
|
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
|
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.
|
message, or when discarding the message data of a received message.
|
||||||
The mailbox updates this field with the actual number of data bytes
|
The mailbox updates this field with the actual number of data bytes
|
||||||
exchanged once the message is received.
|
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
|
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
|
:c:macro:`NULL` when sending a memory pool block, or when sending
|
||||||
an empty message. (Not used when receiving a message.)
|
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
|
The descriptor for the memory pool block containing the sending task's
|
||||||
message data. (Not used when sending a message data buffer,
|
message data. (Not used when sending a message data buffer,
|
||||||
or when sending an empty message. Not used when receiving a message.)
|
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
|
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
|
: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
|
retrieved by a subsequent mailbox operation. (Not used when sending
|
||||||
a message.)
|
a message.)
|
||||||
|
|
||||||
:c:option:`tx_task`
|
*tx_task*
|
||||||
The name of the sending task. Set it to :c:macro:`ANYTASK` to receive
|
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
|
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
|
actual sender's name once the message is received. (Not used when
|
||||||
sending a message.)
|
sending a message.)
|
||||||
|
|
||||||
:c:option:`rx_task`
|
*rx_task*
|
||||||
The name of the receiving task. Set it to :c:macro:`ANYTASK` to allow
|
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
|
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
|
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
|
* 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
|
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
|
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
|
:c:func:`task_mbox_data_get()`. This instructs the mailbox to copy the data
|
||||||
and delete the message.
|
and delete the message.
|
||||||
|
|
||||||
* If the message descriptor size is non-zero and the receiving task does *not*
|
* 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
|
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.
|
This instructs the mailbox to delete the message without copying the data.
|
||||||
|
|
||||||
The subsequent data retrieval technique is suitable for applications where
|
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.
|
Retrieve message data into a buffer.
|
||||||
|
|
||||||
:cpp:func:`task_mbox_data_block_get()`
|
:cpp:func:`task_mbox_data_block_get()`
|
||||||
Retrieve message data into a block, with time limited waiting.
|
Retrieve message data into a block, with time limited waiting.
|
||||||
|
|
|
@ -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
|
and a :dfn:`pipe option` that indicates the minimum number of data bytes
|
||||||
the pipe must accept. The following pipe option values are supported:
|
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.
|
Specifies that **all** available data bytes must be accepted by the pipe.
|
||||||
When this requirement is not fulfilled, the send request either fails or
|
When this requirement is not fulfilled, the send request either fails or
|
||||||
performs a partial send.
|
performs a partial send.
|
||||||
:option:`_1_TO_N`
|
|
||||||
|
``_1_TO_N``
|
||||||
|
|
||||||
Specifies that **at least one** data byte must be accepted by the pipe.
|
Specifies that **at least one** data byte must be accepted by the pipe.
|
||||||
When this requirement is not fulfilled, the send request fails.
|
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
|
Specifies that **any number** of data bytes, including zero, may be accepted
|
||||||
by the pipe; the send request never fails.
|
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
|
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
|
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
|
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
|
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
|
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
|
data bytes the pipe must deliver. The following pipe option values
|
||||||
are supported:
|
are supported:
|
||||||
|
|
||||||
:option:`_ALL_N`
|
``_ALL_N``
|
||||||
|
|
||||||
Specifies that all desired number of data bytes must be received.
|
Specifies that all desired number of data bytes must be received.
|
||||||
When this requirement is not fulfilled, the receive request either fails or
|
When this requirement is not fulfilled, the receive request either fails or
|
||||||
performs a partial receive.
|
performs a partial receive.
|
||||||
:option:`_1_TO_N`
|
|
||||||
|
``_1_TO_N``
|
||||||
|
|
||||||
Specifies that at least one data byte must be received. When this requirement
|
Specifies that at least one data byte must be received. When this requirement
|
||||||
is not fulfilled, the receive request fails.
|
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
|
Specifies that any number of data bytes (including zero) may be
|
||||||
received; the receive request never fails.
|
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
|
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
|
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
|
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
|
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
|
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
|
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;
|
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
|
transferred in a single operation. The same is true when multiple receiving
|
||||||
tasks are reading from the same pipe.
|
tasks are reading from the same pipe.
|
||||||
|
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue