USBDM (JS16 Minimal Version) V4.8
Data Structures | Typedefs | Enumerations | Functions

USBDM_API.h File Reference

Header file for USBDM_API.c. More...

Data Structures

struct  USBDMStatus_t
 State of BDM Communication. More...
struct  BDM_Options_t
 BDM interface options. More...
struct  USBDM_Version_t
 Structure to hold version information for BDM. More...
struct  USBDM_bdmInformation_t
 Structure describing characteristics of currently open BDM. More...

Typedefs

typedef ICP_ErrorCode_t(* icpCallBackT )(ICP_ErrorCode_t status, unsigned int percent)
 ICP callback.

Enumerations

enum  USBDM_ErrorCode {
  BDM_RC_OK = 0, BDM_RC_ILLEGAL_PARAMS = 1, BDM_RC_FAIL = 2, BDM_RC_BUSY = 3,
  BDM_RC_ILLEGAL_COMMAND = 4, BDM_RC_NO_CONNECTION = 5, BDM_RC_OVERRUN = 6, BDM_RC_CF_ILLEGAL_COMMAND = 7,
  BDM_RC_UNKNOWN_TARGET = 15, BDM_RC_NO_TX_ROUTINE = 16, BDM_RC_NO_RX_ROUTINE = 17, BDM_RC_BDM_EN_FAILED = 18,
  BDM_RC_RESET_TIMEOUT_FALL = 19, BDM_RC_BKGD_TIMEOUT = 20, BDM_RC_SYNC_TIMEOUT = 21, BDM_RC_UNKNOWN_SPEED = 22,
  BDM_RC_WRONG_PROGRAMMING_MODE = 23, BDM_RC_FLASH_PROGRAMING_BUSY = 24, BDM_RC_VDD_NOT_REMOVED = 25, BDM_RC_VDD_NOT_PRESENT = 26,
  BDM_RC_VDD_WRONG_MODE = 27, BDM_RC_CF_BUS_ERROR = 28, BDM_RC_USB_ERROR = 29, BDM_RC_ACK_TIMEOUT = 30,
  BDM_RC_FAILED_TRIM = 31, BDM_RC_FEATURE_NOT_SUPPORTED = 32, BDM_RC_RESET_TIMEOUT_RISE = 33, BDM_RC_WRONG_BDM_REVISION = 34,
  BDM_RC_WRONG_DLL_REVISION = 35, BDM_RC_NO_USBDM_DEVICE = 36, BDM_RC_JTAG_UNMATCHED_REPEAT = 37, BDM_RC_JTAG_UNMATCHED_RETURN = 38,
  BDM_RC_JTAG_UNMATCHED_IF = 39, BDM_RC_JTAG_STACK_ERROR = 40, BDM_RC_JTAG_ILLEGAL_SEQUENCE = 41, BDM_RC_TARGET_BUSY = 42,
  BDM_RC_JTAG_TOO_LARGE = 43, BDM_RC_DEVICE_NOT_OPEN = 44, BDM_RC_UNKNOWN_DEVICE = 45, BDM_RC_DEVICE_DATABASE_ERROR = 46,
  BDM_RC_ARM_PWR_UP_FAIL = 47, BDM_RC_ARM_ACCESS_ERROR = 48, BDM_JTAG_TOO_MANY_DEVICES = 49, BDM_RC_SECURED = 50
}
 

Error codes returned from BDM routines and BDM commands.

More...
enum  HardwareCapabilities_t { ,
  BDM_CAP_HCS12 = (1<<0), BDM_CAP_RS08 = (1<<1), BDM_CAP_VDDCONTROL = (1<<2), BDM_CAP_VDDSENSE = (1<<3),
  BDM_CAP_CFVx = (1<<4), BDM_CAP_HCS08 = (1<<5), BDM_CAP_CFV1 = (1<<6), BDM_CAP_JTAG = (1<<7),
  BDM_CAP_DSC = (1<<8), BDM_CAP_ARM_JTAG = (1<<9), BDM_CAP_RST = (1<<10), BDM_CAP_PST = (1<<11),
  BDM_CAP_CDC = (1<<12), BDM_CAP_ARM_SWD = (1<<9)
}
 

Capabilities of the hardware.

More...
enum  TargetType_t {
  T_HC12 = 0, T_HCS08 = 1, T_RS08 = 2, T_CFV1 = 3,
  T_CFVx = 4, T_JTAG = 5, T_EZFLASH = 6, T_MC56F80xx = 7,
  T_ARM_JTAG = 8, T_OFF = 0xFF
}
 

Target microcontroller types.

More...
enum  DerivativeType_t {
  KA1 = 0, KA2 = 1, LA8 = 2, KA4 = 4,
  KA8 = 5, LE4 = 6
}
 

Target RS08 microcontroller derivatives.

More...
enum  AcknMode_t { WAIT = 0, ACKN = 1 }
 

Target supports ACKN or uses fixed delay {WAIT} instead.

More...
enum  SpeedMode_t { SPEED_NO_INFO = 0, SPEED_SYNC = 1, SPEED_GUESSED = 2, SPEED_USER_SUPPLIED = 3 }
 

Target speed selection.

More...
enum  ResetState_t { RSTO_ACTIVE = 0, RSTO_INACTIVE = 1 }
 

Target RSTO state.

More...
enum  ResetMode_t { NO_RESET_ACTIVITY = 0 , RESET_DETECTED = 1 }
 

Target reset status values.

More...
enum  TargetRunState_t { TARGET_RUNNING = 0, TARGET_HALTED = 1 }
 

Target Halt state.

More...
enum  TargetVddState_t { BDM_TARGET_VDD_NONE = 0, BDM_TARGET_VDD_EXT = 1, BDM_TARGET_VDD_INT = 2, BDM_TARGET_VDD_ERR = 3 }
 

Target Voltage supply state.

More...
enum  AutoConnect_t { AUTOCONNECT_NEVER = 0, AUTOCONNECT_STATUS = 1, AUTOCONNECT_ALWAYS = 2 }
 

Auto-reconnect options.

More...
enum  TargetVddSelect_t {
  BDM_TARGET_VDD_OFF = 0, BDM_TARGET_VDD_3V3 = 1, BDM_TARGET_VDD_5V = 2, BDM_TARGET_VDD_ENABLE = 0x10,
  BDM_TARGET_VDD_DISABLE = 0x11
}
 

Internal Target Voltage supply selection.

More...
enum  TargetVppSelect_t { BDM_TARGET_VPP_OFF = 0, BDM_TARGET_VPP_STANDBY = 1, BDM_TARGET_VPP_ON = 2, BDM_TARGET_VPP_ERROR = 3 }
 

Internal Programming Voltage supply selection.

More...
enum  ClkSwValues_t { CS_DEFAULT = 0xFF, CS_ALT_CLK = 0, CS_NORMAL_CLK = 1 }
 

Target BDM Clock selection.

More...
enum  TargetMode_t {
  RESET_MODE_MASK = (3<<0), RESET_SPECIAL = (0<<0), RESET_NORMAL = (1<<0), RESET_TYPE_MASK = (7<<2),
  RESET_ALL = (0<<2), RESET_HARDWARE = (1<<2), RESET_SOFTWARE = (2<<2), RESET_POWER = (3<<2)
}
 

Reset mode as used by CMD_USBDM_TARGET_RESET.

More...
enum  HCS12_Registers_t {
  HCS12_RegPC = 3, HCS12_RegD = 4, HCS12_RegX = 5, HCS12_RegY = 6,
  HCS12_RegSP = 7, HCS12_RegCCR = 0x80
}
 

regNo Parameter for USBDM_ReadReg() with HCS12 target

More...
enum  HCS08_Registers_t {
  HCS08_RegPC = 0xB, HCS08_RegSP = 0xF, HCS08_RegHX = 0xC, HCS08_RegA = 8,
  HCS08_RegCCR = 9
}
 

regNo Parameter for USBDM_ReadReg() with HCS08 target

More...
enum  RS08_Registers_t { RS08_RegCCR_PC = 0xB, RS08_RegSPC = 0xF, RS08_RegA = 8 }
 

regNo Parameter for USBDM_ReadReg() with RS08 target

