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_MODULE_H_ 7 #define CRAS_DSP_MODULE_H_ 8 9 #ifdef __cplusplus 10 extern "C" { 11 #endif 12 13 #include "cras_dsp_ini.h" 14 15 #define MAX_EXT_DSP_PORTS 8 16 17 /* Holds the functions we can use on a dsp module. */ 18 struct dsp_module { 19 /* Opaque data used by the implementation of this module */ 20 void *data; 21 22 /* Initializes the module for a given sampling rate. To change 23 * the sampling rate, deinstantiate() must be called before 24 * calling instantiate again. 25 * Args: 26 * sample_rate - The sampling rate for the audio data, like 44100. 27 * Returns: 28 * 0 if the initialization is successful. -1 otherwise. 29 */ 30 int (*instantiate)(struct dsp_module *mod, unsigned long sample_rate); 31 32 /* Assigns the memory location for a port of this module. 33 * Args: 34 * port - The index of the port. 35 * data_location - The memory address of the data for this port. 36 */ 37 void (*connect_port)(struct dsp_module *mod, unsigned long port, 38 float *data_location); 39 40 /* Returns the buffering delay of this module. This should be called 41 * only after all input control ports have been connected. 42 * Returns: 43 * The buffering delay in frames. The value returned should only be 44 * based on the sampling rate and the input control ports values and not 45 * the audio data itself. 46 */ 47 int (*get_delay)(struct dsp_module *mod); 48 49 /* Processes a block of samples using this module. The memory 50 * location for the input and output data are assigned by the 51 * connect_port() call. 52 * Args: 53 * sample_count - The number of samples to be processed. 54 */ 55 void (*run)(struct dsp_module *mod, unsigned long sample_count); 56 57 /* Free resources used by the module. This module can be used 58 * again by calling instantiate() */ 59 void (*deinstantiate)(struct dsp_module *mod); 60 61 /* Frees all resources used by this module. After calling 62 * free_module(), this struct dsp_module cannot be used 63 * anymore. 64 */ 65 void (*free_module)(struct dsp_module *mod); 66 67 /* Returns special properties of this module, see the enum 68 * below for details */ 69 int (*get_properties)(struct dsp_module *mod); 70 71 /* Dumps the information about current state of this module */ 72 void (*dump)(struct dsp_module *mod, struct dumper *d); 73 }; 74 75 /* An external module interface working with existing dsp pipeline. 76 * __________ ___________ ____________ __________ 77 * | | | | | | | | 78 * | |->| dsp mod |-> ...->| dsp mod | ---> | | 79 * | device | |_________| |__________| | stream | 80 * | | | ___________ | | 81 * | | | | ext | | | 82 * | | ->| dsp mod | -> | | 83 * |________| |_________| |________| 84 * 85 * According to above diagram, an ext_dsp_module works by appending to 86 * the sink of existing dsp pipeline. For audio input, this creates a 87 * multiple output pipeline that stream can read processed buffer from. 88 * This is useful for a stream to apply special processing effects while 89 * sharing the common dsp with the other streams. 90 * 91 * Members: 92 * ports - A list of ports can connect to existing dsp ports in a pipeline. 93 * run - Processes |nframes| of data. 94 * configure - Configures given external dsp module by the device buffer 95 * size, rate, and number of channels of the format of the device that 96 * the associated pipeline runs for. 97 */ 98 struct ext_dsp_module { 99 float *ports[MAX_EXT_DSP_PORTS]; 100 void (*run)(struct ext_dsp_module *ext, unsigned int nframes); 101 void (*configure)(struct ext_dsp_module *ext, unsigned int buffer_size, 102 unsigned int num_channels, unsigned int rate); 103 }; 104 105 enum { MODULE_INPLACE_BROKEN = 1 }; /* See ladspa.h for explanation */ 106 107 /* Connects an external dsp module to a builtin sink module. */ 108 void cras_dsp_module_set_sink_ext_module(struct dsp_module *module, 109 struct ext_dsp_module *ext_module); 110 111 struct dsp_module *cras_dsp_module_load_ladspa(struct plugin *plugin); 112 struct dsp_module *cras_dsp_module_load_builtin(struct plugin *plugin); 113 114 #ifdef __cplusplus 115 } /* extern "C" */ 116 #endif 117 118 #endif /* CRAS_DSP_MODULE_H_ */ 119