149 lines
5.5 KiB
Plaintext
149 lines
5.5 KiB
Plaintext
MSPDebug embedded mode
|
|
|
|
Daniel Beer <dlbeer@gmail.com>
|
|
9 Oct 2012
|
|
|
|
This document describes mspdebug's embedded mode, which makes it easier
|
|
to use it as a back-end to a third-party user interface. The key
|
|
differences between the normal terminal interface and embedded mode are:
|
|
|
|
* Command reading: in embedded mode, commands are read without
|
|
displaying a prompt to the user.
|
|
|
|
* Output processing: rather than directing errors to stderr, all
|
|
output is sent to stdout, so that all messages remain in sync
|
|
relative to one another. Output lines are prefixed with a sigil
|
|
character to indicate their type (error/normal/debug).
|
|
|
|
* Interrupt processing: normally, Ctrl+C or Ctrl+Break sequences can
|
|
be used to interrupt a running command via the SIGINT signal, or a
|
|
console event handler. In embedded mode, a terminal is not
|
|
available, so another method which relies only on standard
|
|
line-oriented IO is provided.
|
|
|
|
* Additional output: additional data is provided which can be used by
|
|
a third-party user interface to improve interaction.
|
|
|
|
These differences are explained in more detail in the following
|
|
sections. To enabled embedded mode, add the --embedded flag to
|
|
mspdebug's command-line arguments.
|
|
|
|
Output processing
|
|
=================
|
|
|
|
In embedded mode, all output is directed to stdout. This ensures that
|
|
the logical streams generated by mspdebug stay in order relative to one
|
|
another when written to an asynchronous pipe.
|
|
|
|
To distinguish the streams, each is prefixed with a single sigil
|
|
character. These sigil characters are:
|
|
|
|
Sigil Output type
|
|
-------- -----------------
|
|
: Normal output
|
|
- Debug output (suppressed in quiet mode)
|
|
! Error messages
|
|
\ Shell messages
|
|
|
|
Another feature of output processing in embedded mode is that when
|
|
colourized output is enabled (``opt color true``), colourization is
|
|
always implemented by including ANSI escape codes in the output, even on
|
|
Windows. Normally, colourized output on Windows is implemented by
|
|
changing console text attributes.
|
|
|
|
Shell messages
|
|
--------------
|
|
|
|
Shell messages are emitted only when in embedded mode. They provide
|
|
additional information to the front-end and consist of a type identifier
|
|
string immediately following the sigil, then optionally a space and
|
|
arguments. Currently, the following shell messages may be emitted:
|
|
|
|
\ready
|
|
|
|
~ The command processor is ready to receive a command.
|
|
|
|
\busy
|
|
|
|
~ The command process has accepted a command and is now executing it.
|
|
|
|
\power-sample-us <period>
|
|
|
|
~ Indicates that power profiling is enabled. The period argument is a
|
|
decimal number giving the sample period in microseconds.
|
|
|
|
\power-samples <data>
|
|
|
|
~ Power data captured from the running device. The data argument is a
|
|
Base64-encoded string. When decoded, it consists of a sequence of
|
|
32-bit little-endian unsigned integers. Integers with bit 31 set are
|
|
MAB values, and those without bit 31 set are current consumption
|
|
readings, in microamps.
|
|
|
|
Input processing and interruption
|
|
=================================
|
|
|
|
A different input processor is used in embedded mode, to allow for
|
|
interruption of running commands without the use of signals or console
|
|
control handlers. When embedded mode is enabled, a prompt is never
|
|
displayed. Lines of text are read from stdin in a separate thread, and
|
|
any commands are posted through to the main thread.
|
|
|
|
The lines of text read are also prefixed with sigils -- either ':' to
|
|
indicate a command, or '\' to indicate a special reader operation. Lines
|
|
of text without a sigil are assumed to be commands.
|
|
|
|
Currently, the only implemented special operation is "\break", which
|
|
raises a break condition to interrupt any running command.
|
|
|
|
End-of-input is signalled by closing stdin. If the command processor is
|
|
running a command when this occurs, it will wait until the command
|
|
finishes before exiting.
|
|
|
|
If a command is sent before the reader is ready to accept one, it is
|
|
discarded. To avoid race conditions, a front end should:
|
|
|
|
* Send a command only after the "\ready" shell message is received,
|
|
and do not send further commands until it has finished executing.
|
|
|
|
* To interrupt a running command by sending a "\break" operation, the
|
|
front-end should first wait until the "\busy" message is received.
|
|
Otherwise, the break condition may be lost.
|
|
|
|
Example
|
|
=======
|
|
|
|
In the following example, arrows are used to indicate text sent to
|
|
mspdebug (=>) and text received from the mspdebug process (<=):
|
|
|
|
$ ./mspdebug --embedded sim -q
|
|
<= \ready
|
|
=> :prog ../fet-fw/20401004.hex
|
|
<= \busy
|
|
<= :Erasing...
|
|
<= :Programming...
|
|
<= :Done, 55472 bytes total
|
|
<= \ready
|
|
=> :reset
|
|
<= \busy
|
|
<= \ready
|
|
=> :run
|
|
<= \busy
|
|
<= :Running. Press Ctrl+C to interrupt...
|
|
=> \break
|
|
<= :
|
|
<= : ( PC: 0c682) ( R4: 00000) ( R8: 00000) (R12: 00000)
|
|
<= : ( SP: 024f2) ( R5: 00000) ( R9: 00000) (R13: 00000)
|
|
<= : ( SR: 0000d) ( R6: 00000) (R10: 0ffff) (R14: 00002)
|
|
<= : ( R3: 00000) ( R7: 00000) (R11: 00000) (R15: 00063)
|
|
<= :0xc682:
|
|
<= : 0c682: 0d 43 CLR R13
|
|
<= : 0c684: 3a 41 POP R10
|
|
<= : 0c686: 30 41 RET
|
|
<= : 0c688: 0a 12 PUSH R10
|
|
<= : 0c68a: 0b 12 PUSH R11
|
|
<= : 0c68c: 08 12 PUSH R8
|
|
<= : 0c68e: 0b 4c MOV R12, R11
|
|
<= : 0c690: 08 4e MOV R14, R8
|
|
<= \ready
|