More...
enum  CFV1_Registers_t {
  CFV1_RegD0 = 0, CFV1_RegD1 = 1, CFV1_RegD2 = 2, CFV1_RegD3 = 3,
  CFV1_RegD4 = 4, CFV1_RegD5 = 5, CFV1_RegD6 = 6, CFV1_RegD7 = 7,
  CFV1_RegA0 = 8, CFV1_RegA1 = 9, CFV1_RegA2 = 10, CFV1_RegA3 = 11,
  CFV1_RegA4 = 12, CFV1_RegA5 = 13, CFV1_RegA6 = 14, CFV1_RegA7 = 15,
  CFV1_PSTBASE = 16
}
 

regNo Parameter for USBDM_ReadReg() with CFV1 target

More...
enum  CFVx_Registers_t {
  CFVx_RegD0 = 0, CFVx_RegD1 = 1, CFVx_RegD2 = 2, CFVx_RegD3 = 3,
  CFVx_RegD4 = 4, CFVx_RegD5 = 5, CFVx_RegD6 = 6, CFVx_RegD7 = 7,
  CFVx_RegA0 = 8, CFVx_RegA1 = 9, CFVx_RegA2 = 10, CFVx_RegA3 = 11,
  CFVx_RegA4 = 12, CFVx_RegA5 = 13, CFVx_RegA6 = 14, CFVx_RegA7 = 15
}
 

regNo Parameter for USBDM_ReadReg() with CFVx target

More...
enum  ARM_Registers_t {
  ARM_RegR0 = 0, ARM_RegR1 = 1, ARM_RegR2 = 2, ARM_RegR3 = 3,
  ARM_RegR4 = 4, ARM_RegR5 = 5, ARM_RegR6 = 6, ARM_RegR7 = 7,
  ARM_RegR8 = 8, ARM_RegR9 = 9, ARM_RegR10 = 10, ARM_RegR11 = 11,
  ARM_RegR12 = 12, ARM_RegSP = 13, ARM_RegLR = 14, ARM_RegPC = 15,
  ARM_RegxPSR = 16, ARM_RegMSP = 17, ARM_RegPSP = 18 , ARM_RegFPSCR = 0x21,
  ARM_RegFPS0 = 0x40
}
 

regNo Parameter for USBDM_ReadReg() with ARM (Kinetis) target

More...
enum  CFV1_CRegisters_t {
  CFV1_CRegOTHER_A7 = 0, CFV1_CRegVBR = 1, CFV1_CRegCPUCR = 2, CFV1_CRegSR = 14,
  CFV1_CRegPC = 15
}
 

regNo Parameter for USBDM_ReadCReg() with CFV1 target

More...
enum  CFVx_CRegisters_t {
  CFVx_CRegD0 = 0x80 , CFVx_CRegA0 , CFVx_CRegOTHER_SP = 0x800, CFVx_CRegVBR = 0x801,
  CFVx_CRegSR = 0x80E, CFVx_CRegPC = 0x80F, CFV1_CRegFLASHBAR = 0xC04, CFV1_CRegRAMBAR = 0xC05
}
 

regNo Parameter for USBDM_ReadCReg() with CFVx target

More...
enum  ARM_CRegisters_t { ARM_MDM_AP_Status = 0x01000000, ARM_MDM_AP_Control = 0x01000004, ARM_MDM_AP_Id = 0x010000FC }
 

regNo Parameter for ARM_ReadCReg() with ARM target

More...
enum  HCS12_DRegisters_t { HCS12_DRegBDMSTS = 0xFF01, HCS12_DRegCCR = 0xFF06, HCS12_DRegBDMINR = 0xFF07 }
 

regNo Parameter for USBDM_ReadDReg() with HCS12 target [BD Space]

More...
enum  HCS08_DRegisters_t { HCS08_DRegBKPT = 0x0 }
 

regNo Parameter for USBDM_ReadDReg() with HCS08 target [BKPT reg]

More...
enum  RS08_DRegisters_t { RS08_DRegBKPT = 0x0 }
 

regNo Parameter for USBDM_ReadDReg() with RS08 target (BKPT)

More...
enum  CFV1_DRegisters_t {
  CFV1_DRegCSR = 0x00, CFV1_DRegXCSR = 0x01, CFV1_DRegCSR2 = 0x02, CFV1_DRegCSR3 = 0x03,
  CFV1_DRegBAAR = 0x05, CFV1_DRegAATR = 0x06, CFV1_DRegTDR = 0x07, CFV1_DRegPBR0 = 0x08,
  CFV1_DRegPBMR = 0x09, CFV1_DRegABHR = 0x0C, CFV1_DRegABLR = 0x0D, CFV1_DRegDBR = 0x0E,
  CFV1_DRegBDMR = 0x0F, CFV1_DRegPBR1 = 0x18, CFV1_DRegPBR2 = 0x1A, CFV1_DRegPBR3 = 0x1B ,
  CFV1_DRegXCSRbyte = CFV1_ByteRegs+CFV1_DRegXCSR, CFV1_DRegCSR2byte = CFV1_ByteRegs+CFV1_DRegCSR2, CFV1_DRegCSR3byte = CFV1_ByteRegs+CFV1_DRegCSR3
}
 

regNo Parameter for USBDM_ReadDReg() with CFV1 target

More...
enum  CFVx_DRegisters_t {
  CFVx_DRegCSR = 0x00, CFVx_DRegBAAR = 0x05, CFVx_DRegAATR = 0x06, CFVx_DRegTDR = 0x07,
  CFVx_DRegPBR0 = 0x08, CFVx_DRegPBMR = 0x09, CFVx_DRegABHR = 0x0C, CFVx_DRegABLR = 0x0D,
  CFVx_DRegDBR = 0x0E, CFVx_DRegBDMR = 0x0F, CFVx_DRegPBR1 = 0x18, CFVx_DRegPBR2 = 0x1A,
  CFVx_DRegPBR3 = 0x1B
}
 

regNo Parameter for USBDM_ReadDReg() with CFV1 target

More...
enum  JTAG_ExitActions_t {
  JTAG_STAY_SHIFT = 0, JTAG_EXIT_IDLE = 1, JTAG_EXIT_SHIFT_DR = 2, JTAG_EXIT_SHIFT_IR = 3 ,
  JTAG_WRITE_0 = 0x00, JTAG_WRITE_1 = 0x80 , JTAG_SHIFT_DR = 0, JTAG_SHIFT_IR = 1
}
 

Options used with JTAG commands.

More...
enum  ICP_ErrorCode_t { ICP_RC_OK = 0, ICP_RC_ILLEGAL = 1, ICP_RC_FLASH_ERR = 2, ICP_RC_VERIFY_ERR = 3 }
 

Error codes returned by JMxx BDM when in ICP mode.

More...
enum  InterfaceLevelMasks_t { ,
  SI_BKGD = (3<<SI_BKGD_OFF), SI_BKGD_LOW = (0<<SI_BKGD_OFF), SI_BKGD_HIGH = (1<<SI_BKGD_OFF), SI_BKGD_3STATE = (2<<SI_BKGD_OFF) ,
  SI_RESET = (3<<SI_RESET_OFF), SI_RESET_LOW = (0<<SI_RESET_OFF), SI_RESET_3STATE = (2<<SI_RESET_OFF) , SI_TA = (3<<SI_TA_OFF),
  SI_TA_LOW = (0<<SI_TA_OFF), SI_TA_3STATE = (2<<SI_TA_OFF) , SI_TRST = (3<<SI_TRST_OFF), SI_TRST_LOW = (0<<SI_TRST_OFF),
  SI_TRST_3STATE = (2<<SI_TRST_OFF) , SI_DISABLE = -1
}
 

Control signal masks for CMD_USBDM_CONTROL_INTERFACE.

