utils_char_queue.h (7042B)
1 /* 2 * This license is set out in https://raw.githubusercontent.com/Broadcom-Network-Switching-Software/OpenBCM/master/Legal/LICENSE file. 3 * 4 * Copyright 2007-2020 Broadcom Inc. All rights reserved. 5 */ 6 7 #ifndef __UTILS_CHAR_QUEUE_H_INCLUDED__ 8 /* { */ 9 #define __UTILS_CHAR_QUEUE_H_INCLUDED__ 10 11 #ifdef __cplusplus 12 extern "C" { 13 #endif 14 15 16 /* 17 * Basic_include_file. 18 */ 19 #include <soc/dpp/SAND/Utils/sand_framework.h> 20 21 /* 22 * General include file for reference design. 23 */ 24 #include <appl/diag/dpp/ref_sys.h> 25 #include <appl/diag/dpp/utils_defx.h> 26 /* 27 * INCLUDE FILES: 28 * { 29 */ 30 31 #ifdef __cplusplus 32 } 33 #endif 34 35 /* CHAR_QUEUE 36 * 37 * ------*+++++++++++++++++X----- 38 * read_ptr write_ptr 39 */ 40 41 typedef struct CHAR_QUEUE 42 { 43 /* 44 * this is the char queue/buffer - 45 * when calling 'create' - will be allocated dynamically 46 */ 47 unsigned char* 48 char_buff; 49 50 /* 51 * size of buffer 52 */ 53 unsigned long 54 char_buff_size; 55 56 /* 57 * read/write pointer 58 * the write pointer points to the next available place to write. 59 * (only if the buffer is full, the write pointer points to the last char 60 * that has been written) 61 * the read pointer points to the next char that hasn't been read already. 62 */ 63 unsigned long 64 char_buff_read_ptr; 65 unsigned long 66 char_buff_write_ptr; 67 68 /* 69 * true - if it's full, 70 * means if the write pointer is 1 before the read pointer, 71 * and the write pointer points to a char that is already written 72 */ 73 uint8 74 char_buff_full; 75 76 77 /* 78 * counts the inputs/outputs of the queue 79 */ 80 unsigned long 81 char_in_cnt; 82 unsigned long 83 char_out_cnt; 84 85 /* 86 * semaphore - to control read/write 87 */ 88 sal_mutex_t 89 char_buff_sem; 90 91 } CHAR_QUEUE; 92 93 94 95 /* 96 * functions implementing the char queue/buffer 97 */ 98 99 /***************************************************** 100 *NAME 101 * char_buff_create 102 *DATE: 05/MAY/2004 103 *FUNCTION: 104 * Allocates memory for the char buffer according to the requested size in bytes 105 * Allocates its semaphore 106 * and init all its members to 0 (by calling 'char_buff_clear') 107 *CALLING SEQUENCE: 108 * char_buff_create( 109 * int in_size, 110 * CHAR_QUEUE* out_char_q 111 * ) 112 *INPUT: 113 * SOC_SAND_DIRECT: 114 * 1. int in_size - the requested size in bytes/chars 115 * 2. CHAR_QUEUE* in_out_char_q - the char queue that we want to create. 116 * this MUST NOT be NULL. we allocate the char buffer inside it 117 * 118 *OUTPUT: 119 * SOC_SAND_DIRECT: 120 * uint8 - FALSE if (in_out_char_q == NULL) or (size <= 0) 121 * TRUE if Success 122 *REMARKS: 123 * None. 124 *SEE ALSO: 125 */ 126 uint8 127 char_buff_create( 128 int in_size, 129 CHAR_QUEUE* in_out_char_q 130 ); 131 132 133 /***************************************************** 134 *NAME 135 * char_buff_delete 136 *DATE: 05/MAY/2004 137 *FUNCTION: 138 * free the memory of the char buffer and puts NULL in it. 139 * free the semaphore 140 *CALLING SEQUENCE: 141 * char_buff_delete( 142 * CHAR_QUEUE* in_char_q 143 * ) 144 *INPUT: 145 * SOC_SAND_DIRECT: 146 * 1. CHAR_QUEUE* in_char_q - the char buffer to be freed 147 * 148 *OUTPUT: 149 * SOC_SAND_DIRECT: 150 *REMARKS: 151 * None. 152 *SEE ALSO: 153 */ 154 void 155 char_buff_delete( 156 CHAR_QUEUE* in_char_q 157 ); 158 159 160 /***************************************************** 161 *NAME 162 * char_buff_is_empty 163 *DATE: 05/MAY/2004 164 *FUNCTION: 165 * checks if the buffer is empty (read pointer = write pointer) 166 * !!! This function uses the char buffer semaphore !!! 167 *CALLING SEQUENCE: 168 * char_buff_is_empty( 169 * CHAR_QUEUE* in_char_q 170 * ) 171 *INPUT: 172 * SOC_SAND_DIRECT: 173 * CHAR_QUEUE* in_char_q - 174 * the pointer to the char queue 175 * 176 *OUTPUT: 177 * SOC_SAND_DIRECT: 178 * uint8 - TRUE if queue is empty (or if buffer is NULL) 179 * FALSE if queue not empty 180 *REMARKS: 181 * None. 182 *SEE ALSO: 183 */ 184 uint8 185 char_buff_is_empty( 186 CHAR_QUEUE* in_char_q 187 ); 188 189 190 /***************************************************** 191 *NAME 192 * char_buff_clear 193 *DATE: 05/MAY/2004 194 *FUNCTION: 195 * Clear a char queue/buffer. 196 * init to 0 all its memebers besides the size... 197 * init also the queue itself to all 0 198 * !!! This function uses the char buffer semaphore !!! 199 *CALLING SEQUENCE: 200 * char_buff_clear( 201 * CHAR_QUEUE* in_char_q 202 * ) 203 *INPUT: 204 * SOC_SAND_DIRECT: 205 * CHAR_QUEUE* in_char_q - 206 * the pointer to the char queue 207 * 208 *OUTPUT: 209 * SOC_SAND_DIRECT: 210 *REMARKS: 211 * None. 212 *SEE ALSO: 213 */ 214 void 215 char_buff_clear( 216 CHAR_QUEUE* in_char_q 217 ); 218 219 220 /***************************************************** 221 *NAME 222 * put_char 223 *DATE: 05/MAY/2004 224 *FUNCTION: 225 * Insert a char to the queue in the write pointer position 226 * If the queue is full - returns error - q full 227 * !!! This function uses the char buffer semaphore !!! 228 *CALLING SEQUENCE: 229 * put_char( 230 * CHAR_QUEUE* in_char_q, 231 * const char in_char 232 * ) 233 *INPUT: 234 * SOC_SAND_DIRECT: 235 * CHAR_QUEUE* in_char_q - 236 * the pointer to the char queue. 237 * const char in_char - the char to insert. 238 * 239 *OUTPUT: 240 * SOC_SAND_DIRECT: 241 * uint8 valid - TRUE if success / FLASE if queue is NULL or Full 242 *REMARKS: 243 * None. 244 *SEE ALSO: 245 */ 246 uint8 247 put_char( 248 CHAR_QUEUE* in_char_q, 249 const char in_char 250 ); 251 252 253 254 /***************************************************** 255 *NAME 256 * get_char 257 *DATE: 05/MAY/2004 258 *FUNCTION: 259 * read a char from the buffer (from the read pointer) 260 * !!! This function uses the char buffer semaphore !!! 261 *CALLING SEQUENCE: 262 * get_char( 263 * CHAR_QUEUE* in_char_q, 264 * char* out_char 265 * ) 266 *INPUT: 267 * SOC_SAND_DIRECT: 268 * CHAR_QUEUE* in_char_q - 269 * the pointer to the char queue. 270 * 271 *OUTPUT: 272 * SOC_SAND_DIRECT: 273 * uint8 valid - TRUE if success 274 * FLASE if queue is NULL or out_char is NULL or queue is Empty 275 * SOC_SAND_INDIRECT: 276 * char* out_char - the char that we get. MUST be allocated before. not NULL. 277 *REMARKS: 278 * None. 279 *SEE ALSO: 280 */ 281 uint8 282 get_char( 283 CHAR_QUEUE* in_char_q, 284 char* out_char 285 ); 286 287 288 289 /***************************************************** 290 *NAME 291 * char_buff_print 292 *DATE: 05/MAY/2004 293 *FUNCTION: 294 * prints the char buffer to the stdout 295 * prints all the char buffer members 296 *CALLING SEQUENCE: 297 * char_buff_print( 298 * CHAR_QUEUE* in_char_q, 299 * ) 300 *INPUT: 301 * SOC_SAND_DIRECT: 302 * CHAR_QUEUE* in_char_q - 303 * the pointer to the char queue. 304 * 305 *OUTPUT: 306 * SOC_SAND_DIRECT: 307 * SOC_SAND_INDIRECT: 308 * print the buffer to the stdout. 309 *REMARKS: 310 * This function does not protect the queue by taking the semaphore 311 * So in case of tasks entering together to the queue, it might print non expected values. 312 *SEE ALSO: 313 */ 314 void 315 char_buff_print( 316 CHAR_QUEUE* in_char_q 317 ); 318 319 320 321 /***************************************************** 322 *NAME 323 * char_buff_test 324 *DATE: 05/MAY/2004 325 *FUNCTION: 326 * for DEBUG. 327 * Creates a buffer. Creates a few tasks that each one writes & reads its own index (1-10) 328 * to the buffer. At the end - each one prints how many reads & writes 329 * it succeeded and prints the buffer. 330 * deletes the buffer 331 *CALLING SEQUENCE: 332 * char_buff_test( 333 * ) 334 *INPUT: 335 * SOC_SAND_DIRECT: 336 *OUTPUT: 337 * SOC_SAND_DIRECT: 338 * SOC_SAND_INDIRECT: 339 *REMARKS: 340 * None. 341 *SEE ALSO: 342 */ 343 void 344 char_buff_test( 345 ); 346 347 348 349 /* } __UTILS_CHAR_QUEUE_H_INCLUDED__*/ 350 #endif 351 352