1 ****************************************
2 ****************************************
4 This is a short introduction to 'un-scare' you about the language
5 known as TCL. It is structured as a guided tour through the files
6 written by me [Duane Ellis] - in early July 2008 for OpenOCD.
8 Which uses the "JIM" embedded Tcl clone-ish language.
10 Thing described here are *totally* TCL generic... not Jim specific.
12 The goal of this document is to encourage you to add your own set of
13 chips to the TCL package - and most importantly you should know where
14 you should put them - so they end up in an organized way.
19 ****************************************
20 ****************************************
22 Adding "chip" support - Duane Ellis July 5 - 2008.
25 In your "openocd.cfg" file add something like this:
27 source [find tcl/chip/VENDOR/FAMILY/NAME.tcl]
30 source [find tcl/chip/atmel/at91/at91sam7x256.tcl]
32 You'll notice that it makes use of:
34 tcl/cpu/arm/<NAME>.tcl.
36 Yes, that is where you should put "core" specific things.
37 Be careful and learn the difference:
39 THE "CORE" - is not the entire chip!
42 That "file" listed above is called a "CHIP FILE".
44 It may be standalone, or may need to "source" other "helper" files.
46 The reference [7/5/2008] is the at91sam7x256.tcl file.
48 ****************************************
49 ****************************************
51 Open: at91sam7x256.tcl
54 A walk through --- For those who are new to TCL.
56 Examine the file: at91sam7x256.tcl
59 source [find path/filename.tcl]
61 In TCL - this is very important.
63 Rule #1 Everything is a string.
64 Rule #2 If you think other wise See #1.
66 Rule #1: The wife is correct.
67 Rule #2: If you think otherwise, See #1
69 Any text contained inside of [square-brackets]
70 is just like `back-ticks` in BASH.
72 Hence, the [find FILENAME] executes the command find with a single
73 parameter the filename.
75 ========================================
77 Next you see a series of:
81 It is mostly "obvious" what is going on.
83 Exception: The arrays.
85 You would *THINK* Tcl supports arrays.
86 In fact, multi-dim arrays. That is false.
88 For the index for"FLASH(0,CHIPSELECT)" is actually the string
89 "0,CHIPSELECT". This is problematic. In the normal world, you think
90 of array indexes as integers.
92 For example these are different:
97 Why? Because 0x0c {lowercase} is a string.
98 Don't forget UPPER CASE.
100 You must be careful - always... always... use simple decimal
101 numbers. When in doubt use 'expr' the evaluator. These are all the
105 set foo([expr $x]) "twelve"
108 set foo([expr $x]) "twelve"
111 set foo([expr $x]) "twelve"
113 **************************************************
114 ***************************************************
116 Open the file: "bitsbytes.tcl"
118 There is some tricky things going on.
121 First, there is a "for" loop - at level 0
122 {level 0 means: out side of a proc/function}
124 This means it is evaluated when the file is parsed.
126 == SIDEBAR: About The FOR command ==
127 In TCL, "FOR" is a funny thing, it is not what you think it is.
129 Syntactically - FOR is a just a command, it is not language
130 construct like for(;;) in C...
132 The "for" command takes 4 parameters.
133 (1) The "initial command" to execute.
134 (2) the test "expression"
135 (3) the "next command"
136 (4) the "body command" of the FOR loop.
138 Notice I used the words "command" and "expression" above.
141 1) executes the "initial command"
142 2) evaluates the expression if 0 it stops.
143 3) executes the "body command"
144 4) executes the "next command"
147 As show, each of these items are in {curly-braces}. This means they
148 are passed as they are - KEY-POINT: un evaluated to the FOR
149 command. Think of it like escaping the backticks in Bash so that the
150 "under-lying" command can evaluate the contents. In this case, the FOR
153 == END: SIDEBAR: About The FOR command ==
155 You'll see two lines:
158 set vn [format "BIT%d" $x]
160 Format is like "sprintf". Because of the [brackets], it becomes what
161 you think. But here's how:
163 First - the line is parsed - for {braces}. In this case, there are
164 none. The, the parser looks for [brackets] and finds them. The,
165 parser then evaluates the contents of the [brackets], and replaces
166 them. It is alot this bash statement.
171 set $vn [expr (1024 * $x)]
174 In line 1, we dynamically created a variable name. Here, we are
175 assigning it a value. Lastly Line 3 we force the variable to be
176 global, not "local" the the "for command body"
181 proc create_mask { MSB LSB } {
185 Like "for" - PROC is really just a command that takes 3 parameters.
186 The (1) NAME of the function, a (2) LIST of parameters, and a (3) BODY
188 Again, this is at "level 0" so it is a global function. (Yes, TCL
189 supports local functions, you put them inside of a function}
191 You'll see in some cases, I nest [brackets] alot and in others I'm
192 lazy or wanted it to be more clear... it is a matter of choice.
196 **************************************************
197 ***************************************************
199 Open the file: "memory.tcl"
202 Here is where I setup some 'memory definitions' that various targets can use.
204 For example - there is an "unknown" memory region.
206 All memory regions must have 2 things:
210 And the array must have some specific names:
212 Where: THING is one of:
218 RWX - the access ablity.
219 WIDTH - the accessable width.
221 ie: Some regions of memory are not 'word'
224 The function "address_info" - given an address should
225 tell you about the address.
227 [as of this writing: 7/5/2008 I have done
228 only a little bit with this -Duane]
234 proc memread32 { ADDR }
235 proc memread16 { ADDR }
236 proc memread8 { ADDR }
238 All read memory - and return the contents.
240 [ FIXME: 7/5/2008 - I need to create "memwrite" functions]
242 **************************************************
243 ***************************************************
245 Open the file: "mmr_helpers.tcl"
248 This file is used to display and work with "memory mapped registers"
250 For example - 'show_mmr32_reg' is given the NAME of the register to
251 display. The assumption is - the NAME is a global variable holding the
254 The code does some tricks. The [set [set NAME]] is the TCL way
255 of doing double variable interpolation - like makefiles...
257 In a makefile or shell script you may have seen this:
259 FOO_linux = "Penguins rule"
260 FOO_winXP = "Broken Glass"
261 FOO_mac = "I like cat names"
267 FOO = ${FOO_${BUILD}}
269 The "double [set] square bracket" thing is the TCL way, nothing more.
273 The IF statement - and "CATCH" .
275 Notice this IF COMMAND - (not statement) is like this:
276 [7/5/2008 it is this way]
278 if ![catch { command } msg ] {
281 error [format string...]
284 The "IF" command expects either 2 params, or 4 params.
286 === Sidebar: About "commands" ===
288 Take a look at the internals of "jim.c"
289 Look for the function: Jim_IfCoreCommand()
290 And all those other "CoreCommands"
292 You'll notice - they all have "argc" and "argv"
294 Yea, the entire thing is done that way.
296 IF is a command. SO is "FOR" and "WHILE" and "DO" and the
297 others. That is why I keep using the phase it is a "command"
299 === END: Sidebar: About "commands" ===
301 Parameter 1 to the IF command is expected to be an expression.
303 As such, I do not need to wrap it in {braces}.
305 In this case, the "expression" is the result of the "CATCH" command.
307 CATCH - is an error catcher.
309 You give CATCH 1 or 2 parameters.
310 The first 1st parameter is the "code to execute"
311 The 2nd (optional) is where to put the error message.
313 CATCH returns 0 on success, 1 for failure.
314 The "![catch command]" is self explaintory.
317 The 3rd parameter to IF must be exactly "else" or "elseif" [I lied
318 above, the IF command can take many parameters they just have to
319 be joined by exactly the words "else" or "elseif".
321 The 4th parameter contains:
323 "error [format STRING....]"
325 This lets me modify the previous lower level error by tacking more
326 text onto the end of it. In this case, i want to add the MMR register
327 name to make my error message look better.
330 Back to something inside show_mmr32_reg{}.
332 You'll see something 'set fn show_${NAME}_helper' Here I am
333 constructing a 'function name' Then - I look it up to see if it
334 exists. {the function: "proc_exists" does this}
336 And - if it does - I call the function.
338 In "C" it is alot like using: 'sprintf()' to construct a function name
339 string, then using "dlopen()" and "dlsym()" to look it up - and get a
340 function pointer - and calling the function pointer.
342 In this case - I execute a dynamic command. You can do some cool
343 tricks with interpretors.
347 Function: show_mmr32_bits()
349 In this case, we use the special TCL command "upvar" which tcl's way
350 of passing things by reference. In this case, we want to reach up into
351 the callers lexical scope and find the array named "NAMES"
353 The rest of the function is pretty straight forward.
355 First - we figure out the longest name.
356 Then print 4 rows of 8bits - with names.
359 **************************************************
360 ***************************************************
362 Open the file: "chips/atmel/at91/usarts.tcl"
365 First - about the AT91SAM series - all of the usarts
366 are basically identical...
368 Second - there can be many of them.
370 In this case - I do some more TCL tricks to dynamically
371 create functions out of thin air.
375 The "CHIP" file has defined some variables in a proper form.
377 ie: AT91C_BASE_US0 - for usart0,
378 AT91C_BASE_US1 - for usart1
381 Near the end of the file - look for a large "foreach" loop that
384 foreach WHO { US0 US1 US2 US3 US4 .... } {
388 In this case, I'm trying to figure out what USARTs exist.
390 Step 1 - is to determine if the NAME has been defined.
391 ie: Does AT91C_BASE_USx - where X is some number exist?
393 The "info exists VARNAME" tells you if the variable exists. Then -
394 inside the IF statement... There is another loop. This loop is the
395 name of various "sub-registers" within the USART.
397 Some more trick are played with the [set VAR] backtick evaluation stuff.
398 And we create two variables
400 We calculate and create the global variable name for every subregister in the USART.
401 And - declare that variable as GLOBAL so the world can find it.
403 Then - we dynamically create a function - based on the register name.
405 Look carefully at how that is done. You'll notice the FUNCTION BODY is
406 a string - not something in {braces}. Why? This is because we need TCL
407 to evaluate the contents of that string "*NOW*" - when $vn exists not
408 later, when the function "show_FOO" is invoked.
410 Lastly - we build a "str" of commands - and create a single function -
411 with the generated list of commands for the entire USART.
413 With that little bit of code - I now have a bunch of functions like:
415 show_US0, show_US1, show_US2, .... etc ...
417 And show_US0_MR, show_US0_IMR ... etc...
419 And - I have this for every USART... without having to create tons of
420 boiler plate yucky code.
422 ****************************************
423 ****************************************
424 END of the Tcl Intro and Walk Through
425 ****************************************
426 ****************************************
430 Some "GPIO" functions...