1 | /* SPDX-License-Identifier: GPL-2.0 |
2 | * |
3 | * compress_driver.h - compress offload driver definations |
4 | * |
5 | * Copyright (C) 2011 Intel Corporation |
6 | * Authors: Vinod Koul <vinod.koul@linux.intel.com> |
7 | * Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com> |
8 | */ |
9 | |
10 | #ifndef __COMPRESS_DRIVER_H |
11 | #define __COMPRESS_DRIVER_H |
12 | |
13 | #include <linux/types.h> |
14 | #include <linux/sched.h> |
15 | #include <sound/core.h> |
16 | #include <sound/compress_offload.h> |
17 | #include <sound/asound.h> |
18 | #include <sound/pcm.h> |
19 | |
20 | struct snd_compr_ops; |
21 | |
22 | /** |
23 | * struct snd_compr_runtime: runtime stream description |
24 | * @state: stream state |
25 | * @ops: pointer to DSP callbacks |
26 | * @buffer: pointer to kernel buffer, valid only when not in mmap mode or |
27 | * DSP doesn't implement copy |
28 | * @buffer_size: size of the above buffer |
29 | * @fragment_size: size of buffer fragment in bytes |
30 | * @fragments: number of such fragments |
31 | * @total_bytes_available: cumulative number of bytes made available in |
32 | * the ring buffer |
33 | * @total_bytes_transferred: cumulative bytes transferred by offload DSP |
34 | * @sleep: poll sleep |
35 | * @private_data: driver private data pointer |
36 | * @dma_area: virtual buffer address |
37 | * @dma_addr: physical buffer address (not accessible from main CPU) |
38 | * @dma_bytes: size of DMA area |
39 | * @dma_buffer_p: runtime dma buffer pointer |
40 | */ |
41 | struct snd_compr_runtime { |
42 | snd_pcm_state_t state; |
43 | struct snd_compr_ops *ops; |
44 | void *buffer; |
45 | u64 buffer_size; |
46 | u32 fragment_size; |
47 | u32 fragments; |
48 | u64 total_bytes_available; |
49 | u64 total_bytes_transferred; |
50 | wait_queue_head_t sleep; |
51 | void *private_data; |
52 | |
53 | unsigned char *dma_area; |
54 | dma_addr_t dma_addr; |
55 | size_t dma_bytes; |
56 | struct snd_dma_buffer *dma_buffer_p; |
57 | }; |
58 | |
59 | /** |
60 | * struct snd_compr_stream: compressed stream |
61 | * @name: device name |
62 | * @ops: pointer to DSP callbacks |
63 | * @runtime: pointer to runtime structure |
64 | * @device: device pointer |
65 | * @error_work: delayed work used when closing the stream due to an error |
66 | * @direction: stream direction, playback/recording |
67 | * @metadata_set: metadata set flag, true when set |
68 | * @next_track: has userspace signal next track transition, true when set |
69 | * @partial_drain: undergoing partial_drain for stream, true when set |
70 | * @pause_in_draining: paused during draining state, true when set |
71 | * @private_data: pointer to DSP private data |
72 | * @dma_buffer: allocated buffer if any |
73 | */ |
74 | struct snd_compr_stream { |
75 | const char *name; |
76 | struct snd_compr_ops *ops; |
77 | struct snd_compr_runtime *runtime; |
78 | struct snd_compr *device; |
79 | struct delayed_work error_work; |
80 | enum snd_compr_direction direction; |
81 | bool metadata_set; |
82 | bool next_track; |
83 | bool partial_drain; |
84 | bool pause_in_draining; |
85 | void *private_data; |
86 | struct snd_dma_buffer dma_buffer; |
87 | }; |
88 | |
89 | /** |
90 | * struct snd_compr_ops: compressed path DSP operations |
91 | * @open: Open the compressed stream |
92 | * This callback is mandatory and shall keep dsp ready to receive the stream |
93 | * parameter |
94 | * @free: Close the compressed stream, mandatory |
95 | * @set_params: Sets the compressed stream parameters, mandatory |
96 | * This can be called in during stream creation only to set codec params |
97 | * and the stream properties |
98 | * @get_params: retrieve the codec parameters, mandatory |
99 | * @set_metadata: Set the metadata values for a stream |
100 | * @get_metadata: retrieves the requested metadata values from stream |
101 | * @trigger: Trigger operations like start, pause, resume, drain, stop. |
102 | * This callback is mandatory |
103 | * @pointer: Retrieve current h/w pointer information. Mandatory |
104 | * @copy: Copy the compressed data to/from userspace, Optional |
105 | * Can't be implemented if DSP supports mmap |
106 | * @mmap: DSP mmap method to mmap DSP memory |
107 | * @ack: Ack for DSP when data is written to audio buffer, Optional |
108 | * Not valid if copy is implemented |
109 | * @get_caps: Retrieve DSP capabilities, mandatory |
110 | * @get_codec_caps: Retrieve capabilities for a specific codec, mandatory |
111 | */ |
112 | struct snd_compr_ops { |
113 | int (*open)(struct snd_compr_stream *stream); |
114 | int (*free)(struct snd_compr_stream *stream); |
115 | int (*set_params)(struct snd_compr_stream *stream, |
116 | struct snd_compr_params *params); |
117 | int (*get_params)(struct snd_compr_stream *stream, |
118 | struct snd_codec *params); |
119 | int (*set_metadata)(struct snd_compr_stream *stream, |
120 | struct snd_compr_metadata *metadata); |
121 | int (*get_metadata)(struct snd_compr_stream *stream, |
122 | struct snd_compr_metadata *metadata); |
123 | int (*trigger)(struct snd_compr_stream *stream, int cmd); |
124 | int (*pointer)(struct snd_compr_stream *stream, |
125 | struct snd_compr_tstamp *tstamp); |
126 | int (*copy)(struct snd_compr_stream *stream, char __user *buf, |
127 | size_t count); |
128 | int (*mmap)(struct snd_compr_stream *stream, |
129 | struct vm_area_struct *vma); |
130 | int (*ack)(struct snd_compr_stream *stream, size_t bytes); |
131 | int (*get_caps) (struct snd_compr_stream *stream, |
132 | struct snd_compr_caps *caps); |
133 | int (*get_codec_caps) (struct snd_compr_stream *stream, |
134 | struct snd_compr_codec_caps *codec); |
135 | }; |
136 | |
137 | /** |
138 | * struct snd_compr: Compressed device |
139 | * @name: DSP device name |
140 | * @dev: associated device instance |
141 | * @ops: pointer to DSP callbacks |
142 | * @private_data: pointer to DSP pvt data |
143 | * @card: sound card pointer |
144 | * @direction: Playback or capture direction |
145 | * @lock: device lock |
146 | * @device: device id |
147 | * @use_pause_in_draining: allow pause in draining, true when set |
148 | */ |
149 | struct snd_compr { |
150 | const char *name; |
151 | struct device *dev; |
152 | struct snd_compr_ops *ops; |
153 | void *private_data; |
154 | struct snd_card *card; |
155 | unsigned int direction; |
156 | struct mutex lock; |
157 | int device; |
158 | bool use_pause_in_draining; |
159 | #ifdef CONFIG_SND_VERBOSE_PROCFS |
160 | /* private: */ |
161 | char id[64]; |
162 | struct snd_info_entry *proc_root; |
163 | struct snd_info_entry *proc_info_entry; |
164 | #endif |
165 | }; |
166 | |
167 | /* compress device register APIs */ |
168 | int snd_compress_new(struct snd_card *card, int device, |
169 | int type, const char *id, struct snd_compr *compr); |
170 | |
171 | /** |
172 | * snd_compr_use_pause_in_draining - Allow pause and resume in draining state |
173 | * @substream: compress substream to set |
174 | * |
175 | * Allow pause and resume in draining state. |
176 | * Only HW driver supports this transition can call this API. |
177 | */ |
178 | static inline void snd_compr_use_pause_in_draining(struct snd_compr_stream *substream) |
179 | { |
180 | substream->device->use_pause_in_draining = true; |
181 | } |
182 | |
183 | /* dsp driver callback apis |
184 | * For playback: driver should call snd_compress_fragment_elapsed() to let the |
185 | * framework know that a fragment has been consumed from the ring buffer |
186 | * |
187 | * For recording: we want to know when a frame is available or when |
188 | * at least one frame is available so snd_compress_frame_elapsed() |
189 | * callback should be called when a encodeded frame is available |
190 | */ |
191 | static inline void snd_compr_fragment_elapsed(struct snd_compr_stream *stream) |
192 | { |
193 | wake_up(&stream->runtime->sleep); |
194 | } |
195 | |
196 | static inline void snd_compr_drain_notify(struct snd_compr_stream *stream) |
197 | { |
198 | if (snd_BUG_ON(!stream)) |
199 | return; |
200 | |
201 | /* for partial_drain case we are back to running state on success */ |
202 | if (stream->partial_drain) { |
203 | stream->runtime->state = SNDRV_PCM_STATE_RUNNING; |
204 | stream->partial_drain = false; /* clear this flag as well */ |
205 | } else { |
206 | stream->runtime->state = SNDRV_PCM_STATE_SETUP; |
207 | } |
208 | |
209 | wake_up(&stream->runtime->sleep); |
210 | } |
211 | |
212 | /** |
213 | * snd_compr_set_runtime_buffer - Set the Compress runtime buffer |
214 | * @stream: compress stream to set |
215 | * @bufp: the buffer information, NULL to clear |
216 | * |
217 | * Copy the buffer information to runtime buffer when @bufp is non-NULL. |
218 | * Otherwise it clears the current buffer information. |
219 | */ |
220 | static inline void |
221 | snd_compr_set_runtime_buffer(struct snd_compr_stream *stream, |
222 | struct snd_dma_buffer *bufp) |
223 | { |
224 | struct snd_compr_runtime *runtime = stream->runtime; |
225 | |
226 | if (bufp) { |
227 | runtime->dma_buffer_p = bufp; |
228 | runtime->dma_area = bufp->area; |
229 | runtime->dma_addr = bufp->addr; |
230 | runtime->dma_bytes = bufp->bytes; |
231 | } else { |
232 | runtime->dma_buffer_p = NULL; |
233 | runtime->dma_area = NULL; |
234 | runtime->dma_addr = 0; |
235 | runtime->dma_bytes = 0; |
236 | } |
237 | } |
238 | |
239 | int snd_compr_malloc_pages(struct snd_compr_stream *stream, size_t size); |
240 | int snd_compr_free_pages(struct snd_compr_stream *stream); |
241 | |
242 | int snd_compr_stop_error(struct snd_compr_stream *stream, |
243 | snd_pcm_state_t state); |
244 | |
245 | #endif |
246 | |