blob: 2aadad888bcbf40178dfb31a5d167fea801ac4db [file] [log] [blame]
Prabhakar Kushwahaa2a55e52015-03-19 09:20:45 -07001/*
2 * Copyright (C) 2014 Freescale Semiconductor
3 *
4 * SPDX-License-Identifier: GPL-2.0+
5 */
6
7#ifndef _FSL_QBMAN_PORTAL_H
8#define _FSL_QBMAN_PORTAL_H
9
10#include <fsl-mc/fsl_qbman_base.h>
11
12/* Create and destroy a functional object representing the given QBMan portal
13 * descriptor. */
14struct qbman_swp *qbman_swp_init(const struct qbman_swp_desc *);
15
16 /************/
17 /* Dequeues */
18 /************/
19
20/* See the QBMan driver API documentation for details on the enqueue
21 * mechanisms. NB: the use of a 'ldpaa_' prefix for this type is because it is
22 * primarily used by the "DPIO" layer that sits above (and hides) the QBMan
23 * driver. The structure is defined in the DPIO interface, but to avoid circular
24 * dependencies we just pre/re-declare it here opaquely. */
25struct ldpaa_dq;
26
27
28/* ------------------- */
29/* Pull-mode dequeuing */
30/* ------------------- */
31
32struct qbman_pull_desc {
33 uint32_t dont_manipulate_directly[6];
34};
35
36/* Clear the contents of a descriptor to default/starting state. */
37void qbman_pull_desc_clear(struct qbman_pull_desc *);
38/* If not called, or if called with 'storage' as NULL, the result pull dequeues
39 * will produce results to DQRR. If 'storage' is non-NULL, then results are
40 * produced to the given memory location (using the physical/DMA address which
41 * the caller provides in 'storage_phys'), and 'stash' controls whether or not
42 * those writes to main-memory express a cache-warming attribute. */
43void qbman_pull_desc_set_storage(struct qbman_pull_desc *,
44 struct ldpaa_dq *storage,
45 dma_addr_t storage_phys,
46 int stash);
47/* numframes must be between 1 and 16, inclusive */
48void qbman_pull_desc_set_numframes(struct qbman_pull_desc *, uint8_t numframes);
49/* token is the value that shows up in the dequeue results that can be used to
50 * detect when the results have been published, and is not really used when
51 * dequeue results go to DQRR. The easiest technique is to zero result "storage"
52 * before issuing a pull dequeue, and use any non-zero 'token' value. */
53void qbman_pull_desc_set_token(struct qbman_pull_desc *, uint8_t token);
54/* Exactly one of the following descriptor "actions" should be set. (Calling any
55 * one of these will replace the effect of any prior call to one of these.)
56 * - pull dequeue from the given frame queue (FQ)
57 * - pull dequeue from any FQ in the given work queue (WQ)
58 * - pull dequeue from any FQ in any WQ in the given channel
59 */
60void qbman_pull_desc_set_fq(struct qbman_pull_desc *, uint32_t fqid);
61
62/* Issue the pull dequeue command */
63int qbman_swp_pull(struct qbman_swp *, struct qbman_pull_desc *);
64
65/* -------------------------------- */
66/* Polling DQRR for dequeue results */
67/* -------------------------------- */
68
69/* NULL return if there are no unconsumed DQRR entries. Returns a DQRR entry
70 * only once, so repeated calls can return a sequence of DQRR entries, without
71 * requiring they be consumed immediately or in any particular order. */
72const struct ldpaa_dq *qbman_swp_dqrr_next(struct qbman_swp *);
73/* Consume DQRR entries previously returned from qbman_swp_dqrr_next(). */
74void qbman_swp_dqrr_consume(struct qbman_swp *, const struct ldpaa_dq *);
75
76/* ------------------------------------------------- */
77/* Polling user-provided storage for dequeue results */
78/* ------------------------------------------------- */
79
80/* Only used for user-provided storage of dequeue results, not DQRR. Prior to
81 * being used, the storage must set "oldtoken", so that the driver notices when
82 * hardware has filled it in with results using a "newtoken". NB, for efficiency
83 * purposes, the driver will perform any required endianness conversion to
84 * ensure that the user's dequeue result storage is in host-endian format
85 * (whether or not that is the same as the little-endian format that hardware
86 * DMA'd to the user's storage). As such, once the user has called
87 * qbman_dq_entry_has_newtoken() and been returned a valid dequeue result, they
88 * should not call it again on the same memory location (except of course if
89 * another dequeue command has been executed to produce a new result to that
90 * location).
91 */
92void qbman_dq_entry_set_oldtoken(struct ldpaa_dq *,
93 unsigned int num_entries,
94 uint8_t oldtoken);
95int qbman_dq_entry_has_newtoken(struct qbman_swp *,
96 const struct ldpaa_dq *,
97 uint8_t newtoken);
98
99/* -------------------------------------------------------- */
100/* Parsing dequeue entries (DQRR and user-provided storage) */
101/* -------------------------------------------------------- */
102
103/* DQRR entries may contain non-dequeue results, ie. notifications */
104int qbman_dq_entry_is_DQ(const struct ldpaa_dq *);
105
106 /************/
107 /* Enqueues */
108 /************/
109
110struct qbman_eq_desc {
111 uint32_t dont_manipulate_directly[8];
112};
113
114
115/* Clear the contents of a descriptor to default/starting state. */
116void qbman_eq_desc_clear(struct qbman_eq_desc *);
117/* Exactly one of the following descriptor "actions" should be set. (Calling
118 * any one of these will replace the effect of any prior call to one of these.)
119 * - enqueue without order-restoration
120 * - enqueue with order-restoration
121 * - fill a hole in the order-restoration sequence, without any enqueue
122 * - advance NESN (Next Expected Sequence Number), without any enqueue
123 * 'respond_success' indicates whether an enqueue response should be DMA'd
124 * after success (otherwise a response is DMA'd only after failure).
125 * 'incomplete' indicates that other fragments of the same 'seqnum' are yet to
126 * be enqueued.
127 */
128void qbman_eq_desc_set_no_orp(struct qbman_eq_desc *, int respond_success);
129void qbman_eq_desc_set_response(struct qbman_eq_desc *,
130 dma_addr_t storage_phys,
131 int stash);
132/* token is the value that shows up in an enqueue response that can be used to
133 * detect when the results have been published. The easiest technique is to zero
134 * result "storage" before issuing an enqueue, and use any non-zero 'token'
135 * value. */
136void qbman_eq_desc_set_token(struct qbman_eq_desc *, uint8_t token);
137/* Exactly one of the following descriptor "targets" should be set. (Calling any
138 * one of these will replace the effect of any prior call to one of these.)
139 * - enqueue to a frame queue
140 * - enqueue to a queuing destination
141 * Note, that none of these will have any affect if the "action" type has been
142 * set to "orp_hole" or "orp_nesn".
143 */
144void qbman_eq_desc_set_fq(struct qbman_eq_desc *, uint32_t fqid);
145void qbman_eq_desc_set_qd(struct qbman_eq_desc *, uint32_t qdid,
146 uint32_t qd_bin, uint32_t qd_prio);
147
148/* Issue an enqueue command. ('fd' should only be NULL if the "action" of the
149 * descriptor is "orp_hole" or "orp_nesn".) */
150int qbman_swp_enqueue(struct qbman_swp *, const struct qbman_eq_desc *,
151 const struct qbman_fd *fd);
152
153 /*******************/
154 /* Buffer releases */
155 /*******************/
156
157struct qbman_release_desc {
158 uint32_t dont_manipulate_directly[1];
159};
160
161/* Clear the contents of a descriptor to default/starting state. */
162void qbman_release_desc_clear(struct qbman_release_desc *);
163/* Set the ID of the buffer pool to release to */
164void qbman_release_desc_set_bpid(struct qbman_release_desc *, uint32_t bpid);
165/* Issue a release command. 'num_buffers' must be less than 8. */
166int qbman_swp_release(struct qbman_swp *, const struct qbman_release_desc *,
167 const uint64_t *buffers, unsigned int num_buffers);
168
169 /*******************/
170 /* Buffer acquires */
171 /*******************/
172
173int qbman_swp_acquire(struct qbman_swp *, uint32_t bpid, uint64_t *buffers,
174 unsigned int num_buffers);
175#endif /* !_FSL_QBMAN_PORTAL_H */