2.18.x
|
|
| VAPI API Reference Documentation 2.18.x |
|
Functions | |
| VSTATUS | VAPI_OpenDevice (IN DEVID DevId, IN PFNEventCallback pfnEventCallback) |
| VSTATUS | VAPI_CloseDevice (IN DEVID DevId, IN ECloseMode eMode) |
| VSTATUS | VAPI_BootDevice (IN DEVID DevId, IN void *pvImageFile, IN U32 uImageSize, IN SHwCfg *pstSHwCfg, IN SRequest *pstRequest) |
| VSTATUS | VAPI_BootDeviceFile (IN DEVID DevId, IN char *strFileName, IN SHwCfg *pstSHwCfg, IN SRequest *pstRequest) |
| VSTATUS | VAPI_InitDevice (IN DEVID DevId, IN U32 ulOperationModeId, IN U32 ulProfileId, IN U32 *pulUserParams, IN SRequest *pstRequest) |
| VSTATUS | VAPI_GetCoreDump (IN DEVID DevId, IN U8 uchMemTypeIdx, OUT U8 *puchBuff, IN U32 ulBuffSize, OUT U32 *pulDataSize, IN U32 ulOffset, OUT Boolean *pbLastRead, IN SHwCfg *pstSHwCfg, IN SRequest *pstRequest) |
| VSTATUS | VAPI_SetEthMac (IN U32 uiID, IN U8 ucLevel, IN U8 *paucSrcMacAddr, IN U8 *paucDestMacAddr, IN SRequest *pstRequest) |
| VSTATUS | VAPI_SetDeviceIPAddr (IN DEVID DevId, IN SIpAddrInfo *pstIpAddrInfo, IN SRequest *pstRequest) |
| VSTATUS | VAPI_AssignBootMAC (IN DEVID DevId, IN SRequest *pstRequest) |
| VSTATUS | VAPI_SetTDMParams (IN DEVID DevId, IN STdmSetupParams *pstTdmSetupParam, IN SRequest *pstRequest) |
| VSTATUS | VAPI_RegisterReset (IN DEVID DevId, IN PFNResetDevice pfnReset, void *pvResetData) |
| VSTATUS | VAPI_SetDeviceVlan (IN DEVID DevId, IN U16 usVlanId, IN SRequest *pstRequest) |
| VSTATUS | VAPI_CESoPSN_Mapper (IN DEVID DevId, IN SRequest *pstRequest, IN EMapperType eMapType, IN CONNID MasterConnId, U16 Action, U16 usConnNum,...) |
Description:
This function assigns the MAC address to the slave mode Ethernet device.
It also disables broadcast reception of the device.
This API is required for Ethernet interface and needs to be called sequentially
for all slave Ethernet devices (i.e. the slaves should be brought out of reset one by one and then call VAPI_AssignBootMAC()).
After assigning MAC to all the slave devices they can be booted in parallel using VAPI_BootDevice().
| Inputs-Outputs | |
| DevId | Device identifier that uniquely identifies a device. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Commands: List of Comcerto commands sent:
| VSTATUS VAPI_BootDevice | ( | IN DEVID | DevId, | |
| IN void * | pvImageFile, | |||
| IN U32 | uImageSize, | |||
| IN SHwCfg * | pstSHwCfg, | |||
| IN SRequest * | pstRequest | |||
| ) |
Description:
The application uses this API to boot a Comcerto device.
Note: In Master mode this API is not needed.
Both the PCI and Ethernet based devices are booted using this API.
If the device to be booted is on the Ethernet then VAPI_AssignBootMAC should be
called before this API. This API downloads the AXF image file and starts the image execution.
The API gets completed after receiving SUPVSR_READY event from MSP.
After the completion device is ready to receive commands.
The boot steps include configuring the clock, SDRAM, chip selects etc by the using the corresponding MSP commands.
This API can used to boot more than one slave devices in parallel, provided that for Ethernet interface devices the MAC addresses have been assigned to them using VAPI_AssignBootMAC().
| Inputs-Outputs | |
| DevId | The device to be booted. |
| pvImageFile | The pointer to image buffer. |
| uImageSize | The size of image (the length of the buffer provided) |
| pstSHwCfg | User specified hardware configuration data. Use NULL for the default initialization. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Commands: The Comcerto commands sent are:
| VSTATUS VAPI_BootDeviceFile | ( | IN DEVID | DevId, | |
| IN char * | strFileName, | |||
| IN SHwCfg * | pstSHwCfg, | |||
| IN SRequest * | pstRequest | |||
| ) |
Description:
The application uses this API to boot a Comcerto device.
Note: In Master mode this API is not needed.
Both the PCI and Ethernet based devices are booted using this API.
If the device to be booted is on the Ethernet then VAPI_AssignBootMAC() should be
called before this API. This API downloads the AXF image file and starts the image execution.
The API gets completed after receiving SUPVSR_READY event from MSP.
After the completion device is ready to receive commands.
The boot steps include configuring the clock, SDRAM, chip selects etc by the using the corresponding MSP commands.
This API can used to boot more than one slave devices in parallel, provided that for Ethernet interface devices the MAC addresses have been assigned to them using VAPI_AssignBootMAC().
| Inputs-Outputs | |
| DevId | The device to be booted. |
| strFileName | The image file name. |
| pstSHwCfg | User specified hardware configuration data. Use NULL for the default initialization |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Commands: The Comcerto commands sent are:
| VSTATUS VAPI_CESoPSN_Mapper | ( | IN DEVID | DevId, | |
| IN SRequest * | pstRequest, | |||
| IN EMapperType | eMapType, | |||
| IN CONNID | MasterConnId, | |||
| U16 | Action, | |||
| U16 | usConnNum, | |||
| ... | ||||
| ) |
Description:
This API maps / unmaps the a master CESOPSN channel to othe CsoPSN channels
The MasterConnId must has been created previously in CESOPSN type (0x81).
In case of eMapType = eChannelMap the other connections must have been created previously in CESOPSN type too
| Inputs-Outputs | |
| DevId | Device ID. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
| MasterConnId | Master connection ID. |
| eMapType | Map channels or timeslots. |
| Action | 1: Map channels, 0: Unmap channels. |
| usConnNum | Number of connections to map. |
| .... | List of connections ID or timeslots to map (depends on eMapType). |
Returns:
usage
...
/* eChannelMap example all connections must be previously created */
/* this feature is supported from Comcerto release MR13*/
.....
result = VAPI_CreateConnection(device_id, 0, eCSEoPSN, 0, U_LAW, NULL, NULL);
if (result != SUCCESS)
printf( "check_cesopsn VAPI_CreateConnection master >>>>>>>>>>> error %d", result);
result = VAPI_CreateConnection(device_id, 1, eCSEoPSN, 1, U_LAW, NULL, NULL);
if (result != SUCCESS)
printf("check_cesopsn VAPI_CreateConnection mapped 1 >>>>>>>>>>> error %d", result);
result = VAPI_CreateConnection(device_id, 2, eCSEoPSN, 2, U_LAW, NULL, NULL);
if (result != SUCCESS)
printf( "check_cesopsn VAPI_CreateConnection mapped 2 >>>>>>>>>>> error %d", result);
result = VAPI_CreateConnection(device_id, 5, eCSEoPSN, 5, U_LAW, NULL, NULL);
if (result != SUCCESS)
printf( "check_cesopsn VAPI_CreateConnection mapped 5 >>>>>>>>>>> error %d", result);
/* the master connection is 0, map 4 connections, 0, 1, 2, 5*/
result = VAPI_CESoPSN_Mapper(device_id, NULL, eChannelMap, 0, 1, 4, 0, 1, 2, 5);
if (result != SUCCESS)
printf("check_cesopsn VAPI_CESoPSN_Mapper eChannelMap >>>>>>>>>>> error %d", result);
...
/* eTSMap example. Only the Master connection must be previously created */
/* this feature is supported from Comcerto release MR15*/
if (result != SUCCESS)
PDEBUG(DEBUG_ERROR, "check_cesopsn VAPI_DestroyConnection >>>>>>>>>>> error %d", result);
result = VAPI_CreateConnection(device_id, 0, eCSEoPSN, 0, U_LAW, NULL, NULL);
if (result != SUCCESS)
printf("check_cesopsn VAPI_CreateConnection master >>>>>>>>>>> error %d", result);
/* the master connection is 0, map 3 timeslots 1, 2, 5*/
result = VAPI_CESoPSN_Mapper(device_id, NULL, eTSMap, 0, 1, 3, 1, 2, 5);
if (result != SUCCESS)
printf( "check_cesopsn VAPI_CESoPSN_Mapper eTSMap >>>>>>>>>>> error %d", result);
}
Commands: List of Comcerto commands sent:
| VSTATUS VAPI_CloseDevice | ( | IN DEVID | DevId, | |
| IN ECloseMode | eMode | |||
| ) |
Description:
This API closes the devices and does the cleanup based on the mode. The VAPI removes all pending request for all channels and then calls the GTL_Shutdown API. In case of ePURGE_ALL if frees all MSP resources (channels, participants, transcoding sessions, conferences).
| Inputs-Outputs | |
| DevId | Device to be closed |
| eMode | Shutdown Mode |
Returns:
usage
/*Close device purge connection*/
status = VAPI_CloseDevice(device_id, ePURGE);
Commands:
| VSTATUS VAPI_GetCoreDump | ( | IN DEVID | DevId, | |
| IN U8 | uchMemTypeIdx, | |||
| OUT U8 * | puchBuff, | |||
| IN U32 | ulBuffSize, | |||
| OUT U32 * | pulDataSize, | |||
| IN U32 | ulOffset, | |||
| OUT Boolean * | pbLastRead, | |||
| IN SHwCfg * | pstSHwCfg, | |||
| IN SRequest * | pstRequest | |||
| ) |
Description:
This API is used to get dump information of the slave device memories, SDRAM, IRAM, etc.
This API must be called successively to get the complete dump.
The application supplies a buffer to hold the dump data for a specified memory and writes the data collected by the API to a file for the specific memory.
Note 1: This API uses BRM commands that resets the device if it was up, therefore operates only when the device RESET functionality is supported at the adapter level by the implementation of xxx_Reset(), which in turn is called through the GTL_Reset ().
Note 2: This API is not applicable in Master mode, also this API leaves the slave in a RESET state so the VAPI_BootDevice () must be called to boot the device for further use.
The VAPI_GetCoreDump() API can also be used to get a RDC (Reduced Size Coredump).
Please see the rcd.c file in the example section.
| Inputs-Outputs | |
| DevId | Id of the device to dump memory of. |
| uchMemTypeIdx | An Index to the memory to dump. Each index, starting from 0, represents a corresponding memory index. The number of memories and their respective sizes are organized by device type in 'vapi_device_config.c' file. |
| puchBuff | A caller allocated buffer that holds the memory dump data. |
| ulBuffSize | Size, in bytes, of the allocated memory dump destination buffer. |
| pulDataSize | A pointer indicating the number of bytes actually read. |
| ulOffset | Offset into the memory to read. |
| pbLastRead | A pointer to a Boolean flag indicating if the call to this API was last read for the memory specified by ucMemTypeIdx. |
| pstSHwCfg | User specified hardware configuration data. Use NULL for the default initialization |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Commands: List of Comcerto commands sent:
| VSTATUS VAPI_InitDevice | ( | IN DEVID | DevId, | |
| IN U32 | ulOperationModeId, | |||
| IN U32 | ulProfileId, | |||
| IN U32 * | pulUserParams, | |||
| IN SRequest * | pstRequest | |||
| ) |
Description:
This command is intended to be sent prior any connections.
It initializes the operation mode of the device (i.e VoIPoETH, VoAAL2oATM, etc )
This API can be called anytime after VAPI_Init(), but prior to VAPI_CreateConnection()
The parameters for the configuration are retrived using the profile ID
****** REMARK From the version 2.5.x this API is mandatory ******
****** if not sent all subsequent Connection Level APIs ******
****** will return the VAPI_ERR_DEVICE_NOT_INITIALIZED error ******
| Inputs-Outputs | |
| DevId | The device to initialize. |
| ulOperationModeId | This ID represents the list of command to be sent. The list of OperationModeId is available in vapi_profile.h file. |
| ulProfileId | This ID represents the configuration to be used to initialize the device. The list of ProfileId is available in vapi_profile.h file. |
| pulUserParams | The pointer to a buffer containg parameters provided by the user. The user specify here the device specific parameters such as MAC address or IP address. The format for these parameters are described in the vapi_profile.h file. In case of profile VAPI_DEV_PROF_SPU_CUSTOM the value for SPU Feature mask is passed through the pulUserParams parameters. For firmware release below MR19 the SPU Feature Mask is a single param (16 bits). From MR19 it could be 2 params (32bits). The LSB is param1 MSB param2 (see Usage section below) |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
...
/*This command will enable the DualFilter EchoCan SPU control option to the device 1*/
status = VAPI_DeviceInit (1, VAPI_DEV_OPMODE_DEFAULT, VAPI_DEV_PROF_SPU_DFECAN_ENABLE, NULL, NULL);
switch (status)
{
case SUCCESS: /* If success go ahead */
break;
default:
vapi_error_handler(status);
break;
}
...
Commands: For the VAPI release 2.4.x and 2.5x the Comcerto commands sent are:
| VSTATUS VAPI_OpenDevice | ( | IN DEVID | DevId, | |
| IN PFNEventCallback | pfnEventCallback | |||
| ) |
Description:
This function allocates resources associated with a device.
The Device ID is specified by the application that uniquely identifies a device.
The device ID is passed to the GTL layer for device initialization.
The GTL layer prepares mapping of Device ID to the proper PCI base address (for PCI) or CSME MAC *address (for CSME) and vice-versa.
| Inputs-Outputs | |
| DevId | Device to be opened. |
| pfnEventCallback | Device specific Event callback. The device level event callback. When events are received on this device this callback is used. |
Returns:
Commands: No Comcerto commands sent.
| VSTATUS VAPI_RegisterReset | ( | IN DEVID | DevId, | |
| IN PFNResetDevice | pfnReset, | |||
| void * | pvResetData | |||
| ) |
Description:
This API stores the customer device reset function and data pointers to the device structure.
The stored reset function with the associated data pointer is called by VAPI when a device reset is required (boot, coredump)
This API must be called after the VAPI_OpenDevice() API.
| Inputs-Outputs | |
| DevId | ID of the device to which the reset function is intented for |
| pfnReset | Customer specific device reset function |
| pvResetData | Customer specific data for the reset function |
Returns:
Usage:
...
/* customer side implementation example
define a structure to specify the reset required data*/
struct reset_data {
U16 reset_line;
U16 reset_time;
};
/* somehow define the data per device */
struct reset_data device0_reset_data = {0, 200};
struct reset_data device1_reset_data = {1, 200};
struct reset_data device2_reset_data = {2, 200};
/* implement the device reset handler */
VSTATUS comcerto_reset_handler(void *reset_data)
{
struct reset_data *this_reset_data = (struct reset_data*) reset_data;
printf("want to reset dev %d, reset time = %d\n", this_reset_data->reset_line, this_reset_data->reset_time);
customer_reset(this_reset_data->reset_line, this_reset_data->reset_time);
return SUCCESS;
}
...
/* register the reset function for the device ID 0, somewhere after VAPI_OpenDevice*/
result = VAPI_RegisterReset(0, comcerto_reset_handler, &device0_reset_data);
...
Commands:
| VSTATUS VAPI_SetDeviceIPAddr | ( | IN DEVID | DevId, | |
| IN SIpAddrInfo * | pstIpAddrInfo, | |||
| IN SRequest * | pstRequest | |||
| ) |
Description:
This function passes the IP address of a Comcerto device to MSP.
It also configures the IP layer. This function must be called before setting up a connection.
User can configure the device to be in single IP mode or in Multiple IP mode using SIpAddrInfo::bIsMultipleMode.
Multiple IP addresses can be provided in the array SIpAddrInfo::auiDevIPAddress.
| Inputs-Outputs | |
| DevId | Device identifier that uniquely identifies a device. |
| pstIpAddrInfo | IP address information |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
/*IP address used as the IP source for the RTP/UDPTL traffic * This IP address must be unique * On master configuration this IP address must be the same as the one defined for eth0 */ U8 device_ip[4] = { 192, 168, 0, 5 }; SIpAddrInfo ip_info; ip_info.ucNumOfSrcIpAddr = 1; /* only one IP addres for this device */ ip_info.bIsMultipleMode = 0; ip_info.ucEncapsulation = 2; /*VoIP packets are passed to the Ethernet Layer*/ ip_info.ucChkSumVerification = 1; /*Disable IP checksum on received packets */ memcpy(ip_info.auiDevIPAddress, device_ip, 4); status = VAPI_SetDeviceIPAddr(device_id, &ip_info, NULL); if (status != SUCCESS) PDEBUG(DEBUG_ERROR, "VAPI_SetDeviceIPAddr failed, status: %d", result);
Commands: List of Comcerto commands sent:
Description:
This API programs the VLAN ID in the ethernet header of the device.
This API doesn't send any command to the device. It just set an internal variable.
It required to issue this API before the VAPI_SetEthMac() to get the VLAN Id taken in account.
| Inputs-Outputs | |
| DevId | Device ID. |
| usVlanId | VLAN ID. If VLAN=0, no VLAN set. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
usage
... /* This MAC address will be used in the IP/UDP/RTP (UDPTL) frame as the source MAC address. * This MAC address must be unique. * On master configuration this MAC address must be the same as the one defined for eth0 */ U8 device_mac[6] = { 0x00, 0x50, 0xFC, 0xC3, 0xBD, 0xE2 }; /* 00:50:fc:c3:bd:e2*/ /* This can be the MAC address of an equipment on the subnet having IP forward capability * (PC, Router, etc). * This destination MAC is global for the device and all channnels, unless * it is overwritten at channel level by the SET_ETH_HDR_CHAN (VAPI_SetEthMac channel level call)*/ U8 default_dest_mac[6] = { 0x00, 0x11, 0xD8, 0xE7, 0xA5, 0x52 }; /*00:11:d8:e7:a5:52*/ /* This command set the VLAN ID at device level */ /* it must be issued before VAPI_SetEthMac() */ result = VAPI_SetDeviceVlan(device_id, 0x0100,NULL); /* This command set the Device MAC address */ status = VAPI_SetEthMac(device_id, CMD_LEVEL_DEVICE, device_mac, default_dest_mac, NULL); switch (status) { case SUCCESS: /* If success go ahead */ break; default: vapi_error_handler(status); break; } ... U8 connection_mac[6]; /* retrieve the MAC address to be assigned to the connection (i.e from a SIP negotiation)*/ get_mac_address(connection_mac); /*This command set the VLAN ID at connection level */ /* it musr be issued before VAPI_SetEthMac()*/ result = VAPI_SetConnVlan(connection_id, 0x0101,NULL); /*This command set the Connection MAC address */ status = VAPI_SetEthMac(connection_id, CMD_LEVEL_CONN, connection_mac, default_dest_mac, NULL); switch (status) { case SUCCESS: /* If success go ahead */ break; default: vapi_error_handler(status); break; }
Commands: List of Comcerto commands sent:
| VSTATUS VAPI_SetEthMac | ( | IN U32 | uiID, | |
| IN U8 | ucLevel, | |||
| IN U8 * | paucSrcMacAddr, | |||
| IN U8 * | paucDestMacAddr, | |||
| IN SRequest * | pstRequest | |||
| ) |
Description:
This API programs the SRC and DEST MAC address of an outgoing IP packet.
| Inputs-Outputs | |
| uiID | Device / Connection ID. |
| ucLevel | Level of command (Device/Connection). Valid values are:
|
| paucSrcMacAddr | Source MAC Address in Ethernet frame header (Big-endian). |
| paucDestMacAddr | Destination MAC address in Ethernet frame header (Big-endian). |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
usage
... /* This MAC address will be used in the IP/UDP/RTP (UDPTL) frame as the source MAC address. * This MAC address must be unique. * On master configuration this MAC address must be the same as the one defined for eth0 */ U8 device_mac[6] = { 0x00, 0x50, 0xFC, 0xC3, 0xBD, 0xE2 }; /* 00:50:fc:c3:bd:e2*/ /* This can be the MAC address of an equipment on the subnet having IP forward capability * (PC, Router, etc). * This destination MAC is global for the device and all channnels, unless * it is overwritten at channel level by the SET_ETH_HDR_CHAN (VAPI_SetEthMac channel level call)*/ U8 default_dest_mac[6] = { 0x00, 0x11, 0xD8, 0xE7, 0xA5, 0x52 }; /*00:11:d8:e7:a5:52*/ /*This command set the Device MAC address */ status = VAPI_SetEthMac(device_id, CMD_LEVEL_DEVICE, device_mac, default_dest_mac, NULL); switch (status) { case SUCCESS: /* If success go ahead */ break; default: vapi_error_handler(status); break; } ... U8 connection_mac[6]; /* retrieve the MAC address to be assigned to the connection (i.e from a SIP negotiation)*/ get_mac_address(connection_mac); /*This command set the Connection MAC address */ status = VAPI_SetEthMac(connection_id, CMD_LEVEL_CONN, connection_mac, default_dest_mac, NULL); switch (status) { case SUCCESS: /* If success go ahead */ break; default: vapi_error_handler(status); break; }
Commands: List of Comcerto commands sent:
| VSTATUS VAPI_SetTDMParams | ( | IN DEVID | DevId, | |
| IN STdmSetupParams * | pstTdmSetupParam, | |||
| IN SRequest * | pstRequest | |||
| ) |
Description:
This function is used to configure the four TDM buses of the Mindspeed device.
This function will configure TDM buses as per the input parameters sent in STdmSetupParam structure.
This function must be called after boot loading the Comcerto device.
| Inputs-Outputs | |
| DevId | Device identifier that uniquely identifies a device. |
| pstTdmSetupParam | TDM bus parameters |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
...
STdmSetupParams tdm_parameters;
memset(&tdm_parameters, 0, sizeof(tdm_parameters));
tdm_parameters.usMode = 1; /* one bus mode */
tdm_parameters.usNoOfBus = 1; /* enable tdm bus */
tdm_parameters.astTdmBusParam[0].ucTxOrder = 1;
tdm_parameters.astTdmBusParam[0].ucTxClkEdge = 1;
tdm_parameters.astTdmBusParam[0].ucFrameEdge = 1;
tdm_parameters.astTdmBusParam[0].usNumOfTS = 128; /* 128 timeslots*/
tdm_parameters.astTdmBusParam[0].ucInvertedFrmSig = 1;
tdm_parameters.astTdmBusParam[0].ucBitOrderRcv = 1;
status = VAPI_SetTDMParams(device_id, &tdm_parameters, NULL);
if (status != SUCCESS)
PDEBUG(DEBUG_ERROR, "VAPI_SetTDMParams failed, status: %d", status);
...
Commands:
List of Comcerto commands sent: