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

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  *
   3  * Copyright (C) 2014 Freescale Semiconductor, Inc.
   4  *
   5  */
   6 #ifndef _FSL_QBMAN_PORTAL_H
   7 #define _FSL_QBMAN_PORTAL_H
   8
   9 #include <fsl_qbman_base.h>
  10
  11 /**
  12  * DOC - QBMan portal APIs to implement the following functions:
  13  * - Initialize and destroy Software portal object.
  14  * - Read and write Software portal interrupt registers.
  15  * - Enqueue, including setting the enqueue descriptor, and issuing enqueue
  16  *   command etc.
  17  * - Dequeue, including setting the dequeue descriptor, issuing dequeue command,
  18  *   parsing the dequeue response in DQRR and memeory, parsing the state change
  19  *   notifications etc.
  20  * - Release, including setting the release descriptor, and issuing the buffer
  21  *   release command.
  22  * - Acquire, acquire the buffer from the given buffer pool.
  23  * - FQ management.
  24  * - Channel management, enable/disable CDAN with or without context.
  25  */
  26
  27 /**
  28  * qbman_swp_init() - Create a functional object representing the given
  29  * QBMan portal descriptor.
  30  * @d: the given qbman swp descriptor
  31  *
  32  * Return qbman_swp portal object for success, NULL if the object cannot
  33  * be created.
  34  */
  35 struct qbman_swp *qbman_swp_init(const struct qbman_swp_desc *d);
  36
  37 /**
  38  * qbman_swp_finish() - Create and destroy a functional object representing
  39  * the given QBMan portal descriptor.
  40  * @p: the qbman_swp object to be destroyed.
  41  *
  42  */
  43 void qbman_swp_finish(struct qbman_swp *p);
  44
  45 /**
  46  * qbman_swp_get_desc() - Get the descriptor of the given portal object.
  47  * @p: the given portal object.
  48  *
  49  * Return the descriptor for this portal.
  50  */
  51 const struct qbman_swp_desc *qbman_swp_get_desc(struct qbman_swp *p);
  52
  53         /**************/
  54         /* Interrupts */
  55         /**************/
  56
  57 /* EQCR ring interrupt */
  58 #define QBMAN_SWP_INTERRUPT_EQRI ((uint32_t)0x00000001)
  59 /* Enqueue command dispatched interrupt */
  60 #define QBMAN_SWP_INTERRUPT_EQDI ((uint32_t)0x00000002)
  61 /* DQRR non-empty interrupt */
  62 #define QBMAN_SWP_INTERRUPT_DQRI ((uint32_t)0x00000004)
  63 /* RCR ring interrupt */
  64 #define QBMAN_SWP_INTERRUPT_RCRI ((uint32_t)0x00000008)
  65 /* Release command dispatched interrupt */
  66 #define QBMAN_SWP_INTERRUPT_RCDI ((uint32_t)0x00000010)
  67 /* Volatile dequeue command interrupt */
  68 #define QBMAN_SWP_INTERRUPT_VDCI ((uint32_t)0x00000020)
  69
  70 /**
  71  * qbman_swp_interrupt_get_vanish() - Get the data in software portal
  72  * interrupt status disable register.
  73  * @p: the given software portal object.
  74  *
  75  * Return the settings in SWP_ISDR register.
  76  */
  77 uint32_t qbman_swp_interrupt_get_vanish(struct qbman_swp *p);
  78
  79 /**
  80  * qbman_swp_interrupt_set_vanish() - Set the data in software portal
  81  * interrupt status disable register.
  82  * @p: the given software portal object.
  83  * @mask: The value to set in SWP_IDSR register.
  84  */
  85 void qbman_swp_interrupt_set_vanish(struct qbman_swp *p, uint32_t mask);
  86
  87 /**
  88  * qbman_swp_interrupt_read_status() - Get the data in software portal
  89  * interrupt status register.
  90  * @p: the given software portal object.
  91  *
  92  * Return the settings in SWP_ISR register.
  93  */
  94 uint32_t qbman_swp_interrupt_read_status(struct qbman_swp *p);
  95
  96 /**
  97  * qbman_swp_interrupt_clear_status() - Set the data in software portal
  98  * interrupt status register.
  99  * @p: the given software portal object.
 100  * @mask: The value to set in SWP_ISR register.
 101  */
 102 void qbman_swp_interrupt_clear_status(struct qbman_swp *p, uint32_t mask);
 103
 104 /**
 105  * qbman_swp_dqrr_thrshld_read_status() - Get the data in software portal
 106  * DQRR interrupt threshold register.
 107  * @p: the given software portal object.
 108  */
 109 uint32_t qbman_swp_dqrr_thrshld_read_status(struct qbman_swp *p);
 110
 111 /**
 112  * qbman_swp_dqrr_thrshld_write() - Set the data in software portal
 113  * DQRR interrupt threshold register.
 114  * @p: the given software portal object.
 115  * @mask: The value to set in SWP_DQRR_ITR register.
 116  */
 117 void qbman_swp_dqrr_thrshld_write(struct qbman_swp *p, uint32_t mask);
 118
 119 /**
 120  * qbman_swp_intr_timeout_read_status() - Get the data in software portal
 121  * Interrupt Time-Out period register.
 122  * @p: the given software portal object.
 123  */
 124 uint32_t qbman_swp_intr_timeout_read_status(struct qbman_swp *p);
 125
 126 /**
 127  * qbman_swp_intr_timeout_write() - Set the data in software portal
 128  * Interrupt Time-Out period register.
 129  * @p: the given software portal object.
 130  * @mask: The value to set in SWP_ITPR register.
 131  */
 132 void qbman_swp_intr_timeout_write(struct qbman_swp *p, uint32_t mask);
 133
 134 /**
 135  * qbman_swp_interrupt_get_trigger() - Get the data in software portal
 136  * interrupt enable register.
 137  * @p: the given software portal object.
 138  *
 139  * Return the settings in SWP_IER register.
 140  */
 141 uint32_t qbman_swp_interrupt_get_trigger(struct qbman_swp *p);
 142
 143 /**
 144  * qbman_swp_interrupt_set_trigger() - Set the data in software portal
 145  * interrupt enable register.
 146  * @p: the given software portal object.
 147  * @mask: The value to set in SWP_IER register.
 148  */
 149 void qbman_swp_interrupt_set_trigger(struct qbman_swp *p, uint32_t mask);
 150
 151 /**
 152  * qbman_swp_interrupt_get_inhibit() - Get the data in software portal
 153  * interrupt inhibit register.
 154  * @p: the given software portal object.
 155  *
 156  * Return the settings in SWP_IIR register.
 157  */
 158 int qbman_swp_interrupt_get_inhibit(struct qbman_swp *p);
 159
 160 /**
 161  * qbman_swp_interrupt_set_inhibit() - Set the data in software portal
 162  * interrupt inhibit register.
 163  * @p: the given software portal object.
 164  * @mask: The value to set in SWP_IIR register.
 165  */
 166 void qbman_swp_interrupt_set_inhibit(struct qbman_swp *p, int inhibit);
 167
 168         /************/
 169         /* Dequeues */
 170         /************/
 171
 172 /**
 173  * struct qbman_result - structure for qbman dequeue response and/or
 174  * notification.
 175  * @donot_manipulate_directly: the 16 32bit data to represent the whole
 176  * possible qbman dequeue result.
 177  */
 178 struct qbman_result {
 179         union {
 180                 struct common {
 181                         uint8_t verb;
 182                         uint8_t reserved[63];
 183                 } common;
 184                 struct dq {
 185                         uint8_t verb;
 186                         uint8_t stat;
 187                         __le16 seqnum;
 188                         __le16 oprid;
 189                         uint8_t reserved;
 190                         uint8_t tok;
 191                         __le32 fqid;
 192                         uint32_t reserved2;
 193                         __le32 fq_byte_cnt;
 194                         __le32 fq_frm_cnt;
 195                         __le64 fqd_ctx;
 196                         uint8_t fd[32];
 197                 } dq;
 198                 struct scn {
 199                         uint8_t verb;
 200                         uint8_t stat;
 201                         uint8_t state;
 202                         uint8_t reserved;
 203                         __le32 rid_tok;
 204                         __le64 ctx;
 205                 } scn;
 206         };
 207 };
 208
 209 /* TODO:
 210  *A DQRI interrupt can be generated when there are dequeue results on the
 211  * portal's DQRR (this mechanism does not deal with "pull" dequeues to
 212  * user-supplied 'storage' addresses). There are two parameters to this
 213  * interrupt source, one is a threshold and the other is a timeout. The
 214  * interrupt will fire if either the fill-level of the ring exceeds 'thresh', or
 215  * if the ring has been non-empty for been longer than 'timeout' nanoseconds.
 216  * For timeout, an approximation to the desired nanosecond-granularity value is
 217  * made, so there are get and set APIs to allow the user to see what actual
 218  * timeout is set (compared to the timeout that was requested).
 219  */
 220 int qbman_swp_dequeue_thresh(struct qbman_swp *s, unsigned int thresh);
 221 int qbman_swp_dequeue_set_timeout(struct qbman_swp *s, unsigned int timeout);
 222 int qbman_swp_dequeue_get_timeout(struct qbman_swp *s, unsigned int *timeout);
 223
 224 /* ------------------- */
 225 /* Push-mode dequeuing */
 226 /* ------------------- */
 227
 228 /* The user of a portal can enable and disable push-mode dequeuing of up to 16
 229  * channels independently. It does not specify this toggling by channel IDs, but
 230  * rather by specifying the index (from 0 to 15) that has been mapped to the
 231  * desired channel.
 232  */
 233
 234 /**
 235  * qbman_swp_push_get() - Get the push dequeue setup.
 236  * @s: the software portal object.
 237  * @channel_idx: the channel index to query.
 238  * @enabled: returned boolean to show whether the push dequeue is enabled for
 239  * the given channel.
 240  */
 241 void qbman_swp_push_get(struct qbman_swp *s, uint8_t channel_idx, int *enabled);
 242
 243 /**
 244  * qbman_swp_push_set() - Enable or disable push dequeue.
 245  * @s: the software portal object.
 246  * @channel_idx: the channel index..
 247  * @enable: enable or disable push dequeue.
 248  *
 249  * The user of a portal can enable and disable push-mode dequeuing of up to 16
 250  * channels independently. It does not specify this toggling by channel IDs, but
 251  * rather by specifying the index (from 0 to 15) that has been mapped to the
 252  * desired channel.
 253  */
 254 void qbman_swp_push_set(struct qbman_swp *s, uint8_t channel_idx, int enable);
 255
 256 /* ------------------- */
 257 /* Pull-mode dequeuing */
 258 /* ------------------- */
 259
 260 /**
 261  * struct qbman_pull_desc - the structure for pull dequeue descriptor
 262  */
 263 struct qbman_pull_desc {
 264         union {
 265                 uint32_t donot_manipulate_directly[16];
 266                 struct pull {
 267                         uint8_t verb;
 268                         uint8_t numf;
 269                         uint8_t tok;
 270                         uint8_t reserved;
 271                         uint32_t dq_src;
 272                         uint64_t rsp_addr;
 273                         uint64_t rsp_addr_virt;
 274                         uint8_t padding[40];
 275                 } pull;
 276         };
 277 };
 278
 279 enum qbman_pull_type_e {
 280         /* dequeue with priority precedence, respect intra-class scheduling */
 281         qbman_pull_type_prio = 1,
 282         /* dequeue with active FQ precedence, respect ICS */
 283         qbman_pull_type_active,
 284         /* dequeue with active FQ precedence, no ICS */
 285         qbman_pull_type_active_noics
 286 };
 287
 288 /**
 289  * qbman_pull_desc_clear() - Clear the contents of a descriptor to
 290  * default/starting state.
 291  * @d: the pull dequeue descriptor to be cleared.
 292  */
 293 void qbman_pull_desc_clear(struct qbman_pull_desc *d);
 294
 295 /**
 296  * qbman_pull_desc_set_storage()- Set the pull dequeue storage
 297  * @d: the pull dequeue descriptor to be set.
 298  * @storage: the pointer of the memory to store the dequeue result.
 299  * @storage_phys: the physical address of the storage memory.
 300  * @stash: to indicate whether write allocate is enabled.
 301  *
 302  * If not called, or if called with 'storage' as NULL, the result pull dequeues
 303  * will produce results to DQRR. If 'storage' is non-NULL, then results are
 304  * produced to the given memory location (using the physical/DMA address which
 305  * the caller provides in 'storage_phys'), and 'stash' controls whether or not
 306  * those writes to main-memory express a cache-warming attribute.
 307  */
 308 void qbman_pull_desc_set_storage(struct qbman_pull_desc *d,
 309                                  struct qbman_result *storage,
 310                                  uint64_t storage_phys,
 311                                  int stash);
 312 /**
 313  * qbman_pull_desc_set_numframes() - Set the number of frames to be dequeued.
 314  * @d: the pull dequeue descriptor to be set.
 315  * @numframes: number of frames to be set, must be between 1 and 16, inclusive.
 316  */
 317 void qbman_pull_desc_set_numframes(struct qbman_pull_desc *d,
 318                                    uint8_t numframes);
 319 /**
 320  * qbman_pull_desc_set_token() - Set dequeue token for pull command
 321  * @d: the dequeue descriptor
 322  * @token: the token to be set
 323  *
 324  * token is the value that shows up in the dequeue response that can be used to
 325  * detect when the results have been published. The easiest technique is to zero
 326  * result "storage" before issuing a dequeue, and use any non-zero 'token' value
 327  */
 328 void qbman_pull_desc_set_token(struct qbman_pull_desc *d, uint8_t token);
 329
 330 /* Exactly one of the following descriptor "actions" should be set. (Calling any
 331  * one of these will replace the effect of any prior call to one of these.)
 332  * - pull dequeue from the given frame queue (FQ)
 333  * - pull dequeue from any FQ in the given work queue (WQ)
 334  * - pull dequeue from any FQ in any WQ in the given channel
 335  */
 336 /**
 337  * qbman_pull_desc_set_fq() - Set fqid from which the dequeue command dequeues.
 338  * @fqid: the frame queue index of the given FQ.
 339  */
 340 void qbman_pull_desc_set_fq(struct qbman_pull_desc *d, uint32_t fqid);
 341
 342 /**
 343  * qbman_pull_desc_set_wq() - Set wqid from which the dequeue command dequeues.
 344  * @wqid: composed of channel id and wqid within the channel.
 345  * @dct: the dequeue command type.
 346  */
 347 void qbman_pull_desc_set_wq(struct qbman_pull_desc *d, uint32_t wqid,
 348                             enum qbman_pull_type_e dct);
 349
 350 /* qbman_pull_desc_set_channel() - Set channelid from which the dequeue command
 351  * dequeues.
 352  * @chid: the channel id to be dequeued.
 353  * @dct: the dequeue command type.
 354  */
 355 void qbman_pull_desc_set_channel(struct qbman_pull_desc *d, uint32_t chid,
 356                                  enum qbman_pull_type_e dct);
 357
 358 /**
 359  * qbman_swp_pull() - Issue the pull dequeue command
 360  * @s: the software portal object.
 361  * @d: the software portal descriptor which has been configured with
 362  * the set of qbman_pull_desc_set_*() calls.
 363  *
 364  * Return 0 for success, and -EBUSY if the software portal is not ready
 365  * to do pull dequeue.
 366  */
 367 int qbman_swp_pull(struct qbman_swp *s, struct qbman_pull_desc *d);
 368
 369 /* -------------------------------- */
 370 /* Polling DQRR for dequeue results */
 371 /* -------------------------------- */
 372
 373 /**
 374  * qbman_swp_dqrr_next() - Get an valid DQRR entry.
 375  * @s: the software portal object.
 376  *
 377  * Return NULL if there are no unconsumed DQRR entries. Return a DQRR entry
 378  * only once, so repeated calls can return a sequence of DQRR entries, without
 379  * requiring they be consumed immediately or in any particular order.
 380  */
 381 const struct qbman_result *qbman_swp_dqrr_next(struct qbman_swp *p);
 382
 383 /**
 384  * qbman_swp_prefetch_dqrr_next() - prefetch the next DQRR entry.
 385  * @s: the software portal object.
 386  */
 387 void qbman_swp_prefetch_dqrr_next(struct qbman_swp *s);
 388
 389 /**
 390  * qbman_swp_dqrr_consume() -  Consume DQRR entries previously returned from
 391  * qbman_swp_dqrr_next().
 392  * @s: the software portal object.
 393  * @dq: the DQRR entry to be consumed.
 394  */
 395 void qbman_swp_dqrr_consume(struct qbman_swp *s, const struct qbman_result *dq);
 396
 397 /**
 398  * qbman_swp_dqrr_idx_consume() -  Given the DQRR index consume the DQRR entry
 399  * @s: the software portal object.
 400  * @dqrr_index: the DQRR index entry to be consumed.
 401  */
 402 void qbman_swp_dqrr_idx_consume(struct qbman_swp *s, uint8_t dqrr_index);
 403
 404 /**
 405  * qbman_get_dqrr_idx() - Get dqrr index from the given dqrr
 406  * @dqrr: the given dqrr object.
 407  *
 408  * Return dqrr index.
 409  */
 410 uint8_t qbman_get_dqrr_idx(const struct qbman_result *dqrr);
 411
 412 /**
 413  * qbman_get_dqrr_from_idx() - Use index to get the dqrr entry from the
 414  * given portal
 415  * @s: the given portal.
 416  * @idx: the dqrr index.
 417  *
 418  * Return dqrr entry object.
 419  */
 420 struct qbman_result *qbman_get_dqrr_from_idx(struct qbman_swp *s, uint8_t idx);
 421
 422 /* ------------------------------------------------- */
 423 /* Polling user-provided storage for dequeue results */
 424 /* ------------------------------------------------- */
 425
 426 /**
 427  * qbman_result_has_new_result() - Check and get the dequeue response from the
 428  * dq storage memory set in pull dequeue command
 429  * @s: the software portal object.
 430  * @dq: the dequeue result read from the memory.
 431  *
 432  * Only used for user-provided storage of dequeue results, not DQRR. For
 433  * efficiency purposes, the driver will perform any required endianness
 434  * conversion to ensure that the user's dequeue result storage is in host-endian
 435  * format (whether or not that is the same as the little-endian format that
 436  * hardware DMA'd to the user's storage). As such, once the user has called
 437  * qbman_result_has_new_result() and been returned a valid dequeue result,
 438  * they should not call it again on the same memory location (except of course
 439  * if another dequeue command has been executed to produce a new result to that
 440  * location).
 441  *
 442  * Return 1 for getting a valid dequeue result, or 0 for not getting a valid
 443  * dequeue result.
 444  */
 445 int qbman_result_has_new_result(struct qbman_swp *s,
 446                                 struct qbman_result *dq);
 447
 448 /**
 449  * qbman_check_command_complete() - Check if the previous issued dq commnd
 450  * is completed and results are available in memory.
 451  * @s: the software portal object.
 452  * @dq: the dequeue result read from the memory.
 453  *
 454  * Return 1 for getting a valid dequeue result, or 0 for not getting a valid
 455  * dequeue result.
 456  */
 457 int qbman_check_command_complete(struct qbman_result *dq);
 458
 459 int qbman_check_new_result(struct qbman_result *dq);
 460
 461 /* -------------------------------------------------------- */
 462 /* Parsing dequeue entries (DQRR and user-provided storage) */
 463 /* -------------------------------------------------------- */
 464
 465 /**
 466  * qbman_result_is_DQ() - check the dequeue result is a dequeue response or not
 467  * @dq: the dequeue result to be checked.
 468  *
 469  * DQRR entries may contain non-dequeue results, ie. notifications
 470  */
 471 int qbman_result_is_DQ(const struct qbman_result *dq);
 472
 473 /**
 474  * qbman_result_is_SCN() - Check the dequeue result is notification or not
 475  * @dq: the dequeue result to be checked.
 476  *
 477  * All the non-dequeue results (FQDAN/CDAN/CSCN/...) are "state change
 478  * notifications" of one type or another. Some APIs apply to all of them, of the
 479  * form qbman_result_SCN_***().
 480  */
 481 static inline int qbman_result_is_SCN(const struct qbman_result *dq)
 482 {
 483         return !qbman_result_is_DQ(dq);
 484 }
 485
 486 /* Recognise different notification types, only required if the user allows for
 487  * these to occur, and cares about them when they do.
 488  */
 489
 490 /**
 491  * qbman_result_is_FQDAN() - Check for FQ Data Availability
 492  * @dq: the qbman_result object.
 493  *
 494  * Return 1 if this is FQDAN.
 495  */
 496 int qbman_result_is_FQDAN(const struct qbman_result *dq);
 497
 498 /**
 499  * qbman_result_is_CDAN() - Check for Channel Data Availability
 500  * @dq: the qbman_result object to check.
 501  *
 502  * Return 1 if this is CDAN.
 503  */
 504 int qbman_result_is_CDAN(const struct qbman_result *dq);
 505
 506 /**
 507  * qbman_result_is_CSCN() - Check for Congestion State Change
 508  * @dq: the qbman_result object to check.
 509  *
 510  * Return 1 if this is CSCN.
 511  */
 512 int qbman_result_is_CSCN(const struct qbman_result *dq);
 513
 514 /**
 515  * qbman_result_is_BPSCN() - Check for Buffer Pool State Change.
 516  * @dq: the qbman_result object to check.
 517  *
 518  * Return 1 if this is BPSCN.
 519  */
 520 int qbman_result_is_BPSCN(const struct qbman_result *dq);
 521
 522 /**
 523  * qbman_result_is_CGCU() - Check for Congestion Group Count Update.
 524  * @dq: the qbman_result object to check.
 525  *
 526  * Return 1 if this is CGCU.
 527  */
 528 int qbman_result_is_CGCU(const struct qbman_result *dq);
 529
 530 /* Frame queue state change notifications; (FQDAN in theory counts too as it
 531  * leaves a FQ parked, but it is primarily a data availability notification)
 532  */
 533
 534 /**
 535  * qbman_result_is_FQRN() - Check for FQ Retirement Notification.
 536  * @dq: the qbman_result object to check.
 537  *
 538  * Return 1 if this is FQRN.
 539  */
 540 int qbman_result_is_FQRN(const struct qbman_result *dq);
 541
 542 /**
 543  * qbman_result_is_FQRNI() - Check for FQ Retirement Immediate
 544  * @dq: the qbman_result object to check.
 545  *
 546  * Return 1 if this is FQRNI.
 547  */
 548 int qbman_result_is_FQRNI(const struct qbman_result *dq);
 549
 550 /**
 551  * qbman_result_is_FQPN() - Check for FQ Park Notification
 552  * @dq: the qbman_result object to check.
 553  *
 554  * Return 1 if this is FQPN.
 555  */
 556 int qbman_result_is_FQPN(const struct qbman_result *dq);
 557
 558 /* Parsing frame dequeue results (qbman_result_is_DQ() must be TRUE)
 559  */
 560 /* FQ empty */
 561 #define QBMAN_DQ_STAT_FQEMPTY       0x80
 562 /* FQ held active */
 563 #define QBMAN_DQ_STAT_HELDACTIVE    0x40
 564 /* FQ force eligible */
 565 #define QBMAN_DQ_STAT_FORCEELIGIBLE 0x20
 566 /* Valid frame */
 567 #define QBMAN_DQ_STAT_VALIDFRAME    0x10
 568 /* FQ ODP enable */
 569 #define QBMAN_DQ_STAT_ODPVALID      0x04
 570 /* Volatile dequeue */
 571 #define QBMAN_DQ_STAT_VOLATILE      0x02
 572 /* volatile dequeue command is expired */
 573 #define QBMAN_DQ_STAT_EXPIRED       0x01
 574
 575 #define QBMAN_EQCR_DCA_IDXMASK          0x0f
 576 #define QBMAN_ENQUEUE_FLAG_DCA          (1ULL << 31)
 577
 578 /**
 579  * qbman_result_DQ_flags() - Get the STAT field of dequeue response
 580  * @dq: the dequeue result.
 581  *
 582  * Return the state field.
 583  */
 584 uint8_t qbman_result_DQ_flags(const struct qbman_result *dq);
 585
 586 /**
 587  * qbman_result_DQ_is_pull() - Check whether the dq response is from a pull
 588  * command.
 589  * @dq: the dequeue result.
 590  *
 591  * Return 1 for volatile(pull) dequeue, 0 for static dequeue.
 592  */
 593 static inline int qbman_result_DQ_is_pull(const struct qbman_result *dq)
 594 {
 595         return (int)(qbman_result_DQ_flags(dq) & QBMAN_DQ_STAT_VOLATILE);
 596 }
 597
 598 /**
 599  * qbman_result_DQ_is_pull_complete() - Check whether the pull command is
 600  * completed.
 601  * @dq: the dequeue result.
 602  *
 603  * Return boolean.
 604  */
 605 static inline int qbman_result_DQ_is_pull_complete(
 606                                         const struct qbman_result *dq)
 607 {
 608         return (int)(qbman_result_DQ_flags(dq) & QBMAN_DQ_STAT_EXPIRED);
 609 }
 610
 611 /**
 612  * qbman_result_DQ_seqnum()  - Get the seqnum field in dequeue response
 613  * seqnum is valid only if VALIDFRAME flag is TRUE
 614  * @dq: the dequeue result.
 615  *
 616  * Return seqnum.
 617  */
 618 uint16_t qbman_result_DQ_seqnum(const struct qbman_result *dq);
 619
 620 /**
 621  * qbman_result_DQ_odpid() - Get the seqnum field in dequeue response
 622  * odpid is valid only if ODPVAILD flag is TRUE.
 623  * @dq: the dequeue result.
 624  *
 625  * Return odpid.
 626  */
 627 uint16_t qbman_result_DQ_odpid(const struct qbman_result *dq);
 628
 629 /**
 630  * qbman_result_DQ_fqid() - Get the fqid in dequeue response
 631  * @dq: the dequeue result.
 632  *
 633  * Return fqid.
 634  */
 635 uint32_t qbman_result_DQ_fqid(const struct qbman_result *dq);
 636
 637 /**
 638  * qbman_result_DQ_byte_count() - Get the byte count in dequeue response
 639  * @dq: the dequeue result.
 640  *
 641  * Return the byte count remaining in the FQ.
 642  */
 643 uint32_t qbman_result_DQ_byte_count(const struct qbman_result *dq);
 644
 645 /**
 646  * qbman_result_DQ_frame_count - Get the frame count in dequeue response
 647  * @dq: the dequeue result.
 648  *
 649  * Return the frame count remaining in the FQ.
 650  */
 651 uint32_t qbman_result_DQ_frame_count(const struct qbman_result *dq);
 652
 653 /**
 654  * qbman_result_DQ_fqd_ctx() - Get the frame queue context in dequeue response
 655  * @dq: the dequeue result.
 656  *
 657  * Return the frame queue context.
 658  */
 659 uint64_t qbman_result_DQ_fqd_ctx(const struct qbman_result *dq);
 660
 661 /**
 662  * qbman_result_DQ_fd() - Get the frame descriptor in dequeue response
 663  * @dq: the dequeue result.
 664  *
 665  * Return the frame descriptor.
 666  */
 667 const struct qbman_fd *qbman_result_DQ_fd(const struct qbman_result *dq);
 668
 669 /* State-change notifications (FQDAN/CDAN/CSCN/...). */
 670
 671 /**
 672  * qbman_result_SCN_state() - Get the state field in State-change notification
 673  * @scn: the state change notification.
 674  *
 675  * Return the state in the notifiation.
 676  */
 677 uint8_t qbman_result_SCN_state(const struct qbman_result *scn);
 678
 679 /**
 680  * qbman_result_SCN_rid() - Get the resource id from the notification
 681  * @scn: the state change notification.
 682  *
 683  * Return the resource id.
 684  */
 685 uint32_t qbman_result_SCN_rid(const struct qbman_result *scn);
 686
 687 /**
 688  * qbman_result_SCN_ctx() - get the context from the notification
 689  * @scn: the state change notification.
 690  *
 691  * Return the context.
 692  */
 693 uint64_t qbman_result_SCN_ctx(const struct qbman_result *scn);
 694
 695 /* Type-specific "resource IDs". Mainly for illustration purposes, though it
 696  * also gives the appropriate type widths.
 697  */
 698 /* Get the FQID from the FQDAN */
 699 #define qbman_result_FQDAN_fqid(dq) qbman_result_SCN_rid(dq)
 700 /* Get the FQID from the FQRN */
 701 #define qbman_result_FQRN_fqid(dq) qbman_result_SCN_rid(dq)
 702 /* Get the FQID from the FQRNI */
 703 #define qbman_result_FQRNI_fqid(dq) qbman_result_SCN_rid(dq)
 704 /* Get the FQID from the FQPN */
 705 #define qbman_result_FQPN_fqid(dq) qbman_result_SCN_rid(dq)
 706 /* Get the channel ID from the CDAN */
 707 #define qbman_result_CDAN_cid(dq) ((uint16_t)qbman_result_SCN_rid(dq))
 708 /* Get the CGID from the CSCN */
 709 #define qbman_result_CSCN_cgid(dq) ((uint16_t)qbman_result_SCN_rid(dq))
 710
 711 /**
 712  * qbman_result_bpscn_bpid() - Get the bpid from BPSCN
 713  * @scn: the state change notification.
 714  *
 715  * Return the buffer pool id.
 716  */
 717 uint16_t qbman_result_bpscn_bpid(const struct qbman_result *scn);
 718
 719 /**
 720  * qbman_result_bpscn_has_free_bufs() - Check whether there are free
 721  * buffers in the pool from BPSCN.
 722  * @scn: the state change notification.
 723  *
 724  * Return the number of free buffers.
 725  */
 726 int qbman_result_bpscn_has_free_bufs(const struct qbman_result *scn);
 727
 728 /**
 729  * qbman_result_bpscn_is_depleted() - Check BPSCN to see whether the
 730  * buffer pool is depleted.
 731  * @scn: the state change notification.
 732  *
 733  * Return the status of buffer pool depletion.
 734  */
 735 int qbman_result_bpscn_is_depleted(const struct qbman_result *scn);
 736
 737 /**
 738  * qbman_result_bpscn_is_surplus() - Check BPSCN to see whether the buffer
 739  * pool is surplus or not.
 740  * @scn: the state change notification.
 741  *
 742  * Return the status of buffer pool surplus.
 743  */
 744 int qbman_result_bpscn_is_surplus(const struct qbman_result *scn);
 745
 746 /**
 747  * qbman_result_bpscn_ctx() - Get the BPSCN CTX from BPSCN message
 748  * @scn: the state change notification.
 749  *
 750  * Return the BPSCN context.
 751  */
 752 uint64_t qbman_result_bpscn_ctx(const struct qbman_result *scn);
 753
 754 /* Parsing CGCU */
 755 /**
 756  * qbman_result_cgcu_cgid() - Check CGCU resouce id, i.e. cgid
 757  * @scn: the state change notification.
 758  *
 759  * Return the CGCU resource id.
 760  */
 761 uint16_t qbman_result_cgcu_cgid(const struct qbman_result *scn);
 762
 763 /**
 764  * qbman_result_cgcu_icnt() - Get the I_CNT from CGCU
 765  * @scn: the state change notification.
 766  *
 767  * Return instantaneous count in the CGCU notification.
 768  */
 769 uint64_t qbman_result_cgcu_icnt(const struct qbman_result *scn);
 770
 771         /************/
 772         /* Enqueues */
 773         /************/
 774
 775 /* struct qbman_eq_desc - structure of enqueue descriptor */
 776 struct qbman_eq_desc {
 777         union {
 778                 uint32_t donot_manipulate_directly[8];
 779                 struct eq {
 780                         uint8_t verb;
 781                         uint8_t dca;
 782                         uint16_t seqnum;
 783                         uint16_t orpid;
 784                         uint16_t reserved1;
 785                         uint32_t tgtid;
 786                         uint32_t tag;
 787                         uint16_t qdbin;
 788                         uint8_t qpri;
 789                         uint8_t reserved[3];
 790                         uint8_t wae;
 791                         uint8_t rspid;
 792                         uint64_t rsp_addr;
 793                 } eq;
 794         };
 795 };
 796
 797 /**
 798  * struct qbman_eq_response - structure of enqueue response
 799  * @donot_manipulate_directly: the 16 32bit data to represent the whole
 800  * enqueue response.
 801  */
 802 struct qbman_eq_response {
 803         uint32_t donot_manipulate_directly[16];
 804 };
 805
 806 /**
 807  * qbman_eq_desc_clear() - Clear the contents of a descriptor to
 808  * default/starting state.
 809  * @d: the given enqueue descriptor.
 810  */
 811 void qbman_eq_desc_clear(struct qbman_eq_desc *d);
 812
 813 /* Exactly one of the following descriptor "actions" should be set. (Calling
 814  * any one of these will replace the effect of any prior call to one of these.)
 815  * - enqueue without order-restoration
 816  * - enqueue with order-restoration
 817  * - fill a hole in the order-restoration sequence, without any enqueue
 818  * - advance NESN (Next Expected Sequence Number), without any enqueue
 819  * 'respond_success' indicates whether an enqueue response should be DMA'd
 820  * after success (otherwise a response is DMA'd only after failure).
 821  * 'incomplete' indicates that other fragments of the same 'seqnum' are yet to
 822  * be enqueued.
 823  */
 824
 825 /**
 826  * qbman_eq_desc_set_no_orp() - Set enqueue descriptor without orp
 827  * @d: the enqueue descriptor.
 828  * @response_success: 1 = enqueue with response always; 0 = enqueue with
 829  * rejections returned on a FQ.
 830  */
 831 void qbman_eq_desc_set_no_orp(struct qbman_eq_desc *d, int respond_success);
 832 /**
 833  * qbman_eq_desc_set_orp() - Set order-resotration in the enqueue descriptor
 834  * @d: the enqueue descriptor.
 835  * @response_success: 1 = enqueue with response always; 0 = enqueue with
 836  * rejections returned on a FQ.
 837  * @opr_id: the order point record id.
 838  * @seqnum: the order restoration sequence number.
 839  * @incomplete: indiates whether this is the last fragments using the same
 840  * sequeue number.
 841  */
 842 void qbman_eq_desc_set_orp(struct qbman_eq_desc *d, int respond_success,
 843                            uint16_t opr_id, uint16_t seqnum, int incomplete);
 844
 845 /**
 846  * qbman_eq_desc_set_orp_hole() - fill a hole in the order-restoration sequence
 847  * without any enqueue
 848  * @d: the enqueue descriptor.
 849  * @opr_id: the order point record id.
 850  * @seqnum: the order restoration sequence number.
 851  */
 852 void qbman_eq_desc_set_orp_hole(struct qbman_eq_desc *d, uint16_t opr_id,
 853                                 uint16_t seqnum);
 854
 855 /**
 856  * qbman_eq_desc_set_orp_nesn() -  advance NESN (Next Expected Sequence Number)
 857  * without any enqueue
 858  * @d: the enqueue descriptor.
 859  * @opr_id: the order point record id.
 860  * @seqnum: the order restoration sequence number.
 861  */
 862 void qbman_eq_desc_set_orp_nesn(struct qbman_eq_desc *d, uint16_t opr_id,
 863                                 uint16_t seqnum);
 864 /**
 865  * qbman_eq_desc_set_response() - Set the enqueue response info.
 866  * @d: the enqueue descriptor
 867  * @storage_phys: the physical address of the enqueue response in memory.
 868  * @stash: indicate that the write allocation enabled or not.
 869  *
 870  * In the case where an enqueue response is DMA'd, this determines where that
 871  * response should go. (The physical/DMA address is given for hardware's
 872  * benefit, but software should interpret it as a "struct qbman_eq_response"
 873  * data structure.) 'stash' controls whether or not the write to main-memory
 874  * expresses a cache-warming attribute.
 875  */
 876 void qbman_eq_desc_set_response(struct qbman_eq_desc *d,
 877                                 uint64_t storage_phys,
 878                                 int stash);
 879
 880 /**
 881  * qbman_eq_desc_set_token() - Set token for the enqueue command
 882  * @d: the enqueue descriptor
 883  * @token: the token to be set.
 884  *
 885  * token is the value that shows up in an enqueue response that can be used to
 886  * detect when the results have been published. The easiest technique is to zero
 887  * result "storage" before issuing an enqueue, and use any non-zero 'token'
 888  * value.
 889  */
 890 void qbman_eq_desc_set_token(struct qbman_eq_desc *d, uint8_t token);
 891
 892 /**
 893  * Exactly one of the following descriptor "targets" should be set. (Calling any
 894  * one of these will replace the effect of any prior call to one of these.)
 895  * - enqueue to a frame queue
 896  * - enqueue to a queuing destination
 897  * Note, that none of these will have any affect if the "action" type has been
 898  * set to "orp_hole" or "orp_nesn".
 899  */
 900 /**
 901  * qbman_eq_desc_set_fq() - Set Frame Queue id for the enqueue command
 902  * @d: the enqueue descriptor
 903  * @fqid: the id of the frame queue to be enqueued.
 904  */
 905 void qbman_eq_desc_set_fq(struct qbman_eq_desc *d, uint32_t fqid);
 906
 907 /**
 908  * qbman_eq_desc_set_qd() - Set Queuing Destination for the enqueue command.
 909  * @d: the enqueue descriptor
 910  * @qdid: the id of the queuing destination to be enqueued.
 911  * @qd_bin: the queuing destination bin
 912  * @qd_prio: the queuing destination priority.
 913  */
 914 void qbman_eq_desc_set_qd(struct qbman_eq_desc *d, uint32_t qdid,
 915                           uint16_t qd_bin, uint8_t qd_prio);
 916
 917 /**
 918  * qbman_eq_desc_set_eqdi() - enable/disable EQDI interrupt
 919  * @d: the enqueue descriptor
 920  * @enable: boolean to enable/disable EQDI
 921  *
 922  * Determines whether or not the portal's EQDI interrupt source should be
 923  * asserted after the enqueue command is completed.
 924  */
 925 void qbman_eq_desc_set_eqdi(struct qbman_eq_desc *d, int enable);
 926
 927 /**
 928  * qbman_eq_desc_set_dca() - Set DCA mode in the enqueue command.
 929  * @d: the enqueue descriptor.
 930  * @enable: enabled/disable DCA mode.
 931  * @dqrr_idx: DCAP_CI, the DCAP consumer index.
 932  * @park: determine the whether park the FQ or not
 933  *
 934  * Determines whether or not a portal DQRR entry should be consumed once the
 935  * enqueue command is completed. (And if so, and the DQRR entry corresponds to a
 936  * held-active (order-preserving) FQ, whether the FQ should be parked instead of
 937  * being rescheduled.)
 938  */
 939 void qbman_eq_desc_set_dca(struct qbman_eq_desc *d, int enable,
 940                            uint8_t dqrr_idx, int park);
 941
 942 /**
 943  * qbman_swp_enqueue() - Issue an enqueue command.
 944  * @s: the software portal used for enqueue.
 945  * @d: the enqueue descriptor.
 946  * @fd: the frame descriptor to be enqueued.
 947  *
 948  * Please note that 'fd' should only be NULL if the "action" of the
 949  * descriptor is "orp_hole" or "orp_nesn".
 950  *
 951  * Return 0 for a successful enqueue, -EBUSY if the EQCR is not ready.
 952  */
 953 int qbman_swp_enqueue(struct qbman_swp *s, const struct qbman_eq_desc *d,
 954                       const struct qbman_fd *fd);
 955 /**
 956  * qbman_swp_enqueue_multiple() - Enqueue multiple frames with same
 957                                   eq descriptor
 958  * @s: the software portal used for enqueue.
 959  * @d: the enqueue descriptor.
 960  * @fd: the frame descriptor to be enqueued.
 961  * @num_frames: the number of the frames to be enqueued.
 962  *
 963  * Return the number of enqueued frames, -EBUSY if the EQCR is not ready.
 964  */
 965 int qbman_swp_enqueue_multiple(struct qbman_swp *s,
 966                                const struct qbman_eq_desc *d,
 967                                const struct qbman_fd *fd,
 968                                uint32_t *flags,
 969                                int num_frames);
 970 /**
 971  * qbman_swp_enqueue_multiple_desc() - Enqueue multiple frames with
 972  *                                     individual eq descriptor.
 973  * @s: the software portal used for enqueue.
 974  * @d: the enqueue descriptor.
 975  * @fd: the frame descriptor to be enqueued.
 976  * @flags: bit-mask of QBMAN_ENQUEUE_FLAG_*** options
 977  * @num_frames: the number of the frames to be enqueued.
 978  *
 979  * Return the number of enqueued frames, -EBUSY if the EQCR is not ready.
 980  */
 981 int qbman_swp_enqueue_multiple_desc(struct qbman_swp *s,
 982                                     const struct qbman_eq_desc *d,
 983                                     const struct qbman_fd *fd,
 984                                     int num_frames);
 985
 986 /* TODO:
 987  * qbman_swp_enqueue_thresh() - Set threshold for EQRI interrupt.
 988  * @s: the software portal.
 989  * @thresh: the threshold to trigger the EQRI interrupt.
 990  *
 991  * An EQRI interrupt can be generated when the fill-level of EQCR falls below
 992  * the 'thresh' value set here. Setting thresh==0 (the default) disables.
 993  */
 994 int qbman_swp_enqueue_thresh(struct qbman_swp *s, unsigned int thresh);
 995
 996         /*******************/
 997         /* Buffer releases */
 998         /*******************/
 999 /**
1000  * struct qbman_release_desc - The structure for buffer release descriptor
1001  * @donot_manipulate_directly: the 32bit data to represent the whole
1002  * possible settings of qbman release descriptor.
1003  */
1004 struct qbman_release_desc {
1005         union {
1006                 uint32_t donot_manipulate_directly[16];
1007                 struct br {
1008                         uint8_t verb;
1009                         uint8_t reserved;
1010                         uint16_t bpid;
1011                         uint32_t reserved2;
1012                         uint64_t buf[7];
1013                 } br;
1014         };
1015 };
1016
1017 /**
1018  * qbman_release_desc_clear() - Clear the contents of a descriptor to
1019  * default/starting state.
1020  * @d: the qbman release descriptor.
1021  */
1022 void qbman_release_desc_clear(struct qbman_release_desc *d);
1023
1024 /**
1025  * qbman_release_desc_set_bpid() - Set the ID of the buffer pool to release to
1026  * @d: the qbman release descriptor.
1027  */
1028 void qbman_release_desc_set_bpid(struct qbman_release_desc *d, uint16_t bpid);
1029
1030 /**
1031  * qbman_release_desc_set_rcdi() - Determines whether or not the portal's RCDI
1032  * interrupt source should be asserted after the release command is completed.
1033  * @d: the qbman release descriptor.
1034  */
1035 void qbman_release_desc_set_rcdi(struct qbman_release_desc *d, int enable);
1036
1037 /**
1038  * qbman_swp_release() - Issue a buffer release command.
1039  * @s: the software portal object.
1040  * @d: the release descriptor.
1041  * @buffers: a pointer pointing to the buffer address to be released.
1042  * @num_buffers: number of buffers to be released,  must be less than 8.
1043  *
1044  * Return 0 for success, -EBUSY if the release command ring is not ready.
1045  */
1046 int qbman_swp_release(struct qbman_swp *s, const struct qbman_release_desc *d,
1047                       const uint64_t *buffers, unsigned int num_buffers);
1048
1049 /* TODO:
1050  * qbman_swp_release_thresh() - Set threshold for RCRI interrupt
1051  * @s: the software portal.
1052  * @thresh: the threshold.
1053  * An RCRI interrupt can be generated when the fill-level of RCR falls below
1054  * the 'thresh' value set here. Setting thresh==0 (the default) disables.
1055  */
1056 int qbman_swp_release_thresh(struct qbman_swp *s, unsigned int thresh);
1057
1058         /*******************/
1059         /* Buffer acquires */
1060         /*******************/
1061 /**
1062  * qbman_swp_acquire() - Issue a buffer acquire command.
1063  * @s: the software portal object.
1064  * @bpid: the buffer pool index.
1065  * @buffers: a pointer pointing to the acquired buffer address|es.
1066  * @num_buffers: number of buffers to be acquired, must be less than 8.
1067  *
1068  * Return 0 for success, or negative error code if the acquire command
1069  * fails.
1070  */
1071 int qbman_swp_acquire(struct qbman_swp *s, uint16_t bpid, uint64_t *buffers,
1072                       unsigned int num_buffers);
1073
1074         /*****************/
1075         /* FQ management */
1076         /*****************/
1077 /**
1078  * qbman_swp_fq_schedule() - Move the fq to the scheduled state.
1079  * @s: the software portal object.
1080  * @fqid: the index of frame queue to be scheduled.
1081  *
1082  * There are a couple of different ways that a FQ can end up parked state,
1083  * This schedules it.
1084  *
1085  * Return 0 for success, or negative error code for failure.
1086  */
1087 int qbman_swp_fq_schedule(struct qbman_swp *s, uint32_t fqid);
1088
1089 /**
1090  * qbman_swp_fq_force() - Force the FQ to fully scheduled state.
1091  * @s: the software portal object.
1092  * @fqid: the index of frame queue to be forced.
1093  *
1094  * Force eligible will force a tentatively-scheduled FQ to be fully-scheduled
1095  * and thus be available for selection by any channel-dequeuing behaviour (push
1096  * or pull). If the FQ is subsequently "dequeued" from the channel and is still
1097  * empty at the time this happens, the resulting dq_entry will have no FD.
1098  * (qbman_result_DQ_fd() will return NULL.)
1099  *
1100  * Return 0 for success, or negative error code for failure.
1101  */
1102 int qbman_swp_fq_force(struct qbman_swp *s, uint32_t fqid);
1103
1104 /**
1105  * These functions change the FQ flow-control stuff between XON/XOFF. (The
1106  * default is XON.) This setting doesn't affect enqueues to the FQ, just
1107  * dequeues. XOFF FQs will remain in the tenatively-scheduled state, even when
1108  * non-empty, meaning they won't be selected for scheduled dequeuing. If a FQ is
1109  * changed to XOFF after it had already become truly-scheduled to a channel, and
1110  * a pull dequeue of that channel occurs that selects that FQ for dequeuing,
1111  * then the resulting dq_entry will have no FD. (qbman_result_DQ_fd() will
1112  * return NULL.)
1113  */
1114 /**
1115  * qbman_swp_fq_xon() - XON the frame queue.
1116  * @s: the software portal object.
1117  * @fqid: the index of frame queue.
1118  *
1119  * Return 0 for success, or negative error code for failure.
1120  */
1121 int qbman_swp_fq_xon(struct qbman_swp *s, uint32_t fqid);
1122 /**
1123  * qbman_swp_fq_xoff() - XOFF the frame queue.
1124  * @s: the software portal object.
1125  * @fqid: the index of frame queue.
1126  *
1127  * Return 0 for success, or negative error code for failure.
1128  */
1129 int qbman_swp_fq_xoff(struct qbman_swp *s, uint32_t fqid);
1130
1131         /**********************/
1132         /* Channel management */
1133         /**********************/
1134
1135 /**
1136  * If the user has been allocated a channel object that is going to generate
1137  * CDANs to another channel, then these functions will be necessary.
1138  * CDAN-enabled channels only generate a single CDAN notification, after which
1139  * it they need to be reenabled before they'll generate another. (The idea is
1140  * that pull dequeuing will occur in reaction to the CDAN, followed by a
1141  * reenable step.) Each function generates a distinct command to hardware, so a
1142  * combination function is provided if the user wishes to modify the "context"
1143  * (which shows up in each CDAN message) each time they reenable, as a single
1144  * command to hardware.
1145  */
1146
1147 /**
1148  * qbman_swp_CDAN_set_context() - Set CDAN context
1149  * @s: the software portal object.
1150  * @channelid: the channel index.
1151  * @ctx: the context to be set in CDAN.
1152  *
1153  * Return 0 for success, or negative error code for failure.
1154  */
1155 int qbman_swp_CDAN_set_context(struct qbman_swp *s, uint16_t channelid,
1156                                uint64_t ctx);
1157
1158 /**
1159  * qbman_swp_CDAN_enable() - Enable CDAN for the channel.
1160  * @s: the software portal object.
1161  * @channelid: the index of the channel to generate CDAN.
1162  *
1163  * Return 0 for success, or negative error code for failure.
1164  */
1165 int qbman_swp_CDAN_enable(struct qbman_swp *s, uint16_t channelid);
1166
1167 /**
1168  * qbman_swp_CDAN_disable() - disable CDAN for the channel.
1169  * @s: the software portal object.
1170  * @channelid: the index of the channel to generate CDAN.
1171  *
1172  * Return 0 for success, or negative error code for failure.
1173  */
1174 int qbman_swp_CDAN_disable(struct qbman_swp *s, uint16_t channelid);
1175
1176 /**
1177  * qbman_swp_CDAN_set_context_enable() - Set CDAN contest and enable CDAN
1178  * @s: the software portal object.
1179  * @channelid: the index of the channel to generate CDAN.
1180  * @ctx: the context set in CDAN.
1181  *
1182  * Return 0 for success, or negative error code for failure.
1183  */
1184 int qbman_swp_CDAN_set_context_enable(struct qbman_swp *s, uint16_t channelid,
1185                                       uint64_t ctx);
1186 #endif /* !_FSL_QBMAN_PORTAL_H */