Zephyr API Documentation  3.7.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
Pipe APIs

Data Structures

struct  k_pipe
 Pipe Structure. More...
 

Macros

#define K_PIPE_DEFINE(name, pipe_buffer_size, pipe_align)
 Statically define and initialize a pipe.
 

Functions

void k_pipe_init (struct k_pipe *pipe, unsigned char *buffer, size_t size)
 Initialize a pipe.
 
int k_pipe_cleanup (struct k_pipe *pipe)
 Release a pipe's allocated buffer.
 
int k_pipe_alloc_init (struct k_pipe *pipe, size_t size)
 Initialize a pipe and allocate a buffer for it.
 
int k_pipe_put (struct k_pipe *pipe, const void *data, size_t bytes_to_write, size_t *bytes_written, size_t min_xfer, k_timeout_t timeout)
 Write data to a pipe.
 
int k_pipe_get (struct k_pipe *pipe, void *data, size_t bytes_to_read, size_t *bytes_read, size_t min_xfer, k_timeout_t timeout)
 Read data from a pipe.
 
size_t k_pipe_read_avail (struct k_pipe *pipe)
 Query the number of bytes that may be read from pipe.
 
size_t k_pipe_write_avail (struct k_pipe *pipe)
 Query the number of bytes that may be written to pipe.
 
void k_pipe_flush (struct k_pipe *pipe)
 Flush the pipe of write data.
 
void k_pipe_buffer_flush (struct k_pipe *pipe)
 Flush the pipe's internal buffer.
 

Detailed Description

Macro Definition Documentation

◆ K_PIPE_DEFINE

#define K_PIPE_DEFINE (   name,
  pipe_buffer_size,
  pipe_align 
)

#include <zephyr/kernel.h>

Value:
static unsigned char __noinit __aligned(pipe_align) \
_k_pipe_buf_##name[pipe_buffer_size]; \
STRUCT_SECTION_ITERABLE(k_pipe, name) = \
Z_PIPE_INITIALIZER(name, _k_pipe_buf_##name, pipe_buffer_size)
Pipe Structure.
Definition: kernel.h:4870

Statically define and initialize a pipe.

The pipe can be accessed outside the module where it is defined using:

extern struct k_pipe <name>;
Parameters
nameName of the pipe.
pipe_buffer_sizeSize of the pipe's ring buffer (in bytes), or zero if no ring buffer is used.
pipe_alignAlignment of the pipe's ring buffer (power of 2).

Function Documentation

◆ k_pipe_alloc_init()

int k_pipe_alloc_init ( struct k_pipe pipe,
size_t  size 
)

#include <zephyr/kernel.h>

Initialize a pipe and allocate a buffer for it.

Storage for the buffer region will be allocated from the calling thread's resource pool. This memory will be released if k_pipe_cleanup() is called, or userspace is enabled and the pipe object loses all references to it.

This function should only be called on uninitialized pipe objects.

Parameters
pipeAddress of the pipe.
sizeSize of the pipe's ring buffer (in bytes), or zero if no ring buffer is used.
Return values
0on success
-ENOMEMif memory couldn't be allocated

◆ k_pipe_buffer_flush()

void k_pipe_buffer_flush ( struct k_pipe pipe)

#include <zephyr/kernel.h>

Flush the pipe's internal buffer.

This routine flushes the pipe's internal buffer. This is equivalent to reading up to N bytes from the pipe (where N is the size of the pipe's buffer) into a temporary buffer and then discarding that buffer. If there were writers previously pending, then some may unpend as they try to fill up the pipe's emptied buffer.

Parameters
pipeAddress of the pipe.

◆ k_pipe_cleanup()

int k_pipe_cleanup ( struct k_pipe pipe)

#include <zephyr/kernel.h>

Release a pipe's allocated buffer.

If a pipe object was given a dynamically allocated buffer via k_pipe_alloc_init(), this will free it. This function does nothing if the buffer wasn't dynamically allocated.

Parameters
pipeAddress of the pipe.
Return values
0on success
-EAGAINnothing to cleanup

◆ k_pipe_flush()

void k_pipe_flush ( struct k_pipe pipe)

#include <zephyr/kernel.h>

Flush the pipe of write data.

This routine flushes the pipe. Flushing the pipe is equivalent to reading both all the data in the pipe's buffer and all the data waiting to go into that pipe into a large temporary buffer and discarding the buffer. Any writers that were previously pended become unpended.

Parameters
pipeAddress of the pipe.

◆ k_pipe_get()

int k_pipe_get ( struct k_pipe pipe,
void *  data,
size_t  bytes_to_read,
size_t bytes_read,
size_t  min_xfer,
k_timeout_t  timeout 
)

#include <zephyr/kernel.h>

Read data from a pipe.

This routine reads up to bytes_to_read bytes of data from pipe.

Parameters
pipeAddress of the pipe.
dataAddress to place the data read from pipe.
bytes_to_readMaximum number of data bytes to read.
bytes_readAddress of area to hold the number of bytes read.
min_xferMinimum number of data bytes to read.
timeoutWaiting period to wait for the data to be read, or one of the special values K_NO_WAIT and K_FOREVER.
Return values
0At least min_xfer bytes of data were read.
-EINVALinvalid parameters supplied
-EIOReturned without waiting; zero data bytes were read.
-EAGAINWaiting period timed out; between zero and min_xfer minus one data bytes were read.

◆ k_pipe_init()

void k_pipe_init ( struct k_pipe pipe,
unsigned char *  buffer,
size_t  size 
)

#include <zephyr/kernel.h>

Initialize a pipe.

This routine initializes a pipe object, prior to its first use.

Parameters
pipeAddress of the pipe.
bufferAddress of the pipe's ring buffer, or NULL if no ring buffer is used.
sizeSize of the pipe's ring buffer (in bytes), or zero if no ring buffer is used.

◆ k_pipe_put()

int k_pipe_put ( struct k_pipe pipe,
const void *  data,
size_t  bytes_to_write,
size_t bytes_written,
size_t  min_xfer,
k_timeout_t  timeout 
)

#include <zephyr/kernel.h>

Write data to a pipe.

This routine writes up to bytes_to_write bytes of data to pipe.

Parameters
pipeAddress of the pipe.
dataAddress of data to write.
bytes_to_writeSize of data (in bytes).
bytes_writtenAddress of area to hold the number of bytes written.
min_xferMinimum number of bytes to write.
timeoutWaiting period to wait for the data to be written, or one of the special values K_NO_WAIT and K_FOREVER.
Return values
0At least min_xfer bytes of data were written.
-EIOReturned without waiting; zero data bytes were written.
-EAGAINWaiting period timed out; between zero and min_xfer minus one data bytes were written.

◆ k_pipe_read_avail()

size_t k_pipe_read_avail ( struct k_pipe pipe)

#include <zephyr/kernel.h>

Query the number of bytes that may be read from pipe.

Parameters
pipeAddress of the pipe.
Return values
anumber n such that 0 <= n <= k_pipe::size; the result is zero for unbuffered pipes.

◆ k_pipe_write_avail()

size_t k_pipe_write_avail ( struct k_pipe pipe)

#include <zephyr/kernel.h>

Query the number of bytes that may be written to pipe.

Parameters
pipeAddress of the pipe.
Return values
anumber n such that 0 <= n <= k_pipe::size; the result is zero for unbuffered pipes.