4310d3655dc028273b6955aea1748fd3c5ba9ca5
[openocd.git] / doc / manual / server.txt
1 /** @page serverdocs OpenOCD Server APIs
2
3 OpenOCD provides support for implementing different types of servers.
4 Presently, the following servers have APIs that can be used.
5
6   - @subpage servergdb
7   - @subpage servertelnet
8   - @subpage serverhttp
9
10 @section serverdocsoverview Overview
11
12 What follows is a development history, and describes some of the intent
13 of why certain features exist within OpenOCD along with the reasoning
14 behind them.
15
16 This roadmap section was written May 2009 - about 9 to 12 months
17 after some of this work had started, it attempts to document some of
18 the reasons why certain features exist within OpenOCD at that time.
19
20 @section serverdocsbg Background
21
22 In early 2008, Oyvind Harboe and Duane Ellis had talked about how to
23 create a reasonable GUI for OpenOCD - something that is non-invasive,
24 simple to use and maintain, and does not tie OpenOCD to many other
25 packages.  It would be wrong to "spider web" requirements into other
26 external external packages.  That makes it difficult for developers to
27 write new code and creates a support nightmare.
28
29 In many ways, people had talked about the need for some type of
30 high-level interface to OpenOCD, because they only had two choices:
31 - the ability to script: via an external program the actions of OpenOCD.
32 - the ablity to write a complex internal commands: native 'commands'
33   inside of OpenOCD was complicated.
34
35 Fundamentally, the basic problem with both of those would be solved
36 with a script language:
37
38 -# <b>Internal</b>: simple, small, and self-contained.
39 -# <b>Cross Language</b>: script friendly front-end
40 -# <b>Cross Host</b>: GUI Host interface
41 -# <b>Cross Debugger</b>: GUI-like interface
42
43 What follows hopefully shows how the plans to solve these problems
44 materialized and help to explain the grand roadmap plan.
45
46 @subsection serverdocsjim Why JimTCL? The Internal Script Language
47
48 At the time, the existing "command context schema" was proving itself
49 insufficient.  However, the problem was also considered from another
50 direction: should OpenOCD be first class and the script second class?
51 Which one rules?
52
53 In the end, OpenOCD won, the conclusion was that simpler will be better.
54 Let the script language be "good enough"; it would not need numerous
55 features.  Imagine debugging an embedded Perl module while debugging
56 OpenOCD. Yuck.  OpenOCD already has a complex enough build system, why
57 make it worse?
58
59 The goal was to add a simple language that would be moderately easy to
60 work with and be self-contained.  JimTCL is a single C and single H
61 file, allowing OpenOCD to avoid the spider web of dependent packages.
62
63 @section serverdocstcl TCL Server Port
64
65 The TCL Server port was added in mid-2008.  With embedded TCL, we can
66 write scripts internally to help things, or we can write "C" code  that
67 interfaces well with TCL.
68
69 From there, the developers wanted to create an external front-end that
70 would be @a very usable and that that @a any language could utilize,
71 allowing simple front-ends to be (a) cross-platform (b) languag
72 agnostic, and (c) easy to develop and use.
73
74 Simple ASCII protocols are easy.  For example, HTTP, FTP (control), and
75 SMTP are all text-based.  All of these examples are widely and
76 well-known, and they do not require high-speed or high-volume.  They
77 also support a high degree of interoperability with multiple systems.
78 They are not human-centric protocols; more correctly, they are rigid,
79 terse, simple ASCII protocols that are emensely parsable by a script.
80
81 Thus, the TCL server -- a 'machine' type socket interface -- was added
82 with the hope was it would output simple "name-value" pair type
83 data.  At the time, simple name/value pairs seemed reasonably easier to
84 do at the time, though Maybe it should output JSON;
85
86 See here:
87
88    http://www.mail-archive.com/openocd-development%40lists.berlios.de/msg00248.html
89
90 The hope was that one could write a script in what ever language you want
91 and do things with it!
92
93 @section serverdocsgui GUI Like Interfaces
94
95 A lot has been said about various "widigit-foo-gui-library is so
96 wonderful".  Please refer back to the domino and spider web problem of
97 dependencies.  Sure, you may well know the WhatEver-GUI library, but
98 most others will not (including the next contributer to OpenOCD).
99 How do we solve that problem?
100
101 For example, Cygwin can be painful, Cygwin GUI packages want X11
102 to be present, crossing the barrier between MinGW and Cygwin is
103 painful, let alone getting the GUI front end to work on MacOS, and
104 Linux, yuck yuck yuck. Painful. very very painful.
105
106 What works easier and is less work is what is already present in every
107 platform?  The answer: A web browser.  In other words, OpenOCD could
108 serve out embedded web pages via "localhost" to your browser.
109
110 Long before OpenOCD had a TCL command line, Zylin AS built their ZY1000
111 devince with a built-in HTTP server.  Later, they were willing to both
112 contribute and integrate most of that work into the main tree.
113
114 @subsection serverdocsother Other Options Concidered
115
116 What if a web browser is not acceptable ie: You want to write your own
117 front gadget in Eclipse, or KDevelop, or PerlTK, Ruby, or what ever
118 the latest and greatest Script De Jour is.
119
120 - Option 1: Can we transport this extra data through the GDB server
121 protocol? In other words, can we extend the GDB server protocol?
122 No, Eclipse wants to talk to GDB directly and control the GDB port.
123
124 - Option 2: SWIG front end (libopenocd): Would that work?
125
126 That's painful - unless you design your api to be very simplistic -
127 every language has it's own set of wack-ness, parameter marshaling is
128 painful.
129
130 What about "callbacks" and structures, and other mess. Imagine
131 debugging that system.  When JimTCL was introduced Spencer Oliver had
132 quite a few well-put concerns (Summer 2008) about the idea of "TCL"
133 taking over OpenOCD.  His concern is and was: how do you debug
134 something written in 2 different languages?  A "SWIG" front-end is
135 unlikely to help that situation.
136
137 @subsection serverdoccombined Combined: Socket & WebServer Benifits
138
139 Seriously think about this question: What script language (or compiled
140 language) today cannot talk directly to a socket? Every thing in the
141 OpenOCD world can work a socket interface. Any host side tool can talk
142 to Localhost or remote host, however one might want to make it work.
143
144 A socket interface is very simple. One could write a Java application
145 and serve it out via the embedded web server, could it - or something
146 like it talk to the built in TCL server? Yes, absolutely! We are on to
147 something here.
148
149 @subsection serverdocplatforms Platform Permuntations
150
151 Look at some permutations where OpenOCD can run; these "just work" if
152 the Socket Approach is used.
153
154
155 - Linux/Cygwin/MinGw/MacOSx/FreeBSD development Host Locally
156 - OpenOCD with some dongle on that host
157
158
159 - Linux/Cygwin/MingW/MacOS/FreeBSD development host
160 - DONGLE:  tcpip based ARM-Linux perhaps at91rm9200 or ep93xx.c, running openocd.
161
162
163 - Windows cygwin/X desktop environment.
164 - Linux development host (via remote X11)
165 - Dongle:  "eb93xx.c" based linux board
166
167
168 @subsection serverdocfuture Development Scale Out
169
170 During 2008, Duane Ellis created some TCL scripts to display peripheral
171 register contents. For example, look at the sam7 TCL scripts, and the
172 stm32 TCL scripts.  The hope was others would create more.
173
174
175 A good example of this is display/view the peripheral registers on
176 your embedded target.  Lots of commercial embedded debug tools have
177 this, some can show the TIMER registers, the interrupt controller.
178
179 What if the chip companies behind STM32, or PIC32, AT91SAM chips -
180 wanted to write something that makes working with their chip better,
181 easier, faster, etc.
182
183 @a Question: How can we (the OpenOCD group) make that really fancy
184 stuff across multiple different host platforms?
185
186 Remember: OpenOCD runs on:
187 -# Linux via USB,
188 -# ARM Linux - bit-banging GPIO pins
189 -# MacOSX
190 -# FreeBSD
191 -# Cygwin
192 -# MinGW32
193 -# Ecos
194
195 How can we get that to work?
196
197 @subsection serverdocdebug What about Debugger Plugins?
198
199 Really GDB is nice, it works, but it is not a good embedded debug tool.
200 OpenOCD cannot work in a GUI when one cannot get to its command line.
201 Some GDB front-end developers have pedantic designs that refuse any and
202 all access to the GDB command line (e.g.  http://www.kdbg.org/todo.php).
203
204 The TELNET interface to OpenOCD works, but the intent of that interface
205 is <b>human interaction</b>. It must remain available, developers depend
206 upon it, sometimes that is the only scheme available.
207
208 As a small group of developers, supporting all the platforms and
209 targets in the debugger will be difficult, as there are enough problem
210 with the plethora of Dongles, Chips, and different target boards.
211 Yes, the TCL interface might be suitable, but it has not received much
212 love or attention.  Perhaps it will after you read and understand this.
213
214 One reason might be, this adds one more host side requirement to make
215 use of the feature.  In other words, one could write a Python/TK
216 front-end, but it is only useable if you have Python/TK installed.
217 Maybe this can be done via Ecllipse, but not all developers use Ecplise.
218 Many devlopers use Emacs (possibly with GUD mode) or vim and will not
219 accept such an interface.  The next developer reading this might be
220 using Insight (GDB-TK) - and somebody else - DDD..
221
222 There is no common host-side GDB front-end method.
223
224 @section serverdocschallenge Front-End Scaling
225
226 Maybe we are wrong - ie: OpenOCD + some TK tool
227
228 Remember: OpenOCD is often (maybe 99.9%) of the time used with
229 GDB-REMOTE.  There is always some front-end package - be it command-line
230 GDB under DDD, Eclipse, KDevelop, Emacs, or some other package
231 (e.g. IAR tools can talk to GDB servers).  How can the OpenOCD
232 developers make that fancy target display GUI visible under 5 to 10
233 different host-side GDB..
234
235 Sure - a <em>man on a mission</em> can make that work.  The GUI might be
236 libopenocd + Perl/TK, or maybe an Eclipse Plug-in.
237 That is a development support nightmare for reasons described
238 above. We have enough support problems as it is with targets, dongles,
239 etc.
240
241 @section serverdocshttpbg HTTP Server Background
242
243 OpenOCD includes an HTTP server because most development environments
244 are likely contain a web browser.  The web browser can talk to OpenOCD's
245 HTTP server and provide a high-level interfaces to the program.
246 Altogether, it provides a universally accessible GUI for OpenOCD.
247
248 @section serverdocshtml Simple HTML Pages
249
250 There is (or could be) a simple "Jim TCL" function to read a memory
251 location. If that can be tied into a TCL script that can modify the
252 HTTP text, then we have a simple script-based web server with a JTAG
253 engine under the hood.
254
255 Imagine a web page - served from a small board with two buttons:
256 "LED_ON" and "LED_OFF", each click - turns the LED on or OFF, a very
257 simplistic idea.  Little boards with web servers are great examples of
258 this: Ethernut is a good example and Contiki (not a board, an embedded
259 OS) is another example.
260
261 One could create a simple: <b>Click here to display memory</b> or maybe
262 <b>click here to display the UART REGISTER BLOCK</b>; click again and see
263 each register explained in exquisit detail.
264
265 For an STM32, one could create a simple HTML page, with simple
266 substitution text that the simple web server use to substitute the
267 HTML text JIMTCL_PEEK32( 0x12345678 ) with the value read from
268 memory. We end up with an HTML page that could list the contents of
269 every peripheral register on the target platform.
270
271 That also is transportable, regardless of the OpenOCD host
272 platform: Linux/X86, Linux/ARM, FreeBSD, Cygwin, MingW, or MacOSX.
273 You could even port OpenOCD to an Google Android and use it as a
274 bit-bang dongle JTAG serving web pages.
275
276 @subsection serverdocshtmladv Advanced HTML Pages
277
278 Java or JavaScript could be used to talk back to the TCL port.  One
279 could write a Java, AJAX, FLASH, or some other developer friendly
280 toolbox and get a real cross-platform GUI interface. Sure, the interface
281 is not native - but it is 100% cross-platform!
282
283 OpenOCD current uses simple HTML pages; others might be an Adobe FLASH
284 expert, or a Java Expert.  These possibilities could allow the pages
285 remain cross-platform but still provide a rich user-interface
286 experience.
287
288 Don't forget it can also be very simple, exactly what one developer
289 can contribute, a set of very simple web pages.
290
291 @subsection serverdocshtmlstatus HTTP/HTML Status
292
293 As of May 2009, much of the HTML pages were contributed by Zylin AS,
294 hence they continue to retain some resemblance to the ZY1000 interface.
295
296 Patches would be welcome to move these parts of the system forward.
297
298  */
299
300 /** @page servergdb OpenOCD GDB Server API
301
302 This section needs to be expanded.
303
304  */
305
306 /** @page servertelnet OpenOCD Telnet Server API
307
308 This section needs to be expanded.
309
310  */
311
312 /** @page serverhttp OpenOCD HTTP Server API
313
314 This section needs to be expanded.
315
316  */