Atmel Data Gateway Interface User guide

Data Gateway Interface

USER GUIDE

Description

The Atmel® Data Gateway Interface is a USB interface for handling the low­level transport of data to and from a target MCU. DGI is available on a
selection of tools and on-board debuggers, such as the Power Debugger
and the EDBG, as found on Xplained Pro.

DGI provides several interfaces utilizing the same API for configuration and
communication. Each interface implements an abstraction to a physical
communication interface, such as SPI and UART, or represents a service not
directly tied to a physical communication interface, such as the timestamp
interface.

Atmel-32223A-Data-Gateway-Interface_User Guide-09/2016

Table of Contents

Description.......................................................................................................................1

1. USB Communication................................................................................................. 3

2. Protocol......................................................................................................................4

2.1. DGI_CMD_SIGN_ON...................................................................................................................5

2.2. DGI_CMD_SIGN_OFF.................................................................................................................5

2.3. DGI_CMD_GET_VERSION......................................................................................................... 6

2.4. DGI_CMD_SET_MODE............................................................................................................... 6

2.5. DGI_CMD_TARGET_RESET.......................................................................................................7

2.6. DGI_CMD_INTERFACES_LIST...................................................................................................7

2.7. DGI_CMD_INTERFACES_ENABLE............................................................................................8

2.8. DGI_CMD_INTERFACES_SET_CONFIG................................................................................... 8

2.9. DGI_CMD_INTERFACES_GET_CONFIG...................................................................................9

2.10. DGI_CMD_INTERFACES_POLL_DATA......................................................................................9

2.11. DGI_CMD_INTERFACES_SEND_DATA................................................................................... 10

2.12. DGI_CMD_INTERFACES_STATUS...........................................................................................10

3. Interfaces.................................................................................................................12

3.1. Timestamp..................................................................................................................................12

3.1.1. Parsing.........................................................................................................................12

3.1.2. Configuration............................................................................................................... 14

3.2. GPIO...........................................................................................................................................14

3.2.1. Parsing.........................................................................................................................14

3.2.2. Configuration............................................................................................................... 14

3.3. SPI..............................................................................................................................................14

3.3.1. Parsing.........................................................................................................................15

3.3.2. Configuration............................................................................................................... 15

3.4. USART....................................................................................................................................... 15

3.4.1. Parsing.........................................................................................................................15

3.4.2. Configuration............................................................................................................... 15

3.5. I2C.............................................................................................................................................. 16

3.5.1. Parsing.........................................................................................................................16

3.5.2. Configuration............................................................................................................... 16

3.6. Power......................................................................................................................................... 16

3.6.1. Parsing.........................................................................................................................16

3.6.2. Configuration............................................................................................................... 18

4. Revision History.......................................................................................................21

Atmel Data Gateway Interface [USER GUIDE]

Atmel-32223A-Data-Gateway-Interface_User Guide-09/2016

2

1. USB Communication

The DGI USB device consists of two endpoints; one OUT Bulk endpoint for sending commands from the
PC, and one IN Bulk endpoint for receiving responses. The endpoint size of both the IN and OUT
endpoint must be taken into account when communicating with the device. A completed packet is
recognized by the transfer having a length of less than the endpoint size. If a packet has a length which is
a multiple of the endpoint size, the last transfer must be a zero length transfer to complete the packet.

All communication is initiated by the host computer sending a command packet over the OUT endpoint.
All commands are given a response over the IN endpoint. Unrecognized commands will receive an error
response.

Commands can have a maximum length of 256 bytes. Responses to most commands are only a few
bytes. However, responses can be several thousand bytes when polling incoming data from the DGI
buffer.

The USB device is a custom implementation, not following any predefined USB classes, and will therefore
require the installation of a driver on most systems.

Atmel Data Gateway Interface [USER GUIDE]

Atmel-32223A-Data-Gateway-Interface_User Guide-09/2016

3

2. Protocol

All values in the protocol are big endian. Command packets consists of a command byte, a 2-byte length
and command-specific parameters. The length field only counts the bytes in parameters, and will be 0 for
commands without parameters.

Table 2-1. Command Packet

Field Size Description

Command 1 Byte The identifier of the command to be executed.

Length 2 Bytes Amount of trailing data in parameters (n).

Parameters n Bytes Command-specific parameters.

All received packets are parsed, executed, and responded to by a response code. The response packet
consists of the received command byte, a status code, and parameters, depending on the command and
status code. Unknown commands will receive an error response.

Table 2-2. Response Packet

Field Size Description

Command 1 Byte The identifier of the command that was executed.

Status Code 1 Byte Response indicating the status of the executed command.

Parameters n Bytes Some status codes have parameters. The parsing of the parameters are

command-specific.

Below is a list of the supported commands and possible response codes. Refer to the following sub­sections for details.

Table 2-3. List of Commands

Name Value Description

DGI_CMD_SIGN_ON 0x00 Initializes DGI and returns a verification string. Must

be the first command called.

DGI_CMD_SIGN_OFF 0x01 Disconnects and stops all interfaces.

DGI_CMD_GET_VERSION 0x02 Returns the version of the DGI implementation.

DGI_CMD_SET_MODE 0x0A Sets the operating mode of DGI.

DGI_CMD_INTERFACES_LIST 0x08 Lists all available interface identifiers.

DGI_CMD_INTERFACES_ENABLE 0x10 Used to enable/disable interfaces.

DGI_CMD_INTERFACES_STATUS 0x11 Fetches the status for the interfaces.

DGI_CMD_INTERFACES_SET_CONFIG 0x12 Sets the configuration for the specified interface.

