AN117

A N 117
USING THE C8051FXXX/TXXX ON-CHIP INTERFACE UTILITIES DLL
Relevant Devices
This application note applies to all Silicon Laboratories C8051Fxxx/Txxx devices.
1. Introduction
The Interface Utilities Dynamic Link Library (DLL) provides the following functionality: download an Intel hex file to
Flash; connect and disconnect to a C8051Fxxx/Txxx processor; “Run” and “Halt” the microprocessor; and read and
write internal, external, and code memory spaces. All this functionality is provided via a PC’s COM port or USB port
and a Silicon Laboratories Debug Adapter.
When using C++, the functions described in this document must be declared as imported functions. Add the C++
Prototype to the header file (*.h) of the source file (*.cpp) from which the function will be called.
The procedures and guidelines presented in this document illustrate how to link the Interface Utilities DLL to a
client executable. A DLL is not a standalone application. It is a library of exported functions that are linked at runtime and called by a Microsoft Windows® application. To write a client using Visual Basic, please refer to Section 14
on page 20 for more information.
An example Interface Utilities application (including program source code) is provided along with the Interface
Utilities DLL as a means of testing or using the Utilities DLL as a base application. The Interface Utilities application
uses implicit linking, which requires the DLL to be placed in a specific directory (see Section 11 on page 16).
Note: In version 2.60 major changes in the generation of error codes were implemented. See Section 12 on
page 16 for the new error code definition and function.
2. Files and Compatibility
The latest versions of the “SiUtil.dll” and “SiUtil.lib” are available at www.silabs.com. The DLL is a Win32 MFC
Regular DLL, meaning it uses the Microsoft Foundation Class (MFC) libraries. It can be loaded by any Win32
programming environment, and only exports “C” style functions. Two versions are currently available, one in which
the MFC library is statically linked in the DLL, and another version in which the MFC library is dynamically linked in
the DLL.
The statically linked MFC version includes a copy of all the MFC library code it needs and is thus self contained. No
external MFC linking is required. With the MFC library code included, the statically linked DLL will be larger in size
than the dynamically linked version.
Although the dynamically linked DLL is smaller in size than the static version, the dynamically linked DLL requires
that files “MFC42.dll” and “MSVCRT.dll” be present on the target machine. This is not a problem if the client
program is dynamically linked to the same version (Version 4.2) or newer of the MFC library (i.e., uses MFC as a
shared library). The required MFC DLLs, “MFC42.dll” and “MSVCRT.dll”, are provided along with the dynamically
linked MFC version of the Utility Programmer DLL. Do not replace equivalent or newer versions of these files if they
are already present on the target machine.
Rev. 3.3 7/13
Copyright © 2013 by Silicon Laboratories
AN117
AN11 7
3. Communications Functions
The following communication functions are available for use in the Interface Utilities DLL.
Connect()
Disconnect()
ConnectUSB()
DisconnectUSB()
Connected()
3.1.
- Connects to a target C8051Fxxx device using a Serial Adapter.
- Disconnects from a target C8051Fxxx device using a Serial Adapter.
- Connects to a target C8051Fxxx device using a USB Debug Adapter.
- Disconnects from a target C8051Fxxx device using a USB Debug Adapter.
- Returns the connection state of the target C8051Fxxx device.
Connect()
Description:
This function is used to connect to a target C8051Fxxx device using a Serial Adapter. Establishing a valid connection is necessary for all memory operations to succeed.
Supported Debug Adapters: Serial Adapter
C++ Prototype: extern “C” __declspec(dllimport) HRESULT__stdcall Connect
(int nComPort=1, int nDisableDialogBoxes=0, int nECprotocol=0,
int nBaudRateIndex=0);
Parameters:
1. nComPort—Target COM port to establish a connection. The default is 1.
2. nDisableDialogBoxes—Disable (1) or enable (0) dialogs boxes within the DLL. The default is 0.
3. nECprotocol—Connection protocol used by the target device; JTAG (0) or Silicon Laboratories
2-Wire (C2) (1). The default is 0. The C2 interface is used with C8051F3xx derivative devices
and the JTAG interface is used with C8051F0xx, C8051F1xx, and C8051F2xx derivative
devices.
4. nBaudRateIndex—Target baud rate to establish a connection; Autobaud detection (0), 115200
(1), 57600 (2), 38400 (3), 9600 (4) or 2400 (5). The default is 0.
Return Value:
3.2.
See Section 12 on page 16 for error return information.
Disconnect()
Description:
This function is used to disconnect from a target C8051Fxxx device using a Serial Adapter.
Supported Debug Adapters: Serial Adapter
C++ Prototype: extern “C” __declspec(dllimport)
HRESULT__stdcall Disconnect(int nComPort=1);
Parameters:
1. nComPort - COM port in use by current connection. The default is 1.
Return Value:
See Section 12 on page 16 for error return information.
2
Rev. 3.3
AN117
3.3.
ConnectUSB()
Description:
This function is used to connect to a target C8051Fxxx device using a USB Debug Adapter.
Establishing a valid connection is necessary for all memory operations to succeed.
Supported Debug Adapters: USB Debug Adapter
C++ Prototype: extern “C” __declspec(dllimport) HRESULT__stdcall ConnectUSB(
const char * sSerialNum=””, int nECprotocol=0, int nPowerTarget=0,
int nDisableDialogBoxes=0);
Parameters:
1. sSerialNumber—The serial number of the USB Debug Adapter. See Section 8 for information
on obtaining the serial number of each USB Debug Adapter connected. If only one USB
Debug Adapter is connected, an empty string can be used. The default is an empty string.
2. nECprotocol—Connection protocol used by the target device; JTAG (0) or Silicon Laboratories
2-Wire (C2) (1). The default is 0. The C2 interface is used with C8051F3xx derivative devices
and the JTAG interface is used with C8051F0xx, C8051F1xx, and C8051F2xx derivative
devices.
3. nPowerTarget—If this parameter is set to 1, the USB Debug Adapter will be configured to
continue supplying power after it has been disconnected from the target device. The default is
0, configuring the adapter to discontinue supplying power when disconnected.
4. nDisableDialogBoxes—Disable (1) or enable (0) dialogs boxes within the DLL. The default is 0.
Return Value:
3.4.
See Section 12 on page 16 for error return information.
DisconnectUSB()
Description:
This function is used to disconnect from a target C8051Fxxx device using a USB Debug Adapter.
Supported Debug Adapters: USB Debug Adapter
C++ Prototype: extern “C” __declspec(dllimport) HRESULT__stdcall DisconnectUSB();
Parameters:
none
Return Value:
See Section 12 on page 16 for error return information.
3.5.
Connected()
Description:
This function returns a value representing the connection state of the target C8051Fxxx.
Supported Debug Adapters: Serial Adapter, USB Debug Adapter
C++ Prototype: extern “C” __declspec(dllimport) BOOL__stdcall Connected();
Parameters:
none
Return Value:
= 0 (not connected) or
= 1 (connected)
Rev. 3.3
3
AN11 7
4. Program Interface Functions
The following program interface functions are available for use in the Interface Utilities DLL.
Download()
ISupportBanking()
GetSAFirmwareVersion()
GetUSBFirmwareVersion()
GetDLLVersion()
GetDeviceName()
4.1.
- Downloads a hex file to the target C8051Fxxx device.
- Checks to see if banking is supported.
- Returns the Serial Adapter firmware version.
- Returns the USB Debug Adapter firmware version.
- Returns the Utilities DLL version.
- Returns the name of the target C8051Fxxx device.
Download()
Description:
This function is used to download a hex file to a target C8051Fxxx device. After a successful exit
from the Download() function, the target C8051xxx will be in a “Halt” state. If the device is left in
the “Halt” state, it will not begin code execution until the device is reset by a Power-On reset or
by a SetTargetGo() DLL function call.
Supported Debug Adapters: Serial Adapter, USB Debug Adapter
C++ Prototype: extern “C” __declspec(dllimport) HRESULT__stdcall Download(
char * sDownloadFile, int nDeviceErase=0, int nDisableDialogBoxes=0,
int nDownloadScratchPadSFLE= 0, int nBankSelect= -1, int nLockFlash= 0),
BOOL bPersistFlash=1);
Parameters:
1. sDownloadFile—A character pointer to the beginning of a character array (string) containing
the full path and filename of the file to be downloaded.
2. nDevice Erase—When set to 1, performs a device erase before the download initiates. If set
to 0, the part will not be erased. A device erase will erase the entire contents of the device’s
Flash. The default is 0.
3. nDisableDialogBoxes—Disable (1) or enable (0) dialogs boxes within the DLL. The default is 0.
4. nDownloadScratchPadSFLE—This parameter is only for use with devices that have a
Scratchpad Flash memory block. Currently, this includes the C8051F02x, C8051F04x,
C8051F06x, and C8051F12x devices. For all other devices, this parameter should be left in
the default state. Set this parameter to 1 in order to download to Scratchpad memory. When
accessing and downloading to Scratchpad memory, the only valid address range is
0x0000 to 0x007F. The default is 0.
5. nBankSelect—This parameter is only for use with C8051F12x devices. For all other devices,
this parameter should be left in the default state. When using a C8051F12x derivative, set this
parameter to 1, 2, or 3 in order to download to a specific bank. The default is –1.
6. nLockFlash—Set this parameter to 1 to lock the Flash following the download. If Flash is locked,
the DLL will no longer be able to connect to the device.
7. bPersistFlash—If set to 1, the contents of Flash will be read prior to programming. Flash pages
are erased prior to programming. If the pages to be programmed contain any data in Flash that
need to be preserved, then set this parameter to 1.
Return Value:
4
See Section 12 on page 16 for error return information.
Rev. 3.3
AN117
4.2. ISupportBanking()
Description:
This function checks to see if banking is supported.
Supported Debug Adapters: Serial Adapter, USB Debug Adapter
C++ Prototype: extern “C” __declspec(dllimport) HRESULT__stdcall ISupportBanking(
int * nSupportedBanks);
Parameters:
1. nSupportedBanks—The ISupportBanking() function expects to receive a valid pointer to an
integer value. The ISupportBanking() function will set nSupportedBanks to the number of
banks supported on the target device, or 0 if none exist.
Return Value:
See Section 12 on page 16 for error return information.
4.3.
GetSAFirmwareVersion()
Description:
This function is used to retrieve the version of the Serial Adapter firmware.
Supported Debug Adapters: Serial Adapter
C++ Prototype: extern "C" __declspec(dllimport) int __stdcall GetSAFirmwareVersion();
Parameters:
none
Return Value:
Serial Adapter Firmware version
4.4.
GetUSBFirmwareVersion()
Description:
This function is used to retrieve the version of the USB Debug Adapter firmware.
Supported Debug Adapters: USB Debug Adapter
C++ Prototype: extern "C" __declspec(dllimport) int __stdcall GetUSBFirmwareVersion();
Parameters:
none
Return Value:
USB Debug Adapter Firmware version
4.5.
GetDLLVersion()
Description:
This function returns the current version of the Utilities DLL.
Supported Debug Adapters: Serial Adapter, USB Debug Adapter
C++ Prototype: extern "C" __declspec(dllimport) char* __stdcall GetDLLVersion();
Parameters:
none
Return Value:
A string containing the Utilities DLL version
4.6.
GetDeviceName()
Description:
This function returns the name of the target C8051Fxxx device that is currently supported.
Supported Debug Adapters: Serial Adapter, USB Debug Adapter
C++ Prototype: extern "C" __declspec(dllimport) HRESULT__stdcall GetDeviceName(
const char **psDeviceName);
Parameters:
1. psDeviceName - A pointer to a character string location where the device name will be copied.
Return Value:
See Section 12 on page 16 for error return information.
Rev. 3.3
5
AN11 7
5. Get Memory Functions
The following functions for reading device memory locations are available for use in the Interface Utilities DLL.
GetRAMMemory()
GetXRAMMemory()
GetCodeMemory()
- Read RAM memory from a specified address.
- Read XRAM memory from a specified address.
- Read Code memory from a specified address.
The “GetMemory” functions all expect to receive a pointer to an initialized, unsigned char (BYTE) array of nLength
as the first parameter. If the “GetMemory” functions complete successfully, the ptrMem variable will contain the
requested memory.
The following example shows how to properly initialize an array in C++:
unsigned char* ptrMem;
ptrMem = new unsigned char[length]; //Assumes that length has been declared
//and set elsewhere
// next populate the array with the bytes to write in memory
Alternatively:
BYTE ptrMem[10] = {0x00};
5.1.
// Must initialize the array prior to passing
// it into the DLL
GetRAMMemory()
Description:
This function will read the requested memory from the Internal Data Address Space. The
requested RAM memory must be located in the target device’s Internal Data Address Space.
Supported Debug Adapters: Serial Adapter, USB Debug Adapter
C++ Prototype: extern “C” __declspec(dllimport) HRESULT__stdcall GetRAMMemory(
BYTE * ptrMem, DWORD wStartAddress, unsigned int nLength);
Parameters:
1. ptrMem—Pointer to the receive buffer; an initialized, unsigned char (BYTE) array of length
nLength. If the function completes successfully, the ptrMem variable will contain the
requested memory.
2. wStartAddress—The start address of the memory location to be referenced.
3. nLength—The number of bytes to read from memory.
Return Value:
6
See Section 12 on page 16 for error return information.
Rev. 3.3
AN117
5.2. GetXRAMMemory()
Description:
This function will read the requested memory from the External Data Address Space. The
requested XRAM memory must be located in the target device’s External Data Address Space.
Pay special attention to insure proper referencing of the External Data Address Space.
Supported Debug Adapters: Serial Adapter, USB Debug Adapter
C++ Prototype: extern “C” __declspec(dllimport) HRESULT__stdcall GetXRAMMemory(
BYTE * ptrMem, DWORD wStartAddress, unsigned int nLength);
Parameters:
1. ptrMem—Pointer to the receive buffer; an initialized, unsigned char (BYTE) array of length
nLength. If the function completes successfully, the ptrMem variable will contain the
requested memory.
2. wStartAddress—The start address of the memory location to be referenced.
3. nLength—The number of bytes to read from memory.
Return Value:
5.3.
See Section 12 on page 16 for error return information.
GetCodeMemory()
Description:
This function will read the requested memory from the program memory space, including the lock
byte(s). The requested Code memory must be located in the target device’s program memory
space. Use caution when reading from a sector that has been read locked. Reading from a sector that has been read locked will always return 0s. Also, reading from the reserved space is not
allowed and will return an error.
Supported Debug Adapters: Serial Adapter, USB Debug Adapter
C++ Prototype: extern “C” __declspec(dllimport) HRESULT__stdcall GetCodeMemory(
BYTE * ptrMem, DWORD wStartAddress, unsigned int nLength);
Parameters:
1. ptrMem—Pointer to the receive buffer, an initialized unsigned char (BYTE) array of length
nLength. If the function completes successfully, the ptrMem variable will contain the
requested memory.
2. wStartAddress—The start address of the memory location to be referenced.
3. nLength—The number of bytes to read from memory.
Return Value:
See Section 12 on page 16 for error return information.
Rev. 3.3
7
AN11 7
6. Set Memory Functions
The following functions for writing to device memory locations are available for use in the Interface Utilities DLL.
SetRAMMemory()
SetXRAMMemory()
SetCodeMemory()
- Writes value to a specified address in RAM memory.
- Writes value to a specified address in XRAM memory.
- Writes value to a specified address in code memory.
The “SetMemory” functions expect to receive a pointer to an initialized unsigned char (BYTE) array of nLength as
the first parameter. This array should contain nLength number of elements initialized prior to calling into the DLL’s
“SetMemory” functions. If the “SetMemory” functions complete successfully, the ptrMem variable will have
successfully programmed the requested memory.
The following example shows how to properly initialize an array in C++:
unsigned char* ptrMem;
ptrMem = new unsigned char[length]; //Assumes that length has been declared
//and set elsewhere
// next populate your array with the bytes that you want to set in memory
Alternatively:
// Must initialize the array prior to calling the DLL
BYTE ptrMem[10] = {0x00, 0x14, 0xAE, 0x50, 0xAD, 0x66, 0x01, 0x05, 0x77, 0xFF};
6.1.
SetRAMMemory()
Description:
This function will write to memory in the Internal Data Address Space. The target RAM memory
must be located in the target device’s Internal Data Address Space.
Supported Debug Adapters: Serial Adapter, USB Debug Adapter
C++ Prototype: extern "C" __declspec(dllimport) HRESULT__stdcall SetRAMMemory(
BYTE * ptrMem, DWORD wStartAddress, unsigned int nLength);
Parameters:
1. ptrMem—Pointer to the transmit buffer, an initialized unsigned char (BYTE) array of length
nLength. If the function completes successfully, the ptrMem variable will have successfully
programmed the requested memory.
2. wStartAddress—The start address of the memory location to be referenced.
3. nLength —The length of memory to be read.
Return Value:
8
See Section 12 on page 16 for error return information.
Rev. 3.3
AN117
6.2. SetXRAMMemory()
Description:
This function will write to memory in the External Data Address Space. The target XRAM
memory must be located in the target device’s External Data Address Space. Pay special
attention to insure proper referencing of the External Data Address Space.
Supported Debug Adapters: Serial Adapter, USB Debug Adapter
C++ Prototype: extern "C" __declspec(dllimport) HRESULT__stdcall SetXRAMMemory(
BYTE * ptrMem, DWORD wStartAddress, unsigned int nLength);
Parameters:
1. ptrMem—Pointer to the transmit buffer, an initialized unsigned char (BYTE) array of length
nLength. If the function completes successfully, the ptrMem variable will have successfully
programmed the requested memory.
2. wStartAddress—The start address of the memory location to be referenced.
3. nLength—The length of memory to be read.
Return Value:
6.3.
See Section 12 on page 16 for error return information.
SetCodeMemory()
Description:
This function will write to memory in the program memory space. If a client tries to write more
than one page of data at one time, or tries to write to the reserved area of Flash or to a write/
erase locked sector, the write function will not complete successfully. To write to a read/write lock
byte, wStartAddress should correspond to the device read/write lock byte address and nLength
should have a value of 1 or 2. Please refer to the relevant device data sheets for additional
information. If SetCodeMemory() completes successfully, only the specified range,
wStartAddress + nLength, will have successfully been written. All other values within the page
will retain their initial values.
Supported Debug Adapters: Serial Adapter, USB Debug Adapter
C++ Prototype: extern "C" __declspec(dllimport) HRESULT__stdcall SetCodeMemory(
BYTE * ptrMem, DWORD wStartAddress, unsigned int nLength,
int nDisableDialogs=0);
Parameters:
1. ptrMem—Pointer to the transmit buffer, an initialized unsigned char (BYTE) array of length
nLength. If the function completes successfully, the ptrMem variable will have successfully
programmed the requested memory.
2. wStartAddress—The start address of the memory location to be referenced.
3. nLength—The length of memory to be read.
4. nDisableDialogs—Disable (1) or enable (0) dialogs boxes within the DLL. The default is 0.
Return Value:
See Section 12 on page 16 for error return information.
Rev. 3.3
9
AN11 7
7. Target Control Functions
The following functions for controlling a device are available for use in the Interface Utilities DLL.
SetTargetGo()
SetTargetHalt()
7.1.
- Puts the target C8051Fxxx device in a “Run” state.
- Puts the target C8051Fxxx device in a “Halt” state.
SetTargetGo()
Description:
After a successful exit from the SetTargetGo() function, the target C8051xxx will be in a “Run” state.
Supported Debug Adapters: Serial Adapter, USB Debug Adapter
C++ Prototype: extern “C” __declspec(dllimport) HRESULT__stdcall SetTargetGo();
Parameters:
none
Return Value:
See Section 12 on page 16 for error return information.
7.2.
SetTargetHalt()
Description:
After a successful exit from the SetTargetHalt() function, the target C8051xxx will be in a “Halt” state.
Supported Debug Adapters: Serial Adapter, USB Debug Adapter
C++ Prototype: extern “C” __declspec(dllimport) HRESULT__stdcall SetTargetHalt();
Parameters:
none
Return Value:
See Section "12. Test Results" on page 16 for error return information.
10
Rev. 3.3
AN117
8. USB Debug Adapter Communication Functions
The following functions are available in the Interface Utilities DLL to query and configure a USB Debug Adapter.
These functions are useful when more than one USB Debug Adapter is connected to the PC. Call
USBDebugDevices() first to determine the number of USB Debug Adapters connected. Next, use
GetUSBDeviceSN() to determine the serial number of each adapter. The serial number can then be used with
other functions to communicate with an individual USB Debug Adapter.
USBDebugDevices()
GetUSBDeviceSN()
GetUSBDLLVersion()
8.1.
- Determines how many USB Debug Adapters are present.
- Obtains the serial number of the enumerated USB Debug Adapters.
- Returns the version of the USB Debug Adapter driver file.
USBDebugDevices()
Description:
This function will query the USB bus and identify how many USB Debug Adapter devices are
present.
Supported Debug Adapters: USB Debug Adapter
C++ Prototype: extern "C" __declspec(dllimport) HRESULT__stdcall USBDebugDevices(
DWORD * dwDevices);
Parameters:
1. dwDevices—A pointer to the value that will contain the number of devices that are found.
Return Value:
See Section 12 on page 16 for error return information.
8.2.
GetUSBDeviceSN()
Description:
This function obtains a serial number string for the USB Debug Adapter specified by an index
passed in the dwDeviceNum parameter. The index of the first device is 0 and the index of the last
device is the value returned by USBDebugDevices() – 1.
Supported Debug Adapters: USB Debug Adapter
C++ Prototype: extern "C" __declspec(dllimport) HRESULT__stdcall GetUSBDeviceSN(
DWORD dwDeviceNum, const char ** psSerialNum);
Parameters:
1. dwDeviceNum—Index of the device for which the serial number is desired. To obtain the
serial number of the first device, use 0.
2. psSerialNum—A pointer to a character string location where the serial number will be copied.
Return Value:
8.3.
See Section 12 on page 16 for error return information.
GetUSBDLLVersion()
Description:
This function will return the version of the driver for the USB Debug Adapter.
Supported Debug Adapters: USB Debug Adapter
C++ Prototype: extern "C" __declspec(dllimport) HRESULT__stdcall GetUSBDLLVersion(
const char ** pVersionString);
Parameters:
1. pVersionString—Pointer to a character string location where the version string of the USB
Debug Adapter driver will be copied.
Return Value:
See Section 12 on page 16 for error return information.
Rev. 3.3
11
AN11 7
9. Stand-Alone Functions
The following stand-alone functions are available for use in the Interface Utilities DLL. These functions do not
require the use of the “Connect” or “Disconnect” functions and do not interact with any other functions.
FLASHErase()
FLASHEraseUSB()
9.1.
- Erase the Flash program memory using a Serial Adapter.
- Erase the Flash program memory using a USB Debug Adapter.
FLASHErase()
Description:
This function is used to erase the Flash program memory of a device using a Serial Adapter. This
function must be used to “unlock” a device whose Flash read and/or write lock bytes have been
written.
Supported Debug Adapters: Serial Adapter
C++ Prototype: extern "C" __declspec(dllimport) HRESULT__stdcall FLASHErase(
int nComPort=1, int nDisableDialogBoxes=0, int nECprotocol=0);
Parameters:
1. nComPort—Target COM port to establish a connection. The default is 1.
2. nDisableDialogBoxes—Disable (1) or enable (0) dialogs boxes within the DLL. The default is 0.
3. nECprotocol—Connection protocol used by the target device; JTAG (0) or Silicon Laboratories
2-Wire (C2) (1). The default is 0. The C2 interface is used with C8051F3xx derivative devices
and the JTAG interface is used with C8051F0xx, C8051F1xx, and C8051F2xx derivative
devices.
Return Value:
9.2.
See Section 12 on page 16 for error return information.
FLASHEraseUSB()
Description:
This function is used to erase the Flash program memory of a device using a USB Debug
Adapter. This function must be used to “unlock” a device whose Flash read and/or write lock
bytes have been written.
Supported Debug Adapters: USB Debug Adapter
C++ Prototype: extern "C" __declspec(dllimport) HRESULT__stdcall FLASHEraseUSB(
const char * sSerialNum, int nDisableDialogBoxes=0, int nECprotocol=0);
Parameters:
1. sSerialNumber—The serial number of the USB Debug Adapter. See Section 8 for information
on obtaining the serial number of each USB Debug Adapter connected. If only one USB
Debug Adapter is connected, an empty string can be used. The default is an empty string.
2. nDisableDialogBoxes—Disable (1) or enable (0) dialogs boxes within the DLL. The default is 0.
3. nECprotocol—Connection protocol used by the target device; JTAG (0) or Silicon Laboratories
2-Wire (C2) (1). The default is 0. The C2 interface is used with C8051F3xx derivative devices
and the JTAG interface is used with C8051F0xx, C8051F1xx, and C8051F2xx derivative
devices.
Return Value:
12
See Section 12 on page 16 for error return information.
Rev. 3.3
AN117
10. Multi-Device JTAG Programming
Multiple Silicon Laboratories C8051Fxxx devices that use the JTAG communications protocol can be connected
and programmed in a JTAG chain. Currently this includes the C8051F0xx, C8051F1xx, and C8051F2xx device
families. Configure the JTAG chain as shown in Figure 1. It will be necessary to know the instruction register length
of each device in the JTAG chain. The instruction register length of all Silicon Laboratories JTAG devices is 16 bits.
The following functions to configure and connect to a C8051Fxxx device on a JTAG chain is available for use in the
Interface Utilities DLL.
SetJTAGDeviceAndConnect()
- Configure a connection to a C8051Fxxx device on a JTAG chain
using a Serial Adapter.
SetJTAGDeviceAndConnectUSB() - Configure a connection to a C8051Fxxx device on a JTAG chain
using a USB Debug Adapter.
Once the “SetJTAGDeviceAndConnect” function has returned successfully and a connection has been established
with a Silicon Laboratories device in the JTAG chain, any of the previously mentioned Communication, Program
Interface, and memory functions may be used on the isolated device. When finished interfacing with the device,
call a “Disconnect” function as usual to disconnect from the device.
TCK
TMS
TDO
TDI
JTAG Controller
(Debug Adapter)
TCK
TDO
TMS
TCK
TDI
JTAG Device #0
TDO
TMS
TDI
JTAG Device #1
TCK
TDO
TMS
TDI
JTAG Device #2
Figure 1. JTAG Chain Connection
Rev. 3.3
13
AN11 7
10.1. SetJTAGDeviceAndConnect()
Description:
This function is used to connect to a single target JTAG device in a JTAG chain using a Serial
Adapter.
Supported Debug Adapters: Serial Adapter
C++ Prototype: extern "C" __declspec(dllimport) HRESULT__stdcall SetJTAGDeviceAndConnect(
int nComPort=1, int nDisableDialogBoxes=0,
BYTE DevicesBeforeTarget=0, BYTE DevicesAfterTarget=0,
WORD IRBitsBeforeTarget=0, WORD IRBitsAfterTarget=0);
Parameters:
1. nComPort—Target COM port to establish a connection. The default is 1.
2. nDisableDialogBoxes—Disable (1) or enable (0) dialogs boxes within the DLL. The default is 0.
3. DevicesBeforeTarget—Number of devices in the JTAG chain before the target device. The
default is 0.
4. DevicesAfterTarget—Number of devices in the JTAG chain after the target device. The default
is 0.
5. IRBitsBeforeTarget—The sum of instruction register bits in the JTAG chain before the target
device. The default is 0.
6. IRBitsAfterTarget—The sum of instruction register bits in the JTAG chain after the target
device. The default is 0.
Following Figure 1, assuming all devices in the JTAG chain are Silicon Laboratories devices, call
SetJTAGDeviceAndConnect() as shown in the following examples:
To access JTAG Device #0:
SetJTAGDeviceAndConnect(1, 0, 0, 2, 0, 32);
nComPort=1
nDisableDialogBoxes=0
DevicesBeforeTarget=0
DevicesAfterTarget=2
IRBitsBeforeTarget=0
IRBitsAfterTarget=32
To access JTAG Device #1:
SetJTAGDeviceAndConnect(1, 0, 1, 1, 16, 16);
nComPort=1
nDisableDialogBoxes=0
DevicesBeforeTarget=1
DevicesAfterTarget=1
IRBitsBeforeTarget=16
IRBitsAfterTarget=16
To access JTAG Device #2:
SetJTAGDeviceAndConnect(1, 0, 2, 0, 32, 0);
nComPort=1
nDisableDialogBoxes=0
DevicesBeforeTarget=2
DevicesAfterTarget=0
IRBitsBeforeTarget=32
IRBitsAfterTarget=0
Return Value:
14
See Section 12 on page 16 for error return information.
Rev. 3.3
AN117
10.2. SetJTAGDeviceAndConnectUSB()
Description:
This function is used to connect to a single target JTAG device in a JTAG chain using a USB
Debug Adapter.
Supported Debug Adapters: USB Debug Adapter
C++ Prototype: extern "C" __declspec(dllimport) HRESULT__stdcall SetJTAGDeviceAndConnectUSB(
const char * sSerialNum, int nPowerTarget=0, int nDisableDialogBoxes=0,
BYTE DevicesBeforeTarget=0, BYTE DevicesAfterTarget=0,
WORD IRBitsBeforeTarget=0, WORD IRBitsAfterTarget=0);
Parameters:
1. sSerialNumber—The serial number of the USB Debug Adapter. See Section 8 for information
on obtaining the serial number of each USB Debug Adapter connected. If only one USB
Debug Adapter is connected, an empty string can be used. The default is an empty string.
2. nPowerTarget—If this parameter is set to 1, the USB Debug Adapter will be configured to
continue supplying power after it has been disconnected from the target device. The default is
0, which configures the adapter to discontinue supplying power when disconnected.
3. nDisableDialogBoxes—Disable (1) or enable (0) dialogs boxes within the DLL. The default is 0.
4. DevicesBeforeTarget—Number of devices in the JTAG chain before the target device. The
default is 0.
5. DevicesAfterTarget—Number of devices in the JTAG chain after the target device. The default
is 0.
6. IRBitsBeforeTarget—The sum of instruction register bits in the JTAG chain before the target
device. The default is 0.
7. IRBitsAfterTarget—The sum of instruction register bits in the JTAG chain after the target
device. The default is 0.
Following Figure 1, assuming all devices in the JTAG chain are Silicon Laboratories devices, call
SetJTAGDeviceAndConnectUSB() as shown in the following examples:
To access JTAG Device #0:
SetJTAGDeviceAndConnectUSB(““, 0, 0, 0, 2, 0, 32);
sSerialNumber=””DevicesBeforeTarget=0
nPowerTarget=0DevicesAfterTarget=2
nDisableDialogBoxes=0IRBitsBeforeTarget=0
IRBitsAfterTarget=32
To access JTAG Device #1:
SetJTAGDeviceAndConnectUSB(““, 0, 0, 1, 1, 16, 16);
sSerialNumber=””DevicesBeforeTarget=1
nPowerTarget=0DevicesAfterTarget=1
nDisableDialogBoxes=0IRBitsBeforeTarget=16
IRBitsAfterTarget=16
To access JTAG Device #2:
SetJTAGDeviceAndConnectUSB(““, 0, 0, 2, 0, 32, 0);
sSerialNumber=””DevicesBeforeTarget=2
nPowerTarget=0DevicesAfterTarget=0
nDisableDialogBoxes=0IRBitsBeforeTarget=32
IRBitsAfterTarget=32
Return Value:
See Section 12 on page 16 for error return information.
Rev. 3.3
15
AN11 7
11. Linking
Unless using explicit linking, it is necessary to provide the linker with the path of the “SiUtil.lib” library file before
building the client executable. In Microsoft Visual C++, this is accomplished by selecting Settings… from the
Project menu and then the Link tab. In the Object/library modules box, enter the full path and filename of the library
file. For example, “c:\project\release\SiUtil.lib” is the path and filename you would use for the library file titled,
“SiUtil.” The library file is not needed after the client executable is built.
If the DLL is implicitly linked, the DLL must be placed in one the following directories:
1. The directory containing the EXE client file.
2. The process’s current directory.
3. The Windows system directory.
4. The Windows directory.
5. A directory listed in the PATH environment variable.
12. Test Results
12.1. Error Code Definition
The DLL implements standard Windows HRESULT error codes. An HRESULT is a 32-bit value that includes a 16bit error code in addition to information about the origin and severity of the error. The following information on the
structure of an HRESULT code can be found in WINERROR.H:
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
16
HRESULTs are 32-bit values laid out as follows:
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
+-+-+-+-+-+---------------------+-------------------------------+
|S|R|C|N|r|
Facility
|
Code
|
+-+-+-+-+-+---------------------+-------------------------------+
where
S - Severity - indicates success/fail
0 - Success
1 - Fail (COERROR)
R - reserved portion of the facility code, corresponds to
NT's second severity bit.
C - reserved portion of the facility code, corresponds to
NT's C field.
N - reserved portion of the facility code. Used to indicate
a mapped NT status value.
r - reserved portion of the facility code. Reserved for
internal use. Used to indicate HRESULT values that are
not status values, but are instead message ids for
display strings.
Facility - is the facility code
Code - is the facility's status code
Rev. 3.3
AN117
The Windows HRESULT implementation also provides macros that should be used to test the function's success
or failure:
//
// Generic test for success on any status value (non-negative
// numbers indicate success).
//
#define SUCCEEDED(Status) ((HRESULT)(Status) >= 0)
//
// and the inverse
//
#define FAILED(Status) ((HRESULT)(Status)<0)
Note that it is possible for functions to return non-zero positive "success" error codes. Therefore, you should
always check for success or failure by using either the SUCCEEDED() or FAILED() macros.
Bit 15 of the Code field is the Target Disconnected Flag. If Bit 15 is set, then this indicates that the target device has
been disconnected as a result of invoking the function. The following macro may be used to help test this bit:
#define TARGET_DISCONNECTED_FLAG 0x8000
When a non-zero HRESULT value is returned, the Facility field will indicate the source of the error.
It is possible to receive the following standard Windows errors (as defined in winerror.h):
E_INVALIDARG
// One or more arguments is invalid
E_HANDLE
// Invalid handle
Additional error return values for each Facility and Code value are defined in Tables 1, 2, 3, and 4.
Rev. 3.3
17
AN11 7
Table 1. Facility Code 100 Error Description Table
Error Code
18
Error Definition
Error Code
Error Definition
0x101
Unable to write to Flash.
0x119
Target is not in the HALT state and did not
respond to the query.
0x102
Unable to lock Flash.
0x11A
A Flash failure occurred.
0x103
Target device is not halted.
0x11B
Not connected to target. (This is a disconnect error, so the target disconnected flag
bit will also be set.)
0x104
Invalid path.
0x11C
The target is not responding.
0x105
Unable to open COM Port.
0x11D
The target reported that the command
failed.
0x106
Unable to download program.
0x11E
Communication port time out.
0x107
Reset failed.
0x11F
Could not clear communication port error.
0x108
Erase failed.
0x120
Error receiving byte.
0x109
Unable to close COM Port.
0x121
Receive Buffer Failure.
0x10A
USB Debug Adapter DLL not found.
0x122
Error occurred during purge of communication port.
0x10B
Unable to open USB Debug Adapter.
0x123
Error occurred during firmware update.
0x10C
External memory is not supported on this
device.
0x124
A CRC comparison failure has occurred.
0x10D
Target device is connected.
0x125
An error occurred during device reset.
0x10E
Unknown device.
0x126
This operation is not supported on this
device.
0x10F
Invalid target response.
0x127
Flash is locked.
0x110
Invalid arguments.
0x128
An incorrect response has been received.
0x111
Target did not respond and may be disconnected.
0x129
Valid adapter selection has not been
assigned.
0x112
Target did not respond with enough data.
0x12A
The USB Debug Adapter handle is void.
0x113
The communication port is busy.
0x12B
USB Debug Adapter unknown function.
0x114
The communication port is not open.
0x12C
Flash erase has been cancelled.
0x115
Timer resource not available.
0x12D
Part not loaded in XML services.
0x116
Unable to write all the data to the target.
0x12E
The MCU product configuration data is
missing information about this device.
0x117
Serial Interface had no new data to return.
0x12F
Unable to access MCU product configuration data.
0x118
UART has not been enabled via GPIO
configuration.
0x130
The version of the device you connected
to is older than the minimum version supported.
Rev. 3.3
AN117
Table 2. Facility Code 102 Error Description Table
Error Code
Error Definition
0x101
Download cancelled.
0x102
Read failed.
Table 3. Facility Code 103 Error Description Table
Error Code
Error Definition
0x101
A valid adapter has not been defined.
0x102
Target could not be reset.
0x103
Unable to set up and open COM Port.
0x104
Unable to halt the target device.
0x105
Maximum number of breakpoints reached.
0x106
Target configuration failure.
0x107
Bootloader failure.
Table 4. Facility Code 104 Error Description Table
Error Code
Error Definition
0x101
Invalid handle.
0x102
Read error.
0x103
Write error.
0x105
Device I/O failed.
0x106
Error string supplied by Windows.
0x107
Read time out error.
0x108
SN access error.
0x109
Reset response failure.
0x10A
TLS invalid.
0x10B
Target not connected. (This is a disconnect
error, so the target disconnected flag bit
will also be set.)
0x10C
USBHID.DLL not initialized.
0x10D
No device selected.
0x1FF
Device not found.
Rev. 3.3
19
AN11 7
The GetErrorMsg() function can be used to get a string describing the error so that an application can display a
message with error information.
12.2. GetErrorMsg()
Description:
This function returns a string describing an error which has been generated by the DLL.
Supported Debug Adapters: Serial Adapter, USB Debug Adapter
C++ Prototype: extern "C" __declspec(dllexport)
char* __stdcall GetErrorMsg (HRESULT errorCode);
Parameters:
1. errorCode - An HRESULT value for an error that should be interpreted.
Return Value:
A string description of the errorCode.
13. Known Limitations
Upon invocation of the DLL in the debug mode of a client process, dialog messaging may not function properly.
Dialog messaging provides a client with a way to get instant information that may not otherwise be available.
Dialog messaging supports a progress indicator that provides a client with information on the progress of memory
operations that may take time to complete. Calling into the DLL with a client (in debug version) may cause the DLL
to misinterpret the correct window handle used to display the dialog boxes. The recommended course of action is
to set all functions that have a nDisableDialogBoxes parameter to 1 before calling DLL functions. All
nDisableDialogBoxes parameters default to 0. This problem will not occur in the release mode of a client process.
14. Visual Basic Information
When writing a Visual Basic client, it is important to note that the Interface Utilities DLL is written using Visual C++.
Thus, you must take into account variable type differences between the two languages. Specifically, the VC++
boolean type and the VB boolean type are incompatible. In VC++, TRUE = 1 and FALSE = 0, whereas in VB
TRUE = –1 and FALSE = 0. To resolve this issue, you must use an integer instead of a boolean when writing your
VB client and send an integer value 1 for TRUE and integer value 0 for FALSE.
20
Rev. 3.3
AN117
DOCUMENT CHANGE LIST
Revision 2.6 to Revision 2.7
Revision 2.2 to Revision 2.3

