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