Skip to content

Commit eee6a25

Browse files
Marcin Makatlauda
Marcin Maka
authored and
tlauda
committed
audio-stream: dox: add full api documentation
Audio stream is an important piece used by components therefore full documentation is required by component developers to operate on source and sink buffers attached ot their components. Signed-off-by: Marcin Maka <marcin.maka@linux.intel.com>
1 parent 73934f3 commit eee6a25

2 files changed

Lines changed: 205 additions & 20 deletions

File tree

‎doc/sof.doxygen.in‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,9 @@ INHERIT_DOCS = YES
2626
ENABLED_SECTIONS = ""
2727
MACRO_EXPANSION = YES
2828
EXPAND_ONLY_PREDEF = YES
29-
PREDEFINED = __attribute__(x)=
29+
PREDEFINED = "__attribute__(x)= " \
30+
"CONFIG_FORMAT_S16LE=1" \
31+
"CONFIG_FORMAT_S32LE=1"
3032

3133
OPTIMIZE_OUTPUT_FOR_C = YES
3234
TYPEDEF_HIDES_STRUCT = YES

‎src/include/sof/audio/audio_stream.h‎

Lines changed: 202 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,10 @@
66
*/
77

88
/**
9-
* audio_stream is kind of circular buffer with information about data format
10-
* and buffer size. Audio processing functions should work on this component.
11-
* This component is not responsible for memory menagement for himself,
12-
* it is a role of highly coupled comp_buffer or dma component as usual.
13-
*/
9+
* \file include/sof/audio/audio_stream.h
10+
* \brief Audio Stream API definition
11+
* \author Karol Trzcinski <karolx.trzcinski@linux.intel.com>
12+
*/
1413

1514
#ifndef __SOF_AUDIO_AUDIO_STREAM_H__
1615
#define __SOF_AUDIO_AUDIO_STREAM_H__
@@ -24,44 +23,139 @@
2423
#include <config.h>
2524
#include <stdint.h>
2625

27-
/* audio circular stream */
26+
/** \addtogroup audio_stream_api Audio Stream API
27+
* @{
28+
*/
29+
30+
/**
31+
* Audio stream is kind of circular buffer with information about data format
32+
* and buffer size.
33+
*
34+
* Audio processing functions should work on this object.
35+
* This object is not responsible for memory management for himself,
36+
* it is a role of highly coupled comp_buffer or dma client code.
37+
*/
2838
struct audio_stream {
2939
/* runtime data */
30-
uint32_t size; /* runtime buffer size in bytes (period multiple) */
31-
uint32_t avail; /* available bytes for reading */
32-
uint32_t free; /* free bytes for writing */
33-
void *w_ptr; /* buffer write pointer */
34-
void *r_ptr; /* buffer read position */
35-
void *addr; /* buffer base address */
36-
void *end_addr; /* buffer end address */
40+
uint32_t size; /**< Runtime buffer size in bytes (period multiple) */
41+
uint32_t avail; /**< Available bytes for reading */
42+
uint32_t free; /**< Free bytes for writing */
43+
void *w_ptr; /**< Buffer write pointer */
44+
void *r_ptr; /**< Buffer read position */
45+
void *addr; /**< Buffer base address */
46+
void *end_addr; /**< Buffer end address */
3747

3848
/* runtime stream params */
39-
enum sof_ipc_frame frame_fmt; /**< sample data format */
40-
uint32_t rate; /**< number of data frames per second [Hz] */
41-
uint16_t channels; /**< number of samples in each frame */
49+
enum sof_ipc_frame frame_fmt; /**< Sample data format */
50+
uint32_t rate; /**< Number of data frames per second [Hz] */
51+
uint16_t channels; /**< Number of samples in each frame */
4252
};
4353

54+
/**
55+
* Retrieves readable address of a sample at specified index (see versions of
56+
* this macro specialized for various sample types).
57+
* @param buffer Buffer.
58+
* @param idx Index of sample.
59+
* @param size Size of sample in bytes.
60+
* @return Pointer to the sample.
61+
*
62+
* Once the consumer finishes reading samples from the buffer, it should
63+
* "commit" the operation and update the buffer state by calling
64+
* audio_stream_consume().
65+
*
66+
* @note Components should call comp_update_buffer_consume().
67+
*
68+
* @see audio_stream_get_frag().
69+
* @see audio_stream_consume().
70+
* @see comp_update_buffer_consume().
71+
*/
4472
#define audio_stream_read_frag(buffer, idx, size) \
4573
audio_stream_get_frag(buffer, buffer->r_ptr, idx, size)
4674

