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)

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

name	Name of the pipe.
pipe_buffer_size	Size of the pipe's ring buffer (in bytes), or zero if no ring buffer is used.
pipe_align	Alignment 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

pipe	Address of the pipe.
size	Size of the pipe's ring buffer (in bytes), or zero if no ring buffer is used.

Return values

0	on success
-ENOMEM	if 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

pipe	Address 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

pipe	Address of the pipe.

Return values

0	on success
-EAGAIN	nothing 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

pipe	Address 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

pipe	Address of the pipe.
data	Address to place the data read from pipe.
bytes_to_read	Maximum number of data bytes to read.
bytes_read	Address of area to hold the number of bytes read.
min_xfer	Minimum number of data bytes to read.
timeout	Waiting period to wait for the data to be read, or one of the special values K_NO_WAIT and K_FOREVER.

Return values

0	At least min_xfer bytes of data were read.
-EINVAL	invalid parameters supplied
-EIO	Returned without waiting; zero data bytes were read.
-EAGAIN	Waiting 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

pipe	Address of the pipe.
buffer	Address of the pipe's ring buffer, or NULL if no ring buffer is used.
size	Size 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

pipe	Address of the pipe.
data	Address of data to write.
bytes_to_write	Size of data (in bytes).
bytes_written	Address of area to hold the number of bytes written.
min_xfer	Minimum number of bytes to write.
timeout	Waiting period to wait for the data to be written, or one of the special values K_NO_WAIT and K_FOREVER.

Return values

0	At least min_xfer bytes of data were written.
-EIO	Returned without waiting; zero data bytes were written.
-EAGAIN	Waiting 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

pipe	Address of the pipe.

Return values

a	number 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

pipe	Address of the pipe.

Return values

a	number n such that 0 <= n <= k_pipe::size; the result is zero for unbuffered pipes.