More...
enum  PinLevelMasks_t { ,
  PIN_BKGD = (3<<PIN_BKGD_OFFS), PIN_BKGD_NC = (0<<PIN_BKGD_OFFS), PIN_BKGD_3STATE = (1<<PIN_BKGD_OFFS), PIN_BKGD_LOW = (2<<PIN_BKGD_OFFS),
  PIN_BKGD_HIGH = (3<<PIN_BKGD_OFFS) , PIN_RESET = (3<<PIN_RESET_OFFS), PIN_RESET_NC = (0<<PIN_RESET_OFFS), PIN_RESET_3STATE = (1<<PIN_RESET_OFFS),
  PIN_RESET_LOW = (2<<PIN_RESET_OFFS) , PIN_TA = (3<<PIN_TA_OFFS), PIN_TA_NC = (0<<PIN_TA_OFFS), PIN_TA_3STATE = (1<<PIN_TA_OFFS),
  PIN_TA_LOW = (2<<PIN_TA_OFFS) , PIN_DE = (3<<PIN_DE_OFFS), PIN_DE_NC = (0<<PIN_DE_OFFS), PIN_DE_3STATE = (1<<PIN_DE_OFFS),
  PIN_DE_LOW = (2<<PIN_DE_OFFS) , PIN_TRST = (3<<PIN_TRST_OFFS), PIN_TRST_NC = (0<<PIN_TRST_OFFS), PIN_TRST_3STATE = (1<<PIN_TRST_OFFS),
  PIN_TRST_LOW = (2<<PIN_TRST_OFFS) , PIN_BKPT = (3<<PIN_BKPT_OFFS), PIN_BKPT_NC = (0<<PIN_BKPT_OFFS), PIN_BKPT_3STATE = (1<<PIN_BKPT_OFFS),
  PIN_BKPT_LOW = (2<<PIN_BKPT_OFFS), PIN_RELEASE = -1
}
 

Control signal masks for CMD_USBDM_CONTROL_PIN.

More...

Functions

USBDM_API USBDM_ErrorCode USBDM_Init (void)
 Initialises USB interface.
USBDM_API USBDM_ErrorCode USBDM_Exit (void)
 Clean up.
USBDM_API unsigned int USBDM_DLLVersion (void)
 Get version of the DLL in BCD format.
USBDM_API const char * USBDM_DLLVersionString (void)
 Get version string for DLL.
USBDM_API const char * USBDM_GetErrorString (USBDM_ErrorCode errorCode)
 Gets string describing a USBDM error code.
USBDM_API USBDM_ErrorCode USBDM_FindDevices (unsigned int *deviceCount)
 Find USBDM Devices
This function creates an internal list of USBDM devices.
USBDM_API USBDM_ErrorCode USBDM_ReleaseDevices (void)
 Release USBDM Device list.
USBDM_API USBDM_ErrorCode USBDM_GetBDMSerialNumber (const char **deviceSerialNumber)
 Obtain serial number of the currently opened BDM.
USBDM_API USBDM_ErrorCode USBDM_GetBDMDescription (const char **deviceDescription)
 Obtain description of the currently opened BDM.
USBDM_API USBDM_ErrorCode USBDM_Open (unsigned char deviceNo)
 Opens a device.
USBDM_API USBDM_ErrorCode USBDM_Close (void)
 Closes currently open device.
USBDM_API USBDM_ErrorCode USBDM_GetVersion (USBDM_Version_t *version)
 Gets BDM software version and type of hardware.
USBDM_API USBDM_ErrorCode USBDM_GetCapabilities (HardwareCapabilities_t *capabilities)
 Obtains the Capability vector from the BDM interface.
USBDM_API USBDM_ErrorCode USBDM_GetBdmInformation (USBDM_bdmInformation_t *info)
 Obtains information about the currently open BDM interface.
USBDM_API USBDM_ErrorCode USBDM_SetOptions (BDM_Options_t *bdmOptions)
 Set BDM interface options.
USBDM_API USBDM_ErrorCode USBDM_SetTargetVdd (TargetVddSelect_t targetVdd)
 Sets Target Vdd voltage.
USBDM_API USBDM_ErrorCode USBDM_SetTargetVpp (TargetVppSelect_t targetVpp)
 Sets Target programming voltage.
USBDM_API USBDM_ErrorCode USBDM_ControlInterface (unsigned char duration_10us, unsigned int control)
 Directly manipulate interface levels.
USBDM_API USBDM_ErrorCode USBDM_ControlPins (unsigned int control, unsigned int *status)
 Directly manipulate interface levels.
USBDM_API USBDM_ErrorCode USBDM_SetTargetType (TargetType_t target_type)
 Sets target MCU type.
USBDM_API USBDM_ErrorCode USBDM_Debug (unsigned char *usb_data)
 Execute debug command (various, see DebugSubCommands)
USBDM_API USBDM_ErrorCode USBDM_GetCommandStatus (void)
 Get status of the last command.
USBDM_API USBDM_ErrorCode USBDM_GetBDMStatus (USBDMStatus_t *USBDMStatus)
 Fills user supplied structure with state of BDM communication channel.
USBDM_API USBDM_ErrorCode USBDM_Connect (void)
 Connects to Target.
USBDM_API USBDM_ErrorCode USBDM_SetSpeed (unsigned long frequency)
 Sets the BDM communication speed.
USBDM_API USBDM_ErrorCode USBDM_GetSpeed (unsigned long *frequency)
 Get the BDM communication speed in kHz.
USBDM_API USBDM_ErrorCode USBDM_GetSpeedHz (unsigned long *frequency)
 Get the BDM communication speed in Hz.
USBDM_API USBDM_ErrorCode USBDM_ReadStatusReg (unsigned long *BDMStatusReg)
 Reads Target Status register byte.
USBDM_API USBDM_ErrorCode USBDM_WriteControlReg (unsigned int value)
 Write Target Control Register byte.
USBDM_API USBDM_ErrorCode USBDM_TargetReset (TargetMode_t target_mode)
 Resets the target to normal or special mode.
USBDM_API USBDM_ErrorCode USBDM_TargetStep (void)
 Steps over a single target instruction.
USBDM_API USBDM_ErrorCode USBDM_TargetGo (void)
 Starts target execution from current PC address.
USBDM_API USBDM_ErrorCode USBDM_TargetHalt (void)
 Brings the target into active background mode.
USBDM_API USBDM_ErrorCode USBDM_WriteReg (unsigned int regNo, unsigned long regValue)
 Write Target Core register.
USBDM_API USBDM_ErrorCode USBDM_ReadReg (unsigned int regNo, unsigned long *regValue)
 Read Target Core register.
USBDM_API USBDM_ErrorCode USBDM_WriteCReg (unsigned int regNo, unsigned long regValue)
 Write Target Control register.
USBDM_API USBDM_ErrorCode USBDM_ReadCReg (unsigned int regNo, unsigned long *regValue)
 Read Target Control register.
USBDM_API USBDM_ErrorCode USBDM_WriteDReg (unsigned int regNo, unsigned long regValue)
 Write Target Debug register.
USBDM_API USBDM_ErrorCode USBDM_ReadDReg (unsigned int regNo, unsigned long *regValue)
 Read Target Debug register.
USBDM_API USBDM_ErrorCode USBDM_WriteMemory (unsigned int elementSize, unsigned int byteCount, unsigned int address, unsigned const char *data)
 Write data to target memory.
USBDM_API USBDM_ErrorCode USBDM_ReadMemory (unsigned int elementSize, unsigned int byteCount, unsigned int address, unsigned char *data)
 Read data from target memory.
USBDM_API USBDM_ErrorCode USBDM_JTAG_Reset (void)
 JTAG - Takes the TAP to TEST-LOGIC-RESET state TMS=11111, TDI=00000 or similar.
USBDM_API USBDM_ErrorCode USBDM_JTAG_SelectShift (unsigned char mode)
 JTAG - move the TAP to SHIFT-DR or SHIFT-IR state SHIFT_DR => TMS=100, TDI=0 (Actually TMS=0000_0100) SHIFT_IR => TMS=1100, TDI=0 (Actually TMS=0000_1100)
USBDM_API USBDM_ErrorCode USBDM_JTAG_Write (unsigned char bitCount, unsigned char exit, const unsigned char *buffer)
 JTAG - write data to JTAG shift register STAY_SHIFT => TMS=Nx0, TDI=NxData EXIT_SHIFT_DR => TMS=Nx0,11100 TDI=NxData,00000 EXIT_SHIFT_IR => TMS=Nx0,111100 TDI=NxData,000000 EXIT_IDLE => TMS=Nx0,10 TDI=NxData,00.
