6.3.2 Working with Flexible Routing Configurations

The following topics provide more information about using Global Call with DM3 boards that use the flexible routing configuration:

• Determining Channel Capabilities (Flexible Routing)
• Using Device Handles (Flexible Routing)
• Multi-Threading and Multi-Processing (Flexible Routing)
• Initializing an Application that Uses DM3 Boards (Flexible Routing)
• Initializing Global Call When Using DM3 Boards (Flexible Routing)
• Device Discovery for DM3 Boards and Springware Boards (Flexible Routing)
• Device Initialization Hint (Flexible Routing)
• Using Protocols with DM3 Boards (Flexible Routing)

6.3.2.1 Determining Channel Capabilities (Flexible Routing)

DM3 boards support three different types of voice devices:

• E1 CAS compatible
• T1 CAS compatible
• ISDN compatible

The E1 CAS compatible is a superset of T1 CAS compatible, and the T1 CAS compatible is a superset of ISDN compatible.

When using Global Call, only certain DM3 network interface devices can be associated with certain other DM3 voice devices using gc_OpenEx( ) or gc_AttachResource( ). Attaching DM3 devices together depends on the network protocol used and voice device capabilities. Specifically:

• A DM3 ISDN network device can be attached to any DM3 voice device.
• A DM3 T1 CAS network device must be attached to a T1 CAS compatible DM3 voice device.
• A DM3 E1 CAS network device must be attached to an E1 CAS compatible DM3 voice device.

Caution: When using gc_OpenEx( ) to open devices, or gc_AttachResource( ) to associate a network device with a resource device, you cannot mix DM3 and Springware devices. For example, you cannot attach a DM3 network interface device with a Springware voice device.

An application can query the capabilities of a device using the dx_getfeaturelist( ) function which includes information about the front end supported, meaning ISDN, TI CAS, or R2/MF. See the Voice API Library Reference for more information about the dx_getfeaturelist( ) function.

When using Global Call, if a voice device is not CAS or R2/MF capable, it cannot be attached (either in the gc_OpenEx( ) function or when using the gc_AttachResource( ) function) to a network interface device that has CAS or R2/MF loaded. Likewise, if a voice device is not routable, it cannot be used in a gc_AttachResource( ) call.

While a network interface protocol cannot be determined programmatically, the dx_getfeaturelist( ) function provides a programmatic way of determining voice capability so that the application can make decisions.

6.3.2.2 Using Device Handles (Flexible Routing)

For DM3 boards using a flexible routing configuration, you can use the same Global Call device initialization, handling, and routing procedures for DM3 devices as you use for Springware devices.

In general, when using DM3 or Springware boards, an application must use a device discovery procedure to become hardware-aware. To perform device discovery and identify whether a logical device belongs to a Springware board or a DM3 board, use the gc_GetCTInfo( ) function and check the ct_devfamily field in the CT_DEVINFO structure for a value of CT_DFDM3. See the Voice API Library Reference for more information on the CT_DEVINFO structure.

When using DM3 boards, application performance may be a consideration when opening and closing devices using Global Call. If an application must use Global Call to dynamically open and close devices as needed, it can impact the application's performance. One way to avoid this is to open all DM3 devices during application initialization and keep them open for the duration of the application, closing them only at the end.

6.3.2.3 Multi-Threading and Multi-Processing (Flexible Routing)

When using DM3 boards, the R4 APIs support multi-threading and multi-processing with some restrictions on multi-processing as follows:

• One specific channel can only be opened in one process at a time. There can, however, be multiple processes accessing different sets of channels. In other words, ensure that each process is provided with a unique set of devices to manipulate.
• If a channel was opened in process A and then closed, process B is then allowed to open the same channel. However, since closing a channel is an asynchronous operation when using R4 with DM3 boards, there is a small gap between the time when the xx_close( ) function returns in process A and the time when process B is allowed to open the same channel. If process B opens the channel too early, things could go wrong. For this reason, this type of sequence should be avoided.

6.3.2.4 Initializing an Application that Uses DM3 Boards (Flexible Routing)

DM3 devices have similar characteristics to Springware devices. The device must first be opened in order to obtain its handle, which can then be used to access the device functionality. Since applications use Global Call for call control (that is, for call setup and tear-down), all Intel® Dialogic network interface devices must be opened using the gc_OpenEx( ) function.

Note: When call control is not required, such as with ISDN NFAS, dt_open( ) can be used to open DM3 network interface devices.

Once the call has been established, voice and or data streaming should be done using the Intel® Dialogic Voice API. Functions such as dx_playiottdata( ), dx_reciottdata( ), and dx_dial( ) can be used. Of course, in order to do so, the voice device handle must be obtained.

