/
EmbeddedMode.txt
148 lines (115 loc) · 5.51 KB
/
EmbeddedMode.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
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