USBDM_API USBDM_ErrorCode USBDM_JTAG_Read (unsigned char bitCount, unsigned char exit, unsigned char *buffer)
 JTAG - read data from JTAG shift register SHIFT_DR => TMS=Nx0, TDI=0, TDO=NxData (captured)
USBDM_API USBDM_ErrorCode USBDM_JTAG_ReadWrite (unsigned char bitCount, unsigned char exit, const unsigned char *outBuffer, unsigned char *inBuffer)
 JTAG - read data from JTAG shift register SHIFT_DR => TMS=Nx0, TDI=0, TDO=NxData (captured)
USBDM_API USBDM_ErrorCode USBDM_JTAG_ExecuteSequence (unsigned char length, const unsigned char *sequence, unsigned char inLength, unsigned char *inBuffer)
 Execute JTAG Sequence.
USBDM_API void USBDM_RebootToICP (void)
 Set BDM for ICP mode & immediately reboots - used in BDM mode only.
USBDM_API ICP_ErrorCode_t USBDM_ICP_Erase (unsigned int addr, unsigned int count)
 ICP mode - erase BDM Flash memory.
USBDM_API ICP_ErrorCode_t USBDM_ICP_Program (unsigned int addr, unsigned int count, unsigned char *data)
 ICP mode - program BDM Flash memory.
USBDM_API ICP_ErrorCode_t USBDM_ICP_Verify (unsigned int addr, unsigned int count, unsigned char *data)
 ICP mode - verify BDM Flash memory.
USBDM_API void USBDM_ICP_Reboot (void)
 ICP mode - reboot.
USBDM_API void USBDM_ICP_SetCallback (icpCallBackT icpCallBack_)
 ICP mode - Set ICP Callback function.

Detailed Description

Header file for USBDM_API.c.

    Copyright (C) 2010  Peter O'Donoghue

    Based on material from OSBDM-JM60 Target Interface Software Package
    Copyright (C) 2009  Freescale

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

    Change History
   +====================================================================
   |    May 2010 | Created
   +====================================================================
    

Enumeration Type Documentation

enum AcknMode_t

Target supports ACKN or uses fixed delay {WAIT} instead.

Enumerator:
WAIT 
  • Use WAIT (delay) instead
ACKN 
  • Target supports ACKN feature and it is enabled

regNo Parameter for ARM_ReadCReg() with ARM target

Enumerator:
ARM_MDM_AP_Status 
ARM_MDM_AP_Control 
ARM_MDM_AP_Id 

regNo Parameter for USBDM_ReadReg() with ARM (Kinetis) target

Enumerator:
ARM_RegR0 
  • R0
ARM_RegR1 
  • R1
ARM_RegR2 
  • R2
ARM_RegR3 
  • R3
ARM_RegR4 
  • R4
ARM_RegR5 
  • R5
ARM_RegR6 
  • R6
ARM_RegR7 
  • R7
ARM_RegR8 
  • R8
ARM_RegR9 
  • R9
ARM_RegR10 
  • R10
ARM_RegR11 
  • R11
ARM_RegR12 
  • R12
ARM_RegSP 
  • SP
ARM_RegLR 
  • LR
ARM_RegPC 
  • PC (Debug return adderss)
ARM_RegxPSR 
  • xPSR
ARM_RegMSP 
  • Main Stack Ptr
ARM_RegPSP 
  • Process Stack Ptr
ARM_RegFPSCR 
ARM_RegFPS0 

Auto-reconnect options.

Enumerator:
AUTOCONNECT_NEVER 
  • Only connect explicitly
AUTOCONNECT_STATUS 
AUTOCONNECT_ALWAYS 
  • Reconnect before every command

regNo Parameter for USBDM_ReadCReg() with CFV1 target

Enumerator:
CFV1_CRegOTHER_A7 
  • Other A7 (not active in target)
CFV1_CRegVBR 
  • Vector Base register
CFV1_CRegCPUCR 
  • CPUCR
CFV1_CRegSR 
  • Status register
CFV1_CRegPC 
  • Program Counter

regNo Parameter for USBDM_ReadDReg() with CFV1 target

Note:
: There may be other registers
Enumerator:
CFV1_DRegCSR 
  • CSR
CFV1_DRegXCSR 
  • XCSR
CFV1_DRegCSR2 
  • CSR2
CFV1_DRegCSR3 
  • CSR3
CFV1_DRegBAAR 
  • BAAR
CFV1_DRegAATR 
  • AATR
CFV1_DRegTDR 
  • TDR
CFV1_DRegPBR0 
  • PBR0
CFV1_DRegPBMR 
  • PBMR - mask for PBR0
CFV1_DRegABHR 
  • ABHR
CFV1_DRegABLR 
  • ABLR
CFV1_DRegDBR 
  • DBR
CFV1_DRegBDMR 
  • DBMR - mask for DBR
CFV1_DRegPBR1 
  • PBR1
CFV1_DRegPBR2 
  • PBR2
CFV1_DRegPBR3 
  • PBR3
CFV1_DRegXCSRbyte 
  • XCSR.msb
CFV1_DRegCSR2byte 
  • CSR2.msb
CFV1_DRegCSR3byte 
  • CSR3.msb

regNo Parameter for USBDM_ReadReg() with CFV1 target

Enumerator:
CFV1_RegD0 
  • D0
CFV1_RegD1 
  • D1
CFV1_RegD2 
  • D2
CFV1_RegD3 
  • D3
CFV1_RegD4 
  • D4
CFV1_RegD5 
  • D5
CFV1_RegD6 
  • D6
CFV1_RegD7 
  • D7
CFV1_RegA0 
  • A0
CFV1_RegA1 
  • A1
CFV1_RegA2 
  • A2
CFV1_RegA3 
  • A3
CFV1_RegA4 
  • A4
CFV1_RegA5 
  • A5
CFV1_RegA6 
  • A6
CFV1_RegA7 
  • A7
CFV1_PSTBASE 
  • Start of PST registers, access as CFV1_PSTBASE+n

regNo Parameter for USBDM_ReadCReg() with CFVx target

Enumerator:
CFVx_CRegD0 
  • D0-D7
CFVx_CRegA0 
  • A0-A7
CFVx_CRegOTHER_SP 
  • Other A7 (not active in target)
CFVx_CRegVBR 
  • Vector Base register
CFVx_CRegSR 
  • Status Register
CFVx_CRegPC 
  • Program Counter
CFV1_CRegFLASHBAR 
  • Dlash Base register
CFV1_CRegRAMBAR 
  • RAM Base register

regNo Parameter for USBDM_ReadDReg() with CFV1 target

Enumerator:
CFVx_DRegCSR 
  • CSR
CFVx_DRegBAAR 
  • BAAR
CFVx_DRegAATR 
  • AATR
CFVx_DRegTDR 
  • TDR
CFVx_DRegPBR0 
  • PBR0
CFVx_DRegPBMR 
  • PBMR - mask for PBR0
CFVx_DRegABHR 
  • ABHR
CFVx_DRegABLR 
  • ABLR
CFVx_DRegDBR 
  • DBR
CFVx_DRegBDMR 
  • DBMR - mask for DBR
CFVx_DRegPBR1 
  • PBR1
CFVx_DRegPBR2 
  • PBR2
CFVx_DRegPBR3 
  • PBR3

regNo Parameter for USBDM_ReadReg() with CFVx target

Enumerator:
CFVx_RegD0 
  • D0
CFVx_RegD1 
  • D1
CFVx_RegD2 
  • D2
CFVx_RegD3 
  • D3
CFVx_RegD4 
  • D4
CFVx_RegD5 
  • D5
CFVx_RegD6 
  • D6
CFVx_RegD7 
  • D7
CFVx_RegA0 
  • A0
CFVx_RegA1 
  • A1
CFVx_RegA2 
  • A2
CFVx_RegA3 
  • A3
CFVx_RegA4 
  • A4
CFVx_RegA5 
  • A5
CFVx_RegA6 
  • A6
CFVx_RegA7 
  • A7

Target BDM Clock selection.

Enumerator:
CS_DEFAULT 
  • Use default clock selection (don't modify target's reset default)
CS_ALT_CLK 
  • Force ALT clock (CLKSW = 0)
