]>
Commit | Line | Data |
---|---|---|
ba94a1bb WD |
1 | /** |
2 | * @file IxQMgr.h | |
3 | * | |
4 | * @date 30-Oct-2001 | |
5 | * | |
6 | * @brief This file contains the public API of IxQMgr component. | |
7 | * | |
8 | * Some functions contained in this module are inline to achieve better | |
9 | * data-path performance. For this to work, the function definitions are | |
10 | * contained in this header file. The "normal" use of inline functions | |
11 | * is to use the inline functions in the module in which they are | |
12 | * defined. In this case these inline functions are used in external | |
13 | * modules and therefore the use of "inline extern". What this means | |
14 | * is as follows: if a function foo is declared as "inline extern" this | |
15 | * definition is only used for inlining, in no case is the function | |
16 | * compiled on its own. If the compiler cannot inline the function it | |
17 | * becomes an external reference. Therefore in IxQMgrQAccess.c all | |
18 | * inline functions are defined without the "inline extern" specifier | |
19 | * and so define the external references. In all other source files | |
20 | * including this header file, these funtions are defined as "inline | |
21 | * extern". | |
22 | * | |
23 | * | |
24 | * @par | |
25 | * IXP400 SW Release version 2.0 | |
26 | * | |
27 | * -- Copyright Notice -- | |
28 | * | |
29 | * @par | |
30 | * Copyright 2001-2005, Intel Corporation. | |
31 | * All rights reserved. | |
32 | * | |
33 | * @par | |
34 | * Redistribution and use in source and binary forms, with or without | |
35 | * modification, are permitted provided that the following conditions | |
36 | * are met: | |
37 | * 1. Redistributions of source code must retain the above copyright | |
38 | * notice, this list of conditions and the following disclaimer. | |
39 | * 2. Redistributions in binary form must reproduce the above copyright | |
40 | * notice, this list of conditions and the following disclaimer in the | |
41 | * documentation and/or other materials provided with the distribution. | |
42 | * 3. Neither the name of the Intel Corporation nor the names of its contributors | |
43 | * may be used to endorse or promote products derived from this software | |
44 | * without specific prior written permission. | |
45 | * | |
46 | * @par | |
47 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' | |
48 | * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
49 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
50 | * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE | |
51 | * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
52 | * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
53 | * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
54 | * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
55 | * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
56 | * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
57 | * SUCH DAMAGE. | |
58 | * | |
59 | * @par | |
60 | * -- End of Copyright Notice -- | |
61 | */ | |
62 | ||
63 | /* ------------------------------------------------------ | |
64 | Doxygen group definitions | |
65 | ------------------------------------------------------ */ | |
66 | /** | |
67 | * @defgroup IxQMgrAPI IXP400 Queue Manager (IxQMgr) API | |
68 | * | |
69 | * @brief The public API for the IXP400 QMgr component. | |
70 | * | |
71 | * IxQMgr is a low level interface to the AHB Queue Manager | |
72 | * | |
73 | * @{ | |
74 | */ | |
75 | ||
76 | #ifndef IXQMGR_H | |
77 | #define IXQMGR_H | |
78 | ||
79 | /* | |
80 | * User defined include files | |
81 | */ | |
82 | ||
83 | #include "IxOsal.h" | |
84 | ||
85 | /* | |
86 | * Define QMgr's IoMem macros, in DC mode if in LE | |
87 | * regular if in BE. (Note: For Linux LSP gold release | |
88 | * may need to adjust mode. | |
89 | */ | |
90 | #if defined (__BIG_ENDIAN) | |
91 | ||
92 | #define IX_QMGR_INLINE_READ_LONG IX_OSAL_READ_LONG_BE | |
93 | #define IX_QMGR_INLINE_WRITE_LONG IX_OSAL_WRITE_LONG_BE | |
94 | ||
95 | #else | |
96 | ||
97 | #define IX_QMGR_INLINE_READ_LONG IX_OSAL_READ_LONG_LE_DC | |
98 | #define IX_QMGR_INLINE_WRITE_LONG IX_OSAL_WRITE_LONG_LE_DC | |
99 | ||
100 | #endif | |
101 | ||
102 | /* | |
103 | * #defines and macros | |
104 | */ | |
105 | ||
106 | /** | |
107 | * | |
108 | * @ingroup IxQMgrAPI | |
109 | * | |
110 | * @def IX_QMGR_INLINE | |
111 | * | |
112 | * @brief Inline definition, for inlining of Queue Access functions on API | |
113 | * | |
114 | * Please read the header information in this file for more details on the | |
115 | * use of function inlining in this component. | |
116 | * | |
117 | */ | |
118 | ||
119 | #ifndef __wince | |
120 | ||
121 | #ifdef IXQMGRQACCESS_C | |
122 | /* If IXQMGRQACCESS_C is set then the IxQmgrQAccess.c is including this file | |
123 | and must instantiate a concrete definition for each inlineable API function | |
124 | whether or not that function actually gets inlined. */ | |
125 | # ifdef NO_INLINE_APIS | |
126 | # undef NO_INLINE_APIS | |
127 | # endif | |
128 | # define IX_QMGR_INLINE /* Empty Define */ | |
129 | #else | |
130 | # ifndef NO_INLINE_APIS | |
131 | # define IX_QMGR_INLINE IX_OSAL_INLINE_EXTERN | |
132 | # else | |
133 | # define IX_QMGR_INLINE /* Empty Define */ | |
134 | # endif | |
135 | #endif | |
136 | ||
137 | #else /* ndef __wince */ | |
138 | ||
139 | # ifndef NO_INLINE_APIS | |
140 | # define NO_INLINE_APIS | |
141 | # endif | |
142 | # define IX_QMGR_INLINE | |
143 | ||
144 | #endif | |
145 | ||
146 | ||
147 | /** | |
148 | * | |
149 | * @ingroup IxQMgrAPI | |
150 | * | |
151 | * @def IX_QMGR_MAX_NUM_QUEUES | |
152 | * | |
153 | * @brief Number of queues supported by the AQM. | |
154 | * | |
155 | * This constant is used to indicate the number of AQM queues | |
156 | * | |
157 | */ | |
158 | #define IX_QMGR_MAX_NUM_QUEUES 64 | |
159 | ||
160 | /** | |
161 | * | |
162 | * @ingroup IxQMgrAPI | |
163 | * | |
164 | * @def IX_QMGR_MIN_QID | |
165 | * | |
166 | * @brief Minimum queue identifier. | |
167 | * | |
168 | * This constant is used to indicate the smallest queue identifier | |
169 | * | |
170 | */ | |
171 | #define IX_QMGR_MIN_QID IX_QMGR_QUEUE_0 | |
172 | ||
173 | /** | |
174 | * | |
175 | * @ingroup IxQMgrAPI | |
176 | * | |
177 | * @def IX_QMGR_MAX_QID | |
178 | * | |
179 | * @brief Maximum queue identifier. | |
180 | * | |
181 | * This constant is used to indicate the largest queue identifier | |
182 | * | |
183 | */ | |
184 | #define IX_QMGR_MAX_QID IX_QMGR_QUEUE_63 | |
185 | ||
186 | /** | |
187 | * | |
188 | * @ingroup IxQMgrAPI | |
189 | * | |
190 | * @def IX_QMGR_MIN_QUEUPP_QID | |
191 | * | |
192 | * @brief Minimum queue identifier for reduced functionality queues. | |
193 | * | |
194 | * This constant is used to indicate Minimum queue identifier for reduced | |
195 | * functionality queues | |
196 | * | |
197 | */ | |
198 | #define IX_QMGR_MIN_QUEUPP_QID 32 | |
199 | ||
200 | /** | |
201 | * | |
202 | * @ingroup IxQMgrAPI | |
203 | * | |
204 | * @def IX_QMGR_MAX_QNAME_LEN | |
205 | * | |
206 | * @brief Maximum queue name length. | |
207 | * | |
208 | * This constant is used to indicate the maximum null terminated string length | |
209 | * (excluding '\0') for a queue name | |
210 | * | |
211 | */ | |
212 | #define IX_QMGR_MAX_QNAME_LEN 16 | |
213 | ||
214 | /** | |
215 | * | |
216 | * @ingroup IxQMgrAPI | |
217 | * | |
218 | * @def IX_QMGR_WARNING | |
219 | * | |
220 | * @brief Warning return code. | |
221 | * | |
222 | * Execution complete, but there is a special case to handle | |
223 | * | |
224 | */ | |
225 | #define IX_QMGR_WARNING 2 | |
226 | ||
227 | /** | |
228 | * | |
229 | * @ingroup IxQMgrAPI | |
230 | * | |
231 | * @def IX_QMGR_PARAMETER_ERROR | |
232 | * | |
233 | * @brief Parameter error return code (NULL pointer etc..). | |
234 | * | |
235 | * parameter error out of range/invalid | |
236 | * | |
237 | */ | |
238 | #define IX_QMGR_PARAMETER_ERROR 3 | |
239 | ||
240 | /** | |
241 | * | |
242 | * @ingroup IxQMgrAPI | |
243 | * | |
244 | * @def IX_QMGR_INVALID_Q_ENTRY_SIZE | |
245 | * | |
246 | * @brief Invalid entry size return code. | |
247 | * | |
248 | * Invalid queue entry size for a queue read/write | |
249 | * | |
250 | */ | |
251 | #define IX_QMGR_INVALID_Q_ENTRY_SIZE 4 | |
252 | ||
253 | /** | |
254 | * | |
255 | * @ingroup IxQMgrAPI | |
256 | * | |
257 | * @def IX_QMGR_INVALID_Q_ID | |
258 | * | |
259 | * @brief Invalid queue identifier return code. | |
260 | * | |
261 | * Invalid queue id, not in range 0-63 | |
262 | * | |
263 | */ | |
264 | #define IX_QMGR_INVALID_Q_ID 5 | |
265 | ||
266 | /** | |
267 | * | |
268 | * @ingroup IxQMgrAPI | |
269 | * | |
270 | * @def IX_QMGR_INVALID_CB_ID | |
271 | * | |
272 | * @brief Invalid callback identifier return code. | |
273 | * | |
274 | * Invalid callback id | |
275 | */ | |
276 | #define IX_QMGR_INVALID_CB_ID 6 | |
277 | ||
278 | /** | |
279 | * | |
280 | * @ingroup IxQMgrAPI | |
281 | * | |
282 | * @def IX_QMGR_CB_ALREADY_SET | |
283 | * | |
284 | * @brief Callback set error return code. | |
285 | * | |
286 | * The specified callback has already been for this queue | |
287 | * | |
288 | */ | |
289 | #define IX_QMGR_CB_ALREADY_SET 7 | |
290 | ||
291 | /** | |
292 | * | |
293 | * @ingroup IxQMgrAPI | |
294 | * | |
295 | * @def IX_QMGR_NO_AVAILABLE_SRAM | |
296 | * | |
297 | * @brief Sram consumed return code. | |
298 | * | |
299 | * All AQM Sram is consumed by queue configuration | |
300 | * | |
301 | */ | |
302 | #define IX_QMGR_NO_AVAILABLE_SRAM 8 | |
303 | ||
304 | /** | |
305 | * | |
306 | * @ingroup IxQMgrAPI | |
307 | * | |
308 | * @def IX_QMGR_INVALID_INT_SOURCE_ID | |
309 | * | |
310 | * @brief Invalid queue interrupt source identifier return code. | |
311 | * | |
312 | * Invalid queue interrupt source given for notification enable | |
313 | */ | |
314 | #define IX_QMGR_INVALID_INT_SOURCE_ID 9 | |
315 | ||
316 | /** | |
317 | * | |
318 | * @ingroup IxQMgrAPI | |
319 | * | |
320 | * @def IX_QMGR_INVALID_QSIZE | |
321 | * | |
322 | * @brief Invalid queue size error code. | |
323 | * | |
324 | * Invalid queue size not one of 16,32, 64, 128 | |
325 | * | |
326 | * | |
327 | */ | |
328 | #define IX_QMGR_INVALID_QSIZE 10 | |
329 | ||
330 | /** | |
331 | * | |
332 | * @ingroup IxQMgrAPI | |
333 | * | |
334 | * @def IX_QMGR_INVALID_Q_WM | |
335 | * | |
336 | * @brief Invalid queue watermark return code. | |
337 | * | |
338 | * Invalid queue watermark given for watermark set | |
339 | */ | |
340 | #define IX_QMGR_INVALID_Q_WM 11 | |
341 | ||
342 | /** | |
343 | * | |
344 | * @ingroup IxQMgrAPI | |
345 | * | |
346 | * @def IX_QMGR_Q_NOT_CONFIGURED | |
347 | * | |
348 | * @brief Queue not configured return code. | |
349 | * | |
350 | * Returned to the client when a function has been called on an unconfigured | |
351 | * queue | |
352 | * | |
353 | */ | |
354 | #define IX_QMGR_Q_NOT_CONFIGURED 12 | |
355 | ||
356 | /** | |
357 | * | |
358 | * @ingroup IxQMgrAPI | |
359 | * | |
360 | * @def IX_QMGR_Q_ALREADY_CONFIGURED | |
361 | * | |
362 | * @brief Queue already configured return code. | |
363 | * | |
364 | * Returned to client to indicate that a queue has already been configured | |
365 | */ | |
366 | #define IX_QMGR_Q_ALREADY_CONFIGURED 13 | |
367 | ||
368 | /** | |
369 | * | |
370 | * @ingroup IxQMgrAPI | |
371 | * | |
372 | * @def IX_QMGR_Q_UNDERFLOW | |
373 | * | |
374 | * @brief Underflow return code. | |
375 | * | |
376 | * Underflow on a queue read has occurred | |
377 | * | |
378 | */ | |
379 | #define IX_QMGR_Q_UNDERFLOW 14 | |
380 | ||
381 | /** | |
382 | * | |
383 | * @ingroup IxQMgrAPI | |
384 | * | |
385 | * @def IX_QMGR_Q_OVERFLOW | |
386 | * | |
387 | * @brief Overflow return code. | |
388 | * | |
389 | * Overflow on a queue write has occurred | |
390 | * | |
391 | */ | |
392 | #define IX_QMGR_Q_OVERFLOW 15 | |
393 | ||
394 | /** | |
395 | * | |
396 | * @ingroup IxQMgrAPI | |
397 | * | |
398 | * @def IX_QMGR_Q_INVALID_PRIORITY | |
399 | * | |
400 | * @brief Invalid priority return code. | |
401 | * | |
402 | * Invalid priority, not one of 0,1,2 | |
403 | */ | |
404 | #define IX_QMGR_Q_INVALID_PRIORITY 16 | |
405 | ||
406 | /** | |
407 | * | |
408 | * @ingroup IxQMgrAPI | |
409 | * | |
410 | * @def IX_QMGR_ENTRY_INDEX_OUT_OF_BOUNDS | |
411 | * | |
412 | * @brief Entry index out of bounds return code. | |
413 | * | |
414 | * Entry index is greater than number of entries in queue. | |
415 | */ | |
416 | #define IX_QMGR_ENTRY_INDEX_OUT_OF_BOUNDS 17 | |
417 | ||
418 | /** | |
419 | * | |
420 | * @ingroup IxQMgrAPI | |
421 | * | |
422 | * @def ixQMgrDispatcherLoopRun | |
423 | * | |
424 | * @brief Map old function name ixQMgrDispatcherLoopRun () | |
425 | * to @ref ixQMgrDispatcherLoopRunA0 (). | |
426 | * | |
427 | */ | |
428 | #define ixQMgrDispatcherLoopRun ixQMgrDispatcherLoopRunA0 | |
429 | ||
430 | ||
431 | /** | |
432 | * | |
433 | * @ingroup IxQMgrAPI | |
434 | * | |
435 | * @def IX_QMGR_QUEUE | |
436 | * | |
437 | * @brief Definition of AQM queue numbers | |
438 | * | |
439 | */ | |
440 | #define IX_QMGR_QUEUE_0 (0) /**< Queue Number 0 */ | |
441 | #define IX_QMGR_QUEUE_1 (1) /**< Queue Number 1 */ | |
442 | #define IX_QMGR_QUEUE_2 (2) /**< Queue Number 2 */ | |
443 | #define IX_QMGR_QUEUE_3 (3) /**< Queue Number 3 */ | |
444 | #define IX_QMGR_QUEUE_4 (4) /**< Queue Number 4 */ | |
445 | #define IX_QMGR_QUEUE_5 (5) /**< Queue Number 5 */ | |
446 | #define IX_QMGR_QUEUE_6 (6) /**< Queue Number 6 */ | |
447 | #define IX_QMGR_QUEUE_7 (7) /**< Queue Number 7 */ | |
448 | #define IX_QMGR_QUEUE_8 (8) /**< Queue Number 8 */ | |
449 | #define IX_QMGR_QUEUE_9 (9) /**< Queue Number 9 */ | |
450 | #define IX_QMGR_QUEUE_10 (10) /**< Queue Number 10 */ | |
451 | #define IX_QMGR_QUEUE_11 (11) /**< Queue Number 11 */ | |
452 | #define IX_QMGR_QUEUE_12 (12) /**< Queue Number 12 */ | |
453 | #define IX_QMGR_QUEUE_13 (13) /**< Queue Number 13 */ | |
454 | #define IX_QMGR_QUEUE_14 (14) /**< Queue Number 14 */ | |
455 | #define IX_QMGR_QUEUE_15 (15) /**< Queue Number 15 */ | |
456 | #define IX_QMGR_QUEUE_16 (16) /**< Queue Number 16 */ | |
457 | #define IX_QMGR_QUEUE_17 (17) /**< Queue Number 17 */ | |
458 | #define IX_QMGR_QUEUE_18 (18) /**< Queue Number 18 */ | |
459 | #define IX_QMGR_QUEUE_19 (19) /**< Queue Number 19 */ | |
460 | #define IX_QMGR_QUEUE_20 (20) /**< Queue Number 20 */ | |
461 | #define IX_QMGR_QUEUE_21 (21) /**< Queue Number 21 */ | |
462 | #define IX_QMGR_QUEUE_22 (22) /**< Queue Number 22 */ | |
463 | #define IX_QMGR_QUEUE_23 (23) /**< Queue Number 23 */ | |
464 | #define IX_QMGR_QUEUE_24 (24) /**< Queue Number 24 */ | |
465 | #define IX_QMGR_QUEUE_25 (25) /**< Queue Number 25 */ | |
466 | #define IX_QMGR_QUEUE_26 (26) /**< Queue Number 26 */ | |
467 | #define IX_QMGR_QUEUE_27 (27) /**< Queue Number 27 */ | |
468 | #define IX_QMGR_QUEUE_28 (28) /**< Queue Number 28 */ | |
469 | #define IX_QMGR_QUEUE_29 (29) /**< Queue Number 29 */ | |
470 | #define IX_QMGR_QUEUE_30 (30) /**< Queue Number 30 */ | |
471 | #define IX_QMGR_QUEUE_31 (31) /**< Queue Number 31 */ | |
472 | #define IX_QMGR_QUEUE_32 (32) /**< Queue Number 32 */ | |
473 | #define IX_QMGR_QUEUE_33 (33) /**< Queue Number 33 */ | |
474 | #define IX_QMGR_QUEUE_34 (34) /**< Queue Number 34 */ | |
475 | #define IX_QMGR_QUEUE_35 (35) /**< Queue Number 35 */ | |
476 | #define IX_QMGR_QUEUE_36 (36) /**< Queue Number 36 */ | |
477 | #define IX_QMGR_QUEUE_37 (37) /**< Queue Number 37 */ | |
478 | #define IX_QMGR_QUEUE_38 (38) /**< Queue Number 38 */ | |
479 | #define IX_QMGR_QUEUE_39 (39) /**< Queue Number 39 */ | |
480 | #define IX_QMGR_QUEUE_40 (40) /**< Queue Number 40 */ | |
481 | #define IX_QMGR_QUEUE_41 (41) /**< Queue Number 41 */ | |
482 | #define IX_QMGR_QUEUE_42 (42) /**< Queue Number 42 */ | |
483 | #define IX_QMGR_QUEUE_43 (43) /**< Queue Number 43 */ | |
484 | #define IX_QMGR_QUEUE_44 (44) /**< Queue Number 44 */ | |
485 | #define IX_QMGR_QUEUE_45 (45) /**< Queue Number 45 */ | |
486 | #define IX_QMGR_QUEUE_46 (46) /**< Queue Number 46 */ | |
487 | #define IX_QMGR_QUEUE_47 (47) /**< Queue Number 47 */ | |
488 | #define IX_QMGR_QUEUE_48 (48) /**< Queue Number 48 */ | |
489 | #define IX_QMGR_QUEUE_49 (49) /**< Queue Number 49 */ | |
490 | #define IX_QMGR_QUEUE_50 (50) /**< Queue Number 50 */ | |
491 | #define IX_QMGR_QUEUE_51 (51) /**< Queue Number 51 */ | |
492 | #define IX_QMGR_QUEUE_52 (52) /**< Queue Number 52 */ | |
493 | #define IX_QMGR_QUEUE_53 (53) /**< Queue Number 53 */ | |
494 | #define IX_QMGR_QUEUE_54 (54) /**< Queue Number 54 */ | |
495 | #define IX_QMGR_QUEUE_55 (55) /**< Queue Number 55 */ | |
496 | #define IX_QMGR_QUEUE_56 (56) /**< Queue Number 56 */ | |
497 | #define IX_QMGR_QUEUE_57 (57) /**< Queue Number 57 */ | |
498 | #define IX_QMGR_QUEUE_58 (58) /**< Queue Number 58 */ | |
499 | #define IX_QMGR_QUEUE_59 (59) /**< Queue Number 59 */ | |
500 | #define IX_QMGR_QUEUE_60 (60) /**< Queue Number 60 */ | |
501 | #define IX_QMGR_QUEUE_61 (61) /**< Queue Number 61 */ | |
502 | #define IX_QMGR_QUEUE_62 (62) /**< Queue Number 62 */ | |
503 | #define IX_QMGR_QUEUE_63 (63) /**< Queue Number 63 */ | |
504 | #define IX_QMGR_QUEUE_INVALID (64) /**< AQM Queue Number Delimiter */ | |
505 | ||
506 | ||
507 | /* | |
508 | * Typedefs | |
509 | */ | |
510 | ||
511 | /** | |
512 | * @typedef IxQMgrQId | |
513 | * | |
514 | * @ingroup IxQMgrAPI | |
515 | * | |
516 | * @brief Used in the API to identify the AQM queues. | |
517 | * | |
518 | */ | |
519 | typedef int IxQMgrQId; | |
520 | ||
521 | /** | |
522 | * @typedef IxQMgrQStatus | |
523 | * | |
524 | * @ingroup IxQMgrAPI | |
525 | * | |
526 | * @brief Queue status. | |
527 | * | |
528 | * A queues status is defined by its relative fullness or relative emptiness. | |
529 | * Each of the queues 0-31 have Nearly Empty, Nearly Full, Empty, Full, | |
530 | * Underflow and Overflow status flags. Queues 32-63 have just Nearly Empty and | |
531 | * Full status flags. | |
532 | * The flags bit positions are outlined below: | |
533 | * | |
534 | * OF - bit-5<br> | |
535 | * UF - bit-4<br> | |
536 | * F - bit-3<br> | |
537 | * NF - bit-2<br> | |
538 | * NE - bit-1<br> | |
539 | * E - bit-0<br> | |
540 | * | |
541 | */ | |
542 | typedef UINT32 IxQMgrQStatus; | |
543 | ||
544 | /** | |
545 | * @enum IxQMgrQStatusMask | |
546 | * | |
547 | * @ingroup IxQMgrAPI | |
548 | * | |
549 | * @brief Queue status mask. | |
550 | * | |
551 | * Masks for extracting the individual status flags from the IxQMgrStatus | |
552 | * word. | |
553 | * | |
554 | */ | |
555 | typedef enum | |
556 | { | |
557 | IX_QMGR_Q_STATUS_E_BIT_MASK = 0x1, | |
558 | IX_QMGR_Q_STATUS_NE_BIT_MASK = 0x2, | |
559 | IX_QMGR_Q_STATUS_NF_BIT_MASK = 0x4, | |
560 | IX_QMGR_Q_STATUS_F_BIT_MASK = 0x8, | |
561 | IX_QMGR_Q_STATUS_UF_BIT_MASK = 0x10, | |
562 | IX_QMGR_Q_STATUS_OF_BIT_MASK = 0x20 | |
563 | } IxQMgrQStatusMask; | |
564 | ||
565 | /** | |
566 | * @enum IxQMgrSourceId | |
567 | * | |
568 | * @ingroup IxQMgrAPI | |
569 | * | |
570 | * @brief Queue interrupt source select. | |
571 | * | |
572 | * This enum defines the different source conditions on a queue that result in | |
573 | * an interupt being fired by the AQM. Interrupt source is configurable for | |
574 | * queues 0-31 only. The interrupt source for queues 32-63 is hardwired to the | |
575 | * NE(Nearly Empty) status flag. | |
576 | * | |
577 | */ | |
578 | typedef enum | |
579 | { | |
580 | IX_QMGR_Q_SOURCE_ID_E = 0, /**< Queue Empty due to last read */ | |
581 | IX_QMGR_Q_SOURCE_ID_NE, /**< Queue Nearly Empty due to last read */ | |
582 | IX_QMGR_Q_SOURCE_ID_NF, /**< Queue Nearly Full due to last write */ | |
583 | IX_QMGR_Q_SOURCE_ID_F, /**< Queue Full due to last write */ | |
584 | IX_QMGR_Q_SOURCE_ID_NOT_E, /**< Queue Not Empty due to last write */ | |
585 | IX_QMGR_Q_SOURCE_ID_NOT_NE, /**< Queue Not Nearly Empty due to last write */ | |
586 | IX_QMGR_Q_SOURCE_ID_NOT_NF, /**< Queue Not Nearly Full due to last read */ | |
587 | IX_QMGR_Q_SOURCE_ID_NOT_F /**< Queue Not Full due to last read */ | |
588 | } IxQMgrSourceId; | |
589 | ||
590 | /** | |
591 | * @enum IxQMgrQEntrySizeInWords | |
592 | * | |
593 | * @ingroup IxQMgrAPI | |
594 | * | |
595 | * @brief QMgr queue entry sizes. | |
596 | * | |
597 | * The entry size of a queue specifies the size of a queues entry in words. | |
598 | * | |
599 | */ | |
600 | typedef enum | |
601 | { | |
602 | IX_QMGR_Q_ENTRY_SIZE1 = 1, /**< 1 word entry */ | |
603 | IX_QMGR_Q_ENTRY_SIZE2 = 2, /**< 2 word entry */ | |
604 | IX_QMGR_Q_ENTRY_SIZE4 = 4 /**< 4 word entry */ | |
605 | } IxQMgrQEntrySizeInWords; | |
606 | ||
607 | /** | |
608 | * @enum IxQMgrQSizeInWords | |
609 | * | |
610 | * @ingroup IxQMgrAPI | |
611 | * | |
612 | * @brief QMgr queue sizes. | |
613 | * | |
614 | * These values define the allowed queue sizes for AQM queue. The sizes are | |
615 | * specified in words. | |
616 | * | |
617 | */ | |
618 | typedef enum | |
619 | { | |
620 | IX_QMGR_Q_SIZE16 = 16, /**< 16 word buffer */ | |
621 | IX_QMGR_Q_SIZE32 = 32, /**< 32 word buffer */ | |
622 | IX_QMGR_Q_SIZE64 = 64, /**< 64 word buffer */ | |
623 | IX_QMGR_Q_SIZE128 = 128, /**< 128 word buffer */ | |
624 | IX_QMGR_Q_SIZE_INVALID = 129 /**< Insure that this is greater than largest | |
625 | * queue size supported by the hardware | |
626 | */ | |
627 | } IxQMgrQSizeInWords; | |
628 | ||
629 | /** | |
630 | * @enum IxQMgrWMLevel | |
631 | * | |
632 | * @ingroup IxQMgrAPI | |
633 | * | |
634 | * @brief QMgr watermark levels. | |
635 | * | |
636 | * These values define the valid watermark levels(in ENTRIES) for queues. Each | |
637 | * queue 0-63 have configurable Nearly full and Nearly empty watermarks. For | |
638 | * queues 32-63 the Nearly full watermark has NO EFFECT. | |
639 | * If the Nearly full watermark is set to IX_QMGR_Q_WM_LEVEL16 this means that | |
640 | * the nearly full flag will be set by the hardware when there are >= 16 empty | |
641 | * entries in the specified queue. | |
642 | * If the Nearly empty watermark is set to IX_QMGR_Q_WM_LEVEL16 this means that | |
643 | * the Nearly empty flag will be set by the hardware when there are <= 16 full | |
644 | * entries in the specified queue. | |
645 | */ | |
646 | typedef enum | |
647 | { | |
648 | IX_QMGR_Q_WM_LEVEL0 = 0, /**< 0 entry watermark */ | |
649 | IX_QMGR_Q_WM_LEVEL1 = 1, /**< 1 entry watermark */ | |
650 | IX_QMGR_Q_WM_LEVEL2 = 2, /**< 2 entry watermark */ | |
651 | IX_QMGR_Q_WM_LEVEL4 = 4, /**< 4 entry watermark */ | |
652 | IX_QMGR_Q_WM_LEVEL8 = 8, /**< 8 entry watermark */ | |
653 | IX_QMGR_Q_WM_LEVEL16 = 16, /**< 16 entry watermark */ | |
654 | IX_QMGR_Q_WM_LEVEL32 = 32, /**< 32 entry watermark */ | |
655 | IX_QMGR_Q_WM_LEVEL64 = 64 /**< 64 entry watermark */ | |
656 | } IxQMgrWMLevel; | |
657 | ||
658 | /** | |
659 | * @ingroup IxQMgrAPI | |
660 | * | |
661 | * @enum IxQMgrDispatchGroup | |
662 | * | |
663 | * @brief QMgr dispatch group select identifiers. | |
664 | * | |
665 | * This enum defines the groups over which the dispatcher will process when | |
666 | * called. One of the enum values must be used as a input to | |
667 | * @a ixQMgrDispatcherLoopRunA0, @a ixQMgrDispatcherLoopRunB0 | |
668 | * or @a ixQMgrDispatcherLoopRunB0LLP. | |
669 | * | |
670 | */ | |
671 | typedef enum | |
672 | { | |
673 | IX_QMGR_QUELOW_GROUP = 0, /**< Queues 0-31 */ | |
674 | IX_QMGR_QUEUPP_GROUP /**< Queues 32-63 */ | |
675 | } IxQMgrDispatchGroup; | |
676 | ||
677 | /** | |
678 | * @ingroup IxQMgrAPI | |
679 | * | |
680 | * @enum IxQMgrPriority | |
681 | * | |
682 | * @brief Dispatcher priority levels. | |
683 | * | |
684 | * This enum defines the different queue dispatch priority levels. | |
685 | * The lowest priority number (0) is the highest priority level. | |
686 | * | |
687 | */ | |
688 | typedef enum | |
689 | { | |
690 | IX_QMGR_Q_PRIORITY_0 = 0, /**< Priority level 0 */ | |
691 | IX_QMGR_Q_PRIORITY_1, /**< Priority level 1 */ | |
692 | IX_QMGR_Q_PRIORITY_2, /**< Priority level 2 */ | |
693 | IX_QMGR_Q_PRIORITY_INVALID /**< Invalid Priority level */ | |
694 | } IxQMgrPriority; | |
695 | ||
696 | /** | |
697 | * @ingroup IxQMgrAPI | |
698 | * | |
699 | * @enum IxQMgrType | |
700 | * | |
701 | * @brief Callback types as used with livelock prevention | |
702 | * | |
703 | * This enum defines the different callback types. | |
704 | * These types are only used when Livelock prevention is enabled. | |
705 | * The default is IX_QMGR_TYPE_REALTIME_OTHER. | |
706 | * | |
707 | */ | |
708 | ||
709 | typedef enum | |
710 | { | |
711 | IX_QMGR_TYPE_REALTIME_OTHER = 0, /**< Real time callbacks-always allowed run*/ | |
712 | IX_QMGR_TYPE_REALTIME_PERIODIC, /**< Periodic callbacks-always allowed run */ | |
713 | IX_QMGR_TYPE_REALTIME_SPORADIC /**< Sporadic callbacks-only run if no | |
714 | periodic callbacks are in progress */ | |
715 | } IxQMgrType; | |
716 | ||
717 | ||
718 | /** | |
719 | * @ingroup IxQMgrAPI | |
720 | * | |
721 | * @typedef IxQMgrCallbackId | |
722 | * | |
723 | * @brief Uniquely identifies a callback function. | |
724 | * | |
725 | * A unique callback identifier associated with each callback | |
726 | * registered by clients. | |
727 | * | |
728 | */ | |
729 | typedef unsigned IxQMgrCallbackId; | |
730 | ||
731 | /** | |
732 | * @typedef IxQMgrCallback | |
733 | * | |
734 | * @brief QMgr notification callback type. | |
735 | * | |
736 | * This defines the interface to all client callback functions. | |
737 | * | |
738 | * @param qId @ref IxQMgrQId [in] - the queue identifier | |
739 | * @param cbId @ref IxQMgrCallbackId [in] - the callback identifier | |
740 | */ | |
741 | typedef void (*IxQMgrCallback)(IxQMgrQId qId, | |
742 | IxQMgrCallbackId cbId); | |
743 | ||
744 | /** | |
745 | * @ingroup IxQMgrAPI | |
746 | * | |
747 | * @typedef IxQMgrDispatcherFuncPtr | |
748 | * | |
749 | * @brief QMgr Dispatcher Loop function pointer. | |
750 | * | |
751 | * This defines the interface for QMgr Dispather functions. | |
752 | * | |
753 | * @param group @ref IxQMgrDispatchGroup [in] - the group of the | |
754 | * queue of which the dispatcher will run | |
755 | */ | |
756 | typedef void (*IxQMgrDispatcherFuncPtr)(IxQMgrDispatchGroup group); | |
757 | ||
758 | /* | |
759 | * Function Prototypes | |
760 | */ | |
761 | ||
762 | /* ------------------------------------------------------------ | |
763 | Initialisation related functions | |
764 | ---------------------------------------------------------- */ | |
765 | ||
766 | /** | |
767 | * | |
768 | * @ingroup IxQMgrAPI | |
769 | * | |
770 | * @fn ixQMgrInit (void) | |
771 | * | |
772 | * @brief Initialise the QMgr. | |
773 | * | |
774 | * This function must be called before and other QMgr function. It | |
775 | * sets up internal data structures. | |
776 | * | |
777 | * @return @li IX_SUCCESS, the IxQMgr successfully initialised | |
778 | * @return @li IX_FAIL, failed to initialize the Qmgr | |
779 | * | |
780 | */ | |
781 | PUBLIC IX_STATUS | |
782 | ixQMgrInit (void); | |
783 | ||
784 | /** | |
785 | * | |
786 | * @ingroup IxQMgrAPI | |
787 | * | |
788 | * @fn ixQMgrUnload (void) | |
789 | * | |
790 | * @brief Uninitialise the QMgr. | |
791 | * | |
792 | * This function will perform the tasks required to unload the QMgr component | |
793 | * cleanly. This includes unmapping kernel memory. | |
794 | * This should be called before a soft reboot or unloading of a kernel module. | |
795 | * | |
796 | * @pre It should only be called if @ref ixQMgrInit has already been called. | |
797 | * | |
798 | * @post No QMgr functions should be called until ixQMgrInit is called again. | |
799 | * | |
800 | * @return @li IX_SUCCESS, the IxQMgr successfully uninitialised | |
801 | * @return @li IX_FAIL, failed to uninitialize the Qmgr | |
802 | * | |
803 | */ | |
804 | PUBLIC IX_STATUS | |
805 | ixQMgrUnload (void); | |
806 | ||
807 | /** | |
808 | * | |
809 | * @ingroup IxQMgrAPI | |
810 | * | |
811 | * @fn ixQMgrShow (void) | |
812 | * | |
813 | * @brief Describe queue configuration and statistics for active queues. | |
814 | * | |
815 | * This function shows active queues, their configurations and statistics. | |
816 | * | |
817 | * @return @li void | |
818 | * | |
819 | */ | |
820 | PUBLIC void | |
821 | ixQMgrShow (void); | |
822 | ||
823 | /** | |
824 | * | |
825 | * @ingroup IxQMgrAPI | |
826 | * | |
827 | * @fn ixQMgrQShow (IxQMgrQId qId) | |
828 | * | |
829 | * @brief Display aqueue configuration and statistics for a queue. | |
830 | * | |
831 | * This function shows queue configuration and statistics for a queue. | |
832 | * | |
833 | * @param qId @ref IxQMgrQId [in] - the queue identifier. | |
834 | * | |
835 | * @return @li IX_SUCCESS, success | |
836 | * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId | |
837 | * | |
838 | */ | |
839 | PUBLIC IX_STATUS | |
840 | ixQMgrQShow (IxQMgrQId qId); | |
841 | ||
842 | ||
843 | /* ------------------------------------------------------------ | |
844 | Configuration related functions | |
845 | ---------------------------------------------------------- */ | |
846 | ||
847 | /** | |
848 | * | |
849 | * @ingroup IxQMgrAPI | |
850 | * | |
851 | * @fn ixQMgrQConfig (char *qName, | |
852 | IxQMgrQId qId, | |
853 | IxQMgrQSizeInWords qSizeInWords, | |
854 | IxQMgrQEntrySizeInWords qEntrySizeInWords) | |
855 | * | |
856 | * @brief Configure an AQM queue. | |
857 | * | |
858 | * This function is called by a client to setup a queue. The size and entrySize | |
859 | * qId and qName(NULL pointer) are checked for valid values. This function must | |
860 | * be called for each queue, before any queue accesses are made and after | |
861 | * ixQMgrInit() has been called. qName is assumed to be a '\0' terminated array | |
862 | * of 16 charachters or less. | |
863 | * | |
864 | * @param *qName char [in] - is the name provided by the client and is associated | |
865 | * with a QId by the QMgr. | |
866 | * @param qId @ref IxQMgrQId [in] - the qId of this queue | |
867 | * @param qSizeInWords @ref IxQMgrQSize [in] - the size of the queue can be one of 16,32 | |
868 | * 64, 128 words. | |
869 | * @param qEntrySizeInWords @ref IxQMgrQEntrySizeInWords [in] - the size of a queue entry | |
870 | * can be one of 1,2,4 words. | |
871 | * | |
872 | * @return @li IX_SUCCESS, a specified queue has been successfully configured. | |
873 | * @return @li IX_FAIL, IxQMgr has not been initialised. | |
874 | * @return @li IX_QMGR_PARAMETER_ERROR, invalid parameter(s). | |
875 | * @return @li IX_QMGR_INVALID_QSIZE, invalid queue size | |
876 | * @return @li IX_QMGR_INVALID_Q_ID, invalid queue id | |
877 | * @return @li IX_QMGR_INVALID_Q_ENTRY_SIZE, invalid queue entry size | |
878 | * @return @li IX_QMGR_Q_ALREADY_CONFIGURED, queue already configured | |
879 | * | |
880 | */ | |
881 | PUBLIC IX_STATUS | |
882 | ixQMgrQConfig (char *qName, | |
883 | IxQMgrQId qId, | |
884 | IxQMgrQSizeInWords qSizeInWords, | |
885 | IxQMgrQEntrySizeInWords qEntrySizeInWords); | |
886 | ||
887 | /** | |
888 | * @ingroup IxQMgrAPI | |
889 | * | |
890 | * @fn ixQMgrQSizeInEntriesGet (IxQMgrQId qId, | |
891 | unsigned *qSizeInEntries) | |
892 | * | |
893 | * @brief Return the size of a queue in entries. | |
894 | * | |
895 | * This function returns the the size of the queue in entriese. | |
896 | * | |
897 | * @param qId @ref IxQMgrQId [in] - the queue identifier | |
898 | * @param *qSizeInEntries @ref IxQMgrQSize [out] - queue size in entries | |
899 | * | |
900 | * @return @li IX_SUCCESS, successfully retrieved the number of full entrie | |
901 | * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId | |
902 | * @return @li IX_QMGR_PARAMETER_ERROR, invalid parameter(s). | |
903 | * | |
904 | */ | |
905 | PUBLIC IX_STATUS | |
906 | ixQMgrQSizeInEntriesGet (IxQMgrQId qId, | |
907 | unsigned *qSizeInEntries); | |
908 | ||
909 | /** | |
910 | * | |
911 | * @ingroup IxQMgrAPI | |
912 | * | |
913 | * @fn ixQMgrWatermarkSet (IxQMgrQId qId, | |
914 | IxQMgrWMLevel ne, | |
915 | IxQMgrWMLevel nf) | |
916 | * | |
917 | * @brief Set the Nearly Empty and Nearly Full Watermarks fo a queue. | |
918 | * | |
919 | * This function is called by a client to set the watermarks NE and NF for the | |
920 | * queue specified by qId. | |
921 | * The queue must be empty at the time this function is called, it is the clients | |
922 | * responsibility to ensure that the queue is empty. | |
923 | * This function will read the status of the queue before the watermarks are set | |
924 | * and again after the watermarks are set. If the status register has changed, | |
925 | * due to a queue access by an NPE for example, a warning is returned. | |
926 | * Queues 32-63 only support the NE flag, therefore the value of nf will be ignored | |
927 | * for these queues. | |
928 | * | |
929 | * @param qId @ref IxQMgrQId [in] - the QId of the queue. | |
930 | * @param ne @ref IxQMgrWMLevel [in] - the NE(Nearly Empty) watermark for this | |
931 | * queue. Valid values are 0,1,2,4,8,16,32 and | |
932 | * 64 entries. | |
933 | * @param nf @ref IxQMgrWMLevel [in] - the NF(Nearly Full) watermark for this queue. | |
934 | * Valid values are 0,1,2,4,8,16,32 and 64 | |
935 | * entries. | |
936 | * | |
937 | * @return @li IX_SUCCESS, watermarks have been set for the queu | |
938 | * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId | |
939 | * @return @li IX_QMGR_INVALID_Q_WM, invalid watermark | |
940 | * @return @li IX_QMGR_WARNING, the status register may not be constistent | |
941 | * | |
942 | */ | |
943 | PUBLIC IX_STATUS | |
944 | ixQMgrWatermarkSet (IxQMgrQId qId, | |
945 | IxQMgrWMLevel ne, | |
946 | IxQMgrWMLevel nf); | |
947 | ||
948 | /** | |
949 | * @ingroup IxQMgrAPI | |
950 | * | |
951 | * @fn ixQMgrAvailableSramAddressGet (UINT32 *address, | |
952 | unsigned *sizeOfFreeSram) | |
953 | * | |
954 | * @brief Return the address of available AQM SRAM. | |
955 | * | |
956 | * This function returns the starting address in AQM SRAM not used by the | |
957 | * current queue configuration and should only be called after all queues | |
958 | * have been configured. | |
959 | * Calling this function before all queues have been configured will will return | |
960 | * the currently available SRAM. A call to configure another queue will use some | |
961 | * of the available SRAM. | |
962 | * The amount of SRAM available is specified in sizeOfFreeSram. The address is the | |
963 | * address of the bottom of available SRAM. Available SRAM extends from address | |
964 | * from address to address + sizeOfFreeSram. | |
965 | * | |
966 | * @param **address UINT32 [out] - the address of the available SRAM, NULL if | |
967 | * none available. | |
968 | * @param *sizeOfFreeSram unsigned [out]- the size in words of available SRAM | |
969 | * | |
970 | * @return @li IX_SUCCESS, there is available SRAM and is pointed to by address | |
971 | * @return @li IX_QMGR_PARAMETER_ERROR, invalid parameter(s) | |
972 | * @return @li IX_QMGR_NO_AVAILABLE_SRAM, all AQM SRAM is consumed by the queue | |
973 | * configuration. | |
974 | * | |
975 | */ | |
976 | PUBLIC IX_STATUS | |
977 | ixQMgrAvailableSramAddressGet (UINT32 *address, | |
978 | unsigned *sizeOfFreeSram); | |
979 | ||
980 | ||
981 | /* ------------------------------------------------------------ | |
982 | Queue access related functions | |
983 | ---------------------------------------------------------- */ | |
984 | ||
985 | /** | |
986 | * | |
987 | * @ingroup IxQMgrAPI | |
988 | * | |
989 | * @fn ixQMgrQReadWithChecks (IxQMgrQId qId, | |
990 | UINT32 *entry) | |
991 | * | |
992 | * @brief Read an entry from a queue. | |
993 | * | |
994 | * This function reads an entire entry from a queue returning it in entry. The | |
995 | * queue configuration word is read to determine what entry size this queue is | |
996 | * configured for and then the number of words specified by the entry size is | |
997 | * read. entry must be a pointer to a previously allocated array of sufficient | |
998 | * size to hold an entry. | |
999 | * | |
1000 | * @note - IX_QMGR_Q_UNDERFLOW is only returned for queues 0-31 as queues 32-63 | |
1001 | * do not have an underflow status maintained. | |
1002 | * | |
1003 | * @param qId @ref IxQMgrQId [in] - the queue identifier. | |
1004 | * @param *entry UINT32 [out] - pointer to the entry word(s). | |
1005 | * | |
1006 | * @return @li IX_SUCCESS, entry was successfully read. | |
1007 | * @return @li IX_QMGR_PARAMETER_ERROR, invalid paramter(s). | |
1008 | * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId | |
1009 | * @return @li IX_QMGR_Q_UNDERFLOW, attempt to read from an empty queue | |
1010 | * | |
1011 | */ | |
1012 | PUBLIC IX_STATUS | |
1013 | ixQMgrQReadWithChecks (IxQMgrQId qId, | |
1014 | UINT32 *entry); | |
1015 | ||
1016 | ||
1017 | ||
1018 | /** | |
1019 | * @brief Internal structure to facilitate inlining functions in IxQMgr.h | |
1020 | */ | |
1021 | typedef struct | |
1022 | { | |
1023 | /* fields related to write functions */ | |
1024 | UINT32 qOflowStatBitMask; /**< overflow status mask */ | |
1025 | UINT32 qWriteCount; /**< queue write count */ | |
1026 | ||
1027 | /* fields related to read and write functions */ | |
1028 | volatile UINT32 *qAccRegAddr; /**< access register */ | |
1029 | volatile UINT32 *qUOStatRegAddr; /**< status register */ | |
1030 | volatile UINT32 *qConfigRegAddr; /**< config register */ | |
1031 | UINT32 qEntrySizeInWords; /**< queue entry size in words */ | |
1032 | UINT32 qSizeInEntries; /**< queue size in entries */ | |
1033 | ||
1034 | /* fields related to read functions */ | |
1035 | UINT32 qUflowStatBitMask; /**< underflow status mask */ | |
1036 | UINT32 qReadCount; /**< queue read count */ | |
1037 | } IxQMgrQInlinedReadWriteInfo; | |
1038 | ||
1039 | ||
1040 | /** | |
1041 | * | |
1042 | * @ingroup IxQMgrAPI | |
1043 | * | |
1044 | * @fn ixQMgrQReadMWordsMinus1 (IxQMgrQId qId, | |
1045 | UINT32 *entry) | |
1046 | * | |
1047 | * @brief This function reads the remaining of the q entry | |
1048 | * for queues configured with many words. | |
1049 | * (the first word of the entry is already read | |
1050 | * in the inlined function and the entry pointer already | |
1051 | * incremented | |
1052 | * | |
1053 | * @param qId @ref IxQMgrQId [in] - the queue identifier. | |
1054 | * @param *entry UINT32 [out] - pointer to the entry word(s). | |
1055 | * | |
1056 | * @return @li IX_SUCCESS, entry was successfully read. | |
1057 | * @return @li IX_QMGR_Q_UNDERFLOW, attempt to read from an empty queue | |
1058 | * | |
1059 | */ | |
1060 | PUBLIC IX_STATUS | |
1061 | ixQMgrQReadMWordsMinus1 (IxQMgrQId qId, | |
1062 | UINT32 *entry); | |
1063 | ||
1064 | ||
1065 | ||
1066 | /** | |
1067 | * | |
1068 | * @ingroup IxQMgrAPI | |
1069 | * | |
1070 | * @fn ixQMgrQRead (IxQMgrQId qId, | |
1071 | UINT32 *entry) | |
1072 | * | |
1073 | * @brief Fast read of an entry from a queue. | |
1074 | * | |
1075 | * This function is a heavily streamlined version of ixQMgrQReadWithChecks(), | |
1076 | * but performs essentially the same task. It reads an entire entry from a | |
1077 | * queue, returning it in entry which must be a pointer to a previously | |
1078 | * allocated array of sufficient size to hold an entry. | |
1079 | * | |
1080 | * @note - This function is inlined, to reduce unnecessary function call | |
1081 | * overhead. It does not perform any parameter checks, or update any statistics. | |
1082 | * Also, it does not check that the queue specified by qId has been configured. | |
1083 | * or is in range. It simply reads an entry from the queue, and checks for | |
1084 | * underflow. | |
1085 | * | |
1086 | * @note - IX_QMGR_Q_UNDERFLOW is only returned for queues 0-31 as queues 32-63 | |
1087 | * do not have an underflow status maintained. | |
1088 | * | |
1089 | * @param qId @ref IxQMgrQId [in] - the queue identifier. | |
1090 | * @param *entry UINT32 [out] - pointer to the entry word(s). | |
1091 | * | |
1092 | * @return @li IX_SUCCESS, entry was successfully read. | |
1093 | * @return @li IX_QMGR_Q_UNDERFLOW, attempt to read from an empty queue | |
1094 | * | |
1095 | */ | |
1096 | #ifdef NO_INLINE_APIS | |
1097 | PUBLIC IX_STATUS | |
1098 | ixQMgrQRead (IxQMgrQId qId, | |
1099 | UINT32 *entryPtr); | |
1100 | #else | |
1101 | extern IxQMgrQInlinedReadWriteInfo ixQMgrQInlinedReadWriteInfo[]; | |
1102 | extern IX_STATUS ixQMgrQReadMWordsMinus1 (IxQMgrQId qId, UINT32 *entryPtr); | |
1103 | ||
1104 | IX_QMGR_INLINE PUBLIC IX_STATUS | |
1105 | ixQMgrQRead (IxQMgrQId qId, | |
1106 | UINT32 *entryPtr); | |
1107 | #endif | |
1108 | ||
1109 | IX_QMGR_INLINE PUBLIC IX_STATUS | |
1110 | ixQMgrQRead (IxQMgrQId qId, | |
1111 | UINT32 *entryPtr) | |
1112 | #ifdef NO_INLINE_APIS | |
1113 | ; | |
1114 | #else | |
1115 | { | |
1116 | IxQMgrQInlinedReadWriteInfo *infoPtr = &ixQMgrQInlinedReadWriteInfo[qId]; | |
1117 | UINT32 entry, entrySize; | |
1118 | ||
1119 | /* get a new entry */ | |
1120 | entrySize = infoPtr->qEntrySizeInWords; | |
1121 | entry = IX_QMGR_INLINE_READ_LONG(infoPtr->qAccRegAddr); | |
1122 | ||
1123 | if (entrySize != IX_QMGR_Q_ENTRY_SIZE1) | |
1124 | { | |
1125 | *entryPtr = entry; | |
1126 | /* process the remaining part of the entry */ | |
1127 | return ixQMgrQReadMWordsMinus1(qId, entryPtr); | |
1128 | } | |
1129 | ||
1130 | /* underflow is available for lower queues only */ | |
1131 | if (qId < IX_QMGR_MIN_QUEUPP_QID) | |
1132 | { | |
1133 | /* the counter of queue entries is decremented. In happy | |
1134 | * day scenario there are many entries in the queue | |
1135 | * and the counter does not reach zero. | |
1136 | */ | |
53677ef1 | 1137 | if (infoPtr->qReadCount-- == 0) |
ba94a1bb WD |
1138 | { |
1139 | /* There is maybe no entry in the queue | |
1140 | * qReadCount is now negative, but will be corrected before | |
1141 | * the function returns. | |
1142 | */ | |
1143 | UINT32 qPtrs; /* queue internal pointers */ | |
1144 | ||
1145 | /* when a queue is empty, the hw guarantees to return | |
1146 | * a null value. If the value is not null, the queue is | |
1147 | * not empty. | |
1148 | */ | |
1149 | if (entry == 0) | |
1150 | { | |
1151 | /* get the queue status */ | |
1152 | UINT32 status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr); | |
1153 | ||
1154 | /* check the underflow status */ | |
1155 | if (status & infoPtr->qUflowStatBitMask) | |
1156 | { | |
1157 | /* the queue is empty | |
1158 | * clear the underflow status bit if it was set | |
1159 | */ | |
1160 | IX_QMGR_INLINE_WRITE_LONG(infoPtr->qUOStatRegAddr, | |
1161 | status & ~infoPtr->qUflowStatBitMask); | |
1162 | *entryPtr = 0; | |
1163 | infoPtr->qReadCount = 0; | |
1164 | return IX_QMGR_Q_UNDERFLOW; | |
1165 | } | |
1166 | } | |
1167 | /* store the result */ | |
1168 | *entryPtr = entry; | |
1169 | ||
1170 | /* No underflow occured : someone is filling the queue | |
1171 | * or the queue contains null entries. | |
1172 | * The current counter needs to be | |
1173 | * updated from the current number of entries in the queue | |
1174 | */ | |
1175 | ||
1176 | /* get snapshot of queue pointers */ | |
1177 | qPtrs = IX_QMGR_INLINE_READ_LONG(infoPtr->qConfigRegAddr); | |
1178 | ||
1179 | /* Mod subtraction of pointers to get number of words in Q. */ | |
1180 | qPtrs = (qPtrs - (qPtrs >> 7)) & 0x7f; | |
1181 | ||
1182 | if (qPtrs == 0) | |
1183 | { | |
1184 | /* no entry in the queue */ | |
1185 | infoPtr->qReadCount = 0; | |
1186 | } | |
1187 | else | |
1188 | { | |
1189 | /* convert the number of words inside the queue | |
1190 | * to a number of entries | |
1191 | */ | |
1192 | infoPtr->qReadCount = qPtrs & (infoPtr->qSizeInEntries - 1); | |
1193 | } | |
1194 | return IX_SUCCESS; | |
1195 | } | |
1196 | } | |
1197 | *entryPtr = entry; | |
1198 | return IX_SUCCESS; | |
1199 | } | |
1200 | #endif | |
1201 | ||
1202 | /** | |
1203 | * | |
1204 | * @ingroup IxQMgrAPI | |
1205 | * | |
1206 | * @fn ixQMgrQBurstRead (IxQMgrQId qId, | |
1207 | UINT32 numEntries, | |
1208 | UINT32 *entries) | |
1209 | * | |
1210 | * @brief Read a number of entries from an AQM queue. | |
1211 | * | |
1212 | * This function will burst read a number of entries from the specified queue. | |
1213 | * The entry size of queue is auto-detected. The function will attempt to | |
1214 | * read as many entries as specified by the numEntries parameter and will | |
1215 | * return an UNDERFLOW if any one of the individual entry reads fail. | |
1216 | * | |
1217 | * @warning | |
1218 | * IX_QMGR_Q_UNDERFLOW is only returned for queues 0-31 as queues 32-63 | |
1219 | * do not have an underflow status maintained, hence there is a potential for | |
1220 | * silent failure here. This function must be used with caution. | |
1221 | * | |
1222 | * @note | |
1223 | * This function is intended for fast draining of queues, so to make it | |
1224 | * as efficient as possible, it has the following features: | |
1225 | * - This function is inlined, to reduce unnecessary function call overhead. | |
1226 | * - It does not perform any parameter checks, or update any statistics. | |
1227 | * - It does not check that the queue specified by qId has been configured. | |
1228 | * - It does not check that the queue has the number of full entries that | |
1229 | * have been specified to be read. It will read until it finds a NULL entry or | |
1230 | * until the number of specified entries have been read. It always checks for | |
1231 | * underflow after all the reads have been performed. | |
1232 | * Therefore, the client should ensure before calling this function that there | |
1233 | * are enough entries in the queue to read. ixQMgrQNumEntriesGet() will | |
1234 | * provide the number of full entries in a queue. | |
1235 | * ixQMgrQRead() or ixQMgrQReadWithChecks(), which only reads | |
1236 | * a single queue entry per call, should be used instead if the user requires | |
1237 | * checks for UNDERFLOW after each entry read. | |
1238 | * | |
1239 | * @param qId @ref IxQMgrQId [in] - the queue identifier. | |
1240 | * @param numEntries unsigned [in] - the number of entries to read. | |
1241 | * This number should be greater than 0 | |
1242 | * @param *entries UINT32 [out] - the word(s) read. | |
1243 | * | |
1244 | * @return @li IX_SUCCESS, entries were successfully read. | |
1245 | * @return @li IX_QMGR_Q_UNDERFLOW, attempt to read from an empty queue | |
1246 | * | |
1247 | */ | |
1248 | #ifdef NO_INLINE_APIS | |
1249 | PUBLIC IX_STATUS | |
1250 | ixQMgrQBurstRead (IxQMgrQId qId, | |
1251 | UINT32 numEntries, | |
1252 | UINT32 *entries); | |
1253 | #else | |
1254 | IX_QMGR_INLINE PUBLIC IX_STATUS | |
1255 | ixQMgrQBurstRead (IxQMgrQId qId, | |
1256 | UINT32 numEntries, | |
1257 | UINT32 *entries); | |
1258 | #endif /* endif NO_INLINE_APIS */ | |
1259 | ||
1260 | IX_QMGR_INLINE PUBLIC IX_STATUS | |
1261 | ixQMgrQBurstRead (IxQMgrQId qId, | |
1262 | UINT32 numEntries, | |
1263 | UINT32 *entries) | |
1264 | #ifdef NO_INLINE_APIS | |
1265 | ; | |
1266 | #else | |
1267 | { | |
1268 | IxQMgrQInlinedReadWriteInfo *infoPtr = &ixQMgrQInlinedReadWriteInfo[qId]; | |
1269 | UINT32 nullCheckEntry; | |
1270 | ||
1271 | if (infoPtr->qEntrySizeInWords == IX_QMGR_Q_ENTRY_SIZE1) | |
1272 | { | |
1273 | volatile UINT32 *qAccRegAddr = infoPtr->qAccRegAddr; | |
1274 | ||
1275 | /* the code is optimized to take care of data dependencies: | |
1276 | * Durig a read, there are a few cycles needed to get the | |
1277 | * read complete. During these cycles, it is poossible to | |
1278 | * do some CPU, e.g. increment pointers and decrement | |
1279 | * counters. | |
1280 | */ | |
1281 | ||
1282 | /* fetch a queue entry */ | |
1283 | nullCheckEntry = IX_QMGR_INLINE_READ_LONG(infoPtr->qAccRegAddr); | |
1284 | ||
1285 | /* iterate the specified number of queue entries */ | |
1286 | while (--numEntries) | |
1287 | { | |
1288 | /* check the result of the previous read */ | |
1289 | if (nullCheckEntry == 0) | |
1290 | { | |
1291 | /* if we read a NULL entry, stop. We have underflowed */ | |
1292 | break; | |
1293 | } | |
1294 | else | |
1295 | { | |
1296 | /* write the entry */ | |
1297 | *entries = nullCheckEntry; | |
1298 | /* fetch next entry */ | |
1299 | nullCheckEntry = IX_QMGR_INLINE_READ_LONG(qAccRegAddr); | |
1300 | /* increment the write address */ | |
1301 | entries++; | |
1302 | } | |
1303 | } | |
1304 | /* write the pre-fetched entry */ | |
1305 | *entries = nullCheckEntry; | |
1306 | } | |
1307 | else | |
1308 | { | |
1309 | IxQMgrQEntrySizeInWords entrySizeInWords = infoPtr->qEntrySizeInWords; | |
1310 | /* read the specified number of queue entries */ | |
1311 | nullCheckEntry = 0; | |
1312 | while (numEntries--) | |
1313 | { | |
1314 | UINT32 i; | |
1315 | ||
1316 | for (i = 0; i < (UINT32)entrySizeInWords; i++) | |
1317 | { | |
1318 | *entries = IX_QMGR_INLINE_READ_LONG(infoPtr->qAccRegAddr + i); | |
1319 | nullCheckEntry |= *entries++; | |
1320 | } | |
1321 | ||
1322 | /* if we read a NULL entry, stop. We have underflowed */ | |
1323 | if (nullCheckEntry == 0) | |
1324 | { | |
1325 | break; | |
1326 | } | |
1327 | nullCheckEntry = 0; | |
1328 | } | |
1329 | } | |
1330 | ||
1331 | /* reset the current read count : next access to the read function | |
1332 | * will force a underflow status check | |
1333 | */ | |
1334 | infoPtr->qReadCount = 0; | |
1335 | ||
1336 | /* Check if underflow occurred on the read */ | |
1337 | if (nullCheckEntry == 0 && qId < IX_QMGR_MIN_QUEUPP_QID) | |
1338 | { | |
1339 | /* get the queue status */ | |
1340 | UINT32 status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr); | |
1341 | ||
1342 | if (status & infoPtr->qUflowStatBitMask) | |
1343 | { | |
1344 | /* clear the underflow status bit if it was set */ | |
1345 | IX_QMGR_INLINE_WRITE_LONG(infoPtr->qUOStatRegAddr, | |
1346 | status & ~infoPtr->qUflowStatBitMask); | |
1347 | return IX_QMGR_Q_UNDERFLOW; | |
1348 | } | |
1349 | } | |
1350 | ||
1351 | return IX_SUCCESS; | |
1352 | } | |
1353 | #endif | |
1354 | ||
1355 | /** | |
1356 | * @ingroup IxQMgrAPI | |
1357 | * | |
1358 | * @fn ixQMgrQPeek (IxQMgrQId qId, | |
1359 | unsigned int entryIndex, | |
1360 | UINT32 *entry) | |
1361 | * | |
1362 | * @brief Read an entry from a queue without moving the read pointer. | |
1363 | * | |
1364 | * This function inspects an entry in a queue. The entry is inspected directly | |
1365 | * in AQM SRAM and is not read from queue access registers. The entry is NOT removed | |
1366 | * from the queue and the read/write pointers are unchanged. | |
1367 | * N.B: The queue should not be accessed when this function is called. | |
1368 | * | |
1369 | * @param qId @ref IxQMgrQId [in] - the queue identifier. | |
1370 | * @param entryIndex unsigned int [in] - index of entry in queue in the range | |
1371 | * [0].......[current number of entries in queue]. | |
1372 | * @param *entry UINT32 [out] - pointer to the entry word(s). | |
1373 | * | |
1374 | * @return @li IX_SUCCESS, entry was successfully inspected. | |
1375 | * @return @li IX_QMGR_PARAMETER_ERROR, invalid paramter(s). | |
1376 | * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId. | |
1377 | * @return @li IX_QMGR_ENTRY_INDEX_OUT_OF_BOUNDS, an entry does not exist at | |
1378 | * specified index. | |
1379 | * @return @li IX_FAIL, failed to inpected the queue entry. | |
1380 | */ | |
1381 | PUBLIC IX_STATUS | |
1382 | ixQMgrQPeek (IxQMgrQId qId, | |
1383 | unsigned int entryIndex, | |
1384 | UINT32 *entry); | |
1385 | ||
1386 | /** | |
1387 | * | |
1388 | * @ingroup IxQMgrAPI | |
1389 | * | |
1390 | * @fn ixQMgrQWriteWithChecks (IxQMgrQId qId, | |
1391 | UINT32 *entry) | |
1392 | * | |
1393 | * @brief Write an entry to an AQM queue. | |
1394 | * | |
1395 | * This function will write the entry size number of words pointed to by entry to | |
1396 | * the queue specified by qId. The queue configuration word is read to | |
1397 | * determine the entry size of queue and the corresponding number of words is | |
1398 | * then written to the queue. | |
1399 | * | |
1400 | * @note - IX_QMGR_Q_OVERFLOW is only returned for queues 0-31 as queues 32-63 | |
1401 | * do not have an overflow status maintained. | |
1402 | * | |
1403 | * @param qId @ref IxQMgrQId [in] - the queue identifier. | |
1404 | * @param *entry UINT32 [in] - the word(s) to write. | |
1405 | * | |
1406 | * @return @li IX_SUCCESS, value was successfully written. | |
1407 | * @return @li IX_QMGR_PARAMETER_ERROR, invalid paramter(s). | |
1408 | * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId | |
1409 | * @return @li IX_QMGR_Q_OVERFLOW, attempt to write to a full queue | |
1410 | * | |
1411 | */ | |
1412 | PUBLIC IX_STATUS | |
1413 | ixQMgrQWriteWithChecks (IxQMgrQId qId, | |
1414 | UINT32 *entry); | |
1415 | ||
1416 | /** | |
1417 | * | |
1418 | * @ingroup IxQMgrAPI | |
1419 | * | |
1420 | * @fn ixQMgrQWrite (IxQMgrQId qId, | |
1421 | UINT32 *entry) | |
1422 | * | |
1423 | * @brief Fast write of an entry to a queue. | |
1424 | * | |
1425 | * This function is a heavily streamlined version of ixQMgrQWriteWithChecks(), | |
1426 | * but performs essentially the same task. It will write the entry size number | |
1427 | * of words pointed to by entry to the queue specified by qId. | |
1428 | * | |
1429 | * @note - This function is inlined, to reduce unnecessary function call | |
1430 | * overhead. It does not perform any parameter checks, or update any | |
1431 | * statistics. Also, it does not check that the queue specified by qId has | |
1432 | * been configured. It simply writes an entry to the queue, and checks for | |
1433 | * overflow. | |
1434 | * | |
1435 | * @note - IX_QMGR_Q_OVERFLOW is only returned for queues 0-31 as queues 32-63 | |
1436 | * do not have an overflow status maintained. | |
1437 | * | |
1438 | * @param qId @ref IxQMgrQId [in] - the queue identifier. | |
1439 | * @param *entry UINT32 [in] - pointer to the entry word(s). | |
1440 | * | |
1441 | * @return @li IX_SUCCESS, entry was successfully read. | |
1442 | * @return @li IX_QMGR_Q_OVERFLOW, attempt to write to a full queue | |
1443 | * | |
1444 | */ | |
1445 | #ifdef NO_INLINE_APIS | |
1446 | PUBLIC IX_STATUS | |
1447 | ixQMgrQWrite (IxQMgrQId qId, | |
1448 | UINT32 *entry); | |
1449 | #else | |
1450 | IX_QMGR_INLINE PUBLIC IX_STATUS | |
1451 | ixQMgrQWrite (IxQMgrQId qId, | |
1452 | UINT32 *entry); | |
1453 | #endif /* NO_INLINE_APIS */ | |
1454 | ||
1455 | IX_QMGR_INLINE PUBLIC IX_STATUS | |
1456 | ixQMgrQWrite (IxQMgrQId qId, | |
1457 | UINT32 *entry) | |
1458 | #ifdef NO_INLINE_APIS | |
1459 | ; | |
1460 | #else | |
1461 | { | |
1462 | IxQMgrQInlinedReadWriteInfo *infoPtr = &ixQMgrQInlinedReadWriteInfo[qId]; | |
1463 | UINT32 entrySize; | |
1464 | ||
1465 | /* write the entry */ | |
1466 | IX_QMGR_INLINE_WRITE_LONG(infoPtr->qAccRegAddr, *entry); | |
1467 | entrySize = infoPtr->qEntrySizeInWords; | |
1468 | ||
1469 | if (entrySize != IX_QMGR_Q_ENTRY_SIZE1) | |
1470 | { | |
1471 | /* process the remaining part of the entry */ | |
1472 | volatile UINT32 *qAccRegAddr = infoPtr->qAccRegAddr; | |
1473 | while (--entrySize) | |
1474 | { | |
1475 | ++entry; | |
1476 | IX_QMGR_INLINE_WRITE_LONG(++qAccRegAddr, *entry); | |
1477 | } | |
53677ef1 | 1478 | entrySize = infoPtr->qEntrySizeInWords; |
ba94a1bb WD |
1479 | } |
1480 | ||
1481 | /* overflow is available for lower queues only */ | |
1482 | if (qId < IX_QMGR_MIN_QUEUPP_QID) | |
1483 | { | |
1484 | UINT32 qSize = infoPtr->qSizeInEntries; | |
1485 | /* increment the current number of entries in the queue | |
1486 | * and check for overflow | |
1487 | */ | |
1488 | if (infoPtr->qWriteCount++ == qSize) | |
1489 | { | |
1490 | /* the queue may have overflow */ | |
1491 | UINT32 qPtrs; /* queue internal pointers */ | |
1492 | ||
1493 | /* get the queue status */ | |
1494 | UINT32 status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr); | |
1495 | ||
1496 | /* read the status twice because the status may | |
1497 | * not be immediately ready after the write operation | |
1498 | */ | |
1499 | if ((status & infoPtr->qOflowStatBitMask) || | |
1500 | ((status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr)) | |
1501 | & infoPtr->qOflowStatBitMask)) | |
1502 | { | |
1503 | /* the queue is full, clear the overflow status | |
1504 | * bit if it was set | |
1505 | */ | |
1506 | IX_QMGR_INLINE_WRITE_LONG(infoPtr->qUOStatRegAddr, | |
1507 | status & ~infoPtr->qOflowStatBitMask); | |
1508 | infoPtr->qWriteCount = infoPtr->qSizeInEntries; | |
1509 | return IX_QMGR_Q_OVERFLOW; | |
1510 | } | |
1511 | /* No overflow occured : someone is draining the queue | |
1512 | * and the current counter needs to be | |
1513 | * updated from the current number of entries in the queue | |
1514 | */ | |
1515 | ||
1516 | /* get q pointer snapshot */ | |
1517 | qPtrs = IX_QMGR_INLINE_READ_LONG(infoPtr->qConfigRegAddr); | |
1518 | ||
1519 | /* Mod subtraction of pointers to get number of words in Q. */ | |
1520 | qPtrs = (qPtrs - (qPtrs >> 7)) & 0x7f; | |
1521 | ||
1522 | if (qPtrs == 0) | |
1523 | { | |
1524 | /* the queue may be full at the time of the | |
1525 | * snapshot. Next access will check | |
1526 | * the overflow status again. | |
1527 | */ | |
1528 | infoPtr->qWriteCount = qSize; | |
1529 | } | |
1530 | else | |
1531 | { | |
1532 | /* convert the number of words to a number of entries */ | |
1533 | if (entrySize == IX_QMGR_Q_ENTRY_SIZE1) | |
1534 | { | |
1535 | infoPtr->qWriteCount = qPtrs & (qSize - 1); | |
1536 | } | |
1537 | else | |
1538 | { | |
1539 | infoPtr->qWriteCount = (qPtrs / entrySize) & (qSize - 1); | |
1540 | } | |
1541 | } | |
1542 | } | |
1543 | } | |
1544 | return IX_SUCCESS; | |
1545 | } | |
1546 | #endif | |
1547 | ||
1548 | /** | |
1549 | * | |
1550 | * @ingroup IxQMgrAPI | |
1551 | * | |
1552 | * @fn ixQMgrQBurstWrite (IxQMgrQId qId, | |
1553 | unsigned numEntries, | |
1554 | UINT32 *entries) | |
1555 | * | |
1556 | * @brief Write a number of entries to an AQM queue. | |
1557 | * | |
1558 | * This function will burst write a number of entries to the specified queue. | |
1559 | * The entry size of queue is auto-detected. The function will attempt to | |
1560 | * write as many entries as specified by the numEntries parameter and will | |
1561 | * return an OVERFLOW if any one of the individual entry writes fail. | |
1562 | * | |
1563 | * @warning | |
1564 | * IX_QMGR_Q_OVERFLOW is only returned for queues 0-31 as queues 32-63 | |
1565 | * do not have an overflow status maintained, hence there is a potential for | |
1566 | * silent failure here. This function must be used with caution. | |
1567 | * | |
1568 | * @note | |
1569 | * This function is intended for fast population of queues, so to make it | |
1570 | * as efficient as possible, it has the following features: | |
1571 | * - This function is inlined, to reduce unnecessary function call overhead. | |
1572 | * - It does not perform any parameter checks, or update any statistics. | |
1573 | * - It does not check that the queue specified by qId has been configured. | |
1574 | * - It does not check that the queue has enough free space to hold the entries | |
1575 | * before writing, and only checks for overflow after all writes have been | |
1576 | * performed. Therefore, the client should ensure before calling this function | |
1577 | * that there is enough free space in the queue to hold the number of entries | |
1578 | * to be written. ixQMgrQWrite() or ixQMgrQWriteWithChecks(), which only writes | |
1579 | * a single queue entry per call, should be used instead if the user requires | |
1580 | * checks for OVERFLOW after each entry written. | |
1581 | * | |
1582 | * @param qId @ref IxQMgrQId [in] - the queue identifier. | |
1583 | * @param numEntries unsigned [in] - the number of entries to write. | |
1584 | * @param *entries UINT32 [in] - the word(s) to write. | |
1585 | * | |
1586 | * @return @li IX_SUCCESS, value was successfully written. | |
1587 | * @return @li IX_QMGR_Q_OVERFLOW, attempt to write to a full queue | |
1588 | * | |
1589 | */ | |
1590 | #ifdef NO_INLINE_APIS | |
1591 | PUBLIC IX_STATUS | |
1592 | ixQMgrQBurstWrite (IxQMgrQId qId, | |
1593 | unsigned numEntries, | |
1594 | UINT32 *entries); | |
1595 | #else | |
1596 | IX_QMGR_INLINE PUBLIC IX_STATUS | |
1597 | ixQMgrQBurstWrite (IxQMgrQId qId, | |
1598 | unsigned numEntries, | |
1599 | UINT32 *entries); | |
1600 | #endif /* NO_INLINE_APIS */ | |
1601 | ||
1602 | IX_QMGR_INLINE PUBLIC IX_STATUS | |
1603 | ixQMgrQBurstWrite (IxQMgrQId qId, | |
1604 | unsigned numEntries, | |
1605 | UINT32 *entries) | |
1606 | #ifdef NO_INLINE_APIS | |
1607 | ; | |
1608 | #else | |
1609 | { | |
1610 | IxQMgrQInlinedReadWriteInfo *infoPtr = &ixQMgrQInlinedReadWriteInfo[qId]; | |
1611 | UINT32 status; | |
1612 | ||
1613 | /* update the current write count */ | |
1614 | infoPtr->qWriteCount += numEntries; | |
1615 | ||
1616 | if (infoPtr->qEntrySizeInWords == IX_QMGR_Q_ENTRY_SIZE1) | |
1617 | { | |
1618 | volatile UINT32 *qAccRegAddr = infoPtr->qAccRegAddr; | |
1619 | while (numEntries--) | |
1620 | { | |
1621 | IX_QMGR_INLINE_WRITE_LONG(qAccRegAddr, *entries); | |
1622 | entries++; | |
1623 | } | |
1624 | } | |
1625 | else | |
1626 | { | |
1627 | IxQMgrQEntrySizeInWords entrySizeInWords = infoPtr->qEntrySizeInWords; | |
1628 | UINT32 i; | |
1629 | ||
1630 | /* write each queue entry */ | |
1631 | while (numEntries--) | |
1632 | { | |
1633 | /* write the queueEntrySize number of words for each entry */ | |
1634 | for (i = 0; i < (UINT32)entrySizeInWords; i++) | |
1635 | { | |
1636 | IX_QMGR_INLINE_WRITE_LONG((infoPtr->qAccRegAddr + i), *entries); | |
1637 | entries++; | |
1638 | } | |
1639 | } | |
1640 | } | |
1641 | ||
1642 | /* check if the write count overflows */ | |
1643 | if (infoPtr->qWriteCount > infoPtr->qSizeInEntries) | |
1644 | { | |
1645 | /* reset the current write count */ | |
1646 | infoPtr->qWriteCount = infoPtr->qSizeInEntries; | |
1647 | } | |
1648 | ||
1649 | /* Check if overflow occurred on the write operation */ | |
1650 | if (qId < IX_QMGR_MIN_QUEUPP_QID) | |
1651 | { | |
1652 | /* get the queue status */ | |
1653 | status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr); | |
1654 | ||
1655 | /* read the status twice because the status may | |
1656 | * not be ready at the time of the write | |
1657 | */ | |
1658 | if ((status & infoPtr->qOflowStatBitMask) || | |
1659 | ((status = IX_QMGR_INLINE_READ_LONG(infoPtr->qUOStatRegAddr)) | |
1660 | & infoPtr->qOflowStatBitMask)) | |
1661 | { | |
1662 | /* clear the underflow status bit if it was set */ | |
1663 | IX_QMGR_INLINE_WRITE_LONG(infoPtr->qUOStatRegAddr, | |
1664 | status & ~infoPtr->qOflowStatBitMask); | |
1665 | return IX_QMGR_Q_OVERFLOW; | |
1666 | } | |
1667 | } | |
1668 | ||
1669 | return IX_SUCCESS; | |
1670 | } | |
1671 | #endif | |
1672 | ||
1673 | /** | |
1674 | * @ingroup IxQMgrAPI | |
1675 | * | |
1676 | * @fn ixQMgrQPoke (IxQMgrQId qId, | |
1677 | unsigned int entryIndex, | |
1678 | UINT32 *entry) | |
1679 | * | |
1680 | * @brief Write an entry to a queue without moving the write pointer. | |
1681 | * | |
1682 | * This function modifies an entry in a queue. The entry is modified directly | |
1683 | * in AQM SRAM and not using the queue access registers. The entry is NOT added to the | |
1684 | * queue and the read/write pointers are unchanged. | |
1685 | * N.B: The queue should not be accessed when this function is called. | |
1686 | * | |
1687 | * @param qId @ref IxQMgrQId [in] - the queue identifier. | |
1688 | * @param entryIndex unsigned int [in] - index of entry in queue in the range | |
1689 | * [0].......[current number of entries in queue]. | |
1690 | * @param *entry UINT32 [in] - pointer to the entry word(s). | |
1691 | * | |
1692 | * @return @li IX_SUCCESS, entry was successfully modified. | |
1693 | * @return @li IX_QMGR_PARAMETER_ERROR, invalid paramter(s). | |
1694 | * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId. | |
1695 | * @return @li IX_QMGR_ENTRY_INDEX_OUT_OF_BOUNDS, an entry does not exist at | |
1696 | * specified index. | |
1697 | * @return @li IX_FAIL, failed to modify the queue entry. | |
1698 | */ | |
1699 | PUBLIC IX_STATUS | |
1700 | ixQMgrQPoke (IxQMgrQId qId, | |
1701 | unsigned int entryIndex, | |
1702 | UINT32 *entry); | |
1703 | ||
1704 | /** | |
1705 | * | |
1706 | * @ingroup IxQMgrAPI | |
1707 | * | |
1708 | * @fn ixQMgrQNumEntriesGet (IxQMgrQId qId, | |
1709 | unsigned *numEntries) | |
1710 | * | |
1711 | * @brief Get a snapshot of the number of entries in a queue. | |
1712 | * | |
1713 | * This function gets the number of entries in a queue. | |
1714 | * | |
1715 | * @param qId @ref IxQMgrQId [in] qId - the queue idenfifier | |
1716 | * @param *numEntries unsigned [out] - the number of entries in a queue | |
1717 | * | |
1718 | * @return @li IX_SUCCESS, got the number of entries for the queue | |
1719 | * @return @li IX_QMGR_PARAMETER_ERROR, invalid paramter(s). | |
1720 | * @return @li IX_QMGR_Q_NOT_CONFIGURED, the specified qId has not been configured | |
1721 | * @return @li IX_QMGR_WARNING, could not determine num entries at this time | |
1722 | * | |
1723 | */ | |
1724 | PUBLIC IX_STATUS | |
1725 | ixQMgrQNumEntriesGet (IxQMgrQId qId, | |
1726 | unsigned *numEntries); | |
1727 | ||
1728 | /** | |
1729 | * | |
1730 | * @ingroup IxQMgrAPI | |
1731 | * | |
1732 | * @fn ixQMgrQStatusGetWithChecks (IxQMgrQId qId, | |
1733 | IxQMgrQStatus *qStatus) | |
1734 | * | |
1735 | * @brief Get a queues status. | |
1736 | * | |
1737 | * This function reads the specified queues status. A queues status is defined | |
1738 | * by its status flags. For queues 0-31 these flags are E,NE,NF,F. For | |
1739 | * queues 32-63 these flags are NE and F. | |
1740 | * | |
1741 | * @param qId @ref IxQMgrQId [in] - the queue identifier. | |
1742 | * @param &qStatus @ref IxQMgrQStatus [out] - the status of the specified queue. | |
1743 | * | |
1744 | * @return @li IX_SUCCESS, queue status was successfully read. | |
1745 | * @return @li IX_QMGR_Q_NOT_CONFIGURED, the specified qId has not been configured | |
1746 | * @return @li IX_QMGR_PARAMETER_ERROR, invalid paramter. | |
1747 | * | |
1748 | */ | |
1749 | PUBLIC IX_STATUS | |
1750 | ixQMgrQStatusGetWithChecks (IxQMgrQId qId, | |
1751 | IxQMgrQStatus *qStatus); | |
1752 | ||
1753 | /** | |
1754 | * | |
1755 | * @ingroup IxQMgrAPI | |
1756 | * | |
1757 | * @fn ixQMgrQStatusGet (IxQMgrQId qId, | |
1758 | IxQMgrQStatus *qStatus) | |
1759 | * | |
1760 | * @brief Fast get of a queue's status. | |
1761 | * | |
1762 | * This function is a streamlined version of ixQMgrQStatusGetWithChecks(), but | |
1763 | * performs essentially the same task. It reads the specified queue's status. | |
1764 | * A queues status is defined by its status flags. For queues 0-31 these flags | |
1765 | * are E,NE,NF,F. For queues 32-63 these flags are NE and F. | |
1766 | * | |
1767 | * @note - This function is inlined, to reduce unnecessary function call | |
1768 | * overhead. It does not perform any parameter checks, or update any | |
1769 | * statistics. Also, it does not check that the queue specified by qId has | |
1770 | * been configured. It simply reads the specified queue's status. | |
1771 | * | |
1772 | * @param qId @ref IxQMgrQId [in] - the queue identifier. | |
1773 | * @param *qStatus @ref IxQMgrQStatus [out] - the status of the specified queue. | |
1774 | * | |
1775 | * @return @li void. | |
1776 | * | |
1777 | */ | |
1778 | ||
1779 | #ifdef NO_INLINE_APIS | |
1780 | PUBLIC IX_STATUS | |
1781 | ixQMgrQStatusGet (IxQMgrQId qId, | |
1782 | IxQMgrQStatus *qStatus); | |
1783 | #else | |
1784 | extern UINT32 ixQMgrAqmIfQueLowStatRegAddr[]; | |
1785 | extern UINT32 ixQMgrAqmIfQueLowStatBitsOffset[]; | |
1786 | extern UINT32 ixQMgrAqmIfQueLowStatBitsMask; | |
1787 | extern UINT32 ixQMgrAqmIfQueUppStat0RegAddr; | |
1788 | extern UINT32 ixQMgrAqmIfQueUppStat1RegAddr; | |
1789 | extern UINT32 ixQMgrAqmIfQueUppStat0BitMask[]; | |
1790 | extern UINT32 ixQMgrAqmIfQueUppStat1BitMask[]; | |
1791 | ||
1792 | IX_QMGR_INLINE PUBLIC IX_STATUS | |
1793 | ixQMgrQStatusGet (IxQMgrQId qId, | |
1794 | IxQMgrQStatus *qStatus); | |
1795 | #endif /* endif NO_INLINE_APIS */ | |
1796 | ||
1797 | IX_QMGR_INLINE PUBLIC IX_STATUS | |
1798 | ixQMgrQStatusGet (IxQMgrQId qId, | |
1799 | IxQMgrQStatus *qStatus) | |
1800 | #ifdef NO_INLINE_APIS | |
1801 | ; | |
1802 | #else | |
1803 | { | |
1804 | /* read the status of a queue in the range 0-31 */ | |
1805 | if (qId < IX_QMGR_MIN_QUEUPP_QID) | |
1806 | { | |
1807 | volatile UINT32 *lowStatRegAddr = (UINT32*)ixQMgrAqmIfQueLowStatRegAddr[qId]; | |
1808 | ||
1809 | UINT32 lowStatBitsOffset = ixQMgrAqmIfQueLowStatBitsOffset[qId]; | |
1810 | UINT32 lowStatBitsMask = ixQMgrAqmIfQueLowStatBitsMask; | |
1811 | ||
1812 | /* read the status register for this queue */ | |
1813 | *qStatus = IX_QMGR_INLINE_READ_LONG(lowStatRegAddr); | |
1814 | ||
1815 | /* mask out the status bits relevant only to this queue */ | |
1816 | *qStatus = (*qStatus >> lowStatBitsOffset) & lowStatBitsMask; | |
1817 | ||
1818 | } | |
1819 | else /* read status of a queue in the range 32-63 */ | |
1820 | { | |
1821 | ||
1822 | volatile UINT32 *qNearEmptyStatRegAddr = (UINT32*)ixQMgrAqmIfQueUppStat0RegAddr; | |
1823 | volatile UINT32 *qFullStatRegAddr = (UINT32*)ixQMgrAqmIfQueUppStat1RegAddr; | |
1824 | int maskIndex = qId - IX_QMGR_MIN_QUEUPP_QID; | |
1825 | UINT32 qNearEmptyStatBitMask = ixQMgrAqmIfQueUppStat0BitMask[maskIndex]; | |
1826 | UINT32 qFullStatBitMask = ixQMgrAqmIfQueUppStat1BitMask[maskIndex]; | |
1827 | ||
1828 | /* Reset the status bits */ | |
1829 | *qStatus = 0; | |
1830 | ||
1831 | /* Check if the queue is nearly empty */ | |
1832 | if (IX_QMGR_INLINE_READ_LONG(qNearEmptyStatRegAddr) & qNearEmptyStatBitMask) | |
1833 | { | |
1834 | *qStatus |= IX_QMGR_Q_STATUS_NE_BIT_MASK; | |
1835 | } | |
1836 | ||
1837 | /* Check if the queue is full */ | |
1838 | if (IX_QMGR_INLINE_READ_LONG(qFullStatRegAddr) & qFullStatBitMask) | |
1839 | { | |
1840 | *qStatus |= IX_QMGR_Q_STATUS_F_BIT_MASK; | |
1841 | } | |
1842 | } | |
1843 | return IX_SUCCESS; | |
1844 | } | |
1845 | #endif | |
1846 | ||
1847 | /* ------------------------------------------------------------ | |
1848 | Queue dispatch related functions | |
1849 | ---------------------------------------------------------- */ | |
1850 | ||
1851 | /** | |
1852 | * | |
1853 | * @ingroup IxQMgrAPI | |
1854 | * | |
1855 | * @fn ixQMgrDispatcherPrioritySet (IxQMgrQId qId, | |
1856 | IxQMgrPriority priority) | |
1857 | * | |
1858 | * @brief Set the dispatch priority of a queue. | |
1859 | * | |
1860 | * This function is called to set the dispatch priority of queue. The effect of | |
1861 | * this function is to add a priority change request to a queue. This queue is | |
1862 | * serviced by @a ixQMgrDispatcherLoopRunA0, @a ixQMgrDispatcherLoopRunB0 or | |
1863 | * @a ixQMgrDispatcherLoopRunB0LLP. | |
1864 | * | |
1865 | * This function is re-entrant. and can be used from an interrupt context | |
1866 | * | |
1867 | * @param qId @ref IxQMgrQId [in] - the queue identifier | |
1868 | * @param priority @ref IxQMgrPriority [in] - the new queue dispatch priority | |
1869 | * | |
1870 | * @return @li IX_SUCCESS, priority change request is queued | |
1871 | * @return @li IX_QMGR_Q_NOT_CONFIGURED, the specified qId has not been configured | |
1872 | * @return @li IX_QMGR_Q_INVALID_PRIORITY, specified priority is invalid | |
1873 | * | |
1874 | */ | |
1875 | PUBLIC IX_STATUS | |
1876 | ixQMgrDispatcherPrioritySet (IxQMgrQId qId, | |
1877 | IxQMgrPriority priority); | |
1878 | /** | |
1879 | * | |
1880 | * @ingroup IxQMgrAPI | |
1881 | * | |
1882 | * @fn ixQMgrNotificationEnable (IxQMgrQId qId, | |
1883 | IxQMgrSourceId sourceId) | |
1884 | * | |
1885 | * @brief Enable notification on a queue for a specified queue source flag. | |
1886 | * | |
1887 | * This function is called by a client of the QMgr to enable notifications on a | |
1888 | * specified condition. | |
1889 | * If the condition for the notification is set after the client has called this | |
1890 | * function but before the function has enabled the interrupt source, then the | |
1891 | * notification will not occur. | |
1892 | * For queues 32-63 the notification source is fixed to the NE(Nearly Empty) flag | |
1893 | * and cannot be changed so the sourceId parameter is ignored for these queues. | |
1894 | * The status register is read before the notofication is enabled and is read again | |
1895 | * after the notification has been enabled, if they differ then the warning status | |
1896 | * is returned. | |
1897 | * | |
1898 | * This function is re-entrant. and can be used from an interrupt context | |
1899 | * | |
1900 | * @param qId @ref IxQMgrQId [in] - the queue identifier | |
1901 | * @param sourceId @ref IxQMgrSourceId [in] - the interrupt src condition identifier | |
1902 | * | |
1903 | * @return @li IX_SUCCESS, the interrupt has been enabled for the specified source | |
1904 | * @return @li IX_QMGR_Q_NOT_CONFIGURED, the specified qId has not been configured | |
1905 | * @return @li IX_QMGR_INVALID_INT_SOURCE_ID, interrupt source invalid for this queue | |
1906 | * @return @li IX_QMGR_WARNING, the status register may not be constistent | |
1907 | * | |
1908 | */ | |
1909 | PUBLIC IX_STATUS | |
1910 | ixQMgrNotificationEnable (IxQMgrQId qId, | |
1911 | IxQMgrSourceId sourceId); | |
1912 | ||
1913 | /** | |
1914 | * @ingroup IxQMgrAPI | |
1915 | * | |
1916 | * @fn ixQMgrNotificationDisable (IxQMgrQId qId) | |
1917 | * | |
1918 | * @brief Disable notifications on a queue. | |
1919 | * | |
1920 | * This function is called to disable notifications on a specified queue. | |
1921 | * | |
1922 | * This function is re-entrant. and can be used from an interrupt context | |
1923 | * | |
1924 | * @param qId @ref IxQMgrQId [in] - the queue identifier | |
1925 | * | |
1926 | * @return @li IX_SUCCESS, the interrupt has been disabled | |
1927 | * @return @li IX_QMGR_Q_NOT_CONFIGURED, the specified qId has not been configured | |
1928 | * | |
1929 | */ | |
1930 | PUBLIC IX_STATUS | |
1931 | ixQMgrNotificationDisable (IxQMgrQId qId); | |
1932 | ||
1933 | /** | |
1934 | * | |
1935 | * @ingroup IxQMgrAPI | |
1936 | * | |
1937 | * @fn ixQMgrDispatcherLoopRunA0 (IxQMgrDispatchGroup group) | |
1938 | * | |
1939 | * @brief Run the callback dispatcher. | |
1940 | * | |
1941 | * This function runs the dispatcher for a group of queues. | |
1942 | * Callbacks are made for interrupts that have occurred on queues within | |
1943 | * the group that have registered callbacks. The order in which queues are | |
1944 | * serviced depends on the queue priorities set by the client. | |
1945 | * This function may be called from interrupt or task context. | |
1946 | * For optimisations that were introduced in IXP42X B0 and supported IXP46X | |
1947 | * the @a ixQMgrDispatcherLoopRunB0, or @a ixQMgrDispatcherLoopRunB0LLP | |
1948 | * should be used. | |
1949 | * | |
1950 | * This function is not re-entrant. | |
1951 | * | |
1952 | * @param group @ref IxQMgrDispatchGroup [in] - the group of queues over which the | |
1953 | * dispatcher will run | |
1954 | * | |
1955 | * @return @li void | |
1956 | * | |
1957 | * @note This function may be called from interrupt or task context. | |
1958 | * However, for optimal performance the choice of context depends also on the | |
1959 | * operating system used. | |
1960 | * | |
1961 | */ | |
1962 | PUBLIC void | |
1963 | ixQMgrDispatcherLoopRunA0 (IxQMgrDispatchGroup group); | |
1964 | ||
1965 | /** | |
1966 | * | |
1967 | * @ingroup IxQMgrAPI | |
1968 | * | |
1969 | * @fn ixQMgrDispatcherLoopRunB0 (IxQMgrDispatchGroup group) | |
1970 | * | |
1971 | * @brief Run the callback dispatcher. | |
1972 | * | |
1973 | * The enhanced version of @a ixQMgrDispatcherLoopRunA0 that is optimised for | |
1974 | * features introduced in IXP42X B0 silicon and supported on IXP46X. | |
1975 | * This is the default dispatcher for IXP42X B0 and IXP46X silicon. | |
1976 | * The function runs the dispatcher for a group of queues. | |
1977 | * Callbacks are made for interrupts that have occurred on queues within | |
1978 | * the group that have registered callbacks. The order in which queues are | |
1979 | * serviced depends on the queue priorities set by the client. | |
1980 | * This function may be called from interrupt or task context. | |
1981 | * | |
1982 | * This function is not re-entrant. | |
1983 | * | |
1984 | * @param group @ref IxQMgrDispatchGroup [in] - the group of queues over which the | |
1985 | * dispatcher will run | |
1986 | * | |
1987 | * @return @li void | |
1988 | * | |
1989 | * | |
1990 | * @note This function may be called from interrupt or task context. | |
1991 | * However, for optimal performance the choice of context depends also on the | |
1992 | * operating system used. | |
1993 | * | |
1994 | */ | |
1995 | PUBLIC void | |
1996 | ixQMgrDispatcherLoopRunB0 (IxQMgrDispatchGroup group); | |
1997 | ||
1998 | /** | |
1999 | * | |
2000 | * @ingroup IxQMgrAPI | |
2001 | * | |
2002 | * @fn ixQMgrDispatcherLoopRunB0LLP (IxQMgrDispatchGroup group) | |
2003 | * | |
2004 | * @brief Run the callback dispatcher. | |
2005 | * | |
2006 | * This is a version of the optimised dispatcher for IXP42X B0 and IXP46X, | |
2007 | * @a ixQMgrDispatcherLoopRunB0, with added support for livelock prevention. | |
2008 | * This dispatcher will only be used for the IXP42X B0 or IXP46X silicon if | |
2009 | * feature control indicates that IX_FEATURECTRL_ORIGB0_DISPATCHER is set to | |
2010 | * IX_FEATURE_CTRL_SWCONFIG_DISABLED. Otherwise the @a ixQMgrDispatcherLoopRunB0 | |
2011 | * dispatcher will be used (Default). | |
2012 | * | |
2013 | * When this dispatcher notifies for a queue that is type | |
2014 | * IX_QMGR_TYPE_REALTIME_PERIODIC, notifications for queues that are set | |
2015 | * as type IX_QMGR_REALTIME_SPORADIC are not processed and disabled. | |
2016 | * This helps prevent any tasks resulting from the notification of the | |
2017 | * IX_QMGR_TYPE_REALTIME_PERIODIC type queue to being subject to livelock. | |
2018 | * The function runs the dispatcher for a group of queues. | |
2019 | * Callbacks are made for interrupts that have occurred on queues within | |
2020 | * the group that have registered callbacks. The order in which queues are | |
2021 | * serviced depends on their type along with the queue priorities set by the | |
2022 | * client. This function may be called from interrupt or task context. | |
2023 | * | |
2024 | * This function is not re-entrant. | |
2025 | * | |
2026 | * @param group @ref IxQMgrDispatchGroup [in] - the group of queues over which | |
2027 | * the dispatcher will run | |
2028 | * | |
2029 | * @return @li void | |
2030 | * | |
2031 | * @note This function may be called from interrupt or task context. | |
2032 | * However, for optimal performance the choice of context depends also on the | |
2033 | * operating system used. | |
2034 | * | |
2035 | */ | |
2036 | PUBLIC void | |
2037 | ixQMgrDispatcherLoopRunB0LLP (IxQMgrDispatchGroup group); | |
2038 | ||
2039 | /** | |
2040 | * | |
2041 | * @ingroup IxQMgrAPI | |
2042 | * | |
2043 | * @fn ixQMgrNotificationCallbackSet (IxQMgrQId qId, | |
2044 | IxQMgrCallback callback, | |
2045 | IxQMgrCallbackId callbackId) | |
2046 | * | |
2047 | * @brief Set the notification callback for a queue. | |
2048 | * | |
2049 | * This function sets the callback for the specified queue. This callback will | |
2050 | * be called by the dispatcher, and may be called in the context of a interrupt | |
2051 | * If callback has a value of NULL the previously registered callback, if one | |
2052 | * exists will be unregistered. | |
2053 | * | |
2054 | * @param qId @ref IxQMgrQId [in] - the queue idenfifier | |
2055 | * @param callback @ref IxQMgrCallback [in] - the callback registered for this queue | |
2056 | * @param callbackId @ref IxQMgrCallbackId [in] - the callback identifier | |
2057 | * | |
2058 | * @return @li IX_SUCCESS, the callback for the specified queue has been set | |
2059 | * @return @li IX_QMGR_Q_NOT_CONFIGURED, the specified qId has not been configured | |
2060 | * | |
2061 | */ | |
2062 | PUBLIC IX_STATUS | |
2063 | ixQMgrNotificationCallbackSet (IxQMgrQId qId, | |
2064 | IxQMgrCallback callback, | |
2065 | IxQMgrCallbackId callbackId); | |
2066 | ||
2067 | /** | |
2068 | * | |
2069 | * @ingroup IxQMgrAPI | |
2070 | * | |
2071 | * @fn ixQMgrDispatcherLoopGet (IxQMgrDispatcherFuncPtr *qDispatcherFuncPtr) | |
2072 | * | |
2073 | * @brief Get QMgr DispatcherLoopRun for respective silicon device | |
2074 | * | |
2075 | * This function gets a function pointer to ixQMgrDispatcherLoopRunA0() for IXP42X A0 | |
2076 | * Silicon. If the IXP42X B0 or 46X Silicon, the default is the ixQMgrDispatcherLoopRunB0() | |
2077 | * function, however if live lock prevention is enabled a function pointer to | |
2078 | * ixQMgrDispatcherLoopRunB0LLP() is given. | |
2079 | * | |
2080 | * @param *qDispatchFuncPtr @ref IxQMgrDispatcherFuncPtr [out] - | |
2081 | * the function pointer of QMgr Dispatcher | |
2082 | * | |
2083 | */ | |
2084 | PUBLIC void | |
2085 | ixQMgrDispatcherLoopGet (IxQMgrDispatcherFuncPtr *qDispatcherFuncPtr); | |
2086 | ||
2087 | /** | |
2088 | * | |
2089 | * @ingroup IxQMgrAPI | |
2090 | * | |
2091 | * @fn ixQMgrStickyInterruptRegEnable(void) | |
2092 | * | |
2093 | * @brief Enable AQM's sticky interrupt register behaviour only available | |
2094 | * on B0 Silicon. | |
2095 | * | |
2096 | * When AQM's sticky interrupt register is enabled, interrupt register bit will | |
2097 | * only be cleared when a '1' is written to interrupt register bit and the | |
2098 | * interrupting condition is satisfied, i.e.queue condition does not exist. | |
2099 | * | |
2100 | * @note This function must be called before any queue is enabled. | |
2101 | * Calling this function after queue is enabled will cause | |
2102 | * undefined results. | |
2103 | * | |
2104 | * @return none | |
2105 | * | |
2106 | */ | |
2107 | PUBLIC void | |
2108 | ixQMgrStickyInterruptRegEnable(void); | |
2109 | ||
2110 | ||
2111 | /** | |
2112 | * @ingroup IxQMgrAPI | |
2113 | * | |
2114 | * @fn ixQMgrCallbackTypeSet(IxQMgrQId qId, | |
2115 | IxQMgrType type) | |
2116 | * | |
2117 | * @brief Set the Callback Type of a queue. | |
2118 | * | |
2119 | * This function is only used for live lock prevention. | |
2120 | * This function allows the callback type of a queue to be set. The default for | |
2121 | * all queues is IX_QMGR_TYPE_REALTIME_OTHER. Setting the type to | |
2122 | * IX_QMGR_TYPE_REALTIME_SPORADIC means that this queue will have it's | |
2123 | * notifications disabled while there is a task associated with a | |
2124 | * queue of type IX_QMGR_TYPE_REALTIME_PERIODIC running. As live lock | |
2125 | * prevention operates on lower queues, this function should | |
2126 | * be called for lower queues only. | |
2127 | * This function is not re-entrant. | |
2128 | * | |
2129 | * @param qId @ref IxQMgrQId [in] - the queue identifier | |
2130 | * @param type @ref IxQMgrType [in] - the type of callback | |
2131 | * | |
2132 | * @return @li IX_SUCCESS, successfully set callback type for the queue entry | |
2133 | * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId | |
2134 | * @return @li IX_QMGR_PARAMETER_ERROR, invalid parameter(s). | |
2135 | * | |
2136 | */ | |
2137 | PUBLIC IX_STATUS | |
2138 | ixQMgrCallbackTypeSet(IxQMgrQId qId, | |
2139 | IxQMgrType type); | |
2140 | ||
2141 | /** | |
2142 | * @ingroup IxQMgrAPI | |
2143 | * | |
2144 | * @fn ixQMgrCallbackTypeGet(IxQMgrQId qId, | |
2145 | IxQMgrType *type) | |
2146 | * | |
2147 | * @brief Get the Callback Type of a queue. | |
2148 | * | |
2149 | * This function allows the callback type of a queue to be got. As live lock | |
2150 | * prevention operates on lower queues, this function should | |
2151 | * be called for lower queues only. | |
2152 | * This function is re-entrant. | |
2153 | * | |
2154 | * @param qId @ref IxQMgrQId [in] - the queue identifier | |
2155 | * @param *type @ref IxQMgrType [out] - the type of callback | |
2156 | * | |
2157 | * @return @li IX_SUCCESS, successfully set callback type for the queue entry | |
2158 | * @return @li IX_QMGR_Q_NOT_CONFIGURED, queue not configured for this QId | |
2159 | * @return @li IX_QMGR_PARAMETER_ERROR, invalid parameter(s) | |
2160 | * | |
2161 | */ | |
2162 | PUBLIC IX_STATUS | |
2163 | ixQMgrCallbackTypeGet(IxQMgrQId qId, | |
2164 | IxQMgrType *type); | |
2165 | ||
2166 | /** | |
2167 | * @ingroup IxQMgrAPI | |
2168 | * | |
2169 | * @fn ixQMgrPeriodicDone(void) | |
2170 | * | |
2171 | * @brief Indicate that the Periodic task is completed for LLP | |
2172 | * | |
2173 | * This function is used as part of live lock prevention. | |
2174 | * A periodic task is a task that results from a queue that | |
2175 | * is set as type IX_QMGR_TYPE_REALTIME_PERIODIC. This function | |
2176 | * should be called to indicate to the dispatcher that the | |
2177 | * the periodic task is completed. This ensures that the notifications | |
2178 | * for queues set as type sporadic queues are re-enabled. | |
2179 | * This function is re-entrant. | |
2180 | * | |
2181 | */ | |
2182 | PUBLIC void | |
2183 | ixQMgrPeriodicDone(void); | |
2184 | ||
2185 | ||
2186 | /** | |
2187 | * @ingroup IxQMgrAPI | |
2188 | * | |
2189 | * @fn ixQMgrLLPShow(int resetStats) | |
2190 | * | |
2191 | * @brief Print out the live lock prevention statistics when in debug mode. | |
2192 | * | |
2193 | * This function prints out statistics related to the livelock. These | |
2194 | * statistics are only collected in debug mode. | |
2195 | * This function is not re-entrant. | |
2196 | * | |
2197 | * @param resetStats @ref int [in] - if set the the stats are reset. | |
2198 | * | |
2199 | */ | |
2200 | PUBLIC void | |
2201 | ixQMgrLLPShow(int resetStats); | |
2202 | ||
2203 | ||
2204 | #endif /* IXQMGR_H */ | |
2205 | ||
2206 | /** | |
2207 | * @} defgroup IxQMgrAPI | |
2208 | */ | |
2209 | ||
2210 |