1 /******************************************************************************
3 © 1995-2003, 2004, 2005-2011 Freescale Semiconductor, Inc.
6 This is proprietary source code of Freescale Semiconductor Inc.,
7 and its use is subject to the NetComm Device Drivers EULA.
8 The copyright notice above does not evidence any actual or intended
9 publication of such source code.
11 ALTERNATIVELY, redistribution and use in source and binary forms, with
12 or without modification, are permitted provided that the following
14 * Redistributions of source code must retain the above copyright
15 notice, this list of conditions and the following disclaimer.
16 * Redistributions in binary form must reproduce the above copyright
17 notice, this list of conditions and the following disclaimer in the
18 documentation and/or other materials provided with the distribution.
19 * Neither the name of Freescale Semiconductor nor the
20 names of its contributors may be used to endorse or promote products
21 derived from this software without specific prior written permission.
23 THIS SOFTWARE IS PROVIDED BY Freescale Semiconductor ``AS IS'' AND ANY
24 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
25 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
26 DISCLAIMED. IN NO EVENT SHALL Freescale Semiconductor BE LIABLE FOR ANY
27 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
28 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
29 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
30 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
31 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
32 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
35 **************************************************************************/
36 /******************************************************************************
39 @Description QM & Portal API
40 *//***************************************************************************/
44 #include "error_ext.h"
50 /**************************************************************************//**
51 @Group QM_grp Queue Manager API
53 @Description QM API functions, definitions and enums.
56 *//***************************************************************************/
58 /**************************************************************************//**
59 @Description This callback type is used when receiving frame.
61 User provides this function. Driver invokes it.
63 @Param[in] h_App A user argument to the callback
64 @Param[in] h_QmFqr A handle to an QM-FQR Module.
65 @Param[in] fqidOffset fqid offset from the FQR's fqid base.
66 @Param[in] p_Frame The Received Frame
68 @Retval e_RX_STORE_RESPONSE_CONTINUE - order the driver to continue Rx
69 operation for all ready data.
70 @Retval e_RX_STORE_RESPONSE_PAUSE - order the driver to stop Rx operation.
72 @Cautions p_Frame is local parameter; i.e. users must NOT access or use
73 this parameter in any means outside this callback context.
74 *//***************************************************************************/
75 typedef e_RxStoreResponse (t_QmReceivedFrameCallback)(t_Handle h_App,
81 /**************************************************************************//**
82 @Description This callback type is used when the FQR is completely was drained.
84 User provides this function. Driver invokes it.
86 @Param[in] h_App A user argument to the callback
87 @Param[in] h_QmFqr A handle to an QM-FQR Module.
89 @Retval E_OK on success; Error code otherwise.
90 *//***************************************************************************/
91 typedef t_Error (t_QmFqrDrainedCompletionCB)(t_Handle h_App,
94 /**************************************************************************//**
95 @Description QM Rejection code enum
96 *//***************************************************************************/
97 typedef enum e_QmRejectionCode
101 e_QM_RC_CG_TAILDROP, /**< This frames was rejected due to congestion
102 group taildrop situation */
103 e_QM_RC_CG_WRED, /**< This frames was rejected due to congestion
104 group WRED situation */
105 e_QM_RC_FQ_TAILDROP /**< This frames was rejected due to FQID TD
108 e_QM_RC_ORPWINDOW_EARLY
109 e_QM_RC_ORPWINDOW_LATE
110 e_QM_RC_ORPWINDOW_RETIRED */
113 /**************************************************************************//**
114 @Description QM Rejected frame information
115 *//***************************************************************************/
116 typedef struct t_QmRejectedFrameInfo
118 e_QmRejectionCode rejectionCode; /**< Rejection code */
123 uint8_t cgId; /**< congestion group id*/
124 } cg; /**< rejection parameters when rejectionCode =
125 e_QM_RC_CG_TAILDROP or e_QM_RC_CG_WRED. */
127 } t_QmRejectedFrameInfo;
129 /**************************************************************************//**
130 @Description This callback type is used when receiving rejected frames.
132 User provides this function. Driver invokes it.
134 @Param[in] h_App A user argument to the callback
135 @Param[in] h_QmFqr A handle to an QM-FQR Module.
136 @Param[in] fqidOffset fqid offset from the FQR's fqid base.
137 @Param[in] p_Frame The Rejected Frame
138 @Param[in] p_QmRejectedFrameInfo Rejected Frame information
140 @Retval e_RX_STORE_RESPONSE_CONTINUE - order the driver to continue Rx
141 operation for all ready data.
142 @Retval e_RX_STORE_RESPONSE_PAUSE - order the driver to stop Rx operation.
144 @Cautions p_Frame is local parameter; i.e. users must NOT access or use
145 this parameter in any means outside this callback context.
146 *//***************************************************************************/
147 typedef e_RxStoreResponse (t_QmRejectedFrameCallback)(t_Handle h_App,
152 t_QmRejectedFrameInfo *p_QmRejectedFrameInfo);
156 /**************************************************************************//**
157 @Group QM_lib_grp QM common API
159 @Description QM common API functions, definitions and enums.
162 *//***************************************************************************/
164 /**************************************************************************//**
165 @Description QM Exceptions
166 *//***************************************************************************/
167 typedef enum e_QmExceptions {
168 e_QM_EX_CORENET_INITIATOR_DATA = 0, /**< Initiator Data Error */
169 e_QM_EX_CORENET_TARGET_DATA, /**< CoreNet Target Data Error */
170 e_QM_EX_CORENET_INVALID_TARGET_TRANSACTION, /**< Invalid Target Transaction */
171 e_QM_EX_PFDR_THRESHOLD, /**< PFDR Low Watermark Interrupt */
172 e_QM_EX_PFDR_ENQUEUE_BLOCKED, /**< PFDR Enqueues Blocked Interrupt */
173 e_QM_EX_SINGLE_ECC, /**< Single Bit ECC Error Interrupt */
174 e_QM_EX_MULTI_ECC, /**< Multi Bit ECC Error Interrupt */
175 e_QM_EX_INVALID_COMMAND, /**< Invalid Command Verb Interrupt */
176 e_QM_EX_DEQUEUE_DCP, /**< Invalid Dequeue Direct Connect Portal Interrupt */
177 e_QM_EX_DEQUEUE_FQ, /**< Invalid Dequeue FQ Interrupt */
178 e_QM_EX_DEQUEUE_SOURCE, /**< Invalid Dequeue Source Interrupt */
179 e_QM_EX_DEQUEUE_QUEUE, /**< Invalid Dequeue Queue Interrupt */
180 e_QM_EX_ENQUEUE_OVERFLOW, /**< Invalid Enqueue Overflow Interrupt */
181 e_QM_EX_ENQUEUE_STATE, /**< Invalid Enqueue State Interrupt */
182 e_QM_EX_ENQUEUE_CHANNEL, /**< Invalid Enqueue Channel Interrupt */
183 e_QM_EX_ENQUEUE_QUEUE, /**< Invalid Enqueue Queue Interrupt */
184 e_QM_EX_CG_STATE_CHANGE /**< CG change state notification */
187 /**************************************************************************//**
188 @Group QM_init_grp QM (common) Initialization Unit
190 @Description QM (common) Initialization Unit
193 *//***************************************************************************/
195 /**************************************************************************//**
196 @Function t_QmExceptionsCallback
198 @Description Exceptions user callback routine, will be called upon an
199 exception passing the exception identification.
201 @Param[in] h_App - User's application descriptor.
202 @Param[in] exception - The exception.
203 *//***************************************************************************/
204 typedef void (t_QmExceptionsCallback) ( t_Handle h_App,
205 e_QmExceptions exception);
207 /**************************************************************************//**
208 @Description Frame's Type to poll
209 *//***************************************************************************/
210 typedef enum e_QmPortalPollSource {
211 e_QM_PORTAL_POLL_SOURCE_DATA_FRAMES = 0, /**< Poll only data frames */
212 e_QM_PORTAL_POLL_SOURCE_CONTROL_FRAMES, /**< Poll only control frames */
213 e_QM_PORTAL_POLL_SOURCE_BOTH /**< Poll both */
214 } e_QmPortalPollSource;
216 /**************************************************************************//**
217 @Description structure representing QM contextA of FQ initialization parameters
218 Note that this is only "space-holder" for the Context-A. The "real"
219 Context-A is described in each specific driver (E.g. FM driver
220 has its own Context-A API).
221 *//***************************************************************************/
223 uint32_t res[2]; /**< reserved size for context-a */
226 /**************************************************************************//**
227 @Description structure representing QM contextB of FQ initialization parameters
228 Note that this is only "space-holder" for the Context-B. The "real"
229 Context-B is described in each specific driver (E.g. FM driver
230 has its own Context-B API).
231 *//***************************************************************************/
232 typedef uint32_t t_QmContextB;
234 /**************************************************************************//**
235 @Description structure representing QM initialization parameters
236 *//***************************************************************************/
238 uint8_t guestId; /**< QM Partition Id */
240 uintptr_t baseAddress; /**< Qm base address (virtual)
241 NOTE: this parameter relevant only for BM in master mode ('guestId'=NCSW_MASTER_ID). */
242 uintptr_t swPortalsBaseAddress; /**< QM Software Portals Base Address (virtual) */
243 uint16_t liodn; /**< This value is attached to every transaction initiated by QMan when accessing its private data structures */
244 uint32_t totalNumOfFqids; /**< Total number of frame-queue-ids in the system */
245 uint32_t fqdMemPartitionId; /**< FQD's mem partition id;
246 NOTE: The memory partition must be non-cacheable and no-coherent area. */
247 uint32_t pfdrMemPartitionId; /**< PFDR's mem partition id;
248 NOTE: The memory partition must be non-cacheable and no-coherent area. */
249 t_QmExceptionsCallback *f_Exception; /**< An application callback routine to handle exceptions.*/
250 t_Handle h_App; /**< A handle to an application layer object; This handle will
251 be passed by the driver upon calling the above callbacks */
252 uintptr_t errIrq; /**< error interrupt line; NO_IRQ if interrupts not used */
253 uint32_t partFqidBase; /**< The first frame-queue-id dedicated to this partition.
254 NOTE: this parameter relevant only when working with multiple partitions. */
255 uint32_t partNumOfFqids; /**< Number of frame-queue-ids dedicated to this partition.
256 NOTE: this parameter relevant only when working with multiple partitions. */
257 uint16_t partCgsBase; /**< The first cgr dedicated to this partition.
258 NOTE: this parameter relevant only when working with multiple partitions. */
259 uint16_t partNumOfCgs; /**< Number of cgr's dedicated to this partition.
260 NOTE: this parameter relevant only when working with multiple partitions. */
264 /**************************************************************************//**
267 @Description Creates descriptor for the QM module.
269 The routine returns a handle (descriptor) to the QM object.
270 This descriptor must be passed as first parameter to all other
273 No actual initialization or configuration of QM hardware is
274 done by this routine.
276 @Param[in] p_QmParam - Pointer to data structure of parameters
278 @Retval Handle to the QM object, or NULL for Failure.
279 *//***************************************************************************/
280 t_Handle QM_Config(t_QmParam *p_QmParam);
282 /**************************************************************************//**
285 @Description Initializes the QM module
287 @Param[in] h_Qm - A handle to the QM module
289 @Return E_OK on success; Error code otherwise.
290 *//***************************************************************************/
291 t_Error QM_Init(t_Handle h_Qm);
293 /**************************************************************************//**
296 @Description Frees all resources that were assigned to the QM module.
298 Calling this routine invalidates the descriptor.
300 @Param[in] h_Qm - A handle to the QM module
302 @Return E_OK on success; Error code otherwise.
303 *//***************************************************************************/
304 t_Error QM_Free(t_Handle h_Qm);
307 /**************************************************************************//**
308 @Group QM_advanced_init_grp QM (common) Advanced Configuration Unit
310 @Description Configuration functions used to change default values.
313 *//***************************************************************************/
315 /**************************************************************************//**
316 @Description structure for defining DC portal ERN destination
317 *//***************************************************************************/
318 typedef struct t_QmDcPortalParams {
320 e_DpaaSwPortal swPortalId;
321 } t_QmDcPortalParams;
324 /**************************************************************************//**
325 @Function QM_ConfigRTFramesDepth
327 @Description Change the run-time frames depth (i.e. the maximum total number
328 of frames that may be inside QM at a certain time) from its default
329 configuration [30000].
331 @Param[in] h_Qm - A handle to the QM module
332 @Param[in] rtFramesDepth - run-time max num of frames.
334 @Return E_OK on success; Error code otherwise.
336 @Cautions Allowed only following QM_Config() and before QM_Init().
337 *//***************************************************************************/
338 t_Error QM_ConfigRTFramesDepth(t_Handle h_Qm, uint32_t rtFramesDepth);
340 /**************************************************************************//**
341 @Function QM_ConfigPfdrThreshold
343 @Description Change the pfdr threshold from its default
345 An interrupt if enables is asserted when the number of PFDRs is below this threshold.
347 @Param[in] h_Qm - A handle to the QM module
348 @Param[in] threshold - threshold value.
350 @Return E_OK on success; Error code otherwise.
352 @Cautions Allowed only following QM_Config() and before QM_Init().
353 *//***************************************************************************/
354 t_Error QM_ConfigPfdrThreshold(t_Handle h_Qm, uint32_t threshold);
356 /**************************************************************************//**
357 @Function QM_ConfigSfdrReservationThreshold
359 @Description Change the sfdr threshold from its default
362 @Param[in] h_Qm - A handle to the QM module
363 @Param[in] threshold - threshold value.
365 @Return E_OK on success; Error code otherwise.
367 @Cautions Allowed only following QM_Config() and before QM_Init().
368 *//***************************************************************************/
369 t_Error QM_ConfigSfdrReservationThreshold(t_Handle h_Qm, uint32_t threshold);
371 /**************************************************************************//**
372 @Function QM_ConfigErrorRejectionNotificationDest
374 @Description Change the destination of rejected frames for DC portals.
375 By default, depending on chip, some DC portals are set to reject
376 frames to HW and some to SW.
378 @Param[in] h_Qm - A handle to the QM module
379 @Param[in] id - DC Portal id.
380 @Param[in] p_Params - Destination parameters.
382 @Return E_OK on success; Error code otherwise.
384 @Cautions Allowed only following QM_Config() and before QM_Init().
385 *//***************************************************************************/
386 t_Error QM_ConfigErrorRejectionNotificationDest(t_Handle h_Qm, e_DpaaDcPortal id, t_QmDcPortalParams *p_Params);
388 /** @} */ /* end of QM_advanced_init_grp group */
389 /** @} */ /* end of QM_init_grp group */
392 /**************************************************************************//**
393 @Group QM_runtime_control_grp QM (common) Runtime Control Unit
395 @Description QM (common) Runtime control unit API functions, definitions and enums.
398 *//***************************************************************************/
400 /**************************************************************************//**
401 @Description enum for defining QM counters
402 *//***************************************************************************/
403 typedef enum e_QmCounters {
404 e_QM_COUNTERS_SFDR_IN_USE = 0, /**< Total Single Frame Descriptor Record (SFDR) currently in use */
405 e_QM_COUNTERS_PFDR_IN_USE, /**< Total Packed Frame Descriptor Record (PFDR) currently in use */
406 e_QM_COUNTERS_PFDR_FREE_POOL /**< Total Packed Frame Descriptor Record (PFDR) Free Pool Count in external memory */
409 /**************************************************************************//**
410 @Description structure for returning revision information
411 *//***************************************************************************/
412 typedef struct t_QmRevisionInfo {
413 uint8_t majorRev; /**< Major revision */
414 uint8_t minorRev; /**< Minor revision */
417 /**************************************************************************//**
418 @Description structure representing QM FQ-Range reservation parameters
419 *//***************************************************************************/
420 typedef struct t_QmRsrvFqrParams {
421 bool useForce; /**< TRUE - force reservation of specific fqids;
422 FALSE - reserve several fqids */
423 uint32_t numOfFqids; /**< number of fqids to be reserved. */
426 uint32_t align; /**< alignment. will be used if useForce=FALSE */
429 uint32_t fqid; /**< the fqid base of the forced fqids. will be used if useForce=TRUE */
434 /**************************************************************************//**
435 @Description structure representing QM Error information
436 *//***************************************************************************/
437 typedef struct t_QmErrorInfo {
440 e_DpaaSwPortal swPortalId; /**< Sw Portal id */
441 e_DpaaDcPortal dcpId; /**< Dcp (hw Portal) id */
447 /**************************************************************************//**
448 @Function QM_ReserveQueues
450 @Description Request to Reserved queues for future use.
452 @Param[in] h_Qm - A handle to the QM Module.
453 @Param[in] p_QmFqrParams - A structure of parameters for defining the
454 desired queues parameters.
455 @Param[out] p_BaseFqid - base-fqid on success; '0' code otherwise.
457 @Return E_OK on success;
459 @Cautions Allowed only after QM_Init().
460 *//***************************************************************************/
461 t_Error QM_ReserveQueues(t_Handle h_Qm, t_QmRsrvFqrParams *p_QmFqrParams, uint32_t *p_BaseFqid);
463 #if (defined(DEBUG_ERRORS) && (DEBUG_ERRORS > 0))
464 /**************************************************************************//**
465 @Function QM_DumpRegs
467 @Description Dumps all QM registers
469 @Param[in] h_Qm - A handle to the QM Module.
471 @Return E_OK on success;
473 @Cautions Allowed only after QM_Init().
474 *//***************************************************************************/
475 t_Error QM_DumpRegs(t_Handle h_Qm);
476 #endif /* (defined(DEBUG_ERRORS) && ... */
478 /**************************************************************************//**
479 @Function QM_SetException
481 @Description Calling this routine enables/disables the specified exception.
483 @Param[in] h_Qm - A handle to the QM Module.
484 @Param[in] exception - The exception to be selected.
485 @Param[in] enable - TRUE to enable interrupt, FALSE to mask it.
487 @Return E_OK on success; Error code otherwise.
489 @Cautions Allowed only following QM_Init().
490 This routine should NOT be called from guest-partition
491 (i.e. guestId != NCSW_MASTER_ID)
492 *//***************************************************************************/
493 t_Error QM_SetException(t_Handle h_Qm, e_QmExceptions exception, bool enable);
495 /**************************************************************************//**
496 @Function QM_ErrorIsr
498 @Description QM interrupt-service-routine for errors.
500 @Param[in] h_Qm - A handle to the QM module
502 @Cautions Allowed only following QM_Init().
503 This routine should NOT be called from guest-partition
504 (i.e. guestId != NCSW_MASTER_ID)
505 *//***************************************************************************/
506 void QM_ErrorIsr(t_Handle h_Qm);
508 /**************************************************************************//**
509 @Function QM_GetErrorInformation
511 @Description Reads the last error information.
513 @Param[in] h_Qm - A handle to the QM Module.
514 @Param[out] p_errInfo - the information will be loaded to this struct.
516 @Return E_OK on success; Error code otherwise.
518 @Cautions Allowed only following QM_Init().
519 This routine should NOT be called from guest-partition
520 (i.e. guestId != NCSW_MASTER_ID)
521 *//***************************************************************************/
522 t_Error QM_GetErrorInformation(t_Handle h_Qm, t_QmErrorInfo *p_errInfo);
524 /**************************************************************************//**
525 @Function QM_GetCounter
527 @Description Reads one of the QM counters.
529 @Param[in] h_Qm - A handle to the QM Module.
530 @Param[in] counter - The requested counter.
532 @Return Counter's current value.
534 @Cautions Allowed only following QM_Init().
535 *//***************************************************************************/
536 uint32_t QM_GetCounter(t_Handle h_Qm, e_QmCounters counter);
538 /**************************************************************************//**
539 @Function QM_GetRevision
541 @Description Returns the QM revision
543 @Param[in] h_Qm A handle to a QM Module.
544 @Param[out] p_QmRevisionInfo A structure of revision information parameters.
548 @Cautions Allowed only following QM_Init().
549 *//***************************************************************************/
550 t_Error QM_GetRevision(t_Handle h_Qm, t_QmRevisionInfo *p_QmRevisionInfo);
552 /** @} */ /* end of QM_runtime_control_grp group */
555 /**************************************************************************//**
556 @Group QM_runtime_data_grp QM (common) Runtime Data Unit
558 @Description QM (common) Runtime data unit API functions, definitions and enums.
561 *//***************************************************************************/
563 /**************************************************************************//**
566 @Description Poll frames from QM.
568 @Param[in] h_Qm - A handle to the QM module
569 @Param[in] source - The selected frames type to poll
571 @Return E_OK on success; Error code otherwise.
573 @Cautions Allowed only following QM_Init().
574 *//***************************************************************************/
575 t_Error QM_Poll(t_Handle h_Qm, e_QmPortalPollSource source);
577 /** @} */ /* end of QM_runtime_data_grp group */
578 /** @} */ /* end of QM_lib_grp group */
581 /**************************************************************************//**
582 @Group QM_portal_grp QM-Portal API
584 @Description QM common API functions, definitions and enums.
587 *//***************************************************************************/
589 /**************************************************************************//**
590 @Group QM_portal_init_grp QM-Portal Initialization Unit
592 @Description QM-Portal Initialization Unit
595 *//***************************************************************************/
597 /**************************************************************************//**
598 @Description structure representing QM-Portal Stash parameters
599 *//***************************************************************************/
601 uint8_t stashDestQueue; /**< This value is used to direct all stashing transactions initiated on behalf of this software portal
602 to the specific Stashing Request Queues (SRQ) */
603 uint8_t eqcr; /**< If 0, disabled. If 1, for every EQCR entry consumed by QMan a new stash transaction is performed.
604 If 2-7, after 2-7 EQCR entries being consumed by QMAN a new stash transaction is performed. */
605 bool eqcrHighPri; /**< EQCR entry stash transactions for this software portal will be signaled with higher priority. */
606 bool dqrr; /**< DQRR entry stash enable/disable */
607 uint16_t dqrrLiodn; /**< This value is attached to every transaction initiated by QMan when performing DQRR entry or EQCR_CI stashing
608 on behalf of this software portal */
609 bool dqrrHighPri; /**< DQRR entry stash transactions for this software portal will be signaled with higher priority. */
610 bool fdFq; /**< Dequeued Frame Data, Annotation, and FQ Context Stashing enable/disable */
611 uint16_t fdFqLiodn; /**< This value is attached to every transaction initiated by QMan when performing dequeued frame data and
612 annotation stashing, or FQ context stashing on behalf of this software portal */
613 bool fdFqHighPri; /**< Dequeued frame data, annotation, and FQ context stash transactions for this software portal will be signaled
614 with higher priority. */
615 bool fdFqDrop; /**< If True, Dequeued frame data, annotation, and FQ context stash transactions for this software portal will be dropped
616 by QMan if the target SRQ is almost full, to prevent QMan sequencer stalling. Stash transactions that are
617 dropped will result in a fetch from main memory when a core reads the addressed coherency granule.
618 If FALSE, Dequeued frame data, annotation, and FQ context stash transactions for this software portal will never be
619 dropped by QMan. If the target SRQ is full a sequencer will stall until each stash transaction can be completed. */
620 } t_QmPortalStashParam;
622 /**************************************************************************//**
623 @Description structure representing QM-Portal initialization parameters
624 *//***************************************************************************/
626 uintptr_t ceBaseAddress; /**< Cache-enabled base address (virtual) */
627 uintptr_t ciBaseAddress; /**< Cache-inhibited base address (virtual) */
628 t_Handle h_Qm; /**< Qm Handle */
629 e_DpaaSwPortal swPortalId; /**< Portal id */
630 uintptr_t irq; /**< portal interrupt line; used only if useIrq set to TRUE */
631 uint16_t fdLiodnOffset; /**< liodn to be used for all frames enqueued via this software portal */
632 t_QmReceivedFrameCallback *f_DfltFrame; /**< this callback will be called unless specific callback assigned to the FQ*/
633 t_QmRejectedFrameCallback *f_RejectedFrame; /**< this callback will be called for rejected frames. */
634 t_Handle h_App; /**< a handle to the upper layer; It will be passed by the driver upon calling the CB */
638 /**************************************************************************//**
639 @Function QM_PORTAL_Config
641 @Description Creates descriptor for a QM-Portal module.
643 The routine returns a handle (descriptor) to a QM-Portal object.
644 This descriptor must be passed as first parameter to all other
645 QM-Portal function calls.
647 No actual initialization or configuration of QM-Portal hardware is
648 done by this routine.
650 @Param[in] p_QmPortalParam - Pointer to data structure of parameters
652 @Retval Handle to a QM-Portal object, or NULL for Failure.
653 *//***************************************************************************/
654 t_Handle QM_PORTAL_Config(t_QmPortalParam *p_QmPortalParam);
656 /**************************************************************************//**
657 @Function QM_PORTAL_Init
659 @Description Initializes a QM-Portal module
661 @Param[in] h_QmPortal - A handle to a QM-Portal module
663 @Return E_OK on success; Error code otherwise.
664 *//***************************************************************************/
665 t_Error QM_PORTAL_Init(t_Handle h_QmPortal);
667 /**************************************************************************//**
668 @Function QM_PORTAL_Free
670 @Description Frees all resources that were assigned to a QM-Portal module.
672 Calling this routine invalidates the descriptor.
674 @Param[in] h_QmPortal - A handle to a QM-Portal module
676 @Return E_OK on success; Error code otherwise.
677 *//***************************************************************************/
678 t_Error QM_PORTAL_Free(t_Handle h_QmPortal);
680 /**************************************************************************//**
681 @Group QM_portal_advanced_init_grp QM-Portal Advanced Configuration Unit
683 @Description Configuration functions used to change default values.
686 *//***************************************************************************/
688 /**************************************************************************//**
689 @Function QM_PORTAL_ConfigDcaMode
691 @Description Change the Discrate Consumption Acknowledge mode
692 from its default configuration [FALSE].
694 @Param[in] h_QmPortal - A handle to a QM-Portal module
695 @Param[in] enable - Enable/Disable DCA mode
697 @Return E_OK on success; Error code otherwise.
699 @Cautions Allowed only following QM_PORTAL_Config() and before QM_PORTAL_Init().
700 *//***************************************************************************/
701 t_Error QM_PORTAL_ConfigDcaMode(t_Handle h_QmPortal, bool enable);
703 /**************************************************************************//**
704 @Function QM_PORTAL_ConfigStash
706 @Description Config the portal to active stash mode.
708 @Param[in] h_QmPortal - A handle to a QM-Portal module
709 @Param[in] p_StashParams - Pointer to data structure of parameters
711 @Return E_OK on success; Error code otherwise.
713 @Cautions Allowed only following QM_PORTAL_Config() and before QM_PORTAL_Init().
714 *//***************************************************************************/
715 t_Error QM_PORTAL_ConfigStash(t_Handle h_QmPortal, t_QmPortalStashParam *p_StashParams);
718 /**************************************************************************//**
719 @Function QM_PORTAL_ConfigPullMode
721 @Description Change the Pull Mode from its default configuration [FALSE].
723 @Param[in] h_QmPortal - A handle to a QM-Portal module
724 @Param[in] pullMode - When TRUE, the Portal will work in pull mode.
726 @Return E_OK on success; Error code otherwise.
728 @Cautions Allowed only following QM_PORTAL_Config() and before QM_PORTAL_Init().
729 *//***************************************************************************/
730 t_Error QM_PORTAL_ConfigPullMode(t_Handle h_QmPortal, bool pullMode);
732 /** @} */ /* end of QM_portal_advanced_init_grp group */
733 /** @} */ /* end of QM_portal_init_grp group */
736 /**************************************************************************//**
737 @Group QM_portal_runtime_control_grp QM-Portal Runtime Control Unit
739 @Description QM-Portal Runtime control unit API functions, definitions and enums.
742 *//***************************************************************************/
744 /**************************************************************************//**
745 @Function QM_PORTAL_AddPoolChannel
747 @Description Adding the pool channel to the SW-Portal's scheduler.
748 the sw-portal will get frames that came from the pool channel.
750 @Param[in] h_QmPortal - A handle to a QM-Portal module
751 @Param[in] poolChannelId - Pool channel id. must between '0' to QM_MAX_NUM_OF_POOL_CHANNELS
753 @Return E_OK on success; Error code otherwise.
755 @Cautions Allowed only following QM_PORTAL_Init().
756 *//***************************************************************************/
757 t_Error QM_PORTAL_AddPoolChannel(t_Handle h_QmPortal, uint8_t poolChannelId);
759 /** @} */ /* end of QM_portal_runtime_control_grp group */
762 /**************************************************************************//**
763 @Group QM_portal_runtime_data_grp QM-Portal Runtime Data Unit
765 @Description QM-Portal Runtime data unit API functions, definitions and enums.
768 *//***************************************************************************/
770 /**************************************************************************//**
771 @Description structure representing QM Portal Frame Info
772 *//***************************************************************************/
773 typedef struct t_QmPortalFrameInfo {
778 } t_QmPortalFrameInfo;
780 /**************************************************************************//**
781 @Function QM_PORTAL_Poll
783 @Description Poll frames from the specified sw-portal.
785 @Param[in] h_QmPortal - A handle to a QM-Portal module
786 @Param[in] source - The selected frames type to poll
788 @Return E_OK on success; Error code otherwise.
790 @Cautions Allowed only following QM_PORTAL_Init().
791 *//***************************************************************************/
792 t_Error QM_PORTAL_Poll(t_Handle h_QmPortal, e_QmPortalPollSource source);
794 /**************************************************************************//**
795 @Function QM_PORTAL_PollFrame
797 @Description Poll frames from the specified sw-portal. will poll only data frames
799 @Param[in] h_QmPortal - A handle to a QM-Portal module
800 @Param[out] p_frameInfo - A structure to hold the dequeued frame information
802 @Return E_OK on success; Error code otherwise.
804 @Cautions Allowed only following QM_PORTAL_Init().
805 *//***************************************************************************/
806 t_Error QM_PORTAL_PollFrame(t_Handle h_QmPortal, t_QmPortalFrameInfo *p_frameInfo);
809 /** @} */ /* end of QM_portal_runtime_data_grp group */
810 /** @} */ /* end of QM_portal_grp group */
813 /**************************************************************************//**
814 @Group QM_fqr_grp QM Frame-Queue-Range API
816 @Description QM-FQR API functions, definitions and enums.
819 *//***************************************************************************/
821 /**************************************************************************//**
822 @Group QM_fqr_init_grp QM-FQR Initialization Unit
824 @Description QM-FQR Initialization Unit
827 *//***************************************************************************/
830 /**************************************************************************//**
831 @Description structure representing QM FQ-Range congestion group parameters
832 *//***************************************************************************/
834 t_Handle h_QmCg; /**< A handle to the congestion group. */
835 int8_t overheadAccountingLength; /**< For each frame add this number for CG calculation
836 (may be negative), if 0 - disable feature */
837 uint32_t fqTailDropThreshold; /**< if not "0" - enable tail drop on this FQR */
838 } t_QmFqrCongestionAvoidanceParams;
840 /**************************************************************************//**
841 @Description structure representing QM FQ-Range initialization parameters
842 *//***************************************************************************/
844 t_Handle h_Qm; /**< A handle to a QM module */
845 t_Handle h_QmPortal; /**< A handle to a QM Portal Module;
846 will be used only for Init and Free routines;
847 NOTE : if NULL, assuming affinity */
848 bool initParked; /**< This FQ-Range will be initialize in park state (un-schedule) */
849 bool holdActive; /**< This FQ-Range can be parked (un-schedule);
850 This affects only on queues destined to software portals*/
851 bool preferInCache; /**< Prefer this FQ-Range to be in QMAN's internal cache for all states */
852 bool useContextAForStash;/**< This FQ-Range will use context A for stash */
855 uint8_t frameAnnotationSize;/**< Size of Frame Annotation to be stashed */
856 uint8_t frameDataSize; /**< Size of Frame Data to be stashed. */
857 uint8_t fqContextSize; /**< Size of FQ context to be stashed. */
858 uint64_t fqContextAddr; /**< 40 bit memory address containing the FQ context information to be stashed;
859 Must be cacheline-aligned */
861 t_QmContextA *p_ContextA; /**< context-A field to be written in the FQ structure */
863 t_QmContextB *p_ContextB; /**< context-B field to be written in the FQ structure;
864 Note that this field may be used for Tx queues only! */
865 e_QmFQChannel channel; /**< Qm Channel */
866 uint8_t wq; /**< Work queue within the channel */
867 bool shadowMode; /**< If TRUE, useForce MUST set to TRUE and numOfFqids MUST set to '1' */
868 uint32_t numOfFqids; /**< number of fqids to be allocated*/
869 bool useForce; /**< TRUE - force allocation of specific fqids;
870 FALSE - allocate several fqids */
873 uint32_t align; /**< alignment. will be used if useForce=FALSE */
876 uint32_t fqid; /**< the fqid base of the forced fqids. will be used if useForce=TRUE */
879 bool congestionAvoidanceEnable;
880 /**< TRUE to enable congestion avoidance mechanism */
881 t_QmFqrCongestionAvoidanceParams congestionAvoidanceParams;
882 /**< Parameters for congestion avoidance */
886 /**************************************************************************//**
887 @Function QM_FQR_Create
889 @Description Initializing and enabling a Frame-Queue-Range.
890 This routine should be called for adding an FQR.
892 @Param[in] p_QmFqrParams - A structure of parameters for defining the
893 desired queues parameters.
895 @Return A handle to the initialized FQR on success; NULL code otherwise.
897 @Cautions Allowed only following QM_Init().
898 *//***************************************************************************/
899 t_Handle QM_FQR_Create(t_QmFqrParams *p_QmFqrParams);
901 /**************************************************************************//**
902 @Function QM_FQR_Free
904 @Description Deleting and free all resources of an initialized FQR.
906 @Param[in] h_QmFqr - A handle to a QM-FQR Module.
908 @Return E_OK on success; Error code otherwise.
910 @Cautions Allowed only following QM_Init() and QM_FQR_Create() for this FQR.
911 *//***************************************************************************/
912 t_Error QM_FQR_Free(t_Handle h_QmFqr);
914 /**************************************************************************//**
915 @Function QM_FQR_FreeWDrain
917 @Description Deleting and free all resources of an initialized FQR
918 with the option of draining.
920 @Param[in] h_QmFqr - A handle to a QM-FQR Module.
921 @Param[in] f_CompletionCB - Pointer to a completion callback to be used in non-blocking mode.
922 @Param[in] deliverFrame - TRUE for deliver the drained frames to the user;
923 FALSE for not deliver the frames.
924 @Param[in] f_CallBack - Pointer to a callback to handle the delivered frames.
925 @Param[in] h_App - User's application descriptor.
927 @Return E_OK on success; Error code otherwise.
929 @Cautions Allowed only following QM_Init() and QM_FQR_Create() for this FQR.
930 *//***************************************************************************/
931 t_Error QM_FQR_FreeWDrain(t_Handle h_QmFqr,
932 t_QmFqrDrainedCompletionCB *f_CompletionCB,
934 t_QmReceivedFrameCallback *f_CallBack,
937 /** @} */ /* end of QM_fqr_init_grp group */
940 /**************************************************************************//**
941 @Group QM_fqr_runtime_control_grp QM-FQR Runtime Control Unit
943 @Description QM-FQR Runtime control unit API functions, definitions and enums.
946 *//***************************************************************************/
948 /**************************************************************************//**
949 @Description enum for defining QM-FQR counters
950 *//***************************************************************************/
951 typedef enum e_QmFqrCounters {
952 e_QM_FQR_COUNTERS_FRAME = 0, /**< Total number of frames on this frame queue */
953 e_QM_FQR_COUNTERS_BYTE /**< Total number of bytes in all frames on this frame queue */
956 /**************************************************************************//**
957 @Function QM_FQR_RegisterCB
959 @Description Register a callback routine to be called when a frame comes from this FQ-Range
961 @Param[in] h_QmFqr - A handle to a QM-FQR Module.
962 @Param[in] f_CallBack - An application callback
963 @Param[in] h_App - User's application descriptor
965 @Return E_OK on success; Error code otherwise.
967 @Cautions Allowed only following QM_FQR_Create().
968 *//***************************************************************************/
969 t_Error QM_FQR_RegisterCB(t_Handle h_QmFqr, t_QmReceivedFrameCallback *f_CallBack, t_Handle h_App);
971 /**************************************************************************//**
972 @Function QM_FQR_Resume
974 @Description Request to Re-Schedule this Fqid.
976 @Param[in] h_QmFqr - A handle to a QM-FQR Module.
977 @Param[in] h_QmPortal - A handle to a QM Portal Module;
978 NOTE : if NULL, assuming affinity.
979 @Param[in] fqidOffset - Fqid offset within the FQ-Range.
981 @Return E_OK on success; Error code otherwise.
983 @Cautions Allowed only following QM_FQR_Create().
984 *//***************************************************************************/
985 t_Error QM_FQR_Resume(t_Handle h_QmFqr, t_Handle h_QmPortal, uint32_t fqidOffset);
987 /**************************************************************************//**
988 @Function QM_FQR_Suspend
990 @Description Request to Un-Schedule this Fqid.
992 @Param[in] h_QmFqr - A handle to a QM-FQR Module.
993 @Param[in] h_QmPortal - A handle to a QM Portal Module;
994 NOTE : if NULL, assuming affinity.
995 @Param[in] fqidOffset - Fqid offset within the FQ-Range.
997 @Return E_OK on success; Error code otherwise.
999 @Cautions Allowed only following QM_FQR_Create().
1000 *//***************************************************************************/
1001 t_Error QM_FQR_Suspend(t_Handle h_QmFqr, t_Handle h_QmPortal, uint32_t fqidOffset);
1003 /**************************************************************************//**
1004 @Function QM_FQR_GetFqid
1006 @Description Returned the Fqid base of the FQ-Range
1008 @Param[in] h_QmFqr - A handle to a QM-FQR Module.
1012 @Cautions Allowed only following QM_FQR_Create().
1013 *//***************************************************************************/
1014 uint32_t QM_FQR_GetFqid(t_Handle h_QmFqr);
1016 /**************************************************************************//**
1017 @Function QM_FQR_GetCounter
1019 @Description Reads one of the QM-FQR counters.
1021 @Param[in] h_QmFqr - A handle to a QM-FQR Module.
1022 @Param[in] h_QmPortal - A handle to a QM Portal Module;
1023 NOTE : if NULL, assuming affinity.
1024 @Param[in] fqidOffset - Fqid offset within the FQ-Range.
1025 @Param[in] counter - The requested counter.
1027 @Return Counter's current value.
1029 @Cautions Allowed only following QM_FQR_Create().
1030 *//***************************************************************************/
1031 uint32_t QM_FQR_GetCounter(t_Handle h_QmFqr, t_Handle h_QmPortal, uint32_t fqidOffset, e_QmFqrCounters counter);
1033 /** @} */ /* end of QM_fqr_runtime_control_grp group */
1036 /**************************************************************************//**
1037 @Group QM_fqr_runtime_data_grp QM-FQR Runtime Data Unit
1039 @Description QM-FQR Runtime data unit API functions, definitions and enums.
1042 *//***************************************************************************/
1044 /**************************************************************************//**
1045 @Function QM_FQR_Enqueue
1047 @Description Enqueue the frame into the FQ to be transmitted.
1049 @Param[in] h_QmFqr - A handle to a QM-FQR Module.
1050 @Param[in] h_QmPortal - A handle to a QM Portal Module;
1051 NOTE : if NULL, assuming affinity.
1052 @Param[in] fqidOffset - Fqid offset within the FQ-Range.
1053 @Param[in] p_Frame - Pointer to the frame to be enqueued.
1055 @Return E_OK on success; Error code otherwise.
1057 @Cautions Allowed only following QM_FQR_Create().
1058 *//***************************************************************************/
1059 t_Error QM_FQR_Enqueue(t_Handle h_QmFqr, t_Handle h_QmPortal, uint32_t fqidOffset, t_DpaaFD *p_Frame);
1061 /**************************************************************************//**
1062 @Function QM_FQR_PullFrame
1064 @Description Perform a Pull command.
1066 @Param[in] h_QmFqr - A handle to a QM-FQR Module.
1067 @Param[in] h_QmPortal - A handle to a QM Portal Module;
1068 NOTE : if NULL, assuming affinity.
1069 @Param[in] fqidOffset - Fqid offset within the FQ-Range.
1070 @Param[out] p_Frame - The Received Frame
1072 @Return E_OK on success; Error code otherwise.
1074 @Cautions Allowed only following QM_PORTAL_Init().
1075 *//***************************************************************************/
1076 t_Error QM_FQR_PullFrame(t_Handle h_QmFqr, t_Handle h_QmPortal, uint32_t fqidOffset, t_DpaaFD *p_Frame);
1079 /** @} */ /* end of QM_fqr_runtime_data_grp group */
1080 /** @} */ /* end of QM_fqr_grp group */
1083 /**************************************************************************//**
1084 @Group QM_cg_grp QM Congestion Group API
1086 @Description QM-CG API functions, definitions and enums.
1089 *//***************************************************************************/
1091 /**************************************************************************//**
1092 @Group QM_cg_init_grp QM-Congestion Group Initialization Unit
1094 @Description QM-CG Initialization Unit
1097 *//***************************************************************************/
1099 /**************************************************************************//**
1100 @Description structure representing QM CG WRED curve
1101 *//***************************************************************************/
1102 typedef struct t_QmCgWredCurve {
1103 uint32_t maxTh; /**< minimum threshold - below this level
1104 all packets are rejected (approximated
1105 to be expressed as x*2^y due to HW
1107 uint32_t minTh; /**< minimum threshold - below this level
1108 all packets are accepted (approximated
1109 due to HW implementation)*/
1110 uint8_t probabilityDenominator; /**< 1-64, the fraction of packets dropped
1111 when the average queue depth is at the
1112 maximum threshold.(approximated due to HW
1116 /**************************************************************************//**
1117 @Description structure representing QM CG WRED parameters
1118 *//***************************************************************************/
1119 typedef struct t_QmCgWredParams {
1121 t_QmCgWredCurve greenCurve;
1123 t_QmCgWredCurve yellowCurve;
1125 t_QmCgWredCurve redCurve;
1128 /**************************************************************************//**
1129 @Description structure representing QM CG configuration parameters
1130 *//***************************************************************************/
1131 typedef struct t_QmCgParams {
1132 t_Handle h_Qm; /**< A handle to a QM module */
1133 t_Handle h_QmPortal; /**< A handle to a QM Portal Module;
1134 will be used for Init, Free and as
1135 an interrupt destination for cg state
1136 change (if CgStateChangeEnable = TRUE) */
1137 bool frameCount; /**< TRUE for frame count, FALSE - byte count */
1138 bool wredEnable; /**< if TRUE - WRED enabled. Each color is enabled independently
1139 so that some colors may use WRED, but others may use
1140 Tail drop - if enabled, or none. */
1141 t_QmCgWredParams wredParams; /**< WRED parameters, relevant if wredEnable = TRUE*/
1142 bool tailDropEnable; /**< if TRUE - Tail drop enabled */
1143 uint32_t threshold; /**< If Tail drop - used as Tail drop threshold, otherwise
1144 'threshold' may still be used to receive notifications
1145 when threshold is passed. If threshold and f_Exception
1146 are set, interrupts are set defaultly by driver. */
1147 bool notifyDcPortal; /**< Relevant if this CG receives enqueues from a direct portal
1148 e_DPAA_DCPORTAL0 or e_DPAA_DCPORTAL1. TRUE to notify
1149 the DC portal, FALSE to notify this SW portal. */
1150 e_DpaaDcPortal dcPortalId; /**< relevant if notifyDcPortal=TRUE - DC Portal id */
1151 t_QmExceptionsCallback *f_Exception; /**< relevant and mandatory if threshold is configured and
1152 notifyDcPortal = FALSE. If threshold and f_Exception
1153 are set, interrupts are set defaultly by driver */
1154 t_Handle h_App; /**< A handle to the application layer, will be passed as
1155 argument to f_Exception */
1159 /**************************************************************************//**
1160 @Function QM_CG_Create
1162 @Description Create and configure a congestion Group.
1164 @Param[in] p_CgParams - CG parameters
1166 @Return A handle to the CG module
1168 @Cautions Allowed only following QM_Init().
1169 *//***************************************************************************/
1170 t_Handle QM_CG_Create(t_QmCgParams *p_CgParams);
1172 /**************************************************************************//**
1173 @Function QM_CG_Free
1175 @Description Deleting and free all resources of an initialized CG.
1177 @Param[in] h_QmCg - A handle to a QM-CG Module.
1179 @Return E_OK on success; Error code otherwise.
1181 @Cautions Allowed only following QM_Init() and QM_CR_Create() for this CG.
1182 *//***************************************************************************/
1183 t_Error QM_CG_Free(t_Handle h_QmCg);
1185 /** @} */ /* end of QM_cg_init_grp group */
1188 /**************************************************************************//**
1189 @Group QM_cg_runtime_control_grp QM-CG Runtime Control Unit
1191 @Description QM-CG Runtime control unit API functions, definitions and enums.
1194 *//***************************************************************************/
1196 /**************************************************************************//**
1197 @Description structure representing QM CG WRED colors
1198 *//***************************************************************************/
1199 typedef enum e_QmCgColor {
1200 e_QM_CG_COLOR_GREEN,
1201 e_QM_CG_COLOR_YELLOW,
1205 /**************************************************************************//**
1206 @Description structure representing QM CG modification parameters
1207 *//***************************************************************************/
1208 typedef struct t_QmCgModifyWredParams {
1211 t_QmCgWredCurve wredParams;
1212 } t_QmCgModifyWredParams;
1215 /**************************************************************************//**
1216 @Function QM_CG_SetException
1218 @Description Set CG exception.
1220 @Param[in] h_QmCg - A handle to a QM-CG Module.
1221 @Param[in] exception - exception enum
1222 @Param[in] enable - TRUE to enable, FALSE to disable.
1224 @Return E_OK on success; Error code otherwise.
1226 @Cautions Allowed only following QM_Init() and QM_CG_Create() for this CG.
1227 *//***************************************************************************/
1228 t_Error QM_CG_SetException(t_Handle h_QmCg, e_QmExceptions exception, bool enable);
1230 /**************************************************************************//**
1231 @Function QM_CG_ModifyWredCurve
1233 @Description Change WRED curve parameters for a selected color.
1234 Note that this routine may be called only for valid CG's that
1235 already have been configured for WRED, and only need a change
1236 in the WRED parameters.
1238 @Param[in] h_QmCg - A handle to a QM-CG Module.
1239 @Param[in] p_QmCgModifyParams - A structure of new WRED parameters.
1241 @Return E_OK on success; Error code otherwise.
1243 @Cautions Allowed only following QM_Init() and QM_CG_Create() for this CG.
1244 *//***************************************************************************/
1245 t_Error QM_CG_ModifyWredCurve(t_Handle h_QmCg, t_QmCgModifyWredParams *p_QmCgModifyParams);
1247 /**************************************************************************//**
1248 @Function QM_CG_ModifyTailDropThreshold
1250 @Description Change WRED curve parameters for a selected color.
1251 Note that this routine may be called only for valid CG's that
1252 already have been configured for tail drop, and only need a change
1253 in the threshold value.
1255 @Param[in] h_QmCg - A handle to a QM-CG Module.
1256 @Param[in] threshold - New threshold.
1258 @Return E_OK on success; Error code otherwise.
1260 @Cautions Allowed only following QM_Init() and QM_CG_Create() for this CG.
1261 *//***************************************************************************/
1262 t_Error QM_CG_ModifyTailDropThreshold(t_Handle h_QmCg, uint32_t threshold);
1265 /** @} */ /* end of QM_cg_runtime_control_grp group */
1266 /** @} */ /* end of QM_cg_grp group */
1267 /** @} */ /* end of QM_grp group */
1270 #endif /* __QM_EXT_H */