2 #ifndef _IOBUFF_H
3 #define _IOBUFF_H
5 #include <stdint.h>
6 #include "libarch.h"
7 /*
8 * I/O buffer management API
9 */
11 enum {
12 IOBUFF_NOERR = 0,
13 IOBUFF_ERR_HANDLE,
14 IOBUFF_ERR_MEMORY,
15 IOBUFF_ERR_BAD_PARAMS,
16 IOBUFF_ERR_UNDERFLOW,
17 IOBUFF_ERR_OVERFLOW
18 };
20 enum {
21 IOBUff_NO_SYNC = 0,
22 IOBUff_READ_SYNC,
23 IOBUFF_WRITE_SYNC,
24 IOBUFF_RW_SYNC
25 };
27 // I/O memory pool configuration parameters
28 typedef struct ioBuffParams {
29 void *base; /* base address of I/O memory provided by the framework */
30 uint_fast32_t size; /* size in MAU's (bytes) of I/O memory */
31 int_fast16_t sync; /* sync type: IOBUff_READ_SYNC, WRITE_SYNC, NO_SYNC, RW_SYNC */
32 uint_fast32_t nominalDelay; /* nominal delay as # of MAU's between write and read */
33 } ioBuffParams_t;
35 typedef void * ioBuffHandle_t;
37 typedef struct ioBuffInfo_s {
38 void *base;
39 void *read;
40 void *write;
41 uint_fast32_t size;
42 } ioBuffInfo_t;
44 /**
45 * @brief ioBuffNumAlloc
46 * Returns the maximum number of memory allocation requests that ioBuffAlloc()
47 * requires.
48 */
49 int ioBuffNumAlloc(void);
51 /**
52 * @brief ioBuffAlloc
53 * Returns a table of memory records that describe the size, alignment, type
54 * and memory space of all buffers required by this component.
55 */
56 int ioBuffAlloc(lib_mem_rec_t *mem_tbl);
58 /**
59 * @brief ioBuffCreate
60 * Based on the provided memory blocks, this function creates an I/O BUFF
61 * instance and returns a handle. This handle points to the memory block
62 * that contains the instance.
63 */
64 int ioBuffCreate(ioBuffHandle_t *handle, const lib_mem_rec_t *mem_tbl);
66 /**
67 * @brief ioBuffInit
68 * Initializes the I/O buffer management instance.
69 */
70 int ioBuffInit (ioBuffHandle_t handle, const ioBuffParams_t *params);
72 /**
73 * @brief ioBuffGetReadPtrs
74 * Provides pointers to read a given size of data from the I/O buffer.
75 * - If I/O buffer wrapps around, two pointers will be provided, each with
76 * a corresponding read size.
77 * - If I/O buffer does not wrapp around, one pointer and the corresponding
78 * size will be provided. The size will be equal to the input mem_size.
79 * The second pointer will be NULL and the corresponding size will be
80 * zero.
81 *
82 * @param[in] handle
83 * @param[in] mem_size size of data to be read
84 * @param[out] rdptr1 read pointer 1
85 * @param[out] size1 read size corresponding to pointer 1
86 * @param[out] rdptr2 read pointer 2
87 * @param[out] size2 read size corresponding to pointer 2
88 *
89 */
90 int ioBuffGetReadPtrs(ioBuffHandle_t handle, size_t mem_size,
91 void **rdptr1, size_t *size1,
92 void **rdptr2, size_t *size2);
94 /**
95 * @brief ioBuffGetWritePtrs
96 * Provides pointers to write a given size of data to the I/O buffer.
97 * - If I/O buffer wrapps around, two pointers will be provided, each with
98 * a corresponding write size.
99 * - If I/O buffer does not wrapp around, one pointer and the corresponding
100 * size will be provided. The size will be equal to the input mem_size.
101 * The second pointer will be NULL and the corresponding size will be
102 * zero.
103 *
104 * @param[in] handle
105 * @param[in] mem_size size of data to be written to the I/O buffer
106 * @param[out] wrptr1 write pointer 1
107 * @param[out] size1 write size corresponding to pointer 1
108 * @param[out] wrptr2 write pointer 2
109 * @param[out] size2 write size corresponding to pointer 2
110 *
111 */
112 int ioBuffGetWritePtrs(ioBuffHandle_t handle, size_t mem_size,
113 void **wrptr1, size_t *size1,
114 void **wrptr2, size_t *size2);
116 /**
117 * @brief ioBuffReadComplete
118 * Marks a portion of the I/O buffer as read complete so that the data in it
119 * can be overwritten now.
120 *
121 * @param[in] handle
122 * @param[in] start start address of the read-completed portion
123 * @param[in] size size of the read-completed portion
124 *
125 * @remark If two buffers, then size should be sum of two sizes.....
126 */
127 int ioBuffReadComplete(ioBuffHandle_t handle, void *start, size_t size);
129 /**
130 * @brief ioBuffWriteComplete
131 * Marks a portion of the I/O buffer as write complete so that the data in it
132 * can be read now.
133 *
134 * @param[in] handle
135 * @param[in] start start address of the write-completed portion
136 * @param[in] size size of the write-completed portion
137 *
138 */
139 int ioBuffWriteComplete(ioBuffHandle_t handle, void *start, size_t size);
141 int ioBuffGetInfo(ioBuffHandle_t handle, ioBuffInfo_t *info);
143 void * ioBuffWrapPointer(ioBuffHandle_t handle, void * pPtr);
145 int ioBuffAdjustDelay(ioBuffHandle_t handle, size_t delay);
147 #endif