Application initialization differs depending on the types of hardware and the APIs used. The simplest hardware and API scenario is that where the system contains only one type of board, so that the application uses either Springware boards or DM3 boards but not both. In these cases, the initialization routine is the simplest in that it does not need to discover the board family type. See Section 6.3.2.5, "Initializing Global Call When Using DM3 Boards (Flexible Routing)" for more information.

Applications that want to make use of both Springware and DM3 devices must have a way of differentiating what type of device is to be opened. The Global Call routing function gc_GetCTInfo( ) provides a programming solution to this problem. DM3 hardware is identified by the CT_DFDM3 value in the ct_devfamily field of the CT_DEVINFO structure. Only DM3 devices will have this field set to CT_DFDM3. See Section 6.3.2.6, "Device Discovery for DM3 Boards and Springware Boards (Flexible Routing)" for more information.

6.3.2.5 Initializing Global Call When Using DM3 Boards (Flexible Routing)

This scenario is one where an application uses only DM3 boards in a flexible routing configuration. When initializing an application to use boards based on the DM3 architecture, you must use Global Call to handle the call control. Initializing Global Call in a system with only DM3 boards is no different than initializing Global Call in a system with only Springware boards. This is because R4 is flexible enough to support the different methods of Global Call initialization for both ISDN and CAS protocols.

Take note of the following flexibility that exists for the gc_OpenEx( ) function when opening a Global Call line device on DM3 boards:

• Due to the nature of the DM3 architecture, the protocol name is irrelevant at the time of opening the Global Call line device; that is, the protocol name is ignored. Although it is not necessary to specify a protocol name, you can retain a protocol name in this field to support Springware boards and so as to retain compatibility with code for Springware boards. Also, when using R4 with boards based on the DM3 architecture, all protocols are bi-directional. You do not need to dynamically open and close devices to change the direction of the protocol.
• It is not necessary to specify a voice device name when opening a Global Call line device. If you specify the voice device name, the network interface device is automatically associated with the voice device (they are attached and routed on the TDM bus). If you do not specify the voice device name when you open the Global Call line device, you can separately open a voice device, and then attach and route it to the network interface device. This flexibility allows you to port a Global Call application that uses Springware boards to an application that uses boards based on the DM3 architecture with little change and regardless of whether the application uses an ISDN or CAS protocol.

  Note that when opening a Global Call line device for CAS protocols on Springware boards, the voice device name, network interface device name, and protocol name are required; otherwise the function fails. For ISDN protocols on Springware boards, it is invalid to specify a voice device name; otherwise the function fails. For boards that use the DM3 architecture in a flexible routing configuration, only the network device name is required.

The following procedure shows how to initialize Global Call when using DM3 boards. For some steps, two alternatives are described, depending upon whether you want your application to retain the greatest degree of compatibility with Global Call using an ISDN protocol or a CAS protocol on Springware boards. Since this procedure is oriented toward retaining compatibility with two common ways of initializing Global Call on Springware boards, it is not intended as a recommendation of a preferred way to initialize Global Call on DM3 boards. The Global Call API allows design flexibility. The procedure for Global Call initialization for a given application would depend on things such as whether Springware boards and DM3 boards are used in the same system, what protocol is used, the purpose of the application program, and its design.

Note: In Windows, use the sr_getboardcnt( ) function with the class name set to DEV_CLASS_DTI and DEV_CLASS_VOICE to determine the number of network and voice boards in the system, respectively.

1. Start/Initialize Global Call using gc_Start( ).
2. Use gc_OpenEx( ) to open a Global Call line device.
   • Specify the network interface device name and the protocol name in the devicename parameter, as in the following example:
     ":N_dtiB1T1:P_ISDN"
   • Alternatively, specify the network interface device name, the voice device name, and the protocol name in the devicename parameter, as in the following example:
     ":N_dtiB1T1:V_dxxxB1C1:P_ar_r2_io"
3. Obtain the voice channel device handle.
   • Open a voice channel device (for example, dxxxB1C1) with dx_open( ) to get its handle.
   • Alternatively, if you specified the voice device name in the devicename parameter in step 2, use gc_GetResourceH( ), with a resourcetype of GC_VOICEDEVICE, to get the handle.
4. Attach the voice and network interface devices.
   • Use gc_AttachResource( ) to attach the voice resource and the network interface line device.
   • Alternatively, if you specified the voice device name in the devicename parameter in step 2, the voice and network interface devices are attached by nature of the gc_OpenEx( ), so no action is necessary for this step.
5. Use gc_GetResourceH( ), with a resourcetype of GC_NETWORKDEVICE, to obtain the network interface time slot device handle that is associated with the line device.
6. Set up TDM bus full duplex routing between the network interface device and voice device.
   • Use nr_scroute(FULL DUPLEX).
   • Alternatively, if you specified the voice device name in the devicename parameter in step 2, the network interface device and voice device are automatically routed on the TDM bus by nature of the gc_OpenEx( ).

