michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Edit microkernel_pipes for ReST syntax, readability, grammar

Browse source 
Add :dfn: and other .rst kinds of syntax and parallel format to
other documents in the microkernel sections. Corrected a few
typos.

Change-Id: I8e0d36a2f9091f551674fdf0518bb66453ada49b
Signed-off-by: L.S. Cook <leonax.cook@intel.com>
This commit is contained in:
L.S. Cook 2016-03-11 08:07:23 -08:00 • committed by Gerrit Code Review
commit e017d92dfe
1 changed files with 55 additions and 49 deletions
Download patch file Download diff file Expand all files Collapse all files

104
doc/kernel/microkernel/microkernel_pipes.rst
View file

@ -6,7 +6,7 @@ Pipes
Concepts Concepts
******** ********
The microkernel's pipe object type is an implementation of a traditional The microkernel's :dfn:`pipe` object type is an implementation of a traditional
anonymous pipe. anonymous pipe.
A pipe allows a task to send a byte stream to another task. The pipe can be A pipe allows a task to send a byte stream to another task. The pipe can be
@ -15,26 +15,28 @@ but not yet received; alternatively, the pipe may have no ring buffer.
Pipes can be used to transfer chunks of data in whole or in part, and either Pipes can be used to transfer chunks of data in whole or in part, and either
synchronously or asynchronously. synchronously or asynchronously.
Any number of pipes can be defined in a microkernel system. Each pipe has a Any number of pipes can be defined in a microkernel system. Each pipe needs
name that uniquely identifies it. In addition, a pipe defines the size of * A **name** to uniquely identify it.
its ring buffer; a size of zero defines a pipe with no ring buffer. * A **size**, in bytes, of the ring buffer. Note that a size of zero defines
a pipe with no ring buffer.
Sending Data Sending Data
============ ============
A task sends data to a pipe by specifying a pointer to the data bytes A task sends data to a pipe by specifying a pointer to the data bytes
to be sent. It also specifies both the number of data bytes available to be sent. It also specifies both the number of data bytes available
and a *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` :option:`_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.
otherwise the send request fails or performs a partial send. When this requirement is not fulfilled, the send request either fails or
performs a partial send.
:option:`_1_TO_N` :option:`_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.
otherwise the send request fails. When this requirement is not fulfilled, the send request fails.
:option:`_0_TO_N` :option:`_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.
The pipe accepts data bytes from the sending task if they can be delivered The pipe accepts data bytes from the sending task if they can be delivered
@ -43,16 +45,17 @@ to wait, or has waited as long as it can, the pipe can also accept data bytes
by copying them to its ring buffer for later delivery. The ring buffer is used by copying them to its ring buffer for later delivery. The ring buffer is used
only when necessary to minimize copying of data bytes. only when necessary to minimize copying of data bytes.
Upon completion of a send operation a return code is provided to indicate Upon the completion of a send operation, a :dfn:`return code` is provided to
if the send request was satisfied. The sending task can also read the *bytes indicate whether the send request was satisfied. The sending task can also read
written* argument to determine how many data bytes were accepted by the pipe, the ``bytes written`` argument attribute to determine how many data bytes were
allowing it to deal with any unsent data bytes. accepted by the pipe, and subsequently allowing it to deal with any unsent data
bytes.
Data sent to a pipe that does not have a ring buffer is sent synchronously; Data sent to a pipe that does not have a ring buffer is sent synchronously;
that is, when the send operation is complete the sending task knows that the that is, when the send operation is complete, the sending task knows that the
receiving task has received the data that was sent. Data sent to a pipe receiving task has received the data that was sent. Data sent to a pipe
that has a ring buffer is sent asynchronously; that is, when the send operation that has a ring buffer is sent asynchronously; that is, when the send operation
is complete some or all of the data that was sent may still be in the pipe is complete, some or all of the data that was sent may still be in the pipe
waiting for the receiving task to receive it. waiting for the receiving task to receive it.
Incomplete Send Requests Incomplete Send Requests
@ -60,15 +63,15 @@ 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 :option:`_ALL_N` pipe option is specified, it does not guarantee that the
data bytes will be accepted in an "all or nothing" manner. If 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 :option:`RC_INCOMPLETE`
to notify the sending task that its request was not fully satisfied; if 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 :option:`RC_FAIL`.
An example of a situation that can result in an incomplete send is a time One example of a situation that can result in an incomplete send is a
limited send request through an unbuffered pipe. If the receiving task time-limited send request through an unbuffered pipe. If the receiving task
chooses to receive only a subset of the sender's data bytes, and then the chooses to receive only a subset of the sender's data bytes, and the send
send operation times out before the receiving task attempts to receive the operation times out before the receiving task attempts to receive the
remainder, an incomplete send occurs. remainder, an incomplete send occurs.
Sending using a Memory Pool Block Sending using a Memory Pool Block
@ -79,27 +82,29 @@ its efficiency by placing the data into a memory pool block and sending
the block. The pipe treats the memory block as a temporary addition to the block. The pipe treats the memory block as a temporary addition to
its ring buffer, allowing it to immediately accept the data bytes without its ring buffer, allowing it to immediately accept the data bytes without
copying them. Once all of the data bytes in the block have been delivered copying them. Once all of the data bytes in the block have been delivered
to the receiving task the pipe automatically frees the block back to the to the receiving task, the pipe automatically frees the block back to the
memory pool. memory pool.
Data sent using a memory pool block is always sent asynchronously, even for Data sent using a memory pool block is always sent asynchronously, even for
a pipe with no ring buffer of its own. Likewise, the pipe always accepts all a pipe with no ring buffer of its own. Likewise, the pipe always accepts all
of the available data in the block---a partial transfer never occurs. of the available data in the block -- a partial transfer never occurs.
Receiving Data Receiving Data
============== ==============
A task receives from a pipe by specifying a pointer to an area to receive A task receives from a pipe by specifying a pointer to an area to receive
the data bytes that were sent. It also specifies both the desired number the data bytes that were sent. It also specifies both the desired number
of data bytes and a *pipe option* that indicates the minimum number of data of data bytes and a :dfn:`pipe option` that indicates the minimum number of
bytes the pipe must deliver. The following pipe option values are supported: data bytes the pipe must deliver. The following pipe option values
are supported:
:option:`_ALL_N` :option:`_ALL_N`
Specifies that all desired number of data bytes must be received; Specifies that all desired number of data bytes must be received.
otherwise the receive request fails or performs a partial receive. When this requirement is not fulfilled, the receive request either fails or
performs a partial receive.
:option:`_1_TO_N` :option:`_1_TO_N`
Specifies that at least one data byte must be received; otherwise Specifies that at least one data byte must be received. When this requirement
the receive request fails. is not fulfilled, the receive request fails.
:option:`_0_TO_N` :option:`_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.
@ -108,27 +113,27 @@ The pipe delivers data bytes by copying them directly from the sending task
or from the pipe's ring buffer. Data bytes taken from the ring buffer are or from the pipe's ring buffer. Data bytes taken from the ring buffer are
delivered in a first in, first out manner. delivered in a first in, first out manner.
When a pipe is unable to deliver the specified minimum number of data bytes When a pipe is unable to deliver the specified minimum number of data bytes,
the receiving task may choose to wait until they can be delivered. the receiving task may choose to wait until they can be delivered.
Upon completion of a receive operation a return code is provided to indicate Upon completion of a receive operation, a :dfn:`return code` is provided to
if the receive request was satisfied. The receiving task can also read the indicate whether the receive request was satisfied. The receiving task also
*bytes read* argument to determine how many data bytes were delivered can read the ``bytes read`` argument attribute to determine how many
by the pipe. data bytes were delivered by the pipe.
Incomplete Receive Requests 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 :option:`_ALL_N` pipe option is specified, it does not guarantee that the
data bytes will be delivered in an "all or nothing" manner. If 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 :option:`RC_INCOMPLETE`
to notify the receiving task that its request was not fully satisfied; if 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 :option:`RC_FAIL`.
An example of a situation that can result in an incomplete receive is a time An example of a situation that can result in an incomplete receive is a
limited recieve request through an unbuffered pipe. If the sending task time-limited receive request through an unbuffered pipe. If the sending task
sends fewer than the desired number of data bytes, and then the receive sends fewer than the desired number of data bytes, and the receive
operation times out before the sending task attempts to send the remainder, operation times out before the sending task attempts to send the remainder,
an incomplete receive occurs. an incomplete receive occurs.
@ -208,7 +213,7 @@ For example, the following code defines a private pipe named ``PRIV_PIPE``.
DEFINE_PIPE(PRIV_PIPE, 1024); DEFINE_PIPE(PRIV_PIPE, 1024);
To utilize this pipe from a different source file use the following syntax: To use this pipe from a different source file use the following syntax:
.. code-block:: c .. code-block:: c
@ -302,13 +307,14 @@ unprocessed data bytes in the pipe.
APIs APIs
**** ****
The following Pipe APIs are provided by :file:`microkernel.h`: Pipe APIs provided by :file:`microkernel.h`
===========================================
:c:func:`task_pipe_put()` :c:func:`task_pipe_put()`
Writes data to a pipe, with time limited waiting. Write data to a pipe, with time limited waiting.
:c:func:`task_pipe_block_put()` :c:func:`task_pipe_block_put()`
Writes data to a pipe from a memory pool block. Write data to a pipe from a memory pool block.
:c:func:`task_pipe_get()` :c:func:`task_pipe_get()`
Reads data from a pipe, or fails and continues if data isn't there. Read data from a pipe, or fails and continues if data isn't there.