Prosody Guide - how to switch data

Prosody channels can process incoming data, through operations such as recording and signal categorisation, and produce output data through operations such as replaying and tone generation. This data is passed between a Prosody processor and the outside world through switch connections. Switch connections are controlled by the Aculab switch driver (except on the, now obsolete, Prosody ISA card). The switch driver controls a switch matrix, to which various devices are connected:

This shows a portion of the switching on a Prosody PCI card. The switch matrix is connected to the external H.100 bus and to Aculab devices on the card. Here is a more detailed view of the way that Prosody connects to the switch matrix:

This shows an example of a Prosody channel which has its output switched to a timeslot on the switch matrix labelled 48:1. A Prosody channel input is switched from a timeslot labelled 49:30. However you can see that there are two timeslots labelled 48:1 and two labelled 49:30. It is important not to confuse them as they are different and, as far as Prosody is concerned, totally unrelated. When you use sm_switch_channel_output() you specify a timeslot from a Prosody channel's output to the switch matrix. To connect this through the switch matrix using the switch API function sw_set_output() you need to specify the parameters:

	p.ist = 48;
	p.its = 1;
	p.mode = CONNECT_MODE;
	p.ost = destination_stream;
	p.ots = destination_timeslot;

Similarly, the stream and timeslot you specify when connecting a Prosody channel's input with sm_switch_channel_input() should be put in the ost and ots field of the parameter structure passed to sw_set_output().

For example, if you want to connect the above example channel so that it can record its own output, you would use:

	OUTPUT_PARMS p;
	p.ist = 48;
	p.its = 1;
	p.mode = CONNECT_MODE;
	p.ost = 49;
	p.ots = 30;
	err = sw_set_output(swdrvr, &p);
	if (err) ...	// handle error

Note that the timeslot assigned with sm_switch_channel_output() can never be used in the ost and ots fields of the parameter structure used by sw_set_output() because values in those fields always refer to the timeslots going in the opposite direction from the switch driver. Similarly the timeslot assigned with sm_switch_channel_input() can never be used in the ist and its field. If an application accidentally gets these the wrong way around none of the APIs can detect this because it is merely using the wrong, but valid, values.

The naming of timeslots on the H.100 bus can be confusing. Each timeslot on the H.100 bus has a unique name so, for example, 4:2 refers to a single timeslot - not a pair. This means that when you are connecting a full-duplex Prosody channel to a destination via the H.100 bus you need to use two H.100 timeslots - one for each direction. If you accidentally use only one, you will get a configuration like this:

Obviously, with both the switch matrix and the external device trying to write to the same timeslot simultaneously, the data will be corrupted, and both the external device and the Prosody input will get garbage.

See the documentation for the switch driver for more details about switching, including the streams available on each Aculab card.

Selecting timeslots to use

There are many ways to arrange timeslot usage. Generally it is a very good idea to use as simple an arrangement as the application architecture allows. For example, if you expect to use Prosody PCI cards with four trunks per card and two Prosody processors, then a very common arrangement is:

This type of fixed arrangement is very useful when debugging because it is not necessary to study detailed log files to determine how the data is routed through a system. It also avoids confusion when using the features, such as echo cancellation and conferencing, which use more than one input and output timeslot.

With one minor exception, Prosody imposes no restrictions on which timeslots can be used for which operations. The exception is that you cannot have both A-law and mu-law timeslots on a single stream. This does not mean that you cannot play A-law and mu-law encoded files simultaneously - it means that the encoding on the timeslots (i.e. as passed through the switch matrix to the outside world) must not be different. This situation is very unusual since only international gateways normally have to deal with both A-law and mu-law trunks.

For the timeslot assignment, half-duplex channels have a special exemption to the rule that a half duplex channel cannot act like both an input and an output channel at the same time. This exemption is that a half-duplex channel can have both an output timeslot and an input timeslot assigned simultaneously. However, this does not allow it to use them simultaneously - it is merely a convenience to avoid having to keep re-assigning the timeslot every time you switch between performing input and output.