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.
 
 
 
 
 
 

431 lines
12 KiB

  1. ****************************************
  2. ****************************************
  3. This is a short introduction to 'un-scare' you about the language
  4. known as TCL. It is structured as a guided tour through the files
  5. written by me [Duane Ellis] - in early July 2008 for OpenOCD.
  6. Which uses the "JIM" embedded Tcl clone-ish language.
  7. Thing described here are *totally* TCL generic... not Jim specific.
  8. The goal of this document is to encourage you to add your own set of
  9. chips to the TCL package - and most importantly you should know where
  10. you should put them - so they end up in an organized way.
  11. --Duane Ellis.
  12. duane@duaneellis.com
  13. ****************************************
  14. ****************************************
  15. Adding "chip" support - Duane Ellis July 5 - 2008.
  16. The concept is this:
  17. In your "openocd.cfg" file add something like this:
  18. source [find tcl/chip/VENDOR/FAMILY/NAME.tcl]
  19. For example...
  20. source [find tcl/chip/atmel/at91/at91sam7x256.tcl]
  21. You'll notice that it makes use of:
  22. tcl/cpu/arm/<NAME>.tcl.
  23. Yes, that is where you should put "core" specific things.
  24. Be careful and learn the difference:
  25. THE "CORE" - is not the entire chip!
  26. Definition:
  27. That "file" listed above is called a "CHIP FILE".
  28. It may be standalone, or may need to "source" other "helper" files.
  29. The reference [7/5/2008] is the at91sam7x256.tcl file.
  30. ****************************************
  31. ****************************************
  32. === TCL TOUR ===
  33. Open: at91sam7x256.tcl
  34. === TCL TOUR ===
  35. A walk through --- For those who are new to TCL.
  36. Examine the file: at91sam7x256.tcl
  37. It starts with:
  38. source [find path/filename.tcl]
  39. In TCL - this is very important.
  40. Rule #1 Everything is a string.
  41. Rule #2 If you think other wise See #1.
  42. Reminds you of:
  43. Rule #1: The wife is correct.
  44. Rule #2: If you think otherwise, See #1
  45. Any text contained inside of [square-brackets]
  46. is just like `back-ticks` in BASH.
  47. Hence, the [find FILENAME] executes the command find with a single
  48. parameter the filename.
  49. ========================================
  50. Next you see a series of:
  51. set NAME VALUE
  52. It is mostly "obvious" what is going on.
  53. Exception: The arrays.
  54. You would *THINK* Tcl supports arrays.
  55. In fact, multi-dim arrays. That is false.
  56. For the index for"FLASH(0,CHIPSELECT)" is actually the string
  57. "0,CHIPSELECT". This is problematic. In the normal world, you think
  58. of array indexes as integers.
  59. For example these are different:
  60. set foo(0x0c) 123
  61. set foo(12) 444
  62. Why? Because 0x0c {lowercase} is a string.
  63. Don't forget UPPER CASE.
  64. You must be careful - always... always... use simple decimal
  65. numbers. When in doubt use 'expr' the evaluator. These are all the
  66. same.
  67. set x 0x0c
  68. set foo([expr $x]) "twelve"
  69. set x 12
  70. set foo([expr $x]) "twelve"
  71. set x "2 * 6"
  72. set foo([expr $x]) "twelve"
  73. **************************************************
  74. ***************************************************
  75. === TCL TOUR ===
  76. Open the file: "bitsbytes.tcl"
  77. There is some tricky things going on.
  78. ===============
  79. First, there is a "for" loop - at level 0
  80. {level 0 means: out side of a proc/function}
  81. This means it is evaluated when the file is parsed.
  82. == SIDEBAR: About The FOR command ==
  83. In TCL, "FOR" is a funny thing, it is not what you think it is.
  84. Syntactically - FOR is a just a command, it is not language
  85. construct like for(;;) in C...
  86. The "for" command takes 4 parameters.
  87. (1) The "initial command" to execute.
  88. (2) the test "expression"
  89. (3) the "next command"
  90. (4) the "body command" of the FOR loop.
  91. Notice I used the words "command" and "expression" above.
  92. The FOR command:
  93. 1) executes the "initial command"
  94. 2) evaluates the expression if 0 it stops.
  95. 3) executes the "body command"
  96. 4) executes the "next command"
  97. 5) Goto Step 2.
  98. As show, each of these items are in {curly-braces}. This means they
  99. are passed as they are - KEY-POINT: un evaluated to the FOR
  100. command. Think of it like escaping the backticks in Bash so that the
  101. "under-lying" command can evaluate the contents. In this case, the FOR
  102. COMMAND.
  103. == END: SIDEBAR: About The FOR command ==
  104. You'll see two lines:
  105. LINE1:
  106. set vn [format "BIT%d" $x]
  107. Format is like "sprintf". Because of the [brackets], it becomes what
  108. you think. But here's how:
  109. First - the line is parsed - for {braces}. In this case, there are
  110. none. The, the parser looks for [brackets] and finds them. The,
  111. parser then evaluates the contents of the [brackets], and replaces
  112. them. It is alot this bash statement.
  113. EXPORT vn=`date`
  114. LINE 2 & 3
  115. set $vn [expr (1024 * $x)]
  116. global $vn
  117. In line 1, we dynamically created a variable name. Here, we are
  118. assigning it a value. Lastly Line 3 we force the variable to be
  119. global, not "local" the the "for command body"
  120. ===============
  121. The PROCS
  122. proc create_mask { MSB LSB } {
  123. ... body ....
  124. }
  125. Like "for" - PROC is really just a command that takes 3 parameters.
  126. The (1) NAME of the function, a (2) LIST of parameters, and a (3) BODY
  127. Again, this is at "level 0" so it is a global function. (Yes, TCL
  128. supports local functions, you put them inside of a function}
  129. You'll see in some cases, I nest [brackets] alot and in others I'm
  130. lazy or wanted it to be more clear... it is a matter of choice.
  131. ===============
  132. **************************************************
  133. ***************************************************
  134. === TCL TOUR ===
  135. Open the file: "memory.tcl"
  136. ===============
  137. Here is where I setup some 'memory definitions' that various targets can use.
  138. For example - there is an "unknown" memory region.
  139. All memory regions must have 2 things:
  140. (1) N_<name>
  141. (2) NAME( array )
  142. And the array must have some specific names:
  143. ( <idx>, THING )
  144. Where: THING is one of:
  145. CHIPSELECT
  146. BASE
  147. LEN
  148. HUMAN
  149. TYPE
  150. RWX - the access ablity.
  151. WIDTH - the accessable width.
  152. ie: Some regions of memory are not 'word'
  153. accessible.
  154. The function "address_info" - given an address should
  155. tell you about the address.
  156. [as of this writing: 7/5/2008 I have done
  157. only a little bit with this -Duane]
  158. ===
  159. MAJOR FUNCTION:
  160. ==
  161. proc memread32 { ADDR }
  162. proc memread16 { ADDR }
  163. proc memread8 { ADDR }
  164. All read memory - and return the contents.
  165. [ FIXME: 7/5/2008 - I need to create "memwrite" functions]
  166. **************************************************
  167. ***************************************************
  168. === TCL TOUR ===
  169. Open the file: "mmr_helpers.tcl"
  170. ===============
  171. This file is used to display and work with "memory mapped registers"
  172. For example - 'show_mmr32_reg' is given the NAME of the register to
  173. display. The assumption is - the NAME is a global variable holding the
  174. address of that MMR.
  175. The code does some tricks. The [set [set NAME]] is the TCL way
  176. of doing double variable interpolation - like makefiles...
  177. In a makefile or shell script you may have seen this:
  178. FOO_linux = "Penguins rule"
  179. FOO_winXP = "Broken Glass"
  180. FOO_mac = "I like cat names"
  181. # Pick one
  182. BUILD = linux
  183. #BUILD = winXP
  184. #BUILD = mac
  185. FOO = ${FOO_${BUILD}}
  186. The "double [set] square bracket" thing is the TCL way, nothing more.
  187. ----
  188. The IF statement - and "CATCH" .
  189. Notice this IF COMMAND - (not statement) is like this:
  190. [7/5/2008 it is this way]
  191. if ![catch { command } msg ] {
  192. ...something...
  193. } else {
  194. error [format string...]
  195. }
  196. The "IF" command expects either 2 params, or 4 params.
  197. === Sidebar: About "commands" ===
  198. Take a look at the internals of "jim.c"
  199. Look for the function: Jim_IfCoreCommand()
  200. And all those other "CoreCommands"
  201. You'll notice - they all have "argc" and "argv"
  202. Yea, the entire thing is done that way.
  203. IF is a command. SO is "FOR" and "WHILE" and "DO" and the
  204. others. That is why I keep using the phase it is a "command"
  205. === END: Sidebar: About "commands" ===
  206. Parameter 1 to the IF command is expected to be an expression.
  207. As such, I do not need to wrap it in {braces}.
  208. In this case, the "expression" is the result of the "CATCH" command.
  209. CATCH - is an error catcher.
  210. You give CATCH 1 or 2 parameters.
  211. The first 1st parameter is the "code to execute"
  212. The 2nd (optional) is where to put the error message.
  213. CATCH returns 0 on success, 1 for failure.
  214. The "![catch command]" is self explaintory.
  215. The 3rd parameter to IF must be exactly "else" or "elseif" [I lied
  216. above, the IF command can take many parameters they just have to
  217. be joined by exactly the words "else" or "elseif".
  218. The 4th parameter contains:
  219. "error [format STRING....]"
  220. This lets me modify the previous lower level error by tacking more
  221. text onto the end of it. In this case, i want to add the MMR register
  222. name to make my error message look better.
  223. ---------
  224. Back to something inside show_mmr32_reg{}.
  225. You'll see something 'set fn show_${NAME}_helper' Here I am
  226. constructing a 'function name' Then - I look it up to see if it
  227. exists. {the function: "proc_exists" does this}
  228. And - if it does - I call the function.
  229. In "C" it is alot like using: 'sprintf()' to construct a function name
  230. string, then using "dlopen()" and "dlsym()" to look it up - and get a
  231. function pointer - and calling the function pointer.
  232. In this case - I execute a dynamic command. You can do some cool
  233. tricks with interpretors.
  234. ----------
  235. Function: show_mmr32_bits()
  236. In this case, we use the special TCL command "upvar" which tcl's way
  237. of passing things by reference. In this case, we want to reach up into
  238. the callers lexical scope and find the array named "NAMES"
  239. The rest of the function is pretty straight forward.
  240. First - we figure out the longest name.
  241. Then print 4 rows of 8bits - with names.
  242. **************************************************
  243. ***************************************************
  244. === TCL TOUR ===
  245. Open the file: "chips/atmel/at91/usarts.tcl"
  246. ===============
  247. First - about the AT91SAM series - all of the usarts
  248. are basically identical...
  249. Second - there can be many of them.
  250. In this case - I do some more TCL tricks to dynamically
  251. create functions out of thin air.
  252. Some assumptions:
  253. The "CHIP" file has defined some variables in a proper form.
  254. ie: AT91C_BASE_US0 - for usart0,
  255. AT91C_BASE_US1 - for usart1
  256. ... And so on ...
  257. Near the end of the file - look for a large "foreach" loop that
  258. looks like this:
  259. foreach WHO { US0 US1 US2 US3 US4 .... } {
  260. }
  261. In this case, I'm trying to figure out what USARTs exist.
  262. Step 1 - is to determine if the NAME has been defined.
  263. ie: Does AT91C_BASE_USx - where X is some number exist?
  264. The "info exists VARNAME" tells you if the variable exists. Then -
  265. inside the IF statement... There is another loop. This loop is the
  266. name of various "sub-registers" within the USART.
  267. Some more trick are played with the [set VAR] backtick evaluation stuff.
  268. And we create two variables
  269. We calculate and create the global variable name for every subregister in the USART.
  270. And - declare that variable as GLOBAL so the world can find it.
  271. Then - we dynamically create a function - based on the register name.
  272. Look carefully at how that is done. You'll notice the FUNCTION BODY is
  273. a string - not something in {braces}. Why? This is because we need TCL
  274. to evaluate the contents of that string "*NOW*" - when $vn exists not
  275. later, when the function "show_FOO" is invoked.
  276. Lastly - we build a "str" of commands - and create a single function -
  277. with the generated list of commands for the entire USART.
  278. With that little bit of code - I now have a bunch of functions like:
  279. show_US0, show_US1, show_US2, .... etc ...
  280. And show_US0_MR, show_US0_IMR ... etc...
  281. And - I have this for every USART... without having to create tons of
  282. boiler plate yucky code.
  283. ****************************************
  284. ****************************************
  285. END of the Tcl Intro and Walk Through
  286. ****************************************
  287. ****************************************
  288. FUTURE PLANS
  289. Some "GPIO" functions...