4 * Copyright (C) 2014 Freescale Semiconductor, Inc.
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are met:
8 * * Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
10 * * Redistributions in binary form must reproduce the above copyright
11 * notice, this list of conditions and the following disclaimer in the
12 * documentation and/or other materials provided with the distribution.
13 * * Neither the name of Freescale Semiconductor nor the
14 * names of its contributors may be used to endorse or promote products
15 * derived from this software without specific prior written permission.
17 * THIS SOFTWARE IS PROVIDED BY Freescale Semiconductor ``AS IS'' AND ANY
18 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
19 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
20 * DISCLAIMED. IN NO EVENT SHALL Freescale Semiconductor BE LIABLE FOR ANY
21 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
22 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
23 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
24 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
26 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28 #ifndef _FSL_QBMAN_PORTAL_H
29 #define _FSL_QBMAN_PORTAL_H
31 #include <fsl_qbman_base.h>
34 * DOC - QBMan portal APIs to implement the following functions:
35 * - Initialize and destroy Software portal object.
36 * - Read and write Software portal interrupt registers.
37 * - Enqueue, including setting the enqueue descriptor, and issuing enqueue
39 * - Dequeue, including setting the dequeue descriptor, issuing dequeue command,
40 * parsing the dequeue response in DQRR and memeory, parsing the state change
42 * - Release, including setting the release descriptor, and issuing the buffer
44 * - Acquire, acquire the buffer from the given buffer pool.
46 * - Channel management, enable/disable CDAN with or without context.
50 * qbman_swp_init() - Create a functional object representing the given
51 * QBMan portal descriptor.
52 * @d: the given qbman swp descriptor
54 * Return qbman_swp portal object for success, NULL if the object cannot
57 struct qbman_swp *qbman_swp_init(const struct qbman_swp_desc *d);
60 * qbman_swp_finish() - Create and destroy a functional object representing
61 * the given QBMan portal descriptor.
62 * @p: the qbman_swp object to be destroyed.
65 void qbman_swp_finish(struct qbman_swp *p);
68 * qbman_swp_get_desc() - Get the descriptor of the given portal object.
69 * @p: the given portal object.
71 * Return the descriptor for this portal.
73 const struct qbman_swp_desc *qbman_swp_get_desc(struct qbman_swp *p);
79 /* EQCR ring interrupt */
80 #define QBMAN_SWP_INTERRUPT_EQRI ((uint32_t)0x00000001)
81 /* Enqueue command dispatched interrupt */
82 #define QBMAN_SWP_INTERRUPT_EQDI ((uint32_t)0x00000002)
83 /* DQRR non-empty interrupt */
84 #define QBMAN_SWP_INTERRUPT_DQRI ((uint32_t)0x00000004)
85 /* RCR ring interrupt */
86 #define QBMAN_SWP_INTERRUPT_RCRI ((uint32_t)0x00000008)
87 /* Release command dispatched interrupt */
88 #define QBMAN_SWP_INTERRUPT_RCDI ((uint32_t)0x00000010)
89 /* Volatile dequeue command interrupt */
90 #define QBMAN_SWP_INTERRUPT_VDCI ((uint32_t)0x00000020)
93 * qbman_swp_interrupt_get_vanish() - Get the data in software portal
94 * interrupt status disable register.
95 * @p: the given software portal object.
97 * Return the settings in SWP_ISDR register.
99 uint32_t qbman_swp_interrupt_get_vanish(struct qbman_swp *p);
102 * qbman_swp_interrupt_set_vanish() - Set the data in software portal
103 * interrupt status disable register.
104 * @p: the given software portal object.
105 * @mask: The value to set in SWP_IDSR register.
107 void qbman_swp_interrupt_set_vanish(struct qbman_swp *p, uint32_t mask);
110 * qbman_swp_interrupt_read_status() - Get the data in software portal
111 * interrupt status register.
112 * @p: the given software portal object.
114 * Return the settings in SWP_ISR register.
116 uint32_t qbman_swp_interrupt_read_status(struct qbman_swp *p);
119 * qbman_swp_interrupt_clear_status() - Set the data in software portal
120 * interrupt status register.
121 * @p: the given software portal object.
122 * @mask: The value to set in SWP_ISR register.
124 void qbman_swp_interrupt_clear_status(struct qbman_swp *p, uint32_t mask);
127 * qbman_swp_dqrr_thrshld_read_status() - Get the data in software portal
128 * DQRR interrupt threshold register.
129 * @p: the given software portal object.
131 uint32_t qbman_swp_dqrr_thrshld_read_status(struct qbman_swp *p);
134 * qbman_swp_dqrr_thrshld_write() - Set the data in software portal
135 * DQRR interrupt threshold register.
136 * @p: the given software portal object.
137 * @mask: The value to set in SWP_DQRR_ITR register.
139 void qbman_swp_dqrr_thrshld_write(struct qbman_swp *p, uint32_t mask);
142 * qbman_swp_intr_timeout_read_status() - Get the data in software portal
143 * Interrupt Time-Out period register.
144 * @p: the given software portal object.
146 uint32_t qbman_swp_intr_timeout_read_status(struct qbman_swp *p);
149 * qbman_swp_intr_timeout_write() - Set the data in software portal
150 * Interrupt Time-Out period register.
151 * @p: the given software portal object.
152 * @mask: The value to set in SWP_ITPR register.
154 void qbman_swp_intr_timeout_write(struct qbman_swp *p, uint32_t mask);
157 * qbman_swp_interrupt_get_trigger() - Get the data in software portal
158 * interrupt enable register.
159 * @p: the given software portal object.
161 * Return the settings in SWP_IER register.
163 uint32_t qbman_swp_interrupt_get_trigger(struct qbman_swp *p);
166 * qbman_swp_interrupt_set_trigger() - Set the data in software portal
167 * interrupt enable register.
168 * @p: the given software portal object.
169 * @mask: The value to set in SWP_IER register.
171 void qbman_swp_interrupt_set_trigger(struct qbman_swp *p, uint32_t mask);
174 * qbman_swp_interrupt_get_inhibit() - Get the data in software portal
175 * interrupt inhibit register.
176 * @p: the given software portal object.
178 * Return the settings in SWP_IIR register.
180 int qbman_swp_interrupt_get_inhibit(struct qbman_swp *p);
183 * qbman_swp_interrupt_set_inhibit() - Set the data in software portal
184 * interrupt inhibit register.
185 * @p: the given software portal object.
186 * @mask: The value to set in SWP_IIR register.
188 void qbman_swp_interrupt_set_inhibit(struct qbman_swp *p, int inhibit);
195 * struct qbman_result - structure for qbman dequeue response and/or
197 * @dont_manipulate_directly: the 16 32bit data to represent the whole
198 * possible qbman dequeue result.
200 struct qbman_result {
201 uint32_t dont_manipulate_directly[16];
205 *A DQRI interrupt can be generated when there are dequeue results on the
206 * portal's DQRR (this mechanism does not deal with "pull" dequeues to
207 * user-supplied 'storage' addresses). There are two parameters to this
208 * interrupt source, one is a threshold and the other is a timeout. The
209 * interrupt will fire if either the fill-level of the ring exceeds 'thresh', or
210 * if the ring has been non-empty for been longer than 'timeout' nanoseconds.
211 * For timeout, an approximation to the desired nanosecond-granularity value is
212 * made, so there are get and set APIs to allow the user to see what actual
213 * timeout is set (compared to the timeout that was requested).
215 int qbman_swp_dequeue_thresh(struct qbman_swp *s, unsigned int thresh);
216 int qbman_swp_dequeue_set_timeout(struct qbman_swp *s, unsigned int timeout);
217 int qbman_swp_dequeue_get_timeout(struct qbman_swp *s, unsigned int *timeout);
219 /* ------------------- */
220 /* Push-mode dequeuing */
221 /* ------------------- */
223 /* The user of a portal can enable and disable push-mode dequeuing of up to 16
224 * channels independently. It does not specify this toggling by channel IDs, but
225 * rather by specifying the index (from 0 to 15) that has been mapped to the
230 * qbman_swp_push_get() - Get the push dequeue setup.
231 * @s: the software portal object.
232 * @channel_idx: the channel index to query.
233 * @enabled: returned boolean to show whether the push dequeue is enabled for
236 void qbman_swp_push_get(struct qbman_swp *s, uint8_t channel_idx, int *enabled);
239 * qbman_swp_push_set() - Enable or disable push dequeue.
240 * @s: the software portal object.
241 * @channel_idx: the channel index..
242 * @enable: enable or disable push dequeue.
244 * The user of a portal can enable and disable push-mode dequeuing of up to 16
245 * channels independently. It does not specify this toggling by channel IDs, but
246 * rather by specifying the index (from 0 to 15) that has been mapped to the
249 void qbman_swp_push_set(struct qbman_swp *s, uint8_t channel_idx, int enable);
251 /* ------------------- */
252 /* Pull-mode dequeuing */
253 /* ------------------- */
256 * struct qbman_pull_desc - the structure for pull dequeue descriptor
257 * @dont_manipulate_directly: the 6 32bit data to represent the whole
258 * possible settings for pull dequeue descriptor.
260 struct qbman_pull_desc {
261 uint32_t dont_manipulate_directly[6];
264 enum qbman_pull_type_e {
265 /* dequeue with priority precedence, respect intra-class scheduling */
266 qbman_pull_type_prio = 1,
267 /* dequeue with active FQ precedence, respect ICS */
268 qbman_pull_type_active,
269 /* dequeue with active FQ precedence, no ICS */
270 qbman_pull_type_active_noics
274 * qbman_pull_desc_clear() - Clear the contents of a descriptor to
275 * default/starting state.
276 * @d: the pull dequeue descriptor to be cleared.
278 void qbman_pull_desc_clear(struct qbman_pull_desc *d);
281 * qbman_pull_desc_set_storage()- Set the pull dequeue storage
282 * @d: the pull dequeue descriptor to be set.
283 * @storage: the pointer of the memory to store the dequeue result.
284 * @storage_phys: the physical address of the storage memory.
285 * @stash: to indicate whether write allocate is enabled.
287 * If not called, or if called with 'storage' as NULL, the result pull dequeues
288 * will produce results to DQRR. If 'storage' is non-NULL, then results are
289 * produced to the given memory location (using the physical/DMA address which
290 * the caller provides in 'storage_phys'), and 'stash' controls whether or not
291 * those writes to main-memory express a cache-warming attribute.
293 void qbman_pull_desc_set_storage(struct qbman_pull_desc *d,
294 struct qbman_result *storage,
295 dma_addr_t storage_phys,
298 * qbman_pull_desc_set_numframes() - Set the number of frames to be dequeued.
299 * @d: the pull dequeue descriptor to be set.
300 * @numframes: number of frames to be set, must be between 1 and 16, inclusive.
302 void qbman_pull_desc_set_numframes(struct qbman_pull_desc *d,
305 * qbman_pull_desc_set_token() - Set dequeue token for pull command
306 * @d: the dequeue descriptor
307 * @token: the token to be set
309 * token is the value that shows up in the dequeue response that can be used to
310 * detect when the results have been published. The easiest technique is to zero
311 * result "storage" before issuing a dequeue, and use any non-zero 'token' value
313 void qbman_pull_desc_set_token(struct qbman_pull_desc *d, uint8_t token);
315 /* Exactly one of the following descriptor "actions" should be set. (Calling any
316 * one of these will replace the effect of any prior call to one of these.)
317 * - pull dequeue from the given frame queue (FQ)
318 * - pull dequeue from any FQ in the given work queue (WQ)
319 * - pull dequeue from any FQ in any WQ in the given channel
322 * qbman_pull_desc_set_fq() - Set fqid from which the dequeue command dequeues.
323 * @fqid: the frame queue index of the given FQ.
325 void qbman_pull_desc_set_fq(struct qbman_pull_desc *d, uint32_t fqid);
328 * qbman_pull_desc_set_wq() - Set wqid from which the dequeue command dequeues.
329 * @wqid: composed of channel id and wqid within the channel.
330 * @dct: the dequeue command type.
332 void qbman_pull_desc_set_wq(struct qbman_pull_desc *d, uint32_t wqid,
333 enum qbman_pull_type_e dct);
335 /* qbman_pull_desc_set_channel() - Set channelid from which the dequeue command
337 * @chid: the channel id to be dequeued.
338 * @dct: the dequeue command type.
340 void qbman_pull_desc_set_channel(struct qbman_pull_desc *d, uint32_t chid,
341 enum qbman_pull_type_e dct);
344 * qbman_swp_pull() - Issue the pull dequeue command
345 * @s: the software portal object.
346 * @d: the software portal descriptor which has been configured with
347 * the set of qbman_pull_desc_set_*() calls.
349 * Return 0 for success, and -EBUSY if the software portal is not ready
350 * to do pull dequeue.
352 int qbman_swp_pull(struct qbman_swp *s, struct qbman_pull_desc *d);
354 /* -------------------------------- */
355 /* Polling DQRR for dequeue results */
356 /* -------------------------------- */
359 * qbman_swp_dqrr_next() - Get an valid DQRR entry.
360 * @s: the software portal object.
362 * Return NULL if there are no unconsumed DQRR entries. Return a DQRR entry
363 * only once, so repeated calls can return a sequence of DQRR entries, without
364 * requiring they be consumed immediately or in any particular order.
366 const struct qbman_result *qbman_swp_dqrr_next(struct qbman_swp *p);
369 * qbman_swp_dqrr_consume() - Consume DQRR entries previously returned from
370 * qbman_swp_dqrr_next().
371 * @s: the software portal object.
372 * @dq: the DQRR entry to be consumed.
374 void qbman_swp_dqrr_consume(struct qbman_swp *s, const struct qbman_result *dq);
377 * qbman_get_dqrr_idx() - Get dqrr index from the given dqrr
378 * @dqrr: the given dqrr object.
382 uint8_t qbman_get_dqrr_idx(const struct qbman_result *dqrr);
385 * qbman_get_dqrr_from_idx() - Use index to get the dqrr entry from the
387 * @s: the given portal.
388 * @idx: the dqrr index.
390 * Return dqrr entry object.
392 struct qbman_result *qbman_get_dqrr_from_idx(struct qbman_swp *s, uint8_t idx);
394 /* ------------------------------------------------- */
395 /* Polling user-provided storage for dequeue results */
396 /* ------------------------------------------------- */
399 * qbman_result_has_new_result() - Check and get the dequeue response from the
400 * dq storage memory set in pull dequeue command
401 * @s: the software portal object.
402 * @dq: the dequeue result read from the memory.
404 * Only used for user-provided storage of dequeue results, not DQRR. For
405 * efficiency purposes, the driver will perform any required endianness
406 * conversion to ensure that the user's dequeue result storage is in host-endian
407 * format (whether or not that is the same as the little-endian format that
408 * hardware DMA'd to the user's storage). As such, once the user has called
409 * qbman_result_has_new_result() and been returned a valid dequeue result,
410 * they should not call it again on the same memory location (except of course
411 * if another dequeue command has been executed to produce a new result to that
414 * Return 1 for getting a valid dequeue result, or 0 for not getting a valid
417 int qbman_result_has_new_result(struct qbman_swp *s,
418 const struct qbman_result *dq);
420 /* -------------------------------------------------------- */
421 /* Parsing dequeue entries (DQRR and user-provided storage) */
422 /* -------------------------------------------------------- */
425 * qbman_result_is_DQ() - check the dequeue result is a dequeue response or not
426 * @dq: the dequeue result to be checked.
428 * DQRR entries may contain non-dequeue results, ie. notifications
430 int qbman_result_is_DQ(const struct qbman_result *dq);
433 * qbman_result_is_SCN() - Check the dequeue result is notification or not
434 * @dq: the dequeue result to be checked.
436 * All the non-dequeue results (FQDAN/CDAN/CSCN/...) are "state change
437 * notifications" of one type or another. Some APIs apply to all of them, of the
438 * form qbman_result_SCN_***().
440 static inline int qbman_result_is_SCN(const struct qbman_result *dq)
442 return !qbman_result_is_DQ(dq);
445 /* Recognise different notification types, only required if the user allows for
446 * these to occur, and cares about them when they do.
450 * qbman_result_is_FQDAN() - Check for FQ Data Availability
451 * @dq: the qbman_result object.
453 * Return 1 if this is FQDAN.
455 int qbman_result_is_FQDAN(const struct qbman_result *dq);
458 * qbman_result_is_CDAN() - Check for Channel Data Availability
459 * @dq: the qbman_result object to check.
461 * Return 1 if this is CDAN.
463 int qbman_result_is_CDAN(const struct qbman_result *dq);
466 * qbman_result_is_CSCN() - Check for Congestion State Change
467 * @dq: the qbman_result object to check.
469 * Return 1 if this is CSCN.
471 int qbman_result_is_CSCN(const struct qbman_result *dq);
474 * qbman_result_is_BPSCN() - Check for Buffer Pool State Change.
475 * @dq: the qbman_result object to check.
477 * Return 1 if this is BPSCN.
479 int qbman_result_is_BPSCN(const struct qbman_result *dq);
482 * qbman_result_is_CGCU() - Check for Congestion Group Count Update.
483 * @dq: the qbman_result object to check.
485 * Return 1 if this is CGCU.
487 int qbman_result_is_CGCU(const struct qbman_result *dq);
489 /* Frame queue state change notifications; (FQDAN in theory counts too as it
490 * leaves a FQ parked, but it is primarily a data availability notification)
494 * qbman_result_is_FQRN() - Check for FQ Retirement Notification.
495 * @dq: the qbman_result object to check.
497 * Return 1 if this is FQRN.
499 int qbman_result_is_FQRN(const struct qbman_result *dq);
502 * qbman_result_is_FQRNI() - Check for FQ Retirement Immediate
503 * @dq: the qbman_result object to check.
505 * Return 1 if this is FQRNI.
507 int qbman_result_is_FQRNI(const struct qbman_result *dq);
510 * qbman_result_is_FQPN() - Check for FQ Park Notification
511 * @dq: the qbman_result object to check.
513 * Return 1 if this is FQPN.
515 int qbman_result_is_FQPN(const struct qbman_result *dq);
517 /* Parsing frame dequeue results (qbman_result_is_DQ() must be TRUE)
520 #define QBMAN_DQ_STAT_FQEMPTY 0x80
522 #define QBMAN_DQ_STAT_HELDACTIVE 0x40
523 /* FQ force eligible */
524 #define QBMAN_DQ_STAT_FORCEELIGIBLE 0x20
526 #define QBMAN_DQ_STAT_VALIDFRAME 0x10
528 #define QBMAN_DQ_STAT_ODPVALID 0x04
529 /* Volatile dequeue */
530 #define QBMAN_DQ_STAT_VOLATILE 0x02
531 /* volatile dequeue command is expired */
532 #define QBMAN_DQ_STAT_EXPIRED 0x01
535 * qbman_result_DQ_flags() - Get the STAT field of dequeue response
536 * @dq: the dequeue result.
538 * Return the state field.
540 uint32_t qbman_result_DQ_flags(const struct qbman_result *dq);
543 * qbman_result_DQ_is_pull() - Check whether the dq response is from a pull
545 * @dq: the dequeue result.
547 * Return 1 for volatile(pull) dequeue, 0 for static dequeue.
549 static inline int qbman_result_DQ_is_pull(const struct qbman_result *dq)
551 return (int)(qbman_result_DQ_flags(dq) & QBMAN_DQ_STAT_VOLATILE);
555 * qbman_result_DQ_is_pull_complete() - Check whether the pull command is
557 * @dq: the dequeue result.
561 static inline int qbman_result_DQ_is_pull_complete(
562 const struct qbman_result *dq)
564 return (int)(qbman_result_DQ_flags(dq) & QBMAN_DQ_STAT_EXPIRED);
568 * qbman_result_DQ_seqnum() - Get the seqnum field in dequeue response
569 * seqnum is valid only if VALIDFRAME flag is TRUE
570 * @dq: the dequeue result.
574 uint16_t qbman_result_DQ_seqnum(const struct qbman_result *dq);
577 * qbman_result_DQ_odpid() - Get the seqnum field in dequeue response
578 * odpid is valid only if ODPVAILD flag is TRUE.
579 * @dq: the dequeue result.
583 uint16_t qbman_result_DQ_odpid(const struct qbman_result *dq);
586 * qbman_result_DQ_fqid() - Get the fqid in dequeue response
587 * @dq: the dequeue result.
591 uint32_t qbman_result_DQ_fqid(const struct qbman_result *dq);
594 * qbman_result_DQ_byte_count() - Get the byte count in dequeue response
595 * @dq: the dequeue result.
597 * Return the byte count remaining in the FQ.
599 uint32_t qbman_result_DQ_byte_count(const struct qbman_result *dq);
602 * qbman_result_DQ_frame_count - Get the frame count in dequeue response
603 * @dq: the dequeue result.
605 * Return the frame count remaining in the FQ.
607 uint32_t qbman_result_DQ_frame_count(const struct qbman_result *dq);
610 * qbman_result_DQ_fqd_ctx() - Get the frame queue context in dequeue response
611 * @dq: the dequeue result.
613 * Return the frame queue context.
615 uint64_t qbman_result_DQ_fqd_ctx(const struct qbman_result *dq);
618 * qbman_result_DQ_fd() - Get the frame descriptor in dequeue response
619 * @dq: the dequeue result.
621 * Return the frame descriptor.
623 const struct qbman_fd *qbman_result_DQ_fd(const struct qbman_result *dq);
625 /* State-change notifications (FQDAN/CDAN/CSCN/...). */
628 * qbman_result_SCN_state() - Get the state field in State-change notification
629 * @scn: the state change notification.
631 * Return the state in the notifiation.
633 uint8_t qbman_result_SCN_state(const struct qbman_result *scn);
636 * qbman_result_SCN_rid() - Get the resource id from the notification
637 * @scn: the state change notification.
639 * Return the resource id.
641 uint32_t qbman_result_SCN_rid(const struct qbman_result *scn);
644 * qbman_result_SCN_ctx() - get the context from the notification
645 * @scn: the state change notification.
647 * Return the context.
649 uint64_t qbman_result_SCN_ctx(const struct qbman_result *scn);
652 * qbman_result_SCN_state_in_mem() - Get the state in notification written
654 * @scn: the state change notification.
658 uint8_t qbman_result_SCN_state_in_mem(const struct qbman_result *scn);
661 * qbman_result_SCN_rid_in_mem() - Get the resource id in notification written
663 * @scn: the state change notification.
665 * Return the resource id.
667 uint32_t qbman_result_SCN_rid_in_mem(const struct qbman_result *scn);
669 /* Type-specific "resource IDs". Mainly for illustration purposes, though it
670 * also gives the appropriate type widths.
672 /* Get the FQID from the FQDAN */
673 #define qbman_result_FQDAN_fqid(dq) qbman_result_SCN_rid(dq)
674 /* Get the FQID from the FQRN */
675 #define qbman_result_FQRN_fqid(dq) qbman_result_SCN_rid(dq)
676 /* Get the FQID from the FQRNI */
677 #define qbman_result_FQRNI_fqid(dq) qbman_result_SCN_rid(dq)
678 /* Get the FQID from the FQPN */
679 #define qbman_result_FQPN_fqid(dq) qbman_result_SCN_rid(dq)
680 /* Get the channel ID from the CDAN */
681 #define qbman_result_CDAN_cid(dq) ((uint16_t)qbman_result_SCN_rid(dq))
682 /* Get the CGID from the CSCN */
683 #define qbman_result_CSCN_cgid(dq) ((uint16_t)qbman_result_SCN_rid(dq))
686 * qbman_result_bpscn_bpid() - Get the bpid from BPSCN
687 * @scn: the state change notification.
689 * Return the buffer pool id.
691 uint16_t qbman_result_bpscn_bpid(const struct qbman_result *scn);
694 * qbman_result_bpscn_has_free_bufs() - Check whether there are free
695 * buffers in the pool from BPSCN.
696 * @scn: the state change notification.
698 * Return the number of free buffers.
700 int qbman_result_bpscn_has_free_bufs(const struct qbman_result *scn);
703 * qbman_result_bpscn_is_depleted() - Check BPSCN to see whether the
704 * buffer pool is depleted.
705 * @scn: the state change notification.
707 * Return the status of buffer pool depletion.
709 int qbman_result_bpscn_is_depleted(const struct qbman_result *scn);
712 * qbman_result_bpscn_is_surplus() - Check BPSCN to see whether the buffer
713 * pool is surplus or not.
714 * @scn: the state change notification.
716 * Return the status of buffer pool surplus.
718 int qbman_result_bpscn_is_surplus(const struct qbman_result *scn);
721 * qbman_result_bpscn_ctx() - Get the BPSCN CTX from BPSCN message
722 * @scn: the state change notification.
724 * Return the BPSCN context.
726 uint64_t qbman_result_bpscn_ctx(const struct qbman_result *scn);
730 * qbman_result_cgcu_cgid() - Check CGCU resouce id, i.e. cgid
731 * @scn: the state change notification.
733 * Return the CGCU resource id.
735 uint16_t qbman_result_cgcu_cgid(const struct qbman_result *scn);
738 * qbman_result_cgcu_icnt() - Get the I_CNT from CGCU
739 * @scn: the state change notification.
741 * Return instantaneous count in the CGCU notification.
743 uint64_t qbman_result_cgcu_icnt(const struct qbman_result *scn);
750 * struct qbman_eq_desc - structure of enqueue descriptor
751 * @dont_manipulate_directly: the 8 32bit data to represent the whole
752 * possible qbman enqueue setting in enqueue descriptor.
754 struct qbman_eq_desc {
755 uint32_t dont_manipulate_directly[8];
759 * struct qbman_eq_response - structure of enqueue response
760 * @dont_manipulate_directly: the 16 32bit data to represent the whole
763 struct qbman_eq_response {
764 uint32_t dont_manipulate_directly[16];
768 * qbman_eq_desc_clear() - Clear the contents of a descriptor to
769 * default/starting state.
770 * @d: the given enqueue descriptor.
772 void qbman_eq_desc_clear(struct qbman_eq_desc *d);
774 /* Exactly one of the following descriptor "actions" should be set. (Calling
775 * any one of these will replace the effect of any prior call to one of these.)
776 * - enqueue without order-restoration
777 * - enqueue with order-restoration
778 * - fill a hole in the order-restoration sequence, without any enqueue
779 * - advance NESN (Next Expected Sequence Number), without any enqueue
780 * 'respond_success' indicates whether an enqueue response should be DMA'd
781 * after success (otherwise a response is DMA'd only after failure).
782 * 'incomplete' indicates that other fragments of the same 'seqnum' are yet to
787 * qbman_eq_desc_set_no_orp() - Set enqueue descriptor without orp
788 * @d: the enqueue descriptor.
789 * @response_success: 1 = enqueue with response always; 0 = enqueue with
790 * rejections returned on a FQ.
792 void qbman_eq_desc_set_no_orp(struct qbman_eq_desc *d, int respond_success);
794 * qbman_eq_desc_set_orp() - Set order-resotration in the enqueue descriptor
795 * @d: the enqueue descriptor.
796 * @response_success: 1 = enqueue with response always; 0 = enqueue with
797 * rejections returned on a FQ.
798 * @opr_id: the order point record id.
799 * @seqnum: the order restoration sequence number.
800 * @incomplete: indiates whether this is the last fragments using the same
803 void qbman_eq_desc_set_orp(struct qbman_eq_desc *d, int respond_success,
804 uint32_t opr_id, uint32_t seqnum, int incomplete);
807 * qbman_eq_desc_set_orp_hole() - fill a hole in the order-restoration sequence
808 * without any enqueue
809 * @d: the enqueue descriptor.
810 * @opr_id: the order point record id.
811 * @seqnum: the order restoration sequence number.
813 void qbman_eq_desc_set_orp_hole(struct qbman_eq_desc *d, uint32_t opr_id,
817 * qbman_eq_desc_set_orp_nesn() - advance NESN (Next Expected Sequence Number)
818 * without any enqueue
819 * @d: the enqueue descriptor.
820 * @opr_id: the order point record id.
821 * @seqnum: the order restoration sequence number.
823 void qbman_eq_desc_set_orp_nesn(struct qbman_eq_desc *d, uint32_t opr_id,
826 * qbman_eq_desc_set_response() - Set the enqueue response info.
827 * @d: the enqueue descriptor
828 * @storage_phys: the physical address of the enqueue response in memory.
829 * @stash: indicate that the write allocation enabled or not.
831 * In the case where an enqueue response is DMA'd, this determines where that
832 * response should go. (The physical/DMA address is given for hardware's
833 * benefit, but software should interpret it as a "struct qbman_eq_response"
834 * data structure.) 'stash' controls whether or not the write to main-memory
835 * expresses a cache-warming attribute.
837 void qbman_eq_desc_set_response(struct qbman_eq_desc *d,
838 dma_addr_t storage_phys,
842 * qbman_eq_desc_set_token() - Set token for the enqueue command
843 * @d: the enqueue descriptor
844 * @token: the token to be set.
846 * token is the value that shows up in an enqueue response that can be used to
847 * detect when the results have been published. The easiest technique is to zero
848 * result "storage" before issuing an enqueue, and use any non-zero 'token'
851 void qbman_eq_desc_set_token(struct qbman_eq_desc *d, uint8_t token);
854 * Exactly one of the following descriptor "targets" should be set. (Calling any
855 * one of these will replace the effect of any prior call to one of these.)
856 * - enqueue to a frame queue
857 * - enqueue to a queuing destination
858 * Note, that none of these will have any affect if the "action" type has been
859 * set to "orp_hole" or "orp_nesn".
862 * qbman_eq_desc_set_fq() - Set Frame Queue id for the enqueue command
863 * @d: the enqueue descriptor
864 * @fqid: the id of the frame queue to be enqueued.
866 void qbman_eq_desc_set_fq(struct qbman_eq_desc *d, uint32_t fqid);
869 * qbman_eq_desc_set_qd() - Set Queuing Destination for the enqueue command.
870 * @d: the enqueue descriptor
871 * @qdid: the id of the queuing destination to be enqueued.
872 * @qd_bin: the queuing destination bin
873 * @qd_prio: the queuing destination priority.
875 void qbman_eq_desc_set_qd(struct qbman_eq_desc *d, uint32_t qdid,
876 uint32_t qd_bin, uint32_t qd_prio);
879 * qbman_eq_desc_set_eqdi() - enable/disable EQDI interrupt
880 * @d: the enqueue descriptor
881 * @enable: boolean to enable/disable EQDI
883 * Determines whether or not the portal's EQDI interrupt source should be
884 * asserted after the enqueue command is completed.
886 void qbman_eq_desc_set_eqdi(struct qbman_eq_desc *d, int enable);
889 * qbman_eq_desc_set_dca() - Set DCA mode in the enqueue command.
890 * @d: the enqueue descriptor.
891 * @enable: enabled/disable DCA mode.
892 * @dqrr_idx: DCAP_CI, the DCAP consumer index.
893 * @park: determine the whether park the FQ or not
895 * Determines whether or not a portal DQRR entry should be consumed once the
896 * enqueue command is completed. (And if so, and the DQRR entry corresponds to a
897 * held-active (order-preserving) FQ, whether the FQ should be parked instead of
898 * being rescheduled.)
900 void qbman_eq_desc_set_dca(struct qbman_eq_desc *d, int enable,
901 uint32_t dqrr_idx, int park);
904 * qbman_swp_enqueue() - Issue an enqueue command.
905 * @s: the software portal used for enqueue.
906 * @d: the enqueue descriptor.
907 * @fd: the frame descriptor to be enqueued.
909 * Please note that 'fd' should only be NULL if the "action" of the
910 * descriptor is "orp_hole" or "orp_nesn".
912 * Return 0 for a successful enqueue, -EBUSY if the EQCR is not ready.
914 int qbman_swp_enqueue(struct qbman_swp *s, const struct qbman_eq_desc *d,
915 const struct qbman_fd *fd);
917 * qbman_swp_enqueue_multiple_eqdesc() - Enqueue multiple frames with separte
918 * enqueue descriptors.
919 * @s: the software portal used for enqueue.
920 * @d: the enqueue descriptors
921 * @fd: the frame descriptor to be enqueued.
922 * @num_frames: the number of the frames to be enqueued.
924 * Return the number of enqueued frames, -EBUSY if the EQCR is not ready.
926 int qbman_swp_enqueue_multiple_eqdesc(struct qbman_swp *s,
927 const struct qbman_eq_desc *d,
928 const struct qbman_fd *fd,
932 * qbman_swp_enqueue_thresh() - Set threshold for EQRI interrupt.
933 * @s: the software portal.
934 * @thresh: the threshold to trigger the EQRI interrupt.
936 * An EQRI interrupt can be generated when the fill-level of EQCR falls below
937 * the 'thresh' value set here. Setting thresh==0 (the default) disables.
939 int qbman_swp_enqueue_thresh(struct qbman_swp *s, unsigned int thresh);
941 /*******************/
942 /* Buffer releases */
943 /*******************/
945 * struct qbman_release_desc - The structure for buffer release descriptor
946 * @dont_manipulate_directly: the 32bit data to represent the whole
947 * possible settings of qbman release descriptor.
949 struct qbman_release_desc {
950 uint32_t dont_manipulate_directly[1];
954 * qbman_release_desc_clear() - Clear the contents of a descriptor to
955 * default/starting state.
956 * @d: the qbman release descriptor.
958 void qbman_release_desc_clear(struct qbman_release_desc *d);
961 * qbman_release_desc_set_bpid() - Set the ID of the buffer pool to release to
962 * @d: the qbman release descriptor.
964 void qbman_release_desc_set_bpid(struct qbman_release_desc *d, uint32_t bpid);
967 * qbman_release_desc_set_rcdi() - Determines whether or not the portal's RCDI
968 * interrupt source should be asserted after the release command is completed.
969 * @d: the qbman release descriptor.
971 void qbman_release_desc_set_rcdi(struct qbman_release_desc *d, int enable);
974 * qbman_swp_release() - Issue a buffer release command.
975 * @s: the software portal object.
976 * @d: the release descriptor.
977 * @buffers: a pointer pointing to the buffer address to be released.
978 * @num_buffers: number of buffers to be released, must be less than 8.
980 * Return 0 for success, -EBUSY if the release command ring is not ready.
982 int qbman_swp_release(struct qbman_swp *s, const struct qbman_release_desc *d,
983 const uint64_t *buffers, unsigned int num_buffers);
986 * qbman_swp_release_thresh() - Set threshold for RCRI interrupt
987 * @s: the software portal.
988 * @thresh: the threshold.
989 * An RCRI interrupt can be generated when the fill-level of RCR falls below
990 * the 'thresh' value set here. Setting thresh==0 (the default) disables.
992 int qbman_swp_release_thresh(struct qbman_swp *s, unsigned int thresh);
994 /*******************/
995 /* Buffer acquires */
996 /*******************/
998 * qbman_swp_acquire() - Issue a buffer acquire command.
999 * @s: the software portal object.
1000 * @bpid: the buffer pool index.
1001 * @buffers: a pointer pointing to the acquired buffer address|es.
1002 * @num_buffers: number of buffers to be acquired, must be less than 8.
1004 * Return 0 for success, or negative error code if the acquire command
1007 int qbman_swp_acquire(struct qbman_swp *s, uint32_t bpid, uint64_t *buffers,
1008 unsigned int num_buffers);
1014 * qbman_swp_fq_schedule() - Move the fq to the scheduled state.
1015 * @s: the software portal object.
1016 * @fqid: the index of frame queue to be scheduled.
1018 * There are a couple of different ways that a FQ can end up parked state,
1019 * This schedules it.
1021 * Return 0 for success, or negative error code for failure.
1023 int qbman_swp_fq_schedule(struct qbman_swp *s, uint32_t fqid);
1026 * qbman_swp_fq_force() - Force the FQ to fully scheduled state.
1027 * @s: the software portal object.
1028 * @fqid: the index of frame queue to be forced.
1030 * Force eligible will force a tentatively-scheduled FQ to be fully-scheduled
1031 * and thus be available for selection by any channel-dequeuing behaviour (push
1032 * or pull). If the FQ is subsequently "dequeued" from the channel and is still
1033 * empty at the time this happens, the resulting dq_entry will have no FD.
1034 * (qbman_result_DQ_fd() will return NULL.)
1036 * Return 0 for success, or negative error code for failure.
1038 int qbman_swp_fq_force(struct qbman_swp *s, uint32_t fqid);
1041 * These functions change the FQ flow-control stuff between XON/XOFF. (The
1042 * default is XON.) This setting doesn't affect enqueues to the FQ, just
1043 * dequeues. XOFF FQs will remain in the tenatively-scheduled state, even when
1044 * non-empty, meaning they won't be selected for scheduled dequeuing. If a FQ is
1045 * changed to XOFF after it had already become truly-scheduled to a channel, and
1046 * a pull dequeue of that channel occurs that selects that FQ for dequeuing,
1047 * then the resulting dq_entry will have no FD. (qbman_result_DQ_fd() will
1051 * qbman_swp_fq_xon() - XON the frame queue.
1052 * @s: the software portal object.
1053 * @fqid: the index of frame queue.
1055 * Return 0 for success, or negative error code for failure.
1057 int qbman_swp_fq_xon(struct qbman_swp *s, uint32_t fqid);
1059 * qbman_swp_fq_xoff() - XOFF the frame queue.
1060 * @s: the software portal object.
1061 * @fqid: the index of frame queue.
1063 * Return 0 for success, or negative error code for failure.
1065 int qbman_swp_fq_xoff(struct qbman_swp *s, uint32_t fqid);
1067 /**********************/
1068 /* Channel management */
1069 /**********************/
1072 * If the user has been allocated a channel object that is going to generate
1073 * CDANs to another channel, then these functions will be necessary.
1074 * CDAN-enabled channels only generate a single CDAN notification, after which
1075 * it they need to be reenabled before they'll generate another. (The idea is
1076 * that pull dequeuing will occur in reaction to the CDAN, followed by a
1077 * reenable step.) Each function generates a distinct command to hardware, so a
1078 * combination function is provided if the user wishes to modify the "context"
1079 * (which shows up in each CDAN message) each time they reenable, as a single
1080 * command to hardware.
1084 * qbman_swp_CDAN_set_context() - Set CDAN context
1085 * @s: the software portal object.
1086 * @channelid: the channel index.
1087 * @ctx: the context to be set in CDAN.
1089 * Return 0 for success, or negative error code for failure.
1091 int qbman_swp_CDAN_set_context(struct qbman_swp *s, uint16_t channelid,
1095 * qbman_swp_CDAN_enable() - Enable CDAN for the channel.
1096 * @s: the software portal object.
1097 * @channelid: the index of the channel to generate CDAN.
1099 * Return 0 for success, or negative error code for failure.
1101 int qbman_swp_CDAN_enable(struct qbman_swp *s, uint16_t channelid);
1104 * qbman_swp_CDAN_disable() - disable CDAN for the channel.
1105 * @s: the software portal object.
1106 * @channelid: the index of the channel to generate CDAN.
1108 * Return 0 for success, or negative error code for failure.
1110 int qbman_swp_CDAN_disable(struct qbman_swp *s, uint16_t channelid);
1113 * qbman_swp_CDAN_set_context_enable() - Set CDAN contest and enable CDAN
1114 * @s: the software portal object.
1115 * @channelid: the index of the channel to generate CDAN.
1116 * @ctx: the context set in CDAN.
1118 * Return 0 for success, or negative error code for failure.
1120 int qbman_swp_CDAN_set_context_enable(struct qbman_swp *s, uint16_t channelid,
1122 int qbman_swp_fill_ring(struct qbman_swp *s,
1123 const struct qbman_eq_desc *d,
1124 const struct qbman_fd *fd,
1125 uint8_t burst_index);
1126 int qbman_swp_flush_ring(struct qbman_swp *s);
1127 void qbman_sync(void);
1128 int qbman_swp_send_multiple(struct qbman_swp *s,
1129 const struct qbman_eq_desc *d,
1130 const struct qbman_fd *fd,
1131 int frames_to_send);
1133 int qbman_check_command_complete(struct qbman_swp *s,
1134 const struct qbman_result *dq);
1135 #endif /* !_FSL_QBMAN_PORTAL_H */