1 /*
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. */
14 struct 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. */
25 struct ldpaa_dq;
26 
27 
28 /* ------------------- */
29 /* Pull-mode dequeuing */
30 /* ------------------- */
31 
32 struct qbman_pull_desc {
33 	uint32_t dont_manipulate_directly[6];
34 };
35 
36 /* Clear the contents of a descriptor to default/starting state. */
37 void 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. */
43 void 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 */
48 void 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. */
53 void 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  */
60 void qbman_pull_desc_set_fq(struct qbman_pull_desc *, uint32_t fqid);
61 
62 /* Issue the pull dequeue command */
63 int 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. */
72 const struct ldpaa_dq *qbman_swp_dqrr_next(struct qbman_swp *);
73 /* Consume DQRR entries previously returned from qbman_swp_dqrr_next(). */
74 void 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  */
92 void qbman_dq_entry_set_oldtoken(struct ldpaa_dq *,
93 				 unsigned int num_entries,
94 				 uint8_t oldtoken);
95 int 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 */
104 int qbman_dq_entry_is_DQ(const struct ldpaa_dq *);
105 
106 	/************/
107 	/* Enqueues */
108 	/************/
109 
110 struct qbman_eq_desc {
111 	uint32_t dont_manipulate_directly[8];
112 };
113 
114 
115 /* Clear the contents of a descriptor to default/starting state. */
116 void 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  */
128 void qbman_eq_desc_set_no_orp(struct qbman_eq_desc *, int respond_success);
129 void 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. */
136 void 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  */
144 void qbman_eq_desc_set_fq(struct qbman_eq_desc *, uint32_t fqid);
145 void 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".) */
150 int qbman_swp_enqueue(struct qbman_swp *, const struct qbman_eq_desc *,
151 		      const struct qbman_fd *fd);
152 
153 	/*******************/
154 	/* Buffer releases */
155 	/*******************/
156 
157 struct qbman_release_desc {
158 	uint32_t dont_manipulate_directly[1];
159 };
160 
161 /* Clear the contents of a descriptor to default/starting state. */
162 void qbman_release_desc_clear(struct qbman_release_desc *);
163 /* Set the ID of the buffer pool to release to */
164 void qbman_release_desc_set_bpid(struct qbman_release_desc *, uint32_t bpid);
165 /* Issue a release command. 'num_buffers' must be less than 8. */
166 int 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 
173 int qbman_swp_acquire(struct qbman_swp *, uint32_t bpid, uint64_t *buffers,
174 		      unsigned int num_buffers);
175 #endif /* !_FSL_QBMAN_PORTAL_H */
176