3.2. CADIReturn_t return values

Most CADI 2.0 methods return a value of type CADIReturn_t. The return value:

The CADIReturn_t object provides hints that are of value in classifying the error. The debugger can take appropriate action such as repeating a call with different parameters or triggering a fallback solution if the functionality is not supported. If required, more detailed information about a failure can be read from the target with the CADIXfaceGetError() method that is accessible through the CADI object of the target.

The possible return values are:

CADI_STATUS_OK

The method call completed successfully. The debugger is not required to take any additional action.

CADI_STATUS_ArgNotSupported

An argument that in principle can be processed is, however, not supported by the current target. This might be, for example, a register ID that is not assigned to any register or a memory address that does not belong to an addressable memory range.

The action the debugger must take depends on the unsupported argument:

  • If the argument represents a certain capability of the target, for example the stepOver argument of CADIExecSingleStep(), the debugger must switch to a fallback solution.

  • If an argument such as the groupID of CADIRegGetMap() is unsupported, this might be because the debugger used the wrong information.

CADI_STATUS_IllegalArgument

Indicates that the client issued a call that is disallowed by the CADI specification. The client must not rely on the target handling an illegal call correctly.

An illegal argument also refers to values that can never be accepted by an implementation of the method. This especially applies to values that represent an invalid CADI data object or to a pointer that has not been set to a valid object. For example, calling CADIBptClear() for a breakpoint ID of 0 (which is reserved for invalid breakpoints) must result in this return value.

Another important example of illegal arguments is the use of null pointers that are not explicitly permitted. If a CADI method returns with this value, the implementation of the corresponding debugger functionality is defective.

CADI_STATUS_CmdNotSupported

The called method is not implemented for the addressed target. An implementation of a CADI call returning this value must never return a different one. The client can assume that all future calls to the same method also return this value.

The debugger must react to this response with a fallback solution. If no fallback is available, the debugger cannot use the requested method on the selected target.

CADI_STATUS_UnknownCommand

This value must only be returned by methods that receive a command string such as CADIXfaceBypass(). It must be used if an unknown command is received. It is completely up to the target which commands are known and unknown.

CADI_STATUS_TargetBusy

The CADI call could not be completed because the target is busy. Registers and memories, for example, might not be writable while the target is executing application code. The target is typically not in a stable state and must return this value.

The debugger can either wait for the target to reach a stable state or enforce a stable state by, for example, stopping a running target. The debugger can repeat the original call after the target reaches a stable state.

CADI_STATUS_TargetNotResponding

The target did not respond to the call and the method timed out. This might be the result of a stalled simulation or, if debugging over a network, a lost connection.

The debugger can attempt to determine the reason the call failed by, for example, calling CADIXfaceGetError(). Depending on the result, the debugger might try to call the target again or it might attempt to safely clean up the connection.

CADI_STATUS_GeneralError

An error occurred that is not covered by one of the more precise return values.

The debugger can call CADIXfaceGetError() to determine the reason the call failed. Depending on the result, the debugger might attempt to handle the error.

CADI_STATUS_PermissionDenied

Method failed because of an access being denied, such as, for example, writing a read-only register.

This typically indicates a wrongly-configured access of a target resource.

CADI_STATUS_SecurityViolation

Method failed because of a security violation such as, for example, reading memory with restricted access.

This typically indicates a wrongly-configured access of a target resource.

CADI_STATUS_BufferSize

A character string buffer used to receive a response from a CADI method is too small to carry the entire string.

It is dependent on the implementation in target whether an empty string is returned or if the buffer is partially filled with the message based on the length of the buffer.

ARM recommends that the debugger does not rely on the returned information. The debugger must repeat the call using a larger string buffer.

CADI_STATUS_InsufficientResources

The method did not complete because of missing resources such as, for example, the simulation was not able to allocate enough memory on the host machine.

To determine which of the resources are insufficient, the debugger must call CADIXfaceGetError(). Depending on the result, the debugger might repeat the failed call with a different set of arguments or use a different call to achieve the wanted result.

Copyright © 2008-2014 ARM. All rights reserved.ARM DUI 0444M
Non-ConfidentialID051314