aboutsummaryrefslogtreecommitdiff
path: root/src/tcl/README_ABOUT_TCL.txt
blob: af3fb086181263e79f51b8d3b6bc9609e397cea6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
****************************************
****************************************

This is a short introduction to 'un-scare' you about the language
known as TCL. It is structured as a guided tour through the files
written by me [Duane Ellis] - in early July 2008 for OpenOCD.

Which uses the "JIM" embedded Tcl clone-ish language.

Thing described here are *totally* TCL generic... not Jim specific.

The goal of this document is to encourage you to add your own set of
chips to the TCL package - and most importantly you should know where
you should put them - so they end up in an organized way.

--Duane Ellis.
	duane@duaneellis.com

****************************************
****************************************

Adding "chip" support - Duane Ellis July 5 - 2008.

The concept is this:
  In your "openocd.cfg" file add something like this:

     source [find tcl/chip/VENDOR/FAMILY/NAME.tcl]

  For example...
     source [find tcl/chip/atmel/at91/at91sam7x256.tcl]

  You'll notice that it makes use of:

       tcl/cpu/arm/<NAME>.tcl.

  Yes, that is where you should put "core" specific things.
  Be careful and learn the difference:

  THE "CORE" - is not the entire chip!

Definition:
   That "file" listed above is called a "CHIP FILE".

   It may be standalone, or may need to "source" other "helper" files.

   The reference [7/5/2008] is the at91sam7x256.tcl file.

****************************************
****************************************
=== TCL TOUR ===
Open:  at91sam7x256.tcl
=== TCL TOUR ===

A walk through --- For those who are new to TCL.

Examine the file: at91sam7x256.tcl

It starts with:
	source [find path/filename.tcl]

In TCL - this is very important.

	Rule #1 Everything is a string.
	Rule #2 If you think other wise See #1.
Reminds you of:
	Rule #1: The wife is correct.
	Rule #2: If you think otherwise, See #1

Any text contained inside of [square-brackets]
is just like `back-ticks` in BASH.

Hence, the [find FILENAME] executes the command find with a single
parameter the filename.

========================================

Next you see a series of:

set  NAME    VALUE

It is mostly "obvious" what is going on.

Exception: The arrays.

  You would *THINK* Tcl supports arrays.
  In fact, multi-dim arrays. That is false.

  For the index for"FLASH(0,CHIPSELECT)" is actually the string
  "0,CHIPSELECT".  This is problematic. In the normal world, you think
  of array indexes as integers.

  For example these are different:

       set foo(0x0c)  123
       set foo(12)    444

  Why? Because 0x0c {lowercase} is a string.
  Don't forget UPPER CASE.

  You must be careful - always... always...  use simple decimal
  numbers. When in doubt use 'expr' the evaluator. These are all the
  same.

       set x 0x0c
       set foo([expr $x])  "twelve"

       set x 12
       set foo([expr $x])  "twelve"

       set x "2 * 6"
       set foo([expr $x])  "twelve"
       
**************************************************
***************************************************
=== TCL TOUR ===
Open the file: "bitsbytes.tcl"

There is some tricky things going on.
===============

First, there is a "for" loop - at level 0
{level 0 means: out side of a proc/function}

This means it is evaluated when the file is parsed.

== SIDEBAR: About The FOR command ==
In TCL, "FOR" is a funny thing, it is not what you think it is.

Syntactically - FOR is a just a command, it is not language
construct like for(;;) in C... 

The "for" command takes 4 parameters.
   (1) The "initial command" to execute.
   (2) the test "expression"
   (3) the "next command"
   (4) the "body command" of the FOR loop.

Notice I used the words "command" and "expression" above.

The FOR command:
1)  executes the "initial command"
2)  evaluates the expression if 0 it stops.
3)  executes the "body command"
4)  executes the "next command"
5)  Goto Step 2.

As show, each of these items are in {curly-braces}.  This means they
are passed as they are - KEY-POINT: un evaluated to the FOR
command. Think of it like escaping the backticks in Bash so that the
"under-lying" command can evaluate the contents. In this case, the FOR
COMMAND.

== END: SIDEBAR: About The FOR command ==

You'll see two lines:

LINE1:
       set vn [format "BIT%d" $x]

Format is like "sprintf". Because of the [brackets], it becomes what
you think.  But here's how:

First - the line is parsed - for {braces}.  In this case, there are
none.  The, the parser looks for [brackets] and finds them.  The,
parser then evaluates the contents of the [brackets], and replaces
them. It is alot this bash statement.

       EXPORT vn=`date`

LINE 2 & 3
       set $vn [expr (1024 * $x)]
       global $vn

In line 1, we dynamically created a variable name.  Here, we are
assigning it a value. Lastly Line 3 we force the variable to be
global, not "local" the the "for command body"

===============
The PROCS

proc create_mask { MSB LSB } {
     ... body ....
}

Like "for" - PROC is really just a command that takes 3 parameters.
The (1) NAME of the function, a (2) LIST of parameters, and a (3) BODY

Again, this is at "level 0" so it is a global function.  (Yes, TCL
supports local functions, you put them inside of a function}

You'll see in some cases, I nest [brackets] alot and in others I'm
lazy or wanted it to be more clear... it is a matter of choice.
===============


**************************************************
***************************************************
=== TCL TOUR ===
Open the file: "memory.tcl"
===============

Here is where I setup some 'memory definitions' that various targets can use.

For example - there is an "unknown" memory region.

All memory regions must have 2 things:

 (1)  N_<name>
 (2)  NAME( array )
      And the array must have some specific names:
          ( <idx>, THING )
	    Where: THING is one of: 
		   CHIPSELECT
		   BASE
		   LEN
		   HUMAN
		   TYPE
		   RWX - the access ablity.
		   WIDTH - the accessable width.

        ie: Some regions of memory are not 'word' 
	accessible.

The function "address_info" - given an address should
tell you about the address.

     [as of this writing: 7/5/2008 I have done
     only a little bit with this -Duane]

===
MAJOR FUNCTION:
==

proc memread32 { ADDR } 
proc memread16 { ADDR } 
proc memread8 { ADDR } 

All read memory - and return the contents.

[ FIXME: 7/5/2008 - I need to create "memwrite" functions]
		 
**************************************************
***************************************************
=== TCL TOUR ===
Open the file: "mmr_helpers.tcl"
===============

This file is used to display and work with "memory mapped registers"

For example - 'show_mmr32_reg' is given the NAME of the register to
display. The assumption is - the NAME is a global variable holding the
address of that MMR.

The code does some tricks. The [set [set NAME]] is the TCL way
of doing double variable interpolation - like makefiles...

In a makefile or shell script you may have seen this:

     FOO_linux = "Penguins rule"
     FOO_winXP = "Broken Glass"
     FOO_mac   = "I like cat names"
     
     # Pick one
     BUILD  = linux
     #BUILD = winXP
     #BUILD = mac
     FOO = ${FOO_${BUILD}}
				
The "double [set] square bracket" thing is the TCL way, nothing more.

----

The IF statement - and "CATCH" .

Notice this IF COMMAND - (not statement) is like this:
[7/5/2008 it is this way]

       if ![catch { command } msg ] {
	  ...something...
       } else {
          error [format string...]
       }

The "IF" command expects either 2 params, or 4 params.

 === Sidebar: About "commands" ===
  
     Take a look at the internals of "jim.c"
     Look for the function: Jim_IfCoreCommand()
     And all those other "CoreCommands"

     You'll notice - they all have "argc" and "argv"

     Yea, the entire thing is done that way.
     
     IF is a command. SO is "FOR" and "WHILE" and "DO" and the
     others. That is why I keep using the phase it is a "command"
     
 === END: Sidebar: About "commands" ===

Parameter 1 to the IF command is expected to be an expression.

As such, I do not need to wrap it in {braces}.

In this case, the "expression" is the result of the "CATCH" command.

CATCH - is an error catcher.

You give CATCH 1 or 2 parameters.
    The first 1st parameter is the "code to execute"
    The 2nd (optional) is where to put the error message.
    
    CATCH returns 0 on success, 1 for failure.
    The "![catch command]" is self explaintory.


The 3rd parameter to IF must be exactly "else" or "elseif" [I lied
above, the IF command can take many parameters they just have to
be joined by exactly the words "else" or "elseif".

The 4th parameter contains:
    
    "error [format STRING....]"

This lets me modify the previous lower level error by tacking more
text onto the end of it. In this case, i want to add the MMR register
name to make my error message look better.

---------
Back to something inside show_mmr32_reg{}.

You'll see something 'set fn show_${NAME}_helper' Here I am
constructing a 'function name' Then - I look it up to see if it
exists.  {the function: "proc_exists" does this}

And - if it does - I call the function.

In "C" it is alot like using: 'sprintf()' to construct a function name
string, then using "dlopen()" and "dlsym()" to look it up - and get a
function pointer - and calling the function pointer.

In this case - I execute a dynamic command. You can do some cool
tricks with interpretors. 

----------

Function:   show_mmr32_bits()

In this case, we use the special TCL command "upvar" which tcl's way
of passing things by reference. In this case, we want to reach up into
the callers lexical scope and find the array named "NAMES"

The rest of the function is pretty straight forward.

First - we figure out the longest name.
Then print 4 rows of 8bits - with names.


**************************************************
***************************************************
=== TCL TOUR ===
Open the file: "chips/atmel/at91/usarts.tcl"
===============

First - about the AT91SAM series - all of the usarts
are basically identical...

Second - there can be many of them.

In this case - I do some more TCL tricks to dynamically
create functions out of thin air.

Some assumptions:

The "CHIP" file has defined some variables in a proper form.

ie:   AT91C_BASE_US0 - for usart0, 
      AT91C_BASE_US1 - for usart1
      ... And so on ...

Near the end of the file - look for a large "foreach" loop that
looks like this:

      foreach WHO { US0 US1 US2 US3 US4 .... } {

      }

In this case, I'm trying to figure out what USARTs exist.

Step 1 - is to determine if the NAME has been defined.
ie: Does AT91C_BASE_USx - where X is some number exist?

The "info exists VARNAME" tells you if the variable exists.  Then -
inside the IF statement... There is another loop. This loop is the
name of various "sub-registers" within the USART.

Some more trick are played with the [set VAR] backtick evaluation stuff.
And we create two variables

We calculate and create the global variable name for every subregister in the USART.
And - declare that variable as GLOBAL so the world can find it.

Then - we dynamically create a function - based on the register name.

Look carefully at how that is done. You'll notice the FUNCTION BODY is
a string - not something in {braces}. Why? This is because we need TCL
to evaluate the contents of that string "*NOW*" - when $vn exists not
later, when the function "show_FOO" is invoked.

Lastly - we build a "str" of commands - and create a single function -
with the generated list of commands for the entire USART.

With that little bit of code - I now have a bunch of functions like:

   show_US0, show_US1, show_US2, .... etc ...
   
   And show_US0_MR, show_US0_IMR ... etc...
  
And - I have this for every USART... without having to create tons of
boiler plate yucky code.

****************************************
****************************************
END of the Tcl Intro and Walk Through
****************************************
****************************************

FUTURE PLANS

       Some "GPIO" functions...