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 /* Gets the dsp ini that corresponds to the pipeline. */ 123 struct ini *cras_dsp_pipeline_get_ini(struct pipeline *pipeline); 124 125 /* Processes a block of audio samples. sample_count should be no more 126 * than DSP_BUFFER_SIZE */ 127 void cras_dsp_pipeline_run(struct pipeline *pipeline, int sample_count); 128 129 /* Add a statistic of running time for the pipeline. 130 * 131 * Args: 132 * time_delta - The time it takes to run the pipeline and any other 133 * preprocessing and postprocessing. 134 * samples - The number of audio sample frames processed. 135 */ 136 void cras_dsp_pipeline_add_statistic(struct pipeline *pipeline, 137 const struct timespec *time_delta, 138 int samples); 139 140 /* Runs the specified pipeline across the given interleaved buffer in place. 141 * Args: 142 * pipeline - The pipeline to run. 143 * buf - The samples to be processed, interleaved. 144 * format - Sample format of the buffer. 145 * frames - the numver of samples in the buffer. 146 * Returns: 147 * Negative code if error, otherwise 0. 148 */ 149 int cras_dsp_pipeline_apply(struct pipeline *pipeline, uint8_t *buf, 150 snd_pcm_format_t format, unsigned int frames); 151 152 /* Dumps the current state of the pipeline. For debugging only */ 153 void cras_dsp_pipeline_dump(struct dumper *d, struct pipeline *pipeline); 154 155 #ifdef __cplusplus 156 } /* extern "C" */ 157 #endif 158 159 #endif /* CRAS_DSP_PIPELINE_H_ */ 160