Prosody application note: using the resource manager

Contents:

• Introduction
• Differences between version 1 and version 2 (TiNG) handled by the resource manager
• Using the resource manager

Introduction

Prosody version 1 performed various resource management functions which are not performed by version 2 (TiNG) itself. While new applications can be written to perform such resource management themselves (or, more commonly, designed such that the resource management is implicit in the design), for backward compatibility with existing applications, a resource manager is provided. Although applications written for version 1 may still require some modifications, these should be very minor.

Note that neither Prosody S nor Prosody X support the use of the resource manager.

Differences between version 1 and version 2 (TiNG) handled by the resource manager

The resource manager provides or modifies the following API functions. See following sections for full details, including any restrictions on their use.

• sm_download_fmw()
• sm_channel_alloc()
• sm_channel_alloc_placed()
• sm_conf_primix_start()
• sm_conf_primix_clone()
• sm_conf_primix_add()
• sm_conf_primix_leave()
• sm_conf_primix_info()
• sm_conf_primix_adj_input()
• sm_conf_primix_adj_output()
• sm_conf_primix_abort()

Firmware download

Prosody version 1 supplied firmware in packages called builds. Each build had a predefined combination of Prosody functionality. A firmware build was downloaded as a unit using either a standalone application or the API call sm_download_fmw().

The resource manager provides this functionality by providing both a facility to download firmware automatically and the sm_download_fmw() API function as well as a selection of predefined builds as described in Prosody application note: the version 1 compatibility builds.

Channel allocation limits

Prosody version 1 attempted to prevent resource exhaustion by limiting the number of channels which could be allocated on each Prosody processor. The caps_mask fields of sm_channel_alloc_placed(), and sm_channel_alloc() were used to allow the application to describe its intended use for each channel, so that Prosody could reserve the required resources.

The resource manager provides this functionality by implementing limits on channel allocation in the same manner as version 1. Note that, although many of the limits are the same, some are different when the application specifies an invalid combination of channels. The resource manager returns an error for many of these cases rather than allocating a channel.

When you use sm_channel_alloc_placed(), these errors may be returned:

ERR_SM_NO_RESOURCES,

The request was valid, but resource exhaustion prevents the channel being allocated. If resource usage is reduced (e.g. by releasing other channels) an identical request may succeed.

ERR_SM_BAD_PARAMETER

The request was invalid. For example, trying to allocate a standalone echo canceller on a module which already has a half-load echo canceller. Reducing resource usage will not permit an identical request to succeed, except possibly releasing all conflicting channels. Note that this error may occur because a program breaks a rule which Prosody 1 did not check.

ERR_SM_WRONG_FIRMWARE_TYPE

The request could not be attempted because it relates to capabilities not present in the downloaded firmware.

ERR_SM_NO_FIRMWARE_RUNNING

The request has failed because this module has no firmware currently running on it.

The behaviour of sm_channel_alloc() is intended to be as intuitive as possible. It follows these steps:

1. If the group field refers to an existing group, perform sm_channel_alloc_placed() on the module hosting that group.
2. Otherwise, if the group field is neither -1 nor 0, return the error ERR_SM_NO_SUCH_GROUP.
3. Otherwise consider all modules compatible with the firmware_id field, attempting to allocate the channel on each module, trying modules in increasing order of module index. If the channel is allocated, return it.
4. Otherwise, if any module reported the error ERR_SM_NO_RESOURCES, return that error.
5. Otherwise, if any module reported the error ERR_SM_BAD_PARAMETER, return that error.
6. Otherwise, if any module reported the error ERR_SM_WRONG_FIRMWARE_TYPE, return that error.
7. Otherwise, if any module reported the error ERR_SM_NO_FIRMWARE_RUNNING, return that error.
8. Otherwise, there are no suitable modules present, return ERR_SM_NO_SUCH_FIRMWARE.

While this is not exactly the same behaviour as Prosody version 1, it is intended to give the same result when channel allocation succeeds, and a good error report when it fails.

Automatic timeslot allocation

Prosody version 1 normally allocated a timeslot to each channel as it was allocated, whereas version 2 (TiNG) requires the application to assign timeslots explictly with sm_switch_channel_input(), and sm_switch_channel_output().

The resource manager provides backward compatibility by performing the allocation and assignment on behalf of the application. The application can retrieve the timeslot assignment using sm_channel_info(), as with Prosody version 1. Note that, just like Prosody 1, all timeslots are forced to be either A-law or mu-law depending on the firmware build being used.

Multi-process access to channels

Prosody version 1 permitted independent processes to control a single channel. Some API functions which used a tSMChannelID (which is local to the process which allocates a channel) had an equivalent which used a channel index instead. Prosody version 2 (TiNG) itself does not provide an implementation for any of these equivalents. However, the resource manager can provide implementations for many of these functions. In particular, these are provided:

• sm_conf_primix_start()
• sm_conf_primix_clone()
• sm_conf_primix_add()
• sm_conf_primix_leave()
• sm_conf_primix_info()
• sm_conf_primix_adj_input()
• sm_conf_primix_adj_output()
• sm_conf_primix_abort()

However, these functions are not provided:

• sm_channel_ix_info()
• sm_get_recognised_ix()
• sm_besp_write_status_ix()
• sm_besp_read_status_ix()
• sm_find_channel()
• sm_get_channel_ix_module_ix()
• sm_switch_channel_ix()