CS_NORMAL_CLK 
  • Force Normal clock (CLKSW = 1)

Target RS08 microcontroller derivatives.

Enumerator:
KA1 
  • RS08KA1
KA2 
  • RS08KA2
LA8 
  • RS08LA8
KA4 
  • RS08KA4
KA8 
  • RS08KA8
LE4 
  • RS08LE4

Capabilities of the hardware.

Enumerator:
BDM_CAP_HCS12 
  • Supports HCS12
BDM_CAP_RS08 
  • 12 V Flash programming supply available (RS08 support)
BDM_CAP_VDDCONTROL 
  • Control over target Vdd
BDM_CAP_VDDSENSE 
  • Sensing of target Vdd
BDM_CAP_CFVx 
  • Support for CFV 1,2 & 3
BDM_CAP_HCS08 
  • Supports HCS08 targets - inverted when queried
BDM_CAP_CFV1 
  • Supports CFV1 targets - inverted when queried
BDM_CAP_JTAG 
  • Supports JTAG targets
BDM_CAP_DSC 
  • Supports DSC targets
BDM_CAP_ARM_JTAG 
  • Supports ARM targets via JTAG
BDM_CAP_RST 
  • Control & sensing of RESET
BDM_CAP_PST 
  • Supports PST signal sensing
BDM_CAP_CDC 
  • Supports CDC Serial over USB interface
BDM_CAP_ARM_SWD 
  • Supports ARM targets via SWD

regNo Parameter for USBDM_ReadDReg() with HCS08 target [BKPT reg]

Enumerator:
HCS08_DRegBKPT 
  • Breakpoint register

regNo Parameter for USBDM_ReadReg() with HCS08 target

Enumerator:
HCS08_RegPC 
  • PC reg
HCS08_RegSP 
  • SP reg
HCS08_RegHX 
  • HX reg
HCS08_RegA 
  • A reg
HCS08_RegCCR 
  • CCR reg

regNo Parameter for USBDM_ReadDReg() with HCS12 target [BD Space]

Note:
: There may be other registers
Enumerator:
HCS12_DRegBDMSTS 
  • BDMSTS (debug status/control) register
HCS12_DRegCCR 
  • Saved Target CCR
HCS12_DRegBDMINR 
  • BDM Internal Register Position Register

regNo Parameter for USBDM_ReadReg() with HCS12 target

Note:
CCR is accessed through USBDM_ReadDReg()
Enumerator:
HCS12_RegPC 
  • PC reg
HCS12_RegD 
  • D reg
HCS12_RegX 
  • X reg
HCS12_RegY 
  • Y reg
HCS12_RegSP 
  • SP reg
HCS12_RegCCR 

Error codes returned by JMxx BDM when in ICP mode.

Enumerator:
ICP_RC_OK 
  • No error
ICP_RC_ILLEGAL 
  • Illegal command or parameters
ICP_RC_FLASH_ERR 
  • Flash failed to program etc
ICP_RC_VERIFY_ERR 
  • Verify failed

Control signal masks for CMD_USBDM_CONTROL_INTERFACE.

Deprecated:
Enumerator:
SI_BKGD 
  • Mask for BKGD values (SI_BKGD_LOW, SI_BKGD_HIGH & SI_BKGD_3STATE)
SI_BKGD_LOW 
  • Set BKGD low
SI_BKGD_HIGH 
  • Set BKGD high
SI_BKGD_3STATE 
  • Set BKGD 3-state
SI_RESET 
  • Mask for RESET values (SI_RESET_LOW & SI_RESET_3STATE)
SI_RESET_LOW 
  • Set Reset low
SI_RESET_3STATE 
  • Set Reset 3-state
SI_TA 
  • Mask for TA signal (not implemented)
SI_TA_LOW 
  • Set TA low
SI_TA_3STATE 
  • Set TA 3-state
SI_TRST 
  • Mask for TRST signal (not implemented)
SI_TRST_LOW 
  • Set TRST low
SI_TRST_3STATE 
  • Set TRST 3-state
SI_DISABLE 
  • Release control (or use CMD_SET_TARGET)

Options used with JTAG commands.

Enumerator:
JTAG_STAY_SHIFT 
  • Remain in SHIFT-DR or SHIFT-IR
JTAG_EXIT_IDLE 
  • Exit SHIFT-XX to RUN-TEST/IDLE
JTAG_EXIT_SHIFT_DR 
  • Exit SHIFT-XX & enter SHIFT-DR w/o crossing RUN-TEST/IDLE
JTAG_EXIT_SHIFT_IR 
  • Exit SHIFT-XX & enter SHIFT-IR w/o crossing RUN-TEST/IDLE
JTAG_WRITE_0 
  • Write 0's when reading - combined with above
JTAG_WRITE_1 
  • Write 1's when reading - combined with above
JTAG_SHIFT_DR 
  • Enter SHIFT-DR (from TEST-LOGIC-RESET or RUN-TEST/IDLE)
JTAG_SHIFT_IR 
  • Enter SHIFT-IR (from TEST-LOGIC-RESET or RUN-TEST/IDLE)

Control signal masks for CMD_USBDM_CONTROL_PIN.

Enumerator:
PIN_BKGD 
  • Mask for BKGD values (PIN_BKGD_LOW, PIN_BKGD_HIGH & PIN_BKGD_3STATE)
PIN_BKGD_NC 
  • No change
PIN_BKGD_3STATE 
  • Set BKGD 3-state
PIN_BKGD_LOW 
  • Set BKGD low
PIN_BKGD_HIGH 
  • Set BKGD high
PIN_RESET 
  • Mask for RESET values (PIN_RESET_LOW & PIN_RESET_3STATE)
PIN_RESET_NC 
  • No change
PIN_RESET_3STATE 
  • Set Reset 3-state
PIN_RESET_LOW 
  • Set Reset low
PIN_TA 
  • Mask for TA signal
PIN_TA_NC 
  • No change
PIN_TA_3STATE 
  • Set TA 3-state
PIN_TA_LOW 
  • Set TA low
PIN_DE 
  • Mask for DE signal
PIN_DE_NC 
  • No change
PIN_DE_3STATE 
  • Set DE 3-state
PIN_DE_LOW 
  • Set DE low
PIN_TRST 
  • Mask for TRST signal (not implemented)
PIN_TRST_NC 
  • No change
PIN_TRST_3STATE 
  • Set TRST 3-state
PIN_TRST_LOW 
  • Set TRST low
PIN_BKPT 
  • Mask for BKPT signal
PIN_BKPT_NC 
  • No change
PIN_BKPT_3STATE 
  • Set BKPT 3-state
PIN_BKPT_LOW 
  • Set BKPT low
PIN_RELEASE 

Release all pins (go to default for current target)

Target reset status values.

Enumerator:
NO_RESET_ACTIVITY 
  • No reset activity since last polled
RESET_DETECTED 
  • Reset since last polled

Target RSTO state.

Enumerator:
RSTO_ACTIVE 
  • RSTO* is currently active [low]
RSTO_INACTIVE 
  • RSTO* is currently inactive [high]

regNo Parameter for USBDM_ReadDReg() with RS08 target (BKPT)

Enumerator:
RS08_DRegBKPT 
  • Breakpoint register

regNo Parameter for USBDM_ReadReg() with RS08 target

Enumerator:
RS08_RegCCR_PC 
  • Combined CCR/PC register
RS08_RegSPC 
  • Shadow PC
RS08_RegA 
  • A reg

Target speed selection.

Enumerator:
SPEED_NO_INFO 
  • Not connected
SPEED_SYNC 
  • Speed determined by SYNC
SPEED_GUESSED 
  • Speed determined by trial & error
SPEED_USER_SUPPLIED 
  • User has specified the speed to use

Reset mode as used by CMD_USBDM_TARGET_RESET.

Enumerator:
RESET_MODE_MASK 

Mask for reset mode (SPECIAL/NORMAL)

RESET_SPECIAL 
  • Special mode [BDM active, Target halted]
RESET_NORMAL 
  • Normal mode [usual reset, Target executes]
RESET_TYPE_MASK 

Mask for reset type (Hardware/Software/Power)

RESET_ALL 

Use all reset strategies as appropriate.

