8616060f4f8934218a4458806d5ebabc7917496b
[fw/sdcc] / doc / sdccman.lyx
1 #LyX 1.3 created this file. For more info see http://www.lyx.org/
2 \lyxformat 221
3 \textclass article
4 \language english
5 \inputencoding default
6 \fontscheme pslatex
7 \graphics default
8 \paperfontsize default
9 \spacing single 
10 \papersize Default
11 \paperpackage a4
12 \use_geometry 0
13 \use_amsmath 0
14 \use_natbib 0
15 \use_numerical_citations 0
16 \paperorientation portrait
17 \secnumdepth 3
18 \tocdepth 3
19 \paragraph_separation indent
20 \defskip medskip
21 \quotes_language swedish
22 \quotes_times 2
23 \papercolumns 1
24 \papersides 1
25 \paperpagestyle fancy
26
27 \layout Comment
28
29 Please note: double dashed longoptions (e.g.
30  --version) need three dashes in this document to be visable in html and
31  pdf output.
32 \layout Title
33
34 SDCC Compiler User Guide
35 \layout Standard
36
37
38 \begin_inset LatexCommand \tableofcontents{}
39
40 \end_inset 
41
42
43 \layout Section
44
45 Introduction
46 \layout Subsection
47
48 About SDCC
49 \layout Standard
50
51
52 \series bold 
53 SDCC
54 \series default 
55  is a Freeware, retargettable, optimizing ANSI-C compiler by 
56 \series bold 
57 Sandeep Dutta
58 \series default 
59  designed for 8 bit Microprocessors.
60  The current version targets Intel MCS51 based Microprocessors(8051,8052,
61  etc), Zilog Z80 based MCUs, and the Dallas DS80C390 variant.
62  It can be retargetted for other microprocessors, support for PIC, AVR and
63  186 is under development.
64  The entire source code for the compiler is distributed under GPL.
65  SDCC uses ASXXXX & ASLINK, a Freeware, retargettable assembler & linker.
66  SDCC has extensive language extensions suitable for utilizing various microcont
67 rollers and underlying hardware effectively.
68  
69 \newline 
70
71 \newline 
72 In addition to the MCU specific optimizations SDCC also does a host of standard
73  optimizations like:
74 \layout Itemize
75
76 global sub expression elimination, 
77 \layout Itemize
78
79 loop optimizations (loop invariant, strength reduction of induction variables
80  and loop reversing), 
81 \layout Itemize
82
83 constant folding & propagation, 
84 \layout Itemize
85
86 copy propagation, 
87 \layout Itemize
88
89 dead code elimination 
90 \layout Itemize
91
92 jumptables for 
93 \emph on 
94 switch
95 \emph default 
96  statements.
97 \layout Standard
98
99 For the back-end SDCC uses a global register allocation scheme which should
100  be well suited for other 8 bit MCUs.
101  
102 \newline 
103
104 \newline 
105 The peep hole optimizer uses a rule based substitution mechanism which is
106  MCU independent.
107  
108 \newline 
109
110 \newline 
111 Supported data-types are:
112 \layout Itemize
113
114 char (8 bits, 1 byte), 
115 \layout Itemize
116
117 short and int (16 bits, 2 bytes), 
118 \layout Itemize
119
120 long (32 bit, 4 bytes)
121 \layout Itemize
122
123 float (4 byte IEEE).
124  
125 \layout Standard
126
127 The compiler also allows 
128 \emph on 
129 inline assembler code
130 \emph default 
131  to be embedded anywhere in a function.
132  In addition, routines developed in assembly can also be called.
133 \newline 
134
135 \newline 
136 SDCC also provides an option (--cyclomatic) to report the relative complexity
137  of a function.
138  These functions can then be further optimized, or hand coded in assembly
139  if needed.
140  
141 \newline 
142
143 \newline 
144 SDCC also comes with a companion source level debugger SDCDB, the debugger
145  currently uses ucSim a freeware simulator for 8051 and other micro-controllers.
146  
147 \newline 
148
149 \newline 
150 The latest version can be downloaded from 
151 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
152
153 \end_inset 
154
155
156 \series bold 
157 .
158 \layout Subsection
159
160 Open Source
161 \layout Standard
162
163 All packages used in this compiler system are 
164 \emph on 
165 opensource
166 \emph default 
167  and 
168 \emph on 
169 freeware
170 \emph default 
171 ; source code for all the sub-packages (pre-processor, assemblers, linkers
172  etc) is distributed with the package.
173  This documentation is maintained using a freeware word processor (LyX).
174 \newline 
175 This program is free software; you can redistribute it and/or modify it
176  under the terms of the GNU General Public License as published by the Free
177  Software Foundation; either version 2, or (at your option) any later version.
178  This program is distributed in the hope that it will be useful, but WITHOUT
179  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
180  FOR A PARTICULAR PURPOSE.
181  See the GNU General Public License for more details.
182  You should have received a copy of the GNU General Public License along
183  with this program; if not, write to the Free Software Foundation, 59 Temple
184  Place - Suite 330, Boston, MA 02111-1307, USA.
185  In other words, you are welcome to use, share and improve this program.
186  You are forbidden to forbid anyone else to use, share and improve what
187  you give them.
188  Help stamp out software-hoarding! 
189 \layout Subsection
190
191 Typographic conventions
192 \layout Standard
193
194 Throughout this manual, we will use the following convention.
195  Commands you have to type in are printed in 
196 \family sans 
197 \series bold 
198 "sans serif"
199 \series default 
200 .
201
202 \family default 
203  Code samples are printed in 
204 \family typewriter 
205 typewriter font.
206
207 \family default 
208  Interesting items and new terms are printed in 
209 \emph on 
210 italic.
211 \layout Subsection
212
213 Compatibility with previous versions
214 \layout Standard
215
216 This version has numerous bug fixes compared with the previous version.
217  But we also introduced some incompatibilities with older versions.
218  Not just for the fun of it, but to make the compiler more stable, efficient
219  and ANSI compliant.
220  
221 \newline 
222
223 \layout Itemize
224
225 short is now equivalent to int (16 bits), it used to be equivalent to char
226  (8 bits) which is not ANSI compliant
227 \layout Itemize
228
229 the default directory for gcc-builds where include, library and documention
230  files are stored is now in /usr/local/share
231 \layout Itemize
232
233 char type parameters to vararg functions are casted to int unless explicitly
234  casted, e.g.: 
235 \newline 
236
237 \family typewriter 
238 \SpecialChar ~
239 \SpecialChar ~
240 char a=3;
241 \newline 
242 \SpecialChar ~
243 \SpecialChar ~
244 printf ("%d %c
245 \backslash 
246 n", a, (char)a);
247 \family default 
248
249 \newline 
250  will push a as an int and as a char resp.
251 \layout Itemize
252
253 option ---regextend has been removed
254 \layout Itemize
255
256 option ---noregparms has been removed
257 \layout Itemize
258
259 option ---stack-after-data has been removed
260 \layout Standard
261
262
263 \emph on 
264 <pending: more incompatibilities?>
265 \layout Subsection
266
267 System Requirements
268 \layout Standard
269
270 What do you need before you start installation of SDCC? A computer, and
271  a desire to compute.
272  The preferred method of installation is to compile SDCC from source using
273  GNU gcc and make.
274  For Windows some pre-compiled binary distributions are available for your
275  convenience.
276  You should have some experience with command line tools and compiler use.
277 \layout Subsection
278
279 Other Resources
280 \layout Standard
281
282 The SDCC home page at 
283 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
284
285 \end_inset 
286
287  is a great place to find distribution sets.
288  You can also find links to the user mailing lists that offer help or discuss
289  SDCC with other SDCC users.
290  Web links to other SDCC related sites can also be found here.
291  This document can be found in the DOC directory of the source package as
292  a text or HTML file.
293  Some of the other tools (simulator and assembler) included with SDCC contain
294  their own documentation and can be found in the source distribution.
295  If you want the latest unreleased software, the complete source package
296  is available directly by anonymous CVS on cvs.sdcc.sourceforge.net.
297 \layout Subsection
298
299 Wishes for the future
300 \layout Standard
301
302 There are (and always will be) some things that could be done.
303  Here are some I can think of:
304 \newline 
305
306 \layout Standard
307
308
309 \family typewriter 
310 char KernelFunction3(char p) at 0x340;
311 \newline 
312
313 \newline 
314
315 \family default 
316 If you can think of some more, please send them to the list.
317 \newline 
318
319 \newline 
320
321 \emph on 
322 <pending: And then of course a proper index-table
323 \begin_inset LatexCommand \index{index}
324
325 \end_inset 
326
327 >
328 \layout Section
329
330 Installation
331 \layout Subsection
332
333 Configure variables
334 \layout Standard
335
336 The install paths and default search paths are defined when running 'configure'.
337  The defaults can be overriden by
338 \layout Standard
339
340 ...
341  TBD
342 \newline 
343
344 \newline 
345 These configure variables are compiled into the binaries, and can only be
346  changed by rerunning 'configure' and recompiling SDCC.
347  The configure variables are written in 
348 \emph on 
349 italics
350 \emph default 
351  to distinguish them from run time environment variables (see section search
352  paths).
353 \newline 
354
355 \newline 
356 Cygwin is handled like a *nix, Mingw32 however belongs to the Win32 builds.
357  The SDCC team uses Mingw32 to build the official Windows binaries, because
358  it's
359 \layout Enumerate
360
361 open source, 
362 \layout Enumerate
363
364 a gcc compiler and last but not least
365 \layout Enumerate
366
367 the binaries can be built by cross compiling on Sourceforge's compile farm.
368 \layout Standard
369
370 The other Win32 builds using Borland, VC or whatever don't use 'configure',
371  but they (hopefully) use the default Win32 paths.
372 \newline 
373
374 \newline 
375 These defaults are:
376 \newline 
377
378 \newline 
379
380 \begin_inset  Tabular
381 <lyxtabular version="3" rows="8" columns="3">
382 <features>
383 <column alignment="left" valignment="top" leftline="true" width="0in">
384 <column alignment="left" valignment="top" leftline="true" width="0in">
385 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
386 <row topline="true" bottomline="true">
387 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
388 \begin_inset Text
389
390 \layout Standard
391
392 Variable
393 \end_inset 
394 </cell>
395 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
396 \begin_inset Text
397
398 \layout Standard
399
400 *nix default
401 \end_inset 
402 </cell>
403 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
404 \begin_inset Text
405
406 \layout Standard
407
408 Win32 default
409 \end_inset 
410 </cell>
411 </row>
412 <row topline="true">
413 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
414 \begin_inset Text
415
416 \layout Standard
417
418
419 \emph on 
420 PREFIX
421 \end_inset 
422 </cell>
423 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
424 \begin_inset Text
425
426 \layout Standard
427
428 /usr/local
429 \end_inset 
430 </cell>
431 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
432 \begin_inset Text
433
434 \layout Standard
435
436
437 \backslash 
438 sdcc
439 \end_inset 
440 </cell>
441 </row>
442 <row topline="true">
443 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
444 \begin_inset Text
445
446 \layout Standard
447
448
449 \emph on 
450 EXEC_PREFIX
451 \end_inset 
452 </cell>
453 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
454 \begin_inset Text
455
456 \layout Standard
457
458
459 \emph on 
460 $PREFIX
461 \end_inset 
462 </cell>
463 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
464 \begin_inset Text
465
466 \layout Standard
467
468
469 \emph on 
470 $PREFIX
471 \end_inset 
472 </cell>
473 </row>
474 <row topline="true">
475 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
476 \begin_inset Text
477
478 \layout Standard
479
480
481 \emph on 
482 BINDIR
483 \end_inset 
484 </cell>
485 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
486 \begin_inset Text
487
488 \layout Standard
489
490
491 \emph on 
492 $EXECPREFIX
493 \emph default 
494 /bin
495 \end_inset 
496 </cell>
497 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
498 \begin_inset Text
499
500 \layout Standard
501
502
503 \emph on 
504 $EXECPREFIX
505 \emph default 
506
507 \backslash 
508 bin
509 \end_inset 
510 </cell>
511 </row>
512 <row topline="true">
513 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
514 \begin_inset Text
515
516 \layout Standard
517
518
519 \emph on 
520 DATADIR
521 \end_inset 
522 </cell>
523 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
524 \begin_inset Text
525
526 \layout Standard
527
528
529 \emph on 
530 $PREFIX
531 \emph default 
532 /share
533 \end_inset 
534 </cell>
535 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
536 \begin_inset Text
537
538 \layout Standard
539
540
541 \emph on 
542 $PREFIX
543 \end_inset 
544 </cell>
545 </row>
546 <row topline="true">
547 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
548 \begin_inset Text
549
550 \layout Standard
551
552
553 \emph on 
554 DOCDIR
555 \end_inset 
556 </cell>
557 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
558 \begin_inset Text
559
560 \layout Standard
561
562
563 \emph on 
564 $DATADIR
565 \emph default 
566 /sdcc/doc
567 \end_inset 
568 </cell>
569 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
570 \begin_inset Text
571
572 \layout Standard
573
574
575 \emph on 
576 $DATADIR
577 \emph default 
578
579 \backslash 
580 doc
581 \end_inset 
582 </cell>
583 </row>
584 <row topline="true">
585 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
586 \begin_inset Text
587
588 \layout Standard
589
590
591 \emph on 
592 INCLUDE_DIR_SUFFIX
593 \end_inset 
594 </cell>
595 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
596 \begin_inset Text
597
598 \layout Standard
599
600 sdcc/include
601 \end_inset 
602 </cell>
603 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
604 \begin_inset Text
605
606 \layout Standard
607
608 include
609 \end_inset 
610 </cell>
611 </row>
612 <row topline="true" bottomline="true">
613 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
614 \begin_inset Text
615
616 \layout Standard
617
618
619 \emph on 
620 LIB_DIR_SUFFIX
621 \end_inset 
622 </cell>
623 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
624 \begin_inset Text
625
626 \layout Standard
627
628 sdcc/lib
629 \end_inset 
630 </cell>
631 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
632 \begin_inset Text
633
634 \layout Standard
635
636 lib
637 \end_inset 
638 </cell>
639 </row>
640 </lyxtabular>
641
642 \end_inset 
643
644
645 \newline 
646
647 \newline 
648
649 \newline 
650 'configure' also computes relative paths.
651  This is needed for full relocatability of a binary package and to complete
652  search paths (see section search paths below):
653 \newline 
654  
655 \newline 
656
657 \begin_inset  Tabular
658 <lyxtabular version="3" rows="4" columns="3">
659 <features>
660 <column alignment="left" valignment="top" leftline="true" width="0in">
661 <column alignment="left" valignment="top" leftline="true" width="0in">
662 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
663 <row topline="true" bottomline="true">
664 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
665 \begin_inset Text
666
667 \layout Standard
668
669 Variable (computed)
670 \end_inset 
671 </cell>
672 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
673 \begin_inset Text
674
675 \layout Standard
676
677 *nix default
678 \end_inset 
679 </cell>
680 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
681 \begin_inset Text
682
683 \layout Standard
684
685 Win32 default
686 \end_inset 
687 </cell>
688 </row>
689 <row topline="true" bottomline="true">
690 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
691 \begin_inset Text
692
693 \layout Standard
694
695
696 \emph on 
697 BIN2DATA_DIR
698 \end_inset 
699 </cell>
700 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
701 \begin_inset Text
702
703 \layout Standard
704
705 ../share
706 \end_inset 
707 </cell>
708 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
709 \begin_inset Text
710
711 \layout Standard
712
713 ..
714 \backslash 
715
716 \end_inset 
717 </cell>
718 </row>
719 <row bottomline="true">
720 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
721 \begin_inset Text
722
723 \layout Standard
724
725
726 \emph on 
727 PREFIX2BIN_DIR
728 \end_inset 
729 </cell>
730 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
731 \begin_inset Text
732
733 \layout Standard
734
735 bin
736 \end_inset 
737 </cell>
738 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
739 \begin_inset Text
740
741 \layout Standard
742
743 bin
744 \end_inset 
745 </cell>
746 </row>
747 <row bottomline="true">
748 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
749 \begin_inset Text
750
751 \layout Standard
752
753
754 \emph on 
755 PREFIX2DATA_DIR
756 \end_inset 
757 </cell>
758 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
759 \begin_inset Text
760
761 \layout Standard
762
763 share/sdcc
764 \end_inset 
765 </cell>
766 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
767 \begin_inset Text
768
769 \layout Standard
770
771 \end_inset 
772 </cell>
773 </row>
774 </lyxtabular>
775
776 \end_inset 
777
778
779 \layout Subsection
780
781 Install paths
782 \layout Standard
783
784 1.
785  Binary files (preprocessor, assembler and linker)
786 \layout Standard
787
788
789 \begin_inset  Tabular
790 <lyxtabular version="3" rows="2" columns="3">
791 <features>
792 <column alignment="left" valignment="top" leftline="true" width="0in">
793 <column alignment="left" valignment="top" leftline="true" width="0in">
794 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
795 <row topline="true" bottomline="true">
796 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
797 \begin_inset Text
798
799 \layout Standard
800
801 Path
802 \end_inset 
803 </cell>
804 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
805 \begin_inset Text
806
807 \layout Standard
808
809 *nix default
810 \end_inset 
811 </cell>
812 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
813 \begin_inset Text
814
815 \layout Standard
816
817 Win32 default
818 \end_inset 
819 </cell>
820 </row>
821 <row topline="true" bottomline="true">
822 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
823 \begin_inset Text
824
825 \layout Standard
826
827
828 \emph on 
829 $EXEC_PREFIX
830 \end_inset 
831 </cell>
832 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
833 \begin_inset Text
834
835 \layout Standard
836
837 /usr/local/bin
838 \end_inset 
839 </cell>
840 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
841 \begin_inset Text
842
843 \layout Standard
844
845
846 \backslash 
847 sdcc
848 \backslash 
849 bin
850 \end_inset 
851 </cell>
852 </row>
853 </lyxtabular>
854
855 \end_inset 
856
857  
858 \newline 
859
860 \newline 
861 2.
862  Include files
863 \layout Standard
864
865
866 \begin_inset  Tabular
867 <lyxtabular version="3" rows="2" columns="3">
868 <features>
869 <column alignment="block" valignment="top" leftline="true" width="1.6in">
870 <column alignment="center" valignment="top" leftline="true" width="0in">
871 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
872 <row topline="true" bottomline="true">
873 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
874 \begin_inset Text
875
876 \layout Standard
877
878 Path
879 \end_inset 
880 </cell>
881 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
882 \begin_inset Text
883
884 \layout Standard
885
886 *nix default
887 \end_inset 
888 </cell>
889 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
890 \begin_inset Text
891
892 \layout Standard
893
894 Win32 default
895 \end_inset 
896 </cell>
897 </row>
898 <row topline="true" bottomline="true">
899 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
900 \begin_inset Text
901
902 \layout Standard
903
904
905 \emph on 
906 $DATADIR/
907 \newline 
908 $INCLUDE_DIR_SUFFIX
909 \end_inset 
910 </cell>
911 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
912 \begin_inset Text
913
914 \layout Standard
915
916 /usr/local/share/sdcc/include
917 \end_inset 
918 </cell>
919 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
920 \begin_inset Text
921
922 \layout Standard
923
924
925 \backslash 
926 sdcc
927 \backslash 
928 include
929 \end_inset 
930 </cell>
931 </row>
932 </lyxtabular>
933
934 \end_inset 
935
936
937 \newline 
938
939 \newline 
940 3.
941  Library files (the 
942 \shape italic 
943 model
944 \shape default 
945  is auto-appended by the compiler, e.g.
946  small, large, z80, ds390 etc.)
947 \layout Standard
948
949
950 \begin_inset  Tabular
951 <lyxtabular version="3" rows="2" columns="3">
952 <features>
953 <column alignment="left" valignment="top" leftline="true" width="0in">
954 <column alignment="left" valignment="top" leftline="true" width="0in">
955 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
956 <row topline="true" bottomline="true">
957 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
958 \begin_inset Text
959
960 \layout Standard
961
962 Path
963 \end_inset 
964 </cell>
965 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
966 \begin_inset Text
967
968 \layout Standard
969
970 *nix default
971 \end_inset 
972 </cell>
973 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
974 \begin_inset Text
975
976 \layout Standard
977
978 Win32 default
979 \end_inset 
980 </cell>
981 </row>
982 <row topline="true" bottomline="true">
983 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
984 \begin_inset Text
985
986 \layout Standard
987
988
989 \emph on 
990 $DATADIR/$LIB_DIR_SUFFIX
991 \end_inset 
992 </cell>
993 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
994 \begin_inset Text
995
996 \layout Standard
997
998 /usr/local/share/sdcc/lib
999 \end_inset 
1000 </cell>
1001 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1002 \begin_inset Text
1003
1004 \layout Standard
1005
1006
1007 \backslash 
1008 sdcc
1009 \backslash 
1010 lib
1011 \end_inset 
1012 </cell>
1013 </row>
1014 </lyxtabular>
1015
1016 \end_inset 
1017
1018
1019 \newline 
1020
1021 \newline 
1022 4.
1023  Documentation
1024 \layout Standard
1025
1026
1027 \begin_inset  Tabular
1028 <lyxtabular version="3" rows="2" columns="3">
1029 <features>
1030 <column alignment="left" valignment="top" leftline="true" width="0in">
1031 <column alignment="left" valignment="top" leftline="true" width="0in">
1032 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
1033 <row topline="true" bottomline="true">
1034 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1035 \begin_inset Text
1036
1037 \layout Standard
1038
1039 Path
1040 \end_inset 
1041 </cell>
1042 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1043 \begin_inset Text
1044
1045 \layout Standard
1046
1047 *nix default
1048 \end_inset 
1049 </cell>
1050 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1051 \begin_inset Text
1052
1053 \layout Standard
1054
1055 Win32 default
1056 \end_inset 
1057 </cell>
1058 </row>
1059 <row topline="true" bottomline="true">
1060 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1061 \begin_inset Text
1062
1063 \layout Standard
1064
1065
1066 \emph on 
1067 $DOCDIR
1068 \end_inset 
1069 </cell>
1070 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1071 \begin_inset Text
1072
1073 \layout Standard
1074
1075 /usr/local/share/sdcc/doc
1076 \end_inset 
1077 </cell>
1078 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1079 \begin_inset Text
1080
1081 \layout Standard
1082
1083
1084 \backslash 
1085 sdcc
1086 \backslash 
1087 doc
1088 \end_inset 
1089 </cell>
1090 </row>
1091 </lyxtabular>
1092
1093 \end_inset 
1094
1095
1096 \layout Subsection
1097
1098 Search paths
1099 \layout Standard
1100
1101 Some search paths or parts of them are determined by configure variables
1102  (in 
1103 \emph on 
1104 italics
1105 \emph default 
1106 , see section above).
1107  Further search paths are determined by environment variables during runtime.
1108  
1109 \newline 
1110 The paths searched when running the compiler are as follows (the first catch
1111  wins):
1112 \newline 
1113
1114 \newline 
1115 1.
1116  Binary files (preprocessor, assembler and linker)
1117 \newline 
1118  
1119 \begin_inset  Tabular
1120 <lyxtabular version="3" rows="4" columns="3">
1121 <features>
1122 <column alignment="left" valignment="top" leftline="true" width="0in">
1123 <column alignment="left" valignment="top" leftline="true" width="0in">
1124 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
1125 <row topline="true" bottomline="true">
1126 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1127 \begin_inset Text
1128
1129 \layout Standard
1130
1131 Search path
1132 \end_inset 
1133 </cell>
1134 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1135 \begin_inset Text
1136
1137 \layout Standard
1138
1139 *nix default
1140 \end_inset 
1141 </cell>
1142 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1143 \begin_inset Text
1144
1145 \layout Standard
1146
1147 Win32 default
1148 \end_inset 
1149 </cell>
1150 </row>
1151 <row topline="true">
1152 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1153 \begin_inset Text
1154
1155 \layout Standard
1156
1157 $SDCC_HOME/
1158 \emph on 
1159 $PPREFIX2BIN_DIR
1160 \end_inset 
1161 </cell>
1162 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1163 \begin_inset Text
1164
1165 \layout Standard
1166
1167 $SDCC_HOME/bin
1168 \end_inset 
1169 </cell>
1170 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1171 \begin_inset Text
1172
1173 \layout Standard
1174
1175 $SDCC_HOME
1176 \backslash 
1177 bin
1178 \end_inset 
1179 </cell>
1180 </row>
1181 <row topline="true">
1182 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1183 \begin_inset Text
1184
1185 \layout Standard
1186
1187 Path of argv[0] (if available)
1188 \end_inset 
1189 </cell>
1190 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1191 \begin_inset Text
1192
1193 \layout Standard
1194
1195 Path of argv[0]
1196 \end_inset 
1197 </cell>
1198 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1199 \begin_inset Text
1200
1201 \layout Standard
1202
1203 Path of argv[0]
1204 \end_inset 
1205 </cell>
1206 </row>
1207 <row topline="true" bottomline="true">
1208 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1209 \begin_inset Text
1210
1211 \layout Standard
1212
1213 $PATH
1214 \end_inset 
1215 </cell>
1216 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1217 \begin_inset Text
1218
1219 \layout Standard
1220
1221 $PATH
1222 \end_inset 
1223 </cell>
1224 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1225 \begin_inset Text
1226
1227 \layout Standard
1228
1229 $PATH
1230 \end_inset 
1231 </cell>
1232 </row>
1233 </lyxtabular>
1234
1235 \end_inset 
1236
1237  
1238 \newline 
1239
1240 \newline 
1241 2.
1242  Include files
1243 \newline 
1244  
1245 \begin_inset  Tabular
1246 <lyxtabular version="3" rows="6" columns="3">
1247 <features>
1248 <column alignment="block" valignment="top" leftline="true" width="1.5in">
1249 <column alignment="block" valignment="top" leftline="true" width="1.5in">
1250 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
1251 <row topline="true" bottomline="true">
1252 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1253 \begin_inset Text
1254
1255 \layout Standard
1256
1257 Search path
1258 \end_inset 
1259 </cell>
1260 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1261 \begin_inset Text
1262
1263 \layout Standard
1264
1265 *nix default
1266 \end_inset 
1267 </cell>
1268 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1269 \begin_inset Text
1270
1271 \layout Standard
1272
1273 Win32 default
1274 \end_inset 
1275 </cell>
1276 </row>
1277 <row topline="true">
1278 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1279 \begin_inset Text
1280
1281 \layout Standard
1282
1283 ---I dir
1284 \end_inset 
1285 </cell>
1286 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1287 \begin_inset Text
1288
1289 \layout Standard
1290
1291 ---I dir
1292 \end_inset 
1293 </cell>
1294 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1295 \begin_inset Text
1296
1297 \layout Standard
1298
1299 ---I dir
1300 \end_inset 
1301 </cell>
1302 </row>
1303 <row topline="true">
1304 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
1305 \begin_inset Text
1306
1307 \layout Standard
1308
1309 $SDCC_INCLUDE
1310 \end_inset 
1311 </cell>
1312 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1313 \begin_inset Text
1314
1315 \layout Standard
1316
1317 $SDCC_INCLUDE
1318 \end_inset 
1319 </cell>
1320 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1321 \begin_inset Text
1322
1323 \layout Standard
1324
1325 $SDCC_INCLUDE
1326 \end_inset 
1327 </cell>
1328 </row>
1329 <row topline="true">
1330 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
1331 \begin_inset Text
1332
1333 \layout Standard
1334
1335 $SDCC_HOME/
1336 \newline 
1337
1338 \emph on 
1339 $PREFIX2DATA_DIR/
1340 \newline 
1341 $INCLUDE_DIR_SUFFIX
1342 \end_inset 
1343 </cell>
1344 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
1345 \begin_inset Text
1346
1347 \layout Standard
1348
1349 $SDCC_ HOME/
1350 \newline 
1351 share/sdcc/
1352 \newline 
1353 include
1354 \end_inset 
1355 </cell>
1356 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1357 \begin_inset Text
1358
1359 \layout Standard
1360
1361 $SDCC_HOME
1362 \backslash 
1363 include
1364 \end_inset 
1365 </cell>
1366 </row>
1367 <row topline="true">
1368 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
1369 \begin_inset Text
1370
1371 \layout Standard
1372
1373 path(argv[0])/
1374 \newline 
1375
1376 \emph on 
1377 $BIN2DATADIR/
1378 \emph default 
1379
1380 \newline 
1381
1382 \emph on 
1383 $INCLUDE_DIR_SUFFIX
1384 \end_inset 
1385 </cell>
1386 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1387 \begin_inset Text
1388
1389 \layout Standard
1390
1391 path(argv[0])/
1392 \newline 
1393 ../sdcc/include
1394 \end_inset 
1395 </cell>
1396 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1397 \begin_inset Text
1398
1399 \layout Standard
1400
1401 path(argv[0])
1402 \backslash 
1403 ..
1404 \backslash 
1405 include
1406 \end_inset 
1407 </cell>
1408 </row>
1409 <row topline="true" bottomline="true">
1410 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
1411 \begin_inset Text
1412
1413 \layout Standard
1414
1415
1416 \emph on 
1417 $DATADIR/
1418 \emph default 
1419
1420 \newline 
1421
1422 \emph on 
1423 $INCLUDE_DIR_SUFFIX
1424 \end_inset 
1425 </cell>
1426 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
1427 \begin_inset Text
1428
1429 \layout Standard
1430
1431 /usr/local/share/sdcc/
1432 \newline 
1433 include
1434 \end_inset 
1435 </cell>
1436 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1437 \begin_inset Text
1438
1439 \layout Standard
1440
1441 (not on Win32)
1442 \end_inset 
1443 </cell>
1444 </row>
1445 </lyxtabular>
1446
1447 \end_inset 
1448
1449  
1450 \newline 
1451
1452 \newline 
1453  The option ---nostdinc disables the last two search paths.
1454 \newline 
1455
1456 \newline 
1457 3.
1458  Library files 
1459 \newline 
1460 With the exception of 
1461 \begin_inset Quotes sld
1462 \end_inset 
1463
1464 ---L dir
1465 \begin_inset Quotes srd
1466 \end_inset 
1467
1468  the 
1469 \shape italic 
1470 model
1471 \shape default 
1472  is auto-appended by the compiler (e.g.
1473  small, large, z80, ds390 etc.).
1474  
1475 \newline 
1476
1477 \begin_inset  Tabular
1478 <lyxtabular version="3" rows="6" columns="3">
1479 <features>
1480 <column alignment="block" valignment="top" leftline="true" width="1.7in">
1481 <column alignment="block" valignment="top" leftline="true" width="1.2in">
1482 <column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
1483 <row topline="true" bottomline="true">
1484 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
1485 \begin_inset Text
1486
1487 \layout Standard
1488
1489 Search path
1490 \end_inset 
1491 </cell>
1492 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
1493 \begin_inset Text
1494
1495 \layout Standard
1496
1497 *nix default
1498 \end_inset 
1499 </cell>
1500 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1501 \begin_inset Text
1502
1503 \layout Standard
1504
1505 Win32 default
1506 \end_inset 
1507 </cell>
1508 </row>
1509 <row topline="true">
1510 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
1511 \begin_inset Text
1512
1513 \layout Standard
1514
1515 ---L dir
1516 \end_inset 
1517 </cell>
1518 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1519 \begin_inset Text
1520
1521 \layout Standard
1522
1523 ---L dir
1524 \end_inset 
1525 </cell>
1526 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1527 \begin_inset Text
1528
1529 \layout Standard
1530
1531 ---L dir
1532 \end_inset 
1533 </cell>
1534 </row>
1535 <row topline="true">
1536 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1537 \begin_inset Text
1538
1539 \layout Standard
1540
1541 $SDCC_LIB/
1542 \newline 
1543
1544 \emph on 
1545 <model>
1546 \end_inset 
1547 </cell>
1548 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
1549 \begin_inset Text
1550
1551 \layout Standard
1552
1553 $SDCC_LIB/
1554 \newline 
1555
1556 \emph on 
1557 <model>
1558 \end_inset 
1559 </cell>
1560 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1561 \begin_inset Text
1562
1563 \layout Standard
1564
1565 $SDCC_LIB
1566 \backslash 
1567
1568 \newline 
1569
1570 \emph on 
1571 <model>
1572 \end_inset 
1573 </cell>
1574 </row>
1575 <row topline="true">
1576 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
1577 \begin_inset Text
1578
1579 \layout Standard
1580
1581 $SDCC_HOME/
1582 \newline 
1583
1584 \emph on 
1585 $PREFIX2DATA_DIR/
1586 \newline 
1587 $LIB_DIR_SUFFIX/<model>
1588 \end_inset 
1589 </cell>
1590 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
1591 \begin_inset Text
1592
1593 \layout Standard
1594
1595 $SDCC_HOME/
1596 \newline 
1597 share/sdcc/
1598 \newline 
1599 lib/
1600 \emph on 
1601 <model>
1602 \end_inset 
1603 </cell>
1604 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1605 \begin_inset Text
1606
1607 \layout Standard
1608
1609 $SDCC_HOME
1610 \backslash 
1611 lib
1612 \backslash 
1613
1614 \emph on 
1615
1616 \newline 
1617 <model>
1618 \end_inset 
1619 </cell>
1620 </row>
1621 <row topline="true">
1622 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
1623 \begin_inset Text
1624
1625 \layout Standard
1626
1627 path(argv[0]/
1628 \newline 
1629
1630 \emph on 
1631 $BIN2DATADIR/
1632 \emph default 
1633
1634 \newline 
1635
1636 \emph on 
1637 $LIB_DIR_SUFFIX/<model>
1638 \end_inset 
1639 </cell>
1640 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
1641 \begin_inset Text
1642
1643 \layout Standard
1644
1645 path(argv[0])/
1646 \newline 
1647 ../sdcc/lib/
1648 \emph on 
1649 <model>
1650 \end_inset 
1651 </cell>
1652 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1653 \begin_inset Text
1654
1655 \layout Standard
1656
1657 path(argv[0]
1658 \backslash 
1659
1660 \newline 
1661 ..
1662 \backslash 
1663 lib
1664 \backslash 
1665
1666 \emph on 
1667 <model>
1668 \end_inset 
1669 </cell>
1670 </row>
1671 <row topline="true" bottomline="true">
1672 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1673 \begin_inset Text
1674
1675 \layout Standard
1676
1677
1678 \emph on 
1679 $DATADIR/
1680 \newline 
1681 $LIB_DIR_SUFFIX/<model>
1682 \end_inset 
1683 </cell>
1684 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1685 \begin_inset Text
1686
1687 \layout Standard
1688
1689 /usr/local/share/sdcc/
1690 \newline 
1691 lib/
1692 \emph on 
1693 <model>
1694 \end_inset 
1695 </cell>
1696 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1697 \begin_inset Text
1698
1699 \layout Standard
1700
1701 (not on Win32)
1702 \end_inset 
1703 </cell>
1704 </row>
1705 </lyxtabular>
1706
1707 \end_inset 
1708
1709
1710 \layout Comment
1711
1712 Don't delete any of the stray spaces in the table above without checking
1713  the HTML output (last line)!
1714 \layout Standard
1715
1716 \SpecialChar ~
1717
1718 \newline 
1719 The option ---nostdlib disables the last two search paths.
1720 \layout Subsection
1721
1722 Linux and other gcc-based systems (cygwin, mingw32, osx)
1723 \layout Enumerate
1724
1725
1726 \series medium 
1727 Download the source package
1728 \series default 
1729  either from the SDCC CVS repository or from the 
1730 \begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
1731
1732 \end_inset 
1733
1734
1735 \series medium 
1736 , it will be named something like sdcc
1737 \series default 
1738 .src
1739 \series medium 
1740 .t
1741 \series default 
1742 ar.
1743 \series medium 
1744 gz.
1745 \layout Enumerate
1746
1747
1748 \series medium 
1749 Bring up a command line terminal, such as xterm.
1750 \layout Enumerate
1751
1752
1753 \series medium 
1754 Unpack the file using a command like: 
1755 \family sans 
1756 \series bold 
1757 "tar -xzf sdcc.src.tar.gz
1758 \family default 
1759 \series default 
1760 "
1761 \series medium 
1762 , this will create a sub-directory called sdcc with all of the sources.
1763 \layout Enumerate
1764
1765 Change directory into the main SDCC directory, for example type: 
1766 \family sans 
1767 \series bold 
1768 "cd sdcc
1769 \series default 
1770 ".
1771 \layout Enumerate
1772
1773
1774 \series medium 
1775 Type 
1776 \family sans 
1777 \series bold 
1778 "./configure
1779 \family default 
1780 \series default 
1781 ".
1782  This configures the package for compilation on your system.
1783 \layout Enumerate
1784
1785
1786 \series medium 
1787 Type 
1788 \family sans 
1789 \series bold 
1790 "make
1791 \family default 
1792 \series default 
1793 "
1794 \series medium 
1795 .
1796
1797 \series default 
1798  All of the source packages will compile, this can take a while.
1799 \layout Enumerate
1800
1801
1802 \series medium 
1803 Type 
1804 \family sans 
1805 \series bold 
1806 "make install"
1807 \family default 
1808 \series default 
1809  as root
1810 \series medium 
1811 .
1812
1813 \series default 
1814  This copies the binary executables, the include files, the libraries and
1815  the documentation to the install directories.
1816 \layout Standard
1817
1818 On OSX 2.x it was reported, that the default gcc (version 3.1 20020420 (prerelease
1819 )) fails to compile SDCC.
1820  Fortunately there's also gcc 2.9.x installed, which works fine.
1821  This compiler can be selected by running 'configure' with:
1822 \layout LyX-Code
1823
1824 ./configure CC=gcc2 CXX=g++2
1825 \layout Subsection
1826
1827 Windows 
1828 \layout Subsubsection
1829
1830 Windows Install Using a Binary Package
1831 \layout Enumerate
1832
1833 Download the binary package and unpack it using your favorite unpacking
1834  tool (gunzip, WinZip, etc).
1835  This should unpack to a group of sub-directories.
1836  An example directory structure after unpacking the mingw32 package is:
1837  c:
1838 \backslash 
1839 usr
1840 \backslash 
1841 local
1842 \backslash 
1843 bin for the executables, c:
1844 \backslash 
1845 usr
1846 \backslash 
1847 local
1848 \backslash 
1849 share
1850 \backslash 
1851 sdcc
1852 \backslash 
1853 include and c:
1854 \backslash 
1855 usr
1856 \backslash 
1857 local
1858 \backslash 
1859 share
1860 \backslash 
1861 sdcc
1862 \backslash 
1863 lib for the include and libraries.
1864 \layout Enumerate
1865
1866 Adjust your environment variable PATH to include the location of the bin
1867  directory or start sdcc using the full path.
1868 \layout Subsubsection
1869
1870 Windows Install Using Cygwin and Mingw32
1871 \layout Standard
1872
1873 Follow the instruction in 
1874 \series bold 
1875 Linux and other gcc-based systems
1876 \series default 
1877 .
1878 \layout Subsubsection
1879
1880 Windows Install Using Microsoft Visual C++ 6.0/NET
1881 \layout Standard
1882
1883
1884 \series medium 
1885 Download the source package
1886 \series default 
1887  either from the SDCC CVS repository or from the 
1888 \begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
1889
1890 \end_inset 
1891
1892
1893 \series medium 
1894 , it will be named something like sdcc
1895 \series default 
1896 .src
1897 \series medium 
1898 .tgz.
1899
1900 \series default 
1901  SDCC is distributed with all the projects, workspaces, and files you need
1902  to build it using Visual C++ 6.0/NET.
1903  The workspace name is 'sdcc.dsw'.
1904  Please note that as it is now, all the executables are created in a folder
1905  called sdcc
1906 \backslash 
1907 bin_vc.
1908  Once built you need to copy the executables from sdcc
1909 \backslash 
1910 bin_vc to sdcc
1911 \backslash 
1912 bin before runnng SDCC.
1913  
1914 \newline 
1915
1916 \newline 
1917 In order to build SDCC with Visual C++ 6.0/NET you need win32 executables
1918  of bison.exe, flex.exe, and gawk.exe.
1919  One good place to get them is 
1920 \begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}
1921
1922 \end_inset 
1923
1924
1925 \newline 
1926
1927 \newline 
1928 Download the file UnxUtils.zip.
1929  Now you have to install the utilities and setup Visual C++ so it can locate
1930  the required programs.
1931  Here there are two alternatives (choose one!):
1932 \layout Enumerate
1933
1934 The easy way:
1935 \newline 
1936
1937 \newline 
1938 a) Extract UnxUtils.zip to your C:
1939 \backslash 
1940  hard disk PRESERVING the original paths, otherwise bison won't work.
1941  (If you are using WinZip make certain that 'Use folder names' is selected)
1942 \newline 
1943
1944 \newline 
1945 b) In the Visual C++ IDE click Tools, Options, select the Directory tab,
1946  in 'Show directories for:' select 'Executable files', and in the directories
1947  window add a new path: 'C:
1948 \backslash 
1949 user
1950 \backslash 
1951 local
1952 \backslash 
1953 wbin', click ok.
1954 \newline 
1955
1956 \newline 
1957 (As a side effect, you get a bunch of Unix utilities that could be useful,
1958  such as diff and patch.)
1959 \layout Enumerate
1960
1961 A more compact way:
1962 \newline 
1963
1964 \newline 
1965 This one avoids extracting a bunch of files you may not use, but requires
1966  some extra work:
1967 \newline 
1968
1969 \newline 
1970 a) Create a directory were to put the tools needed, or use a directory already
1971  present.
1972  Say for example 'C:
1973 \backslash 
1974 util'.
1975 \newline 
1976
1977 \newline 
1978 b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe
1979  to such directory WITHOUT preserving the original paths.
1980  (If you are using WinZip make certain that 'Use folder names' is not selected)
1981 \newline 
1982
1983 \newline 
1984 c) Rename bison.exe to '_bison.exe'.
1985 \newline 
1986
1987 \newline 
1988 d) Create a batch file 'bison.bat' in 'C:
1989 \backslash 
1990 util
1991 \backslash 
1992 ' and add these lines: 
1993 \newline 
1994 \SpecialChar ~
1995 \SpecialChar ~
1996 set BISON_SIMPLE=C:
1997 \backslash 
1998 util
1999 \backslash 
2000 bison.simple 
2001 \newline 
2002 \SpecialChar ~
2003 \SpecialChar ~
2004 set BISON_HAIRY=C:
2005 \backslash 
2006 util
2007 \backslash 
2008 bison.hairy
2009 \newline 
2010 \SpecialChar ~
2011 \SpecialChar ~
2012 _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
2013 \newline 
2014
2015 \newline 
2016 Steps 'c' and 'd' are needed because bison requires by default that the
2017  files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory,
2018  '/usr/local/share/' I think.
2019  So it is necessary to tell bison where those files are located if they
2020  are not in such directory.
2021  That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
2022 \newline 
2023
2024 \newline 
2025 e) In the Visual C++ IDE click Tools, Options, select the Directory tab,
2026  in 'Show directories for:' select 'Executable files', and in the directories
2027  window add a new path: 'c:
2028 \backslash 
2029 util', click ok.
2030  Note that you can use any other path instead of 'c:
2031 \backslash 
2032 util', even the path where the Visual C++ tools are, probably: 'C:
2033 \backslash 
2034 Program Files
2035 \backslash 
2036 Microsoft Visual Studio
2037 \backslash 
2038 Common
2039 \backslash 
2040 Tools'.
2041  So you don't have to execute step 'e' :)
2042 \layout Standard
2043
2044 That is it.
2045  Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
2046  the executables from sdcc
2047 \backslash 
2048 bin_vc to sdcc
2049 \backslash 
2050 bin, and you can compile using sdcc.
2051 \layout Subsubsection
2052
2053 Windows Install Using Borland
2054 \layout Enumerate
2055
2056 From the sdcc directory, run the command "make -f Makefile.bcc".
2057  This should regenerate all the .exe files in the bin directory except for
2058  sdcdb.exe (which currently doesn't build under Borland C++).
2059 \layout Enumerate
2060
2061 If you modify any source files and need to rebuild, be aware that the dependanci
2062 es may not be correctly calculated.
2063  The safest option is to delete all .obj files and run the build again.
2064  From a Cygwin BASH prompt, this can easily be done with the commmand:
2065 \newline 
2066
2067 \newline 
2068
2069 \family sans 
2070 \series bold 
2071 find .
2072  
2073 \backslash 
2074 ( -name '*.obj' -o -name '*.lib' -o -name '*.rul' 
2075 \backslash 
2076 ) -print -exec rm {} 
2077 \backslash 
2078 ;
2079 \family default 
2080 \series default 
2081
2082 \newline 
2083
2084 \newline 
2085 or on Windows NT/2000/XP from the command prompt with the commmand:
2086 \newline 
2087
2088 \family sans 
2089 \series bold 
2090
2091 \newline 
2092 del /s *.obj *.lib *.rul
2093 \family default 
2094 \series default 
2095  from the sdcc directory.
2096 \layout Subsection
2097
2098 Testing out the SDCC Compiler
2099 \layout Standard
2100
2101 The first thing you should do after installing your SDCC compiler is to
2102  see if it runs.
2103  Type 
2104 \family sans 
2105 \series bold 
2106 "sdcc ---version"
2107 \family default 
2108 \series default 
2109  at the prompt, and the program should run and tell you the version.
2110  If it doesn't run, or gives a message about not finding sdcc program, then
2111  you need to check over your installation.
2112  Make sure that the sdcc bin directory is in your executable search path
2113  defined by the PATH environment setting (see the Trouble-shooting section
2114  for suggestions).
2115  Make sure that the sdcc program is in the bin folder, if not perhaps something
2116  did not install correctly.
2117 \newline 
2118
2119 \newline 
2120
2121 \series medium 
2122 SDCC 
2123 \series default 
2124 is commonly installed as described in section 
2125 \begin_inset Quotes sld
2126 \end_inset 
2127
2128 Install and search paths
2129 \begin_inset Quotes srd
2130 \end_inset 
2131
2132
2133 \newline 
2134
2135 \newline 
2136
2137 \series medium 
2138 Make sure the compiler works on a very simple example.
2139  Type in the following test.c program using your favorite 
2140 \series default 
2141 ascii 
2142 \series medium 
2143 editor:
2144 \series default 
2145
2146 \newline 
2147
2148 \family typewriter 
2149
2150 \newline 
2151 char test;
2152 \newline 
2153
2154 \newline 
2155 void main(void) {
2156 \newline 
2157 \SpecialChar ~
2158 \SpecialChar ~
2159 \SpecialChar ~
2160 \SpecialChar ~
2161 test=0;
2162 \newline 
2163 }
2164 \family default 
2165
2166 \newline 
2167
2168 \emph on 
2169
2170 \newline 
2171
2172 \series medium 
2173 \emph default 
2174 Compile this using the following command: 
2175 \family sans 
2176 \series bold 
2177 "sdcc -c test.c".
2178
2179 \family default 
2180 \series default 
2181  
2182 \series medium 
2183 If all goes well, the compiler will generate a test.asm and test.rel file.
2184  Congratulations, you've just compiled your first program with SDCC.
2185  We used the -c option to tell SDCC not to link the generated code, just
2186  to keep things simple for this step.
2187 \series default 
2188
2189 \newline 
2190
2191 \newline 
2192
2193 \series medium 
2194 The next step is to try it with the linker.
2195  Type in 
2196 \family sans 
2197 \series bold 
2198 "sdcc test.c
2199 \family default 
2200 \series default 
2201 "
2202 \series medium 
2203 .
2204  If all goes well the compiler will link with the libraries and produce
2205  a test.ihx output file.
2206  If this step fails
2207 \series default 
2208  
2209 \series medium 
2210 (no test.ihx, and the linker generates warnings), then the problem is most
2211  likely that sdcc cannot find the 
2212 \series default 
2213 /
2214 \series medium 
2215 usr/local/share/sdcc/lib directory
2216 \series default 
2217  
2218 \series medium 
2219 (see the Install trouble-shooting section for suggestions).
2220 \series default 
2221
2222 \newline 
2223
2224 \newline 
2225
2226 \series medium 
2227 The final test is to ensure sdcc can use the 
2228 \series default 
2229 standard
2230 \series medium 
2231  header files and libraries.
2232  Edit test.c and change it to the following:
2233 \series default 
2234
2235 \newline 
2236
2237 \newline 
2238
2239 \family typewriter 
2240 #include <string.h>
2241 \newline 
2242
2243 \newline 
2244 char str1[10];
2245 \newline 
2246
2247 \newline 
2248 void main(void) {
2249 \newline 
2250 \SpecialChar ~
2251 \SpecialChar ~
2252 strcpy(str1, "testing");
2253 \newline 
2254 }
2255 \newline 
2256
2257 \newline 
2258
2259 \family default 
2260 \series medium 
2261 Compile this by typing 
2262 \family sans 
2263 \series bold 
2264 "sdcc test.c"
2265 \family default 
2266 \series medium 
2267 .
2268  This should generate a test.ihx output file, and it should give no warnings
2269  such as not finding the string.h file.
2270  If it cannot find the string.h file, then the problem is that sdcc cannot
2271  find the /usr/local/share/sdcc/include directory
2272 \series default 
2273  
2274 \series medium 
2275 (see the Install trouble-shooting section for suggestions).
2276 \layout Subsection
2277
2278 Install Trouble-shooting
2279 \layout Subsubsection
2280
2281 SDCC does not build correctly.
2282 \layout Standard
2283
2284 A thing to try is starting from scratch by unpacking the .tgz source package
2285  again in an empty directory.
2286  Confure it like:
2287 \newline 
2288
2289 \newline 
2290
2291 \family sans 
2292 \series bold 
2293 ./configure 2>&1 | tee configure.log
2294 \family default 
2295 \series default 
2296
2297 \newline 
2298
2299 \newline 
2300 and build it like:
2301 \newline 
2302
2303 \newline 
2304
2305 \family sans 
2306 \series bold 
2307 make 2>&1 | tee make.log
2308 \family default 
2309 \series default 
2310
2311 \newline 
2312
2313 \newline 
2314 If anything goes wrong, you can review the log files to locate the problem.
2315  Or a relevant part of this can be attached to an email that could be helpful
2316  when requesting help from the mailing list.
2317 \layout Subsubsection
2318
2319 What the 
2320 \begin_inset Quotes sld
2321 \end_inset 
2322
2323 ./configure
2324 \begin_inset Quotes srd
2325 \end_inset 
2326
2327  does
2328 \layout Standard
2329
2330 The 
2331 \begin_inset Quotes sld
2332 \end_inset 
2333
2334 ./configure
2335 \begin_inset Quotes srd
2336 \end_inset 
2337
2338  command is a script that analyzes your system and performs some configuration
2339  to ensure the source package compiles on your system.
2340  It will take a few minutes to run, and will compile a few tests to determine
2341  what compiler features are installed.
2342 \layout Subsubsection
2343
2344 What the 
2345 \begin_inset Quotes sld
2346 \end_inset 
2347
2348 make
2349 \begin_inset Quotes srd
2350 \end_inset 
2351
2352  does.
2353 \layout Standard
2354
2355 This runs the GNU make tool, which automatically compiles all the source
2356  packages into the final installed binary executables.
2357 \layout Subsubsection
2358
2359 What the 
2360 \begin_inset Quotes sld
2361 \end_inset 
2362
2363 make install
2364 \begin_inset Quotes erd
2365 \end_inset 
2366
2367  command does.
2368 \layout Standard
2369
2370 This will install the compiler, other executables libraries and include
2371  files in to the appropriate directories.
2372  See section 
2373 \begin_inset Quotes sld
2374 \end_inset 
2375
2376 Install and Search PATHS
2377 \begin_inset Quotes srd
2378 \end_inset 
2379
2380 .
2381 \newline 
2382 On most systems you will need super-user privilages to do this.
2383 \layout Subsection
2384
2385 Components of SDCC
2386 \layout Standard
2387
2388 SDCC is not just a compiler, but a collection of tools by various developers.
2389  These include linkers, assemblers, simulators and other components.
2390  Here is a summary of some of the components.
2391  Note that the included simulator and assembler have separate documentation
2392  which you can find in the source package in their respective directories.
2393  As SDCC grows to include support for other processors, other packages from
2394  various developers are included and may have their own sets of documentation.
2395 \newline 
2396
2397 \newline 
2398 You might want to look at the files which are installed in <installdir>.
2399  At the time of this writing, we find the following programs for gcc-builds:
2400 \newline 
2401  
2402 \newline 
2403 In <installdir>/bin:
2404 \layout Itemize
2405
2406 sdcc - The compiler.
2407 \layout Itemize
2408
2409 sdcpp - The C preprocessor.
2410 \layout Itemize
2411
2412 asx8051 - The assembler for 8051 type processors.
2413 \layout Itemize
2414
2415 as-z80
2416 \series bold 
2417
2418 \series default 
2419 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
2420 \layout Itemize
2421
2422 aslink -The linker for 8051 type processors.
2423 \layout Itemize
2424
2425 link-z80
2426 \series bold 
2427
2428 \series default 
2429 link-gbz80 - The Z80 and GameBoy Z80 linkers.
2430 \layout Itemize
2431
2432 s51 - The ucSim 8051 simulator.
2433 \layout Itemize
2434
2435 sdcdb - The source debugger.
2436 \layout Itemize
2437
2438 packihx - A tool to pack (compress) Intel hex files.
2439 \layout Standard
2440
2441 In <installdir>/share/sdcc/include
2442 \layout Itemize
2443
2444 the include files
2445 \layout Standard
2446
2447 In <installdir>/share/sdcc/lib
2448 \layout Itemize
2449
2450 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
2451  relocatables.
2452 \layout Standard
2453
2454 In <installdir>/share/sdcc/doc
2455 \layout Itemize
2456
2457 the documentation
2458 \layout Standard
2459
2460 As development for other processors proceeds, this list will expand to include
2461  executables to support processors like AVR, PIC, etc.
2462 \layout Subsubsection
2463
2464 sdcc - The Compiler
2465 \layout Standard
2466
2467 This is the actual compiler, it in turn uses the c-preprocessor and invokes
2468  the assembler and linkage editor.
2469 \layout Subsubsection
2470
2471 sdcpp - The C-Preprocessor
2472 \layout Standard
2473
2474 The preprocessor is a modified version of the GNU preprocessor.
2475  The C preprocessor is used to pull in #include sources, process #ifdef
2476  statements, #defines and so on.
2477 \layout Subsubsection
2478
2479 asx8051, as-z80, as-gbz80, aslink, link-z80, link-gbz80 - The Assemblers
2480  and Linkage Editors
2481 \layout Standard
2482
2483 This is retargettable assembler & linkage editor, it was developed by Alan
2484  Baldwin.
2485  John Hartman created the version for 8051, and I (Sandeep) have made some
2486  enhancements and bug fixes for it to work properly with the SDCC.
2487 \layout Subsubsection
2488
2489 s51 - The Simulator
2490 \layout Standard
2491
2492 S51 is a freeware, opensource simulator developed by Daniel Drotos (
2493 \begin_inset LatexCommand \url{mailto:drdani@mazsola.iit.uni-miskolc.hu}
2494
2495 \end_inset 
2496
2497 ).
2498  The simulator is built as part of the build process.
2499  For more information visit Daniel's website at: 
2500 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
2501
2502 \end_inset 
2503
2504 .
2505  It currently support the core mcs51, the Dallas DS80C390 and the Philips
2506  XA51 family.
2507 \layout Subsubsection
2508
2509 sdcdb - Source Level Debugger
2510 \layout Standard
2511
2512
2513 \family typewriter 
2514 \shape italic 
2515 <todo: is this thing still alive?>
2516 \newline 
2517
2518 \newline 
2519
2520 \family default 
2521 \shape default 
2522 Sdcdb is the companion source level debugger.
2523  The current version of the debugger uses Daniel's Simulator S51, but can
2524  be easily changed to use other simulators.
2525 \layout Section
2526
2527 Using SDCC
2528 \layout Subsection
2529
2530 Compiling
2531 \layout Subsubsection
2532
2533 Single Source File Projects
2534 \layout Standard
2535
2536 For single source file 8051 projects the process is very simple.
2537  Compile your programs with the following command 
2538 \family sans 
2539 \series bold 
2540 "sdcc sourcefile.c".
2541
2542 \family default 
2543 \series default 
2544  This will compile, assemble and link your source file.
2545  Output files are as follows
2546 \newline 
2547
2548 \newline 
2549 sourcefile.asm - Assembler source file created by the compiler
2550 \newline 
2551 sourcefile.lst - Assembler listing file created by the Assembler
2552 \newline 
2553 sourcefile.rst - Assembler listing file updated with linkedit information,
2554  created by linkage editor
2555 \newline 
2556 sourcefile.sym - symbol listing for the sourcefile, created by the assembler
2557 \newline 
2558 sourcefile.rel - Object file created by the assembler, input to Linkage editor
2559 \newline 
2560 sourcefile.map - The memory map for the load module, created by the Linker
2561 \newline 
2562 sourcefile.ihx - The load module in Intel hex format (you can select the
2563  Motorola S19 format with ---out-fmt-s19)
2564 \newline 
2565 sourcefile.cdb - An optional file (with ---debug) containing debug information
2566 \newline 
2567 sourcefile.dump* - Dump file to debug the compiler it self (with ---dumpall)
2568  (see section 
2569 \begin_inset Quotes sld
2570 \end_inset 
2571
2572 Anatomy of the compiler
2573 \begin_inset Quotes srd
2574 \end_inset 
2575
2576 ).
2577 \layout Subsubsection
2578
2579 Projects with Multiple Source Files
2580 \layout Standard
2581
2582 SDCC can compile only ONE file at a time.
2583  Let us for example assume that you have a project containing the following
2584  files:
2585 \newline 
2586
2587 \newline 
2588 foo1.c (contains some functions)
2589 \newline 
2590 foo2.c (contains some more functions)
2591 \newline 
2592 foomain.c (contains more functions and the function main)
2593 \newline 
2594
2595 \size footnotesize 
2596
2597 \newline 
2598
2599 \size default 
2600 The first two files will need to be compiled separately with the commands:
2601 \size footnotesize 
2602  
2603 \size default 
2604
2605 \newline 
2606
2607 \newline 
2608
2609 \family sans 
2610 \series bold 
2611 sdcc\SpecialChar ~
2612 -c\SpecialChar ~
2613 foo1.c
2614 \family default 
2615 \series default 
2616 \size footnotesize 
2617
2618 \newline 
2619
2620 \family sans 
2621 \series bold 
2622 \size default 
2623 sdcc\SpecialChar ~
2624 -c\SpecialChar ~
2625 foo2.c
2626 \family default 
2627 \series default 
2628
2629 \newline 
2630
2631 \newline 
2632 Then compile the source file containing the 
2633 \emph on 
2634 main()
2635 \emph default 
2636  function and link the files together with the following command: 
2637 \newline 
2638
2639 \newline 
2640
2641 \family sans 
2642 \series bold 
2643 sdcc\SpecialChar ~
2644 foomain.c\SpecialChar ~
2645 foo1.rel\SpecialChar ~
2646 foo2.rel
2647 \family default 
2648 \series default 
2649
2650 \newline 
2651
2652 \newline 
2653 Alternatively, 
2654 \emph on 
2655 foomain.c 
2656 \emph default 
2657 can be separately compiled as well: 
2658 \family sans 
2659 \series bold 
2660
2661 \newline 
2662
2663 \newline 
2664 sdcc\SpecialChar ~
2665 -c\SpecialChar ~
2666 foomain.c
2667 \newline 
2668 sdcc foomain.rel foo1.rel foo2.rel
2669 \newline 
2670
2671 \newline 
2672
2673 \family default 
2674 \series default 
2675 The file containing the 
2676 \emph on 
2677 main()
2678 \emph default 
2679  function
2680 \emph on 
2681  
2682 \emph default 
2683 \noun on 
2684 must
2685 \noun default 
2686  be the 
2687 \noun on 
2688 first
2689 \noun default 
2690  file specified in the command line, since the linkage editor processes
2691  file in the order they are presented to it.
2692 \layout Subsubsection
2693
2694 Projects with Additional Libraries
2695 \layout Standard
2696
2697 Some reusable routines may be compiled into a library, see the documentation
2698  for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
2699  for how to create a 
2700 \emph on 
2701 .lib
2702 \emph default 
2703  library file.
2704  Libraries created in this manner can be included in the command line.
2705  Make sure you include the -L <library-path> option to tell the linker where
2706  to look for these files if they are not in the current directory.
2707  Here is an example, assuming you have the source file 
2708 \emph on 
2709 foomain.c
2710 \emph default 
2711  and a library
2712 \emph on 
2713  foolib.lib
2714 \emph default 
2715  in the directory 
2716 \emph on 
2717 mylib
2718 \emph default 
2719  (if that is not the same as your current project):
2720 \newline 
2721
2722 \newline 
2723
2724 \family sans 
2725 \series bold 
2726 sdcc foomain.c foolib.lib -L mylib
2727 \newline 
2728
2729 \newline 
2730
2731 \family default 
2732 \series default 
2733 Note here that
2734 \emph on 
2735  mylib
2736 \emph default 
2737  must be an absolute path name.
2738 \newline 
2739
2740 \newline 
2741 The most efficient way to use libraries is to keep seperate modules in seperate
2742  source files.
2743  The lib file now should name all the modules.rel files.
2744  For an example see the standard library file 
2745 \emph on 
2746 libsdcc.lib
2747 \emph default 
2748  in the directory <installdir>/share/lib/small.
2749 \layout Subsection
2750
2751 Command Line Options
2752 \layout Subsubsection
2753
2754 Processor Selection Options
2755 \layout List
2756 \labelwidthstring 00.00.0000
2757
2758
2759 \series bold 
2760 -mmcs51
2761 \series default 
2762  Generate code for the MCS51 (8051) family of processors.
2763  This is the default processor target.
2764 \layout List
2765 \labelwidthstring 00.00.0000
2766
2767
2768 \series bold 
2769 -mds390
2770 \series default 
2771  Generate code for the DS80C390 processor.
2772 \layout List
2773 \labelwidthstring 00.00.0000
2774
2775
2776 \series bold 
2777 -mz80
2778 \series default 
2779  Generate code for the Z80 family of processors.
2780 \layout List
2781 \labelwidthstring 00.00.0000
2782
2783
2784 \series bold 
2785 -mgbz80
2786 \series default 
2787  Generate code for the GameBoy Z80 processor.
2788 \layout List
2789 \labelwidthstring 00.00.0000
2790
2791
2792 \series bold 
2793 -mavr
2794 \series default 
2795  Generate code for the Atmel AVR processor (In development, not complete).
2796 \layout List
2797 \labelwidthstring 00.00.0000
2798
2799
2800 \series bold 
2801 -mpic14
2802 \series default 
2803  Generate code for the PIC 14-bit processors (In development, not complete).
2804 \layout List
2805 \labelwidthstring 00.00.0000
2806
2807
2808 \series bold 
2809 -mtlcs900h
2810 \series default 
2811  Generate code for the Toshiba TLCS-900H processor (In development, not
2812  complete).
2813 \layout List
2814 \labelwidthstring 00.00.0000
2815
2816
2817 \series bold 
2818 -mxa51
2819 \series default 
2820  Generate code for the Philips XA51 processor (In development, not complete).
2821 \layout Subsubsection
2822
2823 Preprocessor Options
2824 \layout List
2825 \labelwidthstring 00.00.0000
2826
2827
2828 \series bold 
2829 -I<path>
2830 \series default 
2831  The additional location where the pre processor will look for <..h> or 
2832 \begin_inset Quotes eld
2833 \end_inset 
2834
2835 ..h
2836 \begin_inset Quotes erd
2837 \end_inset 
2838
2839  files.
2840 \layout List
2841 \labelwidthstring 00.00.0000
2842
2843
2844 \series bold 
2845 -D<macro[=value]>
2846 \series default 
2847  Command line definition of macros.
2848  Passed to the pre processor.
2849 \layout List
2850 \labelwidthstring 00.00.0000
2851
2852
2853 \series bold 
2854 -M
2855 \series default 
2856  Tell the preprocessor to output a rule suitable for make describing the
2857  dependencies of each object file.
2858  For each source file, the preprocessor outputs one make-rule whose target
2859  is the object file name for that source file and whose dependencies are
2860  all the files `#include'd in it.
2861  This rule may be a single line or may be continued with `
2862 \backslash 
2863 '-newline if it is long.
2864  The list of rules is printed on standard output instead of the preprocessed
2865  C program.
2866  `-M' implies `-E'.
2867 \layout List
2868 \labelwidthstring 00.00.0000
2869
2870
2871 \series bold 
2872 -C
2873 \series default 
2874  Tell the preprocessor not to discard comments.
2875  Used with the `-E' option.
2876 \layout List
2877 \labelwidthstring 00.00.0000
2878
2879
2880 \series bold 
2881 -MM
2882 \size large 
2883 \bar under 
2884  
2885 \series default 
2886 \size default 
2887 \bar default 
2888 Like `-M' but the output mentions only the user header files included with
2889  `#include 
2890 \begin_inset Quotes eld
2891 \end_inset 
2892
2893 file"'.
2894  System header files included with `#include <file>' are omitted.
2895 \layout List
2896 \labelwidthstring 00.00.0000
2897
2898
2899 \series bold 
2900 -Aquestion(answer)
2901 \series default 
2902  Assert the answer answer for question, in case it is tested with a preprocessor
2903  conditional such as `#if #question(answer)'.
2904  `-A-' disables the standard assertions that normally describe the target
2905  machine.
2906 \layout List
2907 \labelwidthstring 00.00.0000
2908
2909
2910 \series bold 
2911 -Aquestion
2912 \series default 
2913  (answer) Assert the answer answer for question, in case it is tested with
2914  a preprocessor conditional such as `#if #question(answer)'.
2915  `-A-' disables the standard assertions that normally describe the target
2916  machine.
2917 \layout List
2918 \labelwidthstring 00.00.0000
2919
2920
2921 \series bold 
2922 -Umacro
2923 \series default 
2924  Undefine macro macro.
2925  `-U' options are evaluated after all `-D' options, but before any `-include'
2926  and `-imacros' options.
2927 \layout List
2928 \labelwidthstring 00.00.0000
2929
2930
2931 \series bold 
2932 -dM
2933 \series default 
2934  Tell the preprocessor to output only a list of the macro definitions that
2935  are in effect at the end of preprocessing.
2936  Used with the `-E' option.
2937 \layout List
2938 \labelwidthstring 00.00.0000
2939
2940
2941 \series bold 
2942 -dD
2943 \series default 
2944  Tell the preprocessor to pass all macro definitions into the output, in
2945  their proper sequence in the rest of the output.
2946 \layout List
2947 \labelwidthstring 00.00.0000
2948
2949
2950 \series bold 
2951 -dN
2952 \size large 
2953 \bar under 
2954  
2955 \series default 
2956 \size default 
2957 \bar default 
2958 Like `-dD' except that the macro arguments and contents are omitted.
2959  Only `#define name' is included in the output.
2960 \layout Subsubsection
2961
2962 Linker Options
2963 \layout List
2964 \labelwidthstring 00.00.0000
2965
2966
2967 \series bold 
2968 -L\SpecialChar ~
2969 ---lib-path
2970 \bar under 
2971  
2972 \series default 
2973 \bar default 
2974 <absolute path to additional libraries> This option is passed to the linkage
2975  editor's additional libraries search path.
2976  The path name must be absolute.
2977  Additional library files may be specified in the command line.
2978  See section Compiling programs for more details.
2979 \layout List
2980 \labelwidthstring 00.00.0000
2981
2982
2983 \series bold 
2984 ---xram-loc
2985 \series default 
2986 <Value> The start location of the external ram, default value is 0.
2987  The value entered can be in Hexadecimal or Decimal format, e.g.: ---xram-loc
2988  0x8000 or ---xram-loc 32768.
2989 \layout List
2990 \labelwidthstring 00.00.0000
2991
2992
2993 \series bold 
2994 ---code-loc
2995 \series default 
2996 <Value> The start location of the code segment, default value 0.
2997  Note when this option is used the interrupt vector table is also relocated
2998  to the given address.
2999  The value entered can be in Hexadecimal or Decimal format, e.g.: ---code-loc
3000  0x8000 or ---code-loc 32768.
3001 \layout List
3002 \labelwidthstring 00.00.0000
3003
3004
3005 \series bold 
3006 ---stack-loc
3007 \series default 
3008 <Value> By default the stack is placed after the data segment.
3009  Using this option the stack can be placed anywhere in the internal memory
3010  space of the 8051.
3011  The value entered can be in Hexadecimal or Decimal format, e.g.
3012  ---stack-loc 0x20 or ---stack-loc 32.
3013  Since the sp register is incremented before a push or call, the initial
3014  sp will be set to one byte prior the provided value.
3015  The provided value should not overlap any other memory areas such as used
3016  register banks or the data segment and with enough space for the current
3017  application.
3018 \layout List
3019 \labelwidthstring 00.00.0000
3020
3021
3022 \series bold 
3023 ---data-loc
3024 \series default 
3025 <Value> The start location of the internal ram data segment.
3026  The value entered can be in Hexadecimal or Decimal format, eg.
3027  ---data-loc 0x20 or ---data-loc 32.
3028  (By default, the start location of the internal ram data segment  is set
3029  as low as possible in memory, taking into account the used register banks
3030  and the bit segment at address 0x20.
3031  For example if register banks 0 and 1 are used without bit variables, the
3032  data segment will be set, if ---data-loc is not used, to location 0x10.)
3033 \layout List
3034 \labelwidthstring 00.00.0000
3035
3036
3037 \series bold 
3038 ---idata-loc
3039 \series default 
3040 <Value> The start location of the indirectly addressable internal ram, default
3041  value is 0x80.
3042  The value entered can be in Hexadecimal or Decimal format, eg.
3043  ---idata-loc 0x88 or ---idata-loc 136.
3044 \layout List
3045 \labelwidthstring 00.00.0000
3046
3047
3048 \series bold 
3049 ---out-fmt-ihx
3050 \bar under 
3051  
3052 \series default 
3053 \bar default 
3054 The linker output (final object code) is in Intel Hex format.
3055  (This is the default option).
3056 \layout List
3057 \labelwidthstring 00.00.0000
3058
3059
3060 \series bold 
3061 ---out-fmt-s19
3062 \bar under 
3063  
3064 \series default 
3065 \bar default 
3066 The linker output (final object code) is in Motorola S19 format.
3067 \layout Subsubsection
3068
3069 MCS51 Options
3070 \layout List
3071 \labelwidthstring 00.00.0000
3072
3073
3074 \series bold 
3075 ---model-large
3076 \series default 
3077  Generate code for Large model programs see section Memory Models for more
3078  details.
3079  If this option is used all source files in the project should be compiled
3080  with this option.
3081  In addition the standard library routines are compiled with small model,
3082  they will need to be recompiled.
3083 \layout List
3084 \labelwidthstring 00.00.0000
3085
3086
3087 \series bold 
3088 ---model-small
3089 \series default 
3090 \size large 
3091 \emph on 
3092  
3093 \size default 
3094 \emph default 
3095 Generate code for Small Model programs see section Memory Models for more
3096  details.
3097  This is the default model.
3098 \layout Subsubsection
3099
3100 DS390 Options
3101 \layout List
3102 \labelwidthstring 00.00.0000
3103
3104
3105 \series bold 
3106 ---model-flat24
3107 \series default 
3108 \size large 
3109 \emph on 
3110  
3111 \size default 
3112 \emph default 
3113 Generate 24-bit flat mode code.
3114  This is the one and only that the ds390 code generator supports right now
3115  and is default when using 
3116 \emph on 
3117 -mds390
3118 \emph default 
3119 .
3120  See section Memory Models for more details.
3121 \layout List
3122 \labelwidthstring 00.00.0000
3123
3124
3125 \series bold 
3126 ---stack-10bit
3127 \series default 
3128  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
3129  This is the one and only that the ds390 code generator supports right now
3130  and is default when using 
3131 \emph on 
3132 -mds390
3133 \emph default 
3134 .
3135  In this mode, the stack is located in the lower 1K of the internal RAM,
3136  which is mapped to 0x400000.
3137  Note that the support is incomplete, since it still uses a single byte
3138  as the stack pointer.
3139  This means that only the lower 256 bytes of the potential 1K stack space
3140  will actually be used.
3141  However, this does allow you to reclaim the precious 256 bytes of low RAM
3142  for use for the DATA and IDATA segments.
3143  The compiler will not generate any code to put the processor into 10 bit
3144  stack mode.
3145  It is important to ensure that the processor is in this mode before calling
3146  any re-entrant functions compiled with this option.
3147  In principle, this should work with the 
3148 \emph on 
3149 ---stack-auto
3150 \emph default 
3151  option, but that has not been tested.
3152  It is incompatible with the 
3153 \emph on 
3154 ---xstack
3155 \emph default 
3156  option.
3157  It also only makes sense if the processor is in 24 bit contiguous addressing
3158  mode (see the 
3159 \emph on 
3160 ---model-flat24 option
3161 \emph default 
3162 ).
3163 \layout Subsubsection
3164
3165 Optimization Options
3166 \layout List
3167 \labelwidthstring 00.00.0000
3168
3169
3170 \series bold 
3171 ---nogcse
3172 \series default 
3173  Will not do global subexpression elimination, this option may be used when
3174  the compiler creates undesirably large stack/data spaces to store compiler
3175  temporaries.
3176  A warning message will be generated when this happens and the compiler
3177  will indicate the number of extra bytes it allocated.
3178  It recommended that this option NOT be used, #pragma\SpecialChar ~
3179 NOGCSE can be used
3180  to turn off global subexpression elimination for a given function only.
3181 \layout List
3182 \labelwidthstring 00.00.0000
3183
3184
3185 \series bold 
3186 ---noinvariant
3187 \series default 
3188  Will not do loop invariant optimizations, this may be turned off for reasons
3189  explained for the previous option.
3190  For more details of loop optimizations performed see section Loop Invariants.It
3191  recommended that this option NOT be used, #pragma\SpecialChar ~
3192 NOINVARIANT can be used
3193  to turn off invariant optimizations for a given function only.
3194 \layout List
3195 \labelwidthstring 00.00.0000
3196
3197
3198 \series bold 
3199 ---noinduction
3200 \series default 
3201  Will not do loop induction optimizations, see section strength reduction
3202  for more details.It is recommended that this option is NOT used, #pragma\SpecialChar ~
3203 NOINDUCT
3204 ION can be used to turn off induction optimizations for a given function
3205  only.
3206 \layout List
3207 \labelwidthstring 00.00.0000
3208
3209
3210 \series bold 
3211 ---nojtbound
3212 \size large 
3213 \bar under 
3214  
3215 \series default 
3216 \size default 
3217 \bar default 
3218  Will not generate boundary condition check when switch statements are implement
3219 ed using jump-tables.
3220  See section Switch Statements for more details.
3221  It is recommended that this option is NOT used, #pragma\SpecialChar ~
3222 NOJTBOUND can be
3223  used to turn off boundary checking for jump tables for a given function
3224  only.
3225 \layout List
3226 \labelwidthstring 00.00.0000
3227
3228
3229 \series bold 
3230 ---noloopreverse
3231 \series default 
3232 \size large 
3233  
3234 \size default 
3235 Will not do loop reversal optimization.
3236 \layout List
3237 \labelwidthstring 00.00.0000
3238
3239 ---
3240 \series bold 
3241 nolabelopt
3242 \series default 
3243  Will not optimize labels (makes the dumpfiles more readable).
3244 \layout List
3245 \labelwidthstring 00.00.0000
3246
3247
3248 \series bold 
3249 ---no-xinit-opt
3250 \series default 
3251  Will not memcpy initialized data in far space from code space.
3252  This saves a few bytes in code space if you don't have initialized data.
3253 \layout Subsubsection
3254
3255 Other Options
3256 \layout List
3257 \labelwidthstring 00.00.0000
3258
3259
3260 \series bold 
3261 -c\SpecialChar ~
3262 ---compile-only
3263 \series default 
3264  will compile and assemble the source, but will not call the linkage editor.
3265 \layout List
3266 \labelwidthstring 00.00.0000
3267
3268
3269 \series bold 
3270 --c1mode
3271 \series default 
3272  reads the preprocessed source from standard input and compiles it.
3273  The file name for the assembler output must be specified using the -o option.
3274 \layout List
3275 \labelwidthstring 00.00.0000
3276
3277
3278 \series bold 
3279 -E
3280 \series default 
3281  Run only the C preprocessor.
3282  Preprocess all the C source files specified and output the results to standard
3283  output.
3284 \layout List
3285 \labelwidthstring 00.00.0000
3286
3287
3288 \series bold 
3289 -o\SpecialChar ~
3290 <path/file> 
3291 \series default 
3292 The output path resp.
3293  file where everything will be placed.
3294  If the parameter is a path, it must have a trailing slash (or backslash
3295  for the Windows binaries) to be recognized as a path.
3296  
3297 \layout List
3298 \labelwidthstring 00.00.0000
3299
3300
3301 \series bold 
3302 ---stack-auto
3303 \series default 
3304 \size large 
3305 \emph on 
3306  
3307 \size default 
3308 \emph default 
3309 All functions in the source file will be compiled as 
3310 \emph on 
3311 reentrant
3312 \emph default 
3313 , i.e.
3314  the parameters and local variables will be allocated on the stack.
3315  see section Parameters and Local Variables for more details.
3316  If this option is used all source files in the project should be compiled
3317  with this option.
3318  
3319 \layout List
3320 \labelwidthstring 00.00.0000
3321
3322
3323 \series bold 
3324 ---xstack
3325 \series default 
3326  Uses a pseudo stack in the first 256 bytes in the external ram for allocating
3327  variables and passing parameters.
3328  See section on external stack for more details.
3329 \layout List
3330 \labelwidthstring 00.00.0000
3331
3332
3333 \series bold 
3334 ---callee-saves function1[,function2][,function3]....
3335
3336 \series default 
3337  The compiler by default uses a caller saves convention for register saving
3338  across function calls, however this can cause unneccessary register pushing
3339  & popping when calling small functions from larger functions.
3340  This option can be used to switch the register saving convention for the
3341  function names specified.
3342  The compiler will not save registers when calling these functions, no extra
3343  code will be generated at the entry & exit for these functions to save
3344  & restore the registers used by these functions, this can SUBSTANTIALLY
3345  reduce code & improve run time performance of the generated code.
3346  In the future the compiler (with interprocedural analysis) will be able
3347  to determine the appropriate scheme to use for each function call.
3348  DO NOT use this option for built-in functions such as _muluint..., if this
3349  option is used for a library function the appropriate library function
3350  needs to be recompiled with the same option.
3351  If the project consists of multiple source files then all the source file
3352  should be compiled with the same ---callee-saves option string.
3353  Also see #pragma\SpecialChar ~
3354 CALLEE-SAVES.
3355 \layout List
3356 \labelwidthstring 00.00.0000
3357
3358
3359 \series bold 
3360 ---debug
3361 \bar under 
3362  
3363 \series default 
3364 \bar default 
3365 When this option is used the compiler will generate debug information, that
3366  can be used with the SDCDB.
3367  The debug information is collected in a file with .cdb extension.
3368  For more information see documentation for SDCDB.
3369 \layout List
3370 \labelwidthstring 00.00.0000
3371
3372
3373 \series bold 
3374 ---peep-file
3375 \series default 
3376 <filename> This option can be used to use additional rules to be used by
3377  the peep hole optimizer.
3378  See section Peep Hole optimizations for details on how to write these rules.
3379 \layout List
3380 \labelwidthstring 00.00.0000
3381
3382
3383 \series bold 
3384 -S
3385 \size large 
3386 \bar under 
3387  
3388 \series default 
3389 \size default 
3390 \bar default 
3391 Stop after the stage of compilation proper; do not assemble.
3392  The output is an assembler code file for the input file specified.
3393 \layout List
3394 \labelwidthstring 00.00.0000
3395
3396
3397 \series bold 
3398 -Wa_asmOption[,asmOption]
3399 \series default 
3400 ...
3401  Pass the asmOption to the assembler.
3402 \layout List
3403 \labelwidthstring 00.00.0000
3404
3405
3406 \series bold 
3407 -Wl_linkOption[,linkOption]
3408 \series default 
3409 ...
3410  Pass the linkOption to the linker.
3411 \layout List
3412 \labelwidthstring 00.00.0000
3413
3414
3415 \series bold 
3416 ---int-long-reent
3417 \series default 
3418 \size large 
3419  
3420 \size default 
3421  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
3422  Note by default these libraries are compiled as non-reentrant.
3423  See section Installation for more details.
3424 \layout List
3425 \labelwidthstring 00.00.0000
3426
3427
3428 \series bold 
3429 ---cyclomatic
3430 \bar under 
3431  
3432 \series default 
3433 \bar default 
3434 This option will cause the compiler to generate an information message for
3435  each function in the source file.
3436  The message contains some 
3437 \emph on 
3438 important
3439 \emph default 
3440  information about the function.
3441  The number of edges and nodes the compiler detected in the control flow
3442  graph of the function, and most importantly the 
3443 \emph on 
3444 cyclomatic complexity
3445 \emph default 
3446  see section on Cyclomatic Complexity for more details.
3447 \layout List
3448 \labelwidthstring 00.00.0000
3449
3450
3451 \series bold 
3452 ---float-reent
3453 \bar under 
3454  
3455 \series default 
3456 \bar default 
3457  Floating point library is compiled as reentrant.See section Installation
3458  for more details.
3459 \layout List
3460 \labelwidthstring 00.00.0000
3461
3462
3463 \series bold 
3464 ---nooverlay
3465 \series default 
3466   The compiler will not overlay parameters and local variables of any function,
3467  see section Parameters and local variables for more details.
3468 \layout List
3469 \labelwidthstring 00.00.0000
3470
3471
3472 \series bold 
3473 ---main-return
3474 \series default 
3475  This option can be used when the code generated is called by a monitor
3476  program.
3477  The compiler will generate a 'ret' upon return from the 'main' function.
3478  The default option is to lock up i.e.
3479  generate a 'ljmp '.
3480 \layout List
3481 \labelwidthstring 00.00.0000
3482
3483
3484 \series bold 
3485 ---no-peep
3486 \series default 
3487   Disable peep-hole optimization.
3488 \layout List
3489 \labelwidthstring 00.00.0000
3490
3491
3492 \series bold 
3493 ---peep-asm
3494 \series default 
3495   Pass the inline assembler code through the peep hole optimizer.
3496  This can cause unexpected changes to inline assembler code, please go through
3497  the peephole optimizer rules defined in the source file tree '<target>/peeph.def
3498 ' before using this option.
3499 \layout List
3500 \labelwidthstring 00.00.0000
3501
3502
3503 \series bold 
3504 ---iram-size
3505 \series default 
3506 <Value> Causes the linker to check if the internal ram usage is within limits
3507  of the given value.
3508 \layout List
3509 \labelwidthstring 00.00.0000
3510
3511
3512 \series bold 
3513 ---xram-size
3514 \series default 
3515 <Value> Causes the linker to check if the external ram usage is within limits
3516  of the given value.
3517 \layout List
3518 \labelwidthstring 00.00.0000
3519
3520
3521 \series bold 
3522 ---code-size
3523 \series default 
3524 <Value> Causes the linker to check if the code usage is within limits of
3525  the given value.
3526 \layout List
3527 \labelwidthstring 00.00.0000
3528
3529
3530 \series bold 
3531 ---nostdincl
3532 \series default 
3533  This will prevent the compiler from passing on the default include path
3534  to the preprocessor.
3535 \layout List
3536 \labelwidthstring 00.00.0000
3537
3538
3539 \series bold 
3540 ---nostdlib
3541 \series default 
3542  This will prevent the compiler from passing on the default library path
3543  to the linker.
3544 \layout List
3545 \labelwidthstring 00.00.0000
3546
3547
3548 \series bold 
3549 ---verbose
3550 \series default 
3551  Shows the various actions the compiler is performing.
3552 \layout List
3553 \labelwidthstring 00.00.0000
3554
3555
3556 \series bold 
3557 -V
3558 \series default 
3559  Shows the actual commands the compiler is executing.
3560 \layout List
3561 \labelwidthstring 00.00.0000
3562
3563
3564 \series bold 
3565 ---no-c-code-in-asm
3566 \series default 
3567  Hides your ugly and inefficient c-code from the asm file, so you can always
3568  blame the compiler :).
3569 \layout List
3570 \labelwidthstring 00.00.0000
3571
3572
3573 \series bold 
3574 ---i-code-in-asm
3575 \series default 
3576  Include i-codes in the asm file.
3577  Sounds like noise but is most helpfull for debugging the compiler itself.
3578 \layout List
3579 \labelwidthstring 00.00.0000
3580
3581
3582 \series bold 
3583 ---less-pedantic
3584 \series default 
3585  Disable some of the more pedantic warnings (jwk burps: please be more specific
3586  here, please!)
3587 \layout Subsubsection
3588
3589 Intermediate Dump Options
3590 \layout Standard
3591
3592 The following options are provided for the purpose of retargetting and debugging
3593  the compiler.
3594  These provided a means to dump the intermediate code (iCode) generated
3595  by the compiler in human readable form at various stages of the compilation
3596  process.
3597  
3598 \layout List
3599 \labelwidthstring 00.00.0000
3600
3601
3602 \series bold 
3603 ---dumpraw
3604 \series default 
3605  This option will cause the compiler to dump the intermediate code into
3606  a file of named 
3607 \emph on 
3608 <source filename>.dumpraw
3609 \emph default 
3610  just after the intermediate code has been generated for a function, i.e.
3611  before any optimizations are done.
3612  The basic blocks at this stage ordered in the depth first number, so they
3613  may not be in sequence of execution.
3614 \layout List
3615 \labelwidthstring 00.00.0000
3616
3617
3618 \series bold 
3619 ---dumpgcse
3620 \series default 
3621  Will create a dump of iCode's, after global subexpression elimination,
3622  into a file named 
3623 \emph on 
3624 <source filename>.dumpgcse.
3625 \layout List
3626 \labelwidthstring 00.00.0000
3627
3628
3629 \series bold 
3630 ---dumpdeadcode
3631 \series default 
3632  Will create a dump of iCode's, after deadcode elimination, into a file
3633  named 
3634 \emph on 
3635 <source filename>.dumpdeadcode.
3636 \layout List
3637 \labelwidthstring 00.00.0000
3638
3639
3640 \series bold 
3641 ---dumploop
3642 \series default 
3643 \size large 
3644  
3645 \size default 
3646 Will create a dump of iCode's, after loop optimizations, into a file named
3647  
3648 \emph on 
3649 <source filename>.dumploop.
3650 \layout List
3651 \labelwidthstring 00.00.0000
3652
3653
3654 \series bold 
3655 ---dumprange
3656 \series default 
3657 \size large 
3658  
3659 \size default 
3660 Will create a dump of iCode's, after live range analysis, into a file named
3661  
3662 \emph on 
3663 <source filename>.dumprange.
3664 \layout List
3665 \labelwidthstring 00.00.0000
3666
3667
3668 \series bold 
3669 ---dumlrange
3670 \series default 
3671  Will dump the life ranges for all symbols.
3672 \layout List
3673 \labelwidthstring 00.00.0000
3674
3675
3676 \series bold 
3677 ---dumpregassign
3678 \bar under 
3679  
3680 \series default 
3681 \bar default 
3682 Will create a dump of iCode's, after register assignment, into a file named
3683  
3684 \emph on 
3685 <source filename>.dumprassgn.
3686 \layout List
3687 \labelwidthstring 00.00.0000
3688
3689
3690 \series bold 
3691 ---dumplrange
3692 \series default 
3693  Will create a dump of the live ranges of iTemp's
3694 \layout List
3695 \labelwidthstring 00.00.0000
3696
3697
3698 \series bold 
3699 ---dumpall
3700 \size large 
3701 \bar under 
3702  
3703 \series default 
3704 \size default 
3705 \bar default 
3706 Will cause all the above mentioned dumps to be created.
3707 \layout Subsection
3708
3709 Environment variables
3710 \layout Standard
3711
3712 SDCC recognizes the following environment variables:
3713 \layout List
3714 \labelwidthstring 00.00.0000
3715
3716
3717 \series bold 
3718 SDCC_LEAVE_SIGNALS
3719 \series default 
3720  SDCC installs a signal handler to be able to delete temporary files after
3721  an user break (^C) or an exception.
3722  If this environment variable is set, SDCC won't install the signal handler
3723  in order to be able to debug SDCC.
3724 \layout List
3725 \labelwidthstring 00.00.0000
3726
3727
3728 \series bold 
3729 TMP,\SpecialChar ~
3730 TEMP,\SpecialChar ~
3731 TMPDIR
3732 \series default 
3733  Path, where temporary files will be created.
3734  The order of the variables is the search order.
3735  In a standard *nix environment these variables are not set, and there's
3736  no need to set them.
3737  On Windows it's recommended to set one of them.
3738 \layout List
3739 \labelwidthstring 00.00.0000
3740
3741
3742 \series bold 
3743 SDCC_HOME
3744 \series default 
3745  Path, see 
3746 \begin_inset Quotes sld
3747 \end_inset 
3748
3749 2.3 Install and search paths
3750 \begin_inset Quotes srd
3751 \end_inset 
3752
3753 .
3754 \layout List
3755 \labelwidthstring 00.00.0000
3756
3757
3758 \series bold 
3759 SDCC_INCLUDE
3760 \series default 
3761  Path, see 
3762 \begin_inset Quotes sld
3763 \end_inset 
3764
3765 2.3 Install and search paths
3766 \begin_inset Quotes srd
3767 \end_inset 
3768
3769 .
3770 \layout List
3771 \labelwidthstring 00.00.0000
3772
3773
3774 \series bold 
3775 SDCC_LIB
3776 \series default 
3777  Path, see 
3778 \begin_inset Quotes sld
3779 \end_inset 
3780
3781 2.3 Install and search paths
3782 \begin_inset Quotes srd
3783 \end_inset 
3784
3785 .
3786 \layout Standard
3787
3788 There are some more environment variables recognized by SDCC, but these
3789  are solely used for debugging purposes.
3790  They can change or disappear very quickly, and will never be documentated.
3791 \layout Subsection
3792
3793 MCS51/DS390 Storage Class Language Extensions
3794 \layout Standard
3795
3796 In addition to the ANSI storage classes SDCC allows the following MCS51
3797  specific storage classes.
3798 \layout Subsubsection
3799
3800 xdata
3801 \layout Standard
3802
3803 Variables declared with this storage class will be placed in the extern
3804  RAM.
3805  This is the 
3806 \series bold 
3807 default
3808 \series default 
3809  storage class for Large Memory model, e.g.:
3810 \newline 
3811
3812 \newline 
3813
3814 \family typewriter 
3815 xdata unsigned char xduc;
3816 \layout Subsubsection
3817
3818 data
3819 \layout Standard
3820
3821 This is the 
3822 \series bold 
3823 default
3824 \series default 
3825  storage class for Small Memory model.
3826  Variables declared with this storage class will be allocated in the internal
3827  RAM, e.g.:
3828 \newline 
3829
3830 \newline 
3831
3832 \family typewriter 
3833 data int iramdata;
3834 \layout Subsubsection
3835
3836 idata
3837 \layout Standard
3838
3839 Variables declared with this storage class will be allocated into the indirectly
3840  addressable portion of the internal ram of a 8051, e.g.:
3841 \newline 
3842
3843 \newline 
3844
3845 \family typewriter 
3846 idata int idi;
3847 \layout Subsubsection
3848
3849 bit
3850 \layout Standard
3851
3852 This is a data-type and a storage class specifier.
3853  When a variable is declared as a bit, it is allocated into the bit addressable
3854  memory of 8051, e.g.:
3855 \newline 
3856
3857 \newline 
3858
3859 \family typewriter 
3860 bit iFlag;
3861 \layout Subsubsection
3862
3863 sfr / sbit
3864 \layout Standard
3865
3866 Like the bit keyword, 
3867 \emph on 
3868 sfr / sbit 
3869 \emph default 
3870 signifies both a data-type and storage class, they are used to describe
3871  the special function registers and special bit variables of a 8051, eg:
3872 \newline 
3873
3874 \newline 
3875
3876 \family typewriter 
3877 sfr at 0x80 P0; /* special function register P0 at location 0x80 */
3878 \newline 
3879 sbit at 0xd7 CY; /* CY (Carry Flag) */
3880 \layout Subsection
3881
3882 Pointers
3883 \layout Standard
3884
3885 SDCC allows (via language extensions) pointers to explicitly point to any
3886  of the memory spaces of the 8051.
3887  In addition to the explicit pointers, the compiler uses (by default) generic
3888  pointers which can be used to point to any of the memory spaces.
3889 \newline 
3890
3891 \newline 
3892 Pointer declaration examples:
3893 \newline 
3894
3895 \size small 
3896
3897 \newline 
3898
3899 \family typewriter 
3900 \size default 
3901 /* pointer physically in xternal ram pointing to object in internal ram
3902  */ 
3903 \newline 
3904 data unsigned char * xdata p;
3905 \newline 
3906
3907 \newline 
3908 /* pointer physically in code rom pointing to data in xdata space */ 
3909 \newline 
3910 xdata unsigned char * code p;
3911 \newline 
3912
3913 \newline 
3914 /* pointer physically in code space pointing to data in code space */ 
3915 \newline 
3916 code unsigned char * code p;
3917 \newline 
3918
3919 \newline 
3920 /* the folowing is a generic pointer physically located in xdata space */
3921 \newline 
3922 char * xdata p;
3923 \family default 
3924 \size small 
3925
3926 \newline 
3927
3928 \newline 
3929
3930 \size default 
3931 Well you get the idea.
3932  
3933 \newline 
3934
3935 \newline 
3936 All unqualified pointers are treated as 3-byte (4-byte for the ds390) 
3937 \emph on 
3938 generic
3939 \emph default 
3940  pointers.
3941  
3942 \size small 
3943
3944 \newline 
3945
3946 \newline 
3947
3948 \size default 
3949 The highest order byte of the 
3950 \emph on 
3951 generic
3952 \emph default 
3953  pointers contains the data space information.
3954  Assembler support routines are called whenever data is stored or retrieved
3955  using 
3956 \emph on 
3957 generic
3958 \emph default 
3959  pointers.
3960  These are useful for developing reusable library routines.
3961  Explicitly specifying the pointer type will generate the most efficient
3962  code.
3963 \layout Subsection
3964
3965 Parameters & Local Variables
3966 \layout Standard
3967
3968 Automatic (local) variables and parameters to functions can either be placed
3969  on the stack or in data-space.
3970  The default action of the compiler is to place these variables in the internal
3971  RAM (for small model) or external RAM (for large model).
3972  This in fact makes them 
3973 \emph on 
3974 static
3975 \emph default 
3976  so by default functions are non-reentrant.
3977 \newline 
3978
3979 \newline 
3980 They can be placed on the stack either by using the
3981 \emph on 
3982  ---stack-auto
3983 \emph default 
3984  option or by using the 
3985 \emph on 
3986 reentrant
3987 \emph default 
3988  keyword in the function declaration, e.g.:
3989 \newline 
3990
3991 \size small 
3992
3993 \newline 
3994
3995 \family typewriter 
3996 \size default 
3997 unsigned char foo(char i) reentrant 
3998 \newline 
3999
4000 \newline 
4001 ...
4002  
4003 \newline 
4004 }
4005 \newline 
4006
4007 \family default 
4008
4009 \newline 
4010 Since stack space on 8051 is limited, the 
4011 \emph on 
4012 reentrant 
4013 \emph default 
4014 keyword or the
4015 \emph on 
4016  ---stack-auto
4017 \emph default 
4018  option should be used sparingly.
4019  Note that the reentrant keyword just means that the parameters & local
4020  variables will be allocated to the stack, it 
4021 \emph on 
4022 does not
4023 \emph default 
4024  mean that the function is register bank independent.
4025 \newline 
4026
4027 \newline 
4028 Local variables can be assigned storage classes and absolute addresses,
4029  e.g.: 
4030 \newline 
4031
4032 \newline 
4033
4034 \family typewriter 
4035 unsigned char foo() {
4036 \newline 
4037 \SpecialChar ~
4038 \SpecialChar ~
4039 \SpecialChar ~
4040 \SpecialChar ~
4041 xdata unsigned char i;
4042 \newline 
4043 \SpecialChar ~
4044 \SpecialChar ~
4045 \SpecialChar ~
4046 \SpecialChar ~
4047 bit bvar;
4048 \newline 
4049 \SpecialChar ~
4050 \SpecialChar ~
4051 \SpecialChar ~
4052 \SpecialChar ~
4053 data at 0x31 unsiged char j;
4054 \newline 
4055 \SpecialChar ~
4056 \SpecialChar ~
4057 \SpecialChar ~
4058 \SpecialChar ~
4059 ...
4060  
4061 \newline 
4062 }
4063 \newline 
4064
4065 \newline 
4066
4067 \family default 
4068 In the above example the variable 
4069 \emph on 
4070 i
4071 \emph default 
4072  will be allocated in the external ram, 
4073 \emph on 
4074 bvar
4075 \emph default 
4076  in bit addressable space and
4077 \emph on 
4078  j
4079 \emph default 
4080  in internal ram.
4081  When compiled with 
4082 \emph on 
4083 ---stack-auto
4084 \emph default 
4085  or when a function is declared as 
4086 \emph on 
4087 reentrant
4088 \emph default 
4089  this should only be done for static variables.
4090 \layout Standard
4091
4092 Parameters however are not allowed any storage class, (storage classes for
4093  parameters will be ignored), their allocation is governed by the memory
4094  model in use, and the reentrancy options.
4095 \layout Subsection
4096
4097 Overlaying
4098 \layout Standard
4099
4100 For non-reentrant functions SDCC will try to reduce internal ram space usage
4101  by overlaying parameters and local variables of a function (if possible).
4102  Parameters and local variables of a function will be allocated to an overlayabl
4103 e segment if the function has 
4104 \emph on 
4105 no other function calls and the function is non-reentrant and the memory
4106  model is small.
4107
4108 \emph default 
4109  If an explicit storage class is specified for a local variable, it will
4110  NOT be overlayed.
4111 \layout Standard
4112
4113 Note that the compiler (not the linkage editor) makes the decision for overlayin
4114 g the data items.
4115  Functions that are called from an interrupt service routine should be preceded
4116  by a #pragma\SpecialChar ~
4117 NOOVERLAY if they are not reentrant.
4118 \layout Standard
4119
4120 Also note that the compiler does not do any processing of inline assembler
4121  code, so the compiler might incorrectly assign local variables and parameters
4122  of a function into the overlay segment if the inline assembler code calls
4123  other c-functions that might use the overlay.
4124  In that case the #pragma\SpecialChar ~
4125 NOOVERLAY should be used.
4126 \layout Standard
4127
4128 Parameters and Local variables of functions that contain 16 or 32 bit multiplica
4129 tion or division will NOT be overlayed since these are implemented using
4130  external functions, e.g.:
4131 \newline 
4132
4133 \newline 
4134
4135 \family typewriter 
4136 #pragma SAVE 
4137 \newline 
4138 #pragma NOOVERLAY 
4139 \newline 
4140 void set_error(unsigned char errcd) 
4141 \newline 
4142 {
4143 \newline 
4144 \SpecialChar ~
4145 \SpecialChar ~
4146 \SpecialChar ~
4147 \SpecialChar ~
4148 P3 = errcd;
4149 \newline 
4150
4151 \newline 
4152 #pragma RESTORE 
4153 \newline 
4154
4155 \newline 
4156 void some_isr () interrupt 2 using 1 
4157 \newline 
4158 {
4159 \newline 
4160 \SpecialChar ~
4161 \SpecialChar ~
4162 \SpecialChar ~
4163 \SpecialChar ~
4164 ...
4165 \newline 
4166 \SpecialChar ~
4167 \SpecialChar ~
4168 \SpecialChar ~
4169 \SpecialChar ~
4170 set_error(10);
4171 \newline 
4172 \SpecialChar ~
4173 \SpecialChar ~
4174 \SpecialChar ~
4175 \SpecialChar ~
4176 ...
4177  
4178 \newline 
4179 }
4180 \newline 
4181
4182 \newline 
4183
4184 \family default 
4185 In the above example the parameter 
4186 \emph on 
4187 errcd
4188 \emph default 
4189  for the function 
4190 \emph on 
4191 set_error
4192 \emph default 
4193  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
4194 NOOVERLAY was
4195  not present, this could cause unpredictable runtime behavior when called
4196  from an ISR.
4197  The #pragma\SpecialChar ~
4198 NOOVERLAY ensures that the parameters and local variables for
4199  the function are NOT overlayed.
4200 \layout Subsection
4201
4202 Interrupt Service Routines
4203 \layout Standard
4204
4205 SDCC allows interrupt service routines to be coded in C, with some extended
4206  keywords.
4207 \newline 
4208
4209 \newline 
4210
4211 \family typewriter 
4212 void timer_isr (void) interrupt 2 using 1 
4213 \newline 
4214
4215 \newline 
4216 ..
4217  
4218 \newline 
4219 }
4220 \newline 
4221
4222 \newline 
4223
4224 \family default 
4225 The number following the 
4226 \emph on 
4227 interrupt
4228 \emph default 
4229  keyword is the interrupt number this routine will service.
4230  The compiler will insert a call to this routine in the interrupt vector
4231  table for the interrupt number specified.
4232  The 
4233 \emph on 
4234 using
4235 \emph default 
4236  keyword is used to tell the compiler to use the specified register bank
4237  (8051 specific) when generating code for this function.
4238  Note that when some function is called from an interrupt service routine
4239  it should be preceded by a #pragma\SpecialChar ~
4240 NOOVERLAY if it is not reentrant.
4241  A special note here, int (16 bit) and long (32 bit) integer division, multiplic
4242 ation & modulus operations are implemented using external support routines
4243  developed in ANSI-C, if an interrupt service routine needs to do any of
4244  these operations then the support routines (as mentioned in a following
4245  section) will have to be recompiled using the
4246 \emph on 
4247  ---stack-auto
4248 \emph default 
4249  option and the source file will need to be compiled using the 
4250 \emph on 
4251 ---int-long-ren
4252 \emph default 
4253 t compiler option.
4254 \layout Standard
4255
4256 If you have multiple source files in your project, interrupt service routines
4257  can be present in any of them, but a prototype of the isr MUST be present
4258  or included in the file that contains the function 
4259 \emph on 
4260 main
4261 \emph default 
4262 .
4263 \layout Standard
4264
4265 Interrupt Numbers and the corresponding address & descriptions for the Standard
4266  8051 are listed below.
4267  SDCC will automatically adjust the interrupt vector table to the maximum
4268  interrupt number specified.
4269 \newline 
4270
4271 \layout Standard
4272
4273
4274 \begin_inset  Tabular
4275 <lyxtabular version="3" rows="6" columns="3">
4276 <features>
4277 <column alignment="center" valignment="top" leftline="true" width="0in">
4278 <column alignment="center" valignment="top" leftline="true" width="0in">
4279 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
4280 <row topline="true" bottomline="true">
4281 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4282 \begin_inset Text
4283
4284 \layout Standard
4285
4286 Interrupt #
4287 \end_inset 
4288 </cell>
4289 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4290 \begin_inset Text
4291
4292 \layout Standard
4293
4294 Description
4295 \end_inset 
4296 </cell>
4297 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4298 \begin_inset Text
4299
4300 \layout Standard
4301
4302 Vector Address
4303 \end_inset 
4304 </cell>
4305 </row>
4306 <row topline="true">
4307 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4308 \begin_inset Text
4309
4310 \layout Standard
4311
4312 0
4313 \end_inset 
4314 </cell>
4315 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4316 \begin_inset Text
4317
4318 \layout Standard
4319
4320 External 0
4321 \end_inset 
4322 </cell>
4323 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4324 \begin_inset Text
4325
4326 \layout Standard
4327
4328 0x0003
4329 \end_inset 
4330 </cell>
4331 </row>
4332 <row topline="true">
4333 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4334 \begin_inset Text
4335
4336 \layout Standard
4337
4338 1
4339 \end_inset 
4340 </cell>
4341 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4342 \begin_inset Text
4343
4344 \layout Standard
4345
4346 Timer 0
4347 \end_inset 
4348 </cell>
4349 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4350 \begin_inset Text
4351
4352 \layout Standard
4353
4354 0x000B
4355 \end_inset 
4356 </cell>
4357 </row>
4358 <row topline="true">
4359 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4360 \begin_inset Text
4361
4362 \layout Standard
4363
4364 2
4365 \end_inset 
4366 </cell>
4367 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4368 \begin_inset Text
4369
4370 \layout Standard
4371
4372 External 1
4373 \end_inset 
4374 </cell>
4375 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4376 \begin_inset Text
4377
4378 \layout Standard
4379
4380 0x0013
4381 \end_inset 
4382 </cell>
4383 </row>
4384 <row topline="true">
4385 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4386 \begin_inset Text
4387
4388 \layout Standard
4389
4390 3
4391 \end_inset 
4392 </cell>
4393 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4394 \begin_inset Text
4395
4396 \layout Standard
4397
4398 Timer 1
4399 \end_inset 
4400 </cell>
4401 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4402 \begin_inset Text
4403
4404 \layout Standard
4405
4406 0x001B
4407 \end_inset 
4408 </cell>
4409 </row>
4410 <row topline="true" bottomline="true">
4411 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4412 \begin_inset Text
4413
4414 \layout Standard
4415
4416 4
4417 \end_inset 
4418 </cell>
4419 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4420 \begin_inset Text
4421
4422 \layout Standard
4423
4424 Serial
4425 \end_inset 
4426 </cell>
4427 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4428 \begin_inset Text
4429
4430 \layout Standard
4431
4432 0x0023
4433 \end_inset 
4434 </cell>
4435 </row>
4436 </lyxtabular>
4437
4438 \end_inset 
4439
4440
4441 \newline 
4442
4443 \newline 
4444 If the interrupt service routine is defined without 
4445 \emph on 
4446 using
4447 \emph default 
4448  a register bank or with register bank 0 (using 0), the compiler will save
4449  the registers used by itself on the stack upon entry and restore them at
4450  exit, however if such an interrupt service routine calls another function
4451  then the entire register bank will be saved on the stack.
4452  This scheme may be advantageous for small interrupt service routines which
4453  have low register usage.
4454 \layout Standard
4455
4456 If the interrupt service routine is defined to be using a specific register
4457  bank then only 
4458 \emph on 
4459 a, b & dptr
4460 \emph default 
4461  are save and restored, if such an interrupt service routine calls another
4462  function (using another register bank) then the entire register bank of
4463  the called function will be saved on the stack.
4464  This scheme is recommended for larger interrupt service routines.
4465 \layout Standard
4466
4467 Calling other functions from an interrupt service routine is not recommended,
4468  avoid it if possible.
4469 \newline 
4470
4471 \newline 
4472 Also see the _naked modifier.
4473 \layout Subsection
4474
4475 Critical Functions
4476 \layout Standard
4477
4478
4479 \shape italic 
4480 <TODO: this isn't implemented at all!>
4481 \shape default 
4482
4483 \newline 
4484
4485 \newline 
4486 A special keyword may be associated with a function declaring it as 
4487 \emph on 
4488 critical
4489 \emph default 
4490 .
4491  SDCC will generate code to disable all interrupts upon entry to a critical
4492  function and enable them back before returning.
4493  Note that nesting critical functions may cause unpredictable results.
4494 \newline 
4495
4496 \size small 
4497
4498 \newline 
4499
4500 \family typewriter 
4501 \size default 
4502 int foo () critical 
4503 \newline 
4504
4505 \newline 
4506 ...
4507  
4508 \newline 
4509 ...
4510  
4511 \newline 
4512 }
4513 \newline 
4514
4515 \family default 
4516
4517 \newline 
4518 The critical attribute maybe used with other attributes like 
4519 \emph on 
4520 reentrant.
4521 \layout Subsection
4522
4523 Naked Functions
4524 \layout Standard
4525
4526 A special keyword may be associated with a function declaring it as 
4527 \emph on 
4528 _naked.
4529  
4530 \emph default 
4531 The 
4532 \emph on 
4533 _naked
4534 \emph default 
4535  function modifier attribute prevents the compiler from generating prologue
4536  and epilogue code for that function.
4537  This means that the user is entirely responsible for such things as saving
4538  any registers that may need to be preserved, selecting the proper register
4539  bank, generating the 
4540 \emph on 
4541 return
4542 \emph default 
4543  instruction at the end, etc.
4544  Practically, this means that the contents of the function must be written
4545  in inline assembler.
4546  This is particularly useful for interrupt functions, which can have a large
4547  (and often unnecessary) prologue/epilogue.
4548  For example, compare the code generated by these two functions:
4549 \newline 
4550
4551 \newline 
4552
4553 \family typewriter 
4554 data unsigned char counter;
4555 \newline 
4556 void simpleInterrupt(void) interrupt 1
4557 \newline 
4558 {
4559 \newline 
4560 \SpecialChar ~
4561 \SpecialChar ~
4562 \SpecialChar ~
4563 \SpecialChar ~
4564 counter++;
4565 \newline 
4566 }
4567 \newline 
4568
4569 \newline 
4570 void nakedInterrupt(void) interrupt 2 _naked
4571 \newline 
4572 {
4573 \newline 
4574 \SpecialChar ~
4575 \SpecialChar ~
4576 \SpecialChar ~
4577 \SpecialChar ~
4578 _asm
4579 \newline 
4580 \SpecialChar ~
4581 \SpecialChar ~
4582 \SpecialChar ~
4583 \SpecialChar ~
4584 \SpecialChar ~
4585 \SpecialChar ~
4586 inc\SpecialChar ~
4587 \SpecialChar ~
4588 \SpecialChar ~
4589 \SpecialChar ~
4590 \SpecialChar ~
4591 _counter
4592 \newline 
4593 \SpecialChar ~
4594 \SpecialChar ~
4595 \SpecialChar ~
4596 \SpecialChar ~
4597 \SpecialChar ~
4598 \SpecialChar ~
4599 reti\SpecialChar ~
4600 \SpecialChar ~
4601 \SpecialChar ~
4602 \SpecialChar ~
4603 ; MUST explicitly include ret in _naked function.
4604 \newline 
4605 \SpecialChar ~
4606 \SpecialChar ~
4607 \SpecialChar ~
4608 \SpecialChar ~
4609 _endasm;
4610 \newline 
4611 }
4612 \family default 
4613
4614 \newline 
4615
4616 \newline 
4617 For an 8051 target, the generated simpleInterrupt looks like:
4618 \newline 
4619
4620 \newline 
4621
4622 \family typewriter 
4623 _simpleIterrupt:
4624 \newline 
4625 \SpecialChar ~
4626 \SpecialChar ~
4627 \SpecialChar ~
4628 \SpecialChar ~
4629 push\SpecialChar ~
4630 \SpecialChar ~
4631 \SpecialChar ~
4632 \SpecialChar ~
4633 acc
4634 \newline 
4635 \SpecialChar ~
4636 \SpecialChar ~
4637 \SpecialChar ~
4638 \SpecialChar ~
4639 push\SpecialChar ~
4640 \SpecialChar ~
4641 \SpecialChar ~
4642 \SpecialChar ~
4643 b
4644 \newline 
4645 \SpecialChar ~
4646 \SpecialChar ~
4647 \SpecialChar ~
4648 \SpecialChar ~
4649 push\SpecialChar ~
4650 \SpecialChar ~
4651 \SpecialChar ~
4652 \SpecialChar ~
4653 dpl
4654 \newline 
4655 \SpecialChar ~
4656 \SpecialChar ~
4657 \SpecialChar ~
4658 \SpecialChar ~
4659 push\SpecialChar ~
4660 \SpecialChar ~
4661 \SpecialChar ~
4662 \SpecialChar ~
4663 dph
4664 \newline 
4665 \SpecialChar ~
4666 \SpecialChar ~
4667 \SpecialChar ~
4668 \SpecialChar ~
4669 push\SpecialChar ~
4670 \SpecialChar ~
4671 \SpecialChar ~
4672 \SpecialChar ~
4673 psw
4674 \newline 
4675 \SpecialChar ~
4676 \SpecialChar ~
4677 \SpecialChar ~
4678 \SpecialChar ~
4679 mov\SpecialChar ~
4680 \SpecialChar ~
4681 \SpecialChar ~
4682 \SpecialChar ~
4683 \SpecialChar ~
4684 psw,#0x00
4685 \newline 
4686 \SpecialChar ~
4687 \SpecialChar ~
4688 \SpecialChar ~
4689 \SpecialChar ~
4690 inc\SpecialChar ~
4691 \SpecialChar ~
4692 \SpecialChar ~
4693 \SpecialChar ~
4694 \SpecialChar ~
4695 _counter
4696 \newline 
4697 \SpecialChar ~
4698 \SpecialChar ~
4699 \SpecialChar ~
4700 \SpecialChar ~
4701 pop\SpecialChar ~
4702 \SpecialChar ~
4703 \SpecialChar ~
4704 \SpecialChar ~
4705 \SpecialChar ~
4706 psw
4707 \newline 
4708 \SpecialChar ~
4709 \SpecialChar ~
4710 \SpecialChar ~
4711 \SpecialChar ~
4712 pop\SpecialChar ~
4713 \SpecialChar ~
4714 \SpecialChar ~
4715 \SpecialChar ~
4716 \SpecialChar ~
4717 dph
4718 \newline 
4719 \SpecialChar ~
4720 \SpecialChar ~
4721 \SpecialChar ~
4722 \SpecialChar ~
4723 pop\SpecialChar ~
4724 \SpecialChar ~
4725 \SpecialChar ~
4726 \SpecialChar ~
4727 \SpecialChar ~
4728 dpl
4729 \newline 
4730 \SpecialChar ~
4731 \SpecialChar ~
4732 \SpecialChar ~
4733 \SpecialChar ~
4734 pop\SpecialChar ~
4735 \SpecialChar ~
4736 \SpecialChar ~
4737 \SpecialChar ~
4738 \SpecialChar ~
4739 b
4740 \newline 
4741 \SpecialChar ~
4742 \SpecialChar ~
4743 \SpecialChar ~
4744 \SpecialChar ~
4745 pop\SpecialChar ~
4746 \SpecialChar ~
4747 \SpecialChar ~
4748 \SpecialChar ~
4749 \SpecialChar ~
4750 acc
4751 \newline 
4752 \SpecialChar ~
4753 \SpecialChar ~
4754 \SpecialChar ~
4755 \SpecialChar ~
4756 reti
4757 \family default 
4758
4759 \newline 
4760
4761 \newline 
4762 whereas nakedInterrupt looks like:
4763 \newline 
4764
4765 \newline 
4766
4767 \family typewriter 
4768 _nakedInterrupt:
4769 \newline 
4770 \SpecialChar ~
4771 \SpecialChar ~
4772 \SpecialChar ~
4773 \SpecialChar ~
4774 inc\SpecialChar ~
4775 \SpecialChar ~
4776 \SpecialChar ~
4777 \SpecialChar ~
4778 _counter
4779 \newline 
4780 \SpecialChar ~
4781 \SpecialChar ~
4782 \SpecialChar ~
4783 \SpecialChar ~
4784 reti\SpecialChar ~
4785 \SpecialChar ~
4786 \SpecialChar ~
4787 ; MUST explicitly include ret(i) in _naked function.
4788 \family default 
4789
4790 \newline 
4791
4792 \newline 
4793 While there is nothing preventing you from writing C code inside a _naked
4794  function, there are many ways to shoot yourself in the foot doing this,
4795  and it is recommended that you stick to inline assembler.
4796 \layout Subsection
4797
4798 Functions using private banks
4799 \layout Standard
4800
4801 The 
4802 \emph on 
4803 using
4804 \emph default 
4805  attribute (which tells the compiler to use a register bank other than the
4806  default bank zero) should only be applied to 
4807 \emph on 
4808 interrupt
4809 \emph default 
4810  functions (see note 1 below).
4811  This will in most circumstances make the generated ISR code more efficient
4812  since it will not have to save registers on the stack.
4813 \layout Standard
4814
4815 The 
4816 \emph on 
4817 using
4818 \emph default 
4819  attribute will have no effect on the generated code for a 
4820 \emph on 
4821 non-interrupt
4822 \emph default 
4823  function (but may occasionally be useful anyway
4824 \begin_inset Foot
4825 collapsed true
4826
4827 \layout Standard
4828
4829 possible exception: if a function is called ONLY from 'interrupt' functions
4830  using a particular bank, it can be declared with the same 'using' attribute
4831  as the calling 'interrupt' functions.
4832  For instance, if you have several ISRs using bank one, and all of them
4833  call memcpy(), it might make sense to create a specialized version of memcpy()
4834  'using 1', since this would prevent the ISR from having to save bank zero
4835  to the stack on entry and switch to bank zero before calling the function
4836 \end_inset 
4837
4838 ).
4839 \newline 
4840
4841 \emph on 
4842 (pending: I don't think this has been done yet)
4843 \layout Standard
4844
4845 An 
4846 \emph on 
4847 interrupt
4848 \emph default 
4849  function using a non-zero bank will assume that it can trash that register
4850  bank, and will not save it.
4851  Since high-priority interrupts can interrupt low-priority ones on the 8051
4852  and friends, this means that if a high-priority ISR 
4853 \emph on 
4854 using
4855 \emph default 
4856  a particular bank occurs while processing a low-priority ISR 
4857 \emph on 
4858 using
4859 \emph default 
4860  the same bank, terrible and bad things can happen.
4861  To prevent this, no single register bank should be 
4862 \emph on 
4863 used
4864 \emph default 
4865  by both a high priority and a low priority ISR.
4866  This is probably most easily done by having all high priority ISRs use
4867  one bank and all low priority ISRs use another.
4868  If you have an ISR which can change priority at runtime, you're on your
4869  own: I suggest using the default bank zero and taking the small performance
4870  hit.
4871 \layout Standard
4872
4873 It is most efficient if your ISR calls no other functions.
4874  If your ISR must call other functions, it is most efficient if those functions
4875  use the same bank as the ISR (see note 1 below); the next best is if the
4876  called functions use bank zero.
4877  It is very inefficient to call a function using a different, non-zero bank
4878  from an ISR.
4879  
4880 \layout Subsection
4881
4882 Absolute Addressing
4883 \layout Standard
4884
4885 Data items can be assigned an absolute address with the 
4886 \emph on 
4887 at <address>
4888 \emph default 
4889  keyword, in addition to a storage class, e.g.:
4890 \newline 
4891
4892 \newline 
4893
4894 \family typewriter 
4895 xdata at 0x8000 unsigned char PORTA_8255 ;
4896 \newline 
4897
4898 \family default 
4899
4900 \newline 
4901 In the above example the PORTA_8255 will be allocated to the location 0x8000
4902  of the external ram.
4903  Note that this feature is provided to give the programmer access to 
4904 \emph on 
4905 memory mapped
4906 \emph default 
4907  devices attached to the controller.
4908  The compiler does not actually reserve any space for variables declared
4909  in this way (they are implemented with an equate in the assembler).
4910  Thus it is left to the programmer to make sure there are no overlaps with
4911  other variables that are declared without the absolute address.
4912  The assembler listing file (.lst) and the linker output files (.rst) and
4913  (.map) are a good places to look for such overlaps.
4914 \newline 
4915
4916 \newline 
4917 Absolute address can be specified for variables in all storage classes,
4918  e.g.:
4919 \newline 
4920
4921 \newline 
4922
4923 \family typewriter 
4924 bit at 0x02 bvar;
4925 \newline 
4926
4927 \newline 
4928
4929 \family default 
4930 The above example will allocate the variable at offset 0x02 in the bit-addressab
4931 le space.
4932  There is no real advantage to assigning absolute addresses to variables
4933  in this manner, unless you want strict control over all the variables allocated.
4934 \layout Subsection
4935
4936 Startup Code
4937 \layout Standard
4938
4939 The compiler inserts a call to the C routine 
4940 \emph on 
4941 _sdcc__external__startup()
4942 \series bold 
4943 \emph default 
4944  
4945 \series default 
4946 at the start of the CODE area.
4947  This routine is in the runtime library.
4948  By default this routine returns 0, if this routine returns a non-zero value,
4949  the static & global variable initialization will be skipped and the function
4950  main will be invoked Other wise static & global variables will be initialized
4951  before the function main is invoked.
4952  You could add a 
4953 \emph on 
4954 _sdcc__external__startup()
4955 \emph default 
4956  routine to your program to override the default if you need to setup hardware
4957  or perform some other critical operation prior to static & global variable
4958  initialization.
4959 \layout Subsection
4960
4961 Inline Assembler Code
4962 \layout Standard
4963
4964 SDCC allows the use of in-line assembler with a few restriction as regards
4965  labels.
4966  All labels defined within inline assembler code 
4967 \emph on 
4968 has to be
4969 \emph default 
4970  of the form 
4971 \emph on 
4972 nnnnn$
4973 \emph default 
4974  where nnnn is a number less than 100 (which implies a limit of utmost 100
4975  inline assembler labels 
4976 \emph on 
4977 per function
4978 \emph default 
4979 \noun on 
4980 )
4981 \noun default 
4982 .
4983  It is strongly recommended that each assembly instruction (including labels)
4984  be placed in a separate line (as the example shows).
4985  When the 
4986 \emph on 
4987 ---peep-asm
4988 \emph default 
4989  command line option is used, the inline assembler code will be passed through
4990  the peephole optimizer.
4991  This might cause some unexpected changes in the inline assembler code.
4992  Please go throught the peephole optimizer rules defined in file 
4993 \emph on 
4994 SDCCpeeph.def
4995 \emph default 
4996  carefully before using this option.
4997 \newline 
4998
4999 \newline 
5000
5001 \family typewriter 
5002 _asm 
5003 \newline 
5004 \SpecialChar ~
5005 \SpecialChar ~
5006 \SpecialChar ~
5007 \SpecialChar ~
5008 mov\SpecialChar ~
5009 \SpecialChar ~
5010 \SpecialChar ~
5011 \SpecialChar ~
5012 \SpecialChar ~
5013 b,#10 
5014 \newline 
5015 00001$: 
5016 \newline 
5017 \SpecialChar ~
5018 \SpecialChar ~
5019 \SpecialChar ~
5020 \SpecialChar ~
5021 djnz\SpecialChar ~
5022 \SpecialChar ~
5023 \SpecialChar ~
5024 \SpecialChar ~
5025 b,00001$ 
5026 \newline 
5027 _endasm ;
5028 \family default 
5029 \size small 
5030
5031 \newline 
5032
5033 \newline 
5034
5035 \size default 
5036 The inline assembler code can contain any valid code understood by the assembler
5037 , this includes any assembler directives and comment lines.
5038  The compiler does not do any validation of the code within the 
5039 \family typewriter 
5040 _asm ...
5041  _endasm;
5042 \family default 
5043  keyword pair.
5044  
5045 \newline 
5046
5047 \newline 
5048 Inline assembler code cannot reference any C-Labels, however it can reference
5049  labels defined by the inline assembler, e.g.:
5050 \newline 
5051
5052 \newline 
5053
5054 \family typewriter 
5055 foo() { 
5056 \newline 
5057 \SpecialChar ~
5058 \SpecialChar ~
5059 \SpecialChar ~
5060 \SpecialChar ~
5061 /* some c code */ 
5062 \newline 
5063 \SpecialChar ~
5064 \SpecialChar ~
5065 \SpecialChar ~
5066 \SpecialChar ~
5067 _asm 
5068 \newline 
5069 \SpecialChar ~
5070 \SpecialChar ~
5071 \SpecialChar ~
5072 \SpecialChar ~
5073 \SpecialChar ~
5074 \SpecialChar ~
5075 ; some assembler code 
5076 \newline 
5077 \SpecialChar ~
5078 \SpecialChar ~
5079 \SpecialChar ~
5080 \SpecialChar ~
5081 \SpecialChar ~
5082 \SpecialChar ~
5083 ljmp $0003 
5084 \newline 
5085 \SpecialChar ~
5086 \SpecialChar ~
5087 \SpecialChar ~
5088 \SpecialChar ~
5089 _endasm; 
5090 \newline 
5091 \SpecialChar ~
5092 \SpecialChar ~
5093 \SpecialChar ~
5094 \SpecialChar ~
5095 /* some more c code */ 
5096 \newline 
5097 clabel:\SpecialChar ~
5098 \SpecialChar ~
5099 /* inline assembler cannot reference this label */ 
5100 \newline 
5101 \SpecialChar ~
5102 \SpecialChar ~
5103 \SpecialChar ~
5104 \SpecialChar ~
5105 _asm
5106 \newline 
5107 \SpecialChar ~
5108 \SpecialChar ~
5109 \SpecialChar ~
5110 \SpecialChar ~
5111 $0003: ;label (can be reference by inline assembler only) 
5112 \newline 
5113 \SpecialChar ~
5114 \SpecialChar ~
5115 \SpecialChar ~
5116 \SpecialChar ~
5117 _endasm ; 
5118 \newline 
5119 \SpecialChar ~
5120 \SpecialChar ~
5121 \SpecialChar ~
5122 \SpecialChar ~
5123 /* some more c code */
5124 \newline 
5125 }
5126 \newline 
5127
5128 \newline 
5129
5130 \family default 
5131 In other words inline assembly code can access labels defined in inline
5132  assembly within the scope of the funtion.
5133  
5134 \layout Standard
5135
5136 The same goes the other way, ie.
5137  labels defines in inline assembly CANNOT be accessed by C statements.
5138 \layout Subsection
5139
5140 int (16 bit) and long (32 bit) Support
5141 \layout Standard
5142
5143 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
5144  multiplication and modulus operations are implemented by support routines.
5145  These support routines are all developed in ANSI-C to facilitate porting
5146  to other MCUs, although some model specific assembler optimations are used.
5147  The following files contain the described routine, all of them can be found
5148  in <installdir>/share/sdcc/lib.
5149 \newline 
5150
5151 \newline 
5152
5153 \emph on 
5154 <pending: tabularise this>
5155 \emph default 
5156
5157 \newline 
5158
5159 \newline 
5160 _mulsint.c - signed 16 bit multiplication (calls _muluint)
5161 \newline 
5162 _muluint.c - unsigned 16 bit multiplication
5163 \newline 
5164 _divsint.c - signed 16 bit division (calls _divuint)
5165 \newline 
5166 _divuint.c - unsigned 16 bit division
5167 \newline 
5168 _modsint.c - signed 16 bit modulus (call _moduint)
5169 \newline 
5170 _moduint.c - unsigned 16 bit modulus
5171 \newline 
5172 _mulslong.c - signed 32 bit multiplication (calls _mululong)
5173 \newline 
5174 _mululong.c - unsigned32 bit multiplication
5175 \newline 
5176 _divslong.c - signed 32 division (calls _divulong)
5177 \newline 
5178 _divulong.c - unsigned 32 division
5179 \newline 
5180 _modslong.c - signed 32 bit modulus (calls _modulong)
5181 \newline 
5182 _modulong.c - unsigned 32 bit modulus 
5183 \size footnotesize 
5184
5185 \newline 
5186
5187 \newline 
5188
5189 \size default 
5190 Since they are compiled as 
5191 \emph on 
5192 non-reentrant
5193 \emph default 
5194 , interrupt service routines should not do any of the above operations.
5195  If this is unavoidable then the above routines will need to be compiled
5196  with the 
5197 \emph on 
5198 ---stack-auto
5199 \emph default 
5200  option, after which the source program will have to be compiled with 
5201 \emph on 
5202 ---int-long-rent
5203 \emph default 
5204  option.
5205 \layout Subsection
5206
5207 Floating Point Support
5208 \layout Standard
5209
5210 SDCC supports IEEE (single precision 4bytes) floating point numbers.The floating
5211  point support routines are derived from gcc's floatlib.c and consists of
5212  the following routines:
5213 \newline 
5214
5215 \newline 
5216
5217 \emph on 
5218 <pending: tabularise this>
5219 \emph default 
5220
5221 \newline 
5222
5223 \newline 
5224 _fsadd.c - add floating point numbers
5225 \newline 
5226 _fssub.c - subtract floating point numbers
5227 \newline 
5228 _fsdiv.c - divide floating point numbers
5229 \newline 
5230 _fsmul.c - multiply floating point numbers
5231 \newline 
5232 _fs2uchar.c - convert floating point to unsigned char
5233 \newline 
5234 _fs2char.c - convert floating point to signed char
5235 \newline 
5236 _fs2uint.c - convert floating point to unsigned int
5237 \newline 
5238 _fs2int.c - convert floating point to signed int
5239 \newline 
5240 _fs2ulong.c - convert floating point to unsigned long
5241 \newline 
5242 _fs2long.c - convert floating point to signed long
5243 \newline 
5244 _uchar2fs.c - convert unsigned char to floating point
5245 \newline 
5246 _char2fs.c - convert char to floating point number
5247 \newline 
5248 _uint2fs.c - convert unsigned int to floating point
5249 \newline 
5250 _int2fs.c - convert int to floating point numbers
5251 \newline 
5252 _ulong2fs.c - convert unsigned long to floating point number
5253 \newline 
5254 _long2fs.c - convert long to floating point number
5255 \size footnotesize 
5256
5257 \newline 
5258
5259 \newline 
5260
5261 \size default 
5262 Note if all these routines are used simultaneously the data space might
5263  overflow.
5264  For serious floating point usage it is strongly recommended that the large
5265  model be used.
5266 \layout Subsection
5267
5268 MCS51 Memory Models
5269 \layout Standard
5270
5271 SDCC allows two memory models for MCS51 code, small and large.
5272  Modules compiled with different memory models should 
5273 \emph on 
5274 never
5275 \emph default 
5276  be combined together or the results would be unpredictable.
5277  The library routines supplied with the compiler are compiled as both small
5278  and large.
5279  The compiled library modules are contained in seperate directories as small
5280  and large so that you can link to either set.
5281  
5282 \layout Standard
5283
5284 When the large model is used all variables declared without a storage class
5285  will be allocated into the external ram, this includes all parameters and
5286  local variables (for non-reentrant functions).
5287  When the small model is used variables without storage class are allocated
5288  in the internal ram.
5289 \layout Standard
5290
5291 Judicious usage of the processor specific storage classes and the 'reentrant'
5292  function type will yield much more efficient code, than using the large
5293  model.
5294  Several optimizations are disabled when the program is compiled using the
5295  large model, it is therefore strongly recommdended that the small model
5296  be used unless absolutely required.
5297 \layout Subsection
5298
5299 DS390 Memory Models
5300 \layout Standard
5301
5302 The only model supported is Flat 24.
5303  This generates code for the 24 bit contiguous addressing mode of the Dallas
5304  DS80C390 part.
5305  In this mode, up to four meg of external RAM or code space can be directly
5306  addressed.
5307  See the data sheets at www.dalsemi.com for further information on this part.
5308 \newline 
5309
5310 \newline 
5311 In older versions of the compiler, this option was used with the MCS51 code
5312  generator (
5313 \emph on 
5314 -mmcs51
5315 \emph default 
5316 ).
5317  Now, however, the '390 has it's own code generator, selected by the 
5318 \emph on 
5319 -mds390
5320 \emph default 
5321  switch.
5322  
5323 \newline 
5324
5325 \newline 
5326 Note that the compiler does not generate any code to place the processor
5327  into 24 bitmode (although 
5328 \emph on 
5329 tinibios
5330 \emph default 
5331  in the ds390 libraries will do that for you).
5332  If you don't use 
5333 \emph on 
5334 tinibios
5335 \emph default 
5336 , the boot loader or similar code must ensure that the processor is in 24
5337  bit contiguous addressing mode before calling the SDCC startup code.
5338 \newline 
5339
5340 \newline 
5341 Like the 
5342 \emph on 
5343 ---model-large
5344 \emph default 
5345  option, variables will by default be placed into the XDATA segment.
5346  
5347 \newline 
5348
5349 \newline 
5350 Segments may be placed anywhere in the 4 meg address space using the usual
5351  ---*-loc options.
5352  Note that if any segments are located above 64K, the -r flag must be passed
5353  to the linker to generate the proper segment relocations, and the Intel
5354  HEX output format must be used.
5355  The -r flag can be passed to the linker by using the option 
5356 \emph on 
5357 -Wl-r
5358 \emph default 
5359  on the sdcc command line.
5360  However, currently the linker can not handle code segments > 64k.
5361 \layout Subsection
5362
5363 Defines Created by the Compiler
5364 \layout Standard
5365
5366 The compiler creates the following #defines.
5367 \layout Itemize
5368
5369 SDCC - this Symbol is always defined.
5370 \layout Itemize
5371
5372 SDCC_mcs51 or SDCC_ds390 or SDCC_z80, etc - depending on the model used
5373  (e.g.: -mds390)
5374 \layout Itemize
5375
5376 __mcs51 or __ds390 or __z80, etc - depending on the model used (e.g.
5377  -mz80)
5378 \layout Itemize
5379
5380 SDCC_STACK_AUTO - this symbol is defined when 
5381 \emph on 
5382 ---stack-auto
5383 \emph default 
5384  option is used.
5385 \layout Itemize
5386
5387 SDCC_MODEL_SMALL - when 
5388 \emph on 
5389 ---model-small
5390 \emph default 
5391  is used.
5392 \layout Itemize
5393
5394 SDCC_MODEL_LARGE - when 
5395 \emph on 
5396 ---model-large
5397 \emph default 
5398  is used.
5399 \layout Itemize
5400
5401 SDCC_USE_XSTACK - when 
5402 \emph on 
5403 ---xstack
5404 \emph default 
5405  option is used.
5406 \layout Itemize
5407
5408 SDCC_STACK_TENBIT - when 
5409 \emph on 
5410 -mds390
5411 \emph default 
5412  is used
5413 \layout Itemize
5414
5415 SDCC_MODEL_FLAT24 - when 
5416 \emph on 
5417 -mds390
5418 \emph default 
5419  is used
5420 \layout Section
5421
5422 SDCC Technical Data
5423 \layout Subsection
5424
5425 Optimizations
5426 \layout Standard
5427
5428 SDCC performs a host of standard optimizations in addition to some MCU specific
5429  optimizations.
5430  
5431 \layout Subsubsection
5432
5433 Sub-expression Elimination
5434 \layout Standard
5435
5436 The compiler does local and global common subexpression elimination, e.g.:
5437  
5438 \newline 
5439
5440 \newline 
5441
5442 \family typewriter 
5443 i = x + y + 1; 
5444 \newline 
5445 j = x + y;
5446 \family default 
5447
5448 \newline 
5449
5450 \newline 
5451 will be translated to
5452 \newline 
5453
5454 \newline 
5455
5456 \family typewriter 
5457 iTemp = x + y 
5458 \newline 
5459 i = iTemp + 1 
5460 \newline 
5461 j = iTemp
5462 \newline 
5463
5464 \family default 
5465
5466 \newline 
5467 Some subexpressions are not as obvious as the above example, e.g.:
5468 \newline 
5469
5470 \newline 
5471
5472 \family typewriter 
5473 a->b[i].c = 10; 
5474 \newline 
5475 a->b[i].d = 11;
5476 \family default 
5477
5478 \newline 
5479
5480 \newline 
5481 In this case the address arithmetic a->b[i] will be computed only once;
5482  the equivalent code in C would be.
5483 \newline 
5484
5485 \newline 
5486
5487 \family typewriter 
5488 iTemp = a->b[i]; 
5489 \newline 
5490 iTemp.c = 10; 
5491 \newline 
5492 iTemp.d = 11;
5493 \family default 
5494
5495 \newline 
5496
5497 \newline 
5498 The compiler will try to keep these temporary variables in registers.
5499 \layout Subsubsection
5500
5501 Dead-Code Elimination
5502 \layout Standard
5503
5504
5505 \family typewriter 
5506 int global; 
5507 \newline 
5508 void f () { 
5509 \newline 
5510 \SpecialChar ~
5511 \SpecialChar ~
5512 int i; 
5513 \newline 
5514 \SpecialChar ~
5515 \SpecialChar ~
5516 i = 1; \SpecialChar ~
5517 /* dead store */ 
5518 \newline 
5519 \SpecialChar ~
5520 \SpecialChar ~
5521 global = 1;\SpecialChar ~
5522 /* dead store */ 
5523 \newline 
5524 \SpecialChar ~
5525 \SpecialChar ~
5526 global = 2; 
5527 \newline 
5528 \SpecialChar ~
5529 \SpecialChar ~
5530 return; 
5531 \newline 
5532 \SpecialChar ~
5533 \SpecialChar ~
5534 global = 3;\SpecialChar ~
5535 /* unreachable */ 
5536 \newline 
5537 }
5538 \family default 
5539
5540 \newline 
5541
5542 \newline 
5543 will be changed to
5544 \newline 
5545
5546 \newline 
5547
5548 \family typewriter 
5549 int global; void f () 
5550 \newline 
5551 {
5552 \newline 
5553 \SpecialChar ~
5554 \SpecialChar ~
5555 global = 2; 
5556 \newline 
5557 \SpecialChar ~
5558 \SpecialChar ~
5559 return; 
5560 \newline 
5561 }
5562 \layout Subsubsection
5563
5564 Copy-Propagation
5565 \layout Standard
5566
5567
5568 \family typewriter 
5569 int f() { 
5570 \newline 
5571 \SpecialChar ~
5572 \SpecialChar ~
5573 int i, j; 
5574 \newline 
5575 \SpecialChar ~
5576 \SpecialChar ~
5577 i = 10; 
5578 \newline 
5579 \SpecialChar ~
5580 \SpecialChar ~
5581 j = i; 
5582 \newline 
5583 \SpecialChar ~
5584 \SpecialChar ~
5585 return j; 
5586 \newline 
5587 }
5588 \family default 
5589
5590 \newline 
5591
5592 \newline 
5593 will be changed to 
5594 \newline 
5595
5596 \newline 
5597
5598 \family typewriter 
5599 int f() { 
5600 \newline 
5601 \SpecialChar ~
5602  \SpecialChar ~
5603  int i,j; 
5604 \newline 
5605 \SpecialChar ~
5606  \SpecialChar ~
5607  i = 10; 
5608 \newline 
5609 \SpecialChar ~
5610  \SpecialChar ~
5611  j = 10; 
5612 \newline 
5613 \SpecialChar ~
5614  \SpecialChar ~
5615  return 10; 
5616 \newline 
5617 }
5618 \newline 
5619
5620 \newline 
5621
5622 \family default 
5623 Note: the dead stores created by this copy propagation will be eliminated
5624  by dead-code elimination.
5625 \layout Subsubsection
5626
5627 Loop Optimizations
5628 \layout Standard
5629
5630 Two types of loop optimizations are done by SDCC loop invariant lifting
5631  and strength reduction of loop induction variables.
5632  In addition to the strength reduction the optimizer marks the induction
5633  variables and the register allocator tries to keep the induction variables
5634  in registers for the duration of the loop.
5635  Because of this preference of the register allocator, loop induction optimizati
5636 on causes an increase in register pressure, which may cause unwanted spilling
5637  of other temporary variables into the stack / data space.
5638  The compiler will generate a warning message when it is forced to allocate
5639  extra space either on the stack or data space.
5640  If this extra space allocation is undesirable then induction optimization
5641  can be eliminated either for the entire source file (with ---noinduction
5642  option) or for a given function only using #pragma\SpecialChar ~
5643 NOINDUCTION.
5644 \newline 
5645
5646 \newline 
5647 Loop Invariant:
5648 \newline 
5649
5650 \newline 
5651
5652 \family typewriter 
5653 for (i = 0 ; i < 100 ; i ++) 
5654 \newline 
5655  \SpecialChar ~
5656  \SpecialChar ~
5657 f += k + l;
5658 \family default 
5659
5660 \newline 
5661
5662 \newline 
5663 changed to
5664 \newline 
5665
5666 \newline 
5667
5668 \family typewriter 
5669 itemp = k + l; 
5670 \newline 
5671 for (i = 0; i < 100; i++) 
5672 \newline 
5673 \SpecialChar ~
5674 \SpecialChar ~
5675 f += itemp;
5676 \family default 
5677
5678 \newline 
5679
5680 \newline 
5681 As mentioned previously some loop invariants are not as apparent, all static
5682  address computations are also moved out of the loop.
5683 \newline 
5684
5685 \newline 
5686 Strength Reduction, this optimization substitutes an expression by a cheaper
5687  expression:
5688 \newline 
5689
5690 \newline 
5691
5692 \family typewriter 
5693 for (i=0;i < 100; i++)
5694 \newline 
5695 \SpecialChar ~
5696 \SpecialChar ~
5697 ar[i*5] = i*3;
5698 \family default 
5699
5700 \newline 
5701
5702 \newline 
5703 changed to
5704 \newline 
5705
5706 \newline 
5707
5708 \family typewriter 
5709 itemp1 = 0; 
5710 \newline 
5711 itemp2 = 0; 
5712 \newline 
5713 for (i=0;i< 100;i++) { 
5714 \newline 
5715  \SpecialChar ~
5716  \SpecialChar ~
5717 ar[itemp1] = itemp2; 
5718 \newline 
5719  \SpecialChar ~
5720  \SpecialChar ~
5721 itemp1 += 5; 
5722 \newline 
5723  \SpecialChar ~
5724  \SpecialChar ~
5725 itemp2 += 3; 
5726 \newline 
5727 }
5728 \family default 
5729
5730 \newline 
5731
5732 \newline 
5733 The more expensive multiplication is changed to a less expensive addition.
5734 \layout Subsubsection
5735
5736 Loop Reversing
5737 \layout Standard
5738
5739 This optimization is done to reduce the overhead of checking loop boundaries
5740  for every iteration.
5741  Some simple loops can be reversed and implemented using a 
5742 \begin_inset Quotes eld
5743 \end_inset 
5744
5745 decrement and jump if not zero
5746 \begin_inset Quotes erd
5747 \end_inset 
5748
5749  instruction.
5750  SDCC checks for the following criterion to determine if a loop is reversible
5751  (note: more sophisticated compilers use data-dependency analysis to make
5752  this determination, SDCC uses a more simple minded analysis).
5753 \layout Itemize
5754
5755 The 'for' loop is of the form 
5756 \newline 
5757
5758 \newline 
5759
5760 \family typewriter 
5761 for (<symbol> = <expression> ; <sym> [< | <=] <expression> ; [<sym>++ |
5762  <sym> += 1])
5763 \newline 
5764 \SpecialChar ~
5765 \SpecialChar ~
5766 \SpecialChar ~
5767 \SpecialChar ~
5768 <for body>
5769 \layout Itemize
5770
5771 The <for body> does not contain 
5772 \begin_inset Quotes eld
5773 \end_inset 
5774
5775 continue
5776 \begin_inset Quotes erd
5777 \end_inset 
5778
5779  or 'break
5780 \begin_inset Quotes erd
5781 \end_inset 
5782
5783 .
5784 \layout Itemize
5785
5786 All goto's are contained within the loop.
5787 \layout Itemize
5788
5789 No function calls within the loop.
5790 \layout Itemize
5791
5792 The loop control variable <sym> is not assigned any value within the loop
5793 \layout Itemize
5794
5795 The loop control variable does NOT participate in any arithmetic operation
5796  within the loop.
5797 \layout Itemize
5798
5799 There are NO switch statements in the loop.
5800 \layout Subsubsection
5801
5802 Algebraic Simplifications
5803 \layout Standard
5804
5805 SDCC does numerous algebraic simplifications, the following is a small sub-set
5806  of these optimizations.
5807 \newline 
5808
5809 \newline 
5810
5811 \family typewriter 
5812 i = j + 0 ; /* changed to */ i = j; 
5813 \newline 
5814 i /= 2; /* changed to */ i >>= 1; 
5815 \newline 
5816 i = j - j ; /* changed to */ i = 0; 
5817 \newline 
5818 i = j / 1 ; /* changed to */ i = j;
5819 \family default 
5820
5821 \newline 
5822
5823 \newline 
5824 Note the subexpressions given above are generally introduced by macro expansions
5825  or as a result of copy/constant propagation.
5826 \layout Subsubsection
5827
5828 'switch' Statements
5829 \layout Standard
5830
5831 SDCC changes switch statements to jump tables when the following conditions
5832  are true.
5833  
5834 \layout Itemize
5835
5836 The case labels are in numerical sequence, the labels need not be in order,
5837  and the starting number need not be one or zero.
5838 \newline 
5839
5840 \newline 
5841
5842 \family typewriter 
5843 switch(i) {\SpecialChar ~
5844  \SpecialChar ~
5845  \SpecialChar ~
5846  \SpecialChar ~
5847  \SpecialChar ~
5848  \SpecialChar ~
5849  \SpecialChar ~
5850  \SpecialChar ~
5851  \SpecialChar ~
5852  \SpecialChar ~
5853  \SpecialChar ~
5854  \SpecialChar ~
5855  \SpecialChar ~
5856 switch (i) { 
5857 \newline 
5858 case 4:...
5859  \SpecialChar ~
5860  \SpecialChar ~
5861  \SpecialChar ~
5862  \SpecialChar ~
5863  \SpecialChar ~
5864  \SpecialChar ~
5865  \SpecialChar ~
5866  \SpecialChar ~
5867  \SpecialChar ~
5868  \SpecialChar ~
5869  \SpecialChar ~
5870  \SpecialChar ~
5871  \SpecialChar ~
5872 case 1: ...
5873  
5874 \newline 
5875 case 5:...
5876  \SpecialChar ~
5877  \SpecialChar ~
5878  \SpecialChar ~
5879  \SpecialChar ~
5880  \SpecialChar ~
5881  \SpecialChar ~
5882  \SpecialChar ~
5883  \SpecialChar ~
5884  \SpecialChar ~
5885  \SpecialChar ~
5886  \SpecialChar ~
5887  \SpecialChar ~
5888  \SpecialChar ~
5889 case 2: ...
5890  
5891 \newline 
5892 case 3:...
5893  \SpecialChar ~
5894  \SpecialChar ~
5895  \SpecialChar ~
5896  \SpecialChar ~
5897  \SpecialChar ~
5898  \SpecialChar ~
5899  \SpecialChar ~
5900  \SpecialChar ~
5901  \SpecialChar ~
5902  \SpecialChar ~
5903  \SpecialChar ~
5904  \SpecialChar ~
5905  \SpecialChar ~
5906 case 3: ...
5907  
5908 \newline 
5909 case 6:...
5910  \SpecialChar ~
5911  \SpecialChar ~
5912  \SpecialChar ~
5913  \SpecialChar ~
5914  \SpecialChar ~
5915  \SpecialChar ~
5916  \SpecialChar ~
5917  \SpecialChar ~
5918  \SpecialChar ~
5919  \SpecialChar ~
5920  \SpecialChar ~
5921  \SpecialChar ~
5922  \SpecialChar ~
5923 case 4: ...
5924  
5925 \newline 
5926 }\SpecialChar ~
5927  \SpecialChar ~
5928  \SpecialChar ~
5929  \SpecialChar ~
5930  \SpecialChar ~
5931  \SpecialChar ~
5932  \SpecialChar ~
5933  \SpecialChar ~
5934  \SpecialChar ~
5935  \SpecialChar ~
5936  \SpecialChar ~
5937  \SpecialChar ~
5938  \SpecialChar ~
5939  \SpecialChar ~
5940  \SpecialChar ~
5941  \SpecialChar ~
5942  \SpecialChar ~
5943  \SpecialChar ~
5944 }
5945 \newline 
5946
5947 \newline 
5948
5949 \family default 
5950 Both the above switch statements will be implemented using a jump-table.
5951 \layout Itemize
5952
5953 The number of case labels is at least three, since it takes two conditional
5954  statements to handle the boundary conditions.
5955 \layout Itemize
5956
5957 The number of case labels is less than 84, since each label takes 3 bytes
5958  and a jump-table can be utmost 256 bytes long.
5959  
5960 \layout Standard
5961
5962 Switch statements which have gaps in the numeric sequence or those that
5963  have more that 84 case labels can be split into more than one switch statement
5964  for efficient code generation, e.g.:
5965 \newline 
5966
5967 \newline 
5968
5969 \family typewriter 
5970 switch (i) { 
5971 \newline 
5972 case 1: ...
5973  
5974 \newline 
5975 case 2: ...
5976  
5977 \newline 
5978 case 3: ...
5979  
5980 \newline 
5981 case 4: ...
5982  
5983 \newline 
5984 case 9: ...
5985  
5986 \newline 
5987 case 10: ...
5988  
5989 \newline 
5990 case 11: ...
5991  
5992 \newline 
5993 case 12: ...
5994  
5995 \newline 
5996 }
5997 \family default 
5998
5999 \newline 
6000
6001 \newline 
6002 If the above switch statement is broken down into two switch statements
6003 \newline 
6004
6005 \newline 
6006
6007 \family typewriter 
6008 switch (i) { 
6009 \newline 
6010 case 1: ...
6011  
6012 \newline 
6013 case 2: ...
6014  
6015 \newline 
6016 case 3: ...
6017  
6018 \newline 
6019 case 4: ...
6020  
6021 \newline 
6022 }
6023 \newline 
6024
6025 \newline 
6026
6027 \family default 
6028 and
6029 \family typewriter 
6030
6031 \newline 
6032
6033 \newline 
6034 switch (i) { 
6035 \newline 
6036 case 9: \SpecialChar ~
6037 ...
6038  
6039 \newline 
6040 case 10: ...
6041  
6042 \newline 
6043 case 11: ...
6044  
6045 \newline 
6046 case 12:\SpecialChar ~
6047 ...
6048  
6049 \newline 
6050 }
6051 \newline 
6052
6053 \newline 
6054
6055 \family default 
6056 then both the switch statements will be implemented using jump-tables whereas
6057  the unmodified switch statement will not be.
6058 \layout Subsubsection
6059
6060 Bit-shifting Operations.
6061 \layout Standard
6062
6063 Bit shifting is one of the most frequently used operation in embedded programmin
6064 g.
6065  SDCC tries to implement bit-shift operations in the most efficient way
6066  possible, e.g.:
6067 \newline 
6068
6069 \family typewriter 
6070
6071 \newline 
6072 unsigned char i;
6073 \newline 
6074 ...
6075  
6076 \newline 
6077 i>>= 4; 
6078 \newline 
6079 ...
6080 \newline 
6081
6082 \family default 
6083
6084 \newline 
6085 generates the following code:
6086 \newline 
6087
6088 \family typewriter 
6089
6090 \newline 
6091 mov a,_i 
6092 \newline 
6093 swap a 
6094 \newline 
6095 anl a,#0x0f 
6096 \newline 
6097 mov _i,a
6098 \family default 
6099
6100 \newline 
6101
6102 \newline 
6103 In general SDCC will never setup a loop if the shift count is known.
6104  Another example:
6105 \newline 
6106
6107 \newline 
6108
6109 \family typewriter 
6110 unsigned int i; 
6111 \newline 
6112 ...
6113  
6114 \newline 
6115 i >>= 9; 
6116 \newline 
6117 ...
6118 \family default 
6119
6120 \newline 
6121
6122 \newline 
6123 will generate:
6124 \newline 
6125
6126 \newline 
6127
6128 \family typewriter 
6129 mov a,(_i + 1) 
6130 \newline 
6131 mov (_i + 1),#0x00 
6132 \newline 
6133 clr c 
6134 \newline 
6135 rrc a 
6136 \newline 
6137 mov _i,a
6138 \family default 
6139
6140 \newline 
6141
6142 \newline 
6143 Note that SDCC stores numbers in little-endian format (i.e.
6144  lowest order first).
6145 \layout Subsubsection
6146
6147 Bit-rotation
6148 \layout Standard
6149
6150 A special case of the bit-shift operation is bit rotation, SDCC recognizes
6151  the following expression to be a left bit-rotation:
6152 \newline 
6153
6154 \newline 
6155
6156 \family typewriter 
6157 unsigned char i; 
6158 \newline 
6159 ...
6160  
6161 \newline 
6162 i = ((i << 1) | (i >> 7)); 
6163 \family default 
6164
6165 \newline 
6166 ...
6167 \newline 
6168
6169 \newline 
6170 will generate the following code:
6171 \newline 
6172
6173 \newline 
6174
6175 \family typewriter 
6176 mov a,_i 
6177 \newline 
6178 rl a 
6179 \newline 
6180 mov _i,a
6181 \family default 
6182
6183 \newline 
6184
6185 \newline 
6186 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
6187 ns of this case will also be recognized as bit-rotation, i.e.: 
6188 \newline 
6189
6190 \newline 
6191
6192 \family typewriter 
6193 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
6194 \layout Subsubsection
6195
6196 Highest Order Bit
6197 \layout Standard
6198
6199 It is frequently required to obtain the highest order bit of an integral
6200  type (long, int, short or char types).
6201  SDCC recognizes the following expression to yield the highest order bit
6202  and generates optimized code for it, e.g.:
6203 \newline 
6204
6205 \newline 
6206  
6207 \family typewriter 
6208 unsigned int gint; 
6209 \newline 
6210
6211 \newline 
6212 foo () { 
6213 \newline 
6214 unsigned char hob; 
6215 \newline 
6216 \SpecialChar ~
6217 \SpecialChar ~
6218 ...
6219  
6220 \newline 
6221 \SpecialChar ~
6222 \SpecialChar ~
6223 hob = (gint >> 15) & 1; 
6224 \newline 
6225 \SpecialChar ~
6226 \SpecialChar ~
6227 ..
6228  
6229 \newline 
6230 }
6231 \family default 
6232
6233 \newline 
6234
6235 \newline 
6236 will generate the following code:
6237 \newline 
6238
6239 \family typewriter 
6240
6241 \newline 
6242 \SpecialChar ~
6243 \SpecialChar ~
6244 \SpecialChar ~
6245 \SpecialChar ~
6246 \SpecialChar ~
6247 \SpecialChar ~
6248 \SpecialChar ~
6249 \SpecialChar ~
6250 \SpecialChar ~
6251 \SpecialChar ~
6252 \SpecialChar ~
6253 \SpecialChar ~
6254 \SpecialChar ~
6255 \SpecialChar ~
6256 \SpecialChar ~
6257 \SpecialChar ~
6258 \SpecialChar ~
6259 \SpecialChar ~
6260 \SpecialChar ~
6261 \SpecialChar ~
6262 \SpecialChar ~
6263 \SpecialChar ~
6264 \SpecialChar ~
6265 \SpecialChar ~
6266 \SpecialChar ~
6267 \SpecialChar ~
6268 \SpecialChar ~
6269 \SpecialChar ~
6270  61 ;\SpecialChar ~
6271  hob.c 7 
6272 \newline 
6273 \SpecialChar ~
6274 \SpecialChar ~
6275  000A E5*01\SpecialChar ~
6276 \SpecialChar ~
6277 \SpecialChar ~
6278 \SpecialChar ~
6279 \SpecialChar ~
6280 \SpecialChar ~
6281 \SpecialChar ~
6282 \SpecialChar ~
6283 \SpecialChar ~
6284 \SpecialChar ~
6285 \SpecialChar ~
6286 \SpecialChar ~
6287 \SpecialChar ~
6288 \SpecialChar ~
6289 \SpecialChar ~
6290  62\SpecialChar ~
6291 \SpecialChar ~
6292 \SpecialChar ~
6293 \SpecialChar ~
6294 \SpecialChar ~
6295 \SpecialChar ~
6296 \SpecialChar ~
6297 \SpecialChar ~
6298  mov\SpecialChar ~
6299  a,(_gint + 1) 
6300 \newline 
6301 \SpecialChar ~
6302 \SpecialChar ~
6303  000C 33\SpecialChar ~
6304 \SpecialChar ~
6305 \SpecialChar ~
6306 \SpecialChar ~
6307 \SpecialChar ~
6308 \SpecialChar ~
6309 \SpecialChar ~
6310 \SpecialChar ~
6311 \SpecialChar ~
6312 \SpecialChar ~
6313 \SpecialChar ~
6314 \SpecialChar ~
6315 \SpecialChar ~
6316 \SpecialChar ~
6317 \SpecialChar ~
6318 \SpecialChar ~
6319 \SpecialChar ~
6320 \SpecialChar ~
6321  63\SpecialChar ~
6322 \SpecialChar ~
6323 \SpecialChar ~
6324 \SpecialChar ~
6325 \SpecialChar ~
6326 \SpecialChar ~
6327 \SpecialChar ~
6328 \SpecialChar ~
6329  rlc\SpecialChar ~
6330  a 
6331 \newline 
6332 \SpecialChar ~
6333 \SpecialChar ~
6334  000D E4\SpecialChar ~
6335 \SpecialChar ~
6336 \SpecialChar ~
6337 \SpecialChar ~
6338 \SpecialChar ~
6339 \SpecialChar ~
6340 \SpecialChar ~
6341 \SpecialChar ~
6342 \SpecialChar ~
6343 \SpecialChar ~
6344 \SpecialChar ~
6345 \SpecialChar ~
6346 \SpecialChar ~
6347 \SpecialChar ~
6348 \SpecialChar ~
6349 \SpecialChar ~
6350 \SpecialChar ~
6351 \SpecialChar ~
6352  64\SpecialChar ~
6353 \SpecialChar ~
6354 \SpecialChar ~
6355 \SpecialChar ~
6356 \SpecialChar ~
6357 \SpecialChar ~
6358 \SpecialChar ~
6359 \SpecialChar ~
6360  clr\SpecialChar ~
6361  a 
6362 \newline 
6363 \SpecialChar ~
6364 \SpecialChar ~
6365  000E 13\SpecialChar ~
6366 \SpecialChar ~
6367 \SpecialChar ~
6368 \SpecialChar ~
6369 \SpecialChar ~
6370 \SpecialChar ~
6371 \SpecialChar ~
6372 \SpecialChar ~
6373 \SpecialChar ~
6374 \SpecialChar ~
6375 \SpecialChar ~
6376 \SpecialChar ~
6377 \SpecialChar ~
6378 \SpecialChar ~
6379 \SpecialChar ~
6380 \SpecialChar ~
6381 \SpecialChar ~
6382 \SpecialChar ~
6383  65\SpecialChar ~
6384 \SpecialChar ~
6385 \SpecialChar ~
6386 \SpecialChar ~
6387 \SpecialChar ~
6388 \SpecialChar ~
6389 \SpecialChar ~
6390 \SpecialChar ~
6391  rrc\SpecialChar ~
6392  a 
6393 \newline 
6394 \SpecialChar ~
6395 \SpecialChar ~
6396  000F F5*02\SpecialChar ~
6397 \SpecialChar ~
6398 \SpecialChar ~
6399 \SpecialChar ~
6400 \SpecialChar ~
6401 \SpecialChar ~
6402 \SpecialChar ~
6403 \SpecialChar ~
6404 \SpecialChar ~
6405 \SpecialChar ~
6406 \SpecialChar ~
6407 \SpecialChar ~
6408 \SpecialChar ~
6409 \SpecialChar ~
6410 \SpecialChar ~
6411  66\SpecialChar ~
6412 \SpecialChar ~
6413 \SpecialChar ~
6414 \SpecialChar ~
6415 \SpecialChar ~
6416 \SpecialChar ~
6417 \SpecialChar ~
6418 \SpecialChar ~
6419  mov\SpecialChar ~
6420  _foo_hob_1_1,a
6421 \newline 
6422
6423 \newline 
6424
6425 \family default 
6426 Variations of this case however will 
6427 \emph on 
6428 not
6429 \emph default 
6430  be recognized.
6431  It is a standard C expression, so I heartily recommend this be the only
6432  way to get the highest order bit, (it is portable).
6433  Of course it will be recognized even if it is embedded in other expressions,
6434  e.g.:
6435 \newline 
6436
6437 \newline 
6438
6439 \family typewriter 
6440 xyz = gint + ((gint >> 15) & 1);
6441 \family default 
6442
6443 \newline 
6444
6445 \newline 
6446 will still be recognized.
6447 \layout Subsubsection
6448
6449 Peep-hole Optimizer
6450 \layout Standard
6451
6452 The compiler uses a rule based, pattern matching and re-writing mechanism
6453  for peep-hole optimization.
6454  It is inspired by 
6455 \emph on 
6456 copt
6457 \emph default 
6458  a peep-hole optimizer by Christopher W.
6459  Fraser (cwfraser@microsoft.com).
6460  A default set of rules are compiled into the compiler, additional rules
6461  may be added with the 
6462 \emph on 
6463 ---peep-file <filename>
6464 \emph default 
6465  option.
6466  The rule language is best illustrated with examples.
6467 \newline 
6468
6469 \newline 
6470
6471 \family typewriter 
6472 replace { 
6473 \newline 
6474 \SpecialChar ~
6475 \SpecialChar ~
6476 mov %1,a 
6477 \newline 
6478 \SpecialChar ~
6479 \SpecialChar ~
6480 mov a,%1
6481 \newline 
6482 } by {
6483 \newline 
6484 \SpecialChar ~
6485 \SpecialChar ~
6486 mov %1,a
6487 \newline 
6488 }
6489 \family default 
6490
6491 \newline 
6492
6493 \newline 
6494 The above rule will change the following assembly sequence:
6495 \newline 
6496
6497 \newline 
6498
6499 \family typewriter 
6500 \SpecialChar ~
6501 \SpecialChar ~
6502 mov r1,a 
6503 \newline 
6504 \SpecialChar ~
6505 \SpecialChar ~
6506 mov a,r1
6507 \family default 
6508
6509 \newline 
6510
6511 \newline 
6512 to
6513 \newline 
6514
6515 \newline 
6516
6517 \family typewriter 
6518 mov r1,a
6519 \family default 
6520
6521 \newline 
6522
6523 \newline 
6524 Note: All occurrences of a 
6525 \emph on 
6526 %n
6527 \emph default 
6528  (pattern variable) must denote the same string.
6529  With the above rule, the assembly sequence:
6530 \newline 
6531
6532 \newline 
6533
6534 \family typewriter 
6535 \SpecialChar ~
6536 \SpecialChar ~
6537 mov r1,a 
6538 \newline 
6539 \SpecialChar ~
6540 \SpecialChar ~
6541 mov a,r2
6542 \family default 
6543
6544 \newline 
6545
6546 \newline 
6547 will remain unmodified.
6548 \newline 
6549
6550 \newline 
6551 Other special case optimizations may be added by the user (via 
6552 \emph on 
6553 ---peep-file option
6554 \emph default 
6555 ).
6556  E.g.
6557  some variants of the 8051 MCU allow only 
6558 \family typewriter 
6559 ajmp
6560 \family default 
6561  and 
6562 \family typewriter 
6563 acall
6564 \family default 
6565 .
6566  The following two rules will change all 
6567 \family typewriter 
6568 ljmp
6569 \family default 
6570  and 
6571 \family typewriter 
6572 lcall
6573 \family default 
6574  to 
6575 \family typewriter 
6576 ajmp
6577 \family default 
6578  and 
6579 \family typewriter 
6580 acall
6581 \family default 
6582
6583 \newline 
6584
6585 \newline 
6586
6587 \family typewriter 
6588 replace { lcall %1 } by { acall %1 } 
6589 \newline 
6590 replace { ljmp %1 } by { ajmp %1 }
6591 \family default 
6592
6593 \newline 
6594
6595 \newline 
6596 The 
6597 \emph on 
6598 inline-assembler code
6599 \emph default 
6600  is also passed through the peep hole optimizer, thus the peephole optimizer
6601  can also be used as an assembly level macro expander.
6602  The rules themselves are MCU dependent whereas the rule language infra-structur
6603 e is MCU independent.
6604  Peephole optimization rules for other MCU can be easily programmed using
6605  the rule language.
6606 \newline 
6607
6608 \newline 
6609 The syntax for a rule is as follows:
6610 \newline 
6611
6612 \newline 
6613
6614 \family typewriter 
6615 rule := replace [ restart ] '{' <assembly sequence> '
6616 \backslash 
6617 n' 
6618 \newline 
6619 \SpecialChar ~
6620  \SpecialChar ~
6621  \SpecialChar ~
6622  \SpecialChar ~
6623  \SpecialChar ~
6624  \SpecialChar ~
6625  \SpecialChar ~
6626  \SpecialChar ~
6627  \SpecialChar ~
6628  \SpecialChar ~
6629  \SpecialChar ~
6630  \SpecialChar ~
6631  \SpecialChar ~
6632  \SpecialChar ~
6633  '}' by '{' '
6634 \backslash 
6635 n' 
6636 \newline 
6637 \SpecialChar ~
6638  \SpecialChar ~
6639  \SpecialChar ~
6640  \SpecialChar ~
6641  \SpecialChar ~
6642  \SpecialChar ~
6643  \SpecialChar ~
6644  \SpecialChar ~
6645  \SpecialChar ~
6646  \SpecialChar ~
6647  \SpecialChar ~
6648  \SpecialChar ~
6649  \SpecialChar ~
6650  \SpecialChar ~
6651  \SpecialChar ~
6652  \SpecialChar ~
6653  <assembly sequence> '
6654 \backslash 
6655 n' 
6656 \newline 
6657 \SpecialChar ~
6658  \SpecialChar ~
6659  \SpecialChar ~
6660  \SpecialChar ~
6661  \SpecialChar ~
6662  \SpecialChar ~
6663  \SpecialChar ~
6664  \SpecialChar ~
6665  \SpecialChar ~
6666  \SpecialChar ~
6667  \SpecialChar ~
6668  \SpecialChar ~
6669  \SpecialChar ~
6670  \SpecialChar ~
6671  '}' [if <functionName> ] '
6672 \backslash 
6673 n' 
6674 \newline 
6675
6676 \family default 
6677
6678 \newline 
6679 <assembly sequence> := assembly instruction (each instruction including
6680  labels must be on a separate line).
6681 \newline 
6682
6683 \newline 
6684 The optimizer will apply to the rules one by one from the top in the sequence
6685  of their appearance, it will terminate when all rules are exhausted.
6686  If the 'restart' option is specified, then the optimizer will start matching
6687  the rules again from the top, this option for a rule is expensive (performance)
6688 , it is intended to be used in situations where a transformation will trigger
6689  the same rule again.
6690  An example of this (not a good one, it has side effects) is the following
6691  rule:
6692 \newline 
6693
6694 \newline 
6695
6696 \family typewriter 
6697 replace restart { 
6698 \newline 
6699 \SpecialChar ~
6700 \SpecialChar ~
6701 pop %1 
6702 \newline 
6703 \SpecialChar ~
6704 \SpecialChar ~
6705 push %1 } by { 
6706 \newline 
6707 \SpecialChar ~
6708 \SpecialChar ~
6709 ; nop 
6710 \newline 
6711 }
6712 \family default 
6713
6714 \newline 
6715
6716 \newline 
6717 Note that the replace pattern cannot be a blank, but can be a comment line.
6718  Without the 'restart' option only the inner most 'pop' 'push' pair would
6719  be eliminated, i.e.:
6720 \newline 
6721
6722 \newline 
6723
6724 \family typewriter 
6725 \SpecialChar ~
6726 \SpecialChar ~
6727 pop ar1 
6728 \newline 
6729 \SpecialChar ~
6730 \SpecialChar ~
6731 pop ar2 
6732 \newline 
6733 \SpecialChar ~
6734 \SpecialChar ~
6735 push ar2 
6736 \newline 
6737 \SpecialChar ~
6738 \SpecialChar ~
6739 push ar1
6740 \family default 
6741
6742 \newline 
6743
6744 \newline 
6745 would result in:
6746 \newline 
6747
6748 \newline 
6749
6750 \family typewriter 
6751 \SpecialChar ~
6752 \SpecialChar ~
6753 pop ar1 
6754 \newline 
6755 \SpecialChar ~
6756 \SpecialChar ~
6757 ; nop 
6758 \newline 
6759 \SpecialChar ~
6760 \SpecialChar ~
6761 push ar1
6762 \family default 
6763
6764 \newline 
6765
6766 \newline 
6767
6768 \emph on 
6769 with
6770 \emph default 
6771  the restart option the rule will be applied again to the resulting code
6772  and then all the pop-push pairs will be eliminated to yield:
6773 \newline 
6774
6775 \newline 
6776
6777 \family typewriter 
6778 \SpecialChar ~
6779 \SpecialChar ~
6780 ; nop 
6781 \newline 
6782 \SpecialChar ~
6783 \SpecialChar ~
6784 ; nop
6785 \family default 
6786
6787 \newline 
6788
6789 \newline 
6790 A conditional function can be attached to a rule.
6791  Attaching rules are somewhat more involved, let me illustrate this with
6792  an example.
6793 \newline 
6794
6795 \newline 
6796
6797 \family typewriter 
6798 replace { 
6799 \newline 
6800 \SpecialChar ~
6801  \SpecialChar ~
6802  \SpecialChar ~
6803 ljmp %5 
6804 \newline 
6805 %2:
6806 \newline 
6807 } by { 
6808 \newline 
6809 \SpecialChar ~
6810  \SpecialChar ~
6811  \SpecialChar ~
6812 sjmp %5 
6813 \newline 
6814 %2:
6815 \newline 
6816 } if labelInRange
6817 \family default 
6818
6819 \newline 
6820
6821 \newline 
6822 The optimizer does a look-up of a function name table defined in function
6823  
6824 \emph on 
6825 callFuncByName
6826 \emph default 
6827  in the source file SDCCpeeph.c, with the name 
6828 \emph on 
6829 labelInRange
6830 \emph default 
6831 .
6832  If it finds a corresponding entry the function is called.
6833  Note there can be no parameters specified for these functions, in this
6834  case the use of 
6835 \emph on 
6836 %5
6837 \emph default 
6838  is crucial, since the function 
6839 \emph on 
6840 labelInRange
6841 \emph default 
6842  expects to find the label in that particular variable (the hash table containin
6843 g the variable bindings is passed as a parameter).
6844  If you want to code more such functions, take a close look at the function
6845  labelInRange and the calling mechanism in source file SDCCpeeph.c.
6846  I know this whole thing is a little kludgey, but maybe some day we will
6847  have some better means.
6848  If you are looking at this file, you will also see the default rules that
6849  are compiled into the compiler, you can add your own rules in the default
6850  set there if you get tired of specifying the ---peep-file option.
6851 \layout Subsection
6852
6853 Pragmas
6854 \layout Standard
6855
6856 SDCC supports the following #pragma directives.
6857 \layout Itemize
6858
6859 SAVE - this will save all the current options.
6860 \layout Itemize
6861
6862 RESTORE - will restore the saved options from the last save.
6863  Note that SAVEs & RESTOREs cannot be nested.
6864  SDCC uses the same buffer to save the options each time a SAVE is called.
6865  (jwk burps: either fix that or throw a warning)
6866 \layout Itemize
6867
6868 NOGCSE - will stop global subexpression elimination.
6869 \layout Itemize
6870
6871 NOINDUCTION - will stop loop induction optimizations.
6872 \layout Itemize
6873
6874 NOJTBOUND - will not generate code for boundary value checking, when switch
6875  statements are turned into jump-tables.
6876 \layout Itemize
6877
6878 NOOVERLAY - the compiler will not overlay the parameters and local variables
6879  of a function.
6880 \layout Itemize
6881
6882 LESS_PEDANTIC - the compiler will not warn you anymore for obvious mistakes,
6883  you'r on your own now ;-(
6884 \layout Itemize
6885
6886 NOLOOPREVERSE - Will not do loop reversal optimization
6887 \layout Itemize
6888
6889 EXCLUDE NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma disables generation
6890  of pair of push/pop instruction in ISR function (using interrupt keyword).
6891  The directive should be placed immediately before the ISR function definition
6892  and it affects ALL ISR functions following it.
6893  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
6894 EXCLUDE\SpecialChar ~
6895 none.
6896 \layout Itemize
6897
6898 NOIV - Do not generate interrupt vector table entries for all ISR functions
6899  defined after the pragma.
6900  This is useful in cases where the interrupt vector table must be defined
6901  manually, or when there is a secondary, manually defined interrupt vector
6902  table (e.g.
6903  for the autovector feature of the Cypress EZ-USB FX2).
6904 \layout Itemize
6905
6906 CALLEE-SAVES function1[,function2[,function3...]] - The compiler by default
6907  uses a caller saves convention for register saving across function calls,
6908  however this can cause unneccessary register pushing & popping when calling
6909  small functions from larger functions.
6910  This option can be used to switch the register saving convention for the
6911  function names specified.
6912  The compiler will not save registers when calling these functions, extra
6913  code will be generated at the entry & exit for these functions to save
6914  & restore the registers used by these functions, this can SUBSTANTIALLY
6915  reduce code & improve run time performance of the generated code.
6916  In future the compiler (with interprocedural analysis) will be able to
6917  determine the appropriate scheme to use for each function call.
6918  If ---callee-saves command line option is used, the function names specified
6919  in #pragma\SpecialChar ~
6920 CALLEE-SAVES is appended to the list of functions specified inthe
6921  command line.
6922 \layout Standard
6923
6924 The pragma's are intended to be used to turn-off certain optimizations which
6925  might cause the compiler to generate extra stack / data space to store
6926  compiler generated temporary variables.
6927  This usually happens in large functions.
6928  Pragma directives should be used as shown in the following example, they
6929  are used to control options & optimizations for a given function; pragmas
6930  should be placed before and/or after a function, placing pragma's inside
6931  a function body could have unpredictable results.
6932 \newline 
6933
6934 \newline 
6935
6936 \family typewriter 
6937 #pragma SAVE /* save the current settings */ 
6938 \newline 
6939 #pragma NOGCSE /* turnoff global subexpression elimination */ 
6940 \newline 
6941 #pragma NOINDUCTION /* turn off induction optimizations */ 
6942 \newline 
6943 int foo () 
6944 \newline 
6945
6946 \newline 
6947 \SpecialChar ~
6948  \SpecialChar ~
6949  ...
6950  
6951 \newline 
6952 \SpecialChar ~
6953  \SpecialChar ~
6954  /* large code */ 
6955 \newline 
6956 \SpecialChar ~
6957  \SpecialChar ~
6958  ...
6959  
6960 \newline 
6961
6962 \newline 
6963 #pragma RESTORE /* turn the optimizations back on */
6964 \family default 
6965
6966 \newline 
6967
6968 \newline 
6969 The compiler will generate a warning message when extra space is allocated.
6970  It is strongly recommended that the SAVE and RESTORE pragma's be used when
6971  changing options for a function.
6972 \layout Subsection
6973
6974
6975 \emph on 
6976 <pending: this is messy and incomplete>
6977 \emph default 
6978  Library Routines
6979 \layout Enumerate
6980
6981 Compiler support routines (_gptrget, _mulint etc)
6982 \layout Enumerate
6983
6984 Stdclib functions (puts, printf, strcat etc)
6985 \layout Enumerate
6986
6987 Math functions (sin, pow, sqrt etc)
6988 \layout Subsection
6989
6990 Interfacing with Assembly Routines
6991 \layout Subsubsection
6992
6993 Global Registers used for Parameter Passing
6994 \layout Standard
6995
6996 The compiler always uses the global registers 
6997 \emph on 
6998 DPL,DPH,B 
6999 \emph default 
7000 and
7001 \emph on 
7002  ACC
7003 \emph default 
7004  to pass the first parameter to a routine.
7005  The second parameter onwards is either allocated on the stack (for reentrant
7006  routines or if ---stack-auto is used) or in the internal / external ram
7007  (depending on the memory model).
7008  
7009 \layout Subsubsection
7010
7011 Assembler Routine(non-reentrant)
7012 \layout Standard
7013
7014 In the following example the function cfunc calls an assembler routine asm_func,
7015  which takes two parameters.
7016 \newline 
7017
7018 \newline 
7019
7020 \family typewriter 
7021 extern int asm_func(unsigned char, unsigned char);
7022 \newline 
7023
7024 \newline 
7025 int c_func (unsigned char i, unsigned char j)
7026 \newline 
7027 {
7028 \newline 
7029 \SpecialChar ~
7030 \SpecialChar ~
7031 \SpecialChar ~
7032 \SpecialChar ~
7033 return asm_func(i,j);
7034 \newline 
7035 }
7036 \newline 
7037
7038 \newline 
7039 int main()
7040 \newline 
7041 {
7042 \newline 
7043 \SpecialChar ~
7044 \SpecialChar ~
7045 \SpecialChar ~
7046 \SpecialChar ~
7047 return c_func(10,9);
7048 \newline 
7049 }
7050 \newline 
7051
7052 \newline 
7053
7054 \family default 
7055 The corresponding assembler function is:
7056 \newline 
7057
7058 \newline 
7059
7060 \family typewriter 
7061 .globl _asm_func_PARM_2 
7062 \newline 
7063 \SpecialChar ~
7064 \SpecialChar ~
7065 \SpecialChar ~
7066 \SpecialChar ~
7067 \SpecialChar ~
7068 \SpecialChar ~
7069 \SpecialChar ~
7070 \SpecialChar ~
7071 .globl _asm_func 
7072 \newline 
7073 \SpecialChar ~
7074 \SpecialChar ~
7075 \SpecialChar ~
7076 \SpecialChar ~
7077 \SpecialChar ~
7078 \SpecialChar ~
7079 \SpecialChar ~
7080 \SpecialChar ~
7081 .area OSEG 
7082 \newline 
7083 _asm_func_PARM_2:
7084 \newline 
7085 \SpecialChar ~
7086 \SpecialChar ~
7087 \SpecialChar ~
7088 \SpecialChar ~
7089 \SpecialChar ~
7090 \SpecialChar ~
7091 \SpecialChar ~
7092 \SpecialChar ~
7093 .ds      1 
7094 \newline 
7095 \SpecialChar ~
7096 \SpecialChar ~
7097 \SpecialChar ~
7098 \SpecialChar ~
7099 \SpecialChar ~
7100 \SpecialChar ~
7101 \SpecialChar ~
7102 \SpecialChar ~
7103 .area CSEG 
7104 \newline 
7105 _asm_func: 
7106 \newline 
7107 \SpecialChar ~
7108 \SpecialChar ~
7109 \SpecialChar ~
7110 \SpecialChar ~
7111 \SpecialChar ~
7112 \SpecialChar ~
7113 \SpecialChar ~
7114 \SpecialChar ~
7115 mov     a,dpl 
7116 \newline 
7117 \SpecialChar ~
7118 \SpecialChar ~
7119 \SpecialChar ~
7120 \SpecialChar ~
7121 \SpecialChar ~
7122 \SpecialChar ~
7123 \SpecialChar ~
7124 \SpecialChar ~
7125 add     a,_asm_func_PARM_2 
7126 \newline 
7127 \SpecialChar ~
7128 \SpecialChar ~
7129 \SpecialChar ~
7130 \SpecialChar ~
7131 \SpecialChar ~
7132 \SpecialChar ~
7133 \SpecialChar ~
7134 \SpecialChar ~
7135 mov     dpl,a 
7136 \newline 
7137 \SpecialChar ~
7138 \SpecialChar ~
7139 \SpecialChar ~
7140 \SpecialChar ~
7141 \SpecialChar ~
7142 \SpecialChar ~
7143 \SpecialChar ~
7144 \SpecialChar ~
7145 mov     dpl,#0x00 
7146 \newline 
7147 \SpecialChar ~
7148 \SpecialChar ~
7149 \SpecialChar ~
7150 \SpecialChar ~
7151 \SpecialChar ~
7152 \SpecialChar ~
7153 \SpecialChar ~
7154 \SpecialChar ~
7155 ret
7156 \newline 
7157
7158 \newline 
7159
7160 \family default 
7161 Note here that the return values are placed in 'dpl' - One byte return value,
7162  'dpl' LSB & 'dph' MSB for two byte values.
7163  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
7164 b' & 'acc' for four byte values.
7165 \layout Standard
7166
7167 The parameter naming convention is _<function_name>_PARM_<n>, where n is
7168  the parameter number starting from 1, and counting from the left.
7169  The first parameter is passed in 
7170 \begin_inset Quotes eld
7171 \end_inset 
7172
7173 dpl
7174 \begin_inset Quotes erd
7175 \end_inset 
7176
7177  for One bye parameter, 
7178 \begin_inset Quotes eld
7179 \end_inset 
7180
7181 dptr
7182 \begin_inset Quotes erd
7183 \end_inset 
7184
7185  if two bytes, 
7186 \begin_inset Quotes eld
7187 \end_inset 
7188
7189 b,dptr
7190 \begin_inset Quotes erd
7191 \end_inset 
7192
7193  for three bytes and 
7194 \begin_inset Quotes eld
7195 \end_inset 
7196
7197 acc,b,dptr
7198 \begin_inset Quotes erd
7199 \end_inset 
7200
7201  for four bytes, the varible name for the second parameter will be _<function_na
7202 me>_PARM_2.
7203 \newline 
7204
7205 \newline 
7206 Assemble the assembler routine with the following command:
7207 \newline 
7208
7209 \newline 
7210
7211 \family sans 
7212 \series bold 
7213 asx8051 -losg asmfunc.asm
7214 \newline 
7215
7216 \newline 
7217
7218 \family default 
7219 \series default 
7220 Then compile and link the assembler routine to the C source file with the
7221  following command:
7222 \newline 
7223
7224 \newline 
7225
7226 \family sans 
7227 \series bold 
7228 sdcc cfunc.c asmfunc.rel
7229 \layout Subsubsection
7230
7231 Assembler Routine(reentrant)
7232 \layout Standard
7233
7234 In this case the second parameter onwards will be passed on the stack, the
7235  parameters are pushed from right to left i.e.
7236  after the call the left most parameter will be on the top of the stack.
7237  Here is an example:
7238 \newline 
7239
7240 \newline 
7241
7242 \family typewriter 
7243 extern int asm_func(unsigned char, unsigned char);
7244 \newline 
7245
7246 \newline 
7247 int c_func (unsigned char i, unsigned char j) reentrant 
7248 \newline 
7249
7250 \newline 
7251 \SpecialChar ~
7252 \SpecialChar ~
7253 \SpecialChar ~
7254 \SpecialChar ~
7255 return asm_func(i,j); 
7256 \newline 
7257
7258 \newline 
7259
7260 \newline 
7261 int main() 
7262 \newline 
7263
7264 \newline 
7265 \SpecialChar ~
7266 \SpecialChar ~
7267 \SpecialChar ~
7268 \SpecialChar ~
7269 return c_func(10,9); 
7270 \newline 
7271 }
7272 \newline 
7273
7274 \family default 
7275
7276 \newline 
7277 The corresponding assembler routine is:
7278 \newline 
7279
7280 \newline 
7281
7282 \family typewriter 
7283 .globl _asm_func 
7284 \newline 
7285 _asm_func: 
7286 \newline 
7287 \SpecialChar ~
7288 \SpecialChar ~
7289 \SpecialChar ~
7290 \SpecialChar ~
7291 push  _bp 
7292 \newline 
7293 \SpecialChar ~
7294 \SpecialChar ~
7295 \SpecialChar ~
7296 \SpecialChar ~
7297 mov  _bp,sp 
7298 \newline 
7299 \SpecialChar ~
7300 \SpecialChar ~
7301 \SpecialChar ~
7302 \SpecialChar ~
7303 mov  r2,dpl
7304 \newline 
7305 \SpecialChar ~
7306 \SpecialChar ~
7307 \SpecialChar ~
7308 \SpecialChar ~
7309 mov  a,_bp 
7310 \newline 
7311 \SpecialChar ~
7312 \SpecialChar ~
7313 \SpecialChar ~
7314 \SpecialChar ~
7315 clr  c 
7316 \newline 
7317 \SpecialChar ~
7318 \SpecialChar ~
7319 \SpecialChar ~
7320 \SpecialChar ~
7321 add  a,#0xfd 
7322 \newline 
7323 \SpecialChar ~
7324 \SpecialChar ~
7325 \SpecialChar ~
7326 \SpecialChar ~
7327 mov  r0,a 
7328 \newline 
7329 \SpecialChar ~
7330 \SpecialChar ~
7331 \SpecialChar ~
7332 \SpecialChar ~
7333 add  a,#0xfc
7334 \newline 
7335 \SpecialChar ~
7336 \SpecialChar ~
7337 \SpecialChar ~
7338 \SpecialChar ~
7339 mov  r1,a 
7340 \newline 
7341 \SpecialChar ~
7342 \SpecialChar ~
7343 \SpecialChar ~
7344 \SpecialChar ~
7345 mov  a,@r0 
7346 \newline 
7347 \SpecialChar ~
7348 \SpecialChar ~
7349 \SpecialChar ~
7350 \SpecialChar ~
7351 add  a,r2
7352 \newline 
7353 \SpecialChar ~
7354 \SpecialChar ~
7355 \SpecialChar ~
7356 \SpecialChar ~
7357 mov  dpl,a 
7358 \newline 
7359 \SpecialChar ~
7360 \SpecialChar ~
7361 \SpecialChar ~
7362 \SpecialChar ~
7363 mov  dph,#0x00 
7364 \newline 
7365 \SpecialChar ~
7366 \SpecialChar ~
7367 \SpecialChar ~
7368 \SpecialChar ~
7369 mov  sp,_bp 
7370 \newline 
7371 \SpecialChar ~
7372 \SpecialChar ~
7373 \SpecialChar ~
7374 \SpecialChar ~
7375 pop  _bp 
7376 \newline 
7377 \SpecialChar ~
7378 \SpecialChar ~
7379 \SpecialChar ~
7380 \SpecialChar ~
7381 ret
7382 \newline 
7383
7384 \newline 
7385
7386 \family default 
7387 The compiling and linking procedure remains the same, however note the extra
7388  entry & exit linkage required for the assembler code, _bp is the stack
7389  frame pointer and is used to compute the offset into the stack for parameters
7390  and local variables.
7391 \layout Subsection
7392
7393 External Stack
7394 \layout Standard
7395
7396 The external stack is located at the start of the external ram segment,
7397  and is 256 bytes in size.
7398  When ---xstack option is used to compile the program, the parameters and
7399  local variables of all reentrant functions are allocated in this area.
7400  This option is provided for programs with large stack space requirements.
7401  When used with the ---stack-auto option, all parameters and local variables
7402  are allocated on the external stack (note support libraries will need to
7403  be recompiled with the same options).
7404 \layout Standard
7405
7406 The compiler outputs the higher order address byte of the external ram segment
7407  into PORT P2, therefore when using the External Stack option, this port
7408  MAY NOT be used by the application program.
7409 \layout Subsection
7410
7411 ANSI-Compliance
7412 \layout Standard
7413
7414 Deviations from the compliancy.
7415 \layout Itemize
7416
7417 functions are not always reentrant.
7418 \layout Itemize
7419
7420 structures cannot be assigned values directly, cannot be passed as function
7421  parameters or assigned to each other and cannot be a return value from
7422  a function, e.g.:
7423 \family typewriter 
7424
7425 \newline 
7426
7427 \newline 
7428 struct s { ...
7429  }; 
7430 \newline 
7431 struct s s1, s2; 
7432 \newline 
7433 foo() 
7434 \newline 
7435
7436 \newline 
7437 \SpecialChar ~
7438 \SpecialChar ~
7439 \SpecialChar ~
7440 \SpecialChar ~
7441 ...
7442  
7443 \newline 
7444 \SpecialChar ~
7445 \SpecialChar ~
7446 \SpecialChar ~
7447 \SpecialChar ~
7448 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */ 
7449 \newline 
7450 \SpecialChar ~
7451 \SpecialChar ~
7452 \SpecialChar ~
7453 \SpecialChar ~
7454 ...
7455  
7456 \newline 
7457 }
7458 \newline 
7459 struct s foo1 (struct s parms) /* is invalid in SDCC although allowed in
7460  ANSI */ 
7461 \newline 
7462
7463 \newline 
7464 \SpecialChar ~
7465 \SpecialChar ~
7466 \SpecialChar ~
7467 \SpecialChar ~
7468 struct s rets; 
7469 \newline 
7470 \SpecialChar ~
7471 \SpecialChar ~
7472 \SpecialChar ~
7473 \SpecialChar ~
7474 ...
7475  
7476 \newline 
7477 \SpecialChar ~
7478 \SpecialChar ~
7479 \SpecialChar ~
7480 \SpecialChar ~
7481 return rets;/* is invalid in SDCC although allowed in ANSI */ 
7482 \newline 
7483 }
7484 \layout Itemize
7485
7486 'long long' (64 bit integers) not supported.
7487 \layout Itemize
7488
7489 'double' precision floating point not supported.
7490 \layout Itemize
7491
7492 No support for setjmp and longjmp (for now).
7493 \layout Itemize
7494
7495 Old K&R style function declarations are NOT allowed.
7496 \newline 
7497
7498 \family typewriter 
7499
7500 \newline 
7501 foo(i,j) /* this old style of function declarations */ 
7502 \newline 
7503 int i,j; /* are valid in ANSI but not valid in SDCC */ 
7504 \newline 
7505
7506 \newline 
7507 \SpecialChar ~
7508 \SpecialChar ~
7509 \SpecialChar ~
7510 \SpecialChar ~
7511 ...
7512  
7513 \newline 
7514 }
7515 \layout Itemize
7516
7517 functions declared as pointers must be dereferenced during the call.
7518 \newline 
7519
7520 \family typewriter 
7521
7522 \newline 
7523 int (*foo)();
7524 \newline 
7525 ...
7526  
7527 \newline 
7528 /* has to be called like this */ 
7529 \newline 
7530 (*foo)(); /* ansi standard allows calls to be made like 'foo()' */
7531 \layout Subsection
7532
7533 Cyclomatic Complexity
7534 \layout Standard
7535
7536 Cyclomatic complexity of a function is defined as the number of independent
7537  paths the program can take during execution of the function.
7538  This is an important number since it defines the number test cases you
7539  have to generate to validate the function.
7540  The accepted industry standard for complexity number is 10, if the cyclomatic
7541  complexity reported by SDCC exceeds 10 you should think about simplification
7542  of the function logic.
7543  Note that the complexity level is not related to the number of lines of
7544  code in a function.
7545  Large functions can have low complexity, and small functions can have large
7546  complexity levels.
7547  
7548 \newline 
7549
7550 \newline 
7551 SDCC uses the following formula to compute the complexity:
7552 \newline 
7553
7554 \layout Standard
7555
7556 complexity = (number of edges in control flow graph) - (number of nodes
7557  in control flow graph) + 2;
7558 \newline 
7559
7560 \newline 
7561 Having said that the industry standard is 10, you should be aware that in
7562  some cases it be may unavoidable to have a complexity level of less than
7563  10.
7564  For example if you have switch statement with more than 10 case labels,
7565  each case label adds one to the complexity level.
7566  The complexity level is by no means an absolute measure of the algorithmic
7567  complexity of the function, it does however provide a good starting point
7568  for which functions you might look at for further optimization.
7569 \layout Section
7570
7571 TIPS
7572 \layout Standard
7573
7574 Here are a few guidelines that will help the compiler generate more efficient
7575  code, some of the tips are specific to this compiler others are generally
7576  good programming practice.
7577 \layout Itemize
7578
7579 Use the smallest data type to represent your data-value.
7580  If it is known in advance that the value is going to be less than 256 then
7581  use an 'unsigned char' instead of a 'short' or 'int'.
7582 \layout Itemize
7583
7584 Use unsigned when it is known in advance that the value is not going to
7585  be negative.
7586  This helps especially if you are doing division or multiplication.
7587 \layout Itemize
7588
7589 NEVER jump into a LOOP.
7590 \layout Itemize
7591
7592 Declare the variables to be local whenever possible, especially loop control
7593  variables (induction).
7594 \layout Itemize
7595
7596 Since the compiler does not always do implicit integral promotion, the programme
7597 r should do an explicit cast when integral promotion is required.
7598 \layout Itemize
7599
7600 Reducing the size of division, multiplication & modulus operations can reduce
7601  code size substantially.
7602  Take the following code for example.
7603 \family typewriter 
7604
7605 \newline 
7606
7607 \newline 
7608 foobar(unsigned int p1, unsigned char ch)
7609 \newline 
7610 {
7611 \newline 
7612     unsigned char ch1 = p1 % ch ;
7613 \newline 
7614     ....
7615     
7616 \newline 
7617 }
7618 \newline 
7619
7620 \family default 
7621
7622 \newline 
7623 For the modulus operation the variable ch will be promoted to unsigned int
7624  first then the modulus operation will be performed (this will lead to a
7625  call to support routine _moduint()), and the result will be casted to a
7626  char.
7627  If the code is changed to 
7628 \newline 
7629
7630 \family typewriter 
7631
7632 \newline 
7633 foobar(unsigned int p1, unsigned char ch)
7634 \newline 
7635 {
7636 \newline 
7637     unsigned char ch1 = (unsigned char)p1 % ch ;
7638 \newline 
7639     ....
7640     
7641 \newline 
7642 }
7643 \newline 
7644
7645 \family default 
7646
7647 \newline 
7648 It would substantially reduce the code generated (future versions of the
7649  compiler will be smart enough to detect such optimization oppurtunities).
7650 \layout Subsection
7651
7652 Notes on MCS51 memory layout
7653 \layout Standard
7654
7655 The 8051 family of micro controller have a minimum of 128 bytes of internal
7656  memory which is structured as follows
7657 \newline 
7658
7659 \newline 
7660 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7 to R7
7661  
7662 \newline 
7663 - Bytes 20-2F - 16 bytes to hold 128 bit variables and 
7664 \newline 
7665 - Bytes 30-7F - 60 bytes for general purpose use.
7666 \newline 
7667
7668 \newline 
7669 Normally the SDCC compiler will only utilise the first bank of registers,
7670  but it is possible to specify that other banks of registers should be used
7671  in interrupt routines.
7672  By default, the compiler will place the stack after the last bank of used
7673  registers, i.e.
7674  if the first 2 banks of registers are used, it will position the base of
7675  the internal stack at address 16 (0X10).
7676  This implies that as the stack grows, it will use up the remaining register
7677  banks, and the 16 bytes used by the 128 bit variables, and 60 bytes for
7678  general purpose use.
7679 \layout Standard
7680
7681 By default, the compiler uses the 60 general purpose bytes to hold "near
7682  data".
7683  The compiler/optimiser may also declare some Local Variables in this area
7684  to hold local data.
7685  
7686 \layout Standard
7687
7688 If any of the 128 bit variables are used, or near data is being used then
7689  care needs to be taken to ensure that the stack does not grow so much that
7690  it starts to over write either your bit variables or "near data".
7691  There is no runtime checking to prevent this from happening.
7692 \layout Standard
7693
7694 The amount of stack being used is affected by the use of the "internal stack"
7695  to save registers before a subroutine call is made (---stack-auto will
7696  declare parameters and local variables on the stack) and the number of
7697  nested subroutines.
7698 \layout Standard
7699
7700 If you detect that the stack is over writing you data, then the following
7701  can be done.
7702  ---xstack will cause an external stack to be used for saving registers
7703  and (if ---stack-auto is being used) storing parameters and local variables.
7704  However this will produce more code which will be slower to execute.
7705  
7706 \layout Standard
7707
7708 ---stack-loc will allow you specify the start of the stack, i.e.
7709  you could start it after any data in the general purpose area.
7710  However this may waste the memory not used by the register banks and if
7711  the size of the "near data" increases, it may creep into the bottom of
7712  the stack.
7713 \layout Standard
7714
7715 ---stack-after-data, similar to the ---stack-loc, but it automatically places
7716  the stack after the end of the "near data".
7717  Again this could waste any spare register space.
7718 \layout Standard
7719
7720 ---data-loc allows you to specify the start address of the near data.
7721  This could be used to move the "near data" further away from the stack
7722  giving it more room to grow.
7723  This will only work if no bit variables are being used and the stack can
7724  grow to use the bit variable space.
7725 \newline 
7726
7727 \newline 
7728 Conclusion.
7729 \newline 
7730
7731 \newline 
7732 If you find that the stack is over writing your bit variables or "near data"
7733  then the approach which best utilised the internal memory is to position
7734  the "near data" after the last bank of used registers or, if you use bit
7735  variables, after the last bit variable by using the ---data-loc, e.g.
7736  if two register banks are being used and no bit variables, ---data-loc
7737  16, and use the ---stack-after-data option.
7738 \layout Standard
7739
7740 If bit variables are being used, another method would be to try and squeeze
7741  the data area in the unused register banks if it will fit, and start the
7742  stack after the last bit variable.
7743 \layout Section
7744
7745 Retargetting for other MCUs.
7746 \layout Standard
7747
7748 The issues for retargetting the compiler are far too numerous to be covered
7749  by this document.
7750  What follows is a brief description of each of the seven phases of the
7751  compiler and its MCU dependency.
7752 \layout Itemize
7753
7754 Parsing the source and building the annotated parse tree.
7755  This phase is largely MCU independent (except for the language extensions).
7756  Syntax & semantic checks are also done in this phase, along with some initial
7757  optimizations like back patching labels and the pattern matching optimizations
7758  like bit-rotation etc.
7759 \layout Itemize
7760
7761 The second phase involves generating an intermediate code which can be easy
7762  manipulated during the later phases.
7763  This phase is entirely MCU independent.
7764  The intermediate code generation assumes the target machine has unlimited
7765  number of registers, and designates them with the name iTemp.
7766  The compiler can be made to dump a human readable form of the code generated
7767  by using the ---dumpraw option.
7768 \layout Itemize
7769
7770 This phase does the bulk of the standard optimizations and is also MCU independe
7771 nt.
7772  This phase can be broken down into several sub-phases:
7773 \newline 
7774
7775 \newline 
7776 Break down intermediate code (iCode) into basic blocks.
7777 \newline 
7778 Do control flow & data flow analysis on the basic blocks.
7779 \newline 
7780 Do local common subexpression elimination, then global subexpression elimination
7781 \newline 
7782 Dead code elimination
7783 \newline 
7784 Loop optimizations
7785 \newline 
7786 If loop optimizations caused any changes then do 'global subexpression eliminati
7787 on' and 'dead code elimination' again.
7788 \layout Itemize
7789
7790 This phase determines the live-ranges; by live range I mean those iTemp
7791  variables defined by the compiler that still survive after all the optimization
7792 s.
7793  Live range analysis is essential for register allocation, since these computati
7794 on determines which of these iTemps will be assigned to registers, and for
7795  how long.
7796 \layout Itemize
7797
7798 Phase five is register allocation.
7799  There are two parts to this process.
7800 \newline 
7801
7802 \newline 
7803 The first part I call 'register packing' (for lack of a better term).
7804  In this case several MCU specific expression folding is done to reduce
7805  register pressure.
7806 \newline 
7807
7808 \newline 
7809 The second part is more MCU independent and deals with allocating registers
7810  to the remaining live ranges.
7811  A lot of MCU specific code does creep into this phase because of the limited
7812  number of index registers available in the 8051.
7813 \layout Itemize
7814
7815 The Code generation phase is (unhappily), entirely MCU dependent and very
7816  little (if any at all) of this code can be reused for other MCU.
7817  However the scheme for allocating a homogenized assembler operand for each
7818  iCode operand may be reused.
7819 \layout Itemize
7820
7821 As mentioned in the optimization section the peep-hole optimizer is rule
7822  based system, which can reprogrammed for other MCUs.
7823 \layout Section
7824
7825 SDCDB - Source Level Debugger
7826 \layout Standard
7827
7828 SDCC is distributed with a source level debugger.
7829  The debugger uses a command line interface, the command repertoire of the
7830  debugger has been kept as close to gdb (the GNU debugger) as possible.
7831  The configuration and build process is part of the standard compiler installati
7832 on, which also builds and installs the debugger in the target directory
7833  specified during configuration.
7834  The debugger allows you debug BOTH at the C source and at the ASM source
7835  level.
7836 \layout Subsection
7837
7838 Compiling for Debugging
7839 \layout Standard
7840
7841 The \SpecialChar \-
7842 \SpecialChar \-
7843 debug option must be specified for all files for which debug information
7844  is to be generated.
7845  The complier generates a .cdb file for each of these files.
7846  The linker updates the .cdb file with the address information.
7847  This .cdb is used by the debugger.
7848 \layout Subsection
7849
7850 How the Debugger Works
7851 \layout Standard
7852
7853 When the ---debug option is specified the compiler generates extra symbol
7854  information some of which are put into the the assembler source and some
7855  are put into the .cdb file, the linker updates the .cdb file with the address
7856  information for the symbols.
7857  The debugger reads the symbolic information generated by the compiler &
7858  the address information generated by the linker.
7859  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
7860  execution is controlled by the debugger.
7861  When a command is issued for the debugger, it translates it into appropriate
7862  commands for the simulator.
7863 \layout Subsection
7864
7865 Starting the Debugger
7866 \layout Standard
7867
7868 The debugger can be started using the following command line.
7869  (Assume the file you are debugging has the file name foo).
7870 \newline 
7871
7872 \newline 
7873
7874 \family sans 
7875 \series bold 
7876 sdcdb foo
7877 \newline 
7878
7879 \family default 
7880 \series default 
7881
7882 \newline 
7883 The debugger will look for the following files.
7884 \layout Itemize
7885
7886 foo.c - the source file.
7887 \layout Itemize
7888
7889 foo.cdb - the debugger symbol information file.
7890 \layout Itemize
7891
7892 foo.ihx - the intel hex format object file.
7893 \layout Subsection
7894
7895 Command Line Options.
7896 \layout Itemize
7897
7898 ---directory=<source file directory> this option can used to specify the
7899  directory search list.
7900  The debugger will look into the directory list specified for source, cdb
7901  & ihx files.
7902  The items in the directory list must be separated by ':', e.g.
7903  if the source files can be in the directories /home/src1 and /home/src2,
7904  the ---directory option should be ---directory=/home/src1:/home/src2.
7905  Note there can be no spaces in the option.
7906  
7907 \layout Itemize
7908
7909 -cd <directory> - change to the <directory>.
7910 \layout Itemize
7911
7912 -fullname - used by GUI front ends.
7913 \layout Itemize
7914
7915 -cpu <cpu-type> - this argument is passed to the simulator please see the
7916  simulator docs for details.
7917 \layout Itemize
7918
7919 -X <Clock frequency > this options is passed to the simulator please see
7920  the simulator docs for details.
7921 \layout Itemize
7922
7923 -s <serial port file> passed to simulator see the simulator docs for details.
7924 \layout Itemize
7925
7926 -S <serial in,out> passed to simulator see the simulator docs for details.
7927 \layout Subsection
7928
7929 Debugger Commands.
7930 \layout Standard
7931
7932 As mention earlier the command interface for the debugger has been deliberately
7933  kept as close the GNU debugger gdb, as possible.
7934  This will help the integration with existing graphical user interfaces
7935  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
7936 \layout Subsubsection
7937
7938 break [line | file:line | function | file:function]
7939 \layout Standard
7940
7941 Set breakpoint at specified line or function:
7942 \newline 
7943
7944 \newline 
7945
7946 \family sans 
7947 \series bold 
7948 sdcdb>break 100 
7949 \newline 
7950 sdcdb>break foo.c:100
7951 \newline 
7952 sdcdb>break funcfoo
7953 \newline 
7954 sdcdb>break foo.c:funcfoo
7955 \layout Subsubsection
7956
7957 clear [line | file:line | function | file:function ]
7958 \layout Standard
7959
7960 Clear breakpoint at specified line or function:
7961 \newline 
7962
7963 \newline 
7964
7965 \family sans 
7966 \series bold 
7967 sdcdb>clear 100
7968 \newline 
7969 sdcdb>clear foo.c:100
7970 \newline 
7971 sdcdb>clear funcfoo
7972 \newline 
7973 sdcdb>clear foo.c:funcfoo
7974 \layout Subsubsection
7975
7976 continue
7977 \layout Standard
7978
7979 Continue program being debugged, after breakpoint.
7980 \layout Subsubsection
7981
7982 finish
7983 \layout Standard
7984
7985 Execute till the end of the current function.
7986 \layout Subsubsection
7987
7988 delete [n]
7989 \layout Standard
7990
7991 Delete breakpoint number 'n'.
7992  If used without any option clear ALL user defined break points.
7993 \layout Subsubsection
7994
7995 info [break | stack | frame | registers ]
7996 \layout Itemize
7997
7998 info break - list all breakpoints
7999 \layout Itemize
8000
8001 info stack - show the function call stack.
8002 \layout Itemize
8003
8004 info frame - show information about the current execution frame.
8005 \layout Itemize
8006
8007 info registers - show content of all registers.
8008 \layout Subsubsection
8009
8010 step
8011 \layout Standard
8012
8013 Step program until it reaches a different source line.
8014 \layout Subsubsection
8015
8016 next
8017 \layout Standard
8018
8019 Step program, proceeding through subroutine calls.
8020 \layout Subsubsection
8021
8022 run
8023 \layout Standard
8024
8025 Start debugged program.
8026 \layout Subsubsection
8027
8028 ptype variable 
8029 \layout Standard
8030
8031 Print type information of the variable.
8032 \layout Subsubsection
8033
8034 print variable
8035 \layout Standard
8036
8037 print value of variable.
8038 \layout Subsubsection
8039
8040 file filename
8041 \layout Standard
8042
8043 load the given file name.
8044  Note this is an alternate method of loading file for debugging.
8045 \layout Subsubsection
8046
8047 frame
8048 \layout Standard
8049
8050 print information about current frame.
8051 \layout Subsubsection
8052
8053 set srcmode
8054 \layout Standard
8055
8056 Toggle between C source & assembly source.
8057 \layout Subsubsection
8058
8059 ! simulator command
8060 \layout Standard
8061
8062 Send the string following '!' to the simulator, the simulator response is
8063  displayed.
8064  Note the debugger does not interpret the command being sent to the simulator,
8065  so if a command like 'go' is sent the debugger can loose its execution
8066  context and may display incorrect values.
8067 \layout Subsubsection
8068
8069 quit.
8070 \layout Standard
8071
8072 "Watch me now.
8073  Iam going Down.
8074  My name is Bobby Brown"
8075 \layout Subsection
8076
8077 Interfacing with XEmacs.
8078 \layout Standard
8079
8080 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
8081  sdcdb.el and sdcdbsrc.el.
8082  These two files can be found in the $(prefix)/bin directory after the installat
8083 ion is complete.
8084  These files need to be loaded into XEmacs for the interface to work.
8085  This can be done at XEmacs startup time by inserting the following into
8086  your '.xemacs' file (which can be found in your HOME directory): 
8087 \newline 
8088
8089 \newline 
8090
8091 \family typewriter 
8092 (load-file sdcdbsrc.el) 
8093 \family default 
8094
8095 \newline 
8096
8097 \newline 
8098 .xemacs is a lisp file so the () around the command is REQUIRED.
8099  The files can also be loaded dynamically while XEmacs is running, set the
8100  environment variable 'EMACSLOADPATH' to the installation bin directory
8101  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
8102  To start the interface enter the following command: 
8103 \newline 
8104
8105 \newline 
8106
8107 \family sans 
8108 \series bold 
8109 ESC-x sdcdbsrc
8110 \family default 
8111 \series default 
8112
8113 \newline 
8114
8115 \newline 
8116 You will prompted to enter the file name to be debugged.
8117  
8118 \newline 
8119
8120 \newline 
8121 The command line options that are passed to the simulator directly are bound
8122  to default values in the file sdcdbsrc.el.
8123  The variables are listed below, these values maybe changed as required.
8124 \layout Itemize
8125
8126 sdcdbsrc-cpu-type '51
8127 \layout Itemize
8128
8129 sdcdbsrc-frequency '11059200
8130 \layout Itemize
8131
8132 sdcdbsrc-serial nil
8133 \layout Standard
8134
8135 The following is a list of key mapping for the debugger interface.
8136 \layout Standard
8137
8138 \SpecialChar ~
8139
8140 \family typewriter 
8141
8142 \newline 
8143 ;; Current Listing :: 
8144 \newline 
8145 ;;key\SpecialChar ~
8146 \SpecialChar ~
8147 \SpecialChar ~
8148 \SpecialChar ~
8149 \SpecialChar ~
8150 \SpecialChar ~
8151 \SpecialChar ~
8152 \SpecialChar ~
8153 \SpecialChar ~
8154 \SpecialChar ~
8155 \SpecialChar ~
8156 \SpecialChar ~
8157 \SpecialChar ~
8158 \SpecialChar ~
8159 \SpecialChar ~
8160 binding\SpecialChar ~
8161 \SpecialChar ~
8162 \SpecialChar ~
8163 \SpecialChar ~
8164 \SpecialChar ~
8165 \SpecialChar ~
8166 \SpecialChar ~
8167 \SpecialChar ~
8168 \SpecialChar ~
8169 \SpecialChar ~
8170 \SpecialChar ~
8171 \SpecialChar ~
8172 \SpecialChar ~
8173 \SpecialChar ~
8174 \SpecialChar ~
8175 \SpecialChar ~
8176 \SpecialChar ~
8177 \SpecialChar ~
8178 \SpecialChar ~
8179 \SpecialChar ~
8180 \SpecialChar ~
8181 \SpecialChar ~
8182 Comment 
8183 \newline 
8184 ;;---\SpecialChar ~
8185 \SpecialChar ~
8186 \SpecialChar ~
8187 \SpecialChar ~
8188 \SpecialChar ~
8189 \SpecialChar ~
8190 \SpecialChar ~
8191 \SpecialChar ~
8192 \SpecialChar ~
8193 \SpecialChar ~
8194 \SpecialChar ~
8195 \SpecialChar ~
8196 \SpecialChar ~
8197 \SpecialChar ~
8198 \SpecialChar ~
8199 ------\SpecialChar ~
8200 \SpecialChar ~
8201 \SpecialChar ~
8202 \SpecialChar ~
8203 \SpecialChar ~
8204 \SpecialChar ~
8205 \SpecialChar ~
8206 \SpecialChar ~
8207 \SpecialChar ~
8208 \SpecialChar ~
8209 \SpecialChar ~
8210 \SpecialChar ~
8211 \SpecialChar ~
8212 \SpecialChar ~
8213 \SpecialChar ~
8214 \SpecialChar ~
8215 \SpecialChar ~
8216 \SpecialChar ~
8217 \SpecialChar ~
8218 \SpecialChar ~
8219 \SpecialChar ~
8220 \SpecialChar ~
8221 -------- 
8222 \newline 
8223 ;; 
8224 \newline 
8225 ;; n\SpecialChar ~
8226 \SpecialChar ~
8227 \SpecialChar ~
8228 \SpecialChar ~
8229 \SpecialChar ~
8230 \SpecialChar ~
8231 \SpecialChar ~
8232 \SpecialChar ~
8233 \SpecialChar ~
8234 \SpecialChar ~
8235 \SpecialChar ~
8236 \SpecialChar ~
8237 \SpecialChar ~
8238 \SpecialChar ~
8239  sdcdb-next-from-src\SpecialChar ~
8240 \SpecialChar ~
8241 \SpecialChar ~
8242 \SpecialChar ~
8243 \SpecialChar ~
8244 \SpecialChar ~
8245 \SpecialChar ~
8246 \SpecialChar ~
8247 \SpecialChar ~
8248 \SpecialChar ~
8249 SDCDB next command 
8250 \newline 
8251 ;; b\SpecialChar ~
8252 \SpecialChar ~
8253 \SpecialChar ~
8254 \SpecialChar ~
8255 \SpecialChar ~
8256 \SpecialChar ~
8257 \SpecialChar ~
8258 \SpecialChar ~
8259 \SpecialChar ~
8260 \SpecialChar ~
8261 \SpecialChar ~
8262 \SpecialChar ~
8263 \SpecialChar ~
8264 \SpecialChar ~
8265  sdcdb-back-from-src\SpecialChar ~
8266 \SpecialChar ~
8267 \SpecialChar ~
8268 \SpecialChar ~
8269 \SpecialChar ~
8270 \SpecialChar ~
8271 \SpecialChar ~
8272 \SpecialChar ~
8273 \SpecialChar ~
8274 \SpecialChar ~
8275 SDCDB back command 
8276 \newline 
8277 ;; c\SpecialChar ~
8278 \SpecialChar ~
8279 \SpecialChar ~
8280 \SpecialChar ~
8281 \SpecialChar ~
8282 \SpecialChar ~
8283 \SpecialChar ~
8284 \SpecialChar ~
8285 \SpecialChar ~
8286 \SpecialChar ~
8287 \SpecialChar ~
8288 \SpecialChar ~
8289 \SpecialChar ~
8290 \SpecialChar ~
8291  sdcdb-cont-from-src\SpecialChar ~
8292 \SpecialChar ~
8293 \SpecialChar ~
8294 \SpecialChar ~
8295 \SpecialChar ~
8296 \SpecialChar ~
8297 \SpecialChar ~
8298 \SpecialChar ~
8299 \SpecialChar ~
8300 \SpecialChar ~
8301 SDCDB continue command
8302 \newline 
8303 ;; s\SpecialChar ~
8304 \SpecialChar ~
8305 \SpecialChar ~
8306 \SpecialChar ~
8307 \SpecialChar ~
8308 \SpecialChar ~
8309 \SpecialChar ~
8310 \SpecialChar ~
8311 \SpecialChar ~
8312 \SpecialChar ~
8313 \SpecialChar ~
8314 \SpecialChar ~
8315 \SpecialChar ~
8316 \SpecialChar ~
8317  sdcdb-step-from-src\SpecialChar ~
8318 \SpecialChar ~
8319 \SpecialChar ~
8320 \SpecialChar ~
8321 \SpecialChar ~
8322 \SpecialChar ~
8323 \SpecialChar ~
8324 \SpecialChar ~
8325 \SpecialChar ~
8326 \SpecialChar ~
8327 SDCDB step command 
8328 \newline 
8329 ;; ?\SpecialChar ~
8330 \SpecialChar ~
8331 \SpecialChar ~
8332 \SpecialChar ~
8333 \SpecialChar ~
8334 \SpecialChar ~
8335 \SpecialChar ~
8336 \SpecialChar ~
8337 \SpecialChar ~
8338 \SpecialChar ~
8339 \SpecialChar ~
8340 \SpecialChar ~
8341 \SpecialChar ~
8342 \SpecialChar ~
8343  sdcdb-whatis-c-sexp\SpecialChar ~
8344 \SpecialChar ~
8345 \SpecialChar ~
8346 \SpecialChar ~
8347 \SpecialChar ~
8348 \SpecialChar ~
8349 \SpecialChar ~
8350 \SpecialChar ~
8351 \SpecialChar ~
8352 \SpecialChar ~
8353 SDCDB ptypecommand for data at 
8354 \newline 
8355 ;;\SpecialChar ~
8356 \SpecialChar ~
8357 \SpecialChar ~
8358 \SpecialChar ~
8359 \SpecialChar ~
8360 \SpecialChar ~
8361 \SpecialChar ~
8362 \SpecialChar ~
8363 \SpecialChar ~
8364 \SpecialChar ~
8365 \SpecialChar ~
8366 \SpecialChar ~
8367 \SpecialChar ~
8368 \SpecialChar ~
8369 \SpecialChar ~
8370 \SpecialChar ~
8371 \SpecialChar ~
8372 \SpecialChar ~
8373 \SpecialChar ~
8374 \SpecialChar ~
8375 \SpecialChar ~
8376 \SpecialChar ~
8377 \SpecialChar ~
8378 \SpecialChar ~
8379 \SpecialChar ~
8380 \SpecialChar ~
8381 \SpecialChar ~
8382 \SpecialChar ~
8383 \SpecialChar ~
8384 \SpecialChar ~
8385 \SpecialChar ~
8386 \SpecialChar ~
8387 \SpecialChar ~
8388 \SpecialChar ~
8389 \SpecialChar ~
8390 \SpecialChar ~
8391 \SpecialChar ~
8392 \SpecialChar ~
8393 \SpecialChar ~
8394 \SpecialChar ~
8395 \SpecialChar ~
8396 \SpecialChar ~
8397 \SpecialChar ~
8398 \SpecialChar ~
8399 \SpecialChar ~
8400 \SpecialChar ~
8401  buffer point 
8402 \newline 
8403 ;; x\SpecialChar ~
8404 \SpecialChar ~
8405 \SpecialChar ~
8406 \SpecialChar ~
8407 \SpecialChar ~
8408 \SpecialChar ~
8409 \SpecialChar ~
8410 \SpecialChar ~
8411 \SpecialChar ~
8412 \SpecialChar ~
8413 \SpecialChar ~
8414 \SpecialChar ~
8415 \SpecialChar ~
8416 \SpecialChar ~
8417  sdcdbsrc-delete\SpecialChar ~
8418 \SpecialChar ~
8419 \SpecialChar ~
8420 \SpecialChar ~
8421 \SpecialChar ~
8422 \SpecialChar ~
8423 \SpecialChar ~
8424 \SpecialChar ~
8425 \SpecialChar ~
8426 \SpecialChar ~
8427 \SpecialChar ~
8428 \SpecialChar ~
8429 \SpecialChar ~
8430 \SpecialChar ~
8431 SDCDB Delete all breakpoints if no arg 
8432 \newline 
8433 ;;\SpecialChar ~
8434 \SpecialChar ~
8435 \SpecialChar ~
8436 \SpecialChar ~
8437 \SpecialChar ~
8438 \SpecialChar ~
8439 \SpecialChar ~
8440 \SpecialChar ~
8441 \SpecialChar ~
8442 \SpecialChar ~
8443 \SpecialChar ~
8444 \SpecialChar ~
8445 \SpecialChar ~
8446 \SpecialChar ~
8447 \SpecialChar ~
8448 \SpecialChar ~
8449 \SpecialChar ~
8450 \SpecialChar ~
8451 \SpecialChar ~
8452 \SpecialChar ~
8453 \SpecialChar ~
8454 \SpecialChar ~
8455 \SpecialChar ~
8456 \SpecialChar ~
8457 \SpecialChar ~
8458 \SpecialChar ~
8459 \SpecialChar ~
8460 \SpecialChar ~
8461 \SpecialChar ~
8462 \SpecialChar ~
8463 \SpecialChar ~
8464 \SpecialChar ~
8465 \SpecialChar ~
8466 \SpecialChar ~
8467 \SpecialChar ~
8468 \SpecialChar ~
8469 \SpecialChar ~
8470 \SpecialChar ~
8471 \SpecialChar ~
8472 \SpecialChar ~
8473 \SpecialChar ~
8474 \SpecialChar ~
8475 \SpecialChar ~
8476 \SpecialChar ~
8477 \SpecialChar ~
8478 \SpecialChar ~
8479 given or delete arg (C-u arg x) 
8480 \newline 
8481 ;; m\SpecialChar ~
8482 \SpecialChar ~
8483 \SpecialChar ~
8484 \SpecialChar ~
8485 \SpecialChar ~
8486 \SpecialChar ~
8487 \SpecialChar ~
8488 \SpecialChar ~
8489 \SpecialChar ~
8490 \SpecialChar ~
8491 \SpecialChar ~
8492 \SpecialChar ~
8493 \SpecialChar ~
8494 \SpecialChar ~
8495  sdcdbsrc-frame\SpecialChar ~
8496 \SpecialChar ~
8497 \SpecialChar ~
8498 \SpecialChar ~
8499 \SpecialChar ~
8500 \SpecialChar ~
8501 \SpecialChar ~
8502 \SpecialChar ~
8503 \SpecialChar ~
8504 \SpecialChar ~
8505 \SpecialChar ~
8506 \SpecialChar ~
8507 \SpecialChar ~
8508 \SpecialChar ~
8509 \SpecialChar ~
8510 SDCDB Display current frame if no arg, 
8511 \newline 
8512 ;;\SpecialChar ~
8513 \SpecialChar ~
8514 \SpecialChar ~
8515 \SpecialChar ~
8516 \SpecialChar ~
8517 \SpecialChar ~
8518 \SpecialChar ~
8519 \SpecialChar ~
8520 \SpecialChar ~
8521 \SpecialChar ~
8522 \SpecialChar ~
8523 \SpecialChar ~
8524 \SpecialChar ~
8525 \SpecialChar ~
8526 \SpecialChar ~
8527 \SpecialChar ~
8528 \SpecialChar ~
8529 \SpecialChar ~
8530 \SpecialChar ~
8531 \SpecialChar ~
8532 \SpecialChar ~
8533 \SpecialChar ~
8534 \SpecialChar ~
8535 \SpecialChar ~
8536 \SpecialChar ~
8537 \SpecialChar ~
8538 \SpecialChar ~
8539 \SpecialChar ~
8540 \SpecialChar ~
8541 \SpecialChar ~
8542 \SpecialChar ~
8543 \SpecialChar ~
8544 \SpecialChar ~
8545 \SpecialChar ~
8546 \SpecialChar ~
8547 \SpecialChar ~
8548 \SpecialChar ~
8549 \SpecialChar ~
8550 \SpecialChar ~
8551 \SpecialChar ~
8552 \SpecialChar ~
8553 \SpecialChar ~
8554 \SpecialChar ~
8555 \SpecialChar ~
8556 \SpecialChar ~
8557 \SpecialChar ~
8558 \SpecialChar ~
8559 given or display frame arg 
8560 \newline 
8561 ;;\SpecialChar ~
8562 \SpecialChar ~
8563 \SpecialChar ~
8564 \SpecialChar ~
8565 \SpecialChar ~
8566 \SpecialChar ~
8567 \SpecialChar ~
8568 \SpecialChar ~
8569 \SpecialChar ~
8570 \SpecialChar ~
8571 \SpecialChar ~
8572 \SpecialChar ~
8573 \SpecialChar ~
8574 \SpecialChar ~
8575 \SpecialChar ~
8576 \SpecialChar ~
8577 \SpecialChar ~
8578 \SpecialChar ~
8579 \SpecialChar ~
8580 \SpecialChar ~
8581 \SpecialChar ~
8582 \SpecialChar ~
8583 \SpecialChar ~
8584 \SpecialChar ~
8585 \SpecialChar ~
8586 \SpecialChar ~
8587 \SpecialChar ~
8588 \SpecialChar ~
8589 \SpecialChar ~
8590 \SpecialChar ~
8591 \SpecialChar ~
8592 \SpecialChar ~
8593 \SpecialChar ~
8594 \SpecialChar ~
8595 \SpecialChar ~
8596 \SpecialChar ~
8597 \SpecialChar ~
8598 \SpecialChar ~
8599 \SpecialChar ~
8600 \SpecialChar ~
8601 \SpecialChar ~
8602 \SpecialChar ~
8603 \SpecialChar ~
8604 \SpecialChar ~
8605 \SpecialChar ~
8606 \SpecialChar ~
8607 \SpecialChar ~
8608 buffer point 
8609 \newline 
8610 ;; !\SpecialChar ~
8611 \SpecialChar ~
8612 \SpecialChar ~
8613 \SpecialChar ~
8614 \SpecialChar ~
8615 \SpecialChar ~
8616 \SpecialChar ~
8617 \SpecialChar ~
8618 \SpecialChar ~
8619 \SpecialChar ~
8620 \SpecialChar ~
8621 \SpecialChar ~
8622 \SpecialChar ~
8623 \SpecialChar ~
8624  sdcdbsrc-goto-sdcdb\SpecialChar ~
8625 \SpecialChar ~
8626 \SpecialChar ~
8627 \SpecialChar ~
8628 \SpecialChar ~
8629 \SpecialChar ~
8630 \SpecialChar ~
8631 \SpecialChar ~
8632 \SpecialChar ~
8633 \SpecialChar ~
8634 Goto the SDCDB output buffer 
8635 \newline 
8636 ;; p\SpecialChar ~
8637 \SpecialChar ~
8638 \SpecialChar ~
8639 \SpecialChar ~
8640 \SpecialChar ~
8641 \SpecialChar ~
8642 \SpecialChar ~
8643 \SpecialChar ~
8644 \SpecialChar ~
8645 \SpecialChar ~
8646 \SpecialChar ~
8647 \SpecialChar ~
8648 \SpecialChar ~
8649 \SpecialChar ~
8650  sdcdb-print-c-sexp\SpecialChar ~
8651 \SpecialChar ~
8652 \SpecialChar ~
8653 \SpecialChar ~
8654 \SpecialChar ~
8655 \SpecialChar ~
8656 \SpecialChar ~
8657 \SpecialChar ~
8658 \SpecialChar ~
8659 \SpecialChar ~
8660 \SpecialChar ~
8661 SDCDB print command for data at 
8662 \newline 
8663 ;;\SpecialChar ~
8664 \SpecialChar ~
8665 \SpecialChar ~
8666 \SpecialChar ~
8667 \SpecialChar ~
8668 \SpecialChar ~
8669 \SpecialChar ~
8670 \SpecialChar ~
8671 \SpecialChar ~
8672 \SpecialChar ~
8673 \SpecialChar ~
8674 \SpecialChar ~
8675 \SpecialChar ~
8676 \SpecialChar ~
8677 \SpecialChar ~
8678 \SpecialChar ~
8679 \SpecialChar ~
8680 \SpecialChar ~
8681 \SpecialChar ~
8682 \SpecialChar ~
8683 \SpecialChar ~
8684 \SpecialChar ~
8685 \SpecialChar ~
8686 \SpecialChar ~
8687 \SpecialChar ~
8688 \SpecialChar ~
8689 \SpecialChar ~
8690 \SpecialChar ~
8691 \SpecialChar ~
8692 \SpecialChar ~
8693 \SpecialChar ~
8694 \SpecialChar ~
8695 \SpecialChar ~
8696 \SpecialChar ~
8697 \SpecialChar ~
8698 \SpecialChar ~
8699 \SpecialChar ~
8700 \SpecialChar ~
8701 \SpecialChar ~
8702 \SpecialChar ~
8703 \SpecialChar ~
8704 \SpecialChar ~
8705 \SpecialChar ~
8706 \SpecialChar ~
8707 \SpecialChar ~
8708 \SpecialChar ~
8709  buffer point 
8710 \newline 
8711 ;; g\SpecialChar ~
8712 \SpecialChar ~
8713 \SpecialChar ~
8714 \SpecialChar ~
8715 \SpecialChar ~
8716 \SpecialChar ~
8717 \SpecialChar ~
8718 \SpecialChar ~
8719 \SpecialChar ~
8720 \SpecialChar ~
8721 \SpecialChar ~
8722 \SpecialChar ~
8723 \SpecialChar ~
8724 \SpecialChar ~
8725  sdcdbsrc-goto-sdcdb\SpecialChar ~
8726 \SpecialChar ~
8727 \SpecialChar ~
8728 \SpecialChar ~
8729 \SpecialChar ~
8730 \SpecialChar ~
8731 \SpecialChar ~
8732 \SpecialChar ~
8733 \SpecialChar ~
8734 \SpecialChar ~
8735 Goto the SDCDB output buffer 
8736 \newline 
8737 ;; t\SpecialChar ~
8738 \SpecialChar ~
8739 \SpecialChar ~
8740 \SpecialChar ~
8741 \SpecialChar ~
8742 \SpecialChar ~
8743 \SpecialChar ~
8744 \SpecialChar ~
8745 \SpecialChar ~
8746 \SpecialChar ~
8747 \SpecialChar ~
8748 \SpecialChar ~
8749 \SpecialChar ~
8750 \SpecialChar ~
8751  sdcdbsrc-mode\SpecialChar ~
8752 \SpecialChar ~
8753 \SpecialChar ~
8754 \SpecialChar ~
8755 \SpecialChar ~
8756 \SpecialChar ~
8757 \SpecialChar ~
8758 \SpecialChar ~
8759 \SpecialChar ~
8760 \SpecialChar ~
8761 \SpecialChar ~
8762 \SpecialChar ~
8763 \SpecialChar ~
8764 \SpecialChar ~
8765 \SpecialChar ~
8766 \SpecialChar ~
8767 Toggles Sdcdbsrc mode (turns it off) 
8768 \newline 
8769 ;; 
8770 \newline 
8771 ;; C-c C-f\SpecialChar ~
8772 \SpecialChar ~
8773 \SpecialChar ~
8774 \SpecialChar ~
8775 \SpecialChar ~
8776 \SpecialChar ~
8777 \SpecialChar ~
8778 \SpecialChar ~
8779  sdcdb-finish-from-src\SpecialChar ~
8780 \SpecialChar ~
8781 \SpecialChar ~
8782 \SpecialChar ~
8783 \SpecialChar ~
8784 \SpecialChar ~
8785 \SpecialChar ~
8786 \SpecialChar ~
8787 SDCDB finish command 
8788 \newline 
8789 ;; 
8790 \newline 
8791 ;; C-x SPC\SpecialChar ~
8792 \SpecialChar ~
8793 \SpecialChar ~
8794 \SpecialChar ~
8795 \SpecialChar ~
8796 \SpecialChar ~
8797 \SpecialChar ~
8798 \SpecialChar ~
8799  sdcdb-break\SpecialChar ~
8800 \SpecialChar ~
8801 \SpecialChar ~
8802 \SpecialChar ~
8803 \SpecialChar ~
8804 \SpecialChar ~
8805 \SpecialChar ~
8806 \SpecialChar ~
8807 \SpecialChar ~
8808 \SpecialChar ~
8809 \SpecialChar ~
8810 \SpecialChar ~
8811 \SpecialChar ~
8812 \SpecialChar ~
8813 \SpecialChar ~
8814 \SpecialChar ~
8815 \SpecialChar ~
8816 \SpecialChar ~
8817 Set break for line with point 
8818 \newline 
8819 ;; ESC t\SpecialChar ~
8820 \SpecialChar ~
8821 \SpecialChar ~
8822 \SpecialChar ~
8823 \SpecialChar ~
8824 \SpecialChar ~
8825 \SpecialChar ~
8826 \SpecialChar ~
8827 \SpecialChar ~
8828 \SpecialChar ~
8829  sdcdbsrc-mode\SpecialChar ~
8830 \SpecialChar ~
8831 \SpecialChar ~
8832 \SpecialChar ~
8833 \SpecialChar ~
8834 \SpecialChar ~
8835 \SpecialChar ~
8836 \SpecialChar ~
8837 \SpecialChar ~
8838 \SpecialChar ~
8839 \SpecialChar ~
8840 \SpecialChar ~
8841 \SpecialChar ~
8842 \SpecialChar ~
8843 \SpecialChar ~
8844 \SpecialChar ~
8845 Toggle Sdcdbsrc mode 
8846 \newline 
8847 ;; ESC m\SpecialChar ~
8848 \SpecialChar ~
8849 \SpecialChar ~
8850 \SpecialChar ~
8851 \SpecialChar ~
8852 \SpecialChar ~
8853 \SpecialChar ~
8854 \SpecialChar ~
8855 \SpecialChar ~
8856 \SpecialChar ~
8857  sdcdbsrc-srcmode\SpecialChar ~
8858 \SpecialChar ~
8859 \SpecialChar ~
8860 \SpecialChar ~
8861 \SpecialChar ~
8862 \SpecialChar ~
8863 \SpecialChar ~
8864 \SpecialChar ~
8865 \SpecialChar ~
8866 \SpecialChar ~
8867 \SpecialChar ~
8868 \SpecialChar ~
8869  Toggle list mode 
8870 \newline 
8871 ;; 
8872 \family default 
8873
8874 \newline 
8875
8876 \layout Section
8877
8878 Other Processors
8879 \layout Subsection
8880
8881 The Z80 and gbz80 port
8882 \layout Standard
8883
8884 SDCC can target both the Zilog Z80 and the Nintendo Gameboy's Z80-like gbz80.
8885  The port is incomplete - long support is incomplete (mul, div and mod are
8886  unimplimented), and both float and bitfield support is missing.
8887  Apart from that the code generated is correct.
8888 \layout Standard
8889
8890 As always, the code is the authoritave reference - see z80/ralloc.c and z80/gen.c.
8891  The stack frame is similar to that generated by the IAR Z80 compiler.
8892  IX is used as the base pointer, HL is used as a temporary register, and
8893  BC and DE are available for holding varibles.
8894  IY is currently unusued.
8895  Return values are stored in HL.
8896  One bad side effect of using IX as the base pointer is that a functions
8897  stack frame is limited to 127 bytes - this will be fixed in a later version.
8898 \layout Section
8899
8900 Support
8901 \layout Standard
8902
8903 SDCC has grown to be a large project.
8904  The compiler alone (without the preprocessor, assembler and linker) is
8905  about 40,000 lines of code (blank stripped).
8906  The open source nature of this project is a key to its continued growth
8907  and support.
8908  You gain the benefit and support of many active software developers and
8909  end users.
8910  Is SDCC perfect? No, that's why we need your help.
8911  The developers take pride in fixing reported bugs.
8912  You can help by reporting the bugs and helping other SDCC users.
8913  There are lots of ways to contribute, and we encourage you to take part
8914  in making SDCC a great software package.
8915 \layout Subsection
8916
8917 Reporting Bugs
8918 \layout Standard
8919
8920 Send an email to the mailing list at 'user-sdcc@sdcc.sourceforge.net' or 'devel-sd
8921 cc@sdcc.sourceforge.net'.
8922  Bugs will be fixed ASAP.
8923  When reporting a bug, it is very useful to include a small test program
8924  which reproduces the problem.
8925  If you can isolate the problem by looking at the generated assembly code,
8926  this can be very helpful.
8927  Compiling your program with the ---dumpall option can sometimes be useful
8928  in locating optimization problems.
8929 \layout Section
8930
8931 Compiler internals
8932 \layout Subsection
8933
8934 The anatomy of the compiler
8935 \layout Standard
8936
8937
8938 \shape italic 
8939 This is an excerpt from an atricle published in Circuit Cellar MagaZine
8940  in august 2000.
8941  It's a little outdated (the compiler is much more efficient now and user/devell
8942 oper friendly), but pretty well exposes the guts of it all.
8943 \shape default 
8944
8945 \newline 
8946
8947 \newline 
8948 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
8949  It is fairly easy to retarget for other 8-bit MCU.
8950  Here we take a look at some of the internals of the compiler.
8951  
8952 \layout Paragraph*
8953
8954 Parsing 
8955 \layout Standard
8956
8957 Parsing the input source file and creating an AST (Annotated Syntax Tree).
8958  This phase also involves propagating types (annotating each node of the
8959  parse tree with type information) and semantic analysis.
8960  There are some MCU specific parsing rules.
8961  For example the storage classes, the extended storage classes are MCU specific
8962  while there may be a xdata storage class for 8051 there is no such storage
8963  class for z80 or Atmel AVR.
8964  SDCC allows MCU specific storage class extensions, i.e.
8965  xdata will be treated as a storage class specifier when parsing 8051 C
8966  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
8967  C code.
8968 \layout Paragraph*
8969
8970 Generating iCode
8971 \layout Standard
8972
8973 Intermediate code generation.
8974  In this phase the AST is broken down into three-operand form (iCode).
8975  These three operand forms are represented as doubly linked lists.
8976  ICode is the term given to the intermediate form generated by the compiler.
8977  ICode example section shows some examples of iCode generated for some simple
8978  C source functions.
8979 \layout Paragraph*
8980
8981 Optimizations.
8982 \layout Standard
8983
8984 Bulk of the target independent optimizations is performed in this phase.
8985  The optimizations include constant propagation, common sub-expression eliminati
8986 on, loop invariant code movement, strength reduction of loop induction variables
8987  and dead-code elimination.
8988 \layout Paragraph*
8989
8990 Live range analysis
8991 \layout Standard
8992
8993 During intermediate code generation phase, the compiler assumes the target
8994  machine has infinite number of registers and generates a lot of temporary
8995  variables.
8996  The live range computation determines the lifetime of each of these compiler-ge
8997 nerated temporaries.
8998  A picture speaks a thousand words.
8999  ICode example sections show the live range annotations for each of the
9000  operand.
9001  It is important to note here, each iCode is assigned a number in the order
9002  of its execution in the function.
9003  The live ranges are computed in terms of these numbers.
9004  The from number is the number of the iCode which first defines the operand
9005  and the to number signifies the iCode which uses this operand last.
9006 \layout Paragraph*
9007
9008 Register Allocation
9009 \layout Standard
9010
9011 The register allocation determines the type and number of registers needed
9012  by each operand.
9013  In most MCUs only a few registers can be used for indirect addressing.
9014  In case of 8051 for example the registers R0 & R1 can be used to indirectly
9015  address the internal ram and DPTR to indirectly address the external ram.
9016  The compiler will try to allocate the appropriate register to pointer variables
9017  if it can.
9018  ICode example section shows the operands annotated with the registers assigned
9019  to them.
9020  The compiler will try to keep operands in registers as much as possible;
9021  there are several schemes the compiler uses to do achieve this.
9022  When the compiler runs out of registers the compiler will check to see
9023  if there are any live operands which is not used or defined in the current
9024  basic block being processed, if there are any found then it will push that
9025  operand and use the registers in this block, the operand will then be popped
9026  at the end of the basic block.
9027  
9028 \layout Standard
9029
9030 There are other MCU specific considerations in this phase.
9031  Some MCUs have an accumulator; very short-lived operands could be assigned
9032  to the accumulator instead of general-purpose register.
9033 \layout Paragraph*
9034
9035 Code generation
9036 \layout Standard
9037
9038 Figure II gives a table of iCode operations supported by the compiler.
9039  The code generation involves translating these operations into corresponding
9040  assembly code for the processor.
9041  This sounds overly simple but that is the essence of code generation.
9042  Some of the iCode operations are generated on a MCU specific manner for
9043  example, the z80 port does not use registers to pass parameters so the
9044  SEND and RECV iCode operations will not be generated, and it also does
9045  not support JUMPTABLES.
9046  
9047 \newline 
9048
9049 \series bold 
9050 \shape italic 
9051 \color red
9052 <Where is Figure II ?>
9053 \layout Paragraph*
9054
9055 ICode Example
9056 \layout Standard
9057
9058 This section shows some details of iCode.
9059  The example C code does not do anything useful; it is used as an example
9060  to illustrate the intermediate code generated by the compiler.
9061 \newline 
9062
9063 \newline 
9064
9065 \family typewriter 
9066 1.\SpecialChar ~
9067 xdata int * p;
9068 \newline 
9069 2.\SpecialChar ~
9070 int gint;
9071 \newline 
9072 3.\SpecialChar ~
9073 /* This function does nothing useful.
9074  It is used
9075 \newline 
9076 4.\SpecialChar ~
9077 \SpecialChar ~
9078 \SpecialChar ~
9079 \SpecialChar ~
9080 for the purpose of explaining iCode */
9081 \newline 
9082 5.\SpecialChar ~
9083 short function (data int *x)
9084 \newline 
9085 6.\SpecialChar ~
9086 {
9087 \newline 
9088 7.\SpecialChar ~
9089 \SpecialChar ~
9090 \SpecialChar ~
9091 short i=10; /* dead initialization eliminated */
9092 \newline 
9093 8.\SpecialChar ~
9094 \SpecialChar ~
9095 \SpecialChar ~
9096 short sum=10; /* dead initialization eliminated */
9097 \newline 
9098 9.\SpecialChar ~
9099 \SpecialChar ~
9100 \SpecialChar ~
9101 short mul;
9102 \newline 
9103 10.\SpecialChar ~
9104 \SpecialChar ~
9105 int j ;
9106 \newline 
9107 11.\SpecialChar ~
9108 \SpecialChar ~
9109 while (*x) *x++ = *p++; 
9110 \newline 
9111 12.\SpecialChar ~
9112 \SpecialChar ~
9113 \SpecialChar ~
9114 \SpecialChar ~
9115 sum = 0 ; 
9116 \newline 
9117 13.\SpecialChar ~
9118 \SpecialChar ~
9119 mul = 0;
9120 \newline 
9121 14.\SpecialChar ~
9122 \SpecialChar ~
9123 /* compiler detects i,j to be induction variables */
9124 \newline 
9125 15.\SpecialChar ~
9126 \SpecialChar ~
9127 for (i = 0, j = 10 ; i < 10 ; i++, j---) {
9128 \newline 
9129 16.\SpecialChar ~
9130 \SpecialChar ~
9131 \SpecialChar ~
9132 \SpecialChar ~
9133 sum += i;
9134 \newline 
9135 17.\SpecialChar ~
9136 \SpecialChar ~
9137 \SpecialChar ~
9138 \SpecialChar ~
9139 mul += i * 3; /* this multiplication remains */
9140 \newline 
9141 18.\SpecialChar ~
9142 \SpecialChar ~
9143 \SpecialChar ~
9144 \SpecialChar ~
9145 gint += j * 3;/* this multiplication changed to addition */
9146 \newline 
9147 19.\SpecialChar ~
9148 \SpecialChar ~
9149 }
9150 \newline 
9151 20.\SpecialChar ~
9152 \SpecialChar ~
9153 return sum+mul;
9154 \newline 
9155 21.\SpecialChar ~
9156 }
9157 \newline 
9158
9159 \newline 
9160
9161 \family default 
9162 In addition to the operands each iCode contains information about the filename
9163  and line it corresponds to in the source file.
9164  The first field in the listing should be interpreted as follows:
9165 \newline 
9166
9167 \shape italic 
9168 \size footnotesize 
9169 Filename(linenumber: iCode Execution sequence number : ICode hash table
9170  key : loop depth of the iCode).
9171 \shape default 
9172 \size default 
9173
9174 \newline 
9175 Then follows the human readable form of the ICode operation.
9176  Each operand of this triplet form can be of three basic types a) compiler
9177  generated temporary b) user defined variable c) a constant value.
9178  Note that local variables and parameters are replaced by compiler generated
9179  temporaries.
9180  Live ranges are computed only for temporaries (i.e.
9181  live ranges are not computed for global variables).
9182  Registers are allocated for temporaries only.
9183  Operands are formatted in the following manner:
9184 \newline 
9185
9186 \shape italic 
9187 \size footnotesize 
9188 Operand Name [lr live-from : live-to ] { type information } [ registers
9189  allocated ].
9190 \shape default 
9191 \size default 
9192
9193 \newline 
9194 As mentioned earlier the live ranges are computed in terms of the execution
9195  sequence number of the iCodes, for example 
9196 \newline 
9197 the iTemp0 is live from (i.e.
9198  first defined in iCode with execution sequence number 3, and is last used
9199  in the iCode with sequence number 5).
9200  For induction variables such as iTemp21 the live range computation extends
9201  the lifetime from the start to the end of the loop.
9202 \newline 
9203 The register allocator used the live range information to allocate registers,
9204  the same registers may be used for different temporaries if their live
9205  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
9206  iTemp17 since their live ranges do not overlap.
9207  In addition the allocator also takes into consideration the type and usage
9208  of a temporary, for example itemp6 is a pointer to near space and is used
9209  as to fetch data from (i.e.
9210  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer registers (r0).
9211  Some short lived temporaries are allocated to special registers which have
9212  meaning to the code generator e.g.
9213  iTemp13 is allocated to a pseudo register CC which tells the back end that
9214  the temporary is used only for a conditional jump the code generation makes
9215  use of this information to optimize a compare and jump ICode.
9216 \newline 
9217 There are several loop optimizations performed by the compiler.
9218  It can detect induction variables iTemp21(i) and iTemp23(j).
9219  Also note the compiler does selective strength reduction, i.e.
9220  the multiplication of an induction variable in line 18 (gint = j * 3) is
9221  changed to addition, a new temporary iTemp17 is allocated and assigned
9222  a initial value, a constant 3 is then added for each iteration of the loop.
9223  The compiler does not change the multiplication in line 17 however since
9224  the processor does support an 8 * 8 bit multiplication.
9225 \newline 
9226 Note the dead code elimination optimization eliminated the dead assignments
9227  in line 7 & 8 to I and sum respectively.
9228 \newline 
9229
9230 \layout Standard
9231
9232
9233 \size footnotesize 
9234 Sample.c (5:1:0:0) _entry($9) :
9235 \layout Standard
9236
9237
9238 \size footnotesize 
9239 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
9240 \layout Standard
9241
9242
9243 \size footnotesize 
9244 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv 
9245 \layout Standard
9246
9247
9248 \size footnotesize 
9249 Sample.c(11:4:53:0) preHeaderLbl0($11) :
9250 \layout Standard
9251
9252
9253 \size footnotesize 
9254 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
9255  * int}[r2]
9256 \layout Standard
9257
9258
9259 \size footnotesize 
9260 Sample.c(11:6:5:1) _whilecontinue_0($1) :
9261 \layout Standard
9262
9263
9264 \size footnotesize 
9265 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
9266  int}[r0]]
9267 \layout Standard
9268
9269
9270 \size footnotesize 
9271 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
9272 \layout Standard
9273
9274
9275 \size footnotesize 
9276 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
9277  * int}
9278 \layout Standard
9279
9280
9281 \size footnotesize 
9282 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
9283  {short}
9284 \layout Standard
9285
9286
9287 \size footnotesize 
9288 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
9289  * int}[DPTR]]
9290 \layout Standard
9291
9292
9293 \size footnotesize 
9294 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
9295 }[r2 r3]
9296 \layout Standard
9297
9298
9299 \size footnotesize 
9300 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
9301  * int}[r0] + 0x2 {short}
9302 \layout Standard
9303
9304
9305 \size footnotesize 
9306 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
9307 \layout Standard
9308
9309
9310 \size footnotesize 
9311 Sample.c(11:17:21:0)_whilebreak_0($3) :
9312 \layout Standard
9313
9314
9315 \size footnotesize 
9316 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
9317 \layout Standard
9318
9319
9320 \size footnotesize 
9321 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
9322 \layout Standard
9323
9324
9325 \size footnotesize 
9326 Sample.c(15:20:54:0)preHeaderLbl1($13) :
9327 \layout Standard
9328
9329
9330 \size footnotesize 
9331 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
9332 \layout Standard
9333
9334
9335 \size footnotesize 
9336 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
9337 \layout Standard
9338
9339
9340 \size footnotesize 
9341 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
9342 \layout Standard
9343
9344
9345 \size footnotesize 
9346 Sample.c(15:24:26:1)_forcond_0($4) :
9347 \layout Standard
9348
9349
9350 \size footnotesize 
9351 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
9352  < 0xa {short}
9353 \layout Standard
9354
9355
9356 \size footnotesize 
9357 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
9358 \layout Standard
9359
9360
9361 \size footnotesize 
9362 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
9363  + ITemp21 [lr21:38]{short}[r4]
9364 \layout Standard
9365
9366
9367 \size footnotesize 
9368 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
9369  * 0x3 {short}
9370 \layout Standard
9371
9372
9373 \size footnotesize 
9374 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
9375  + iTemp15 [lr29:30]{short}[r1]
9376 \layout Standard
9377
9378
9379 \size footnotesize 
9380 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
9381  r0]- 0x3 {short}
9382 \layout Standard
9383
9384
9385 \size footnotesize 
9386 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
9387 int}[r7 r0]
9388 \layout Standard
9389
9390
9391 \size footnotesize 
9392 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
9393  + 0x1 {short}
9394 \layout Standard
9395
9396
9397 \size footnotesize 
9398 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
9399  r6]- 0x1 {short}
9400 \layout Standard
9401
9402
9403 \size footnotesize 
9404 Sample.c(19:38:47:1) goto _forcond_0($4)
9405 \layout Standard
9406
9407
9408 \size footnotesize 
9409 Sample.c(19:39:48:0)_forbreak_0($7) :
9410 \layout Standard
9411
9412
9413 \size footnotesize 
9414 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
9415  + ITemp11 [lr19:40]{short}[r3]
9416 \layout Standard
9417
9418
9419 \size footnotesize 
9420 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
9421 \layout Standard
9422
9423
9424 \size footnotesize 
9425 Sample.c(20:42:51:0)_return($8) :
9426 \layout Standard
9427
9428
9429 \size footnotesize 
9430 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
9431 \size default 
9432
9433 \newline 
9434
9435 \newline 
9436 Finally the code generated for this function:
9437 \newline 
9438
9439 \layout Standard
9440
9441
9442 \size footnotesize 
9443 .area DSEG (DATA)
9444 \layout Standard
9445
9446
9447 \size footnotesize 
9448 _p::
9449 \layout Standard
9450
9451
9452 \size footnotesize 
9453 \SpecialChar ~
9454 \SpecialChar ~
9455 .ds 2
9456 \layout Standard
9457
9458
9459 \size footnotesize 
9460 _gint::
9461 \layout Standard
9462
9463
9464 \size footnotesize 
9465 \SpecialChar ~
9466 \SpecialChar ~
9467 .ds 2
9468 \layout Standard
9469
9470
9471 \size footnotesize 
9472 ; sample.c 5
9473 \layout Standard
9474
9475
9476 \size footnotesize 
9477 ; ----------------------------------------------
9478 \layout Standard
9479
9480
9481 \size footnotesize 
9482 ; function function
9483 \layout Standard
9484
9485
9486 \size footnotesize 
9487 ; ----------------------------------------------
9488 \layout Standard
9489
9490
9491 \size footnotesize 
9492 _function:
9493 \layout Standard
9494
9495
9496 \size footnotesize 
9497 ; iTemp0 [lr3:5]{_near * int}[r2] = recv 
9498 \layout Standard
9499
9500
9501 \size footnotesize 
9502 \SpecialChar ~
9503 \SpecialChar ~
9504 mov r2,dpl
9505 \layout Standard
9506
9507
9508 \size footnotesize 
9509 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
9510 \layout Standard
9511
9512
9513 \size footnotesize 
9514 \SpecialChar ~
9515 \SpecialChar ~
9516 mov ar0,r2
9517 \layout Standard
9518
9519
9520 \size footnotesize 
9521 ;_whilecontinue_0($1) :
9522 \layout Standard
9523
9524
9525 \size footnotesize 
9526 00101$:
9527 \layout Standard
9528
9529
9530 \size footnotesize 
9531 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
9532 \layout Standard
9533
9534
9535 \size footnotesize 
9536 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
9537 \layout Standard
9538
9539
9540 \size footnotesize 
9541 \SpecialChar ~
9542 \SpecialChar ~
9543 mov ar2,@r0
9544 \layout Standard
9545
9546
9547 \size footnotesize 
9548 \SpecialChar ~
9549 \SpecialChar ~
9550 inc r0
9551 \layout Standard
9552
9553
9554 \size footnotesize 
9555 \SpecialChar ~
9556 \SpecialChar ~
9557 mov ar3,@r0
9558 \layout Standard
9559
9560
9561 \size footnotesize 
9562 \SpecialChar ~
9563 \SpecialChar ~
9564 dec r0
9565 \layout Standard
9566
9567
9568 \size footnotesize 
9569 \SpecialChar ~
9570 \SpecialChar ~
9571 mov a,r2
9572 \layout Standard
9573
9574
9575 \size footnotesize 
9576 \SpecialChar ~
9577 \SpecialChar ~
9578 orl a,r3
9579 \layout Standard
9580
9581
9582 \size footnotesize 
9583 \SpecialChar ~
9584 \SpecialChar ~
9585 jz 00103$
9586 \layout Standard
9587
9588
9589 \size footnotesize 
9590 00114$:
9591 \layout Standard
9592
9593
9594 \size footnotesize 
9595 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
9596 \layout Standard
9597
9598
9599 \size footnotesize 
9600 \SpecialChar ~
9601 \SpecialChar ~
9602 mov dpl,_p
9603 \layout Standard
9604
9605
9606 \size footnotesize 
9607 \SpecialChar ~
9608 \SpecialChar ~
9609 mov dph,(_p + 1)
9610 \layout Standard
9611
9612
9613 \size footnotesize 
9614 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
9615 \layout Standard
9616
9617
9618 \size footnotesize 
9619 \SpecialChar ~
9620 \SpecialChar ~
9621 mov a,#0x02
9622 \layout Standard
9623
9624
9625 \size footnotesize 
9626 \SpecialChar ~
9627 \SpecialChar ~
9628 add a,_p
9629 \layout Standard
9630
9631
9632 \size footnotesize 
9633 \SpecialChar ~
9634 \SpecialChar ~
9635 mov _p,a
9636 \layout Standard
9637
9638
9639 \size footnotesize 
9640 \SpecialChar ~
9641 \SpecialChar ~
9642 clr a
9643 \layout Standard
9644
9645
9646 \size footnotesize 
9647 \SpecialChar ~
9648 \SpecialChar ~
9649 addc a,(_p + 1)
9650 \layout Standard
9651
9652
9653 \size footnotesize 
9654 \SpecialChar ~
9655 \SpecialChar ~
9656 mov (_p + 1),a
9657 \layout Standard
9658
9659
9660 \size footnotesize 
9661 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
9662 \layout Standard
9663
9664
9665 \size footnotesize 
9666 \SpecialChar ~
9667 \SpecialChar ~
9668 movx a,@dptr
9669 \layout Standard
9670
9671
9672 \size footnotesize 
9673 \SpecialChar ~
9674 \SpecialChar ~
9675 mov r2,a
9676 \layout Standard
9677
9678
9679 \size footnotesize 
9680 \SpecialChar ~
9681 \SpecialChar ~
9682 inc dptr
9683 \layout Standard
9684
9685
9686 \size footnotesize 
9687 \SpecialChar ~
9688 \SpecialChar ~
9689 movx a,@dptr
9690 \layout Standard
9691
9692
9693 \size footnotesize 
9694 \SpecialChar ~
9695 \SpecialChar ~
9696 mov r3,a
9697 \layout Standard
9698
9699
9700 \size footnotesize 
9701 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
9702 \layout Standard
9703
9704
9705 \size footnotesize 
9706 \SpecialChar ~
9707 \SpecialChar ~
9708 mov @r0,ar2
9709 \layout Standard
9710
9711
9712 \size footnotesize 
9713 \SpecialChar ~
9714 \SpecialChar ~
9715 inc r0
9716 \layout Standard
9717
9718
9719 \size footnotesize 
9720 \SpecialChar ~
9721 \SpecialChar ~
9722 mov @r0,ar3
9723 \layout Standard
9724
9725
9726 \size footnotesize 
9727 ; iTemp6 [lr5:16]{_near * int}[r0] = 
9728 \layout Standard
9729
9730
9731 \size footnotesize 
9732 ; iTemp6 [lr5:16]{_near * int}[r0] + 
9733 \layout Standard
9734
9735
9736 \size footnotesize 
9737 ; 0x2 {short}
9738 \layout Standard
9739
9740
9741 \size footnotesize 
9742 \SpecialChar ~
9743 \SpecialChar ~
9744 inc r0
9745 \layout Standard
9746
9747
9748 \size footnotesize 
9749 ; goto _whilecontinue_0($1)
9750 \layout Standard
9751
9752
9753 \size footnotesize 
9754 \SpecialChar ~
9755 \SpecialChar ~
9756 sjmp 00101$
9757 \layout Standard
9758
9759
9760 \size footnotesize 
9761 ; _whilebreak_0($3) :
9762 \layout Standard
9763
9764
9765 \size footnotesize 
9766 00103$:
9767 \layout Standard
9768
9769
9770 \size footnotesize 
9771 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
9772 \layout Standard
9773
9774
9775 \size footnotesize 
9776 \SpecialChar ~
9777 \SpecialChar ~
9778 mov r2,#0x00
9779 \layout Standard
9780
9781
9782 \size footnotesize 
9783 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
9784 \layout Standard
9785
9786
9787 \size footnotesize 
9788 \SpecialChar ~
9789 \SpecialChar ~
9790 mov r3,#0x00
9791 \layout Standard
9792
9793
9794 \size footnotesize 
9795 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
9796 \layout Standard
9797
9798
9799 \size footnotesize 
9800 \SpecialChar ~
9801 \SpecialChar ~
9802 mov r4,#0x00
9803 \layout Standard
9804
9805
9806 \size footnotesize 
9807 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
9808 \layout Standard
9809
9810
9811 \size footnotesize 
9812 \SpecialChar ~
9813 \SpecialChar ~
9814 mov r5,#0x0A
9815 \layout Standard
9816
9817
9818 \size footnotesize 
9819 \SpecialChar ~
9820 \SpecialChar ~
9821 mov r6,#0x00
9822 \layout Standard
9823
9824
9825 \size footnotesize 
9826 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
9827 \layout Standard
9828
9829
9830 \size footnotesize 
9831 \SpecialChar ~
9832 \SpecialChar ~
9833 mov r7,#0x1E
9834 \layout Standard
9835
9836
9837 \size footnotesize 
9838 \SpecialChar ~
9839 \SpecialChar ~
9840 mov r0,#0x00
9841 \layout Standard
9842
9843
9844 \size footnotesize 
9845 ; _forcond_0($4) :
9846 \layout Standard
9847
9848
9849 \size footnotesize 
9850 00104$:
9851 \layout Standard
9852
9853
9854 \size footnotesize 
9855 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
9856 \layout Standard
9857
9858
9859 \size footnotesize 
9860 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
9861 \layout Standard
9862
9863
9864 \size footnotesize 
9865 \SpecialChar ~
9866 \SpecialChar ~
9867 clr c
9868 \layout Standard
9869
9870
9871 \size footnotesize 
9872 \SpecialChar ~
9873 \SpecialChar ~
9874 mov a,r4
9875 \layout Standard
9876
9877
9878 \size footnotesize 
9879 \SpecialChar ~
9880 \SpecialChar ~
9881 xrl a,#0x80
9882 \layout Standard
9883
9884
9885 \size footnotesize 
9886 \SpecialChar ~
9887 \SpecialChar ~
9888 subb a,#0x8a
9889 \layout Standard
9890
9891
9892 \size footnotesize 
9893 \SpecialChar ~
9894 \SpecialChar ~
9895 jnc 00107$
9896 \layout Standard
9897
9898
9899 \size footnotesize 
9900 00115$:
9901 \layout Standard
9902
9903
9904 \size footnotesize 
9905 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] + 
9906 \layout Standard
9907
9908
9909 \size footnotesize 
9910 ; iTemp21 [lr21:38]{short}[r4]
9911 \layout Standard
9912
9913
9914 \size footnotesize 
9915 \SpecialChar ~
9916 \SpecialChar ~
9917 mov a,r4
9918 \layout Standard
9919
9920
9921 \size footnotesize 
9922 \SpecialChar ~
9923 \SpecialChar ~
9924 add a,r2
9925 \layout Standard
9926
9927
9928 \size footnotesize 
9929 \SpecialChar ~
9930 \SpecialChar ~
9931 mov r2,a
9932 \layout Standard
9933
9934
9935 \size footnotesize 
9936 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
9937 \layout Standard
9938
9939
9940 \size footnotesize 
9941 \SpecialChar ~
9942 \SpecialChar ~
9943 mov b,#0x03
9944 \layout Standard
9945
9946
9947 \size footnotesize 
9948 \SpecialChar ~
9949 \SpecialChar ~
9950 mov a,r4
9951 \layout Standard
9952
9953
9954 \size footnotesize 
9955 \SpecialChar ~
9956 \SpecialChar ~
9957 mul ab
9958 \layout Standard
9959
9960
9961 \size footnotesize 
9962 \SpecialChar ~
9963 \SpecialChar ~
9964 mov r1,a
9965 \layout Standard
9966
9967
9968 \size footnotesize 
9969 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] + 
9970 \layout Standard
9971
9972
9973 \size footnotesize 
9974 ; iTemp15 [lr29:30]{short}[r1]
9975 \layout Standard
9976
9977
9978 \size footnotesize 
9979 \SpecialChar ~
9980 \SpecialChar ~
9981 add a,r3
9982 \layout Standard
9983
9984
9985 \size footnotesize 
9986 \SpecialChar ~
9987 \SpecialChar ~
9988 mov r3,a
9989 \layout Standard
9990
9991
9992 \size footnotesize 
9993 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
9994 \layout Standard
9995
9996
9997 \size footnotesize 
9998 \SpecialChar ~
9999 \SpecialChar ~
10000 mov a,r7
10001 \layout Standard
10002
10003
10004 \size footnotesize 
10005 \SpecialChar ~
10006 \SpecialChar ~
10007 add a,#0xfd
10008 \layout Standard
10009
10010
10011 \size footnotesize 
10012 \SpecialChar ~
10013 \SpecialChar ~
10014 mov r7,a
10015 \layout Standard
10016
10017
10018 \size footnotesize 
10019 \SpecialChar ~
10020 \SpecialChar ~
10021 mov a,r0
10022 \layout Standard
10023
10024
10025 \size footnotesize 
10026 \SpecialChar ~
10027 \SpecialChar ~
10028 addc a,#0xff
10029 \layout Standard
10030
10031
10032 \size footnotesize 
10033 \SpecialChar ~
10034 \SpecialChar ~
10035 mov r0,a
10036 \layout Standard
10037
10038
10039 \size footnotesize 
10040 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
10041 \layout Standard
10042
10043
10044 \size footnotesize 
10045 \SpecialChar ~
10046 \SpecialChar ~
10047 mov a,r7
10048 \layout Standard
10049
10050
10051 \size footnotesize 
10052 \SpecialChar ~
10053 \SpecialChar ~
10054 add a,_gint
10055 \layout Standard
10056
10057
10058 \size footnotesize 
10059 \SpecialChar ~
10060 \SpecialChar ~
10061 mov _gint,a
10062 \layout Standard
10063
10064
10065 \size footnotesize 
10066 \SpecialChar ~
10067 \SpecialChar ~
10068 mov a,r0
10069 \layout Standard
10070
10071
10072 \size footnotesize 
10073 \SpecialChar ~
10074 \SpecialChar ~
10075 addc a,(_gint + 1)
10076 \layout Standard
10077
10078
10079 \size footnotesize 
10080 \SpecialChar ~
10081 \SpecialChar ~
10082 mov (_gint + 1),a
10083 \layout Standard
10084
10085
10086 \size footnotesize 
10087 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
10088 \layout Standard
10089
10090
10091 \size footnotesize 
10092 \SpecialChar ~
10093 \SpecialChar ~
10094 inc r4
10095 \layout Standard
10096
10097
10098 \size footnotesize 
10099 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
10100 \layout Standard
10101
10102
10103 \size footnotesize 
10104 \SpecialChar ~
10105 \SpecialChar ~
10106 dec r5
10107 \layout Standard
10108
10109
10110 \size footnotesize 
10111 \SpecialChar ~
10112 \SpecialChar ~
10113 cjne r5,#0xff,00104$
10114 \layout Standard
10115
10116
10117 \size footnotesize 
10118 \SpecialChar ~
10119 \SpecialChar ~
10120 dec r6
10121 \layout Standard
10122
10123
10124 \size footnotesize 
10125 ; goto _forcond_0($4)
10126 \layout Standard
10127
10128
10129 \size footnotesize 
10130 \SpecialChar ~
10131 \SpecialChar ~
10132 sjmp 00104$
10133 \layout Standard
10134
10135
10136 \size footnotesize 
10137 ; _forbreak_0($7) :
10138 \layout Standard
10139
10140
10141 \size footnotesize 
10142 00107$:
10143 \layout Standard
10144
10145
10146 \size footnotesize 
10147 ; ret iTemp24 [lr40:41]{short}
10148 \layout Standard
10149
10150
10151 \size footnotesize 
10152 \SpecialChar ~
10153 \SpecialChar ~
10154 mov a,r3
10155 \layout Standard
10156
10157
10158 \size footnotesize 
10159 \SpecialChar ~
10160 \SpecialChar ~
10161 add a,r2
10162 \layout Standard
10163
10164
10165 \size footnotesize 
10166 \SpecialChar ~
10167 \SpecialChar ~
10168 mov dpl,a
10169 \layout Standard
10170
10171
10172 \size footnotesize 
10173 ; _return($8) :
10174 \layout Standard
10175
10176
10177 \size footnotesize 
10178 00108$:
10179 \layout Standard
10180
10181
10182 \size footnotesize 
10183 \SpecialChar ~
10184 \SpecialChar ~
10185 ret
10186 \newline 
10187
10188 \layout Subsection
10189
10190 A few words about basic block successors, predecessors and dominators
10191 \layout Standard
10192
10193 Successors are basic blocks that might execute after this basic block.
10194 \newline 
10195 Predecessors are basic blocks that might execute before reaching this basic
10196  block.
10197 \newline 
10198 Dominators are basic blocks that WILL execute before reaching this basic
10199  block.
10200 \newline 
10201
10202 \layout Standard
10203
10204 [basic block 1]
10205 \layout Standard
10206
10207 if (something)
10208 \layout Standard
10209
10210 [basic block 2]
10211 \layout Standard
10212
10213 else
10214 \layout Standard
10215
10216 [basic block 3]
10217 \layout Standard
10218
10219 [basic block 4]
10220 \newline 
10221
10222 \layout Standard
10223
10224 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
10225 \layout Standard
10226
10227 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
10228 \layout Standard
10229
10230 c) domVect of [BB4] = BB1 ...
10231  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
10232  was executed.
10233 \layout Section
10234
10235 Acknowledgments
10236 \layout Standard
10237
10238
10239 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
10240
10241 \end_inset 
10242
10243
10244 \newline 
10245
10246 \newline 
10247
10248 \emph on 
10249 Thanks to all the other volunteer developers who have helped with coding,
10250  testing, web-page creation, distribution sets, etc.
10251  You know who you are :-)
10252 \emph default 
10253
10254 \newline 
10255
10256 \layout Standard
10257
10258 This document was initially written by Sandeep Dutta
10259 \layout Standard
10260
10261 All product names mentioned herein may be trademarks of their respective
10262  companies.
10263  
10264 \layout Standard
10265
10266
10267 \begin_inset LatexCommand \printindex{}
10268
10269 \end_inset 
10270
10271
10272 \the_end