tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1/* SPDX-License-Identifier: GPL-2.0 */
2/*
3 * K3 Ring Accelerator (RA) subsystem interface
4 *
5 * Copyright (C) 2019 Texas Instruments Incorporated - http://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 */
71struct k3_ring_cfg {
72 u32 size;
73 enum k3_ring_size elm_size;
74 enum k3_ring_mode mode;
75#define K3_RINGACC_RING_SHARED BIT(1)
76 u32 flags;
77};
78
79#define K3_RINGACC_RING_ID_ANY (-1)
80
81/**
82 * of_k3_ringacc_get_by_phandle - find a RA by phandle property
83 * @np: device node
84 * @propname: property name containing phandle on RA node
85 *
86 * Returns pointer on the RA - struct k3_ringacc
87 * or -ENODEV if not found,
88 * or -EPROBE_DEFER if not yet registered
89 */
90struct k3_ringacc *of_k3_ringacc_get_by_phandle(struct device_node *np,
91 const char *property);
92
93#define K3_RINGACC_RING_USE_PROXY BIT(1)
94
95/**
96 * k3_ringacc_request_ring - request ring from ringacc
97 * @ringacc: pointer on ringacc
98 * @id: ring id or K3_RINGACC_RING_ID_ANY for any general purpose ring
99 * @flags:
100 * @K3_RINGACC_RING_USE_PROXY: if set - proxy will be allocated and
101 * used to access ring memory. Sopported only for rings in
102 * Message/Credentials/Queue mode.
103 *
104 * Returns pointer on the Ring - struct k3_ring
105 * or NULL in case of failure.
106 */
107struct k3_ring *k3_ringacc_request_ring(struct k3_ringacc *ringacc,
108 int id, u32 flags);
109
110/**
111 * k3_ringacc_ring_reset - ring reset
112 * @ring: pointer on Ring
113 *
114 * Resets ring internal state ((hw)occ, (hw)idx).
115 */
116void k3_ringacc_ring_reset(struct k3_ring *ring);
117/**
118 * k3_ringacc_ring_reset - ring reset for DMA rings
119 * @ring: pointer on Ring
120 *
121 * Resets ring internal state ((hw)occ, (hw)idx). Should be used for rings
122 * which are read by K3 UDMA, like TX or Free Host PD rings.
123 */
124void k3_ringacc_ring_reset_dma(struct k3_ring *ring, u32 occ);
125
126/**
127 * k3_ringacc_ring_free - ring free
128 * @ring: pointer on Ring
129 *
130 * Resets ring and free all alocated resources.
131 */
132int k3_ringacc_ring_free(struct k3_ring *ring);
133
134/**
135 * k3_ringacc_get_ring_id - Get the Ring ID
136 * @ring: pointer on ring
137 *
138 * Returns the Ring ID
139 */
140u32 k3_ringacc_get_ring_id(struct k3_ring *ring);
141
142/**
143 * k3_ringacc_get_ring_irq_num - Get the irq number for the ring
144 * @ring: pointer on ring
145 *
146 * Returns the interrupt number which can be used to request the interrupt
147 */
148int k3_ringacc_get_ring_irq_num(struct k3_ring *ring);
149
150/**
151 * k3_ringacc_ring_cfg - ring configure
152 * @ring: pointer on ring
153 * @cfg: Ring configuration parameters (see &struct k3_ring_cfg)
154 *
155 * Configures ring, including ring memory allocation.
156 * Returns 0 on success, errno otherwise.
157 */
158int k3_ringacc_ring_cfg(struct k3_ring *ring, struct k3_ring_cfg *cfg);
159
160/**
161 * k3_ringacc_ring_get_size - get ring size
162 * @ring: pointer on ring
163 *
164 * Returns ring size in number of elements.
165 */
166u32 k3_ringacc_ring_get_size(struct k3_ring *ring);
167
168/**
169 * k3_ringacc_ring_get_free - get free elements
170 * @ring: pointer on ring
171 *
172 * Returns number of free elements in the ring.
173 */
174u32 k3_ringacc_ring_get_free(struct k3_ring *ring);
175
176/**
177 * k3_ringacc_ring_get_occ - get ring occupancy
178 * @ring: pointer on ring
179 *
180 * Returns total number of valid entries on the ring
181 */
182u32 k3_ringacc_ring_get_occ(struct k3_ring *ring);
183
184/**
185 * k3_ringacc_ring_is_full - checks if ring is full
186 * @ring: pointer on ring
187 *
188 * Returns true if the ring is full
189 */
190u32 k3_ringacc_ring_is_full(struct k3_ring *ring);
191
192/**
193 * k3_ringacc_ring_push - push element to the ring tail
194 * @ring: pointer on ring
195 * @elem: pointer on ring element buffer
196 *
197 * Push one ring element to the ring tail. Size of the ring element is
198 * determined by ring configuration &struct k3_ring_cfg elm_size.
199 *
200 * Returns 0 on success, errno otherwise.
201 */
202int k3_ringacc_ring_push(struct k3_ring *ring, void *elem);
203
204/**
205 * k3_ringacc_ring_pop - pop element from the ring head
206 * @ring: pointer on ring
207 * @elem: pointer on ring element buffer
208 *
209 * Push one ring element from the ring head. Size of the ring element is
210 * determined by ring configuration &struct k3_ring_cfg elm_size..
211 *
212 * Returns 0 on success, errno otherwise.
213 */
214int k3_ringacc_ring_pop(struct k3_ring *ring, void *elem);
215
216/**
217 * k3_ringacc_ring_push_head - push element to the ring head
218 * @ring: pointer on ring
219 * @elem: pointer on ring element buffer
220 *
221 * Push one ring element to the ring head. Size of the ring element is
222 * determined by ring configuration &struct k3_ring_cfg elm_size.
223 *
224 * Returns 0 on success, errno otherwise.
225 * Not Supported by ring modes: K3_RINGACC_RING_MODE_RING
226 */
227int k3_ringacc_ring_push_head(struct k3_ring *ring, void *elem);
228
229/**
230 * k3_ringacc_ring_pop_tail - pop element from the ring tail
231 * @ring: pointer on ring
232 * @elem: pointer on ring element buffer
233 *
234 * Push one ring element from the ring tail. Size of the ring element is
235 * determined by ring configuration &struct k3_ring_cfg elm_size.
236 *
237 * Returns 0 on success, errno otherwise.
238 * Not Supported by ring modes: K3_RINGACC_RING_MODE_RING
239 */
240int k3_ringacc_ring_pop_tail(struct k3_ring *ring, void *elem);
241
242u32 k3_ringacc_get_tisci_dev_id(struct k3_ring *ring);
243
244#endif /* __SOC_TI_K3_RINGACC_API_H_ */