linux/include/linux/soc/ti/k3-ringacc.h
<<
>>
Prefs
   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 */
  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
 110int k3_ringacc_request_rings_pair(struct k3_ringacc *ringacc,
 111                                  int fwd_id, int compl_id,
 112                                  struct k3_ring **fwd_ring,
 113                                  struct k3_ring **compl_ring);
 114/**
 115 * k3_ringacc_ring_reset - ring reset
 116 * @ring: pointer on Ring
 117 *
 118 * Resets ring internal state ((hw)occ, (hw)idx).
 119 */
 120void k3_ringacc_ring_reset(struct k3_ring *ring);
 121/**
 122 * k3_ringacc_ring_reset - ring reset for DMA rings
 123 * @ring: pointer on Ring
 124 *
 125 * Resets ring internal state ((hw)occ, (hw)idx). Should be used for rings
 126 * which are read by K3 UDMA, like TX or Free Host PD rings.
 127 */
 128void k3_ringacc_ring_reset_dma(struct k3_ring *ring, u32 occ);
 129
 130/**
 131 * k3_ringacc_ring_free - ring free
 132 * @ring: pointer on Ring
 133 *
 134 * Resets ring and free all alocated resources.
 135 */
 136int k3_ringacc_ring_free(struct k3_ring *ring);
 137
 138/**
 139 * k3_ringacc_get_ring_id - Get the Ring ID
 140 * @ring: pointer on ring
 141 *
 142 * Returns the Ring ID
 143 */
 144u32 k3_ringacc_get_ring_id(struct k3_ring *ring);
 145
 146/**
 147 * k3_ringacc_get_ring_irq_num - Get the irq number for the ring
 148 * @ring: pointer on ring
 149 *
 150 * Returns the interrupt number which can be used to request the interrupt
 151 */
 152int k3_ringacc_get_ring_irq_num(struct k3_ring *ring);
 153
 154/**
 155 * k3_ringacc_ring_cfg - ring configure
 156 * @ring: pointer on ring
 157 * @cfg: Ring configuration parameters (see &struct k3_ring_cfg)
 158 *
 159 * Configures ring, including ring memory allocation.
 160 * Returns 0 on success, errno otherwise.
 161 */
 162int k3_ringacc_ring_cfg(struct k3_ring *ring, struct k3_ring_cfg *cfg);
 163
 164/**
 165 * k3_ringacc_ring_get_size - get ring size
 166 * @ring: pointer on ring
 167 *
 168 * Returns ring size in number of elements.
 169 */
 170u32 k3_ringacc_ring_get_size(struct k3_ring *ring);
 171
 172/**
 173 * k3_ringacc_ring_get_free - get free elements
 174 * @ring: pointer on ring
 175 *
 176 * Returns number of free elements in the ring.
 177 */
 178u32 k3_ringacc_ring_get_free(struct k3_ring *ring);
 179
 180/**
 181 * k3_ringacc_ring_get_occ - get ring occupancy
 182 * @ring: pointer on ring
 183 *
 184 * Returns total number of valid entries on the ring
 185 */
 186u32 k3_ringacc_ring_get_occ(struct k3_ring *ring);
 187
 188/**
 189 * k3_ringacc_ring_is_full - checks if ring is full
 190 * @ring: pointer on ring
 191 *
 192 * Returns true if the ring is full
 193 */
 194u32 k3_ringacc_ring_is_full(struct k3_ring *ring);
 195
 196/**
 197 * k3_ringacc_ring_push - push element to the ring tail
 198 * @ring: pointer on ring
 199 * @elem: pointer on ring element buffer
 200 *
 201 * Push one ring element to the ring tail. Size of the ring element is
 202 * determined by ring configuration &struct k3_ring_cfg elm_size.
 203 *
 204 * Returns 0 on success, errno otherwise.
 205 */
 206int k3_ringacc_ring_push(struct k3_ring *ring, void *elem);
 207
 208/**
 209 * k3_ringacc_ring_pop - pop element from the ring head
 210 * @ring: pointer on ring
 211 * @elem: pointer on ring element buffer
 212 *
 213 * Push one ring element from the ring head. Size of the ring element is
 214 * determined by ring configuration &struct k3_ring_cfg elm_size..
 215 *
 216 * Returns 0 on success, errno otherwise.
 217 */
 218int k3_ringacc_ring_pop(struct k3_ring *ring, void *elem);
 219
 220/**
 221 * k3_ringacc_ring_push_head - push element to the ring head
 222 * @ring: pointer on ring
 223 * @elem: pointer on ring element buffer
 224 *
 225 * Push one ring element to the ring head. Size of the ring element is
 226 * determined by ring configuration &struct k3_ring_cfg elm_size.
 227 *
 228 * Returns 0 on success, errno otherwise.
 229 * Not Supported by ring modes: K3_RINGACC_RING_MODE_RING
 230 */
 231int k3_ringacc_ring_push_head(struct k3_ring *ring, void *elem);
 232
 233/**
 234 * k3_ringacc_ring_pop_tail - pop element from the ring tail
 235 * @ring: pointer on ring
 236 * @elem: pointer on ring element buffer
 237 *
 238 * Push one ring element from the ring tail. Size of the ring element is
 239 * determined by ring configuration &struct k3_ring_cfg elm_size.
 240 *
 241 * Returns 0 on success, errno otherwise.
 242 * Not Supported by ring modes: K3_RINGACC_RING_MODE_RING
 243 */
 244int k3_ringacc_ring_pop_tail(struct k3_ring *ring, void *elem);
 245
 246u32 k3_ringacc_get_tisci_dev_id(struct k3_ring *ring);
 247
 248#endif /* __SOC_TI_K3_RINGACC_API_H_ */
 249