RESET_HARDWARE 

Use hardware RESET pin reset.

RESET_SOFTWARE 

Use software (BDM commands) reset.

RESET_POWER 

Cycle power.

Target Halt state.

Enumerator:
TARGET_RUNNING 
  • CFVx target running (ALLPST == 0)
TARGET_HALTED 
  • CFVx target halted (ALLPST == 1)

Target microcontroller types.

Enumerator:
T_HC12 
  • HC12 or HCS12 target
T_HCS08 
  • HCS08 target
T_RS08 
  • RS08 target
T_CFV1 
  • Coldfire Version 1 target
T_CFVx 
  • Coldfire Version 2,3,4 target
T_JTAG 
  • JTAG target - TAP is set to RUN-TEST/IDLE
T_EZFLASH 
  • EzPort Flash interface (SPI?)
T_MC56F80xx 
  • JTAG target with MC56F80xx optimised subroutines
T_ARM_JTAG 
  • ARM target using JTAG
T_OFF 
  • Turn off interface (no target)

Internal Target Voltage supply selection.

Enumerator:
BDM_TARGET_VDD_OFF 
  • Target Vdd Off
BDM_TARGET_VDD_3V3 
  • Target Vdd internal 3.3V
BDM_TARGET_VDD_5V 
  • Target Vdd internal 5.0V
BDM_TARGET_VDD_ENABLE 
  • Target Vdd internal at last set level
BDM_TARGET_VDD_DISABLE 
  • Target Vdd Off but previously set level unchanged

Target Voltage supply state.

Enumerator:
BDM_TARGET_VDD_NONE 
  • Target Vdd not detected
BDM_TARGET_VDD_EXT 
  • Target Vdd external
BDM_TARGET_VDD_INT 
  • Target Vdd internal
BDM_TARGET_VDD_ERR 
  • Target Vdd error

Internal Programming Voltage supply selection.

Enumerator:
BDM_TARGET_VPP_OFF 
  • Target Vpp Off
BDM_TARGET_VPP_STANDBY 
  • Target Vpp Standby (Inverter on, Vpp off)
BDM_TARGET_VPP_ON 
  • Target Vpp On
BDM_TARGET_VPP_ERROR 
  • Target Vpp ??

Error codes returned from BDM routines and BDM commands.

Enumerator:
BDM_RC_OK 
  • No error
BDM_RC_ILLEGAL_PARAMS 
  • Illegal parameters to command
BDM_RC_FAIL 
  • General Fail
BDM_RC_BUSY 
  • Busy with last command - try again - don't change
BDM_RC_ILLEGAL_COMMAND 
  • Illegal (unknown) command (may be in wrong target mode)
BDM_RC_NO_CONNECTION 
  • No connection to target
BDM_RC_OVERRUN 
  • New command before previous command completed
BDM_RC_CF_ILLEGAL_COMMAND 
  • Coldfire BDM interface did not recognize the command
BDM_RC_UNKNOWN_TARGET 
  • Target not supported
BDM_RC_NO_TX_ROUTINE 
  • No Tx routine available at measured BDM communication speed
BDM_RC_NO_RX_ROUTINE 
  • No Rx routine available at measured BDM communication speed
BDM_RC_BDM_EN_FAILED 
  • Failed to enable BDM mode in target (warning)
BDM_RC_RESET_TIMEOUT_FALL 
  • RESET signal failed to fall
BDM_RC_BKGD_TIMEOUT 
  • BKGD signal failed to rise/fall
BDM_RC_SYNC_TIMEOUT 
  • No response to SYNC sequence
BDM_RC_UNKNOWN_SPEED 
  • Communication speed is not known or cannot be determined
BDM_RC_WRONG_PROGRAMMING_MODE 
  • Attempted Flash programming when in wrong mode (e.g. Vpp off)
BDM_RC_FLASH_PROGRAMING_BUSY 
  • Busy with last Flash programming command
BDM_RC_VDD_NOT_REMOVED 
  • Target Vdd failed to fall
BDM_RC_VDD_NOT_PRESENT 
  • Target Vdd not present/failed to rise
BDM_RC_VDD_WRONG_MODE 
  • Attempt to cycle target Vdd when not controlled by BDM interface
BDM_RC_CF_BUS_ERROR 
  • Illegal bus cycle on target (Coldfire)
BDM_RC_USB_ERROR 
  • Indicates USB transfer failed (returned by driver not BDM)
BDM_RC_ACK_TIMEOUT 
  • Indicates an expected ACK was missing
BDM_RC_FAILED_TRIM 
  • Trimming of target clock failed (out of clock range?).
BDM_RC_FEATURE_NOT_SUPPORTED 
  • Feature not supported by this version of hardware/firmware
BDM_RC_RESET_TIMEOUT_RISE 
  • RESET signal failed to rise
BDM_RC_WRONG_BDM_REVISION 
  • BDM Hardware is incompatible with driver/program
BDM_RC_WRONG_DLL_REVISION 
  • Program is incompatible with DLL
BDM_RC_NO_USBDM_DEVICE 
  • No usbdm device was located
BDM_RC_JTAG_UNMATCHED_REPEAT 
  • Unmatched REPEAT-END_REPEAT
BDM_RC_JTAG_UNMATCHED_RETURN 
  • Unmatched CALL-RETURN
BDM_RC_JTAG_UNMATCHED_IF 
  • Unmatched IF-END_IF
BDM_RC_JTAG_STACK_ERROR 
  • Underflow in call/return sequence, unmatched REPEAT etc.
BDM_RC_JTAG_ILLEGAL_SEQUENCE 
  • Illegal JTAG sequence
BDM_RC_TARGET_BUSY 
  • Target is busy (executing?)
BDM_RC_JTAG_TOO_LARGE 
  • Subroutine is too large to cache
BDM_RC_DEVICE_NOT_OPEN 
  • USBDM Device has not been opened
BDM_RC_UNKNOWN_DEVICE 
  • Device is not in database
BDM_RC_DEVICE_DATABASE_ERROR 
  • Device database not found or failed to open/parse
BDM_RC_ARM_PWR_UP_FAIL 
  • ARM System power failed
BDM_RC_ARM_ACCESS_ERROR 
  • ARM Access error
BDM_JTAG_TOO_MANY_DEVICES 
  • JTAG chain is too long (or greater than 1!)
BDM_RC_SECURED 
  • ARM Device is secured (& operation failed?)

Function Documentation

USBDM_API USBDM_ErrorCode USBDM_Close ( void  )

Closes currently open device.

Returns:

BDM_RC_OK => OK
USBDM_API USBDM_ErrorCode USBDM_Connect ( void  )

Connects to Target.

This will cause the BDM module to attempt to connect to the Target. In most cases the BDM module will automatically determine the connection speed and successfully connect. If unsuccessful, it may be necessary to manually set the speed using set_speed().

Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_ControlInterface ( unsigned char  duration_10us,
unsigned int  control 
)

Directly manipulate interface levels.

Parameters:
control=> mask indicating interface levels see InterfaceLevelMasks_t
duration_10us=> time (in 10us ticks) to assert level (0 = indefinite)
Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
Note:
- Only partially implemented in BDM firmware
Deprecated:
USBDM_API USBDM_ErrorCode USBDM_ControlPins ( unsigned int  control,
unsigned int *  status 
)

Directly manipulate interface levels.

Parameters:
control=> mask indicating interface levels see PinLevelMasks_t
status=> currently unused
Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
Note:
- Only partially implemented in BDM firmware
USBDM_API USBDM_ErrorCode USBDM_Debug ( unsigned char *  usb_data)

Execute debug command (various, see DebugSubCommands)

Parameters:
usb_data- Command for BDM
Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
USBDM_API unsigned int USBDM_DLLVersion ( void  )

Get version of the DLL in BCD format.

Returns:
8-bit version number (2 BCD digits, major-minor)
USBDM_API const char* USBDM_DLLVersionString ( void  )

Get version string for DLL.

Returns:
ptr to static ASCII string
USBDM_API USBDM_ErrorCode USBDM_Exit ( void  )

Clean up.

This must be called after all USBDM operations are finished

Returns:

BDM_RC_OK => OK
other => USB Error - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_FindDevices ( unsigned int *  deviceCount)

