-
Notifications
You must be signed in to change notification settings - Fork 9
/
picforth.html
2333 lines (1867 loc) · 91.4 KB
/
picforth.html
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
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<html lang="en">
<head>
<title>PicForth programmer manual</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="PicForth programmer manual">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="top" href="#Top">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<h1 class="settitle">PicForth programmer manual</h1>
<div class="node">
<a name="Top"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Preamble">Preamble</a>,
Previous: <a rel="previous" accesskey="p" href="#dir">(dir)</a>,
Up: <a rel="up" accesskey="u" href="#dir">(dir)</a>
</div>
<ul class="menu">
<li><a accesskey="1" href="#Preamble">Preamble</a>
<li><a accesskey="2" href="#Introduction">Introduction</a>
<li><a accesskey="3" href="#A-very-short-Forth-primer">A very short Forth primer</a>
<li><a accesskey="4" href="#Our-first-PicForth-program">Our first PicForth program</a>
<li><a accesskey="5" href="#Compiler-documentation">Compiler documentation</a>
<li><a accesskey="6" href="#Optimizations">Optimizations</a>
<li><a accesskey="7" href="#Examples">Examples</a>
</li></ul>
<p>--- The Detailed Node Listing ---
<p>Introduction
</p>
<ul class="menu">
<li><a accesskey="8" href="#What-is-that_003f">What is that?</a>
<li><a accesskey="9" href="#Why-this-project_003f">Why this project?</a>
<li><a href="#State-of-the-compiler">State of the compiler</a>
<li><a href="#License">License</a>
<li><a href="#Why-not-use-Mary_003f">Why not use Mary?</a>
<li><a href="#Credits">Credits</a>
<li><a href="#Resources">Resources</a>
</li></ul>
<p>A very short Forth primer
</p>
<ul class="menu">
<li><a href="#Foreword">Foreword</a>
<li><a href="#Words">Words</a>
<li><a href="#Stack-and-arguments-passing">Stack and arguments passing</a>
<li><a href="#Memory-access">Memory access</a>
<li><a href="#Constant-and-variables">Constant and variables</a>
<li><a href="#Tests">Tests</a>
<li><a href="#Loops">Loops</a>
</li></ul>
<p>Our first PicForth program
</p>
<ul class="menu">
<li><a href="#The-program-itself">The program itself</a>
<li><a href="#Line-by-line-explanation">Line by line explanation</a>
<li><a href="#Generated-assembly-code">Generated assembly code</a>
<li><a href="#An-alternate-solution">An alternate solution</a>
<li><a href="#Using-inlined-code">Using inlined code</a>
</li></ul>
<p>Compiler documentation
</p>
<ul class="menu">
<li><a href="#Organisation">Organisation</a>
<li><a href="#Compiling">Compiling</a>
<li><a href="#Code">Code</a>
<li><a href="#Interactive-mode">Interactive mode</a>
<li><a href="#Specifying-the-architecture">Specifying the architecture</a>
<li><a href="#Literals">Literals</a>
<li><a href="#Default-base">Default base</a>
<li><a href="#Stack-size">Stack size</a>
<li><a href="#Shifting">Shifting</a>
<li><a href="#Looping">Looping</a>
<li><a href="#Memory">Memory</a>
<li><a href="#Warnings-and-errors">Warnings and errors</a>
<li><a href="#Variables">Variables</a>
<li><a href="#Flags">Flags</a>
<li><a href="#Tables">Tables</a>
<li><a href="#Jump-tables">Jump tables</a>
<li><a href="#Main-program">Main program</a>
<li><a href="#Macros">Macros</a>
<li><a href="#Included-files">Included files</a>
<li><a href="#Assembler">Assembler</a>
<li><a href="#Interrupts">Interrupts</a>
<li><a href="#Argument-passing">Argument passing</a>
<li><a href="#Bit-manipulation">Bit manipulation</a>
<li><a href="#Decrementing-and-incrementing-a-memory-register">Decrementing and incrementing a memory register</a>
<li><a href="#Watchdog-timer">Watchdog timer</a>
<li><a href="#Sleep-mode">Sleep mode</a>
<li><a href="#Reading-from-or-writing-to-EEPROM">Reading from or writing to EEPROM</a>
<li><a href="#Reading-from-or-writing-to-flash-memory">Reading from or writing to flash memory</a>
<li><a href="#Map-and-disassembler-code">Map and disassembler code</a>
<li><a href="#Multitasking">Multitasking</a>
<li><a href="#Libraries">Libraries</a>
<li><a href="#Configuration-word">Configuration word</a>
<li><a href="#Caveats-and-limitations">Caveats and limitations</a>
</li></ul>
<p>Multitasking
</p>
<ul class="menu">
<li><a href="#Priority_002dbased-multitasker">Priority-based multitasker</a>
<li><a href="#Basic-cooperative-multitasker">Basic cooperative multitasker</a>
</li></ul>
<p>Optimizations
</p>
<ul class="menu">
<li><a href="#Tail-recursion">Tail recursion</a>
<li><a href="#Redundant-pop_002fpush-are-removed">Redundant pop/push are removed</a>
<li><a href="#Direct_002daccess-and-literal-variants">Direct-access and literal variants</a>
<li><a href="#Load">Load</a>
<li><a href="#Condition-inversions">Condition inversions</a>
<li><a href="#Bank-switch-optimizations">Bank switch optimizations</a>
<li><a href="#Operation-retarget">Operation retarget</a>
<li><a href="#Bit-test-operations">Bit test operations</a>
<li><a href="#Useless-loads-removed-when-testing">Useless loads removed when testing</a>
<li><a href="#Increment_002fdecrement-and-skip-if-zero-used-when-possible">Increment/decrement and skip if zero used when possible</a>
<li><a href="#Values-are-not-normalized-when-this-is-not-necessary">Values are not normalized when this is not necessary</a>
<li><a href="#Optimize-words-ending-with-constants-pushing">Optimize words ending with constants pushing</a>
<li><a href="#Use-subwf-when-possible">Use subwf when possible</a>
</ul>
<div class="node">
<a name="Preamble"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Introduction">Introduction</a>,
Previous: <a rel="previous" accesskey="p" href="#Top">Top</a>,
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
</div>
<h2 class="chapter">1 Preamble</h2>
<p>Microchip PIC 16Fx microcontrollers are very well suited for a number
of tasks. However, the programmer is left with several choices to
program them:
<ul>
<li>Use Microchip MPLab IDE running on Microsoft Windows with the assembly
programming language.
<li>Buy a third-party C compiler running on Microsoft Windows.
<li>Use the <code>gputils</code> package on a Unix system and program the PIC
using the assembly language.
<li>Use the <code>sdcc</code> C compiler on a Unix system and program the PIC in C.
<li>Use the <code>PicForth</code> Forth compiler on a Unix system and program the
PIC in Forth.
</ul>
<p>We do believe that the latest is a very pleasant solution for PIC
development, as Forth is particularily suited to embedded systems, and
Unix is more user-friendly for the developper.
<p><b>Warning:</b> this manual is a work-in-progress, and is in no way complete.
<div class="node">
<a name="Introduction"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#A-very-short-Forth-primer">A very short Forth primer</a>,
Previous: <a rel="previous" accesskey="p" href="#Preamble">Preamble</a>,
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
</div>
<h2 class="chapter">2 Introduction</h2>
<ul class="menu">
<li><a accesskey="1" href="#What-is-that_003f">What is that?</a>
<li><a accesskey="2" href="#Why-this-project_003f">Why this project?</a>
<li><a accesskey="3" href="#State-of-the-compiler">State of the compiler</a>
<li><a accesskey="4" href="#License">License</a>
<li><a accesskey="5" href="#Why-not-use-Mary_003f">Why not use Mary?</a>
<li><a accesskey="6" href="#Credits">Credits</a>
<li><a accesskey="7" href="#Resources">Resources</a>
</ul>
<div class="node">
<a name="What-is-that%3f"></a>
<a name="What-is-that_003f"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Why-this-project_003f">Why this project?</a>,
Previous: <a rel="previous" accesskey="p" href="#Introduction">Introduction</a>,
Up: <a rel="up" accesskey="u" href="#Introduction">Introduction</a>
</div>
<h3 class="section">2.1 What is that?</h3>
<p>This program is a Forth compiler for the Microchip PIC 16F87x and 16F88
family. The version described in this manual is PicForth 1.3.
<div class="node">
<a name="Why-this-project%3f"></a>
<a name="Why-this-project_003f"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#State-of-the-compiler">State of the compiler</a>,
Previous: <a rel="previous" accesskey="p" href="#What-is-that_003f">What is that?</a>,
Up: <a rel="up" accesskey="u" href="#Introduction">Introduction</a>
</div>
<h3 class="section">2.2 Why this project?</h3>
<p>I needed to write some code on a PIC to control a digital model railroad
system using the DCC (Digital Control Command) protocol. However, writing
it in assembly is error-prone and writing it in C is no fun as C compiled code
typically needs a lot of space.
<p>So I wrote this compiler, not for the purpose of writing a compiler, but as
a tool to write my DCC engine.
<div class="node">
<a name="State-of-the-compiler"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#License">License</a>,
Previous: <a rel="previous" accesskey="p" href="#Why-this-project_003f">Why this project?</a>,
Up: <a rel="up" accesskey="u" href="#Introduction">Introduction</a>
</div>
<h3 class="section">2.3 State of the compiler</h3>
<p>The compiler does not aim to be ANS Forth compliant. It has quite a few words
already implemented, and I will implement more of them as needed. Of course,
you are welcome to contribute some (see below for license information).
<p>At this time, many words are missing from standard Forth. For example, I have
no multiply operation as I have no use for it at this time and won't spend
time to implement things I don't need (remember, Forth is a tool before
anything else).
<div class="node">
<a name="License"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Why-not-use-Mary_003f">Why not use Mary?</a>,
Previous: <a rel="previous" accesskey="p" href="#State-of-the-compiler">State of the compiler</a>,
Up: <a rel="up" accesskey="u" href="#Introduction">Introduction</a>
</div>
<h3 class="section">2.4 License</h3>
<p>The compiler is released at the moment under the GNU General Public
License version 3 (I intend to use the less restrictive BSD license in
the future, but as it is based on gforth, I have to sort out those
issues with gforth copyright holders).
<p>However, the code produced by using this compiler is not tainted by the
GPL license at all. You can do whatever you want with it, and I claim
absolutely no right on the input or output of this compiler. I encourage
to use it for whatever you want.
<p>Note that I would really like people to send me their modifications
(be they bug fixes or new features) so that I can incorporate them in
the next release.
<div class="node">
<a name="Why-not-use-Mary%3f"></a>
<a name="Why-not-use-Mary_003f"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Credits">Credits</a>,
Previous: <a rel="previous" accesskey="p" href="#License">License</a>,
Up: <a rel="up" accesskey="u" href="#Introduction">Introduction</a>
</div>
<h3 class="section">2.5 Why not use Mary?</h3>
<p>Mary was a great inspiration source, I even kept some of the names from it.
However, no code has been reused, as both Forth do not have the same goal.
<div class="node">
<a name="Credits"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Resources">Resources</a>,
Previous: <a rel="previous" accesskey="p" href="#Why-not-use-Mary_003f">Why not use Mary?</a>,
Up: <a rel="up" accesskey="u" href="#Introduction">Introduction</a>
</div>
<h3 class="section">2.6 Credits</h3>
<p>I would like to thank the following people, in no particular order:
<ul>
<li>Alex Holden for his bug reports
<li>Jamie Lawson for his ports on the 16F88 architecture
<li>David McNab for his numerous enhancements, bug fixes, contributions and
ideas
<li>Francisco Rodrigo Escobedo Robles for his Mary PIC Forth compiler
<li>Daniel Serpell for his superoptimizer (a program looking for the
shortest possible sequences doing a particular job)
<li>Herman Tamas for his suggestions for some word names
<li>Keith Wootten for his precious examples of how he uses a forth-ish
assembler for the PIC and his inspiration for some control structures
<li>John C. Wren for his code contributions
<li>Wojciech Zabolotny for his helpful remarks on interrupts and context saving
</ul>
<div class="node">
<a name="Resources"></a>
<p><hr>
Previous: <a rel="previous" accesskey="p" href="#Credits">Credits</a>,
Up: <a rel="up" accesskey="u" href="#Introduction">Introduction</a>
</div>
<h3 class="section">2.7 Resources</h3>
<p>PicForth is supported through the following channels:
<ul>
<li>A mailing-list available at
<a href="http://lists.rfc1149.net/mailman/listinfo/picforth">http://lists.rfc1149.net/mailman/listinfo/picforth</a> and gatewayed
to a newsgroup at
<a href="http://dir.gmane.org/gmane.comp.lang.forth.picforth">http://dir.gmane.org/gmane.comp.lang.forth.picforth</a>.
<li>A wiki server at <a href="http://wiki.enst.fr/bin/view/Picforth">http://wiki.enst.fr/bin/view/Picforth</a>
</ul>
<div class="node">
<a name="A-very-short-Forth-primer"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Our-first-PicForth-program">Our first PicForth program</a>,
Previous: <a rel="previous" accesskey="p" href="#Introduction">Introduction</a>,
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
</div>
<h2 class="chapter">3 A very short Forth primer</h2>
<ul class="menu">
<li><a accesskey="1" href="#Foreword">Foreword</a>
<li><a accesskey="2" href="#Words">Words</a>
<li><a accesskey="3" href="#Stack-and-arguments-passing">Stack and arguments passing</a>
<li><a accesskey="4" href="#Memory-access">Memory access</a>
<li><a accesskey="5" href="#Constant-and-variables">Constant and variables</a>
<li><a accesskey="6" href="#Tests">Tests</a>
<li><a accesskey="7" href="#Loops">Loops</a>
</ul>
<div class="node">
<a name="Foreword"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Words">Words</a>,
Previous: <a rel="previous" accesskey="p" href="#A-very-short-Forth-primer">A very short Forth primer</a>,
Up: <a rel="up" accesskey="u" href="#A-very-short-Forth-primer">A very short Forth primer</a>
</div>
<h3 class="section">3.1 Foreword</h3>
<p>For a full introduction to the Forth programming language, please have a
look at the appropriate section of the Open Directory (maintained by
volunteers), at address
<a href="http://dmoz.org/Computers/Programming/Languages/Forth/">http://dmoz.org/Computers/Programming/Languages/Forth/</a>. Only a
small subset of the language will be presented here, sometimes
overlooking details.
<div class="node">
<a name="Words"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Stack-and-arguments-passing">Stack and arguments passing</a>,
Previous: <a rel="previous" accesskey="p" href="#Foreword">Foreword</a>,
Up: <a rel="up" accesskey="u" href="#A-very-short-Forth-primer">A very short Forth primer</a>
</div>
<h3 class="section">3.2 Words</h3>
<p>The Forth programming language may look unusual to people used to other
languages. First of all, the actions to execute are spelled one after
each other. The sentence <code>init mainloop cleanup</code> will call, in
turn, the word <code>init</code>, the word <code>mainloop</code> then the word
<code>cleanup</code>.
<p>To define a new word, the <code>:</code> defining word is used, while the
<code>;</code> word ends the definition. The following code defines a new word
<code>doit</code> which factors the three words used above:
<pre class="example"> : doit init mainloop cleanup ;
</pre>
<p>After it has been defined, the word <code>doit</code> can be called as other
words by using its name. A Forth program is a collection of
application-specific words. Each word, made of other words, will be used
in turn to define new words, until the whole solution is described.
<p>Words are similar to subprograms in more conventional programming
languages. Any non-blank character can be part of a word name. For
example, <code>\</code>, <code>^</code>, or <code>$</code> are legal characters in a word
name, and can even be a word name by themselves.
<div class="node">
<a name="Stack-and-arguments-passing"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Memory-access">Memory access</a>,
Previous: <a rel="previous" accesskey="p" href="#Words">Words</a>,
Up: <a rel="up" accesskey="u" href="#A-very-short-Forth-primer">A very short Forth primer</a>
</div>
<h3 class="section">3.3 Stack and arguments passing</h3>
<p>In Forth, one does not use parenthesis to give arguments to called
words. Instead, a stack is used, where the arguments can be pushed and
where they can be popped from.
<p>The word <code>+</code> pops two arguments from the top of the
stack and pushes their sum. To push an integer to the top of the stack,
one writes its value. The sentence <code>3 5 +</code> will push
<code>3</code> on the stack, then <code>5</code>, and calls the word <code>+</code> which
removes <code>3</code> and <code>5</code> and pushes <code>8</code>.
<p>Some words do manipulate the stack explicitely. <code>dup</code> duplicates
the element at the top of the stack, while <code>drop</code> removes
it. <code>swap</code> exchanges the two top elements. The following word that
we name <code>2*</code> (remember that this name is perfectly valid in Forth)
does multiply the top of the stack by two, by adding it to itself:
<pre class="example"> : 2* dup + ;
</pre>
<p>The stack effect of a word is often written as a comment between
parenthesis; those comments are ignored by the Forth compiler. The
previously defined word could have been written:
<pre class="example"> : 2* ( n -- 2*n ) dup + ;
</pre>
<p>Elements on the stack are represented from left to right (top of the
stack). For example, the <code>-</code> word which substract the top of the
stack from the second element on the stack would have a stack comment
looking like <code>( n1 n2 -- n1-n2 )</code>.
<p>Let's assume that you want to multiply the top of the stack by four. You
can define the <code>4*</code> word as:
<pre class="example"> : 4* ( n -- 4*n ) dup + dup + ;
</pre>
<p>But remember that you can define your own words from existing words. If you
now need a word which multiplies the top of the stack by four, you can
use your previously defined <code>2*</code> word:
<pre class="example"> : 4* ( n -- 4*n) 2* 2* ;
</pre>
<p>Definitions in Forth tend to be very short. The grouping of common parts
in words is called <b>factoring</b>, and leads to very concise machine code.
<div class="node">
<a name="Memory-access"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Constant-and-variables">Constant and variables</a>,
Previous: <a rel="previous" accesskey="p" href="#Stack-and-arguments-passing">Stack and arguments passing</a>,
Up: <a rel="up" accesskey="u" href="#A-very-short-Forth-primer">A very short Forth primer</a>
</div>
<h3 class="section">3.4 Memory access</h3>
<p>Two useful words allow you to access memory. <code>@</code> gets the
content of the memory byte whose address is at the top of the stack and
<code>!</code> stores, in the memory byte whose address is at the top of the
stack, the following element.
<p>The code below defines a word <code>mirror</code> which mirrors the content of
port A into port B (we will later see more practical ways of defining
some of the words seen here):
<pre class="example"> : porta 5 ;
: portb 6 ;
: mirror porta @ portb ! ;
</pre>
<div class="node">
<a name="Constant-and-variables"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Tests">Tests</a>,
Previous: <a rel="previous" accesskey="p" href="#Memory-access">Memory access</a>,
Up: <a rel="up" accesskey="u" href="#A-very-short-Forth-primer">A very short Forth primer</a>
</div>
<h3 class="section">3.5 Constant and variables</h3>
<p>The defining word <code>constant</code> allows you to define named
constants. Using this word, one can simplify the above example:
<pre class="example"> 5 constant porta
6 constant portb
: mirror porta @ portb ! ;
</pre>
<p>The defining word <code>variable</code> reserves a byte in the PIC RAM and
gives it a name:
<pre class="example"> 5 constant porta
variable counter
: increment-counter counter @ 1 + counter ! ;
: counter-to-porta counter @ porta ! ;
</pre>
<div class="node">
<a name="Tests"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Loops">Loops</a>,
Previous: <a rel="previous" accesskey="p" href="#Constant-and-variables">Constant and variables</a>,
Up: <a rel="up" accesskey="u" href="#A-very-short-Forth-primer">A very short Forth primer</a>
</div>
<h3 class="section">3.6 Tests</h3>
<p>Testing in Forth is done using a <code>if</code> construct, terminated by a
<code>then</code>, with an optional <code>else</code>. Operators such as <code><</code> or
<code>=</code> can be used, and any non-null value is considered as true. The
<code>abs</code> word changes the value on top of the stack to its absolute
value (note that <code>abs</code> and <code>negate</code> are in fact already
defined by PicForth):
<pre class="example"> : negate 0 swap - ;
: abs dup 0 < if negate then ;
</pre>
<p>The word <code>mirror </code>duplicates port A to port B or port C, depending on
its argument; <code>0</code> for port B, anything else for port C
(<code>porta</code>, <code>portb</code> and <code>portc</code> constant are already
defined in PicForth), as are <code>trisa</code>, <code>trisb</code> and <code>trisc</code>:
<pre class="example"> : mirror ( n -- ) porta @ swap if portb ! else portc ! then ;
</pre>
<p>It is also possible to use Forth's <code>case</code>, <code>of</code>, <code>endof</code> and
<code>endcase</code>.
<div class="node">
<a name="Loops"></a>
<p><hr>
Previous: <a rel="previous" accesskey="p" href="#Tests">Tests</a>,
Up: <a rel="up" accesskey="u" href="#A-very-short-Forth-primer">A very short Forth primer</a>
</div>
<h3 class="section">3.7 Loops</h3>
<p>Several looping constructs are used in PicForth. The first of them is
built upon <code>begin</code> and <code>again</code>, which here calls
<code>do-one-thing</code> indefinitely:
<pre class="example"> : mainloop begin do-one-thing again ;
</pre>
<p><code>while</code> and <code>repeat</code> can add a test in the loop and continue
as long as the word <code>continue?</code> returns a non-null result:
<pre class="example"> : mainloop begin do-one-thing continue? while repeat ;
</pre>
<p>Note that <code>while</code> can be present anywhere between <code>begin</code> and
<code>repeat</code>, letting you build elaborate constructs. Also,
<code>until</code> allows you to wait for a condition. The following word
calls <code>do-one-thing</code> until <code>end?</code> returns a non-null value:
<pre class="example"> : mainloop begin do-one-thing end? until ;
</pre>
<p>The last construct seen here is built around <code>v-for</code> and
<code>v-next</code>. <code>v-for</code> takes a (non-included) high bound and a
variable address on the stack. The following word <code>main</code> calls
<code>do-one-thing</code> 10 times:
<pre class="example"> variable count
: main 10 count v-for do-one-thing count v-next ;
</pre>
<div class="node">
<a name="Our-first-PicForth-program"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Compiler-documentation">Compiler documentation</a>,
Previous: <a rel="previous" accesskey="p" href="#A-very-short-Forth-primer">A very short Forth primer</a>,
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
</div>
<h2 class="chapter">4 Our first PicForth program</h2>
<ul class="menu">
<li><a accesskey="1" href="#The-program-itself">The program itself</a>
<li><a accesskey="2" href="#Line-by-line-explanation">Line by line explanation</a>
<li><a accesskey="3" href="#Generated-assembly-code">Generated assembly code</a>
<li><a accesskey="4" href="#An-alternate-solution">An alternate solution</a>
<li><a accesskey="5" href="#Using-inlined-code">Using inlined code</a>
</ul>
<div class="node">
<a name="The-program-itself"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Line-by-line-explanation">Line by line explanation</a>,
Previous: <a rel="previous" accesskey="p" href="#Our-first-PicForth-program">Our first PicForth program</a>,
Up: <a rel="up" accesskey="u" href="#Our-first-PicForth-program">Our first PicForth program</a>
</div>
<h3 class="section">4.1 The program itself</h3>
<p>Our first PicForth program will generate a rectangle wave signal on port
B0 as fast as possible:
<pre class="example"> 0 pin-b i/o
: init i/o >output ;
: pulse i/o high i/o low ;
: mainloop begin pulse again ;
main : program init mainloop ;
</pre>
<div class="node">
<a name="Line-by-line-explanation"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Generated-assembly-code">Generated assembly code</a>,
Previous: <a rel="previous" accesskey="p" href="#The-program-itself">The program itself</a>,
Up: <a rel="up" accesskey="u" href="#Our-first-PicForth-program">Our first PicForth program</a>
</div>
<h3 class="section">4.2 Line by line explanation</h3>
<p>The first line <code>0 pin-b i/o</code> defines a new word <code>i/o</code> which,
when executed, will push two integers <code>6</code> (corresponding to portb)
and <code>0</code> on the stack. This way, instead of writing <code>portb 0</code>
to manipulate bit 0 of port B you can write <code>i/o</code>, which is shorter
and lets you change it at only one place should you want to change which
port is used.
<p>The second line uses the PicForth word <code>>output</code> which sets the
port whose address and bit are on the stack in output mode. This defines
a new <code>init</code> word which initializes our port B0 as an output.
<p>The third line creates a new word <code>pulse</code> which uses the PicForth
words <code>high</code> and <code>low</code> to set a pin high or low. As a result,
executing the <code>pulse</code> word will set the B0 pin high then low, this
generating a pulse.
<p>The fourth line defines a <code>mainloop</code> word which calls <code>pulse</code>
endlessly, thus generating the rectangle wave signal we want.
<p>The last line uses the PicForth word <code>main</code>. This word indicates to
PicForth that the next word to be defined will be the one to call on
reset. The word, called <code>program</code> here, calls <code>init</code> then
<code>mainloop</code>. As <code>mainloop</code> never returns, the program runs
until the end of time (which is usually considered quite a long time).
<div class="node">
<a name="Generated-assembly-code"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#An-alternate-solution">An alternate solution</a>,
Previous: <a rel="previous" accesskey="p" href="#Line-by-line-explanation">Line by line explanation</a>,
Up: <a rel="up" accesskey="u" href="#Our-first-PicForth-program">Our first PicForth program</a>
</div>
<h3 class="section">4.3 Generated assembly code</h3>
<p>The generated code looks like:
<pre class="example"> 0x0000 018A clrf 0x0A
0x0001 280C goto 0x00C ; (init-picforth)
0x0002 0000 nop
; name: init
; max return-stack depth: 0
0x0003 1683 bsf 0x03,5
0x0004 1006 bcf 0x06,0
0x0005 1283 bcf 0x03,5
0x0006 0008 return
; name: pulse
; max return-stack depth: 0
0x0007 1406 bsf 0x06,0
0x0008 1006 bcf 0x06,0
0x0009 0008 return
; name: mainloop
; max return-stack depth: 1
0x000A 2007 call 0x007 ; pulse
0x000B 280A goto 0x00A ; mainloop (rs depth: 1)
; name: (init-picforth)
; max return-stack depth: 0
0x000C 3032 movlw 0x32
0x000D 0084 movwf 0x04
; name: program
; max return-stack depth: 1
0x000E 2003 call 0x003 ; init
0x000F 280A goto 0x00A ; mainloop (rs depth: 1)
</pre>
<div class="node">
<a name="An-alternate-solution"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Using-inlined-code">Using inlined code</a>,
Previous: <a rel="previous" accesskey="p" href="#Generated-assembly-code">Generated assembly code</a>,
Up: <a rel="up" accesskey="u" href="#Our-first-PicForth-program">Our first PicForth program</a>
</div>
<h3 class="section">4.4 An alternate solution</h3>
<p>Of course, it is possible to write less factored code for such a
simple task, and write instead:
<pre class="example"> 0 pin-b i/o
main : program i/o >output begin i/o high i/o low repeat ;
</pre>
<p>In this case, it generates effectively a code which is a bit shorter:
<pre class="example"> 0x0000 018A clrf 0x0A
0x0001 2803 goto 0x003 ; (init-picforth)
0x0002 0000 nop
; name: (init-picforth)
; max return-stack depth: 0
0x0003 3032 movlw 0x32
0x0004 0084 movwf 0x04
; name: program
; max return-stack depth: 0
0x0005 1683 bsf 0x03,5
0x0006 1006 bcf 0x06,0
0x0007 1283 bcf 0x03,5
0x0008 1406 bsf 0x06,0
0x0009 1006 bcf 0x06,0
0x000A 2808 goto 0x008 ; program + 0x003
</pre>
<p>However, do not let this short example mislead you. While the code looks
more efficient and shorter (and it is), this is generally not true for
real-life programs. For example, in a bigger program it would be quite
common to have to call <code>pulse</code> from other places.
<div class="node">
<a name="Using-inlined-code"></a>
<p><hr>
Previous: <a rel="previous" accesskey="p" href="#An-alternate-solution">An alternate solution</a>,
Up: <a rel="up" accesskey="u" href="#Our-first-PicForth-program">Our first PicForth program</a>
</div>
<h3 class="section">4.5 Using inlined code</h3>
<p>It is possible to use inlined code by surrounding the words you want to
inline by the <code>macro</code> and <code>target</code> words:
<pre class="example"> 0 pin-b i/o
macro
: init i/o >output ;
: pulse i/o high i/o low ;
: mainloop begin pulse again ;
target
main : program init mainloop ;
</pre>
<p>While this code is highly factored and easily maintainable, it generates
the very same code as the less-factored version above.
<p>The only exception is <code>exit</code>: if this word is present in an inlined word,
it will exit from the caller. As a rule, inlined word should only have
one regular exit point at the end of the word.
<div class="node">
<a name="Compiler-documentation"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Optimizations">Optimizations</a>,
Previous: <a rel="previous" accesskey="p" href="#Our-first-PicForth-program">Our first PicForth program</a>,
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
</div>
<h2 class="chapter">5 Compiler documentation</h2>
<ul class="menu">
<li><a accesskey="1" href="#Organisation">Organisation</a>
<li><a accesskey="2" href="#Compiling">Compiling</a>
<li><a accesskey="3" href="#Code">Code</a>
<li><a accesskey="4" href="#Interactive-mode">Interactive mode</a>
<li><a accesskey="5" href="#Specifying-the-architecture">Specifying the architecture</a>
<li><a accesskey="6" href="#Literals">Literals</a>
<li><a accesskey="7" href="#Default-base">Default base</a>
<li><a accesskey="8" href="#Stack-size">Stack size</a>
<li><a accesskey="9" href="#Shifting">Shifting</a>
<li><a href="#Looping">Looping</a>
<li><a href="#Memory">Memory</a>
<li><a href="#Warnings-and-errors">Warnings and errors</a>
<li><a href="#Variables">Variables</a>
<li><a href="#Flags">Flags</a>
<li><a href="#Tables">Tables</a>
<li><a href="#Jump-tables">Jump tables</a>
<li><a href="#Main-program">Main program</a>
<li><a href="#Macros">Macros</a>
<li><a href="#Included-files">Included files</a>
<li><a href="#Assembler">Assembler</a>
<li><a href="#Interrupts">Interrupts</a>
<li><a href="#Argument-passing">Argument passing</a>
<li><a href="#Bit-manipulation">Bit manipulation</a>
<li><a href="#Decrementing-and-incrementing-a-memory-register">Decrementing and incrementing a memory register</a>
<li><a href="#Watchdog-timer">Watchdog timer</a>
<li><a href="#Sleep-mode">Sleep mode</a>
<li><a href="#Reading-from-or-writing-to-EEPROM">Reading from or writing to EEPROM</a>
<li><a href="#Reading-from-or-writing-to-flash-memory">Reading from or writing to flash memory</a>
<li><a href="#Map-and-disassembler-code">Map and disassembler code</a>
<li><a href="#Multitasking">Multitasking</a>
<li><a href="#Libraries">Libraries</a>
<li><a href="#Configuration-word">Configuration word</a>
<li><a href="#Caveats-and-limitations">Caveats and limitations</a>
</ul>
<div class="node">
<a name="Organisation"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Compiling">Compiling</a>,
Previous: <a rel="previous" accesskey="p" href="#Compiler-documentation">Compiler documentation</a>,
Up: <a rel="up" accesskey="u" href="#Compiler-documentation">Compiler documentation</a>
</div>
<h3 class="section">5.1 Organisation</h3>
<p>The stack is indexed by the only indirect register, fsr. The indf register
automatically points to the top of stack.
<p>The w register is used as a scratch. Attempts to use it to cache the
top of stack proved to be inefficient, as we often need a scratch register.
<div class="node">
<a name="Compiling"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Code">Code</a>,
Previous: <a rel="previous" accesskey="p" href="#Organisation">Organisation</a>,
Up: <a rel="up" accesskey="u" href="#Compiler-documentation">Compiler documentation</a>
</div>
<h3 class="section">5.2 Compiling</h3>
<p>The compiler is hosted on gforth, a free software compiler for Unix
systems. The command line to use to compile file <samp><span class="file">foo.fs</span></samp> into
<samp><span class="file">foo.hex</span></samp>, and getting a usable map into foo.map is:
<pre class="example"> gforth picforth.fs -e 'include foo.fs file-dump foo.hex map bye' | \
sort -o foo.map
</pre>
<p>Of course, you should automate this in a Makefile, such as the one provided
with the compiler.
<p>If you install the GNU PIC utils (from http://gputils.sourceforge.net/),
then you can read the assembled code by using <code>gpdasm</code>.
<div class="node">
<a name="Code"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Interactive-mode">Interactive mode</a>,
Previous: <a rel="previous" accesskey="p" href="#Compiling">Compiling</a>,
Up: <a rel="up" accesskey="u" href="#Compiler-documentation">Compiler documentation</a>
</div>
<h3 class="section">5.3 Code</h3>
<p>The whole code space can be used. However, code generated in the first
2048 words is more efficient than the code generated in the following
2048 words; both are more efficient than the code generated for the
remaining words. This is due to the PIC architecture which does not
allow to see the code space as a flat zone.
<div class="node">
<a name="Interactive-mode"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Specifying-the-architecture">Specifying the architecture</a>,
Previous: <a rel="previous" accesskey="p" href="#Code">Code</a>,
Up: <a rel="up" accesskey="u" href="#Compiler-documentation">Compiler documentation</a>
</div>
<h3 class="section">5.4 Interactive mode</h3>
<p>By executing
<pre class="example"> gforth picforth.fs -e 'host picquit'
</pre>
<p>(or <code>make interactive</code> from a Unix shell), you are dropped into an
interactive mode, where you can use the following words to check your code:
<pre class="example"> see ( "name" -- ) Disassemble a word
map ( -- ) Print code memory map
dis ( -- ) Disassemble the whole code section
</pre>
<div class="node">
<a name="Specifying-the-architecture"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Literals">Literals</a>,
Previous: <a rel="previous" accesskey="p" href="#Interactive-mode">Interactive mode</a>,
Up: <a rel="up" accesskey="u" href="#Compiler-documentation">Compiler documentation</a>
</div>
<h3 class="section">5.5 Specifying the architecture</h3>
<p>You can choose the architecture you want to compile for by using:
<pre class="example"> pic16f87x ( -- ) Generate code for a PIC16F87x target
pic16f88 ( -- ) Generate code for a PIC16F88 target
</pre>
<div class="node">
<a name="Literals"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Default-base">Default base</a>,
Previous: <a rel="previous" accesskey="p" href="#Specifying-the-architecture">Specifying the architecture</a>,
Up: <a rel="up" accesskey="u" href="#Compiler-documentation">Compiler documentation</a>
</div>
<h3 class="section">5.6 Literals</h3>
<p>Hexadecimal literals should be prefixed by a dollar sign <code>$</code> to avoid
confusion with existing constants (such as <code>c</code> for carry bit). This is a
strong advice.
<div class="node">
<a name="Default-base"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Stack-size">Stack size</a>,
Previous: <a rel="previous" accesskey="p" href="#Literals">Literals</a>,
Up: <a rel="up" accesskey="u" href="#Compiler-documentation">Compiler documentation</a>
</div>
<h3 class="section">5.7 Default base</h3>
<p>The default base is hexadecimal. Do not change it before including libraries
bundled with the compiler, as they do expect hexadecimal mode.
<div class="node">
<a name="Stack-size"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Shifting">Shifting</a>,
Previous: <a rel="previous" accesskey="p" href="#Default-base">Default base</a>,
Up: <a rel="up" accesskey="u" href="#Compiler-documentation">Compiler documentation</a>
</div>
<h3 class="section">5.8 Stack size</h3>
<p>The default stack size is 16. If you use the multitasker included in
<samp><span class="file">multitasker.fs</span></samp> (see below), each task gets an additionnal 8 bytes of
task-specific stack.
<p>You can change the default stack size by using
<pre class="example"> set-stack-size ( n -- )
</pre>
<p>in interpretation mode before using <code>main</code>.
<div class="node">
<a name="Shifting"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Looping">Looping</a>,
Previous: <a rel="previous" accesskey="p" href="#Stack-size">Stack size</a>,
Up: <a rel="up" accesskey="u" href="#Compiler-documentation">Compiler documentation</a>
</div>
<h3 class="section">5.9 Shifting</h3>
<p><code>rlf-tos</code> and <code>rrf-tos</code> respectively shift the top-of-stack
left and right, with the carry entering the byte and the outgoing bit
entering the carry.
<p><code>rlf!</code> and <code>rrf!</code> respectively shift the given variable left
and right, with the carry entering the byte and the outgoing bit entering
the carry.
<p><code>lshift</code> and <code>rshift</code> used with a constant shift, and
<code>2*</code> and <code>2/</code> do have the last exited bit in the carry.
<p><code>swapf-tos</code> will swap the upper and lower nibble of the top-of-stack.
<div class="node">
<a name="Looping"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Memory">Memory</a>,
Previous: <a rel="previous" accesskey="p" href="#Shifting">Shifting</a>,
Up: <a rel="up" accesskey="u" href="#Compiler-documentation">Compiler documentation</a>
</div>
<h3 class="section">5.10 Looping</h3>
<p>There exists a <code>v-for</code>/<code>v-next</code> structure (v stands for variable):
<pre class="example"> v-for ( n addr -- )
Initialize addr content with n.
v-next ( -- )
Decrement addr content. If content is not zero,
jump to v-for location.
</pre>
<p>The address has to be located in bank 0.
<p>Also, the words <code>begin</code>, <code>again</code>, <code>while</code>, <code>until</code>