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