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.

81 lines
3.1 KiB

  1. Plan for hosted scripting support in OpenOCD
  2. ============================================
  3. What scripting will not do
  4. ==========================
  5. It is not the intention that normal OpenOCD users will
  6. use tcl scripting extensively, write lots of clever scripts,
  7. or contribute back to OpenOCD.
  8. The scripting support is intended for developers of OpenOCD.
  9. Target scripts can contain new procedures that end users may
  10. tinker to their needs without really understanding tcl.
  11. Since end users are not expected to mess with the scripting
  12. language, the choice of language is not terribly important
  13. to those same end users.
  14. Jim Tcl was chosen as it was easy to integrate, works
  15. great in an embedded environment and √ėyvind Harboe
  16. had experience with it.
  17. Uses of scripting
  18. =================
  19. Default implementation of procedures in tcl/procedures.tcl.
  20. - Polymorphic commands for target scripts.
  21. - there will be added some commands in Tcl that the target
  22. scripts can replace.
  23. - produce <productionfile> <serialnumber>. Default implementation
  24. is to ignore serial number and write a raw binary file
  25. to beginning of first flash. Target script can dictate
  26. file format and structure of serialnumber. Tcl allows
  27. an argument to consit of e.g. a list so the structure of
  28. the serial number is not limited to a single string.
  29. - reset handling. Precise control of how srst, trst &
  30. tms is handled.
  31. - replace some parts of the current command line handler.
  32. This is only to simplify the implementation of OpenOCD
  33. and will have no externally visible consequences.
  34. Tcl has an advantage in that it's syntax is backwards
  35. compatible with the current OpenOCD syntax.
  36. - external scripting. Low level tcl functions will be defined
  37. that return machine readable output. These low level tcl
  38. functions constitute the tcl api. flash_banks is such
  39. a low level tcl proc. "flash banks" is an example of
  40. a command that has human readable output. The human
  41. readable output is expected to change inbetween versions
  42. of OpenOCD. The output from flash_banks may not be
  43. in the preferred form for the client. The client then
  44. has two choices a) parse the output from flash_banks
  45. or b) write a small piece of tcl to output the
  46. flash_banks output to a more suitable form. The latter may
  47. be simpler.
  48. External scripting
  49. ==================
  50. The embedded Jim Tcl interpreter in OpenOCD is very limited
  51. compared to any full scale PC hosted scripting language.
  52. The goal is to keep the internal Jim Tcl interpreter as
  53. small as possible and allow any advanced scripting,
  54. especially scripting that interacts with the host,
  55. run on the host and talk to OpenOCD via the TCP/IP
  56. scripting connection.
  57. Another problem with Jim Tcl is that there is no debugger
  58. for it.
  59. With a bit of trickery it should be possible to run Jim
  60. Tcl scripts under a Tcl interpreter on a PC. The advantage
  61. would be that the Jim Tcl scripts could be debugged using
  62. a standard PC Tcl debugger.
  63. The rough idea is to write an unknown proc that sends
  64. unknown commands to OpenOCD.
  65. Basically a PC version of startup.tcl. Patches most
  66. gratefully accepted! :-)