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_ */ 230