Home ·

Connection QML Type

The Connection type represents a physical connection to a programmable device. More...

Import Statement: import SAMBA 3.2
Inherited By:

JLinkConnection and SerialConnection

Properties

Signals

Methods

Detailed Description

This type contains methods to communicate with a device:

It is only intended to define the method prototypes and does not communicate with anything. Please use any of the types that inherit from Connection for actual usable implementations.

Reading and Writing Memory

The following methods are provided to read and write to memory:

NameDescription
readReads a memory block
readu8Reads single unsigned byte
readu16Reads single unsigned 16-bit word
readu32Reads single unsigned 32-bit word
writeWrites a memory block
writeu8Writes single unsigned byte
writeu16Writes single unsigned 16-bit word
writeu32Writes single unsigned 32-bit word

For example, to read a 32-bit unsigned word at address 0x12345678:

var data = connection.readu32(0x12345678)

To write unsigned 32-bit value 0x42 to address 0x12345678:

connection.writeu32(0x12345678, 0x42)

Executing Code

The go method can be used to execute code on the device. It make the CPU jump to the given address. Please note that depending on the communication method, the executed code may have to give the control back to its caller. SAM-BA Applets contain such code to give back control to SAM-BA Monitor.

For example, to execute code at address 0x12345678:

connection.go(0x12345678)

Loading and Running Applets

The Connection type also contains methods to load and execute applets (see Applet for more information on SAM-BA applets). The methods related to applet handling are:

NameDescription
appletUploadUpload the applet code to the device
appletMailboxReadReads single unsigned 32-bit word from the mailbox
appletBufferReadReads a block from the applet buffer
appletBufferWriteWrites a block into the applet buffer
appletExecuteWrites parameters in the applet mailbox and execute the applet code

For example, to load and initialize an applet:

connection.appletUpload(applet)
connection.appletExecute("init")

This example assumes that:

To read a 0x42 bytes block at offset 0x1234 from a "memory" applet:

connection.appletExecute("read", [ connection.applet.bufferAddr, 0x42, 0x1234 ])
var block = connection.appletBufferRead(0x42)

This example assumes that:

Property Documentation

aliases : var

The connection aliases (alternate names that can be used on the command-line)


applet : var

The current applet, or undefined if no applet is loaded.


appletConnectionType : var

The connection type value passed at applet initialization


autoConnect : bool

Connection automatic connection flag

Whether the connection should be automatically established once the Connection QML object is ready.


autoDeviceInit : bool

Connection automatic device initialization flag

Whether the device initialize() function should be automatically called once the connection is opened.


device : var

Device whose applets will be used


mailbox : var

The applet mailbox, or undefined if the applet has not been executed yet.


name : var

The connection name


priority : var

The connection priority value

The connection with the lowest priority is selected by default when no connection parameter is provided on the command-line.


Signal Documentation

connectionClosed()

This signal is triggered when the connection has been closed.


connectionFailed(string message)

This signal is triggered when the connection failed to open.

The message parameter contains the failure cause.


connectionOpened()

This signal is triggered when the connection has been opened successfully.


Method Documentation

ByteArray appletBufferRead(int length)

Reads length bytes from the applet buffer.

Returns the data on success, undefined if an error occurred or if the requested length is greater than the current applet buffer size.


bool appletBufferWrite(ByteArray data)

Writes data into the applet buffer.

Returns true on success, false if an error occurred or if the data length is greater than the current applet buffer.


int appletExecute(AppletCommand command, var arguments)

Execute applet command with arguments and poll for completion until the command has completed or its timeout is expired.

Arguments can be supplied a single integer if there is only one argument, or an array of integers if multiple arguments are needed.

After an applet command is started, the Connection will poll for applet completion until the requested timeout is expired.

Returns the applet return code. Zero (0) is usually means success and anything else is an error. The values of the error codes are applet-specific. No value is returned if no applet is loaded, if the arguments types are invalid or if the applet command has not completed before the timeout was reached.


int appletMailboxRead(int index)

Reads unsigned 32-bit word at index index in the applet mailbox.


bool appletMailboxReceive(int timeout)

Receive the content of the applet mailbox.

Returns true on success, false otherwise.


bool appletMailboxSend()

Send the content of the applet mailbox.

Returns true on success, false otherwise.


bool appletUpload(Applet applet)

Uploads an applet to the device.

The applet code is written at the applet codeAddr but no code is executed.

Returns true on success, false otherwise.


void close()

Closes the connection.

The connectionClosed signal will be raised when the connection is closed.


void defaultAppletExecute(AppletCommand command, var arguments)

Default implementation for Connection::appletExecute()

Returns the applet return code. No value is returned if no applet is loaded, if the arguments types are invalid or if the applet command has not completed before the timeout was reached.


bool go(int address)

Execute code at address address.

Returns true on success, false otherwise.


void initializeApplet(string appletName)

Loads and initializes the appletName applet for the currently selected device.

Throws an Error if the applet is not found or could not be loaded/initialized.


void open()

Opens the connection.

On success, the connectionOpened signal will be raised. If an error occurrs, the connectionFailed signal will be raised with the failure cause as argument.


ByteArray read(int address, int length)

Read length bytes at address address.

Returns a ByteArray with the data or undefined if an error occured or if no data could be read after timeout milliseconds.


int readu8(int address, int timeout)

Read a single unsigned byte at the given address.

Returns the unsigned byte read at address or undefined if an error occured or if no value could be read after timeout milliseconds.


int readu16(int address, int timeout)

Read a single unsigned 16-bit word at the given address.

Returns the unsigned 16-bit word read at address or undefined if an error occured or if no value could be read after timeout milliseconds.


int readu32(int address, int timeout)

Read a single unsigned 32-bit word at the given address.

Returns the unsigned 32-bit word read at address or undefined if an error occured or if no value could be read after timeout milliseconds.


bool toSecureMonitor()

Tells whether we connect to the secure SAM-BA monitor.

Returns true if the connection is established to the secure SAM-BA monitor, false otherwise.


bool waitForMonitor(int timeout)

Wait timeout milliseconds for monitor to be ready

Some connection plugins do no implement this feature and will return true even when the monitor is not yet ready.

Returns true on success, false otherwise.


bool write(int address, ByteArray data)

Write byte array data at address address.

Returns true on success, false otherwise.


bool writeu8(int address, int data)

Write unsigned byte data at address address.

Returns true on success, false otherwise.


bool writeu16(int address, int data)

Write unsigned 16-bit word data at address address.

Returns true on success, false otherwise.


bool writeu32(int address, int data)

Write unsigned 32-bit word data at address address.

Returns true on success, false otherwise.



Copyright © 2018 Microchip Technology
SAM-BA Documentation