|Home > Using the CADI Interface Methods from a Debugger > CADI accesses from a debugger > About CADI accesses from a debugger|
Using the CADI interface requires specific calling schemes and procedures.
This chapter describes typical schemes and the general usage of the CADI interface from the caller side.
A major aim of CADI 2.0 is to prevent the passing of data objects from the heap memory across dynamic library boundaries. To achieve this, each method call that passes information from the target to the caller must allocate data objects to receive the information. A pointer to this object is forwarded to the target that must fill it.
All CADI 2.0 data types provide a default constructor that initializes newly created data objects with reasonable values. This eliminates the risk that initialization is forgotten and unexpected behavior is caused by accident.
CADI 2.0 includes fundamental calling schemes for requesting hardware resource information and accessing these resources.
Methods in CADI 2.0 to request resource information typically have a prototype of this form:
CADIReturn_t method_name(uint32_t startIndex, uint32_t desiredNumOfElements, uint32_t *actualNumOfElements, dataType *buffer);
Follow these guidelines for all CADI calls:
startIndexrefers to an internal list within the target that contains the requested data. If requesting information of which every element holds a specific ID, the ID does not necessarily match the list index. Consequently, IDs are not required to be sequential.
bufferarray must match the
desiredNumOfElementsparameter. This is necessary to guarantee enough memory for passing the requested data.
desiredNumOfElementsmust always be larger or equal to the actually returned number of elements. Otherwise, the used buffer is too small and this might lead to undesired effects.
buffercontaining a smaller number of elements than requested. The available elements are copied into
bufferstarting from position zero. The call finishes with
actualNumOfElementsmust provide this number.
startIndexpoints behind the last position of the internal list held by the target, the call ends successfully and returning
Other similar schemes exist. The returned
CADIReturn_t and the
actualNumOfElements parameter are set accordingly.
If querying certain resource information, the expected number can be usually obtained in
the form of target properties returned by previous method calls. There are, however, some
methods such as
GetSimulationInfos() for which the caller cannot know the exact number of
properties in advance. For such calls, it is necessary to estimate a reasonable number that
is sufficient to receive all expected items.
If the complete array is filled for such calls, it might be necessary to repeat the call with a larger array because a completely filled array might mean both a number of items that exactly matched the requested one and a number of items that was too small. Because this case cannot be excluded, it is therefore necessary to ask for more items to assure that all items have been acquired.