75+
/**
76+
* Retrieves readable address of a signed 16-bit sample at specified index.
77+
* @param buffer Buffer.
78+
* @param idx Index of sample.
79+
* @return Pointer to the sample.
80+
*
81+
* @see audio_stream_get_frag().
82+
*/
4783
#define audio_stream_read_frag_s16(buffer, idx) \
4884
audio_stream_get_frag(buffer, buffer->r_ptr, idx, sizeof(int16_t))
4985

86+
/**
87+
* Retrieves readable address of a signed 32-bit sample at specified index.
88+
* @param buffer Buffer.
89+
* @param idx Index of sample.
90+
* @return Pointer to the sample.
91+
*
92+
* @see audio_stream_get_frag().
93+
*/
5094
#define audio_stream_read_frag_s32(buffer, idx) \
5195
audio_stream_get_frag(buffer, buffer->r_ptr, idx, sizeof(int32_t))
5296

97+
/**
98+
* Retrieves writeable address of a sample at specified index (see versions of
99+
* this macro specialized for various sample types).
100+
* @param buffer Buffer.
101+
* @param idx Index of sample.
102+
* @param size Size of sample in bytes.
103+
* @return Pointer to the space for sample.
104+
*
105+
* Once the producer finishes writing samples to the buffer, it should
106+
* "commit" the operation and update the buffer state by calling
107+
* audio_stream_produce().
108+
*
109+
* @note Components should call comp_update_buffer_produce().
110+
*
111+
* @see audio_stream_get_frag().
112+
* @see audio_stream_produce().
113+
* @see comp_update_buffer_produce().
114+
*/
53115
#define audio_stream_write_frag(buffer, idx, size) \
54116
audio_stream_get_frag(buffer, buffer->w_ptr, idx, size)
55117

118+
/**
119+
* Retrieves writeable address of a signed 16-bit sample at specified index.
120+
* @param buffer Buffer.
121+
* @param idx Index of sample.
122+
* @return Pointer to the space for sample.
123+
*
124+
* @see audio_stream_get_frag().
125+
*/
56126
#define audio_stream_write_frag_s16(buffer, idx) \
57127
audio_stream_get_frag(buffer, buffer->w_ptr, idx, sizeof(int16_t))
58128

129+
/**
130+
* Retrieves writeable address of a signed 32-bit sample at specified index.
131+
* @param buffer Buffer.
132+
* @param idx Index of sample.
133+
* @return Pointer to the space for sample.
134+
*
135+
* @see audio_stream_get_frag().
136+
*/
59137
#define audio_stream_write_frag_s32(buffer, idx) \
60138
audio_stream_get_frag(buffer, buffer->w_ptr, idx, sizeof(int32_t))
61139

140+
/**
141+
* Retrieves address of sample (space for sample) at specified index within
142+
* the buffer. Index is interpreted as an offset relative to the specified
143+
* pointer, rollover is ensured.
144+
* @param buffer Circular buffer.
145+
* @param ptr Pointer to start from, it may be either read or write pointer.
146+
* @param idx Index of the sample.
147+
* @param sample_size Size of the sample in bytes.
148+
* @return Pointer to the sample.
149+
*/
62150
#define audio_stream_get_frag(buffer, ptr, idx, sample_size) \
63151
audio_stream_wrap(buffer, (char *)(ptr) + ((idx) * (sample_size)))
64152

