Home | History | Annotate | Download | only in server 
      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 
     76 /* An external module interface working with existing dsp pipeline.
     77  * __________  ___________        ____________      __________
     78  * |        |  |         |        |          |      |        |
     79  * |        |->| dsp mod |-> ...->| dsp mod  | ---> |        |
     80  * | device |  |_________|        |__________|      | stream |
     81  * |        |                      | ___________    |        |
     82  * |        |                      | | ext     |    |        |
     83  * |        |                      ->| dsp mod | -> |        |
     84  * |________|                        |_________|    |________|
     85  *
     86  * According to above diagram, an ext_dsp_module works by appending to
     87  * the sink of existing dsp pipeline. For audio input, this creates a
     88  * multiple output pipeline that stream can read processed buffer from.
     89  * This is useful for a stream to apply special processing effects while
     90  * sharing the common dsp with the other streams.
     91  *
     92  * Members:
     93  *    ports - A list of ports can connect to existing dsp ports in a pipeline.
     94  *    run - Processes |nframes| of data.
     95  *    configure - Configures given external dsp module by the device buffer
     96  *        size, rate, and number of channels of the format of the device that
     97  *        the associated pipeline runs for.
     98  */
     99 struct ext_dsp_module {
    100 	float *ports[MAX_EXT_DSP_PORTS];
    101 	void (*run)(struct ext_dsp_module *ext,
    102 		    unsigned int nframes);
    103 	void (*configure)(struct ext_dsp_module *ext,
    104 			  unsigned int buffer_size,
    105 			  unsigned int num_channels,
    106 			  unsigned int rate);
    107 };
    108 
    109 
    110 enum {
    111 	MODULE_INPLACE_BROKEN = 1  /* See ladspa.h for explanation */
    112 };
    113 
    114 /* Connects an external dsp module to a builtin sink module. */
    115 void cras_dsp_module_set_sink_ext_module(struct dsp_module *module,
    116 					 struct ext_dsp_module *ext_module);
    117 
    118 struct dsp_module *cras_dsp_module_load_ladspa(struct plugin *plugin);
    119 struct dsp_module *cras_dsp_module_load_builtin(struct plugin *plugin);
    120 
    121 #ifdef __cplusplus
    122 } /* extern "C" */
    123 #endif
    124 
    125 #endif /* CRAS_DSP_MODULE_H_ */
    126