include/linux/soc/ti/k3-navss-ringacc.h

   1 /* SPDX-License-Identifier: GPL-2.0+ */
   2 /*
   3  * TI K3 AM65x NAVSS Ring accelerator Manager (RA) subsystem driver
   4  *
   5  * Copyright (C) 2018 Texas Instruments Incorporated - http://www.ti.com
   6  */
   7
   8 #ifndef __SOC_TI_K3_NAVSS_RINGACC_API_H_
   9 #define __SOC_TI_K3_NAVSS_RINGACC_API_H_
  10
  11 #include <dm/ofnode.h>
  12
  13 /**
  14  * enum k3_nav_ring_mode - &struct k3_nav_ring_cfg mode
  15  *
  16  * RA ring operational modes
  17  *
  18  * @K3_NAV_RINGACC_RING_MODE_RING: Exposed Ring mode for SW direct access
  19  * @K3_NAV_RINGACC_RING_MODE_MESSAGE: Messaging mode. Messaging mode requires
  20  *      that all accesses to the queue must go through this IP so that all
  21  *      accesses to the memory are controlled and ordered. This IP then
  22  *      controls the entire state of the queue, and SW has no directly control,
  23  *      such as through doorbells and cannot access the storage memory directly.
  24  *      This is particularly useful when more than one SW or HW entity can be
  25  *      the producer and/or consumer at the same time
  26  * @K3_NAV_RINGACC_RING_MODE_CREDENTIALS: Credentials mode is message mode plus
  27  *      stores credentials with each message, requiring the element size to be
  28  *      doubled to fit the credentials. Any exposed memory should be protected
  29  *      by a firewall from unwanted access
  30  * @K3_NAV_RINGACC_RING_MODE_QM:  Queue manager mode. This takes the credentials
  31  *      mode and adds packet length per element, along with additional read only
  32  *      fields for element count and accumulated queue length. The QM mode only
  33  *      operates with an 8 byte element size (any other element size is
  34  *      illegal), and like in credentials mode each operation uses 2 element
  35  *      slots to store the credentials and length fields
  36  */
  37 enum k3_nav_ring_mode {
  38         K3_NAV_RINGACC_RING_MODE_RING = 0,
  39         K3_NAV_RINGACC_RING_MODE_MESSAGE,
  40         K3_NAV_RINGACC_RING_MODE_CREDENTIALS,
  41         K3_NAV_RINGACC_RING_MODE_QM,
  42         k3_NAV_RINGACC_RING_MODE_INVALID
  43 };
  44
  45 /**
  46  * enum k3_nav_ring_size - &struct k3_nav_ring_cfg elm_size
  47  *
  48  * RA ring element's sizes in bytes.
  49  */
  50 enum k3_nav_ring_size {
  51         K3_NAV_RINGACC_RING_ELSIZE_4 = 0,
  52         K3_NAV_RINGACC_RING_ELSIZE_8,
  53         K3_NAV_RINGACC_RING_ELSIZE_16,
  54         K3_NAV_RINGACC_RING_ELSIZE_32,
  55         K3_NAV_RINGACC_RING_ELSIZE_64,
  56         K3_NAV_RINGACC_RING_ELSIZE_128,
  57         K3_NAV_RINGACC_RING_ELSIZE_256,
  58         K3_NAV_RINGACC_RING_ELSIZE_INVALID
  59 };
  60
  61 struct k3_nav_ringacc;
  62 struct k3_nav_ring;
  63
  64 /**
  65  * enum k3_nav_ring_cfg - RA ring configuration structure
  66  *
  67  * @size: Ring size, number of elements
  68  * @elm_size: Ring element size
  69  * @mode: Ring operational mode
  70  * @flags: Ring configuration flags. Possible values:
  71  *       @K3_NAV_RINGACC_RING_SHARED: when set allows to request the same ring
  72  *       few times. It's usable when the same ring is used as Free Host PD ring
  73  *       for different flows, for example.
  74  *       Note: Locking should be done by consumer if required
  75  */
  76 struct k3_nav_ring_cfg {
  77         u32 size;
  78         enum k3_nav_ring_size elm_size;
  79         enum k3_nav_ring_mode mode;
  80 #define K3_NAV_RINGACC_RING_SHARED BIT(1)
  81         u32 flags;
  82 };
  83
  84 #define K3_NAV_RINGACC_RING_ID_ANY (-1)
  85 #define K3_NAV_RINGACC_RING_USE_PROXY BIT(1)
  86
  87 /**
  88  * k3_nav_ringacc_request_ring - request ring from ringacc
  89  * @ringacc: pointer on ringacc
  90  * @id: ring id or K3_NAV_RINGACC_RING_ID_ANY for any general purpose ring
  91  * @flags:
  92  *      @K3_NAV_RINGACC_RING_USE_PROXY: if set - proxy will be allocated and
  93  *              used to access ring memory. Sopported only for rings in
  94  *              Message/Credentials/Queue mode.
  95  *
  96  * Returns pointer on the Ring - struct k3_nav_ring
  97  * or NULL in case of failure.
  98  */
  99 struct k3_nav_ring *k3_nav_ringacc_request_ring(struct k3_nav_ringacc *ringacc,
 100                                                 int id, u32 flags);
 101
 102 /**
 103  * k3_nav_ringacc_get_dev - get pointer on RA device
 104  * @ringacc: pointer on RA
 105  *
 106  * Returns device pointer
 107  */
 108 struct udevice *k3_nav_ringacc_get_dev(struct k3_nav_ringacc *ringacc);
 109
 110 /**
 111  * k3_nav_ringacc_ring_reset - ring reset
 112  * @ring: pointer on Ring
 113  *
 114  * Resets ring internal state ((hw)occ, (hw)idx).
 115  * TODO_GS: ? Ring can be reused without reconfiguration
 116  */
 117 void k3_nav_ringacc_ring_reset(struct k3_nav_ring *ring);
 118 /**
 119  * k3_nav_ringacc_ring_reset - ring reset for DMA rings
 120  * @ring: pointer on Ring
 121  *
 122  * Resets ring internal state ((hw)occ, (hw)idx). Should be used for rings
 123  * which are read by K3 UDMA, like TX or Free Host PD rings.
 124  */
 125 void k3_nav_ringacc_ring_reset_dma(struct k3_nav_ring *ring, u32 occ);
 126
 127 /**
 128  * k3_nav_ringacc_ring_free - ring free
 129  * @ring: pointer on Ring
 130  *
 131  * Resets ring and free all alocated resources.
 132  */
 133 int k3_nav_ringacc_ring_free(struct k3_nav_ring *ring);
 134
 135 /**
 136  * k3_nav_ringacc_get_ring_id - Get the Ring ID
 137  * @ring: pointer on ring
 138  *
 139  * Returns the Ring ID
 140  */
 141 u32 k3_nav_ringacc_get_ring_id(struct k3_nav_ring *ring);
 142
 143 /**
 144  * k3_nav_ringacc_ring_cfg - ring configure
 145  * @ring: pointer on ring
 146  * @cfg: Ring configuration parameters (see &struct k3_nav_ring_cfg)
 147  *
 148  * Configures ring, including ring memory allocation.
 149  * Returns 0 on success, errno otherwise.
 150  */
 151 int k3_nav_ringacc_ring_cfg(struct k3_nav_ring *ring,
 152                             struct k3_nav_ring_cfg *cfg);
 153
 154 /**
 155  * k3_nav_ringacc_ring_get_size - get ring size
 156  * @ring: pointer on ring
 157  *
 158  * Returns ring size in number of elements.
 159  */
 160 u32 k3_nav_ringacc_ring_get_size(struct k3_nav_ring *ring);
 161
 162 /**
 163  * k3_nav_ringacc_ring_get_free - get free elements
 164  * @ring: pointer on ring
 165  *
 166  * Returns number of free elements in the ring.
 167  */
 168 u32 k3_nav_ringacc_ring_get_free(struct k3_nav_ring *ring);
 169
 170 /**
 171  * k3_nav_ringacc_ring_get_occ - get ring occupancy
 172  * @ring: pointer on ring
 173  *
 174  * Returns total number of valid entries on the ring
 175  */
 176 u32 k3_nav_ringacc_ring_get_occ(struct k3_nav_ring *ring);
 177
 178 /**
 179  * k3_nav_ringacc_ring_is_full - checks if ring is full
 180  * @ring: pointer on ring
 181  *
 182  * Returns true if the ring is full
 183  */
 184 u32 k3_nav_ringacc_ring_is_full(struct k3_nav_ring *ring);
 185
 186 /**
 187  * k3_nav_ringacc_ring_push - push element to the ring tail
 188  * @ring: pointer on ring
 189  * @elem: pointer on ring element buffer
 190  *
 191  * Push one ring element to the ring tail. Size of the ring element is
 192  * determined by ring configuration &struct k3_nav_ring_cfg elm_size.
 193  *
 194  * Returns 0 on success, errno otherwise.
 195  */
 196 int k3_nav_ringacc_ring_push(struct k3_nav_ring *ring, void *elem);
 197
 198 /**
 199  * k3_nav_ringacc_ring_pop - pop element from the ring head
 200  * @ring: pointer on ring
 201  * @elem: pointer on ring element buffer
 202  *
 203  * Push one ring element from the ring head. Size of the ring element is
 204  * determined by ring configuration &struct k3_nav_ring_cfg elm_size..
 205  *
 206  * Returns 0 on success, errno otherwise.
 207  */
 208 int k3_nav_ringacc_ring_pop(struct k3_nav_ring *ring, void *elem);
 209
 210 /**
 211  * k3_nav_ringacc_ring_push_head - push element to the ring head
 212  * @ring: pointer on ring
 213  * @elem: pointer on ring element buffer
 214  *
 215  * Push one ring element to the ring head. Size of the ring element is
 216  * determined by ring configuration &struct k3_nav_ring_cfg elm_size.
 217  *
 218  * Returns 0 on success, errno otherwise.
 219  * Not Supported by ring modes: K3_NAV_RINGACC_RING_MODE_RING
 220  */
 221 int k3_nav_ringacc_ring_push_head(struct k3_nav_ring *ring, void *elem);
 222
 223 /**
 224  * k3_nav_ringacc_ring_pop_tail - pop element from the ring tail
 225  * @ring: pointer on ring
 226  * @elem: pointer on ring element buffer
 227  *
 228  * Push one ring element from the ring tail. Size of the ring element is
 229  * determined by ring configuration &struct k3_nav_ring_cfg elm_size.
 230  *
 231  * Returns 0 on success, errno otherwise.
 232  * Not Supported by ring modes: K3_NAV_RINGACC_RING_MODE_RING
 233  */
 234 int k3_nav_ringacc_ring_pop_tail(struct k3_nav_ring *ring, void *elem);
 235
 236 #endif /* __SOC_TI_K3_NAVSS_RINGACC_API_H_ */