michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: document pipe API in header file

Browse source 
Change-Id: Ibac21c7fef5ee3a7313025aa91980cad170e5a0f
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
Anas Nashif 2015-08-19 12:10:36 -04:00
commit d62d1ac256
2 changed files with 146 additions and 36 deletions
Download patch file Download diff file Expand all files Collapse all files

157
include/microkernel/pipe.h
View file

@ -37,51 +37,162 @@
extern "C" {
#endif
/**
* @brief Pipes
* @defgroup microkernel_pipes Microkernel Pipes
* @ingroup microkernel_services
* @{
*/
#include <sections.h>
extern int _task_pipe_put(kpipe_t id,
void *pBuffer,
int iNbrBytesToWrite,
int *piNbrBytesWritten,
K_PIPE_OPTION Option,
int32_t TimeOut);
void *pBuffer,
int iNbrBytesToWrite,
int *piNbrBytesWritten,
K_PIPE_OPTION Option,
int32_t TimeOut);
/**
* @brief Pipe write request
*
* Attempt to write data from a memory buffer area to the specified pipe.
* Fail immediately if it is not possible.
*
* @param i Pipe ID
* @param b Buffer
* @param n Number of bytes to write
* @param pn Pointer to number of bytes written
* @param o Pipe options
*
* @return RC_OK, RC_INCOMPLETE, RC_FAIL, or RC_ALIGNMENT
*/
#define task_pipe_put(i, b, n, pn, o) \
_task_pipe_put(i, b, n, pn, o, TICKS_NONE)
/**
* @brief Pipe write request with unlimited wait
*
* Attempt to write data from a memory buffer area to the
* specified pipe and wait forever until it succeeds.
*
* @param i Pipe ID
* @param b Buffer
* @param n Number of bytes to write
* @param pn Pointer to number of bytes written
* @param o Pipe options
*
* @return RC_OK, RC_INCOMPLETE or RC_ALIGNMENT
*/
#define task_pipe_put_wait(i, b, n, pn, o) \
_task_pipe_put(i, b, n, pn, o, TICKS_UNLIMITED)
#define task_pipe_put_wait_timeout(i, b, n, pn, o, t) \
_task_pipe_put(i, b, n, pn, o, t)
/**
* @brief Pipe write request with timeout
*
* Attemp to write data from a memory buffer area to the
* specified pipe with a timeout option.
*
* @param id Pipe ID
* @param b Buffer
* @param n Number of bytes to write
* @param pn Pointer to number of bytes written
* @param o Pipe options
* @param t Timeout
*
* @return RC_OK, RC_INCOMPLETE, RC_FAIL, RC_TIME, or RC_ALIGNMENT
*/
#define task_pipe_put_wait_timeout(id, b, n, pn, o, t) \
_task_pipe_put(id, b, n, pn, o, t)
extern int _task_pipe_get(kpipe_t id,
void *pBuffer,
int iNbrBytesToRead,
int *piNbrBytesRead,
K_PIPE_OPTION Option,
int32_t TimeOut);
void *pBuffer,
int iNbrBytesToRead,
int *piNbrBytesRead,
K_PIPE_OPTION Option,
int32_t TimeOut);
#define task_pipe_get(i, b, n, pn, o) \
_task_pipe_get(i, b, n, pn, o, TICKS_NONE)
#define task_pipe_get_wait(i, b, n, pn, o) \
_task_pipe_get(i, b, n, pn, o, TICKS_UNLIMITED)
#define task_pipe_get_wait_timeout(i, b, n, pn, o, t) \
_task_pipe_get(i, b, n, pn, o, t)
/**
* @brief Pipe read request
*
* Attempt to read data into a memory buffer area from the
* specified pipe and fail immediately if not possible.
*
* @param id Pipe ID
* @param b Buffer
* @param n Number of bytes to read
* @param pn Pointer to number of bytes read
* @param o Pipe options
*
* @return RC_OK, RC_INCOMPLETE, RC_FAIL, or RC_ALIGNMENT
*/
#define task_pipe_get(id, b, n, pn, o) \
_task_pipe_get(id, b, n, pn, o, TICKS_NONE)
/**
* @brief Pipe read request and wait
*
* Attempt to read data into a memory buffer area from the
* specified pipe and wait forever until it succeeds.
*
* @param id Pipe ID
* @param b Buffer
* @param n Number of bytes to read
* @param pn Pointer to number of bytes read
* @param o Pipe options
*
* @return RC_OK, RC_INCOMPLETE, or RC_ALIGNMENT
*/
#define task_pipe_get_wait(id, b, n, pn, o) \
_task_pipe_get(id, b, n, pn, o, TICKS_UNLIMITED)
/**
* @brief Pipe read request
*
* This routine attempts to read data into a memory buffer area from the
* specified pipe, with a possible timeout option.
*
* @param id Pipe ID
* @param b Buffer
* @param n Number of bytes to read
* @param pn Pointer to number of bytes read
* @param o Pipe options
* @param t Timeout
*
* @return RC_OK, RC_INCOMPLETE, RC_FAIL, RC_TIME, or RC_ALIGNMENT
*/
#define task_pipe_get_wait_timeout(id, b, n, pn, o, t) \
_task_pipe_get(id, b, n, pn, o, t)
extern int _task_pipe_block_put(kpipe_t id,
struct k_block block,
int size,
ksem_t sema);
struct k_block block,
int size,
ksem_t sema);
/**
* @brief Asynchronous pipe write request
*
* This routine attempts to write data from a memory pool block to the
* specified pipe. (Note that partial transfers and timeouts are not
* supported, unlike the case for synchronous write requests.)
*
* @param id pipe ID
* @param block Block
* @param size Size of data to be transferred
* @param sema Semphore ID
*
* @return RC_OK, RC_FAIL, or RC_ALIGNMENT
*/
#define task_pipe_block_put(id, block, size, sema) \
_task_pipe_block_put(id, block, size, sema)
/**
* @internal
* @brief Initialize a pipe struct.
*
* @param size Size of pipe buffer.
* @param buffer Pointer to the buffer.
* @endinternal
*/
#define __K_PIPE_INITIALIZER(size, buffer) \
{ \
@ -103,6 +214,10 @@ extern int _task_pipe_block_put(kpipe_t id,
__section(_k_pipe_ptr, private, pipe) = \
(kpipe_t)&_k_pipe_obj_##name;
/*
* @}
*/
#ifdef __cplusplus
}
#endif

25
kernel/microkernel/k_pipe.c
View file

@ -1,5 +1,3 @@
/* pipe kernel services */
/*
* Copyright (c) 1997-2010, 2013-2014 Wind River Systems, Inc.
*
@ -30,6 +28,11 @@
* POSSIBILITY OF SUCH DAMAGE.
*/
/*
* @file
* @brief Pipe kernel services
*/
#include <micro_private.h>
#include <k_pipe_buffer.h>
#include <k_pipe_util.h>
@ -40,7 +43,6 @@ extern kpipe_t _k_pipe_ptr_start[];
extern kpipe_t _k_pipe_ptr_end[];
/**
*
* @brief Initialize kernel pipe subsystem
*
* Performs any initialization of statically-defined pipes that wasn't done
@ -48,7 +50,6 @@ extern kpipe_t _k_pipe_ptr_end[];
*
* @return N/A
*/
void _k_pipe_init(void)
{
kpipe_t *pipeId;
@ -62,7 +63,6 @@ void _k_pipe_init(void)
}
/**
*
* @brief Pipe read request
*
* This routine attempts to read data into a memory buffer area from the
@ -70,10 +70,9 @@ void _k_pipe_init(void)
*
* @return RC_OK, RC_INCOMPLETE, RC_FAIL, RC_TIME, or RC_ALIGNMENT
*/
int _task_pipe_get(kpipe_t Id, void *pBuffer,
int iNbrBytesToRead, int *piNbrBytesRead,
K_PIPE_OPTION Option, int32_t TimeOut)
int iNbrBytesToRead, int *piNbrBytesRead,
K_PIPE_OPTION Option, int32_t TimeOut)
{
struct k_args A;
@ -114,7 +113,6 @@ int _task_pipe_get(kpipe_t Id, void *pBuffer,
}
/**
*
* @brief Pipe write request
*
* This routine attempts to write data from a memory buffer area to the
@ -122,10 +120,9 @@ int _task_pipe_get(kpipe_t Id, void *pBuffer,
*
* @return RC_OK, RC_INCOMPLETE, RC_FAIL, RC_TIME, or RC_ALIGNMENT
*/
int _task_pipe_put(kpipe_t Id, void *pBuffer,
int iNbrBytesToWrite, int *piNbrBytesWritten,
K_PIPE_OPTION Option, int32_t TimeOut)
int iNbrBytesToWrite, int *piNbrBytesWritten,
K_PIPE_OPTION Option, int32_t TimeOut)
{
struct k_args A;
@ -166,7 +163,6 @@ int _task_pipe_put(kpipe_t Id, void *pBuffer,
}
/**
*
* @brief Asynchronous pipe write request
*
* This routine attempts to write data from a memory pool block to the
@ -175,9 +171,8 @@ int _task_pipe_put(kpipe_t Id, void *pBuffer,
*
* @return RC_OK, RC_FAIL, or RC_ALIGNMENT
*/
int _task_pipe_block_put(kpipe_t Id, struct k_block Block,
int iReqSize2Xfer, ksem_t sema)
int iReqSize2Xfer, ksem_t sema)
{
unsigned int iSize2Xfer;
struct k_args A;