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