Find USBDM Devices
This function creates an internal list of USBDM devices.

The list is held until USBDM_ReleaseDevices() is called.
USBDM_FindDevices() must be done before any device may be opened.

Parameters:
deviceCountNumber of BDM devices found
Returns:

BDM_RC_OK => OK
BDM_RC_NO_USBDM_DEVICE => No devices found. other => other Error - see USBDM_ErrorCode
Note:
deviceCount == 0 on any error so may be used w/o checking rc
The device list is held until USBDM_ReleaseDevices() is called
USBDM_API USBDM_ErrorCode USBDM_GetBDMDescription ( const char **  deviceDescription)

Obtain description of the currently opened BDM.

Parameters:
deviceDescriptionUpdated to point to UTF-16LE device description
Returns:

== BDM_RC_OK (0) => Success
== BDM_RC_USB_ERROR => USB failure
Note:
deviceDescription points at a statically allocated buffer - do not free
USBDM_API USBDM_ErrorCode USBDM_GetBdmInformation ( USBDM_bdmInformation_t info)

Obtains information about the currently open BDM interface.

Parameters:
infoptr to structure to contain the information
Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
Note:
The size element of info should be initialised before call.
Uses cached information from when the BDM was opened.
USBDM_API USBDM_ErrorCode USBDM_GetBDMSerialNumber ( const char **  deviceSerialNumber)

Obtain serial number of the currently opened BDM.

Parameters:
deviceSerialNumberUpdated to point to UTF-16LE serial number
Returns:

== BDM_RC_OK (0) => Success
== BDM_RC_USB_ERROR => USB failure
Note:
deviceDescription points at a statically allocated buffer - do not free
USBDM_API USBDM_ErrorCode USBDM_GetBDMStatus ( USBDMStatus_t USBDMStatus)

Fills user supplied structure with state of BDM communication channel.

Parameters:
USBDMStatusPointer to structure to receive status, see USBDMStatus_t
Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_GetCapabilities ( HardwareCapabilities_t capabilities)

Obtains the Capability vector from the BDM interface.

Parameters:
capabilities: ptr to where to return capability vector see HardwareCapabilities_t
Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
Deprecated:
: use USBDM_GetBdmInformation()
USBDM_API USBDM_ErrorCode USBDM_GetCommandStatus ( void  )

Get status of the last command.

Returns:

BDM_RC_OK => OK
BDM_RC_USB_ERROR => USB failure
other => Error code - see USBDM_ErrorCode
USBDM_API const char* USBDM_GetErrorString ( USBDM_ErrorCode  errorCode)

Gets string describing a USBDM error code.

Parameters:
errorCode- error code returned from USBDM API routine.
Returns:
- ptr to static string describing the error.
USBDM_API USBDM_ErrorCode USBDM_GetSpeed ( unsigned long *  frequency)

Get the BDM communication speed in kHz.

Parameters:
frequency=> BDM Communication speed in kHz
Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_GetSpeedHz ( unsigned long *  frequency)

Get the BDM communication speed in Hz.

Parameters:
frequency=> BDM Communication speed in Hz
Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_GetVersion ( USBDM_Version_t version)

Gets BDM software version and type of hardware.

Parameters:
versionVersion numbers (4 bytes)

  • USBDM software version
  • USBDM hardware type
  • ICP software version
  • ICP hardware type
    USBDM & ICP hardware versions should always agree
Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
Note:
- This command is directed to EP0 and is also allowed in ICP mode
Deprecated:
: use USBDM_GetBdmInformation()
USBDM_API ICP_ErrorCode_t USBDM_ICP_Erase ( unsigned int  addr,
unsigned int  count 
)

ICP mode - erase BDM Flash memory.

Parameters:
addr32-bit memory address
countnumber of bytes to erase
Returns:
Note:
Flash memory alignment requirements should be taken into account. The range erased should be a multiple of the Flash erase block size.
USBDM_API ICP_ErrorCode_t USBDM_ICP_Program ( unsigned int  addr,
unsigned int  count,
unsigned char *  data 
)

ICP mode - program BDM Flash memory.

Parameters:
addr32-bit memory address
countnumber of bytes to program
dataPointer to buffer containing data
Returns:
USBDM_API void USBDM_ICP_Reboot ( void  )

ICP mode - reboot.

The BDM does a normal reset

Used in ICP mode to reset to normal (BDM) mode.

Note:
Communication is lost.
The BDM will do the usual flash validity checks before entering BDM mode so if flash is not correctly programmed the BDM may remain in ICP mode.
USBDM_API void USBDM_ICP_SetCallback ( icpCallBackT  icpCallBack_)

ICP mode - Set ICP Callback function.

Parameters:
icpCallBack_callback function used to indicate progress
Returns:
  • == ICP_RC_OK => success
Note:
The callback is cleared after each ICP operation completes
USBDM_API ICP_ErrorCode_t USBDM_ICP_Verify ( unsigned int  addr,
unsigned int  count,
unsigned char *  data 
)

ICP mode - verify BDM Flash memory.

Parameters:
addr32-bit memory address
countnumber of bytes to verify
dataPointer to buffer containing data
Returns:
USBDM_API USBDM_ErrorCode USBDM_Init ( void  )

Initialises USB interface.

This must be done before any other operations.

Returns:

BDM_RC_OK => OK
other => USB Error - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_JTAG_ExecuteSequence ( unsigned char  length,
const unsigned char *  sequence,
unsigned char  inLength,
unsigned char *  inBuffer 
)

Execute JTAG Sequence.

Parameters:
length- JTAG sequence length.
sequence- Pointer to sequence.
inLength- Expected length of input data
inBuffer- Returned values
Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_JTAG_Read ( unsigned char  bitCount,
unsigned char  exit,
unsigned char *  buffer 
)

JTAG - read data from JTAG shift register SHIFT_DR => TMS=Nx0, TDI=0, TDO=NxData (captured)

Parameters:
exitaction after shift, see JTAG_ExitActions_t

  • JTAG_STAY_SHIFT - Remain in SHIFT-DR or SHIFT-IR
  • JTAG_EXIT_IDLE - Exit SHIFT-XX to RUN-TEST/IDLE
  • JTAG_EXIT_SHIFT_DR - Exit SHIFT-XX & enter SHIFT-DR w/o crossing RUN-TEST/IDLE
  • JTAG_EXIT_SHIFT_IR - Exit SHIFT-XX & enter SHIFT-IR w/o crossing RUN-TEST/IDLE
  • +JTAG_WRITE_0 - Write 0's when reading - combined with one of above
  • +JTAG_WRITE_1 - Write 1's when reading - combined with one of above
bitCount8-bit count of bits to shift in. [>0]
It is not possible to do 0 bits.
bufferPointer to buffer for data read out of the device (first bit in LSB of the last byte in the buffer)
Note:
Requires the tap to be in SHIFT-DR or SHIFT-IR state.
Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_JTAG_ReadWrite ( unsigned char  bitCount,
unsigned char  exit,
const unsigned char *  outBuffer,
unsigned char *  inBuffer 
)

JTAG - read data from JTAG shift register SHIFT_DR => TMS=Nx0, TDI=0, TDO=NxData (captured)

Parameters:
exitaction after shift, see JTAG_ExitActions_t

  • JTAG_STAY_SHIFT - Remain in SHIFT-DR or SHIFT-IR
  • JTAG_EXIT_IDLE - Exit SHIFT-XX to RUN-TEST/IDLE
  • JTAG_EXIT_SHIFT_DR - Exit SHIFT-XX & enter SHIFT-DR w/o crossing RUN-TEST/IDLE
  • JTAG_EXIT_SHIFT_IR - Exit SHIFT-XX & enter SHIFT-IR w/o crossing RUN-TEST/IDLE
  • +JTAG_WRITE_0 - Write 0's when reading - combined with one of above
  • +JTAG_WRITE_1 - Write 1's when reading - combined with one of above
bitCount8-bit count of bits to shift in. [>0]
It is not possible to do 0 bits.
inBufferPointer to buffer for data written to the device (first bit in LSB of the last byte in the buffer)
outBufferPointer to buffer for data read out of the device (first bit in LSB of the last byte in the buffer)
Note:
Requires the tap to be in SHIFT-DR or SHIFT-IR state.
inbuffer and outbuffer may be the same location
Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_JTAG_Reset ( void  )