Instructions for declaring functions moved to Section
1.
 Reference to the SetJTAGDeviceAndConnect()
function moved from Section 9 to Section 10.
 Replaced incorrect function descriptions in the
Section 9 function list.

Revision 2.3 to Revision 2.4





“Supported Debug Adapter” field added to each
function definition.
The following new functions added to support the
USB Debug Adapter: ConnectUSB(),
DisconnectUSB(), USBDebugDevices(),
GetUSBDeviceSN(), GetHIDDLLVersion(),
FLASHEraseUSB(), GetUSBFirmwareVersion(),
SetJTAGDeviceAndConnectUSB()
Section 4, “Program Interface Functions” split into 2
sections, creating Section 7, “Target Control
Functions”.
Section 8, “USB Debug Adapter Communication
Functions” added.
Added Return Codes 9 and 10 to Table 1, “Return
Codes”.
Revision 2.4 to Revision 2.5
Added description for new GetDeviceName()
function as Section 4.6 on page 5.
 Moved function descriptions for
GetSAFirmwareVersion(),
GetUSBFirmwareVersion(), and GetDLLVersion() to
Section 4, “Program Interface Functions”.
Revision 2.7 to Revision 2.8
Updated Section 4.6 on page 5.
 Updated Section 8.2 on page 11.

