diff --git a/doc/manual/server.txt b/doc/manual/server.txt index 2379a93cb..2e5aaf3b7 100644 --- a/doc/manual/server.txt +++ b/doc/manual/server.txt @@ -7,7 +7,293 @@ Presently, the following servers have APIs that can be used. - @subpage servertelnet - @subpage serverhttp -This section needs to be expanded. +@section serverdocsoverview Overview + +What follows is a development history, and describes some of the intent +of why certain features exist within OpenOCD along with the reasoning +behind them. + +This roadmap section was written May 2009 - about 9 to 12 months +after some of this work had started, it attempts to document some of +the reasons why certain features exist within OpenOCD at that time. + +@section serverdocsbg Background + +In early 2008, Oyvind Harboe and Duane Ellis had talked about how to +create a reasonable GUI for OpenOCD - something that is non-invasive, +simple to use and maintain, and does not tie OpenOCD to many other +packages. It would be wrong to "spider web" requirements into other +external external packages. That makes it difficult for developers to +write new code and creates a support nightmare. + +In many ways, people had talked about the need for some type of +high-level interface to OpenOCD, because they only had two choices: +- the ability to script: via an external program the actions of OpenOCD. +- the ablity to write a complex internal commands: native 'commands' + inside of OpenOCD was complicated. + +Fundamentally, the basic problem with both of those would be solved +with a script language: + +-# Internal: simple, small, and self-contained. +-# Cross Language: script friendly front-end +-# Cross Host: GUI Host interface +-# Cross Debugger: GUI-like interface + +What follows hopefully shows how the plans to solve these problems +materialized and help to explain the grand roadmap plan. + +@subsection serverdocsjim Why JimTCL? The Internal Script Language + +At the time, the existing "command context schema" was proving itself +insufficient. However, the problem was also considered from another +direction: should OpenOCD be first class and the script second class? +Which one rules? + +In the end, OpenOCD won, the conclusion was that simpler will be better. +Let the script language be "good enough"; it would not need numerous +features. Imagine debugging an embedded Perl module while debugging +OpenOCD. Yuck. OpenOCD already has a complex enough build system, why +make it worse? + +The goal was to add a simple language that would be moderately easy to +work with and be self-contained. JimTCL is a single C and single H +file, allowing OpenOCD to avoid the spider web of dependent packages. + +@section serverdocstcl TCL Server Port + +The TCL Server port was added in mid-2008. With embedded TCL, we can +write scripts internally to help things, or we can write "C" code that +interfaces well with TCL. + +From there, the developers wanted to create an external front-end that +would be @a very usable and that that @a any language could utilize, +allowing simple front-ends to be (a) cross-platform (b) languag +agnostic, and (c) easy to develop and use. + +Simple ASCII protocols are easy. For example, HTTP, FTP (control), and +SMTP are all text-based. All of these examples are widely and +well-known, and they do not require high-speed or high-volume. They +also support a high degree of interoperability with multiple systems. +They are not human-centric protocols; more correctly, they are rigid, +terse, simple ASCII protocols that are emensely parsable by a script. + +Thus, the TCL server -- a 'machine' type socket interface -- was added +with the hope was it would output simple "name-value" pair type +data. At the time, simple name/value pairs seemed reasonably easier to +do at the time, though Maybe it should output JSON; + +See here: + + http://www.mail-archive.com/openocd-development%40lists.berlios.de/msg00248.html + +The hope was that one could write a script in what ever language you want +and do things with it! + +@section serverdocsgui GUI Like Interfaces + +A lot has been said about various "widigit-foo-gui-library is so +wonderful". Please refer back to the domino and spider web problem of +dependencies. Sure, you may well know the WhatEver-GUI library, but +most others will not (including the next contributer to OpenOCD). +How do we solve that problem? + +For example, Cygwin can be painful, Cygwin GUI packages want X11 +to be present, crossing the barrier between MinGW and Cygwin is +painful, let alone getting the GUI front end to work on MacOS, and +Linux, yuck yuck yuck. Painful. very very painful. + +What works easier and is less work is what is already present in every +platform? The answer: A web browser. In other words, OpenOCD could +serve out embedded web pages via "localhost" to your browser. + +Long before OpenOCD had a TCL command line, Zylin AS built their ZY1000 +devince with a built-in HTTP server. Later, they were willing to both +contribute and integrate most of that work into the main tree. + +@subsection serverdocsother Other Options Concidered + +What if a web browser is not acceptable ie: You want to write your own +front gadget in Eclipse, or KDevelop, or PerlTK, Ruby, or what ever +the latest and greatest Script De Jour is. + +- Option 1: Can we transport this extra data through the GDB server +protocol? In other words, can we extend the GDB server protocol? +No, Eclipse wants to talk to GDB directly and control the GDB port. + +- Option 2: SWIG front end (libopenocd): Would that work? + +That's painful - unless you design your api to be very simplistic - +every language has it's own set of wack-ness, parameter marshaling is +painful. + +What about "callbacks" and structures, and other mess. Imagine +debugging that system. When JimTCL was introduced Spencer Oliver had +quite a few well-put concerns (Summer 2008) about the idea of "TCL" +taking over OpenOCD. His concern is and was: how do you debug +something written in 2 different languages? A "SWIG" front-end is +unlikely to help that situation. + +@subsection serverdoccombined Combined: Socket & WebServer Benifits + +Seriously think about this question: What script language (or compiled +language) today cannot talk directly to a socket? Every thing in the +OpenOCD world can work a socket interface. Any host side tool can talk +to Localhost or remote host, however one might want to make it work. + +A socket interface is very simple. One could write a Java application +and serve it out via the embedded web server, could it - or something +like it talk to the built in TCL server? Yes, absolutely! We are on to +something here. + +@subsection serverdocplatforms Platform Permuntations + +Look at some permutations where OpenOCD can run; these "just work" if +the Socket Approach is used. + + +- Linux/Cygwin/MinGw/MacOSx/FreeBSD development Host Locally +- OpenOCD with some dongle on that host + + +- Linux/Cygwin/MingW/MacOS/FreeBSD development host +- DONGLE: tcpip based ARM-Linux perhaps at91rm9200 or ep93xx.c, running openocd. + + +- Windows cygwin/X desktop environment. +- Linux development host (via remote X11) +- Dongle: "eb93xx.c" based linux board + + +@subsection serverdocfuture Development Scale Out + +During 2008, Duane Ellis created some TCL scripts to display peripheral +register contents. For example, look at the sam7 TCL scripts, and the +stm32 TCL scripts. The hope was others would create more. + + +A good example of this is display/view the peripheral registers on +your embedded target. Lots of commercial embedded debug tools have +this, some can show the TIMER registers, the interrupt controller. + +What if the chip companies behind STM32, or PIC32, AT91SAM chips - +wanted to write something that makes working with their chip better, +easier, faster, etc. + +@a Question: How can we (the OpenOCD group) make that really fancy +stuff across multiple different host platforms? + +Remember: OpenOCD runs on: +-# Linux via USB, +-# ARM Linux - bit-banging GPIO pins +-# MacOSX +-# FreeBSD +-# Cygwin +-# MinGW32 +-# Ecos + +How can we get that to work? + +@subsection serverdocdebug What about Debugger Plugins? + +Really GDB is nice, it works, but it is not a good embedded debug tool. +OpenOCD cannot work in a GUI when one cannot get to its command line. +Some GDB front-end developers have pedantic designs that refuse any and +all access to the GDB command line (e.g. http://www.kdbg.org/todo.php). + +The TELNET interface to OpenOCD works, but the intent of that interface +is human interaction. It must remain available, developers depend +upon it, sometimes that is the only scheme available. + +As a small group of developers, supporting all the platforms and +targets in the debugger will be difficult, as there are enough problem +with the plethora of Dongles, Chips, and different target boards. +Yes, the TCL interface might be suitable, but it has not received much +love or attention. Perhaps it will after you read and understand this. + +One reason might be, this adds one more host side requirement to make +use of the feature. In other words, one could write a Python/TK +front-end, but it is only useable if you have Python/TK installed. +Maybe this can be done via Ecllipse, but not all developers use Ecplise. +Many devlopers use Emacs (possibly with GUD mode) or vim and will not +accept such an interface. The next developer reading this might be +using Insight (GDB-TK) - and somebody else - DDD.. + +There is no common host-side GDB front-end method. + +@section serverdocschallenge Front-End Scaling + +Maybe we are wrong - ie: OpenOCD + some TK tool + +Remember: OpenOCD is often (maybe 99.9%) of the time used with +GDB-REMOTE. There is always some front-end package - be it command-line +GDB under DDD, Eclipse, KDevelop, Emacs, or some other package +(e.g. IAR tools can talk to GDB servers). How can the OpenOCD +developers make that fancy target display GUI visible under 5 to 10 +different host-side GDB.. + +Sure - a man on a mission can make that work. The GUI might be +libopenocd + Perl/TK, or maybe an Eclipse Plug-in. +That is a development support nightmare for reasons described +above. We have enough support problems as it is with targets, dongles, +etc. + +@section serverdocshttpbg HTTP Server Background + +OpenOCD includes an HTTP server because most development environments +are likely contain a web browser. The web browser can talk to OpenOCD's +HTTP server and provide a high-level interfaces to the program. +Altogether, it provides a universally accessible GUI for OpenOCD. + +@section serverdocshtml Simple HTML Pages + +There is (or could be) a simple "Jim TCL" function to read a memory +location. If that can be tied into a TCL script that can modify the +HTTP text, then we have a simple script-based web server with a JTAG +engine under the hood. + +Imagine a web page - served from a small board with two buttons: +"LED_ON" and "LED_OFF", each click - turns the LED on or OFF, a very +simplistic idea. Little boards with web servers are great examples of +this: Ethernut is a good example and Contiki (not a board, an embedded +OS) is another example. + +One could create a simple: Click here to display memory or maybe +click here to display the UART REGISTER BLOCK; click again and see +each register explained in exquisit detail. + +For an STM32, one could create a simple HTML page, with simple +substitution text that the simple web server use to substitute the +HTML text JIMTCL_PEEK32( 0x12345678 ) with the value read from +memory. We end up with an HTML page that could list the contents of +every peripheral register on the target platform. + +That also is transportable, regardless of the OpenOCD host +platform: Linux/X86, Linux/ARM, FreeBSD, Cygwin, MingW, or MacOSX. +You could even port OpenOCD to an Google Android and use it as a +bit-bang dongle JTAG serving web pages. + +@subsection serverdocshtmladv Advanced HTML Pages + +Java or JavaScript could be used to talk back to the TCL port. One +could write a Java, AJAX, FLASH, or some other developer friendly +toolbox and get a real cross-platform GUI interface. Sure, the interface +is not native - but it is 100% cross-platform! + +OpenOCD current uses simple HTML pages; others might be an Adobe FLASH +expert, or a Java Expert. These possibilities could allow the pages +remain cross-platform but still provide a rich user-interface +experience. + +Don't forget it can also be very simple, exactly what one developer +can contribute, a set of very simple web pages. + +@subsection serverdocshtmlstatus HTTP/HTML Status + +As of May 2009, much of the HTML pages were contributed by Zylin AS, +hence they continue to retain some resemblance to the ZY1000 interface. + +Patches would be welcome to move these parts of the system forward. */