Configuration Files

The configuration files are intended to provide distribution and user settable configuration options. Among these are the device definitions and the settings for the various subcomponents of FFADO. This page describes the configuration file format and what entries can be used.

File Locations

FFADO reads configuration files from two locations:

  • $HOME/.ffado/configuration -- for user configuration
  • $PREFIX/share/libffado/configuration -- for distro configuration

The entries in the user configuration file always take precedence over those in the distro file.

File Format

The following rules apply:

  • all entries require a semicolon to terminate them
  • entries are of the form key = value;
  • a colon can be used instead of an equal sign. E.g.: key : value; is equivalent to key = value; .
  • lists are of the form list = ( entry1 = value; entry2 = value; );
  • entries can be grouped into a 'struct' as follows: { entry1 = value; entry2 = value; }

Device support entries

With device support entries a specific driver can be defined for each device. Device are discriminated based upon their Vendor and/or ModelId. The base level of the config file contains a list named device_definitions that contains groups of device entries formatted as follows:

  {
    vendorid = 0xAAC;
    modelid = 0x3;
    vendorname = "TerraTec Electronic GmbH";
    modelname = "Phase 88 FW";
    driver = 1;
  }

The vendorid and modelid are the same as those in the config rom of the device. The vendorname and modelname are textual descriptions that can be chosen freely.

The driver field indicates the driver that should be used for a device matching this entry. Since r2345 driver names may be used. Currently the following driver types are defined:

 0               = Unknown
 1/"BEBOB"       = BridgeCo BeBoB platform driver (+ vendor-specific extensions if available)
 2/"FIREWORKS"   = ECHO Audio Fireworks platform driver
 3/"GENERICAVC"  = Generic AV/C driver (will one day be Apple platform driver compatible)
 4/"OXFORD"      = Oxford Semiconductor AV/C driver (placeholder, not present)
 5/"MAUDIO"      = M-Audio non-BeBoB driver  (placeholder, not present)
 10/"MOTU"       = MOTU reverse engineered driver
 20/"DICE"       = TCAT DICE platform driver
 30/"METRICHALO" = Metric Halo driver (placeholder, not present)
 40/"RME"        = RME Fireface driver
 50/"BOUNCE"     = Bounce driver (placeholder, not present)
 60/"DIGIDESIGN" = Didesign driver (placeholder, not present)

Example device_definitions entry:

device_definitions = ( 
  {
    vendorid = 0xAAC;
    modelid = 0x3;
    vendorname = "TerraTec Electronic GmbH";
    modelname = "Phase 88 FW";
    driver = "BEBOB"; # or 1
  }, 
  {
    vendorid = 0x130E;
    modelid = 0x3;
    vendorname = "Focusrite";
    modelname = "Saffire Pro26IO";
    driver = 1; # or "BEBOB"
  }, 
  {
    vendorid = 0x1486;
    modelid = 0xAF2;
    vendorname = "Echo";
    modelname = "AudioFire2";
    driver = "FIREWORKS";  # or 2
  }
);

Note that the last entry does not end with a comma.

Host controller and ISO settings

This section controls the behaviour of the host controllers. It can be used to tweak libffado to the users setup. Note that the code contains sensible defaults that are used for entries not present in the config file. None of these entries are required to be present.

The config file top level should contain a group named ieee1394 . E.g.:

ieee1394 = {
   config_entry = config_value;
   ...
};

Possible config_entry's are:

  • min_split_timeout_usecs: (int) the minimum SPLIT_TIMEOUT to use. Increase this if you experience discovery issues with BridgeCo? based devices.
  • isomanager group: contains the settings for the ISO traffic manager component
    • iso_receive_mode: (int) the mode to use for ISO receive DMA. 0 = auto, 1 = packet-per-buffer, 2 = bufferfill. 'auto' will automatically choose the mode that is expected to perform best for the given situation. For large periods this is 'bufferfill' mode, for small periods this is 'packet-per-buffer' mode. The 'bufferfill_mode_threshold' defines what a 'large period' is.
    • bufferfill_mode_threshold: (int) the number of packets required to fill one period from which the bufferfill mode is to be used in auto receive mode.
    • prio_increase: (int) thread priority increase base level (can be negative)
    • prio_increase_xmit: (int) additional thread priority increase for transmit (can be negative)
    • prio_increase_recv: (int) additional thread priority increase for receive (can be negative)
    • min_interrupts_per_period: (int) number of interrupts that should be generated by the hardware within one audio period
    • max_nb_buffers_xmit: (int) maximum number of ISO transmit buffers to allocate in the kernel
    • max_packetsize_xmit: (int) maximum size of transmitted packets (can be limited by the hardware)
    • min_packetsize_xmit: (int) minimum value that can be used for the max_packetsize kernel parameter.
    • max_nb_buffers_recv: (int) maximum number of ISO receive buffers to allocate in the kernel
    • min_packetsize_recv: (int) minimum value that can be used for the max_packetsize kernel parameter.
    • isotask_activity_timeout_usecs: (int64) usecs for an ISO task activity wait to time-out.

Streaming subsystem settings

The config file top level should contain a group named streaming . E.g.:

streaming = {
   config_entry = config_value;
   ...
};

Possible config_entry's are:

  • spm group: settings for the StreamProcessorManager?
    • syncstart_tries: (int) number of retries to do when trying to synchronize the streams
    • sync_wait_time_msec: (int) number of milliseconds to wait for sync on each try
    • align_tries: (int) number of retries to do when trying to align the streams
    • align_average_time_msec: (int) number of milliseconds to average over when determining the phase of streams to align
    • signal_delay_ticks: (int) the additional time (in ticks) to wait to signal a period after it (is supposed to be) received
    • cycles_for_startup: (int) startup delay (in cycles) for the SP's
    • prestart_cycles_for_xmit: additional startup delay (in cycles) for the transmit SP's
    • prestart_cycles_for_recv: additional startup delay (in cycles) for the receive SP's

Example File

ieee1394 : 
{
  min_split_timeout_usecs = 1000000;
  isomanager :
  {
    iso_receive_mode = 0;
  };
};

device_definitions = ( 
  {
    vendorid = 0xAAC;
    modelid = 0x3;
    vendorname = "TerraTec Electronic GmbH";
    modelname = "Phase 88 FW";
    driver = "BEBOB";
  }, 
  {
    vendorid = 0x130E;
    modelid = 0x3;
    vendorname = "Focusrite";
    modelname = "Saffire Pro26IO";
    driver = "BEBOB";
  }, 
  {
    vendorid = 0x1486;
    modelid = 0xAF2;
    vendorname = "Echo";
    modelname = "AudioFire2";
    driver = "FIREWORKS";
  }
);