Replaced
“dllexport” with “dllimport”.
Revision 2.8 to Revision 2.9
Error code return type changed from int_stdcall to
HRESULT_stdcall.
 New parameter, bPersistFlash, added to Section
"4.1. Download()" on page 4.
 Section “12. Test Results” replaced with new error
code implementation information.

Revision 2.9 to Revision 3.0

In Section "7.2. SetTargetHalt()" on page 10, return
value type changed from BOOL to HRESULT with
the function using the new error code
implementation.
Revision 3.0 to Revision 3.1
Updated "12.1. Error Code Definition" on page 16.
Updated Table 1, “Facility Code 100 Error
Description Table,” on page 18.
 Updated Table 2, “Facility Code 102 Error
Description Table,” on page 19.
 Updated Table 3, “Facility Code 103 Error
Description Table,” on page 19.
 Updated Table 4, “Facility Code 104 Error
Description Table,” on page 19.
Pointer format in prototypes corrected for
consistency.
 Std::string types of variables changed to const
char * variables.
 Section 8.3, “GetUSBDLLVersion()” function name
changed from GetHIDDLLVersion to
GetUSBDLLVersion.
 Section 10.2, “SetJTAGDeviceAndConnectUSB()”
prototype corrected.

Revision 2.5 to Revision 2.6
Revision 3.1 to Revision 3.2
New parameter nLockFlash added to Download()
function, Section 4.1.
 GetDLLVersion() function returns a "char*" value
