kmd communications protocol

All communication is controlled by the front-end controller which sends commands to the back-end and expects the appropriate response. In the case of a response being detectably wrong or timing out it is the front-end s job to re-establish/resynchronise the protocol and recover.

Commands sent are single bytes with a variable number of parameters following.

In the following descriptions these definitions apply: Byte: 8 bits, Halfword: 16 bits, Word: 32 bits, Double word 64 bits, Pointer: 32 bits (ARM).

Commands are divided into sets on the most significant two bits as follows:

Command Use
00xx xxxx General operations
01xx xxxx Memory transfers
10xx xxxx Programme execution
11xx xxxx Auxiliary functions

General operations are functions which establish and maintain communications with the target unit, setting breakpoints et al. They are also used for downloading configuration files to board features such as FPGAs.

Memory transfers are used for up- and down-loading the states in the address spaces of the target unit. All accessible state (memories, registers, etc.) is mapped into one of these addressable spaces.

Programme execution is used to start execution and set various options such as single stepping or breakpoints.

Auxiliary functions are reserved for future expansion.

General operations:

Command Meaning
0000 xxxx Board level communications
0001 xxxx Board `feature' communications
0010 xxxx Programme execution control extras
0011 xxxx Breakpoint/watchpoint manipulation

Board level communications:

Command Function Parameters Return values
0000 0000 No operation None None
0000 0001 "Ping" - resynchronise None W: OK?? ?? is the software version - initially 00
0000 0010 Board definition None H: message length
B: processor type
H: processor subtype
B: feature count
B: feature ID
H: feature sub-ID
B: memory segment count
W: memory segment address
W: memory segment length
0000 0011 Reserved    
0000 0100 Reset None None
0000 0101+ Reserved    

Board feature/subfeature definitions

Feature Subfeature
00 Terminal --- ---
01-10 Not defined --- ---
11 Xilinx Spartan XL 05xx


12 Xilinx Virtex 05xx


13 Xilinx Virtex E as Virtex (#12) as Virtex (#12)
14-FF Not defined --- ---

Board `feature' communications:

Command Function Parameters Return values
0001 0000 Get Status B: Feature number W: Status
(Currently always 0)
0001 0001 Set Status B: Feature number
W: Status
(Currently ignored)
0001 0010 Send message B: Feature number
B: Length
Specified number of bytes
B: Number of bytes accepted
0001 0011 Get message B: Feature number
B: Max. length
B: Actual length
Specified number of bytes.
0001 0100 Download Header B: Feature number
W: Length of file
B: 'A' if successful/'N if feature unrecognised
0001 0101 Download Packet B: Feature number
B: Packet length (1-256)
Specified number of bytes.
B: 'A' if successful/'N if unsuccessful
0001 0110+ Reserved B: Feature number ---

Device download is instigated by sending a header to the appropriate feature. In the case of an FPGA this initialises the device and readies it to receive a new programme. Subsequently a number of packets should be sent with a total length equal to the specified file length. (Packets beyond this length will be ignored.)

Programme execution control extras

Command Function Parameters Return values
0010 0000 What is executing? None B: Execution status
W: Number of steps `remaining'
W: Number of steps since reset
0010 0001 Stop execution None None
0010 0010 Pause execution None None
0010 0011 Continue execution None None
0010 0100 Set runtime flags B: xxxx xxIF None
0010 0101 Get runtime flags None B: xxxx xxIF
0010 0110+ Reserved --- ---

Execution status Meaning
00 Reset
01 Busy - go away!
40 Stopped
41 Stopped due to breakpoint
42 Stopped due to watchpoint
43 Stopped due to memory fault
44 Stopped by programme request
80 Running normally
81 Servicing a SWI
8? Servicing ???
C0-FF Error codes

Trap manipulation

Command Function Parameters Return values
0011 bb00 Define trap B: trap number
B: trap conditions
B: trap sizes
W: trap address A
W: trap address B
D: trap data A
D: trap data B
0011 bb01 Read trap definition B: trap number B: trap conditions
B: trap sizes
W: trap address A
W: trap address B
D: trap data A
D: trap data B
0011 bb10 Set trap status W: bitmask1
W: bitmask0
0011 bb11 Read trap status None W: bitmask1
W: bitmask0

The actual class of trap is defined by the two bits "bb":

bb Meaning
00 Breakpoint (instruction fetch)
01 Watchpoint (data transfer)
01 Register
01 Reserved
There may be the 'obvious' error in this table. TBC

The trap conditions are set up as follows:

Trap condition Meaning
Uxxx xxxx 0: do not trap if in user mode
1: may trap if in user mode
xPxx xxxx 0: do not trap if in privileged mode
1: may trap if in privileged mode
xxRW xxxx 00: do not trap
01: trap only on write accesses
10: trap only on read accesses
11: may trap on any transfer
xxxx AAxx 0x: reserved
10: may trap if addrA <= addr <= addrB
11: may trap if addr AND addrB = addrA
xxxx xxDD 0x: reserved
10: may trap if dataA <= data <= dataB
11: may trap if data AND dataB = dataA

These allow a flexible range of conditions to be set up. Note that not all conditions may be supported in all cases.

Transfer size mask Meaning
xxxx Sxxx Trap on 64-bit accesses
xxxx xSxx Trap on 32-bit accesses
xxxx xxSx Trap on 16-bit accesses
xxxx xxxS Trap on 8-bit accesses

When activating of deactivating traps all the traps (of a given type) can be manipulated with a single command. The trap is defined by the two bits with the appropriate bit numbers.

bitmask1:bitmask0 Meaning when written Meaning when read
0:0 No operation Not implemented
0:1 Delete definition Implemented but not defined
1:0 Inactivate Inactive
1:1 Activate Active

Thus the parameters 00000005:00000003 would inactivate trap #2, delete trap #1 and activate trap #0; an undefined trap will not be activated.

Memory transfers

Memory transfers are specified by the command word as follows:
mm indicates the address space used:

mm Meaning
00 Memory address space
01 Registers
1x Reserved

d indicates the direction:

d Meaning
0 Write (0utput from user)
1 Read (1nput to user)

sss indicates the transfer element size:

sss Meaning
000 8 bit
001 16 bit
010 32 bit
011 64 bit
1xx Reserved

All memory transaction commands are followed by two parameters: These are then followed by the designated number of elements of the designated size in the appropriate direction.
The address will be incremented to the next element remotely.
All transfers are little endian, so that a serial line will assume least significant byte first.

Programme execution

Run is a single byte command used to start execution on the remote processor. It is encoded as follows, where each bit 0/1 means disabled/enabled respectively: Run commands are always followed by a single, word parameter which indicates the maximum number of steps to execute; 00000000 is a special case which indicates unlimited steps.

Auxiliary functions

None of these is yet defined.