drivers/net/ipa/gsi_trans.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2
   3 /* Copyright (c) 2012-2018, The Linux Foundation. All rights reserved.
   4  * Copyright (C) 2019-2024 Linaro Ltd.
   5  */
   6 #ifndef _GSI_TRANS_H_
   7 #define _GSI_TRANS_H_
   8
   9 #include <linux/completion.h>
  10 #include <linux/dma-direction.h>
  11 #include <linux/refcount.h>
  12 #include <linux/types.h>
  13
  14 #include "ipa_cmd.h"
  15
  16 struct device;
  17 struct page;
  18 struct scatterlist;
  19 struct sk_buff;
  20
  21 struct gsi;
  22 struct gsi_trans_pool;
  23
  24 /* Maximum number of TREs in an IPA immediate command transaction */
  25 #define IPA_COMMAND_TRANS_TRE_MAX       8
  26
  27 /**
  28  * struct gsi_trans - a GSI transaction
  29  *
  30  * Most fields in this structure for internal use by the transaction core code:
  31  * @gsi:        GSI pointer
  32  * @channel_id: Channel number transaction is associated with
  33  * @cancelled:  If set by the core code, transaction was cancelled
  34  * @rsvd_count: Number of TREs reserved for this transaction
  35  * @used_count: Number of TREs *used* (could be less than rsvd_count)
  36  * @len:        Number of bytes sent or received by the transaction
  37  * @data:       Preserved but not touched by the core transaction code
  38  * @cmd_opcode: Array of command opcodes (command channel only)
  39  * @sgl:        An array of scatter/gather entries managed by core code
  40  * @direction:  DMA transfer direction (DMA_NONE for commands)
  41  * @refcount:   Reference count used for destruction
  42  * @completion: Completed when the transaction completes
  43  * @byte_count: TX channel byte count recorded when transaction committed
  44  * @trans_count: Channel transaction count when committed (for BQL accounting)
  45  *
  46  * The @len field is set when the transaction is committed.  For RX
  47  * transactions it is updated later to reflect the actual number of bytes
  48  * received.
  49  */
  50 struct gsi_trans {
  51         struct gsi *gsi;
  52         u8 channel_id;
  53
  54         bool cancelled;                 /* true if transaction was cancelled */
  55
  56         u8 rsvd_count;                  /* # TREs requested */
  57         u8 used_count;                  /* # entries used in sgl[] */
  58         u32 len;                        /* total # bytes across sgl[] */
  59
  60         union {
  61                 void *data;
  62                 u8 cmd_opcode[IPA_COMMAND_TRANS_TRE_MAX];
  63         };
  64         struct scatterlist *sgl;
  65         enum dma_data_direction direction;
  66
  67         refcount_t refcount;
  68         struct completion completion;
  69
  70         u64 byte_count;                 /* channel byte_count when committed */
  71         u64 trans_count;                /* channel trans_count when committed */
  72 };
  73
  74 /**
  75  * gsi_trans_pool_init() - Initialize a pool of structures for transactions
  76  * @pool:       GSI transaction pool pointer
  77  * @size:       Size of elements in the pool
  78  * @count:      Minimum number of elements in the pool
  79  * @max_alloc:  Maximum number of elements allocated at a time from pool
  80  *
  81  * Return:      0 if successful, or a negative error code
  82  */
  83 int gsi_trans_pool_init(struct gsi_trans_pool *pool, size_t size, u32 count,
  84                         u32 max_alloc);
  85
  86 /**
  87  * gsi_trans_pool_alloc() - Allocate one or more elements from a pool
  88  * @pool:       Pool pointer
  89  * @count:      Number of elements to allocate from the pool
  90  *
  91  * Return:      Virtual address of element(s) allocated from the pool
  92  */
  93 void *gsi_trans_pool_alloc(struct gsi_trans_pool *pool, u32 count);
  94
  95 /**
  96  * gsi_trans_pool_exit() - Inverse of gsi_trans_pool_init()
  97  * @pool:       Pool pointer
  98  */
  99 void gsi_trans_pool_exit(struct gsi_trans_pool *pool);
 100
 101 /**
 102  * gsi_trans_pool_init_dma() - Initialize a pool of DMA-able structures
 103  * @dev:        Device used for DMA
 104  * @pool:       Pool pointer
 105  * @size:       Size of elements in the pool
 106  * @count:      Minimum number of elements in the pool
 107  * @max_alloc:  Maximum number of elements allocated at a time from pool
 108  *
 109  * Return:      0 if successful, or a negative error code
 110  *
 111  * Structures in this pool reside in DMA-coherent memory.
 112  */
 113 int gsi_trans_pool_init_dma(struct device *dev, struct gsi_trans_pool *pool,
 114                             size_t size, u32 count, u32 max_alloc);
 115
 116 /**
 117  * gsi_trans_pool_alloc_dma() - Allocate an element from a DMA pool
 118  * @pool:       DMA pool pointer
 119  * @addr:       DMA address "handle" associated with the allocation
 120  *
 121  * Return:      Virtual address of element allocated from the pool
 122  *
 123  * Only one element at a time may be allocated from a DMA pool.
 124  */
 125 void *gsi_trans_pool_alloc_dma(struct gsi_trans_pool *pool, dma_addr_t *addr);
 126
 127 /**
 128  * gsi_trans_pool_exit_dma() - Inverse of gsi_trans_pool_init_dma()
 129  * @dev:        Device used for DMA
 130  * @pool:       Pool pointer
 131  */
 132 void gsi_trans_pool_exit_dma(struct device *dev, struct gsi_trans_pool *pool);
 133
 134 /**
 135  * gsi_channel_trans_idle() - Return whether no transactions are allocated
 136  * @gsi:        GSI pointer
 137  * @channel_id: Channel the transaction is associated with
 138  *
 139  * Return:      True if no transactions are allocated, false otherwise
 140  *
 141  */
 142 bool gsi_channel_trans_idle(struct gsi *gsi, u32 channel_id);
 143
 144 /**
 145  * gsi_channel_trans_alloc() - Allocate a GSI transaction on a channel
 146  * @gsi:        GSI pointer
 147  * @channel_id: Channel the transaction is associated with
 148  * @tre_count:  Number of elements in the transaction
 149  * @direction:  DMA direction for entire SGL (or DMA_NONE)
 150  *
 151  * Return:      A GSI transaction structure, or a null pointer if all
 152  *              available transactions are in use
 153  */
 154 struct gsi_trans *gsi_channel_trans_alloc(struct gsi *gsi, u32 channel_id,
 155                                           u32 tre_count,
 156                                           enum dma_data_direction direction);
 157
 158 /**
 159  * gsi_trans_free() - Free a previously-allocated GSI transaction
 160  * @trans:      Transaction to be freed
 161  */
 162 void gsi_trans_free(struct gsi_trans *trans);
 163
 164 /**
 165  * gsi_trans_cmd_add() - Add an immediate command to a transaction
 166  * @trans:      Transaction
 167  * @buf:        Buffer pointer for command payload
 168  * @size:       Number of bytes in buffer
 169  * @addr:       DMA address for payload
 170  * @opcode:     IPA immediate command opcode
 171  */
 172 void gsi_trans_cmd_add(struct gsi_trans *trans, void *buf, u32 size,
 173                        dma_addr_t addr, enum ipa_cmd_opcode opcode);
 174
 175 /**
 176  * gsi_trans_page_add() - Add a page transfer to a transaction
 177  * @trans:      Transaction
 178  * @page:       Page pointer
 179  * @size:       Number of bytes (starting at offset) to transfer
 180  * @offset:     Offset within page for start of transfer
 181  */
 182 int gsi_trans_page_add(struct gsi_trans *trans, struct page *page, u32 size,
 183                        u32 offset);
 184
 185 /**
 186  * gsi_trans_skb_add() - Add a socket transfer to a transaction
 187  * @trans:      Transaction
 188  * @skb:        Socket buffer for transfer (outbound)
 189  *
 190  * Return:      0, or -EMSGSIZE if socket data won't fit in transaction.
 191  */
 192 int gsi_trans_skb_add(struct gsi_trans *trans, struct sk_buff *skb);
 193
 194 /**
 195  * gsi_trans_commit() - Commit a GSI transaction
 196  * @trans:      Transaction to commit
 197  * @ring_db:    Whether to tell the hardware about these queued transfers
 198  */
 199 void gsi_trans_commit(struct gsi_trans *trans, bool ring_db);
 200
 201 /**
 202  * gsi_trans_commit_wait() - Commit a GSI transaction and wait for it
 203  *                           to complete
 204  * @trans:      Transaction to commit
 205  */
 206 void gsi_trans_commit_wait(struct gsi_trans *trans);
 207
 208 /**
 209  * gsi_trans_read_byte() - Issue a single byte read TRE on a channel
 210  * @gsi:        GSI pointer
 211  * @channel_id: Channel on which to read a byte
 212  * @addr:       DMA address into which to transfer the one byte
 213  *
 214  * This is not a transaction operation at all.  It's defined here because
 215  * it needs to be done in coordination with other transaction activity.
 216  */
 217 int gsi_trans_read_byte(struct gsi *gsi, u32 channel_id, dma_addr_t addr);
 218
 219 /**
 220  * gsi_trans_read_byte_done() - Clean up after a single byte read TRE
 221  * @gsi:        GSI pointer
 222  * @channel_id: Channel on which byte was read
 223  *
 224  * This function needs to be called to signal that the work related
 225  * to reading a byte initiated by gsi_trans_read_byte() is complete.
 226  */
 227 void gsi_trans_read_byte_done(struct gsi *gsi, u32 channel_id);
 228
 229 #endif /* _GSI_TRANS_H_ */