instead of an "int" value, Section 4.5.




Revision 3.2 to Revision 3.3

Rev. 3.3
Updated document’s scope.
21
AN11 7
CONTACT INFORMATION
Silicon Laboratories Inc.
400 West Cesar Chavez
Austin, TX 78701
Tel: 1+(512) 416-8500
Fax: 1+(512) 416-9669
Toll Free: 1+(877) 444-3032
Please visit the Silicon Labs Technical Support web page:
https://www.silabs.com/support/pages/contacttechnicalsupport.aspx
and register to submit a technical support request.
Patent Notice
Silicon Labs invests in research and development to help our customers differentiate in the market with innovative low-power, small size, analogintensive mixed-signal solutions. Silicon Labs' extensive patent portfolio is a testament to our unique approach and world-class engineering team.
The information in this document is believed to be accurate in all respects at the time of publication but is subject to change without notice.
Silicon Laboratories assumes no responsibility for errors and omissions, and disclaims responsibility for any consequences resulting from
the use of information included herein. Additionally, Silicon Laboratories assumes no responsibility for the functioning of undescribed features or parameters. Silicon Laboratories reserves the right to make changes without further notice. Silicon Laboratories makes no warranty, representation or guarantee regarding the suitability of its products for any particular purpose, nor does Silicon Laboratories assume any
liability arising out of the application or use of any product or circuit, and specifically disclaims any and all liability, including without limitation
consequential or incidental damages. Silicon Laboratories products are not designed, intended, or authorized for use in applications intended to support or sustain life, or for any other application in which the failure of the Silicon Laboratories product could create a situation where
personal injury or death may occur. Should Buyer purchase or use Silicon Laboratories products for any such unintended or unauthorized
application, Buyer shall indemnify and hold Silicon Laboratories harmless against all claims and damages.
Silicon Laboratories and Silicon Labs are trademarks of Silicon Laboratories Inc.
Other products or brandnames mentioned herein are trademarks or registered trademarks of their respective holders.
22
Rev. 3.3