Skip to content

Commit

Permalink
kernel: Rewrite k_pipe_* API
Browse files Browse the repository at this point in the history 
The `k_pipe_*` API has been reworked to provide a more consistent and
intuitive interface. The new API aims to provide a simple to use byte
stream interface that is more in line with the POSIX pipe API.
The previous API has been deprecated and will be removed in a future
release.

Signed-off-by: Måns Ansgariusson <[email protected]>
  • Loading branch information
@Mattemagikern
Mattemagikern committed Dec 20, 2024
1 parent 088afe9 commit 17a7e7e
Show file tree
Hide file tree
Showing 4 changed files with 333 additions and 10 deletions.
137 changes: 136 additions & 1 deletion include/zephyr/kernel.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4971,6 +4971,7 @@ void k_mbox_data_get(struct k_mbox_msg *rx_msg, void *buffer);
* @{
*/

#ifdef CONFIG_PIPES
/** Pipe Structure */
struct k_pipe {
unsigned char *buffer; /**< Pipe buffer: may be NULL */
Expand Down Expand Up @@ -5041,6 +5042,7 @@ struct k_pipe {
Z_PIPE_INITIALIZER(name, _k_pipe_buf_##name, pipe_buffer_size)

/**
* @deprecated
* @brief Initialize a pipe.
*
* This routine initializes a pipe object, prior to its first use.
Expand All @@ -5054,6 +5056,7 @@ struct k_pipe {
void k_pipe_init(struct k_pipe *pipe, unsigned char *buffer, size_t size);

/**
* @deprecated
* @brief Release a pipe's allocated buffer
*
* If a pipe object was given a dynamically allocated buffer via
Expand All @@ -5067,6 +5070,7 @@ void k_pipe_init(struct k_pipe *pipe, unsigned char *buffer, size_t size);
int k_pipe_cleanup(struct k_pipe *pipe);

/**
* @deprecated
* @brief Initialize a pipe and allocate a buffer for it
*
* Storage for the buffer region will be allocated from the calling thread's
Expand All @@ -5084,6 +5088,7 @@ int k_pipe_cleanup(struct k_pipe *pipe);
__syscall int k_pipe_alloc_init(struct k_pipe *pipe, size_t size);

/**
* @deprecated
* @brief Write data to a pipe.
*
* This routine writes up to @a bytes_to_write bytes of data to @a pipe.
Expand All @@ -5106,6 +5111,7 @@ __syscall int k_pipe_put(struct k_pipe *pipe, const void *data,
size_t min_xfer, k_timeout_t timeout);

/**
* @deprecated
* @brief Read data from a pipe.
*
* This routine reads up to @a bytes_to_read bytes of data from @a pipe.
Expand All @@ -5129,6 +5135,7 @@ __syscall int k_pipe_get(struct k_pipe *pipe, void *data,
size_t min_xfer, k_timeout_t timeout);

/**
* @deprecated
* @brief Query the number of bytes that may be read from @a pipe.
*
* @param pipe Address of the pipe.
Expand All @@ -5139,6 +5146,7 @@ __syscall int k_pipe_get(struct k_pipe *pipe, void *data,
__syscall size_t k_pipe_read_avail(struct k_pipe *pipe);

/**
* @deprecated
* @brief Query the number of bytes that may be written to @a pipe
*
* @param pipe Address of the pipe.
Expand All @@ -5149,6 +5157,7 @@ __syscall size_t k_pipe_read_avail(struct k_pipe *pipe);
__syscall size_t k_pipe_write_avail(struct k_pipe *pipe);

/**
* @deprecated
* @brief Flush the pipe of write data
*
* This routine flushes the pipe. Flushing the pipe is equivalent to reading
Expand All @@ -5161,6 +5170,7 @@ __syscall size_t k_pipe_write_avail(struct k_pipe *pipe);
__syscall void k_pipe_flush(struct k_pipe *pipe);

/**
* @deprecated
* @brief Flush the pipe's internal buffer
*
* This routine flushes the pipe's internal buffer. This is equivalent to
Expand All @@ -5175,10 +5185,135 @@ __syscall void k_pipe_buffer_flush(struct k_pipe *pipe);

/** @} */

#else /* CONFIG_PIPES */

enum pipe_flags {
PIPE_FLAG_OPEN = BIT(0),
PIPE_FLAG_RESET = BIT(1),
PIPE_FLAG_FULL = BIT(2),
};

struct k_pipe {
size_t head;
size_t tail;
size_t waiting;
size_t buffer_size;
uint8_t *buffer;

struct k_spinlock lock;
_wait_q_t data;
_wait_q_t space;
uint8_t flags;
};

#define Z_PIPE_INITIALIZER(obj, pipe_buffer, pipe_buffer_size) \
{ \
.flags = 0, \
.head = 0, \
.tail = 0, \
.count = 0, \
.lock = {}, \
.buffer = pipe_buffer, \
.buffer_size = pipe_buffer_size, \
.data = Z_WAIT_Q_INIT(&obj.data), \
.space = Z_WAIT_Q_INIT(&obj.space), \
}

/**
* @cond INTERNAL_HIDDEN
* INTERNAL_HIDDEN @endcond
*/

/**
* @brief Statically define and initialize a pipe.
*
* The pipe can be accessed outside the module where it is defined using:
*
* @code extern struct k_pipe <name>; @endcode
*
* @param name Name of the pipe.
* @param pipe_buffer_size Size of the pipe's ring buffer (in bytes).
* @param pipe_align Alignment of the pipe's ring buffer (power of 2).
*
*/
#define K_PIPE_DEFINE(name, pipe_buffer_size, pipe_align) \
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)

/**
* @brief initialize a pipe
*
* This routine initializes a pipe object, prior to its first use.
*
* @param pipe Address of the pipe.
* @param buffer Address of the pipe's buffer.
* @param buffer_size Size of the pipe's buffer.
*/
__syscall void k_pipe_init(struct k_pipe *pipe, uint8_t *buffer, size_t buffer_size);

/**
* @brief Write data to a pipe
*
* This routine writes up to @a len bytes of data to @a pipe.
* If the pipe is full, the routine will block until the data can be written or the timeout expires.
*
* @param pipe Address of the pipe.
* @param data Address of data to write.
* @param len Size of data (in bytes).
* @param timeout Waiting period to wait for the data to be written.
*
* @retval 0 on success
* @retval -EAGAIN if the data could not be written before the timeout expired
* @retval -ECANCELED if the write was interrupted by eg. k_pipe_flush(..)
* @retval -EPIPE if the pipe was closed
*/
__syscall int k_pipe_write(struct k_pipe *pipe, const uint8_t *data, size_t len,
k_timeout_t timeout);

/**
* @brief Read data from a pipe
* This routine reads up to @a len bytes of data from @a pipe.
* If the pipe is empty, the routine will block until the data can be read or the timeout expires.
*
* @param pipe Address of the pipe.
* @param data Address to place the data read from pipe.
* @param len Requested number of bytes to read.
* @param timeout Waiting period to wait for the data to be read.
*
* @retval number of bytes read on success
* @retval -EAGAIN if the data could not be read before the timeout expired
* @retval -ECANCELED if the read was interrupted by eg. k_pipe_flush(..)
* @retval -EPIPE if the pipe was closed
*/
__syscall int k_pipe_read(struct k_pipe *pipe, uint8_t *data, size_t len,
k_timeout_t timeout);

/**
* @brief Reset the pipe
*
* This routine resets the internal state of the pipe and any
* writers or readers that were previously pended become unpended.
*
* @param pipe Address of the pipe.
*/
__syscall int k_pipe_reset(struct k_pipe *pipe);

/**
* @brief Close a pipe
*
* This routine closes a pipe. Any threads that were blocked on the pipe
* will be unblocked and receive an error code.
*
* @param pipe Address of the pipe.
* @retval 0 on success
*/
__syscall int k_pipe_close(struct k_pipe *pipe);
#endif /* CONFIG_PIPES */

/**
* @cond INTERNAL_HIDDEN
*/
struct k_mem_slab_info {
uint32_t num_blocks;
size_t block_size;
Expand Down
4 changes: 4 additions & 0 deletions kernel/CMakeLists.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,10 @@ list(APPEND kernel_files
thread.c
sched.c
)
# FIXME: Once the prior pipe implementation is removed, this should be included in the above list
if(NOT CONFIG_PIPES)
list(APPEND kernel_files pipe.c)
endif() # NOT CONFIG_PIPES
if(CONFIG_SMP)
list(APPEND kernel_files
smp.c
Expand Down
Loading

0 comments on commit 17a7e7e

Please sign in to comment.