DGI_CMD_INTERFACES_GET_CONFIG 0x13 Gets the configuration for the specified interface.

DGI_CMD_INTERFACES_SEND_DATA 0x14 Sends data for transmission over specified interface.

DGI_CMD_INTERFACES_POLL_DATA 0x15 Returns the data buffer for the specified interface.

DGI_CMD_TARGET_RESET 0x20 Controls the state of the reset line of the target

device.

Atmel Data Gateway Interface [USER GUIDE]

Atmel-32223A-Data-Gateway-Interface_User Guide-09/2016

4

Table 2-4. List of Responses

Name Value Description

DGI_RESP_OK 0x80 Verifies that the command was executed correctly.

DGI_RESP_FAIL 0x99 An error occurred during execution of the command. Usually caused

DGI_RESP_DATA 0xA0 The command was executed correctly and returned data. The data is

DGI_RESP_UNKNOWN 0xFF The received command identifier is unknown.

2.1. DGI_CMD_SIGN_ON

The sign on command is always the very first command to be called. It will initialize all states, buffers, and
interfaces to a known starting point. A tool-specific string is returned as an acknowledgment of the sign
on.

Table 2-5. Command Packet

Field Size Description

DGI_CMD_SIGN_ON (0x00) 1 Byte Command ID.

by wrong usage of the protocol.

command-specific and must be parsed accordingly.

Length (0) 2 Bytes No parameters.

Table 2-6. Response Packet

Field Size Description

DGI_CMD_SIGN_ON (0x00) 1 Byte Command ID.

DGI_RESP_DATA (0xA0) 1 Byte Response code.

Length 2 Bytes Length, n, of the acknowledgment string.

String n Bytes Acknowledgment string.

2.2. DGI_CMD_SIGN_OFF

The sign off command is the last command to be called. It will de-initialize all states, buffers, and
interfaces.

Table 2-7. Command Packet

• EDBG = "EDBG Data Gateway Interface"

• Power Debugger = "Powerdebugger Data Gateway

Interface"

• Atmel-ICE = "Atmel-ICE Data Gateway Interface"

Field Size Description

DGI_CMD_SIGN_OFF (0x01) 1 Byte Command ID.

Length (0) 2 Bytes No parameters.

Atmel Data Gateway Interface [USER GUIDE]

Atmel-32223A-Data-Gateway-Interface_User Guide-09/2016

5

Table 2-8. Response Packet

Field Size Description

DGI_CMD_SIGN_OFF (0x01) 1 Byte Command ID.

DGI_RESP_OK (0x80) 1 Byte Response code.

2.3. DGI_CMD_GET_VERSION

This command gets the version number of the DGI implementation. The latest version at the time of
writing is 3.1.

Table 2-9. Command Packet

Field Size Description

DGI_CMD_GET_VERSION (0x02) 1 Byte Command ID.

Length (0) 2 Bytes No parameters.

Table 2-10. Response Packet

Field Size Description

DGI_CMD_GET_VERSION (0x02) 1 Byte Command ID.

DGI_RESP_DATA (0xA0) 1 Byte Response code.

Major version 1 Byte Incremented only for big breaking changes.

Minor version 1 Byte Incremented for each change relevant to the protocol.

2.4. DGI_CMD_SET_MODE

This command changes the operating mode of certain aspects of the DGI mechanisms and protocol.
Affected commands will have details in the command specific sections.

Table 2-11. Command Packet

Field Size Description

DGI_CMD_SET_MODE (0x0A) 1 Byte Command ID.

Length (1) 2 Bytes

Mode 1 Byte Each bit corresponds to a specific setting. Default value is 0.

• Bit 2

0: Use 2 byte length for poll response.

1: Use 4 byte length for poll response.

• Bit 0

0: Poll response does not include overflow indicator.

1: Add buffer overflow indicator to poll response.

Atmel Data Gateway Interface [USER GUIDE]

Atmel-32223A-Data-Gateway-Interface_User Guide-09/2016

6

Table 2-12. Response Packet

Field Size Description

DGI_CMD_SET_MODE (0x0A) 1 Byte Command ID.

DGI_RESP_OK (0x80) 1 Byte Response code.

2.5. DGI_CMD_TARGET_RESET

This command sets the state of the reset line.

Table 2-13. Command Packet

Field Size Description

DGI_CMD_TARGET_RESET (0x20) 1 Byte Command ID.

Length (1) 2 Bytes

Reset state 1 Byte • Bit 0

0: Not asserted (released, pulled high by external
pull-up).

1: Asserted (pulled low).

Table 2-14. Response Packet

Field Size Description

DGI_CMD_TARGET_RESET (0x20) 1 Byte Command ID.

DGI_RESP_OK (0x80) 1 Byte Response code.

2.6. DGI_CMD_INTERFACES_LIST

This command is used to discover the available interfaces on the tool. It will receive a list of all interfaces.

Table 2-15. Command Packet

Field Size Description

DGI_CMD_INTERFACES_LIST (0x08) 1 Byte Command ID.

Length (0) 2 Bytes No parameters.

Table 2-16. Response Packet

Field Size Description

DGI_CMD_INTERFACES_LIST (0x08) 1 Byte Command ID.

DGI_RESP_DATA (0x80) 1 Byte Response code.

Count (n) 1 Byte Number of interfaces in following list.

Interface list n Bytes List of identifiers for available interfaces.

Related Links

Atmel Data Gateway Interface [USER GUIDE]

Atmel-32223A-Data-Gateway-Interface_User Guide-09/2016

7