Loading...
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-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
16struct device;
17struct page;
18struct scatterlist;
19struct sk_buff;
20
21struct gsi;
22struct 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 */
50struct 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 */
83int 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 */
93void *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 */
99void 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 */
113int 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 */
125void *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 */
132void 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 */
142bool 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 */
154struct 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 */
162void 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 */
172void 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 */
182int 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 */
192int 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 */
199void 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 */
206void 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 */
217int 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 */
227void gsi_trans_read_byte_done(struct gsi *gsi, u32 channel_id);
228
229#endif /* _GSI_TRANS_H_ */