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