Because of the extra performance overhead imposed by using channel indexes, if you want to use them in an application, you must define the additional C preprocessor symbol TiNG_USE_CHANNEL_IX. In addition, the only channels which can use the ...conf_primix... API functions are "remote channels". These are channels which were allocated with the bit kSMChannelCapsRemoteAlloc set in the caps_mask field of the sm_channel_alloc() or sm_channel_alloc_placed() which allocated them. This causes the channel to be allocated inside the resource manager, rather than locally in your application. If you attempt to use an ordinary, local, channel with one of the ...conf_primix... API functions, it will normally return the error ERR_SM_NO_SUCH_CHANNEL, as the channel is local and the resource manager does not have a record of it. A remote channel has limited functionality. The only API functions which can use them are the ...conf_primix... and these:

• smd_ev_create()
• smd_ev_free()
• sm_channel_set_event()
• sm_listen_for()
• sm_get_recognised()

The above API calls allow remote channels to use events of type kSMEventTypeRecog to notify applications upon receipt of digits. Remote channels do not support any other event type.

An application may allocate a mixture of remote and local channels. It is the responsibility of the developer to ensure that the correct API calls are used for the different channel types.

It is best to reserve this feature purely for maintaining applications which require it for backward compatibility.

Controlling the resource manager

When the resource manager is running, you can give it commands on its input. The commands available are:

?

Help. Shows all the commands recognised.

q

Quit. The resource manager shuts itself down and exits.

t

Timeslots. The resource manager displays a snapshot of timeslots in use as described below.

c

Channels. The resource manager displays a snapshot of all channels in use as described below.

Timeslot display

The display of timelsots in use looks like this:

                                   1                   2                   3
       c  m st 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
       0  0 48       I         O     * *     O   * I       I
       0  0 49 *                                            
       0  1 50
       0  1 51
       0  2 52
       0  2 53
       0  3 54
       0  3 55
       1  4 48 * * * * * * * * * * * * * * * *

Each line shows the status of one stream. The labels on the left show the card number, module number, and stream number for the stream. The rest of the line shows each timeslot on that stream, with a star (*) for a timeslot if both the input and output is in use, "O" if only the output is in use, "I" if only the input is in use, and blank if it is not in use at all. So in the above example, the input timeslot 48:3 is in use, as is the output timeslot 48:8, while both input and output timeslots 48:11 are in use.

Channel display

The display of channels in use consists of one line for each channel. The lines look like this:

	   23 f c0  m0 ->48:0 <-48:0
	  101 h c1  m5
	  100 i c1  m5 <-50:5
	   30 o c0  m0 ->48:1

This shows four channels allocated. The first column is the channel index. The next column shows whether the channel is a full-duplex channel (f), a half-duplex channel (h), an input channel (i), or an output channel (o). This is followed by the card number and module number. The rest of the line shows information that may not apply to every channel. If the channel has an output timeslot assigned, this is shown as "->" and the stream and timeslot number. Similarly, "<-" indicates an input timeslot.

Using the resource manager

Before running an application that requires the resource manager, you must ensure that the resource manager is running. This may be done by starting it when the system boots, or by running the application from a script or batch file which starts the resource manager before the application. The resource manager is supplied in the directory $(TiNG)/ResourceManager. This directory contains firmware configuration files for the version 1 compatibility builds while the resource manager itself is in an appropriate sub-directory (gen-*) for each supported variant. When you start it, you must pass it the name of the appropriate configuration file as a parameter. For example:

	gen-WINNT/ResourceManager.exe sp30x2.cfg

where sp30x2.cfg is the desired configuration file. The format of this file is fully described in Firmware Download and Configuration Files, but for a quick and simple way to get started, take the sample sp30x2.cfg file and modify it to describe your system. The example file shows a configuration for a system with two DSPs each running the sp30 firmware build for A-law timeslots. There are two changes you might need to make: changing the number of DSPs (add or remove a section starting with <DSPINDEX> and adjust the number specified for <NUMDSPS>) and using different firmware builds (change sp30a.sfw to sp60u.sfw or whatever you want - the names are the same as the Prosody version 1 builds except they end in .sfw instead of .smf).

Building an application which uses the resource manager

Applications which use the resource manager must be built slightly differently to applications which use Prosody version 2 (TiNG) without the resource manager. The procedure described in Prosody Guide - how to build applications to use Prosody is extended as follows:

• You must define the additional C preprocessor symbol TiNG_USE_RESOURCE_MANAGER.
• If you want to use channel indexes, you must define the additional C preprocessor symbol TiNG_USE_CHANNEL_IX.
• You must build it as a multithreaded application (because the resource manager uses a thread inside the library).
• You must link it with a TCP/IP socket library:
  • On Linux, this is done automatically by the linker.
  • On Microsoft Windows, this means you must specify ws2_32.lib (or your preferred alternative socket library) as an extra library. For example in Visual Studio, in the project settings, there is an item labelled "Object/library modules" on the "Link" pane, and you add the socket library in there.
• You must link with the correct Prosody API library. To use the resource manager without channel indexes, this is:
  • On Linux: apilib/gen-LINUX/TiNGcore_rm.o
  • On Microsoft Windows: lib/gen-WINNT/TiNGcore_rm.obj or lib/gen-WINNT/TiNGcore_rm.dll
  To use channel indexes as well, it is:
  • On Linux: apilib/gen-LINUX/TiNGcore_rm_ix.o
  • On Microsoft Windows: lib/gen-WINNT/TiNGcore_rm_ix.obj or lib/gen-WINNT/TiNGcore_rm_ix.dll

On Microsoft Windows, there are project files for VisualStudio as described in Prosody installation guide: Visual Studio Project files which build the two variants of the Prosody library which use the resource mananger. The project called apilib_rm is the library for the resource manager and apilib_rm_ix is the library with channel indexes as well. Instead of explictly adding a Prosody library to your project, you can tell VisualStudio that your project uses one of these, and it will link with the correct library.

Document reference: AN 1387