k3-ringacc.h

  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
 13struct 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 */
 33enum 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 */
 45enum 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
 56struct k3_ringacc;
 57struct 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 */
 75struct 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 */
 97struct 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 */
114struct k3_ring *k3_ringacc_request_ring(struct k3_ringacc *ringacc,
115					int id, u32 flags);
116
117int 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 */
127void 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 */
135void 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 */
143int 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 */
151u32 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 */
159int 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 */
169int 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 */
177u32 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 */
185u32 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 */
193u32 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 */
201u32 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 */
213int 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 */
225int 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 */
238int 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 */
251int k3_ringacc_ring_pop_tail(struct k3_ring *ring, void *elem);
252
253u32 k3_ringacc_get_tisci_dev_id(struct k3_ring *ring);
254
255/* DMA ring support */
256struct ti_sci_handle;
257
258/**
259 * struct struct k3_ringacc_init_data - Initialization data for DMA rings
260 */
261struct k3_ringacc_init_data {
262	const struct ti_sci_handle *tisci;
263	u32 tisci_dev_id;
264	u32 num_rings;
265};
266
267struct 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_ */