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