Repeat steps 2 to 6 for all Global Call device line devices.

6.3.2.6 Device Discovery for DM3 Boards and Springware Boards (Flexible Routing)

The following procedure shows how to initialize an application and perform device discovery when the application supports DM3 and Springware boards.

Note: In Windows, use the sr_getboardcnt( ) function with the class name set to DEV_CLASS_DTI and DEV_CLASS_VOICE to determine the number of network and voice boards in the system, respectively.

1. Open the first network interface time slot device (for example, dtiB1T1) on the first trunk with dt_open( ).
2. Call dt_getctinfo( ) and check the CT_DEVINFO.ct_devfamily value.
3. If ct_devfamily is CT_DFDM3, then flag all the network interface time slot devices associated with the trunk as DM3 type.
4. Close the DTI device with dt_close( ).
5. Repeat steps 1 to 4 for each trunk.
6. Open the first voice channel device on the first voice board in the system with dx_open( ).
7. Call dx_getctinfo( ) and check the CT_DEVINFO.ct_devfamily value.
8. If ct_devfamily is CT_DFDM3, then flag all the voice channel devices associated with the board as DM3 type.
9. Close the voice channel with dx_close( ).
10. Repeat steps 6 to 9 for each voice board.
11. For those voice and network interface devices that are not DM3 devices, proceed with the standard initialization process for Springware boards as performed in the original application.
12. For those voice and network interface devices that are DM3 devices, proceed with the initialization as described in Section 6.3.2.5, "Initializing Global Call When Using DM3 Boards (Flexible Routing)".

6.3.2.7 Device Initialization Hint (Flexible Routing)

In some applications, when xx_open( ) functions (Global Call, Voice, Fax) are issued asynchronously, it may cause slow device-initialization performance. Fortunately, you can avoid this particular problem quite simply by reorganizing the way the application opens and then configures devices. The recommendation is to do all xx_open( ) functions for all channels before proceeding with the next function. For example, you would have one loop through the system devices to do all the xx_open( ) functions first, and then start a second loop through the devices to configure them, instead of doing one single loop where a xx_open( ) is immediately followed by other API functions on the same device. With this method, by the time all xx_open( ) commands are completed, the first channel will be initialized, so you won't experience problems.

This change is not necessary for all applications, but if you experience poor initialization performance, you can gain back speed by using this hint.

6.3.2.8 Using Protocols with DM3 Boards (Flexible Routing)

For T-1 and ISDN protocols, the protocol to use is determined at board initialization time and not when opening a Global Call device. Protocol parameters are configured in the CONFIG file, which is then converted to an FCD file using the FCDGEN utility. The FCD file is then downloaded to the board. If a protocol is specified in the devicename parameter of the gc_OpenEx( ) command when opening a device, it is ignored.

For E-1 R2MF protocols, you can use the DM3 PDK Manager utility to select E-1 CAS R2MF protocols to use. The DM3 PDK Manager does not integrate Country Dependent Parameter (CDP) file information into the FCD file. Instead, it hotloads protocol information separately to the board after the FCD file is downloaded and the board is initialized. See the Intel® NetStructure on DM3 Architecture for cPCI Configuration Guide for information on the DM3 PDK Manager. The Global Call protocols suitable for use with DM3 boards are available on a separate Global Call Protocols Package CD. Contact Technical Support for more information. Once the protocols have been hotloaded to the board, the protocol to use can be specified in the devicename parameter of the gc_OpenEx( ) command.

6.3.2.9 Country Dependent Parameter (CDP) Files

For T-1 and ISDN protocols, Country Dependent Parameter (CDP) files are not used. Country dependent parameters are specified in the [CHP] section of the CONFIG file. The purpose of the CONFIG file is to define the parameter settings necessary to configure a DM3 hardware/firmware product for a particular feature set. The FCDGEN utility is then used to convert the CONFIG file to a Feature Configuration Description (FCD) file. The FCD file configures the DM3 board (including protocol country dependent parameters) as part of the firmware download process.

E-1 CAS R2MF protocols are available on a separate Global Call Protocols Package CD. When the protocols are installed, the Country Dependent Parameter (CDP) files are installed in the \data directory under the Dialogic home directory.

Caution: For configurations that use both DM3 and Springware boards, CDP files for protocols used with DM3 boards have the same names as CDP files for protocols used with Springware boards. The DM3 CDP files are located in the \data directory; while the Springware CDP files are located in the \cfg directory. When editing a CDP file, be careful that you are editing the correct CDP file.

Click here to contact Telecom Support Resources