153+
/**
154+
* Applies parameters to the buffer.
155+
* @param buffer Buffer.
156+
* @param params Parameters (frame format, rate, number of channels).
157+
* @return 0 if succeeded, error code otherwise.
158+
*/
65159
static inline int audio_stream_set_params(struct audio_stream *buffer,
66160
struct sof_ipc_stream_params *params)
67161
{
@@ -75,6 +169,13 @@ static inline int audio_stream_set_params(struct audio_stream *buffer,
75169
return 0;
76170
}
77171

172+
/**
173+
* Verifies the pointer and performs rollover when reached the end of
174+
* the buffer.
175+
* @param buffer Buffer accessed by the pointer.
176+
* @param ptr Pointer
177+
* @return Pointer, adjusted if necessary.
178+
*/
78179
static inline void *audio_stream_wrap(const struct audio_stream *buffer,
79180
void *ptr)
80181
{
@@ -85,7 +186,16 @@ static inline void *audio_stream_wrap(const struct audio_stream *buffer,
85186
return ptr;
86187
}
87188

88-
/* get the max number of bytes that can be copied between sink and source */
189+
/**
190+
* Verifies whether specified number of bytes can be copied from source buffer
191+
* to sink buffer.
192+
* @param source Source buffer.
193+
* @param sink Sink buffer.
194+
* @param bytes Number of bytes to copy.
195+
* @return 0 if there is enough data in source and enough free space in sink.
196+
* @return 1 if there is not enough free space in sink.
197+
* @return -1 if there is not enough data in source.
198+
*/
89199
static inline int audio_stream_can_copy_bytes(const struct audio_stream *source,
90200
const struct audio_stream *sink,
91201
uint32_t bytes)
@@ -102,6 +212,14 @@ static inline int audio_stream_can_copy_bytes(const struct audio_stream *source,
102212
return 0;
103213
}
104214

215+
/**
216+
* Computes maximum number of bytes that can be copied from source buffer to
217+
* sink buffer, verifying number of bytes available in source vs. free space
218+
* available in sink.
219+
* @param source Source buffer.
220+
* @param sink Sink buffer.
221+
* @return Number of bytes.
222+
*/
105223
static inline uint32_t
106224
audio_stream_get_copy_bytes(const struct audio_stream *source,
107225
const struct audio_stream *sink)
@@ -144,6 +262,14 @@ static inline uint32_t audio_stream_period_bytes(const struct audio_stream *buf,
144262
return frames * audio_stream_frame_bytes(buf);
145263
}
146264

265+
/**
266+
* Computes maximum number of frames that can be copied from source buffer
267+
* to sink buffer, verifying number of available source frames vs. free
268+
* space available in sink.
269+
* @param source Source buffer.
270+
* @param sink Sink buffer.
271+
* @return Number of frames.
272+
*/
147273
static inline uint32_t
148274
audio_stream_avail_frames(const struct audio_stream *source,
149275
const struct audio_stream *sink)
@@ -154,7 +280,11 @@ audio_stream_avail_frames(const struct audio_stream *source,
154280
return MIN(src_frames, sink_frames);
155281
}
156282

157-
/* called only by a comp_buffer procedures */
283+
/**
284+
* Updates the buffer state after writing to the buffer.
285+
* @param buffer Buffer to update.
286+
* @param bytes Number of written bytes.
287+
*/
158288
static inline void audio_stream_produce(struct audio_stream *buffer,
159289
uint32_t bytes)
160290
{
@@ -178,7 +308,11 @@ static inline void audio_stream_produce(struct audio_stream *buffer,
178308
buffer->free = buffer->size - buffer->avail;
179309
}
180310

181-
/* called only by a comp_buffer procedures */
311+
/**
312+
* Updates the buffer state after reading from the buffer.
313+
* @param buffer Buffer to update.
314+
* @param bytes Number of read bytes.
315+
*/
182316
static inline void audio_stream_consume(struct audio_stream *buffer,
183317
uint32_t bytes)
184318
{
@@ -198,6 +332,10 @@ static inline void audio_stream_consume(struct audio_stream *buffer,
198332
buffer->free = buffer->size - buffer->avail;
199333
}
200334

335+
/**
336+
* Resets the buffer.
337+
* @param buffer Buffer to reset.
338+
*/
201339
static inline void audio_stream_reset(struct audio_stream *buffer)
202340
{
203341
/* reset read and write pointer to buffer bas */
@@ -211,6 +349,12 @@ static inline void audio_stream_reset(struct audio_stream *buffer)
211349
buffer->avail = 0;
212350
}
213351

352+
/**
353+
* Initializes the buffer with specified memory block and size.
354+
* @param buffer Buffer to initialize.
355+
* @param buff_addr Address of the memory block to assign.
356+
* @param size Size of the memory block in bytes.
357+
*/
214358
static inline void audio_stream_init(struct audio_stream *buffer,
215359
void *buff_addr, uint32_t size)
216360
{
@@ -220,6 +364,12 @@ static inline void audio_stream_init(struct audio_stream *buffer,
220364
audio_stream_reset(buffer);
221365
}
222366

367+
/**
368+
* Invalidates (in DSP d-cache) the buffer in range [r_ptr, r_ptr+bytes],
369+
* with rollover if necessary.
370+
* @param buffer Buffer.
371+
* @param bytes Size of the fragment to invalidate.
372+
*/
223373
static inline void audio_stream_invalidate(struct audio_stream *buffer,
224374
uint32_t bytes)
225375
{
@@ -237,6 +387,12 @@ static inline void audio_stream_invalidate(struct audio_stream *buffer,
237387
dcache_invalidate_region(buffer->addr, tail_size);
238388
}
239389

390+
/**
391+
* Writes back (from DSP d-cache) the buffer in range [w_ptr, w_ptr+bytes],
392+
* with rollover if necessary.
393+
* @param buffer Buffer.
394+
* @param bytes Size of the fragment to write back.
395+
*/
240396
static inline void audio_stream_writeback(struct audio_stream *buffer,
241397
uint32_t bytes)
242398
{
@@ -254,6 +410,15 @@ static inline void audio_stream_writeback(struct audio_stream *buffer,
254410
dcache_writeback_region(buffer->addr, tail_size);
255411
}
256412

413+
/**
414+
* Copies data from source buffer to sink buffer.
415+
* @param source Source buffer.
416+
* @param ioffset_bytes Offset (in bytes) in source buffer to start reading
417+
* from.
418+
* @param sink Sink buffer.
419+
* @param ooffset_bytes Offset (in bytes) in sink buffer to start writing to.
420+
* @param bytes Number of bytes to copy.
421+
*/
257422
static inline void audio_stream_copy(const struct audio_stream *source,
258423
uint32_t ioffset_bytes,
259424
struct audio_stream *sink,
@@ -287,6 +452,14 @@ static inline void audio_stream_copy(const struct audio_stream *source,
287452

288453
#if CONFIG_FORMAT_S16LE
289454

455+
/**
456+
* Copies signed 16-bit samples from source buffer to sink buffer.
457+
* @param source Source buffer.
458+
* @param ioffset Offset (in samples) in source buffer to start reading from.
459+
* @param sink Sink buffer.
460+
* @param ooffset Offset (in samples) in sink buffer to start writing to.
461+
* @param samples Number of samples to copy.
462+
*/
290463
static inline void audio_stream_copy_s16(const struct audio_stream *source,
291464
uint32_t ioffset,
292465
struct audio_stream *sink,
@@ -302,6 +475,14 @@ static inline void audio_stream_copy_s16(const struct audio_stream *source,
302475

303476
#if CONFIG_FORMAT_S24LE || CONFIG_FORMAT_S32LE || CONFIG_FORMAT_FLOAT
304477

478+
/**
479+
* Copies signed 32-bit samples from source buffer to sink buffer.
480+
* @param source Source buffer.
481+
* @param ioffset Offset (in samples) in source buffer to start reading from.
482+
* @param sink Sink buffer.
483+
* @param ooffset Offset (in samples) in sink buffer to start writing to.
484+
* @param samples Number of samples to copy.
485+
*/
305486
static inline void audio_stream_copy_s32(const struct audio_stream *source,
306487
uint32_t ioffset,
307488
struct audio_stream *sink,
@@ -315,4 +496,6 @@ static inline void audio_stream_copy_s32(const struct audio_stream *source,
315496

316497
#endif /* CONFIG_FORMAT_S24LE || CONFIG_FORMAT_S32LE || CONFIG_FORMAT_FLOAT */
317498

499+
/** @}*/
500+
318501
#endif /* __SOF_AUDIO_AUDIO_STREAM_H__ */

0 commit comments

Comments
 (0)