1 | /* SPDX-License-Identifier: GPL-2.0 */ |
2 | /* |
3 | * K3 Ring Accelerator (RA) subsystem interface |
4 | * |
5 | * Copyright (C) 2019 Texas Instruments Incorporated - https://www.ti.com |
6 | */ |
7 | |
8 | #ifndef __SOC_TI_K3_RINGACC_API_H_ |
9 | #define __SOC_TI_K3_RINGACC_API_H_ |
10 | |
11 | #include <linux/types.h> |
12 | |
13 | struct device_node; |
14 | |
15 | /** |
16 | * enum k3_ring_mode - &struct k3_ring_cfg mode |
17 | * |
18 | * RA ring operational modes |
19 | * |
20 | * @K3_RINGACC_RING_MODE_RING: Exposed Ring mode for SW direct access |
21 | * @K3_RINGACC_RING_MODE_MESSAGE: Messaging mode. Messaging mode requires |
22 | * that all accesses to the queue must go through this IP so that all |
23 | * accesses to the memory are controlled and ordered. This IP then |
24 | * controls the entire state of the queue, and SW has no directly control, |
25 | * such as through doorbells and cannot access the storage memory directly. |
26 | * This is particularly useful when more than one SW or HW entity can be |
27 | * the producer and/or consumer at the same time |
28 | * @K3_RINGACC_RING_MODE_CREDENTIALS: Credentials mode is message mode plus |
29 | * stores credentials with each message, requiring the element size to be |
30 | * doubled to fit the credentials. Any exposed memory should be protected |
31 | * by a firewall from unwanted access |
32 | */ |
33 | enum k3_ring_mode { |
34 | K3_RINGACC_RING_MODE_RING = 0, |
35 | K3_RINGACC_RING_MODE_MESSAGE, |
36 | K3_RINGACC_RING_MODE_CREDENTIALS, |
37 | K3_RINGACC_RING_MODE_INVALID |
38 | }; |
39 | |
40 | /** |
41 | * enum k3_ring_size - &struct k3_ring_cfg elm_size |
42 | * |
43 | * RA ring element's sizes in bytes. |
44 | */ |
45 | enum k3_ring_size { |
46 | K3_RINGACC_RING_ELSIZE_4 = 0, |
47 | K3_RINGACC_RING_ELSIZE_8, |
48 | K3_RINGACC_RING_ELSIZE_16, |
49 | K3_RINGACC_RING_ELSIZE_32, |
50 | K3_RINGACC_RING_ELSIZE_64, |
51 | K3_RINGACC_RING_ELSIZE_128, |
52 | K3_RINGACC_RING_ELSIZE_256, |
53 | K3_RINGACC_RING_ELSIZE_INVALID |
54 | }; |
55 | |
56 | struct k3_ringacc; |
57 | struct k3_ring; |
58 | |
59 | /** |
60 | * enum k3_ring_cfg - RA ring configuration structure |
61 | * |
62 | * @size: Ring size, number of elements |
63 | * @elm_size: Ring element size |
64 | * @mode: Ring operational mode |
65 | * @flags: Ring configuration flags. Possible values: |
66 | * @K3_RINGACC_RING_SHARED: when set allows to request the same ring |
67 | * few times. It's usable when the same ring is used as Free Host PD ring |
68 | * for different flows, for example. |
69 | * Note: Locking should be done by consumer if required |
70 | * @dma_dev: Master device which is using and accessing to the ring |
71 | * memory when the mode is K3_RINGACC_RING_MODE_RING. Memory allocations |
72 | * should be done using this device. |
73 | * @asel: Address Space Select value for physical addresses |
74 | */ |
75 | struct k3_ring_cfg { |
76 | u32 size; |
77 | enum k3_ring_size elm_size; |
78 | enum k3_ring_mode mode; |
79 | #define K3_RINGACC_RING_SHARED BIT(1) |
80 | u32 flags; |
81 | |
82 | struct device *dma_dev; |
83 | u32 asel; |
84 | }; |
85 | |
86 | #define K3_RINGACC_RING_ID_ANY (-1) |
87 | |
88 | /** |
89 | * of_k3_ringacc_get_by_phandle - find a RA by phandle property |
90 | * @np: device node |
91 | * @propname: property name containing phandle on RA node |
92 | * |
93 | * Returns pointer on the RA - struct k3_ringacc |
94 | * or -ENODEV if not found, |
95 | * or -EPROBE_DEFER if not yet registered |
96 | */ |
97 | struct k3_ringacc *of_k3_ringacc_get_by_phandle(struct device_node *np, |
98 | const char *property); |
99 | |
100 | #define K3_RINGACC_RING_USE_PROXY BIT(1) |
101 | |
102 | /** |
103 | * k3_ringacc_request_ring - request ring from ringacc |
104 | * @ringacc: pointer on ringacc |
105 | * @id: ring id or K3_RINGACC_RING_ID_ANY for any general purpose ring |
106 | * @flags: |
107 | * @K3_RINGACC_RING_USE_PROXY: if set - proxy will be allocated and |
108 | * used to access ring memory. Sopported only for rings in |
109 | * Message/Credentials/Queue mode. |
110 | * |
111 | * Returns pointer on the Ring - struct k3_ring |
112 | * or NULL in case of failure. |
113 | */ |
114 | struct k3_ring *k3_ringacc_request_ring(struct k3_ringacc *ringacc, |
115 | int id, u32 flags); |
116 | |
117 | int k3_ringacc_request_rings_pair(struct k3_ringacc *ringacc, |
118 | int fwd_id, int compl_id, |
119 | struct k3_ring **fwd_ring, |
120 | struct k3_ring **compl_ring); |
121 | /** |
122 | * k3_ringacc_ring_reset - ring reset |
123 | * @ring: pointer on Ring |
124 | * |
125 | * Resets ring internal state ((hw)occ, (hw)idx). |
126 | */ |
127 | void k3_ringacc_ring_reset(struct k3_ring *ring); |
128 | /** |
129 | * k3_ringacc_ring_reset - ring reset for DMA rings |
130 | * @ring: pointer on Ring |
131 | * |
132 | * Resets ring internal state ((hw)occ, (hw)idx). Should be used for rings |
133 | * which are read by K3 UDMA, like TX or Free Host PD rings. |
134 | */ |
135 | void k3_ringacc_ring_reset_dma(struct k3_ring *ring, u32 occ); |
136 | |
137 | /** |
138 | * k3_ringacc_ring_free - ring free |
139 | * @ring: pointer on Ring |
140 | * |
141 | * Resets ring and free all alocated resources. |
142 | */ |
143 | int k3_ringacc_ring_free(struct k3_ring *ring); |
144 | |
145 | /** |
146 | * k3_ringacc_get_ring_id - Get the Ring ID |
147 | * @ring: pointer on ring |
148 | * |
149 | * Returns the Ring ID |
150 | */ |
151 | u32 k3_ringacc_get_ring_id(struct k3_ring *ring); |
152 | |
153 | /** |
154 | * k3_ringacc_get_ring_irq_num - Get the irq number for the ring |
155 | * @ring: pointer on ring |
156 | * |
157 | * Returns the interrupt number which can be used to request the interrupt |
158 | */ |
159 | int k3_ringacc_get_ring_irq_num(struct k3_ring *ring); |
160 | |
161 | /** |
162 | * k3_ringacc_ring_cfg - ring configure |
163 | * @ring: pointer on ring |
164 | * @cfg: Ring configuration parameters (see &struct k3_ring_cfg) |
165 | * |
166 | * Configures ring, including ring memory allocation. |
167 | * Returns 0 on success, errno otherwise. |
168 | */ |
169 | int k3_ringacc_ring_cfg(struct k3_ring *ring, struct k3_ring_cfg *cfg); |
170 | |
171 | /** |
172 | * k3_ringacc_ring_get_size - get ring size |
173 | * @ring: pointer on ring |
174 | * |
175 | * Returns ring size in number of elements. |
176 | */ |
177 | u32 k3_ringacc_ring_get_size(struct k3_ring *ring); |
178 | |
179 | /** |
180 | * k3_ringacc_ring_get_free - get free elements |
181 | * @ring: pointer on ring |
182 | * |
183 | * Returns number of free elements in the ring. |
184 | */ |
185 | u32 k3_ringacc_ring_get_free(struct k3_ring *ring); |
186 | |
187 | /** |
188 | * k3_ringacc_ring_get_occ - get ring occupancy |
189 | * @ring: pointer on ring |
190 | * |
191 | * Returns total number of valid entries on the ring |
192 | */ |
193 | u32 k3_ringacc_ring_get_occ(struct k3_ring *ring); |
194 | |
195 | /** |
196 | * k3_ringacc_ring_is_full - checks if ring is full |
197 | * @ring: pointer on ring |
198 | * |
199 | * Returns true if the ring is full |
200 | */ |
201 | u32 k3_ringacc_ring_is_full(struct k3_ring *ring); |
202 | |
203 | /** |
204 | * k3_ringacc_ring_push - push element to the ring tail |
205 | * @ring: pointer on ring |
206 | * @elem: pointer on ring element buffer |
207 | * |
208 | * Push one ring element to the ring tail. Size of the ring element is |
209 | * determined by ring configuration &struct k3_ring_cfg elm_size. |
210 | * |
211 | * Returns 0 on success, errno otherwise. |
212 | */ |
213 | int k3_ringacc_ring_push(struct k3_ring *ring, void *elem); |
214 | |
215 | /** |
216 | * k3_ringacc_ring_pop - pop element from the ring head |
217 | * @ring: pointer on ring |
218 | * @elem: pointer on ring element buffer |
219 | * |
220 | * Push one ring element from the ring head. Size of the ring element is |
221 | * determined by ring configuration &struct k3_ring_cfg elm_size.. |
222 | * |
223 | * Returns 0 on success, errno otherwise. |
224 | */ |
225 | int k3_ringacc_ring_pop(struct k3_ring *ring, void *elem); |
226 | |
227 | /** |
228 | * k3_ringacc_ring_push_head - push element to the ring head |
229 | * @ring: pointer on ring |
230 | * @elem: pointer on ring element buffer |
231 | * |
232 | * Push one ring element to the ring head. Size of the ring element is |
233 | * determined by ring configuration &struct k3_ring_cfg elm_size. |
234 | * |
235 | * Returns 0 on success, errno otherwise. |
236 | * Not Supported by ring modes: K3_RINGACC_RING_MODE_RING |
237 | */ |
238 | int k3_ringacc_ring_push_head(struct k3_ring *ring, void *elem); |
239 | |
240 | /** |
241 | * k3_ringacc_ring_pop_tail - pop element from the ring tail |
242 | * @ring: pointer on ring |
243 | * @elem: pointer on ring element buffer |
244 | * |
245 | * Push one ring element from the ring tail. Size of the ring element is |
246 | * determined by ring configuration &struct k3_ring_cfg elm_size. |
247 | * |
248 | * Returns 0 on success, errno otherwise. |
249 | * Not Supported by ring modes: K3_RINGACC_RING_MODE_RING |
250 | */ |
251 | int k3_ringacc_ring_pop_tail(struct k3_ring *ring, void *elem); |
252 | |
253 | u32 k3_ringacc_get_tisci_dev_id(struct k3_ring *ring); |
254 | |
255 | /* DMA ring support */ |
256 | struct ti_sci_handle; |
257 | |
258 | /** |
259 | * struct struct k3_ringacc_init_data - Initialization data for DMA rings |
260 | */ |
261 | struct k3_ringacc_init_data { |
262 | const struct ti_sci_handle *tisci; |
263 | u32 tisci_dev_id; |
264 | u32 num_rings; |
265 | }; |
266 | |
267 | struct k3_ringacc *k3_ringacc_dmarings_init(struct platform_device *pdev, |
268 | struct k3_ringacc_init_data *data); |
269 | |
270 | #endif /* __SOC_TI_K3_RINGACC_API_H_ */ |
271 | |