Pipes

Sending Data

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 and a pipe option that indicates the minimum number of data bytes the pipe must accept. The following pipe option values are supported:

_ALL_N

Specifies that all available data bytes must be accepted by the pipe; otherwise the send request fails or performs a partial send.

_1_TO_N

Specifies that at least one data byte must be accepted by the pipe; otherwise the send request fails.

_0_TO_N

Specifies that any number of data bytes, including zero, may be accepted by the pipe; the send request never fails.

The pipe accepts data bytes from the sending task if they can be delivered by copying them directly to the receiving task. If the sending task is unable 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 only when necessary to minimize copying of data bytes.

Upon completion of a send operation a return code is provided to indicate if the send request was satisfied. The sending task can also read the bytes written argument to determine how many data bytes were accepted by the pipe, allowing it to deal with any unsent data bytes.

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 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 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.

Receiving Data

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 of data bytes and a pipe option that indicates the minimum number of data bytes the pipe must deliver. The following pipe option values are supported:

_ALL_N

Specifies that all desired number of data bytes must be received; otherwise the receive request fails or performs a partial receive.

_1_TO_N

Specifies that at least one data byte must be received; otherwise the receive request fails.

_0_TO_N

Specifies that any number of data bytes (including zero) may be received; the receive request never fails.

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 delivered in a first in, first out manner.

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.

Upon completion of a receive operation a return code is provided to indicate if the receive request was satisfied. The receiving task can also read the bytes read argument to determine how many data bytes were delivered by the pipe.

Sharing a Pipe

A pipe is typically used by a single sending task and a single receiving task; however, it is possible for a pipe to be shared by multiple sending 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 _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.

Defining a Pipe

The following parameters must be defined:

name

This specifies a unique name for the pipe.

buffer_size

This specifies the size in bytes of the pipe’s ring buffer. If no ring buffer is to be used specify zero.

PIPE name buffer_size

% PIPE   NAME          BUFFERSIZE
% ===============================
  PIPE   DATA_PIPE        1024

DEFINE_PIPE(name, size);

DEFINE_PIPE(PRIV_PIPE, 1024);

extern const kpipe_t PRIV_PIPE;

Example: Writing Fixed-Size Data Items to a Pipe

This code uses a pipe to send a series of fixed-size data items to a consuming task.

void producer_task(void)
{
    struct item_type data_item;
    int amount_written;

    while (1) {
        /* generate a data item to send */
        data_item = ... ;

        /* write the entire data item to the pipe */
        task_pipe_put(DATA_PIPE, &data_item, sizeof(data_item),
                           &amount_written, _ALL_N, TICKS_UNLIMITED);

    }
}

Example: Reading Fixed-Size Data Items from a Pipe

This code uses a pipe to receive a series of fixed-size data items from a producing task. To improve performance, the consuming task waits until 20 data items are available then reads them as a group, rather than reading them individually.

void consumer_task(void)
{
    struct item_type data_items[20];
    int amount_read;
    int i;

    while (1) {
        /* read 20 complete data items at once */
        task_pipe_get(DATA_PIPE, &data_items, sizeof(data_items),
                      &amount_read, _ALL_N, TICKS_UNLIMITED);

        /* process the data items one at a time */
        for (i = 0; i < 20; i++) {
            ... = data_items[i];
            ...
        }
    }
}

Example: Reading a Stream of Data Bytes from a Pipe

This code uses a pipe to process a stream of data bytes from a producing task. The pipe is read in a non-blocking manner to allow the consuming task to perform other work when there are no unprocessed data bytes in the pipe.

void consumer_task(void)
{
    char data_area[20];
    int amount_read;
    int i;

    while (1) {
        /* consume any data bytes currently in the pipe */
        while (task_pipe_get(DATA_PIPE, &data_area, sizeof(data_area),
                             &amount_read, _1_TO_N, TICKS_NONE) == RC_OK) {
            /* now have from 1 to 20 data bytes */
            for (i = 0; i < amount_read; i++) {
                ... = data_area[i];
                ...
            }
        }

        /* do other processing */
        ...
    }
}