3.1.1 About CADI accesses from a debugger

Using the CADI interface requires specific calling schemes and procedures.

  • Some are typically used for all targets such as, for example, setting up a target connection.
  • Some might be deployed for dedicated functionality such as, for example, writing to memories.

This chapter describes typical schemes and the general usage of the CADI interface from the caller side.

Note:

Procedures that are described in separate chapters are only covered briefly in this one.

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:

  • The startIndex refers 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.
  • The size of the buffer array must match the desiredNumOfElements parameter. This is necessary to guarantee enough memory for passing the requested data.
  • The number of elements requested in desiredNumOfElements must 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.
  • If more data elements than available are requested, only the existing elements are returned. This results in buffer containing a smaller number of elements than requested. The available elements are copied into buffer starting from position zero. The call finishes with CADI_STATUS_OK.
  • Even if a call fails, some data elements might have been successfully set. If so, actualNumOfElements must provide this number.
  • If the startIndex points behind the last position of the internal list held by the target, the call ends successfully and returning CADI_STATUS_OK, but actualNumOfElements is zero.

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 GetSimulationFactories() and 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.

Non-ConfidentialPDF file icon PDF versionARM 100963_0200_00_en
Copyright © 2014–2017 ARM Limited or its affiliates. All rights reserved.