You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

317 lines
13 KiB

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