Cycle Accurate Debug Interface v2.0 Developer Guide: 2.4. Using GetSimulationFactories()

2.4. Using GetSimulationFactories()

One way to establish a connection to a simulation target within CADI is to instantiate a CADI simulation and to connect to one of its targets.

To retrieve the list of available CADI simulation factories, the caller must execute the GetSimulationFactories() method in the CADI broker as shown in Figure 2.4. The result of this call is an array of CADISimulationFactory pointers.

The list of simulation factories is static for a CADI broker, therefore it is only required to retrieve the list once at the beginning of a debug session.

Note

The caller is responsible for releasing, but not deleting, all obtained simulation factory objects. It is not sufficient to release only those which have been used to instantiate a simulation.

Figure 2.4. Getting the CADI simulation factories

After retrieving the list of available simulation factories, the next step is to call the ObtainInterface() method of the CADI broker to check the compatibility of the requested factory. A static_cast() is required for the interface as described in Creating the CADIBroker.

After obtaining the appropriate CADI simulation factory, the caller must prepare the configuration of the targeted platform. This includes retrieving the available parameters and their settings.

Call the GetParamterInfos() method of CADISimulationFactory to retrieve the parameter information. It returns a list with descriptions of the configurable parameters (that is of data type CADIParameterInfo_t). This includes information such as the parameter ID for later reference, the parameter type, and the default value.

The caller can create a list of parameter values (of type CADIParameterValue_t) that are used for configuration of the platform. This list must end with an extra element that has the parameter ID 0xFFFFFFFF. It is required to add this element because not all parameters require setting and the order of the parameters within the list is undefined.

Note

Parameters that are not part of the value list sent by the caller are set to their default value.

The ID 0xFFFFFFFF is equal to static_cast<uint32_t>(-1).

Figure 2.5. Instantiating a CADI simulation

The list of parameter values is forwarded to the Instantiate() method of the simulation factory. This call creates the actual CADI simulation. It might also receive a pointer to a CADIErrorCallback object and a pointer to a CADISimulationCallback object. These objects are automatically registered to the newly instantiated CADI simulation and must be provided by the caller.

The result of the simulation instantiation is a pointer to a CADISimulation object as shown in Figure 2.5. A compatibility check consisting of its ObtainInterface() method and calling static_cast() must be performed.

After the CADI simulation is created, the simulation factory is no longer required. The pointer to the corresponding CADISimulationFactory can therefore be released. This can be safely done for the following reasons:

the CADI simulation is managed by the CADI broker
the simulation factory can be retrieved again from the broker if required.

Example 2.3 shows the entire process:

Example 2.3. Getting the simulation factory

//having already obtained a pointer to the CADIBroker before
//which is called cadi_broker
//callback objects, will be registered to CADISimulation
MyCADIErrorCallback errorCallbackObject;
MyCADISimulationCallback simulationCallbackObject;

//enable vector for MyCADISimulationCallback
char simulationCallbacksEnable[eslapi::CADI_SIM_CB_Count];

//enable all callbacks of MyCADISimulationCallback
memset(simulationCallbacksEnable,
       1, eslapi::CADI_SIM_CB_Count * sizeof(char)); 

//preparing parameters for GetSimulationFactories()
uint32_t desiredNumberOfFactories = 10; //arbitrarily chosen, must be large
                                        //enough to get all factories
uint32_t startFactoryIndex = 0;
uint32_t actualNumberOfFactories = 0;

// array of CADISimulationFactory pointers to store the broker's factories
eslapi::CADISimulationFactory** factoryList =
          new eslapi::CADISimulationFactory*[desiredNumberOfFactories]();

eslapi::CADIReturn_t status;

status = cadi_broker->GetSimulationFactories(startFactoryIndex,
                      desiredNumberOfFactories,
                      factoryList,
                      &actualNumberOfFactories);
if (status != eslapi::CADI_STATUS_OK)
{
   //GetSimulationFactories() failed 
}

//...decide which entry in factory list to use,
//let's assume we chose the second (index '1'!!)...
//check compatibility of factory
eslapi::if_name_t ifNameFactory = "eslapi.CADISimulationFactory2";
eslapi::if_rev_t  minRevFactory = 0;
eslapi::if_rev_t  actualRevFactory = 0;
if (factoryList[1]->ObtainInterface(ifNameFactory,
                                    minRevFactory,
                                    &actualRevFactory) == NULL)
{
     //factory is incompatible
}
//continue with instantiation of a simulation...
uint32_t desiredNumberOfParameterInfos = 20; //arbitrarily chose, must
                          //be large enough to store all parameter infos
uint32_t startParameterInfoIndex = 0;
uint32_t actualNumberOfParameterInfos = 0;
eslapi::CADIParameterInfo_t* parameterInfoList = new
eslapi::CADIParameterInfo_t[desiredNumberOfParameterInfos]();
status = factoryList[1]->GetParameterInfos(startParameterInfoIndex,
                                         desiredNumberOfParameterInfos,
                                         parameterInfoList,
                                         &actualNumberOfParameterInfos);
if (status != eslapi::CADI_STATUS_OK)
{
   //GetParameterInfos() failed
}
eslapi::CADIParameterValue_t* parameterValues =
  new eslapi::CADIParameterValue_t[actualNumberOfParameterInfos + 1]();
                                   // + additional "terminating" element
// ...fill the parameter values accordingly...
// set terminating element
parameterValues[actualNumberOfParameterInfos].parameterID =
                                              static_cast<uint32_t>(-1);
cadi_simulation = factoryList[1]->Instantiate(parameterValues,
                       &errorCallbackObject,
                       &simulationCallbackObject,
                       simulationCallbacksEnable);
if (cadi_simulation == NULL)
{
       //instantiation failed
}
//check compatibility of simulation
eslapi::if_name_t ifNameSimulation = "eslapi.CADISimulation2";
eslapi::if_rev_t  minRevSimulation = 0;
eslapi::if_rev_t  actualRevSimulation = 0;
if (cadi_simulation->ObtainInterface(ifNameSimulation,
                                     minRevSimulation,
                                     &actualRevSimulation) == NULL)
{
       //interface incompatible
}

//no longer needed
//release CADISimulationFactories, no longer needed
for (uint32_t i = 0; i < actualNumberOfFactories; i++)
     factoryList[1]->Release();

//no longer needed, destroy just the array
delete[] factoryList;

//continue with obtaining the CADI interface from simulation...

Copyright © 2008-2010 ARM Limited. All rights reserved.	ARM DUI 0444F
Non-Confidential	ID110210
PDF version