The resource manager parses its main configuration file during the start-up procedure. Where this refers to firmware configuration files, it parses them and downloads firmware as specified before the server process is started. If any applications are started during this time and call a Prosody API function, they will be blocked until the resource manager has finished its initialisation.
The configuration files have a simple format. They consist of a sequence of tagged items. Each item is in the format:
optional-space '<' tagname '>' data '\n'
where tagname is a tag, and data is
arbitrary data which may contain newlines but not '<' symbols.
Tag names are case sensitive (they currently use only capital
letters), and no space is permitted before or after the tag name. The
significance of spaces in the data depends on the interpretation of
the data, which can vary from one tag to another. Here is an example
with two items:
<ELFFILE> hello world <CHANNELLIMIT> 23
If data for the ELFFILE tag is written as a C string, it
would be " hello\nworld". i.e. it starts with a space and has a
newline character in the value. When we later look at the meaning of this
tag, we will see that it splits its data into a list of names, one
per line, and strips leading and trailing spaces from the names, so
it will see two names: "hello" and "world". You can assume that
leading and trailing spaces are ignored unless the description of a
tag says otherwise. Similarly, you can assume that blank lines are
ignored.
A line starting with # (possibly after some blank space)
is considered a comment and is ignored.
The order of tags in a file is significant.
These files are typically named *.sfw. Since they are
intended to emulate Prosody 1 firmware builds, and a suitable file is
provided for each of the builds (for example, sp30a.sfw
emulates the old sp30a.smf), you don't normally need to
understand this file format - just the format of the
main configuration file. However the format is
documented here for completeness. These files contain these
items in any order:
<ELFFILE>
<CHANNELLIMIT>
<COMPANDING>
<FMWTYPE>
<RESLIST>
The firmware file must include all of these tags and have data for each one. These provide a complete description of the firmware as needed to control the downloading, configuration, and resource allocation limits.
The data for this tag is a list of the names of firmware modules to be
downloaded. Each name is the name of one firmware module which is
normally to be found in a file which is in the firmware directory and
named X.elf where X is the name of the module.
A very basic firmware for playback of A-law might contain the following:
<ELFLIST> outchan playA gainbg
This specifies an absolute limit on the number of channels available with this firmware, regardless of caps_mask values. The restriction imposed by capabilities masks may be smaller than that imposed by the channel limit but never larger. The channel limit is imposed at the firmware level because this is the only time at which the exact module load-out is known. The data for this tag is a decimal integer.
Currently the maximum value for CHANNELLIMIT is 128. This is a count of available simplex channels. It should be noted that half and full duplex channels will each consume two of these resources.
This tag appears in the firmware configuration file to indicate whether
the underlying network will be A-law or mu-law. Allowable values
are: ALAW, MULAW and DATA. The
DATA value may be deprecated in the resource manager.
This refers to the Prosody 1 build type of the firmware file and is used
by the resource manager when interpreting the resource list (see below).
The value can be SP30, SP60,
ESP30 or ECR24. These values are case
sensitive. NOTE: To emulate the sp64a.smf and
sp64u.smf builds, specify SP60.
This lists the set of resources available to each firmware build. These
resources are significant to the resource manager as specified and
changing these values may cause unexpected behaviour within the resource
manager. Their significance depends on the <FMWTYPE>
selected. The data for this tag is a list of integers separated by
spaces. The correct values for each firmware type are shown below,
along with the amount of each resource used when a channel is
allocated with each caps_mask capability.
| SP30 | 30 | 30 |
|---|---|---|
| Write | 0 | 1 |
| Read | 0 | 0 |
| Recog | 1 | 0 |
| SP60 | 60 | 60 |
|---|---|---|
| Write | 1 | 0 |
| Read | 1 | 0 |
| Recog | 0 | 1 |
| ESP30 | 26 | 30 | 32 | 30 | 32 |
|---|---|---|---|---|---|
| Write | 0 | 1 | 0 | 0 | 0 |
| Read | 0 | 0 | 0 | 0 | 0 |
| Recog | 1 | 0 | 0 | 0 | 0 |
| HalfLoad | 0 | 0 | 1 | 0 | 0 |
| StandAlone | 0 | 0 | 0 | 1 | 0 |
| CondRefInput | 0 | 0 | 0 | 0 | 1 |
| ECR24 | 24 | 32 | 32 | 32 |
|---|---|---|---|---|
| Write | 0 | 1 | 0 | 0 |
| Read | 0 | 0 | 0 | 0 |
| Recog | 1 | 0 | 0 | 0 |
| StandAlone | 1 | 0 | 0 | 0 |
| RecAltDataSource | 0 | 0 | 0 | 1 |
| CondRefInput | 0 | 0 | 1 | 0 |
Note that, although 'read' capability is listed as using zero resources on several firmware types, this does not mean that you can have as many such channels as you like! As described in Prosody application note: the version 1 compatibility builds, 'read' capability always adds an implicit 'recog' capability as well, so the apparent need for zero resources merely means that 'read' requires no extra resource beyond that needed for 'recog'.
This file details the initial state of the system including the number
of Prosody processors for which the resource manager is responsible.
A specimen is provided (sp30x2.cfg) in the
ResourceManager directory showing a configuration of two
DSPs each emulating sp30a.smf. It may contain the following
items:
The items do not necessarily need to be in that order - see the individual item desriptions for ordering requirements. An empty file is invalid.
This must be the first tag in a file and must be set to a positive
value. It is the number of DSPs which are to be controlled by the
resource manager. If more are present in the system, the resource
manager will not use them, so they are available for use by
applications which don't use the resource manager. This number must
match the number of DSPs for which configuration is provided.
Note, however, that you do not have to use DSPs in order: if a system
has four DSPs you can specify <NUMDSP> is two and use DSPs
1 and 3 or any other pair.
The data for this item must be set to reflect the name of the base install directory of the TiNG package. The resource manager assumes that the TiNG directory structure is left intact (e.g. so that it can find the firmware and download programs for the purposes of kernel and firmware download). This item must appear exactly once in the configuration file.
This tag specifies the DSP that subsequent tags refer to. Its data is a decimal integer which is the DSP number. It may occur as often as you like, each occurrence only affecting items until the next occurrence. It is an error for this value to be greater than or equal to the value specified by <NUMDSPS>.
The data for this optional tag must name the firmware configuration
file to be used for the DSP currently selected by the most recent
<DSPINDEX> tag. The resource manager will attempt to open the
firmware file and interpret it according to the format described above.
A DSP can have at most one <FIRMWAREFILE> specified. If none is
specified, the firmware must be downloaded by an application using
sm_download_fmw(), which
can also be done for any DSP controlled by the resource manager whilst
an application is executing as long as no channels are allocated on the
DSP in question (this includes DSPs whose firmware was initially
downloaded from the configuration file). A suitable configuration file
is provided to emulate each of the Prosody 1 *.smf
files. These are in the ResourceManager directory. For
example, sp60u.sfw emulates sp60u.smf.
This optional tag specifies the firmware ID to be used for the DSP currently selected by the most recent <DSPINDEX> tag. It may be used only once per DSP. If omitted, the value zero will be used for the firmware ID.