1 /* Copyright (c) 2012 The Chromium OS Authors. All rights reserved.
2  * Use of this source code is governed by a BSD-style license that can be
3  * found in the LICENSE file.
4  */
5 
6 #ifndef CRAS_DSP_PIPELINE_H_
7 #define CRAS_DSP_PIPELINE_H_
8 
9 #ifdef __cplusplus
10 extern "C" {
11 #endif
12 
13 #include <stdint.h>
14 
15 #include "dumper.h"
16 #include "cras_dsp_ini.h"
17 
18 /* These are the functions to create and use dsp pipelines. A dsp
19  * pipeline is a collection of dsp plugins that process audio
20  * data. The plugins and their connections are specified in an ini
21  * file. Before using the pipeline, we need to instantiate the
22  * pipeline by giving an audio sampling rate. Then we get the pointers
23  * to the input buffers, fill the input data, run the pipeline, and
24  * obtain the processed data from the output buffers.
25  */
26 
27 /* The maximum number of samples that cras_dsp_pipeline_run() can
28  * accept. Beyond this the user should break the samples into several
29  * blocks and call cras_dsp_pipeline_run() several times.
30  */
31 #define DSP_BUFFER_SIZE 2048
32 
33 struct pipeline;
34 
35 /* Creates a pipeline from the given ini file.
36  * Args:
37  *    ini - The ini file the pipeline is created from.
38  *    env - The expression environment for evaluating disable expression.
39  *    purpose - The purpose of the pipeline, "playback" or "capture".
40  * Returns:
41  *    A pointer to the pipeline, or NULL if the creation fails.
42  */
43 struct pipeline *cras_dsp_pipeline_create(struct ini* ini,
44 					  struct cras_expr_env *env,
45 					  const char *purpose);
46 
47 /* Frees the resources used by the pipeline. */
48 void cras_dsp_pipeline_free(struct pipeline *pipeline);
49 
50 /* Loads the implementation of the plugins in the pipeline (from
51  * shared libraries). Must be called before
52  * cras_dsp_pipeline_instantiate().
53  * Returns:
54  *    0 if successful. -1 otherwise.
55  */
56 int cras_dsp_pipeline_load(struct pipeline *pipeline);
57 
58 /* Instantiates the pipeline given the sampling rate.
59  * Args:
60  *    sample_rate - The audio sampling rate.
61  * Returns:
62  *    0 if successful. -1 otherwise.
63  */
64 int cras_dsp_pipeline_instantiate(struct pipeline *pipeline, int sample_rate);
65 
66 /* The counterpart of cras_dsp_pipeline_instantiate(). To change the
67  * sampling rate, this must be called before another call to
68  * cras_dsp_pipeline_instantiate(). */
69 void cras_dsp_pipeline_deinstantiate(struct pipeline *pipeline);
70 
71 /* Returns the buffering delay of the pipeline. This should only be called
72  * after a pipeline has been instantiated.
73  * Returns:
74  *    The buffering delay in frames.
75  */
76 int cras_dsp_pipeline_get_delay(struct pipeline *pipeline);
77 
78 /* Returns the number of input/output audio channels this pipeline expects */
79 int cras_dsp_pipeline_get_num_input_channels(struct pipeline *pipeline);
80 int cras_dsp_pipeline_get_num_output_channels(struct pipeline *pipeline);
81 
82 /* Returns the pointer to the input buffer for a channel of this
83  * pipeline. The size of the buffer is DSP_BUFFER_SIZE samples, and
84  * the number of samples acually used should be passed to
85  * cras_dsp_pipeline_run().
86  *
87  * Args:
88  *    index - The channel index. The valid value is 0 to
89  *            cras_dsp_pipeline_get_num_channels() - 1.
90  */
91 float *cras_dsp_pipeline_get_source_buffer(struct pipeline *pipeline,
92 					   int index);
93 
94 /* Returns the pointer to the output buffer for a channel of this
95  * pipeline. The size of the buffer is DSP_BUFFER_SIZE samples.
96  *
97  * Args:
98  *    index - The channel index. The valid value is 0 to
99  *            cras_dsp_pipeline_get_num_channels() - 1.
100  */
101 float *cras_dsp_pipeline_get_sink_buffer(struct pipeline *pipeline, int index);
102 
103 /* Returns the number of internal audio buffers allocated by the
104  * pipeline. This is used by the unit test only */
105 int cras_dsp_pipeline_get_peak_audio_buffers(struct pipeline *pipeline);
106 
107 /* Returns the sampling rate passed by cras_dsp_pipeline_instantiate(),
108  * or 0 if is has not been called */
109 int cras_dsp_pipeline_get_sample_rate(struct pipeline *pipeline);
110 
111 /* Processes a block of audio samples. sample_count should be no more
112  * than DSP_BUFFER_SIZE */
113 void cras_dsp_pipeline_run(struct pipeline *pipeline, int sample_count);
114 
115 /* Add a statistic of running time for the pipeline.
116  *
117  * Args:
118  *    time_delta - The time it takes to run the pipeline and any other
119  *                 preprocessing and postprocessing.
120  *    samples - The number of audio sample frames processed.
121  */
122 void cras_dsp_pipeline_add_statistic(struct pipeline *pipeline,
123 				     const struct timespec *time_delta,
124 				     int samples);
125 
126 /* Runs the specified pipeline across the given interleaved buffer in place.
127  * Args:
128  *    pipeline - The pipeline to run.
129  *    buf - The samples to be processed, interleaved.
130  *    frames - the numver of samples in the buffer.
131  */
132 void cras_dsp_pipeline_apply(struct pipeline *pipeline,
133 			     uint8_t *buf, unsigned int frames);
134 
135 /* Dumps the current state of the pipeline. For debugging only */
136 void cras_dsp_pipeline_dump(struct dumper *d, struct pipeline *pipeline);
137 
138 #ifdef __cplusplus
139 } /* extern "C" */
140 #endif
141 
142 #endif /* CRAS_DSP_PIPELINE_H_ */
143