drivers/bus/fslmc/qbman/include/fsl_qbman_portal.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  * Copyright (C) 2014 Freescale Semiconductor, Inc.
   5  *
   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.
  16  *
  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.
  27  */
  28 #ifndef _FSL_QBMAN_PORTAL_H
  29 #define _FSL_QBMAN_PORTAL_H
  30
  31 #include <fsl_qbman_base.h>
  32
  33 /**
  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
  38  *   command etc.
  39  * - Dequeue, including setting the dequeue descriptor, issuing dequeue command,
  40  *   parsing the dequeue response in DQRR and memeory, parsing the state change
  41  *   notifications etc.
  42  * - Release, including setting the release descriptor, and issuing the buffer
  43  *   release command.
  44  * - Acquire, acquire the buffer from the given buffer pool.
  45  * - FQ management.
  46  * - Channel management, enable/disable CDAN with or without context.
  47  */
  48
  49 /**
  50  * qbman_swp_init() - Create a functional object representing the given
  51  * QBMan portal descriptor.
  52  * @d: the given qbman swp descriptor
  53  *
  54  * Return qbman_swp portal object for success, NULL if the object cannot
  55  * be created.
  56  */
  57 struct qbman_swp *qbman_swp_init(const struct qbman_swp_desc *d);
  58
  59 /**
  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.
  63  *
  64  */
  65 void qbman_swp_finish(struct qbman_swp *p);
  66
  67 /**
  68  * qbman_swp_get_desc() - Get the descriptor of the given portal object.
  69  * @p: the given portal object.
  70  *
  71  * Return the descriptor for this portal.
  72  */
  73 const struct qbman_swp_desc *qbman_swp_get_desc(struct qbman_swp *p);
  74
  75         /**************/
  76         /* Interrupts */
  77         /**************/
  78
  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)
  91
  92 /**
  93  * qbman_swp_interrupt_get_vanish() - Get the data in software portal
  94  * interrupt status disable register.
  95  * @p: the given software portal object.
  96  *
  97  * Return the settings in SWP_ISDR register.
  98  */
  99 uint32_t qbman_swp_interrupt_get_vanish(struct qbman_swp *p);
 100
 101 /**
 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.
 106  */
 107 void qbman_swp_interrupt_set_vanish(struct qbman_swp *p, uint32_t mask);
 108
 109 /**
 110  * qbman_swp_interrupt_read_status() - Get the data in software portal
 111  * interrupt status register.
 112  * @p: the given software portal object.
 113  *
 114  * Return the settings in SWP_ISR register.
 115  */
 116 uint32_t qbman_swp_interrupt_read_status(struct qbman_swp *p);
 117
 118 /**
 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.
 123  */
 124 void qbman_swp_interrupt_clear_status(struct qbman_swp *p, uint32_t mask);
 125
 126 /**
 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.
 130  */
 131 uint32_t qbman_swp_dqrr_thrshld_read_status(struct qbman_swp *p);
 132
 133 /**
 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.
 138  */
 139 void qbman_swp_dqrr_thrshld_write(struct qbman_swp *p, uint32_t mask);
 140
 141 /**
 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.
 145  */
 146 uint32_t qbman_swp_intr_timeout_read_status(struct qbman_swp *p);
 147
 148 /**
 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.
 153  */
 154 void qbman_swp_intr_timeout_write(struct qbman_swp *p, uint32_t mask);
 155
 156 /**
 157  * qbman_swp_interrupt_get_trigger() - Get the data in software portal
 158  * interrupt enable register.
 159  * @p: the given software portal object.
 160  *
 161  * Return the settings in SWP_IER register.
 162  */
 163 uint32_t qbman_swp_interrupt_get_trigger(struct qbman_swp *p);
 164
 165 /**
 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.
 170  */
 171 void qbman_swp_interrupt_set_trigger(struct qbman_swp *p, uint32_t mask);
 172
 173 /**
 174  * qbman_swp_interrupt_get_inhibit() - Get the data in software portal
 175  * interrupt inhibit register.
 176  * @p: the given software portal object.
 177  *
 178  * Return the settings in SWP_IIR register.
 179  */
 180 int qbman_swp_interrupt_get_inhibit(struct qbman_swp *p);
 181
 182 /**
 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.
 187  */
 188 void qbman_swp_interrupt_set_inhibit(struct qbman_swp *p, int inhibit);
 189
 190         /************/
 191         /* Dequeues */
 192         /************/
 193
 194 /**
 195  * struct qbman_result - structure for qbman dequeue response and/or
 196  * notification.
 197  * @dont_manipulate_directly: the 16 32bit data to represent the whole
 198  * possible qbman dequeue result.
 199  */
 200 struct qbman_result {
 201         uint32_t dont_manipulate_directly[16];
 202 };
 203
 204 /* TODO:
 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).
 214  */
 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);
 218
 219 /* ------------------- */
 220 /* Push-mode dequeuing */
 221 /* ------------------- */
 222
 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
 226  * desired channel.
 227  */
 228
 229 /**
 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
 234  * the given channel.
 235  */
 236 void qbman_swp_push_get(struct qbman_swp *s, uint8_t channel_idx, int *enabled);
 237
 238 /**
 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.
 243  *
 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
 247  * desired channel.
 248  */
 249 void qbman_swp_push_set(struct qbman_swp *s, uint8_t channel_idx, int enable);
 250
 251 /* ------------------- */
 252 /* Pull-mode dequeuing */
 253 /* ------------------- */
 254
 255 /**
 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.
 259  */
 260 struct qbman_pull_desc {
 261         uint32_t dont_manipulate_directly[6];
 262 };
 263
 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
 271 };
 272
 273 /**
 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.
 277  */
 278 void qbman_pull_desc_clear(struct qbman_pull_desc *d);
 279
 280 /**
 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.
 286  *
 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.
 292  */
 293 void qbman_pull_desc_set_storage(struct qbman_pull_desc *d,
 294                                  struct qbman_result *storage,
 295                                  dma_addr_t storage_phys,
 296                                  int stash);
 297 /**
 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.
 301  */
 302 void qbman_pull_desc_set_numframes(struct qbman_pull_desc *d,
 303                                    uint8_t numframes);
 304 /**
 305  * qbman_pull_desc_set_token() - Set dequeue token for pull command
 306  * @d: the dequeue descriptor
 307  * @token: the token to be set
 308  *
 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
 312  */
 313 void qbman_pull_desc_set_token(struct qbman_pull_desc *d, uint8_t token);
 314
 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
 320  */
 321 /**
 322  * qbman_pull_desc_set_fq() - Set fqid from which the dequeue command dequeues.
 323  * @fqid: the frame queue index of the given FQ.
 324  */
 325 void qbman_pull_desc_set_fq(struct qbman_pull_desc *d, uint32_t fqid);
 326
 327 /**
 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.
 331  */
 332 void qbman_pull_desc_set_wq(struct qbman_pull_desc *d, uint32_t wqid,
 333                             enum qbman_pull_type_e dct);
 334
 335 /* qbman_pull_desc_set_channel() - Set channelid from which the dequeue command
 336  * dequeues.
 337  * @chid: the channel id to be dequeued.
 338  * @dct: the dequeue command type.
 339  */
 340 void qbman_pull_desc_set_channel(struct qbman_pull_desc *d, uint32_t chid,
 341                                  enum qbman_pull_type_e dct);
 342
 343 /**
 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.
 348  *
 349  * Return 0 for success, and -EBUSY if the software portal is not ready
 350  * to do pull dequeue.
 351  */
 352 int qbman_swp_pull(struct qbman_swp *s, struct qbman_pull_desc *d);
 353
 354 /* -------------------------------- */
 355 /* Polling DQRR for dequeue results */
 356 /* -------------------------------- */
 357
 358 /**
 359  * qbman_swp_dqrr_next() - Get an valid DQRR entry.
 360  * @s: the software portal object.
 361  *
 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.
 365  */
 366 const struct qbman_result *qbman_swp_dqrr_next(struct qbman_swp *p);
 367
 368 /**
 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.
 373  */
 374 void qbman_swp_dqrr_consume(struct qbman_swp *s, const struct qbman_result *dq);
 375
 376 /**
 377  * qbman_get_dqrr_idx() - Get dqrr index from the given dqrr
 378  * @dqrr: the given dqrr object.
 379  *
 380  * Return dqrr index.
 381  */
 382 uint8_t qbman_get_dqrr_idx(const struct qbman_result *dqrr);
 383
 384 /**
 385  * qbman_get_dqrr_from_idx() - Use index to get the dqrr entry from the
 386  * given portal
 387  * @s: the given portal.
 388  * @idx: the dqrr index.
 389  *
 390  * Return dqrr entry object.
 391  */
 392 struct qbman_result *qbman_get_dqrr_from_idx(struct qbman_swp *s, uint8_t idx);
 393
 394 /* ------------------------------------------------- */
 395 /* Polling user-provided storage for dequeue results */
 396 /* ------------------------------------------------- */
 397
 398 /**
 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.
 403  *
 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
 412  * location).
 413  *
 414  * Return 1 for getting a valid dequeue result, or 0 for not getting a valid
 415  * dequeue result.
 416  */
 417 int qbman_result_has_new_result(struct qbman_swp *s,
 418                                 const struct qbman_result *dq);
 419
 420 /* -------------------------------------------------------- */
 421 /* Parsing dequeue entries (DQRR and user-provided storage) */
 422 /* -------------------------------------------------------- */
 423
 424 /**
 425  * qbman_result_is_DQ() - check the dequeue result is a dequeue response or not
 426  * @dq: the dequeue result to be checked.
 427  *
 428  * DQRR entries may contain non-dequeue results, ie. notifications
 429  */
 430 int qbman_result_is_DQ(const struct qbman_result *dq);
 431
 432 /**
 433  * qbman_result_is_SCN() - Check the dequeue result is notification or not
 434  * @dq: the dequeue result to be checked.
 435  *
 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_***().
 439  */
 440 static inline int qbman_result_is_SCN(const struct qbman_result *dq)
 441 {
 442         return !qbman_result_is_DQ(dq);
 443 }
 444
 445 /* Recognise different notification types, only required if the user allows for
 446  * these to occur, and cares about them when they do.
 447  */
 448
 449 /**
 450  * qbman_result_is_FQDAN() - Check for FQ Data Availability
 451  * @dq: the qbman_result object.
 452  *
 453  * Return 1 if this is FQDAN.
 454  */
 455 int qbman_result_is_FQDAN(const struct qbman_result *dq);
 456
 457 /**
 458  * qbman_result_is_CDAN() - Check for Channel Data Availability
 459  * @dq: the qbman_result object to check.
 460  *
 461  * Return 1 if this is CDAN.
 462  */
 463 int qbman_result_is_CDAN(const struct qbman_result *dq);
 464
 465 /**
 466  * qbman_result_is_CSCN() - Check for Congestion State Change
 467  * @dq: the qbman_result object to check.
 468  *
 469  * Return 1 if this is CSCN.
 470  */
 471 int qbman_result_is_CSCN(const struct qbman_result *dq);
 472
 473 /**
 474  * qbman_result_is_BPSCN() - Check for Buffer Pool State Change.
 475  * @dq: the qbman_result object to check.
 476  *
 477  * Return 1 if this is BPSCN.
 478  */
 479 int qbman_result_is_BPSCN(const struct qbman_result *dq);
 480
 481 /**
 482  * qbman_result_is_CGCU() - Check for Congestion Group Count Update.
 483  * @dq: the qbman_result object to check.
 484  *
 485  * Return 1 if this is CGCU.
 486  */
 487 int qbman_result_is_CGCU(const struct qbman_result *dq);
 488
 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)
 491  */
 492
 493 /**
 494  * qbman_result_is_FQRN() - Check for FQ Retirement Notification.
 495  * @dq: the qbman_result object to check.
 496  *
 497  * Return 1 if this is FQRN.
 498  */
 499 int qbman_result_is_FQRN(const struct qbman_result *dq);
 500
 501 /**
 502  * qbman_result_is_FQRNI() - Check for FQ Retirement Immediate
 503  * @dq: the qbman_result object to check.
 504  *
 505  * Return 1 if this is FQRNI.
 506  */
 507 int qbman_result_is_FQRNI(const struct qbman_result *dq);
 508
 509 /**
 510  * qbman_result_is_FQPN() - Check for FQ Park Notification
 511  * @dq: the qbman_result object to check.
 512  *
 513  * Return 1 if this is FQPN.
 514  */
 515 int qbman_result_is_FQPN(const struct qbman_result *dq);
 516
 517 /* Parsing frame dequeue results (qbman_result_is_DQ() must be TRUE)
 518  */
 519 /* FQ empty */
 520 #define QBMAN_DQ_STAT_FQEMPTY       0x80
 521 /* FQ held active */
 522 #define QBMAN_DQ_STAT_HELDACTIVE    0x40
 523 /* FQ force eligible */
 524 #define QBMAN_DQ_STAT_FORCEELIGIBLE 0x20
 525 /* Valid frame */
 526 #define QBMAN_DQ_STAT_VALIDFRAME    0x10
 527 /* FQ ODP enable */
 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
 533
 534 /**
 535  * qbman_result_DQ_flags() - Get the STAT field of dequeue response
 536  * @dq: the dequeue result.
 537  *
 538  * Return the state field.
 539  */
 540 uint32_t qbman_result_DQ_flags(const struct qbman_result *dq);
 541
 542 /**
 543  * qbman_result_DQ_is_pull() - Check whether the dq response is from a pull
 544  * command.
 545  * @dq: the dequeue result.
 546  *
 547  * Return 1 for volatile(pull) dequeue, 0 for static dequeue.
 548  */
 549 static inline int qbman_result_DQ_is_pull(const struct qbman_result *dq)
 550 {
 551         return (int)(qbman_result_DQ_flags(dq) & QBMAN_DQ_STAT_VOLATILE);
 552 }
 553
 554 /**
 555  * qbman_result_DQ_is_pull_complete() - Check whether the pull command is
 556  * completed.
 557  * @dq: the dequeue result.
 558  *
 559  * Return boolean.
 560  */
 561 static inline int qbman_result_DQ_is_pull_complete(
 562                                         const struct qbman_result *dq)
 563 {
 564         return (int)(qbman_result_DQ_flags(dq) & QBMAN_DQ_STAT_EXPIRED);
 565 }
 566
 567 /**
 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.
 571  *
 572  * Return seqnum.
 573  */
 574 uint16_t qbman_result_DQ_seqnum(const struct qbman_result *dq);
 575
 576 /**
 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.
 580  *
 581  * Return odpid.
 582  */
 583 uint16_t qbman_result_DQ_odpid(const struct qbman_result *dq);
 584
 585 /**
 586  * qbman_result_DQ_fqid() - Get the fqid in dequeue response
 587  * @dq: the dequeue result.
 588  *
 589  * Return fqid.
 590  */
 591 uint32_t qbman_result_DQ_fqid(const struct qbman_result *dq);
 592
 593 /**
 594  * qbman_result_DQ_byte_count() - Get the byte count in dequeue response
 595  * @dq: the dequeue result.
 596  *
 597  * Return the byte count remaining in the FQ.
 598  */
 599 uint32_t qbman_result_DQ_byte_count(const struct qbman_result *dq);
 600
 601 /**
 602  * qbman_result_DQ_frame_count - Get the frame count in dequeue response
 603  * @dq: the dequeue result.
 604  *
 605  * Return the frame count remaining in the FQ.
 606  */
 607 uint32_t qbman_result_DQ_frame_count(const struct qbman_result *dq);
 608
 609 /**
 610  * qbman_result_DQ_fqd_ctx() - Get the frame queue context in dequeue response
 611  * @dq: the dequeue result.
 612  *
 613  * Return the frame queue context.
 614  */
 615 uint64_t qbman_result_DQ_fqd_ctx(const struct qbman_result *dq);
 616
 617 /**
 618  * qbman_result_DQ_fd() - Get the frame descriptor in dequeue response
 619  * @dq: the dequeue result.
 620  *
 621  * Return the frame descriptor.
 622  */
 623 const struct qbman_fd *qbman_result_DQ_fd(const struct qbman_result *dq);
 624
 625 /* State-change notifications (FQDAN/CDAN/CSCN/...). */
 626
 627 /**
 628  * qbman_result_SCN_state() - Get the state field in State-change notification
 629  * @scn: the state change notification.
 630  *
 631  * Return the state in the notifiation.
 632  */
 633 uint8_t qbman_result_SCN_state(const struct qbman_result *scn);
 634
 635 /**
 636  * qbman_result_SCN_rid() - Get the resource id from the notification
 637  * @scn: the state change notification.
 638  *
 639  * Return the resource id.
 640  */
 641 uint32_t qbman_result_SCN_rid(const struct qbman_result *scn);
 642
 643 /**
 644  * qbman_result_SCN_ctx() - get the context from the notification
 645  * @scn: the state change notification.
 646  *
 647  * Return the context.
 648  */
 649 uint64_t qbman_result_SCN_ctx(const struct qbman_result *scn);
 650
 651 /**
 652  * qbman_result_SCN_state_in_mem() - Get the state in notification written
 653  * in memory
 654  * @scn: the state change notification.
 655  *
 656  * Return the state.
 657  */
 658 uint8_t qbman_result_SCN_state_in_mem(const struct qbman_result *scn);
 659
 660 /**
 661  * qbman_result_SCN_rid_in_mem() - Get the resource id in notification written
 662  * in memory.
 663  * @scn: the state change notification.
 664  *
 665  * Return the resource id.
 666  */
 667 uint32_t qbman_result_SCN_rid_in_mem(const struct qbman_result *scn);
 668
 669 /* Type-specific "resource IDs". Mainly for illustration purposes, though it
 670  * also gives the appropriate type widths.
 671  */
 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))
 684
 685 /**
 686  * qbman_result_bpscn_bpid() - Get the bpid from BPSCN
 687  * @scn: the state change notification.
 688  *
 689  * Return the buffer pool id.
 690  */
 691 uint16_t qbman_result_bpscn_bpid(const struct qbman_result *scn);
 692
 693 /**
 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.
 697  *
 698  * Return the number of free buffers.
 699  */
 700 int qbman_result_bpscn_has_free_bufs(const struct qbman_result *scn);
 701
 702 /**
 703  * qbman_result_bpscn_is_depleted() - Check BPSCN to see whether the
 704  * buffer pool is depleted.
 705  * @scn: the state change notification.
 706  *
 707  * Return the status of buffer pool depletion.
 708  */
 709 int qbman_result_bpscn_is_depleted(const struct qbman_result *scn);
 710
 711 /**
 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.
 715  *
 716  * Return the status of buffer pool surplus.
 717  */
 718 int qbman_result_bpscn_is_surplus(const struct qbman_result *scn);
 719
 720 /**
 721  * qbman_result_bpscn_ctx() - Get the BPSCN CTX from BPSCN message
 722  * @scn: the state change notification.
 723  *
 724  * Return the BPSCN context.
 725  */
 726 uint64_t qbman_result_bpscn_ctx(const struct qbman_result *scn);
 727
 728 /* Parsing CGCU */
 729 /**
 730  * qbman_result_cgcu_cgid() - Check CGCU resouce id, i.e. cgid
 731  * @scn: the state change notification.
 732  *
 733  * Return the CGCU resource id.
 734  */
 735 uint16_t qbman_result_cgcu_cgid(const struct qbman_result *scn);
 736
 737 /**
 738  * qbman_result_cgcu_icnt() - Get the I_CNT from CGCU
 739  * @scn: the state change notification.
 740  *
 741  * Return instantaneous count in the CGCU notification.
 742  */
 743 uint64_t qbman_result_cgcu_icnt(const struct qbman_result *scn);
 744
 745         /************/
 746         /* Enqueues */
 747         /************/
 748
 749 /**
 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.
 753  */
 754 struct qbman_eq_desc {
 755         uint32_t dont_manipulate_directly[8];
 756 };
 757
 758 /**
 759  * struct qbman_eq_response - structure of enqueue response
 760  * @dont_manipulate_directly: the 16 32bit data to represent the whole
 761  * enqueue response.
 762  */
 763 struct qbman_eq_response {
 764         uint32_t dont_manipulate_directly[16];
 765 };
 766
 767 /**
 768  * qbman_eq_desc_clear() - Clear the contents of a descriptor to
 769  * default/starting state.
 770  * @d: the given enqueue descriptor.
 771  */
 772 void qbman_eq_desc_clear(struct qbman_eq_desc *d);
 773
 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
 783  * be enqueued.
 784  */
 785
 786 /**
 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.
 791  */
 792 void qbman_eq_desc_set_no_orp(struct qbman_eq_desc *d, int respond_success);
 793 /**
 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
 801  * sequeue number.
 802  */
 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);
 805
 806 /**
 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.
 812  */
 813 void qbman_eq_desc_set_orp_hole(struct qbman_eq_desc *d, uint32_t opr_id,
 814                                 uint32_t seqnum);
 815
 816 /**
 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.
 822  */
 823 void qbman_eq_desc_set_orp_nesn(struct qbman_eq_desc *d, uint32_t opr_id,
 824                                 uint32_t seqnum);
 825 /**
 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.
 830  *
 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.
 836  */
 837 void qbman_eq_desc_set_response(struct qbman_eq_desc *d,
 838                                 dma_addr_t storage_phys,
 839                                 int stash);
 840
 841 /**
 842  * qbman_eq_desc_set_token() - Set token for the enqueue command
 843  * @d: the enqueue descriptor
 844  * @token: the token to be set.
 845  *
 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'
 849  * value.
 850  */
 851 void qbman_eq_desc_set_token(struct qbman_eq_desc *d, uint8_t token);
 852
 853 /**
 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".
 860  */
 861 /**
 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.
 865  */
 866 void qbman_eq_desc_set_fq(struct qbman_eq_desc *d, uint32_t fqid);
 867
 868 /**
 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.
 874  */
 875 void qbman_eq_desc_set_qd(struct qbman_eq_desc *d, uint32_t qdid,
 876                           uint32_t qd_bin, uint32_t qd_prio);
 877
 878 /**
 879  * qbman_eq_desc_set_eqdi() - enable/disable EQDI interrupt
 880  * @d: the enqueue descriptor
 881  * @enable: boolean to enable/disable EQDI
 882  *
 883  * Determines whether or not the portal's EQDI interrupt source should be
 884  * asserted after the enqueue command is completed.
 885  */
 886 void qbman_eq_desc_set_eqdi(struct qbman_eq_desc *d, int enable);
 887
 888 /**
 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
 894  *
 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.)
 899  */
 900 void qbman_eq_desc_set_dca(struct qbman_eq_desc *d, int enable,
 901                            uint32_t dqrr_idx, int park);
 902
 903 /**
 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.
 908  *
 909  * Please note that 'fd' should only be NULL if the "action" of the
 910  * descriptor is "orp_hole" or "orp_nesn".
 911  *
 912  * Return 0 for a successful enqueue, -EBUSY if the EQCR is not ready.
 913  */
 914 int qbman_swp_enqueue(struct qbman_swp *s, const struct qbman_eq_desc *d,
 915                       const struct qbman_fd *fd);
 916 /**
 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.
 923  *
 924  * Return the number of enqueued frames, -EBUSY if the EQCR is not ready.
 925  */
 926 int qbman_swp_enqueue_multiple_eqdesc(struct qbman_swp *s,
 927                                const struct qbman_eq_desc *d,
 928                                const struct qbman_fd *fd,
 929                                int num_frames);
 930
 931 /* TODO:
 932  * qbman_swp_enqueue_thresh() - Set threshold for EQRI interrupt.
 933  * @s: the software portal.
 934  * @thresh: the threshold to trigger the EQRI interrupt.
 935  *
 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.
 938  */
 939 int qbman_swp_enqueue_thresh(struct qbman_swp *s, unsigned int thresh);
 940
 941         /*******************/
 942         /* Buffer releases */
 943         /*******************/
 944 /**
 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.
 948  */
 949 struct qbman_release_desc {
 950         uint32_t dont_manipulate_directly[1];
 951 };
 952
 953 /**
 954  * qbman_release_desc_clear() - Clear the contents of a descriptor to
 955  * default/starting state.
 956  * @d: the qbman release descriptor.
 957  */
 958 void qbman_release_desc_clear(struct qbman_release_desc *d);
 959
 960 /**
 961  * qbman_release_desc_set_bpid() - Set the ID of the buffer pool to release to
 962  * @d: the qbman release descriptor.
 963  */
 964 void qbman_release_desc_set_bpid(struct qbman_release_desc *d, uint32_t bpid);
 965
 966 /**
 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.
 970  */
 971 void qbman_release_desc_set_rcdi(struct qbman_release_desc *d, int enable);
 972
 973 /**
 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.
 979  *
 980  * Return 0 for success, -EBUSY if the release command ring is not ready.
 981  */
 982 int qbman_swp_release(struct qbman_swp *s, const struct qbman_release_desc *d,
 983                       const uint64_t *buffers, unsigned int num_buffers);
 984
 985 /* TODO:
 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.
 991  */
 992 int qbman_swp_release_thresh(struct qbman_swp *s, unsigned int thresh);
 993
 994         /*******************/
 995         /* Buffer acquires */
 996         /*******************/
 997 /**
 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.
1003  *
1004  * Return 0 for success, or negative error code if the acquire command
1005  * fails.
1006  */
1007 int qbman_swp_acquire(struct qbman_swp *s, uint32_t bpid, uint64_t *buffers,
1008                       unsigned int num_buffers);
1009
1010         /*****************/
1011         /* FQ management */
1012         /*****************/
1013 /**
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.
1017  *
1018  * There are a couple of different ways that a FQ can end up parked state,
1019  * This schedules it.
1020  *
1021  * Return 0 for success, or negative error code for failure.
1022  */
1023 int qbman_swp_fq_schedule(struct qbman_swp *s, uint32_t fqid);
1024
1025 /**
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.
1029  *
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.)
1035  *
1036  * Return 0 for success, or negative error code for failure.
1037  */
1038 int qbman_swp_fq_force(struct qbman_swp *s, uint32_t fqid);
1039
1040 /**
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
1048  * return NULL.)
1049  */
1050 /**
1051  * qbman_swp_fq_xon() - XON the frame queue.
1052  * @s: the software portal object.
1053  * @fqid: the index of frame queue.
1054  *
1055  * Return 0 for success, or negative error code for failure.
1056  */
1057 int qbman_swp_fq_xon(struct qbman_swp *s, uint32_t fqid);
1058 /**
1059  * qbman_swp_fq_xoff() - XOFF the frame queue.
1060  * @s: the software portal object.
1061  * @fqid: the index of frame queue.
1062  *
1063  * Return 0 for success, or negative error code for failure.
1064  */
1065 int qbman_swp_fq_xoff(struct qbman_swp *s, uint32_t fqid);
1066
1067         /**********************/
1068         /* Channel management */
1069         /**********************/
1070
1071 /**
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.
1081  */
1082
1083 /**
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.
1088  *
1089  * Return 0 for success, or negative error code for failure.
1090  */
1091 int qbman_swp_CDAN_set_context(struct qbman_swp *s, uint16_t channelid,
1092                                uint64_t ctx);
1093
1094 /**
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.
1098  *
1099  * Return 0 for success, or negative error code for failure.
1100  */
1101 int qbman_swp_CDAN_enable(struct qbman_swp *s, uint16_t channelid);
1102
1103 /**
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.
1107  *
1108  * Return 0 for success, or negative error code for failure.
1109  */
1110 int qbman_swp_CDAN_disable(struct qbman_swp *s, uint16_t channelid);
1111
1112 /**
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.
1117  *
1118  * Return 0 for success, or negative error code for failure.
1119  */
1120 int qbman_swp_CDAN_set_context_enable(struct qbman_swp *s, uint16_t channelid,
1121                                       uint64_t ctx);
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);
1132
1133 int qbman_check_command_complete(struct qbman_swp *s,
1134                                  const struct qbman_result *dq);
1135
1136 int qbman_get_version(void);
1137 #endif /* !_FSL_QBMAN_PORTAL_H */