JTAG - Takes the TAP to TEST-LOGIC-RESET state TMS=11111, TDI=00000 or similar.

Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_JTAG_SelectShift ( unsigned char  mode)

JTAG - move the TAP to SHIFT-DR or SHIFT-IR state SHIFT_DR => TMS=100, TDI=0 (Actually TMS=0000_0100) SHIFT_IR => TMS=1100, TDI=0 (Actually TMS=0000_1100)

Parameters:
modeAction, ref JTAG_ExitActions_t

  • SHIFT_DR - Enter SHIFT-DR
  • SHIFT_IR - Enter SHIFT-IR
Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
Note:
- Requires the tap to be initially in TEST-LOGIC-RESET or RUN-TEST/IDLE
USBDM_API USBDM_ErrorCode USBDM_JTAG_Write ( unsigned char  bitCount,
unsigned char  exit,
const unsigned char *  buffer 
)

JTAG - write data to JTAG shift register STAY_SHIFT => TMS=Nx0, TDI=NxData EXIT_SHIFT_DR => TMS=Nx0,11100 TDI=NxData,00000 EXIT_SHIFT_IR => TMS=Nx0,111100 TDI=NxData,000000 EXIT_IDLE => TMS=Nx0,10 TDI=NxData,00.

Parameters:
exitaction after shift, see JTAG_ExitActions_t

  • JTAG_STAY_SHIFT - Remain in SHIFT-DR or SHIFT-IR
  • JTAG_EXIT_IDLE - Exit SHIFT-XX to RUN-TEST/IDLE
  • JTAG_EXIT_SHIFT_DR - Exit SHIFT-XX & enter SHIFT-DR w/o crossing RUN-TEST/IDLE
  • JTAG_EXIT_SHIFT_IR - Exit SHIFT-XX & enter SHIFT-IR w/o crossing RUN-TEST/IDLE
bitCount8-bit count of bits to shift in. [>0]
It is not possible to do 0 bits.
bufferPointer to data buffer. The data is shifted in LSB (last byte) first, unused bits (if any) are in the MSB (first) byte;
Note:
Requires the tap to be in SHIFT-DR or SHIFT-IR state.
Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_Open ( unsigned char  deviceNo)

Opens a device.

Parameters:
deviceNoNumber (0..N) of device to open. A device must be open before any communication with the device can take place.
Note:
The range of device numbers must be obtained from USBDM_FindDevices() before calling this function.
Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_ReadCReg ( unsigned int  regNo,
unsigned long *  regValue 
)

Read Target Control register.

Parameters:
regNoRegister #

regValue8/16/32-bit value
Returns:
error code
BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_ReadDReg ( unsigned int  regNo,
unsigned long *  regValue 
)

Read Target Debug register.

Parameters:
regNoRegister #

regValue8/16/32-bit value
Returns:
error code
BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_ReadMemory ( unsigned int  elementSize,
unsigned int  byteCount,
unsigned int  address,
unsigned char *  data 
)

Read data from target memory.

Parameters:
elementSize= Size of data (1/2/4 bytes)
byteCount= Number of bytes to transfer
address= Memory address
data= Where to place data
Returns:
error code
BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_ReadReg ( unsigned int  regNo,
unsigned long *  regValue 
)

Read Target Core register.

Parameters:
regNoRegister #

regValue8/16/32-bit value
Returns:
error code
BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
Note:
HCS12_RegCCR is accessed through USBDM_ReadDReg()
USBDM_API USBDM_ErrorCode USBDM_ReadStatusReg ( unsigned long *  BDMStatusReg)

Reads Target Status register byte.

Parameters:
BDMStatusReg=> status register value read.
The register read depends on target:

  • HCS12 = BDMSTS, BDM Status register
  • HCS08 = BDCSCR, BDM Status & Control register
  • RS08 = BDCSCR, BDM Status & Control register
  • CFV1 = XCSR[31..24], Extended Configuration/Status Register
  • CFVx = CSR, Configuration/Status Register (CSR)
Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
Note:

The BDM may resynchronize with the target before doing this read.
USBDM_API void USBDM_RebootToICP ( void  )

Set BDM for ICP mode & immediately reboots - used in BDM mode only.

The BDM resets in ICP mode after this command

Note:
Communication is lost.
USBDM_API USBDM_ErrorCode USBDM_ReleaseDevices ( void  )

Release USBDM Device list.

Returns:

BDM_RC_OK => OK
other => USB Error - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_SetOptions ( BDM_Options_t bdmOptions)

Set BDM interface options.

Parameters:
bdmOptions: Options to pass to BDM interface
Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_SetSpeed ( unsigned long  frequency)

Sets the BDM communication speed.

Parameters:
frequency=> BDM Communication speed in kHz

  • T_CFVx, T_JTAG, T_MC56F80xx : JTAG clock frequency
  • RS08, HCS08, HCS12, CFV1 : BDM interface frequency
    Usually equal to the CPU Bus frequency.
    May be unrelated to bus speed if alternative BDM clock is in use.
    A value of zero causes a connect sequence instead i.e. automatically try to determine connection speed.
Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_SetTargetType ( TargetType_t  target_type)

Sets target MCU type.

Parameters:
target_typetype of target
Returns:
0 => Success,
!=0 => Fail

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_SetTargetVdd ( TargetVddSelect_t  targetVdd)

Sets Target Vdd voltage.

Parameters:
targetVdd=> control value for Vdd
Returns:

BDM_RC_OK => OK
else => Various errors
USBDM_API USBDM_ErrorCode USBDM_SetTargetVpp ( TargetVppSelect_t  targetVpp)

Sets Target programming voltage.

Parameters:
targetVpp=> control value for Vpp
Note:
Before enabling target Vpp it is necessary to do the following:
  • Target device must be set to T_RS08
  • Target Vdd must be present (internally or externally)
  • The Target Vpp must be first set to BDM_TARGET_VPP_STANDBY then BDM_TARGET_VPP_ON
    The above is checked by the BDM firmware
Returns:

BDM_RC_OK => OK
else => Various errors
USBDM_API USBDM_ErrorCode USBDM_TargetGo ( void  )

Starts target execution from current PC address.

Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_TargetHalt ( void  )

Brings the target into active background mode.

The target will be halted.

Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_TargetReset ( TargetMode_t  target_mode)

Resets the target to normal or special mode.

Parameters:
target_modesee
Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
Note:
V4.4 onwards - Communication with the target is lost. It is necessary to use USBDM_Connect() to re-connect. This is no longer done automatically as it may interfere with security checking if attempted too soon after reset.
USBDM_API USBDM_ErrorCode USBDM_TargetStep ( void  )

Steps over a single target instruction.

Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_WriteControlReg ( unsigned int  value)

Write Target Control Register byte.

Parameters:
value=> value to write The register written depends on target:

  • HCS12 = BDMSTS, BDM Status register
  • HCS08 = BDCSCR, BDM Status & Control register
  • RS08 = BDCSCR, BDM Status & Control register
  • CFV1 = XCSR[31..24], Extended Configuration/Status Register
  • CFVx not supported (Access CSR through writeControlReg())
Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_WriteCReg ( unsigned int  regNo,
unsigned long  regValue 
)

Write Target Control register.

Parameters:
regNoRegister #

regValue8/16/32-bit value
Returns:
error code
BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_WriteDReg ( unsigned int  regNo,
unsigned long  regValue 
)

Write Target Debug register.

Parameters:
regNoRegister #

regValue8/16/32-bit value
Returns:
error code
BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_WriteMemory ( unsigned int  elementSize,
unsigned int  byteCount,
unsigned int  address,
unsigned const char *  data 
)

Write data to target memory.

Parameters:
elementSize= Size of data elements (1/2/4 bytes)
byteCount= Number of _bytes_ to transfer
address= Memory address
data= Ptr to block of data to write
Returns:
error code
BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
USBDM_API USBDM_ErrorCode USBDM_WriteReg ( unsigned int  regNo,
unsigned long  regValue 
)

Write Target Core register.

Parameters:
regNoRegister #

regValue8/16/32-bit value
Returns:
error code
BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode