USBDM/CF (JMxx Version) V4.9.5
Data Structures | Defines | Typedefs | Enumerations | Functions

USBDM_API.h File Reference

Header file for USBDM_API.c. More...

#include <stdint.h>
#include "USBDM_ErrorMessages.h"

Data Structures

struct  USBDMStatus_t
 State of BDM Communication. More...
struct  BDM_Options_t
 BDM interface options. More...
struct  USBDM_ExtendedOptions_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...

Defines

#define bool   int
 Define bool for C.
#define USBDM_API_VERSION   (40905)
 USBDM Version this header describes.
#define CAP_HCS12   (1<<0)
 Supports HCS12 targets.
#define CAP_RS08   (1<<1)
 Supports RS08 targets.
#define CAP_VDDCONTROL   (1<<2)
 Control over target Vdd.
#define CAP_VDDSENSE   (1<<3)
 Sensing of target Vdd.
#define CAP_CFVx   (1<<4)
 Supports CFVx.
#define CAP_HCS08   (1<<5)
 Supports HCS08 targets - inverted when queried.
#define CAP_CFV1   (1<<6)
 Supports CFV1 targets - inverted when queried.
#define CAP_JTAG   (1<<7)
 Supports JTAG targets.
#define CAP_DSC   (1<<8)
 Supports DSC targets.
#define CAP_ARM_JTAG   (1<<9)
 Supports ARM targets via JTAG.
#define CAP_RST   (1<<10)
 Control & sensing of RESET.
#define CAP_PST   (1<<11)
 Supports PST signal sensing.
#define CAP_CDC   (1<<12)
 Supports CDC Serial over USB interface.
#define CAP_ARM_SWD   (1<<13)
 Supports ARM targets via SWD.

Typedefs

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

Enumerations

enum  HardwareCapabilities_t {
  BDM_CAP_NONE = (0), BDM_CAP_ALL = (0xFFFF), 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_HCS12 = T_HC12, 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_LAST = T_ARM_JTAG, 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  MemorySpace_t {
  MS_Byte = 1, MS_Word = 2, MS_Long = 4, MS_None = 0<<4,
  MS_Program = 1<<4, MS_Data = 2<<4, MS_Global = 3<<4, MS_SIZE = 0x7<<0,
  MS_SPACE = 0x7<<4, MS_PWord = MS_Word+MS_Program, MS_PLong = MS_Long+MS_Program, MS_XByte = MS_Byte+MS_Data,
  MS_XWord = MS_Word+MS_Data, MS_XLong = MS_Long+MS_Data
}
 

Memory space indicator - includes element size.


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_INACTIVE = NO_RESET_ACTIVITY, 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_METHOD_MASK = (7<<2),
  RESET_ALL = (0<<2), RESET_HARDWARE = (1<<2), RESET_SOFTWARE = (2<<2), RESET_POWER = (3<<2),
  RESET_DEFAULT = (7<<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_RegMISC = 20,
  ARM_RegFPSCR = 0x21, ARM_RegFPS0 = 0x40
}
 

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

More...
enum  DSC_Registers_t {
  DSC_RegX0, DSC_FirstCoreRegister = DSC_RegX0, DSC_RegY0, DSC_RegY1,
  DSC_RegA0, DSC_RegA1, DSC_RegA2, DSC_RegB0,
  DSC_RegB1, DSC_RegB2, DSC_RegC0, DSC_RegC1,
  DSC_RegC2, DSC_RegD0, DSC_RegD1, DSC_RegD2,
  DSC_RegOMR, DSC_RegSR, DSC_RegLA, DSC_RegLA2,
  DSC_RegLC, DSC_RegLC2, DSC_RegHWS0, DSC_RegHWS1,
  DSC_RegSP, DSC_RegN3, DSC_RegM01, DSC_RegN,
  DSC_RegR0, DSC_RegR1, DSC_RegR2, DSC_RegR3,
  DSC_RegR4, DSC_RegR5, DSC_RegsHM01, DSC_RegsHN,
  DSC_RegsHR0, DSC_RegsHR1, DSC_RegPC, DSC_LastCoreRegister = DSC_RegPC,
  DSC_RegIDCODE, DSC_RegOCR, DSC_FirstONCERegister = DSC_RegOCR, DSC_RegOSCNTR,
  DSC_RegOSR, DSC_RegOPDBR, DSC_RegOBASE, DSC_RegOTXRXSR,
  DSC_RegOTX, DSC_RegOTX1, DSC_RegORX, DSC_RegORX1,
  DSC_RegOTBCR, DSC_RegOTBPR, DSC_RegOTB, DSC_RegOB0CR,
  DSC_RegOB0AR1, DSC_RegOB0AR2, DSC_RegOB0MSK, DSC_RegOB0CNTR,
  DSC_LastONCERegister = DSC_RegOB0CNTR, DSC_GdiStatus = 0x1001, DSC_UnknownReg = 0xFFFFFF
}
 

regNo Parameter for DSC_ReadReg() with DSC target DSC Core registers


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_CRegD1, CFVx_CRegD2, CFVx_CRegD3,
  CFVx_CRegD4, CFVx_CRegD5, CFVx_CRegD6, CFVx_CRegD7,
  CFVx_CRegA0, CFVx_CRegA1, CFVx_CRegA2, CFVx_CRegA3,
  CFVx_CRegA4, CFVx_CRegA5, CFVx_CRegA6, CFVx_CRegUSER_SP,
  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


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_ByteRegs = 0x1000, 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_EXIT_ACTION_MASK = 0x3, JTAG_WRITE_0 = 0x00, JTAG_WRITE_1 = 0x80, JTAG_WRITE_MASK = 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_OFF = (0), 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_BKGD_NONE = (3<<SI_BKGD_OFF), SI_RESET_OFF = (2), SI_RESET = (3<<SI_RESET_OFF),
  SI_RESET_LOW = (0<<SI_RESET_OFF), SI_RESET_3STATE = (2<<SI_RESET_OFF), SI_RESET_NONE = (3<<SI_RESET_OFF), SI_TA_OFF = (4),
  SI_TA = (3<<SI_TA_OFF), SI_TA_LOW = (0<<SI_TA_OFF), SI_TA_3STATE = (2<<SI_TA_OFF), SI_TC_NONE = (3<<SI_TA_OFF),
  SI_TRST_OFF = (6), SI_TRST = (3<<SI_TRST_OFF), SI_TRST_LOW = (0<<SI_TRST_OFF), SI_TRST_3STATE = (2<<SI_TRST_OFF),
  SI_TRST_NONE = (3<<SI_TRST_OFF), SI_DISABLE = -1
}
 

Control signal masks for CMD_USBDM_CONTROL_INTERFACE.

More...
enum  PinLevelMasks_t {
  PIN_BKGD_OFFS = (0), 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_OFFS = (2), 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_OFFS = (4),
  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_OFFS = (4), 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_OFFS = (6), 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_OFFS = (8), 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_NOCHANGE = 0,
  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.
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_GetDefaultExtendedOptions (USBDM_ExtendedOptions_t *currentBdmOptions)
 Get default (target specific) BDM interface options.
USBDM_API USBDM_ErrorCode USBDM_SetExtendedOptions (const USBDM_ExtendedOptions_t *bdmOptions)
 Set BDM interface options.
USBDM_API USBDM_ErrorCode USBDM_GetExtendedOptions (USBDM_ExtendedOptions_t *currentBdmOptions)
 Get 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.

enum ARM_Registers_t

regNo Parameter for ARM_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.

enum AutoConnect_t

Auto-reconnect options.

Enumerator:
AUTOCONNECT_NEVER 

Only connect explicitly.

AUTOCONNECT_STATUS 

Reconnect on USBDM_ReadStatusReg()

AUTOCONNECT_ALWAYS 

Reconnect before every command.

enum CFV1_CRegisters_t

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.

enum CFV1_DRegisters_t

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.

enum CFV1_Registers_t

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.

enum CFVx_CRegisters_t

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.

enum CFVx_DRegisters_t

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.

enum CFVx_Registers_t

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.

enum ClkSwValues_t

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)

enum DerivativeType_t

Target RS08 microcontroller derivatives.

Enumerator:
KA1 

RS08KA1.

KA2 

RS08KA2.

LA8 

RS08LA8.

KA4 

RS08KA4.

KA8 

RS08KA8.

LE4 

RS08LE4.

enum HardwareCapabilities_t

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.

enum HCS08_DRegisters_t

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

Enumerator:
HCS08_DRegBKPT 

Breakpoint register.

enum HCS08_Registers_t

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.

enum HCS12_DRegisters_t

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.

enum HCS12_Registers_t

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 

CCR reg - redirected to USBDM_ReadDReg()

enum ICP_ErrorCode_t

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.

enum InterfaceLevelMasks_t

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)

enum JTAG_ExitActions_t

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)

enum PinLevelMasks_t

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_NOCHANGE 

No change to pins (used to get pin status)

PIN_RELEASE 

Release all pins (go to default for current target)

enum ResetMode_t

Target reset status values.

Enumerator:
NO_RESET_ACTIVITY 

No reset activity since last polled.

RESET_DETECTED 

Reset since last polled.

enum ResetState_t

Target RSTO state.

Enumerator:
RSTO_ACTIVE 

RSTO* is currently active [low].

RSTO_INACTIVE 

RSTO* is currently inactive [high].

enum RS08_DRegisters_t

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

Enumerator:
RS08_DRegBKPT 

Breakpoint register.

enum RS08_Registers_t

regNo Parameter for USBDM_ReadReg() with RS08 target

Enumerator:
RS08_RegCCR_PC 

Combined CCR/PC register.

RS08_RegSPC 

Shadow PC.

RS08_RegA 

A reg.

enum SpeedMode_t

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.

enum TargetMode_t

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_METHOD_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.

RESET_DEFAULT 

Use target specific default method.

enum TargetRunState_t

Target Halt state.

Enumerator:
TARGET_RUNNING 

CFVx target running (ALLPST == 0)

TARGET_HALTED 

CFVx target halted (ALLPST == 1)

enum TargetType_t

Target microcontroller types.

Enumerator:
T_HC12 

HC12 or HCS12 target.

T_HCS12 

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)

enum TargetVddSelect_t

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.

enum TargetVddState_t

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.

enum TargetVppSelect_t

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 ??

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:
: Use USBDM_ControlPins()
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.

Returns:
version number (e.g. V4.9.5 => 40905)
Note:
Prior to V4.9.5 an 8-bit version number (2 BCD digits, major-minor) was returned
This shouldn't be a problem as still monotonic
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
BDM_RC_WRONG_BDM_REVISION => BDM firmware/DLL are incompatible
other => Error code - see USBDM_ErrorCode
Note:
Uses cached information from when the BDM was opened.
Can be used to check BDM firmware/DLL compatibility
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 USBDM_ErrorCode USBDM_GetDefaultExtendedOptions ( USBDM_ExtendedOptions_t *  currentBdmOptions)

Get default (target specific) BDM interface options.

Parameters:
currentBdmOptions: Current options from BDM interface
Note - size field must be initialised

  • targetType may be set
Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
Note:
newBdmOptions.targetType should be set if called before USBDM_SetTarget()
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_GetExtendedOptions ( USBDM_ExtendedOptions_t *  currentBdmOptions)

Get BDM interface options.

Parameters:
currentBdmOptions: Current options from BDM interface
Note - size field must be initialised
Returns:

BDM_RC_OK => OK
other => Error code - see USBDM_ErrorCode
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_SetExtendedOptions ( const USBDM_ExtendedOptions_t *  bdmOptions)

Set BDM interface options.

Parameters:
bdmOptions: Options to pass to BDM interface
Note - size field must be initialised
Returns:

BDM_RC_OK => OK
other => Error code - 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