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