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 Considered
 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 Adapters, 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, adapters,
 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 Android system and use it as a
 274 bit-banging JTAG Adapter 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  */