git.gag.com Git - fw/sdcc/blob - doc/sdccman.lyx

   1 #LyX 1.3 created this file. For more info see http://www.lyx.org/
   2 \lyxformat 221
   3 \textclass book
   4 \begin_preamble
   5 \pdfoptionpdfminorversion=3
   6 \usepackage[
   7   pdftitle={SDCC Compiler User Guide},
   8   pdfauthor={SDCC development team},
   9   pdfsubject={installation, user manual},
  10   pdfkeywords={68hc08 8032 8051 ansi c compiler assembler CPU DS390 embedded development free Floating Point Arithmetic Freescale GPL HC08 inline Intel ISO/IEC 9899:1990 Linux MAC OS X manual Maxim mcs51 Microchip microcontroller open source PIC Unix Windows Z80 Zilog},
  11   pdfpagemode=UseOutlines,
  12   colorlinks=true,
  13   linkcolor=blue] {hyperref}
  14 %
  15 \sloppy
  16 \tolerance=500
  17 \emergencystretch=30pt
  18 %
  19 \date{}
  20 \end_preamble
  21 \language english
  22 \inputencoding default
  23 \fontscheme pslatex
  24 \graphics default
  25 \paperfontsize default
  26 \spacing single
  27 \papersize letterpaper
  28 \paperpackage a4
  29 \use_geometry 1
  30 \use_amsmath 0
  31 \use_natbib 0
  32 \use_numerical_citations 0
  33 \paperorientation portrait
  34 \leftmargin 30mm
  35 \topmargin 20mm
  36 \rightmargin 25mm
  37 \bottommargin 20mm
  38 \secnumdepth 3
  39 \tocdepth 3
  40 \paragraph_separation indent
  41 \defskip medskip
  42 \quotes_language swedish
  43 \quotes_times 2
  44 \papercolumns 1
  45 \papersides 1
  46 \paperpagestyle fancy
  47
  48 \layout Comment
  49
  50 Please note: double dashed longoptions (e.g.
  51  --version) are written this way: -
  52 \begin_inset ERT
  53 status Collapsed
  54
  55 \layout Standard
  56
  57 \backslash
  58 /
  59 \end_inset
  60
  61 -
  62 \layout Comment
  63
  64 Two resp.
  65  three consecutive dashes simply result in a long resp.
  66  extra long dash.
  67 \layout Comment
  68
  69 Architecture specific stuff (like memory models, code examples) should maybe
  70  later go
  71 \layout Comment
  72
  73 into seperate sections/chapters/appendices (it is hard to document PIC or
  74  Z80 in
  75 \layout Comment
  76
  77 a 8051 centered document) - for now simply add.
  78 \layout Title
  79
  80 SDCC Compiler User Guide
  81 \layout Date
  82
  83
  84 \size normal
  85 SDCC 2.6.4
  86 \size footnotesize
  87
  88 \newline
  89 $Date$
  90 \newline
  91 $Revision$
  92 \layout Comment
  93
  94 The above strings enclosed in $ are automatically updated by Subversion
  95 \layout Standard
  96
  97
  98 \begin_inset LatexCommand \tableofcontents{}
  99
 100 \end_inset
 101
 102
 103 \layout Chapter
 104
 105 Introduction
 106 \layout Section
 107
 108 About SDCC
 109 \layout Standard
 110
 111
 112 \series bold
 113 SDCC
 114 \series default
 115  (
 116 \emph on
 117 S
 118 \emph default
 119 mall
 120 \emph on
 121 D
 122 \emph default
 123 evice
 124 \emph on
 125 C
 126 \emph default
 127
 128 \emph on
 129 C
 130 \emph default
 131 ompiler) is an open source, retargettable, optimizing ANSI-C compiler by
 132
 133 \series bold
 134 Sandeep Dutta
 135 \series default
 136  designed for 8 bit Microprocessors.
 137  The current version targets Intel MCS51 based Microprocessors (8031, 8032,
 138  8051, 8052
 139 \begin_inset LatexCommand \index{8031, 8032, 8051, 8052, mcs51 CPU}
 140
 141 \end_inset
 142
 143 , etc.), Dallas DS80C390 variants, Freescale (formerly Motorola) HC08 and
 144  Zilog Z80 based MCUs.
 145  It can be retargeted for other microprocessors, support for Microchip PIC,
 146  Atmel AVR is under development.
 147  The entire source code for the compiler is distributed under GPL.
 148  SDCC uses ASXXXX
 149 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
 150
 151 \end_inset
 152
 153  & ASLINK
 154 \begin_inset LatexCommand \index{aslink}
 155
 156 \end_inset
 157
 158 , an open source retargetable assembler & linker.
 159  SDCC has extensive language extensions suitable for utilizing various microcont
 160 rollers and underlying hardware effectively.
 161
 162 \newline
 163
 164 \newline
 165 In addition to the MCU specific optimizations SDCC also does a host of standard
 166  optimizations like:
 167 \layout Itemize
 168
 169 global sub expression elimination,
 170 \layout Itemize
 171
 172 loop optimizations (loop invariant, strength reduction of induction variables
 173  and loop reversing),
 174 \layout Itemize
 175
 176 constant folding & propagation,
 177 \layout Itemize
 178
 179 copy propagation,
 180 \layout Itemize
 181
 182 dead code elimination
 183 \layout Itemize
 184
 185 jump tables for
 186 \emph on
 187 switch
 188 \emph default
 189  statements.
 190 \layout Standard
 191
 192 For the back-end SDCC uses a global register allocation scheme which should
 193  be well suited for other 8 bit MCUs.
 194
 195 \newline
 196
 197 \newline
 198 The peep hole optimizer uses a rule based substitution mechanism which is
 199  MCU independent.
 200
 201 \newline
 202
 203 \newline
 204 Supported data-types are:
 205 \layout Standard
 206
 207
 208 \begin_inset  Tabular
 209 <lyxtabular version="3" rows="8" columns="5">
 210 <features>
 211 <column alignment="center" valignment="top" leftline="true" width="0">
 212 <column alignment="center" valignment="top" leftline="true" width="0">
 213 <column alignment="center" valignment="top" leftline="true" width="0">
 214 <column alignment="center" valignment="top" leftline="true" width="0">
 215 <column alignment="block" valignment="top" leftline="true" rightline="true" width="20text%">
 216 <row topline="true" bottomline="true">
 217 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 218 \begin_inset Text
 219
 220 \layout Standard
 221
 222 type
 223 \end_inset
 224 </cell>
 225 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 226 \begin_inset Text
 227
 228 \layout Standard
 229
 230 width
 231 \end_inset
 232 </cell>
 233 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 234 \begin_inset Text
 235
 236 \layout Standard
 237
 238 default
 239 \end_inset
 240 </cell>
 241 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 242 \begin_inset Text
 243
 244 \layout Standard
 245
 246 signed range
 247 \end_inset
 248 </cell>
 249 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 250 \begin_inset Text
 251
 252 \layout Standard
 253
 254 unsigned range
 255 \end_inset
 256 </cell>
 257 </row>
 258 <row topline="true">
 259 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 260 \begin_inset Text
 261
 262 \layout Standard
 263
 264 bool
 265 \end_inset
 266 </cell>
 267 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 268 \begin_inset Text
 269
 270 \layout Standard
 271
 272 1 bit
 273 \end_inset
 274 </cell>
 275 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 276 \begin_inset Text
 277
 278 \layout Standard
 279
 280 unsigned
 281 \end_inset
 282 </cell>
 283 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 284 \begin_inset Text
 285
 286 \layout Standard
 287
 288 -
 289 \end_inset
 290 </cell>
 291 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 292 \begin_inset Text
 293
 294 \layout Standard
 295
 296 0, 1
 297 \end_inset
 298 </cell>
 299 </row>
 300 <row topline="true">
 301 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 302 \begin_inset Text
 303
 304 \layout Standard
 305
 306 char
 307 \end_inset
 308 </cell>
 309 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 310 \begin_inset Text
 311
 312 \layout Standard
 313
 314 8 bits, 1 byte
 315 \end_inset
 316 </cell>
 317 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 318 \begin_inset Text
 319
 320 \layout Standard
 321
 322 signed
 323 \end_inset
 324 </cell>
 325 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 326 \begin_inset Text
 327
 328 \layout Standard
 329
 330 -128, +127
 331 \end_inset
 332 </cell>
 333 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 334 \begin_inset Text
 335
 336 \layout Standard
 337
 338 0, +255
 339 \end_inset
 340 </cell>
 341 </row>
 342 <row topline="true">
 343 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 344 \begin_inset Text
 345
 346 \layout Standard
 347
 348 short
 349 \end_inset
 350 </cell>
 351 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 352 \begin_inset Text
 353
 354 \layout Standard
 355
 356 16 bits, 2 bytes
 357 \end_inset
 358 </cell>
 359 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 360 \begin_inset Text
 361
 362 \layout Standard
 363
 364 signed
 365 \end_inset
 366 </cell>
 367 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 368 \begin_inset Text
 369
 370 \layout Standard
 371
 372 -32.768, +32.767
 373 \end_inset
 374 </cell>
 375 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 376 \begin_inset Text
 377
 378 \layout Standard
 379
 380 0, +65.535
 381 \end_inset
 382 </cell>
 383 </row>
 384 <row topline="true">
 385 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 386 \begin_inset Text
 387
 388 \layout Standard
 389
 390 int
 391 \end_inset
 392 </cell>
 393 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 394 \begin_inset Text
 395
 396 \layout Standard
 397
 398 16 bits, 2 bytes
 399 \end_inset
 400 </cell>
 401 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 402 \begin_inset Text
 403
 404 \layout Standard
 405
 406 signed
 407 \end_inset
 408 </cell>
 409 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 410 \begin_inset Text
 411
 412 \layout Standard
 413
 414 -32.768, +32.767
 415 \end_inset
 416 </cell>
 417 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 418 \begin_inset Text
 419
 420 \layout Standard
 421
 422 0, +65.535
 423 \end_inset
 424 </cell>
 425 </row>
 426 <row topline="true" bottomline="true">
 427 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 428 \begin_inset Text
 429
 430 \layout Standard
 431
 432 long
 433 \end_inset
 434 </cell>
 435 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 436 \begin_inset Text
 437
 438 \layout Standard
 439
 440 32 bits, 4 bytes
 441 \end_inset
 442 </cell>
 443 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 444 \begin_inset Text
 445
 446 \layout Standard
 447
 448 signed
 449 \end_inset
 450 </cell>
 451 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 452 \begin_inset Text
 453
 454 \layout Standard
 455
 456 -2.147.483.648, +2.147.483.647
 457 \end_inset
 458 </cell>
 459 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 460 \begin_inset Text
 461
 462 \layout Standard
 463
 464 0, +4.294.967.295
 465 \end_inset
 466 </cell>
 467 </row>
 468 <row topline="true" bottomline="true">
 469 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 470 \begin_inset Text
 471
 472 \layout Standard
 473
 474 float
 475 \end_inset
 476 </cell>
 477 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 478 \begin_inset Text
 479
 480 \layout Standard
 481
 482 4 bytes IEEE 754
 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 signed
 491 \end_inset
 492 </cell>
 493 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 494 \begin_inset Text
 495
 496 \layout Standard
 497
 498 \end_inset
 499 </cell>
 500 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 501 \begin_inset Text
 502
 503 \layout Standard
 504
 505 1.175494351E-38,
 506 \family roman
 507 \series medium
 508 \shape up
 509 \size normal
 510 \emph off
 511 \bar no
 512 \noun off
 513 \color none
 514 3.402823466E+38
 515 \end_inset
 516 </cell>
 517 </row>
 518 <row topline="true" bottomline="true">
 519 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 520 \begin_inset Text
 521
 522 \layout Standard
 523
 524 pointer
 525 \end_inset
 526 </cell>
 527 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 528 \begin_inset Text
 529
 530 \layout Standard
 531
 532 1, 2, 3 or 4 bytes
 533 \end_inset
 534 </cell>
 535 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 536 \begin_inset Text
 537
 538 \layout Standard
 539
 540 generic
 541 \end_inset
 542 </cell>
 543 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 544 \begin_inset Text
 545
 546 \layout Standard
 547
 548 \end_inset
 549 </cell>
 550 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 551 \begin_inset Text
 552
 553 \layout Standard
 554
 555 \end_inset
 556 </cell>
 557 </row>
 558 </lyxtabular>
 559
 560 \end_inset
 561
 562
 563 \newline
 564 The compiler also allows
 565 \emph on
 566 inline assembler code
 567 \emph default
 568  to be embedded anywhere in a function.
 569  In addition, routines developed in assembly can also be called.
 570 \newline
 571
 572 \newline
 573 SDCC also provides an option (-
 574 \begin_inset ERT
 575 status Collapsed
 576
 577 \layout Standard
 578
 579 \backslash
 580 /
 581 \end_inset
 582
 583 -cyclomatic) to report the relative complexity of a function.
 584  These functions can then be further optimized, or hand coded in assembly
 585  if needed.
 586
 587 \newline
 588
 589 \newline
 590 SDCC also comes with a companion source level debugger SDCDB, the debugger
 591  currently uses ucSim a freeware simulator for 8051 and other micro-controllers.<
 592 \newline
 593
 594 \newline
 595 The latest version can be downloaded from
 596 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
 597
 598 \end_inset
 599
 600 .
 601
 602 \series bold
 603
 604 \series default
 605 \emph on
 606 Please note: the compiler will probably always be some steps ahead of this
 607  documentation
 608 \series bold
 609 \emph default
 610
 611 \begin_inset LatexCommand \index{Status of documentation}
 612
 613 \end_inset
 614
 615
 616 \begin_inset Foot
 617 collapsed false
 618
 619 \layout Standard
 620
 621 Obviously this has pros and cons
 622 \end_inset
 623
 624 .
 625 \layout Section
 626
 627 Open Source
 628 \layout Standard
 629
 630 All packages used in this compiler system are
 631 \emph on
 632 open source
 633 \emph default
 634  and
 635 \emph on
 636 freeware
 637 \emph default
 638 ; source code for all the sub-packages (pre-processor, assemblers, linkers
 639  etc) is distributed with the package.
 640  This documentation is maintained using a freeware word processor (LyX).
 641 \newline
 642 This program is free software; you can redistribute it and/or modify it
 643  under the terms of the GNU General Public License
 644 \begin_inset LatexCommand \index{GNU General Public License, GPL}
 645
 646 \end_inset
 647
 648  as published by the Free Software Foundation; either version 2, or (at
 649  your option) any later version.
 650  This program is distributed in the hope that it will be useful, but WITHOUT
 651  ANY WARRANTY; without even the implied warranty
 652 \begin_inset LatexCommand \index{warranty}
 653
 654 \end_inset
 655
 656  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 657  See the GNU General Public License for more details.
 658  You should have received a copy of the GNU General Public License along
 659  with this program; if not, write to the Free Software Foundation, 59 Temple
 660  Place - Suite 330, Boston, MA 02111-1307, USA.
 661  In other words, you are welcome to use, share and improve this program.
 662  You are forbidden to forbid anyone else to use, share and improve what
 663  you give them.
 664  Help stamp out software-hoarding!
 665 \layout Section
 666
 667 Typographic conventions
 668 \begin_inset LatexCommand \index{Typographic conventions}
 669
 670 \end_inset
 671
 672
 673 \layout Standard
 674
 675 Throughout this manual, we will use the following convention.
 676  Commands you have to type in are printed in
 677 \family sans
 678 \series bold
 679 "sans serif"
 680 \series default
 681 .
 682
 683 \family default
 684  Code samples are printed in
 685 \family typewriter
 686 typewriter font.
 687
 688 \family default
 689  Interesting items and new terms are printed in
 690 \emph on
 691 italic.
 692 \layout Section
 693
 694 Compatibility
 695 \begin_inset LatexCommand \label{sec:Compatibility-with-previous}
 696
 697 \end_inset
 698
 699  with previous versions
 700 \begin_inset LatexCommand \index{Compatibility with previous versions}
 701
 702 \end_inset
 703
 704
 705 \layout Standard
 706
 707 This version has numerous bug fixes compared with the previous version.
 708  But we also introduced some incompatibilities with older versions.
 709  Not just for the fun of it, but to make the compiler more stable, efficient
 710  and ANSI compliant
 711 \begin_inset LatexCommand \index{ANSI-compliance}
 712
 713 \end_inset
 714
 715  (see section
 716 \begin_inset LatexCommand \ref{sub:ANSI-Compliance}
 717
 718 \end_inset
 719
 720  for ANSI-Compliance).
 721
 722 \newline
 723
 724 \layout Itemize
 725
 726 short is now equivalent to int (16 bits), it used to be equivalent to char
 727  (8 bits) which is not ANSI compliant.
 728 \layout Itemize
 729
 730 the default directory for gcc-builds where include, library and documentation
 731  files are stored is now in /usr/local/share.
 732 \layout Itemize
 733
 734 char type parameters to vararg
 735 \begin_inset LatexCommand \index{vararg, va\_arg}
 736
 737 \end_inset
 738
 739  functions are casted to int unless explicitly casted
 740 \begin_inset Marginal
 741 collapsed true
 742
 743 \layout Standard
 744
 745
 746 \series bold
 747 \SpecialChar ~
 748 !
 749 \end_inset
 750
 751 , e.g.:
 752 \newline
 753
 754 \family typewriter
 755 \SpecialChar ~
 756 \SpecialChar ~
 757 char a=3;
 758 \newline
 759 \SpecialChar ~
 760 \SpecialChar ~
 761 printf ("%d %c
 762 \backslash
 763 n", a, (char)a);
 764 \family default
 765
 766 \newline
 767  will push a as an int and as a char resp.
 768 \layout Itemize
 769
 770 option -
 771 \begin_inset ERT
 772 status Collapsed
 773
 774 \layout Standard
 775
 776 \backslash
 777 /
 778 \end_inset
 779
 780 -regextend has been removed.
 781 \layout Itemize
 782
 783 option -
 784 \begin_inset ERT
 785 status Collapsed
 786
 787 \layout Standard
 788
 789 \backslash
 790 /
 791 \end_inset
 792
 793 -noregparms has been removed.
 794 \layout Itemize
 795
 796 option -
 797 \begin_inset ERT
 798 status Collapsed
 799
 800 \layout Standard
 801
 802 \backslash
 803 /
 804 \end_inset
 805
 806 -stack-after-data has been removed.
 807 \layout Itemize
 808
 809 bit
 810 \begin_inset LatexCommand \index{bit}
 811
 812 \end_inset
 813
 814  and sbit
 815 \begin_inset LatexCommand \index{sbit}
 816
 817 \end_inset
 818
 819
 820 \begin_inset LatexCommand \index{\_\_sbit}
 821
 822 \end_inset
 823
 824  types now consistently behave like the C99 _Bool type with respect to type
 825  conversion
 826 \begin_inset LatexCommand \index{type conversion}
 827
 828 \end_inset
 829
 830
 831 \begin_inset LatexCommand \index{type promotion}
 832
 833 \end_inset
 834
 835 .
 836  The most common incompatibility resulting from this change is related to
 837  bit toggling
 838 \begin_inset LatexCommand \index{Bit toggling}
 839
 840 \end_inset
 841
 842  idioms, e.g.:
 843 \newline
 844
 845 \family typewriter
 846 \SpecialChar ~
 847 \SpecialChar ~
 848 bit b;
 849 \newline
 850 \SpecialChar ~
 851 \SpecialChar ~
 852 b = ~
 853 \begin_inset LatexCommand \index{\~\/ Operator}
 854
 855 \end_inset
 856
 857 b; /* equivalent to b=1 instead of toggling b */
 858 \begin_inset Marginal
 859 collapsed true
 860
 861 \layout Standard
 862
 863
 864 \series bold
 865 \SpecialChar ~
 866 !
 867 \end_inset
 868
 869
 870 \newline
 871 \SpecialChar ~
 872 \SpecialChar ~
 873 b = !b; /* toggles b */
 874 \newline
 875
 876 \family default
 877 In previous versions, both forms would have toggled the bit.
 878 \layout Standard
 879
 880
 881 \emph on
 882 <pending: more incompatibilities?>
 883 \layout Section
 884
 885 System Requirements
 886 \layout Standard
 887
 888 What do you need before you start installation of SDCC? A computer, and
 889  a desire to compute.
 890  The preferred method of installation is to compile SDCC from source using
 891  GNU gcc and make.
 892  For Windows some pre-compiled binary distributions are available for your
 893  convenience.
 894  You should have some experience with command line tools and compiler use.
 895 \layout Section
 896
 897 Other Resources
 898 \layout Standard
 899
 900 The SDCC home page at
 901 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
 902
 903 \end_inset
 904
 905  is a great place to find distribution sets.
 906  You can also find links to the user mailing lists that offer help or discuss
 907  SDCC with other SDCC users.
 908  Web links to other SDCC related sites can also be found here.
 909  This document can be found in the DOC directory of the source package as
 910  a text or HTML file.
 911  A pdf version of this document is available at
 912 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
 913
 914 \end_inset
 915
 916 .
 917  Some of the other tools (simulator and assembler) included with SDCC contain
 918  their own documentation and can be found in the source distribution.
 919  If you want the latest unreleased software, the complete source package
 920  is available directly from Subversion on https://svn.sourceforge.net/svnroot/sdcc
 921 /trunk/sdcc.
 922 \layout Section
 923
 924 Wishes for the future
 925 \layout Standard
 926
 927 There are (and always will be) some things that could be done.
 928  Here are some I can think of:
 929 \newline
 930
 931 \layout Standard
 932
 933
 934 \family typewriter
 935 char KernelFunction3(char p) at 0x340;
 936 \newline
 937
 938 \layout Standard
 939
 940
 941 \family typewriter
 942 better code banking
 943 \begin_inset LatexCommand \index{code banking (limited support)}
 944
 945 \end_inset
 946
 947  support for mcs51
 948 \newline
 949
 950 \newline
 951
 952 \family default
 953 If you can think of some more, please see the section
 954 \begin_inset LatexCommand \ref{sub:Requesting-Features}
 955
 956 \end_inset
 957
 958  about filing feature requests
 959 \begin_inset LatexCommand \index{Requesting features}
 960
 961 \end_inset
 962
 963
 964 \begin_inset LatexCommand \index{Feature request}
 965
 966 \end_inset
 967
 968 .
 969 \newline
 970
 971 \layout Chapter
 972
 973 Installing SDCC
 974 \begin_inset LatexCommand \index{Installation}
 975
 976 \end_inset
 977
 978
 979 \layout Standard
 980
 981 For most users it is sufficient to skip to either section
 982 \begin_inset LatexCommand \ref{sub:Building-SDCC-on-Linux}
 983
 984 \end_inset
 985
 986  (Unix) or section
 987 \begin_inset LatexCommand \ref{sub:Windows-Install}
 988
 989 \end_inset
 990
 991  (Windows).
 992  More detailed instructions follow below.
 993 \layout Section
 994
 995 Configure Options
 996 \begin_inset LatexCommand \index{Options SDCC configuration}
 997
 998 \end_inset
 999
1000
1001 \layout Standard
1002
1003 The install paths, search paths and other options are defined when running
1004  'configure'.
1005  The defaults can be overridden by:
1006 \layout List
1007 \labelwidthstring 00.00.0000
1008
1009 -
1010 \begin_inset ERT
1011 status Collapsed
1012
1013 \layout Standard
1014
1015 \backslash
1016 /
1017 \end_inset
1018
1019 -prefix see table below
1020 \layout List
1021 \labelwidthstring 00.00.0000
1022
1023 -
1024 \begin_inset ERT
1025 status Collapsed
1026
1027 \layout Standard
1028
1029 \backslash
1030 /
1031 \end_inset
1032
1033 -exec_prefix see table below
1034 \layout List
1035 \labelwidthstring 00.00.0000
1036
1037 -
1038 \begin_inset ERT
1039 status Collapsed
1040
1041 \layout Standard
1042
1043 \backslash
1044 /
1045 \end_inset
1046
1047 -bindir see table below
1048 \layout List
1049 \labelwidthstring 00.00.0000
1050
1051 -
1052 \begin_inset ERT
1053 status Collapsed
1054
1055 \layout Standard
1056
1057 \backslash
1058 /
1059 \end_inset
1060
1061 -datadir see table below
1062 \newline
1063
1064 \layout List
1065 \labelwidthstring 00.00.0000
1066
1067 \SpecialChar ~
1068 \SpecialChar ~
1069 docdir environment variable, see table below
1070 \layout List
1071 \labelwidthstring 00.00.0000
1072
1073 \SpecialChar ~
1074 \SpecialChar ~
1075 include_dir_suffix environment variable, see table below
1076 \layout List
1077 \labelwidthstring 00.00.0000
1078
1079 \SpecialChar ~
1080 \SpecialChar ~
1081 lib_dir_suffix environment variable, see table below
1082 \layout List
1083 \labelwidthstring 00.00.0000
1084
1085 \SpecialChar ~
1086 \SpecialChar ~
1087 sdccconf_h_dir_separator environment variable, either / or
1088 \backslash
1089
1090 \backslash
1091  makes sense here.
1092  This character will only be used in sdccconf.h; don't forget it's a C-header,
1093  therefore a double-backslash is needed there.
1094 \newline
1095
1096 \layout List
1097 \labelwidthstring 00.00.0000
1098
1099 -
1100 \begin_inset ERT
1101 status Collapsed
1102
1103 \layout Standard
1104
1105 \backslash
1106 /
1107 \end_inset
1108
1109 -disable-mcs51-port Excludes the Intel mcs51 port
1110 \layout List
1111 \labelwidthstring 00.00.0000
1112
1113 -
1114 \begin_inset ERT
1115 status Collapsed
1116
1117 \layout Standard
1118
1119 \backslash
1120 /
1121 \end_inset
1122
1123 -disable-gbz80-port Excludes the Gameboy gbz80 port
1124 \layout List
1125 \labelwidthstring 00.00.0000
1126
1127 -
1128 \begin_inset ERT
1129 status Collapsed
1130
1131 \layout Standard
1132
1133 \backslash
1134 /
1135 \end_inset
1136
1137 -disable-z80-port Excludes the z80 port
1138 \layout List
1139 \labelwidthstring 00.00.0000
1140
1141 -
1142 \begin_inset ERT
1143 status Collapsed
1144
1145 \layout Standard
1146
1147 \backslash
1148 /
1149 \end_inset
1150
1151 -disable-avr-port Excludes the AVR port
1152 \layout List
1153 \labelwidthstring 00.00.0000
1154
1155 -
1156 \begin_inset ERT
1157 status Collapsed
1158
1159 \layout Standard
1160
1161 \backslash
1162 /
1163 \end_inset
1164
1165 -disable-ds390-port Excludes the DS390 port
1166 \layout List
1167 \labelwidthstring 00.00.0000
1168
1169 -
1170 \begin_inset ERT
1171 status Collapsed
1172
1173 \layout Standard
1174
1175 \backslash
1176 /
1177 \end_inset
1178
1179 -disable-hc08-port Excludes the HC08 port
1180 \layout List
1181 \labelwidthstring 00.00.0000
1182
1183 -
1184 \begin_inset ERT
1185 status Collapsed
1186
1187 \layout Standard
1188
1189 \backslash
1190 /
1191 \end_inset
1192
1193 -disable-pic-port Excludes the PIC port
1194 \layout List
1195 \labelwidthstring 00.00.0000
1196
1197 -
1198 \begin_inset ERT
1199 status Collapsed
1200
1201 \layout Standard
1202
1203 \backslash
1204 /
1205 \end_inset
1206
1207 -disable-xa51-port Excludes the XA51 port
1208 \layout List
1209 \labelwidthstring 00.00.0000
1210
1211 -
1212 \begin_inset ERT
1213 status Collapsed
1214
1215 \layout Standard
1216
1217 \backslash
1218 /
1219 \end_inset
1220
1221 -disable-ucsim Disables configuring and building of ucsim
1222 \layout List
1223 \labelwidthstring 00.00.0000
1224
1225 -
1226 \begin_inset ERT
1227 status Collapsed
1228
1229 \layout Standard
1230
1231 \backslash
1232 /
1233 \end_inset
1234
1235 -disable-device-lib Disables automatically building device libraries
1236 \layout List
1237 \labelwidthstring 00.00.0000
1238
1239 -
1240 \begin_inset ERT
1241 status Collapsed
1242
1243 \layout Standard
1244
1245 \backslash
1246 /
1247 \end_inset
1248
1249 -disable-packihx Disables building packihx
1250 \newline
1251
1252 \layout List
1253 \labelwidthstring 00.00.0000
1254
1255 -
1256 \begin_inset ERT
1257 status Collapsed
1258
1259 \layout Standard
1260
1261 \backslash
1262 /
1263 \end_inset
1264
1265 -enable-doc Build pdf, html and txt files from the lyx sources
1266 \layout List
1267 \labelwidthstring 00.00.0000
1268
1269 -
1270 \begin_inset ERT
1271 status Collapsed
1272
1273 \layout Standard
1274
1275 \backslash
1276 /
1277 \end_inset
1278
1279 -enable-libgc Use the Bohem memory allocator.
1280  Lower runtime footprint.
1281 \layout Standard
1282
1283 Furthermore the environment variables CC, CFLAGS, ...
1284  the tools and their arguments can be influenced.
1285  Please see `configure -
1286 \begin_inset ERT
1287 status Collapsed
1288
1289 \layout Standard
1290
1291 \backslash
1292 /
1293 \end_inset
1294
1295 -help` and the man/info pages of `configure` for details.
1296 \newline
1297
1298 \newline
1299 The names of the standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB,
1300  STD_FP_LIB, STD_DS390_LIB, STD_XA51_LIB and the environment variables SDCC_DIR_
1301 NAME, SDCC_INCLUDE_NAME, SDCC_LIB_NAME are defined by `configure` too.
1302  At the moment it's not possible to change the default settings (it was
1303  simply never required).
1304 \newline
1305
1306 \newline
1307 These configure options are compiled into the binaries, and can only be
1308  changed by rerunning 'configure' and recompiling SDCC.
1309  The configure options are written in
1310 \emph on
1311 italics
1312 \emph default
1313  to distinguish them from run time environment variables (see section search
1314  paths).
1315 \newline
1316
1317 \newline
1318 The settings for
1319 \begin_inset Quotes sld
1320 \end_inset
1321
1322 Win32 builds
1323 \begin_inset Quotes srd
1324 \end_inset
1325
1326  are used by the SDCC team to build the official Win32 binaries.
1327  The SDCC team uses Mingw32 to build the official Windows binaries, because
1328  it's
1329 \layout Enumerate
1330
1331 open source,
1332 \layout Enumerate
1333
1334 a gcc compiler and last but not least
1335 \layout Enumerate
1336
1337 the binaries can be built by cross compiling on Sourceforge's compile farm.
1338 \layout Standard
1339
1340 See the examples, how to pass the Win32 settings to 'configure'.
1341  The other Win32 builds using Borland, VC or whatever don't use 'configure',
1342  but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure'
1343  for Win32.
1344 \newline
1345
1346 \newline
1347 These defaults are:
1348 \newline
1349
1350 \layout Standard
1351 \align center
1352
1353 \begin_inset  Tabular
1354 <lyxtabular version="3" rows="8" columns="3">
1355 <features>
1356 <column alignment="block" valignment="top" leftline="true" width="0in">
1357 <column alignment="block" valignment="top" leftline="true" width="0in">
1358 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1359 <row topline="true" bottomline="true">
1360 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1361 \begin_inset Text
1362
1363 \layout Standard
1364
1365 Variable
1366 \end_inset
1367 </cell>
1368 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1369 \begin_inset Text
1370
1371 \layout Standard
1372
1373 default
1374 \end_inset
1375 </cell>
1376 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1377 \begin_inset Text
1378
1379 \layout Standard
1380
1381 Win32 builds
1382 \end_inset
1383 </cell>
1384 </row>
1385 <row topline="true">
1386 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1387 \begin_inset Text
1388
1389 \layout Standard
1390
1391
1392 \emph on
1393 PREFIX
1394 \end_inset
1395 </cell>
1396 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1397 \begin_inset Text
1398
1399 \layout Standard
1400
1401 /usr/local
1402 \end_inset
1403 </cell>
1404 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1405 \begin_inset Text
1406
1407 \layout Standard
1408
1409
1410 \backslash
1411 sdcc
1412 \end_inset
1413 </cell>
1414 </row>
1415 <row topline="true">
1416 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1417 \begin_inset Text
1418
1419 \layout Standard
1420
1421
1422 \emph on
1423 EXEC_PREFIX
1424 \end_inset
1425 </cell>
1426 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1427 \begin_inset Text
1428
1429 \layout Standard
1430
1431
1432 \emph on
1433 $PREFIX
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
1442 \emph on
1443 $PREFIX
1444 \end_inset
1445 </cell>
1446 </row>
1447 <row topline="true">
1448 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1449 \begin_inset Text
1450
1451 \layout Standard
1452
1453
1454 \emph on
1455 BINDIR
1456 \end_inset
1457 </cell>
1458 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1459 \begin_inset Text
1460
1461 \layout Standard
1462
1463
1464 \emph on
1465 $EXECPREFIX
1466 \emph default
1467 /bin
1468 \end_inset
1469 </cell>
1470 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1471 \begin_inset Text
1472
1473 \layout Standard
1474
1475
1476 \emph on
1477 $EXECPREFIX
1478 \emph default
1479
1480 \backslash
1481 bin
1482 \end_inset
1483 </cell>
1484 </row>
1485 <row topline="true">
1486 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1487 \begin_inset Text
1488
1489 \layout Standard
1490
1491
1492 \emph on
1493 DATADIR
1494 \end_inset
1495 </cell>
1496 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1497 \begin_inset Text
1498
1499 \layout Standard
1500
1501
1502 \emph on
1503 $PREFIX
1504 \emph default
1505 /share
1506 \end_inset
1507 </cell>
1508 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1509 \begin_inset Text
1510
1511 \layout Standard
1512
1513
1514 \emph on
1515 $PREFIX
1516 \end_inset
1517 </cell>
1518 </row>
1519 <row topline="true">
1520 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1521 \begin_inset Text
1522
1523 \layout Standard
1524
1525
1526 \emph on
1527 DOCDIR
1528 \end_inset
1529 </cell>
1530 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1531 \begin_inset Text
1532
1533 \layout Standard
1534
1535
1536 \emph on
1537 $DATADIR
1538 \emph default
1539 /sdcc/doc
1540 \end_inset
1541 </cell>
1542 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1543 \begin_inset Text
1544
1545 \layout Standard
1546
1547
1548 \emph on
1549 $DATADIR
1550 \emph default
1551
1552 \backslash
1553 doc
1554 \end_inset
1555 </cell>
1556 </row>
1557 <row topline="true">
1558 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1559 \begin_inset Text
1560
1561 \layout Standard
1562
1563
1564 \emph on
1565 INCLUDE_DIR_SUFFIX
1566 \end_inset
1567 </cell>
1568 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1569 \begin_inset Text
1570
1571 \layout Standard
1572
1573 sdcc/include
1574 \end_inset
1575 </cell>
1576 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1577 \begin_inset Text
1578
1579 \layout Standard
1580
1581 include
1582 \end_inset
1583 </cell>
1584 </row>
1585 <row topline="true" bottomline="true">
1586 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1587 \begin_inset Text
1588
1589 \layout Standard
1590
1591
1592 \emph on
1593 LIB_DIR_SUFFIX
1594 \end_inset
1595 </cell>
1596 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1597 \begin_inset Text
1598
1599 \layout Standard
1600
1601 sdcc/lib
1602 \end_inset
1603 </cell>
1604 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1605 \begin_inset Text
1606
1607 \layout Standard
1608
1609 lib
1610 \end_inset
1611 </cell>
1612 </row>
1613 </lyxtabular>
1614
1615 \end_inset
1616
1617
1618 \newline
1619
1620 \layout Standard
1621 \noindent
1622 'configure' also computes relative paths.
1623  This is needed for full relocatability of a binary package and to complete
1624  search paths (see section search paths below):
1625 \newline
1626
1627 \layout Standard
1628 \align center
1629
1630 \begin_inset  Tabular
1631 <lyxtabular version="3" rows="4" columns="3">
1632 <features>
1633 <column alignment="block" valignment="top" leftline="true" width="0in">
1634 <column alignment="block" valignment="top" leftline="true" width="0in">
1635 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1636 <row topline="true" bottomline="true">
1637 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1638 \begin_inset Text
1639
1640 \layout Standard
1641
1642 Variable (computed)
1643 \end_inset
1644 </cell>
1645 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1646 \begin_inset Text
1647
1648 \layout Standard
1649
1650 default
1651 \end_inset
1652 </cell>
1653 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1654 \begin_inset Text
1655
1656 \layout Standard
1657
1658 Win32 builds
1659 \end_inset
1660 </cell>
1661 </row>
1662 <row topline="true" bottomline="true">
1663 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1664 \begin_inset Text
1665
1666 \layout Standard
1667
1668
1669 \emph on
1670 BIN2DATA_DIR
1671 \end_inset
1672 </cell>
1673 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1674 \begin_inset Text
1675
1676 \layout Standard
1677
1678 ../share
1679 \end_inset
1680 </cell>
1681 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1682 \begin_inset Text
1683
1684 \layout Standard
1685
1686 ..
1687 \end_inset
1688 </cell>
1689 </row>
1690 <row bottomline="true">
1691 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1692 \begin_inset Text
1693
1694 \layout Standard
1695
1696
1697 \emph on
1698 PREFIX2BIN_DIR
1699 \end_inset
1700 </cell>
1701 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1702 \begin_inset Text
1703
1704 \layout Standard
1705
1706 bin
1707 \end_inset
1708 </cell>
1709 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1710 \begin_inset Text
1711
1712 \layout Standard
1713
1714 bin
1715 \end_inset
1716 </cell>
1717 </row>
1718 <row bottomline="true">
1719 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1720 \begin_inset Text
1721
1722 \layout Standard
1723
1724
1725 \emph on
1726 PREFIX2DATA_DIR
1727 \end_inset
1728 </cell>
1729 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1730 \begin_inset Text
1731
1732 \layout Standard
1733
1734 share/sdcc
1735 \end_inset
1736 </cell>
1737 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1738 \begin_inset Text
1739
1740 \layout Standard
1741
1742 \end_inset
1743 </cell>
1744 </row>
1745 </lyxtabular>
1746
1747 \end_inset
1748
1749
1750 \newline
1751
1752 \layout Standard
1753 \noindent
1754 Examples:
1755 \layout LyX-Code
1756
1757 ./configure
1758 \newline
1759 ./configure -
1760 \begin_inset ERT
1761 status Collapsed
1762
1763 \layout Standard
1764
1765 \backslash
1766 /
1767 \end_inset
1768
1769 -prefix=
1770 \begin_inset Quotes srd
1771 \end_inset
1772
1773 /usr/bin
1774 \begin_inset Quotes srd
1775 \end_inset
1776
1777  -
1778 \begin_inset ERT
1779 status Collapsed
1780
1781 \layout Standard
1782
1783 \backslash
1784 /
1785 \end_inset
1786
1787 -datadir=
1788 \begin_inset Quotes srd
1789 \end_inset
1790
1791 /usr/share
1792 \begin_inset Quotes srd
1793 \end_inset
1794
1795
1796 \newline
1797 ./configure -
1798 \begin_inset ERT
1799 status Collapsed
1800
1801 \layout Standard
1802
1803 \backslash
1804 /
1805 \end_inset
1806
1807 -disable-avr-port -
1808 \begin_inset ERT
1809 status Collapsed
1810
1811 \layout Standard
1812
1813 \backslash
1814 /
1815 \end_inset
1816
1817 -disable-xa51-port
1818 \layout Standard
1819
1820 To cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw
1821 32'):
1822 \layout LyX-Code
1823
1824 ./configure
1825 \backslash
1826
1827 \newline
1828 CC=
1829 \begin_inset Quotes srd
1830 \end_inset
1831
1832 i586-mingw32msvc-gcc
1833 \begin_inset Quotes srd
1834 \end_inset
1835
1836  CXX=
1837 \begin_inset Quotes srd
1838 \end_inset
1839
1840 i586-mingw32msvc-g++
1841 \begin_inset Quotes srd
1842 \end_inset
1843
1844
1845 \backslash
1846
1847 \newline
1848 RANLIB=
1849 \begin_inset Quotes srd
1850 \end_inset
1851
1852 i586-mingw32msvc-ranlib
1853 \begin_inset Quotes srd
1854 \end_inset
1855
1856
1857 \backslash
1858
1859 \newline
1860 STRIP=
1861 \begin_inset Quotes srd
1862 \end_inset
1863
1864 i586-mingw32msvc-strip
1865 \begin_inset Quotes srd
1866 \end_inset
1867
1868
1869 \backslash
1870
1871 \newline
1872 -
1873 \begin_inset ERT
1874 status Collapsed
1875
1876 \layout Standard
1877
1878 \backslash
1879 /
1880 \end_inset
1881
1882 -prefix=
1883 \begin_inset Quotes srd
1884 \end_inset
1885
1886 /sdcc
1887 \begin_inset Quotes srd
1888 \end_inset
1889
1890
1891 \backslash
1892
1893 \newline
1894 -
1895 \begin_inset ERT
1896 status Collapsed
1897
1898 \layout Standard
1899
1900 \backslash
1901 /
1902 \end_inset
1903
1904 -datadir=
1905 \begin_inset Quotes srd
1906 \end_inset
1907
1908 /sdcc
1909 \begin_inset Quotes srd
1910 \end_inset
1911
1912
1913 \backslash
1914
1915 \newline
1916 docdir=
1917 \begin_inset Quotes srd
1918 \end_inset
1919
1920 /sdcc/doc
1921 \begin_inset Quotes srd
1922 \end_inset
1923
1924
1925 \backslash
1926
1927 \newline
1928 include_dir_suffix=
1929 \begin_inset Quotes srd
1930 \end_inset
1931
1932 include
1933 \begin_inset Quotes srd
1934 \end_inset
1935
1936
1937 \backslash
1938
1939 \newline
1940 lib_dir_suffix=
1941 \begin_inset Quotes srd
1942 \end_inset
1943
1944 lib
1945 \begin_inset Quotes srd
1946 \end_inset
1947
1948
1949 \backslash
1950
1951 \newline
1952 sdccconf_h_dir_separator=
1953 \begin_inset Quotes srd
1954 \end_inset
1955
1956
1957 \backslash
1958
1959 \backslash
1960
1961 \backslash
1962
1963 \backslash
1964
1965 \begin_inset Quotes srd
1966 \end_inset
1967
1968
1969 \backslash
1970
1971 \newline
1972 -
1973 \begin_inset ERT
1974 status Collapsed
1975
1976 \layout Standard
1977
1978 \backslash
1979 /
1980 \end_inset
1981
1982 -disable-device-lib
1983 \backslash
1984
1985 \newline
1986 -
1987 \begin_inset ERT
1988 status Collapsed
1989
1990 \layout Standard
1991
1992 \backslash
1993 /
1994 \end_inset
1995
1996 -host=i586-mingw32msvc
1997 \backslash
1998
1999 \newline
2000 -
2001 \begin_inset ERT
2002 status Collapsed
2003
2004 \layout Standard
2005
2006 \backslash
2007 /
2008 \end_inset
2009
2010 -build=unknown-unknown-linux-gnu
2011 \layout Standard
2012
2013 To
2014 \begin_inset Quotes sld
2015 \end_inset
2016
2017 cross
2018 \begin_inset Quotes srd
2019 \end_inset
2020
2021 compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32
2022 ):
2023 \layout LyX-Code
2024
2025 ./configure -C
2026 \backslash
2027
2028 \newline
2029 -
2030 \begin_inset ERT
2031 status Collapsed
2032
2033 \layout Standard
2034
2035 \backslash
2036 /
2037 \end_inset
2038
2039 -prefix=
2040 \begin_inset Quotes srd
2041 \end_inset
2042
2043 /sdcc
2044 \begin_inset Quotes srd
2045 \end_inset
2046
2047
2048 \backslash
2049
2050 \newline
2051 -
2052 \begin_inset ERT
2053 status Collapsed
2054
2055 \layout Standard
2056
2057 \backslash
2058 /
2059 \end_inset
2060
2061 -datadir=
2062 \begin_inset Quotes srd
2063 \end_inset
2064
2065 /sdcc
2066 \begin_inset Quotes srd
2067 \end_inset
2068
2069
2070 \backslash
2071
2072 \newline
2073 docdir=
2074 \begin_inset Quotes srd
2075 \end_inset
2076
2077 /sdcc/doc
2078 \begin_inset Quotes srd
2079 \end_inset
2080
2081
2082 \backslash
2083
2084 \newline
2085 include_dir_suffix=
2086 \begin_inset Quotes srd
2087 \end_inset
2088
2089 include
2090 \begin_inset Quotes srd
2091 \end_inset
2092
2093
2094 \backslash
2095
2096 \newline
2097 lib_dir_suffix=
2098 \begin_inset Quotes srd
2099 \end_inset
2100
2101 lib
2102 \begin_inset Quotes srd
2103 \end_inset
2104
2105
2106 \backslash
2107
2108 \newline
2109 sdccconf_h_dir_separator=
2110 \begin_inset Quotes srd
2111 \end_inset
2112
2113
2114 \backslash
2115
2116 \backslash
2117
2118 \backslash
2119
2120 \backslash
2121
2122 \begin_inset Quotes srd
2123 \end_inset
2124
2125
2126 \backslash
2127
2128 \newline
2129 CC=
2130 \begin_inset Quotes srd
2131 \end_inset
2132
2133 gcc -mno-cygwin
2134 \begin_inset Quotes srd
2135 \end_inset
2136
2137
2138 \backslash
2139
2140 \newline
2141 CXX=
2142 \begin_inset Quotes srd
2143 \end_inset
2144
2145 g++ -mno-cygwin
2146 \begin_inset Quotes srd
2147 \end_inset
2148
2149
2150 \layout Standard
2151
2152 'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
2153  The option '-
2154 \begin_inset ERT
2155 status Collapsed
2156
2157 \layout Standard
2158
2159 \backslash
2160 /
2161 \end_inset
2162
2163 -C' turns on caching, which gives a little bit extra speed.
2164  However if options are changed, it can be necessary to delete the config.cache
2165  file.
2166 \layout Section
2167
2168 Install paths
2169 \begin_inset LatexCommand \label{sub:Install-paths}
2170
2171 \end_inset
2172
2173
2174 \begin_inset LatexCommand \index{Install paths}
2175
2176 \end_inset
2177
2178
2179 \layout Standard
2180 \added_space_top medskip \align center
2181
2182 \begin_inset  Tabular
2183 <lyxtabular version="3" rows="5" columns="4">
2184 <features>
2185 <column alignment="left" valignment="top" leftline="true" width="0">
2186 <column alignment="left" valignment="top" leftline="true" width="0">
2187 <column alignment="left" valignment="top" leftline="true" width="0">
2188 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
2189 <row topline="true" bottomline="true">
2190 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2191 \begin_inset Text
2192
2193 \layout Standard
2194
2195
2196 \series bold
2197 Description
2198 \end_inset
2199 </cell>
2200 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2201 \begin_inset Text
2202
2203 \layout Standard
2204
2205
2206 \series bold
2207 Path
2208 \end_inset
2209 </cell>
2210 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2211 \begin_inset Text
2212
2213 \layout Standard
2214
2215
2216 \series bold
2217 Default
2218 \end_inset
2219 </cell>
2220 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2221 \begin_inset Text
2222
2223 \layout Standard
2224
2225
2226 \series bold
2227 Win32 builds
2228 \end_inset
2229 </cell>
2230 </row>
2231 <row topline="true">
2232 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2233 \begin_inset Text
2234
2235 \layout Standard
2236
2237 Binary files*
2238 \end_inset
2239 </cell>
2240 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2241 \begin_inset Text
2242
2243 \layout Standard
2244
2245
2246 \emph on
2247 $EXEC_PREFIX
2248 \end_inset
2249 </cell>
2250 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2251 \begin_inset Text
2252
2253 \layout Standard
2254
2255 /usr/local/bin
2256 \end_inset
2257 </cell>
2258 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2259 \begin_inset Text
2260
2261 \layout Standard
2262
2263
2264 \backslash
2265 sdcc
2266 \backslash
2267 bin
2268 \end_inset
2269 </cell>
2270 </row>
2271 <row topline="true">
2272 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2273 \begin_inset Text
2274
2275 \layout Standard
2276
2277 Include files
2278 \end_inset
2279 </cell>
2280 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2281 \begin_inset Text
2282
2283 \layout Standard
2284
2285
2286 \emph on
2287 $DATADIR/ $INCLUDE_DIR_SUFFIX
2288 \end_inset
2289 </cell>
2290 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2291 \begin_inset Text
2292
2293 \layout Standard
2294
2295 /usr/local/share/sdcc/include
2296 \end_inset
2297 </cell>
2298 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2299 \begin_inset Text
2300
2301 \layout Standard
2302
2303
2304 \backslash
2305 sdcc
2306 \backslash
2307 include
2308 \end_inset
2309 </cell>
2310 </row>
2311 <row topline="true">
2312 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2313 \begin_inset Text
2314
2315 \layout Standard
2316
2317 Library file**
2318 \end_inset
2319 </cell>
2320 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2321 \begin_inset Text
2322
2323 \layout Standard
2324
2325
2326 \emph on
2327 $DATADIR/$LIB_DIR_SUFFIX
2328 \end_inset
2329 </cell>
2330 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2331 \begin_inset Text
2332
2333 \layout Standard
2334
2335 /usr/local/share/sdcc/lib
2336 \end_inset
2337 </cell>
2338 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2339 \begin_inset Text
2340
2341 \layout Standard
2342
2343
2344 \backslash
2345 sdcc
2346 \backslash
2347 lib
2348 \end_inset
2349 </cell>
2350 </row>
2351 <row topline="true" bottomline="true">
2352 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2353 \begin_inset Text
2354
2355 \layout Standard
2356
2357 Documentation
2358 \end_inset
2359 </cell>
2360 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2361 \begin_inset Text
2362
2363 \layout Standard
2364
2365
2366 \emph on
2367 $DOCDIR
2368 \end_inset
2369 </cell>
2370 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2371 \begin_inset Text
2372
2373 \layout Standard
2374
2375 /usr/local/share/sdcc/doc
2376 \end_inset
2377 </cell>
2378 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2379 \begin_inset Text
2380
2381 \layout Standard
2382
2383
2384 \backslash
2385 sdcc
2386 \backslash
2387 doc
2388 \end_inset
2389 </cell>
2390 </row>
2391 </lyxtabular>
2392
2393 \end_inset
2394
2395
2396 \layout Verse
2397
2398
2399 \size footnotesize
2400 *compiler, preprocessor, assembler, and linker
2401 \newline
2402 **the
2403 \shape italic
2404 model
2405 \shape default
2406  is auto-appended by the compiler, e.g.
2407  small, large, z80, ds390 etc
2408 \layout Standard
2409 \noindent
2410 The install paths can still be changed during `make install` with e.g.:
2411 \layout LyX-Code
2412
2413 make install prefix=$(HOME)/local/sdcc
2414 \layout Standard
2415
2416 Of course this doesn't change the search paths compiled into the binaries.
2417 \newline
2418
2419 \newline
2420 Moreover the install path can be changed by defining DESTDIR
2421 \begin_inset LatexCommand \index{DESTDIR}
2422
2423 \end_inset
2424
2425 :
2426 \layout LyX-Code
2427
2428 make install DESTDIR=$(HOME)/sdcc.rpm/
2429 \layout Standard
2430
2431 Please note that DESTDIR must have a trailing slash!
2432 \layout Section
2433
2434 Search Paths
2435 \begin_inset LatexCommand \label{sub:Search-Paths}
2436
2437 \end_inset
2438
2439
2440 \begin_inset LatexCommand \index{Search path}
2441
2442 \end_inset
2443
2444
2445 \layout Standard
2446
2447 Some search paths or parts of them are determined by configure variables
2448  (in
2449 \emph on
2450 italics
2451 \emph default
2452 , see section above).
2453  Further search paths are determined by environment variables during runtime.
2454
2455 \newline
2456 The paths searched when running the compiler are as follows (the first catch
2457  wins):
2458 \newline
2459
2460 \newline
2461 1.
2462  Binary files (preprocessor, assembler and linker)
2463 \newline
2464
2465 \layout Standard
2466 \align center
2467
2468 \begin_inset  Tabular
2469 <lyxtabular version="3" rows="4" columns="3">
2470 <features>
2471 <column alignment="block" valignment="top" leftline="true" width="0in">
2472 <column alignment="block" valignment="top" leftline="true" width="0in">
2473 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2474 <row topline="true" bottomline="true">
2475 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2476 \begin_inset Text
2477
2478 \layout Standard
2479
2480 Search path
2481 \end_inset
2482 </cell>
2483 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2484 \begin_inset Text
2485
2486 \layout Standard
2487
2488 default
2489 \end_inset
2490 </cell>
2491 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2492 \begin_inset Text
2493
2494 \layout Standard
2495
2496 Win32 builds
2497 \end_inset
2498 </cell>
2499 </row>
2500 <row topline="true">
2501 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2502 \begin_inset Text
2503
2504 \layout Standard
2505
2506 $SDCC_HOME/
2507 \emph on
2508 $PPREFIX2BIN_DIR
2509 \end_inset
2510 </cell>
2511 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2512 \begin_inset Text
2513
2514 \layout Standard
2515
2516 $SDCC_HOME/bin
2517 \end_inset
2518 </cell>
2519 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2520 \begin_inset Text
2521
2522 \layout Standard
2523
2524 $SDCC_HOME
2525 \backslash
2526 bin
2527 \end_inset
2528 </cell>
2529 </row>
2530 <row topline="true">
2531 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2532 \begin_inset Text
2533
2534 \layout Standard
2535
2536 Path of argv[0] (if available)
2537 \end_inset
2538 </cell>
2539 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2540 \begin_inset Text
2541
2542 \layout Standard
2543
2544 Path of argv[0]
2545 \end_inset
2546 </cell>
2547 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2548 \begin_inset Text
2549
2550 \layout Standard
2551
2552 Path of argv[0]
2553 \end_inset
2554 </cell>
2555 </row>
2556 <row topline="true" bottomline="true">
2557 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2558 \begin_inset Text
2559
2560 \layout Standard
2561
2562 $PATH
2563 \end_inset
2564 </cell>
2565 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2566 \begin_inset Text
2567
2568 \layout Standard
2569
2570 $PATH
2571 \end_inset
2572 </cell>
2573 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2574 \begin_inset Text
2575
2576 \layout Standard
2577
2578 $PATH
2579 \end_inset
2580 </cell>
2581 </row>
2582 </lyxtabular>
2583
2584 \end_inset
2585
2586
2587 \newline
2588
2589 \layout Standard
2590 \noindent
2591 2.
2592  Include files
2593 \newline
2594
2595 \layout Standard
2596 \align center
2597
2598 \begin_inset  Tabular
2599 <lyxtabular version="3" rows="6" columns="3">
2600 <features>
2601 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2602 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2603 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2604 <row topline="true" bottomline="true">
2605 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2606 \begin_inset Text
2607
2608 \layout Standard
2609
2610 Search path
2611 \end_inset
2612 </cell>
2613 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2614 \begin_inset Text
2615
2616 \layout Standard
2617
2618 default
2619 \end_inset
2620 </cell>
2621 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2622 \begin_inset Text
2623
2624 \layout Standard
2625
2626 Win32 builds
2627 \end_inset
2628 </cell>
2629 </row>
2630 <row topline="true">
2631 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2632 \begin_inset Text
2633
2634 \layout Standard
2635
2636 -
2637 \begin_inset ERT
2638 status Collapsed
2639
2640 \layout Standard
2641
2642 \backslash
2643 /
2644 \end_inset
2645
2646 -I dir
2647 \end_inset
2648 </cell>
2649 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2650 \begin_inset Text
2651
2652 \layout Standard
2653
2654 -
2655 \begin_inset ERT
2656 status Collapsed
2657
2658 \layout Standard
2659
2660 \backslash
2661 /
2662 \end_inset
2663
2664 -I dir
2665 \end_inset
2666 </cell>
2667 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2668 \begin_inset Text
2669
2670 \layout Standard
2671
2672 -
2673 \begin_inset ERT
2674 status Collapsed
2675
2676 \layout Standard
2677
2678 \backslash
2679 /
2680 \end_inset
2681
2682 -I dir
2683 \end_inset
2684 </cell>
2685 </row>
2686 <row topline="true">
2687 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2688 \begin_inset Text
2689
2690 \layout Standard
2691
2692 $SDCC_INCLUDE
2693 \end_inset
2694 </cell>
2695 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2696 \begin_inset Text
2697
2698 \layout Standard
2699
2700 $SDCC_INCLUDE
2701 \end_inset
2702 </cell>
2703 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2704 \begin_inset Text
2705
2706 \layout Standard
2707
2708 $SDCC_INCLUDE
2709 \end_inset
2710 </cell>
2711 </row>
2712 <row topline="true">
2713 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2714 \begin_inset Text
2715
2716 \layout Standard
2717
2718 $SDCC_HOME/
2719 \newline
2720
2721 \emph on
2722 $PREFIX2DATA_DIR/
2723 \newline
2724 $INCLUDE_DIR_SUFFIX
2725 \end_inset
2726 </cell>
2727 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2728 \begin_inset Text
2729
2730 \layout Standard
2731
2732 $SDCC_ HOME/
2733 \newline
2734 share/sdcc/
2735 \newline
2736 include
2737 \end_inset
2738 </cell>
2739 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2740 \begin_inset Text
2741
2742 \layout Standard
2743
2744 $SDCC_HOME
2745 \backslash
2746 include
2747 \end_inset
2748 </cell>
2749 </row>
2750 <row topline="true">
2751 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2752 \begin_inset Text
2753
2754 \layout Standard
2755
2756 path(argv[0])/
2757 \newline
2758
2759 \emph on
2760 $BIN2DATADIR/
2761 \emph default
2762
2763 \newline
2764
2765 \emph on
2766 $INCLUDE_DIR_SUFFIX
2767 \end_inset
2768 </cell>
2769 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2770 \begin_inset Text
2771
2772 \layout Standard
2773
2774 path(argv[0])/
2775 \newline
2776 ../sdcc/include
2777 \newline
2778 \SpecialChar ~
2779 \SpecialChar ~
2780 \SpecialChar ~
2781 \SpecialChar ~
2782 \SpecialChar ~
2783 \SpecialChar ~
2784 \SpecialChar ~
2785 \SpecialChar ~
2786 \SpecialChar ~
2787 \SpecialChar ~
2788 \SpecialChar ~
2789 \SpecialChar ~
2790 \SpecialChar ~
2791 \SpecialChar ~
2792 \SpecialChar ~
2793 \SpecialChar ~
2794 \SpecialChar ~
2795 \SpecialChar ~
2796 \SpecialChar ~
2797 \SpecialChar ~
2798 \SpecialChar ~
2799 \SpecialChar ~
2800 \SpecialChar ~
2801 \SpecialChar ~
2802 \SpecialChar ~
2803 \SpecialChar ~
2804 \SpecialChar ~
2805 \SpecialChar ~
2806 \SpecialChar ~
2807 \SpecialChar ~
2808 \SpecialChar ~
2809 \SpecialChar ~
2810 \SpecialChar ~
2811 \SpecialChar ~
2812 \SpecialChar ~
2813 \SpecialChar ~
2814 \SpecialChar ~
2815 \SpecialChar ~
2816
2817 \end_inset
2818 </cell>
2819 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2820 \begin_inset Text
2821
2822 \layout Standard
2823
2824 path(argv[0])
2825 \backslash
2826 ..
2827 \backslash
2828 include
2829 \end_inset
2830 </cell>
2831 </row>
2832 <row topline="true" bottomline="true">
2833 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2834 \begin_inset Text
2835
2836 \layout Standard
2837
2838
2839 \emph on
2840 $DATADIR/
2841 \emph default
2842
2843 \newline
2844
2845 \emph on
2846 $INCLUDE_DIR_SUFFIX
2847 \end_inset
2848 </cell>
2849 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2850 \begin_inset Text
2851
2852 \layout Standard
2853
2854 /usr/local/share/sdcc/
2855 \newline
2856 include
2857 \end_inset
2858 </cell>
2859 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2860 \begin_inset Text
2861
2862 \layout Standard
2863
2864 (not on Win32)
2865 \end_inset
2866 </cell>
2867 </row>
2868 </lyxtabular>
2869
2870 \end_inset
2871
2872
2873 \newline
2874
2875 \layout Standard
2876 \noindent
2877 The option -
2878 \begin_inset ERT
2879 status Collapsed
2880
2881 \layout Standard
2882
2883 \backslash
2884 /
2885 \end_inset
2886
2887 -nostdinc disables the last two search paths.
2888 \newline
2889
2890 \newline
2891 3.
2892  Library files
2893 \newline
2894
2895 \layout Standard
2896
2897 With the exception of
2898 \begin_inset Quotes sld
2899 \end_inset
2900
2901 -
2902 \begin_inset ERT
2903 status Collapsed
2904
2905 \layout Standard
2906
2907 \backslash
2908 /
2909 \end_inset
2910
2911 -L dir
2912 \begin_inset Quotes srd
2913 \end_inset
2914
2915  the
2916 \shape italic
2917 model
2918 \shape default
2919  is auto-appended by the compiler (e.g.
2920  small, large, z80, ds390 etc.).
2921
2922 \newline
2923
2924 \layout Standard
2925 \align center
2926
2927 \begin_inset  Tabular
2928 <lyxtabular version="3" rows="6" columns="3">
2929 <features>
2930 <column alignment="block" valignment="top" leftline="true" width="1.7in">
2931 <column alignment="block" valignment="top" leftline="true" width="1.2in">
2932 <column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
2933 <row topline="true" bottomline="true">
2934 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2935 \begin_inset Text
2936
2937 \layout Standard
2938
2939 Search path
2940 \end_inset
2941 </cell>
2942 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2943 \begin_inset Text
2944
2945 \layout Standard
2946
2947 default
2948 \end_inset
2949 </cell>
2950 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2951 \begin_inset Text
2952
2953 \layout Standard
2954
2955 Win32 builds
2956 \end_inset
2957 </cell>
2958 </row>
2959 <row topline="true">
2960 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2961 \begin_inset Text
2962
2963 \layout Standard
2964
2965 -
2966 \begin_inset ERT
2967 status Collapsed
2968
2969 \layout Standard
2970
2971 \backslash
2972 /
2973 \end_inset
2974
2975 -L dir
2976 \end_inset
2977 </cell>
2978 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2979 \begin_inset Text
2980
2981 \layout Standard
2982
2983 -
2984 \begin_inset ERT
2985 status Collapsed
2986
2987 \layout Standard
2988
2989 \backslash
2990 /
2991 \end_inset
2992
2993 -L dir
2994 \end_inset
2995 </cell>
2996 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2997 \begin_inset Text
2998
2999 \layout Standard
3000
3001 -
3002 \begin_inset ERT
3003 status Collapsed
3004
3005 \layout Standard
3006
3007 \backslash
3008 /
3009 \end_inset
3010
3011 -L dir
3012 \end_inset
3013 </cell>
3014 </row>
3015 <row topline="true">
3016 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3017 \begin_inset Text
3018
3019 \layout Standard
3020
3021 $SDCC_LIB/
3022 \newline
3023
3024 \emph on
3025 <model>
3026 \end_inset
3027 </cell>
3028 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3029 \begin_inset Text
3030
3031 \layout Standard
3032
3033 $SDCC_LIB/
3034 \newline
3035
3036 \emph on
3037 <model>
3038 \end_inset
3039 </cell>
3040 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3041 \begin_inset Text
3042
3043 \layout Standard
3044
3045 $SDCC_LIB
3046 \backslash
3047
3048 \newline
3049
3050 \emph on
3051 <model>
3052 \end_inset
3053 </cell>
3054 </row>
3055 <row topline="true">
3056 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3057 \begin_inset Text
3058
3059 \layout Standard
3060
3061 $SDCC_HOME/
3062 \newline
3063
3064 \emph on
3065 $PREFIX2DATA_DIR/
3066 \newline
3067 $LIB_DIR_SUFFIX/<model>
3068 \end_inset
3069 </cell>
3070 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3071 \begin_inset Text
3072
3073 \layout Standard
3074
3075 $SDCC_HOME/
3076 \newline
3077 share/sdcc/
3078 \newline
3079 lib/
3080 \emph on
3081 <model>
3082 \end_inset
3083 </cell>
3084 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3085 \begin_inset Text
3086
3087 \layout Standard
3088
3089 $SDCC_HOME
3090 \backslash
3091 lib
3092 \backslash
3093
3094 \emph on
3095
3096 \newline
3097 <model>
3098 \end_inset
3099 </cell>
3100 </row>
3101 <row topline="true">
3102 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3103 \begin_inset Text
3104
3105 \layout Standard
3106
3107 path(argv[0])/
3108 \newline
3109
3110 \emph on
3111 $BIN2DATADIR/
3112 \emph default
3113
3114 \newline
3115
3116 \emph on
3117 $LIB_DIR_SUFFIX/<model>
3118 \end_inset
3119 </cell>
3120 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3121 \begin_inset Text
3122
3123 \layout Standard
3124
3125 path(argv[0])/
3126 \newline
3127 ../sdcc/lib/
3128 \emph on
3129 <model>
3130 \newline
3131 \SpecialChar ~
3132 \SpecialChar ~
3133 \SpecialChar ~
3134 \SpecialChar ~
3135 \SpecialChar ~
3136 \SpecialChar ~
3137 \SpecialChar ~
3138 \SpecialChar ~
3139 \SpecialChar ~
3140 \SpecialChar ~
3141 \SpecialChar ~
3142 \SpecialChar ~
3143 \SpecialChar ~
3144 \SpecialChar ~
3145 \SpecialChar ~
3146 \SpecialChar ~
3147 \SpecialChar ~
3148 \SpecialChar ~
3149 \SpecialChar ~
3150 \SpecialChar ~
3151 \SpecialChar ~
3152 \SpecialChar ~
3153 \SpecialChar ~
3154 \SpecialChar ~
3155 \SpecialChar ~
3156 \SpecialChar ~
3157 \SpecialChar ~
3158 \SpecialChar ~
3159 \SpecialChar ~
3160 \SpecialChar ~
3161 \SpecialChar ~
3162 \SpecialChar ~
3163 \SpecialChar ~
3164 \SpecialChar ~
3165 \SpecialChar ~
3166 \SpecialChar ~
3167 \SpecialChar ~
3168 \SpecialChar ~
3169 \SpecialChar ~
3170
3171 \end_inset
3172 </cell>
3173 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3174 \begin_inset Text
3175
3176 \layout Standard
3177
3178 path(argv[0])
3179 \backslash
3180
3181 \newline
3182 ..
3183 \backslash
3184 lib
3185 \backslash
3186
3187 \emph on
3188 <model>
3189 \newline
3190 \SpecialChar ~
3191 \SpecialChar ~
3192 \SpecialChar ~
3193 \SpecialChar ~
3194 \SpecialChar ~
3195 \SpecialChar ~
3196 \SpecialChar ~
3197 \SpecialChar ~
3198 \SpecialChar ~
3199 \SpecialChar ~
3200 \SpecialChar ~
3201 \SpecialChar ~
3202 \SpecialChar ~
3203 \SpecialChar ~
3204 \SpecialChar ~
3205 \SpecialChar ~
3206 \SpecialChar ~
3207 \SpecialChar ~
3208 \SpecialChar ~
3209 \SpecialChar ~
3210 \SpecialChar ~
3211 \SpecialChar ~
3212 \SpecialChar ~
3213 \SpecialChar ~
3214 \SpecialChar ~
3215 \SpecialChar ~
3216 \SpecialChar ~
3217 \SpecialChar ~
3218 \SpecialChar ~
3219 \SpecialChar ~
3220 \SpecialChar ~
3221 \SpecialChar ~
3222 \SpecialChar ~
3223 \SpecialChar ~
3224 \SpecialChar ~
3225
3226 \end_inset
3227 </cell>
3228 </row>
3229 <row topline="true" bottomline="true">
3230 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3231 \begin_inset Text
3232
3233 \layout Standard
3234
3235
3236 \emph on
3237 $DATADIR/
3238 \newline
3239 $LIB_DIR_SUFFIX/<model>
3240 \end_inset
3241 </cell>
3242 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3243 \begin_inset Text
3244
3245 \layout Standard
3246
3247 /usr/local/share/sdcc/
3248 \newline
3249 lib/
3250 \emph on
3251 <model>
3252 \end_inset
3253 </cell>
3254 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3255 \begin_inset Text
3256
3257 \layout Standard
3258
3259 (not on Win32)
3260 \end_inset
3261 </cell>
3262 </row>
3263 </lyxtabular>
3264
3265 \end_inset
3266
3267
3268 \newline
3269
3270 \layout Comment
3271
3272 Don't delete any of the stray spaces in the table above without checking
3273  the HTML output (last line)!
3274 \layout Standard
3275
3276 \SpecialChar ~
3277
3278 \newline
3279 The option -
3280 \begin_inset ERT
3281 status Collapsed
3282
3283 \layout Standard
3284
3285 \backslash
3286 /
3287 \end_inset
3288
3289 -nostdlib disables the last two search paths.
3290 \layout Section
3291
3292 Building SDCC
3293 \begin_inset LatexCommand \index{Building SDCC}
3294
3295 \end_inset
3296
3297
3298 \layout Subsection
3299
3300 Building SDCC on Linux
3301 \begin_inset LatexCommand \label{sub:Building-SDCC-on-Linux}
3302
3303 \end_inset
3304
3305
3306 \layout Enumerate
3307
3308
3309 \series medium
3310 Download the source package
3311 \series default
3312  either from the SDCC Subversion repository or from the nightly snapshots
3313 \series medium
3314 , it will be named something like sdcc
3315 \series default
3316 .src
3317 \series medium
3318 .t
3319 \series default
3320 ar.
3321 \series medium
3322 gz
3323 \series default
3324
3325 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
3326
3327 \end_inset
3328
3329 .
3330 \layout Enumerate
3331
3332
3333 \series medium
3334 Bring up a command line terminal, such as xterm.
3335 \layout Enumerate
3336
3337
3338 \series medium
3339 Unpack the file using a command like:
3340 \family sans
3341 \series bold
3342 "tar -xvzf sdcc.src.tar.gz
3343 \family default
3344 \series default
3345 "
3346 \series medium
3347 , this will create a sub-directory called sdcc with all of the sources.
3348 \layout Enumerate
3349
3350 Change directory into the main SDCC directory, for example type:
3351 \family sans
3352 \series bold
3353 "cd sdcc
3354 \series default
3355 ".
3356 \layout Enumerate
3357
3358
3359 \series medium
3360 Type
3361 \family sans
3362 \series bold
3363 "./configure
3364 \family default
3365 \series default
3366 ".
3367  This configures the package for compilation on your system.
3368 \layout Enumerate
3369
3370
3371 \series medium
3372 Type
3373 \family sans
3374 \series bold
3375 "make
3376 \family default
3377 \series default
3378 "
3379 \series medium
3380 .
3381
3382 \series default
3383  All of the source packages will compile, this can take a while.
3384 \layout Enumerate
3385
3386
3387 \series medium
3388 Type
3389 \family sans
3390 \series bold
3391 "make install"
3392 \family default
3393 \series default
3394  as root
3395 \series medium
3396 .
3397
3398 \series default
3399  This copies the binary executables, the include files, the libraries and
3400  the documentation to the install directories.
3401  Proceed with section
3402 \begin_inset LatexCommand \ref{sec:Testing-the-SDCC}
3403
3404 \end_inset
3405
3406 .
3407 \layout Subsection
3408
3409 Building SDCC on OSX 2.x
3410 \layout Standard
3411
3412 Follow the instruction for Linux.
3413 \newline
3414
3415 \newline
3416 On OSX 2.x it was reported, that the default gcc (version 3.1 20020420 (prerelease
3417 )) fails to compile SDCC.
3418  Fortunately there's also gcc 2.9.x installed, which works fine.
3419  This compiler can be selected by running 'configure' with:
3420 \layout LyX-Code
3421
3422 ./configure CC=gcc2 CXX=g++2
3423 \layout Subsection
3424
3425 Cross compiling SDCC on Linux for Windows
3426 \layout Standard
3427
3428 With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32.
3429  See section 'Configure Options'.
3430 \layout Subsection
3431
3432 Building SDCC using Cygwin and Mingw32
3433 \layout Standard
3434
3435 For building and installing a Cygwin executable follow the instructions
3436  for Linux.
3437 \newline
3438
3439 \newline
3440 On Cygwin a
3441 \begin_inset Quotes sld
3442 \end_inset
3443
3444 native
3445 \begin_inset Quotes srd
3446 \end_inset
3447
3448  Win32-binary can be built, which will not need the Cygwin-DLL.
3449  For the necessary 'configure' options see section 'configure options' or
3450  the script 'sdcc/support/scripts/sdcc_cygwin_mingw32'.
3451 \newline
3452
3453 \newline
3454 In order to install Cygwin on Windows download setup.exe from
3455 \begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/}
3456
3457 \end_inset
3458
3459 .
3460  Run it, set the
3461 \begin_inset Quotes sld
3462 \end_inset
3463
3464 default text file type
3465 \begin_inset Quotes srd
3466 \end_inset
3467
3468  to
3469 \begin_inset Quotes sld
3470 \end_inset
3471
3472 unix
3473 \begin_inset Quotes srd
3474 \end_inset
3475
3476  and download/install at least the following packages.
3477  Some packages are selected by default, others will be automatically selected
3478  because of dependencies with the manually selected packages.
3479  Never deselect these packages!
3480 \layout Itemize
3481
3482 flex
3483 \layout Itemize
3484
3485 bison
3486 \layout Itemize
3487
3488 gcc ; version 3.x is fine, no need to use the old 2.9x
3489 \layout Itemize
3490
3491 binutils ; selected with gcc
3492 \layout Itemize
3493
3494 make
3495 \layout Itemize
3496
3497 rxvt ; a nice console, which makes life much easier under windoze (see below)
3498 \layout Itemize
3499
3500 man ; not really needed for building SDCC, but you'll miss it sooner or
3501  later
3502 \layout Itemize
3503
3504 less ; not really needed for building SDCC, but you'll miss it sooner or
3505  later
3506 \layout Itemize
3507
3508 svn ; only if you use Subversion access
3509 \layout Standard
3510
3511 If you want to develop something you'll need:
3512 \layout Itemize
3513
3514 python ; for the regression tests
3515 \layout Itemize
3516
3517 gdb ; the gnu debugger, together with the nice GUI
3518 \begin_inset Quotes sld
3519 \end_inset
3520
3521 insight
3522 \begin_inset Quotes srd
3523 \end_inset
3524
3525
3526 \layout Itemize
3527
3528 openssh ; to access the CF or commit changes
3529 \layout Itemize
3530
3531 autoconf and autoconf-devel ; if you want to fight with 'configure', don't
3532  use autoconf-stable!
3533 \layout Standard
3534
3535 rxvt is a nice console with history.
3536  Replace in your cygwin.bat the line
3537 \layout LyX-Code
3538
3539 bash -
3540 \begin_inset ERT
3541 status Collapsed
3542
3543 \layout Standard
3544
3545 \backslash
3546 /
3547 \end_inset
3548
3549 -login -i
3550 \layout Standard
3551
3552 with (one line):
3553 \layout LyX-Code
3554
3555 rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
3556 \layout LyX-Code
3557
3558      -bg black -fg white -geometry 100x65 -e bash -
3559 \begin_inset ERT
3560 status Collapsed
3561
3562 \layout Standard
3563
3564 \backslash
3565 /
3566 \end_inset
3567
3568 -login
3569 \layout Standard
3570
3571 Text selected with the mouse is automatically copied to the clipboard, pasting
3572  works with shift-insert.
3573 \newline
3574
3575 \newline
3576 The other good tip is to make sure you have no //c/-style paths anywhere,
3577  use /cygdrive/c/ instead.
3578  Using // invokes a network lookup which is very slow.
3579  If you think
3580 \begin_inset Quotes sld
3581 \end_inset
3582
3583 cygdrive
3584 \begin_inset Quotes srd
3585 \end_inset
3586
3587  is too long, you can change it with e.g.
3588 \layout LyX-Code
3589
3590 mount -s -u -c /mnt
3591 \layout Standard
3592
3593 SDCC sources use the unix line ending LF.
3594  Life is much easier, if you store the source tree on a drive which is mounted
3595  in binary mode.
3596  And use an editor which can handle LF-only line endings.
3597  Make sure not to commit files with windows line endings.
3598  The tabulator spacing
3599 \begin_inset LatexCommand \index{tabulator spacing (8 columns)}
3600
3601 \end_inset
3602
3603  used in the project is 8.
3604  Although a tabulator spacing of 8 is a sensible choice for programmers
3605  (it's a power of 2 and allows to display 8/16 bit signed variables without
3606  loosing columns) the plan is to move towards using only spaces in the source.
3607 \layout Subsection
3608
3609 Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
3610 \layout Standard
3611
3612
3613 \series medium
3614 Download the source package
3615 \series default
3616  either from the SDCC Subversion repository or from the
3617 \begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
3618
3619 \end_inset
3620
3621
3622 \series medium
3623 , it will be named something like sdcc
3624 \series default
3625 .src
3626 \series medium
3627 .tgz.
3628
3629 \series default
3630  SDCC is distributed with all the projects, workspaces, and files you need
3631  to build it using Visual C++ 6.0/NET (except for SDCDB and ucSim).
3632  The workspace name is 'sdcc.dsw'.
3633  Please note that as it is now, all the executables are created in a folder
3634  called sdcc
3635 \backslash
3636 bin_vc.
3637  Once built you need to copy the executables from sdcc
3638 \backslash
3639 bin_vc to sdcc
3640 \backslash
3641 bin before running SDCC.
3642
3643 \newline
3644
3645 \newline
3646 WARNING: Visual studio is very picky with line terminations; it expects
3647  the 0x0d, 0x0a DOS style line endings, not the 0x0a Unix style line endings.
3648  When using the Subversion repository it's easiest to configure the svn
3649  client to convert automatically for you.
3650  If however you are getting a message such as "This makefile was not generated
3651  by Developer Studio etc.
3652  etc.
3653 \begin_inset Quotes srd
3654 \end_inset
3655
3656  when opening the sdcc.dsw workspace or any of the *.dsp projects, then you
3657  need to convert the Unix style line endings to DOS style line endings.
3658  To do so you can use the
3659 \begin_inset Quotes sld
3660 \end_inset
3661
3662 unix2dos
3663 \begin_inset Quotes srd
3664 \end_inset
3665
3666  utility freely available on the internet.
3667  Doug Hawkins reported in the sdcc-user list that this works:
3668 \newline
3669
3670 \newline
3671 C:
3672 \backslash
3673 Programming
3674 \backslash
3675 SDCC> unix2dos sdcc.dsw
3676 \newline
3677 C:
3678 \backslash
3679 Programming
3680 \backslash
3681 SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
3682 \newline
3683
3684 \newline
3685 In order to build SDCC with MSVC you need win32 executables of bison.exe,
3686  flex.exe, and gawk.exe.
3687  One good place to get them is
3688 \begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}
3689
3690 \end_inset
3691
3692
3693 \newline
3694
3695 \newline
3696 Download the file UnxUtils
3697 \begin_inset LatexCommand \index{UnxUtils}
3698
3699 \end_inset
3700
3701 .zip.
3702  Now you have to install the utilities and setup MSVC so it can locate the
3703  required programs.
3704  Here there are two alternatives (choose one!):
3705 \layout Enumerate
3706
3707 The easy way:
3708 \newline
3709
3710 \newline
3711 a) Extract UnxUtils.zip to your C:
3712 \backslash
3713  hard disk PRESERVING the original paths, otherwise bison won't work.
3714  (If you are using WinZip make certain that 'Use folder names' is selected)
3715 \newline
3716
3717 \newline
3718 b) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3719  in 'Show directories for:' select 'Executable files', and in the directories
3720  window add a new path: 'C:
3721 \backslash
3722 user
3723 \backslash
3724 local
3725 \backslash
3726 wbin', click ok.
3727 \newline
3728
3729 \newline
3730 (As a side effect, you get a bunch of Unix utilities that could be useful,
3731  such as diff and patch.)
3732 \layout Enumerate
3733
3734 A more compact way:
3735 \newline
3736
3737 \newline
3738 This one avoids extracting a bunch of files you may not use, but requires
3739  some extra work:
3740 \newline
3741
3742 \newline
3743 a) Create a directory were to put the tools needed, or use a directory already
3744  present.
3745  Say for example 'C:
3746 \backslash
3747 util'.
3748 \newline
3749
3750 \newline
3751 b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe
3752  to such directory WITHOUT preserving the original paths.
3753  (If you are using WinZip make certain that 'Use folder names' is not selected)
3754 \newline
3755
3756 \newline
3757 c) Rename bison.exe to '_bison.exe'.
3758 \newline
3759
3760 \newline
3761 d) Create a batch file 'bison.bat' in 'C:
3762 \backslash
3763 util
3764 \backslash
3765 ' and add these lines:
3766 \newline
3767 \SpecialChar ~
3768 \SpecialChar ~
3769 set BISON_SIMPLE=C:
3770 \backslash
3771 util
3772 \backslash
3773 bison.simple
3774 \newline
3775 \SpecialChar ~
3776 \SpecialChar ~
3777 set BISON_HAIRY=C:
3778 \backslash
3779 util
3780 \backslash
3781 bison.hairy
3782 \newline
3783 \SpecialChar ~
3784 \SpecialChar ~
3785 _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
3786 \newline
3787
3788 \newline
3789 Steps 'c' and 'd' are needed because bison requires by default that the
3790  files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory,
3791  '/usr/local/share/' I think.
3792  So it is necessary to tell bison where those files are located if they
3793  are not in such directory.
3794  That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
3795 \newline
3796
3797 \newline
3798 e) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3799  in 'Show directories for:' select 'Executable files', and in the directories
3800  window add a new path: 'c:
3801 \backslash
3802 util', click ok.
3803  Note that you can use any other path instead of 'c:
3804 \backslash
3805 util', even the path where the Visual C++ tools are, probably: 'C:
3806 \backslash
3807 Program Files
3808 \backslash
3809 Microsoft Visual Studio
3810 \backslash
3811 Common
3812 \backslash
3813 Tools'.
3814  So you don't have to execute step 'e' :)
3815 \layout Standard
3816
3817 That is it.
3818  Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
3819  the executables from sdcc
3820 \backslash
3821 bin_vc to sdcc
3822 \backslash
3823 bin, and you can compile using SDCC.
3824 \layout Subsection
3825
3826 Building SDCC Using Borland
3827 \layout Enumerate
3828
3829 From the sdcc directory, run the command "make -f Makefile.bcc".
3830  This should regenerate all the .exe files in the bin directory except for
3831  SDCDB and ucSim.
3832 \layout Enumerate
3833
3834 If you modify any source files and need to rebuild, be aware that the dependenci
3835 es may not be correctly calculated.
3836  The safest option is to delete all .obj files and run the build again.
3837  From a Cygwin BASH prompt, this can easily be done with the command (be
3838  sure you are in the sdcc directory):
3839 \newline
3840
3841 \newline
3842
3843 \family sans
3844 \series bold
3845 find .
3846
3847 \backslash
3848 ( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
3849 \backslash
3850 ) -print -exec rm {}
3851 \backslash
3852 ;
3853 \family default
3854 \series default
3855
3856 \newline
3857
3858 \newline
3859 or on Windows NT/2000/XP from the command prompt with the command:
3860 \newline
3861
3862 \family sans
3863 \series bold
3864
3865 \newline
3866 del /s *.obj *.lib *.rul
3867 \family default
3868 \series default
3869  from the sdcc directory.
3870 \layout Subsection
3871
3872 Windows Install Using a ZIP Package
3873 \layout Enumerate
3874
3875 Download the binary zip package from
3876 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3877
3878 \end_inset
3879
3880  and unpack it using your favorite unpacking tool (gunzip, WinZip, etc).
3881  This should unpack to a group of sub-directories.
3882  An example directory structure after unpacking the mingw32 package is:
3883  c:
3884 \backslash
3885 sdcc
3886 \backslash
3887 bin for the executables, c:
3888 \backslash
3889 sdcc
3890 \backslash
3891 include and c:
3892 \backslash
3893 sdcc
3894 \backslash
3895 lib for the include and libraries.
3896 \layout Enumerate
3897
3898 Adjust your environment variable PATH to include the location of the bin
3899  directory or start sdcc using the full path.
3900 \layout Subsection
3901
3902 Windows Install Using the Setup Program
3903 \begin_inset LatexCommand \label{sub:Windows-Install}
3904
3905 \end_inset
3906
3907
3908 \layout Standard
3909
3910 Download the setup program
3911 \emph on
3912 sdcc-x.y.z-setup.exe
3913 \emph default
3914  for an official release from
3915 \newline
3916
3917 \begin_inset LatexCommand \url{http://sf.net/project/showfiles.php?group_id=599}
3918
3919 \end_inset
3920
3921  or a setup program for one of the snapshots
3922 \emph on
3923 sdcc-yyyymmdd-xxxx-setup.exe
3924 \emph default
3925  from
3926 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3927
3928 \end_inset
3929
3930  and execute it.
3931  A windows typical installer will guide you through the installation process.
3932 \layout Subsection
3933
3934 VPATH
3935 \begin_inset LatexCommand \index{VPATH}
3936
3937 \end_inset
3938
3939  feature
3940 \layout Standard
3941
3942 SDCC supports the VPATH feature provided by configure and make.
3943  It allows to separate the source and build trees.
3944  Here's an example:
3945 \layout Standard
3946
3947
3948 \family typewriter
3949 cd ~\SpecialChar ~
3950 \SpecialChar ~
3951 \SpecialChar ~
3952 \SpecialChar ~
3953 \SpecialChar ~
3954 \SpecialChar ~
3955 \SpecialChar ~
3956 \SpecialChar ~
3957 \SpecialChar ~
3958 \SpecialChar ~
3959 \SpecialChar ~
3960 \SpecialChar ~
3961 \SpecialChar ~
3962 \SpecialChar ~
3963 \SpecialChar ~
3964 \SpecialChar ~
3965 \SpecialChar ~
3966 \SpecialChar ~
3967 \SpecialChar ~
3968 \SpecialChar ~
3969 \SpecialChar ~
3970 # cd $HOME
3971 \layout Standard
3972
3973
3974 \family typewriter
3975 tar -xzf sdcc.src.tar.gz\SpecialChar ~
3976 # extract source to directory sdcc
3977 \layout Standard
3978
3979
3980 \family typewriter
3981 mkdir sdcc.build\SpecialChar ~
3982 \SpecialChar ~
3983 \SpecialChar ~
3984 \SpecialChar ~
3985 \SpecialChar ~
3986 \SpecialChar ~
3987 \SpecialChar ~
3988 \SpecialChar ~
3989 \SpecialChar ~
3990 # put output in sdcc.build
3991 \layout Standard
3992
3993
3994 \family typewriter
3995 cd sdcc.build
3996 \layout Standard
3997
3998
3999 \family typewriter
4000 ../sdcc/configure\SpecialChar ~
4001 \SpecialChar ~
4002 \SpecialChar ~
4003 \SpecialChar ~
4004 \SpecialChar ~
4005 \SpecialChar ~
4006 \SpecialChar ~
4007 \SpecialChar ~
4008 # configure is doing all the magic!
4009 \layout Standard
4010
4011
4012 \family typewriter
4013 make
4014 \layout Standard
4015 \noindent
4016 That's it!
4017 \series bold
4018 configure
4019 \series default
4020  will create the directory tree will all the necessary Makefiles in ~/sdcc.build.
4021  It automagically computes the variables srcdir, top_srcdir and top_buildir
4022  for each directory.
4023  After running
4024 \series bold
4025 make
4026 \series default
4027  the generated files will be in ~/sdcc.build, while the source files stay
4028  in ~/sdcc.
4029 \newline
4030 This is not only usefull for building different binaries, e.g.
4031  when cross compiling.
4032  It also gives you a much better overview in the source tree when all the
4033  generated files are not scattered between the source files.
4034  And the best thing is: if you want to change a file you can leave the original
4035  file untouched in the source directory.
4036  Simply copy it to the build directory, edit it, enter `make clean`, `rm
4037  Makefile.dep` and `make`.
4038
4039 \series bold
4040 make
4041 \series default
4042  will do the rest for you!
4043 \layout Section
4044
4045 Building the Documentation
4046 \layout Standard
4047
4048 Add -
4049 \begin_inset ERT
4050 status Collapsed
4051
4052 \layout Standard
4053
4054 \backslash
4055 /
4056 \end_inset
4057
4058 -enable-doc to the configure arguments to build the documentation together
4059  with all the other stuff.
4060  You will need several tools (LyX, LaTeX, LaTeX2HTML, pdflatex, dvipdf,
4061  dvips and makeindex) to get the job done.
4062  Another possibility is to change to the doc directory and to type
4063 \family sans
4064 \series bold
4065
4066 \begin_inset Quotes srd
4067 \end_inset
4068
4069 make
4070 \begin_inset Quotes srd
4071 \end_inset
4072
4073
4074 \family default
4075 \series default
4076  there.
4077  You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
4078 x).
4079  Using LyX
4080 \begin_inset LatexCommand \url{http://www.lyx.org}
4081
4082 \end_inset
4083
4084  as editor is straightforward.
4085  Prebuilt documentation in html and pdf format is available from
4086 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
4087
4088 \end_inset
4089
4090 .
4091 \layout Section
4092
4093 Reading the Documentation
4094 \begin_inset LatexCommand \index{Documentation}
4095
4096 \end_inset
4097
4098
4099 \layout Standard
4100
4101 Currently reading the document in pdf format is recommended, as for unknown
4102  reason the hyperlinks are working there whereas in the html version they
4103  are not
4104 \begin_inset Foot
4105 collapsed false
4106
4107 \layout Standard
4108
4109 If you should know why please drop us a note
4110 \end_inset
4111
4112 .
4113
4114 \newline
4115 You'll find the pdf version
4116 \begin_inset LatexCommand \index{PDF version of this document}
4117
4118 \end_inset
4119
4120  at
4121 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.pdf}
4122
4123 \end_inset
4124
4125 .
4126
4127 \newline
4128 A html version
4129 \begin_inset LatexCommand \index{HTML version of this document}
4130
4131 \end_inset
4132
4133  should be online at
4134 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.html/index.html}
4135
4136 \end_inset
4137
4138 .
4139 \newline
4140 This documentation is in some aspects different from a commercial documentation:
4141
4142 \layout Itemize
4143
4144 It tries to document SDCC for several processor architectures in one document
4145  (commercially these probably would be separate documents/products).
4146  This document
4147 \begin_inset LatexCommand \index{Status of documentation}
4148
4149 \end_inset
4150
4151  currently matches SDCC for mcs51 and DS390 best and does give too few informati
4152 on about f.e.
4153  Z80, PIC14, PIC16 and HC08.
4154 \layout Itemize
4155
4156 There are many references pointing away from this documentation.
4157  Don't let this distract you.
4158  If there f.e.
4159  was a reference like
4160 \begin_inset LatexCommand \url{http://www.opencores.org}
4161
4162 \end_inset
4163
4164  together with a statement
4165 \begin_inset Quotes sld
4166 \end_inset
4167
4168 some processors which are targetted by SDCC can be implemented in a
4169 \emph on
4170 f
4171 \emph default
4172 ield
4173 \emph on
4174 p
4175 \emph default
4176 rogrammable
4177 \emph on
4178 g
4179 \emph default
4180 ate
4181 \emph on
4182 a
4183 \emph default
4184 rray
4185 \begin_inset LatexCommand \index{FPGA (field programmable gate array)}
4186
4187 \end_inset
4188
4189
4190 \begin_inset Quotes srd
4191 \end_inset
4192
4193  or
4194 \begin_inset LatexCommand \url{http://sf.net/projects/fpgac}
4195
4196 \end_inset
4197
4198
4199 \begin_inset LatexCommand \index{FpgaC ((subset of) C to FPGA compiler)}
4200
4201 \end_inset
4202
4203
4204 \begin_inset Quotes sld
4205 \end_inset
4206
4207 have you ever heard of an open source compiler that compiles a subset of
4208  C for an FPGA?
4209 \begin_inset Quotes srd
4210 \end_inset
4211
4212  we expect you to have a quick look there and come back.
4213  If you read this you are on the right track.
4214 \layout Itemize
4215
4216 Some sections attribute more space to problems, restrictions and warnings
4217  than to the solution.
4218 \layout Itemize
4219
4220 The installation section and the section about the debugger is intimidating.
4221 \layout Itemize
4222
4223 There are still lots of typos and there are more different writing styles
4224  than pictures.
4225 \layout Section
4226
4227 Testing the SDCC Compiler
4228 \begin_inset LatexCommand \label{sec:Testing-the-SDCC}
4229
4230 \end_inset
4231
4232
4233 \layout Standard
4234
4235 The first thing you should do after installing your SDCC compiler is to
4236  see if it runs.
4237  Type
4238 \family sans
4239 \series bold
4240 "sdcc -
4241 \begin_inset ERT
4242 status Collapsed
4243
4244 \layout Standard
4245
4246 \backslash
4247 /
4248 \end_inset
4249
4250 -version"
4251 \begin_inset LatexCommand \index{version}
4252
4253 \end_inset
4254
4255
4256 \family default
4257 \series default
4258  at the prompt, and the program should run and output its version like:
4259
4260 \newline
4261
4262 \family typewriter
4263 SDCC : mcs51/z80/avr/ds390/pic16/pic14/ds400/hc08 2.5.6 #4169 (May 8 2006)
4264  (UNIX)
4265 \layout Standard
4266
4267 If it doesn't run, or gives a message about not finding sdcc program, then
4268  you need to check over your installation.
4269  Make sure that the sdcc bin directory is in your executable search path
4270  defined by the PATH environment setting (
4271 \series medium
4272 see
4273 \series default
4274 section
4275 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
4276
4277 \end_inset
4278
4279 \SpecialChar ~
4280
4281 \series medium
4282 Install trouble-shooting for suggestions
4283 \series default
4284 ).
4285  Make sure that the sdcc program is in the bin folder, if not perhaps something
4286  did not install correctly.
4287 \newline
4288
4289 \newline
4290
4291 \series medium
4292 SDCC
4293 \series default
4294 is commonly installed as described in section
4295 \begin_inset Quotes sld
4296 \end_inset
4297
4298 Install and search paths
4299 \begin_inset Quotes srd
4300 \end_inset
4301
4302 .
4303 \newline
4304
4305 \newline
4306
4307 \series medium
4308 Make sure the compiler works on a very simple example.
4309  Type in the following test.c program using your favorite
4310 \series default
4311 ASCII
4312 \series medium
4313 editor:
4314 \layout Verse
4315
4316
4317 \family typewriter
4318 char test;
4319 \newline
4320
4321 \newline
4322 void main(void) {
4323 \newline
4324 \SpecialChar ~
4325 \SpecialChar ~
4326 \SpecialChar ~
4327 \SpecialChar ~
4328 test=0;
4329 \newline
4330 }
4331 \layout Standard
4332
4333
4334 \series medium
4335 Compile this using the following command:
4336 \family sans
4337 \series bold
4338 "sdcc -c test.c".
4339
4340 \family default
4341 \series default
4342
4343 \series medium
4344 If all goes well, the compiler will generate a test.asm and test.rel file.
4345  Congratulations, you've just compiled your first program with SDCC.
4346  We used the -c option to tell SDCC not to link the generated code, just
4347  to keep things simple for this step.
4348 \series default
4349
4350 \newline
4351
4352 \newline
4353
4354 \series medium
4355 The next step is to try it with the linker.
4356  Type in
4357 \family sans
4358 \series bold
4359 "sdcc test.c
4360 \family default
4361 \series default
4362 "
4363 \series medium
4364 .
4365  If all goes well the compiler will link with the libraries and produce
4366  a test.ihx output file.
4367  If this step fails
4368 \series default
4369
4370 \series medium
4371 (no test.ihx, and the linker generates warnings), then the problem is most
4372  likely that
4373 \series default
4374 SDCC
4375 \series medium
4376  cannot find the
4377 \series default
4378 /
4379 \series medium
4380 usr/local/share/sdcc/lib directory
4381 \series default
4382
4383 \series medium
4384 (see
4385 \series default
4386 section
4387 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
4388
4389 \end_inset
4390
4391 \SpecialChar ~
4392
4393 \series medium
4394 Install trouble-shooting for suggestions).
4395 \series default
4396
4397 \newline
4398
4399 \newline
4400
4401 \series medium
4402 The final test is to ensure
4403 \series default
4404 SDCC
4405 \series medium
4406  can use the
4407 \series default
4408 standard
4409 \series medium
4410  header files and libraries.
4411  Edit test.c and change it to the following:
4412 \layout Verse
4413
4414
4415 \family typewriter
4416 #include <string.h>
4417 \newline
4418
4419 \newline
4420 char str1[10];
4421 \newline
4422
4423 \newline
4424 void main(void) {
4425 \newline
4426 \SpecialChar ~
4427 \SpecialChar ~
4428 strcpy(str1, "testing");
4429 \newline
4430 }
4431 \layout Standard
4432
4433
4434 \series medium
4435 Compile this by typing
4436 \family sans
4437 \series bold
4438 "sdcc test.c"
4439 \family default
4440 \series medium
4441 .
4442  This should generate a test.ihx output file, and it should give no warnings
4443  such as not finding the string.h file.
4444  If it cannot find the string.h file, then the problem is that
4445 \series default
4446 SDCC
4447 \series medium
4448  cannot find the /usr/local/share/sdcc/include directory
4449 \series default
4450
4451 \series medium
4452 (see the
4453 \series default
4454 section
4455 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
4456
4457 \end_inset
4458
4459 \SpecialChar ~
4460
4461 \series medium
4462 Install trouble-shooting section for suggestions).
4463
4464 \series default
4465  Use option
4466 \series bold
4467 -
4468 \begin_inset ERT
4469 status Collapsed
4470
4471 \layout Standard
4472
4473 \backslash
4474 /
4475 \end_inset
4476
4477 -print-search-dirs
4478 \series default
4479
4480 \begin_inset LatexCommand \index{-\/-print-search-dirs}
4481
4482 \end_inset
4483
4484  to find exactly where SDCC is looking for the include and lib files.
4485 \layout Section
4486
4487 Install Trouble-shooting
4488 \begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
4489
4490 \end_inset
4491
4492
4493 \begin_inset LatexCommand \index{Install trouble-shooting}
4494
4495 \end_inset
4496
4497
4498 \layout Subsection
4499
4500 If SDCC does not build correctly
4501 \layout Standard
4502
4503 A thing to try is starting from scratch by unpacking the .tgz source package
4504  again in an empty directory.
4505  Configure it like:
4506 \newline
4507
4508 \newline
4509
4510 \family sans
4511 \series bold
4512 ./configure 2>&1 | tee configure.log
4513 \family default
4514 \series default
4515
4516 \newline
4517
4518 \newline
4519 and build it like:
4520 \newline
4521
4522 \newline
4523
4524 \family sans
4525 \series bold
4526 make 2>&1 | tee make.log
4527 \family default
4528 \series default
4529
4530 \newline
4531
4532 \newline
4533 If anything goes wrong, you can review the log files to locate the problem.
4534  Or a relevant part of this can be attached to an email that could be helpful
4535  when requesting help from the mailing list.
4536 \layout Subsection
4537
4538 What the
4539 \begin_inset Quotes sld
4540 \end_inset
4541
4542 ./configure
4543 \begin_inset Quotes srd
4544 \end_inset
4545
4546  does
4547 \layout Standard
4548
4549 The
4550 \begin_inset Quotes sld
4551 \end_inset
4552
4553 ./configure
4554 \begin_inset Quotes srd
4555 \end_inset
4556
4557  command is a script that analyzes your system and performs some configuration
4558  to ensure the source package compiles on your system.
4559  It will take a few minutes to run, and will compile a few tests to determine
4560  what compiler features are installed.
4561 \layout Subsection
4562
4563 What the
4564 \begin_inset Quotes sld
4565 \end_inset
4566
4567 make
4568 \begin_inset Quotes srd
4569 \end_inset
4570
4571  does
4572 \layout Standard
4573
4574 This runs the GNU make tool, which automatically compiles all the source
4575  packages into the final installed binary executables.
4576 \layout Subsection
4577
4578 What the
4579 \begin_inset Quotes sld
4580 \end_inset
4581
4582 make install
4583 \begin_inset Quotes erd
4584 \end_inset
4585
4586  command does.
4587 \layout Standard
4588
4589 This will install the compiler, other executables libraries and include
4590  files into the appropriate directories.
4591  See sections
4592 \begin_inset LatexCommand \ref{sub:Install-paths}
4593
4594 \end_inset
4595
4596 ,\SpecialChar ~
4597
4598 \begin_inset LatexCommand \ref{sub:Search-Paths}
4599
4600 \end_inset
4601
4602 \SpecialChar ~
4603 about install and search paths.
4604 \newline
4605 On most systems you will need super-user privileges to do this.
4606 \layout Section
4607
4608 Components of SDCC
4609 \layout Standard
4610
4611 SDCC is not just a compiler, but a collection of tools by various developers.
4612  These include linkers, assemblers, simulators and other components.
4613  Here is a summary of some of the components.
4614  Note that the included simulator and assembler have separate documentation
4615  which you can find in the source package in their respective directories.
4616  As SDCC grows to include support for other processors, other packages from
4617  various developers are included and may have their own sets of documentation.
4618 \newline
4619
4620 \newline
4621 You might want to look at the files which are installed in <installdir>.
4622  At the time of this writing, we find the following programs for gcc-builds:
4623 \newline
4624
4625 \newline
4626 In <installdir>/bin:
4627 \layout Itemize
4628
4629 sdcc - The compiler.
4630 \layout Itemize
4631
4632 sdcpp - The C preprocessor.
4633 \layout Itemize
4634
4635 asx8051 - The assembler for 8051 type processors.
4636 \layout Itemize
4637
4638 as-z80
4639 \series bold
4640 ,
4641 \series default
4642 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
4643 \layout Itemize
4644
4645 aslink -The linker for 8051 type processors.
4646 \layout Itemize
4647
4648 link-z80
4649 \series bold
4650 ,
4651 \series default
4652 link-gbz80 - The Z80 and GameBoy Z80 linkers.
4653 \layout Itemize
4654
4655 s51 - The ucSim 8051 simulator.
4656 \layout Itemize
4657
4658 sdcdb - The source debugger.
4659 \layout Itemize
4660
4661 packihx - A tool to pack (compress) Intel hex files.
4662 \layout Standard
4663
4664 In <installdir>/share/sdcc/include
4665 \layout Itemize
4666
4667 the include files
4668 \layout Standard
4669
4670 In <installdir>/share/sdcc/lib
4671 \layout Itemize
4672
4673 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
4674  relocatables.
4675 \layout Standard
4676
4677 In <installdir>/share/sdcc/doc
4678 \layout Itemize
4679
4680 the documentation
4681 \layout Standard
4682
4683 As development for other processors proceeds, this list will expand to include
4684  executables to support processors like AVR, PIC, etc.
4685 \layout Subsection
4686
4687 sdcc - The Compiler
4688 \layout Standard
4689
4690 This is the actual compiler, it in turn uses the c-preprocessor and invokes
4691  the assembler and linkage editor.
4692 \layout Subsection
4693
4694 sdcpp - The C-Preprocessor
4695 \layout Standard
4696
4697 The preprocessor
4698 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
4699
4700 \end_inset
4701
4702  is a modified version of the GNU cpp
4703 \begin_inset LatexCommand \index{cpp|see{sdcpp}}
4704
4705 \end_inset
4706
4707  preprocessor
4708 \begin_inset LatexCommand \url{http://gcc.gnu.org/}
4709
4710 \end_inset
4711
4712 .
4713  The C preprocessor is used to pull in #include sources, process #ifdef
4714  statements, #defines and so on.
4715 \layout Subsection
4716
4717 as
4718 \emph on
4719 xxxx
4720 \emph default
4721 , aslink, link-
4722 \emph on
4723 xxx
4724 \emph default
4725  - The Assemblers and Linkage Editors
4726 \layout Standard
4727
4728 This is retargettable assembler & linkage editor, it was developed by Alan
4729  Baldwin.
4730  John Hartman created the version for 8051, and I (Sandeep) have made some
4731  enhancements and bug fixes for it to work properly with SDCC.
4732 \layout Subsection
4733
4734 s51 - The Simulator
4735 \layout Standard
4736
4737 S51
4738 \begin_inset LatexCommand \index{s51}
4739
4740 \end_inset
4741
4742  is a freeware, opensource simulator developed by Daniel Drotos.
4743  The simulator is built as part of the build process.
4744  For more information visit Daniel's web site at:
4745 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
4746
4747 \end_inset
4748
4749 .
4750  It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
4751  XA51 family.
4752 \layout Subsection
4753
4754 sdcdb - Source Level Debugger
4755 \layout Standard
4756
4757 SDCDB
4758 \begin_inset LatexCommand \index{SDCDB (debugger)}
4759
4760 \end_inset
4761
4762  is the companion source level debugger.
4763  More about SDCDB in section
4764 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
4765
4766 \end_inset
4767
4768 .
4769  The current version of the debugger uses Daniel's Simulator S51
4770 \begin_inset LatexCommand \index{s51}
4771
4772 \end_inset
4773
4774 , but can be easily changed to use other simulators.
4775 \layout Chapter
4776
4777 Using SDCC
4778 \layout Section
4779
4780 Compiling
4781 \layout Subsection
4782
4783 Single Source File Projects
4784 \layout Standard
4785
4786 For single source file 8051 projects the process is very simple.
4787  Compile your programs with the following command
4788 \family sans
4789 \series bold
4790 "sdcc sourcefile.c".
4791
4792 \family default
4793 \series default
4794  This will compile, assemble and link your source file.
4795  Output files are as follows:
4796 \layout Itemize
4797
4798 sourcefile.asm
4799 \begin_inset LatexCommand \index{<file>.asm}
4800
4801 \end_inset
4802
4803  - Assembler source
4804 \begin_inset LatexCommand \index{Assembler source}
4805
4806 \end_inset
4807
4808  file created by the compiler
4809 \layout Itemize
4810
4811 sourcefile.lst
4812 \begin_inset LatexCommand \index{<file>.lst}
4813
4814 \end_inset
4815
4816  - Assembler listing
4817 \begin_inset LatexCommand \index{Assembler listing}
4818
4819 \end_inset
4820
4821  file created by the Assembler
4822 \layout Itemize
4823
4824 sourcefile.rst
4825 \begin_inset LatexCommand \index{<file>.rst}
4826
4827 \end_inset
4828
4829  - Assembler listing
4830 \begin_inset LatexCommand \index{Assembler listing}
4831
4832 \end_inset
4833
4834  file updated with linkedit information, created by linkage editor
4835 \layout Itemize
4836
4837 sourcefile.sym
4838 \begin_inset LatexCommand \index{<file>.sym}
4839
4840 \end_inset
4841
4842  - symbol listing
4843 \begin_inset LatexCommand \index{Symbol listing}
4844
4845 \end_inset
4846
4847  for the sourcefile, created by the assembler
4848 \layout Itemize
4849
4850 sourcefile.rel
4851 \begin_inset LatexCommand \index{<file>.rel}
4852
4853 \end_inset
4854
4855  or sourcefile.o
4856 \begin_inset LatexCommand \index{<file>.o}
4857
4858 \end_inset
4859
4860  - Object file
4861 \begin_inset LatexCommand \index{Object file}
4862
4863 \end_inset
4864
4865  created by the assembler, input to Linkage editor
4866 \layout Itemize
4867
4868 sourcefile.map
4869 \begin_inset LatexCommand \index{<file>.map}
4870
4871 \end_inset
4872
4873  - The memory map
4874 \begin_inset LatexCommand \index{Memory map}
4875
4876 \end_inset
4877
4878  for the load module, created by the Linker
4879 \layout Itemize
4880
4881 sourcefile.mem
4882 \begin_inset LatexCommand \index{<file>.mem}
4883
4884 \end_inset
4885
4886  - A file with a summary of the memory usage
4887 \layout Itemize
4888
4889 sourcefile.ihx
4890 \begin_inset LatexCommand \index{<file>.ihx}
4891
4892 \end_inset
4893
4894  - The load module in Intel hex format
4895 \begin_inset LatexCommand \index{Intel hex format}
4896
4897 \end_inset
4898
4899  (you can select the Motorola S19 format
4900 \begin_inset LatexCommand \index{Motorola S19 format}
4901
4902 \end_inset
4903
4904  with -
4905 \begin_inset ERT
4906 status Collapsed
4907
4908 \layout Standard
4909
4910 \backslash
4911 /
4912 \end_inset
4913
4914 -out-fmt-s19
4915 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
4916
4917 \end_inset
4918
4919 .
4920  If you need another format you might want to use
4921 \family sans
4922 \shape italic
4923 objdump
4924 \family default
4925 \shape default
4926
4927 \begin_inset LatexCommand \index{objdump (tool)}
4928
4929 \end_inset
4930
4931  or
4932 \family sans
4933 \shape italic
4934  srecord
4935 \family default
4936 \shape default
4937
4938 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
4939
4940 \end_inset
4941
4942 ).
4943  Both formats are documented in the documentation of srecord
4944 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
4945
4946 \end_inset
4947
4948
4949 \layout Itemize
4950
4951 sourcefile.adb
4952 \begin_inset LatexCommand \index{<file>.adb}
4953
4954 \end_inset
4955
4956  - An intermediate file containing debug information needed to create the
4957  .cdb file (with -
4958 \begin_inset ERT
4959 status Collapsed
4960
4961 \layout Standard
4962
4963 \backslash
4964 /
4965 \end_inset
4966
4967 -debug
4968 \begin_inset LatexCommand \index{-\/-debug}
4969
4970 \end_inset
4971
4972 )
4973 \layout Itemize
4974
4975 sourcefile.cdb
4976 \begin_inset LatexCommand \index{<file>.cdb}
4977
4978 \end_inset
4979
4980  - An optional file (with -
4981 \begin_inset ERT
4982 status Collapsed
4983
4984 \layout Standard
4985
4986 \backslash
4987 /
4988 \end_inset
4989
4990 -debug) containing debug information.
4991  The format is documented in cdbfileformat.pdf
4992 \layout Itemize
4993
4994 sourcefile.
4995  - (no extension)
4996 \begin_inset LatexCommand \index{<file> (no extension)}
4997
4998 \end_inset
4999
5000  An optional AOMF or AOMF51
5001 \begin_inset LatexCommand \index{AOMF, AOMF51}
5002
5003 \end_inset
5004
5005
5006 \begin_inset LatexCommand \label{OMF file}
5007
5008 \end_inset
5009
5010 file containing debug information (generated with option -
5011 \begin_inset ERT
5012 status Collapsed
5013
5014 \layout Standard
5015
5016 \backslash
5017 /
5018 \end_inset
5019
5020 -debug).
5021  The (Intel)
5022 \emph on
5023  a
5024 \emph default
5025 bsolute
5026 \emph on
5027 o
5028 \emph default
5029 bject
5030 \emph on
5031 m
5032 \emph default
5033 odule
5034 \emph on
5035 f
5036 \emph default
5037 ormat is commonly used by third party tools (debuggers
5038 \begin_inset LatexCommand \index{Debugger}
5039
5040 \end_inset
5041
5042 , simulators, emulators)
5043 \layout Itemize
5044
5045 sourcefile.dump*
5046 \begin_inset LatexCommand \index{<file>.dump*}
5047
5048 \end_inset
5049
5050  - Dump file to debug the compiler it self (generated with option -
5051 \begin_inset ERT
5052 status Collapsed
5053
5054 \layout Standard
5055
5056 \backslash
5057 /
5058 \end_inset
5059
5060 -dumpall) (see section
5061 \begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
5062
5063 \end_inset
5064
5065 \SpecialChar ~
5066  and section
5067 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
5068
5069 \end_inset
5070
5071 \SpecialChar ~
5072
5073 \begin_inset Quotes sld
5074 \end_inset
5075
5076 Anatomy of the compiler
5077 \begin_inset Quotes srd
5078 \end_inset
5079
5080 ).
5081 \layout Subsection
5082
5083 Postprocessing the Intel Hex
5084 \begin_inset LatexCommand \index{Intel hex format}
5085
5086 \end_inset
5087
5088  file
5089 \layout Standard
5090
5091 In most cases this won't be needed but the Intel Hex file
5092 \begin_inset LatexCommand \index{<file>.ihx}
5093
5094 \end_inset
5095
5096  which is generated by SDCC might include lines of varying length and the
5097  addresses within the file are not guaranteed to be strictly ascending.
5098  If your toolchain or a bootloader does not like this you can use the tool
5099
5100 \family typewriter
5101 packihx
5102 \family default
5103
5104 \begin_inset LatexCommand \index{packihx (tool)}
5105
5106 \end_inset
5107
5108  which is part of the SDCC distribution:
5109 \newline
5110
5111 \newline
5112
5113 \family sans
5114 \series bold
5115  packihx sourcefile.ihx >sourcefile.hex
5116 \family default
5117 \series default
5118
5119 \newline
5120
5121 \newline
5122 The separately available
5123 \emph on
5124  srecord
5125 \emph default
5126
5127 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
5128
5129 \end_inset
5130
5131  package additionally allows to set undefined locations to a predefined
5132  value, to insert checksums
5133 \begin_inset LatexCommand \index{checksum}
5134
5135 \end_inset
5136
5137  of various flavours (crc, add, xor) and to perform other manipulations
5138  (convert, split, crop, offset, ...).
5139
5140 \newline
5141
5142 \newline
5143
5144 \family sans
5145 \series bold
5146 srec_cat\SpecialChar ~
5147 \SpecialChar ~
5148 sourcefile.ihx -intel\SpecialChar ~
5149 \SpecialChar ~
5150 -o sourcefile.hex -intel
5151 \newline
5152
5153 \newline
5154
5155 \family default
5156 \series default
5157 An example for a more complex command line
5158 \begin_inset Foot
5159 collapsed false
5160
5161 \layout Standard
5162
5163 the command backfills
5164 \begin_inset LatexCommand \index{backfill unused memory}
5165
5166 \end_inset
5167
5168  unused memory with 0x12 and the overall 16 bit sum of the complete 64 kByte
5169  block is zero.
5170  If the program counter on an mcs51 runs wild the backfill pattern 0x12
5171  will be interpreted as an
5172 \family typewriter
5173 lcall
5174 \family default
5175  to address
5176 \family typewriter
5177 0x1212
5178 \family default
5179  (where an emergency routine could sit).
5180 \end_inset
5181
5182  could look like:
5183 \newline
5184
5185 \newline
5186
5187 \family sans
5188 \series bold
5189 \size footnotesize
5190 srec_cat\SpecialChar ~
5191 sourcefile.ihx -intel\SpecialChar ~
5192 \SpecialChar ~
5193 -fill 0x12 0x0000 0xfffe\SpecialChar ~
5194 -little-endian-checksum-nega
5195 tive 0xfffe 0x02 0x02\SpecialChar ~
5196 \SpecialChar ~
5197 -o sourcefile.hex -intel
5198 \size default
5199
5200 \newline
5201
5202 \newline
5203
5204 \family default
5205 \series default
5206 The srecord package is available at
5207 \begin_inset LatexCommand \url{http://sf.net/projects/srecord}
5208
5209 \end_inset
5210
5211  .
5212 \layout Subsection
5213
5214 Projects with Multiple Source Files
5215 \layout Standard
5216
5217 SDCC can compile only ONE file at a time.
5218  Let us for example assume that you have a project containing the following
5219  files:
5220 \newline
5221
5222 \newline
5223 foo1.c (contains some functions)
5224 \newline
5225 foo2.c (contains some more functions)
5226 \newline
5227 foomain.c (contains more functions and the function main)
5228 \newline
5229
5230 \size footnotesize
5231
5232 \newline
5233
5234 \size default
5235 The first two files will need to be compiled separately with the commands:
5236 \size footnotesize
5237
5238 \size default
5239
5240 \newline
5241
5242 \newline
5243
5244 \family sans
5245 \series bold
5246 sdcc\SpecialChar ~
5247 -c\SpecialChar ~
5248 foo1.c
5249 \family default
5250 \series default
5251 \size footnotesize
5252
5253 \newline
5254
5255 \family sans
5256 \series bold
5257 \size default
5258 sdcc\SpecialChar ~
5259 -c\SpecialChar ~
5260 foo2.c
5261 \family default
5262 \series default
5263
5264 \newline
5265
5266 \newline
5267 Then compile the source file containing the
5268 \emph on
5269 main()
5270 \emph default
5271  function and link
5272 \begin_inset LatexCommand \index{Linker}
5273
5274 \end_inset
5275
5276  the files together with the following command:
5277 \newline
5278
5279 \newline
5280
5281 \family sans
5282 \series bold
5283 sdcc\SpecialChar ~
5284 foomain.c\SpecialChar ~
5285 foo1.rel\SpecialChar ~
5286 foo2.rel
5287 \family default
5288 \series default
5289
5290 \begin_inset LatexCommand \index{<file>.rel}
5291
5292 \end_inset
5293
5294
5295 \newline
5296
5297 \newline
5298 Alternatively,
5299 \emph on
5300 foomain.c
5301 \emph default
5302 can be separately compiled as well:
5303 \family sans
5304 \series bold
5305
5306 \newline
5307
5308 \newline
5309 sdcc\SpecialChar ~
5310 -c\SpecialChar ~
5311 foomain.c
5312 \newline
5313 sdcc foomain.rel foo1.rel foo2.rel
5314 \newline
5315
5316 \newline
5317
5318 \family default
5319 \series default
5320 The file containing the
5321 \emph on
5322 main()
5323 \emph default
5324  function
5325 \emph on
5326
5327 \emph default
5328 \noun on
5329 must
5330 \noun default
5331  be the
5332 \noun on
5333 first
5334 \noun default
5335  file specified in the command line, since the linkage editor processes
5336  file in the order they are presented to it.
5337  The linker is invoked from SDCC using a script file with extension .lnk
5338 \begin_inset LatexCommand \index{<file>.lnk}
5339
5340 \end_inset
5341
5342 .
5343  You can view this file to troubleshoot linking problems such as those arising
5344  from missing libraries.
5345 \layout Subsection
5346
5347 Projects with Additional Libraries
5348 \begin_inset LatexCommand \index{Libraries}
5349
5350 \end_inset
5351
5352
5353 \layout Standard
5354
5355 Some reusable routines may be compiled into a library, see the documentation
5356  for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
5357  for how to create a
5358 \emph on
5359 .lib
5360 \begin_inset LatexCommand \index{<file>.lib}
5361
5362 \end_inset
5363
5364
5365 \emph default
5366  library file.
5367  Libraries created in this manner can be included in the command line.
5368  Make sure you include the -L <library-path> option to tell the linker where
5369  to look for these files if they are not in the current directory.
5370  Here is an example, assuming you have the source file
5371 \emph on
5372 foomain.c
5373 \emph default
5374  and a library
5375 \emph on
5376  foolib.lib
5377 \emph default
5378  in the directory
5379 \emph on
5380 mylib
5381 \emph default
5382  (if that is not the same as your current project):
5383 \newline
5384
5385 \newline
5386
5387 \family sans
5388 \series bold
5389 sdcc foomain.c foolib.lib -L mylib
5390 \newline
5391
5392 \newline
5393
5394 \family default
5395 \series default
5396 Note here that
5397 \emph on
5398  mylib
5399 \emph default
5400  must be an absolute path name.
5401 \newline
5402
5403 \newline
5404 The most efficient way to use libraries is to keep separate modules in separate
5405  source files.
5406  The lib file now should name all the modules.rel
5407 \begin_inset LatexCommand \index{<file>.rel}
5408
5409 \end_inset
5410
5411  files.
5412  For an example see the standard library file
5413 \emph on
5414 libsdcc.lib
5415 \emph default
5416  in the directory <installdir>/share/lib/small.
5417 \layout Subsection
5418
5419 Using sdcclib to Create and Manage Libraries
5420 \begin_inset LatexCommand \index{sdcclib}
5421
5422 \end_inset
5423
5424
5425 \layout Standard
5426
5427 Alternatively, instead of having a .rel file for each entry on the library
5428  file as described in the preceding section, sdcclib can be used to embed
5429  all the modules belonging to such library in the library file itself.
5430  This results in a larger library file, but it greatly reduces the number
5431  of disk files accessed by the linker.
5432   Additionally, the packed library file contains an index of all include
5433  modules and symbols that significantly speeds up the linking process.
5434  To display a list of options supported by sdcclib type:
5435 \newline
5436
5437 \layout Standard
5438
5439
5440 \family sans
5441 \series bold
5442 sdcclib -?
5443 \begin_inset LatexCommand \index{sdcclib}
5444
5445 \end_inset
5446
5447
5448 \newline
5449
5450 \newline
5451
5452 \family default
5453 \series default
5454 To create a new library file, start by compiling all the required modules.
5455  For example:
5456 \newline
5457
5458 \layout Standard
5459
5460
5461 \family sans
5462 \series bold
5463 sdcc -c _divsint.c
5464 \layout Standard
5465
5466
5467 \family sans
5468 \series bold
5469 sdcc -c _divuint.c
5470 \layout Standard
5471
5472
5473 \family sans
5474 \series bold
5475 sdcc -c _modsint.c
5476 \layout Standard
5477
5478
5479 \family sans
5480 \series bold
5481 sdcc -c _moduint.c
5482 \layout Standard
5483
5484
5485 \family sans
5486 \series bold
5487 sdcc -c _mulint.c
5488 \newline
5489
5490 \layout Standard
5491
5492 This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
5493  and _mulint.rel.
5494  The next step is to add the .rel files to the library file:
5495 \newline
5496
5497 \layout Standard
5498
5499
5500 \family sans
5501 \series bold
5502 sdcclib libint.lib _divsint.rel
5503 \family default
5504
5505 \begin_inset LatexCommand \index{sdcclib}
5506
5507 \end_inset
5508
5509
5510 \layout Standard
5511
5512
5513 \family sans
5514 \series bold
5515 sdcclib libint.lib _divuint.rel
5516 \layout Standard
5517
5518
5519 \family sans
5520 \series bold
5521 sdcclib libint.lib _modsint.rel
5522 \layout Standard
5523
5524
5525 \family sans
5526 \series bold
5527 sdcclib libint.lib _moduint.rel
5528 \layout Standard
5529
5530
5531 \family sans
5532 \series bold
5533 sdcclib libint.lib _mulint.rel
5534 \series default
5535
5536 \newline
5537
5538 \layout Standard
5539
5540 If the file already exists in the library, it will be replaced.
5541  To see what modules and symbols are included in the library, options -s
5542  and -m are available.
5543  For example:
5544 \newline
5545
5546 \newline
5547
5548 \family sans
5549 \series bold
5550 sdcclib -s libint.lib
5551 \family default
5552
5553 \begin_inset LatexCommand \index{sdcclib}
5554
5555 \end_inset
5556
5557
5558 \newline
5559
5560 \family typewriter
5561 \series default
5562 _divsint.rel:
5563 \layout Standard
5564
5565
5566 \family typewriter
5567 __divsint_a_1_1
5568 \layout Standard
5569
5570
5571 \family typewriter
5572 __divsint_PARM_2
5573 \layout Standard
5574
5575
5576 \family typewriter
5577 __divsint
5578 \newline
5579 _divuint.rel:
5580 \layout Standard
5581
5582
5583 \family typewriter
5584 __divuint_a_1_1
5585 \layout Standard
5586
5587
5588 \family typewriter
5589 __divuint_PARM_2
5590 \layout Standard
5591
5592
5593 \family typewriter
5594 __divuint_reste_1_1
5595 \layout Standard
5596
5597
5598 \family typewriter
5599 __divuint_count_1_1
5600 \layout Standard
5601
5602
5603 \family typewriter
5604 __divuint
5605 \newline
5606 _modsint.rel:
5607 \layout Standard
5608
5609
5610 \family typewriter
5611 __modsint_a_1_1
5612 \layout Standard
5613
5614
5615 \family typewriter
5616 __modsint_PARM_2
5617 \layout Standard
5618
5619
5620 \family typewriter
5621 __modsint
5622 \newline
5623 _moduint.rel:
5624 \layout Standard
5625
5626
5627 \family typewriter
5628 __moduint_a_1_1
5629 \layout Standard
5630
5631
5632 \family typewriter
5633 __moduint_PARM_2
5634 \layout Standard
5635
5636
5637 \family typewriter
5638 __moduint_count_1_1
5639 \layout Standard
5640
5641
5642 \family typewriter
5643 __moduint
5644 \newline
5645 _mulint.rel:
5646 \layout Standard
5647
5648
5649 \family typewriter
5650 __mulint_PARM_2
5651 \layout Standard
5652
5653
5654 \family typewriter
5655 __mulint
5656 \family default
5657 \series bold
5658
5659 \newline
5660
5661 \layout Standard
5662 \added_space_bottom bigskip
5663 If the source files are compiled using -
5664 \begin_inset ERT
5665 status Collapsed
5666
5667 \layout Standard
5668
5669 \backslash
5670 /
5671 \end_inset
5672
5673 -debug
5674 \begin_inset LatexCommand \index{-\/-debug}
5675
5676 \end_inset
5677
5678 , the corresponding debug information file .adb will be include in the library
5679  file as well.
5680  The library files created with sdcclib are plain text files, so they can
5681  be viewed with a text editor.
5682  It is not recomended to modify a library file created with sdcclib using
5683  a text editor, as there are file indexes numbers located accross the file
5684  used by the linker to quickly locate the required module to link.
5685  Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
5686  it can be safely deleted, since all the information required for linking
5687  is embedded in the library file itself.
5688  Library files created using sdcclib are used as described in the preceding
5689  sections.
5690 \layout Section
5691
5692 Command Line Options
5693 \begin_inset LatexCommand \index{Command Line Options}
5694
5695 \end_inset
5696
5697
5698 \layout Subsection
5699
5700 Processor Selection Options
5701 \begin_inset LatexCommand \index{Options processor selection}
5702
5703 \end_inset
5704
5705
5706 \begin_inset LatexCommand \index{Processor selection options}
5707
5708 \end_inset
5709
5710
5711 \layout List
5712 \labelwidthstring 00.00.0000
5713
5714
5715 \series bold
5716 -mmcs51
5717 \begin_inset LatexCommand \index{-mmcs51}
5718
5719 \end_inset
5720
5721
5722 \series default
5723  Generate code for the Intel MCS51
5724 \begin_inset LatexCommand \index{MCS51}
5725
5726 \end_inset
5727
5728  family of processors.
5729  This is the default processor target.
5730 \layout List
5731 \labelwidthstring 00.00.0000
5732
5733
5734 \series bold
5735 -mds390
5736 \begin_inset LatexCommand \index{-mds390}
5737
5738 \end_inset
5739
5740
5741 \series default
5742  Generate code for the Dallas DS80C390
5743 \begin_inset LatexCommand \index{DS80C390}
5744
5745 \end_inset
5746
5747  processor.
5748 \layout List
5749 \labelwidthstring 00.00.0000
5750
5751
5752 \series bold
5753 -mds400
5754 \begin_inset LatexCommand \index{-mds400}
5755
5756 \end_inset
5757
5758
5759 \series default
5760  Generate code for the Dallas DS80C400
5761 \begin_inset LatexCommand \index{DS80C400}
5762
5763 \end_inset
5764
5765  processor.
5766 \layout List
5767 \labelwidthstring 00.00.0000
5768
5769
5770 \series bold
5771 -mhc08
5772 \begin_inset LatexCommand \index{-mhc08}
5773
5774 \end_inset
5775
5776
5777 \series default
5778  Generate code for the Freescale/Motorola HC08
5779 \begin_inset LatexCommand \index{HC08}
5780
5781 \end_inset
5782
5783  family of processors.
5784 \layout List
5785 \labelwidthstring 00.00.0000
5786
5787
5788 \series bold
5789 -mz80
5790 \begin_inset LatexCommand \index{-mz80}
5791
5792 \end_inset
5793
5794
5795 \series default
5796  Generate code for the Zilog Z80
5797 \begin_inset LatexCommand \index{Z80}
5798
5799 \end_inset
5800
5801  family of processors.
5802 \layout List
5803 \labelwidthstring 00.00.0000
5804
5805
5806 \series bold
5807 -mgbz80
5808 \begin_inset LatexCommand \index{-mgbz80}
5809
5810 \end_inset
5811
5812
5813 \series default
5814  Generate code for the GameBoy Z80
5815 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
5816
5817 \end_inset
5818
5819  processor (Not actively maintained).
5820 \layout List
5821 \labelwidthstring 00.00.0000
5822
5823
5824 \series bold
5825 -mavr
5826 \begin_inset LatexCommand \index{-mavr}
5827
5828 \end_inset
5829
5830
5831 \series default
5832  Generate code for the Atmel AVR
5833 \begin_inset LatexCommand \index{AVR}
5834
5835 \end_inset
5836
5837  processor (Not maintained, not complete).
5838  AVR users should probably have a look at winavr
5839 \begin_inset LatexCommand \url{http://sourceforge.net/projects/winavr}
5840
5841 \end_inset
5842
5843  or
5844 \begin_inset LatexCommand \url{http://www.avrfreaks.net/index.php?name=PNphpBB2&file=index}
5845
5846 \end_inset
5847
5848 .
5849 \layout Comment
5850
5851 I think it is fair to direct users there for now.
5852  Open source is also about avoiding unnecessary work .
5853  But I didn't find the 'official' link.
5854 \layout List
5855 \labelwidthstring 00.00.0000
5856
5857
5858 \series bold
5859 -mpic14
5860 \begin_inset LatexCommand \index{-mpic14}
5861
5862 \end_inset
5863
5864
5865 \series default
5866  Generate code for the Microchip PIC 14
5867 \begin_inset LatexCommand \index{PIC14}
5868
5869 \end_inset
5870
5871 -bit processors (p16f84 and variants.
5872  In development, not complete).
5873 \layout Comment
5874
5875 p16f627 p16f628 p16f84 p16f873 p16f877?
5876 \layout List
5877 \labelwidthstring 00.00.0000
5878
5879
5880 \series bold
5881 -mpic16
5882 \begin_inset LatexCommand \index{-mpic16}
5883
5884 \end_inset
5885
5886
5887 \series default
5888  Generate code for the Microchip PIC 16
5889 \begin_inset LatexCommand \index{PIC16}
5890
5891 \end_inset
5892
5893 -bit processors (p18f452 and variants.
5894  In development, not complete).
5895 \layout List
5896 \labelwidthstring 00.00.0000
5897
5898
5899 \series bold
5900 -mtlcs900h
5901 \series default
5902  Generate code for the Toshiba TLCS-900H
5903 \begin_inset LatexCommand \index{TLCS-900H}
5904
5905 \end_inset
5906
5907  processor (Not maintained, not complete).
5908 \layout List
5909 \added_space_bottom bigskip \labelwidthstring 00.00.0000
5910
5911
5912 \series bold
5913 -mxa51
5914 \begin_inset LatexCommand \index{-mxa51}
5915
5916 \end_inset
5917
5918
5919 \series default
5920  Generate code for the Phillips XA51
5921 \begin_inset LatexCommand \index{XA51}
5922
5923 \end_inset
5924
5925  processor (Not maintained, not complete).
5926 \layout Subsection
5927
5928 Preprocessor Options
5929 \begin_inset LatexCommand \index{Options preprocessor}
5930
5931 \end_inset
5932
5933
5934 \begin_inset LatexCommand \index{Preprocessor options}
5935
5936 \end_inset
5937
5938
5939 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5940
5941 \end_inset
5942
5943
5944 \layout List
5945 \labelwidthstring 00.00.0000
5946
5947
5948 \series bold
5949 -I<path>
5950 \begin_inset LatexCommand \index{-I<path>}
5951
5952 \end_inset
5953
5954
5955 \series default
5956  The additional location where the pre processor will look for <..h> or
5957 \begin_inset Quotes eld
5958 \end_inset
5959
5960 ..h
5961 \begin_inset Quotes erd
5962 \end_inset
5963
5964  files.
5965 \layout List
5966 \labelwidthstring 00.00.0000
5967
5968
5969 \series bold
5970 -D<macro[=value]>
5971 \begin_inset LatexCommand \index{-D<macro[=value]>}
5972
5973 \end_inset
5974
5975
5976 \series default
5977  Command line definition of macros.
5978  Passed to the preprocessor.
5979 \layout List
5980 \labelwidthstring 00.00.0000
5981
5982
5983 \series bold
5984 -M
5985 \begin_inset LatexCommand \index{-M}
5986
5987 \end_inset
5988
5989
5990 \series default
5991  Tell the preprocessor to output a rule suitable for make describing the
5992  dependencies of each object file.
5993  For each source file, the preprocessor outputs one make-rule whose target
5994  is the object file name for that source file and whose dependencies are
5995  all the files `#include'd in it.
5996  This rule may be a single line or may be continued with `
5997 \backslash
5998 '-newline if it is long.
5999  The list of rules is printed on standard output instead of the preprocessed
6000  C program.
6001  `-M' implies `-E
6002 \begin_inset LatexCommand \index{-E}
6003
6004 \end_inset
6005
6006 '.
6007 \layout List
6008 \labelwidthstring 00.00.0000
6009
6010
6011 \series bold
6012 -C
6013 \begin_inset LatexCommand \index{-C}
6014
6015 \end_inset
6016
6017
6018 \series default
6019  Tell the preprocessor not to discard comments.
6020  Used with the `-E' option.
6021 \layout List
6022 \labelwidthstring 00.00.0000
6023
6024
6025 \series bold
6026 -MM
6027 \begin_inset LatexCommand \index{-MM}
6028
6029 \end_inset
6030
6031
6032 \size large
6033 \bar under
6034
6035 \series default
6036 \size default
6037 \bar default
6038 Like `-M' but the output mentions only the user header files included with
6039  `#include
6040 \begin_inset Quotes eld
6041 \end_inset
6042
6043 file"'.
6044  System header files included with `#include <file>' are omitted.
6045 \layout List
6046 \labelwidthstring 00.00.0000
6047
6048
6049 \series bold
6050 -Aquestion(answer)
6051 \begin_inset LatexCommand \index{-Aquestion(answer)}
6052
6053 \end_inset
6054
6055
6056 \series default
6057  Assert the answer answer for question, in case it is tested with a preprocessor
6058  conditional such as `#if #question(answer)'.
6059  `-A-' disables the standard assertions that normally describe the target
6060  machine.
6061 \layout List
6062 \labelwidthstring 00.00.0000
6063
6064
6065 \series bold
6066 -Umacro
6067 \begin_inset LatexCommand \index{-Umacro}
6068
6069 \end_inset
6070
6071
6072 \series default
6073  Undefine macro macro.
6074  `-U' options are evaluated after all `-D' options, but before any `-include'
6075  and `-imacros' options.
6076 \layout List
6077 \labelwidthstring 00.00.0000
6078
6079
6080 \series bold
6081 -dM
6082 \begin_inset LatexCommand \index{-dM}
6083
6084 \end_inset
6085
6086
6087 \series default
6088  Tell the preprocessor to output only a list of the macro definitions that
6089  are in effect at the end of preprocessing.
6090  Used with the `-E' option.
6091 \layout List
6092 \labelwidthstring 00.00.0000
6093
6094
6095 \series bold
6096 -dD
6097 \begin_inset LatexCommand \index{-dD}
6098
6099 \end_inset
6100
6101
6102 \series default
6103  Tell the preprocessor to pass all macro definitions into the output, in
6104  their proper sequence in the rest of the output.
6105 \layout List
6106 \labelwidthstring 00.00.0000
6107
6108
6109 \series bold
6110 -dN
6111 \begin_inset LatexCommand \index{-dN}
6112
6113 \end_inset
6114
6115
6116 \size large
6117 \bar under
6118
6119 \series default
6120 \size default
6121 \bar default
6122 Like `-dD' except that the macro arguments and contents are omitted.
6123  Only `#define name' is included in the output.
6124 \layout List
6125 \labelwidthstring 00.00.0000
6126
6127
6128 \series bold
6129 -pedantic-parse-number
6130 \begin_inset LatexCommand \index{-pedantic-parse-number}
6131
6132 \end_inset
6133
6134
6135 \size large
6136 \bar under
6137
6138 \series default
6139 \size default
6140 \bar default
6141 Pedentic parse numbers so that situations like 0xfe-LO_B(3) are parsed properly
6142  and the macro LO_B(3) gets expanded.
6143  See also #pragma pedantic_parse_number in section
6144 \begin_inset LatexCommand \ref{sec:Pragmas}
6145
6146 \end_inset
6147
6148
6149 \emph on
6150 Note: this functionality is not in conformance with standard!
6151 \layout List
6152 \added_space_bottom bigskip \labelwidthstring 00.00.0000
6153
6154
6155 \series bold
6156 -Wp\SpecialChar ~
6157 preprocessorOption[,preprocessorOption]
6158 \series default
6159
6160 \begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
6161
6162 \end_inset
6163
6164 ...
6165  Pass the preprocessorOption to the preprocessor
6166 \family typewriter
6167 sdcpp
6168 \family default
6169
6170 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
6171
6172 \end_inset
6173
6174 .
6175  SDCC uses an adapted version of the preprocessor
6176 \emph on
6177 cpp
6178 \emph default
6179  of the GNU Compiler Collection
6180 \begin_inset LatexCommand \index{gcc (GNU Compiler Collection)}
6181
6182 \end_inset
6183
6184  (
6185 \emph on
6186 gcc
6187 \emph default
6188
6189 \begin_inset LatexCommand \url{http://gcc.gnu.org/}
6190
6191 \end_inset
6192
6193 ), if you need more dedicated options please refer to the GCC\SpecialChar ~
6194 4.1.1\SpecialChar ~
6195 CPP\SpecialChar ~
6196 Manual
6197  at
6198 \begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
6199
6200 \end_inset
6201
6202 .
6203 \layout Subsection
6204
6205 Linker Options
6206 \begin_inset LatexCommand \index{Options linker}
6207
6208 \end_inset
6209
6210
6211 \begin_inset LatexCommand \index{Linker options}
6212
6213 \end_inset
6214
6215
6216 \layout List
6217 \labelwidthstring 00.00.0000
6218
6219
6220 \series bold
6221 -L\SpecialChar ~
6222 -
6223 \series default
6224
6225 \begin_inset ERT
6226 status Collapsed
6227
6228 \layout Standard
6229
6230 \backslash
6231 /
6232 \end_inset
6233
6234
6235 \series bold
6236 -lib-path
6237 \begin_inset LatexCommand \index{-\/-lib-path <path>}
6238
6239 \end_inset
6240
6241
6242 \begin_inset LatexCommand \index{-L -\/-lib-path}
6243
6244 \end_inset
6245
6246
6247 \series default
6248 \SpecialChar ~
6249 <absolute path to additional libraries> This option is passed to the linkage
6250  editor's additional libraries
6251 \begin_inset LatexCommand \index{Libraries}
6252
6253 \end_inset
6254
6255  search path.
6256  The path name must be absolute.
6257  Additional library files may be specified in the command line.
6258  See section Compiling programs for more details.
6259 \layout List
6260 \labelwidthstring 00.00.0000
6261
6262
6263 \series bold
6264 -
6265 \begin_inset ERT
6266 status Collapsed
6267
6268 \layout Standard
6269
6270 \backslash
6271 /
6272 \end_inset
6273
6274 -xram-loc
6275 \series default
6276
6277 \begin_inset LatexCommand \index{-\/-xram-loc <Value>}
6278
6279 \end_inset
6280
6281 \SpecialChar ~
6282 <Value> The start location of the external ram
6283 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
6284
6285 \end_inset
6286
6287 , default value is 0.
6288  The value entered can be in Hexadecimal or Decimal format, e.g.: -
6289 \begin_inset ERT
6290 status Collapsed
6291
6292 \layout Standard
6293
6294 \backslash
6295 /
6296 \end_inset
6297
6298 -xram-loc 0x8000 or -
6299 \begin_inset ERT
6300 status Collapsed
6301
6302 \layout Standard
6303
6304 \backslash
6305 /
6306 \end_inset
6307
6308 -xram-loc 32768.
6309 \layout List
6310 \labelwidthstring 00.00.0000
6311
6312
6313 \series bold
6314 -
6315 \begin_inset ERT
6316 status Collapsed
6317
6318 \layout Standard
6319
6320 \backslash
6321 /
6322 \end_inset
6323
6324 -code-loc
6325 \series default
6326
6327 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
6328
6329 \end_inset
6330
6331 \SpecialChar ~
6332 <Value> The start location of the code
6333 \begin_inset LatexCommand \index{code}
6334
6335 \end_inset
6336
6337  segment, default value 0.
6338  Note when this option is used the interrupt vector table
6339 \begin_inset LatexCommand \index{interrupt vector table}
6340
6341 \end_inset
6342
6343  is also relocated to the given address.
6344  The value entered can be in Hexadecimal or Decimal format, e.g.: -
6345 \begin_inset ERT
6346 status Collapsed
6347
6348 \layout Standard
6349
6350 \backslash
6351 /
6352 \end_inset
6353
6354 -code-loc 0x8000 or -
6355 \begin_inset ERT
6356 status Collapsed
6357
6358 \layout Standard
6359
6360 \backslash
6361 /
6362 \end_inset
6363
6364 -code-loc 32768.
6365 \layout List
6366 \labelwidthstring 00.00.0000
6367
6368
6369 \series bold
6370 -
6371 \begin_inset ERT
6372 status Collapsed
6373
6374 \layout Standard
6375
6376 \backslash
6377 /
6378 \end_inset
6379
6380 -stack-loc
6381 \series default
6382
6383 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
6384
6385 \end_inset
6386
6387 \SpecialChar ~
6388 <Value> By default the stack
6389 \begin_inset LatexCommand \index{stack}
6390
6391 \end_inset
6392
6393  is placed after the data segment.
6394  Using this option the stack can be placed anywhere in the internal memory
6395  space of the 8051.
6396  The value entered can be in Hexadecimal or Decimal format, e.g.
6397  -
6398 \begin_inset ERT
6399 status Collapsed
6400
6401 \layout Standard
6402
6403 \backslash
6404 /
6405 \end_inset
6406
6407 -stack-loc 0x20 or -
6408 \begin_inset ERT
6409 status Collapsed
6410
6411 \layout Standard
6412
6413 \backslash
6414 /
6415 \end_inset
6416
6417 -stack-loc 32.
6418  Since the sp register is incremented before a push or call, the initial
6419  sp will be set to one byte prior the provided value.
6420  The provided value should not overlap any other memory areas such as used
6421  register banks or the data segment and with enough space for the current
6422  application.
6423  The
6424 \series bold
6425 -
6426 \begin_inset ERT
6427 status Collapsed
6428
6429 \layout Standard
6430
6431 \backslash
6432 /
6433 \end_inset
6434
6435 -pack-iram
6436 \series default
6437 \SpecialChar ~
6438
6439 \begin_inset LatexCommand \index{-\/-pack-iram}
6440
6441 \end_inset
6442
6443  option (which is now a default setting) will override this setting, so
6444  you should also specify the
6445 \series bold
6446 -
6447 \begin_inset ERT
6448 status Collapsed
6449
6450 \layout Standard
6451
6452 \backslash
6453 /
6454 \end_inset
6455
6456 -no-pack-iram
6457 \series default
6458 \SpecialChar ~
6459
6460 \begin_inset LatexCommand \index{-\/-no-pack-iram}
6461
6462 \end_inset
6463
6464  option if you need to manually place the stack.
6465 \layout List
6466 \labelwidthstring 00.00.0000
6467
6468
6469 \series bold
6470 -
6471 \begin_inset ERT
6472 status Collapsed
6473
6474 \layout Standard
6475
6476 \backslash
6477 /
6478 \end_inset
6479
6480 -xstack-loc
6481 \series default
6482
6483 \begin_inset LatexCommand \index{-\/-xstack-loc <Value>}
6484
6485 \end_inset
6486
6487 \SpecialChar ~
6488 <Value> By default the external stack
6489 \begin_inset LatexCommand \index{xstack}
6490
6491 \end_inset
6492
6493  is placed after the pdata
6494 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
6495
6496 \end_inset
6497
6498  segment.
6499  Using this option the xstack can be placed anywhere in the external memory
6500  space of the 8051.
6501  The value entered can be in Hexadecimal or Decimal format, e.g.
6502  -
6503 \begin_inset ERT
6504 status Collapsed
6505
6506 \layout Standard
6507
6508 \backslash
6509 /
6510 \end_inset
6511
6512 -xstack-loc 0x8000 or -
6513 \begin_inset ERT
6514 status Collapsed
6515
6516 \layout Standard
6517
6518 \backslash
6519 /
6520 \end_inset
6521
6522 -stack-loc 32768.
6523  The provided value should not overlap any other memory areas such as the
6524  pdata or xdata segment and with enough space for the current application.
6525 \layout List
6526 \labelwidthstring 00.00.0000
6527
6528
6529 \series bold
6530 -
6531 \begin_inset ERT
6532 status Collapsed
6533
6534 \layout Standard
6535
6536 \backslash
6537 /
6538 \end_inset
6539
6540 -data-loc
6541 \series default
6542
6543 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
6544
6545 \end_inset
6546
6547 \SpecialChar ~
6548 <Value> The start location of the internal ram data
6549 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
6550
6551 \end_inset
6552
6553  segment.
6554  The value entered can be in Hexadecimal or Decimal format, eg.
6555  -
6556 \begin_inset ERT
6557 status Collapsed
6558
6559 \layout Standard
6560
6561 \backslash
6562 /
6563 \end_inset
6564
6565 -data-loc 0x20 or -
6566 \begin_inset ERT
6567 status Collapsed
6568
6569 \layout Standard
6570
6571 \backslash
6572 /
6573 \end_inset
6574
6575 -data-loc 32.
6576  (By default, the start location of the internal ram data segment  is set
6577  as low as possible in memory, taking into account the used register banks
6578  and the bit segment at address 0x20.
6579  For example if register banks 0 and 1 are used without bit variables, the
6580  data segment will be set, if -
6581 \begin_inset ERT
6582 status Collapsed
6583
6584 \layout Standard
6585
6586 \backslash
6587 /
6588 \end_inset
6589
6590 -data-loc is not used, to location 0x10.)
6591 \layout List
6592 \labelwidthstring 00.00.0000
6593
6594
6595 \series bold
6596 -
6597 \begin_inset ERT
6598 status Collapsed
6599
6600 \layout Standard
6601
6602 \backslash
6603 /
6604 \end_inset
6605
6606 -idata-loc
6607 \series default
6608
6609 \begin_inset LatexCommand \index{-\/-idata-loc <Value>}
6610
6611 \end_inset
6612
6613 \SpecialChar ~
6614 <Value> The start location of the indirectly addressable internal ram
6615 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
6616
6617 \end_inset
6618
6619  of the 8051, default value is 0x80.
6620  The value entered can be in Hexadecimal or Decimal format, eg.
6621  -
6622 \begin_inset ERT
6623 status Collapsed
6624
6625 \layout Standard
6626
6627 \backslash
6628 /
6629 \end_inset
6630
6631 -idata-loc 0x88 or -
6632 \begin_inset ERT
6633 status Collapsed
6634
6635 \layout Standard
6636
6637 \backslash
6638 /
6639 \end_inset
6640
6641 -idata-loc 136.
6642 \layout List
6643 \labelwidthstring 00.00.0000
6644
6645
6646 \series bold
6647 -
6648 \begin_inset ERT
6649 status Collapsed
6650
6651 \layout Standard
6652
6653 \backslash
6654 /
6655 \end_inset
6656
6657 -bit-loc
6658 \series default
6659 \SpecialChar ~
6660 <Value> The start location of the bit
6661 \begin_inset LatexCommand \index{bit}
6662
6663 \end_inset
6664
6665  addressable internal ram of the 8051.
6666  This is
6667 \emph on
6668 not
6669 \emph default
6670  implemented yet.
6671  Instead an option can be passed directly to the linker: -Wl\SpecialChar ~
6672 -bBSEG=<Value>.
6673 \layout List
6674 \labelwidthstring 00.00.0000
6675
6676
6677 \series bold
6678 -
6679 \begin_inset ERT
6680 status Collapsed
6681
6682 \layout Standard
6683
6684 \backslash
6685 /
6686 \end_inset
6687
6688 -out-fmt-ihx
6689 \begin_inset LatexCommand \index{-\/-out-fmt-ihx}
6690
6691 \end_inset
6692
6693
6694 \bar under
6695
6696 \series default
6697 \bar default
6698 The linker output (final object code) is in Intel Hex format.
6699 \begin_inset LatexCommand \index{Intel hex format}
6700
6701 \end_inset
6702
6703  This is the default option.
6704  The format itself is documented in the documentation of srecord
6705 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
6706
6707 \end_inset
6708
6709 .
6710 \layout List
6711 \labelwidthstring 00.00.0000
6712
6713
6714 \series bold
6715 -
6716 \begin_inset ERT
6717 status Collapsed
6718
6719 \layout Standard
6720
6721 \backslash
6722 /
6723 \end_inset
6724
6725 -out-fmt-s19
6726 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
6727
6728 \end_inset
6729
6730
6731 \bar under
6732
6733 \series default
6734 \bar default
6735 The linker output (final object code) is in Motorola S19 format
6736 \begin_inset LatexCommand \index{Motorola S19 format}
6737
6738 \end_inset
6739
6740 .
6741  The format itself is documented in the documentation of srecord.
6742 \layout List
6743 \labelwidthstring 00.00.0000
6744
6745
6746 \series bold
6747 -
6748 \begin_inset ERT
6749 status Collapsed
6750
6751 \layout Standard
6752
6753 \backslash
6754 /
6755 \end_inset
6756
6757 -out-fmt-elf
6758 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
6759
6760 \end_inset
6761
6762
6763 \begin_inset LatexCommand \index{HC08!Options!-\/-out-fmt-elf}
6764
6765 \end_inset
6766
6767
6768 \bar under
6769
6770 \series default
6771 \bar default
6772 The linker output (final object code) is in ELF format
6773 \begin_inset LatexCommand \index{ELF format}
6774
6775 \end_inset
6776
6777 .
6778  (Currently only supported for the HC08
6779 \begin_inset LatexCommand \index{HC08}
6780
6781 \end_inset
6782
6783  processors)
6784 \layout List
6785 \added_space_bottom bigskip \labelwidthstring 00.00.0000
6786
6787
6788 \series bold
6789 -Wl\SpecialChar ~
6790 linkOption[,linkOption]
6791 \series default
6792
6793 \begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
6794
6795 \end_inset
6796
6797 ...
6798  Pass the linkOption to the linker.
6799  If a bootloader is used an option like
6800 \begin_inset Quotes sld
6801 \end_inset
6802
6803 -Wl\SpecialChar ~
6804 -bCSEG=0x1000
6805 \begin_inset Quotes srd
6806 \end_inset
6807
6808  would be typical to set the start of the code segment.
6809  See also #pragma constseg and #pragma codeseg in section
6810 \begin_inset LatexCommand \ref{sec:Pragmas}
6811
6812 \end_inset
6813
6814  .
6815  File sdcc/as/doc/asxhtm.html has more on linker options.
6816 \layout Subsection
6817
6818 MCS51 Options
6819 \begin_inset LatexCommand \index{Options MCS51}
6820
6821 \end_inset
6822
6823
6824 \begin_inset LatexCommand \index{MCS51 options}
6825
6826 \end_inset
6827
6828
6829 \layout List
6830 \labelwidthstring 00.00.0000
6831
6832
6833 \series bold
6834 -
6835 \begin_inset ERT
6836 status Collapsed
6837
6838 \layout Standard
6839
6840 \backslash
6841 /
6842 \end_inset
6843
6844 -model-small
6845 \begin_inset LatexCommand \index{-\/-model-small}
6846
6847 \end_inset
6848
6849
6850 \series default
6851 \size large
6852 \emph on
6853
6854 \size default
6855 \emph default
6856 Generate code for Small Model programs, see section Memory Models for more
6857  details.
6858  This is the default model.
6859 \layout List
6860 \labelwidthstring 00.00.0000
6861
6862
6863 \series bold
6864 -
6865 \begin_inset ERT
6866 status Collapsed
6867
6868 \layout Standard
6869
6870 \backslash
6871 /
6872 \end_inset
6873
6874 -model-medium
6875 \begin_inset LatexCommand \index{-\/-model-medium}
6876
6877 \end_inset
6878
6879
6880 \series default
6881  Generate code for Medium model programs, see section Memory Models for
6882  more details.
6883  If this option is used all source files in the project have to be compiled
6884  with this option.
6885  It must also be used when invoking the linker.
6886 \layout List
6887 \labelwidthstring 00.00.0000
6888
6889
6890 \series bold
6891 -
6892 \begin_inset ERT
6893 status Collapsed
6894
6895 \layout Standard
6896
6897 \backslash
6898 /
6899 \end_inset
6900
6901 -model-large
6902 \begin_inset LatexCommand \index{-\/-model-large}
6903
6904 \end_inset
6905
6906
6907 \series default
6908  Generate code for Large model programs, see section Memory Models for more
6909  details.
6910  If this option is used all source files in the project have to be compiled
6911  with this option.
6912  It must also be used when invoking the linker.
6913 \layout List
6914 \labelwidthstring 00.00.0000
6915
6916
6917 \series bold
6918 -
6919 \begin_inset ERT
6920 status Collapsed
6921
6922 \layout Standard
6923
6924 \backslash
6925 /
6926 \end_inset
6927
6928 -xstack
6929 \begin_inset LatexCommand \index{-\/-xstack}
6930
6931 \end_inset
6932
6933
6934 \series default
6935  Uses a pseudo stack in the pdata
6936 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
6937
6938 \end_inset
6939
6940  area (usually the first 256 bytes in the external ram) for allocating variables
6941  and passing parameters.
6942  See section
6943 \begin_inset LatexCommand \ref{sub:External-Stack}
6944
6945 \end_inset
6946
6947 \SpecialChar ~
6948  External Stack for more details.
6949 \layout List
6950 \labelwidthstring 00.00.0000
6951
6952
6953 \series bold
6954 -
6955 \begin_inset ERT
6956 status Collapsed
6957
6958 \layout Standard
6959
6960 \backslash
6961 /
6962 \end_inset
6963
6964 -iram-size
6965 \series default
6966 \SpecialChar ~
6967 <Value>
6968 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
6969
6970 \end_inset
6971
6972  Causes the linker to check if the internal ram usage is within limits of
6973  the given value.
6974 \layout List
6975 \labelwidthstring 00.00.0000
6976
6977
6978 \series bold
6979 -
6980 \begin_inset ERT
6981 status Collapsed
6982
6983 \layout Standard
6984
6985 \backslash
6986 /
6987 \end_inset
6988
6989 -xram-size
6990 \series default
6991 \SpecialChar ~
6992 <Value>
6993 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
6994
6995 \end_inset
6996
6997  Causes the linker to check if the external ram usage is within limits of
6998  the given value.
6999 \layout List
7000 \labelwidthstring 00.00.0000
7001
7002
7003 \series bold
7004 -
7005 \begin_inset ERT
7006 status Collapsed
7007
7008 \layout Standard
7009
7010 \backslash
7011 /
7012 \end_inset
7013
7014 -code-size
7015 \series default
7016 \SpecialChar ~
7017 <Value>
7018 \begin_inset LatexCommand \index{-\/-code-size <Value>}
7019
7020 \end_inset
7021
7022  Causes the linker to check if the code memory usage is within limits of
7023  the given value.
7024 \layout List
7025 \labelwidthstring 00.00.0000
7026
7027
7028 \series bold
7029 -
7030 \begin_inset ERT
7031 status Collapsed
7032
7033 \layout Standard
7034
7035 \backslash
7036 /
7037 \end_inset
7038
7039 -stack-size
7040 \series default
7041 \SpecialChar ~
7042 <Value>
7043 \begin_inset LatexCommand \index{-\/-stack-size <Value>}
7044
7045 \end_inset
7046
7047  Causes the linker to check if there is at minimum <Value> bytes for stack.
7048 \layout List
7049 \labelwidthstring 00.00.0000
7050
7051
7052 \series bold
7053 -
7054 \begin_inset ERT
7055 status Collapsed
7056
7057 \layout Standard
7058
7059 \backslash
7060 /
7061 \end_inset
7062
7063 -pack-iram
7064 \series default
7065 \SpecialChar ~
7066
7067 \begin_inset LatexCommand \index{-\/-pack-iram}
7068
7069 \end_inset
7070
7071  Causes the linker to use unused register banks for data variables and pack
7072  data, idata and stack together.
7073  This is the default now.
7074 \layout List
7075 \added_space_bottom bigskip \labelwidthstring 00.00.0000
7076
7077
7078 \series bold
7079 -
7080 \begin_inset ERT
7081 status Collapsed
7082
7083 \layout Standard
7084
7085 \backslash
7086 /
7087 \end_inset
7088
7089 -no-pack-iram
7090 \series default
7091 \SpecialChar ~
7092
7093 \begin_inset LatexCommand \index{-\/-no-pack-iram}
7094
7095 \end_inset
7096
7097  Causes the linker to use old style for allocating memory areas.
7098 \layout Subsection
7099
7100 DS390 / DS400 Options
7101 \begin_inset LatexCommand \index{Options DS390}
7102
7103 \end_inset
7104
7105
7106 \begin_inset LatexCommand \index{DS390}
7107
7108 \end_inset
7109
7110
7111 \layout List
7112 \labelwidthstring 00.00.0000
7113
7114
7115 \series bold
7116 -
7117 \begin_inset ERT
7118 status Collapsed
7119
7120 \layout Standard
7121
7122 \backslash
7123 /
7124 \end_inset
7125
7126 -model-flat24
7127 \series default
7128
7129 \begin_inset LatexCommand \index{DS390!Options!-\/-model-flat24}
7130
7131 \end_inset
7132
7133
7134 \size large
7135 \emph on
7136
7137 \size default
7138 \emph default
7139 Generate 24-bit flat mode code.
7140  This is the one and only that the ds390 code generator supports right now
7141  and is default when using
7142 \emph on
7143 -mds390
7144 \emph default
7145 .
7146  See section Memory Models for more details.
7147 \layout List
7148 \labelwidthstring 00.00.0000
7149
7150
7151 \series bold
7152 -
7153 \begin_inset ERT
7154 status Collapsed
7155
7156 \layout Standard
7157
7158 \backslash
7159 /
7160 \end_inset
7161
7162 -protect-sp-update
7163 \begin_inset LatexCommand \index{DS390!Options!-\/-protect-sp-update}
7164
7165 \end_inset
7166
7167
7168 \series default
7169  disable interrupts during ESP:SP updates.
7170 \layout List
7171 \labelwidthstring 00.00.0000
7172
7173
7174 \series bold
7175 -
7176 \begin_inset ERT
7177 status Collapsed
7178
7179 \layout Standard
7180
7181 \backslash
7182 /
7183 \end_inset
7184
7185 -stack-10bit
7186 \series default
7187
7188 \begin_inset LatexCommand \index{DS390!Options!-\/-stack-10bit}
7189
7190 \end_inset
7191
7192  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
7193  This is the one and only that the ds390 code generator supports right now
7194  and is default when using
7195 \emph on
7196 -mds390
7197 \emph default
7198 .
7199  In this mode, the stack is located in the lower 1K of the internal RAM,
7200  which is mapped to 0x400000.
7201  Note that the support is incomplete, since it still uses a single byte
7202  as the stack pointer.
7203  This means that only the lower 256 bytes of the potential 1K stack space
7204  will actually be used.
7205  However, this does allow you to reclaim the precious 256 bytes of low RAM
7206  for use for the DATA and IDATA segments.
7207  The compiler will not generate any code to put the processor into 10 bit
7208  stack mode.
7209  It is important to ensure that the processor is in this mode before calling
7210  any re-entrant functions compiled with this option.
7211  In principle, this should work with the
7212 \emph on
7213 -
7214 \begin_inset ERT
7215 status Collapsed
7216
7217 \layout Standard
7218
7219 \backslash
7220 /
7221 \end_inset
7222
7223 -stack-auto
7224 \begin_inset LatexCommand \index{-\/-stack-auto}
7225
7226 \end_inset
7227
7228
7229 \emph default
7230  option, but that has not been tested.
7231  It is incompatible with the
7232 \emph on
7233 -
7234 \begin_inset ERT
7235 status Collapsed
7236
7237 \layout Standard
7238
7239 \backslash
7240 /
7241 \end_inset
7242
7243 -xstack
7244 \begin_inset LatexCommand \index{-\/-xstack}
7245
7246 \end_inset
7247
7248
7249 \emph default
7250  option.
7251  It also only makes sense if the processor is in 24 bit contiguous addressing
7252  mode (see the
7253 \emph on
7254 -
7255 \begin_inset ERT
7256 status Collapsed
7257
7258 \layout Standard
7259
7260 \backslash
7261 /
7262 \end_inset
7263
7264 -model-flat24 option
7265 \emph default
7266 ).
7267 \layout List
7268 \labelwidthstring 00.00.0000
7269
7270
7271 \series bold
7272 -
7273 \begin_inset ERT
7274 status Collapsed
7275
7276 \layout Standard
7277
7278 \backslash
7279 /
7280 \end_inset
7281
7282 -stack-probe
7283 \begin_inset LatexCommand \index{DS390!Options!-\/-stack-probe}
7284
7285 \end_inset
7286
7287
7288 \series default
7289  insert call to function __stack_probe at each function prologue.
7290 \layout List
7291 \labelwidthstring 00.00.0000
7292
7293
7294 \series bold
7295 -
7296 \begin_inset ERT
7297 status Collapsed
7298
7299 \layout Standard
7300
7301 \backslash
7302 /
7303 \end_inset
7304
7305 -tini-libid
7306 \begin_inset LatexCommand \index{DS390!Options!-\/-tini-libid}
7307
7308 \end_inset
7309
7310
7311 \series default
7312  <nnnn> LibraryID used in -mTININative.
7313
7314 \layout List
7315 \added_space_bottom bigskip \labelwidthstring 00.00.0000
7316
7317
7318 \series bold
7319 -
7320 \begin_inset ERT
7321 status Collapsed
7322
7323 \layout Standard
7324
7325 \backslash
7326 /
7327 \end_inset
7328
7329 -use-accelerator
7330 \begin_inset LatexCommand \index{DS390!Options!-\/-use-accelerator}
7331
7332 \end_inset
7333
7334
7335 \series default
7336  generate code for DS390 Arithmetic Accelerator.
7337
7338 \layout Subsection
7339
7340 Z80 Options
7341 \begin_inset LatexCommand \index{Options Z80}
7342
7343 \end_inset
7344
7345
7346 \begin_inset LatexCommand \index{Z80}
7347
7348 \end_inset
7349
7350
7351 \layout List
7352 \labelwidthstring 00.00.0000
7353
7354
7355 \series bold
7356 -
7357 \begin_inset ERT
7358 status Collapsed
7359
7360 \layout Standard
7361
7362 \backslash
7363 /
7364 \end_inset
7365
7366 -callee-saves-bc
7367 \series default
7368
7369 \begin_inset LatexCommand \index{Z80!Options!-\/-callee-saves-bc}
7370
7371 \end_inset
7372
7373
7374 \size large
7375 \emph on
7376
7377 \size default
7378 \emph default
7379 Force a called function to always save BC.
7380 \layout List
7381 \added_space_bottom bigskip \labelwidthstring 00.00.0000
7382
7383
7384 \series bold
7385 -
7386 \begin_inset ERT
7387 status Collapsed
7388
7389 \layout Standard
7390
7391 \backslash
7392 /
7393 \end_inset
7394
7395 -no-std-crt0
7396 \series default
7397
7398 \begin_inset LatexCommand \index{Z80!Options!-\/-no-std-crt0}
7399
7400 \end_inset
7401
7402  When linking, skip the standard crt0.o object file.
7403  You must provide your own crt0.o for your system when linking.
7404
7405 \layout Subsection
7406
7407 Optimization Options
7408 \begin_inset LatexCommand \index{Options optimization}
7409
7410 \end_inset
7411
7412
7413 \begin_inset LatexCommand \index{Optimization options}
7414
7415 \end_inset
7416
7417
7418 \layout List
7419 \labelwidthstring 00.00.0000
7420
7421
7422 \series bold
7423 -
7424 \begin_inset ERT
7425 status Collapsed
7426
7427 \layout Standard
7428
7429 \backslash
7430 /
7431 \end_inset
7432
7433 -nogcse
7434 \begin_inset LatexCommand \index{-\/-nogcse}
7435
7436 \end_inset
7437
7438
7439 \series default
7440  Will not do global subexpression elimination, this option may be used when
7441  the compiler creates undesirably large stack/data spaces to store compiler
7442  temporaries (
7443 \emph on
7444 s
7445 \emph default
7446 pill
7447 \emph on
7448 loc
7449 \emph default
7450 ations, sloc
7451 \begin_inset LatexCommand \index{sloc (spill location)}
7452
7453 \end_inset
7454
7455 ).
7456  A warning message will be generated when this happens and the compiler
7457  will indicate the number of extra bytes it allocated.
7458  It is recommended that this option NOT be used, #pragma\SpecialChar ~
7459 nogcse
7460 \begin_inset LatexCommand \index{\#pragma nogcse}
7461
7462 \end_inset
7463
7464  can be used to turn off global subexpression elimination
7465 \begin_inset LatexCommand \index{Subexpression elimination}
7466
7467 \end_inset
7468
7469  for a given function only.
7470 \layout List
7471 \labelwidthstring 00.00.0000
7472
7473
7474 \series bold
7475 -
7476 \begin_inset ERT
7477 status Collapsed
7478
7479 \layout Standard
7480
7481 \backslash
7482 /
7483 \end_inset
7484
7485 -noinvariant
7486 \begin_inset LatexCommand \index{-\/-noinvariant}
7487
7488 \end_inset
7489
7490
7491 \series default
7492  Will not do loop invariant optimizations, this may be turned off for reasons
7493  explained for the previous option.
7494  For more details of loop optimizations performed see Loop Invariants in
7495  section
7496 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
7497
7498 \end_inset
7499
7500 .
7501  It is recommended that this option NOT be used, #pragma\SpecialChar ~
7502 noinvariant
7503 \begin_inset LatexCommand \index{\#pragma noinvariant}
7504
7505 \end_inset
7506
7507  can be used to turn off invariant optimizations for a given function only.
7508 \layout List
7509 \labelwidthstring 00.00.0000
7510
7511
7512 \series bold
7513 -
7514 \begin_inset ERT
7515 status Collapsed
7516
7517 \layout Standard
7518
7519 \backslash
7520 /
7521 \end_inset
7522
7523 -noinduction
7524 \begin_inset LatexCommand \index{-\/-noinduction}
7525
7526 \end_inset
7527
7528
7529 \series default
7530  Will not do loop induction optimizations, see section strength reduction
7531  for more details.
7532  It is recommended that this option is NOT used, #pragma\SpecialChar ~
7533 noinduction
7534 \begin_inset LatexCommand \index{\#pragma noinduction}
7535
7536 \end_inset
7537
7538  can be used to turn off induction optimizations for a given function only.
7539 \layout List
7540 \labelwidthstring 00.00.0000
7541
7542
7543 \series bold
7544 -
7545 \begin_inset ERT
7546 status Collapsed
7547
7548 \layout Standard
7549
7550 \backslash
7551 /
7552 \end_inset
7553
7554 -nojtbound
7555 \begin_inset LatexCommand \index{-\/-nojtbound}
7556
7557 \end_inset
7558
7559
7560 \size large
7561 \bar under
7562
7563 \series default
7564 \size default
7565 \bar default
7566  Will not generate boundary condition check when switch statements
7567 \begin_inset LatexCommand \index{switch statement}
7568
7569 \end_inset
7570
7571  are implemented using jump-tables.
7572  See section
7573 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
7574
7575 \end_inset
7576
7577 \SpecialChar ~
7578 Switch Statements for more details.
7579  It is recommended that this option is NOT used, #pragma\SpecialChar ~
7580 nojtbound
7581 \begin_inset LatexCommand \index{\#pragma nojtbound}
7582
7583 \end_inset
7584
7585  can be used to turn off boundary checking for jump tables for a given function
7586  only.
7587 \layout List
7588 \labelwidthstring 00.00.0000
7589
7590
7591 \series bold
7592 -
7593 \begin_inset ERT
7594 status Collapsed
7595
7596 \layout Standard
7597
7598 \backslash
7599 /
7600 \end_inset
7601
7602 -noloopreverse
7603 \begin_inset LatexCommand \index{-\/-noloopreverse}
7604
7605 \end_inset
7606
7607
7608 \series default
7609 \size large
7610
7611 \size default
7612 Will not do loop reversal
7613 \begin_inset LatexCommand \index{Loop reversing}
7614
7615 \end_inset
7616
7617 optimization.
7618 \layout List
7619 \labelwidthstring 00.00.0000
7620
7621 -
7622 \begin_inset ERT
7623 status Collapsed
7624
7625 \layout Standard
7626
7627 \backslash
7628 /
7629 \end_inset
7630
7631 -
7632 \series bold
7633 nolabelopt
7634 \series default
7635
7636 \begin_inset LatexCommand \index{-\/-nolabelopt }
7637
7638 \end_inset
7639
7640 Will not optimize labels (makes the dumpfiles more readable).
7641 \layout List
7642 \labelwidthstring 00.00.0000
7643
7644
7645 \series bold
7646 -
7647 \begin_inset ERT
7648 status Collapsed
7649
7650 \layout Standard
7651
7652 \backslash
7653 /
7654 \end_inset
7655
7656 -no-xinit-opt
7657 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
7658
7659 \end_inset
7660
7661
7662 \series default
7663  Will not memcpy initialized data from code space into xdata space.
7664  This saves a few bytes in code space if you don't have initialized data
7665 \begin_inset LatexCommand \index{Variable initialization}
7666
7667 \end_inset
7668
7669 .
7670 \layout List
7671 \labelwidthstring 00.00.0000
7672
7673
7674 \series bold
7675 -
7676 \begin_inset ERT
7677 status Collapsed
7678
7679 \layout Standard
7680
7681 \backslash
7682 /
7683 \end_inset
7684
7685 -nooverlay
7686 \begin_inset LatexCommand \index{-\/-nooverlay}
7687
7688 \end_inset
7689
7690
7691 \series default
7692   The compiler will not overlay parameters and local variables of any function,
7693  see section Parameters and local variables for more details.
7694 \layout List
7695 \labelwidthstring 00.00.0000
7696
7697
7698 \series bold
7699 -
7700 \begin_inset ERT
7701 status Collapsed
7702
7703 \layout Standard
7704
7705 \backslash
7706 /
7707 \end_inset
7708
7709 -no-peep
7710 \begin_inset LatexCommand \index{-\/-no-peep}
7711
7712 \end_inset
7713
7714
7715 \series default
7716  Disable peep-hole optimization with built-in rules.
7717 \layout List
7718 \labelwidthstring 00.00.0000
7719
7720
7721 \series bold
7722 -
7723 \begin_inset ERT
7724 status Collapsed
7725
7726 \layout Standard
7727
7728 \backslash
7729 /
7730 \end_inset
7731
7732 -peep-file
7733 \series default
7734
7735 \begin_inset LatexCommand \index{-\/-peep-file}
7736
7737 \end_inset
7738
7739 \SpecialChar ~
7740 <filename> This option can be used to use additional rules to be used by
7741  the peep hole optimizer.
7742  See section
7743 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
7744
7745 \end_inset
7746
7747 \SpecialChar ~
7748 Peep Hole optimizations for details on how to write these rules.
7749 \layout List
7750 \labelwidthstring 00.00.0000
7751
7752
7753 \series bold
7754 -
7755 \begin_inset ERT
7756 status Collapsed
7757
7758 \layout Standard
7759
7760 \backslash
7761 /
7762 \end_inset
7763
7764 -peep-asm
7765 \begin_inset LatexCommand \index{-\/-peep-asm}
7766
7767 \end_inset
7768
7769
7770 \series default
7771  Pass the inline assembler code through the peep hole optimizer.
7772  This can cause unexpected changes to inline assembler code, please go through
7773  the peephole optimizer
7774 \begin_inset LatexCommand \index{Peephole optimizer}
7775
7776 \end_inset
7777
7778  rules defined in the source file tree '<target>/peeph.def' before using
7779  this option.
7780 \layout List
7781 \labelwidthstring 00.00.0000
7782
7783
7784 \series bold
7785 -
7786 \begin_inset ERT
7787 status Collapsed
7788
7789 \layout Standard
7790
7791 \backslash
7792 /
7793 \end_inset
7794
7795 -opt-code-speed
7796 \begin_inset LatexCommand \index{-\/-opt-code-speed}
7797
7798 \end_inset
7799
7800
7801 \series default
7802  The compiler will optimize code generation towards fast code, possibly
7803  at the expense of code size.
7804 \layout List
7805 \added_space_bottom bigskip \labelwidthstring 00.00.0000
7806
7807
7808 \series bold
7809 -
7810 \begin_inset ERT
7811 status Collapsed
7812
7813 \layout Standard
7814
7815 \backslash
7816 /
7817 \end_inset
7818
7819 -opt-code-size
7820 \begin_inset LatexCommand \index{-\/-opt-code-size}
7821
7822 \end_inset
7823
7824
7825 \series default
7826  The compiler will optimize code generation towards compact code, possibly
7827  at the expense of code speed.
7828 \layout Subsection
7829
7830 Other Options
7831 \begin_inset LatexCommand \index{Options other}
7832
7833 \end_inset
7834
7835
7836 \layout List
7837 \labelwidthstring 00.00.0000
7838
7839
7840 \series bold
7841 -c\SpecialChar ~
7842 -
7843 \begin_inset ERT
7844 status Collapsed
7845
7846 \layout Standard
7847
7848 \backslash
7849 /
7850 \end_inset
7851
7852 -compile-only
7853 \begin_inset LatexCommand \index{-\/-compile-only}
7854
7855 \end_inset
7856
7857
7858 \begin_inset LatexCommand \index{-c -\/-compile-only}
7859
7860 \end_inset
7861
7862
7863 \series default
7864  will compile and assemble the source, but will not call the linkage editor.
7865 \layout List
7866 \labelwidthstring 00.00.0000
7867
7868
7869 \series bold
7870 -
7871 \series default
7872
7873 \begin_inset ERT
7874 status Collapsed
7875
7876 \layout Standard
7877
7878 \backslash
7879 /
7880 \end_inset
7881
7882
7883 \series bold
7884 -c1mode
7885 \begin_inset LatexCommand \index{-\/-c1mode}
7886
7887 \end_inset
7888
7889
7890 \series default
7891  reads the preprocessed source from standard input and compiles it.
7892  The file name for the assembler output must be specified using the -o option.
7893 \layout List
7894 \labelwidthstring 00.00.0000
7895
7896
7897 \series bold
7898 -E
7899 \begin_inset LatexCommand \index{-E}
7900
7901 \end_inset
7902
7903
7904 \series default
7905  Run only the C preprocessor.
7906  Preprocess all the C source files specified and output the results to standard
7907  output.
7908 \layout List
7909 \labelwidthstring 00.00.0000
7910
7911
7912 \series bold
7913 -o\SpecialChar ~
7914 <path/file>
7915 \begin_inset LatexCommand \index{-o <path/file>}
7916
7917 \end_inset
7918
7919
7920 \series default
7921 The output path resp.
7922  file where everything will be placed.
7923  If the parameter is a path, it must have a trailing slash (or backslash
7924  for the Windows binaries) to be recognized as a path.
7925
7926 \layout List
7927 \labelwidthstring 00.00.0000
7928
7929
7930 \series bold
7931 -
7932 \begin_inset ERT
7933 status Collapsed
7934
7935 \layout Standard
7936
7937 \backslash
7938 /
7939 \end_inset
7940
7941 -stack-auto
7942 \begin_inset LatexCommand \index{-\/-stack-auto}
7943
7944 \end_inset
7945
7946
7947 \series default
7948 \size large
7949 \emph on
7950
7951 \size default
7952 \emph default
7953 All functions in the source file will be compiled as
7954 \emph on
7955 reentrant
7956 \emph default
7957
7958 \begin_inset LatexCommand \index{reentrant}
7959
7960 \end_inset
7961
7962 , i.e.
7963  the parameters and local variables will be allocated on the stack
7964 \begin_inset LatexCommand \index{stack}
7965
7966 \end_inset
7967
7968 .
7969  See section
7970 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
7971
7972 \end_inset
7973
7974  Parameters and Local Variables for more details.
7975  If this option is used all source files in the project should be compiled
7976  with this option.
7977  It automatically implies --int-long-reent and --float-reent.
7978
7979 \layout List
7980 \labelwidthstring 00.00.0000
7981
7982
7983 \series bold
7984 -
7985 \begin_inset ERT
7986 status Collapsed
7987
7988 \layout Standard
7989
7990 \backslash
7991 /
7992 \end_inset
7993
7994 -callee-saves
7995 \begin_inset LatexCommand \index{-\/-callee-saves}
7996
7997 \end_inset
7998
7999  function1[,function2][,function3]....
8000
8001 \series default
8002  The compiler by default uses a caller saves convention for register saving
8003  across function calls, however this can cause unnecessary register pushing
8004  & popping when calling small functions from larger functions.
8005  This option can be used to switch the register saving convention for the
8006  function names specified.
8007  The compiler will not save registers when calling these functions, no extra
8008  code will be generated at the entry & exit (function prologue
8009 \series bold
8010
8011 \begin_inset LatexCommand \index{function prologue}
8012
8013 \end_inset
8014
8015
8016 \series default
8017  & epilogue
8018 \series bold
8019
8020 \begin_inset LatexCommand \index{function epilogue}
8021
8022 \end_inset
8023
8024
8025 \series default
8026 ) for these functions to save & restore the registers used by these functions,
8027  this can SUBSTANTIALLY reduce code & improve run time performance of the
8028  generated code.
8029  In the future the compiler (with inter procedural analysis) will be able
8030  to determine the appropriate scheme to use for each function call.
8031  DO NOT use this option for built-in functions such as _mulint..., if this
8032  option is used for a library function the appropriate library function
8033  needs to be recompiled with the same option.
8034  If the project consists of multiple source files then all the source file
8035  should be compiled with the same -
8036 \begin_inset ERT
8037 status Collapsed
8038
8039 \layout Standard
8040
8041 \backslash
8042 /
8043 \end_inset
8044
8045 -callee-saves option string.
8046  Also see #pragma\SpecialChar ~
8047 callee_saves
8048 \begin_inset LatexCommand \index{\#pragma callee\_saves}
8049
8050 \end_inset
8051
8052 .
8053 \layout List
8054 \labelwidthstring 00.00.0000
8055
8056
8057 \series bold
8058 -
8059 \begin_inset ERT
8060 status Collapsed
8061
8062 \layout Standard
8063
8064 \backslash
8065 /
8066 \end_inset
8067
8068 -debug
8069 \begin_inset LatexCommand \index{-\/-debug}
8070
8071 \end_inset
8072
8073
8074 \bar under
8075
8076 \series default
8077 \bar default
8078 When this option is used the compiler will generate debug information.
8079  The debug information collected in a file with .cdb extension can be used
8080  with the SDCDB.
8081  For more information see documentation for SDCDB.
8082  Another file with no extension contains debug information in AOMF or AOMF51
8083 \begin_inset LatexCommand \index{AOMF, AOMF51}
8084
8085 \end_inset
8086
8087  format which is commonly used by third party tools.
8088 \layout List
8089 \labelwidthstring 00.00.0000
8090
8091
8092 \series bold
8093 -S
8094 \begin_inset LatexCommand \index{-S}
8095
8096 \end_inset
8097
8098
8099 \size large
8100 \bar under
8101
8102 \series default
8103 \size default
8104 \bar default
8105 Stop after the stage of compilation proper; do not assemble.
8106  The output is an assembler code file for the input file specified.
8107 \layout List
8108 \labelwidthstring 00.00.0000
8109
8110
8111 \series bold
8112 -
8113 \begin_inset ERT
8114 status Collapsed
8115
8116 \layout Standard
8117
8118 \backslash
8119 /
8120 \end_inset
8121
8122 -int-long-reent
8123 \begin_inset LatexCommand \index{-\/-int-long-reent}
8124
8125 \end_inset
8126
8127
8128 \series default
8129  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
8130  Note by default these libraries are compiled as non-reentrant.
8131  See section Installation for more details.
8132 \layout List
8133 \labelwidthstring 00.00.0000
8134
8135
8136 \series bold
8137 -
8138 \begin_inset ERT
8139 status Collapsed
8140
8141 \layout Standard
8142
8143 \backslash
8144 /
8145 \end_inset
8146
8147 -cyclomatic
8148 \begin_inset LatexCommand \index{-\/-cyclomatic}
8149
8150 \end_inset
8151
8152
8153 \bar under
8154
8155 \series default
8156 \bar default
8157 This option will cause the compiler to generate an information message for
8158  each function in the source file.
8159  The message contains some
8160 \emph on
8161 important
8162 \emph default
8163  information about the function.
8164  The number of edges and nodes the compiler detected in the control flow
8165  graph of the function, and most importantly the
8166 \emph on
8167 cyclomatic complexity
8168 \begin_inset LatexCommand \index{Cyclomatic complexity}
8169
8170 \end_inset
8171
8172
8173 \emph default
8174  see section on Cyclomatic Complexity for more details.
8175 \layout List
8176 \labelwidthstring 00.00.0000
8177
8178
8179 \series bold
8180 -
8181 \begin_inset ERT
8182 status Collapsed
8183
8184 \layout Standard
8185
8186 \backslash
8187 /
8188 \end_inset
8189
8190 -float-reent
8191 \begin_inset LatexCommand \index{-\/-float-reent}
8192
8193 \end_inset
8194
8195
8196 \series default
8197  Floating point library is compiled as reentrant
8198 \begin_inset LatexCommand \index{reentrant}
8199
8200 \end_inset
8201
8202 .
8203  See section Installation for more details.
8204 \layout List
8205 \labelwidthstring 00.00.0000
8206
8207
8208 \series bold
8209 -
8210 \begin_inset ERT
8211 status Collapsed
8212
8213 \layout Standard
8214
8215 \backslash
8216 /
8217 \end_inset
8218
8219 -main-return
8220 \begin_inset LatexCommand \index{-\/-main-return}
8221
8222 \end_inset
8223
8224
8225 \series default
8226  This option can be used if the code generated is called by a monitor program
8227  or if the main routine includes an endless loop.
8228  This option results in slightly smaller code and saves two bytes of stack
8229  space.
8230  The return from the 'main'
8231 \begin_inset LatexCommand \index{main return}
8232
8233 \end_inset
8234
8235  function will return to the function calling main.
8236  The default setting is to lock up i.e.
8237  generate a '
8238 \family typewriter
8239 sjmp .
8240 \family default
8241 '.
8242 \layout List
8243 \labelwidthstring 00.00.0000
8244
8245
8246 \series bold
8247 -
8248 \begin_inset ERT
8249 status Collapsed
8250
8251 \layout Standard
8252
8253 \backslash
8254 /
8255 \end_inset
8256
8257 -nostdinc
8258 \begin_inset LatexCommand \index{-\/-nostdinc}
8259
8260 \end_inset
8261
8262
8263 \series default
8264  This will prevent the compiler from passing on the default include path
8265  to the preprocessor.
8266 \layout List
8267 \labelwidthstring 00.00.0000
8268
8269
8270 \series bold
8271 -
8272 \begin_inset ERT
8273 status Collapsed
8274
8275 \layout Standard
8276
8277 \backslash
8278 /
8279 \end_inset
8280
8281 -nostdlib
8282 \begin_inset LatexCommand \index{-\/-nostdlib}
8283
8284 \end_inset
8285
8286
8287 \series default
8288  This will prevent the compiler from passing on the default library
8289 \begin_inset LatexCommand \index{Libraries}
8290
8291 \end_inset
8292
8293  path to the linker.
8294 \layout List
8295 \labelwidthstring 00.00.0000
8296
8297
8298 \series bold
8299 -
8300 \begin_inset ERT
8301 status Collapsed
8302
8303 \layout Standard
8304
8305 \backslash
8306 /
8307 \end_inset
8308
8309 -verbose
8310 \begin_inset LatexCommand \index{-\/-verbose}
8311
8312 \end_inset
8313
8314
8315 \series default
8316  Shows the various actions the compiler is performing.
8317 \layout List
8318 \labelwidthstring 00.00.0000
8319
8320
8321 \series bold
8322 -V
8323 \begin_inset LatexCommand \index{-V}
8324
8325 \end_inset
8326
8327
8328 \series default
8329  Shows the actual commands the compiler is executing.
8330 \layout List
8331 \labelwidthstring 00.00.0000
8332
8333
8334 \series bold
8335 -
8336 \begin_inset ERT
8337 status Collapsed
8338
8339 \layout Standard
8340
8341 \backslash
8342 /
8343 \end_inset
8344
8345 -no-c-code-in-asm
8346 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
8347
8348 \end_inset
8349
8350
8351 \series default
8352  Hides your ugly and inefficient c-code from the asm file, so you can always
8353  blame the compiler :)
8354 \layout List
8355 \labelwidthstring 00.00.0000
8356
8357
8358 \series bold
8359 -
8360 \begin_inset ERT
8361 status Collapsed
8362
8363 \layout Standard
8364
8365 \backslash
8366 /
8367 \end_inset
8368
8369 -no-peep-comments
8370 \begin_inset LatexCommand \index{-\/-no-peep-comments}
8371
8372 \end_inset
8373
8374
8375 \series default
8376  Will not include peep-hole comments in the generated files.
8377 \layout List
8378 \labelwidthstring 00.00.0000
8379
8380
8381 \series bold
8382 -
8383 \begin_inset ERT
8384 status Collapsed
8385
8386 \layout Standard
8387
8388 \backslash
8389 /
8390 \end_inset
8391
8392 -i-code-in-asm
8393 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
8394
8395 \end_inset
8396
8397
8398 \series default
8399  Include i-codes in the asm file.
8400  Sounds like noise but is most helpful for debugging the compiler itself.
8401 \layout List
8402 \labelwidthstring 00.00.0000
8403
8404
8405 \series bold
8406 -
8407 \begin_inset ERT
8408 status Collapsed
8409
8410 \layout Standard
8411
8412 \backslash
8413 /
8414 \end_inset
8415
8416 -less-pedantic
8417 \begin_inset LatexCommand \index{-\/-less-pedantic}
8418
8419 \end_inset
8420
8421
8422 \series default
8423  Disable some of the more pedantic warnings
8424 \begin_inset LatexCommand \index{Warnings}
8425
8426 \end_inset
8427
8428  (jwk burps: please be more specific here, please!).
8429 \layout List
8430 \labelwidthstring 00.00.0000
8431
8432
8433 \series bold
8434 -
8435 \begin_inset ERT
8436 status Collapsed
8437
8438 \layout Standard
8439
8440 \backslash
8441 /
8442 \end_inset
8443
8444 -disable-warning\SpecialChar ~
8445 <nnnn>
8446 \begin_inset LatexCommand \index{-\/-disable-warning}
8447
8448 \end_inset
8449
8450
8451 \series default
8452  Disable specific warning with number <nnnn>.
8453 \layout List
8454 \labelwidthstring 00.00.0000
8455
8456
8457 \series bold
8458 -
8459 \begin_inset ERT
8460 status Collapsed
8461
8462 \layout Standard
8463
8464 \backslash
8465 /
8466 \end_inset
8467
8468 -print-search-dirs
8469 \begin_inset LatexCommand \index{-\/-print-search-dirs}
8470
8471 \end_inset
8472
8473
8474 \series default
8475  Display the directories in the compiler's search path
8476 \layout List
8477 \labelwidthstring 00.00.0000
8478
8479
8480 \series bold
8481 -
8482 \begin_inset ERT
8483 status Collapsed
8484
8485 \layout Standard
8486
8487 \backslash
8488 /
8489 \end_inset
8490
8491 -vc
8492 \begin_inset LatexCommand \index{-\/-vc}
8493
8494 \end_inset
8495
8496
8497 \series default
8498  Display errors and warnings using MSVC style, so you can use SDCC with
8499  the visual studio IDE
8500 \begin_inset LatexCommand \index{IDE}
8501
8502 \end_inset
8503
8504 .
8505  With SDCC both offering a GCC-like (the default) and a MSVC-like
8506 \begin_inset LatexCommand \index{MSVC output style}
8507
8508 \end_inset
8509
8510  output style, integration into most programming editors should be straightforwa
8511 rd.
8512 \layout List
8513 \labelwidthstring 00.00.0000
8514
8515
8516 \series bold
8517 -
8518 \begin_inset ERT
8519 status Collapsed
8520
8521 \layout Standard
8522
8523 \backslash
8524 /
8525 \end_inset
8526
8527 -use-stdout
8528 \begin_inset LatexCommand \index{-\/-use-stdout}
8529
8530 \end_inset
8531
8532
8533 \series default
8534  Send errors and warnings to stdout instead of stderr.
8535 \layout List
8536 \labelwidthstring 00.00.0000
8537
8538
8539 \series bold
8540 -Wa\SpecialChar ~
8541 asmOption[,asmOption]
8542 \series default
8543
8544 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
8545
8546 \end_inset
8547
8548 ...
8549  Pass the asmOption to the assembler
8550 \begin_inset LatexCommand \index{Options assembler}
8551
8552 \end_inset
8553
8554
8555 \begin_inset LatexCommand \index{Assembler options}
8556
8557 \end_inset
8558
8559 .
8560  See file sdcc/as/doc/asxhtm.html for assembler options.cd
8561 \layout List
8562 \labelwidthstring 00.00.0000
8563
8564
8565 \series bold
8566 -
8567 \begin_inset ERT
8568 status Collapsed
8569
8570 \layout Standard
8571
8572 \backslash
8573 /
8574 \end_inset
8575
8576 -std-sdcc89
8577 \begin_inset LatexCommand \index{-\/-std-sdcc89}
8578
8579 \end_inset
8580
8581
8582 \series default
8583  Generally follow the C89 standard, but allow SDCC features that conflict
8584  with the standard (default).
8585 \layout List
8586 \labelwidthstring 00.00.0000
8587
8588
8589 \series bold
8590 -
8591 \begin_inset ERT
8592 status Collapsed
8593
8594 \layout Standard
8595
8596 \backslash
8597 /
8598 \end_inset
8599
8600 -std-c89
8601 \begin_inset LatexCommand \index{-\/-std-c89}
8602
8603 \end_inset
8604
8605
8606 \series default
8607  Follow the C89 standard and disable SDCC features that conflict with the
8608  standard.
8609 \layout List
8610 \labelwidthstring 00.00.0000
8611
8612
8613 \series bold
8614 -
8615 \begin_inset ERT
8616 status Collapsed
8617
8618 \layout Standard
8619
8620 \backslash
8621 /
8622 \end_inset
8623
8624 -std-sdcc99
8625 \begin_inset LatexCommand \index{-\/-std-sdcc99}
8626
8627 \end_inset
8628
8629
8630 \series default
8631  Generally follow the C99 standard, but allow SDCC features that conflict
8632  with the standard (incomplete support).
8633 \layout List
8634 \labelwidthstring 00.00.0000
8635
8636
8637 \series bold
8638 -
8639 \begin_inset ERT
8640 status Collapsed
8641
8642 \layout Standard
8643
8644 \backslash
8645 /
8646 \end_inset
8647
8648 -std-c99
8649 \begin_inset LatexCommand \index{-\/-std-sdcc99}
8650
8651 \end_inset
8652
8653
8654 \series default
8655  Follow the C99 standard and disable SDCC features that conflict with the
8656  standard (incomplete support).
8657 \layout List
8658 \labelwidthstring 00.00.0000
8659
8660
8661 \series bold
8662 -
8663 \begin_inset ERT
8664 status Collapsed
8665
8666 \layout Standard
8667
8668 \backslash
8669 /
8670 \end_inset
8671
8672 -codeseg
8673 \series default
8674
8675 \begin_inset LatexCommand \index{-\/-codeseg <Value>}
8676
8677 \end_inset
8678
8679 \SpecialChar ~
8680 <Name> The name to be used for the code
8681 \begin_inset LatexCommand \index{code}
8682
8683 \end_inset
8684
8685  segment, default CSEG.
8686  This is useful if you need to tell the compiler to put the code in a special
8687  segment so you can later on tell the linker to put this segment in a special
8688  place in memory.
8689  Can be used for instance when using bank switching to put the code in a
8690  bank.
8691 \layout List
8692 \labelwidthstring 00.00.0000
8693
8694
8695 \series bold
8696 -
8697 \begin_inset ERT
8698 status Collapsed
8699
8700 \layout Standard
8701
8702 \backslash
8703 /
8704 \end_inset
8705
8706 -constseg
8707 \series default
8708
8709 \begin_inset LatexCommand \index{-\/-constseg <Value>}
8710
8711 \end_inset
8712
8713 \SpecialChar ~
8714 <Name> The name to be used for the const
8715 \begin_inset LatexCommand \index{code}
8716
8717 \end_inset
8718
8719  segment, default CONST.
8720  This is useful if you need to tell the compiler to put the const data in
8721  a special segment so you can later on tell the linker to put this segment
8722  in a special place in memory.
8723  Can be used for instance when using bank switching to put the const data
8724  in a bank.
8725 \layout List
8726 \added_space_bottom bigskip \labelwidthstring 00.00.0000
8727
8728
8729 \series bold
8730 more-pedantic
8731 \series default
8732  Actually this is
8733 \series bold
8734 \emph on
8735 not
8736 \series default
8737 \emph default
8738  a SDCC compiler option but if you want
8739 \emph on
8740 more
8741 \emph default
8742  warnings you can use a separate tool dedicated to syntax checking like
8743  splint
8744 \begin_inset LatexCommand \label{lyx:more-pedantic-SPLINT}
8745
8746 \end_inset
8747
8748
8749 \begin_inset LatexCommand \index{lint (syntax checking tool)}
8750
8751 \end_inset
8752
8753
8754 \begin_inset LatexCommand \url{http://www.splint.org}
8755
8756 \end_inset
8757
8758 .
8759  To make your source files parseable by splint you will have to include
8760
8761 \family sans
8762 lint.h
8763 \family default
8764
8765 \begin_inset LatexCommand \index{splint (syntax checking tool)}
8766
8767 \end_inset
8768
8769  in your source file and add brackets around extended keywords (like
8770 \family sans
8771
8772 \begin_inset Quotes sld
8773 \end_inset
8774
8775 __at\SpecialChar ~
8776
8777 \series bold
8778 (
8779 \series default
8780 0xab
8781 \series bold
8782 )
8783 \series default
8784
8785 \begin_inset Quotes srd
8786 \end_inset
8787
8788
8789 \family default
8790  and
8791 \family sans
8792
8793 \begin_inset Quotes sld
8794 \end_inset
8795
8796 __interrupt\SpecialChar ~
8797 (2)
8798 \begin_inset Quotes srd
8799 \end_inset
8800
8801
8802 \family default
8803 ).
8804
8805 \newline
8806 Splint has an excellent on line manual at
8807 \begin_inset LatexCommand \url{http://www.splint.org/manual/}
8808
8809 \end_inset
8810
8811  and it's capabilities go beyond pure syntax checking.
8812  You'll need to tell splint the location of SDCC's include files so a typical
8813  command line could look like this:
8814 \newline
8815
8816 \family sans
8817 splint\SpecialChar ~
8818 -I\SpecialChar ~
8819 /usr/local/share/sdcc/include/mcs51/\SpecialChar ~
8820 \SpecialChar ~
8821 myprogram.c
8822 \layout Subsection
8823
8824 Intermediate Dump Options
8825 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
8826
8827 \end_inset
8828
8829
8830 \begin_inset LatexCommand \index{Options intermediate dump}
8831
8832 \end_inset
8833
8834
8835 \begin_inset LatexCommand \index{Intermediate dump options}
8836
8837 \end_inset
8838
8839
8840 \layout Standard
8841
8842 The following options are provided for the purpose of retargetting and debugging
8843  the compiler.
8844  They provide a means to dump the intermediate code (iCode
8845 \begin_inset LatexCommand \index{iCode}
8846
8847 \end_inset
8848
8849 ) generated by the compiler in human readable form at various stages of
8850  the compilation process.
8851  More on iCodes see chapter
8852 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
8853
8854 \end_inset
8855
8856
8857 \begin_inset Quotes srd
8858 \end_inset
8859
8860 The anatomy of the compiler
8861 \begin_inset Quotes srd
8862 \end_inset
8863
8864 .
8865 \layout List
8866 \labelwidthstring 00.00.0000
8867
8868
8869 \series bold
8870 -
8871 \begin_inset ERT
8872 status Collapsed
8873
8874 \layout Standard
8875
8876 \backslash
8877 /
8878 \end_inset
8879
8880 -dumpraw
8881 \begin_inset LatexCommand \index{-\/-dumpraw}
8882
8883 \end_inset
8884
8885
8886 \series default
8887  This option will cause the compiler to dump the intermediate code into
8888  a file of named
8889 \emph on
8890 <source filename>.dumpraw
8891 \emph default
8892  just after the intermediate code has been generated for a function, i.e.
8893  before any optimizations are done.
8894  The basic blocks
8895 \begin_inset LatexCommand \index{Basic blocks}
8896
8897 \end_inset
8898
8899  at this stage ordered in the depth first number, so they may not be in
8900  sequence of execution.
8901 \layout List
8902 \labelwidthstring 00.00.0000
8903
8904
8905 \series bold
8906 -
8907 \begin_inset ERT
8908 status Collapsed
8909
8910 \layout Standard
8911
8912 \backslash
8913 /
8914 \end_inset
8915
8916 -dumpgcse
8917 \begin_inset LatexCommand \index{-\/-dumpgcse}
8918
8919 \end_inset
8920
8921
8922 \series default
8923  Will create a dump of iCode's, after global subexpression elimination
8924 \begin_inset LatexCommand \index{Global subexpression elimination}
8925
8926 \end_inset
8927
8928 , into a file named
8929 \emph on
8930 <source filename>.dumpgcse.
8931 \layout List
8932 \labelwidthstring 00.00.0000
8933
8934
8935 \series bold
8936 -
8937 \begin_inset ERT
8938 status Collapsed
8939
8940 \layout Standard
8941
8942 \backslash
8943 /
8944 \end_inset
8945
8946 -dumpdeadcode
8947 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
8948
8949 \end_inset
8950
8951
8952 \series default
8953  Will create a dump of iCode's, after deadcode elimination
8954 \begin_inset LatexCommand \index{Dead-code elimination}
8955
8956 \end_inset
8957
8958 , into a file named
8959 \emph on
8960 <source filename>.dumpdeadcode.
8961 \layout List
8962 \labelwidthstring 00.00.0000
8963
8964
8965 \series bold
8966 -
8967 \begin_inset ERT
8968 status Collapsed
8969
8970 \layout Standard
8971
8972 \backslash
8973 /
8974 \end_inset
8975
8976 -dumploop
8977 \begin_inset LatexCommand \index{-\/-dumploop}
8978
8979 \end_inset
8980
8981
8982 \series default
8983 \size large
8984
8985 \size default
8986 Will create a dump of iCode's, after loop optimizations
8987 \begin_inset LatexCommand \index{Loop optimization}
8988
8989 \end_inset
8990
8991 , into a file named
8992 \emph on
8993 <source filename>.dumploop.
8994 \layout List
8995 \labelwidthstring 00.00.0000
8996
8997
8998 \series bold
8999 -
9000 \begin_inset ERT
9001 status Collapsed
9002
9003 \layout Standard
9004
9005 \backslash
9006 /
9007 \end_inset
9008
9009 -dumprange
9010 \begin_inset LatexCommand \index{-\/-dumprange}
9011
9012 \end_inset
9013
9014
9015 \series default
9016 \size large
9017
9018 \size default
9019 Will create a dump of iCode's, after live range analysis
9020 \begin_inset LatexCommand \index{Live range analysis}
9021
9022 \end_inset
9023
9024 , into a file named
9025 \emph on
9026 <source filename>.dumprange.
9027 \layout List
9028 \labelwidthstring 00.00.0000
9029
9030
9031 \series bold
9032 -
9033 \begin_inset ERT
9034 status Collapsed
9035
9036 \layout Standard
9037
9038 \backslash
9039 /
9040 \end_inset
9041
9042 -dumlrange
9043 \begin_inset LatexCommand \index{-\/-dumlrange}
9044
9045 \end_inset
9046
9047
9048 \series default
9049  Will dump the life ranges
9050 \begin_inset LatexCommand \index{Live range analysis}
9051
9052 \end_inset
9053
9054  for all symbols.
9055 \layout List
9056 \labelwidthstring 00.00.0000
9057
9058
9059 \series bold
9060 -
9061 \begin_inset ERT
9062 status Collapsed
9063
9064 \layout Standard
9065
9066 \backslash
9067 /
9068 \end_inset
9069
9070 -dumpregassign
9071 \begin_inset LatexCommand \index{-\/-dumpregassign}
9072
9073 \end_inset
9074
9075
9076 \bar under
9077
9078 \series default
9079 \bar default
9080 Will create a dump of iCode's, after register assignment
9081 \begin_inset LatexCommand \index{Register assignment}
9082
9083 \end_inset
9084
9085 , into a file named
9086 \emph on
9087 <source filename>.dumprassgn.
9088 \layout List
9089 \labelwidthstring 00.00.0000
9090
9091
9092 \series bold
9093 -
9094 \begin_inset ERT
9095 status Collapsed
9096
9097 \layout Standard
9098
9099 \backslash
9100 /
9101 \end_inset
9102
9103 -dumplrange
9104 \begin_inset LatexCommand \index{-\/-dumplrange}
9105
9106 \end_inset
9107
9108
9109 \series default
9110  Will create a dump of the live ranges of iTemp's
9111 \layout List
9112 \added_space_bottom bigskip \labelwidthstring 00.00.0000
9113
9114
9115 \series bold
9116 -
9117 \begin_inset ERT
9118 status Collapsed
9119
9120 \layout Standard
9121
9122 \backslash
9123 /
9124 \end_inset
9125
9126 -dumpall
9127 \begin_inset LatexCommand \index{-\/-dumpall}
9128
9129 \end_inset
9130
9131
9132 \size large
9133 \bar under
9134
9135 \series default
9136 \size default
9137 \bar default
9138 Will cause all the above mentioned dumps to be created.
9139 \layout Subsection
9140
9141 Redirecting output on Windows Shells
9142 \layout Standard
9143 \added_space_bottom bigskip
9144 By default SDCC writes it's error messages to
9145 \begin_inset Quotes sld
9146 \end_inset
9147
9148 standard error
9149 \begin_inset Quotes srd
9150 \end_inset
9151
9152 .
9153  To force all messages to
9154 \begin_inset Quotes sld
9155 \end_inset
9156
9157 standard output
9158 \begin_inset Quotes srd
9159 \end_inset
9160
9161  use
9162 \series bold
9163 -
9164 \series default
9165 \emph on
9166
9167 \begin_inset ERT
9168 status Collapsed
9169
9170 \layout Standard
9171
9172 \backslash
9173 /
9174 \end_inset
9175
9176
9177 \series bold
9178 \emph default
9179 -
9180 \series default
9181 use-stdout
9182 \begin_inset LatexCommand \index{-\/-use-stdout}
9183
9184 \end_inset
9185
9186 .
9187  Additionally, if you happen to have visual studio installed in your windows
9188  machine, you can use it to compile your sources using a custom build and
9189  the SDCC -
9190 \emph on
9191
9192 \begin_inset ERT
9193 status Collapsed
9194
9195 \layout Standard
9196
9197 \backslash
9198 /
9199 \end_inset
9200
9201
9202 \emph default
9203 -vc
9204 \begin_inset LatexCommand \index{-\/-vc}
9205
9206 \end_inset
9207
9208  option.
9209  Something like this should work:
9210 \newline
9211
9212 \newline
9213
9214 \series bold
9215 c:
9216 \backslash
9217 sdcc
9218 \backslash
9219 bin
9220 \backslash
9221 sdcc.exe -
9222 \series default
9223 \emph on
9224
9225 \begin_inset ERT
9226 status Collapsed
9227
9228 \layout Standard
9229
9230 \backslash
9231 /
9232 \end_inset
9233
9234
9235 \series bold
9236 \emph default
9237 -vc -
9238 \series default
9239 \emph on
9240
9241 \begin_inset ERT
9242 status Collapsed
9243
9244 \layout Standard
9245
9246 \backslash
9247 /
9248 \end_inset
9249
9250
9251 \series bold
9252 \emph default
9253 -model-large -c $(InputPath)
9254 \layout Section
9255
9256 Environment variables
9257 \begin_inset LatexCommand \index{Environment variables}
9258
9259 \end_inset
9260
9261
9262 \layout Standard
9263
9264 SDCC recognizes the following environment variables:
9265 \layout List
9266 \labelwidthstring 00.00.0000
9267
9268
9269 \series bold
9270 SDCC_LEAVE_SIGNALS
9271 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
9272
9273 \end_inset
9274
9275
9276 \series default
9277  SDCC installs a signal handler
9278 \begin_inset LatexCommand \index{signal handler}
9279
9280 \end_inset
9281
9282  to be able to delete temporary files after an user break (^C) or an exception.
9283  If this environment variable is set, SDCC won't install the signal handler
9284  in order to be able to debug SDCC.
9285 \layout List
9286 \labelwidthstring 00.00.0000
9287
9288
9289 \series bold
9290 TMP,\SpecialChar ~
9291 TEMP,\SpecialChar ~
9292 TMPDIR
9293 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
9294
9295 \end_inset
9296
9297
9298 \series default
9299  Path, where temporary files will be created.
9300  The order of the variables is the search order.
9301  In a standard *nix environment these variables are not set, and there's
9302  no need to set them.
9303  On Windows it's recommended to set one of them.
9304 \layout List
9305 \labelwidthstring 00.00.0000
9306
9307
9308 \series bold
9309 SDCC_HOME
9310 \begin_inset LatexCommand \index{SDCC\_HOME}
9311
9312 \end_inset
9313
9314
9315 \series default
9316  Path, see section
9317 \begin_inset LatexCommand \ref{sub:Install-paths}
9318
9319 \end_inset
9320
9321 \SpecialChar ~
9322
9323 \begin_inset Quotes sld
9324 \end_inset
9325
9326  Install Paths
9327 \begin_inset Quotes srd
9328 \end_inset
9329
9330 .
9331 \layout List
9332 \labelwidthstring 00.00.0000
9333
9334
9335 \series bold
9336 SDCC_INCLUDE
9337 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
9338
9339 \end_inset
9340
9341
9342 \series default
9343  Path, see section
9344 \begin_inset LatexCommand \ref{sub:Search-Paths}
9345
9346 \end_inset
9347
9348 \SpecialChar ~
9349
9350 \begin_inset Quotes sld
9351 \end_inset
9352
9353 Search Paths
9354 \begin_inset Quotes srd
9355 \end_inset
9356
9357 .
9358 \layout List
9359 \labelwidthstring 00.00.0000
9360
9361
9362 \series bold
9363 SDCC_LIB
9364 \begin_inset LatexCommand \index{SDCC\_LIB}
9365
9366 \end_inset
9367
9368
9369 \series default
9370  Path, see section
9371 \begin_inset LatexCommand \ref{sub:Search-Paths}
9372
9373 \end_inset
9374
9375 \SpecialChar ~
9376
9377 \begin_inset Quotes sld
9378 \end_inset
9379
9380 Search Paths
9381 \begin_inset Quotes srd
9382 \end_inset
9383
9384 ..
9385 \layout Standard
9386 \added_space_bottom bigskip
9387 There are some more environment variables recognized by SDCC, but these
9388  are solely used for debugging purposes.
9389  They can change or disappear very quickly, and will never be documented.
9390 \layout Section
9391
9392 Storage Class Language Extensions
9393 \layout Subsection
9394
9395 MCS51/DS390 Storage Class
9396 \begin_inset LatexCommand \index{Storage class}
9397
9398 \end_inset
9399
9400  Language Extensions
9401 \layout Standard
9402
9403 In addition to the ANSI storage classes SDCC allows the following MCS51
9404  specific storage classes:
9405 \layout Subsubsection
9406
9407 data
9408 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
9409
9410 \end_inset
9411
9412
9413 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
9414
9415 \end_inset
9416
9417  / near
9418 \begin_inset LatexCommand \index{near (storage class)}
9419
9420 \end_inset
9421
9422
9423 \begin_inset LatexCommand \index{\_\_near (storage class)}
9424
9425 \end_inset
9426
9427
9428 \layout Standard
9429
9430 This is the
9431 \series bold
9432 default
9433 \series default
9434  storage class for the Small Memory model (
9435 \emph on
9436 data
9437 \emph default
9438  and
9439 \emph on
9440 near
9441 \emph default
9442  or the more ANSI-C compliant forms
9443 \emph on
9444 __data
9445 \emph default
9446  and
9447 \emph on
9448 __near
9449 \emph default
9450  can be used synonymously).
9451  Variables declared with this storage class will be allocated in the directly
9452  addressable portion of the internal RAM of a 8051, e.g.:
9453 \layout Verse
9454
9455
9456 \family typewriter
9457 __data unsigned char test_data;
9458 \layout Standard
9459
9460 Writing 0x01 to this variable generates the assembly code:
9461 \layout Verse
9462
9463
9464 \family typewriter
9465 75*00 01\SpecialChar ~
9466 \SpecialChar ~
9467 \SpecialChar ~
9468 mov\SpecialChar ~
9469 \SpecialChar ~
9470 _test_data,#0x01
9471 \layout Subsubsection
9472
9473 xdata
9474 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9475
9476 \end_inset
9477
9478
9479 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9480
9481 \end_inset
9482
9483  / far
9484 \begin_inset LatexCommand \index{far (storage class)}
9485
9486 \end_inset
9487
9488
9489 \begin_inset LatexCommand \index{\_\_far (storage class)}
9490
9491 \end_inset
9492
9493
9494 \layout Standard
9495
9496 Variables declared with this storage class will be placed in the external
9497  RAM.
9498  This is the
9499 \series bold
9500 default
9501 \series default
9502  storage class for the Large Memory model, e.g.:
9503 \layout Verse
9504
9505
9506 \family typewriter
9507 __xdata unsigned char test_xdata;
9508 \layout Standard
9509
9510 Writing 0x01 to this variable generates the assembly code:
9511 \layout Verse
9512
9513
9514 \family typewriter
9515 90s00r00\SpecialChar ~
9516 \SpecialChar ~
9517 \SpecialChar ~
9518 mov\SpecialChar ~
9519 \SpecialChar ~
9520 dptr,#_test_xdata
9521 \newline
9522 74\SpecialChar ~
9523 01\SpecialChar ~
9524 \SpecialChar ~
9525 \SpecialChar ~
9526 \SpecialChar ~
9527 \SpecialChar ~
9528 \SpecialChar ~
9529 mov\SpecialChar ~
9530 \SpecialChar ~
9531 a,#0x01
9532 \newline
9533 F0\SpecialChar ~
9534 \SpecialChar ~
9535 \SpecialChar ~
9536 \SpecialChar ~
9537 \SpecialChar ~
9538 \SpecialChar ~
9539 \SpecialChar ~
9540 \SpecialChar ~
9541 \SpecialChar ~
9542 movx\SpecialChar ~
9543 @dptr,a
9544 \layout Subsubsection
9545
9546 idata
9547 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
9548
9549 \end_inset
9550
9551
9552 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
9553
9554 \end_inset
9555
9556
9557 \layout Standard
9558
9559 Variables declared with this storage class will be allocated into the indirectly
9560  addressable portion of the internal ram of a 8051, e.g.:
9561 \layout Verse
9562
9563
9564 \family typewriter
9565 __idata unsigned char test_idata;
9566 \layout Standard
9567
9568 Writing 0x01 to this variable generates the assembly code:
9569 \layout Verse
9570
9571
9572 \family typewriter
9573 78r00\SpecialChar ~
9574 \SpecialChar ~
9575 \SpecialChar ~
9576 \SpecialChar ~
9577 \SpecialChar ~
9578 \SpecialChar ~
9579 \SpecialChar ~
9580 mov\SpecialChar ~
9581 \SpecialChar ~
9582 r0,#_test_idata
9583 \newline
9584 76\SpecialChar ~
9585 01\SpecialChar ~
9586 \SpecialChar ~
9587 \SpecialChar ~
9588 \SpecialChar ~
9589 \SpecialChar ~
9590 \SpecialChar ~
9591 \SpecialChar ~
9592 mov\SpecialChar ~
9593 \SpecialChar ~
9594 @r0,#0x01
9595 \layout Standard
9596
9597 Please note, the first 128 byte of idata physically access the same RAM
9598  as the data memory.
9599  The original 8051 had 128 byte idata memory, nowadays most devices have
9600  256 byte idata memory.
9601  The stack
9602 \begin_inset LatexCommand \index{stack}
9603
9604 \end_inset
9605
9606  is located in idata memory.
9607 \layout Subsubsection
9608
9609 pdata
9610 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
9611
9612 \end_inset
9613
9614
9615 \begin_inset LatexCommand \index{\_\_pdata (mcs51, ds390 storage class)}
9616
9617 \end_inset
9618
9619
9620 \layout Standard
9621
9622 Paged xdata access is just as straightforward as using the other addressing
9623  modes of a 8051.
9624  It is typically located at the start of xdata and has a maximum size of
9625  256 bytes.
9626  The following example writes 0x01 to the pdata variable.
9627  Please note, pdata access physically accesses xdata memory.
9628  The high byte of the address is determined by port P2
9629 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
9630
9631 \end_inset
9632
9633 (or in case of some 8051 variants by a separate Special Function Register,
9634  see section
9635 \begin_inset LatexCommand \ref{sub:MCS51-variants}
9636
9637 \end_inset
9638
9639 ).
9640  This is the
9641 \series bold
9642 default
9643 \series default
9644  storage class for the Medium Memory model, e.g.:
9645 \layout Verse
9646
9647
9648 \family typewriter
9649 __pdata unsigned char test_pdata;
9650 \layout Standard
9651
9652 Writing 0x01 to this variable generates the assembly code:
9653 \layout Verse
9654
9655
9656 \family typewriter
9657 78r00\SpecialChar ~
9658 \SpecialChar ~
9659 \SpecialChar ~
9660 \SpecialChar ~
9661 \SpecialChar ~
9662 \SpecialChar ~
9663 mov r0,#_test_pdata
9664 \newline
9665 74 01\SpecialChar ~
9666 \SpecialChar ~
9667 \SpecialChar ~
9668 \SpecialChar ~
9669 \SpecialChar ~
9670 \SpecialChar ~
9671 mov a,#0x01
9672 \newline
9673 F2\SpecialChar ~
9674 \SpecialChar ~
9675 \SpecialChar ~
9676 \SpecialChar ~
9677 \SpecialChar ~
9678 \SpecialChar ~
9679 \SpecialChar ~
9680 \SpecialChar ~
9681 \SpecialChar ~
9682 movx @r0,a
9683 \layout Standard
9684
9685 If the -
9686 \begin_inset ERT
9687 status Collapsed
9688
9689 \layout Standard
9690
9691 \backslash
9692 /
9693 \end_inset
9694
9695 -xstack
9696 \begin_inset LatexCommand \index{-\/-xstack}
9697
9698 \end_inset
9699
9700  option is used the pdata memory area is followed by the xstack memory area
9701  and the sum of their sizes is limited to 256 bytes.
9702 \layout Subsubsection
9703
9704 code
9705 \begin_inset LatexCommand \index{code}
9706
9707 \end_inset
9708
9709
9710 \begin_inset LatexCommand \index{\_\_code}
9711
9712 \end_inset
9713
9714
9715 \layout Standard
9716
9717 'Variables' declared with this storage class will be placed in the code
9718  memory:
9719 \layout Verse
9720
9721
9722 \family typewriter
9723 __code unsigned char test_code;
9724 \layout Standard
9725
9726 Read access to this variable generates the assembly code:
9727 \layout Verse
9728
9729
9730 \family typewriter
9731 90s00r6F\SpecialChar ~
9732 \SpecialChar ~
9733 \SpecialChar ~
9734 mov dptr,#_test_code
9735 \newline
9736 E4\SpecialChar ~
9737 \SpecialChar ~
9738 \SpecialChar ~
9739 \SpecialChar ~
9740 \SpecialChar ~
9741 \SpecialChar ~
9742 \SpecialChar ~
9743 \SpecialChar ~
9744 \SpecialChar ~
9745 clr a
9746 \newline
9747 93\SpecialChar ~
9748 \SpecialChar ~
9749 \SpecialChar ~
9750 \SpecialChar ~
9751 \SpecialChar ~
9752 \SpecialChar ~
9753 \SpecialChar ~
9754 \SpecialChar ~
9755 \SpecialChar ~
9756 movc a,@a+dptr
9757 \layout Standard
9758
9759
9760 \family typewriter
9761 char
9762 \family default
9763  indexed arrays of characters in code memory can be accessed efficiently:
9764 \layout Verse
9765
9766
9767 \family typewriter
9768 __code char test_array[] = {'c','h','e','a','p'};
9769 \layout Standard
9770
9771 Read access to this array using an 8-bit unsigned index generates the assembly
9772  code:
9773 \layout Verse
9774
9775
9776 \family typewriter
9777 E5*00\SpecialChar ~
9778 \SpecialChar ~
9779 \SpecialChar ~
9780 \SpecialChar ~
9781 \SpecialChar ~
9782 \SpecialChar ~
9783 mov a,_index
9784 \layout Verse
9785
9786
9787 \family typewriter
9788 90s00r41\SpecialChar ~
9789 \SpecialChar ~
9790 \SpecialChar ~
9791 mov dptr,#_test_array
9792 \layout Verse
9793
9794
9795 \family typewriter
9796 93\SpecialChar ~
9797 \SpecialChar ~
9798 \SpecialChar ~
9799 \SpecialChar ~
9800 \SpecialChar ~
9801 \SpecialChar ~
9802 \SpecialChar ~
9803 \SpecialChar ~
9804 \SpecialChar ~
9805 movc a,@a+dptr
9806 \layout Subsubsection
9807
9808 bit
9809 \begin_inset LatexCommand \index{bit}
9810
9811 \end_inset
9812
9813
9814 \begin_inset LatexCommand \index{\_\_bit}
9815
9816 \end_inset
9817
9818
9819 \layout Standard
9820
9821 This is a data-type and a storage class specifier.
9822  When a variable is declared as a bit, it is allocated into the bit addressable
9823  memory of 8051, e.g.:
9824 \layout Verse
9825
9826
9827 \family typewriter
9828 __bit test_bit;
9829 \layout Standard
9830
9831 Writing 1 to this variable generates the assembly code:
9832 \layout Verse
9833
9834
9835 \family typewriter
9836 D2*00\SpecialChar ~
9837 \SpecialChar ~
9838 \SpecialChar ~
9839 \SpecialChar ~
9840 \SpecialChar ~
9841 \SpecialChar ~
9842 \SpecialChar ~
9843 setb\SpecialChar ~
9844 _test_bit
9845 \layout Standard
9846
9847 The bit addressable memory consists of 128 bits which are located from 0x20
9848  to 0x2f in data memory.
9849
9850 \newline
9851 Apart from this 8051 specific storage class most architectures support ANSI-C
9852  bitfields
9853 \begin_inset LatexCommand \index{bitfields}
9854
9855 \end_inset
9856
9857
9858 \begin_inset Foot
9859 collapsed false
9860
9861 \layout Standard
9862
9863 Not really meant as examples, but nevertheless showing what bitfields are
9864  about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
9865 \end_inset
9866
9867 .
9868  In accordance with ISO/IEC 9899 bits and bitfields without an explicit
9869  signed modifier are implemented as unsigned.
9870 \layout Subsubsection
9871
9872 sfr
9873 \begin_inset LatexCommand \index{sfr}
9874
9875 \end_inset
9876
9877
9878 \begin_inset LatexCommand \index{\_\_sfr}
9879
9880 \end_inset
9881
9882  / sfr16
9883 \begin_inset LatexCommand \index{sfr16}
9884
9885 \end_inset
9886
9887
9888 \begin_inset LatexCommand \index{\_\_sfr16}
9889
9890 \end_inset
9891
9892  / sfr32
9893 \begin_inset LatexCommand \index{sfr32}
9894
9895 \end_inset
9896
9897
9898 \begin_inset LatexCommand \index{\_\_sfr32}
9899
9900 \end_inset
9901
9902  / sbit
9903 \begin_inset LatexCommand \index{\_\_sbit}
9904
9905 \end_inset
9906
9907
9908 \begin_inset LatexCommand \index{sbit}
9909
9910 \end_inset
9911
9912
9913 \layout Standard
9914
9915 Like the bit keyword,
9916 \emph on
9917 sfr / sfr16 / sfr32 / sbit
9918 \emph default
9919 signify both a data-type and storage class, they are used to describe the
9920
9921 \emph on
9922 s
9923 \emph default
9924 pecial
9925 \emph on
9926 f
9927 \emph default
9928 unction
9929 \emph on
9930 r
9931 \emph default
9932 egisters and
9933 \emph on
9934 s
9935 \emph default
9936 pecial
9937 \emph on
9938 bit
9939 \emph default
9940  variables of a 8051, eg:
9941 \layout Verse
9942
9943
9944 \family typewriter
9945 __sfr __at
9946 \begin_inset LatexCommand \index{at}
9947
9948 \end_inset
9949
9950
9951 \begin_inset LatexCommand \index{\_\_at}
9952
9953 \end_inset
9954
9955  (0x80) P0;\SpecialChar ~
9956  /* special function register P0 at location 0x80 */
9957 \newline
9958
9959 \newline
9960 /* 16 bit special function register combination for timer 0
9961 \newline
9962 \SpecialChar ~
9963 \SpecialChar ~
9964  with the high byte at location 0x8C and the low byte at location 0x8A */
9965 \newline
9966 __sfr16 __at (0x8C8A) TMR0;
9967 \newline
9968
9969 \newline
9970 __sbit __at
9971 \begin_inset LatexCommand \index{at}
9972
9973 \end_inset
9974
9975
9976 \begin_inset LatexCommand \index{\_\_at}
9977
9978 \end_inset
9979
9980  (0xd7) CY;\SpecialChar ~
9981  /* CY (Carry Flag
9982 \begin_inset LatexCommand \index{Flags}
9983
9984 \end_inset
9985
9986
9987 \begin_inset LatexCommand \index{Carry flag}
9988
9989 \end_inset
9990
9991 ) */
9992 \layout Standard
9993
9994 Special function registers which are located on an address dividable by
9995  8 are bit-addressable, an
9996 \emph on
9997  sbit
9998 \emph default
9999  addresses a specific bit within these sfr.
10000 \newline
10001 16 Bit and 32 bit special function register combinations which require a
10002  certain access order are better not declared using
10003 \emph on
10004 sfr16
10005 \emph default
10006  or
10007 \emph on
10008 sfr32.
10009
10010 \emph default
10011  Allthough SDCC usually accesses them Least Significant Byte (LSB) first,
10012  this is not guaranteed.
10013 \newline
10014
10015 \layout Standard
10016
10017 Please note, if you use a header file which was written for another compiler
10018  then the sfr / sfr16 / sfr32 / sbit Storage Class extensions will most
10019  likely be
10020 \emph on
10021 not
10022 \emph default
10023 compatible.
10024  Specifically the syntax
10025 \family typewriter
10026 \SpecialChar ~
10027 sfr P0 = 0x80;\SpecialChar ~
10028
10029 \family default
10030  is compiled
10031 \emph on
10032 without warning
10033 \emph default
10034  by SDCC to an assignment of 0x80 to a variable called P0
10035 \family typewriter
10036
10037 \begin_inset Marginal
10038 collapsed true
10039
10040 \layout Standard
10041
10042
10043 \series bold
10044 \SpecialChar ~
10045 !
10046 \end_inset
10047
10048 .
10049
10050 \family default
10051 Nevertheless it is possible to write header files
10052 \begin_inset LatexCommand \index{Header files}
10053
10054 \end_inset
10055
10056
10057 \begin_inset LatexCommand \index{Include files}
10058
10059 \end_inset
10060
10061  which can be shared among different compilers (see section
10062 \begin_inset LatexCommand \ref{sec:Porting-code-to-other-compilers}
10063
10064 \end_inset
10065
10066 ).
10067
10068 \layout Subsubsection
10069
10070 Pointers
10071 \begin_inset LatexCommand \index{Pointer}
10072
10073 \end_inset
10074
10075  to MCS51/DS390 specific memory spaces
10076 \layout Standard
10077
10078 SDCC allows (via language extensions) pointers to explicitly point to any
10079  of the memory spaces
10080 \begin_inset LatexCommand \index{Memory model}
10081
10082 \end_inset
10083
10084  of the 8051.
10085  In addition to the explicit pointers, the compiler uses (by default) generic
10086  pointers which can be used to point to any of the memory spaces.
10087 \newline
10088
10089 \newline
10090 Pointer declaration examples:
10091 \layout Verse
10092
10093
10094 \family typewriter
10095 /* pointer physically in internal ram pointing to object in external ram
10096  */
10097 \newline
10098 __xdata unsigned char * __data p;
10099 \newline
10100
10101 \newline
10102 /* pointer physically in external ram pointing to object in internal ram
10103  */
10104 \newline
10105 __data unsigned char * __xdata p;
10106 \newline
10107
10108 \newline
10109 /* pointer physically in code rom pointing to data in xdata space */
10110 \newline
10111 __xdata unsigned char * __code p;
10112 \newline
10113
10114 \newline
10115 /* pointer physically in code space pointing to data in code space */
10116 \newline
10117 __code unsigned char * __code p;
10118 \newline
10119
10120 \newline
10121 /* generic pointer physically located in xdata space */
10122 \newline
10123 unsigned char * __xdata p;
10124 \newline
10125
10126 \newline
10127 /* generic pointer physically located in default memory space */
10128 \newline
10129 unsigned char * p;
10130 \newline
10131
10132 \newline
10133 /* the following is a function pointer
10134 \begin_inset LatexCommand \index{function pointer}
10135
10136 \end_inset
10137
10138  physically located in data space */
10139 \newline
10140 char (* __data fp)(void);
10141 \layout Standard
10142
10143 Well you get the idea.
10144
10145 \newline
10146
10147 \newline
10148 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
10149 \emph on
10150 generic
10151 \emph default
10152  pointers.
10153
10154 \size small
10155
10156 \newline
10157
10158 \newline
10159
10160 \size default
10161 The highest order byte of the
10162 \emph on
10163 generic
10164 \emph default
10165  pointers contains the data space information.
10166  Assembler support routines are called whenever data is stored or retrieved
10167  using
10168 \emph on
10169 generic
10170 \emph default
10171  pointers.
10172  These are useful for developing reusable library
10173 \begin_inset LatexCommand \index{Libraries}
10174
10175 \end_inset
10176
10177  routines.
10178  Explicitly specifying the pointer
10179 \begin_inset LatexCommand \index{pointer}
10180
10181 \end_inset
10182
10183  type will generate the most efficient code.
10184 \layout Subsubsection
10185
10186 Notes on MCS51 memory
10187 \begin_inset LatexCommand \index{MCS51 memory}
10188
10189 \end_inset
10190
10191  layout
10192 \layout Standard
10193
10194 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
10195  RAM memory which is structured as follows:
10196 \newline
10197
10198 \newline
10199 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
10200
10201 \newline
10202 - Bytes 20-2F - 16 bytes to hold 128 bit
10203 \begin_inset LatexCommand \index{bit}
10204
10205 \end_inset
10206
10207  variables and,
10208 \newline
10209 - Bytes 30-7F - 80 bytes for general purpose use.
10210 \newline
10211
10212 \layout Standard
10213
10214 Additionally some members of the MCS51 family may have up to 128 bytes of
10215  additional, indirectly addressable, internal RAM memory (
10216 \emph on
10217 idata
10218 \emph default
10219
10220 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
10221
10222 \end_inset
10223
10224
10225 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
10226
10227 \end_inset
10228
10229 ).
10230  Furthermore, some chips may have some built in external memory (
10231 \emph on
10232 xdata
10233 \emph default
10234
10235 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
10236
10237 \end_inset
10238
10239
10240 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
10241
10242 \end_inset
10243
10244 ) which should not be confused with the internal, directly addressable RAM
10245  memory (
10246 \emph on
10247 data
10248 \emph default
10249
10250 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
10251
10252 \end_inset
10253
10254
10255 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
10256
10257 \end_inset
10258
10259 ).
10260  Sometimes this built in
10261 \emph on
10262 xdata
10263 \emph default
10264  memory has to be activated before using it (you can probably find this
10265  information on the datasheet of the microcontroller your are using, see
10266  also section
10267 \begin_inset LatexCommand \ref{sub:Startup-Code}
10268
10269 \end_inset
10270
10271 \SpecialChar ~
10272 Startup-Code).
10273 \layout Standard
10274
10275 Normally SDCC will only use the first bank
10276 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
10277
10278 \end_inset
10279
10280  of registers (register bank 0), but it is possible to specify that other
10281  banks of registers (keyword
10282 \emph on
10283 using
10284 \emph default
10285
10286 \emph on
10287
10288 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10289
10290 \end_inset
10291
10292
10293 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
10294
10295 \end_inset
10296
10297
10298 \emph default
10299 ) should be used in interrupt
10300 \begin_inset LatexCommand \index{interrupt}
10301
10302 \end_inset
10303
10304
10305 \begin_inset LatexCommand \index{\_\_interrupt}
10306
10307 \end_inset
10308
10309  routines.
10310  By default, the compiler will place the stack after the last byte of allocated
10311  memory for variables.
10312  For example, if the first 2 banks of registers are used, and only four
10313  bytes are used for
10314 \emph on
10315 data
10316 \emph default
10317  variables, it will position the base of the internal stack at address 20
10318  (0x14).
10319  This implies that as the stack
10320 \begin_inset LatexCommand \index{stack}
10321
10322 \end_inset
10323
10324  grows, it will use up the remaining register banks, and the 16 bytes used
10325  by the 128 bit variables, and 80 bytes for general purpose use.
10326  If any bit variables are used, the data variables will be placed in unused
10327  register banks and after the byte holding the last bit variable.
10328  For example, if register banks 0 and 1 are used, and there are 9 bit variables
10329  (two bytes used),
10330 \emph on
10331 data
10332 \emph default
10333  variables will be placed starting from address 0x10 to 0x20 and continue
10334  at address 0x22.
10335  You can also use -
10336 \begin_inset ERT
10337 status Collapsed
10338
10339 \layout Standard
10340
10341 \backslash
10342 /
10343 \end_inset
10344
10345 -data-loc
10346 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
10347
10348 \end_inset
10349
10350  to specify the start address of the
10351 \emph on
10352 data
10353 \emph default
10354  and -
10355 \begin_inset ERT
10356 status Collapsed
10357
10358 \layout Standard
10359
10360 \backslash
10361 /
10362 \end_inset
10363
10364 -iram-size
10365 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
10366
10367 \end_inset
10368
10369  to specify the size of the total internal RAM (
10370 \emph on
10371 data
10372 \emph default
10373 +
10374 \emph on
10375 idata
10376 \emph default
10377 ).
10378
10379 \newline
10380
10381 \layout Standard
10382
10383 By default the 8051 linker will place the stack after the last byte of (i)data
10384  variables.
10385  Option -
10386 \begin_inset ERT
10387 status Collapsed
10388
10389 \layout Standard
10390
10391 \backslash
10392 /
10393 \end_inset
10394
10395 -stack-loc
10396 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
10397
10398 \end_inset
10399
10400  allows you to specify the start of the stack, i.e.
10401  you could start it after any data in the general purpose area.
10402  If your microcontroller has additional indirectly addressable internal
10403  RAM (
10404 \emph on
10405 idata
10406 \emph default
10407 ) you can place the stack on it.
10408  You may also need to use -
10409 \begin_inset ERT
10410 status Collapsed
10411
10412 \layout Standard
10413
10414 \backslash
10415 /
10416 \end_inset
10417
10418 -xdata-loc
10419 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
10420
10421 \end_inset
10422
10423  to set the start address of the external RAM (
10424 \emph on
10425 xdata
10426 \emph default
10427 ) and -
10428 \begin_inset ERT
10429 status Collapsed
10430
10431 \layout Standard
10432
10433 \backslash
10434 /
10435 \end_inset
10436
10437 -xram-size
10438 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
10439
10440 \end_inset
10441
10442  to specify its size.
10443  Same goes for the code memory, using -
10444 \begin_inset ERT
10445 status Collapsed
10446
10447 \layout Standard
10448
10449 \backslash
10450 /
10451 \end_inset
10452
10453 -code-loc
10454 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
10455
10456 \end_inset
10457
10458  and -
10459 \begin_inset ERT
10460 status Collapsed
10461
10462 \layout Standard
10463
10464 \backslash
10465 /
10466 \end_inset
10467
10468 -code-size
10469 \begin_inset LatexCommand \index{-\/-code-size <Value>}
10470
10471 \end_inset
10472
10473 .
10474  If in doubt, don't specify any options and see if the resulting memory
10475  layout is appropriate, then you can adjust it.
10476 \layout Standard
10477 \added_space_bottom bigskip
10478 The linker generates two files with memory allocation information.
10479  The first, with extension .map
10480 \begin_inset LatexCommand \index{<file>.map}
10481
10482 \end_inset
10483
10484  shows all the variables and segments.
10485  The second with extension .mem
10486 \begin_inset LatexCommand \index{<file>.mem}
10487
10488 \end_inset
10489
10490  shows the final memory layout.
10491  The linker will complain either if memory segments overlap, there is not
10492  enough memory, or there is not enough space for stack.
10493  If you get any linking warnings and/or errors related to stack or segments
10494  allocation, take a look at either the .map or .mem files to find out what
10495  the problem is.
10496  The .mem file may even suggest a solution to the problem.
10497 \layout Subsection
10498
10499 Z80/Z180 Storage Class
10500 \begin_inset LatexCommand \index{Z80!Storage class}
10501
10502 \end_inset
10503
10504  Language Extensions
10505 \layout Subsubsection
10506
10507 sfr
10508 \begin_inset LatexCommand \index{sfr}
10509
10510 \end_inset
10511
10512
10513 \begin_inset LatexCommand \index{\_\_sfr}
10514
10515 \end_inset
10516
10517  (in/out to 8-bit addresses)
10518 \layout Standard
10519
10520 The Z80
10521 \begin_inset LatexCommand \index{Z80}
10522
10523 \end_inset
10524
10525  family has separate address spaces for memory and
10526 \emph on
10527 i
10528 \emph default
10529 nput/
10530 \emph on
10531 o
10532 \emph default
10533 utput memory.
10534  I/O memory
10535 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
10536
10537 \end_inset
10538
10539
10540 \begin_inset LatexCommand \index{Z80!I/O memory}
10541
10542 \end_inset
10543
10544
10545 \begin_inset LatexCommand \index{Z180!I/O memory}
10546
10547 \end_inset
10548
10549  is accessed with special instructions, e.g.:
10550 \layout Verse
10551
10552
10553 \family typewriter
10554 sfr at 0x78 IoPort;\SpecialChar ~
10555 \SpecialChar ~
10556 /* define a var in I/O space at 78h called IoPort */
10557
10558 \layout Standard
10559
10560 Writing 0x01 to this variable generates the assembly code:
10561 \layout Verse
10562
10563
10564 \family typewriter
10565 3E 01\SpecialChar ~
10566 \SpecialChar ~
10567 \SpecialChar ~
10568 \SpecialChar ~
10569 \SpecialChar ~
10570 \SpecialChar ~
10571 ld a,#0x01
10572 \newline
10573 D3 78\SpecialChar ~
10574 \SpecialChar ~
10575 \SpecialChar ~
10576 \SpecialChar ~
10577 \SpecialChar ~
10578 \SpecialChar ~
10579 out (_IoPort),a
10580 \layout Subsubsection
10581
10582 banked sfr
10583 \begin_inset LatexCommand \index{sfr}
10584
10585 \end_inset
10586
10587
10588 \begin_inset LatexCommand \index{\_\_sfr}
10589
10590 \end_inset
10591
10592  (in/out to 16-bit addresses)
10593 \layout Standard
10594
10595 The keyword
10596 \emph on
10597 banked
10598 \emph default
10599  is used to support 16 bit addresses in I/O memory e.g.:
10600 \layout Verse
10601
10602
10603 \family typewriter
10604 sfr banked at
10605 \begin_inset LatexCommand \index{at}
10606
10607 \end_inset
10608
10609
10610 \begin_inset LatexCommand \index{\_\_at}
10611
10612 \end_inset
10613
10614  0x123 IoPort;
10615 \layout Standard
10616
10617 Writing 0x01 to this variable generates the assembly code:
10618 \layout Verse
10619
10620
10621 \family typewriter
10622 01 23 01\SpecialChar ~
10623 \SpecialChar ~
10624 \SpecialChar ~
10625 ld bc,#_IoPort
10626 \newline
10627 3E 01\SpecialChar ~
10628 \SpecialChar ~
10629 \SpecialChar ~
10630 \SpecialChar ~
10631 \SpecialChar ~
10632 \SpecialChar ~
10633 ld a,#0x01
10634 \newline
10635 ED 79\SpecialChar ~
10636 \SpecialChar ~
10637 \SpecialChar ~
10638 \SpecialChar ~
10639 \SpecialChar ~
10640 \SpecialChar ~
10641 out (c),a
10642 \layout Subsubsection
10643
10644 sfr
10645 \begin_inset LatexCommand \index{sfr}
10646
10647 \end_inset
10648
10649
10650 \begin_inset LatexCommand \index{\_\_sfr}
10651
10652 \end_inset
10653
10654  (in0/out0 to 8 bit addresses on Z180
10655 \begin_inset LatexCommand \index{Z180}
10656
10657 \end_inset
10658
10659 /HD64180
10660 \begin_inset LatexCommand \index{HD64180 (see Z180)}
10661
10662 \end_inset
10663
10664 )
10665 \layout Standard
10666 \added_space_bottom bigskip
10667 The compiler option -
10668 \begin_inset ERT
10669 status Collapsed
10670
10671 \layout Standard
10672
10673 \backslash
10674 /
10675 \end_inset
10676
10677 -portmode
10678 \begin_inset LatexCommand \index{Z180!Options!-\/-portmode}
10679
10680 \end_inset
10681
10682 =180 (80) and a compiler #pragma\SpecialChar ~
10683 portmode
10684 \begin_inset LatexCommand \index{Z180!Pragmas!\#pragma portmode}
10685
10686 \end_inset
10687
10688  z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
10689 ns
10690 \family typewriter
10691 in0/out0
10692 \family default
10693  instead of
10694 \family typewriter
10695 in/out
10696 \family default
10697 .
10698  If you include the file z180.h this will be set automatically.
10699 \layout Subsection
10700
10701 HC08 Storage Class
10702 \begin_inset LatexCommand \index{HC08!Storage class}
10703
10704 \end_inset
10705
10706  Language Extensions
10707 \layout Subsubsection
10708
10709 data
10710 \begin_inset LatexCommand \index{data (hc08 storage class)}
10711
10712 \end_inset
10713
10714
10715 \begin_inset LatexCommand \index{\_\_data (hc08 storage class)}
10716
10717 \end_inset
10718
10719
10720 \layout Standard
10721
10722 The data storage class declares a variable that resides in the first 256
10723  bytes of memory (the direct page).
10724  The HC08
10725 \begin_inset LatexCommand \index{HC08}
10726
10727 \end_inset
10728
10729  is most efficient at accessing variables (especially pointers) stored here.
10730 \layout Subsubsection
10731
10732 xdata
10733 \begin_inset LatexCommand \index{xdata (hc08 storage class)}
10734
10735 \end_inset
10736
10737
10738 \begin_inset LatexCommand \index{\_\_xdata (hc08 storage class)}
10739
10740 \end_inset
10741
10742
10743 \layout Standard
10744 \added_space_bottom bigskip
10745 The xdata storage class declares a variable that can reside anywhere in
10746  memory.
10747  This is the default if no storage class is specified.
10748
10749 \layout Section
10750
10751 Absolute Addressing
10752 \begin_inset LatexCommand \index{Absolute addressing}
10753
10754 \end_inset
10755
10756
10757 \layout Standard
10758
10759 Data items can be assigned an absolute address with the
10760 \emph on
10761 at
10762 \begin_inset LatexCommand \index{at}
10763
10764 \end_inset
10765
10766
10767 \begin_inset LatexCommand \index{\_\_at}
10768
10769 \end_inset
10770
10771  <address>
10772 \emph default
10773  keyword, in addition to a storage class, e.g.:
10774 \layout Verse
10775
10776
10777 \family typewriter
10778 xdata
10779 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
10780
10781 \end_inset
10782
10783
10784 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
10785
10786 \end_inset
10787
10788  at
10789 \begin_inset LatexCommand \index{at}
10790
10791 \end_inset
10792
10793
10794 \begin_inset LatexCommand \index{\_\_at}
10795
10796 \end_inset
10797
10798  0x7ffe unsigned int chksum;
10799 \layout Standard
10800
10801 or, better conforming to ISO/IEC 9899 C:
10802 \layout Verse
10803
10804
10805 \family typewriter
10806 __xdata __at (0x7ffe) unsigned int chksum;
10807 \layout Standard
10808
10809 In the above example the variable chksum will be located at 0x7ffe and 0x7fff
10810  of the external ram.
10811  The compiler does
10812 \emph on
10813 not
10814 \emph default
10815  reserve any space for variables declared in this way
10816 \begin_inset Marginal
10817 collapsed true
10818
10819 \layout Standard
10820
10821
10822 \series bold
10823 \SpecialChar ~
10824 !
10825 \end_inset
10826
10827  (they are implemented with an equate in the assembler).
10828  Thus it is left to the programmer to make sure there are no overlaps with
10829  other variables that are declared without the absolute address.
10830  The assembler listing file (.lst
10831 \begin_inset LatexCommand \index{<file>.lst}
10832
10833 \end_inset
10834
10835 ) and the linker output files (.rst
10836 \begin_inset LatexCommand \index{<file>.rst}
10837
10838 \end_inset
10839
10840 ) and (.map
10841 \begin_inset LatexCommand \index{<file>.map}
10842
10843 \end_inset
10844
10845 ) are good places to look for such overlaps.
10846  Variables with an absolute address are
10847 \emph on
10848 not
10849 \begin_inset Marginal
10850 collapsed true
10851
10852 \layout Standard
10853
10854
10855 \series bold
10856 \SpecialChar ~
10857 !
10858 \end_inset
10859
10860
10861 \emph default
10862  initialized
10863 \begin_inset LatexCommand \index{Variable initialization}
10864
10865 \end_inset
10866
10867 .
10868 \layout Standard
10869
10870 In case of memory mapped I/O devices the keyword
10871 \emph on
10872 volatile
10873 \emph default
10874  has to be used to tell the compiler that accesses might not be removed:
10875 \layout Verse
10876
10877
10878 \family typewriter
10879 volatile
10880 \begin_inset LatexCommand \index{volatile}
10881
10882 \end_inset
10883
10884  __xdata
10885 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
10886
10887 \end_inset
10888
10889  __at
10890 \begin_inset LatexCommand \index{at}
10891
10892 \end_inset
10893
10894  (0x8000) unsigned char PORTA_8255;
10895 \layout Standard
10896
10897 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
10898 r) array
10899 \family typewriter
10900 \size footnotesize
10901
10902 \begin_inset LatexCommand \index{Aligned array}
10903
10904 \end_inset
10905
10906
10907 \family default
10908 \size default
10909  starts at a block (256 byte) boundary
10910 \begin_inset LatexCommand \index{block boundary}
10911
10912 \end_inset
10913
10914  (section
10915 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
10916
10917 \end_inset
10918
10919  has an example).
10920 \newline
10921 Absolute addresses can be specified for variables in all storage classes,
10922  e.g.:
10923 \layout Verse
10924
10925
10926 \family typewriter
10927 __bit
10928 \begin_inset LatexCommand \index{bit}
10929
10930 \end_inset
10931
10932  __at
10933 \begin_inset LatexCommand \index{at}
10934
10935 \end_inset
10936
10937  (0x02) bvar;
10938 \layout Standard
10939
10940 The above example will allocate the variable at offset 0x02 in the bit-addressab
10941 le space.
10942  There is no real advantage to assigning absolute addresses to variables
10943  in this manner, unless you want strict control over all the variables allocated.
10944  One possible use would be to write hardware portable code.
10945  For example, if you have a routine that uses one or more of the microcontroller
10946  I/O pins, and such pins are different for two different hardwares, you
10947  can declare the I/O pins in your routine using:
10948 \layout Verse
10949
10950
10951 \family typewriter
10952 extern volatile
10953 \begin_inset LatexCommand \index{volatile}
10954
10955 \end_inset
10956
10957  __bit MOSI;\SpecialChar ~
10958 \SpecialChar ~
10959 \SpecialChar ~
10960 \SpecialChar ~
10961 /* master out, slave in */
10962 \newline
10963 extern volatile __bit MISO;\SpecialChar ~
10964 \SpecialChar ~
10965 \SpecialChar ~
10966 \SpecialChar ~
10967 /* master in, slave out */
10968 \newline
10969 extern volatile __bit MCLK;\SpecialChar ~
10970 \SpecialChar ~
10971 \SpecialChar ~
10972 \SpecialChar ~
10973 /* master clock */
10974 \newline
10975
10976 \newline
10977 /* Input and Output of a byte on a 3-wire serial bus.
10978 \newline
10979 \SpecialChar ~
10980 \SpecialChar ~
10981 \SpecialChar ~
10982 If needed adapt polarity of clock, polarity of data and bit order
10983 \newline
10984 \SpecialChar ~
10985 */
10986 \newline
10987 unsigned char spi_io(unsigned char out_byte)
10988 \newline
10989 {
10990 \newline
10991 \SpecialChar ~
10992 \SpecialChar ~
10993 \SpecialChar ~
10994 \SpecialChar ~
10995 unsigned char i=8;
10996 \newline
10997 \SpecialChar ~
10998 \SpecialChar ~
10999 \SpecialChar ~
11000 \SpecialChar ~
11001 do {
11002 \newline
11003 \SpecialChar ~
11004 \SpecialChar ~
11005 \SpecialChar ~
11006 \SpecialChar ~
11007 \SpecialChar ~
11008 \SpecialChar ~
11009 \SpecialChar ~
11010 \SpecialChar ~
11011 MOSI = out_byte & 0x80;
11012 \newline
11013 \SpecialChar ~
11014 \SpecialChar ~
11015 \SpecialChar ~
11016 \SpecialChar ~
11017 \SpecialChar ~
11018 \SpecialChar ~
11019 \SpecialChar ~
11020 \SpecialChar ~
11021 out_byte <<= 1;
11022 \newline
11023 \SpecialChar ~
11024 \SpecialChar ~
11025 \SpecialChar ~
11026 \SpecialChar ~
11027 \SpecialChar ~
11028 \SpecialChar ~
11029 \SpecialChar ~
11030 \SpecialChar ~
11031 MCLK = 1;
11032 \newline
11033 \SpecialChar ~
11034 \SpecialChar ~
11035 \SpecialChar ~
11036 \SpecialChar ~
11037 \SpecialChar ~
11038 \SpecialChar ~
11039 \SpecialChar ~
11040 \SpecialChar ~
11041 /* _asm nop _endasm; */\SpecialChar ~
11042 \SpecialChar ~
11043 \SpecialChar ~
11044 \SpecialChar ~
11045 \SpecialChar ~
11046 \SpecialChar ~
11047 \SpecialChar ~
11048 \SpecialChar ~
11049 /* for slow peripherals */
11050 \newline
11051 \SpecialChar ~
11052 \SpecialChar ~
11053 \SpecialChar ~
11054 \SpecialChar ~
11055 \SpecialChar ~
11056 \SpecialChar ~
11057 \SpecialChar ~
11058 \SpecialChar ~
11059 if(MISO)
11060 \newline
11061 \SpecialChar ~
11062 \SpecialChar ~
11063 \SpecialChar ~
11064 \SpecialChar ~
11065 \SpecialChar ~
11066 \SpecialChar ~
11067 \SpecialChar ~
11068 \SpecialChar ~
11069 \SpecialChar ~
11070 \SpecialChar ~
11071 \SpecialChar ~
11072 \SpecialChar ~
11073 out_byte += 1;
11074 \newline
11075 \SpecialChar ~
11076 \SpecialChar ~
11077 \SpecialChar ~
11078 \SpecialChar ~
11079 \SpecialChar ~
11080 \SpecialChar ~
11081 \SpecialChar ~
11082 \SpecialChar ~
11083 MCLK = 0;
11084 \newline
11085 \SpecialChar ~
11086 \SpecialChar ~
11087 \SpecialChar ~
11088 \SpecialChar ~
11089 } while(--i);
11090 \newline
11091 \SpecialChar ~
11092 \SpecialChar ~
11093 \SpecialChar ~
11094 \SpecialChar ~
11095 return out_byte;
11096 \newline
11097 }
11098 \layout Standard
11099
11100 Then, someplace in the code for the first hardware you would use
11101 \layout Verse
11102
11103
11104 \family typewriter
11105 __bit __at
11106 \begin_inset LatexCommand \index{at}
11107
11108 \end_inset
11109
11110
11111 \begin_inset LatexCommand \index{\_\_at}
11112
11113 \end_inset
11114
11115  (0x80) MOSI;\SpecialChar ~
11116 \SpecialChar ~
11117 \SpecialChar ~
11118 \SpecialChar ~
11119 /* I/O port 0, bit 0 */
11120 \newline
11121 __bit __at (0x81) MISO;\SpecialChar ~
11122 \SpecialChar ~
11123 \SpecialChar ~
11124 \SpecialChar ~
11125 /* I/O port 0, bit 1 */
11126 \newline
11127 __bit __at (0x82) MCLK;\SpecialChar ~
11128 \SpecialChar ~
11129 \SpecialChar ~
11130 \SpecialChar ~
11131 /* I/O port 0, bit 2 */
11132 \layout Standard
11133
11134 Similarly, for the second hardware you would use
11135 \layout Verse
11136
11137
11138 \family typewriter
11139 __bit __at (0x83) MOSI;\SpecialChar ~
11140 \SpecialChar ~
11141 \SpecialChar ~
11142 \SpecialChar ~
11143 /* I/O port 0, bit 3 */
11144 \newline
11145 __bit __at (0x91) MISO;\SpecialChar ~
11146 \SpecialChar ~
11147 \SpecialChar ~
11148 \SpecialChar ~
11149 /* I/O port 1, bit 1 */
11150 \newline
11151 __bit
11152 \begin_inset LatexCommand \index{bit}
11153
11154 \end_inset
11155
11156  __at (0x92) MCLK;\SpecialChar ~
11157 \SpecialChar ~
11158 \SpecialChar ~
11159 \SpecialChar ~
11160 /* I/O port 1, bit 2 */
11161 \layout Standard
11162 \added_space_bottom bigskip
11163 and you can use the same hardware dependent routine without changes, as
11164  for example in a library.
11165  This is somehow similar to sbit, but only one absolute address has to be
11166  specified in the whole project.
11167 \layout Section
11168
11169 Parameters
11170 \begin_inset LatexCommand \index{Parameters}
11171
11172 \end_inset
11173
11174
11175 \begin_inset LatexCommand \index{function parameter}
11176
11177 \end_inset
11178
11179  & Local Variables
11180 \begin_inset LatexCommand \index{local variables}
11181
11182 \end_inset
11183
11184
11185 \begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
11186
11187 \end_inset
11188
11189
11190 \layout Standard
11191
11192 Automatic (local) variables and parameters to functions can either be placed
11193  on the stack or in data-space.
11194  The default action of the compiler is to place these variables in the internal
11195  RAM (for small model) or external RAM (for large model).
11196  This in fact makes them similar to
11197 \emph on
11198 static
11199 \begin_inset LatexCommand \index{static}
11200
11201 \end_inset
11202
11203
11204 \emph default
11205  so by default functions are non-reentrant
11206 \begin_inset LatexCommand \index{reentrant}
11207
11208 \end_inset
11209
11210 .
11211
11212 \newline
11213
11214 \newline
11215 They can be placed on the stack
11216 \begin_inset LatexCommand \index{stack}
11217
11218 \end_inset
11219
11220  by using the
11221 \emph on
11222  -
11223 \begin_inset ERT
11224 status Collapsed
11225
11226 \layout Standard
11227
11228 \backslash
11229 /
11230 \end_inset
11231
11232 -stack-auto
11233 \begin_inset LatexCommand \index{-\/-stack-auto}
11234
11235 \end_inset
11236
11237
11238 \emph default
11239  option, by using
11240 \emph on
11241 #pragma\SpecialChar ~
11242 stackauto
11243 \emph default
11244
11245 \begin_inset LatexCommand \index{\#pragma stackauto}
11246
11247 \end_inset
11248
11249  or by using the
11250 \emph on
11251 reentrant
11252 \begin_inset LatexCommand \index{reentrant}
11253
11254 \end_inset
11255
11256
11257 \emph default
11258  keyword in the function declaration, e.g.:
11259 \layout Verse
11260
11261
11262 \family typewriter
11263 unsigned char foo(char i) __reentrant
11264 \newline
11265 {
11266 \newline
11267 \SpecialChar ~
11268 \SpecialChar ~
11269 \SpecialChar ~
11270 \SpecialChar ~
11271 ...
11272
11273 \newline
11274 }
11275 \layout Standard
11276
11277 Since stack space on 8051 is limited, the
11278 \emph on
11279 reentrant
11280 \emph default
11281 keyword or the
11282 \emph on
11283  -
11284 \begin_inset ERT
11285 status Collapsed
11286
11287 \layout Standard
11288
11289 \backslash
11290 /
11291 \end_inset
11292
11293 -stack-auto
11294 \emph default
11295  option should be used sparingly.
11296  Note that the reentrant keyword just means that the parameters & local
11297  variables will be allocated to the stack, it
11298 \emph on
11299 does not
11300 \emph default
11301  mean that the function is register bank
11302 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
11303
11304 \end_inset
11305
11306  independent.
11307 \newline
11308
11309 \newline
11310 Local variables
11311 \begin_inset LatexCommand \index{local variables}
11312
11313 \end_inset
11314
11315  can be assigned storage classes and absolute
11316 \begin_inset LatexCommand \index{Absolute addressing}
11317
11318 \end_inset
11319
11320  addresses, e.g.:
11321 \layout Verse
11322
11323
11324 \family typewriter
11325 unsigned char foo()
11326 \newline
11327 {
11328 \newline
11329 \SpecialChar ~
11330 \SpecialChar ~
11331 \SpecialChar ~
11332 \SpecialChar ~
11333 __xdata unsigned char i;
11334 \newline
11335 \SpecialChar ~
11336 \SpecialChar ~
11337 \SpecialChar ~
11338 \SpecialChar ~
11339 __bit bvar;
11340 \newline
11341 \SpecialChar ~
11342 \SpecialChar ~
11343 \SpecialChar ~
11344 \SpecialChar ~
11345 __data __at
11346 \begin_inset LatexCommand \index{at}
11347
11348 \end_inset
11349
11350  (0x31) unsigned char j;
11351 \newline
11352 \SpecialChar ~
11353 \SpecialChar ~
11354 \SpecialChar ~
11355 \SpecialChar ~
11356 ...
11357
11358 \newline
11359 }
11360 \layout Standard
11361
11362 In the above example the variable
11363 \emph on
11364 i
11365 \emph default
11366  will be allocated in the external ram,
11367 \emph on
11368 bvar
11369 \emph default
11370  in bit addressable space and
11371 \emph on
11372  j
11373 \emph default
11374  in internal ram.
11375  When compiled with
11376 \emph on
11377 -
11378 \begin_inset ERT
11379 status Collapsed
11380
11381 \layout Standard
11382
11383 \backslash
11384 /
11385 \end_inset
11386
11387 -stack-auto
11388 \emph default
11389  or when a function is declared as
11390 \emph on
11391 reentrant
11392 \emph default
11393  this should only be done for static variables.
11394 \layout Standard
11395
11396 Parameters
11397 \begin_inset LatexCommand \index{function parameter}
11398
11399 \end_inset
11400
11401  however are not allowed any storage class
11402 \begin_inset LatexCommand \index{Storage class}
11403
11404 \end_inset
11405
11406 , (storage classes for parameters will be ignored), their allocation is
11407  governed by the memory model in use, and the reentrancy options.
11408 \layout Standard
11409
11410 It is however allowed to use bit parameters in reentrant functions and also
11411  non-static local bit variables are supported.
11412  Efficient use is limited to 8 semi-bitregisters in bit space.
11413  They are pushed and popped to stack
11414 \begin_inset LatexCommand \index{stack}
11415
11416 \end_inset
11417
11418  as a single byte just like the normal registers.
11419 \layout Section
11420
11421 Overlaying
11422 \begin_inset LatexCommand \label{sub:Overlaying}
11423
11424 \end_inset
11425
11426
11427 \begin_inset LatexCommand \index{Overlaying}
11428
11429 \end_inset
11430
11431
11432 \layout Standard
11433
11434 For non-reentrant
11435 \begin_inset LatexCommand \index{reentrant}
11436
11437 \end_inset
11438
11439  functions SDCC will try to reduce internal ram space usage by overlaying
11440  parameters and local variables of a function (if possible).
11441  Parameters and local variables
11442 \begin_inset LatexCommand \index{local variables}
11443
11444 \end_inset
11445
11446  of a function will be allocated to an overlayable segment if the function
11447  has
11448 \emph on
11449 no other function calls and the function is non-reentrant and the memory
11450  model
11451 \begin_inset LatexCommand \index{Memory model}
11452
11453 \end_inset
11454
11455  is small.
11456
11457 \emph default
11458  If an explicit storage class
11459 \begin_inset LatexCommand \index{Storage class}
11460
11461 \end_inset
11462
11463  is specified for a local variable, it will NOT be overlayed.
11464 \layout Standard
11465
11466 Note that the compiler (not the linkage editor) makes the decision for overlayin
11467 g the data items.
11468  Functions that are called from an interrupt service routine
11469 \begin_inset Marginal
11470 collapsed true
11471
11472 \layout Standard
11473
11474
11475 \series bold
11476 !
11477 \end_inset
11478
11479  should be preceded by a #pragma\SpecialChar ~
11480 nooverlay
11481 \begin_inset LatexCommand \index{\#pragma nooverlay}
11482
11483 \end_inset
11484
11485  if they are not reentrant.
11486 \layout Standard
11487
11488 Also note that the compiler does not do any processing of inline assembler
11489  code, so the compiler might incorrectly assign local variables and parameters
11490  of a function into the overlay segment if the inline assembler code calls
11491  other c-functions that might use the overlay.
11492  In that case the #pragma\SpecialChar ~
11493 nooverlay should be used.
11494 \layout Standard
11495
11496 Parameters and local variables of functions that contain 16 or 32 bit multiplica
11497 tion
11498 \begin_inset LatexCommand \index{Multiplication}
11499
11500 \end_inset
11501
11502  or division
11503 \begin_inset LatexCommand \index{Division}
11504
11505 \end_inset
11506
11507  will NOT be overlayed since these are implemented using external functions,
11508  e.g.:
11509 \layout Verse
11510
11511
11512 \family typewriter
11513 #pragma save
11514 \newline
11515 #pragma nooverlay
11516 \begin_inset LatexCommand \index{\#pragma nooverlay}
11517
11518 \end_inset
11519
11520
11521 \newline
11522 void set_error(unsigned char errcd)
11523 \newline
11524 {
11525 \newline
11526 \SpecialChar ~
11527 \SpecialChar ~
11528 \SpecialChar ~
11529 \SpecialChar ~
11530 P3 = errcd;
11531 \newline
11532 }
11533 \newline
11534 #pragma restore
11535 \newline
11536
11537 \newline
11538 void some_isr () __interrupt
11539 \begin_inset LatexCommand \index{interrupt}
11540
11541 \end_inset
11542
11543  (2)
11544 \newline
11545 {
11546 \newline
11547 \SpecialChar ~
11548 \SpecialChar ~
11549 \SpecialChar ~
11550 \SpecialChar ~
11551 ...
11552 \newline
11553 \SpecialChar ~
11554 \SpecialChar ~
11555 \SpecialChar ~
11556 \SpecialChar ~
11557 set_error(10);
11558 \newline
11559 \SpecialChar ~
11560 \SpecialChar ~
11561 \SpecialChar ~
11562 \SpecialChar ~
11563 ...
11564
11565 \newline
11566 }
11567 \layout Standard
11568 \added_space_bottom bigskip
11569 In the above example the parameter
11570 \emph on
11571 errcd
11572 \emph default
11573  for the function
11574 \emph on
11575 set_error
11576 \emph default
11577  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
11578 nooverlay was
11579  not present, this could cause unpredictable runtime behavior when called
11580  from an interrupt service routine.
11581  The #pragma\SpecialChar ~
11582 nooverlay ensures that the parameters and local variables for
11583  the function are NOT overlayed.
11584 \layout Section
11585
11586 Interrupt Service Routines
11587 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
11588
11589 \end_inset
11590
11591
11592 \layout Subsection
11593
11594 General Information
11595 \layout Standard
11596
11597 SDCC allows
11598 \emph on
11599 i
11600 \emph default
11601 nterrupt
11602 \emph on
11603 s
11604 \emph default
11605 ervice
11606 \emph on
11607 r
11608 \emph default
11609 outines to be coded in C, with some extended keywords.
11610 \layout Verse
11611
11612
11613 \family typewriter
11614 void timer_isr (void) __interrupt (1) __using (1)
11615 \newline
11616 {
11617 \newline
11618 \SpecialChar ~
11619 \SpecialChar ~
11620 \SpecialChar ~
11621 \SpecialChar ~
11622 ...
11623
11624 \newline
11625 }
11626 \layout Standard
11627
11628 The optional number following the
11629 \emph on
11630 interrupt
11631 \begin_inset LatexCommand \index{interrupt}
11632
11633 \end_inset
11634
11635
11636 \begin_inset LatexCommand \index{\_\_interrupt}
11637
11638 \end_inset
11639
11640
11641 \emph default
11642  keyword is the interrupt number this routine will service.
11643  When present, the compiler will insert a call to this routine in the interrupt
11644  vector table
11645 \begin_inset LatexCommand \index{interrupt vector table}
11646
11647 \end_inset
11648
11649  for the interrupt number specified.
11650  If you have multiple source files in your project, interrupt service routines
11651  can be present in any of them, but a prototype of the isr MUST be present
11652  or included in the file that contains the function
11653 \emph on
11654 main
11655 \emph default
11656 .
11657  The optional (8051 specific) keyword
11658 \emph on
11659 using
11660 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11661
11662 \end_inset
11663
11664
11665 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11666
11667 \end_inset
11668
11669
11670 \emph default
11671  can be used to tell the compiler to use the specified register bank when
11672  generating code for this function.
11673
11674 \newline
11675 Interrupt service routines open the door for some very interesting bugs:
11676 \layout Subsubsection
11677
11678
11679 \begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-volatile}
11680
11681 \end_inset
11682
11683 Common interrupt pitfall: variable not declared
11684 \emph on
11685 volatile
11686 \layout Standard
11687
11688 If an interrupt service routine changes variables which are accessed by
11689  other functions these variables have to be declared
11690 \emph on
11691 volatile
11692 \emph default
11693
11694 \begin_inset LatexCommand \index{volatile}
11695
11696 \end_inset
11697
11698 .
11699  See
11700 \begin_inset LatexCommand \url{http://en.wikipedia.org/wiki/Volatile_variable}
11701
11702 \end_inset
11703
11704  .
11705 \layout Subsubsection
11706
11707
11708 \begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-non-atomic}
11709
11710 \end_inset
11711
11712 Common interrupt pitfall:
11713 \emph on
11714 non-atomic access
11715 \layout Standard
11716
11717 If the access to these variables is not
11718 \emph on
11719 atomic
11720 \begin_inset LatexCommand \index{atomic}
11721
11722 \end_inset
11723
11724
11725 \emph default
11726  (i.e.
11727  the processor needs more than one instruction for the access and could
11728  be interrupted while accessing the variable) the interrupt must be disabled
11729  during the access to avoid inconsistent data.
11730
11731 \newline
11732 Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs and
11733  should be protected by disabling interrupts.
11734  You're not automatically on the safe side if you use 8 bit variables though.
11735  We need an example here: f.e.
11736  on the 8051 the harmless looking
11737 \begin_inset Quotes srd
11738 \end_inset
11739
11740
11741 \family typewriter
11742 flags\SpecialChar ~
11743 |=\SpecialChar ~
11744 0x80;
11745 \family default
11746
11747 \begin_inset Quotes sld
11748 \end_inset
11749
11750  is not atomic if
11751 \family typewriter
11752 flags
11753 \family default
11754  resides in xdata.
11755  Setting
11756 \begin_inset Quotes srd
11757 \end_inset
11758
11759
11760 \family typewriter
11761 flags\SpecialChar ~
11762 |=\SpecialChar ~
11763 0x40;
11764 \family default
11765
11766 \begin_inset Quotes sld
11767 \end_inset
11768
11769  from within an interrupt routine might get lost if the interrupt occurs
11770  at the wrong time.
11771
11772 \begin_inset Quotes sld
11773 \end_inset
11774
11775
11776 \family typewriter
11777 counter\SpecialChar ~
11778 +=\SpecialChar ~
11779 8;
11780 \family default
11781
11782 \begin_inset Quotes srd
11783 \end_inset
11784
11785  is not atomic on the 8051 even if
11786 \family typewriter
11787 counter
11788 \family default
11789  is located in data memory.
11790 \newline
11791 Bugs like these are hard to reproduce and can cause a lot of trouble.
11792
11793 \layout Subsubsection
11794
11795
11796 \begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-stack-overflow}
11797
11798 \end_inset
11799
11800 Common interrupt pitfall:
11801 \emph on
11802 stack overflow
11803 \layout Standard
11804
11805 The return address and the registers used in the interrupt service routine
11806  are saved on the stack
11807 \begin_inset LatexCommand \index{stack}
11808
11809 \end_inset
11810
11811  so there must be sufficient stack space.
11812  If there isn't variables or registers (or even the return address itself)
11813  will be corrupted.
11814  This
11815 \emph on
11816 stack overflow
11817 \emph default
11818
11819 \begin_inset LatexCommand \index{stack overflow}
11820
11821 \end_inset
11822
11823  is most likely to happen if the interrupt occurs during the
11824 \begin_inset Quotes sld
11825 \end_inset
11826
11827 deepest
11828 \begin_inset Quotes srd
11829 \end_inset
11830
11831  subroutine when the stack is already in use for f.e.
11832  many return addresses.
11833 \layout Subsubsection
11834
11835
11836 \begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-non-reentrant}
11837
11838 \end_inset
11839
11840 Common interrupt pitfall:
11841 \emph on
11842 use of non-reentrant functions
11843 \layout Standard
11844
11845 A special note here, int (16 bit) and long (32 bit) integer division
11846 \begin_inset LatexCommand \index{Division}
11847
11848 \end_inset
11849
11850 , multiplication
11851 \begin_inset LatexCommand \index{Multiplication}
11852
11853 \end_inset
11854
11855  & modulus
11856 \begin_inset LatexCommand \index{Modulus}
11857
11858 \end_inset
11859
11860  and floating-point
11861 \begin_inset LatexCommand \index{Floating point support}
11862
11863 \end_inset
11864
11865  operations are implemented using external support routines.
11866  If an interrupt service routine needs to do any of these operations then
11867  the support routines (as mentioned in a following section) will have to
11868  be recompiled using the
11869 \emph on
11870  -
11871 \begin_inset ERT
11872 status Collapsed
11873
11874 \layout Standard
11875
11876 \backslash
11877 /
11878 \end_inset
11879
11880 -stack-auto
11881 \begin_inset LatexCommand \index{-\/-stack-auto}
11882
11883 \end_inset
11884
11885
11886 \emph default
11887  option and the source file will need to be compiled using the
11888 \emph on
11889 -
11890 \begin_inset ERT
11891 status Collapsed
11892
11893 \layout Standard
11894
11895 \backslash
11896 /
11897 \end_inset
11898
11899 -int-long-reent
11900 \emph default
11901
11902 \begin_inset LatexCommand \index{-\/-int-long-reent}
11903
11904 \end_inset
11905
11906  compiler option.
11907
11908 \newline
11909 Note, the type promotion
11910 \begin_inset LatexCommand \index{type promotion}
11911
11912 \end_inset
11913
11914  required by ANSI C can cause 16 bit routines to be used
11915 \begin_inset Marginal
11916 collapsed true
11917
11918 \layout Standard
11919
11920
11921 \series bold
11922 \SpecialChar ~
11923 !
11924 \end_inset
11925
11926  without the programmer being aware of it.
11927  See f.e.
11928  the cast
11929 \family typewriter
11930 (unsigned char)(tail-1)
11931 \family default
11932  within the if clause in section
11933 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
11934
11935 \end_inset
11936
11937 .
11938 \layout Standard
11939 \added_space_bottom bigskip
11940 Calling other functions from an interrupt service routine is not recommended,
11941  avoid it if possible.
11942  Note that when some function is called from an interrupt service routine
11943  it should be preceded by a #pragma\SpecialChar ~
11944 nooverlay
11945 \begin_inset LatexCommand \index{\#pragma nooverlay}
11946
11947 \end_inset
11948
11949  if it is not reentrant.
11950  Furthermore nonreentrant functions should not be called from the main program
11951  while the interrupt service routine might be active.
11952  They also must not be called from low priority interrupt service routines
11953  while a high priority interrupt service routine might be active.
11954  You could use semaphores or make the function
11955 \emph on
11956  critical
11957 \emph default
11958  if all parameters are passed in registers.
11959 \newline
11960  Also see section
11961 \begin_inset LatexCommand \ref{sub:Overlaying}
11962
11963 \end_inset
11964
11965 \SpecialChar ~
11966 about Overlaying and section
11967 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
11968
11969 \end_inset
11970
11971 \SpecialChar ~
11972 about Functions using private register banks.
11973 \layout Subsection
11974
11975 MCS51/DS390 Interrupt Service Routines
11976 \layout Standard
11977
11978 Interrupt
11979 \begin_inset LatexCommand \index{interrupt}
11980
11981 \end_inset
11982
11983  numbers and the corresponding address & descriptions for the Standard 8051/8052
11984  are listed below.
11985  SDCC will automatically adjust the
11986 \begin_inset LatexCommand \index{interrupt vector table}
11987
11988 \end_inset
11989
11990  to the maximum interrupt number specified.
11991 \newline
11992
11993 \layout Standard
11994 \align center
11995
11996 \begin_inset  Tabular
11997 <lyxtabular version="3" rows="9" columns="3">
11998 <features>
11999 <column alignment="center" valignment="top" leftline="true" width="0in">
12000 <column alignment="left" valignment="top" leftline="true" width="0in">
12001 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
12002 <row topline="true" bottomline="true">
12003 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12004 \begin_inset Text
12005
12006 \layout Standard
12007
12008 Interrupt #
12009 \end_inset
12010 </cell>
12011 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12012 \begin_inset Text
12013
12014 \layout Standard
12015
12016 Description
12017 \end_inset
12018 </cell>
12019 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12020 \begin_inset Text
12021
12022 \layout Standard
12023
12024 Vector Address
12025 \end_inset
12026 </cell>
12027 </row>
12028 <row topline="true">
12029 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12030 \begin_inset Text
12031
12032 \layout Standard
12033
12034 0
12035 \end_inset
12036 </cell>
12037 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12038 \begin_inset Text
12039
12040 \layout Standard
12041
12042 External 0
12043 \end_inset
12044 </cell>
12045 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12046 \begin_inset Text
12047
12048 \layout Standard
12049
12050 0x0003
12051 \end_inset
12052 </cell>
12053 </row>
12054 <row topline="true">
12055 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12056 \begin_inset Text
12057
12058 \layout Standard
12059
12060 1
12061 \end_inset
12062 </cell>
12063 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12064 \begin_inset Text
12065
12066 \layout Standard
12067
12068 Timer 0
12069 \end_inset
12070 </cell>
12071 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12072 \begin_inset Text
12073
12074 \layout Standard
12075
12076 0x000b
12077 \end_inset
12078 </cell>
12079 </row>
12080 <row topline="true">
12081 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12082 \begin_inset Text
12083
12084 \layout Standard
12085
12086 2
12087 \end_inset
12088 </cell>
12089 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12090 \begin_inset Text
12091
12092 \layout Standard
12093
12094 External 1
12095 \end_inset
12096 </cell>
12097 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12098 \begin_inset Text
12099
12100 \layout Standard
12101
12102 0x0013
12103 \end_inset
12104 </cell>
12105 </row>
12106 <row topline="true">
12107 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12108 \begin_inset Text
12109
12110 \layout Standard
12111
12112 3
12113 \end_inset
12114 </cell>
12115 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12116 \begin_inset Text
12117
12118 \layout Standard
12119
12120 Timer 1
12121 \end_inset
12122 </cell>
12123 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12124 \begin_inset Text
12125
12126 \layout Standard
12127
12128 0x001b
12129 \end_inset
12130 </cell>
12131 </row>
12132 <row topline="true">
12133 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12134 \begin_inset Text
12135
12136 \layout Standard
12137
12138 4
12139 \end_inset
12140 </cell>
12141 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12142 \begin_inset Text
12143
12144 \layout Standard
12145
12146 Serial
12147 \end_inset
12148 </cell>
12149 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12150 \begin_inset Text
12151
12152 \layout Standard
12153
12154 0x0023
12155 \end_inset
12156 </cell>
12157 </row>
12158 <row topline="true">
12159 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12160 \begin_inset Text
12161
12162 \layout Standard
12163
12164 5
12165 \end_inset
12166 </cell>
12167 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12168 \begin_inset Text
12169
12170 \layout Standard
12171
12172 Timer 2 (8052)
12173 \end_inset
12174 </cell>
12175 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12176 \begin_inset Text
12177
12178 \layout Standard
12179
12180 0x002b
12181 \end_inset
12182 </cell>
12183 </row>
12184 <row topline="true">
12185 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12186 \begin_inset Text
12187
12188 \layout Standard
12189
12190 ...
12191 \end_inset
12192 </cell>
12193 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12194 \begin_inset Text
12195
12196 \layout Standard
12197
12198 \end_inset
12199 </cell>
12200 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12201 \begin_inset Text
12202
12203 \layout Standard
12204
12205 ...
12206 \end_inset
12207 </cell>
12208 </row>
12209 <row topline="true" bottomline="true">
12210 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12211 \begin_inset Text
12212
12213 \layout Standard
12214
12215 n
12216 \end_inset
12217 </cell>
12218 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12219 \begin_inset Text
12220
12221 \layout Standard
12222
12223 \end_inset
12224 </cell>
12225 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12226 \begin_inset Text
12227
12228 \layout Standard
12229
12230 0x0003 + 8*n
12231 \end_inset
12232 </cell>
12233 </row>
12234 </lyxtabular>
12235
12236 \end_inset
12237
12238
12239 \newline
12240
12241 \layout Standard
12242
12243 If the interrupt service routine is defined without
12244 \emph on
12245 using
12246 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
12247
12248 \end_inset
12249
12250
12251 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
12252
12253 \end_inset
12254
12255
12256 \emph default
12257  a register bank or with register bank 0 (
12258 \emph on
12259 using
12260 \emph default
12261  0), the compiler will save the registers used by itself on the stack upon
12262  entry and restore them at exit, however if such an interrupt service routine
12263  calls another function then the entire register bank will be saved on the
12264  stack.
12265  This scheme may be advantageous for small interrupt service routines which
12266  have low register usage.
12267 \layout Standard
12268 \added_space_bottom bigskip
12269 If the interrupt service routine is defined to be using a specific register
12270  bank then only
12271 \emph on
12272 a, b, dptr
12273 \emph default
12274  & psw are saved and restored, if such an interrupt service routine calls
12275  another function (using another register bank) then the entire register
12276  bank of the called function will be saved on the stack
12277 \begin_inset LatexCommand \index{stack}
12278
12279 \end_inset
12280
12281 .
12282  This scheme is recommended for larger interrupt service routines.
12283 \layout Subsection
12284
12285 HC08
12286 \begin_inset LatexCommand \index{HC08}
12287
12288 \end_inset
12289
12290  Interrupt Service Routines
12291 \layout Standard
12292 \added_space_bottom bigskip
12293 Since the number of interrupts
12294 \begin_inset LatexCommand \index{HC08!interrupt}
12295
12296 \end_inset
12297
12298  available is chip specific and the interrupt vector table always ends at
12299  the last byte of memory, the interrupt numbers corresponds to the interrupt
12300  vectors in reverse order of address.
12301  For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
12302  2 will use the interrupt vector at 0xfffa, and so on.
12303  However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
12304  this way; instead see section
12305 \begin_inset LatexCommand \ref{sub:Startup-Code}
12306
12307 \end_inset
12308
12309  for details on customizing startup.
12310 \layout Subsection
12311
12312 Z80 Interrupt Service Routines
12313 \layout Standard
12314
12315 The Z80
12316 \begin_inset LatexCommand \index{Z80}
12317
12318 \end_inset
12319
12320  uses several different methods for determining the correct interrupt
12321 \begin_inset LatexCommand \index{Z80!interrupt}
12322
12323 \end_inset
12324
12325  vector depending on the hardware implementation.
12326  Therefore, SDCC ignores the optional interrupt number and does not attempt
12327  to generate an interrupt vector table.
12328 \layout Standard
12329
12330 By default, SDCC generates code for a maskable interrupt, which uses a RETI
12331  instruction to return from the interrupt.
12332  To write an interrupt handler for the non-maskable interrupt, which needs
12333  a RETN instruction instead, add the
12334 \emph on
12335 critical
12336 \emph default
12337  keyword:
12338 \layout Verse
12339
12340
12341 \family typewriter
12342 void nmi_isr (void) critical interrupt
12343 \newline
12344 {
12345 \newline
12346 \SpecialChar ~
12347 \SpecialChar ~
12348 \SpecialChar ~
12349 \SpecialChar ~
12350 ...
12351
12352 \newline
12353 }
12354 \layout Standard
12355 \added_space_bottom bigskip
12356 However if you need to create a non-interruptable interrupt service routine
12357  you would also require the
12358 \emph on
12359 critical
12360 \emph default
12361  keyword.
12362  To distinguish between this and an nmi_isr you must provide an interrupt
12363  number.
12364 \layout Section
12365
12366 Enabling and Disabling Interrupts
12367 \layout Subsection
12368
12369 Critical Functions and Critical Statements
12370 \layout Standard
12371
12372 A special keyword may be associated with a block or a function declaring
12373  it as
12374 \emph on
12375 critical
12376 \emph default
12377 .
12378  SDCC will generate code to disable all interrupts
12379 \begin_inset LatexCommand \index{interrupt}
12380
12381 \end_inset
12382
12383  upon entry to a critical function and restore the interrupt enable to the
12384  previous state before returning.
12385  Nesting critical functions will need one additional byte on the stack
12386 \begin_inset LatexCommand \index{stack}
12387
12388 \end_inset
12389
12390  for each call.
12391 \layout Verse
12392
12393
12394 \family typewriter
12395 int foo () __critical
12396 \begin_inset LatexCommand \index{critical}
12397
12398 \end_inset
12399
12400
12401 \begin_inset LatexCommand \index{\_\_critical}
12402
12403 \end_inset
12404
12405
12406 \newline
12407 {
12408 \newline
12409 \SpecialChar ~
12410 \SpecialChar ~
12411 \SpecialChar ~
12412 \SpecialChar ~
12413 ...
12414
12415 \newline
12416 \SpecialChar ~
12417 \SpecialChar ~
12418 \SpecialChar ~
12419 \SpecialChar ~
12420 ...
12421
12422 \newline
12423 }
12424 \layout Standard
12425
12426 The critical attribute maybe used with other attributes like
12427 \emph on
12428 reentrant.
12429 \emph default
12430
12431 \newline
12432 The keyword
12433 \emph on
12434 critical
12435 \emph default
12436  may also be used to disable interrupts more locally:
12437 \layout Verse
12438
12439
12440 \family typewriter
12441 __critical{ i++; }
12442 \layout Standard
12443
12444 More than one statement could have been included in the block.
12445 \layout Subsection
12446
12447 Enabling and Disabling Interrupts directly
12448 \layout Standard
12449
12450 Interrupts
12451 \begin_inset LatexCommand \index{interrupt}
12452
12453 \end_inset
12454
12455  can also be disabled and enabled directly (8051):
12456 \layout Verse
12457
12458
12459 \family typewriter
12460 EA = 0;\SpecialChar ~
12461 \SpecialChar ~
12462 \SpecialChar ~
12463 \SpecialChar ~
12464 \SpecialChar ~
12465 \SpecialChar ~
12466 \SpecialChar ~
12467 \SpecialChar ~
12468 \SpecialChar ~
12469 \SpecialChar ~
12470 \SpecialChar ~
12471 \SpecialChar ~
12472 or:\SpecialChar ~
12473 \SpecialChar ~
12474 \SpecialChar ~
12475 \SpecialChar ~
12476 \SpecialChar ~
12477 \SpecialChar ~
12478 \SpecialChar ~
12479 \SpecialChar ~
12480 \SpecialChar ~
12481 \SpecialChar ~
12482 \SpecialChar ~
12483 EA_SAVE = EA;
12484 \layout Verse
12485
12486
12487 \family typewriter
12488 ...\SpecialChar ~
12489 \SpecialChar ~
12490 \SpecialChar ~
12491 \SpecialChar ~
12492 \SpecialChar ~
12493 \SpecialChar ~
12494 \SpecialChar ~
12495 \SpecialChar ~
12496 \SpecialChar ~
12497 \SpecialChar ~
12498 \SpecialChar ~
12499 \SpecialChar ~
12500 \SpecialChar ~
12501 \SpecialChar ~
12502 \SpecialChar ~
12503 \SpecialChar ~
12504 \SpecialChar ~
12505 \SpecialChar ~
12506 \SpecialChar ~
12507 \SpecialChar ~
12508 \SpecialChar ~
12509 \SpecialChar ~
12510 \SpecialChar ~
12511 \SpecialChar ~
12512 \SpecialChar ~
12513 \SpecialChar ~
12514 \SpecialChar ~
12515 \SpecialChar ~
12516 \SpecialChar ~
12517 \SpecialChar ~
12518 EA = 0;
12519 \layout Verse
12520
12521
12522 \family typewriter
12523 EA = 1;\SpecialChar ~
12524 \SpecialChar ~
12525 \SpecialChar ~
12526 \SpecialChar ~
12527 \SpecialChar ~
12528 \SpecialChar ~
12529 \SpecialChar ~
12530 \SpecialChar ~
12531 \SpecialChar ~
12532 \SpecialChar ~
12533 \SpecialChar ~
12534 \SpecialChar ~
12535 \SpecialChar ~
12536 \SpecialChar ~
12537 \SpecialChar ~
12538 \SpecialChar ~
12539 \SpecialChar ~
12540 \SpecialChar ~
12541 \SpecialChar ~
12542 \SpecialChar ~
12543 \SpecialChar ~
12544 \SpecialChar ~
12545 \SpecialChar ~
12546 \SpecialChar ~
12547 \SpecialChar ~
12548 \SpecialChar ~
12549 ...
12550 \layout Verse
12551
12552
12553 \family typewriter
12554 \SpecialChar ~
12555 \SpecialChar ~
12556 \SpecialChar ~
12557 \SpecialChar ~
12558 \SpecialChar ~
12559 \SpecialChar ~
12560 \SpecialChar ~
12561 \SpecialChar ~
12562 \SpecialChar ~
12563 \SpecialChar ~
12564 \SpecialChar ~
12565 \SpecialChar ~
12566 \SpecialChar ~
12567 \SpecialChar ~
12568 \SpecialChar ~
12569 \SpecialChar ~
12570 \SpecialChar ~
12571 \SpecialChar ~
12572 \SpecialChar ~
12573 \SpecialChar ~
12574 \SpecialChar ~
12575 \SpecialChar ~
12576 \SpecialChar ~
12577 \SpecialChar ~
12578 \SpecialChar ~
12579 \SpecialChar ~
12580 \SpecialChar ~
12581 \SpecialChar ~
12582 \SpecialChar ~
12583 \SpecialChar ~
12584 \SpecialChar ~
12585 \SpecialChar ~
12586 \SpecialChar ~
12587 EA = EA_SAVE;
12588 \layout Standard
12589
12590 On other architectures which have seperate opcodes for enabling and disabling
12591  interrupts you might want to make use of defines with inline assembly
12592 \begin_inset LatexCommand \index{Assembler routines}
12593
12594 \end_inset
12595
12596  (HC08
12597 \begin_inset LatexCommand \index{HC08!interrupt}
12598
12599 \end_inset
12600
12601 ):
12602 \layout Verse
12603
12604
12605 \family typewriter
12606 #define CLI _asm
12607 \begin_inset LatexCommand \index{\_asm}
12608
12609 \end_inset
12610
12611 \SpecialChar ~
12612 \SpecialChar ~
12613 cli\SpecialChar ~
12614 \SpecialChar ~
12615 _endasm
12616 \begin_inset LatexCommand \index{\_endasm}
12617
12618 \end_inset
12619
12620 ;
12621 \layout Verse
12622
12623
12624 \family typewriter
12625 #define SEI _asm\SpecialChar ~
12626 \SpecialChar ~
12627 sei\SpecialChar ~
12628 \SpecialChar ~
12629 _endasm;
12630 \layout Verse
12631
12632
12633 \family typewriter
12634 ...
12635 \layout Standard
12636
12637 Note: it is sometimes sufficient to disable only a specific interrupt source
12638  like f.e.
12639  a timer or serial interrupt by manipulating an
12640 \emph on
12641 interrupt mask
12642 \begin_inset LatexCommand \index{interrupt mask}
12643
12644 \end_inset
12645
12646
12647 \emph default
12648  register.
12649
12650 \layout Standard
12651
12652 Usually the time during which interrupts are disabled should be kept as
12653  short as possible.
12654  This minimizes both
12655 \emph on
12656 interrupt latency
12657 \emph default
12658
12659 \begin_inset LatexCommand \index{interrupt latency}
12660
12661 \end_inset
12662
12663  (the time between the occurrence of the interrupt and the execution of
12664  the first code in the interrupt routine) and
12665 \emph on
12666 interrupt jitter
12667 \emph default
12668
12669 \begin_inset LatexCommand \index{interrupt jitter}
12670
12671 \end_inset
12672
12673  (the difference between the shortest and the longest interrupt latency).
12674  These really are something different, f.e.
12675  a serial interrupt has to be served before its buffer overruns so it cares
12676  for the maximum interrupt latency, whereas it does not care about jitter.
12677  On a loudspeaker driven via a digital to analog converter which is fed
12678  by an interrupt a latency of a few milliseconds might be tolerable, whereas
12679  a much smaller jitter will be very audible.
12680 \layout Standard
12681
12682 You can reenable interrupts within an interrupt routine and on some architecture
12683 s you can make use of two (or more) levels of
12684 \emph on
12685 interrupt priorities
12686 \emph default
12687
12688 \begin_inset LatexCommand \index{interrupt priority}
12689
12690 \end_inset
12691
12692 .
12693  On some architectures which don't support interrupt priorities these can
12694  be implemented by manipulating the interrupt mask and reenabling interrupts
12695  within the interrupt routine.
12696  Check there is sufficient space on the stack
12697 \begin_inset LatexCommand \index{stack}
12698
12699 \end_inset
12700
12701  and don't add complexity unless you have to.
12702
12703 \layout Subsection
12704
12705 Semaphore
12706 \begin_inset LatexCommand \index{semaphore}
12707
12708 \end_inset
12709
12710  locking (mcs51/ds390)
12711 \layout Standard
12712
12713 Some architectures (mcs51/ds390) have an atomic
12714 \begin_inset LatexCommand \index{atomic}
12715
12716 \end_inset
12717
12718  bit test and
12719 \emph on
12720
12721 \emph default
12722 clear
12723 \emph on
12724
12725 \emph default
12726 instruction.
12727  These type of instructions are typically used in preemptive multitasking
12728  systems, where a routine f.e.
12729  claims the use of a data structure ('acquires a lock
12730 \begin_inset LatexCommand \index{lock}
12731
12732 \end_inset
12733
12734  on it'), makes some modifications and then releases the lock when the data
12735  structure is consistent again.
12736  The instruction may also be used if interrupt and non-interrupt code have
12737  to compete for a resource.
12738  With the atomic bit test and clear instruction interrupts
12739 \begin_inset LatexCommand \index{interrupt}
12740
12741 \end_inset
12742
12743  don't have to be disabled for the locking operation.
12744
12745 \layout Standard
12746
12747 SDCC generates this instruction if the source follows this pattern:
12748 \layout Verse
12749
12750
12751 \family typewriter
12752 volatile
12753 \begin_inset LatexCommand \index{volatile}
12754
12755 \end_inset
12756
12757  bit resource_is_free;
12758 \newline
12759
12760 \newline
12761 if (resource_is_free)
12762 \newline
12763 \SpecialChar ~
12764 \SpecialChar ~
12765 {
12766 \newline
12767 \SpecialChar ~
12768 \SpecialChar ~
12769 \SpecialChar ~
12770 \SpecialChar ~
12771 resource_is_free=0;
12772 \newline
12773 \SpecialChar ~
12774 \SpecialChar ~
12775 \SpecialChar ~
12776 \SpecialChar ~
12777 ...
12778
12779 \newline
12780 \SpecialChar ~
12781 \SpecialChar ~
12782 \SpecialChar ~
12783 \SpecialChar ~
12784 resource_is_free=1;
12785 \newline
12786 \SpecialChar ~
12787 \SpecialChar ~
12788 }
12789 \layout Standard
12790
12791 Note, mcs51 and ds390 support only an atomic
12792 \begin_inset LatexCommand \index{atomic}
12793
12794 \end_inset
12795
12796  bit test and
12797 \emph on
12798 clear
12799 \emph default
12800  instruction (as opposed to atomic bit test and
12801 \emph on
12802 set).
12803 \layout Section
12804
12805 Functions using private register banks
12806 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
12807
12808 \end_inset
12809
12810  (mcs51/ds390)
12811 \layout Standard
12812
12813 Some architectures have support for quickly changing register sets.
12814  SDCC supports this feature with the
12815 \emph on
12816 using
12817 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
12818
12819 \end_inset
12820
12821
12822 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
12823
12824 \end_inset
12825
12826
12827 \emph default
12828  attribute (which tells the compiler to use a register bank
12829 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
12830
12831 \end_inset
12832
12833  other than the default bank zero).
12834  It should only be applied to
12835 \emph on
12836 interrupt
12837 \begin_inset LatexCommand \index{interrupt}
12838
12839 \end_inset
12840
12841
12842 \emph default
12843  functions (see footnote below).
12844  This will in most circumstances make the generated ISR code more efficient
12845  since it will not have to save registers on the stack.
12846 \layout Standard
12847
12848 The
12849 \emph on
12850 using
12851 \emph default
12852  attribute will have no effect on the generated code for a
12853 \emph on
12854 non-interrupt
12855 \emph default
12856  function (but may occasionally be useful anyway
12857 \begin_inset Foot
12858 collapsed false
12859
12860 \layout Standard
12861
12862 possible exception: if a function is called ONLY from 'interrupt' functions
12863  using a particular bank, it can be declared with the same 'using' attribute
12864  as the calling 'interrupt' functions.
12865  For instance, if you have several ISRs using bank one, and all of them
12866  call memcpy(), it might make sense to create a specialized version of memcpy()
12867  'using 1', since this would prevent the ISR from having to save bank zero
12868  to the stack on entry and switch to bank zero before calling the function
12869 \end_inset
12870
12871 ).
12872 \newline
12873
12874 \emph on
12875 (pending: Note, nowadays the
12876 \emph default
12877 using
12878 \emph on
12879  attribute has an effect on
12880 \emph default
12881
12882 \emph on
12883 the generated code for a
12884 \emph default
12885 non-interrupt
12886 \emph on
12887  function
12888 \emph default
12889 .
12890 \emph on
12891 )
12892 \layout Standard
12893
12894 An
12895 \emph on
12896 interrupt
12897 \emph default
12898  function using a non-zero bank will assume that it can trash that register
12899  bank, and will not save it.
12900  Since high-priority interrupts
12901 \begin_inset LatexCommand \index{interrupts}
12902
12903 \end_inset
12904
12905
12906 \begin_inset LatexCommand \index{interrupt priority}
12907
12908 \end_inset
12909
12910  can interrupt low-priority ones on the 8051 and friends, this means that
12911  if a high-priority ISR
12912 \emph on
12913 using
12914 \emph default
12915  a particular bank occurs while processing a low-priority ISR
12916 \emph on
12917 using
12918 \emph default
12919  the same bank, terrible and bad things can happen.
12920  To prevent this, no single register bank should be
12921 \emph on
12922 used
12923 \emph default
12924  by both a high priority and a low priority ISR.
12925  This is probably most easily done by having all high priority ISRs use
12926  one bank and all low priority ISRs use another.
12927  If you have an ISR which can change priority at runtime, you're on your
12928  own: I suggest using the default bank zero and taking the small performance
12929  hit.
12930 \layout Standard
12931 \added_space_bottom bigskip
12932 It is most efficient if your ISR calls no other functions.
12933  If your ISR must call other functions, it is most efficient if those functions
12934  use the same bank as the ISR (see note 1 below); the next best is if the
12935  called functions use bank zero.
12936  It is very inefficient to call a function using a different, non-zero bank
12937  from an ISR.
12938
12939 \layout Section
12940
12941 Startup Code
12942 \begin_inset LatexCommand \label{sub:Startup-Code}
12943
12944 \end_inset
12945
12946
12947 \begin_inset LatexCommand \index{Startup code}
12948
12949 \end_inset
12950
12951
12952 \layout Subsection
12953
12954 MCS51/DS390 Startup Code
12955 \layout Standard
12956
12957 The compiler inserts a call to the C routine
12958 \emph on
12959 _sdcc_external_startup()
12960 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
12961
12962 \end_inset
12963
12964
12965 \series bold
12966 \emph default
12967
12968 \series default
12969 at the start of the CODE area.
12970  This routine is in the runtime library
12971 \begin_inset LatexCommand \index{Runtime library}
12972
12973 \end_inset
12974
12975 .
12976  By default this routine returns 0, if this routine returns a non-zero value,
12977  the static & global variable initialization will be skipped and the function
12978  main will be invoked.
12979  Otherwise static & global variables will be initialized before the function
12980  main is invoked.
12981  You could add a
12982 \emph on
12983 _sdcc_external_startup()
12984 \emph default
12985  routine to your program to override the default if you need to setup hardware
12986  or perform some other critical operation prior to static & global variable
12987  initialization
12988 \begin_inset LatexCommand \index{Variable initialization}
12989
12990 \end_inset
12991
12992 .
12993  On some mcs51 variants xdata
12994 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
12995
12996 \end_inset
12997
12998  memory has to be explicitly enabled before it can be accessed or if the
12999  watchdog
13000 \begin_inset LatexCommand \index{watchdog}
13001
13002 \end_inset
13003
13004  needs to be disabled, this is the place to do it.
13005  The startup code clears all internal data memory, 256 bytes by default,
13006  but from 0 to n-1 if
13007 \emph on
13008 -
13009 \begin_inset ERT
13010 status Collapsed
13011
13012 \layout Standard
13013
13014 \backslash
13015 /
13016 \end_inset
13017
13018 -iram-size
13019 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
13020
13021 \end_inset
13022
13023 n
13024 \emph default
13025  is used.
13026  (recommended for Chipcon CC1010).
13027 \layout Standard
13028 \added_space_bottom bigskip
13029 See also the compiler options
13030 \emph on
13031 -
13032 \begin_inset ERT
13033 status Collapsed
13034
13035 \layout Standard
13036
13037 \backslash
13038 /
13039 \end_inset
13040
13041 -no-xinit
13042 \emph default
13043 -
13044 \emph on
13045 opt
13046 \emph default
13047
13048 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
13049
13050 \end_inset
13051
13052 ,
13053 \emph on
13054 -
13055 \begin_inset ERT
13056 status Collapsed
13057
13058 \layout Standard
13059
13060 \backslash
13061 /
13062 \end_inset
13063
13064 -main-return
13065 \emph default
13066
13067 \begin_inset LatexCommand \index{-\/-main-return}
13068
13069 \end_inset
13070
13071  and section
13072 \begin_inset LatexCommand \ref{sub:MCS51-variants}
13073
13074 \end_inset
13075
13076  about MCS51-variants.
13077 \layout Subsection
13078
13079 HC08 Startup Code
13080 \layout Standard
13081 \added_space_bottom bigskip
13082 The HC08
13083 \begin_inset LatexCommand \index{HC08}
13084
13085 \end_inset
13086
13087  startup code follows the same scheme as the MCS51 startup code.
13088 \layout Subsection
13089
13090 Z80 Startup Code
13091 \layout Standard
13092 \added_space_bottom bigskip
13093 On the Z80
13094 \begin_inset LatexCommand \index{Z80}
13095
13096 \end_inset
13097
13098  the startup code is inserted by linking with crt0.o which is generated from
13099  sdcc/device/lib/z80/crt0.s.
13100  If you need a different startup code you can use the compiler option
13101 \emph on
13102 -
13103 \series bold
13104 \emph default
13105
13106 \begin_inset ERT
13107 status Collapsed
13108
13109 \layout Standard
13110
13111 \backslash
13112 /
13113 \end_inset
13114
13115
13116 \series default
13117 \emph on
13118 -no-std-crt0
13119 \emph default
13120
13121 \begin_inset LatexCommand \index{-\/-no-std-crt0}
13122
13123 \end_inset
13124
13125  and provide your own crt0.o.
13126
13127 \layout Section
13128
13129 Inline Assembler Code
13130 \begin_inset LatexCommand \index{Assembler routines}
13131
13132 \end_inset
13133
13134
13135 \layout Subsection
13136
13137 A Step by Step Introduction
13138 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
13139
13140 \end_inset
13141
13142
13143 \layout Standard
13144
13145 Starting from a small snippet of c-code this example shows for the MCS51
13146  how to use inline assembly, access variables, a function parameter and
13147  an array in xdata memory.
13148  The example uses an MCS51 here but is easily adapted for other architectures.
13149  This is a buffer routine which should be optimized:
13150 \layout Verse
13151
13152
13153 \family typewriter
13154 \size footnotesize
13155 unsigned char __far
13156 \begin_inset LatexCommand \index{far (storage class)}
13157
13158 \end_inset
13159
13160
13161 \begin_inset LatexCommand \index{\_\_far (storage class)}
13162
13163 \end_inset
13164
13165  __at
13166 \begin_inset LatexCommand \index{at}
13167
13168 \end_inset
13169
13170
13171 \begin_inset LatexCommand \index{\_\_at}
13172
13173 \end_inset
13174
13175 (0x7f00) buf[0x100];
13176 \begin_inset LatexCommand \index{Aligned array}
13177
13178 \end_inset
13179
13180
13181 \newline
13182 unsigned char head, tail;\SpecialChar ~
13183 \SpecialChar ~
13184 \SpecialChar ~
13185 \SpecialChar ~
13186 \SpecialChar ~
13187 \SpecialChar ~
13188 \SpecialChar ~
13189 \SpecialChar ~
13190 \SpecialChar ~
13191 \SpecialChar ~
13192 \SpecialChar ~
13193 \SpecialChar ~
13194 \SpecialChar ~
13195 \SpecialChar ~
13196 \SpecialChar ~
13197 \SpecialChar ~
13198 \SpecialChar ~
13199 /* if interrupts
13200 \begin_inset LatexCommand \index{interrupt}
13201
13202 \end_inset
13203
13204  are involved see
13205 \newline
13206 \SpecialChar ~
13207 \SpecialChar ~
13208 \SpecialChar ~
13209 \SpecialChar ~
13210 \SpecialChar ~
13211 \SpecialChar ~
13212 \SpecialChar ~
13213 \SpecialChar ~
13214 \SpecialChar ~
13215 \SpecialChar ~
13216 \SpecialChar ~
13217 \SpecialChar ~
13218 \SpecialChar ~
13219 \SpecialChar ~
13220 \SpecialChar ~
13221 \SpecialChar ~
13222 \SpecialChar ~
13223 \SpecialChar ~
13224 \SpecialChar ~
13225 \SpecialChar ~
13226 \SpecialChar ~
13227 \SpecialChar ~
13228 \SpecialChar ~
13229 \SpecialChar ~
13230 \SpecialChar ~
13231 \SpecialChar ~
13232 \SpecialChar ~
13233 \SpecialChar ~
13234 \SpecialChar ~
13235 \SpecialChar ~
13236 \SpecialChar ~
13237 \SpecialChar ~
13238 \SpecialChar ~
13239 \SpecialChar ~
13240 \SpecialChar ~
13241 \SpecialChar ~
13242 \SpecialChar ~
13243 \SpecialChar ~
13244 \SpecialChar ~
13245 \SpecialChar ~
13246 \SpecialChar ~
13247 \SpecialChar ~
13248 \SpecialChar ~
13249 \SpecialChar ~
13250 \SpecialChar ~
13251 section
13252 \begin_inset LatexCommand \ref{sub:Common-interrupt-pitfall-volatile}
13253
13254 \end_inset
13255
13256  about
13257 \series bold
13258  volatile
13259 \series default
13260  */
13261 \newline
13262
13263 \newline
13264 void to_buffer( unsigned char c )
13265 \newline
13266 {
13267 \newline
13268 \SpecialChar ~
13269 \SpecialChar ~
13270 \SpecialChar ~
13271 \SpecialChar ~
13272 if( head != (unsigned char)(tail-1) )\SpecialChar ~
13273 /* cast
13274 \series bold
13275 needed
13276 \series default
13277  to avoid promotion
13278 \begin_inset LatexCommand \index{promotion to signed int}
13279
13280 \end_inset
13281
13282
13283 \begin_inset LatexCommand \index{type promotion}
13284
13285 \end_inset
13286
13287  to integer */
13288 \begin_inset Marginal
13289 collapsed true
13290
13291 \layout Standard
13292
13293
13294 \series bold
13295 \SpecialChar ~
13296 !
13297 \end_inset
13298
13299
13300 \newline
13301 \SpecialChar ~
13302 \SpecialChar ~
13303 \SpecialChar ~
13304 \SpecialChar ~
13305 \SpecialChar ~
13306 \SpecialChar ~
13307 \SpecialChar ~
13308 \SpecialChar ~
13309 buf[ head++ ] = c;\SpecialChar ~
13310 \SpecialChar ~
13311 \SpecialChar ~
13312 \SpecialChar ~
13313 \SpecialChar ~
13314 \SpecialChar ~
13315 \SpecialChar ~
13316 \SpecialChar ~
13317 \SpecialChar ~
13318 \SpecialChar ~
13319 \SpecialChar ~
13320 \SpecialChar ~
13321 \SpecialChar ~
13322 \SpecialChar ~
13323 \SpecialChar ~
13324 \SpecialChar ~
13325 /* access to a 256 byte aligned array */
13326 \newline
13327 }
13328 \layout Standard
13329
13330 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
13331  then a corresponding buffer.asm file is generated.
13332  We define a new function
13333 \family typewriter
13334 to_buffer_asm()
13335 \family default
13336  in file buffer.c in which we cut and paste the generated code, removing
13337  unwanted comments and some ':'.
13338  Then add
13339 \begin_inset Quotes sld
13340 \end_inset
13341
13342 _asm
13343 \begin_inset Quotes srd
13344 \end_inset
13345
13346  and
13347 \begin_inset Quotes sld
13348 \end_inset
13349
13350 _endasm;
13351 \begin_inset Quotes srd
13352 \end_inset
13353
13354  to the beginning and the end of the function body:
13355 \layout Verse
13356
13357
13358 \family typewriter
13359 \size footnotesize
13360 /* With a cut and paste from the .asm file, we have something to start with.
13361 \newline
13362 \SpecialChar ~
13363 \SpecialChar ~
13364 \SpecialChar ~
13365 The function is not yet OK! (registers aren't saved) */
13366 \newline
13367 void to_buffer_asm( unsigned char c )
13368 \newline
13369 {
13370 \newline
13371 \SpecialChar ~
13372 \SpecialChar ~
13373 \SpecialChar ~
13374 \SpecialChar ~
13375 _asm
13376 \begin_inset LatexCommand \index{\_asm}
13377
13378 \end_inset
13379
13380
13381 \begin_inset LatexCommand \index{\_\_asm}
13382
13383 \end_inset
13384
13385
13386 \newline
13387 \SpecialChar ~
13388 \SpecialChar ~
13389 \SpecialChar ~
13390 \SpecialChar ~
13391 mov\SpecialChar ~
13392 \SpecialChar ~
13393 r2,dpl
13394 \newline
13395 ;buffer.c if( head != (unsigned char)(tail-1) ) \SpecialChar ~
13396 /* cast
13397 \series bold
13398 needed
13399 \series default
13400  to avoid promotion
13401 \begin_inset LatexCommand \index{promotion to signed int}
13402
13403 \end_inset
13404
13405
13406 \begin_inset LatexCommand \index{type promotion}
13407
13408 \end_inset
13409
13410  to integer */
13411 \newline
13412 \SpecialChar ~
13413 \SpecialChar ~
13414 \SpecialChar ~
13415 \SpecialChar ~
13416 mov\SpecialChar ~
13417 \SpecialChar ~
13418 a,_tail
13419 \newline
13420 \SpecialChar ~
13421 \SpecialChar ~
13422 \SpecialChar ~
13423 \SpecialChar ~
13424 dec\SpecialChar ~
13425 \SpecialChar ~
13426 a
13427 \newline
13428 \SpecialChar ~
13429 \SpecialChar ~
13430 \SpecialChar ~
13431 \SpecialChar ~
13432 mov\SpecialChar ~
13433 \SpecialChar ~
13434 r3,a
13435 \newline
13436 \SpecialChar ~
13437 \SpecialChar ~
13438 \SpecialChar ~
13439 \SpecialChar ~
13440 mov\SpecialChar ~
13441 \SpecialChar ~
13442 a,_head
13443 \newline
13444 \SpecialChar ~
13445 \SpecialChar ~
13446 \SpecialChar ~
13447 \SpecialChar ~
13448 cjne a,ar3,00106$
13449 \newline
13450 \SpecialChar ~
13451 \SpecialChar ~
13452 \SpecialChar ~
13453 \SpecialChar ~
13454 ret
13455 \newline
13456 00106$:
13457 \newline
13458 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
13459 \begin_inset LatexCommand \index{Aligned array}
13460
13461 \end_inset
13462
13463
13464 \newline
13465 \SpecialChar ~
13466 \SpecialChar ~
13467 \SpecialChar ~
13468 \SpecialChar ~
13469 mov\SpecialChar ~
13470 \SpecialChar ~
13471 r3,_head
13472 \newline
13473 \SpecialChar ~
13474 \SpecialChar ~
13475 \SpecialChar ~
13476 \SpecialChar ~
13477 inc\SpecialChar ~
13478 \SpecialChar ~
13479 _head
13480 \newline
13481 \SpecialChar ~
13482 \SpecialChar ~
13483 \SpecialChar ~
13484 \SpecialChar ~
13485 mov\SpecialChar ~
13486 \SpecialChar ~
13487 dpl,r3
13488 \newline
13489 \SpecialChar ~
13490 \SpecialChar ~
13491 \SpecialChar ~
13492 \SpecialChar ~
13493 mov\SpecialChar ~
13494 \SpecialChar ~
13495 dph,#(_buf >> 8)
13496 \newline
13497 \SpecialChar ~
13498 \SpecialChar ~
13499 \SpecialChar ~
13500 \SpecialChar ~
13501 mov\SpecialChar ~
13502 \SpecialChar ~
13503 a,r2
13504 \newline
13505 \SpecialChar ~
13506 \SpecialChar ~
13507 \SpecialChar ~
13508 \SpecialChar ~
13509 movx @dptr,a
13510 \newline
13511 00103$:
13512 \newline
13513 \SpecialChar ~
13514 \SpecialChar ~
13515 \SpecialChar ~
13516 \SpecialChar ~
13517 ret
13518 \newline
13519 \SpecialChar ~
13520 \SpecialChar ~
13521 \SpecialChar ~
13522 \SpecialChar ~
13523 _endasm
13524 \begin_inset LatexCommand \index{\_endasm}
13525
13526 \end_inset
13527
13528
13529 \begin_inset LatexCommand \index{\_\_endasm}
13530
13531 \end_inset
13532
13533 ;
13534 \newline
13535 }
13536 \layout Standard
13537
13538 The new file buffer.c should compile with only one warning about the unreferenced
13539  function argument 'c'.
13540  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
13541  (1) and finally have:
13542 \layout Verse
13543
13544
13545 \family typewriter
13546 \size footnotesize
13547 unsigned char __far __at(0x7f00) buf[0x100];
13548 \newline
13549 unsigned char head, tail;
13550 \newline
13551 #define USE_ASSEMBLY (1)
13552 \newline
13553
13554 \newline
13555 #if !USE_ASSEMBLY
13556 \newline
13557
13558 \newline
13559 void to_buffer( unsigned char c )
13560 \newline
13561 {
13562 \newline
13563 \SpecialChar ~
13564 \SpecialChar ~
13565 \SpecialChar ~
13566 \SpecialChar ~
13567 if( head != (unsigned char)(tail-1) )
13568 \newline
13569 \SpecialChar ~
13570 \SpecialChar ~
13571 \SpecialChar ~
13572 \SpecialChar ~
13573 \SpecialChar ~
13574 \SpecialChar ~
13575 \SpecialChar ~
13576 \SpecialChar ~
13577 buf[ head++ ] = c;
13578 \newline
13579 }
13580 \newline
13581
13582 \newline
13583 #else
13584 \newline
13585
13586 \newline
13587 void to_buffer( unsigned char c )
13588 \newline
13589 {
13590 \newline
13591 \SpecialChar ~
13592 \SpecialChar ~
13593 \SpecialChar ~
13594 \SpecialChar ~
13595 c; // to avoid warning: unreferenced function argument
13596 \newline
13597 \SpecialChar ~
13598 \SpecialChar ~
13599 \SpecialChar ~
13600 \SpecialChar ~
13601 _asm
13602 \begin_inset LatexCommand \index{\_asm}
13603
13604 \end_inset
13605
13606
13607 \begin_inset LatexCommand \index{\_\_asm}
13608
13609 \end_inset
13610
13611
13612 \newline
13613 \SpecialChar ~
13614 \SpecialChar ~
13615 \SpecialChar ~
13616 \SpecialChar ~
13617 \SpecialChar ~
13618 \SpecialChar ~
13619 \SpecialChar ~
13620 \SpecialChar ~
13621 ; save used registers here.
13622
13623 \newline
13624 \SpecialChar ~
13625 \SpecialChar ~
13626 \SpecialChar ~
13627 \SpecialChar ~
13628 \SpecialChar ~
13629 \SpecialChar ~
13630 \SpecialChar ~
13631 \SpecialChar ~
13632 ; If we were still using r2,r3 we would have to push them here.
13633
13634 \newline
13635 ; if( head != (unsigned char)(tail-1) )
13636 \newline
13637 \SpecialChar ~
13638 \SpecialChar ~
13639 \SpecialChar ~
13640 \SpecialChar ~
13641 \SpecialChar ~
13642 \SpecialChar ~
13643 \SpecialChar ~
13644 \SpecialChar ~
13645 mov\SpecialChar ~
13646  a,_tail
13647 \newline
13648 \SpecialChar ~
13649 \SpecialChar ~
13650 \SpecialChar ~
13651 \SpecialChar ~
13652 \SpecialChar ~
13653 \SpecialChar ~
13654 \SpecialChar ~
13655 \SpecialChar ~
13656 dec\SpecialChar ~
13657  a
13658 \newline
13659 \SpecialChar ~
13660 \SpecialChar ~
13661 \SpecialChar ~
13662 \SpecialChar ~
13663 \SpecialChar ~
13664 \SpecialChar ~
13665 \SpecialChar ~
13666 \SpecialChar ~
13667 xrl\SpecialChar ~
13668  a,_head
13669 \newline
13670 \SpecialChar ~
13671 \SpecialChar ~
13672 \SpecialChar ~
13673 \SpecialChar ~
13674 \SpecialChar ~
13675 \SpecialChar ~
13676 \SpecialChar ~
13677 \SpecialChar ~
13678 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
13679 \newline
13680 \SpecialChar ~
13681 \SpecialChar ~
13682 \SpecialChar ~
13683 \SpecialChar ~
13684 \SpecialChar ~
13685 \SpecialChar ~
13686 \SpecialChar ~
13687 \SpecialChar ~
13688 jz\SpecialChar ~
13689 \SpecialChar ~
13690  t_b_end$
13691 \newline
13692 \SpecialChar ~
13693 \SpecialChar ~
13694 \SpecialChar ~
13695 \SpecialChar ~
13696 \SpecialChar ~
13697 \SpecialChar ~
13698 \SpecialChar ~
13699 \SpecialChar ~
13700 ;
13701 \newline
13702 ; buf[ head++ ] = c;
13703 \newline
13704 \SpecialChar ~
13705 \SpecialChar ~
13706 \SpecialChar ~
13707 \SpecialChar ~
13708 \SpecialChar ~
13709 \SpecialChar ~
13710 \SpecialChar ~
13711 \SpecialChar ~
13712 mov\SpecialChar ~
13713  a,dpl \SpecialChar ~
13714 \SpecialChar ~
13715 \SpecialChar ~
13716 \SpecialChar ~
13717 \SpecialChar ~
13718 \SpecialChar ~
13719 \SpecialChar ~
13720 ; dpl holds lower byte of function argument
13721 \newline
13722 \SpecialChar ~
13723 \SpecialChar ~
13724 \SpecialChar ~
13725 \SpecialChar ~
13726 \SpecialChar ~
13727 \SpecialChar ~
13728 \SpecialChar ~
13729 \SpecialChar ~
13730 mov\SpecialChar ~
13731  dpl,_head \SpecialChar ~
13732 \SpecialChar ~
13733 \SpecialChar ~
13734 ; buf is 0x100 byte aligned so head can be used directly
13735 \newline
13736 \SpecialChar ~
13737 \SpecialChar ~
13738 \SpecialChar ~
13739 \SpecialChar ~
13740 \SpecialChar ~
13741 \SpecialChar ~
13742 \SpecialChar ~
13743 \SpecialChar ~
13744 mov\SpecialChar ~
13745  dph,#(_buf>>8)
13746 \newline
13747 \SpecialChar ~
13748 \SpecialChar ~
13749 \SpecialChar ~
13750 \SpecialChar ~
13751 \SpecialChar ~
13752 \SpecialChar ~
13753 \SpecialChar ~
13754 \SpecialChar ~
13755 movx @dptr,a
13756 \newline
13757 \SpecialChar ~
13758 \SpecialChar ~
13759 \SpecialChar ~
13760 \SpecialChar ~
13761 \SpecialChar ~
13762 \SpecialChar ~
13763 \SpecialChar ~
13764 \SpecialChar ~
13765 inc \SpecialChar ~
13766 _head
13767 \newline
13768 \SpecialChar ~
13769 \SpecialChar ~
13770 \SpecialChar ~
13771 \SpecialChar ~
13772 \SpecialChar ~
13773 \SpecialChar ~
13774 \SpecialChar ~
13775 \SpecialChar ~
13776 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
13777 \newline
13778 t_b_end$:
13779 \newline
13780 \SpecialChar ~
13781 \SpecialChar ~
13782 \SpecialChar ~
13783 \SpecialChar ~
13784 \SpecialChar ~
13785 \SpecialChar ~
13786 \SpecialChar ~
13787 \SpecialChar ~
13788 ; restore used registers here
13789 \newline
13790 \SpecialChar ~
13791 \SpecialChar ~
13792 \SpecialChar ~
13793 \SpecialChar ~
13794 _endasm
13795 \begin_inset LatexCommand \index{\_endasm}
13796
13797 \end_inset
13798
13799
13800 \begin_inset LatexCommand \index{\_\_endasm}
13801
13802 \end_inset
13803
13804 ;
13805 \newline
13806 }
13807 \newline
13808 #endif
13809 \layout Standard
13810
13811 The inline assembler code can contain any valid code understood by the assembler
13812 , this includes any assembler directives and comment lines.
13813  The assembler does not like some characters like ':' or ''' in comments.
13814  You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
13815 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
13816
13817 \end_inset
13818
13819
13820 \begin_inset LatexCommand \index{Assembler documentation}
13821
13822 \end_inset
13823
13824  or online at
13825 \begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/as/doc/asxhtm.html}
13826
13827 \end_inset
13828
13829 \SpecialChar ~
13830 .
13831 \layout Standard
13832
13833 The compiler does not do any validation of the code within the
13834 \family typewriter
13835 _asm
13836 \begin_inset LatexCommand \index{\_asm}
13837
13838 \end_inset
13839
13840
13841 \begin_inset LatexCommand \index{\_\_asm}
13842
13843 \end_inset
13844
13845  ...
13846  _endasm
13847 \size footnotesize
13848
13849 \begin_inset LatexCommand \index{\_endasm}
13850
13851 \end_inset
13852
13853
13854 \begin_inset LatexCommand \index{\_\_endasm}
13855
13856 \end_inset
13857
13858
13859 \size default
13860 ;
13861 \family default
13862  keyword pair.
13863  Specifically it will not know which registers are used and thus register
13864  pushing/popping
13865 \begin_inset LatexCommand \index{push/pop}
13866
13867 \end_inset
13868
13869  has to be done manually.
13870
13871 \layout Standard
13872
13873 It is recommended that each assembly instruction (including labels) be placed
13874  in a separate line (as the example shows).
13875  When the -
13876 \begin_inset ERT
13877 status Collapsed
13878
13879 \layout Standard
13880
13881 \backslash
13882 /
13883 \end_inset
13884
13885 -
13886 \emph on
13887 peep-asm
13888 \begin_inset LatexCommand \index{-\/-peep-asm}
13889
13890 \end_inset
13891
13892
13893 \emph default
13894  command line option is used, the inline assembler code will be passed through
13895  the peephole optimizer
13896 \begin_inset LatexCommand \index{Peephole optimizer}
13897
13898 \end_inset
13899
13900 .
13901  There are only a few (if any) cases where this option makes sense, it might
13902  cause some unexpected changes in the inline assembler code.
13903  Please go through the peephole optimizer rules defined in file
13904 \emph on
13905 SDCCpeeph.def
13906 \emph default
13907  before using this option.
13908 \layout Subsection
13909
13910 Naked Functions
13911 \begin_inset LatexCommand \label{sub:Naked-Functions}
13912
13913 \end_inset
13914
13915
13916 \begin_inset LatexCommand \index{Naked functions}
13917
13918 \end_inset
13919
13920
13921 \layout Standard
13922
13923 A special keyword may be associated with a function declaring it as
13924 \emph on
13925 _naked
13926 \begin_inset LatexCommand \index{\_naked}
13927
13928 \end_inset
13929
13930
13931 \begin_inset LatexCommand \index{\_\_naked}
13932
13933 \end_inset
13934
13935 .
13936
13937 \emph default
13938 The
13939 \emph on
13940 _naked
13941 \emph default
13942  function modifier attribute prevents the compiler from generating prologue
13943 \begin_inset LatexCommand \index{function prologue}
13944
13945 \end_inset
13946
13947  and epilogue
13948 \begin_inset LatexCommand \index{function epilogue}
13949
13950 \end_inset
13951
13952  code for that function.
13953  This means that the user is entirely responsible for such things as saving
13954  any registers that may need to be preserved, selecting the proper register
13955  bank, generating the
13956 \emph on
13957 return
13958 \emph default
13959  instruction at the end, etc.
13960  Practically, this means that the contents of the function must be written
13961  in inline assembler.
13962  This is particularly useful for interrupt functions, which can have a large
13963  (and often unnecessary) prologue/epilogue.
13964  For example, compare the code generated by these two functions:
13965 \layout Verse
13966
13967
13968 \family typewriter
13969 volatile
13970 \begin_inset LatexCommand \index{volatile}
13971
13972 \end_inset
13973
13974  data unsigned char counter;
13975 \newline
13976
13977 \newline
13978 void simpleInterrupt(void) __interrupt
13979 \begin_inset LatexCommand \index{interrupt}
13980
13981 \end_inset
13982
13983
13984 \begin_inset LatexCommand \index{\_\_interrupt}
13985
13986 \end_inset
13987
13988  (1)
13989 \newline
13990 {
13991 \newline
13992 \SpecialChar ~
13993 \SpecialChar ~
13994 \SpecialChar ~
13995 \SpecialChar ~
13996 counter++;
13997 \newline
13998 }
13999 \newline
14000
14001 \newline
14002 void nakedInterrupt(void) __interrupt (2) __naked
14003 \newline
14004 {
14005 \newline
14006 \SpecialChar ~
14007 \SpecialChar ~
14008 \SpecialChar ~
14009 \SpecialChar ~
14010 _asm
14011 \begin_inset LatexCommand \index{\_asm}
14012
14013 \end_inset
14014
14015
14016 \begin_inset LatexCommand \index{\_\_asm}
14017
14018 \end_inset
14019
14020
14021 \newline
14022 \SpecialChar ~
14023 \SpecialChar ~
14024 \SpecialChar ~
14025 \SpecialChar ~
14026 \SpecialChar ~
14027 \SpecialChar ~
14028 inc\SpecialChar ~
14029 \SpecialChar ~
14030 \SpecialChar ~
14031 \SpecialChar ~
14032 \SpecialChar ~
14033 _counter ; does not change flags, no need to save psw
14034 \newline
14035 \SpecialChar ~
14036 \SpecialChar ~
14037 \SpecialChar ~
14038 \SpecialChar ~
14039 \SpecialChar ~
14040 \SpecialChar ~
14041 reti\SpecialChar ~
14042 \SpecialChar ~
14043 \SpecialChar ~
14044 \SpecialChar ~
14045 ; MUST explicitly include ret or reti in _naked function.
14046 \newline
14047 \SpecialChar ~
14048 \SpecialChar ~
14049 \SpecialChar ~
14050 \SpecialChar ~
14051 _endasm
14052 \begin_inset LatexCommand \index{\_endasm}
14053
14054 \end_inset
14055
14056
14057 \begin_inset LatexCommand \index{\_\_endasm}
14058
14059 \end_inset
14060
14061 ;
14062 \newline
14063 }
14064 \layout Standard
14065
14066 For an 8051 target, the generated simpleInterrupt looks like:
14067 \layout Verse
14068
14069
14070 \family typewriter
14071 Note, this is an
14072 \emph on
14073 outdated
14074 \emph default
14075  example, recent versions of SDCC generate
14076 \newline
14077 the
14078 \emph on
14079 same
14080 \emph default
14081  code for simpleInterrupt() and nakedInterrupt()!
14082 \newline
14083
14084 \newline
14085 _simpleInterrupt:
14086 \newline
14087 \SpecialChar ~
14088 \SpecialChar ~
14089 \SpecialChar ~
14090 \SpecialChar ~
14091 push\SpecialChar ~
14092 \SpecialChar ~
14093 \SpecialChar ~
14094 \SpecialChar ~
14095 acc
14096 \newline
14097 \SpecialChar ~
14098 \SpecialChar ~
14099 \SpecialChar ~
14100 \SpecialChar ~
14101 push\SpecialChar ~
14102 \SpecialChar ~
14103 \SpecialChar ~
14104 \SpecialChar ~
14105 b
14106 \newline
14107 \SpecialChar ~
14108 \SpecialChar ~
14109 \SpecialChar ~
14110 \SpecialChar ~
14111 push\SpecialChar ~
14112 \SpecialChar ~
14113 \SpecialChar ~
14114 \SpecialChar ~
14115 dpl
14116 \newline
14117 \SpecialChar ~
14118 \SpecialChar ~
14119 \SpecialChar ~
14120 \SpecialChar ~
14121 push\SpecialChar ~
14122 \SpecialChar ~
14123 \SpecialChar ~
14124 \SpecialChar ~
14125 dph
14126 \newline
14127 \SpecialChar ~
14128 \SpecialChar ~
14129 \SpecialChar ~
14130 \SpecialChar ~
14131 push\SpecialChar ~
14132 \SpecialChar ~
14133 \SpecialChar ~
14134 \SpecialChar ~
14135 psw
14136 \newline
14137 \SpecialChar ~
14138 \SpecialChar ~
14139 \SpecialChar ~
14140 \SpecialChar ~
14141 mov\SpecialChar ~
14142 \SpecialChar ~
14143 \SpecialChar ~
14144 \SpecialChar ~
14145 \SpecialChar ~
14146 psw,#0x00
14147 \newline
14148 \SpecialChar ~
14149 \SpecialChar ~
14150 \SpecialChar ~
14151 \SpecialChar ~
14152 inc\SpecialChar ~
14153 \SpecialChar ~
14154 \SpecialChar ~
14155 \SpecialChar ~
14156 \SpecialChar ~
14157 _counter
14158 \newline
14159 \SpecialChar ~
14160 \SpecialChar ~
14161 \SpecialChar ~
14162 \SpecialChar ~
14163 pop\SpecialChar ~
14164 \SpecialChar ~
14165 \SpecialChar ~
14166 \SpecialChar ~
14167 \SpecialChar ~
14168 psw
14169 \newline
14170 \SpecialChar ~
14171 \SpecialChar ~
14172 \SpecialChar ~
14173 \SpecialChar ~
14174 pop\SpecialChar ~
14175 \SpecialChar ~
14176 \SpecialChar ~
14177 \SpecialChar ~
14178 \SpecialChar ~
14179 dph
14180 \newline
14181 \SpecialChar ~
14182 \SpecialChar ~
14183 \SpecialChar ~
14184 \SpecialChar ~
14185 pop\SpecialChar ~
14186 \SpecialChar ~
14187 \SpecialChar ~
14188 \SpecialChar ~
14189 \SpecialChar ~
14190 dpl
14191 \newline
14192 \SpecialChar ~
14193 \SpecialChar ~
14194 \SpecialChar ~
14195 \SpecialChar ~
14196 pop\SpecialChar ~
14197 \SpecialChar ~
14198 \SpecialChar ~
14199 \SpecialChar ~
14200 \SpecialChar ~
14201 b
14202 \newline
14203 \SpecialChar ~
14204 \SpecialChar ~
14205 \SpecialChar ~
14206 \SpecialChar ~
14207 pop\SpecialChar ~
14208 \SpecialChar ~
14209 \SpecialChar ~
14210 \SpecialChar ~
14211 \SpecialChar ~
14212 acc
14213 \newline
14214 \SpecialChar ~
14215 \SpecialChar ~
14216 \SpecialChar ~
14217 \SpecialChar ~
14218 reti
14219 \layout Standard
14220
14221 whereas nakedInterrupt looks like:
14222 \layout Verse
14223
14224
14225 \family typewriter
14226 _nakedInterrupt:
14227 \newline
14228 \SpecialChar ~
14229 \SpecialChar ~
14230 \SpecialChar ~
14231 \SpecialChar ~
14232 inc\SpecialChar ~
14233 \SpecialChar ~
14234 \SpecialChar ~
14235 \SpecialChar ~
14236 _counter ; does not change flags, no need to save psw
14237 \newline
14238 \SpecialChar ~
14239 \SpecialChar ~
14240 \SpecialChar ~
14241 \SpecialChar ~
14242 reti\SpecialChar ~
14243 \SpecialChar ~
14244 \SpecialChar ~
14245 \SpecialChar ~
14246 \SpecialChar ~
14247 \SpecialChar ~
14248 \SpecialChar ~
14249 \SpecialChar ~
14250 \SpecialChar ~
14251 \SpecialChar ~
14252 \SpecialChar ~
14253 \SpecialChar ~
14254 ; MUST explicitly include ret or reti in _naked function
14255 \layout Standard
14256
14257 The related directive #pragma exclude
14258 \begin_inset LatexCommand \index{\#pragma exclude}
14259
14260 \end_inset
14261
14262  allows a more fine grained control over pushing & popping
14263 \begin_inset LatexCommand \index{push/pop}
14264
14265 \end_inset
14266
14267  the registers.
14268 \layout Standard
14269
14270 While there is nothing preventing you from writing C code inside a
14271 \family typewriter
14272 _naked
14273 \family default
14274  function, there are many ways to shoot yourself in the foot doing this,
14275  and it is recommended that you stick to inline assembler.
14276 \layout Subsection
14277
14278 Use of Labels within Inline Assembler
14279 \layout Standard
14280
14281 SDCC allows the use of in-line assembler with a few restrictions regarding
14282  labels.
14283  In older versions of the compiler all labels defined within inline assembler
14284  code
14285 \emph on
14286 had to be
14287 \emph default
14288  of the form
14289 \emph on
14290 nnnnn$
14291 \emph default
14292  where nnnn is a number less than 100 (which implies a limit of utmost 100
14293  inline assembler labels
14294 \emph on
14295 per function
14296 \emph default
14297 \noun on
14298 )
14299 \noun default
14300 .
14301
14302 \layout Verse
14303
14304
14305 \family typewriter
14306 _asm
14307 \begin_inset LatexCommand \index{\_asm}
14308
14309 \end_inset
14310
14311
14312 \begin_inset LatexCommand \index{\_\_asm}
14313
14314 \end_inset
14315
14316
14317 \newline
14318 \SpecialChar ~
14319 \SpecialChar ~
14320 \SpecialChar ~
14321 \SpecialChar ~
14322 mov\SpecialChar ~
14323 \SpecialChar ~
14324 \SpecialChar ~
14325 \SpecialChar ~
14326 \SpecialChar ~
14327 b,#10
14328 \newline
14329 00001$:
14330 \newline
14331 \SpecialChar ~
14332 \SpecialChar ~
14333 \SpecialChar ~
14334 \SpecialChar ~
14335 djnz\SpecialChar ~
14336 \SpecialChar ~
14337 \SpecialChar ~
14338 \SpecialChar ~
14339 b,00001$
14340 \newline
14341 _endasm
14342 \begin_inset LatexCommand \index{\_endasm}
14343
14344 \end_inset
14345
14346
14347 \begin_inset LatexCommand \index{\_\_endasm}
14348
14349 \end_inset
14350
14351  ;
14352 \layout Standard
14353
14354 Inline assembler code cannot reference any C-Labels, however it can reference
14355  labels
14356 \begin_inset LatexCommand \index{Labels}
14357
14358 \end_inset
14359
14360  defined by the inline assembler, e.g.:
14361 \layout Verse
14362
14363
14364 \family typewriter
14365 foo() {
14366 \newline
14367 \SpecialChar ~
14368 \SpecialChar ~
14369 \SpecialChar ~
14370 \SpecialChar ~
14371 /* some c code */
14372 \newline
14373 \SpecialChar ~
14374 \SpecialChar ~
14375 \SpecialChar ~
14376 \SpecialChar ~
14377 _asm
14378 \newline
14379 \SpecialChar ~
14380 \SpecialChar ~
14381 \SpecialChar ~
14382 \SpecialChar ~
14383 \SpecialChar ~
14384 \SpecialChar ~
14385 ; some assembler code
14386 \newline
14387 \SpecialChar ~
14388 \SpecialChar ~
14389 \SpecialChar ~
14390 \SpecialChar ~
14391 \SpecialChar ~
14392 \SpecialChar ~
14393 ljmp $0003
14394 \newline
14395 \SpecialChar ~
14396 \SpecialChar ~
14397 \SpecialChar ~
14398 \SpecialChar ~
14399 _endasm;
14400 \newline
14401 \SpecialChar ~
14402 \SpecialChar ~
14403 \SpecialChar ~
14404 \SpecialChar ~
14405 /* some more c code */
14406 \newline
14407 clabel:\SpecialChar ~
14408 \SpecialChar ~
14409 /* inline assembler cannot reference this label */
14410 \newline
14411 \SpecialChar ~
14412 \SpecialChar ~
14413 \SpecialChar ~
14414 \SpecialChar ~
14415 _asm
14416 \newline
14417 \SpecialChar ~
14418 \SpecialChar ~
14419 \SpecialChar ~
14420 \SpecialChar ~
14421 $0003: ;label (can be referenced by inline assembler only)
14422 \newline
14423 \SpecialChar ~
14424 \SpecialChar ~
14425 \SpecialChar ~
14426 \SpecialChar ~
14427 _endasm
14428 \begin_inset LatexCommand \index{\_endasm}
14429
14430 \end_inset
14431
14432
14433 \begin_inset LatexCommand \index{\_\_endasm}
14434
14435 \end_inset
14436
14437  ;
14438 \newline
14439 \SpecialChar ~
14440 \SpecialChar ~
14441 \SpecialChar ~
14442 \SpecialChar ~
14443 /* some more c code */
14444 \newline
14445 }
14446 \layout Standard
14447
14448 In other words inline assembly code can access labels defined in inline
14449  assembly within the scope of the function.
14450  The same goes the other way, i.e.
14451  labels defines in inline assembly can not be accessed by C statements.
14452 \layout Section
14453
14454 Interfacing with Assembler Code
14455 \begin_inset LatexCommand \index{Assembler routines}
14456
14457 \end_inset
14458
14459
14460 \layout Subsection
14461
14462 Global Registers used for Parameter Passing
14463 \begin_inset LatexCommand \index{Parameter passing}
14464
14465 \end_inset
14466
14467
14468 \layout Standard
14469
14470 The compiler always uses the global registers
14471 \emph on
14472 DPL, DPH
14473 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
14474
14475 \end_inset
14476
14477
14478 \begin_inset LatexCommand \index{DPTR}
14479
14480 \end_inset
14481
14482 , B
14483 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
14484
14485 \end_inset
14486
14487
14488 \emph default
14489 and
14490 \emph on
14491  ACC
14492 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
14493
14494 \end_inset
14495
14496
14497 \emph default
14498  to pass the first parameter to a routine.
14499  The second parameter onwards is either allocated on the stack (for reentrant
14500  routines or if -
14501 \begin_inset ERT
14502 status Collapsed
14503
14504 \layout Standard
14505
14506 \backslash
14507 /
14508 \end_inset
14509
14510 -stack-auto is used) or in data / xdata memory (depending on the memory
14511  model).
14512
14513 \layout Subsection
14514
14515 Assembler Routine (non-reentrant)
14516 \layout Standard
14517
14518 In the following example
14519 \begin_inset LatexCommand \index{reentrant}
14520
14521 \end_inset
14522
14523
14524 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
14525
14526 \end_inset
14527
14528  the function c_func calls an assembler routine asm_func, which takes two
14529  parameters
14530 \begin_inset LatexCommand \index{function parameter}
14531
14532 \end_inset
14533
14534 .
14535 \layout Verse
14536
14537
14538 \family typewriter
14539 extern int asm_func(unsigned char, unsigned char);
14540 \newline
14541
14542 \newline
14543 int c_func (unsigned char i, unsigned char j)
14544 \newline
14545 {
14546 \newline
14547 \SpecialChar ~
14548 \SpecialChar ~
14549 \SpecialChar ~
14550 \SpecialChar ~
14551 return asm_func(i,j);
14552 \newline
14553 }
14554 \newline
14555
14556 \newline
14557 int main()
14558 \newline
14559 {
14560 \newline
14561 \SpecialChar ~
14562 \SpecialChar ~
14563 \SpecialChar ~
14564 \SpecialChar ~
14565 return c_func(10,9);
14566 \newline
14567 }
14568 \layout Standard
14569
14570 The corresponding assembler function is:
14571 \layout Verse
14572
14573
14574 \family typewriter
14575 .globl _asm_func_PARM_2
14576 \newline
14577 \SpecialChar ~
14578 \SpecialChar ~
14579 \SpecialChar ~
14580 \SpecialChar ~
14581 \SpecialChar ~
14582 \SpecialChar ~
14583 \SpecialChar ~
14584 \SpecialChar ~
14585 .globl _asm_func
14586 \newline
14587 \SpecialChar ~
14588 \SpecialChar ~
14589 \SpecialChar ~
14590 \SpecialChar ~
14591 \SpecialChar ~
14592 \SpecialChar ~
14593 \SpecialChar ~
14594 \SpecialChar ~
14595 .area OSEG
14596 \newline
14597 _asm_func_PARM_2:
14598 \newline
14599 \SpecialChar ~
14600 \SpecialChar ~
14601 \SpecialChar ~
14602 \SpecialChar ~
14603 \SpecialChar ~
14604 \SpecialChar ~
14605 \SpecialChar ~
14606 \SpecialChar ~
14607 .ds    1
14608 \newline
14609 \SpecialChar ~
14610 \SpecialChar ~
14611 \SpecialChar ~
14612 \SpecialChar ~
14613 \SpecialChar ~
14614 \SpecialChar ~
14615 \SpecialChar ~
14616 \SpecialChar ~
14617 .area CSEG
14618 \newline
14619 _asm_func:
14620 \newline
14621 \SpecialChar ~
14622 \SpecialChar ~
14623 \SpecialChar ~
14624 \SpecialChar ~
14625 \SpecialChar ~
14626 \SpecialChar ~
14627 \SpecialChar ~
14628 \SpecialChar ~
14629 mov\SpecialChar ~
14630 \SpecialChar ~
14631 \SpecialChar ~
14632 \SpecialChar ~
14633 a,dpl
14634 \newline
14635 \SpecialChar ~
14636 \SpecialChar ~
14637 \SpecialChar ~
14638 \SpecialChar ~
14639 \SpecialChar ~
14640 \SpecialChar ~
14641 \SpecialChar ~
14642 \SpecialChar ~
14643 add\SpecialChar ~
14644 \SpecialChar ~
14645 \SpecialChar ~
14646 \SpecialChar ~
14647 a,_asm_func_PARM_2
14648 \newline
14649 \SpecialChar ~
14650 \SpecialChar ~
14651 \SpecialChar ~
14652 \SpecialChar ~
14653 \SpecialChar ~
14654 \SpecialChar ~
14655 \SpecialChar ~
14656 \SpecialChar ~
14657 mov\SpecialChar ~
14658 \SpecialChar ~
14659 \SpecialChar ~
14660 \SpecialChar ~
14661 dpl,a
14662 \newline
14663 \SpecialChar ~
14664 \SpecialChar ~
14665 \SpecialChar ~
14666 \SpecialChar ~
14667 \SpecialChar ~
14668 \SpecialChar ~
14669 \SpecialChar ~
14670 \SpecialChar ~
14671 mov\SpecialChar ~
14672 \SpecialChar ~
14673 \SpecialChar ~
14674 \SpecialChar ~
14675 dph
14676 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
14677
14678 \end_inset
14679
14680 ,#0x00
14681 \newline
14682 \SpecialChar ~
14683 \SpecialChar ~
14684 \SpecialChar ~
14685 \SpecialChar ~
14686 \SpecialChar ~
14687 \SpecialChar ~
14688 \SpecialChar ~
14689 \SpecialChar ~
14690 ret
14691 \layout Standard
14692
14693 Note here that the return values
14694 \begin_inset LatexCommand \index{return value}
14695
14696 \end_inset
14697
14698  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
14699  two byte values.
14700  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
14701 b' & 'acc' for four byte values.
14702 \layout Standard
14703
14704 The parameter naming convention is _<function_name>_PARM_<n>, where n is
14705  the parameter number starting from 1, and counting from the left.
14706  The first parameter is passed in
14707 \begin_inset Quotes eld
14708 \end_inset
14709
14710 dpl
14711 \begin_inset Quotes erd
14712 \end_inset
14713
14714  for a one byte parameter,
14715 \begin_inset Quotes eld
14716 \end_inset
14717
14718 dptr
14719 \begin_inset Quotes erd
14720 \end_inset
14721
14722  for two bytes,
14723 \begin_inset Quotes eld
14724 \end_inset
14725
14726 b,dptr
14727 \begin_inset Quotes erd
14728 \end_inset
14729
14730  for three bytes and
14731 \begin_inset Quotes eld
14732 \end_inset
14733
14734 acc,b,dptr
14735 \begin_inset Quotes erd
14736 \end_inset
14737
14738  for a four bytes parameter.
14739  The variable name for the second parameter will be _<function_name>_PARM_2.
14740 \newline
14741
14742 \newline
14743 Assemble the assembler routine with the following command:
14744 \newline
14745
14746 \newline
14747
14748 \family sans
14749 \series bold
14750 asx8051 -losg asmfunc.asm
14751 \newline
14752
14753 \newline
14754
14755 \family default
14756 \series default
14757 Then compile and link the assembler routine to the C source file with the
14758  following command:
14759 \newline
14760
14761 \newline
14762
14763 \family sans
14764 \series bold
14765 sdcc cfunc.c asmfunc.rel
14766 \layout Subsection
14767
14768 Assembler Routine (reentrant)
14769 \layout Standard
14770
14771 In this case
14772 \begin_inset LatexCommand \index{reentrant}
14773
14774 \end_inset
14775
14776
14777 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
14778
14779 \end_inset
14780
14781  the second parameter
14782 \begin_inset LatexCommand \index{function parameter}
14783
14784 \end_inset
14785
14786  onwards will be passed on the stack, the parameters are pushed from right
14787  to left i.e.
14788  after the call the leftmost parameter will be on the top of the stack.
14789  Here is an example:
14790 \layout Verse
14791
14792
14793 \family typewriter
14794 extern int asm_func(unsigned char, unsigned char);
14795 \newline
14796
14797 \newline
14798 int c_func (unsigned char i, unsigned char j) reentrant
14799 \newline
14800 {
14801 \newline
14802 \SpecialChar ~
14803 \SpecialChar ~
14804 \SpecialChar ~
14805 \SpecialChar ~
14806 return asm_func(i,j);
14807 \newline
14808 }
14809 \newline
14810
14811 \newline
14812 int main()
14813 \newline
14814 {
14815 \newline
14816 \SpecialChar ~
14817 \SpecialChar ~
14818 \SpecialChar ~
14819 \SpecialChar ~
14820 return c_func(10,9);
14821 \newline
14822 }
14823 \layout Standard
14824
14825 The corresponding assembler routine is:
14826 \layout Verse
14827
14828
14829 \family typewriter
14830 .globl _asm_func
14831 \newline
14832 _asm_func:
14833 \newline
14834 \SpecialChar ~
14835 \SpecialChar ~
14836 \SpecialChar ~
14837 \SpecialChar ~
14838 push  _bp
14839 \newline
14840 \SpecialChar ~
14841 \SpecialChar ~
14842 \SpecialChar ~
14843 \SpecialChar ~
14844 mov _bp,sp
14845 \newline
14846 \SpecialChar ~
14847 \SpecialChar ~
14848 \SpecialChar ~
14849 \SpecialChar ~
14850 mov r2,dpl
14851 \newline
14852 \SpecialChar ~
14853 \SpecialChar ~
14854 \SpecialChar ~
14855 \SpecialChar ~
14856 mov a,_bp
14857 \newline
14858 \SpecialChar ~
14859 \SpecialChar ~
14860 \SpecialChar ~
14861 \SpecialChar ~
14862 add a,#0xfd
14863 \newline
14864 \SpecialChar ~
14865 \SpecialChar ~
14866 \SpecialChar ~
14867 \SpecialChar ~
14868 mov r0,a
14869 \newline
14870 \SpecialChar ~
14871 \SpecialChar ~
14872 \SpecialChar ~
14873 \SpecialChar ~
14874 add  a,#0xfc ;?
14875 \newline
14876 \SpecialChar ~
14877 \SpecialChar ~
14878 \SpecialChar ~
14879 \SpecialChar ~
14880 mov  r1,a
14881 \newline
14882 \SpecialChar ~
14883 \SpecialChar ~
14884 \SpecialChar ~
14885 \SpecialChar ~
14886 mov  a,@r0
14887 \newline
14888 \SpecialChar ~
14889 \SpecialChar ~
14890 \SpecialChar ~
14891 \SpecialChar ~
14892 add  a,r2 ;?
14893 \newline
14894 \SpecialChar ~
14895 \SpecialChar ~
14896 \SpecialChar ~
14897 \SpecialChar ~
14898 mov  dpl,a
14899 \newline
14900 \SpecialChar ~
14901 \SpecialChar ~
14902 \SpecialChar ~
14903 \SpecialChar ~
14904 mov  dph,#0x00
14905 \newline
14906 \SpecialChar ~
14907 \SpecialChar ~
14908 \SpecialChar ~
14909 \SpecialChar ~
14910 mov  sp,_bp
14911 \newline
14912 \SpecialChar ~
14913 \SpecialChar ~
14914 \SpecialChar ~
14915 \SpecialChar ~
14916 pop  _bp
14917 \newline
14918 \SpecialChar ~
14919 \SpecialChar ~
14920 \SpecialChar ~
14921 \SpecialChar ~
14922 ret
14923 \layout Standard
14924 \added_space_bottom bigskip
14925 The compiling and linking procedure remains the same, however note the extra
14926  entry & exit linkage required for the assembler code, _bp is the stack
14927  frame pointer and is used to compute the offset into the stack for parameters
14928  and local variables.
14929 \layout Section
14930
14931 int (16 bit)
14932 \begin_inset LatexCommand \index{int (16 bit)}
14933
14934 \end_inset
14935
14936  and long (32 bit)
14937 \begin_inset LatexCommand \index{long (32 bit)}
14938
14939 \end_inset
14940
14941  Support
14942 \layout Standard
14943
14944 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
14945  multiplication and modulus operations are implemented by support routines.
14946  These support routines are all developed in ANSI-C to facilitate porting
14947  to other MCUs, although some model specific assembler optimizations are
14948  used.
14949  The following files contain the described routines, all of them can be
14950  found in <installdir>/share/sdcc/lib.
14951 \newline
14952
14953 \layout Standard
14954 \align center
14955
14956 \begin_inset  Tabular
14957 <lyxtabular version="3" rows="11" columns="2">
14958 <features>
14959 <column alignment="left" valignment="top" leftline="true" width="0">
14960 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
14961 <row topline="true" bottomline="true">
14962 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14963 \begin_inset Text
14964
14965 \layout Standard
14966
14967
14968 \series bold
14969 Function
14970 \end_inset
14971 </cell>
14972 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14973 \begin_inset Text
14974
14975 \layout Standard
14976
14977
14978 \series bold
14979 Description
14980 \end_inset
14981 </cell>
14982 </row>
14983 <row topline="true">
14984 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14985 \begin_inset Text
14986
14987 \layout Standard
14988
14989 _mulint.c
14990 \end_inset
14991 </cell>
14992 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14993 \begin_inset Text
14994
14995 \layout Standard
14996
14997 16 bit multiplication
14998 \end_inset
14999 </cell>
15000 </row>
15001 <row topline="true">
15002 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15003 \begin_inset Text
15004
15005 \layout Standard
15006
15007 _divsint.c
15008 \end_inset
15009 </cell>
15010 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15011 \begin_inset Text
15012
15013 \layout Standard
15014
15015  signed 16 bit division (calls _divuint)
15016 \end_inset
15017 </cell>
15018 </row>
15019 <row topline="true">
15020 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15021 \begin_inset Text
15022
15023 \layout Standard
15024
15025 _divuint.c
15026 \end_inset
15027 </cell>
15028 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15029 \begin_inset Text
15030
15031 \layout Standard
15032
15033  unsigned 16 bit division
15034 \end_inset
15035 </cell>
15036 </row>
15037 <row topline="true">
15038 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15039 \begin_inset Text
15040
15041 \layout Standard
15042
15043 _modsint.c
15044 \end_inset
15045 </cell>
15046 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15047 \begin_inset Text
15048
15049 \layout Standard
15050
15051 signed 16 bit modulus (calls _moduint)
15052 \end_inset
15053 </cell>
15054 </row>
15055 <row topline="true">
15056 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15057 \begin_inset Text
15058
15059 \layout Standard
15060
15061 _moduint.c
15062 \end_inset
15063 </cell>
15064 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15065 \begin_inset Text
15066
15067 \layout Standard
15068
15069 unsigned 16 bit modulus
15070 \end_inset
15071 </cell>
15072 </row>
15073 <row topline="true">
15074 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15075 \begin_inset Text
15076
15077 \layout Standard
15078
15079 _mullong.c
15080 \end_inset
15081 </cell>
15082 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15083 \begin_inset Text
15084
15085 \layout Standard
15086
15087 32 bit multiplication
15088 \end_inset
15089 </cell>
15090 </row>
15091 <row topline="true">
15092 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15093 \begin_inset Text
15094
15095 \layout Standard
15096
15097 _divslong.c
15098 \end_inset
15099 </cell>
15100 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15101 \begin_inset Text
15102
15103 \layout Standard
15104
15105  signed 32 division (calls _divulong)
15106 \end_inset
15107 </cell>
15108 </row>
15109 <row topline="true">
15110 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15111 \begin_inset Text
15112
15113 \layout Standard
15114
15115 _divulong.c
15116 \end_inset
15117 </cell>
15118 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15119 \begin_inset Text
15120
15121 \layout Standard
15122
15123 unsigned 32 division
15124 \end_inset
15125 </cell>
15126 </row>
15127 <row topline="true">
15128 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15129 \begin_inset Text
15130
15131 \layout Standard
15132
15133 _modslong.c
15134 \end_inset
15135 </cell>
15136 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15137 \begin_inset Text
15138
15139 \layout Standard
15140
15141  signed 32 bit modulus (calls _modulong)
15142 \end_inset
15143 </cell>
15144 </row>
15145 <row topline="true" bottomline="true">
15146 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15147 \begin_inset Text
15148
15149 \layout Standard
15150
15151 _modulong.c
15152 \end_inset
15153 </cell>
15154 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15155 \begin_inset Text
15156
15157 \layout Standard
15158
15159 unsigned 32 bit modulus
15160 \end_inset
15161 </cell>
15162 </row>
15163 </lyxtabular>
15164
15165 \end_inset
15166
15167
15168 \newline
15169
15170 \layout Standard
15171
15172 Since they are compiled as
15173 \emph on
15174 non-reentrant
15175 \emph default
15176
15177 \begin_inset LatexCommand \index{reentrant}
15178
15179 \end_inset
15180
15181 , interrupt
15182 \begin_inset LatexCommand \index{interrupt}
15183
15184 \end_inset
15185
15186  service routines should not do any of the above operations.
15187  If this is unavoidable then the above routines will need to be compiled
15188  with the
15189 \emph on
15190 -
15191 \begin_inset ERT
15192 status Collapsed
15193
15194 \layout Standard
15195
15196 \backslash
15197 /
15198 \end_inset
15199
15200 -stack-auto
15201 \begin_inset LatexCommand \index{-\/-stack-auto}
15202
15203 \end_inset
15204
15205
15206 \emph default
15207  option, after which the source program will have to be compiled with
15208 \emph on
15209 -
15210 \begin_inset ERT
15211 status Collapsed
15212
15213 \layout Standard
15214
15215 \backslash
15216 /
15217 \end_inset
15218
15219 -int-long-reent
15220 \begin_inset LatexCommand \index{-\/-int-long-reent}
15221
15222 \end_inset
15223
15224
15225 \emph default
15226  option.
15227  Notice that you don't have to call these routines directly.
15228  The compiler will use them automatically every time an integer operation
15229  is required.
15230 \layout Section
15231
15232 Floating Point Support
15233 \begin_inset LatexCommand \index{Floating point support}
15234
15235 \end_inset
15236
15237
15238 \layout Standard
15239
15240 SDCC supports IEEE (single precision 4 bytes) floating point numbers.
15241  The floating point support routines are derived from gcc's floatlib.c and
15242  consist of the following routines:
15243 \newline
15244
15245 \layout Standard
15246 \align center
15247
15248 \size footnotesize
15249
15250 \begin_inset  Tabular
15251 <lyxtabular version="3" rows="17" columns="2">
15252 <features>
15253 <column alignment="left" valignment="top" leftline="true" width="0">
15254 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
15255 <row topline="true" bottomline="true">
15256 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15257 \begin_inset Text
15258
15259 \layout Standard
15260
15261
15262 \family roman
15263 \series medium
15264 \shape up
15265 \size normal
15266 \emph off
15267 \bar no
15268 \noun off
15269 \color none
15270 Function
15271 \end_inset
15272 </cell>
15273 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15274 \begin_inset Text
15275
15276 \layout Standard
15277
15278 Description
15279 \end_inset
15280 </cell>
15281 </row>
15282 <row topline="true">
15283 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15284 \begin_inset Text
15285
15286 \layout Standard
15287
15288
15289 \family roman
15290 \series medium
15291 \shape up
15292 \size normal
15293 \emph off
15294 \bar no
15295 \noun off
15296 \color none
15297 _fsadd.c
15298 \end_inset
15299 </cell>
15300 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15301 \begin_inset Text
15302
15303 \layout Standard
15304
15305
15306 \family roman
15307 \series medium
15308 \shape up
15309 \size normal
15310 \emph off
15311 \bar no
15312 \noun off
15313 \color none
15314 add floating point numbers
15315 \end_inset
15316 </cell>
15317 </row>
15318 <row topline="true">
15319 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15320 \begin_inset Text
15321
15322 \layout Standard
15323
15324
15325 \family roman
15326 \series medium
15327 \shape up
15328 \size normal
15329 \emph off
15330 \bar no
15331 \noun off
15332 \color none
15333 _fssub.c
15334 \end_inset
15335 </cell>
15336 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15337 \begin_inset Text
15338
15339 \layout Standard
15340
15341
15342 \family roman
15343 \series medium
15344 \shape up
15345 \size normal
15346 \emph off
15347 \bar no
15348 \noun off
15349 \color none
15350 subtract floating point numbers
15351 \end_inset
15352 </cell>
15353 </row>
15354 <row topline="true">
15355 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15356 \begin_inset Text
15357
15358 \layout Standard
15359
15360
15361 \family roman
15362 \series medium
15363 \shape up
15364 \size normal
15365 \emph off
15366 \bar no
15367 \noun off
15368 \color none
15369 _fsdiv.c
15370 \end_inset
15371 </cell>
15372 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15373 \begin_inset Text
15374
15375 \layout Standard
15376
15377
15378 \family roman
15379 \series medium
15380 \shape up
15381 \size normal
15382 \emph off
15383 \bar no
15384 \noun off
15385 \color none
15386 divide floating point numbers
15387 \end_inset
15388 </cell>
15389 </row>
15390 <row topline="true">
15391 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15392 \begin_inset Text
15393
15394 \layout Standard
15395
15396
15397 \family roman
15398 \series medium
15399 \shape up
15400 \size normal
15401 \emph off
15402 \bar no
15403 \noun off
15404 \color none
15405 _fsmul.c
15406 \end_inset
15407 </cell>
15408 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15409 \begin_inset Text
15410
15411 \layout Standard
15412
15413
15414 \family roman
15415 \series medium
15416 \shape up
15417 \size normal
15418 \emph off
15419 \bar no
15420 \noun off
15421 \color none
15422 multiply floating point numbers
15423 \end_inset
15424 </cell>
15425 </row>
15426 <row topline="true">
15427 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15428 \begin_inset Text
15429
15430 \layout Standard
15431
15432
15433 \family roman
15434 \series medium
15435 \shape up
15436 \size normal
15437 \emph off
15438 \bar no
15439 \noun off
15440 \color none
15441 _fs2uchar.c
15442 \end_inset
15443 </cell>
15444 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15445 \begin_inset Text
15446
15447 \layout Standard
15448
15449
15450 \family roman
15451 \series medium
15452 \shape up
15453 \size normal
15454 \emph off
15455 \bar no
15456 \noun off
15457 \color none
15458 convert floating point to unsigned char
15459 \end_inset
15460 </cell>
15461 </row>
15462 <row topline="true">
15463 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15464 \begin_inset Text
15465
15466 \layout Standard
15467
15468
15469 \family roman
15470 \series medium
15471 \shape up
15472 \size normal
15473 \emph off
15474 \bar no
15475 \noun off
15476 \color none
15477 _fs2char.c
15478 \end_inset
15479 </cell>
15480 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15481 \begin_inset Text
15482
15483 \layout Standard
15484
15485
15486 \family roman
15487 \series medium
15488 \shape up
15489 \size normal
15490 \emph off
15491 \bar no
15492 \noun off
15493 \color none
15494 convert floating point to signed char
15495 \end_inset
15496 </cell>
15497 </row>
15498 <row topline="true">
15499 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15500 \begin_inset Text
15501
15502 \layout Standard
15503
15504
15505 \family roman
15506 \series medium
15507 \shape up
15508 \size normal
15509 \emph off
15510 \bar no
15511 \noun off
15512 \color none
15513 _fs2uint.c
15514 \end_inset
15515 </cell>
15516 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15517 \begin_inset Text
15518
15519 \layout Standard
15520
15521
15522 \family roman
15523 \series medium
15524 \shape up
15525 \size normal
15526 \emph off
15527 \bar no
15528 \noun off
15529 \color none
15530 convert floating point to unsigned int
15531 \end_inset
15532 </cell>
15533 </row>
15534 <row topline="true">
15535 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15536 \begin_inset Text
15537
15538 \layout Standard
15539
15540
15541 \family roman
15542 \series medium
15543 \shape up
15544 \size normal
15545 \emph off
15546 \bar no
15547 \noun off
15548 \color none
15549 _fs2int.c
15550 \end_inset
15551 </cell>
15552 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15553 \begin_inset Text
15554
15555 \layout Standard
15556
15557
15558 \family roman
15559 \series medium
15560 \shape up
15561 \size normal
15562 \emph off
15563 \bar no
15564 \noun off
15565 \color none
15566 convert floating point to signed int
15567 \end_inset
15568 </cell>
15569 </row>
15570 <row topline="true">
15571 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15572 \begin_inset Text
15573
15574 \layout Standard
15575
15576
15577 \family roman
15578 \series medium
15579 \shape up
15580 \size normal
15581 \emph off
15582 \bar no
15583 \noun off
15584 \color none
15585 _fs2ulong.
15586 \family default
15587 \series default
15588 \shape default
15589 \size default
15590 \emph default
15591 \bar default
15592 \noun default
15593 \color default
15594 c
15595 \end_inset
15596 </cell>
15597 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15598 \begin_inset Text
15599
15600 \layout Standard
15601
15602
15603 \family roman
15604 \series medium
15605 \shape up
15606 \size normal
15607 \emph off
15608 \bar no
15609 \noun off
15610 \color none
15611 convert floating point to unsigned long
15612 \end_inset
15613 </cell>
15614 </row>
15615 <row topline="true">
15616 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15617 \begin_inset Text
15618
15619 \layout Standard
15620
15621
15622 \family roman
15623 \series medium
15624 \shape up
15625 \size normal
15626 \emph off
15627 \bar no
15628 \noun off
15629 \color none
15630 _fs2long.c
15631 \end_inset
15632 </cell>
15633 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15634 \begin_inset Text
15635
15636 \layout Standard
15637
15638
15639 \family roman
15640 \series medium
15641 \shape up
15642 \size normal
15643 \emph off
15644 \bar no
15645 \noun off
15646 \color none
15647 convert floating point to signed long
15648 \end_inset
15649 </cell>
15650 </row>
15651 <row topline="true">
15652 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15653 \begin_inset Text
15654
15655 \layout Standard
15656
15657
15658 \family roman
15659 \series medium
15660 \shape up
15661 \size normal
15662 \emph off
15663 \bar no
15664 \noun off
15665 \color none
15666 _uchar2fs.c
15667 \end_inset
15668 </cell>
15669 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15670 \begin_inset Text
15671
15672 \layout Standard
15673
15674
15675 \family roman
15676 \series medium
15677 \shape up
15678 \size normal
15679 \emph off
15680 \bar no
15681 \noun off
15682 \color none
15683 convert unsigned char to floating point
15684 \end_inset
15685 </cell>
15686 </row>
15687 <row topline="true">
15688 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15689 \begin_inset Text
15690
15691 \layout Standard
15692
15693
15694 \family roman
15695 \series medium
15696 \shape up
15697 \size normal
15698 \emph off
15699 \bar no
15700 \noun off
15701 \color none
15702 _char2fs.c
15703 \end_inset
15704 </cell>
15705 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15706 \begin_inset Text
15707
15708 \layout Standard
15709
15710
15711 \family roman
15712 \series medium
15713 \shape up
15714 \size normal
15715 \emph off
15716 \bar no
15717 \noun off
15718 \color none
15719 convert char to floating point number
15720 \end_inset
15721 </cell>
15722 </row>
15723 <row topline="true">
15724 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15725 \begin_inset Text
15726
15727 \layout Standard
15728
15729
15730 \family roman
15731 \series medium
15732 \shape up
15733 \size normal
15734 \emph off
15735 \bar no
15736 \noun off
15737 \color none
15738 _uint2fs.c
15739 \end_inset
15740 </cell>
15741 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15742 \begin_inset Text
15743
15744 \layout Standard
15745
15746
15747 \family roman
15748 \series medium
15749 \shape up
15750 \size normal
15751 \emph off
15752 \bar no
15753 \noun off
15754 \color none
15755 convert unsigned int to floating point
15756 \end_inset
15757 </cell>
15758 </row>
15759 <row topline="true">
15760 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15761 \begin_inset Text
15762
15763 \layout Standard
15764
15765
15766 \family roman
15767 \series medium
15768 \shape up
15769 \size normal
15770 \emph off
15771 \bar no
15772 \noun off
15773 \color none
15774 _int2fs.c
15775 \end_inset
15776 </cell>
15777 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15778 \begin_inset Text
15779
15780 \layout Standard
15781
15782
15783 \family roman
15784 \series medium
15785 \shape up
15786 \size normal
15787 \emph off
15788 \bar no
15789 \noun off
15790 \color none
15791 convert int to floating point numbers
15792 \end_inset
15793 </cell>
15794 </row>
15795 <row topline="true">
15796 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15797 \begin_inset Text
15798
15799 \layout Standard
15800
15801
15802 \family roman
15803 \series medium
15804 \shape up
15805 \size normal
15806 \emph off
15807 \bar no
15808 \noun off
15809 \color none
15810 _ulong2fs.c
15811 \end_inset
15812 </cell>
15813 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15814 \begin_inset Text
15815
15816 \layout Standard
15817
15818
15819 \family roman
15820 \series medium
15821 \shape up
15822 \size normal
15823 \emph off
15824 \bar no
15825 \noun off
15826 \color none
15827 convert unsigned long to floating point number
15828 \end_inset
15829 </cell>
15830 </row>
15831 <row topline="true" bottomline="true">
15832 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15833 \begin_inset Text
15834
15835 \layout Standard
15836
15837
15838 \family roman
15839 \series medium
15840 \shape up
15841 \size normal
15842 \emph off
15843 \bar no
15844 \noun off
15845 \color none
15846 _long2fs.c
15847 \end_inset
15848 </cell>
15849 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15850 \begin_inset Text
15851
15852 \layout Standard
15853
15854
15855 \family roman
15856 \series medium
15857 \shape up
15858 \size normal
15859 \emph off
15860 \bar no
15861 \noun off
15862 \color none
15863 convert long to floating point number
15864 \end_inset
15865 </cell>
15866 </row>
15867 </lyxtabular>
15868
15869 \end_inset
15870
15871
15872 \newline
15873
15874 \layout Standard
15875 \added_space_bottom bigskip
15876 These support routines are developed in ANSI-C so there is room for space
15877  and speed improvement
15878 \begin_inset Foot
15879 collapsed false
15880
15881 \layout Standard
15882
15883 These floating point routines (
15884 \emph on
15885 not
15886 \emph default
15887  sinf(), cosf(), ...) for the mcs51 are implemented in assembler.
15888
15889 \end_inset
15890
15891 .
15892  Note if all these routines are used simultaneously the data space might
15893  overflow.
15894  For serious floating point usage the large model might be needed.
15895  Also notice that you don't have to call this routines directly.
15896  The compiler will use them automatically every time a floating point operation
15897  is required.
15898 \layout Section
15899
15900 Library Routines
15901 \begin_inset LatexCommand \index{Libraries}
15902
15903 \end_inset
15904
15905
15906 \layout Standard
15907
15908
15909 \emph on
15910 <pending: this is messy and incomplete - a little more information is in
15911  sdcc/doc/libdoc.txt
15912 \emph default
15913  >
15914 \layout Subsection
15915
15916 Compiler support routines (_gptrget, _mulint etc.)
15917 \layout Subsection
15918
15919 Stdclib functions (puts, printf, strcat etc.)
15920 \layout Subsubsection
15921
15922 <stdio.h>
15923 \layout Standard
15924
15925
15926 \begin_inset LatexCommand \index{<stdio.h>}
15927
15928 \end_inset
15929
15930 As usual on embedded systems you have to provide your own
15931 \family typewriter
15932 getchar()
15933 \begin_inset LatexCommand \index{getchar()}
15934
15935 \end_inset
15936
15937
15938 \family default
15939 and
15940 \family typewriter
15941 putchar()
15942 \begin_inset LatexCommand \index{putchar()}
15943
15944 \end_inset
15945
15946
15947 \family default
15948  routines.
15949  SDCC does not know whether the system connects to a serial line with or
15950  without handshake, LCD, keyboard or other device.
15951  And whether a
15952 \family typewriter
15953 lf
15954 \family default
15955  to
15956 \family typewriter
15957 crlf
15958 \family default
15959  conversion within
15960 \family typewriter
15961 putchar()
15962 \family default
15963  is intended.
15964  You'll find examples for serial routines f.e.
15965  in sdcc/device/lib.
15966 \layout Standard
15967
15968 The default
15969 \family typewriter
15970  printf()
15971 \begin_inset LatexCommand \index{printf()}
15972
15973 \end_inset
15974
15975
15976 \family default
15977 implementation in
15978 \family typewriter
15979  printf_large.c
15980 \family default
15981  does not support float (except on ds390).
15982  To enable this recompile it with the option
15983 \emph on
15984 -
15985 \begin_inset ERT
15986 status Collapsed
15987
15988 \layout Standard
15989
15990 \backslash
15991 /
15992 \end_inset
15993
15994 DUSE_FLOATS=1
15995 \begin_inset LatexCommand \index{USE\_FLOATS}
15996
15997 \end_inset
15998
15999
16000 \emph default
16001  on the command line.
16002  Use
16003 \emph on
16004  -
16005 \begin_inset ERT
16006 status Collapsed
16007
16008 \layout Standard
16009
16010 \backslash
16011 /
16012 \end_inset
16013
16014 -model-large
16015 \begin_inset LatexCommand \index{-\/-model-large}
16016
16017 \end_inset
16018
16019
16020 \emph default
16021  for the mcs51 port, since this uses a lot of memory.
16022 \layout Standard
16023
16024 If you're short on memory you might want to use
16025 \family typewriter
16026 printf_small()
16027 \begin_inset LatexCommand \index{printf\_small()}
16028
16029 \end_inset
16030
16031
16032 \family default
16033
16034 \emph on
16035 instead
16036 \emph default
16037  of
16038 \family typewriter
16039  printf().
16040
16041 \family default
16042  For the mcs51 there additionally are assembly versions
16043 \family typewriter
16044 printf_tiny()
16045 \begin_inset LatexCommand \index{printf\_tiny() (mcs51)}
16046
16047 \end_inset
16048
16049
16050 \family default
16051  (subset of printf using less than 270 bytes) and
16052 \family typewriter
16053 printf_fast()
16054 \begin_inset LatexCommand \index{printf\_fast() (mcs51)}
16055
16056 \end_inset
16057
16058
16059 \family default
16060 and
16061 \family typewriter
16062  printf_fast_f()
16063 \begin_inset LatexCommand \index{printf\_fast\_f() (mcs51)}
16064
16065 \end_inset
16066
16067
16068 \family default
16069  (floating-point aware version of printf_fast) which should fit the requirements
16070  of many embedded systems (printf_fast() can be customized by unsetting
16071  #defines to
16072 \emph on
16073 not
16074 \emph default
16075  support long variables and field widths).
16076 \layout Subsubsection
16077
16078 <malloc.h>
16079 \begin_inset LatexCommand \index{malloc.h}
16080
16081 \end_inset
16082
16083
16084 \layout Standard
16085
16086 As of SDCC 2.6.2 you no longer need to call an initialization routine before
16087  using dynamic memory allocation
16088 \begin_inset LatexCommand \index{dynamic memory allocation (malloc)}
16089
16090 \end_inset
16091
16092  and a default heap
16093 \begin_inset LatexCommand \index{heap (malloc)}
16094
16095 \end_inset
16096
16097  space of 1024 bytes is provided for malloc to allocate memory from.
16098  If you need a different heap size you need to recompile _heap.c with the
16099  required size defined in HEAP_SIZE.
16100  It is recommended to make a copy of this file into your project directory
16101  and compile it there with:
16102 \layout Verse
16103
16104
16105 \family typewriter
16106 sdcc -c _heap.c -D HEAD_SIZE=2048
16107 \newline
16108
16109 \family default
16110 And then link it with:
16111 \layout Verse
16112
16113
16114 \family typewriter
16115 sdcc main.rel _heap.rel
16116 \newline
16117
16118 \layout Subsection
16119
16120 Math functions (sinf, powf, sqrtf etc.)
16121 \layout Subsubsection
16122
16123 <math.h>
16124 \layout Standard
16125
16126 See definitions in file <math.h>.
16127 \layout Subsection
16128
16129 Other libraries
16130 \layout Standard
16131
16132 Libraries
16133 \begin_inset LatexCommand \index{Libraries}
16134
16135 \end_inset
16136
16137  included in SDCC should have a license at least as liberal as the GNU Lesser
16138  General Public License
16139 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
16140
16141 \end_inset
16142
16143
16144 \emph on
16145 LGPL
16146 \emph default
16147 .
16148 \layout Comment
16149
16150 license statements for the libraries are missing.
16151  sdcc/device/lib/ser_ir.c
16152 \layout Comment
16153
16154 or _decdptr f.e.
16155  come with a GPL (as opposed to LGPL) License - this will not be liberal
16156  enough for many embedded programmers.
16157 \layout Standard
16158
16159 If you have ported some library or want to share experience about some code
16160  which f.e.
16161  falls into any of these categories Busses (I
16162 \begin_inset Formula $^{\textrm{2}}$
16163 \end_inset
16164
16165 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
16166  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
16167  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
16168 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
16169
16170 \end_inset
16171
16172 \SpecialChar ~
16173 would certainly like to hear about it.
16174 \layout Standard
16175 \added_space_bottom bigskip
16176 Programmers coding for embedded systems are not especially famous for being
16177  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
16178 e these references are very valuable.
16179  Let's help to create a climate where information is shared.
16180 \layout Section
16181
16182 Memory Models
16183 \layout Subsection
16184
16185 MCS51 Memory Models
16186 \begin_inset LatexCommand \index{Memory model}
16187
16188 \end_inset
16189
16190
16191 \begin_inset LatexCommand \index{MCS51 memory model}
16192
16193 \end_inset
16194
16195
16196 \layout Subsubsection
16197
16198 Small, Medium and Large
16199 \layout Standard
16200
16201 SDCC allows three memory models for MCS51 code,
16202 \shape slanted
16203 small, medium
16204 \shape default
16205  and
16206 \shape slanted
16207 large
16208 \shape default
16209 .
16210  Modules compiled with different memory models should
16211 \emph on
16212 never
16213 \emph default
16214  be combined together or the results would be unpredictable.
16215  The library routines supplied with the compiler are compiled as small,
16216  medium and large.
16217  The compiled library modules are contained in separate directories as small,
16218  medium and large so that you can link to the appropriate set.
16219 \layout Standard
16220
16221 When the medium or large model is used all variables declared without a
16222  storage class will be allocated into the external ram, this includes all
16223  parameters and local variables (for non-reentrant
16224 \begin_inset LatexCommand \index{reentrant}
16225
16226 \end_inset
16227
16228  functions).
16229  When the small model is used variables without storage class are allocated
16230  in the internal ram.
16231 \layout Standard
16232
16233 Judicious usage of the processor specific storage classes
16234 \begin_inset LatexCommand \index{Storage class}
16235
16236 \end_inset
16237
16238  and the 'reentrant' function type will yield much more efficient code,
16239  than using the large model.
16240  Several optimizations are disabled when the program is compiled using the
16241  large model, it is therefore recommended that the small model be used unless
16242  absolutely required.
16243 \layout Subsubsection
16244
16245 External Stack
16246 \begin_inset LatexCommand \label{sub:External-Stack}
16247
16248 \end_inset
16249
16250
16251 \begin_inset LatexCommand \index{stack}
16252
16253 \end_inset
16254
16255
16256 \begin_inset LatexCommand \index{External stack (mcs51)}
16257
16258 \end_inset
16259
16260
16261 \layout Standard
16262
16263 The external stack (-
16264 \begin_inset ERT
16265 status Collapsed
16266
16267 \layout Standard
16268
16269 \backslash
16270 /
16271 \end_inset
16272
16273 -xstack option
16274 \begin_inset LatexCommand \index{-\/-xstack}
16275
16276 \end_inset
16277
16278 ) is located in pdata
16279 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
16280
16281 \end_inset
16282
16283  memory (usually at the start of the external ram segment) and uses all
16284  unused space in pdata (max.
16285  256 bytes).
16286  When -
16287 \begin_inset ERT
16288 status Collapsed
16289
16290 \layout Standard
16291
16292 \backslash
16293 /
16294 \end_inset
16295
16296 -xstack option is used to compile the program, the parameters and local
16297  variables
16298 \begin_inset LatexCommand \index{local variables}
16299
16300 \end_inset
16301
16302  of all reentrant functions are allocated in this area.
16303  This option is provided for programs with large stack space requirements.
16304  When used with the -
16305 \begin_inset ERT
16306 status Collapsed
16307
16308 \layout Standard
16309
16310 \backslash
16311 /
16312 \end_inset
16313
16314 -stack-auto
16315 \begin_inset LatexCommand \index{-\/-stack-auto}
16316
16317 \end_inset
16318
16319  option, all parameters and local variables are allocated on the external
16320  stack (note: support libraries will need to be recompiled with the same
16321  options.
16322  There is a predefined target in the library makefile).
16323 \layout Standard
16324
16325 The compiler outputs the higher order address byte of the external ram segment
16326  into port P2
16327 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
16328
16329 \end_inset
16330
16331  (see also section
16332 \begin_inset LatexCommand \ref{sub:MCS51-variants}
16333
16334 \end_inset
16335
16336 ), therefore when using the External Stack option, this port
16337 \emph on
16338 may not
16339 \emph default
16340  be used by the application program.
16341 \layout Subsection
16342
16343 DS390 Memory Model
16344 \begin_inset LatexCommand \index{Memory model}
16345
16346 \end_inset
16347
16348
16349 \begin_inset LatexCommand \index{DS390 memory model}
16350
16351 \end_inset
16352
16353
16354 \layout Standard
16355
16356 The only model supported is Flat 24
16357 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
16358
16359 \end_inset
16360
16361 .
16362  This generates code for the 24 bit contiguous addressing mode of the Dallas
16363  DS80C390 part.
16364  In this mode, up to four meg of external RAM or code space can be directly
16365  addressed.
16366  See the data sheets at www.dalsemi.com for further information on this part.
16367 \newline
16368
16369 \newline
16370 Note that the compiler does not generate any code to place the processor
16371  into 24 bitmode (although
16372 \emph on
16373 tinibios
16374 \emph default
16375  in the ds390 libraries will do that for you).
16376  If you don't use
16377 \emph on
16378 tinibios
16379 \emph default
16380
16381 \begin_inset LatexCommand \index{Tinibios (DS390)}
16382
16383 \end_inset
16384
16385 , the boot loader or similar code must ensure that the processor is in 24
16386  bit contiguous addressing mode before calling the SDCC startup code.
16387 \newline
16388
16389 \newline
16390 Like the
16391 \emph on
16392 -
16393 \begin_inset ERT
16394 status Collapsed
16395
16396 \layout Standard
16397
16398 \backslash
16399 /
16400 \end_inset
16401
16402 -model-large
16403 \emph default
16404  option, variables will by default be placed into the XDATA segment.
16405
16406 \newline
16407
16408 \newline
16409 Segments may be placed anywhere in the 4 meg address space using the usual
16410  -
16411 \begin_inset ERT
16412 status Collapsed
16413
16414 \layout Standard
16415
16416 \backslash
16417 /
16418 \end_inset
16419
16420 -*-loc options.
16421  Note that if any segments are located above 64K, the -r flag must be passed
16422  to the linker to generate the proper segment relocations, and the Intel
16423  HEX output format must be used.
16424  The -r flag can be passed to the linker by using the option
16425 \emph on
16426 -Wl-r
16427 \emph default
16428  on the SDCC command line.
16429  However, currently the linker can not handle code segments > 64k.
16430 \layout Section
16431
16432 Pragmas
16433 \begin_inset LatexCommand \label{sec:Pragmas}
16434
16435 \end_inset
16436
16437
16438 \begin_inset LatexCommand \index{Pragmas}
16439
16440 \end_inset
16441
16442
16443 \layout Standard
16444
16445 SDCC supports the following #pragma directives:
16446 \layout Itemize
16447
16448
16449 \series bold
16450 save
16451 \series default
16452
16453 \begin_inset LatexCommand \index{\#pragma save}
16454
16455 \end_inset
16456
16457  - this will save most current options to the save/restore stack.
16458  See #pragma\SpecialChar ~
16459 restore.
16460 \layout Itemize
16461
16462
16463 \series bold
16464 restore
16465 \series default
16466
16467 \begin_inset LatexCommand \index{\#pragma restore}
16468
16469 \end_inset
16470
16471  - will restore saved options from the last save.
16472  saves & restores can be nested.
16473  SDCC uses a save/restore stack: save pushes current options to the stack,
16474  restore pulls current options from the stack.
16475  See #pragma\SpecialChar ~
16476 save.
16477 \newline
16478
16479 \layout Itemize
16480
16481
16482 \series bold
16483 callee_saves
16484 \series default
16485
16486 \begin_inset LatexCommand \index{\#pragma callee\_saves}
16487
16488 \end_inset
16489
16490
16491 \begin_inset LatexCommand \index{function prologue}
16492
16493 \end_inset
16494
16495  function1[,function2[,function3...]] - The compiler by default uses a caller
16496  saves convention for register saving across function calls, however this
16497  can cause unnecessary register pushing & popping
16498 \begin_inset LatexCommand \index{push/pop}
16499
16500 \end_inset
16501
16502  when calling small functions from larger functions.
16503  This option can be used to switch off the register saving convention for
16504  the function names specified.
16505  The compiler will not save registers when calling these functions, extra
16506  code need to be manually inserted at the entry & exit for these functions
16507  to save & restore the registers used by these functions, this can SUBSTANTIALLY
16508  reduce code & improve run time performance of the generated code.
16509  In the future the compiler (with inter procedural analysis) may be able
16510  to determine the appropriate scheme to use for each function call.
16511  If -
16512 \begin_inset ERT
16513 status Collapsed
16514
16515 \layout Standard
16516
16517 \backslash
16518 /
16519 \end_inset
16520
16521 -callee-saves command line option is used, the function names specified
16522  in #pragma\SpecialChar ~
16523 callee_saves
16524 \begin_inset LatexCommand \index{\#pragma callee\_saves}
16525
16526 \end_inset
16527
16528  is appended to the list of functions specified in the command line.
16529 \layout Itemize
16530
16531
16532 \series bold
16533 exclude
16534 \series default
16535
16536 \begin_inset LatexCommand \index{\#pragma exclude}
16537
16538 \end_inset
16539
16540  none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
16541  of pairs of push/pop
16542 \begin_inset LatexCommand \index{push/pop}
16543
16544 \end_inset
16545
16546  instructions in
16547 \emph on
16548 I
16549 \emph default
16550 nterrupt
16551 \begin_inset LatexCommand \index{interrupt}
16552
16553 \end_inset
16554
16555
16556 \emph on
16557 S
16558 \emph default
16559 ervice
16560 \emph on
16561 R
16562 \emph default
16563 outines.
16564  The directive should be placed immediately before the ISR function definition
16565  and it affects ALL ISR functions following it.
16566  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
16567 exclude\SpecialChar ~
16568 none
16569 \begin_inset LatexCommand \index{\#pragma exclude}
16570
16571 \end_inset
16572
16573 .
16574  See also the related keyword _naked
16575 \begin_inset LatexCommand \index{\_naked}
16576
16577 \end_inset
16578
16579
16580 \begin_inset LatexCommand \index{\_\_naked}
16581
16582 \end_inset
16583
16584 .
16585 \layout Itemize
16586
16587
16588 \series bold
16589 less_pedantic
16590 \series default
16591
16592 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
16593
16594 \end_inset
16595
16596  - the compiler will not warn you anymore for obvious mistakes, you'r on
16597  your own now ;-(
16598 \layout Itemize
16599
16600
16601 \series bold
16602 disable_warning
16603 \series default
16604  <nnnn>
16605 \begin_inset LatexCommand \index{\#pragma disable\_warning}
16606
16607 \end_inset
16608
16609  - the compiler will not warn you anymore about warning number <nnnn>.
16610 \layout Itemize
16611
16612
16613 \series bold
16614 nogcse
16615 \series default
16616
16617 \begin_inset LatexCommand \index{\#pragma nogcse}
16618
16619 \end_inset
16620
16621  - will stop global common subexpression elimination.
16622 \layout Itemize
16623
16624
16625 \series bold
16626 noinduction
16627 \series default
16628
16629 \begin_inset LatexCommand \index{\#pragma noinduction}
16630
16631 \end_inset
16632
16633  - will stop loop induction optimizations.
16634 \layout Itemize
16635
16636
16637 \series bold
16638 noinvariant
16639 \series default
16640
16641 \begin_inset LatexCommand \index{\#pragma noinvariant}
16642
16643 \end_inset
16644
16645  - will not do loop invariant optimizations.
16646  For more details see Loop Invariants in section
16647 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
16648
16649 \end_inset
16650
16651 .
16652 \layout Itemize
16653
16654
16655 \series bold
16656 noiv
16657 \series default
16658
16659 \begin_inset LatexCommand \index{\#pragma noiv}
16660
16661 \end_inset
16662
16663  - Do not generate interrupt
16664 \begin_inset LatexCommand \index{interrupt}
16665
16666 \end_inset
16667
16668  vector table
16669 \begin_inset LatexCommand \index{interrupt vector table}
16670
16671 \end_inset
16672
16673  entries for all ISR functions defined after the pragma.
16674  This is useful in cases where the interrupt vector table must be defined
16675  manually, or when there is a secondary, manually defined interrupt vector
16676  table (e.g.
16677  for the autovector feature of the Cypress EZ-USB FX2).
16678  More elegantly this can be achieved by obmitting the optional interrupt
16679  number after the interrupt keyword, see section
16680 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
16681
16682 \end_inset
16683
16684 \SpecialChar ~
16685 about interrupts.
16686 \layout Itemize
16687
16688
16689 \series bold
16690 nojtbound
16691 \series default
16692
16693 \begin_inset LatexCommand \index{\#pragma nojtbound}
16694
16695 \end_inset
16696
16697  - will not generate code for boundary value checking, when switch statements
16698  are turned into jump-tables (dangerous).
16699  For more details see section
16700 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
16701
16702 \end_inset
16703
16704 .
16705 \layout Itemize
16706
16707
16708 \series bold
16709 noloopreverse
16710 \series default
16711
16712 \begin_inset LatexCommand \index{\#pragma noloopreverse}
16713
16714 \end_inset
16715
16716  - Will not do loop reversal optimization
16717 \layout Itemize
16718
16719
16720 \series bold
16721 nooverlay
16722 \series default
16723
16724 \begin_inset LatexCommand \index{\#pragma nooverlay}
16725
16726 \end_inset
16727
16728  - the compiler will not overlay the parameters and local variables of a
16729  function.
16730 \layout Itemize
16731
16732
16733 \series bold
16734 stackauto
16735 \series default
16736
16737 \begin_inset LatexCommand \index{\#pragma stackauto}
16738
16739 \end_inset
16740
16741 - See option -
16742 \begin_inset ERT
16743 status Collapsed
16744
16745 \layout Standard
16746
16747 \backslash
16748 /
16749 \end_inset
16750
16751 -stack-auto
16752 \begin_inset LatexCommand \index{-\/-stack-auto}
16753
16754 \end_inset
16755
16756  and section
16757 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
16758
16759 \end_inset
16760
16761  Parameters and Local Variables.
16762 \layout Itemize
16763
16764
16765 \series bold
16766 opt_code_speed
16767 \series default
16768
16769 \begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
16770
16771 \end_inset
16772
16773 - The compiler will optimize code generation towards fast code, possibly
16774  at the expense of code size.
16775  Currently this has little effect.
16776 \layout Itemize
16777
16778
16779 \series bold
16780 opt_code_size
16781 \series default
16782
16783 \begin_inset LatexCommand \index{\#pragma opt\_code\_size}
16784
16785 \end_inset
16786
16787 - The compiler will optimize code generation towards compact code, possibly
16788  at the expense of code speed.
16789  Currently this has little effect.
16790 \layout Itemize
16791
16792
16793 \series bold
16794 opt_code_balanced
16795 \series default
16796
16797 \begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
16798
16799 \end_inset
16800
16801 - The compiler will attempt to generate code that is both compact and fast,
16802  as long as meeting one goal is not a detriment to the other (this is the
16803  default).
16804
16805 \layout Itemize
16806
16807
16808 \series bold
16809 std_sdcc89
16810 \series default
16811
16812 \begin_inset LatexCommand \index{\#pragma std\_sdcc89}
16813
16814 \end_inset
16815
16816 - Generally follow the C89 standard, but allow SDCC features that conflict
16817  with the standard (default).
16818 \layout Itemize
16819
16820
16821 \series bold
16822 std_c89
16823 \series default
16824
16825 \begin_inset LatexCommand \index{\#pragma std\_c89}
16826
16827 \end_inset
16828
16829 - Follow the C89 standard and disable SDCC features that conflict with the
16830  standard.
16831 \layout Itemize
16832
16833
16834 \series bold
16835 std_sdcc99
16836 \series default
16837
16838 \begin_inset LatexCommand \index{\#pragma std\_sdcc99}
16839
16840 \end_inset
16841
16842 - Generally follow the C99 standard, but allow SDCC features that conflict
16843  with the standard (incomplete support).
16844 \layout Itemize
16845
16846
16847 \series bold
16848 std_c99
16849 \series default
16850
16851 \begin_inset LatexCommand \index{\#pragma std\_c99}
16852
16853 \end_inset
16854
16855 - Follow the C99 standard and disable SDCC features that conflict with the
16856  standard (incomplete support).
16857 \layout Itemize
16858
16859
16860 \series bold
16861 codeseg
16862 \series default
16863  <name>
16864 \begin_inset LatexCommand \index{\#pragma codeseg}
16865
16866 \end_inset
16867
16868 - Use this name (max.
16869  8 characters) for the code segment.
16870  See option -
16871 \begin_inset ERT
16872 status Collapsed
16873
16874 \layout Standard
16875
16876 \backslash
16877 /
16878 \end_inset
16879
16880 -codeseg.
16881 \layout Itemize
16882
16883
16884 \series bold
16885 constseg
16886 \series default
16887  <name>
16888 \begin_inset LatexCommand \index{\#pragma constseg}
16889
16890 \end_inset
16891
16892 - Use this name (max.
16893  8 characters) for the const segment.
16894  See option -
16895 \begin_inset ERT
16896 status Collapsed
16897
16898 \layout Standard
16899
16900 \backslash
16901 /
16902 \end_inset
16903
16904 -constseg.
16905 \layout Standard
16906
16907 The preprocessor SDCPP
16908 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
16909
16910 \end_inset
16911
16912  supports the following #pragma directives:
16913 \layout Itemize
16914
16915
16916 \series bold
16917 pedantic_parse_number
16918 \series default
16919
16920 \begin_inset LatexCommand \index{\#pragma pedantic\_parse\_number}
16921
16922 \end_inset
16923
16924  (+ | -) - Pedantic parse numbers so that situations like 0xfe-LO_B(3) are
16925  parsed properly and the macro LO_B(3) gets expanded.
16926  Default is off.
16927  Below is an example on how to use this pragma.
16928
16929 \emph on
16930  Note: this functionality is not in conformance with standard!
16931 \layout Verse
16932
16933
16934 \family typewriter
16935 #pragma pedantic_parse_number +
16936 \begin_inset LatexCommand \index{\#pragma pedantic\_parse\_number}
16937
16938 \end_inset
16939
16940
16941 \newline
16942
16943 \newline
16944 #define LO_B(x) ((x) & 0xff)
16945 \newline
16946
16947 \newline
16948 unsigned char foo(void)
16949 \newline
16950 {
16951 \newline
16952 \SpecialChar ~
16953 \SpecialChar ~
16954 \SpecialChar ~
16955 unsigned char c=0xfe-LO_B(3);
16956 \newline
16957
16958 \newline
16959 \SpecialChar ~
16960 \SpecialChar ~
16961 \SpecialChar ~
16962 return c;
16963 \newline
16964 }
16965 \newline
16966
16967 \layout Itemize
16968
16969
16970 \series bold
16971 preproc_asm
16972 \series default
16973
16974 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
16975
16976 \end_inset
16977
16978  (+ | -) - switch _asm _endasm block preprocessing on / off.
16979  Default is on.
16980  You use this prama to define multilines of assembly code.
16981  This will prevent the preprocessor from changing the formating required
16982  by assembly code.
16983  Below is an example on how to use this pragma.
16984 \layout Verse
16985
16986
16987 \family typewriter
16988 #pragma preproc_asm -
16989 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
16990
16991 \end_inset
16992
16993
16994 \newline
16995 #define MYDELAY _asm
16996 \newline
16997 \SpecialChar ~
16998 \SpecialChar ~
16999 \SpecialChar ~
17000 nop ;my assembly comment...
17001 \newline
17002 \SpecialChar ~
17003 \SpecialChar ~
17004 \SpecialChar ~
17005 nop
17006 \newline
17007 \SpecialChar ~
17008 \SpecialChar ~
17009 \SpecialChar ~
17010 nop
17011 \newline
17012 _endasm
17013 \newline
17014 #pragma preproc_asm +
17015 \newline
17016
17017 \newline
17018 void foo (void)
17019 \newline
17020 {
17021 \newline
17022 \SpecialChar ~
17023 \SpecialChar ~
17024 \SpecialChar ~
17025  ...
17026
17027 \newline
17028 \SpecialChar ~
17029 \SpecialChar ~
17030 \SpecialChar ~
17031  MYDELAY;
17032 \newline
17033 \SpecialChar ~
17034 \SpecialChar ~
17035 \SpecialChar ~
17036  ...
17037
17038 \newline
17039 }
17040 \newline
17041
17042 \layout Itemize
17043
17044
17045 \series bold
17046 sdcc_hash
17047 \series default
17048
17049 \begin_inset LatexCommand \index{\#pragma sdcc\_hash}
17050
17051 \end_inset
17052
17053  (+ | -) - Allow "naked" hash in macro definition, for example:
17054 \newline
17055
17056 \family typewriter
17057 #define DIR_LO(x) #(x & 0xff)
17058 \family default
17059
17060 \newline
17061 Default is off.
17062  Below is an example on how to use this pragma.
17063 \layout Verse
17064
17065
17066 \family typewriter
17067 #pragma preproc_asm +
17068 \newline
17069 #pragma sdcc_hash +
17070 \begin_inset LatexCommand \index{\#pragma sdcc\_hash}
17071
17072 \end_inset
17073
17074
17075 \newline
17076
17077 \newline
17078 #define ROMCALL(x)
17079 \backslash
17080
17081 \newline
17082 \SpecialChar ~
17083 \SpecialChar ~
17084 \SpecialChar ~
17085 mov R6_B3, #(x & 0xff)
17086 \backslash
17087
17088 \newline
17089 \SpecialChar ~
17090 \SpecialChar ~
17091 \SpecialChar ~
17092 mov R7_B3, #((x >> 8) & 0xff)
17093 \backslash
17094
17095 \newline
17096 \SpecialChar ~
17097 \SpecialChar ~
17098 \SpecialChar ~
17099 lcall __romcall
17100 \newline
17101
17102 \newline
17103 ...
17104 \newline
17105 _asm
17106 \newline
17107 ROMCALL(72)
17108 \newline
17109 _endasm;
17110 \newline
17111 ...
17112 \newline
17113
17114 \layout Standard
17115
17116 The pragma's are intended to be used to turn-on or off certain optimizations
17117  which might cause the compiler to generate extra stack / data space to
17118  store compiler generated temporary variables.
17119  This usually happens in large functions.
17120  Pragma directives should be used as shown in the following example, they
17121  are used to control options & optimizations for a given function; pragmas
17122  should be placed before and/or after a function, placing pragma's inside
17123  a function body could have unpredictable results.
17124 \layout Verse
17125
17126
17127 \family typewriter
17128 #pragma save
17129 \begin_inset LatexCommand \index{\#pragma save}
17130
17131 \end_inset
17132
17133  \SpecialChar ~
17134 \SpecialChar ~
17135 \SpecialChar ~
17136 \SpecialChar ~
17137 \SpecialChar ~
17138 \SpecialChar ~
17139 \SpecialChar ~
17140 /* save the current settings */
17141 \newline
17142 #pragma nogcse
17143 \begin_inset LatexCommand \index{\#pragma nogcse}
17144
17145 \end_inset
17146
17147  \SpecialChar ~
17148 \SpecialChar ~
17149 \SpecialChar ~
17150 \SpecialChar ~
17151 \SpecialChar ~
17152 /* turnoff global subexpression elimination */
17153 \newline
17154 #pragma noinduction
17155 \begin_inset LatexCommand \index{\#pragma noinduction}
17156
17157 \end_inset
17158
17159  /* turn off induction optimizations */
17160 \newline
17161 int foo ()
17162 \newline
17163 {
17164 \newline
17165 \SpecialChar ~
17166  \SpecialChar ~
17167  ...
17168
17169 \newline
17170 \SpecialChar ~
17171  \SpecialChar ~
17172  /* large code */
17173 \newline
17174 \SpecialChar ~
17175  \SpecialChar ~
17176  ...
17177
17178 \newline
17179 }
17180 \newline
17181 #pragma restore
17182 \begin_inset LatexCommand \index{\#pragma restore}
17183
17184 \end_inset
17185
17186  /* turn the optimizations back on */
17187 \layout Standard
17188
17189 The compiler will generate a warning message when extra space is allocated.
17190  It is strongly recommended that the save and restore pragma's be used when
17191  changing options for a function.
17192 \newline
17193
17194 \newline
17195
17196 \newline
17197
17198 \layout Section
17199
17200 Defines Created by the Compiler
17201 \layout Standard
17202
17203 The compiler creates the following #defines
17204 \begin_inset LatexCommand \index{\#defines}
17205
17206 \end_inset
17207
17208
17209 \begin_inset LatexCommand \index{Defines created by the compiler}
17210
17211 \end_inset
17212
17213 :
17214 \newline
17215
17216 \layout Standard
17217
17218
17219 \begin_inset  Tabular
17220 <lyxtabular version="3" rows="11" columns="2">
17221 <features>
17222 <column alignment="left" valignment="top" leftline="true" width="3in">
17223 <column alignment="left" valignment="top" leftline="true" rightline="true" width="3in">
17224 <row topline="true" bottomline="true">
17225 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17226 \begin_inset Text
17227
17228 \layout Standard
17229
17230
17231 \series bold
17232 #define
17233 \end_inset
17234 </cell>
17235 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17236 \begin_inset Text
17237
17238 \layout Standard
17239
17240
17241 \series bold
17242 Description
17243 \end_inset
17244 </cell>
17245 </row>
17246 <row topline="true">
17247 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17248 \begin_inset Text
17249
17250 \layout Standard
17251
17252 SDCC
17253 \begin_inset LatexCommand \index{SDCC}
17254
17255 \end_inset
17256
17257
17258 \end_inset
17259 </cell>
17260 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17261 \begin_inset Text
17262
17263 \layout Standard
17264
17265 Always defined.
17266  Since version 2.5.6 the version number as an int (ex.
17267  256)
17268 \end_inset
17269 </cell>
17270 </row>
17271 <row topline="true">
17272 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17273 \begin_inset Text
17274
17275 \layout Standard
17276
17277 SDCC_mcs51
17278 \begin_inset LatexCommand \index{SDCC\_mcs51}
17279
17280 \end_inset
17281
17282  or SDCC_ds390
17283 \begin_inset LatexCommand \index{SDCC\_ds390}
17284
17285 \end_inset
17286
17287  or SDCC_z80
17288 \begin_inset LatexCommand \index{SDCC\_z80}
17289
17290 \end_inset
17291
17292 , etc.
17293 \end_inset
17294 </cell>
17295 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17296 \begin_inset Text
17297
17298 \layout Standard
17299
17300 depending on the model used (e.g.: -mds390)
17301 \end_inset
17302 </cell>
17303 </row>
17304 <row topline="true">
17305 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17306 \begin_inset Text
17307
17308 \layout Standard
17309
17310 __mcs51
17311 \begin_inset LatexCommand \index{\_\_mcs51}
17312
17313 \end_inset
17314
17315 , __ds390
17316 \begin_inset LatexCommand \index{\_\_ds390}
17317
17318 \end_inset
17319
17320 , __hc08
17321 \begin_inset LatexCommand \index{\_\_hc08}
17322
17323 \end_inset
17324
17325 , __z80
17326 \begin_inset LatexCommand \index{\_\_z80}
17327
17328 \end_inset
17329
17330 , etc
17331 \end_inset
17332 </cell>
17333 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17334 \begin_inset Text
17335
17336 \layout Standard
17337
17338 depending on the model used (e.g.
17339  -mz80)
17340 \end_inset
17341 </cell>
17342 </row>
17343 <row topline="true">
17344 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17345 \begin_inset Text
17346
17347 \layout Standard
17348
17349 SDCC_STACK_AUTO
17350 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
17351
17352 \end_inset
17353
17354
17355 \end_inset
17356 </cell>
17357 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17358 \begin_inset Text
17359
17360 \layout Standard
17361
17362 when
17363 \emph on
17364 -
17365 \begin_inset ERT
17366 status Collapsed
17367
17368 \layout Standard
17369
17370 \backslash
17371 /
17372 \end_inset
17373
17374 -stack-auto
17375 \emph default
17376  option is used
17377 \end_inset
17378 </cell>
17379 </row>
17380 <row topline="true">
17381 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17382 \begin_inset Text
17383
17384 \layout Standard
17385
17386 SDCC_MODEL_SMALL
17387 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
17388
17389 \end_inset
17390
17391
17392 \end_inset
17393 </cell>
17394 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17395 \begin_inset Text
17396
17397 \layout Standard
17398
17399 when
17400 \emph on
17401 -
17402 \begin_inset ERT
17403 status Collapsed
17404
17405 \layout Standard
17406
17407 \backslash
17408 /
17409 \end_inset
17410
17411 -model-small
17412 \emph default
17413  is used
17414 \end_inset
17415 </cell>
17416 </row>
17417 <row topline="true">
17418 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17419 \begin_inset Text
17420
17421 \layout Standard
17422
17423 SDCC_MODEL_MEDIUM
17424 \begin_inset LatexCommand \index{SDCC\_MODEL\_MEDIUM}
17425
17426 \end_inset
17427
17428
17429 \end_inset
17430 </cell>
17431 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17432 \begin_inset Text
17433
17434 \layout Standard
17435
17436 when
17437 \emph on
17438 -
17439 \begin_inset ERT
17440 status Collapsed
17441
17442 \layout Standard
17443
17444 \backslash
17445 /
17446 \end_inset
17447
17448 -model-medium
17449 \emph default
17450  is used
17451 \end_inset
17452 </cell>
17453 </row>
17454 <row topline="true">
17455 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17456 \begin_inset Text
17457
17458 \layout Standard
17459
17460 SDCC_MODEL_LARGE
17461 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
17462
17463 \end_inset
17464
17465
17466 \end_inset
17467 </cell>
17468 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17469 \begin_inset Text
17470
17471 \layout Standard
17472
17473 when
17474 \emph on
17475 -
17476 \begin_inset ERT
17477 status Collapsed
17478
17479 \layout Standard
17480
17481 \backslash
17482 /
17483 \end_inset
17484
17485 -model-large
17486 \emph default
17487  is used
17488 \end_inset
17489 </cell>
17490 </row>
17491 <row topline="true">
17492 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17493 \begin_inset Text
17494
17495 \layout Standard
17496
17497 SDCC_USE_XSTACK
17498 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
17499
17500 \end_inset
17501
17502
17503 \end_inset
17504 </cell>
17505 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17506 \begin_inset Text
17507
17508 \layout Standard
17509
17510 when
17511 \emph on
17512 -
17513 \begin_inset ERT
17514 status Collapsed
17515
17516 \layout Standard
17517
17518 \backslash
17519 /
17520 \end_inset
17521
17522 -xstack
17523 \emph default
17524  option is used
17525 \end_inset
17526 </cell>
17527 </row>
17528 <row topline="true">
17529 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17530 \begin_inset Text
17531
17532 \layout Standard
17533
17534 SDCC_STACK_TENBIT
17535 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
17536
17537 \end_inset
17538
17539
17540 \end_inset
17541 </cell>
17542 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17543 \begin_inset Text
17544
17545 \layout Standard
17546
17547 when
17548 \emph on
17549 -mds390
17550 \emph default
17551  is used
17552 \end_inset
17553 </cell>
17554 </row>
17555 <row topline="true" bottomline="true">
17556 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17557 \begin_inset Text
17558
17559 \layout Standard
17560
17561 SDCC_MODEL_FLAT24
17562 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
17563
17564 \end_inset
17565
17566
17567 \end_inset
17568 </cell>
17569 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17570 \begin_inset Text
17571
17572 \layout Standard
17573
17574 when
17575 \emph on
17576 -mds390
17577 \emph default
17578  is used
17579 \end_inset
17580 </cell>
17581 </row>
17582 </lyxtabular>
17583
17584 \end_inset
17585
17586
17587 \layout Chapter
17588
17589 Notes on supported Processors
17590 \layout Section
17591
17592 MCS51 variants
17593 \begin_inset LatexCommand \label{sub:MCS51-variants}
17594
17595 \end_inset
17596
17597
17598 \begin_inset LatexCommand \index{MCS51 variants}
17599
17600 \end_inset
17601
17602
17603 \layout Standard
17604
17605 MCS51 processors are available from many vendors and come in many different
17606  flavours.
17607  While they might differ considerably in respect to Special Function Registers
17608  the core MCS51 is usually not modified or is kept compatible.
17609
17610 \layout Subsection
17611
17612 pdata access by SFR
17613 \layout Standard
17614
17615 With the upcome of devices with internal xdata and flash memory devices
17616  using port P2
17617 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
17618
17619 \end_inset
17620
17621  as dedicated I/O port is becoming more popular.
17622  Switching the high byte for pdata
17623 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
17624
17625 \end_inset
17626
17627  access which was formerly done by port P2 is then achieved by a Special
17628  Function Register
17629 \begin_inset LatexCommand \index{sfr}
17630
17631 \end_inset
17632
17633 .
17634  In well-established MCS51 tradition the address of this
17635 \emph on
17636 sfr
17637 \emph default
17638  is where the chip designers decided to put it.
17639  Needless to say that they didn't agree on a common name either.
17640  So that the startup code can correctly initialize xdata variables, you
17641  should define an sfr with the name _XPAGE
17642 \family typewriter
17643
17644 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
17645
17646 \end_inset
17647
17648
17649 \family default
17650  at the appropriate location if the default, port P2, is not used for this.
17651  Some examples are:
17652 \layout Verse
17653
17654
17655 \family typewriter
17656 __sfr __at (0x92) _XPAGE; /* Cypress EZ-USB family */
17657 \layout Verse
17658
17659
17660 \family typewriter
17661 __sfr __at (0xaf) _XPAGE; /* some Silicon Labs (Cygnal) chips */
17662 \layout Verse
17663
17664
17665 \family typewriter
17666 __sfr __at (0xaa) _XPAGE; /* some Silicon Labs (Cygnal) chips */
17667 \layout Standard
17668
17669 For more exotic implementations further customizations may be needed.
17670  See section
17671 \begin_inset LatexCommand \ref{sub:Startup-Code}
17672
17673 \end_inset
17674
17675  for other possibilities.
17676 \layout Subsection
17677
17678 Other Features available by SFR
17679 \layout Standard
17680 \added_space_bottom bigskip
17681 Some MCS51 variants offer features like Double DPTR
17682 \begin_inset LatexCommand \index{DPTR}
17683
17684 \end_inset
17685
17686 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
17687  These are currently not used for the MCS51 port.
17688  If you absolutely need them you can fall back to inline assembly or submit
17689  a patch to SDCC.
17690 \layout Section
17691
17692 DS400 port
17693 \layout Standard
17694 \added_space_bottom bigskip
17695 The DS80C400
17696 \begin_inset LatexCommand \index{DS80C400}
17697
17698 \end_inset
17699
17700
17701 \begin_inset LatexCommand \index{DS400}
17702
17703 \end_inset
17704
17705  microcontroller has a rich set of peripherals.
17706  In its built-in ROM library it includes functions to access some of the
17707  features, among them is a TCP stack with IP4 and IP6 support.
17708  Library headers (currently in beta status) and other files are provided
17709  at
17710 \size footnotesize
17711
17712 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
17713
17714 \end_inset
17715
17716 .
17717
17718 \layout Section
17719
17720 The Z80 and gbz80 port
17721 \layout Standard
17722
17723 SDCC can target both the Zilog Z80
17724 \begin_inset LatexCommand \index{Z80}
17725
17726 \end_inset
17727
17728  and the Nintendo Gameboy's Z80-like gbz80
17729 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
17730
17731 \end_inset
17732
17733 .
17734  The Z80 port is passed through the same
17735 \emph on
17736 regressions tests
17737 \begin_inset LatexCommand \index{Regression test}
17738
17739 \end_inset
17740
17741
17742 \emph default
17743  (see section
17744 \begin_inset LatexCommand \ref{sec:Quality-control}
17745
17746 \end_inset
17747
17748 ) as the MCS51 and DS390 ports, so floating point support, support for long
17749  variables and bitfield support is fine.
17750  See mailing lists and forums about interrupt routines.
17751 \layout Standard
17752 \added_space_bottom bigskip
17753 As always, the code is the authoritative reference - see z80/ralloc.c and
17754  z80/gen.c.
17755  The stack
17756 \begin_inset LatexCommand \index{Z80!stack}
17757
17758 \end_inset
17759
17760  frame is similar to that generated by the IAR Z80 compiler.
17761  IX is used as the base pointer, HL and IY are used as a temporary registers,
17762  and BC and DE are available for holding variables.
17763  Return values
17764 \begin_inset LatexCommand \index{Z80!return value}
17765
17766 \end_inset
17767
17768  for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
17769  bytes).
17770  The gbz80 port use the same set of registers for the return values, but
17771  in a different order of significance: E (one byte), DE (two bytes), or
17772  HLDE (four bytes).
17773 \layout Section
17774
17775 The HC08 port
17776 \layout Standard
17777
17778 The port to the Freescale/Motorola HC08
17779 \begin_inset LatexCommand \index{HC08}
17780
17781 \end_inset
17782
17783  family has been added in October 2003, and is still undergoing some basic
17784  development.
17785  The code generator is complete, but the register allocation is still quite
17786  unoptimized.
17787  Some of the SDCC's standard C library functions have embedded non-HC08
17788  inline assembly and so are not yet usable.
17789 \layout Standard
17790 \added_space_bottom bigskip
17791 The HC08 port passes the regression test suite (see section
17792 \begin_inset LatexCommand \ref{sec:Quality-control}
17793
17794 \end_inset
17795
17796 ).
17797 \layout Section
17798 \pagebreak_top
17799 The PIC14 port
17800 \layout Standard
17801
17802 The 14bit PIC
17803 \begin_inset LatexCommand \index{PIC14}
17804
17805 \end_inset
17806
17807  port still requires a major effort from the development community.
17808  However it can work for simple code.
17809  It passes its (smaller set of) regression tests
17810 \begin_inset LatexCommand \index{Regression test (PIC14)}
17811
17812 \end_inset
17813
17814  in the directory
17815 \shape italic
17816 sdcc/src/regression
17817 \shape default
17818 .
17819 \layout Subsection
17820
17821 C code and 14bit PIC code page
17822 \begin_inset LatexCommand \index{code page (pic14)}
17823
17824 \end_inset
17825
17826  and RAM banks
17827 \begin_inset LatexCommand \index{RAM bank (pic14)}
17828
17829 \end_inset
17830
17831
17832 \layout Standard
17833
17834 The linker organizes allocation for the code page and RAM banks.
17835  It does not have intimate knowledge of the code flow.
17836  It will put all the code section of a single asm file into a single code
17837  page.
17838  In order to make use of multiple code pages, separate asm files must be
17839  used.
17840  The compiler treats all functions of a single C file as being in the same
17841  code page unless it is non static.
17842 \newline
17843
17844 \newline
17845 To get the best follow these guide lines:
17846 \layout Enumerate
17847
17848 Make local functions static, as non static functions require code page selection
17849  overhead.
17850 \layout Enumerate
17851
17852 For devices that have multiple code pages it is more efficient to use the
17853  same number of files as pages, i.e.
17854  for the 16F877 use 4 separate files and i.e.
17855  for the 16F874 use 2 separate files.
17856  This way the linker can put the code for each file into different code
17857  pages and there's less page selection overhead.
17858 \layout Enumerate
17859
17860  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
17861  instruction set), use 'unsigned char' whereever possible instead of 'int'.
17862 \layout Subsection
17863
17864 Creating a device include file
17865 \layout Standard
17866
17867 For generating a device include file
17868 \begin_inset LatexCommand \index{PIC14!Header files}
17869
17870 \end_inset
17871
17872  use the support perl script inc2h.pl kept in directory support/script.
17873 \layout Subsection
17874
17875 Interrupt code
17876 \layout Standard
17877
17878 For the interrupt function, use the keyword '__interrupt'
17879 \begin_inset LatexCommand \index{PIC14!interrupt}
17880
17881 \end_inset
17882
17883  with level number of 0 (PIC14 only has 1 interrupt so this number is only
17884  there to avoid a syntax error - it ought to be fixed).
17885  E.g.:
17886 \layout Verse
17887
17888
17889 \family typewriter
17890 void Intr(void) __interrupt 0
17891 \newline
17892 {
17893 \newline
17894 \SpecialChar ~
17895 \SpecialChar ~
17896 T0IF = 0; /* Clear timer interrupt */
17897 \newline
17898 }
17899 \layout Subsection
17900
17901 Linking and assembling
17902 \layout Standard
17903
17904 For assembling you can use either GPUTILS'
17905 \begin_inset LatexCommand \index{gputils (pic tools)}
17906
17907 \end_inset
17908
17909  gpasm.exe or MPLAB's mpasmwin.exe.
17910  GPUTILS is available from
17911 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
17912
17913 \end_inset
17914
17915 .
17916  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
17917  If you use MPLAB and an interrupt function then the linker script file
17918  vectors section will need to be enlarged to link with mplink.
17919 \newline
17920
17921 \newline
17922 Here is a
17923 \family typewriter
17924 Makefile
17925 \family default
17926  using GPUTILS:
17927 \layout Verse
17928
17929
17930 \family typewriter
17931 .c.o:
17932 \newline
17933 \SpecialChar ~
17934 \SpecialChar ~
17935 \SpecialChar ~
17936 \SpecialChar ~
17937 \SpecialChar ~
17938 \SpecialChar ~
17939 \SpecialChar ~
17940 \SpecialChar ~
17941 sdcc -S -V -mpic14 -p16F877 $<
17942 \newline
17943 \SpecialChar ~
17944 \SpecialChar ~
17945 \SpecialChar ~
17946 \SpecialChar ~
17947 \SpecialChar ~
17948 \SpecialChar ~
17949 \SpecialChar ~
17950 \SpecialChar ~
17951 gpasm -c $*.asm
17952 \newline
17953
17954 \newline
17955 $(PRJ).hex: $(OBJS)
17956 \newline
17957 \SpecialChar ~
17958 \SpecialChar ~
17959 \SpecialChar ~
17960 \SpecialChar ~
17961 \SpecialChar ~
17962 \SpecialChar ~
17963 \SpecialChar ~
17964 \SpecialChar ~
17965 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS) libsdcc.lib
17966 \layout Standard
17967
17968 Here is a
17969 \family typewriter
17970 Makefile
17971 \family default
17972  using MPLAB:
17973 \layout Verse
17974
17975
17976 \family typewriter
17977 .c.o:
17978 \newline
17979 \SpecialChar ~
17980 \SpecialChar ~
17981 \SpecialChar ~
17982 \SpecialChar ~
17983 \SpecialChar ~
17984 \SpecialChar ~
17985 \SpecialChar ~
17986 \SpecialChar ~
17987 sdcc -S -V -mpic14 -p16F877 $<
17988 \newline
17989 \SpecialChar ~
17990 \SpecialChar ~
17991 \SpecialChar ~
17992 \SpecialChar ~
17993 \SpecialChar ~
17994 \SpecialChar ~
17995 \SpecialChar ~
17996 \SpecialChar ~
17997 mpasmwin /q /o $*.asm
17998 \newline
17999
18000 \newline
18001 $(PRJ).hex: $(OBJS)
18002 \newline
18003 \SpecialChar ~
18004 \SpecialChar ~
18005 \SpecialChar ~
18006 \SpecialChar ~
18007 \SpecialChar ~
18008 \SpecialChar ~
18009 \SpecialChar ~
18010 \SpecialChar ~
18011 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS) libsdcc.lib
18012 \layout Standard
18013
18014 Please note that indentations within a
18015 \family typewriter
18016  Makefile
18017 \family default
18018  have to be done with a tabulator character.
18019 \layout Subsection
18020
18021 Command-line options
18022 \layout Standard
18023
18024 Besides the switches common to all SDCC backends, the PIC14 port accepts
18025  the following options (for an updated list see sdcc -
18026 \begin_inset ERT
18027 status Collapsed
18028
18029 \layout Standard
18030
18031 \backslash
18032 /
18033 \end_inset
18034
18035 -help):
18036 \layout List
18037 \labelwidthstring 00.00.0000
18038
18039 -
18040 \begin_inset ERT
18041 status Collapsed
18042
18043 \layout Standard
18044
18045 \backslash
18046 /
18047 \end_inset
18048
18049 -debug-extra
18050 \begin_inset LatexCommand \index{PIC14!Options!-\/-debug-extra}
18051
18052 \end_inset
18053
18054  emit debug info in assembly output
18055 \layout List
18056 \labelwidthstring 00.00.0000
18057
18058 -
18059 \begin_inset ERT
18060 status Collapsed
18061
18062 \layout Standard
18063
18064 \backslash
18065 /
18066 \end_inset
18067
18068 -no-pcode-opt
18069 \begin_inset LatexCommand \index{PIC14!Options!-\/-no-pcode-opt}
18070
18071 \end_inset
18072
18073  disable (slightly faulty) optimization on pCode
18074 \layout List
18075 \labelwidthstring 00.00.0000
18076
18077 -
18078 \begin_inset ERT
18079 status Collapsed
18080
18081 \layout Standard
18082
18083 \backslash
18084 /
18085 \end_inset
18086
18087 -stack-loc
18088 \begin_inset LatexCommand \index{PIC14!Options!-\/-stack-loc}
18089
18090 \end_inset
18091
18092  sets the lowest address of the argument passing stack (defaults to a suitably
18093  large shared databank to reduce BANKSEL overhead)
18094 \layout List
18095 \labelwidthstring 00.00.0000
18096
18097 -
18098 \begin_inset ERT
18099 status Collapsed
18100
18101 \layout Standard
18102
18103 \backslash
18104 /
18105 \end_inset
18106
18107 -stack-size
18108 \begin_inset LatexCommand \index{PIC14!Options!-\/-stack-size}
18109
18110 \end_inset
18111
18112  sets the size if the argument passing stack (default: 16, minimum: 4)
18113 \layout Subsection
18114
18115 The library
18116 \layout Subsubsection
18117
18118 error: missing definition for symbol
18119 \begin_inset Quotes sld
18120 \end_inset
18121
18122 __gptrget1
18123 \begin_inset Quotes srd
18124 \end_inset
18125
18126
18127 \layout Standard
18128
18129 The PIC14 port uses library routines to provide more complex operations
18130  like multiplication, division/modulus and (generic) pointer dereferencing.
18131  In order to add these routines to your project, you must link with PIC14's
18132
18133 \family typewriter
18134 libsdcc.lib
18135 \family default
18136 .
18137  For single source file projects this is done automatically, more complex
18138  projects must add
18139 \family typewriter
18140 libsdcc.lib
18141 \family default
18142  to the linker's arguments.
18143  Make sure you also add an include path for the library (using the -I switch
18144  to the linker)!
18145 \layout Subsubsection
18146
18147 Processor mismatch in file
18148 \begin_inset Quotes sld
18149 \end_inset
18150
18151 XXX
18152 \begin_inset Quotes srd
18153 \end_inset
18154
18155 .
18156 \layout Standard
18157
18158 This warning can usually be ignored due to the very good compatibility amongst
18159  14 bit PIC
18160 \begin_inset LatexCommand \index{PIC14}
18161
18162 \end_inset
18163
18164  devices.
18165 \layout Standard
18166
18167 You might also consider recompiling the library for your specific device
18168  by changing the ARCH=p16f877 (default target) entry in
18169 \family typewriter
18170 device/lib/pic/Makefile.in
18171 \family default
18172  and
18173 \family typewriter
18174 device/lib/pic/Makefile
18175 \family default
18176  to reflect your device.
18177  This might even improve performance for smaller devices as unneccesary
18178  BANKSELs migth be removed.
18179 \layout Subsection
18180
18181 Known bugs
18182 \layout Subsubsection
18183
18184 initialized data
18185 \layout Standard
18186
18187 Currently, data can only be initialized if it resides in the source file
18188  together with
18189 \emph on
18190 main()
18191 \emph default
18192 .
18193  Data in other source files will silently
18194 \series bold
18195 not
18196 \series default
18197  be initialized.
18198 \family typewriter
18199 \size footnotesize
18200
18201 \begin_inset Marginal
18202 collapsed true
18203
18204 \layout Standard
18205
18206
18207 \series bold
18208 \SpecialChar ~
18209 !
18210 \end_inset
18211
18212
18213 \layout Section
18214 \pagebreak_top
18215 The PIC16
18216 \begin_inset LatexCommand \index{PIC16}
18217
18218 \end_inset
18219
18220  port
18221 \layout Standard
18222
18223 The PIC16
18224 \begin_inset LatexCommand \index{PIC16}
18225
18226 \end_inset
18227
18228  port is the portion of SDCC that is responsible to produce code for the
18229  Microchip
18230 \begin_inset LatexCommand \index{Microchip}
18231
18232 \end_inset
18233
18234 (TM) microcontrollers with 16 bit core.
18235  Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
18236  Currently supported devices are:
18237 \layout Standard
18238 \align center
18239
18240 \begin_inset  Tabular
18241 <lyxtabular version="3" rows="4" columns="6">
18242 <features>
18243 <column alignment="center" valignment="top" leftline="true" width="0">
18244 <column alignment="center" valignment="top" leftline="true" width="0">
18245 <column alignment="center" valignment="top" leftline="true" width="0">
18246 <column alignment="center" valignment="top" leftline="true" width="0">
18247 <column alignment="center" valignment="top" leftline="true" width="0">
18248 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18249 <row topline="true">
18250 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18251 \begin_inset Text
18252
18253 \layout Standard
18254
18255 18F242
18256 \end_inset
18257 </cell>
18258 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18259 \begin_inset Text
18260
18261 \layout Standard
18262
18263 18F248
18264 \end_inset
18265 </cell>
18266 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18267 \begin_inset Text
18268
18269 \layout Standard
18270
18271 18F252
18272 \end_inset
18273 </cell>
18274 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18275 \begin_inset Text
18276
18277 \layout Standard
18278
18279 18F258
18280 \end_inset
18281 </cell>
18282 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18283 \begin_inset Text
18284
18285 \layout Standard
18286
18287 18F442
18288 \end_inset
18289 </cell>
18290 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18291 \begin_inset Text
18292
18293 \layout Standard
18294
18295 18F448
18296 \end_inset
18297 </cell>
18298 </row>
18299 <row topline="true">
18300 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18301 \begin_inset Text
18302
18303 \layout Standard
18304
18305 18F452
18306 \end_inset
18307 </cell>
18308 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18309 \begin_inset Text
18310
18311 \layout Standard
18312
18313 18F458
18314 \end_inset
18315 </cell>
18316 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18317 \begin_inset Text
18318
18319 \layout Standard
18320
18321 18F1220
18322 \end_inset
18323 </cell>
18324 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18325 \begin_inset Text
18326
18327 \layout Standard
18328
18329 18F2220
18330 \end_inset
18331 </cell>
18332 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18333 \begin_inset Text
18334
18335 \layout Standard
18336
18337 18F2550
18338 \end_inset
18339 </cell>
18340 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18341 \begin_inset Text
18342
18343 \layout Standard
18344
18345 18F4331
18346 \end_inset
18347 </cell>
18348 </row>
18349 <row topline="true">
18350 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18351 \begin_inset Text
18352
18353 \layout Standard
18354
18355 18F4455
18356 \end_inset
18357 </cell>
18358 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18359 \begin_inset Text
18360
18361 \layout Standard
18362
18363 18F6520
18364 \end_inset
18365 </cell>
18366 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18367 \begin_inset Text
18368
18369 \layout Standard
18370
18371 18F6620
18372 \end_inset
18373 </cell>
18374 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18375 \begin_inset Text
18376
18377 \layout Standard
18378
18379 18F6680
18380 \end_inset
18381 </cell>
18382 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18383 \begin_inset Text
18384
18385 \layout Standard
18386
18387 18F6720
18388 \end_inset
18389 </cell>
18390 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18391 \begin_inset Text
18392
18393 \layout Standard
18394
18395 18F8520
18396 \end_inset
18397 </cell>
18398 </row>
18399 <row topline="true" bottomline="true">
18400 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18401 \begin_inset Text
18402
18403 \layout Standard
18404
18405 18F8620
18406 \end_inset
18407 </cell>
18408 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18409 \begin_inset Text
18410
18411 \layout Standard
18412
18413 18F8680
18414 \end_inset
18415 </cell>
18416 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18417 \begin_inset Text
18418
18419 \layout Standard
18420
18421 18F8720
18422 \end_inset
18423 </cell>
18424 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18425 \begin_inset Text
18426
18427 \layout Standard
18428
18429 \end_inset
18430 </cell>
18431 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18432 \begin_inset Text
18433
18434 \layout Standard
18435
18436 \end_inset
18437 </cell>
18438 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18439 \begin_inset Text
18440
18441 \layout Standard
18442
18443 \end_inset
18444 </cell>
18445 </row>
18446 </lyxtabular>
18447
18448 \end_inset
18449
18450
18451 \layout Subsection
18452
18453 Global Options
18454 \layout Standard
18455
18456 PIC16 port supports the standard command line arguments as supposed, with
18457  the exception of certain cases that will be mentioned in the following
18458  list:
18459 \layout List
18460 \labelwidthstring 00.00.0000
18461
18462 -
18463 \begin_inset ERT
18464 status Collapsed
18465
18466 \layout Standard
18467
18468 \backslash
18469 /
18470 \end_inset
18471
18472 -callee-saves
18473 \begin_inset LatexCommand \index{PIC16!Options!-\/-callee-saves}
18474
18475 \end_inset
18476
18477  See -
18478 \begin_inset ERT
18479 status Collapsed
18480
18481 \layout Standard
18482
18483 \backslash
18484 /
18485 \end_inset
18486
18487 -all-callee-saves
18488 \layout List
18489 \labelwidthstring 00.00.0000
18490
18491 -
18492 \begin_inset ERT
18493 status Collapsed
18494
18495 \layout Standard
18496
18497 \backslash
18498 /
18499 \end_inset
18500
18501 -all-callee-saves
18502 \begin_inset LatexCommand \index{PIC16!Options!-\/-all-callee-saves}
18503
18504 \end_inset
18505
18506  All function arguments are passed on stack by default.
18507
18508 \emph on
18509 There is no need to specify this in the command line.
18510 \layout List
18511 \labelwidthstring 00.00.0000
18512
18513 -
18514 \begin_inset ERT
18515 status Collapsed
18516
18517 \layout Standard
18518
18519 \backslash
18520 /
18521 \end_inset
18522
18523 -fommit-frame-pointer
18524 \begin_inset LatexCommand \index{PIC16!Options!-\/-fommit-frame-pointer}
18525
18526 \end_inset
18527
18528  Frame pointer will be omitted when the function uses no local variables.
18529 \layout Subsection
18530
18531 Port Specific Options
18532 \begin_inset LatexCommand \index{Options PIC16}
18533
18534 \end_inset
18535
18536
18537 \layout Standard
18538
18539 The port specific options appear after the global options in the sdcc --help
18540  output.
18541 \layout Subsubsection
18542
18543 General Options
18544 \layout Standard
18545
18546 General options enable certain port features and optimizations.
18547 \layout List
18548 \labelwidthstring 00.00.0000
18549
18550 -
18551 \begin_inset ERT
18552 status Collapsed
18553
18554 \layout Standard
18555
18556 \backslash
18557 /
18558 \end_inset
18559
18560 -pstack-model=[model] Used in conjuction with the command above.
18561  Defines the stack model to be used, valid stack models are :
18562 \begin_deeper
18563 \layout List
18564 \labelwidthstring 00.00.0000
18565
18566
18567 \emph on
18568 small
18569 \emph default
18570  Selects small stack model.
18571  8 bit stack and frame pointers.
18572  Supports 256 bytes stack size.
18573 \layout List
18574 \labelwidthstring 00.00.0000
18575
18576
18577 \emph on
18578 large
18579 \emph default
18580  Selects large stack model.
18581  16 bit stack and frame pointers.
18582  Supports 65536 bytes stack size.
18583 \end_deeper
18584 \layout List
18585 \labelwidthstring 00.00.0000
18586
18587 -
18588 \begin_inset ERT
18589 status Collapsed
18590
18591 \layout Standard
18592
18593 \backslash
18594 /
18595 \end_inset
18596
18597 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
18598  unitialized data variables with [kword].
18599  Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
18600 \layout List
18601 \labelwidthstring 00.00.0000
18602
18603 -
18604 \begin_inset ERT
18605 status Collapsed
18606
18607 \layout Standard
18608
18609 \backslash
18610 /
18611 \end_inset
18612
18613 -ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
18614  Useful for bootloaders.
18615 \layout List
18616 \labelwidthstring 00.00.0000
18617
18618 -
18619 \begin_inset ERT
18620 status Collapsed
18621
18622 \layout Standard
18623
18624 \backslash
18625 /
18626 \end_inset
18627
18628 -asm= sets the full path and name of an external assembler to call.
18629 \layout List
18630 \labelwidthstring 00.00.0000
18631
18632 -
18633 \begin_inset ERT
18634 status Collapsed
18635
18636 \layout Standard
18637
18638 \backslash
18639 /
18640 \end_inset
18641
18642 -link= sets the full path and name of an external linker to call.
18643 \layout List
18644 \labelwidthstring 00.00.0000
18645
18646 -
18647 \begin_inset ERT
18648 status Collapsed
18649
18650 \layout Standard
18651
18652 \backslash
18653 /
18654 \end_inset
18655
18656 -mplab-comp MPLAB
18657 \begin_inset LatexCommand \index{PIC16!MPLAB}
18658
18659 \end_inset
18660
18661  compatibility option.
18662  Currently only suppresses special gpasm directives.
18663 \layout Subsubsection
18664
18665 Optimization Options
18666 \layout List
18667 \labelwidthstring 00.00.0000
18668
18669 -
18670 \begin_inset ERT
18671 status Collapsed
18672
18673 \layout Standard
18674
18675 \backslash
18676 /
18677 \end_inset
18678
18679 -optimize-goto Try to use (conditional) BRA instead of GOTO
18680 \layout List
18681 \labelwidthstring 00.00.0000
18682
18683 -
18684 \begin_inset ERT
18685 status Collapsed
18686
18687 \layout Standard
18688
18689 \backslash
18690 /
18691 \end_inset
18692
18693 -optimize-cmp Try to optimize some compares.
18694 \layout List
18695 \labelwidthstring 00.00.0000
18696
18697 -
18698 \begin_inset ERT
18699 status Collapsed
18700
18701 \layout Standard
18702
18703 \backslash
18704 /
18705 \end_inset
18706
18707 -optimize-df Analyze the dataflow of the generated code and improve it.
18708 \layout List
18709 \labelwidthstring 00.00.0000
18710
18711 -
18712 \begin_inset ERT
18713 status Collapsed
18714
18715 \layout Standard
18716
18717 \backslash
18718 /
18719 \end_inset
18720
18721 -obanksel=nn Set optimization level for inserting BANKSELs.
18722 \newline
18723
18724 \begin_deeper
18725 \layout List
18726 \labelwidthstring 00.00.0000
18727
18728 0 no optimization
18729 \layout List
18730 \labelwidthstring 00.00.0000
18731
18732 1 checks previous used register and if it is the same then does not emit
18733  BANKSEL, accounts only for labels.
18734 \layout List
18735 \labelwidthstring 00.00.0000
18736
18737 2 tries to check the location of (even different) symbols and removes BANKSELs
18738  if they are in the same bank.
18739
18740 \newline
18741
18742 \emph on
18743 Important: There might be problems if the linker script has data sections
18744  across bank borders!
18745 \end_deeper
18746 \layout Subsubsection
18747
18748 Linking Options
18749 \layout List
18750 \labelwidthstring 00.00.0000
18751
18752 -
18753 \begin_inset ERT
18754 status Collapsed
18755
18756 \layout Standard
18757
18758 \backslash
18759 /
18760 \end_inset
18761
18762 -nodefaultlibs do not link default libraries when linking
18763 \layout List
18764 \labelwidthstring 00.00.0000
18765
18766 -
18767 \begin_inset ERT
18768 status Collapsed
18769
18770 \layout Standard
18771
18772 \backslash
18773 /
18774 \end_inset
18775
18776 -no-crt Don't link the default run-time modules
18777 \layout List
18778 \labelwidthstring 00.00.0000
18779
18780 -
18781 \begin_inset ERT
18782 status Collapsed
18783
18784 \layout Standard
18785
18786 \backslash
18787 /
18788 \end_inset
18789
18790 -use-crt= Use a custom run-time module instead of the defaults.
18791 \layout Subsubsection
18792
18793 Debugging Options
18794 \layout Standard
18795
18796 Debugging options enable extra debugging information in the output files.
18797 \layout List
18798 \labelwidthstring 00.00.0000
18799
18800 -
18801 \begin_inset ERT
18802 status Collapsed
18803
18804 \layout Standard
18805
18806 \backslash
18807 /
18808 \end_inset
18809
18810 -debug-xtra Similar to -
18811 \begin_inset ERT
18812 status Collapsed
18813
18814 \layout Standard
18815
18816 \backslash
18817 /
18818 \end_inset
18819
18820 -debug
18821 \begin_inset LatexCommand \index{-\/-debug}
18822
18823 \end_inset
18824
18825 , but dumps more information.
18826 \layout List
18827 \labelwidthstring 00.00.0000
18828
18829 -
18830 \begin_inset ERT
18831 status Collapsed
18832
18833 \layout Standard
18834
18835 \backslash
18836 /
18837 \end_inset
18838
18839 -debug-ralloc Force register allocator to dump <source>.d file with debugging
18840  information.
18841  <source> is the name of the file compiled.
18842 \layout List
18843 \labelwidthstring 00.00.0000
18844
18845 -
18846 \begin_inset ERT
18847 status Collapsed
18848
18849 \layout Standard
18850
18851 \backslash
18852 /
18853 \end_inset
18854
18855 -pcode-verbose Enable pcode debugging information in translation.
18856 \layout List
18857 \labelwidthstring 00.00.0000
18858
18859 -
18860 \begin_inset ERT
18861 status Collapsed
18862
18863 \layout Standard
18864
18865 \backslash
18866 /
18867 \end_inset
18868
18869 -denable-peeps Force the usage of peepholes.
18870  Use with care.
18871 \layout List
18872 \labelwidthstring 00.00.0000
18873
18874 -
18875 \begin_inset ERT
18876 status Collapsed
18877
18878 \layout Standard
18879
18880 \backslash
18881 /
18882 \end_inset
18883
18884 -gstack Trace push/pops for stack pointer overflow
18885 \layout List
18886 \labelwidthstring 00.00.0000
18887
18888 -
18889 \begin_inset ERT
18890 status Collapsed
18891
18892 \layout Standard
18893
18894 \backslash
18895 /
18896 \end_inset
18897
18898 -call-tree dump call tree in .calltree file
18899 \layout Subsection
18900
18901 Enviromental Variables
18902 \layout Standard
18903
18904 There is a number of enviromental variables that can be used when running
18905  SDCC to enable certain optimizations or force a specific program behaviour.
18906  these variables are primarily for debugging purposes so they can be enabled/dis
18907 abled at will.
18908 \layout Standard
18909
18910 Currently there is only two such variables available:
18911 \layout List
18912 \labelwidthstring 00.00.0000
18913
18914 OPTIMIZE_BITFIELD_POINTER_GET when this variable exists reading of structure
18915  bitfields is optimized by directly loading FSR0 with the address of the
18916  bitfield structure.
18917  Normally SDCC will cast the bitfield structure to a bitfield pointer and
18918  then load FSR0.
18919  This step saves data ram and code space for functions that perform heavy
18920  use of bitfields.
18921  (ie.
18922  80 bytes of code space are saved when compiling malloc.c with this option).
18923
18924 \layout List
18925 \labelwidthstring 00.00.0000
18926
18927 NO_REG_OPT do not perform pCode registers optimization.
18928  This should be used for debugging purposes.
18929  In some where bugs in the pcode optimizer are found, users can benefit
18930  from temporarily disabling the optimizer until the bug is fixed.
18931 \layout Subsection
18932
18933 Preprocessor Macros
18934 \layout Standard
18935
18936 PIC16
18937 \begin_inset LatexCommand \index{PIC16}
18938
18939 \end_inset
18940
18941  port defines the following preprocessor macros while translating a source.
18942 \layout Standard
18943 \align center
18944
18945 \begin_inset  Tabular
18946 <lyxtabular version="3" rows="6" columns="2">
18947 <features>
18948 <column alignment="center" valignment="top" leftline="true" width="0">
18949 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18950 <row topline="true" bottomline="true">
18951 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18952 \begin_inset Text
18953
18954 \layout Standard
18955
18956 Macro
18957 \end_inset
18958 </cell>
18959 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18960 \begin_inset Text
18961
18962 \layout Standard
18963
18964 Description
18965 \end_inset
18966 </cell>
18967 </row>
18968 <row topline="true">
18969 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18970 \begin_inset Text
18971
18972 \layout Standard
18973
18974 SDCC_pic16
18975 \end_inset
18976 </cell>
18977 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18978 \begin_inset Text
18979
18980 \layout Standard
18981
18982 Port identification
18983 \end_inset
18984 </cell>
18985 </row>
18986 <row topline="true">
18987 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18988 \begin_inset Text
18989
18990 \layout Standard
18991
18992 _
18993 \begin_inset ERT
18994 status Collapsed
18995
18996 \layout Standard
18997
18998 \backslash
18999 /
19000 \end_inset
19001
19002 _pic16
19003 \end_inset
19004 </cell>
19005 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19006 \begin_inset Text
19007
19008 \layout Standard
19009
19010 Port identification (same as above)
19011 \end_inset
19012 </cell>
19013 </row>
19014 <row topline="true">
19015 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19016 \begin_inset Text
19017
19018 \layout Standard
19019
19020 pic18fxxxx
19021 \end_inset
19022 </cell>
19023 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19024 \begin_inset Text
19025
19026 \layout Standard
19027
19028 MCU Identification.
19029
19030 \emph on
19031 xxxx
19032 \emph default
19033  is the microcontrol identification number, i.e.
19034  452, 6620, etc
19035 \end_inset
19036 </cell>
19037 </row>
19038 <row topline="true">
19039 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19040 \begin_inset Text
19041
19042 \layout Standard
19043
19044 _
19045 \begin_inset ERT
19046 status Collapsed
19047
19048 \layout Standard
19049
19050 \backslash
19051 /
19052 \end_inset
19053
19054 _18Fxxxx
19055 \end_inset
19056 </cell>
19057 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19058 \begin_inset Text
19059
19060 \layout Standard
19061
19062 MCU Identification (same as above)
19063 \end_inset
19064 </cell>
19065 </row>
19066 <row topline="true" bottomline="true">
19067 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19068 \begin_inset Text
19069
19070 \layout Standard
19071
19072 STACK_MODEL_nnn
19073 \end_inset
19074 </cell>
19075 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19076 \begin_inset Text
19077
19078 \layout Standard
19079
19080 nnn = SMALL or LARGE respectively according to the stack model used
19081 \end_inset
19082 </cell>
19083 </row>
19084 </lyxtabular>
19085
19086 \end_inset
19087
19088
19089 \layout Standard
19090
19091 In addition the following macros are defined when calling assembler:
19092 \layout Standard
19093 \align center
19094
19095 \begin_inset  Tabular
19096 <lyxtabular version="3" rows="4" columns="2">
19097 <features>
19098 <column alignment="center" valignment="top" leftline="true" width="0">
19099 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19100 <row topline="true" bottomline="true">
19101 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19102 \begin_inset Text
19103
19104 \layout Standard
19105
19106 Macro
19107 \end_inset
19108 </cell>
19109 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19110 \begin_inset Text
19111
19112 \layout Standard
19113
19114 Description
19115 \end_inset
19116 </cell>
19117 </row>
19118 <row topline="true">
19119 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19120 \begin_inset Text
19121
19122 \layout Standard
19123
19124 __18Fxxxx
19125 \end_inset
19126 </cell>
19127 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19128 \begin_inset Text
19129
19130 \layout Standard
19131
19132 MCU Identification.
19133
19134 \emph on
19135 xxxx
19136 \emph default
19137  is the microcontrol identification number, i.e.
19138  452, 6620, etc
19139 \end_inset
19140 </cell>
19141 </row>
19142 <row topline="true">
19143 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19144 \begin_inset Text
19145
19146 \layout Standard
19147
19148 SDCC_MODEL_nnn
19149 \end_inset
19150 </cell>
19151 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19152 \begin_inset Text
19153
19154 \layout Standard
19155
19156 nnn = SMALL or LARGE respectively according to the memory model used for
19157  SDCC
19158 \end_inset
19159 </cell>
19160 </row>
19161 <row topline="true" bottomline="true">
19162 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19163 \begin_inset Text
19164
19165 \layout Standard
19166
19167 STACK_MODEL_nnn
19168 \end_inset
19169 </cell>
19170 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19171 \begin_inset Text
19172
19173 \layout Standard
19174
19175 nnn = SMALL or LARGE respectively according to the stack model used
19176 \end_inset
19177 </cell>
19178 </row>
19179 </lyxtabular>
19180
19181 \end_inset
19182
19183
19184 \layout Subsection
19185
19186 Directories
19187 \layout Standard
19188
19189 PIC16
19190 \begin_inset LatexCommand \index{PIC16}
19191
19192 \end_inset
19193
19194  port uses the following directories for searching header files and libraries.
19195 \layout Standard
19196 \align center
19197
19198 \begin_inset  Tabular
19199 <lyxtabular version="3" rows="3" columns="4">
19200 <features>
19201 <column alignment="center" valignment="top" leftline="true" width="0">
19202 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19203 <column alignment="center" valignment="top" width="0">
19204 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19205 <row topline="true" bottomline="true">
19206 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19207 \begin_inset Text
19208
19209 \layout Standard
19210
19211 Directory
19212 \end_inset
19213 </cell>
19214 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19215 \begin_inset Text
19216
19217 \layout Standard
19218
19219 Description
19220 \end_inset
19221 </cell>
19222 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19223 \begin_inset Text
19224
19225 \layout Standard
19226
19227 Target
19228 \end_inset
19229 </cell>
19230 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19231 \begin_inset Text
19232
19233 \layout Standard
19234
19235 Command prefix
19236 \end_inset
19237 </cell>
19238 </row>
19239 <row topline="true">
19240 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19241 \begin_inset Text
19242
19243 \layout Standard
19244
19245 PREFIX/sdcc/include/pic16
19246 \end_inset
19247 </cell>
19248 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19249 \begin_inset Text
19250
19251 \layout Standard
19252
19253 PIC16 specific headers
19254 \end_inset
19255 </cell>
19256 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19257 \begin_inset Text
19258
19259 \layout Standard
19260
19261 Compiler
19262 \end_inset
19263 </cell>
19264 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19265 \begin_inset Text
19266
19267 \layout Standard
19268
19269 -I
19270 \end_inset
19271 </cell>
19272 </row>
19273 <row topline="true" bottomline="true">
19274 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19275 \begin_inset Text
19276
19277 \layout Standard
19278
19279 PREFIX/sdcc/lib/pic16
19280 \end_inset
19281 </cell>
19282 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19283 \begin_inset Text
19284
19285 \layout Standard
19286
19287 PIC16 specific libraries
19288 \end_inset
19289 </cell>
19290 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19291 \begin_inset Text
19292
19293 \layout Standard
19294
19295 Linker
19296 \end_inset
19297 </cell>
19298 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19299 \begin_inset Text
19300
19301 \layout Standard
19302
19303 -L
19304 \end_inset
19305 </cell>
19306 </row>
19307 </lyxtabular>
19308
19309 \end_inset
19310
19311
19312 \layout Subsection
19313
19314 Pragmas
19315 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
19316
19317 \end_inset
19318
19319
19320 \layout Standard
19321
19322 PIC16
19323 \begin_inset LatexCommand \index{PIC16}
19324
19325 \end_inset
19326
19327  port currently supports the following pragmas:
19328 \layout List
19329 \labelwidthstring 00.00.0000
19330
19331 stack
19332 \begin_inset LatexCommand \index{PIC16!Pragmas!\#pragma stack}
19333
19334 \end_inset
19335
19336  pragma stack
19337 \begin_inset LatexCommand \index{PIC16!stack}
19338
19339 \end_inset
19340
19341  forces the code generator to initialize the stack & frame pointers at a
19342  specific address.
19343  This is an adhoc solution for cases where no STACK directive is available
19344  in the linker script or gplink is not instructed to create a stack section.
19345 \newline
19346 The stack pragma should be used only once in a project.
19347  Multiple pragmas may result in indeterminate behaviour of the program.
19348 \begin_inset Foot
19349 collapsed false
19350
19351 \layout Standard
19352
19353 The old format (ie.
19354  #pragma stack 0x5ff) is deprecated and will cause the stack pointer to
19355  cross page boundaries (or even exceed the available data RAM) and crash
19356  the program.
19357  Make sure that stack does not cross page boundaries when using the SMALL
19358  stack model.
19359 \end_inset
19360
19361
19362 \newline
19363 The format is as follows:
19364 \layout LyX-Code
19365
19366 #pragma stack bottom_address [stack_size]
19367 \layout Standard
19368
19369
19370 \emph on
19371 bottom_address
19372 \emph default
19373  is the lower bound of the stack section.
19374  The stack pointer initially will point at address (bottom_address+stack_size-1).
19375 \layout LyX-Code
19376
19377 Example:
19378 \layout LyX-Code
19379
19380 \layout LyX-Code
19381
19382 /* initializes stack of 100 bytes at RAM address 0x200 */
19383 \layout LyX-Code
19384
19385 #pragma stack 0x200 100
19386 \layout Standard
19387
19388 If the stack_size field is omitted then a stack is created with the default
19389  size of 64.
19390  This size might be enough for most programs, but its not enough for operations
19391  with deep function nesting or excessive stack usage.
19392 \layout List
19393 \labelwidthstring 00.00.0000
19394
19395 code
19396 \begin_inset LatexCommand \index{PIC16!Pragmas!\#pragma code}
19397
19398 \end_inset
19399
19400  place a function symbol at static FLASH address
19401 \layout LyX-Code
19402
19403 Example:
19404 \layout LyX-Code
19405
19406 \layout LyX-Code
19407
19408 /* place function test_func at 0x4000 */
19409 \layout LyX-Code
19410
19411 #pragma code test_func 0x4000
19412 \layout LyX-Code
19413
19414 \layout List
19415 \labelwidthstring 00.00.0000
19416
19417 library instructs the linker to use a library module.
19418 \newline
19419 Usage:
19420 \layout LyX-Code
19421
19422 #pragma library module_name
19423 \layout Standard
19424
19425
19426 \emph on
19427 module_name
19428 \emph default
19429  can be any library or object file (including its path).
19430  Note that there are four reserved keywords which have special meaning.
19431  These are:
19432 \layout Standard
19433 \align center
19434
19435 \begin_inset  Tabular
19436 <lyxtabular version="3" rows="6" columns="3">
19437 <features>
19438 <column alignment="center" valignment="top" leftline="true" width="0">
19439 <column alignment="block" valignment="top" leftline="true" width="20page%">
19440 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
19441 <row topline="true" bottomline="true">
19442 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19443 \begin_inset Text
19444
19445 \layout Standard
19446
19447 Keyword
19448 \end_inset
19449 </cell>
19450 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19451 \begin_inset Text
19452
19453 \layout Standard
19454
19455 Description
19456 \end_inset
19457 </cell>
19458 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19459 \begin_inset Text
19460
19461 \layout Standard
19462
19463 Module to link
19464 \end_inset
19465 </cell>
19466 </row>
19467 <row topline="true">
19468 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19469 \begin_inset Text
19470
19471 \layout Standard
19472
19473
19474 \series bold
19475 ignore
19476 \end_inset
19477 </cell>
19478 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19479 \begin_inset Text
19480
19481 \layout Standard
19482
19483 ignore all library pragmas
19484 \end_inset
19485 </cell>
19486 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19487 \begin_inset Text
19488
19489 \layout Standard
19490
19491
19492 \emph on
19493 (none)
19494 \end_inset
19495 </cell>
19496 </row>
19497 <row topline="true">
19498 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19499 \begin_inset Text
19500
19501 \layout Standard
19502
19503
19504 \series bold
19505 c
19506 \end_inset
19507 </cell>
19508 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19509 \begin_inset Text
19510
19511 \layout Standard
19512
19513 link the C library
19514 \end_inset
19515 </cell>
19516 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19517 \begin_inset Text
19518
19519 \layout Standard
19520
19521
19522 \emph on
19523 libc18f
19524 \emph default
19525 .lib
19526 \end_inset
19527 </cell>
19528 </row>
19529 <row topline="true">
19530 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19531 \begin_inset Text
19532
19533 \layout Standard
19534
19535
19536 \series bold
19537 math
19538 \end_inset
19539 </cell>
19540 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19541 \begin_inset Text
19542
19543 \layout Standard
19544
19545 link the Math libarary
19546 \end_inset
19547 </cell>
19548 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19549 \begin_inset Text
19550
19551 \layout Standard
19552
19553
19554 \emph on
19555 libm18f
19556 \emph default
19557 .lib
19558 \end_inset
19559 </cell>
19560 </row>
19561 <row topline="true">
19562 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19563 \begin_inset Text
19564
19565 \layout Standard
19566
19567
19568 \series bold
19569 io
19570 \end_inset
19571 </cell>
19572 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19573 \begin_inset Text
19574
19575 \layout Standard
19576
19577 link the I/O library
19578 \end_inset
19579 </cell>
19580 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19581 \begin_inset Text
19582
19583 \layout Standard
19584
19585
19586 \emph on
19587 libio18f*
19588 \emph default
19589 .lib
19590 \end_inset
19591 </cell>
19592 </row>
19593 <row topline="true" bottomline="true">
19594 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19595 \begin_inset Text
19596
19597 \layout Standard
19598
19599
19600 \series bold
19601 debug
19602 \end_inset
19603 </cell>
19604 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19605 \begin_inset Text
19606
19607 \layout Standard
19608
19609 link the debug library
19610 \end_inset
19611 </cell>
19612 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19613 \begin_inset Text
19614
19615 \layout Standard
19616
19617
19618 \emph on
19619 libdebug
19620 \emph default
19621 .lib
19622 \end_inset
19623 </cell>
19624 </row>
19625 </lyxtabular>
19626
19627 \end_inset
19628
19629
19630 \newline
19631 * is the device number, i.e.
19632  452 for PIC18F452 MCU.
19633 \layout Standard
19634
19635 This feature allows for linking with specific libraries withoug having to
19636  explicit name them in the command line.
19637  Note that the
19638 \noun on
19639 ignore
19640 \noun default
19641  keyword will reject all modules specified by the library pragma.
19642 \layout List
19643 \labelwidthstring 00.00.0000
19644
19645 udata pragma udata instructs the compiler to emit code so that linker will
19646  place a variable at a specific memory bank
19647 \layout LyX-Code
19648
19649 Example:
19650 \layout LyX-Code
19651
19652 \layout LyX-Code
19653
19654 /* places variable foo at bank2 */
19655 \layout LyX-Code
19656
19657 #pragma udata bank2 foo
19658 \layout LyX-Code
19659
19660 char foo;
19661 \layout Standard
19662
19663 In order for this pragma to work extra SECTION directives should be added
19664  in the .lkr script.
19665  In the following example a sample .lkr file is shown:
19666 \layout LyX-Code
19667
19668 \layout LyX-Code
19669
19670 // Sample linker script for the PIC18F452 processor
19671 \layout LyX-Code
19672
19673 LIBPATH .
19674 \layout LyX-Code
19675
19676 CODEPAGE   NAME=vectors    START=0x0            END=0x29           PROTECTED
19677 \layout LyX-Code
19678
19679 CODEPAGE   NAME=page       START=0x2A           END=0x7FFF
19680 \layout LyX-Code
19681
19682 CODEPAGE   NAME=idlocs     START=0x200000       END=0x200007       PROTECTED
19683 \layout LyX-Code
19684
19685 CODEPAGE   NAME=config     START=0x300000       END=0x30000D       PROTECTED
19686 \layout LyX-Code
19687
19688 CODEPAGE   NAME=devid      START=0x3FFFFE       END=0x3FFFFF       PROTECTED
19689 \layout LyX-Code
19690
19691 CODEPAGE   NAME=eedata     START=0xF00000       END=0xF000FF       PROTECTED
19692 \layout LyX-Code
19693
19694 ACCESSBANK NAME=accessram  START=0x0            END=0x7F
19695 \layout LyX-Code
19696
19697 \layout LyX-Code
19698
19699 DATABANK   NAME=gpr0       START=0x80           END=0xFF
19700 \layout LyX-Code
19701
19702 DATABANK   NAME=gpr1       START=0x100          END=0x1FF
19703 \layout LyX-Code
19704
19705 DATABANK   NAME=gpr2       START=0x200          END=0x2FF
19706 \layout LyX-Code
19707
19708 DATABANK   NAME=gpr3       START=0x300          END=0x3FF
19709 \layout LyX-Code
19710
19711 DATABANK   NAME=gpr4       START=0x400          END=0x4FF
19712 \layout LyX-Code
19713
19714 DATABANK   NAME=gpr5       START=0x500          END=0x5FF
19715 \layout LyX-Code
19716
19717 ACCESSBANK NAME=accesssfr  START=0xF80          END=0xFFF          PROTECTED
19718 \layout LyX-Code
19719
19720 \layout LyX-Code
19721
19722 SECTION    NAME=CONFIG     ROM=config
19723 \layout LyX-Code
19724
19725 \layout LyX-Code
19726
19727 SECTION    NAME=bank0      RAM=gpr0       # these SECTION directives
19728 \layout LyX-Code
19729
19730 SECTION    NAME=bank1      RAM=gpr1       # should be added to link
19731 \layout LyX-Code
19732
19733 SECTION    NAME=bank2      RAM=gpr2       # section name 'bank?' with
19734 \layout LyX-Code
19735
19736 SECTION    NAME=bank3      RAM=gpr3       # a specific DATABANK name
19737 \layout LyX-Code
19738
19739 SECTION    NAME=bank4      RAM=gpr4
19740 \layout LyX-Code
19741
19742 SECTION    NAME=bank5      RAM=gpr5
19743 \layout Standard
19744
19745 The linker will recognise the section name set in the pragma statement and
19746  will position the variable at the memory bank set with the RAM field at
19747  the SECTION line in the linker script file.
19748 \layout Subsection
19749
19750 Header Files
19751 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
19752
19753 \end_inset
19754
19755
19756 \layout Standard
19757
19758 There is one main header file
19759 \begin_inset LatexCommand \index{PIC16!Header files}
19760
19761 \end_inset
19762
19763  that can be included to the source files using the pic16
19764 \begin_inset LatexCommand \index{PIC16}
19765
19766 \end_inset
19767
19768  port.
19769  That file is the
19770 \series bold
19771 pic18fregs.h
19772 \series default
19773 .
19774  This header file contains the definitions for the processor special registers,
19775  so it is necessary if the source accesses them.
19776  It can be included by adding the following line in the beginning of the
19777  file:
19778 \layout LyX-Code
19779
19780 #include <pic18fregs.h>
19781 \layout Standard
19782
19783 The specific microcontroller is selected within the pic18fregs.h automatically,
19784  so the same source can be used with a variety of devices.
19785 \layout Subsection
19786
19787 Libraries
19788 \layout Standard
19789
19790 The libraries
19791 \begin_inset LatexCommand \index{PIC16!Libraries}
19792
19793 \end_inset
19794
19795  that PIC16
19796 \begin_inset LatexCommand \index{PIC16}
19797
19798 \end_inset
19799
19800  port depends on are the microcontroller device libraries which contain
19801  the symbol definitions for the microcontroller special function registers.
19802  These libraries have the format pic18fxxxx.lib, where
19803 \emph on
19804 xxxx
19805 \emph default
19806  is the microcontroller identification number.
19807  The specific library is selected automatically by the compiler at link
19808  stage according to the selected device.
19809 \layout Standard
19810
19811 Libraries are created with gplib which is part of the gputils package
19812 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
19813
19814 \end_inset
19815
19816 .
19817 \layout Subsubsection*
19818
19819 Building the libraries
19820 \layout Standard
19821
19822 Before using SDCC/pic16 there are some libraries that need to be compiled.
19823  This process is not done automatically by SDCC since not all users use
19824  SDCC for pic16 projects.
19825  So each user should compile the libraries separately.
19826 \layout Standard
19827
19828 The steps to compile the pic16 libraries under Linux are:
19829 \layout LyX-Code
19830
19831 cd device/lib/pic16
19832 \layout LyX-Code
19833
19834 ./configure
19835 \layout LyX-Code
19836
19837 make
19838 \layout LyX-Code
19839
19840 cd ..
19841 \layout LyX-Code
19842
19843 make model-pic16
19844 \layout LyX-Code
19845
19846 su -c 'make install'     # install the libraries, you need the root password
19847 \layout Standard
19848
19849 If you need to install the headers too, do:
19850 \layout LyX-Code
19851
19852 cd device/include
19853 \layout LyX-Code
19854
19855 su -c 'make install'     # install the headers, you need the root password
19856 \layout Standard
19857
19858 There exist a special target to build the I/O libraries.
19859  This target is not automatically build because it will build the I/O library
19860  for
19861 \emph on
19862 every
19863 \emph default
19864  supported device.
19865  This way building will take quite a lot of time.
19866  Users are advised to edit the
19867 \series bold
19868 device/lib/pic16/pics.build
19869 \series default
19870  file and then execute:
19871 \layout LyX-Code
19872
19873 make lib-io
19874 \layout Subsection
19875
19876 Memory Models
19877 \layout Standard
19878
19879 The following memory models are supported by the PIC16 port:
19880 \layout Itemize
19881
19882 small model
19883 \layout Itemize
19884
19885 large model
19886 \layout Standard
19887
19888 Memory model affects the default size of pointers within the source.
19889  The sizes are shown in the next table:
19890 \layout Standard
19891 \align center
19892
19893 \begin_inset  Tabular
19894 <lyxtabular version="3" rows="3" columns="3">
19895 <features>
19896 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19897 <column alignment="center" valignment="top" leftline="true" width="0">
19898 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19899 <row topline="true" bottomline="true">
19900 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19901 \begin_inset Text
19902
19903 \layout Standard
19904
19905 Pointer sizes according to memory model
19906 \end_inset
19907 </cell>
19908 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19909 \begin_inset Text
19910
19911 \layout Standard
19912
19913 small model
19914 \end_inset
19915 </cell>
19916 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19917 \begin_inset Text
19918
19919 \layout Standard
19920
19921 large model
19922 \end_inset
19923 </cell>
19924 </row>
19925 <row topline="true" bottomline="true">
19926 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19927 \begin_inset Text
19928
19929 \layout Standard
19930
19931 code pointers
19932 \end_inset
19933 </cell>
19934 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19935 \begin_inset Text
19936
19937 \layout Standard
19938
19939 16-bits
19940 \end_inset
19941 </cell>
19942 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19943 \begin_inset Text
19944
19945 \layout Standard
19946
19947 24-bits
19948 \end_inset
19949 </cell>
19950 </row>
19951 <row topline="true" bottomline="true">
19952 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19953 \begin_inset Text
19954
19955 \layout Standard
19956
19957 data pointers
19958 \end_inset
19959 </cell>
19960 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
19961 \begin_inset Text
19962
19963 \layout Standard
19964
19965 16-bits
19966 \end_inset
19967 </cell>
19968 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19969 \begin_inset Text
19970
19971 \layout Standard
19972
19973 16-bits
19974 \end_inset
19975 </cell>
19976 </row>
19977 </lyxtabular>
19978
19979 \end_inset
19980
19981
19982 \layout Standard
19983
19984 It is advisable that all sources within a project are compiled with the
19985  same memory model.
19986  If one wants to override the default memory model, this can be done by
19987  declaring a pointer as
19988 \series bold
19989 far
19990 \series default
19991  or
19992 \series bold
19993 near
19994 \series default
19995 .
19996  Far selects large memory model's pointers, while near selects small memory
19997  model's pointers.
19998 \layout Standard
19999
20000 The standard device libraries (see
20001 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
20002
20003 \end_inset
20004
20005 ) contain no reference to pointers, so they can be used with both memory
20006  models.
20007 \layout Subsection
20008
20009 Stack
20010 \layout Standard
20011
20012 The stack
20013 \begin_inset LatexCommand \index{PIC16!stack}
20014
20015 \end_inset
20016
20017  implementation for the PIC16 port uses two indirect registers, FSR1 and
20018  FSR2.
20019 \layout List
20020 \labelwidthstring 00.00.0000
20021
20022 FSR1 is assigned as stack pointer
20023 \layout List
20024 \labelwidthstring 00.00.0000
20025
20026 FSR2 is assigned as frame pointer
20027 \layout Standard
20028
20029 The following stack models are supported by the PIC16 port
20030 \layout Itemize
20031
20032
20033 \noun on
20034 small
20035 \noun default
20036  model
20037 \layout Itemize
20038
20039
20040 \noun on
20041 large
20042 \noun default
20043  model
20044 \layout Standard
20045
20046
20047 \noun on
20048 Small
20049 \noun default
20050  model means that only the FSRxL byte is used to access stack and frame,
20051  while
20052 \emph on
20053 \noun on
20054 large
20055 \emph default
20056 \noun default
20057  uses both FSRxL and FSRxH registers.
20058  The following table shows the stack/frame pointers sizes according to stack
20059  model and the maximum space they can address:
20060 \layout Standard
20061 \align center
20062
20063 \begin_inset  Tabular
20064 <lyxtabular version="3" rows="3" columns="3">
20065 <features>
20066 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20067 <column alignment="center" valignment="top" leftline="true" width="0">
20068 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20069 <row topline="true" bottomline="true">
20070 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20071 \begin_inset Text
20072
20073 \layout Standard
20074
20075 Stack & Frame pointer sizes according to stack model
20076 \end_inset
20077 </cell>
20078 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20079 \begin_inset Text
20080
20081 \layout Standard
20082
20083 small
20084 \end_inset
20085 </cell>
20086 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20087 \begin_inset Text
20088
20089 \layout Standard
20090
20091 large
20092 \end_inset
20093 </cell>
20094 </row>
20095 <row topline="true">
20096 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20097 \begin_inset Text
20098
20099 \layout Standard
20100
20101 Stack pointer FSR1
20102 \end_inset
20103 </cell>
20104 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20105 \begin_inset Text
20106
20107 \layout Standard
20108
20109 8-bits
20110 \end_inset
20111 </cell>
20112 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20113 \begin_inset Text
20114
20115 \layout Standard
20116
20117 16-bits
20118 \end_inset
20119 </cell>
20120 </row>
20121 <row topline="true" bottomline="true">
20122 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20123 \begin_inset Text
20124
20125 \layout Standard
20126
20127 Frame pointer FSR2
20128 \end_inset
20129 </cell>
20130 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20131 \begin_inset Text
20132
20133 \layout Standard
20134
20135 8-bits
20136 \end_inset
20137 </cell>
20138 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20139 \begin_inset Text
20140
20141 \layout Standard
20142
20143 16-bits
20144 \end_inset
20145 </cell>
20146 </row>
20147 </lyxtabular>
20148
20149 \end_inset
20150
20151
20152 \layout Standard
20153
20154
20155 \noun on
20156 Large
20157 \noun default
20158 stack model is currently not working properly throughout the code generator.
20159  So its use is not advised.
20160  Also there are some other points that need special care:
20161 \newline
20162
20163 \layout Enumerate
20164
20165 Do not create stack sections with size more than one physical bank (that
20166  is 256 bytes)
20167 \layout Enumerate
20168
20169 Stack sections should no cross physical bank limits (i.e.
20170  #pragma stack 0x50 0x100)
20171 \layout Standard
20172
20173 These limitations are caused by the fact that only FSRxL is modified when
20174  using SMALL stack model, so no more than 256 bytes of stack can be used.
20175  This problem will disappear after LARGE model is fully implemented.
20176 \layout Subsection
20177
20178 Functions
20179 \layout Standard
20180
20181 In addition to the standard SDCC function keywords, PIC16
20182 \begin_inset LatexCommand \index{PIC16}
20183
20184 \end_inset
20185
20186  port makes available two more:
20187 \layout List
20188 \labelwidthstring 00.00.0000
20189
20190 wparam
20191 \begin_inset LatexCommand \index{PIC16!wparam}
20192
20193 \end_inset
20194
20195  Use the WREG to pass one byte of the first function argument.
20196  This improves speed but you may not use this for functions with arguments
20197  that are called via function pointers, otherwise the first byte of the
20198  first parameter will get lost.
20199  Usage:
20200 \layout LyX-Code
20201
20202 void func_wparam(int a) wparam
20203 \layout LyX-Code
20204
20205 {
20206 \layout LyX-Code
20207
20208     /* WREG hold the lower part of a */
20209 \layout LyX-Code
20210
20211     /* the high part of a is stored in FSR2+2 (or +3 for large stack model)
20212  */
20213 \layout LyX-Code
20214
20215 ...
20216 \layout LyX-Code
20217
20218 }
20219 \layout List
20220 \labelwidthstring 00.00.0000
20221
20222 shadowregs
20223 \begin_inset LatexCommand \index{PIC16!shadowregs}
20224
20225 \end_inset
20226
20227  When entering/exiting an ISR, it is possible to take advantage of the PIC18F
20228  hardware shadow registers which hold the values of WREG, STATUS and BSR
20229  registers.
20230  This can be done by adding the keyword
20231 \emph on
20232 shadowregs
20233 \emph default
20234  before the
20235 \emph on
20236 interrupt
20237 \emph default
20238  keyword in the function's header.
20239 \layout LyX-Code
20240
20241 void isr_shadow(void) shadowregs interrupt 1
20242 \layout LyX-Code
20243
20244 {
20245 \layout LyX-Code
20246
20247 ...
20248 \layout LyX-Code
20249
20250 }
20251 \layout Standard
20252
20253
20254 \emph on
20255 shadowregs
20256 \emph default
20257  instructs the code generator not to store/restore WREG, STATUS, BSR when
20258  entering/exiting the ISR.
20259 \layout Subsection
20260
20261 Function return values
20262 \layout Standard
20263
20264 Return values from functions are placed to the appropriate registers following
20265  a modified Microchip policy optimized for SDCC.
20266  The following table shows these registers:
20267 \layout Standard
20268 \align center
20269
20270 \begin_inset  Tabular
20271 <lyxtabular version="3" rows="6" columns="2">
20272 <features>
20273 <column alignment="center" valignment="top" leftline="true" width="0">
20274 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20275 <row topline="true" bottomline="true">
20276 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20277 \begin_inset Text
20278
20279 \layout Standard
20280
20281 size
20282 \end_inset
20283 </cell>
20284 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20285 \begin_inset Text
20286
20287 \layout Standard
20288
20289 destination register
20290 \end_inset
20291 </cell>
20292 </row>
20293 <row topline="true">
20294 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20295 \begin_inset Text
20296
20297 \layout Standard
20298
20299 8 bits
20300 \end_inset
20301 </cell>
20302 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20303 \begin_inset Text
20304
20305 \layout Standard
20306
20307 WREG
20308 \end_inset
20309 </cell>
20310 </row>
20311 <row topline="true">
20312 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20313 \begin_inset Text
20314
20315 \layout Standard
20316
20317 16 bits
20318 \end_inset
20319 </cell>
20320 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20321 \begin_inset Text
20322
20323 \layout Standard
20324
20325 PRODL:WREG
20326 \end_inset
20327 </cell>
20328 </row>
20329 <row topline="true">
20330 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20331 \begin_inset Text
20332
20333 \layout Standard
20334
20335 24 bits
20336 \end_inset
20337 </cell>
20338 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20339 \begin_inset Text
20340
20341 \layout Standard
20342
20343 PRODH:PRODL:WREG
20344 \end_inset
20345 </cell>
20346 </row>
20347 <row topline="true">
20348 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20349 \begin_inset Text
20350
20351 \layout Standard
20352
20353 32 bits
20354 \end_inset
20355 </cell>
20356 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20357 \begin_inset Text
20358
20359 \layout Standard
20360
20361 FSR0L:PRODH:PRODL:WREG
20362 \end_inset
20363 </cell>
20364 </row>
20365 <row topline="true" bottomline="true">
20366 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20367 \begin_inset Text
20368
20369 \layout Standard
20370
20371 >32 bits
20372 \end_inset
20373 </cell>
20374 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20375 \begin_inset Text
20376
20377 \layout Standard
20378
20379 on stack, FSR0 points to the beginning
20380 \end_inset
20381 </cell>
20382 </row>
20383 </lyxtabular>
20384
20385 \end_inset
20386
20387
20388 \layout Subsection
20389
20390 Interrupts
20391 \layout Standard
20392
20393 An interrupt
20394 \begin_inset LatexCommand \index{PIC16!interrupt}
20395
20396 \end_inset
20397
20398  service routine (ISR) is declared using the
20399 \emph on
20400 interrupt
20401 \emph default
20402  keyword.
20403 \layout LyX-Code
20404
20405 void isr(void) interrupt
20406 \emph on
20407 n
20408 \layout LyX-Code
20409
20410 {
20411 \layout LyX-Code
20412
20413 ...
20414 \layout LyX-Code
20415
20416 }
20417 \layout Standard
20418
20419
20420 \emph on
20421 n
20422 \emph default
20423  is the interrupt number, which for PIC18F devices can be:
20424 \layout Standard
20425 \align center
20426
20427 \begin_inset  Tabular
20428 <lyxtabular version="3" rows="4" columns="3">
20429 <features>
20430 <column alignment="center" valignment="top" leftline="true" width="0">
20431 <column alignment="center" valignment="top" leftline="true" width="0">
20432 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20433 <row topline="true" bottomline="true">
20434 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20435 \begin_inset Text
20436
20437 \layout Standard
20438
20439
20440 \emph on
20441 n
20442 \end_inset
20443 </cell>
20444 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20445 \begin_inset Text
20446
20447 \layout Standard
20448
20449 Interrupt Vector
20450 \end_inset
20451 </cell>
20452 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20453 \begin_inset Text
20454
20455 \layout Standard
20456
20457 Interrupt Vector Address
20458 \end_inset
20459 </cell>
20460 </row>
20461 <row topline="true">
20462 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20463 \begin_inset Text
20464
20465 \layout Standard
20466
20467 0
20468 \end_inset
20469 </cell>
20470 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20471 \begin_inset Text
20472
20473 \layout Standard
20474
20475 RESET vector
20476 \end_inset
20477 </cell>
20478 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20479 \begin_inset Text
20480
20481 \layout Standard
20482
20483 0x000000
20484 \end_inset
20485 </cell>
20486 </row>
20487 <row topline="true">
20488 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20489 \begin_inset Text
20490
20491 \layout Standard
20492
20493
20494 \family roman
20495 \series medium
20496 \shape up
20497 \size normal
20498 \emph off
20499 \bar no
20500 \noun off
20501 \color none
20502 1
20503 \end_inset
20504 </cell>
20505 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20506 \begin_inset Text
20507
20508 \layout Standard
20509
20510
20511 \family roman
20512 \series medium
20513 \shape up
20514 \size normal
20515 \emph off
20516 \bar no
20517 \noun off
20518 \color none
20519 HIGH priority interrupts
20520 \end_inset
20521 </cell>
20522 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20523 \begin_inset Text
20524
20525 \layout Standard
20526
20527 0x000008
20528 \end_inset
20529 </cell>
20530 </row>
20531 <row topline="true" bottomline="true">
20532 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20533 \begin_inset Text
20534
20535 \layout Standard
20536
20537 2
20538 \end_inset
20539 </cell>
20540 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20541 \begin_inset Text
20542
20543 \layout Standard
20544
20545 LOW priority interrupts
20546 \end_inset
20547 </cell>
20548 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20549 \begin_inset Text
20550
20551 \layout Standard
20552
20553 0x000018
20554 \end_inset
20555 </cell>
20556 </row>
20557 </lyxtabular>
20558
20559 \end_inset
20560
20561
20562 \layout Standard
20563
20564 When generating assembly code for ISR the code generator places a
20565 \noun on
20566 goto
20567 \noun default
20568 instruction at the
20569 \emph on
20570 Interrupt Vector Address
20571 \emph default
20572  which points at the genetated ISR.
20573  This single GOTO instruction is part of an automatically generated
20574 \emph on
20575 interrupt entry point
20576 \emph default
20577  function.
20578  The actuall ISR code is placed as normally would in the code space.
20579  Upon interrupt request, the GOTO instruction is executed which jumps to
20580  the ISR code.
20581  When declaring interrupt functions as _naked this GOTO instruction is
20582 \series bold
20583 not
20584 \series default
20585  generated.
20586  The whole interrupt functions is therefore placed at the Interrupt Vector
20587  Address of the specific interrupt.
20588  This is not a problem for the LOW priority interrupts, but it is a problem
20589  for the RESET and the HIGH priority interrupts because code may be written
20590  at the next interrupt´s vector address and cause undeterminate program
20591  behaviour if that interrupt is raised.
20592 \begin_inset Foot
20593 collapsed false
20594
20595 \layout Standard
20596
20597 This is not a problem when
20598 \layout Enumerate
20599
20600 this is a HIGH interrupt ISR and LOW interrupts are
20601 \emph on
20602 disabled
20603 \emph default
20604  or not used.
20605 \layout Enumerate
20606
20607 when the ISR is small enough not to reach the next interrupt´s vector address.
20608 \end_inset
20609
20610
20611 \layout Standard
20612
20613
20614 \emph on
20615 n
20616 \emph default
20617  is possible to be omitted.
20618  This way a function is generated similar to an ISR, but it is not assigned
20619  to any interrupt.
20620 \layout Standard
20621
20622 When entering an interrupt, currently the PIC16
20623 \begin_inset LatexCommand \index{PIC16}
20624
20625 \end_inset
20626
20627  port automatically saves the following registers:
20628 \layout Itemize
20629
20630 WREG
20631 \layout Itemize
20632
20633 STATUS
20634 \layout Itemize
20635
20636 BSR
20637 \layout Itemize
20638
20639 PROD (PRODL and PRODH)
20640 \layout Itemize
20641
20642 FSR0 (FSR0L and FSR0H)
20643 \layout Standard
20644
20645 These registers are restored upon return from the interrupt routine.
20646 \begin_inset Foot
20647 collapsed false
20648
20649 \layout Standard
20650
20651 NOTE that when the _naked attribute is specified for an interrupt routine,
20652  then NO registers are stored or restored.
20653 \end_inset
20654
20655
20656 \layout Subsection
20657
20658 Generic Pointers
20659 \layout Standard
20660
20661 Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types.
20662  There are 3 types of generic pointers currently implemented data, code
20663  and eeprom pointers.
20664  They are differentiated by the value of the 7th and 6th bits of the upper
20665  byte:
20666 \layout Standard
20667 \align center
20668
20669 \begin_inset  Tabular
20670 <lyxtabular version="3" rows="5" columns="5">
20671 <features>
20672 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20673 <column alignment="center" valignment="top" width="0">
20674 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20675 <column alignment="center" valignment="top" width="0">
20676 <column alignment="left" valignment="top" rightline="true" width="0">
20677 <row topline="true" bottomline="true">
20678 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20679 \begin_inset Text
20680
20681 \layout Standard
20682
20683 pointer type
20684 \end_inset
20685 </cell>
20686 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20687 \begin_inset Text
20688
20689 \layout Standard
20690
20691 7th bit
20692 \end_inset
20693 </cell>
20694 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20695 \begin_inset Text
20696
20697 \layout Standard
20698
20699 6th bit
20700 \end_inset
20701 </cell>
20702 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20703 \begin_inset Text
20704
20705 \layout Standard
20706
20707 rest of the pointer
20708 \end_inset
20709 </cell>
20710 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20711 \begin_inset Text
20712
20713 \layout Standard
20714
20715 description
20716 \end_inset
20717 </cell>
20718 </row>
20719 <row topline="true" bottomline="true">
20720 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20721 \begin_inset Text
20722
20723 \layout Standard
20724
20725 data
20726 \end_inset
20727 </cell>
20728 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20729 \begin_inset Text
20730
20731 \layout Standard
20732
20733 1
20734 \end_inset
20735 </cell>
20736 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20737 \begin_inset Text
20738
20739 \layout Standard
20740
20741 0
20742 \end_inset
20743 </cell>
20744 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20745 \begin_inset Text
20746
20747 \layout Standard
20748
20749
20750 \family typewriter
20751 \shape slanted
20752 \emph on
20753 uuuuuu uuuuxxxx xxxxxxxx
20754 \end_inset
20755 </cell>
20756 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20757 \begin_inset Text
20758
20759 \layout Standard
20760
20761 a 12-bit data pointer in data RAM memory
20762 \end_inset
20763 </cell>
20764 </row>
20765 <row bottomline="true">
20766 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20767 \begin_inset Text
20768
20769 \layout Standard
20770
20771 code
20772 \end_inset
20773 </cell>
20774 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20775 \begin_inset Text
20776
20777 \layout Standard
20778
20779 0
20780 \end_inset
20781 </cell>
20782 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20783 \begin_inset Text
20784
20785 \layout Standard
20786
20787 0
20788 \end_inset
20789 </cell>
20790 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20791 \begin_inset Text
20792
20793 \layout Standard
20794
20795
20796 \family typewriter
20797 \shape slanted
20798 \emph on
20799 uxxxxx xxxxxxxx xxxxxxxx
20800 \end_inset
20801 </cell>
20802 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20803 \begin_inset Text
20804
20805 \layout Standard
20806
20807 a 21-bit code pointer in FLASH memory
20808 \end_inset
20809 </cell>
20810 </row>
20811 <row bottomline="true">
20812 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20813 \begin_inset Text
20814
20815 \layout Standard
20816
20817 eeprom
20818 \end_inset
20819 </cell>
20820 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20821 \begin_inset Text
20822
20823 \layout Standard
20824
20825 0
20826 \end_inset
20827 </cell>
20828 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20829 \begin_inset Text
20830
20831 \layout Standard
20832
20833 1
20834 \end_inset
20835 </cell>
20836 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20837 \begin_inset Text
20838
20839 \layout Standard
20840
20841
20842 \family typewriter
20843 \shape slanted
20844 \emph on
20845 uuuuuu uuuuuuxx xxxxxxxx
20846 \end_inset
20847 </cell>
20848 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20849 \begin_inset Text
20850
20851 \layout Standard
20852
20853 a 10-bit eeprom pointer in EEPROM memory
20854 \end_inset
20855 </cell>
20856 </row>
20857 <row bottomline="true">
20858 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20859 \begin_inset Text
20860
20861 \layout Standard
20862
20863 (unimplemented)
20864 \end_inset
20865 </cell>
20866 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20867 \begin_inset Text
20868
20869 \layout Standard
20870
20871 1
20872 \end_inset
20873 </cell>
20874 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20875 \begin_inset Text
20876
20877 \layout Standard
20878
20879 1
20880 \end_inset
20881 </cell>
20882 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20883 \begin_inset Text
20884
20885 \layout Standard
20886
20887
20888 \family typewriter
20889 \shape slanted
20890 \emph on
20891 xxxxxx xxxxxxxx xxxxxxxx
20892 \end_inset
20893 </cell>
20894 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20895 \begin_inset Text
20896
20897 \layout Standard
20898
20899 unimplemented pointer type
20900 \end_inset
20901 </cell>
20902 </row>
20903 </lyxtabular>
20904
20905 \end_inset
20906
20907
20908 \layout Standard
20909
20910 Generic pointer are read and written with a set of library functions which
20911  read/write 1, 2, 3, 4 bytes.
20912 \layout Subsection
20913
20914 PIC16 C Libraries
20915 \layout Subsubsection
20916
20917 Standard I/O Streams
20918 \layout Standard
20919
20920 In the
20921 \emph on
20922 stdio.h
20923 \emph default
20924  the type FILE is defined as:
20925 \layout LyX-Code
20926
20927 typedef char * FILE;
20928 \layout Standard
20929
20930 This type is the stream type implemented I/O in the PIC18F devices.
20931  Also the standard input and output streams are declared in stdio.h:
20932 \layout LyX-Code
20933
20934 extern FILE * stdin;
20935 \layout LyX-Code
20936
20937 extern FILE * stdout;
20938 \layout Standard
20939
20940 The FILE type is actually a generic pointer which defines one more type
20941  of generic pointers, the
20942 \emph on
20943 stream
20944 \emph default
20945 pointer.
20946  This new type has the format:
20947 \layout Standard
20948 \align center
20949
20950 \begin_inset  Tabular
20951 <lyxtabular version="3" rows="2" columns="7">
20952 <features>
20953 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20954 <column alignment="center" valignment="top" width="0">
20955 <column alignment="center" valignment="top" leftline="true" width="0">
20956 <column alignment="center" valignment="top" leftline="true" width="0">
20957 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20958 <column alignment="center" valignment="top" width="0">
20959 <column alignment="left" valignment="top" rightline="true" width="0">
20960 <row topline="true" bottomline="true">
20961 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20962 \begin_inset Text
20963
20964 \layout Standard
20965
20966 pointer type
20967 \end_inset
20968 </cell>
20969 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20970 \begin_inset Text
20971
20972 \layout Standard
20973
20974 <7:6>
20975 \end_inset
20976 </cell>
20977 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20978 \begin_inset Text
20979
20980 \layout Standard
20981
20982 <5>
20983 \end_inset
20984 </cell>
20985 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20986 \begin_inset Text
20987
20988 \layout Standard
20989
20990 <4>
20991 \end_inset
20992 </cell>
20993 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20994 \begin_inset Text
20995
20996 \layout Standard
20997
20998 <3:0>
20999 \end_inset
21000 </cell>
21001 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21002 \begin_inset Text
21003
21004 \layout Standard
21005
21006 rest of the pointer
21007 \end_inset
21008 </cell>
21009 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21010 \begin_inset Text
21011
21012 \layout Standard
21013
21014 descrption
21015 \end_inset
21016 </cell>
21017 </row>
21018 <row topline="true" bottomline="true">
21019 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21020 \begin_inset Text
21021
21022 \layout Standard
21023
21024 stream
21025 \end_inset
21026 </cell>
21027 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21028 \begin_inset Text
21029
21030 \layout Standard
21031
21032 00
21033 \end_inset
21034 </cell>
21035 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21036 \begin_inset Text
21037
21038 \layout Standard
21039
21040 1
21041 \end_inset
21042 </cell>
21043 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21044 \begin_inset Text
21045
21046 \layout Standard
21047
21048 0
21049 \end_inset
21050 </cell>
21051 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21052 \begin_inset Text
21053
21054 \layout Standard
21055
21056 nnnn
21057 \end_inset
21058 </cell>
21059 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21060 \begin_inset Text
21061
21062 \layout Standard
21063
21064
21065 \family typewriter
21066 \shape slanted
21067 \emph on
21068 uuuuuuuu uuuuuuuu
21069 \end_inset
21070 </cell>
21071 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21072 \begin_inset Text
21073
21074 \layout Standard
21075
21076 upper byte high nubble is 0x2n, the rest are zeroes
21077 \end_inset
21078 </cell>
21079 </row>
21080 </lyxtabular>
21081
21082 \end_inset
21083
21084
21085 \layout Standard
21086
21087 Currently implemented there are 3 types of streams defined:
21088 \layout Standard
21089 \align center
21090
21091 \begin_inset  Tabular
21092 <lyxtabular version="3" rows="4" columns="4">
21093 <features>
21094 <column alignment="center" valignment="top" leftline="true" width="0">
21095 <column alignment="center" valignment="top" leftline="true" width="0">
21096 <column alignment="center" valignment="top" leftline="true" width="0">
21097 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
21098 <row topline="true" bottomline="true">
21099 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21100 \begin_inset Text
21101
21102 \layout Standard
21103
21104 stream type
21105 \end_inset
21106 </cell>
21107 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21108 \begin_inset Text
21109
21110 \layout Standard
21111
21112 value
21113 \end_inset
21114 </cell>
21115 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21116 \begin_inset Text
21117
21118 \layout Standard
21119
21120 module
21121 \end_inset
21122 </cell>
21123 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21124 \begin_inset Text
21125
21126 \layout Standard
21127
21128 description
21129 \end_inset
21130 </cell>
21131 </row>
21132 <row topline="true">
21133 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21134 \begin_inset Text
21135
21136 \layout Standard
21137
21138 STREAM_USART
21139 \end_inset
21140 </cell>
21141 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21142 \begin_inset Text
21143
21144 \layout Standard
21145
21146
21147 \family typewriter
21148 0x200000UL
21149 \end_inset
21150 </cell>
21151 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21152 \begin_inset Text
21153
21154 \layout Standard
21155
21156 USART
21157 \end_inset
21158 </cell>
21159 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21160 \begin_inset Text
21161
21162 \layout Standard
21163
21164 Writes/Reads characters via the USART peripheral
21165 \end_inset
21166 </cell>
21167 </row>
21168 <row topline="true">
21169 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21170 \begin_inset Text
21171
21172 \layout Standard
21173
21174 STREAM_MSSP
21175 \end_inset
21176 </cell>
21177 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21178 \begin_inset Text
21179
21180 \layout Standard
21181
21182
21183 \family typewriter
21184 0x210000UL
21185 \end_inset
21186 </cell>
21187 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21188 \begin_inset Text
21189
21190 \layout Standard
21191
21192 MSSP
21193 \end_inset
21194 </cell>
21195 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21196 \begin_inset Text
21197
21198 \layout Standard
21199
21200 Writes/Reads characters via the MSSP peripheral
21201 \end_inset
21202 </cell>
21203 </row>
21204 <row topline="true" bottomline="true">
21205 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21206 \begin_inset Text
21207
21208 \layout Standard
21209
21210 STREAM_USER
21211 \end_inset
21212 </cell>
21213 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21214 \begin_inset Text
21215
21216 \layout Standard
21217
21218
21219 \family typewriter
21220 0x2f0000UL
21221 \end_inset
21222 </cell>
21223 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21224 \begin_inset Text
21225
21226 \layout Standard
21227
21228 (none)
21229 \end_inset
21230 </cell>
21231 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21232 \begin_inset Text
21233
21234 \layout Standard
21235
21236 Writes/Reads characters via used defined functions
21237 \end_inset
21238 </cell>
21239 </row>
21240 </lyxtabular>
21241
21242 \end_inset
21243
21244
21245 \layout Standard
21246
21247 The stream identifiers are declared as macros in the stdio.h header.
21248 \layout Standard
21249
21250 In the libc library there exist the functions that are used to write to
21251  each of the above streams.
21252  These are
21253 \layout List
21254 \labelwidthstring 00.00.0000
21255
21256 _
21257 \begin_inset ERT
21258 status Collapsed
21259
21260 \layout Standard
21261
21262 \backslash
21263 /
21264 \end_inset
21265
21266 _stream_usart_putchar writes a character at the USART stream
21267 \layout List
21268 \labelwidthstring 00.00.0000
21269
21270 _
21271 \begin_inset ERT
21272 status Collapsed
21273
21274 \layout Standard
21275
21276 \backslash
21277 /
21278 \end_inset
21279
21280 _stream_mssp_putchar writes a character at the MSSP stream
21281 \layout List
21282 \labelwidthstring 00.00.0000
21283
21284 putchar dummy function.
21285  This writes a character to a user specified manner.
21286 \layout Standard
21287
21288 In order to increase performance
21289 \emph on
21290 putchar
21291 \emph default
21292 is declared in stdio.h as having its parameter in WREG (it has the wparam
21293  keyword).
21294  In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function
21295  in a user-friendly way.
21296
21297 \emph on
21298 arg
21299 \emph default
21300  is the name of the variable that holds the character to print.
21301  An example follows:
21302 \layout LyX-Code
21303
21304 #include <pic18fregs.h>
21305 \newline
21306 #include <stdio.h>
21307 \newline
21308
21309 \newline
21310 PUTCHAR( c )
21311 \layout LyX-Code
21312
21313 {
21314 \layout LyX-Code
21315
21316     PORTA = c;    /* dump character c to PORTA */
21317 \layout LyX-Code
21318
21319 }
21320 \newline
21321
21322 \newline
21323 void main(void)
21324 \layout LyX-Code
21325
21326 {
21327 \layout LyX-Code
21328
21329     stdout = STREAM_USER;    /* this is not necessary, since stdout points
21330 \layout LyX-Code
21331
21332                               * by default to STREAM_USER */
21333 \layout LyX-Code
21334
21335     printf (¨This is a printf test
21336 \backslash
21337 n¨);
21338 \layout LyX-Code
21339
21340 }
21341 \layout LyX-Code
21342
21343 \layout Subsubsection
21344
21345 Printing functions
21346 \layout Standard
21347
21348 PIC16 contains an implementation of the printf-family of functions.
21349  There exist the following functions:
21350 \layout LyX-Code
21351
21352 extern unsigned int sprintf(char *buf, char *fmt, ...);
21353 \layout LyX-Code
21354
21355 extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
21356 \layout LyX-Code
21357
21358 \layout LyX-Code
21359
21360 extern unsigned int printf(char *fmt, ...);
21361 \layout LyX-Code
21362
21363 extern unsigned int vprintf(char *fmt, va_lista ap);
21364 \layout LyX-Code
21365
21366 \layout LyX-Code
21367
21368 extern unsigned int fprintf(FILE *fp, char *fmt, ...);
21369 \layout LyX-Code
21370
21371 extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
21372 \layout Standard
21373
21374 For sprintf and vsprintf
21375 \emph on
21376 buf
21377 \emph default
21378 should normally be a data pointer where the resulting string will be placed.
21379  No range checking is done so the user should allocate the necessery buffer.
21380  For fprintf and vfprintf
21381 \emph on
21382 fp
21383 \emph default
21384  should be a stream pointer (i.e.
21385  stdout, STREAM_MSSP, etc...).
21386 \layout Subsubsection
21387
21388 Signals
21389 \layout Standard
21390
21391 The PIC18F family of microcontrollers supports a number of interrupt sources.
21392  A list of these interrupts is shown in the following table:
21393 \layout Standard
21394 \align center
21395
21396 \begin_inset  Tabular
21397 <lyxtabular version="3" rows="11" columns="4">
21398 <features>
21399 <column alignment="left" valignment="top" leftline="true" width="0">
21400 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
21401 <column alignment="left" valignment="top" leftline="true" width="0">
21402 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
21403 <row topline="true" bottomline="true">
21404 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21405 \begin_inset Text
21406
21407 \layout Standard
21408
21409 signal name
21410 \end_inset
21411 </cell>
21412 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21413 \begin_inset Text
21414
21415 \layout Standard
21416
21417 description
21418 \end_inset
21419 </cell>
21420 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21421 \begin_inset Text
21422
21423 \layout Standard
21424
21425 signal name
21426 \end_inset
21427 </cell>
21428 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21429 \begin_inset Text
21430
21431 \layout Standard
21432
21433 descritpion
21434 \end_inset
21435 </cell>
21436 </row>
21437 <row topline="true">
21438 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21439 \begin_inset Text
21440
21441 \layout Standard
21442
21443 SIG_RB
21444 \end_inset
21445 </cell>
21446 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21447 \begin_inset Text
21448
21449 \layout Standard
21450
21451 PORTB change interrupt
21452 \end_inset
21453 </cell>
21454 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21455 \begin_inset Text
21456
21457 \layout Standard
21458
21459 SIG_EE
21460 \end_inset
21461 </cell>
21462 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21463 \begin_inset Text
21464
21465 \layout Standard
21466
21467 EEPROM/FLASH write complete interrupt
21468 \end_inset
21469 </cell>
21470 </row>
21471 <row topline="true">
21472 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21473 \begin_inset Text
21474
21475 \layout Standard
21476
21477 SIG_INT0
21478 \end_inset
21479 </cell>
21480 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21481 \begin_inset Text
21482
21483 \layout Standard
21484
21485 INT0 external interrupt
21486 \end_inset
21487 </cell>
21488 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21489 \begin_inset Text
21490
21491 \layout Standard
21492
21493 SIG_BCOL
21494 \end_inset
21495 </cell>
21496 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21497 \begin_inset Text
21498
21499 \layout Standard
21500
21501 Bus collision interrupt
21502 \end_inset
21503 </cell>
21504 </row>
21505 <row topline="true">
21506 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21507 \begin_inset Text
21508
21509 \layout Standard
21510
21511 SIG_INT1
21512 \end_inset
21513 </cell>
21514 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21515 \begin_inset Text
21516
21517 \layout Standard
21518
21519 INT1 external interrupt
21520 \end_inset
21521 </cell>
21522 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21523 \begin_inset Text
21524
21525 \layout Standard
21526
21527 SIG_LVD
21528 \end_inset
21529 </cell>
21530 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21531 \begin_inset Text
21532
21533 \layout Standard
21534
21535 Low voltage detect interrupt
21536 \end_inset
21537 </cell>
21538 </row>
21539 <row topline="true">
21540 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21541 \begin_inset Text
21542
21543 \layout Standard
21544
21545 SIG_INT2
21546 \end_inset
21547 </cell>
21548 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21549 \begin_inset Text
21550
21551 \layout Standard
21552
21553 INT2 external interrupt
21554 \end_inset
21555 </cell>
21556 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21557 \begin_inset Text
21558
21559 \layout Standard
21560
21561 SIG_PSP
21562 \end_inset
21563 </cell>
21564 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21565 \begin_inset Text
21566
21567 \layout Standard
21568
21569 Parallel slave port interrupt
21570 \end_inset
21571 </cell>
21572 </row>
21573 <row topline="true">
21574 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21575 \begin_inset Text
21576
21577 \layout Standard
21578
21579 SIG_CCP1
21580 \end_inset
21581 </cell>
21582 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21583 \begin_inset Text
21584
21585 \layout Standard
21586
21587 CCP1 module interrupt
21588 \end_inset
21589 </cell>
21590 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21591 \begin_inset Text
21592
21593 \layout Standard
21594
21595 SIG_AD
21596 \end_inset
21597 </cell>
21598 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21599 \begin_inset Text
21600
21601 \layout Standard
21602
21603 AD convertion complete interrupt
21604 \end_inset
21605 </cell>
21606 </row>
21607 <row topline="true">
21608 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21609 \begin_inset Text
21610
21611 \layout Standard
21612
21613 SIG_CCP2
21614 \end_inset
21615 </cell>
21616 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21617 \begin_inset Text
21618
21619 \layout Standard
21620
21621 CCP2 module interrupt
21622 \end_inset
21623 </cell>
21624 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21625 \begin_inset Text
21626
21627 \layout Standard
21628
21629 SIG_RC
21630 \end_inset
21631 </cell>
21632 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21633 \begin_inset Text
21634
21635 \layout Standard
21636
21637 USART receive interrupt
21638 \end_inset
21639 </cell>
21640 </row>
21641 <row topline="true">
21642 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21643 \begin_inset Text
21644
21645 \layout Standard
21646
21647 SIG_TMR0
21648 \end_inset
21649 </cell>
21650 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21651 \begin_inset Text
21652
21653 \layout Standard
21654
21655 TMR0 overflow interrupt
21656 \end_inset
21657 </cell>
21658 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21659 \begin_inset Text
21660
21661 \layout Standard
21662
21663 SIG_TX
21664 \end_inset
21665 </cell>
21666 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21667 \begin_inset Text
21668
21669 \layout Standard
21670
21671 USART transmit interrupt
21672 \end_inset
21673 </cell>
21674 </row>
21675 <row topline="true">
21676 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21677 \begin_inset Text
21678
21679 \layout Standard
21680
21681 SIG_TMR1
21682 \end_inset
21683 </cell>
21684 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21685 \begin_inset Text
21686
21687 \layout Standard
21688
21689 TMR1 overflow interrupt
21690 \end_inset
21691 </cell>
21692 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21693 \begin_inset Text
21694
21695 \layout Standard
21696
21697 SIG_MSSP
21698 \end_inset
21699 </cell>
21700 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21701 \begin_inset Text
21702
21703 \layout Standard
21704
21705 SSP receive/transmit interrupt
21706 \end_inset
21707 </cell>
21708 </row>
21709 <row topline="true">
21710 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21711 \begin_inset Text
21712
21713 \layout Standard
21714
21715 SIG_TMR2
21716 \end_inset
21717 </cell>
21718 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21719 \begin_inset Text
21720
21721 \layout Standard
21722
21723 TMR2 matches PR2 interrupt
21724 \end_inset
21725 </cell>
21726 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21727 \begin_inset Text
21728
21729 \layout Standard
21730
21731 \end_inset
21732 </cell>
21733 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21734 \begin_inset Text
21735
21736 \layout Standard
21737
21738 \end_inset
21739 </cell>
21740 </row>
21741 <row topline="true" bottomline="true">
21742 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21743 \begin_inset Text
21744
21745 \layout Standard
21746
21747 SIG_TMR3
21748 \end_inset
21749 </cell>
21750 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21751 \begin_inset Text
21752
21753 \layout Standard
21754
21755 TMR3 overflow interrupt
21756 \end_inset
21757 </cell>
21758 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21759 \begin_inset Text
21760
21761 \layout Standard
21762
21763 \end_inset
21764 </cell>
21765 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21766 \begin_inset Text
21767
21768 \layout Standard
21769
21770 \end_inset
21771 </cell>
21772 </row>
21773 </lyxtabular>
21774
21775 \end_inset
21776
21777
21778 \layout Standard
21779
21780 The prototypes for these names are defined in the header file
21781 \emph on
21782 signal.h
21783 \emph default
21784  .
21785 \layout Standard
21786
21787 In order to simplify signal handling, a number of macros is provided:
21788 \layout List
21789 \labelwidthstring 00.00.0000
21790
21791 DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for
21792  high priority interrupts.
21793
21794 \emph on
21795 name
21796 \emph default
21797  is the function name to use.
21798 \layout List
21799 \labelwidthstring 00.00.0000
21800
21801 DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo
21802  low priority interrupt.
21803
21804 \emph on
21805 name
21806 \emph default
21807  is the function name to use.
21808 \layout List
21809 \labelwidthstring 00.00.0000
21810
21811 DEF_HANDLER(sig,handler) define a handler for signal
21812 \emph on
21813 sig.
21814 \layout List
21815 \labelwidthstring 00.00.0000
21816
21817 END_DEF end the declaration of the dispatch table.
21818 \layout Standard
21819
21820 Additionally there are two more macros to simplify the declaration of the
21821  signal handler:
21822 \layout List
21823 \labelwidthstring 00.00.0000
21824
21825
21826 \series medium
21827 SIGHANDLER(handler)
21828 \series default
21829 this declares the function prototype for the
21830 \emph on
21831 handler
21832 \emph default
21833  function.
21834 \layout List
21835 \labelwidthstring 00.00.0000
21836
21837 SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function.
21838 \layout Standard
21839
21840 An example of using the macros above is shown below:
21841 \layout LyX-Code
21842
21843 #include <pic18fregs.h>
21844 \layout LyX-Code
21845
21846 #include <signal.h>
21847 \newline
21848
21849 \newline
21850 DEF_INTHIGH(high_int)
21851 \layout LyX-Code
21852
21853 DEF_HANDLER(SIG_TMR0, _tmr0_handler)
21854 \layout LyX-Code
21855
21856 DEF_HANDLER(SIG_BCOL, _bcol_handler)
21857 \layout LyX-Code
21858
21859 END_DEF
21860 \newline
21861
21862 \newline
21863 SIGHANDLER(_tmr0_handler)
21864 \layout LyX-Code
21865
21866 {
21867 \layout LyX-Code
21868
21869   /* action to be taken when timer 0 overflows */
21870 \layout LyX-Code
21871
21872 }
21873 \newline
21874
21875 \newline
21876 SIGHANDLERNAKED(_bcol_handler)
21877 \layout LyX-Code
21878
21879 {
21880 \layout LyX-Code
21881
21882   _asm
21883 \layout LyX-Code
21884
21885     /* action to be taken when bus collision occurs */
21886 \layout LyX-Code
21887
21888     retfie
21889 \layout LyX-Code
21890
21891  _endasm;
21892 \layout LyX-Code
21893
21894 }
21895 \layout Standard
21896
21897
21898 \series bold
21899 NOTES:
21900 \series default
21901  Special care should be taken when using the above scheme:
21902 \layout Itemize
21903
21904 do not place a colon (;) at the end of the DEF_* and END_DEF macros.
21905 \layout Itemize
21906
21907 when declaring SIGHANDLERNAKED handler never forget to use
21908 \emph on
21909 retfie
21910 \emph default
21911  for proper returning.
21912 \layout Subsection
21913
21914 PIC16 Port -- Tips
21915 \layout Standard
21916
21917 Here you can find some general tips for compiling programs with SDCC/pic16.
21918 \layout Subsubsection
21919
21920 Stack size
21921 \layout Standard
21922
21923 The default stack
21924 \begin_inset LatexCommand \index{PIC16!stack}
21925
21926 \end_inset
21927
21928  size (that is 64 bytes) probably is enough for many programs.
21929  One must take care that when there are many levels of function nesting,
21930  or there is excessive usage of stack, its size should be extended.
21931  An example of such a case is the printf/sprintf family of functions.
21932  If you encounter problems like not being able to print integers, then you
21933  need to set the stack size around the maximum (256 for small stack model).
21934  The following diagram shows what happens when calling printf to print an
21935  integer:
21936 \layout LyX-Code
21937
21938 printf () --> ltoa () --> ultoa () --> divschar ()
21939 \layout Standard
21940
21941 It is should be understood that stack is easily consumed when calling complicate
21942 d functions.
21943  Using command line arguments like -
21944 \begin_inset ERT
21945 status Collapsed
21946
21947 \layout Standard
21948
21949 \backslash
21950 /
21951 \end_inset
21952
21953 -fommit-frame-pointer might reduce stack usage by not creating unnecessery
21954  stack frames.
21955  Other ways to reduce stack usage may exist.
21956 \layout Subsection
21957
21958 Known bugs
21959 \layout Standard
21960
21961 The PIC16 Port currently does not pass SDCC's regression test
21962 \begin_inset LatexCommand \index{Regression test (PIC16)}
21963
21964 \end_inset
21965
21966  suite (see section
21967 \begin_inset LatexCommand \ref{sec:Quality-control}
21968
21969 \end_inset
21970
21971 ) and thus the nightly regression tests for the PIC16 target are currently
21972  disabled for all hosts except for
21973 \emph on
21974 Linux on Opteron.
21975
21976 \emph default
21977  This means you can see the result of the PIC16 regression tests f.e.
21978  by checking the log files in
21979 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/regression_test_results/amd64-unknown-linux2.3/}
21980
21981 \end_inset
21982
21983  (pick the most up to date file there, scroll down, lend a hand).
21984 \layout Chapter
21985
21986 Debugging
21987 \layout Standard
21988
21989 There are several approaches to debugging your code.
21990  This chapter is meant to show your options and to give detail on some of
21991  them:
21992 \newline
21993
21994 \newline
21995 When writing your code:
21996 \layout Itemize
21997
21998 write your code with debugging in mind (avoid duplicating code, put conceptually
21999  similar variables into structs, use structured code, have strategic points
22000  within your code where all variables are consistent, ...)
22001 \layout Itemize
22002
22003 run a syntax-checking tool like splint
22004 \begin_inset LatexCommand \index{splint (syntax checking tool)}
22005
22006 \end_inset
22007
22008
22009 \begin_inset LatexCommand \index{lint (syntax checking tool)}
22010
22011 \end_inset
22012
22013  (see -
22014 \begin_inset ERT
22015 status Collapsed
22016
22017 \layout Standard
22018
22019 \backslash
22020 /
22021 \end_inset
22022
22023 -more-pedantic
22024 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
22025
22026 \end_inset
22027
22028 ) over the code.
22029 \layout Itemize
22030
22031 for the high level code use a C-compiler (like f.e.
22032  GCC) to compile run and debug the code on your host.
22033  See (see -
22034 \begin_inset ERT
22035 status Collapsed
22036
22037 \layout Standard
22038
22039 \backslash
22040 /
22041 \end_inset
22042
22043 -more-pedantic
22044 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
22045
22046 \end_inset
22047
22048  ) on howto handle syntax extensions like __xdata, __at(), ...
22049
22050 \layout Itemize
22051
22052 use another C-compiler to compile code for your target.
22053  Always an option but not recommended:) And not very likely to help you.
22054  If you seriously consider walking this path you should at least occasionally
22055  check portability of your code.
22056  Most commercial compiler vendors will offer an evaluation version so you
22057  can test compile your code or snippets of your code.
22058 \layout Standard
22059
22060 Debugging on a simulator:
22061 \layout Itemize
22062
22063 there is a separate section about SDCDB (section
22064 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
22065
22066 \end_inset
22067
22068 ) below.
22069 \layout Itemize
22070
22071 or (8051 specific) use a freeware/commercial simulator which interfaces
22072  to the AOMF
22073 \begin_inset LatexCommand \index{AOMF, AOMF51}
22074
22075 \end_inset
22076
22077  file (see
22078 \begin_inset LatexCommand \ref{OMF file}
22079
22080 \end_inset
22081
22082 ) optionally generated by SDCC.
22083 \layout Standard
22084
22085 Debugging On-target:
22086 \layout Itemize
22087
22088 use a MCU port pin to serially output debug data to the RS232 port of your
22089  host.
22090  You'll probably want some level shifting device typically involving a MAX232
22091  or similar IC.
22092  If the hardware serial port of the MCU is not available search for 'Software
22093  UART' in your favourite search machine.
22094 \layout Itemize
22095
22096 use an on-target monitor.
22097  In this context a monitor is a small program which usually accepts commands
22098  via a serial line and allows to set program counter, to single step through
22099  a program and read/write memory locations.
22100  For the 8051 good examples of monitors are paulmon and cmon51 (see section
22101
22102 \begin_inset LatexCommand \ref{sec:Related-open-source-tools}
22103
22104 \end_inset
22105
22106 ).
22107 \layout Itemize
22108
22109 toggle MCU port pins at strategic points within your code and use an oscilloscop
22110 e.
22111  A
22112 \emph on
22113 digital oscilloscope
22114 \emph default
22115
22116 \begin_inset LatexCommand \index{Oscilloscope}
22117
22118 \end_inset
22119
22120  with deep trace memory is really helpful especially if you have to debug
22121  a realtime application.
22122  If you need to monitor more pins than your oscilloscope provides you can
22123  sometimes get away with a small R-2R network.
22124  On a single channel oscilloscope you could f.e.
22125  monitor 2 push-pull driven pins by connecting one via a 10\SpecialChar ~
22126 k
22127 \begin_inset Formula $\Omega$
22128 \end_inset
22129
22130  resistor and the other one by a 5\SpecialChar ~
22131 k
22132 \begin_inset Formula $\Omega$
22133 \end_inset
22134
22135  resistor to the oscilloscope probe (check output drive capability of the
22136  pins you want to monitor).
22137  If you need to monitor many more pins a
22138 \emph on
22139 logic analyzer
22140 \emph default
22141  will be handy.
22142 \layout Itemize
22143
22144 use an ICE (
22145 \emph on
22146 i
22147 \emph default
22148 n
22149 \emph on
22150 c
22151 \emph default
22152 ircuit
22153 \emph on
22154 e
22155 \emph default
22156 mulator
22157 \begin_inset LatexCommand \index{ICE (in circuit emulator)}
22158
22159 \end_inset
22160
22161 ).
22162  Usually very expensive.
22163  And very nice to have too.
22164  And usually locks you (for years...) to the devices the ICE can emulate.
22165
22166 \layout Itemize
22167
22168 use a remote debugger.
22169  In most 8-bit systems the symbol information is not available on the target,
22170  and a complete debugger is too bulky for the target system.
22171  Therefore usually a debugger on the host system connects to an on-target
22172  debugging stub which accepts only primitive commands.
22173
22174 \newline
22175 Terms to enter into your favourite search engine could be 'remote debugging',
22176  'gdb stub' or 'inferior debugger'.
22177  (is there one?)
22178 \layout Itemize
22179
22180 use an on target hardware debugger.
22181  Some of the more modern MCUs include hardware support for setting break
22182  points and monitoring/changing variables by using dedicated hardware pins.
22183  This facility doesn't require additional code to run on the target and
22184
22185 \emph on
22186 usually
22187 \emph default
22188  doesn't affect runtime behaviour until a breakpoint is hit.
22189  For the mcs51 most hardware debuggers use the AOMF
22190 \begin_inset LatexCommand \index{AOMF, AOMF51}
22191
22192 \end_inset
22193
22194  file (see
22195 \begin_inset LatexCommand \ref{OMF file}
22196
22197 \end_inset
22198
22199 ) as input file.
22200
22201 \layout Standard
22202
22203 Last not least:
22204 \layout Itemize
22205
22206 if you are not familiar with any of the following terms you're likely to
22207  run into problems rather sooner than later:
22208 \emph on
22209 volatile
22210 \emph default
22211 ,
22212 \emph on
22213 atomic
22214 \emph default
22215 ,
22216 \emph on
22217 memory map
22218 \emph default
22219 ,
22220 \emph on
22221 overlay
22222 \emph default
22223 .
22224  As an embedded programmer you
22225 \emph on
22226 have
22227 \emph default
22228  to know them so why not look them up
22229 \emph on
22230 before
22231 \emph default
22232  you have problems?)
22233 \layout Itemize
22234
22235 tell someone else about your problem (actually this is a surprisingly effective
22236  means to hunt down the bug even if the listener is not familiar with your
22237  environment).
22238  As 'failure to communicate' is probably one of the job-induced deformations
22239  of an embedded programmer this is highly encouraged.
22240 \layout Section
22241
22242 Debugging with SDCDB
22243 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
22244
22245 \end_inset
22246
22247
22248 \begin_inset LatexCommand \index{SDCDB (debugger)}
22249
22250 \end_inset
22251
22252
22253 \layout Standard
22254
22255 SDCC is distributed with a source level debugger
22256 \begin_inset LatexCommand \index{Debugger}
22257
22258 \end_inset
22259
22260 .
22261  The debugger uses a command line interface, the command repertoire of the
22262  debugger has been kept as close to gdb
22263 \begin_inset LatexCommand \index{gdb}
22264
22265 \end_inset
22266
22267  (the GNU debugger) as possible.
22268  The configuration and build process is part of the standard compiler installati
22269 on, which also builds and installs the debugger in the target directory
22270  specified during configuration.
22271  The debugger allows you debug BOTH at the C source and at the ASM source
22272  level.
22273 \layout Subsection
22274
22275 Compiling for Debugging
22276 \layout Standard
22277
22278 The -
22279 \begin_inset ERT
22280 status Collapsed
22281
22282 \layout Standard
22283
22284 \backslash
22285 /
22286 \end_inset
22287
22288 -debug
22289 \begin_inset LatexCommand \index{-\/-debug}
22290
22291 \end_inset
22292
22293  option must be specified for all files for which debug information is to
22294  be generated.
22295  The compiler generates a .adb file for each of these files.
22296  The linker creates the .cdb
22297 \begin_inset LatexCommand \index{<file>.cdb}
22298
22299 \end_inset
22300
22301  file from the .adb
22302 \begin_inset LatexCommand \index{<file>.adb}
22303
22304 \end_inset
22305
22306  files and the address information.
22307  This .cdb is used by the debugger.
22308 \layout Subsection
22309
22310 How the Debugger Works
22311 \layout Standard
22312
22313 When the -
22314 \begin_inset ERT
22315 status Collapsed
22316
22317 \layout Standard
22318
22319 \backslash
22320 /
22321 \end_inset
22322
22323 -debug option is specified the compiler generates extra symbol information
22324  some of which are put into the assembler source and some are put into the
22325  .adb file.
22326  Then the linker creates the .cdb file from the individual .adb files with
22327  the address information for the symbols.
22328  The debugger reads the symbolic information generated by the compiler &
22329  the address information generated by the linker.
22330  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
22331  execution is controlled by the debugger.
22332  When a command is issued for the debugger, it translates it into appropriate
22333  commands for the simulator.
22334  (Currently SDCDM only connects to the simulator but
22335 \emph on
22336 newcdb
22337 \emph default
22338  at
22339 \begin_inset LatexCommand \url{http://ec2drv.sf.net/}
22340
22341 \end_inset
22342
22343  is an effort to connect directly to the hardware.)
22344 \layout Subsection
22345
22346 Starting the Debugger SDCDB
22347 \layout Standard
22348
22349 The debugger can be started using the following command line.
22350  (Assume the file you are debugging has the file name foo).
22351 \newline
22352
22353 \newline
22354
22355 \family sans
22356 \series bold
22357 sdcdb foo
22358 \newline
22359
22360 \family default
22361 \series default
22362
22363 \newline
22364 The debugger will look for the following files.
22365 \layout Itemize
22366
22367 foo.c - the source file.
22368 \layout Itemize
22369
22370 foo.cdb - the debugger symbol information file.
22371 \layout Itemize
22372
22373 foo.ihx - the Intel hex format
22374 \begin_inset LatexCommand \index{Intel hex format}
22375
22376 \end_inset
22377
22378  object file.
22379 \layout Subsection
22380
22381 SDCDB Command Line Options
22382 \layout Itemize
22383
22384 -
22385 \begin_inset ERT
22386 status Collapsed
22387
22388 \layout Standard
22389
22390 \backslash
22391 /
22392 \end_inset
22393
22394 -directory=<source file directory> this option can used to specify the directory
22395  search list.
22396  The debugger will look into the directory list specified for source, cdb
22397  & ihx files.
22398  The items in the directory list must be separated by ':', e.g.
22399  if the source files can be in the directories /home/src1 and /home/src2,
22400  the -
22401 \begin_inset ERT
22402 status Collapsed
22403
22404 \layout Standard
22405
22406 \backslash
22407 /
22408 \end_inset
22409
22410 -directory option should be -
22411 \begin_inset ERT
22412 status Collapsed
22413
22414 \layout Standard
22415
22416 \backslash
22417 /
22418 \end_inset
22419
22420 -directory=/home/src1:/home/src2.
22421  Note there can be no spaces in the option.
22422
22423 \layout Itemize
22424
22425 -cd <directory> - change to the <directory>.
22426 \layout Itemize
22427
22428 -fullname - used by GUI front ends.
22429 \layout Itemize
22430
22431 -cpu <cpu-type> - this argument is passed to the simulator please see the
22432  simulator docs for details.
22433 \layout Itemize
22434
22435 -X <Clock frequency > this options is passed to the simulator please see
22436  the simulator docs for details.
22437 \layout Itemize
22438
22439 -s <serial port file> passed to simulator see the simulator docs for details.
22440 \layout Itemize
22441
22442 -S <serial in,out> passed to simulator see the simulator docs for details.
22443 \layout Itemize
22444
22445 -k <port number> passed to simulator see the simulator docs for details.
22446 \layout Subsection
22447
22448 SDCDB Debugger Commands
22449 \layout Standard
22450
22451 As mentioned earlier the command interface for the debugger has been deliberatel
22452 y kept as close the GNU debugger gdb, as possible.
22453  This will help the integration with existing graphical user interfaces
22454  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
22455  If you use a graphical user interface for the debugger you can skip this
22456  section.
22457 \layout Subsubsection*
22458
22459 break [line | file:line | function | file:function]
22460 \layout Standard
22461
22462 Set breakpoint at specified line or function:
22463 \newline
22464
22465 \newline
22466
22467 \family sans
22468 \series bold
22469 sdcdb>break 100
22470 \newline
22471 sdcdb>break foo.c:100
22472 \newline
22473 sdcdb>break funcfoo
22474 \newline
22475 sdcdb>break foo.c:funcfoo
22476 \layout Subsubsection*
22477
22478 clear [line | file:line | function | file:function ]
22479 \layout Standard
22480
22481 Clear breakpoint at specified line or function:
22482 \newline
22483
22484 \newline
22485
22486 \family sans
22487 \series bold
22488 sdcdb>clear 100
22489 \newline
22490 sdcdb>clear foo.c:100
22491 \newline
22492 sdcdb>clear funcfoo
22493 \newline
22494 sdcdb>clear foo.c:funcfoo
22495 \layout Subsubsection*
22496
22497 continue
22498 \layout Standard
22499
22500 Continue program being debugged, after breakpoint.
22501 \layout Subsubsection*
22502
22503 finish
22504 \layout Standard
22505
22506 Execute till the end of the current function.
22507 \layout Subsubsection*
22508
22509 delete [n]
22510 \layout Standard
22511
22512 Delete breakpoint number 'n'.
22513  If used without any option clear ALL user defined break points.
22514 \layout Subsubsection*
22515
22516 info [break | stack | frame | registers ]
22517 \layout Itemize
22518
22519 info break - list all breakpoints
22520 \layout Itemize
22521
22522 info stack - show the function call stack.
22523 \layout Itemize
22524
22525 info frame - show information about the current execution frame.
22526 \layout Itemize
22527
22528 info registers - show content of all registers.
22529 \layout Subsubsection*
22530
22531 step
22532 \layout Standard
22533
22534 Step program until it reaches a different source line.
22535  Note: pressing <return> repeats the last command.
22536 \layout Subsubsection*
22537
22538 next
22539 \layout Standard
22540
22541 Step program, proceeding through subroutine calls.
22542 \layout Subsubsection*
22543
22544 run
22545 \layout Standard
22546
22547 Start debugged program.
22548 \layout Subsubsection*
22549
22550 ptype variable
22551 \layout Standard
22552
22553 Print type information of the variable.
22554 \layout Subsubsection*
22555
22556 print variable
22557 \layout Standard
22558
22559 print value of variable.
22560 \layout Subsubsection*
22561
22562 file filename
22563 \layout Standard
22564
22565 load the given file name.
22566  Note this is an alternate method of loading file for debugging.
22567 \layout Subsubsection*
22568
22569 frame
22570 \layout Standard
22571
22572 print information about current frame.
22573 \layout Subsubsection*
22574
22575 set srcmode
22576 \layout Standard
22577
22578 Toggle between C source & assembly source.
22579 \layout Subsubsection*
22580
22581 ! simulator command
22582 \layout Standard
22583
22584 Send the string following '!' to the simulator, the simulator response is
22585  displayed.
22586  Note the debugger does not interpret the command being sent to the simulator,
22587  so if a command like 'go' is sent the debugger can loose its execution
22588  context and may display incorrect values.
22589 \layout Subsubsection*
22590
22591 quit
22592 \layout Standard
22593
22594 "Watch me now.
22595  Iam going Down.
22596  My name is Bobby Brown"
22597 \layout Subsection
22598
22599 Interfacing SDCDB with DDD
22600 \layout Comment
22601
22602 The screenshot was converted from png to eps with:
22603 \begin_inset Quotes sld
22604 \end_inset
22605
22606 bmeps -c -e8f -p3 ddd_example.png >ddd_example.eps
22607 \begin_inset Quotes srd
22608 \end_inset
22609
22610  which produces a pretty compact eps file which is free from compression
22611  artifacts.
22612 \layout Comment
22613
22614 The screenshot was included in sdccman.lyx cvs version 1.120 but later removed
22615  as this broke the build system on Sourceforge (pdf-file was broken.
22616  pdflatex does not accept eps files).
22617 \layout Standard
22618
22619 The
22620 \emph on
22621 p
22622 \emph default
22623 ortable
22624 \emph on
22625 n
22626 \emph default
22627 etwork
22628 \emph on
22629 g
22630 \emph default
22631 raphics File
22632 \size footnotesize
22633
22634 \begin_inset LatexCommand \url{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/doc/figures/ddd_example.png}
22635
22636 \end_inset
22637
22638
22639 \size default
22640  shows a screenshot of a debugging session with DDD
22641 \begin_inset LatexCommand \index{DDD (debugger)}
22642
22643 \end_inset
22644
22645  (Unix only) on a simulated 8032.
22646  The debugging session might not run as smoothly as the screenshot suggests.
22647  The debugger allows setting of breakpoints, displaying and changing variables,
22648  single stepping through C and assembler code.
22649
22650 \newline
22651 The source was compiled with
22652 \family sans
22653 \series bold
22654
22655 \newline
22656
22657 \newline
22658 sdcc -
22659 \family default
22660 \series default
22661
22662 \begin_inset ERT
22663 status Collapsed
22664
22665 \layout Standard
22666
22667 \backslash
22668 /
22669 \end_inset
22670
22671
22672 \family sans
22673 \series bold
22674 -debug ddd_example.c
22675 \family default
22676 \series default
22677
22678 \family sans
22679 \series bold
22680
22681 \newline
22682
22683 \family default
22684 \series default
22685
22686 \newline
22687 and DDD was invoked with
22688 \family sans
22689 \series bold
22690
22691 \newline
22692
22693 \newline
22694 ddd -debugger 'sdcdb -cpu 8032 ddd_example'
22695 \layout Subsection
22696
22697 Interfacing SDCDB with XEmacs
22698 \begin_inset LatexCommand \index{XEmacs}
22699
22700 \end_inset
22701
22702
22703 \begin_inset LatexCommand \index{Emacs}
22704
22705 \end_inset
22706
22707
22708 \layout Standard
22709
22710 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
22711  sdcdb.el and sdcdbsrc.el.
22712  These two files can be found in the $(prefix)/bin directory after the installat
22713 ion is complete.
22714  These files need to be loaded into XEmacs for the interface to work.
22715  This can be done at XEmacs startup time by inserting the following into
22716  your '.xemacs' file (which can be found in your HOME directory):
22717 \newline
22718
22719 \newline
22720
22721 \family typewriter
22722 (load-file sdcdbsrc.el)
22723 \family default
22724
22725 \newline
22726
22727 \newline
22728 .xemacs is a lisp file so the () around the command is REQUIRED.
22729  The files can also be loaded dynamically while XEmacs is running, set the
22730  environment variable 'EMACSLOADPATH' to the installation bin directory
22731  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
22732  To start the interface enter the following command:
22733 \newline
22734
22735 \newline
22736
22737 \family sans
22738 \series bold
22739 ESC-x sdcdbsrc
22740 \family default
22741 \series default
22742
22743 \newline
22744
22745 \newline
22746 You will prompted to enter the file name to be debugged.
22747
22748 \newline
22749
22750 \newline
22751 The command line options that are passed to the simulator directly are bound
22752  to default values in the file sdcdbsrc.el.
22753  The variables are listed below, these values maybe changed as required.
22754 \layout Itemize
22755
22756 sdcdbsrc-cpu-type '51
22757 \layout Itemize
22758
22759 sdcdbsrc-frequency '11059200
22760 \layout Itemize
22761
22762 sdcdbsrc-serial nil
22763 \layout Standard
22764
22765 The following is a list of key mapping for the debugger interface.
22766 \layout Standard
22767
22768 \SpecialChar ~
22769
22770 \family typewriter
22771
22772 \newline
22773 ;;\SpecialChar ~
22774 Current Listing ::
22775 \newline
22776 ;;key\SpecialChar ~
22777 \SpecialChar ~
22778 \SpecialChar ~
22779 \SpecialChar ~
22780 \SpecialChar ~
22781 \SpecialChar ~
22782 \SpecialChar ~
22783 \SpecialChar ~
22784 \SpecialChar ~
22785 \SpecialChar ~
22786 \SpecialChar ~
22787 \SpecialChar ~
22788 \SpecialChar ~
22789 \SpecialChar ~
22790 binding\SpecialChar ~
22791 \SpecialChar ~
22792 \SpecialChar ~
22793 \SpecialChar ~
22794 \SpecialChar ~
22795 \SpecialChar ~
22796 \SpecialChar ~
22797 \SpecialChar ~
22798 \SpecialChar ~
22799 \SpecialChar ~
22800 \SpecialChar ~
22801 \SpecialChar ~
22802 \SpecialChar ~
22803 \SpecialChar ~
22804 \SpecialChar ~
22805 \SpecialChar ~
22806 \SpecialChar ~
22807 \SpecialChar ~
22808 \SpecialChar ~
22809 \SpecialChar ~
22810 \SpecialChar ~
22811 \SpecialChar ~
22812 Comment
22813 \newline
22814 ;;---\SpecialChar ~
22815 \SpecialChar ~
22816 \SpecialChar ~
22817 \SpecialChar ~
22818 \SpecialChar ~
22819 \SpecialChar ~
22820 \SpecialChar ~
22821 \SpecialChar ~
22822 \SpecialChar ~
22823 \SpecialChar ~
22824 \SpecialChar ~
22825 \SpecialChar ~
22826 \SpecialChar ~
22827 \SpecialChar ~
22828 -------\SpecialChar ~
22829 \SpecialChar ~
22830 \SpecialChar ~
22831 \SpecialChar ~
22832 \SpecialChar ~
22833 \SpecialChar ~
22834 \SpecialChar ~
22835 \SpecialChar ~
22836 \SpecialChar ~
22837 \SpecialChar ~
22838 \SpecialChar ~
22839 \SpecialChar ~
22840 \SpecialChar ~
22841 \SpecialChar ~
22842 \SpecialChar ~
22843 \SpecialChar ~
22844 \SpecialChar ~
22845 \SpecialChar ~
22846 \SpecialChar ~
22847 \SpecialChar ~
22848 \SpecialChar ~
22849 \SpecialChar ~
22850 -------
22851 \newline
22852 ;;
22853 \newline
22854 ;;\SpecialChar ~
22855 n\SpecialChar ~
22856 \SpecialChar ~
22857 \SpecialChar ~
22858 \SpecialChar ~
22859 \SpecialChar ~
22860 \SpecialChar ~
22861 \SpecialChar ~
22862 \SpecialChar ~
22863 \SpecialChar ~
22864 \SpecialChar ~
22865 \SpecialChar ~
22866 \SpecialChar ~
22867 \SpecialChar ~
22868 \SpecialChar ~
22869 \SpecialChar ~
22870 sdcdb-next-from-src\SpecialChar ~
22871 \SpecialChar ~
22872 \SpecialChar ~
22873 \SpecialChar ~
22874 \SpecialChar ~
22875 \SpecialChar ~
22876 \SpecialChar ~
22877 \SpecialChar ~
22878 \SpecialChar ~
22879 \SpecialChar ~
22880 SDCDB next command
22881 \newline
22882 ;;\SpecialChar ~
22883 b\SpecialChar ~
22884 \SpecialChar ~
22885 \SpecialChar ~
22886 \SpecialChar ~
22887 \SpecialChar ~
22888 \SpecialChar ~
22889 \SpecialChar ~
22890 \SpecialChar ~
22891 \SpecialChar ~
22892 \SpecialChar ~
22893 \SpecialChar ~
22894 \SpecialChar ~
22895 \SpecialChar ~
22896 \SpecialChar ~
22897 \SpecialChar ~
22898 sdcdb-back-from-src\SpecialChar ~
22899 \SpecialChar ~
22900 \SpecialChar ~
22901 \SpecialChar ~
22902 \SpecialChar ~
22903 \SpecialChar ~
22904 \SpecialChar ~
22905 \SpecialChar ~
22906 \SpecialChar ~
22907 \SpecialChar ~
22908 SDCDB back command
22909 \newline
22910 ;;\SpecialChar ~
22911 c\SpecialChar ~
22912 \SpecialChar ~
22913 \SpecialChar ~
22914 \SpecialChar ~
22915 \SpecialChar ~
22916 \SpecialChar ~
22917 \SpecialChar ~
22918 \SpecialChar ~
22919 \SpecialChar ~
22920 \SpecialChar ~
22921 \SpecialChar ~
22922 \SpecialChar ~
22923 \SpecialChar ~
22924 \SpecialChar ~
22925 \SpecialChar ~
22926 sdcdb-cont-from-src\SpecialChar ~
22927 \SpecialChar ~
22928 \SpecialChar ~
22929 \SpecialChar ~
22930 \SpecialChar ~
22931 \SpecialChar ~
22932 \SpecialChar ~
22933 \SpecialChar ~
22934 \SpecialChar ~
22935 \SpecialChar ~
22936 SDCDB continue command
22937 \newline
22938 ;;\SpecialChar ~
22939 s\SpecialChar ~
22940 \SpecialChar ~
22941 \SpecialChar ~
22942 \SpecialChar ~
22943 \SpecialChar ~
22944 \SpecialChar ~
22945 \SpecialChar ~
22946 \SpecialChar ~
22947 \SpecialChar ~
22948 \SpecialChar ~
22949 \SpecialChar ~
22950 \SpecialChar ~
22951 \SpecialChar ~
22952 \SpecialChar ~
22953 \SpecialChar ~
22954 sdcdb-step-from-src\SpecialChar ~
22955 \SpecialChar ~
22956 \SpecialChar ~
22957 \SpecialChar ~
22958 \SpecialChar ~
22959 \SpecialChar ~
22960 \SpecialChar ~
22961 \SpecialChar ~
22962 \SpecialChar ~
22963 \SpecialChar ~
22964 SDCDB step command
22965 \newline
22966 ;;\SpecialChar ~
22967 ?\SpecialChar ~
22968 \SpecialChar ~
22969 \SpecialChar ~
22970 \SpecialChar ~
22971 \SpecialChar ~
22972 \SpecialChar ~
22973 \SpecialChar ~
22974 \SpecialChar ~
22975 \SpecialChar ~
22976 \SpecialChar ~
22977 \SpecialChar ~
22978 \SpecialChar ~
22979 \SpecialChar ~
22980 \SpecialChar ~
22981 \SpecialChar ~
22982 sdcdb-whatis-c-sexp\SpecialChar ~
22983 \SpecialChar ~
22984 \SpecialChar ~
22985 \SpecialChar ~
22986 \SpecialChar ~
22987 \SpecialChar ~
22988 \SpecialChar ~
22989 \SpecialChar ~
22990 \SpecialChar ~
22991 \SpecialChar ~
22992 SDCDB ptypecommand for data at
22993 \newline
22994 ;;\SpecialChar ~
22995 \SpecialChar ~
22996 \SpecialChar ~
22997 \SpecialChar ~
22998 \SpecialChar ~
22999 \SpecialChar ~
23000 \SpecialChar ~
23001 \SpecialChar ~
23002 \SpecialChar ~
23003 \SpecialChar ~
23004 \SpecialChar ~
23005 \SpecialChar ~
23006 \SpecialChar ~
23007 \SpecialChar ~
23008 \SpecialChar ~
23009 \SpecialChar ~
23010 \SpecialChar ~
23011 \SpecialChar ~
23012 \SpecialChar ~
23013 \SpecialChar ~
23014 \SpecialChar ~
23015 \SpecialChar ~
23016 \SpecialChar ~
23017 \SpecialChar ~
23018 \SpecialChar ~
23019 \SpecialChar ~
23020 \SpecialChar ~
23021 \SpecialChar ~
23022 \SpecialChar ~
23023 \SpecialChar ~
23024 \SpecialChar ~
23025 \SpecialChar ~
23026 \SpecialChar ~
23027 \SpecialChar ~
23028 \SpecialChar ~
23029 \SpecialChar ~
23030 \SpecialChar ~
23031 \SpecialChar ~
23032 \SpecialChar ~
23033 \SpecialChar ~
23034 \SpecialChar ~
23035 \SpecialChar ~
23036 \SpecialChar ~
23037 \SpecialChar ~
23038 \SpecialChar ~
23039 \SpecialChar ~
23040 \SpecialChar ~
23041 buffer point
23042 \newline
23043 ;;\SpecialChar ~
23044 x\SpecialChar ~
23045 \SpecialChar ~
23046 \SpecialChar ~
23047 \SpecialChar ~
23048 \SpecialChar ~
23049 \SpecialChar ~
23050 \SpecialChar ~
23051 \SpecialChar ~
23052 \SpecialChar ~
23053 \SpecialChar ~
23054 \SpecialChar ~
23055 \SpecialChar ~
23056 \SpecialChar ~
23057 \SpecialChar ~
23058 \SpecialChar ~
23059 sdcdbsrc-delete\SpecialChar ~
23060 \SpecialChar ~
23061 \SpecialChar ~
23062 \SpecialChar ~
23063 \SpecialChar ~
23064 \SpecialChar ~
23065 \SpecialChar ~
23066 \SpecialChar ~
23067 \SpecialChar ~
23068 \SpecialChar ~
23069 \SpecialChar ~
23070 \SpecialChar ~
23071 \SpecialChar ~
23072 \SpecialChar ~
23073 SDCDB Delete all breakpoints if no arg
23074 \newline
23075 ;;\SpecialChar ~
23076 \SpecialChar ~
23077 \SpecialChar ~
23078 \SpecialChar ~
23079 \SpecialChar ~
23080 \SpecialChar ~
23081 \SpecialChar ~
23082 \SpecialChar ~
23083 \SpecialChar ~
23084 \SpecialChar ~
23085 \SpecialChar ~
23086 \SpecialChar ~
23087 \SpecialChar ~
23088 \SpecialChar ~
23089 \SpecialChar ~
23090 \SpecialChar ~
23091 \SpecialChar ~
23092 \SpecialChar ~
23093 \SpecialChar ~
23094 \SpecialChar ~
23095 \SpecialChar ~
23096 \SpecialChar ~
23097 \SpecialChar ~
23098 \SpecialChar ~
23099 \SpecialChar ~
23100 \SpecialChar ~
23101 \SpecialChar ~
23102 \SpecialChar ~
23103 \SpecialChar ~
23104 \SpecialChar ~
23105 \SpecialChar ~
23106 \SpecialChar ~
23107 \SpecialChar ~
23108 \SpecialChar ~
23109 \SpecialChar ~
23110 \SpecialChar ~
23111 \SpecialChar ~
23112 \SpecialChar ~
23113 \SpecialChar ~
23114 \SpecialChar ~
23115 \SpecialChar ~
23116 \SpecialChar ~
23117 \SpecialChar ~
23118 \SpecialChar ~
23119 \SpecialChar ~
23120 \SpecialChar ~
23121 \SpecialChar ~
23122 given or delete arg (C-u arg x)
23123 \newline
23124 ;;\SpecialChar ~
23125 m\SpecialChar ~
23126 \SpecialChar ~
23127 \SpecialChar ~
23128 \SpecialChar ~
23129 \SpecialChar ~
23130 \SpecialChar ~
23131 \SpecialChar ~
23132 \SpecialChar ~
23133 \SpecialChar ~
23134 \SpecialChar ~
23135 \SpecialChar ~
23136 \SpecialChar ~
23137 \SpecialChar ~
23138 \SpecialChar ~
23139 \SpecialChar ~
23140 sdcdbsrc-frame\SpecialChar ~
23141 \SpecialChar ~
23142 \SpecialChar ~
23143 \SpecialChar ~
23144 \SpecialChar ~
23145 \SpecialChar ~
23146 \SpecialChar ~
23147 \SpecialChar ~
23148 \SpecialChar ~
23149 \SpecialChar ~
23150 \SpecialChar ~
23151 \SpecialChar ~
23152 \SpecialChar ~
23153 \SpecialChar ~
23154 \SpecialChar ~
23155 SDCDB Display current frame if no arg,
23156 \newline
23157 ;;\SpecialChar ~
23158 \SpecialChar ~
23159 \SpecialChar ~
23160 \SpecialChar ~
23161 \SpecialChar ~
23162 \SpecialChar ~
23163 \SpecialChar ~
23164 \SpecialChar ~
23165 \SpecialChar ~
23166 \SpecialChar ~
23167 \SpecialChar ~
23168 \SpecialChar ~
23169 \SpecialChar ~
23170 \SpecialChar ~
23171 \SpecialChar ~
23172 \SpecialChar ~
23173 \SpecialChar ~
23174 \SpecialChar ~
23175 \SpecialChar ~
23176 \SpecialChar ~
23177 \SpecialChar ~
23178 \SpecialChar ~
23179 \SpecialChar ~
23180 \SpecialChar ~
23181 \SpecialChar ~
23182 \SpecialChar ~
23183 \SpecialChar ~
23184 \SpecialChar ~
23185 \SpecialChar ~
23186 \SpecialChar ~
23187 \SpecialChar ~
23188 \SpecialChar ~
23189 \SpecialChar ~
23190 \SpecialChar ~
23191 \SpecialChar ~
23192 \SpecialChar ~
23193 \SpecialChar ~
23194 \SpecialChar ~
23195 \SpecialChar ~
23196 \SpecialChar ~
23197 \SpecialChar ~
23198 \SpecialChar ~
23199 \SpecialChar ~
23200 \SpecialChar ~
23201 \SpecialChar ~
23202 \SpecialChar ~
23203 \SpecialChar ~
23204 given or display frame arg
23205 \newline
23206 ;;\SpecialChar ~
23207 \SpecialChar ~
23208 \SpecialChar ~
23209 \SpecialChar ~
23210 \SpecialChar ~
23211 \SpecialChar ~
23212 \SpecialChar ~
23213 \SpecialChar ~
23214 \SpecialChar ~
23215 \SpecialChar ~
23216 \SpecialChar ~
23217 \SpecialChar ~
23218 \SpecialChar ~
23219 \SpecialChar ~
23220 \SpecialChar ~
23221 \SpecialChar ~
23222 \SpecialChar ~
23223 \SpecialChar ~
23224 \SpecialChar ~
23225 \SpecialChar ~
23226 \SpecialChar ~
23227 \SpecialChar ~
23228 \SpecialChar ~
23229 \SpecialChar ~
23230 \SpecialChar ~
23231 \SpecialChar ~
23232 \SpecialChar ~
23233 \SpecialChar ~
23234 \SpecialChar ~
23235 \SpecialChar ~
23236 \SpecialChar ~
23237 \SpecialChar ~
23238 \SpecialChar ~
23239 \SpecialChar ~
23240 \SpecialChar ~
23241 \SpecialChar ~
23242 \SpecialChar ~
23243 \SpecialChar ~
23244 \SpecialChar ~
23245 \SpecialChar ~
23246 \SpecialChar ~
23247 \SpecialChar ~
23248 \SpecialChar ~
23249 \SpecialChar ~
23250 \SpecialChar ~
23251 \SpecialChar ~
23252 \SpecialChar ~
23253 buffer point
23254 \newline
23255 ;;\SpecialChar ~
23256 !\SpecialChar ~
23257 \SpecialChar ~
23258 \SpecialChar ~
23259 \SpecialChar ~
23260 \SpecialChar ~
23261 \SpecialChar ~
23262 \SpecialChar ~
23263 \SpecialChar ~
23264 \SpecialChar ~
23265 \SpecialChar ~
23266 \SpecialChar ~
23267 \SpecialChar ~
23268 \SpecialChar ~
23269 \SpecialChar ~
23270 \SpecialChar ~
23271 sdcdbsrc-goto-sdcdb\SpecialChar ~
23272 \SpecialChar ~
23273 \SpecialChar ~
23274 \SpecialChar ~
23275 \SpecialChar ~
23276 \SpecialChar ~
23277 \SpecialChar ~
23278 \SpecialChar ~
23279 \SpecialChar ~
23280 \SpecialChar ~
23281 Goto the SDCDB output buffer
23282 \newline
23283 ;;\SpecialChar ~
23284 p\SpecialChar ~
23285 \SpecialChar ~
23286 \SpecialChar ~
23287 \SpecialChar ~
23288 \SpecialChar ~
23289 \SpecialChar ~
23290 \SpecialChar ~
23291 \SpecialChar ~
23292 \SpecialChar ~
23293 \SpecialChar ~
23294 \SpecialChar ~
23295 \SpecialChar ~
23296 \SpecialChar ~
23297 \SpecialChar ~
23298 \SpecialChar ~
23299 sdcdb-print-c-sexp\SpecialChar ~
23300 \SpecialChar ~
23301 \SpecialChar ~
23302 \SpecialChar ~
23303 \SpecialChar ~
23304 \SpecialChar ~
23305 \SpecialChar ~
23306 \SpecialChar ~
23307 \SpecialChar ~
23308 \SpecialChar ~
23309 \SpecialChar ~
23310 SDCDB print command for data at
23311 \newline
23312 ;;\SpecialChar ~
23313 \SpecialChar ~
23314 \SpecialChar ~
23315 \SpecialChar ~
23316 \SpecialChar ~
23317 \SpecialChar ~
23318 \SpecialChar ~
23319 \SpecialChar ~
23320 \SpecialChar ~
23321 \SpecialChar ~
23322 \SpecialChar ~
23323 \SpecialChar ~
23324 \SpecialChar ~
23325 \SpecialChar ~
23326 \SpecialChar ~
23327 \SpecialChar ~
23328 \SpecialChar ~
23329 \SpecialChar ~
23330 \SpecialChar ~
23331 \SpecialChar ~
23332 \SpecialChar ~
23333 \SpecialChar ~
23334 \SpecialChar ~
23335 \SpecialChar ~
23336 \SpecialChar ~
23337 \SpecialChar ~
23338 \SpecialChar ~
23339 \SpecialChar ~
23340 \SpecialChar ~
23341 \SpecialChar ~
23342 \SpecialChar ~
23343 \SpecialChar ~
23344 \SpecialChar ~
23345 \SpecialChar ~
23346 \SpecialChar ~
23347 \SpecialChar ~
23348 \SpecialChar ~
23349 \SpecialChar ~
23350 \SpecialChar ~
23351 \SpecialChar ~
23352 \SpecialChar ~
23353 \SpecialChar ~
23354 \SpecialChar ~
23355 \SpecialChar ~
23356 \SpecialChar ~
23357 \SpecialChar ~
23358 \SpecialChar ~
23359 buffer point
23360 \newline
23361 ;;\SpecialChar ~
23362 g\SpecialChar ~
23363 \SpecialChar ~
23364 \SpecialChar ~
23365 \SpecialChar ~
23366 \SpecialChar ~
23367 \SpecialChar ~
23368 \SpecialChar ~
23369 \SpecialChar ~
23370 \SpecialChar ~
23371 \SpecialChar ~
23372 \SpecialChar ~
23373 \SpecialChar ~
23374 \SpecialChar ~
23375 \SpecialChar ~
23376 \SpecialChar ~
23377 sdcdbsrc-goto-sdcdb\SpecialChar ~
23378 \SpecialChar ~
23379 \SpecialChar ~
23380 \SpecialChar ~
23381 \SpecialChar ~
23382 \SpecialChar ~
23383 \SpecialChar ~
23384 \SpecialChar ~
23385 \SpecialChar ~
23386 \SpecialChar ~
23387 Goto the SDCDB output buffer
23388 \newline
23389 ;;\SpecialChar ~
23390 t\SpecialChar ~
23391 \SpecialChar ~
23392 \SpecialChar ~
23393 \SpecialChar ~
23394 \SpecialChar ~
23395 \SpecialChar ~
23396 \SpecialChar ~
23397 \SpecialChar ~
23398 \SpecialChar ~
23399 \SpecialChar ~
23400 \SpecialChar ~
23401 \SpecialChar ~
23402 \SpecialChar ~
23403 \SpecialChar ~
23404 \SpecialChar ~
23405 sdcdbsrc-mode\SpecialChar ~
23406 \SpecialChar ~
23407 \SpecialChar ~
23408 \SpecialChar ~
23409 \SpecialChar ~
23410 \SpecialChar ~
23411 \SpecialChar ~
23412 \SpecialChar ~
23413 \SpecialChar ~
23414 \SpecialChar ~
23415 \SpecialChar ~
23416 \SpecialChar ~
23417 \SpecialChar ~
23418 \SpecialChar ~
23419 \SpecialChar ~
23420 \SpecialChar ~
23421 Toggles Sdcdbsrc mode (turns it off)
23422 \newline
23423 ;;
23424 \newline
23425 ;;\SpecialChar ~
23426 C-c\SpecialChar ~
23427 C-f\SpecialChar ~
23428 \SpecialChar ~
23429 \SpecialChar ~
23430 \SpecialChar ~
23431 \SpecialChar ~
23432 \SpecialChar ~
23433 \SpecialChar ~
23434 \SpecialChar ~
23435 \SpecialChar ~
23436 sdcdb-finish-from-src\SpecialChar ~
23437 \SpecialChar ~
23438 \SpecialChar ~
23439 \SpecialChar ~
23440 \SpecialChar ~
23441 \SpecialChar ~
23442 \SpecialChar ~
23443 \SpecialChar ~
23444 SDCDB finish command
23445 \newline
23446 ;;
23447 \newline
23448 ;;\SpecialChar ~
23449 C-x\SpecialChar ~
23450 SPC\SpecialChar ~
23451 \SpecialChar ~
23452 \SpecialChar ~
23453 \SpecialChar ~
23454 \SpecialChar ~
23455 \SpecialChar ~
23456 \SpecialChar ~
23457 \SpecialChar ~
23458 \SpecialChar ~
23459 sdcdb-break\SpecialChar ~
23460 \SpecialChar ~
23461 \SpecialChar ~
23462 \SpecialChar ~
23463 \SpecialChar ~
23464 \SpecialChar ~
23465 \SpecialChar ~
23466 \SpecialChar ~
23467 \SpecialChar ~
23468 \SpecialChar ~
23469 \SpecialChar ~
23470 \SpecialChar ~
23471 \SpecialChar ~
23472 \SpecialChar ~
23473 \SpecialChar ~
23474 \SpecialChar ~
23475 \SpecialChar ~
23476 \SpecialChar ~
23477 Set break for line with point
23478 \newline
23479 ;;\SpecialChar ~
23480 ESC\SpecialChar ~
23481 t\SpecialChar ~
23482 \SpecialChar ~
23483 \SpecialChar ~
23484 \SpecialChar ~
23485 \SpecialChar ~
23486 \SpecialChar ~
23487 \SpecialChar ~
23488 \SpecialChar ~
23489 \SpecialChar ~
23490 \SpecialChar ~
23491 \SpecialChar ~
23492 sdcdbsrc-mode\SpecialChar ~
23493 \SpecialChar ~
23494 \SpecialChar ~
23495 \SpecialChar ~
23496 \SpecialChar ~
23497 \SpecialChar ~
23498 \SpecialChar ~
23499 \SpecialChar ~
23500 \SpecialChar ~
23501 \SpecialChar ~
23502 \SpecialChar ~
23503 \SpecialChar ~
23504 \SpecialChar ~
23505 \SpecialChar ~
23506 \SpecialChar ~
23507 \SpecialChar ~
23508 Toggle Sdcdbsrc mode
23509 \newline
23510 ;;\SpecialChar ~
23511 ESC\SpecialChar ~
23512 m\SpecialChar ~
23513 \SpecialChar ~
23514 \SpecialChar ~
23515 \SpecialChar ~
23516 \SpecialChar ~
23517 \SpecialChar ~
23518 \SpecialChar ~
23519 \SpecialChar ~
23520 \SpecialChar ~
23521 \SpecialChar ~
23522 \SpecialChar ~
23523 sdcdbsrc-srcmode\SpecialChar ~
23524 \SpecialChar ~
23525 \SpecialChar ~
23526 \SpecialChar ~
23527 \SpecialChar ~
23528 \SpecialChar ~
23529 \SpecialChar ~
23530 \SpecialChar ~
23531 \SpecialChar ~
23532 \SpecialChar ~
23533 \SpecialChar ~
23534 \SpecialChar ~
23535 \SpecialChar ~
23536 Toggle list mode
23537 \newline
23538 ;;
23539 \newline
23540
23541 \layout Chapter
23542 \pagebreak_top
23543 TIPS
23544 \layout Standard
23545
23546 Here are a few guidelines that will help the compiler generate more efficient
23547  code, some of the tips are specific to this compiler others are generally
23548  good programming practice.
23549 \layout Itemize
23550
23551 Use the smallest data type to represent your data-value.
23552  If it is known in advance that the value is going to be less than 256 then
23553  use an 'unsigned char' instead of a 'short' or 'int'.
23554  Please note, that ANSI C requires both signed and unsigned chars to be
23555  promoted to 'signed int'
23556 \begin_inset LatexCommand \index{promotion to signed int}
23557
23558 \end_inset
23559
23560
23561 \begin_inset Marginal
23562 collapsed true
23563
23564 \layout Standard
23565
23566
23567 \series bold
23568 \SpecialChar ~
23569 !
23570 \end_inset
23571
23572  before doing any operation.
23573  This promotion
23574 \begin_inset LatexCommand \index{type promotion}
23575
23576 \end_inset
23577
23578
23579 \begin_inset LatexCommand \label{type promotion}
23580
23581 \end_inset
23582
23583  can be omitted, if the result is the same.
23584  The effect of the promotion rules together with the sign-extension is often
23585  surprising:
23586 \begin_deeper
23587 \layout Verse
23588
23589
23590 \family typewriter
23591 unsigned char uc = 0xfe;
23592 \newline
23593 if (uc * uc < 0) /* this is true! */
23594 \newline
23595 {
23596 \newline
23597 \SpecialChar ~
23598 \SpecialChar ~
23599 \SpecialChar ~
23600 \SpecialChar ~
23601 ....
23602 \newline
23603 }
23604 \layout Standard
23605
23606
23607 \family typewriter
23608 uc * uc
23609 \family default
23610  is evaluated as
23611 \family typewriter
23612 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
23613 \family default
23614 .
23615
23616 \newline
23617 Another one:
23618 \layout Verse
23619
23620
23621 \family typewriter
23622 (unsigned char) -12 / (signed char) -3 = ...
23623 \layout Standard
23624
23625 No, the result is not 4:
23626 \layout Verse
23627
23628
23629 \family typewriter
23630 (int) (unsigned char) -12 / (int) (signed char) -3 =
23631 \newline
23632 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
23633 \newline
23634 (int) 0x00f4 / (int) 0xfffd =
23635 \newline
23636 (int) 0x00f4 / (int) 0xfffd =
23637 \newline
23638 (int) 244 / (int) -3 =
23639 \newline
23640 (int) -81 = (int) 0xffaf;
23641 \layout Standard
23642
23643 Don't complain, that gcc gives you a different result.
23644  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
23645  Therefore the results are different.
23646 \newline
23647 From
23648 \begin_inset Quotes sld
23649 \end_inset
23650
23651 comp.lang.c FAQ
23652 \begin_inset Quotes srd
23653 \end_inset
23654
23655 :
23656 \layout Quote
23657
23658
23659 \emph on
23660 If well-defined overflow characteristics are important and negative values
23661  are not, or if you want to steer clear of sign-extension problems when
23662  manipulating bits or bytes, use one of the corresponding unsigned types.
23663  (Beware when mixing signed and unsigned values in expressions, though.)
23664 \newline
23665 Although character types (especially unsigned char) can be used as "tiny"
23666  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
23667 ble sign extension and increased code size.
23668 \end_deeper
23669 \layout Itemize
23670
23671 Use unsigned when it is known in advance that the value is not going to
23672  be negative.
23673  This helps especially if you are doing division or multiplication, bit-shifting
23674  or are using an array index.
23675 \layout Itemize
23676
23677 NEVER jump into a LOOP.
23678 \layout Itemize
23679
23680 Declare the variables to be local
23681 \begin_inset LatexCommand \index{local variables}
23682
23683 \end_inset
23684
23685  whenever possible, especially loop control variables (induction).
23686 \layout Itemize
23687
23688 Have a look at the assembly listing to get a
23689 \begin_inset Quotes sld
23690 \end_inset
23691
23692 feeling
23693 \begin_inset Quotes srd
23694 \end_inset
23695
23696  for the code generation.
23697 \layout Section
23698
23699 Porting code from or to other compilers
23700 \begin_inset LatexCommand \label{sec:Porting-code-to-other-compilers}
23701
23702 \end_inset
23703
23704
23705 \layout Itemize
23706
23707 check whether endianness of the compilers differs and adapt where needed.
23708 \layout Itemize
23709
23710 check the device specific header files
23711 \begin_inset LatexCommand \index{Header files}
23712
23713 \end_inset
23714
23715
23716 \begin_inset LatexCommand \index{Include files}
23717
23718 \end_inset
23719
23720  for compiler specific syntax.
23721  Eventually include the file <compiler.h
23722 \begin_inset LatexCommand \index{compiler.h (include file)}
23723
23724 \end_inset
23725
23726 >
23727 \begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/device/include/mcs51/compiler.h?view=markup}
23728
23729 \end_inset
23730
23731  to allow using common header files.
23732  (see f.e.
23733  cc2510fx.h
23734 \begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/device/include/mcs51/cc2510fx.h?view=markup}
23735
23736 \end_inset
23737
23738 ).
23739 \layout Itemize
23740
23741 check whether the startup code contains the correct initialization (watchdog,
23742  peripherals).
23743 \layout Itemize
23744
23745 check whether the sizes of short, int, long match.
23746 \layout Itemize
23747
23748 check if some 16 or 32 bit hardware registers require a specific addressing
23749  order (least significant or most significant byte first) and adapt if needed
23750  (
23751 \emph on
23752 first
23753 \emph default
23754  and
23755 \emph on
23756 last
23757 \emph default
23758  relate to time and not to lower/upper memory location here, so this is
23759
23760 \emph on
23761 not
23762 \emph default
23763  the same as endianness).
23764 \layout Itemize
23765
23766 check whether the keyword
23767 \emph on
23768 volatile
23769 \emph default
23770  is used where needed.
23771  The compilers might differ in their optimization characteristics (as different
23772  versions of the same compiler might also use more clever optimizations
23773  this is good idea anyway).
23774  See section
23775 \begin_inset LatexCommand \ref{sub:Common-interrupt-pitfall-volatile}
23776
23777 \end_inset
23778
23779 .
23780 \layout Itemize
23781
23782 check that the compilers are not told to supress warnings.
23783 \layout Itemize
23784
23785 check and convert compiler specific extensions (interrupts, memory areas,
23786  pragmas etc.).
23787 \layout Itemize
23788
23789 check for differences in type promotion.
23790  Especially check for math operations on
23791 \family typewriter
23792 char
23793 \family default
23794  or
23795 \family typewriter
23796 unsigned char
23797 \family default
23798  variables.
23799  For the sake of C99 compatibility SDCC will probably promote these to
23800 \family typewriter
23801 int
23802 \family default
23803  more often than other compilers.
23804  Eventually insert explicit casts to
23805 \family typewriter
23806 (char)
23807 \family default
23808 or
23809 \family typewriter
23810  (unsigned char)
23811 \family default
23812 .
23813  Also check that the ~\SpecialChar ~
23814 operator
23815 \begin_inset LatexCommand \index{\~\/ Operator}
23816
23817 \end_inset
23818
23819  is not used on
23820 \family typewriter
23821 bit
23822 \begin_inset LatexCommand \index{bit}
23823
23824 \end_inset
23825
23826
23827 \family default
23828  variables, use the !\SpecialChar ~
23829 operator instead.
23830  See sections
23831 \begin_inset LatexCommand \ref{type promotion}
23832
23833 \end_inset
23834
23835  and
23836 \begin_inset LatexCommand \ref{sec:Compatibility-with-previous}
23837
23838 \end_inset
23839
23840 .
23841 \layout Itemize
23842
23843 check the assembly code generated for interrupt routines (f.e.
23844  for calls to possibly non-reentrant library functions).
23845 \layout Itemize
23846
23847 check whether timing loops result in proper timing (or preferably consider
23848  a rewrite of the code with timer based delays instead).
23849 \layout Itemize
23850
23851 check for differences in printf parameters (some compilers push (va_arg
23852 \begin_inset LatexCommand \index{vararg, va\_arg}
23853
23854 \end_inset
23855
23856 ) char variables as
23857 \family typewriter
23858 int
23859 \family default
23860  others push them as
23861 \family typewriter
23862 char
23863 \family default
23864 .
23865  See section
23866 \begin_inset LatexCommand \ref{sec:Compatibility-with-previous}
23867
23868 \end_inset
23869
23870 ).
23871 \layout Itemize
23872
23873 check the resulting memory map
23874 \begin_inset LatexCommand \index{Memory map}
23875
23876 \end_inset
23877
23878 .
23879  Usage of different memory spaces: code, stack, data (for mcs51/ds390 additional
23880 ly idata, pdata, xdata).
23881  Eventually check if unexpected library functions are included.
23882 \layout Section
23883
23884 Tools
23885 \begin_inset LatexCommand \index{Tools}
23886
23887 \end_inset
23888
23889  included in the distribution
23890 \layout Standard
23891 \align left
23892
23893 \begin_inset  Tabular
23894 <lyxtabular version="3" rows="12" columns="3">
23895 <features>
23896 <column alignment="left" valignment="top" leftline="true" width="0pt">
23897 <column alignment="left" valignment="top" leftline="true" width="0pt">
23898 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
23899 <row topline="true" bottomline="true">
23900 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23901 \begin_inset Text
23902
23903 \layout Standard
23904
23905
23906 \series bold
23907 Name
23908 \end_inset
23909 </cell>
23910 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23911 \begin_inset Text
23912
23913 \layout Standard
23914
23915
23916 \series bold
23917 Purpose
23918 \end_inset
23919 </cell>
23920 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23921 \begin_inset Text
23922
23923 \layout Standard
23924
23925
23926 \series bold
23927 Directory
23928 \end_inset
23929 </cell>
23930 </row>
23931 <row topline="true">
23932 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23933 \begin_inset Text
23934
23935 \layout Standard
23936
23937 ucSsim
23938 \end_inset
23939 </cell>
23940 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23941 \begin_inset Text
23942
23943 \layout Standard
23944
23945 Simulator for various architectures
23946 \end_inset
23947 </cell>
23948 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23949 \begin_inset Text
23950
23951 \layout Standard
23952
23953 sdcc/sim/ucsim
23954 \end_inset
23955 </cell>
23956 </row>
23957 <row topline="true">
23958 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23959 \begin_inset Text
23960
23961 \layout Standard
23962
23963 keil2sdcc.pl
23964 \end_inset
23965 </cell>
23966 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23967 \begin_inset Text
23968
23969 \layout Standard
23970
23971 header file
23972 \begin_inset LatexCommand \index{Header files}
23973
23974 \end_inset
23975
23976
23977 \begin_inset LatexCommand \index{Include files}
23978
23979 \end_inset
23980
23981  conversion
23982 \end_inset
23983 </cell>
23984 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23985 \begin_inset Text
23986
23987 \layout Standard
23988
23989 sdcc/support/scripts
23990 \end_inset
23991 </cell>
23992 </row>
23993 <row topline="true">
23994 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23995 \begin_inset Text
23996
23997 \layout Standard
23998
23999 mh2h.c
24000 \end_inset
24001 </cell>
24002 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24003 \begin_inset Text
24004
24005 \layout Standard
24006
24007 header file conversion
24008 \end_inset
24009 </cell>
24010 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24011 \begin_inset Text
24012
24013 \layout Standard
24014
24015 sdcc/support/scripts
24016 \end_inset
24017 </cell>
24018 </row>
24019 <row topline="true">
24020 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24021 \begin_inset Text
24022
24023 \layout Standard
24024
24025 as-gbz80
24026 \end_inset
24027 </cell>
24028 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24029 \begin_inset Text
24030
24031 \layout Standard
24032
24033 Assembler
24034 \end_inset
24035 </cell>
24036 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24037 \begin_inset Text
24038
24039 \layout Standard
24040
24041
24042 \family roman
24043 \series medium
24044 \shape up
24045 \size normal
24046 \emph off
24047 \bar no
24048 \noun off
24049 \color none
24050 sdcc/bin
24051 \end_inset
24052 </cell>
24053 </row>
24054 <row topline="true">
24055 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24056 \begin_inset Text
24057
24058 \layout Standard
24059
24060 as-z80
24061 \end_inset
24062 </cell>
24063 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24064 \begin_inset Text
24065
24066 \layout Standard
24067
24068 Assembler
24069 \end_inset
24070 </cell>
24071 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24072 \begin_inset Text
24073
24074 \layout Standard
24075
24076
24077 \family roman
24078 \series medium
24079 \shape up
24080 \size normal
24081 \emph off
24082 \bar no
24083 \noun off
24084 \color none
24085 sdcc/bin
24086 \end_inset
24087 </cell>
24088 </row>
24089 <row topline="true">
24090 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24091 \begin_inset Text
24092
24093 \layout Standard
24094
24095 asx8051
24096 \end_inset
24097 </cell>
24098 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24099 \begin_inset Text
24100
24101 \layout Standard
24102
24103 Assembler
24104 \end_inset
24105 </cell>
24106 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24107 \begin_inset Text
24108
24109 \layout Standard
24110
24111
24112 \family roman
24113 \series medium
24114 \shape up
24115 \size normal
24116 \emph off
24117 \bar no
24118 \noun off
24119 \color none
24120 sdcc/bin
24121 \end_inset
24122 </cell>
24123 </row>
24124 <row topline="true">
24125 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24126 \begin_inset Text
24127
24128 \layout Standard
24129
24130 SDCDB
24131 \end_inset
24132 </cell>
24133 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24134 \begin_inset Text
24135
24136 \layout Standard
24137
24138 Simulator
24139 \end_inset
24140 </cell>
24141 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24142 \begin_inset Text
24143
24144 \layout Standard
24145
24146
24147 \family roman
24148 \series medium
24149 \shape up
24150 \size normal
24151 \emph off
24152 \bar no
24153 \noun off
24154 \color none
24155 sdcc/bin
24156 \end_inset
24157 </cell>
24158 </row>
24159 <row topline="true">
24160 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24161 \begin_inset Text
24162
24163 \layout Standard
24164
24165 aslink
24166 \end_inset
24167 </cell>
24168 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24169 \begin_inset Text
24170
24171 \layout Standard
24172
24173 Linker
24174 \end_inset
24175 </cell>
24176 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24177 \begin_inset Text
24178
24179 \layout Standard
24180
24181
24182 \family roman
24183 \series medium
24184 \shape up
24185 \size normal
24186 \emph off
24187 \bar no
24188 \noun off
24189 \color none
24190 sdcc/bin
24191 \end_inset
24192 </cell>
24193 </row>
24194 <row topline="true">
24195 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24196 \begin_inset Text
24197
24198 \layout Standard
24199
24200 link-z80
24201 \end_inset
24202 </cell>
24203 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24204 \begin_inset Text
24205
24206 \layout Standard
24207
24208 Linker
24209 \end_inset
24210 </cell>
24211 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24212 \begin_inset Text
24213
24214 \layout Standard
24215
24216
24217 \family roman
24218 \series medium
24219 \shape up
24220 \size normal
24221 \emph off
24222 \bar no
24223 \noun off
24224 \color none
24225 sdcc/bin
24226 \end_inset
24227 </cell>
24228 </row>
24229 <row topline="true">
24230 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24231 \begin_inset Text
24232
24233 \layout Standard
24234
24235 link-gbz80
24236 \end_inset
24237 </cell>
24238 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24239 \begin_inset Text
24240
24241 \layout Standard
24242
24243 Linker
24244 \end_inset
24245 </cell>
24246 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24247 \begin_inset Text
24248
24249 \layout Standard
24250
24251
24252 \family roman
24253 \series medium
24254 \shape up
24255 \size normal
24256 \emph off
24257 \bar no
24258 \noun off
24259 \color none
24260 sdcc/bin
24261 \end_inset
24262 </cell>
24263 </row>
24264 <row topline="true" bottomline="true">
24265 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24266 \begin_inset Text
24267
24268 \layout Standard
24269
24270 packihx
24271 \end_inset
24272 </cell>
24273 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24274 \begin_inset Text
24275
24276 \layout Standard
24277
24278 Intel Hex packer
24279 \begin_inset LatexCommand \index{packihx (tool)}
24280
24281 \end_inset
24282
24283
24284 \end_inset
24285 </cell>
24286 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24287 \begin_inset Text
24288
24289 \layout Standard
24290
24291
24292 \family roman
24293 \series medium
24294 \shape up
24295 \size normal
24296 \emph off
24297 \bar no
24298 \noun off
24299 \color none
24300 sdcc/bin
24301 \end_inset
24302 </cell>
24303 </row>
24304 </lyxtabular>
24305
24306 \end_inset
24307
24308
24309 \newline
24310
24311 \layout Section
24312
24313 Documentation
24314 \begin_inset LatexCommand \index{Documentation}
24315
24316 \end_inset
24317
24318  included in the distribution
24319 \layout Standard
24320 \align left
24321
24322 \begin_inset  Tabular
24323 <lyxtabular version="3" rows="10" columns="2">
24324 <features>
24325 <column alignment="block" valignment="top" leftline="true" width="40col%">
24326 <column alignment="block" valignment="top" leftline="true" rightline="true" width="60col%">
24327 <row topline="true" bottomline="true" endhead="true">
24328 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24329 \begin_inset Text
24330
24331 \layout Standard
24332
24333
24334 \series bold
24335 Subject / Title
24336 \end_inset
24337 </cell>
24338 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24339 \begin_inset Text
24340
24341 \layout Standard
24342
24343
24344 \series bold
24345 Filename / Where to get
24346 \end_inset
24347 </cell>
24348 </row>
24349 <row topline="true">
24350 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24351 \begin_inset Text
24352
24353 \layout Standard
24354
24355 SDCC Compiler User Guide
24356 \end_inset
24357 </cell>
24358 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24359 \begin_inset Text
24360
24361 \layout Standard
24362
24363 You're reading it right now
24364 \emph on
24365  \SpecialChar ~
24366 \SpecialChar ~
24367 \SpecialChar ~
24368
24369 \hfill
24370 online at:
24371 \emph default
24372
24373 \newline
24374
24375 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
24376
24377 \end_inset
24378
24379
24380 \end_inset
24381 </cell>
24382 </row>
24383 <row topline="true">
24384 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24385 \begin_inset Text
24386
24387 \layout Standard
24388
24389 Changelog of SDCC
24390 \end_inset
24391 </cell>
24392 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24393 \begin_inset Text
24394
24395 \layout Standard
24396
24397 sdcc/Changelog
24398 \emph on
24399  \SpecialChar ~
24400 \SpecialChar ~
24401 \SpecialChar ~
24402
24403 \hfill
24404 online at:
24405 \emph default
24406
24407 \newline
24408
24409 \begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/ChangeLog}
24410
24411 \end_inset
24412
24413
24414 \end_inset
24415 </cell>
24416 </row>
24417 <row topline="true">
24418 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24419 \begin_inset Text
24420
24421 \layout Standard
24422
24423 ASXXXX
24424 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
24425
24426 \end_inset
24427
24428
24429 \begin_inset LatexCommand \index{Assembler documentation}
24430
24431 \end_inset
24432
24433  Assemblers and
24434 \newline
24435 ASLINK
24436 \begin_inset LatexCommand \index{aslink}
24437
24438 \end_inset
24439
24440
24441 \begin_inset LatexCommand \index{Linker documentation}
24442
24443 \end_inset
24444
24445  Relocating Linker
24446 \end_inset
24447 </cell>
24448 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24449 \begin_inset Text
24450
24451 \layout Standard
24452
24453 sdcc/as/doc/asxhtm.html
24454 \emph on
24455 \SpecialChar ~
24456 \SpecialChar ~
24457 \SpecialChar ~
24458
24459 \hfill
24460 online at:
24461 \emph default
24462
24463 \newline
24464
24465 \begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/as/doc/asxhtm.html}
24466
24467 \end_inset
24468
24469
24470 \end_inset
24471 </cell>
24472 </row>
24473 <row topline="true">
24474 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24475 \begin_inset Text
24476
24477 \layout Standard
24478
24479 SDCC regression test
24480 \begin_inset LatexCommand \index{Regression test}
24481
24482 \end_inset
24483
24484
24485 \end_inset
24486 </cell>
24487 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24488 \begin_inset Text
24489
24490 \layout Standard
24491
24492 sdcc/doc/test_suite_spec.pdf
24493 \emph on
24494 \SpecialChar ~
24495 \SpecialChar ~
24496 \SpecialChar ~
24497
24498 \hfill
24499 online at:
24500 \emph default
24501
24502 \newline
24503
24504 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/test_suite_spec.pdf}
24505
24506 \end_inset
24507
24508
24509 \end_inset
24510 </cell>
24511 </row>
24512 <row topline="true">
24513 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24514 \begin_inset Text
24515
24516 \layout Standard
24517
24518 Various notes
24519 \end_inset
24520 </cell>
24521 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24522 \begin_inset Text
24523
24524 \layout Standard
24525
24526 sdcc/doc/*
24527 \emph on
24528 \SpecialChar ~
24529 \SpecialChar ~
24530 \SpecialChar ~
24531
24532 \hfill
24533 online at:
24534 \emph default
24535
24536 \newline
24537
24538 \begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/doc/}
24539
24540 \end_inset
24541
24542
24543 \end_inset
24544 </cell>
24545 </row>
24546 <row topline="true">
24547 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24548 \begin_inset Text
24549
24550 \layout Standard
24551
24552 Notes on debugging with SDCDB
24553 \begin_inset LatexCommand \index{SDCDB (debugger)}
24554
24555 \end_inset
24556
24557
24558 \end_inset
24559 </cell>
24560 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24561 \begin_inset Text
24562
24563 \layout Standard
24564
24565 sdcc/debugger/README
24566 \emph on
24567 \SpecialChar ~
24568 \SpecialChar ~
24569 \SpecialChar ~
24570
24571 \hfill
24572 online at
24573 \emph default
24574 :
24575 \newline
24576
24577 \begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/debugger/README}
24578
24579 \end_inset
24580
24581
24582 \end_inset
24583 </cell>
24584 </row>
24585 <row topline="true">
24586 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24587 \begin_inset Text
24588
24589 \layout Standard
24590
24591 Software simulator for microcontrollers
24592 \end_inset
24593 </cell>
24594 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24595 \begin_inset Text
24596
24597 \layout Standard
24598
24599
24600 \family roman
24601 \series medium
24602 \shape up
24603 \size normal
24604 \emph off
24605 \bar no
24606 \noun off
24607 \color none
24608 sdcc/sim/ucsim/doc
24609 \family default
24610 \series default
24611 \shape default
24612 \size default
24613 \emph default
24614 \bar default
24615 \noun default
24616 \color default
24617 /index.html
24618 \emph on
24619 \SpecialChar ~
24620 \SpecialChar ~
24621 \SpecialChar ~
24622
24623 \hfill
24624 online at:
24625 \emph default
24626
24627 \newline
24628
24629 \begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/sim/ucsim/doc/index.html}
24630
24631 \end_inset
24632
24633
24634 \end_inset
24635 </cell>
24636 </row>
24637 <row topline="true">
24638 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24639 \begin_inset Text
24640
24641 \layout Standard
24642
24643 Temporary notes on the pic16
24644 \begin_inset LatexCommand \index{PIC16}
24645
24646 \end_inset
24647
24648  port
24649 \end_inset
24650 </cell>
24651 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24652 \begin_inset Text
24653
24654 \layout Standard
24655
24656 sdcc/src/pic16/NOTES
24657 \emph on
24658 \SpecialChar ~
24659 \SpecialChar ~
24660 \SpecialChar ~
24661
24662 \hfill
24663 online at:
24664 \newline
24665
24666 \emph default
24667
24668 \begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/src/pic16/NOTES}
24669
24670 \end_inset
24671
24672
24673 \end_inset
24674 </cell>
24675 </row>
24676 <row topline="true" bottomline="true">
24677 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24678 \begin_inset Text
24679
24680 \layout Standard
24681
24682 SDCC internal documentation (debugging file format)
24683 \end_inset
24684 </cell>
24685 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24686 \begin_inset Text
24687
24688 \layout Standard
24689
24690 sdcc/doc/
24691 \family roman
24692 \series medium
24693 \shape up
24694 \size normal
24695 \emph off
24696 \bar no
24697 \noun off
24698 \color none
24699 cdbfileformat.pd
24700 \family default
24701 \series default
24702 \shape default
24703 \size default
24704 \emph default
24705 \bar default
24706 \noun default
24707 \color default
24708 f
24709 \emph on
24710  \SpecialChar ~
24711 \SpecialChar ~
24712 \SpecialChar ~
24713
24714 \hfill
24715 online at:
24716 \emph default
24717
24718 \newline
24719
24720 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/cdbfileformat.pdf}
24721
24722 \end_inset
24723
24724
24725 \end_inset
24726 </cell>
24727 </row>
24728 </lyxtabular>
24729
24730 \end_inset
24731
24732
24733 \newline
24734
24735 \layout Section
24736
24737 Related open source tools
24738 \begin_inset LatexCommand \label{sec:Related-open-source-tools}
24739
24740 \end_inset
24741
24742
24743 \begin_inset LatexCommand \index{Related tools}
24744
24745 \end_inset
24746
24747
24748 \layout Standard
24749 \align left
24750
24751 \begin_inset  Tabular
24752 <lyxtabular version="3" rows="14" columns="3">
24753 <features>
24754 <column alignment="left" valignment="top" leftline="true" width="0pt">
24755 <column alignment="block" valignment="top" leftline="true" width="30line%">
24756 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
24757 <row topline="true" bottomline="true">
24758 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24759 \begin_inset Text
24760
24761 \layout Standard
24762
24763
24764 \series bold
24765 Name
24766 \end_inset
24767 </cell>
24768 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24769 \begin_inset Text
24770
24771 \layout Standard
24772
24773
24774 \series bold
24775 Purpose
24776 \end_inset
24777 </cell>
24778 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24779 \begin_inset Text
24780
24781 \layout Standard
24782
24783
24784 \series bold
24785 Where to get
24786 \end_inset
24787 </cell>
24788 </row>
24789 <row topline="true">
24790 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24791 \begin_inset Text
24792
24793 \layout Standard
24794
24795 gpsim
24796 \begin_inset LatexCommand \index{gpsim (pic simulator)}
24797
24798 \end_inset
24799
24800
24801 \end_inset
24802 </cell>
24803 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24804 \begin_inset Text
24805
24806 \layout Standard
24807
24808 PIC simulator
24809 \end_inset
24810 </cell>
24811 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24812 \begin_inset Text
24813
24814 \layout Standard
24815
24816
24817 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
24818
24819 \end_inset
24820
24821
24822 \end_inset
24823 </cell>
24824 </row>
24825 <row topline="true">
24826 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24827 \begin_inset Text
24828
24829 \layout Standard
24830
24831 gputils
24832 \begin_inset LatexCommand \index{gputils (pic tools)}
24833
24834 \end_inset
24835
24836
24837 \end_inset
24838 </cell>
24839 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24840 \begin_inset Text
24841
24842 \layout Standard
24843
24844 GNU PIC utilities
24845 \end_inset
24846 </cell>
24847 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24848 \begin_inset Text
24849
24850 \layout Standard
24851
24852
24853 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
24854
24855 \end_inset
24856
24857
24858 \end_inset
24859 </cell>
24860 </row>
24861 <row topline="true">
24862 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24863 \begin_inset Text
24864
24865 \layout Standard
24866
24867 flP5
24868 \end_inset
24869 </cell>
24870 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24871 \begin_inset Text
24872
24873 \layout Standard
24874
24875 PIC programmer
24876 \end_inset
24877 </cell>
24878 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24879 \begin_inset Text
24880
24881 \layout Standard
24882
24883
24884 \begin_inset LatexCommand \url{http://freshmeat.net/projects/flp5/}
24885
24886 \end_inset
24887
24888
24889 \end_inset
24890 </cell>
24891 </row>
24892 <row topline="true">
24893 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24894 \begin_inset Text
24895
24896 \layout Standard
24897
24898 ec2drv/newcdb
24899 \end_inset
24900 </cell>
24901 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24902 \begin_inset Text
24903
24904 \layout Standard
24905
24906 Tools for Silicon Laboratories JTAG debug adapter, partly based on SDCDB
24907  (Unix only)
24908 \end_inset
24909 </cell>
24910 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24911 \begin_inset Text
24912
24913 \layout Standard
24914
24915
24916 \begin_inset LatexCommand \url{http://sourceforge.net/projects/ec2drv}
24917
24918 \end_inset
24919
24920
24921 \end_inset
24922 </cell>
24923 </row>
24924 <row topline="true">
24925 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24926 \begin_inset Text
24927
24928 \layout Standard
24929
24930 indent
24931 \begin_inset LatexCommand \index{indent (source formatting tool)}
24932
24933 \end_inset
24934
24935
24936 \end_inset
24937 </cell>
24938 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24939 \begin_inset Text
24940
24941 \layout Standard
24942
24943 Formats C source - Master of the white spaces
24944 \end_inset
24945 </cell>
24946 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24947 \begin_inset Text
24948
24949 \layout Standard
24950
24951
24952 \begin_inset LatexCommand \url{http://directory.fsf.org/GNU/indent.html}
24953
24954 \end_inset
24955
24956
24957 \end_inset
24958 </cell>
24959 </row>
24960 <row topline="true">
24961 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24962 \begin_inset Text
24963
24964 \layout Standard
24965
24966 srecord
24967 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
24968
24969 \end_inset
24970
24971
24972 \end_inset
24973 </cell>
24974 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24975 \begin_inset Text
24976
24977 \layout Standard
24978
24979 Object file conversion, checksumming, ...
24980 \end_inset
24981 </cell>
24982 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24983 \begin_inset Text
24984
24985 \layout Standard
24986
24987
24988 \begin_inset LatexCommand \url{http://sourceforge.net/projects/srecord}
24989
24990 \end_inset
24991
24992
24993 \end_inset
24994 </cell>
24995 </row>
24996 <row topline="true">
24997 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24998 \begin_inset Text
24999
25000 \layout Standard
25001
25002 objdump
25003 \begin_inset LatexCommand \index{objdump (tool)}
25004
25005 \end_inset
25006
25007
25008 \end_inset
25009 </cell>
25010 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25011 \begin_inset Text
25012
25013 \layout Standard
25014
25015 Object file conversion, ...
25016 \end_inset
25017 </cell>
25018 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25019 \begin_inset Text
25020
25021 \layout Standard
25022
25023 Part of binutils (should be there anyway)
25024 \end_inset
25025 </cell>
25026 </row>
25027 <row topline="true">
25028 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25029 \begin_inset Text
25030
25031 \layout Standard
25032
25033 cmon51
25034 \end_inset
25035 </cell>
25036 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25037 \begin_inset Text
25038
25039 \layout Standard
25040
25041 8051 monitor (hex up-/download, single step, disassemble)
25042 \end_inset
25043 </cell>
25044 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25045 \begin_inset Text
25046
25047 \layout Standard
25048
25049
25050 \begin_inset LatexCommand \url{http://sourceforge.net/projects/cmon51}
25051
25052 \end_inset
25053
25054
25055 \end_inset
25056 </cell>
25057 </row>
25058 <row topline="true">
25059 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25060 \begin_inset Text
25061
25062 \layout Standard
25063
25064 doxygen
25065 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
25066
25067 \end_inset
25068
25069
25070 \end_inset
25071 </cell>
25072 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25073 \begin_inset Text
25074
25075 \layout Standard
25076
25077 Source code documentation system
25078 \end_inset
25079 </cell>
25080 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25081 \begin_inset Text
25082
25083 \layout Standard
25084
25085
25086 \begin_inset LatexCommand \url{http://www.doxygen.org}
25087
25088 \end_inset
25089
25090
25091 \end_inset
25092 </cell>
25093 </row>
25094 <row topline="true">
25095 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25096 \begin_inset Text
25097
25098 \layout Standard
25099
25100 kdevelop
25101 \end_inset
25102 </cell>
25103 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25104 \begin_inset Text
25105
25106 \layout Standard
25107
25108 IDE (has anyone tried integrating SDCC & SDCDB? Unix only)
25109 \end_inset
25110 </cell>
25111 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25112 \begin_inset Text
25113
25114 \layout Standard
25115
25116
25117 \begin_inset LatexCommand \url{http://www.kdevelop.org}
25118
25119 \end_inset
25120
25121
25122 \end_inset
25123 </cell>
25124 </row>
25125 <row topline="true">
25126 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25127 \begin_inset Text
25128
25129 \layout Standard
25130
25131 paulmon
25132 \end_inset
25133 </cell>
25134 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25135 \begin_inset Text
25136
25137 \layout Standard
25138
25139 8051 monitor (hex up-/download, single step, disassemble)
25140 \end_inset
25141 </cell>
25142 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25143 \begin_inset Text
25144
25145 \layout Standard
25146
25147
25148 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/paulmon2.html}
25149
25150 \end_inset
25151
25152
25153 \end_inset
25154 </cell>
25155 </row>
25156 <row topline="true">
25157 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25158 \begin_inset Text
25159
25160 \layout Standard
25161
25162 splint
25163 \begin_inset LatexCommand \index{splint (syntax checking tool)}
25164
25165 \end_inset
25166
25167
25168 \end_inset
25169 </cell>
25170 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25171 \begin_inset Text
25172
25173 \layout Standard
25174
25175 Statically checks c sources (see
25176 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
25177
25178 \end_inset
25179
25180 )
25181 \end_inset
25182 </cell>
25183 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25184 \begin_inset Text
25185
25186 \layout Standard
25187
25188
25189 \begin_inset LatexCommand \url{http://www.splint.org}
25190
25191 \end_inset
25192
25193
25194 \end_inset
25195 </cell>
25196 </row>
25197 <row topline="true" bottomline="true">
25198 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25199 \begin_inset Text
25200
25201 \layout Standard
25202
25203 ddd
25204 \begin_inset LatexCommand \index{DDD (debugger)}
25205
25206 \end_inset
25207
25208
25209 \end_inset
25210 </cell>
25211 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25212 \begin_inset Text
25213
25214 \layout Standard
25215
25216 Debugger, serves nicely as GUI to SDCDB
25217 \begin_inset LatexCommand \index{SDCDB (debugger)}
25218
25219 \end_inset
25220
25221  (Unix only)
25222 \end_inset
25223 </cell>
25224 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25225 \begin_inset Text
25226
25227 \layout Standard
25228
25229
25230 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
25231
25232 \end_inset
25233
25234
25235 \end_inset
25236 </cell>
25237 </row>
25238 </lyxtabular>
25239
25240 \end_inset
25241
25242
25243 \newline
25244
25245 \layout Section
25246
25247 Related documentation / recommended reading
25248 \layout Standard
25249 \align left
25250
25251 \begin_inset  Tabular
25252 <lyxtabular version="3" rows="7" columns="3">
25253 <features>
25254 <column alignment="left" valignment="top" leftline="true" width="0pt">
25255 <column alignment="left" valignment="top" leftline="true" width="0">
25256 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
25257 <row topline="true" bottomline="true">
25258 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25259 \begin_inset Text
25260
25261 \layout Standard
25262
25263
25264 \series bold
25265 Name
25266 \end_inset
25267 </cell>
25268 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25269 \begin_inset Text
25270
25271 \layout Standard
25272
25273
25274 \series bold
25275 Subject / Title
25276 \end_inset
25277 </cell>
25278 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25279 \begin_inset Text
25280
25281 \layout Standard
25282
25283
25284 \series bold
25285 Where to get
25286 \end_inset
25287 </cell>
25288 </row>
25289 <row topline="true">
25290 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25291 \begin_inset Text
25292
25293 \layout Standard
25294
25295
25296 \family roman
25297 \series medium
25298 \shape up
25299 \size normal
25300 \emph off
25301 \bar no
25302 \noun off
25303 \color none
25304 c-refcard.pdf
25305 \end_inset
25306 </cell>
25307 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25308 \begin_inset Text
25309
25310 \layout Standard
25311
25312 C Reference Card
25313 \begin_inset LatexCommand \index{C Reference card}
25314
25315 \end_inset
25316
25317 , 2 pages
25318 \end_inset
25319 </cell>
25320 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25321 \begin_inset Text
25322
25323 \layout Standard
25324
25325
25326 \begin_inset LatexCommand \url{http://refcards.com/refcards/c/index.html}
25327
25328 \end_inset
25329
25330
25331 \end_inset
25332 </cell>
25333 </row>
25334 <row topline="true">
25335 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25336 \begin_inset Text
25337
25338 \layout Standard
25339
25340 c-faq
25341 \end_inset
25342 </cell>
25343 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25344 \begin_inset Text
25345
25346 \layout Standard
25347
25348 C-FAQ
25349 \begin_inset LatexCommand \index{C FAQ}
25350
25351 \end_inset
25352
25353
25354 \end_inset
25355 </cell>
25356 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25357 \begin_inset Text
25358
25359 \layout Standard
25360
25361
25362 \begin_inset LatexCommand \url{http://www.c-faq.com}
25363
25364 \end_inset
25365
25366
25367 \end_inset
25368 </cell>
25369 </row>
25370 <row topline="true">
25371 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25372 \begin_inset Text
25373
25374 \layout Standard
25375
25376 ISO/IEC 9899:TC2
25377 \end_inset
25378 </cell>
25379 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25380 \begin_inset Text
25381
25382 \layout Standard
25383
25384
25385 \begin_inset Quotes sld
25386 \end_inset
25387
25388 C-Standard
25389 \begin_inset Quotes srd
25390 \end_inset
25391
25392
25393 \end_inset
25394 </cell>
25395 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25396 \begin_inset Text
25397
25398 \layout Standard
25399
25400
25401 \size footnotesize
25402
25403 \begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899}
25404
25405 \end_inset
25406
25407
25408 \end_inset
25409 </cell>
25410 </row>
25411 <row topline="true">
25412 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25413 \begin_inset Text
25414
25415 \layout Standard
25416
25417 ISO/IEC DTR 18037
25418 \end_inset
25419 </cell>
25420 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25421 \begin_inset Text
25422
25423 \layout Standard
25424
25425
25426 \begin_inset Quotes sld
25427 \end_inset
25428
25429 Extensions for Embedded C
25430 \begin_inset Quotes srd
25431 \end_inset
25432
25433
25434 \end_inset
25435 </cell>
25436 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25437 \begin_inset Text
25438
25439 \layout Standard
25440
25441
25442 \size footnotesize
25443
25444 \begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1021.pdf}
25445
25446 \end_inset
25447
25448
25449 \end_inset
25450 </cell>
25451 </row>
25452 <row topline="true">
25453 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25454 \begin_inset Text
25455
25456 \layout Standard
25457
25458 \end_inset
25459 </cell>
25460 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25461 \begin_inset Text
25462
25463 \layout Standard
25464
25465 Latest datasheet of target CPU
25466 \end_inset
25467 </cell>
25468 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25469 \begin_inset Text
25470
25471 \layout Standard
25472
25473 vendor
25474 \end_inset
25475 </cell>
25476 </row>
25477 <row topline="true" bottomline="true">
25478 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25479 \begin_inset Text
25480
25481 \layout Standard
25482
25483 \end_inset
25484 </cell>
25485 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25486 \begin_inset Text
25487
25488 \layout Standard
25489
25490 Revision history of datasheet
25491 \end_inset
25492 </cell>
25493 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25494 \begin_inset Text
25495
25496 \layout Standard
25497
25498 vendor
25499 \end_inset
25500 </cell>
25501 </row>
25502 </lyxtabular>
25503
25504 \end_inset
25505
25506
25507 \newline
25508
25509 \layout Section
25510
25511 Application notes specifically for SDCC
25512 \layout Standard
25513
25514 SDCC makes no claims about the completeness of this list and about up-to-datenes
25515 s or correctness of the application notes
25516 \begin_inset LatexCommand \index{Application notes}
25517
25518 \end_inset
25519
25520 .
25521 \layout Standard
25522 \align left
25523
25524 \size footnotesize
25525
25526 \begin_inset  Tabular
25527 <lyxtabular version="3" rows="7" columns="3">
25528 <features>
25529 <column alignment="block" valignment="top" leftline="true" width="17col%">
25530 <column alignment="block" valignment="top" leftline="true" width="27col%">
25531 <column alignment="block" valignment="top" leftline="true" rightline="true" width="57col%">
25532 <row topline="true" bottomline="true">
25533 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25534 \begin_inset Text
25535
25536 \layout Standard
25537
25538
25539 \series bold
25540 \size footnotesize
25541 Vendor
25542 \end_inset
25543 </cell>
25544 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
25545 \begin_inset Text
25546
25547 \layout Standard
25548
25549
25550 \series bold
25551 \size footnotesize
25552 Subject / Title
25553 \end_inset
25554 </cell>
25555 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25556 \begin_inset Text
25557
25558 \layout Standard
25559
25560
25561 \series bold
25562 \size footnotesize
25563 Where to get
25564 \end_inset
25565 </cell>
25566 </row>
25567 <row topline="true">
25568 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25569 \begin_inset Text
25570
25571 \layout Standard
25572
25573
25574 \size footnotesize
25575 Maxim / Dallas
25576 \end_inset
25577 </cell>
25578 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25579 \begin_inset Text
25580
25581 \layout Standard
25582
25583
25584 \size footnotesize
25585 Using the SDCC Compiler for the DS80C400
25586 \begin_inset LatexCommand \index{DS80C400}
25587
25588 \end_inset
25589
25590
25591 \end_inset
25592 </cell>
25593 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25594 \begin_inset Text
25595
25596 \layout Standard
25597
25598
25599 \size footnotesize
25600
25601 \begin_inset LatexCommand \url{http://pdfserv.maxim-ic.com/en/an/AN3346.pdf}
25602
25603 \end_inset
25604
25605
25606 \end_inset
25607 </cell>
25608 </row>
25609 <row topline="true">
25610 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25611 \begin_inset Text
25612
25613 \layout Standard
25614
25615
25616 \size footnotesize
25617 Maxim / Dallas
25618 \end_inset
25619 </cell>
25620 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none" width="30line%">
25621 \begin_inset Text
25622
25623 \layout Standard
25624
25625
25626 \size footnotesize
25627 Using the Free SDCC C Compiler to Develop Firmware for the DS89C420/430/440/450
25628 \begin_inset LatexCommand \index{DS89C4x0}
25629
25630 \end_inset
25631
25632  Family of Microcontrollers
25633 \end_inset
25634 </cell>
25635 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25636 \begin_inset Text
25637
25638 \layout Standard
25639
25640
25641 \size footnotesize
25642
25643 \begin_inset LatexCommand \url{http://pdfserv.maxim-ic.com/en/an/AN3477.pdf}
25644
25645 \end_inset
25646
25647
25648 \end_inset
25649 </cell>
25650 </row>
25651 <row topline="true">
25652 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25653 \begin_inset Text
25654
25655 \layout Standard
25656
25657
25658 \size footnotesize
25659 Silicon Laboratories / Cygnal
25660 \end_inset
25661 </cell>
25662 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25663 \begin_inset Text
25664
25665 \layout Standard
25666
25667
25668 \size footnotesize
25669 Integrating SDCC 8051 Tools Into The Silicon Labs IDE
25670 \begin_inset LatexCommand \index{IDE}
25671
25672 \end_inset
25673
25674
25675 \end_inset
25676 </cell>
25677 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25678 \begin_inset Text
25679
25680 \layout Standard
25681
25682
25683 \size footnotesize
25684
25685 \begin_inset LatexCommand \url{http://www.silabs.com/public/documents/tpub_doc/anote/Microcontrollers/en/an198.pdf}
25686
25687 \end_inset
25688
25689
25690 \end_inset
25691 </cell>
25692 </row>
25693 <row topline="true">
25694 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25695 \begin_inset Text
25696
25697 \layout Standard
25698
25699
25700 \size footnotesize
25701 Ramtron / Goal Semiconductor
25702 \end_inset
25703 </cell>
25704 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25705 \begin_inset Text
25706
25707 \layout Standard
25708
25709
25710 \size footnotesize
25711 Interfacing SDCC to Syn and Textpad
25712 \end_inset
25713 </cell>
25714 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25715 \begin_inset Text
25716
25717 \layout Standard
25718
25719
25720 \size footnotesize
25721
25722 \begin_inset LatexCommand \url{http://www.ramtron.com/doc/Products/Microcontroller/Support_Tools.asp}
25723
25724 \end_inset
25725
25726
25727 \end_inset
25728 </cell>
25729 </row>
25730 <row topline="true">
25731 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25732 \begin_inset Text
25733
25734 \layout Standard
25735
25736
25737 \size footnotesize
25738 Ramtron / Goal Semiconductor
25739 \end_inset
25740 </cell>
25741 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25742 \begin_inset Text
25743
25744 \layout Standard
25745
25746
25747 \size footnotesize
25748 Installing and Configuring SDCC and Crimson Editor
25749 \end_inset
25750 </cell>
25751 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25752 \begin_inset Text
25753
25754 \layout Standard
25755
25756
25757 \size footnotesize
25758
25759 \begin_inset LatexCommand \url{http://www.ramtron.com/doc/Products/Microcontroller/Support_Tools.asp}
25760
25761 \end_inset
25762
25763
25764 \end_inset
25765 </cell>
25766 </row>
25767 <row topline="true" bottomline="true">
25768 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25769 \begin_inset Text
25770
25771 \layout Standard
25772
25773
25774 \size footnotesize
25775 Texas Instruments
25776 \end_inset
25777 </cell>
25778 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25779 \begin_inset Text
25780
25781 \layout Standard
25782
25783
25784 \size footnotesize
25785 MSC12xx Programming with SDCC
25786 \end_inset
25787 </cell>
25788 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25789 \begin_inset Text
25790
25791 \layout Standard
25792
25793
25794 \size footnotesize
25795
25796 \begin_inset LatexCommand \url{http://focus.ti.com/general/docs/lit/getliterature.tsp?literatureNumber=sbaa109&fileType=pdf}
25797
25798 \end_inset
25799
25800
25801 \end_inset
25802 </cell>
25803 </row>
25804 </lyxtabular>
25805
25806 \end_inset
25807
25808
25809 \layout Section
25810
25811 Some Questions
25812 \layout Standard
25813
25814 Some questions answered, some pointers given - it might be time to in turn
25815  ask
25816 \emph on
25817 you
25818 \emph default
25819  some questions:
25820 \layout Itemize
25821
25822 can you solve your project with the selected microcontroller? Would you
25823  find out early or rather late that your target is too small/slow/whatever?
25824  Can you switch to a slightly better device if it doesn't fit?
25825 \layout Itemize
25826
25827 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
25828  and/or another programming language be more adequate? Would an operating
25829  system on the target device help?
25830 \layout Itemize
25831
25832 if you solved the problem, will the marketing department be happy?
25833 \layout Itemize
25834
25835 if the marketing department is happy, will customers be happy?
25836 \layout Itemize
25837
25838 if you're the project manager, marketing department and maybe even the customer
25839  in one person, have you tried to see the project from the outside?
25840 \layout Itemize
25841
25842 is the project done if you think it is done? Or is just that other interface/pro
25843 tocol/feature/configuration/option missing? How about website, manual(s),
25844  internationali(z|s)ation, packaging, labels, 2nd source for components,
25845  electromagnetic compatability/interference, documentation for production,
25846  production test software, update mechanism, patent issues?
25847 \layout Itemize
25848
25849 is your project adequately positioned in that magic triangle: fame, fortune,
25850  fun?
25851 \layout Standard
25852
25853 Maybe not all answers to these questions are known and some answers may
25854  even be
25855 \emph on
25856 no
25857 \emph default
25858 , nevertheless knowing these questions may help you to avoid burnout
25859 \begin_inset Foot
25860 collapsed false
25861
25862 \layout Standard
25863
25864 burnout is bad for electronic devices, programmers and motorcycle tyres
25865 \end_inset
25866
25867 .
25868  Chances are you didn't want to hear some of them...
25869 \layout Chapter
25870
25871 Support
25872 \begin_inset LatexCommand \index{Support}
25873
25874 \end_inset
25875
25876
25877 \layout Standard
25878
25879 SDCC has grown to be a large project.
25880  The compiler alone (without the preprocessor, assembler and linker) is
25881  well over 150,000 lines of code (blank stripped).
25882  The open source nature of this project is a key to its continued growth
25883  and support.
25884  You gain the benefit and support of many active software developers and
25885  end users.
25886  Is SDCC perfect? No, that's why we need your help.
25887  The developers take pride in fixing reported bugs.
25888  You can help by reporting the bugs and helping other SDCC users.
25889  There are lots of ways to contribute, and we encourage you to take part
25890  in making SDCC a great software package.
25891
25892 \layout Standard
25893
25894 The SDCC project is hosted on the SDCC sourceforge site at
25895 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
25896
25897 \end_inset
25898
25899 .
25900  You'll find the complete set of mailing lists
25901 \begin_inset LatexCommand \index{Mailing list(s)}
25902
25903 \end_inset
25904
25905 , forums, bug reporting system, patch submission
25906 \begin_inset LatexCommand \index{Patch submission}
25907
25908 \end_inset
25909
25910  system, download
25911 \begin_inset LatexCommand \index{download}
25912
25913 \end_inset
25914
25915  area and Subversion code repository
25916 \begin_inset LatexCommand \index{Subversion code repository}
25917
25918 \end_inset
25919
25920  there.
25921 \layout Section
25922
25923 Reporting Bugs
25924 \begin_inset LatexCommand \index{Bug reporting}
25925
25926 \end_inset
25927
25928
25929 \begin_inset LatexCommand \index{Reporting bugs}
25930
25931 \end_inset
25932
25933
25934 \layout Standard
25935
25936 The recommended way of reporting bugs is using the infrastructure of the
25937  sourceforge site.
25938  You can follow the status of bug reports there and have an overview about
25939  the known bugs.
25940 \layout Standard
25941
25942 Bug reports are automatically forwarded to the developer mailing list and
25943  will be fixed ASAP.
25944  When reporting a bug, it is very useful to include a small test program
25945  (the smaller the better) which reproduces the problem.
25946  If you can isolate the problem by looking at the generated assembly code,
25947  this can be very helpful.
25948  Compiling your program with the -
25949 \begin_inset ERT
25950 status Collapsed
25951
25952 \layout Standard
25953
25954 \backslash
25955 /
25956 \end_inset
25957
25958 -dumpall
25959 \begin_inset LatexCommand \index{-\/-dumpall}
25960
25961 \end_inset
25962
25963  option can sometimes be useful in locating optimization problems.
25964  When reporting a bug please make sure you:
25965 \layout Enumerate
25966
25967 Attach the code you are compiling with SDCC.
25968
25969 \layout Enumerate
25970
25971 Specify the exact command you use to run SDCC, or attach your Makefile.
25972
25973 \layout Enumerate
25974
25975 Specify the SDCC version (type "
25976 \family sans
25977 \series bold
25978 sdcc -v
25979 \family default
25980 \series default
25981 "), your platform, and operating system.
25982
25983 \layout Enumerate
25984
25985 Provide an exact copy of any error message or incorrect output.
25986
25987 \layout Enumerate
25988
25989 Put something meaningful in the subject of your message.
25990 \layout Standard
25991
25992 Please attempt to include these 5 important parts, as applicable, in all
25993  requests for support or when reporting any problems or bugs with SDCC.
25994  Though this will make your message lengthy, it will greatly improve your
25995  chance that SDCC users and developers will be able to help you.
25996  Some SDCC developers are frustrated by bug reports without code provided
25997  that they can use to reproduce and ultimately fix the problem, so please
25998  be sure to provide sample code if you are reporting a bug!
25999 \layout Standard
26000
26001 Please have a short check that you are using a recent version of SDCC and
26002  the bug is not yet known.
26003  This is the link for reporting bugs:
26004 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
26005
26006 \end_inset
26007
26008 .
26009  With SDCC on average having more than 200 downloads
26010 \begin_inset LatexCommand \index{download}
26011
26012 \end_inset
26013
26014  on sourceforge per day
26015 \begin_inset Foot
26016 collapsed false
26017
26018 \layout Standard
26019
26020 220 daily downloads on average Jan-Sept 2006 and about 150 daily downloads
26021  between 2002 and 2005.
26022  This does not include other methods of distribution.
26023 \end_inset
26024
26025  there must be some users.
26026  So it's not exactly easy to find a new bug.
26027  If you find one we need it:
26028 \emph on
26029 reporting bugs is good
26030 \emph default
26031 .
26032 \layout Section
26033
26034 Requesting Features
26035 \begin_inset LatexCommand \label{sub:Requesting-Features}
26036
26037 \end_inset
26038
26039
26040 \begin_inset LatexCommand \index{Feature request}
26041
26042 \end_inset
26043
26044
26045 \begin_inset LatexCommand \index{Requesting features}
26046
26047 \end_inset
26048
26049
26050 \layout Standard
26051
26052 Like bug reports feature requests are forwarded to the developer mailing
26053  list.
26054  This is the link for requesting features:
26055 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
26056
26057 \end_inset
26058
26059 .
26060 \layout Section
26061
26062 Submitting patches
26063 \layout Standard
26064
26065 Like bug reports contributed patches are forwarded to the developer mailing
26066  list.
26067  This is the link for submitting patches
26068 \begin_inset LatexCommand \index{Patch submission}
26069
26070 \end_inset
26071
26072 :
26073 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
26074
26075 \end_inset
26076
26077 .
26078 \layout Standard
26079
26080 You need to specify some parameters to the
26081 \family typewriter
26082 diff
26083 \family default
26084  command for the patches to be useful.
26085  If you modified more than one file a patch created f.e.
26086  with
26087 \family sans
26088 \series bold
26089
26090 \begin_inset Quotes sld
26091 \end_inset
26092
26093 diff -Naur unmodified_directory modified_directory >my_changes.patch
26094 \begin_inset Quotes srd
26095 \end_inset
26096
26097
26098 \family default
26099 \series default
26100  will be fine, otherwise
26101 \family sans
26102 \series bold
26103
26104 \begin_inset Quotes sld
26105 \end_inset
26106
26107 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
26108 \begin_inset Quotes srd
26109 \end_inset
26110
26111
26112 \series default
26113
26114 \family default
26115 will do.
26116 \layout Section
26117
26118 Getting Help
26119 \layout Standard
26120
26121 These links should take you directly to the
26122 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
26123
26124 \end_inset
26125
26126
26127 \begin_inset Foot
26128 collapsed false
26129
26130 \layout Standard
26131
26132 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
26133  automated messages (mid 2003)
26134 \end_inset
26135
26136  and the
26137 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
26138
26139 \end_inset
26140
26141 , lists
26142 \begin_inset LatexCommand \index{Mailing list(s)}
26143
26144 \end_inset
26145
26146  and forums are archived and searchable so if you are lucky someone already
26147  had a similar problem.
26148  While mails to the lists themselves are delivered promptly their web front
26149  end on sourceforge sometimes shows a severe time lag (up to several weeks),
26150  if you're seriously using SDCC please consider subscribing to the lists.
26151 \layout Section
26152
26153 ChangeLog
26154 \layout Standard
26155
26156 You can follow the status of the Subversion version
26157 \begin_inset LatexCommand \index{version}
26158
26159 \end_inset
26160
26161  of SDCC by watching the Changelog
26162 \begin_inset LatexCommand \index{Changelog}
26163
26164 \end_inset
26165
26166  in the Subversion repository
26167 \size footnotesize
26168
26169 \begin_inset LatexCommand \htmlurl{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/ChangeLog}
26170
26171 \end_inset
26172
26173 .
26174 \layout Section
26175
26176 Subversion Source Code Repository
26177 \layout Standard
26178
26179 The output of
26180 \family sans
26181 \series bold
26182 sdcc --version
26183 \family default
26184 \series default
26185  or the filenames of the snapshot versions of SDCC include date and its
26186  Subversion
26187 \begin_inset LatexCommand \index{Subversion code repository}
26188
26189 \end_inset
26190
26191  number.
26192  Subversion allows to download the source of recent or previous versions
26193
26194 \begin_inset LatexCommand \url{http://sourceforge.net/svn/?group_id=599}
26195
26196 \end_inset
26197
26198  (by number or by date).
26199  An on-line source code browser and detailled instructions are also available
26200  there.
26201  SDCC versions starting from 1999 up to now are available (currently the
26202  versions prior to the conversion from cvs
26203 \begin_inset LatexCommand \index{cvs|see{Subversion}}
26204
26205 \end_inset
26206
26207  to Subversion (April 2006) are either by accessible by Subversion or by
26208  cvs).
26209 \layout Section
26210
26211 Release policy
26212 \begin_inset LatexCommand \index{Release policy}
26213
26214 \end_inset
26215
26216
26217 \layout Standard
26218
26219 Historically there often were long delays between official releases and
26220  the sourceforge download area tends to get not updated at all.
26221  Excuses in the past might have referred to problems with live range analysis,
26222  but as this was fixed a while ago, the current problem is that another
26223  excuse has to be found.
26224  Kidding aside, we have to get better there! On the other hand there are
26225  daily snapshots available at
26226 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
26227
26228 \end_inset
26229
26230 , and you can always build the very last version (hopefully with many bugs
26231  fixed, and features added) from the source code available at
26232 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
26233
26234 \end_inset
26235
26236 .
26237  A release wiki
26238 \begin_inset LatexCommand \index{wiki}
26239
26240 \end_inset
26241
26242
26243 \begin_inset LatexCommand \index{Release wiki}
26244
26245 \end_inset
26246
26247  at
26248 \begin_inset LatexCommand \url{http://sdcc.sf.net/release_wiki/}
26249
26250 \end_inset
26251
26252  also holds some information about past and future releases.
26253 \layout Section
26254
26255 Examples
26256 \begin_inset LatexCommand \index{Examples}
26257
26258 \end_inset
26259
26260
26261 \layout Standard
26262
26263 You'll find some small examples in the directory
26264 \emph on
26265 sdcc/device/examples/.
26266
26267 \emph default
26268 More examples and libraries are available at
26269 \emph on
26270  The SDCC Open Knowledge Resource
26271 \begin_inset LatexCommand \url{http://sdccokr.dl9sec.de/}
26272
26273 \end_inset
26274
26275
26276 \emph default
26277 web site or at
26278 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
26279
26280 \end_inset
26281
26282 .
26283 \layout Comment
26284
26285 I did insert a reference to Paul's web site here although it seems rather
26286  dedicated to a specific 8032 board (I think it's okay because it f.e.
26287  shows LCD/Harddisc interface and has a free 8051 monitor.
26288  Independent 8032 board vendors face hard competition of heavily subsidized
26289  development boards anyway).
26290 \layout Comment
26291
26292 Maybe we should include some links to real world applications.
26293  Preferably pointer to pointers (one for each architecture) so this stays
26294  manageable here?
26295 \layout Section
26296
26297 Quality control
26298 \begin_inset LatexCommand \label{sec:Quality-control}
26299
26300 \end_inset
26301
26302
26303 \begin_inset LatexCommand \index{Quality control}
26304
26305 \end_inset
26306
26307
26308 \layout Standard
26309
26310 The compiler is passed through nightly compile and build checks.
26311  The so called
26312 \shape italic
26313 regression tests
26314 \shape default
26315
26316 \begin_inset LatexCommand \index{Regression test}
26317
26318 \end_inset
26319
26320  check that SDCC itself compiles flawlessly on several host platforms (i386,
26321  Opteron, 64 bit Alpha, ppc64, MacOS X on PPC, Solaris on Sparc) and checks
26322  the quality of the code generated by SDCC by running the code for several
26323  target platforms through simulators.
26324  The regression test suite comprises more than 100 files which expand to
26325  more than 500 test cases which include more than 4500 tests.
26326  The results of these tests are published daily on SDCC's snapshot page
26327  (click on the red or green symbols on the right side of
26328 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
26329
26330 \end_inset
26331
26332 ).
26333 \layout Standard
26334
26335 There is a separate document
26336 \shape italic
26337 test_suite.pdf
26338 \begin_inset LatexCommand \index{Test suite}
26339
26340 \end_inset
26341
26342
26343 \shape default
26344
26345 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/test_suite_spec.pdf}
26346
26347 \end_inset
26348
26349  about the regression test suite.
26350 \layout Standard
26351
26352 You'll find the test code in the directory
26353 \shape italic
26354 sdcc/support/regression
26355 \shape default
26356 .
26357  You can run these tests manually by running
26358 \family sans
26359 make
26360 \family default
26361  in this directory (or f.e.
26362
26363 \family sans
26364 \series bold
26365
26366 \begin_inset Quotes sld
26367 \end_inset
26368
26369 make test-mcs51
26370 \begin_inset Quotes srd
26371 \end_inset
26372
26373
26374 \family default
26375 \series default
26376  if you don't want to run the complete tests).
26377  The test code might also be interesting if you want to look for examples
26378 \begin_inset LatexCommand \index{Examples}
26379
26380 \end_inset
26381
26382  checking corner cases of SDCC or if you plan to submit patches
26383 \begin_inset LatexCommand \index{Patch submission}
26384
26385 \end_inset
26386
26387 .
26388 \layout Standard
26389
26390 The 14bit pic port uses a different set of regression tests
26391 \begin_inset LatexCommand \index{Regression test (PIC14)}
26392
26393 \end_inset
26394
26395 , you'll find them in the directory
26396 \shape italic
26397 sdcc/src/regression
26398 \shape default
26399 .
26400 \layout Section
26401
26402 Use of SDCC in Education
26403 \layout Standard
26404
26405 In short:
26406 \emph on
26407 highly
26408 \emph default
26409  encouraged
26410 \begin_inset Foot
26411 collapsed false
26412
26413 \layout Standard
26414
26415 the phrase "use in education" might evoke the association "
26416 \emph on
26417 only
26418 \emph default
26419  fit for use in education".
26420  This connotation is not intended but nevertheless risked as the licensing
26421  of SDCC makes it difficult to offer educational discounts
26422 \end_inset
26423
26424 .
26425  If your rationales are to:
26426 \layout Enumerate
26427
26428 give students a chance to understand the
26429 \emph on
26430 complete
26431 \emph default
26432  steps of code generation
26433 \layout Enumerate
26434
26435 have a curriculum that can be extended for years.
26436  Then you could use an fpga board as target and your curriculum will seamlessly
26437  extend from logic synthesis (
26438 \begin_inset LatexCommand \url[http://www.opencores.org]{opencores.org}
26439
26440 \end_inset
26441
26442 ,
26443 \begin_inset LatexCommand \url[Oregano]{http://www.oregano.at/ip/ip01.htm}
26444
26445 \end_inset
26446
26447 ), over assembly programming, to C to FPGA compilers (
26448 \begin_inset LatexCommand \url[FPGAC]{http://sf.net/projects/fpgac}
26449
26450 \end_inset
26451
26452 ) and to C.
26453 \layout Enumerate
26454
26455 be able to insert excursions about skills like using a revision control
26456  system, submitting/applying patches, using a type-setting (as opposed to
26457  word-processing) engine LyX/LaTeX, using
26458 \begin_inset LatexCommand \url[SourceForge]{http://www.sf.net}
26459
26460 \end_inset
26461
26462 , following some
26463 \begin_inset LatexCommand \url[netiquette]{http://en.wikipedia.org/wiki/Netiquette}
26464
26465 \end_inset
26466
26467 , understanding BSD/LGPL/GPL/Proprietary licensing, growth models of Open
26468  Source Software, CPU simulation, compiler regression tests
26469 \begin_inset LatexCommand \index{Regression test}
26470
26471 \end_inset
26472
26473 .
26474
26475 \newline
26476 And if there should be a shortage of ideas then you can always point students
26477  to the ever-growing feature request list
26478 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
26479
26480 \end_inset
26481
26482 .
26483 \layout Enumerate
26484
26485 not tie students to a specific host platform and instead allow them to use
26486  a host platform of
26487 \emph on
26488 their
26489 \emph default
26490  choice (among them Alpha, i386, i386_64, MacOs, Mips, Sparc, Windows and
26491  eventually
26492 \begin_inset LatexCommand \url[OLPC]{http://www.laptop.org}
26493
26494 \end_inset
26495
26496 )
26497 \layout Enumerate
26498
26499 not encourage students to use illegal copies of educational software
26500 \layout Enumerate
26501
26502 be immune to licensing/availability/price changes of the chosen tool chain
26503 \layout Enumerate
26504
26505 be able to change to a new target platform without having to adopt a new
26506  tool chain
26507 \layout Enumerate
26508
26509 have complete control over and insight into the tool chain
26510 \layout Enumerate
26511
26512 make your students aware about the pros and cons of open source software
26513  development
26514 \layout Enumerate
26515
26516 give back to the public as you are probably at least partially publically
26517  funded
26518 \layout Enumerate
26519
26520 give students a chance to publically prove their skills and to possibly
26521  see a world wide impact
26522 \layout Standard
26523
26524 then SDCC is probably among the first choices.
26525  Well, probably SDCC might be the only choice.
26526 \layout Chapter
26527 \pagebreak_top
26528 SDCC Technical Data
26529 \layout Section
26530
26531 Optimizations
26532 \begin_inset LatexCommand \index{Optimizations}
26533
26534 \end_inset
26535
26536
26537 \layout Standard
26538
26539 SDCC performs a host of standard optimizations in addition to some MCU specific
26540  optimizations.
26541
26542 \layout Subsection
26543
26544 Sub-expression Elimination
26545 \begin_inset LatexCommand \index{Subexpression elimination}
26546
26547 \end_inset
26548
26549
26550 \layout Standard
26551
26552 The compiler does local and
26553 \emph on
26554 g
26555 \emph default
26556 lobal
26557 \emph on
26558 c
26559 \emph default
26560 ommon
26561 \emph on
26562 s
26563 \emph default
26564 ubexpression
26565 \emph on
26566 e
26567 \emph default
26568 limination, e.g.:
26569 \layout Verse
26570
26571
26572 \family typewriter
26573 i = x + y + 1;
26574 \newline
26575 j = x + y;
26576 \layout Standard
26577
26578 will be translated to
26579 \layout Verse
26580
26581
26582 \family typewriter
26583 iTemp = x + y;
26584 \newline
26585 i = iTemp + 1;
26586 \newline
26587 j = iTemp;
26588 \layout Standard
26589
26590 Some subexpressions are not as obvious as the above example, e.g.:
26591 \layout Verse
26592
26593
26594 \family typewriter
26595 a->b[i].c = 10;
26596 \newline
26597 a->b[i].d = 11;
26598 \layout Standard
26599
26600 In this case the address arithmetic a->b[i] will be computed only once;
26601  the equivalent code in C would be.
26602 \layout Verse
26603
26604
26605 \family typewriter
26606 iTemp = a->b[i];
26607 \newline
26608 iTemp.c = 10;
26609 \newline
26610 iTemp.d = 11;
26611 \layout Standard
26612
26613 The compiler will try to keep these temporary variables in registers.
26614 \layout Subsection
26615
26616 Dead-Code Elimination
26617 \begin_inset LatexCommand \index{Dead-code elimination}
26618
26619 \end_inset
26620
26621
26622 \layout Verse
26623
26624
26625 \family typewriter
26626 int global;
26627 \newline
26628
26629 \newline
26630 void f () {
26631 \newline
26632 \SpecialChar ~
26633 \SpecialChar ~
26634 int i;
26635 \newline
26636 \SpecialChar ~
26637 \SpecialChar ~
26638 i = 1; \SpecialChar ~
26639 \SpecialChar ~
26640 \SpecialChar ~
26641 \SpecialChar ~
26642 \SpecialChar ~
26643 /* dead store */
26644 \newline
26645 \SpecialChar ~
26646 \SpecialChar ~
26647 global = 1;\SpecialChar ~
26648 /* dead store */
26649 \newline
26650 \SpecialChar ~
26651 \SpecialChar ~
26652 global = 2;
26653 \newline
26654 \SpecialChar ~
26655 \SpecialChar ~
26656 return;
26657 \newline
26658 \SpecialChar ~
26659 \SpecialChar ~
26660 global = 3;\SpecialChar ~
26661 /* unreachable */
26662 \newline
26663 }
26664 \layout Standard
26665
26666 will be changed to
26667 \layout Verse
26668
26669
26670 \family typewriter
26671 int global;
26672 \newline
26673
26674 \newline
26675 void f () {
26676 \newline
26677 \SpecialChar ~
26678 \SpecialChar ~
26679 global = 2;
26680 \newline
26681 }
26682 \layout Subsection
26683
26684 Copy-Propagation
26685 \begin_inset LatexCommand \index{Copy propagation}
26686
26687 \end_inset
26688
26689
26690 \layout Verse
26691
26692
26693 \family typewriter
26694 int f() {
26695 \newline
26696 \SpecialChar ~
26697 \SpecialChar ~
26698 int i, j;
26699 \newline
26700 \SpecialChar ~
26701 \SpecialChar ~
26702 i = 10;
26703 \newline
26704 \SpecialChar ~
26705 \SpecialChar ~
26706 j = i;
26707 \newline
26708 \SpecialChar ~
26709 \SpecialChar ~
26710 return j;
26711 \newline
26712 }
26713 \layout Standard
26714
26715 will be changed to
26716 \layout Verse
26717
26718
26719 \family typewriter
26720 int f() {
26721 \newline
26722 \SpecialChar ~
26723 \SpecialChar ~
26724 int i, j;
26725 \newline
26726 \SpecialChar ~
26727 \SpecialChar ~
26728 i = 10;
26729 \newline
26730 \SpecialChar ~
26731 \SpecialChar ~
26732 j = 10;
26733 \newline
26734 \SpecialChar ~
26735 \SpecialChar ~
26736 return 10;
26737 \newline
26738 }
26739 \layout Standard
26740
26741 Note: the dead stores created by this copy propagation will be eliminated
26742  by dead-code elimination.
26743 \layout Subsection
26744
26745 Loop Optimizations
26746 \begin_inset LatexCommand \index{Loop optimization}
26747
26748 \end_inset
26749
26750
26751 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
26752
26753 \end_inset
26754
26755
26756 \layout Standard
26757
26758 Two types of loop optimizations are done by SDCC
26759 \emph on
26760 loop invariant
26761 \emph default
26762  lifting and
26763 \emph on
26764  strength reduction
26765 \emph default
26766  of loop induction variables.
26767  In addition to the strength reduction the optimizer marks the induction
26768  variables and the register allocator tries to keep the induction variables
26769  in registers for the duration of the loop.
26770  Because of this preference of the register allocator
26771 \begin_inset LatexCommand \index{Register allocation}
26772
26773 \end_inset
26774
26775 , loop induction optimization causes an increase in register pressure, which
26776  may cause unwanted spilling of other temporary variables into the stack
26777 \begin_inset LatexCommand \index{stack}
26778
26779 \end_inset
26780
26781  / data space.
26782  The compiler will generate a warning message when it is forced to allocate
26783  extra space either on the stack or data space.
26784  If this extra space allocation is undesirable then induction optimization
26785  can be eliminated either for the entire source file (with -
26786 \begin_inset ERT
26787 status Collapsed
26788
26789 \layout Standard
26790
26791 \backslash
26792 /
26793 \end_inset
26794
26795 -noinduction option) or for a given function only using #pragma\SpecialChar ~
26796 noinduction
26797 \begin_inset LatexCommand \index{\#pragma noinduction}
26798
26799 \end_inset
26800
26801 .
26802 \newline
26803
26804 \newline
26805 Loop Invariant:
26806 \layout Verse
26807
26808
26809 \family typewriter
26810 for (i = 0 ; i < 100 ; i ++)
26811 \newline
26812 \SpecialChar ~
26813 \SpecialChar ~
26814 \SpecialChar ~
26815 \SpecialChar ~
26816 f += k + l;
26817 \layout Standard
26818
26819 changed to
26820 \layout Verse
26821
26822
26823 \family typewriter
26824 itemp = k + l;
26825 \newline
26826 for (i = 0; i < 100; i++)
26827 \newline
26828 \SpecialChar ~
26829 \SpecialChar ~
26830 \SpecialChar ~
26831 \SpecialChar ~
26832 f += itemp;
26833 \layout Standard
26834
26835 As mentioned previously some loop invariants are not as apparent, all static
26836  address computations are also moved out of the loop.
26837 \newline
26838
26839 \newline
26840 Strength Reduction
26841 \begin_inset LatexCommand \index{Strength reduction}
26842
26843 \end_inset
26844
26845 , this optimization substitutes an expression by a cheaper expression:
26846 \layout Verse
26847
26848
26849 \family typewriter
26850 for (i=0;i < 100; i++)
26851 \newline
26852 \SpecialChar ~
26853 \SpecialChar ~
26854 \SpecialChar ~
26855 \SpecialChar ~
26856 ar[i*5] = i*3;
26857 \layout Standard
26858
26859 changed to
26860 \layout Verse
26861
26862
26863 \family typewriter
26864 itemp1 = 0;
26865 \newline
26866 itemp2 = 0;
26867 \newline
26868 for (i=0;i< 100;i++) {
26869 \newline
26870 \SpecialChar ~
26871 \SpecialChar ~
26872 \SpecialChar ~
26873 \SpecialChar ~
26874 ar[itemp1] = itemp2;
26875 \newline
26876 \SpecialChar ~
26877 \SpecialChar ~
26878 \SpecialChar ~
26879 \SpecialChar ~
26880 itemp1 += 5;
26881 \newline
26882 \SpecialChar ~
26883 \SpecialChar ~
26884 \SpecialChar ~
26885 \SpecialChar ~
26886 itemp2 += 3;
26887 \newline
26888 }
26889 \layout Standard
26890
26891 The more expensive multiplication
26892 \begin_inset LatexCommand \index{Multiplication}
26893
26894 \end_inset
26895
26896  is changed to a less expensive addition.
26897 \layout Subsection
26898
26899 Loop Reversing
26900 \begin_inset LatexCommand \index{Loop reversing}
26901
26902 \end_inset
26903
26904
26905 \layout Standard
26906
26907 This optimization is done to reduce the overhead of checking loop boundaries
26908  for every iteration.
26909  Some simple loops can be reversed and implemented using a
26910 \begin_inset Quotes eld
26911 \end_inset
26912
26913 decrement and jump if not zero
26914 \begin_inset Quotes erd
26915 \end_inset
26916
26917  instruction.
26918  SDCC checks for the following criterion to determine if a loop is reversible
26919  (note: more sophisticated compilers use data-dependency analysis to make
26920  this determination, SDCC uses a more simple minded analysis).
26921 \layout Itemize
26922
26923 The 'for' loop is of the form
26924 \newline
26925
26926 \newline
26927
26928 \family typewriter
26929 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
26930  += 1])
26931 \newline
26932 \SpecialChar ~
26933 \SpecialChar ~
26934 \SpecialChar ~
26935 \SpecialChar ~
26936 <for body>
26937 \layout Itemize
26938
26939 The <for body> does not contain
26940 \begin_inset Quotes eld
26941 \end_inset
26942
26943 continue
26944 \begin_inset Quotes erd
26945 \end_inset
26946
26947  or 'break
26948 \begin_inset Quotes erd
26949 \end_inset
26950
26951 .
26952 \layout Itemize
26953
26954 All goto's are contained within the loop.
26955 \layout Itemize
26956
26957 No function calls within the loop.
26958 \layout Itemize
26959
26960 The loop control variable <sym> is not assigned any value within the loop
26961 \layout Itemize
26962
26963 The loop control variable does NOT participate in any arithmetic operation
26964  within the loop.
26965 \layout Itemize
26966
26967 There are NO switch statements in the loop.
26968 \layout Subsection
26969
26970 Algebraic Simplifications
26971 \layout Standard
26972
26973 SDCC does numerous algebraic simplifications, the following is a small sub-set
26974  of these optimizations.
26975 \layout Verse
26976
26977
26978 \family typewriter
26979 i = j + 0;\SpecialChar ~
26980 \SpecialChar ~
26981 \SpecialChar ~
26982 \SpecialChar ~
26983  /* changed to: */\SpecialChar ~
26984 \SpecialChar ~
26985 \SpecialChar ~
26986 \SpecialChar ~
26987  i = j;
26988 \newline
26989 i /= 2;\SpecialChar ~
26990 \SpecialChar ~
26991 \SpecialChar ~
26992 \SpecialChar ~
26993 \SpecialChar ~
26994 \SpecialChar ~
26995 \SpecialChar ~
26996  /* changed to: */\SpecialChar ~
26997 \SpecialChar ~
26998 \SpecialChar ~
26999 \SpecialChar ~
27000  i >>= 1;
27001 \newline
27002 i = j - j;\SpecialChar ~
27003 \SpecialChar ~
27004 \SpecialChar ~
27005 \SpecialChar ~
27006  /* changed to: */\SpecialChar ~
27007 \SpecialChar ~
27008 \SpecialChar ~
27009 \SpecialChar ~
27010  i = 0;
27011 \newline
27012 i = j / 1;\SpecialChar ~
27013 \SpecialChar ~
27014 \SpecialChar ~
27015 \SpecialChar ~
27016  /* changed to: */\SpecialChar ~
27017 \SpecialChar ~
27018 \SpecialChar ~
27019 \SpecialChar ~
27020  i = j;
27021 \layout Standard
27022
27023 Note the subexpressions
27024 \begin_inset LatexCommand \index{Subexpression}
27025
27026 \end_inset
27027
27028  given above are generally introduced by macro expansions or as a result
27029  of copy/constant propagation.
27030 \layout Subsection
27031
27032 'switch' Statements
27033 \begin_inset LatexCommand \label{sub:'switch'-Statements}
27034
27035 \end_inset
27036
27037
27038 \begin_inset LatexCommand \index{switch statement}
27039
27040 \end_inset
27041
27042
27043 \layout Standard
27044
27045 SDCC can optimize switch statements to jump tables
27046 \begin_inset LatexCommand \index{jump tables}
27047
27048 \end_inset
27049
27050 .
27051  It makes the decision based on an estimate of the generated code size.
27052  SDCC is quite liberal in the requirements for jump table generation:
27053 \layout Itemize
27054
27055 The labels need not be in order, and the starting number need not be one
27056  or zero, the case labels are in numerical sequence or not too many case
27057  labels are missing.
27058 \begin_deeper
27059 \layout Verse
27060
27061
27062 \family typewriter
27063 switch(i) {\SpecialChar ~
27064 \SpecialChar ~
27065 \SpecialChar ~
27066 \SpecialChar ~
27067 \SpecialChar ~
27068 \SpecialChar ~
27069 \SpecialChar ~
27070 \SpecialChar ~
27071 \SpecialChar ~
27072 \SpecialChar ~
27073 \SpecialChar ~
27074 \SpecialChar ~
27075 \SpecialChar ~
27076 \SpecialChar ~
27077 \SpecialChar ~
27078 \SpecialChar ~
27079 \SpecialChar ~
27080 \SpecialChar ~
27081 \SpecialChar ~
27082 \SpecialChar ~
27083 \SpecialChar ~
27084 \SpecialChar ~
27085 \SpecialChar ~
27086 \SpecialChar ~
27087 \SpecialChar ~
27088 \SpecialChar ~
27089 switch (i) {
27090 \newline
27091 \SpecialChar ~
27092 \SpecialChar ~
27093 \SpecialChar ~
27094 case 4: ...\SpecialChar ~
27095 \SpecialChar ~
27096 \SpecialChar ~
27097 \SpecialChar ~
27098 \SpecialChar ~
27099 \SpecialChar ~
27100 \SpecialChar ~
27101 \SpecialChar ~
27102 \SpecialChar ~
27103 \SpecialChar ~
27104 \SpecialChar ~
27105 \SpecialChar ~
27106 \SpecialChar ~
27107 \SpecialChar ~
27108 \SpecialChar ~
27109 \SpecialChar ~
27110 \SpecialChar ~
27111 \SpecialChar ~
27112 \SpecialChar ~
27113 \SpecialChar ~
27114 \SpecialChar ~
27115 \SpecialChar ~
27116 \SpecialChar ~
27117 \SpecialChar ~
27118 \SpecialChar ~
27119 \SpecialChar ~
27120 case 0: ...
27121
27122 \newline
27123 \SpecialChar ~
27124 \SpecialChar ~
27125 \SpecialChar ~
27126 case 5: ...\SpecialChar ~
27127 \SpecialChar ~
27128 \SpecialChar ~
27129 \SpecialChar ~
27130 \SpecialChar ~
27131 \SpecialChar ~
27132 \SpecialChar ~
27133 \SpecialChar ~
27134 \SpecialChar ~
27135 \SpecialChar ~
27136 \SpecialChar ~
27137 \SpecialChar ~
27138 \SpecialChar ~
27139 \SpecialChar ~
27140 \SpecialChar ~
27141 \SpecialChar ~
27142 \SpecialChar ~
27143 \SpecialChar ~
27144 \SpecialChar ~
27145 \SpecialChar ~
27146 \SpecialChar ~
27147 \SpecialChar ~
27148 \SpecialChar ~
27149 \SpecialChar ~
27150 \SpecialChar ~
27151 \SpecialChar ~
27152 case 1: ...
27153
27154 \newline
27155 \SpecialChar ~
27156 \SpecialChar ~
27157 \SpecialChar ~
27158 case 3: ...\SpecialChar ~
27159 \SpecialChar ~
27160 \SpecialChar ~
27161 \SpecialChar ~
27162 \SpecialChar ~
27163 \SpecialChar ~
27164 \SpecialChar ~
27165 \SpecialChar ~
27166 \SpecialChar ~
27167 \SpecialChar ~
27168 \SpecialChar ~
27169 \SpecialChar ~
27170 \SpecialChar ~
27171 \SpecialChar ~
27172 \SpecialChar ~
27173 \SpecialChar ~
27174 \SpecialChar ~
27175 \SpecialChar ~
27176 \SpecialChar ~
27177 \SpecialChar ~
27178 \SpecialChar ~
27179 \SpecialChar ~
27180 \SpecialChar ~
27181 \SpecialChar ~
27182 \SpecialChar ~
27183 \SpecialChar ~
27184
27185 \newline
27186 \SpecialChar ~
27187 \SpecialChar ~
27188 \SpecialChar ~
27189 case 6: ...\SpecialChar ~
27190 \SpecialChar ~
27191 \SpecialChar ~
27192 \SpecialChar ~
27193 \SpecialChar ~
27194 \SpecialChar ~
27195 \SpecialChar ~
27196 \SpecialChar ~
27197 \SpecialChar ~
27198 \SpecialChar ~
27199 \SpecialChar ~
27200 \SpecialChar ~
27201 \SpecialChar ~
27202 \SpecialChar ~
27203 \SpecialChar ~
27204 \SpecialChar ~
27205 \SpecialChar ~
27206 \SpecialChar ~
27207 \SpecialChar ~
27208 \SpecialChar ~
27209 \SpecialChar ~
27210 \SpecialChar ~
27211 \SpecialChar ~
27212 \SpecialChar ~
27213 \SpecialChar ~
27214 \SpecialChar ~
27215 case 3: ...
27216
27217 \newline
27218 \SpecialChar ~
27219 \SpecialChar ~
27220 \SpecialChar ~
27221 case 7: ...\SpecialChar ~
27222 \SpecialChar ~
27223 \SpecialChar ~
27224 \SpecialChar ~
27225 \SpecialChar ~
27226 \SpecialChar ~
27227 \SpecialChar ~
27228 \SpecialChar ~
27229 \SpecialChar ~
27230 \SpecialChar ~
27231 \SpecialChar ~
27232 \SpecialChar ~
27233 \SpecialChar ~
27234 \SpecialChar ~
27235 \SpecialChar ~
27236 \SpecialChar ~
27237 \SpecialChar ~
27238 \SpecialChar ~
27239 \SpecialChar ~
27240 \SpecialChar ~
27241 \SpecialChar ~
27242 \SpecialChar ~
27243 \SpecialChar ~
27244 \SpecialChar ~
27245 \SpecialChar ~
27246 \SpecialChar ~
27247 case 4: ...
27248
27249 \newline
27250 \SpecialChar ~
27251 \SpecialChar ~
27252 \SpecialChar ~
27253 case 8: ...\SpecialChar ~
27254 \SpecialChar ~
27255 \SpecialChar ~
27256 \SpecialChar ~
27257 \SpecialChar ~
27258 \SpecialChar ~
27259 \SpecialChar ~
27260 \SpecialChar ~
27261 \SpecialChar ~
27262 \SpecialChar ~
27263 \SpecialChar ~
27264 \SpecialChar ~
27265 \SpecialChar ~
27266 \SpecialChar ~
27267 \SpecialChar ~
27268 \SpecialChar ~
27269 \SpecialChar ~
27270 \SpecialChar ~
27271 \SpecialChar ~
27272 \SpecialChar ~
27273 \SpecialChar ~
27274 \SpecialChar ~
27275 \SpecialChar ~
27276 \SpecialChar ~
27277 \SpecialChar ~
27278 \SpecialChar ~
27279 case 5: ...
27280
27281 \newline
27282 \SpecialChar ~
27283 \SpecialChar ~
27284 \SpecialChar ~
27285 case 9: ...\SpecialChar ~
27286 \SpecialChar ~
27287 \SpecialChar ~
27288 \SpecialChar ~
27289 \SpecialChar ~
27290 \SpecialChar ~
27291 \SpecialChar ~
27292 \SpecialChar ~
27293 \SpecialChar ~
27294 \SpecialChar ~
27295 \SpecialChar ~
27296 \SpecialChar ~
27297 \SpecialChar ~
27298 \SpecialChar ~
27299 \SpecialChar ~
27300 \SpecialChar ~
27301 \SpecialChar ~
27302 \SpecialChar ~
27303 \SpecialChar ~
27304 \SpecialChar ~
27305 \SpecialChar ~
27306 \SpecialChar ~
27307 \SpecialChar ~
27308 \SpecialChar ~
27309 \SpecialChar ~
27310 \SpecialChar ~
27311 case 6: ...
27312
27313 \newline
27314 \SpecialChar ~
27315 \SpecialChar ~
27316 \SpecialChar ~
27317 case 10: ...\SpecialChar ~
27318 \SpecialChar ~
27319 \SpecialChar ~
27320 \SpecialChar ~
27321 \SpecialChar ~
27322 \SpecialChar ~
27323 \SpecialChar ~
27324 \SpecialChar ~
27325 \SpecialChar ~
27326 \SpecialChar ~
27327 \SpecialChar ~
27328 \SpecialChar ~
27329 \SpecialChar ~
27330 \SpecialChar ~
27331 \SpecialChar ~
27332 \SpecialChar ~
27333 \SpecialChar ~
27334 \SpecialChar ~
27335 \SpecialChar ~
27336 \SpecialChar ~
27337 \SpecialChar ~
27338 \SpecialChar ~
27339 \SpecialChar ~
27340 \SpecialChar ~
27341 \SpecialChar ~
27342 case 7: ...
27343
27344 \newline
27345 \SpecialChar ~
27346 \SpecialChar ~
27347 \SpecialChar ~
27348 case 11: ...\SpecialChar ~
27349 \SpecialChar ~
27350 \SpecialChar ~
27351 \SpecialChar ~
27352 \SpecialChar ~
27353 \SpecialChar ~
27354 \SpecialChar ~
27355 \SpecialChar ~
27356 \SpecialChar ~
27357 \SpecialChar ~
27358 \SpecialChar ~
27359 \SpecialChar ~
27360 \SpecialChar ~
27361 \SpecialChar ~
27362 \SpecialChar ~
27363 \SpecialChar ~
27364 \SpecialChar ~
27365 \SpecialChar ~
27366 \SpecialChar ~
27367 \SpecialChar ~
27368 \SpecialChar ~
27369 \SpecialChar ~
27370 \SpecialChar ~
27371 \SpecialChar ~
27372 \SpecialChar ~
27373 case 8: ...
27374
27375 \newline
27376 }\SpecialChar ~
27377 \SpecialChar ~
27378 \SpecialChar ~
27379 \SpecialChar ~
27380 \SpecialChar ~
27381 \SpecialChar ~
27382 \SpecialChar ~
27383 \SpecialChar ~
27384 \SpecialChar ~
27385 \SpecialChar ~
27386 \SpecialChar ~
27387 \SpecialChar ~
27388 \SpecialChar ~
27389 \SpecialChar ~
27390 \SpecialChar ~
27391 \SpecialChar ~
27392 \SpecialChar ~
27393 \SpecialChar ~
27394 \SpecialChar ~
27395 \SpecialChar ~
27396 \SpecialChar ~
27397 \SpecialChar ~
27398 \SpecialChar ~
27399 \SpecialChar ~
27400 \SpecialChar ~
27401 \SpecialChar ~
27402 \SpecialChar ~
27403 \SpecialChar ~
27404 \SpecialChar ~
27405 \SpecialChar ~
27406 \SpecialChar ~
27407 \SpecialChar ~
27408 \SpecialChar ~
27409 \SpecialChar ~
27410 \SpecialChar ~
27411 \SpecialChar ~
27412 }
27413 \layout Standard
27414
27415 Both the above switch statements will be implemented using a jump-table.
27416  The example to the right side is slightly more efficient as the check for
27417  the lower boundary of the jump-table is not needed.
27418 \end_deeper
27419 \layout Itemize
27420
27421 The number of case labels is not larger than supported by the target architectur
27422 e.
27423 \layout Itemize
27424
27425 If the case labels are not in numerical sequence ('gaps' between cases)
27426  SDCC checks whether a jump table with additionally inserted dummy cases
27427  is still attractive.
27428
27429 \layout Itemize
27430
27431 If the starting number is not zero and a check for the lower boundary of
27432  the jump-table can thus be eliminated SDCC might insert dummy cases 0,
27433  ...
27434  .
27435 \layout Standard
27436
27437 Switch statements which have large gaps in the numeric sequence or those
27438  that have too many case labels can be split into more than one switch statement
27439  for efficient code generation, e.g.:
27440 \layout Verse
27441
27442
27443 \family typewriter
27444 switch (i) {
27445 \newline
27446 \SpecialChar ~
27447 \SpecialChar ~
27448 case 1: ...
27449
27450 \newline
27451 \SpecialChar ~
27452 \SpecialChar ~
27453 case 2: ...
27454
27455 \newline
27456 \SpecialChar ~
27457 \SpecialChar ~
27458 case 3: ...
27459
27460 \newline
27461 \SpecialChar ~
27462 \SpecialChar ~
27463 case 4: ...
27464
27465 \newline
27466 \SpecialChar ~
27467 \SpecialChar ~
27468 case 5: ...
27469
27470 \newline
27471 \SpecialChar ~
27472 \SpecialChar ~
27473 case 6: ...
27474
27475 \newline
27476 \SpecialChar ~
27477 \SpecialChar ~
27478 case 7: ...
27479
27480 \newline
27481 \SpecialChar ~
27482 \SpecialChar ~
27483 case 101: ...
27484
27485 \newline
27486 \SpecialChar ~
27487 \SpecialChar ~
27488 case 102: ...
27489
27490 \newline
27491 \SpecialChar ~
27492 \SpecialChar ~
27493 case 103: ...
27494
27495 \newline
27496 \SpecialChar ~
27497 \SpecialChar ~
27498 case 104: ...
27499
27500 \newline
27501 \SpecialChar ~
27502 \SpecialChar ~
27503 case 105: ...
27504
27505 \newline
27506 \SpecialChar ~
27507 \SpecialChar ~
27508 case 106: ...
27509
27510 \newline
27511 \SpecialChar ~
27512 \SpecialChar ~
27513 case 107: ...
27514
27515 \newline
27516 }
27517 \layout Standard
27518
27519 If the above switch statement is broken down into two switch statements
27520 \layout Verse
27521
27522
27523 \family typewriter
27524 switch (i) {
27525 \newline
27526 \SpecialChar ~
27527 \SpecialChar ~
27528 case 1: ...
27529
27530 \newline
27531 \SpecialChar ~
27532 \SpecialChar ~
27533 case 2: ...
27534
27535 \newline
27536 \SpecialChar ~
27537 \SpecialChar ~
27538 case 3: ...
27539
27540 \newline
27541 \SpecialChar ~
27542 \SpecialChar ~
27543 case 4: ...
27544
27545 \newline
27546 \SpecialChar ~
27547 \SpecialChar ~
27548 case 5: ...
27549
27550 \newline
27551 \SpecialChar ~
27552 \SpecialChar ~
27553 case 6: ...
27554
27555 \newline
27556 \SpecialChar ~
27557 \SpecialChar ~
27558 case 7: ...
27559
27560 \newline
27561 }
27562 \layout Standard
27563
27564 and
27565 \layout Verse
27566
27567
27568 \family typewriter
27569 switch (i) {
27570 \newline
27571 \SpecialChar ~
27572 \SpecialChar ~
27573 case 101: ...
27574
27575 \newline
27576 \SpecialChar ~
27577 \SpecialChar ~
27578 case 102: ...
27579
27580 \newline
27581 \SpecialChar ~
27582 \SpecialChar ~
27583 case 103: ...
27584
27585 \newline
27586 \SpecialChar ~
27587 \SpecialChar ~
27588 case 104: ...
27589
27590 \newline
27591 \SpecialChar ~
27592 \SpecialChar ~
27593 case 105: ...
27594
27595 \newline
27596 \SpecialChar ~
27597 \SpecialChar ~
27598 case 106: ...
27599
27600 \newline
27601 \SpecialChar ~
27602 \SpecialChar ~
27603 case 107: ...
27604
27605 \newline
27606 }
27607 \layout Standard
27608
27609 then both the switch statements will be implemented using jump-tables whereas
27610  the unmodified switch statement will not be.
27611 \layout Comment
27612
27613 There might be reasons which SDCC cannot know about to either favour or
27614  not favour jump tables.
27615  If the target system has to be as quick for the last switch case as for
27616  the first (pro jump table), or if the switch argument is known to be zero
27617  in the majority of the cases (contra jump table).
27618 \layout Standard
27619
27620 The pragma nojtbound
27621 \begin_inset LatexCommand \index{\#pragma nojtbound}
27622
27623 \end_inset
27624
27625  can be used to turn off checking the
27626 \emph on
27627 j
27628 \emph default
27629 ump
27630 \emph on
27631 t
27632 \emph default
27633 able
27634 \emph on
27635 bound
27636 \emph default
27637 aries.
27638  It has no effect if a default label is supplied.
27639  Use of this pragma is dangerous: if the switch
27640 \begin_inset LatexCommand \index{switch statement}
27641
27642 \end_inset
27643
27644  argument is not matched by a case statement the processor will happily
27645  jump into Nirvana.
27646 \layout Subsection
27647
27648 Bit-shifting Operations
27649 \begin_inset LatexCommand \index{Bit shifting}
27650
27651 \end_inset
27652
27653 .
27654 \layout Standard
27655
27656 Bit shifting is one of the most frequently used operation in embedded programmin
27657 g.
27658  SDCC tries to implement bit-shift operations in the most efficient way
27659  possible, e.g.:
27660 \layout Verse
27661
27662
27663 \family typewriter
27664 unsigned char i;
27665 \newline
27666 ...
27667
27668 \newline
27669 i >>= 4;
27670 \newline
27671 ...
27672 \layout Standard
27673
27674 generates the following code:
27675 \layout Verse
27676
27677
27678 \family typewriter
27679 mov\SpecialChar ~
27680  a,_i
27681 \newline
27682 swap a
27683 \newline
27684 anl\SpecialChar ~
27685  a,#0x0f
27686 \newline
27687 mov\SpecialChar ~
27688  _i,a
27689 \layout Standard
27690
27691 In general SDCC will never setup a loop if the shift count is known.
27692  Another example:
27693 \layout Verse
27694
27695
27696 \family typewriter
27697 unsigned int i;
27698 \newline
27699 ...
27700
27701 \newline
27702 i >>= 9;
27703 \newline
27704 ...
27705 \layout Standard
27706
27707 will generate:
27708 \layout Verse
27709
27710
27711 \family typewriter
27712 mov\SpecialChar ~
27713 \SpecialChar ~
27714 a,(_i + 1)
27715 \newline
27716 mov\SpecialChar ~
27717 \SpecialChar ~
27718 (_i + 1),#0x00
27719 \newline
27720 clr\SpecialChar ~
27721 \SpecialChar ~
27722 c
27723 \newline
27724 rrc\SpecialChar ~
27725 \SpecialChar ~
27726 a
27727 \newline
27728 mov\SpecialChar ~
27729 \SpecialChar ~
27730 _i,a
27731 \layout Subsection
27732
27733 Bit-rotation
27734 \begin_inset LatexCommand \index{Bit rotation}
27735
27736 \end_inset
27737
27738
27739 \layout Standard
27740
27741 A special case of the bit-shift operation is bit rotation
27742 \begin_inset LatexCommand \index{rotating bits}
27743
27744 \end_inset
27745
27746 , SDCC recognizes the following expression to be a left bit-rotation:
27747 \layout Verse
27748
27749
27750 \family typewriter
27751 \series bold
27752 unsigned
27753 \series default
27754 \SpecialChar ~
27755 \SpecialChar ~
27756 char i;\SpecialChar ~
27757 \SpecialChar ~
27758 \SpecialChar ~
27759 \SpecialChar ~
27760 \SpecialChar ~
27761 \SpecialChar ~
27762 \SpecialChar ~
27763 \SpecialChar ~
27764 \SpecialChar ~
27765 \SpecialChar ~
27766 \SpecialChar ~
27767 /* unsigned is needed for rotation */
27768 \newline
27769 ...
27770
27771 \newline
27772 i = ((i << 1) | (i >> 7));
27773 \family default
27774
27775 \newline
27776
27777 \family typewriter
27778 ...
27779 \layout Standard
27780
27781 will generate the following code:
27782 \layout Verse
27783
27784
27785 \family typewriter
27786 mov\SpecialChar ~
27787 \SpecialChar ~
27788 a,_i
27789 \newline
27790 rl\SpecialChar ~
27791 \SpecialChar ~
27792 \SpecialChar ~
27793 a
27794 \newline
27795 mov\SpecialChar ~
27796 \SpecialChar ~
27797 _i,a
27798 \layout Standard
27799
27800 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
27801 ns of this case will also be recognized as bit-rotation, i.e.:
27802 \layout Verse
27803
27804
27805 \family typewriter
27806 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
27807 \layout Subsection
27808
27809 Nibble and Byte Swapping
27810 \layout Standard
27811
27812 Other special cases of the bit-shift operations are nibble or byte swapping
27813 \begin_inset LatexCommand \index{swapping nibbles/bytes}
27814
27815 \end_inset
27816
27817 , SDCC recognizes the following expressions:
27818 \layout Verse
27819
27820
27821 \family typewriter
27822 \series bold
27823 unsigned
27824 \series default
27825 \SpecialChar ~
27826 \SpecialChar ~
27827 char i;
27828 \newline
27829
27830 \series bold
27831 unsigned
27832 \series default
27833 \SpecialChar ~
27834 \SpecialChar ~
27835 int j;
27836 \newline
27837 ...
27838
27839 \newline
27840 i = ((i << 4) | (i >> 4));
27841 \family default
27842
27843 \newline
27844
27845 \family typewriter
27846 j = ((j << 8) | (j >> 8));
27847 \layout Standard
27848
27849 and generates a swap instruction for the nibble swapping
27850 \begin_inset LatexCommand \index{Nibble swapping}
27851
27852 \end_inset
27853
27854  or move instructions for the byte swapping
27855 \begin_inset LatexCommand \index{Byte swapping}
27856
27857 \end_inset
27858
27859 .
27860  The
27861 \begin_inset Quotes sld
27862 \end_inset
27863
27864 j
27865 \begin_inset Quotes srd
27866 \end_inset
27867
27868  example can be used to convert from little to big-endian or vice versa.
27869  If you want to change the endianness of a
27870 \emph on
27871 signed
27872 \emph default
27873  integer you have to cast to
27874 \family typewriter
27875 (unsigned int)
27876 \family default
27877  first.
27878 \layout Standard
27879
27880 Note that SDCC stores numbers in little-endian
27881 \begin_inset Foot
27882 collapsed false
27883
27884 \layout Standard
27885
27886 Usually 8-bit processors don't care much about endianness.
27887  This is not the case for the standard 8051 which only has an instruction
27888  to increment its
27889 \emph on
27890 dptr
27891 \emph default
27892
27893 \begin_inset LatexCommand \index{DPTR}
27894
27895 \end_inset
27896
27897 -datapointer
27898 \emph on
27899
27900 \emph default
27901 so little-endian is the more efficient byte order.
27902 \end_inset
27903
27904
27905 \begin_inset LatexCommand \index{little-endian}
27906
27907 \end_inset
27908
27909
27910 \begin_inset LatexCommand \index{Endianness}
27911
27912 \end_inset
27913
27914  format (i.e.
27915  lowest order first).
27916 \layout Subsection
27917
27918 Highest Order Bit
27919 \begin_inset LatexCommand \index{Highest Order Bit}
27920
27921 \end_inset
27922
27923  / Any Order Bit
27924 \begin_inset LatexCommand \index{Any Order Bit}
27925
27926 \end_inset
27927
27928
27929 \layout Standard
27930
27931 It is frequently required to obtain the highest order bit of an integral
27932  type (long, int, short or char types).
27933  Also obtaining any other order bit is not uncommon.
27934  SDCC recognizes the following expressions to yield the highest order bit
27935  and generates optimized code for it, e.g.:
27936 \layout Verse
27937
27938
27939 \family typewriter
27940 unsigned int gint;
27941 \newline
27942
27943 \newline
27944 foo () {
27945 \newline
27946 \SpecialChar ~
27947 \SpecialChar ~
27948 unsigned char hob1, aob1;
27949 \newline
27950 \SpecialChar ~
27951 \SpecialChar ~
27952 bit hob2, hob3, aob2, aob3;
27953 \newline
27954 \SpecialChar ~
27955 \SpecialChar ~
27956 ...
27957
27958 \newline
27959 \SpecialChar ~
27960 \SpecialChar ~
27961 hob1 = (gint >> 15) & 1;
27962 \newline
27963 \SpecialChar ~
27964 \SpecialChar ~
27965 hob2 = (gint >> 15) & 1;
27966 \newline
27967 \SpecialChar ~
27968 \SpecialChar ~
27969 hob3 = gint & 0x8000;
27970 \newline
27971 \SpecialChar ~
27972 \SpecialChar ~
27973 aob1 = (gint >> 9) & 1;
27974 \newline
27975 \SpecialChar ~
27976 \SpecialChar ~
27977 aob2 = (gint >> 8) & 1;
27978 \newline
27979 \SpecialChar ~
27980 \SpecialChar ~
27981 aob3 = gint & 0x0800;
27982 \newline
27983 \SpecialChar ~
27984 \SpecialChar ~
27985 ..
27986
27987 \newline
27988 }
27989 \layout Standard
27990
27991 will generate the following code:
27992 \layout Verse
27993
27994
27995 \family typewriter
27996 \SpecialChar ~
27997 \SpecialChar ~
27998 \SpecialChar ~
27999 \SpecialChar ~
28000 \SpecialChar ~
28001 \SpecialChar ~
28002 \SpecialChar ~
28003 \SpecialChar ~
28004 \SpecialChar ~
28005 \SpecialChar ~
28006 \SpecialChar ~
28007 \SpecialChar ~
28008 \SpecialChar ~
28009 \SpecialChar ~
28010 \SpecialChar ~
28011 \SpecialChar ~
28012 \SpecialChar ~
28013 \SpecialChar ~
28014 \SpecialChar ~
28015 \SpecialChar ~
28016 \SpecialChar ~
28017 \SpecialChar ~
28018 \SpecialChar ~
28019 \SpecialChar ~
28020 \SpecialChar ~
28021  61 ;\SpecialChar ~
28022  hob.c 7
28023 \newline
28024 000A E5*01\SpecialChar ~
28025 \SpecialChar ~
28026 \SpecialChar ~
28027 \SpecialChar ~
28028 \SpecialChar ~
28029 \SpecialChar ~
28030 \SpecialChar ~
28031 \SpecialChar ~
28032 \SpecialChar ~
28033 \SpecialChar ~
28034 \SpecialChar ~
28035 \SpecialChar ~
28036 \SpecialChar ~
28037 \SpecialChar ~
28038 \SpecialChar ~
28039  62\SpecialChar ~
28040 \SpecialChar ~
28041 \SpecialChar ~
28042 \SpecialChar ~
28043 \SpecialChar ~
28044 \SpecialChar ~
28045 \SpecialChar ~
28046 \SpecialChar ~
28047  mov\SpecialChar ~
28048 \SpecialChar ~
28049  a,(_gint + 1)
28050 \newline
28051 000C 23\SpecialChar ~
28052 \SpecialChar ~
28053 \SpecialChar ~
28054 \SpecialChar ~
28055 \SpecialChar ~
28056 \SpecialChar ~
28057 \SpecialChar ~
28058 \SpecialChar ~
28059 \SpecialChar ~
28060 \SpecialChar ~
28061 \SpecialChar ~
28062 \SpecialChar ~
28063 \SpecialChar ~
28064 \SpecialChar ~
28065 \SpecialChar ~
28066 \SpecialChar ~
28067 \SpecialChar ~
28068 \SpecialChar ~
28069  63\SpecialChar ~
28070 \SpecialChar ~
28071 \SpecialChar ~
28072 \SpecialChar ~
28073 \SpecialChar ~
28074 \SpecialChar ~
28075 \SpecialChar ~
28076 \SpecialChar ~
28077  rl\SpecialChar ~
28078 \SpecialChar ~
28079 \SpecialChar ~
28080  a
28081 \newline
28082 000D 54 01\SpecialChar ~
28083 \SpecialChar ~
28084 \SpecialChar ~
28085 \SpecialChar ~
28086 \SpecialChar ~
28087 \SpecialChar ~
28088 \SpecialChar ~
28089 \SpecialChar ~
28090 \SpecialChar ~
28091 \SpecialChar ~
28092 \SpecialChar ~
28093 \SpecialChar ~
28094 \SpecialChar ~
28095 \SpecialChar ~
28096 \SpecialChar ~
28097  64\SpecialChar ~
28098 \SpecialChar ~
28099 \SpecialChar ~
28100 \SpecialChar ~
28101 \SpecialChar ~
28102 \SpecialChar ~
28103 \SpecialChar ~
28104 \SpecialChar ~
28105  anl\SpecialChar ~
28106 \SpecialChar ~
28107  a,#0x01
28108 \newline
28109 000F F5*02\SpecialChar ~
28110 \SpecialChar ~
28111 \SpecialChar ~
28112 \SpecialChar ~
28113 \SpecialChar ~
28114 \SpecialChar ~
28115 \SpecialChar ~
28116 \SpecialChar ~
28117 \SpecialChar ~
28118 \SpecialChar ~
28119 \SpecialChar ~
28120 \SpecialChar ~
28121 \SpecialChar ~
28122 \SpecialChar ~
28123 \SpecialChar ~
28124  65\SpecialChar ~
28125 \SpecialChar ~
28126 \SpecialChar ~
28127 \SpecialChar ~
28128 \SpecialChar ~
28129 \SpecialChar ~
28130 \SpecialChar ~
28131 \SpecialChar ~
28132  mov\SpecialChar ~
28133 \SpecialChar ~
28134  _foo_hob1_1_1,a
28135 \newline
28136 \SpecialChar ~
28137 \SpecialChar ~
28138 \SpecialChar ~
28139 \SpecialChar ~
28140 \SpecialChar ~
28141 \SpecialChar ~
28142 \SpecialChar ~
28143 \SpecialChar ~
28144 \SpecialChar ~
28145 \SpecialChar ~
28146 \SpecialChar ~
28147 \SpecialChar ~
28148 \SpecialChar ~
28149 \SpecialChar ~
28150 \SpecialChar ~
28151 \SpecialChar ~
28152 \SpecialChar ~
28153 \SpecialChar ~
28154 \SpecialChar ~
28155 \SpecialChar ~
28156 \SpecialChar ~
28157 \SpecialChar ~
28158 \SpecialChar ~
28159 \SpecialChar ~
28160 \SpecialChar ~
28161  66 ;\SpecialChar ~
28162  hob.c 8
28163 \newline
28164 0011 E5*01\SpecialChar ~
28165 \SpecialChar ~
28166 \SpecialChar ~
28167 \SpecialChar ~
28168 \SpecialChar ~
28169 \SpecialChar ~
28170 \SpecialChar ~
28171 \SpecialChar ~
28172 \SpecialChar ~
28173 \SpecialChar ~
28174 \SpecialChar ~
28175 \SpecialChar ~
28176 \SpecialChar ~
28177 \SpecialChar ~
28178 \SpecialChar ~
28179  67\SpecialChar ~
28180 \SpecialChar ~
28181 \SpecialChar ~
28182 \SpecialChar ~
28183 \SpecialChar ~
28184 \SpecialChar ~
28185 \SpecialChar ~
28186 \SpecialChar ~
28187  mov\SpecialChar ~
28188 \SpecialChar ~
28189  a,(_gint + 1)
28190 \newline
28191 0013 33\SpecialChar ~
28192 \SpecialChar ~
28193 \SpecialChar ~
28194 \SpecialChar ~
28195 \SpecialChar ~
28196 \SpecialChar ~
28197 \SpecialChar ~
28198 \SpecialChar ~
28199 \SpecialChar ~
28200 \SpecialChar ~
28201 \SpecialChar ~
28202 \SpecialChar ~
28203 \SpecialChar ~
28204 \SpecialChar ~
28205 \SpecialChar ~
28206 \SpecialChar ~
28207 \SpecialChar ~
28208 \SpecialChar ~
28209  68\SpecialChar ~
28210 \SpecialChar ~
28211 \SpecialChar ~
28212 \SpecialChar ~
28213 \SpecialChar ~
28214 \SpecialChar ~
28215 \SpecialChar ~
28216 \SpecialChar ~
28217  rlc\SpecialChar ~
28218 \SpecialChar ~
28219  a
28220 \newline
28221 0014 92*00\SpecialChar ~
28222 \SpecialChar ~
28223 \SpecialChar ~
28224 \SpecialChar ~
28225 \SpecialChar ~
28226 \SpecialChar ~
28227 \SpecialChar ~
28228 \SpecialChar ~
28229 \SpecialChar ~
28230 \SpecialChar ~
28231 \SpecialChar ~
28232 \SpecialChar ~
28233 \SpecialChar ~
28234 \SpecialChar ~
28235 \SpecialChar ~
28236  69\SpecialChar ~
28237 \SpecialChar ~
28238 \SpecialChar ~
28239 \SpecialChar ~
28240 \SpecialChar ~
28241 \SpecialChar ~
28242 \SpecialChar ~
28243 \SpecialChar ~
28244  mov\SpecialChar ~
28245 \SpecialChar ~
28246  _foo_hob2_1_1,c
28247 \newline
28248 \SpecialChar ~
28249 \SpecialChar ~
28250 \SpecialChar ~
28251 \SpecialChar ~
28252 \SpecialChar ~
28253 \SpecialChar ~
28254 \SpecialChar ~
28255 \SpecialChar ~
28256 \SpecialChar ~
28257 \SpecialChar ~
28258 \SpecialChar ~
28259 \SpecialChar ~
28260 \SpecialChar ~
28261 \SpecialChar ~
28262 \SpecialChar ~
28263 \SpecialChar ~
28264 \SpecialChar ~
28265 \SpecialChar ~
28266 \SpecialChar ~
28267 \SpecialChar ~
28268 \SpecialChar ~
28269 \SpecialChar ~
28270 \SpecialChar ~
28271 \SpecialChar ~
28272 \SpecialChar ~
28273  66 ;\SpecialChar ~
28274  hob.c 9
28275 \newline
28276 0016 E5*01\SpecialChar ~
28277 \SpecialChar ~
28278 \SpecialChar ~
28279 \SpecialChar ~
28280 \SpecialChar ~
28281 \SpecialChar ~
28282 \SpecialChar ~
28283 \SpecialChar ~
28284 \SpecialChar ~
28285 \SpecialChar ~
28286 \SpecialChar ~
28287 \SpecialChar ~
28288 \SpecialChar ~
28289 \SpecialChar ~
28290 \SpecialChar ~
28291  67\SpecialChar ~
28292 \SpecialChar ~
28293 \SpecialChar ~
28294 \SpecialChar ~
28295 \SpecialChar ~
28296 \SpecialChar ~
28297 \SpecialChar ~
28298 \SpecialChar ~
28299  mov\SpecialChar ~
28300 \SpecialChar ~
28301  a,(_gint + 1)
28302 \newline
28303 0018 33\SpecialChar ~
28304 \SpecialChar ~
28305 \SpecialChar ~
28306 \SpecialChar ~
28307 \SpecialChar ~
28308 \SpecialChar ~
28309 \SpecialChar ~
28310 \SpecialChar ~
28311 \SpecialChar ~
28312 \SpecialChar ~
28313 \SpecialChar ~
28314 \SpecialChar ~
28315 \SpecialChar ~
28316 \SpecialChar ~
28317 \SpecialChar ~
28318 \SpecialChar ~
28319 \SpecialChar ~
28320 \SpecialChar ~
28321  68\SpecialChar ~
28322 \SpecialChar ~
28323 \SpecialChar ~
28324 \SpecialChar ~
28325 \SpecialChar ~
28326 \SpecialChar ~
28327 \SpecialChar ~
28328 \SpecialChar ~
28329  rlc\SpecialChar ~
28330 \SpecialChar ~
28331  a
28332 \newline
28333 0019 92*01\SpecialChar ~
28334 \SpecialChar ~
28335 \SpecialChar ~
28336 \SpecialChar ~
28337 \SpecialChar ~
28338 \SpecialChar ~
28339 \SpecialChar ~
28340 \SpecialChar ~
28341 \SpecialChar ~
28342 \SpecialChar ~
28343 \SpecialChar ~
28344 \SpecialChar ~
28345 \SpecialChar ~
28346 \SpecialChar ~
28347 \SpecialChar ~
28348  69\SpecialChar ~
28349 \SpecialChar ~
28350 \SpecialChar ~
28351 \SpecialChar ~
28352 \SpecialChar ~
28353 \SpecialChar ~
28354 \SpecialChar ~
28355 \SpecialChar ~
28356  mov\SpecialChar ~
28357 \SpecialChar ~
28358  _foo_hob3_1_1,c
28359 \newline
28360 \SpecialChar ~
28361 \SpecialChar ~
28362 \SpecialChar ~
28363 \SpecialChar ~
28364 \SpecialChar ~
28365 \SpecialChar ~
28366 \SpecialChar ~
28367 \SpecialChar ~
28368 \SpecialChar ~
28369 \SpecialChar ~
28370 \SpecialChar ~
28371 \SpecialChar ~
28372 \SpecialChar ~
28373 \SpecialChar ~
28374 \SpecialChar ~
28375 \SpecialChar ~
28376 \SpecialChar ~
28377 \SpecialChar ~
28378 \SpecialChar ~
28379 \SpecialChar ~
28380 \SpecialChar ~
28381 \SpecialChar ~
28382 \SpecialChar ~
28383 \SpecialChar ~
28384 \SpecialChar ~
28385  70 ;\SpecialChar ~
28386  hob.c 10
28387 \newline
28388 001B E5*01\SpecialChar ~
28389 \SpecialChar ~
28390 \SpecialChar ~
28391 \SpecialChar ~
28392 \SpecialChar ~
28393 \SpecialChar ~
28394 \SpecialChar ~
28395 \SpecialChar ~
28396 \SpecialChar ~
28397 \SpecialChar ~
28398 \SpecialChar ~
28399 \SpecialChar ~
28400 \SpecialChar ~
28401 \SpecialChar ~
28402 \SpecialChar ~
28403  71\SpecialChar ~
28404 \SpecialChar ~
28405 \SpecialChar ~
28406 \SpecialChar ~
28407 \SpecialChar ~
28408 \SpecialChar ~
28409 \SpecialChar ~
28410 \SpecialChar ~
28411  mov\SpecialChar ~
28412 \SpecialChar ~
28413  a,(_gint + 1)
28414 \newline
28415 001D 03\SpecialChar ~
28416 \SpecialChar ~
28417 \SpecialChar ~
28418 \SpecialChar ~
28419 \SpecialChar ~
28420 \SpecialChar ~
28421 \SpecialChar ~
28422 \SpecialChar ~
28423 \SpecialChar ~
28424 \SpecialChar ~
28425 \SpecialChar ~
28426 \SpecialChar ~
28427 \SpecialChar ~
28428 \SpecialChar ~
28429 \SpecialChar ~
28430 \SpecialChar ~
28431 \SpecialChar ~
28432 \SpecialChar ~
28433  72\SpecialChar ~
28434 \SpecialChar ~
28435 \SpecialChar ~
28436 \SpecialChar ~
28437 \SpecialChar ~
28438 \SpecialChar ~
28439 \SpecialChar ~
28440 \SpecialChar ~
28441  rr\SpecialChar ~
28442 \SpecialChar ~
28443 \SpecialChar ~
28444  a
28445 \newline
28446 001E 54 01\SpecialChar ~
28447 \SpecialChar ~
28448 \SpecialChar ~
28449 \SpecialChar ~
28450 \SpecialChar ~
28451 \SpecialChar ~
28452 \SpecialChar ~
28453 \SpecialChar ~
28454 \SpecialChar ~
28455 \SpecialChar ~
28456 \SpecialChar ~
28457 \SpecialChar ~
28458 \SpecialChar ~
28459 \SpecialChar ~
28460 \SpecialChar ~
28461  73\SpecialChar ~
28462 \SpecialChar ~
28463 \SpecialChar ~
28464 \SpecialChar ~
28465 \SpecialChar ~
28466 \SpecialChar ~
28467 \SpecialChar ~
28468 \SpecialChar ~
28469  anl\SpecialChar ~
28470 \SpecialChar ~
28471  a,#0x01
28472 \newline
28473 0020 F5*03\SpecialChar ~
28474 \SpecialChar ~
28475 \SpecialChar ~
28476 \SpecialChar ~
28477 \SpecialChar ~
28478 \SpecialChar ~
28479 \SpecialChar ~
28480 \SpecialChar ~
28481 \SpecialChar ~
28482 \SpecialChar ~
28483 \SpecialChar ~
28484 \SpecialChar ~
28485 \SpecialChar ~
28486 \SpecialChar ~
28487 \SpecialChar ~
28488  74\SpecialChar ~
28489 \SpecialChar ~
28490 \SpecialChar ~
28491 \SpecialChar ~
28492 \SpecialChar ~
28493 \SpecialChar ~
28494 \SpecialChar ~
28495 \SpecialChar ~
28496  mov\SpecialChar ~
28497 \SpecialChar ~
28498  _foo_aob1_1_1,a
28499 \newline
28500 \SpecialChar ~
28501 \SpecialChar ~
28502 \SpecialChar ~
28503 \SpecialChar ~
28504 \SpecialChar ~
28505 \SpecialChar ~
28506 \SpecialChar ~
28507 \SpecialChar ~
28508 \SpecialChar ~
28509 \SpecialChar ~
28510 \SpecialChar ~
28511 \SpecialChar ~
28512 \SpecialChar ~
28513 \SpecialChar ~
28514 \SpecialChar ~
28515 \SpecialChar ~
28516 \SpecialChar ~
28517 \SpecialChar ~
28518 \SpecialChar ~
28519 \SpecialChar ~
28520 \SpecialChar ~
28521 \SpecialChar ~
28522 \SpecialChar ~
28523 \SpecialChar ~
28524 \SpecialChar ~
28525  75 ;\SpecialChar ~
28526  hob.c 11
28527 \newline
28528 0022 E5*01\SpecialChar ~
28529 \SpecialChar ~
28530 \SpecialChar ~
28531 \SpecialChar ~
28532 \SpecialChar ~
28533 \SpecialChar ~
28534 \SpecialChar ~
28535 \SpecialChar ~
28536 \SpecialChar ~
28537 \SpecialChar ~
28538 \SpecialChar ~
28539 \SpecialChar ~
28540 \SpecialChar ~
28541 \SpecialChar ~
28542 \SpecialChar ~
28543  76\SpecialChar ~
28544 \SpecialChar ~
28545 \SpecialChar ~
28546 \SpecialChar ~
28547 \SpecialChar ~
28548 \SpecialChar ~
28549 \SpecialChar ~
28550 \SpecialChar ~
28551  mov\SpecialChar ~
28552 \SpecialChar ~
28553  a,(_gint + 1)
28554 \newline
28555 0024 13\SpecialChar ~
28556 \SpecialChar ~
28557 \SpecialChar ~
28558 \SpecialChar ~
28559 \SpecialChar ~
28560 \SpecialChar ~
28561 \SpecialChar ~
28562 \SpecialChar ~
28563 \SpecialChar ~
28564 \SpecialChar ~
28565 \SpecialChar ~
28566 \SpecialChar ~
28567 \SpecialChar ~
28568 \SpecialChar ~
28569 \SpecialChar ~
28570 \SpecialChar ~
28571 \SpecialChar ~
28572 \SpecialChar ~
28573  77\SpecialChar ~
28574 \SpecialChar ~
28575 \SpecialChar ~
28576 \SpecialChar ~
28577 \SpecialChar ~
28578 \SpecialChar ~
28579 \SpecialChar ~
28580 \SpecialChar ~
28581  rrc\SpecialChar ~
28582 \SpecialChar ~
28583  a
28584 \newline
28585 0025 92*02\SpecialChar ~
28586 \SpecialChar ~
28587 \SpecialChar ~
28588 \SpecialChar ~
28589 \SpecialChar ~
28590 \SpecialChar ~
28591 \SpecialChar ~
28592 \SpecialChar ~
28593 \SpecialChar ~
28594 \SpecialChar ~
28595 \SpecialChar ~
28596 \SpecialChar ~
28597 \SpecialChar ~
28598 \SpecialChar ~
28599 \SpecialChar ~
28600  78\SpecialChar ~
28601 \SpecialChar ~
28602 \SpecialChar ~
28603 \SpecialChar ~
28604 \SpecialChar ~
28605 \SpecialChar ~
28606 \SpecialChar ~
28607 \SpecialChar ~
28608  mov\SpecialChar ~
28609 \SpecialChar ~
28610  _foo_aob2_1_1,c
28611 \newline
28612 \SpecialChar ~
28613 \SpecialChar ~
28614 \SpecialChar ~
28615 \SpecialChar ~
28616 \SpecialChar ~
28617 \SpecialChar ~
28618 \SpecialChar ~
28619 \SpecialChar ~
28620 \SpecialChar ~
28621 \SpecialChar ~
28622 \SpecialChar ~
28623 \SpecialChar ~
28624 \SpecialChar ~
28625 \SpecialChar ~
28626 \SpecialChar ~
28627 \SpecialChar ~
28628 \SpecialChar ~
28629 \SpecialChar ~
28630 \SpecialChar ~
28631 \SpecialChar ~
28632 \SpecialChar ~
28633 \SpecialChar ~
28634 \SpecialChar ~
28635 \SpecialChar ~
28636 \SpecialChar ~
28637  79 ;\SpecialChar ~
28638  hob.c 12
28639 \newline
28640 0027 E5*01\SpecialChar ~
28641 \SpecialChar ~
28642 \SpecialChar ~
28643 \SpecialChar ~
28644 \SpecialChar ~
28645 \SpecialChar ~
28646 \SpecialChar ~
28647 \SpecialChar ~
28648 \SpecialChar ~
28649 \SpecialChar ~
28650 \SpecialChar ~
28651 \SpecialChar ~
28652 \SpecialChar ~
28653 \SpecialChar ~
28654 \SpecialChar ~
28655  80\SpecialChar ~
28656 \SpecialChar ~
28657 \SpecialChar ~
28658 \SpecialChar ~
28659 \SpecialChar ~
28660 \SpecialChar ~
28661 \SpecialChar ~
28662 \SpecialChar ~
28663  mov\SpecialChar ~
28664 \SpecialChar ~
28665  a,(_gint + 1)
28666 \newline
28667 0029 A2 E3\SpecialChar ~
28668 \SpecialChar ~
28669 \SpecialChar ~
28670 \SpecialChar ~
28671 \SpecialChar ~
28672 \SpecialChar ~
28673 \SpecialChar ~
28674 \SpecialChar ~
28675 \SpecialChar ~
28676 \SpecialChar ~
28677 \SpecialChar ~
28678 \SpecialChar ~
28679 \SpecialChar ~
28680 \SpecialChar ~
28681 \SpecialChar ~
28682  81\SpecialChar ~
28683 \SpecialChar ~
28684 \SpecialChar ~
28685 \SpecialChar ~
28686 \SpecialChar ~
28687 \SpecialChar ~
28688 \SpecialChar ~
28689 \SpecialChar ~
28690  mov\SpecialChar ~
28691 \SpecialChar ~
28692  c,acc[3]
28693 \newline
28694 002B 92*03\SpecialChar ~
28695 \SpecialChar ~
28696 \SpecialChar ~
28697 \SpecialChar ~
28698 \SpecialChar ~
28699 \SpecialChar ~
28700 \SpecialChar ~
28701 \SpecialChar ~
28702 \SpecialChar ~
28703 \SpecialChar ~
28704 \SpecialChar ~
28705 \SpecialChar ~
28706 \SpecialChar ~
28707 \SpecialChar ~
28708 \SpecialChar ~
28709  82\SpecialChar ~
28710 \SpecialChar ~
28711 \SpecialChar ~
28712 \SpecialChar ~
28713 \SpecialChar ~
28714 \SpecialChar ~
28715 \SpecialChar ~
28716 \SpecialChar ~
28717  mov\SpecialChar ~
28718 \SpecialChar ~
28719  _foo_aob3_1_1,c
28720 \layout Standard
28721
28722 Other variations of these cases however will
28723 \emph on
28724 not
28725 \emph default
28726  be recognized.
28727  They are standard C expressions, so I heartily recommend these be the only
28728  way to get the highest order bit, (it is portable).
28729  Of course it will be recognized even if it is embedded in other expressions,
28730  e.g.:
28731 \layout Verse
28732
28733
28734 \family typewriter
28735 xyz = gint + ((gint >> 15) & 1);
28736 \layout Standard
28737
28738 will still be recognized.
28739 \layout Subsection
28740
28741 Higher Order Byte
28742 \begin_inset LatexCommand \index{Higher Order Byte}
28743
28744 \end_inset
28745
28746  / Higher Order Word
28747 \begin_inset LatexCommand \index{Higher Order Word}
28748
28749 \end_inset
28750
28751
28752 \layout Standard
28753
28754 It is also frequently required to obtain a higher order byte or word of
28755  a larger integral type (long, int or short types).
28756  SDCC recognizes the following expressions to yield the higher order byte
28757  or word and generates optimized code for it, e.g.:
28758 \layout Verse
28759
28760
28761 \family typewriter
28762 unsigned int gint;
28763 \newline
28764 unsigned long int glong;
28765 \newline
28766
28767 \newline
28768 foo () {
28769 \newline
28770 \SpecialChar ~
28771 \SpecialChar ~
28772 unsigned char hob1, hob2;
28773 \newline
28774 \SpecialChar ~
28775 \SpecialChar ~
28776 unsigned int how1, how2;
28777 \newline
28778 \SpecialChar ~
28779 \SpecialChar ~
28780 ...
28781
28782 \newline
28783 \SpecialChar ~
28784 \SpecialChar ~
28785 hob1 = (gint >> 8) & 0xFF;
28786 \newline
28787 \SpecialChar ~
28788 \SpecialChar ~
28789 hob2 = glong >> 24;
28790 \newline
28791 \SpecialChar ~
28792 \SpecialChar ~
28793 how1 = (glong >> 16) & 0xFFFF;
28794 \newline
28795 \SpecialChar ~
28796 \SpecialChar ~
28797 how2 = glong >> 8;
28798 \newline
28799 \SpecialChar ~
28800 \SpecialChar ~
28801 ..
28802
28803 \newline
28804 }
28805 \layout Standard
28806
28807 will generate the following code:
28808 \layout Verse
28809
28810
28811 \family typewriter
28812 \SpecialChar ~
28813 \SpecialChar ~
28814 \SpecialChar ~
28815 \SpecialChar ~
28816 \SpecialChar ~
28817 \SpecialChar ~
28818 \SpecialChar ~
28819 \SpecialChar ~
28820 \SpecialChar ~
28821 \SpecialChar ~
28822 \SpecialChar ~
28823 \SpecialChar ~
28824 \SpecialChar ~
28825 \SpecialChar ~
28826 \SpecialChar ~
28827 \SpecialChar ~
28828 \SpecialChar ~
28829 \SpecialChar ~
28830 \SpecialChar ~
28831 \SpecialChar ~
28832 \SpecialChar ~
28833 \SpecialChar ~
28834 \SpecialChar ~
28835 \SpecialChar ~
28836 \SpecialChar ~
28837  91 ;\SpecialChar ~
28838  hob.c 15
28839 \newline
28840 0037 85*01*06\SpecialChar ~
28841 \SpecialChar ~
28842 \SpecialChar ~
28843 \SpecialChar ~
28844 \SpecialChar ~
28845 \SpecialChar ~
28846 \SpecialChar ~
28847 \SpecialChar ~
28848 \SpecialChar ~
28849 \SpecialChar ~
28850 \SpecialChar ~
28851 \SpecialChar ~
28852  92\SpecialChar ~
28853 \SpecialChar ~
28854 \SpecialChar ~
28855 \SpecialChar ~
28856 \SpecialChar ~
28857 \SpecialChar ~
28858 \SpecialChar ~
28859 \SpecialChar ~
28860  mov\SpecialChar ~
28861 \SpecialChar ~
28862  _foo_hob1_1_1,(_gint + 1)
28863 \newline
28864 \SpecialChar ~
28865 \SpecialChar ~
28866 \SpecialChar ~
28867 \SpecialChar ~
28868 \SpecialChar ~
28869 \SpecialChar ~
28870 \SpecialChar ~
28871 \SpecialChar ~
28872 \SpecialChar ~
28873 \SpecialChar ~
28874 \SpecialChar ~
28875 \SpecialChar ~
28876 \SpecialChar ~
28877 \SpecialChar ~
28878 \SpecialChar ~
28879 \SpecialChar ~
28880 \SpecialChar ~
28881 \SpecialChar ~
28882 \SpecialChar ~
28883 \SpecialChar ~
28884 \SpecialChar ~
28885 \SpecialChar ~
28886 \SpecialChar ~
28887 \SpecialChar ~
28888 \SpecialChar ~
28889  93 ;\SpecialChar ~
28890  hob.c 16
28891 \newline
28892 003A 85*05*07\SpecialChar ~
28893 \SpecialChar ~
28894 \SpecialChar ~
28895 \SpecialChar ~
28896 \SpecialChar ~
28897 \SpecialChar ~
28898 \SpecialChar ~
28899 \SpecialChar ~
28900 \SpecialChar ~
28901 \SpecialChar ~
28902 \SpecialChar ~
28903 \SpecialChar ~
28904  94\SpecialChar ~
28905 \SpecialChar ~
28906 \SpecialChar ~
28907 \SpecialChar ~
28908 \SpecialChar ~
28909 \SpecialChar ~
28910 \SpecialChar ~
28911 \SpecialChar ~
28912  mov\SpecialChar ~
28913 \SpecialChar ~
28914  _foo_hob2_1_1,(_glong + 3)
28915 \newline
28916 \SpecialChar ~
28917 \SpecialChar ~
28918 \SpecialChar ~
28919 \SpecialChar ~
28920 \SpecialChar ~
28921 \SpecialChar ~
28922 \SpecialChar ~
28923 \SpecialChar ~
28924 \SpecialChar ~
28925 \SpecialChar ~
28926 \SpecialChar ~
28927 \SpecialChar ~
28928 \SpecialChar ~
28929 \SpecialChar ~
28930 \SpecialChar ~
28931 \SpecialChar ~
28932 \SpecialChar ~
28933 \SpecialChar ~
28934 \SpecialChar ~
28935 \SpecialChar ~
28936 \SpecialChar ~
28937 \SpecialChar ~
28938 \SpecialChar ~
28939 \SpecialChar ~
28940 \SpecialChar ~
28941  95 ;\SpecialChar ~
28942  hob.c 17
28943 \newline
28944 003D 85*04*08\SpecialChar ~
28945 \SpecialChar ~
28946 \SpecialChar ~
28947 \SpecialChar ~
28948 \SpecialChar ~
28949 \SpecialChar ~
28950 \SpecialChar ~
28951 \SpecialChar ~
28952 \SpecialChar ~
28953 \SpecialChar ~
28954 \SpecialChar ~
28955 \SpecialChar ~
28956  96\SpecialChar ~
28957 \SpecialChar ~
28958 \SpecialChar ~
28959 \SpecialChar ~
28960 \SpecialChar ~
28961 \SpecialChar ~
28962 \SpecialChar ~
28963 \SpecialChar ~
28964  mov\SpecialChar ~
28965 \SpecialChar ~
28966  _foo_how1_1_1,(_glong + 2)
28967 \newline
28968 0040 85*05*09\SpecialChar ~
28969 \SpecialChar ~
28970 \SpecialChar ~
28971 \SpecialChar ~
28972 \SpecialChar ~
28973 \SpecialChar ~
28974 \SpecialChar ~
28975 \SpecialChar ~
28976 \SpecialChar ~
28977 \SpecialChar ~
28978 \SpecialChar ~
28979 \SpecialChar ~
28980  97\SpecialChar ~
28981 \SpecialChar ~
28982 \SpecialChar ~
28983 \SpecialChar ~
28984 \SpecialChar ~
28985 \SpecialChar ~
28986 \SpecialChar ~
28987 \SpecialChar ~
28988  mov\SpecialChar ~
28989 \SpecialChar ~
28990  (_foo_how1_1_1 + 1),(_glong + 3)
28991 \newline
28992 0043 85*03*0A\SpecialChar ~
28993 \SpecialChar ~
28994 \SpecialChar ~
28995 \SpecialChar ~
28996 \SpecialChar ~
28997 \SpecialChar ~
28998 \SpecialChar ~
28999 \SpecialChar ~
29000 \SpecialChar ~
29001 \SpecialChar ~
29002 \SpecialChar ~
29003 \SpecialChar ~
29004  98\SpecialChar ~
29005 \SpecialChar ~
29006 \SpecialChar ~
29007 \SpecialChar ~
29008 \SpecialChar ~
29009 \SpecialChar ~
29010 \SpecialChar ~
29011 \SpecialChar ~
29012  mov\SpecialChar ~
29013 \SpecialChar ~
29014  _foo_how2_1_1,(_glong + 1)
29015 \newline
29016 0046 85*04*0B\SpecialChar ~
29017 \SpecialChar ~
29018 \SpecialChar ~
29019 \SpecialChar ~
29020 \SpecialChar ~
29021 \SpecialChar ~
29022 \SpecialChar ~
29023 \SpecialChar ~
29024 \SpecialChar ~
29025 \SpecialChar ~
29026 \SpecialChar ~
29027 \SpecialChar ~
29028  99\SpecialChar ~
29029 \SpecialChar ~
29030 \SpecialChar ~
29031 \SpecialChar ~
29032 \SpecialChar ~
29033 \SpecialChar ~
29034 \SpecialChar ~
29035 \SpecialChar ~
29036  mov\SpecialChar ~
29037 \SpecialChar ~
29038  (_foo_how2_1_1 + 1),(_glong + 2)
29039 \layout Standard
29040
29041 Again, variations of these cases may
29042 \emph on
29043 not
29044 \emph default
29045  be recognized.
29046  They are standard C expressions, so I heartily recommend these be the only
29047  way to get the higher order byte/word, (it is portable).
29048  Of course it will be recognized even if it is embedded in other expressions,
29049  e.g.:
29050 \layout Verse
29051
29052
29053 \family typewriter
29054 xyz = gint + ((gint >> 8) & 0xFF);
29055 \layout Standard
29056
29057 will still be recognized.
29058 \layout Subsection
29059
29060 Peephole Optimizer
29061 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
29062
29063 \end_inset
29064
29065
29066 \begin_inset LatexCommand \index{Peephole optimizer}
29067
29068 \end_inset
29069
29070
29071 \layout Standard
29072
29073 The compiler uses a rule based, pattern matching and re-writing mechanism
29074  for peep-hole optimization.
29075  It is inspired by
29076 \emph on
29077 copt
29078 \emph default
29079  a peep-hole optimizer by Christopher W.
29080  Fraser (cwfraser\SpecialChar ~
29081 @\SpecialChar ~
29082 microsoft.com).
29083  A default set of rules are compiled into the compiler, additional rules
29084  may be added with the
29085 \emph on
29086 -
29087 \begin_inset ERT
29088 status Collapsed
29089
29090 \layout Standard
29091
29092 \backslash
29093 /
29094 \end_inset
29095
29096 -peep-file
29097 \begin_inset LatexCommand \index{-\/-peep-file}
29098
29099 \end_inset
29100
29101  <filename>
29102 \emph default
29103  option.
29104  The rule language is best illustrated with examples.
29105 \layout Verse
29106
29107
29108 \family typewriter
29109 replace {
29110 \newline
29111 \SpecialChar ~
29112 \SpecialChar ~
29113 mov %1,a
29114 \newline
29115 \SpecialChar ~
29116 \SpecialChar ~
29117 mov a,%1
29118 \newline
29119 } by {
29120 \newline
29121 \SpecialChar ~
29122 \SpecialChar ~
29123 mov %1,a
29124 \newline
29125 }
29126 \layout Standard
29127
29128 The above rule will change the following assembly
29129 \begin_inset LatexCommand \index{Assembler routines}
29130
29131 \end_inset
29132
29133  sequence:
29134 \layout Verse
29135
29136
29137 \family typewriter
29138 mov r1,a
29139 \newline
29140 mov a,r1
29141 \layout Standard
29142
29143 to
29144 \layout Verse
29145
29146
29147 \family typewriter
29148 mov r1,a
29149 \layout Standard
29150
29151 Note: All occurrences of a
29152 \emph on
29153 %n
29154 \emph default
29155  (pattern variable) must denote the same string.
29156  With the above rule, the assembly sequence:
29157 \layout Verse
29158
29159
29160 \family typewriter
29161 mov r1,a
29162 \newline
29163 mov a,r2
29164 \layout Standard
29165
29166 will remain unmodified.
29167 \newline
29168
29169 \newline
29170 Other special case optimizations may be added by the user (via
29171 \emph on
29172 -
29173 \begin_inset ERT
29174 status Collapsed
29175
29176 \layout Standard
29177
29178 \backslash
29179 /
29180 \end_inset
29181
29182 -peep-file option
29183 \emph default
29184 ).
29185  E.g.
29186  some variants of the 8051 MCU
29187 \begin_inset LatexCommand \index{MCS51 variants}
29188
29189 \end_inset
29190
29191  allow only
29192 \family typewriter
29193 ajmp
29194 \family default
29195  and
29196 \family typewriter
29197 acall
29198 \family default
29199 .
29200  The following two rules will change all
29201 \family typewriter
29202 ljmp
29203 \family default
29204  and
29205 \family typewriter
29206 lcall
29207 \family default
29208  to
29209 \family typewriter
29210 ajmp
29211 \family default
29212  and
29213 \family typewriter
29214 acall
29215 \layout Verse
29216
29217
29218 \family typewriter
29219 replace { lcall %1 } by { acall %1 }
29220 \newline
29221 replace { ljmp %1 } by { ajmp %1 }
29222 \layout Standard
29223
29224 The
29225 \emph on
29226 inline-assembler code
29227 \emph default
29228  is also passed through the peep hole optimizer, thus the peephole optimizer
29229  can also be used as an assembly level macro expander.
29230  The rules themselves are MCU dependent whereas the rule language infra-structur
29231 e is MCU independent.
29232  Peephole optimization rules for other MCU can be easily programmed using
29233  the rule language.
29234 \newline
29235
29236 \newline
29237 The syntax for a rule is as follows:
29238 \layout Verse
29239
29240
29241 \family typewriter
29242 rule := replace [ restart ] '{' <assembly sequence> '
29243 \backslash
29244 n'
29245 \newline
29246 \SpecialChar ~
29247  \SpecialChar ~
29248  \SpecialChar ~
29249  \SpecialChar ~
29250  \SpecialChar ~
29251  \SpecialChar ~
29252  \SpecialChar ~
29253  \SpecialChar ~
29254  \SpecialChar ~
29255  \SpecialChar ~
29256  \SpecialChar ~
29257  \SpecialChar ~
29258  \SpecialChar ~
29259  \SpecialChar ~
29260  '}' by '{' '
29261 \backslash
29262 n'
29263 \newline
29264 \SpecialChar ~
29265  \SpecialChar ~
29266  \SpecialChar ~
29267  \SpecialChar ~
29268  \SpecialChar ~
29269  \SpecialChar ~
29270  \SpecialChar ~
29271  \SpecialChar ~
29272  \SpecialChar ~
29273  \SpecialChar ~
29274  \SpecialChar ~
29275  \SpecialChar ~
29276  \SpecialChar ~
29277  \SpecialChar ~
29278  \SpecialChar ~
29279  \SpecialChar ~
29280  <assembly sequence> '
29281 \backslash
29282 n'
29283 \newline
29284 \SpecialChar ~
29285  \SpecialChar ~
29286  \SpecialChar ~
29287  \SpecialChar ~
29288  \SpecialChar ~
29289  \SpecialChar ~
29290  \SpecialChar ~
29291  \SpecialChar ~
29292  \SpecialChar ~
29293  \SpecialChar ~
29294  \SpecialChar ~
29295  \SpecialChar ~
29296  \SpecialChar ~
29297  \SpecialChar ~
29298  '}' [if <functionName> ] '
29299 \backslash
29300 n'
29301 \layout Standard
29302
29303 <assembly sequence> := assembly instruction (each instruction including
29304  labels must be on a separate line).
29305 \newline
29306
29307 \newline
29308 The optimizer will apply to the rules one by one from the top in the sequence
29309  of their appearance, it will terminate when all rules are exhausted.
29310  If the 'restart' option is specified, then the optimizer will start matching
29311  the rules again from the top, this option for a rule is expensive (performance)
29312 , it is intended to be used in situations where a transformation will trigger
29313  the same rule again.
29314  An example of this (not a good one, it has side effects) is the following
29315  rule:
29316 \layout Verse
29317
29318
29319 \family typewriter
29320 replace restart {
29321 \newline
29322 \SpecialChar ~
29323 \SpecialChar ~
29324 pop %1
29325 \newline
29326 \SpecialChar ~
29327 \SpecialChar ~
29328 push %1 } by {
29329 \newline
29330 \SpecialChar ~
29331 \SpecialChar ~
29332 ; nop
29333 \newline
29334 }
29335 \layout Standard
29336
29337 Note that the replace pattern cannot be a blank, but can be a comment line.
29338  Without the 'restart' option only the innermost 'pop' 'push' pair would
29339  be eliminated, i.e.:
29340 \layout Verse
29341
29342
29343 \family typewriter
29344 pop ar1
29345 \newline
29346 pop ar2
29347 \newline
29348 push ar2
29349 \newline
29350 push ar1
29351 \layout Standard
29352
29353 would result in:
29354 \layout Verse
29355
29356
29357 \family typewriter
29358 pop ar1
29359 \newline
29360 ; nop
29361 \newline
29362 push ar1
29363 \layout Standard
29364
29365
29366 \emph on
29367 with
29368 \emph default
29369  the restart option the rule will be applied again to the resulting code
29370  and then all the pop-push pairs will be eliminated to yield:
29371 \layout Verse
29372
29373
29374 \family typewriter
29375 ; nop
29376 \newline
29377 ; nop
29378 \layout Standard
29379
29380 A conditional function can be attached to a rule.
29381  Attaching rules are somewhat more involved, let me illustrate this with
29382  an example.
29383 \layout Verse
29384
29385
29386 \family typewriter
29387 replace {
29388 \newline
29389 \SpecialChar ~
29390  \SpecialChar ~
29391  \SpecialChar ~
29392 ljmp %5
29393 \newline
29394 %2:
29395 \newline
29396 } by {
29397 \newline
29398 \SpecialChar ~
29399  \SpecialChar ~
29400  \SpecialChar ~
29401 sjmp %5
29402 \newline
29403 %2:
29404 \newline
29405 } if labelInRange
29406 \layout Standard
29407
29408 The optimizer does a look-up of a function name table defined in function
29409
29410 \emph on
29411 callFuncByName
29412 \emph default
29413  in the source file SDCCpeeph.c, with the name
29414 \emph on
29415 labelInRange
29416 \emph default
29417 .
29418  If it finds a corresponding entry the function is called.
29419  Note there can be no parameters specified for these functions, in this
29420  case the use of
29421 \emph on
29422 %5
29423 \emph default
29424  is crucial, since the function
29425 \emph on
29426 labelInRange
29427 \emph default
29428  expects to find the label in that particular variable (the hash table containin
29429 g the variable bindings is passed as a parameter).
29430  If you want to code more such functions, take a close look at the function
29431  labelInRange and the calling mechanism in source file SDCCpeeph.c.
29432  Currently implemented are
29433 \emph on
29434 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
29435  24bitMode, portIsDS390, 24bitModeAndPortDS390
29436 \emph default
29437 and
29438 \emph on
29439  notVolatile
29440 \emph default
29441 .
29442 \layout Standard
29443
29444 I know this whole thing is a little kludgey, but maybe some day we will
29445  have some better means.
29446  If you are looking at this file, you will see the default rules that are
29447  compiled into the compiler, you can add your own rules in the default set
29448  there if you get tired of specifying the -
29449 \begin_inset ERT
29450 status Collapsed
29451
29452 \layout Standard
29453
29454 \backslash
29455 /
29456 \end_inset
29457
29458 -peep-file option.
29459 \layout Section
29460
29461 ANSI-Compliance
29462 \begin_inset LatexCommand \index{ANSI-compliance}
29463
29464 \end_inset
29465
29466
29467 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
29468
29469 \end_inset
29470
29471
29472 \layout Standard
29473
29474 The latest publically available version of the standard
29475 \emph on
29476 ISO/IEC 9899 - Programming languages - C
29477 \emph default
29478  should be available at:
29479 \begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899}
29480
29481 \end_inset
29482
29483 .
29484 \newline
29485
29486 \layout Standard
29487
29488 Deviations from the compliance:
29489 \layout Itemize
29490
29491 functions are not reentrant
29492 \begin_inset LatexCommand \index{reentrant}
29493
29494 \end_inset
29495
29496  unless explicitly declared as such or the
29497 \series bold
29498 -
29499 \begin_inset ERT
29500 status Collapsed
29501
29502 \layout Standard
29503
29504 \backslash
29505 /
29506 \end_inset
29507
29508 -stack-auto
29509 \begin_inset LatexCommand \index{-\/-stack-auto}
29510
29511 \end_inset
29512
29513
29514 \series default
29515  command line option is specified.
29516 \layout Itemize
29517
29518 structures
29519 \begin_inset LatexCommand \index{struct}
29520
29521 \end_inset
29522
29523  and unions
29524 \begin_inset LatexCommand \index{union}
29525
29526 \end_inset
29527
29528  cannot be assigned values directly, cannot be passed as function parameters
29529  or assigned to each other and cannot be a return value
29530 \begin_inset LatexCommand \index{return value}
29531
29532 \end_inset
29533
29534  from a function, e.g.:
29535 \begin_deeper
29536 \layout Verse
29537
29538
29539 \family typewriter
29540 struct s { ...
29541  };
29542 \newline
29543 struct s s1, s2;
29544 \newline
29545 foo()
29546 \newline
29547 {
29548 \newline
29549 \SpecialChar ~
29550 \SpecialChar ~
29551 \SpecialChar ~
29552 \SpecialChar ~
29553 ...
29554
29555 \newline
29556 \SpecialChar ~
29557 \SpecialChar ~
29558 \SpecialChar ~
29559 \SpecialChar ~
29560 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
29561 \newline
29562 \SpecialChar ~
29563 \SpecialChar ~
29564 \SpecialChar ~
29565 \SpecialChar ~
29566 ...
29567
29568 \newline
29569 }
29570 \newline
29571
29572 \series bold
29573 struct
29574 \series default
29575  s foo1 (
29576 \series bold
29577 struct
29578 \series default
29579  s parms) /* invalid in SDCC although allowed in ANSI */
29580 \newline
29581 {
29582 \newline
29583 \SpecialChar ~
29584 \SpecialChar ~
29585 \SpecialChar ~
29586 \SpecialChar ~
29587 struct s rets;
29588 \newline
29589 \SpecialChar ~
29590 \SpecialChar ~
29591 \SpecialChar ~
29592 \SpecialChar ~
29593 ...
29594
29595 \newline
29596 \SpecialChar ~
29597 \SpecialChar ~
29598 \SpecialChar ~
29599 \SpecialChar ~
29600 return rets; /* is invalid in SDCC although allowed in ANSI */
29601 \newline
29602 }
29603 \end_deeper
29604 \layout Itemize
29605
29606 initialization of structure arrays must be fully braced.
29607 \begin_deeper
29608 \layout Verse
29609
29610
29611 \family typewriter
29612 struct s { char x } a[] = {1, 2};\SpecialChar ~
29613 \SpecialChar ~
29614 \SpecialChar ~
29615 \SpecialChar ~
29616 \SpecialChar ~
29617 /* invalid in SDCC */
29618 \newline
29619 struct s { char x } a[] = {{1}, {2}}; /* OK */
29620 \end_deeper
29621 \layout Itemize
29622
29623 'long long
29624 \begin_inset LatexCommand \index{long long (not supported)}
29625
29626 \end_inset
29627
29628 ' (64 bit integers
29629 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
29630
29631 \end_inset
29632
29633 ) not supported.
29634 \layout Itemize
29635
29636 'double
29637 \begin_inset LatexCommand \index{double (not supported)}
29638
29639 \end_inset
29640
29641 ' precision floating point
29642 \begin_inset LatexCommand \index{Floating point support}
29643
29644 \end_inset
29645
29646 not supported.
29647 \layout Itemize
29648
29649 Old K&R style
29650 \begin_inset LatexCommand \index{K\&R style}
29651
29652 \end_inset
29653
29654  function declarations are NOT allowed.
29655 \begin_deeper
29656 \layout Verse
29657
29658
29659 \family typewriter
29660 foo(i,j) /* this old style of function declarations */
29661 \newline
29662 int i,j; /* are valid in ANSI but not valid in SDCC */
29663 \newline
29664 {
29665 \newline
29666 \SpecialChar ~
29667 \SpecialChar ~
29668 \SpecialChar ~
29669 \SpecialChar ~
29670 ...
29671
29672 \newline
29673 }
29674 \end_deeper
29675 \layout Itemize
29676
29677 Most enhancements in C99 are not supported, f.e.:
29678 \begin_deeper
29679 \layout Verse
29680
29681
29682 \family typewriter
29683 \series bold
29684 inline
29685 \begin_inset LatexCommand \index{inline (not supported)}
29686
29687 \end_inset
29688
29689
29690 \series default
29691  int increment (int a) { return a+1; } /* is invalid in SDCC although allowed
29692  in C99.
29693  An empty define
29694 \emph on
29695 #define inline
29696 \emph default
29697  can be used as a work around */
29698 \newline
29699
29700 \newline
29701 for (
29702 \series bold
29703 int
29704 \series default
29705  i=0; i<10; i++) /* is invalid in SDCC although allowed in C99 */
29706 \end_deeper
29707 \layout Itemize
29708
29709 Certain words that are valid identifiers in the standard may be reserved
29710  words in SDCC unless the
29711 \series bold
29712 -
29713 \begin_inset ERT
29714 status Collapsed
29715
29716 \layout Standard
29717
29718 \backslash
29719 /
29720 \end_inset
29721
29722 -std-c89
29723 \begin_inset LatexCommand \index{-\/-std-c89}
29724
29725 \end_inset
29726
29727  or -
29728 \begin_inset ERT
29729 status Collapsed
29730
29731 \layout Standard
29732
29733 \backslash
29734 /
29735 \end_inset
29736
29737 -std-c99
29738 \begin_inset LatexCommand \index{-\/-std-c99}
29739
29740 \end_inset
29741
29742
29743 \series default
29744  command line options are used.
29745  These may include (depending on the selected processor): 'at', 'banked',
29746  'bit', 'code', 'critical', 'data', 'eeprom', 'far', 'flash', 'idata', 'interrup
29747 t', 'near', 'nonbanked', 'pdata', 'reentrant', 'sbit', 'sfr', 'shadowregs',
29748  'sram', 'using', 'wparam', 'xdata', '_overlay', '_asm', '_endasm', and
29749  '_naked'.
29750  Compliant equivalents of these keywords are always available in a form
29751  that begin with two underscores
29752 \begin_inset LatexCommand \index{\_\_ (prefix for extended keywords)}
29753
29754 \end_inset
29755
29756 , f.e.
29757  '__data' instead of 'data'.
29758 \layout Section
29759
29760 Cyclomatic Complexity
29761 \begin_inset LatexCommand \index{Cyclomatic complexity}
29762
29763 \end_inset
29764
29765
29766 \layout Standard
29767
29768 Cyclomatic complexity of a function is defined as the number of independent
29769  paths the program can take during execution of the function.
29770  This is an important number since it defines the number test cases you
29771  have to generate to validate the function.
29772  The accepted industry standard for complexity number is 10, if the cyclomatic
29773  complexity reported by SDCC exceeds 10 you should think about simplification
29774  of the function logic.
29775  Note that the complexity level is not related to the number of lines of
29776  code in a function.
29777  Large functions can have low complexity, and small functions can have large
29778  complexity levels.
29779
29780 \newline
29781
29782 \newline
29783 SDCC uses the following formula to compute the complexity:
29784 \newline
29785
29786 \layout Standard
29787
29788 complexity = (number of edges in control flow graph) - (number of nodes
29789  in control flow graph) + 2;
29790 \newline
29791
29792 \newline
29793 Having said that the industry standard is 10, you should be aware that in
29794  some cases it be may unavoidable to have a complexity level of less than
29795  10.
29796  For example if you have switch statement with more than 10 case labels,
29797  each case label adds one to the complexity level.
29798  The complexity level is by no means an absolute measure of the algorithmic
29799  complexity of the function, it does however provide a good starting point
29800  for which functions you might look at for further optimization.
29801 \layout Section
29802
29803 Retargetting for other Processors
29804 \layout Standard
29805
29806 The issues for retargetting the compiler are far too numerous to be covered
29807  by this document.
29808  What follows is a brief description of each of the seven phases of the
29809  compiler and its MCU dependency.
29810 \layout Itemize
29811
29812 Parsing the source and building the annotated parse tree.
29813  This phase is largely MCU independent (except for the language extensions).
29814  Syntax & semantic checks are also done in this phase, along with some initial
29815  optimizations like back patching labels and the pattern matching optimizations
29816  like bit-rotation etc.
29817 \layout Itemize
29818
29819 The second phase involves generating an intermediate code which can be easy
29820  manipulated during the later phases.
29821  This phase is entirely MCU independent.
29822  The intermediate code generation assumes the target machine has unlimited
29823  number of registers, and designates them with the name iTemp.
29824  The compiler can be made to dump a human readable form of the code generated
29825  by using the -
29826 \begin_inset ERT
29827 status Collapsed
29828
29829 \layout Standard
29830
29831 \backslash
29832 /
29833 \end_inset
29834
29835 -dumpraw option.
29836 \layout Itemize
29837
29838 This phase does the bulk of the standard optimizations and is also MCU independe
29839 nt.
29840  This phase can be broken down into several sub-phases:
29841 \newline
29842
29843 \newline
29844 Break down intermediate code (iCode) into basic blocks.
29845 \newline
29846 Do control flow & data flow analysis on the basic blocks.
29847 \newline
29848 Do local common subexpression elimination, then global subexpression elimination
29849 \newline
29850 Dead code elimination
29851 \newline
29852 Loop optimizations
29853 \newline
29854 If loop optimizations caused any changes then do 'global subexpression eliminati
29855 on' and 'dead code elimination' again.
29856 \layout Itemize
29857
29858 This phase determines the live-ranges; by live range I mean those iTemp
29859  variables defined by the compiler that still survive after all the optimization
29860 s.
29861  Live range analysis
29862 \begin_inset LatexCommand \index{Live range analysis}
29863
29864 \end_inset
29865
29866  is essential for register allocation, since these computation determines
29867  which of these iTemps will be assigned to registers, and for how long.
29868 \layout Itemize
29869
29870 Phase five is register allocation.
29871  There are two parts to this process.
29872 \newline
29873
29874 \newline
29875 The first part I call 'register packing' (for lack of a better term).
29876  In this case several MCU specific expression folding is done to reduce
29877  register pressure.
29878 \newline
29879
29880 \newline
29881 The second part is more MCU independent and deals with allocating registers
29882  to the remaining live ranges.
29883  A lot of MCU specific code does creep into this phase because of the limited
29884  number of index registers available in the 8051.
29885 \layout Itemize
29886
29887 The Code generation phase is (unhappily), entirely MCU dependent and very
29888  little (if any at all) of this code can be reused for other MCU.
29889  However the scheme for allocating a homogenized assembler operand for each
29890  iCode operand may be reused.
29891 \layout Itemize
29892
29893 As mentioned in the optimization section the peep-hole optimizer is rule
29894  based system, which can reprogrammed for other MCUs.
29895 \layout Standard
29896
29897 More information is available in a wiki
29898 \begin_inset LatexCommand \index{wiki}
29899
29900 \end_inset
29901
29902  (preliminary link
29903 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/release_wiki/index.php?page=SDCC+internals+and+porting}
29904
29905 \end_inset
29906
29907 ) and in the thread
29908 \begin_inset LatexCommand \url{http://sf.net/mailarchive/message.php?msg_id=13954144}
29909
29910 \end_inset
29911
29912  .
29913 \layout Chapter
29914
29915 Compiler internals
29916 \begin_inset LatexCommand \index{Compiler internals}
29917
29918 \end_inset
29919
29920
29921 \layout Section
29922
29923 The anatomy of the compiler
29924 \begin_inset LatexCommand \label{sub:The-anatomy-of}
29925
29926 \end_inset
29927
29928
29929 \layout Standard
29930
29931
29932 \shape italic
29933 This is an excerpt from an article published in Circuit Cellar Magazine
29934  in
29935 \series bold
29936 August 2000
29937 \series default
29938 .
29939  It's a little outdated (the compiler is much more efficient now and user/develo
29940 per friendly), but pretty well exposes the guts of it all.
29941 \shape default
29942
29943 \newline
29944
29945 \newline
29946 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
29947  It is fairly easy to retarget for other 8-bit MCU.
29948  Here we take a look at some of the internals of the compiler.
29949
29950 \layout Paragraph*
29951
29952 Parsing
29953 \begin_inset LatexCommand \index{Parsing}
29954
29955 \end_inset
29956
29957
29958 \layout Standard
29959
29960 Parsing the input source file and creating an AST (Annotated Syntax Tree
29961 \begin_inset LatexCommand \index{Annotated syntax tree}
29962
29963 \end_inset
29964
29965 ).
29966  This phase also involves propagating types (annotating each node of the
29967  parse tree with type information) and semantic analysis.
29968  There are some MCU specific parsing rules.
29969  For example the storage classes, the extended storage classes are MCU specific
29970  while there may be a xdata storage class for 8051 there is no such storage
29971  class for z80 or Atmel AVR.
29972  SDCC allows MCU specific storage class extensions, i.e.
29973  xdata will be treated as a storage class specifier when parsing 8051 C
29974  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
29975  C code.
29976 \layout Paragraph*
29977
29978 Generating iCode
29979 \begin_inset LatexCommand \index{iCode}
29980
29981 \end_inset
29982
29983
29984 \layout Standard
29985
29986 Intermediate code generation.
29987  In this phase the AST is broken down into three-operand form (iCode).
29988  These three operand forms are represented as doubly linked lists.
29989  ICode is the term given to the intermediate form generated by the compiler.
29990  ICode example section shows some examples of iCode generated for some simple
29991  C source functions.
29992 \layout Paragraph*
29993
29994 Optimizations
29995 \begin_inset LatexCommand \index{Optimizations}
29996
29997 \end_inset
29998
29999 .
30000 \layout Standard
30001
30002 Bulk of the target independent optimizations is performed in this phase.
30003  The optimizations include constant propagation, common sub-expression eliminati
30004 on, loop invariant code movement, strength reduction of loop induction variables
30005  and dead-code elimination.
30006 \layout Paragraph*
30007
30008 Live range analysis
30009 \begin_inset LatexCommand \index{Live range analysis}
30010
30011 \end_inset
30012
30013
30014 \layout Standard
30015
30016 During intermediate code generation phase, the compiler assumes the target
30017  machine has infinite number of registers and generates a lot of temporary
30018  variables.
30019  The live range computation determines the lifetime of each of these compiler-ge
30020 nerated temporaries.
30021  A picture speaks a thousand words.
30022  ICode example sections show the live range annotations for each of the
30023  operand.
30024  It is important to note here, each iCode is assigned a number in the order
30025  of its execution in the function.
30026  The live ranges are computed in terms of these numbers.
30027  The from number is the number of the iCode which first defines the operand
30028  and the to number signifies the iCode which uses this operand last.
30029 \layout Paragraph*
30030
30031 Register Allocation
30032 \begin_inset LatexCommand \index{Register allocation}
30033
30034 \end_inset
30035
30036
30037 \layout Standard
30038
30039 The register allocation determines the type and number of registers needed
30040  by each operand.
30041  In most MCUs only a few registers can be used for indirect addressing.
30042  In case of 8051 for example the registers R0 & R1 can be used to indirectly
30043  address the internal ram and DPTR to indirectly address the external ram.
30044  The compiler will try to allocate the appropriate register to pointer variables
30045  if it can.
30046  ICode example section shows the operands annotated with the registers assigned
30047  to them.
30048  The compiler will try to keep operands in registers as much as possible;
30049  there are several schemes the compiler uses to do achieve this.
30050  When the compiler runs out of registers the compiler will check to see
30051  if there are any live operands which is not used or defined in the current
30052  basic block being processed, if there are any found then it will push that
30053  operand and use the registers in this block, the operand will then be popped
30054  at the end of the basic block.
30055
30056 \layout Standard
30057
30058 There are other MCU specific considerations in this phase.
30059  Some MCUs have an accumulator; very short-lived operands could be assigned
30060  to the accumulator instead of a general-purpose register.
30061 \layout Paragraph*
30062
30063 Code generation
30064 \layout Standard
30065
30066 Figure II gives a table of iCode
30067 \begin_inset LatexCommand \index{iCode}
30068
30069 \end_inset
30070
30071  operations supported by the compiler.
30072  The code generation involves translating these operations into corresponding
30073  assembly code for the processor.
30074  This sounds overly simple but that is the essence of code generation.
30075  Some of the iCode operations are generated on a MCU specific manner for
30076  example, the z80 port does not use registers to pass parameters so the
30077  SEND and RECV iCode operations will not be generated, and it also does
30078  not support JUMPTABLES.
30079
30080 \newline
30081
30082 \layout Standard
30083
30084
30085 \size footnotesize
30086 Figure II
30087 \begin_inset  Tabular
30088 <lyxtabular version="3" rows="39" columns="4">
30089 <features islongtable="true" headBottomDL="true">
30090 <column alignment="block" valignment="top" leftline="true" width="13col%">
30091 <column alignment="left" valignment="top" leftline="true" width="13col%">
30092 <column alignment="block" valignment="top" leftline="true" width="22col%">
30093 <column alignment="block" valignment="top" leftline="true" rightline="true" width="40col%">
30094 <row topline="true" bottomline="true" endhead="true">
30095 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30096 \begin_inset Text
30097
30098 \layout Standard
30099
30100
30101 \series bold
30102 iCode
30103 \series default
30104
30105 \begin_inset LatexCommand \index{iCode}
30106
30107 \end_inset
30108
30109
30110 \end_inset
30111 </cell>
30112 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30113 \begin_inset Text
30114
30115 \layout Standard
30116
30117
30118 \series bold
30119 Operands
30120 \end_inset
30121 </cell>
30122 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30123 \begin_inset Text
30124
30125 \layout Standard
30126
30127
30128 \series bold
30129 Description
30130 \end_inset
30131 </cell>
30132 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30133 \begin_inset Text
30134
30135 \layout Standard
30136
30137
30138 \series bold
30139 C Equivalent
30140 \end_inset
30141 </cell>
30142 </row>
30143 <row topline="true">
30144 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30145 \begin_inset Text
30146
30147 \layout Standard
30148
30149
30150 \size footnotesize
30151 '!'
30152 \end_inset
30153 </cell>
30154 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30155 \begin_inset Text
30156
30157 \layout Standard
30158
30159
30160 \size footnotesize
30161 IC_LEFT() IC_RESULT()
30162 \end_inset
30163 </cell>
30164 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30165 \begin_inset Text
30166
30167 \layout Standard
30168
30169
30170 \size footnotesize
30171 NOT operation
30172 \end_inset
30173 </cell>
30174 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30175 \begin_inset Text
30176
30177 \layout Standard
30178
30179
30180 \size footnotesize
30181 IC_RESULT = ! IC_LEFT;
30182 \end_inset
30183 </cell>
30184 </row>
30185 <row topline="true">
30186 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30187 \begin_inset Text
30188
30189 \layout Standard
30190
30191
30192 \size footnotesize
30193 '~'
30194 \end_inset
30195 </cell>
30196 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30197 \begin_inset Text
30198
30199 \layout Standard
30200
30201
30202 \size footnotesize
30203 IC_LEFT() IC_RESULT()
30204 \end_inset
30205 </cell>
30206 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30207 \begin_inset Text
30208
30209 \layout Standard
30210
30211
30212 \size footnotesize
30213 Bitwise complement of
30214 \end_inset
30215 </cell>
30216 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30217 \begin_inset Text
30218
30219 \layout Standard
30220
30221
30222 \size footnotesize
30223 IC_RESULT = ~IC_LEFT;
30224 \end_inset
30225 </cell>
30226 </row>
30227 <row topline="true">
30228 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30229 \begin_inset Text
30230
30231 \layout Standard
30232
30233
30234 \size footnotesize
30235 RRC
30236 \end_inset
30237 </cell>
30238 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30239 \begin_inset Text
30240
30241 \layout Standard
30242
30243
30244 \size footnotesize
30245 IC_LEFT() IC_RESULT()
30246 \end_inset
30247 </cell>
30248 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30249 \begin_inset Text
30250
30251 \layout Standard
30252
30253
30254 \size footnotesize
30255 Rotate right with carry
30256 \end_inset
30257 </cell>
30258 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30259 \begin_inset Text
30260
30261 \layout Standard
30262
30263
30264 \size footnotesize
30265 IC_RESULT = (IC_LEFT << 1) | (IC_LEFT >> (sizeof(IC_LEFT)*8-1));
30266 \end_inset
30267 </cell>
30268 </row>
30269 <row topline="true">
30270 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30271 \begin_inset Text
30272
30273 \layout Standard
30274
30275
30276 \size footnotesize
30277 RLC
30278 \end_inset
30279 </cell>
30280 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30281 \begin_inset Text
30282
30283 \layout Standard
30284
30285
30286 \size footnotesize
30287 IC_LEFT() IC_RESULT()
30288 \end_inset
30289 </cell>
30290 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30291 \begin_inset Text
30292
30293 \layout Standard
30294
30295
30296 \size footnotesize
30297 Rotate left with carry
30298 \end_inset
30299 </cell>
30300 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30301 \begin_inset Text
30302
30303 \layout Standard
30304
30305
30306 \size footnotesize
30307 IC_RESULT = (IC_LEFT << (sizeof(LC_LEFT)*8-1) ) | (IC_LEFT >> 1);
30308 \end_inset
30309 </cell>
30310 </row>
30311 <row topline="true">
30312 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30313 \begin_inset Text
30314
30315 \layout Standard
30316
30317
30318 \size footnotesize
30319 GETHBIT
30320 \end_inset
30321 </cell>
30322 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30323 \begin_inset Text
30324
30325 \layout Standard
30326
30327
30328 \size footnotesize
30329 IC_LEFT() IC_RESULT()
30330 \end_inset
30331 </cell>
30332 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30333 \begin_inset Text
30334
30335 \layout Standard
30336
30337
30338 \size footnotesize
30339 Get the highest order bit of IC_LEFT
30340 \end_inset
30341 </cell>
30342 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30343 \begin_inset Text
30344
30345 \layout Standard
30346
30347
30348 \size footnotesize
30349 IC_RESULT = (IC_LEFT >> (sizeof(IC_LEFT)*8 -1));
30350 \end_inset
30351 </cell>
30352 </row>
30353 <row topline="true">
30354 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30355 \begin_inset Text
30356
30357 \layout Standard
30358
30359
30360 \size footnotesize
30361 UNARYMINUS
30362 \end_inset
30363 </cell>
30364 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30365 \begin_inset Text
30366
30367 \layout Standard
30368
30369
30370 \size footnotesize
30371 IC_LEFT() IC_RESULT()
30372 \end_inset
30373 </cell>
30374 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30375 \begin_inset Text
30376
30377 \layout Standard
30378
30379
30380 \size footnotesize
30381 Unary minus
30382 \end_inset
30383 </cell>
30384 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30385 \begin_inset Text
30386
30387 \layout Standard
30388
30389
30390 \size footnotesize
30391 IC_RESULT = - IC_LEFT;
30392 \end_inset
30393 </cell>
30394 </row>
30395 <row topline="true">
30396 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30397 \begin_inset Text
30398
30399 \layout Standard
30400
30401
30402 \size footnotesize
30403 IPUSH
30404 \end_inset
30405 </cell>
30406 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30407 \begin_inset Text
30408
30409 \layout Standard
30410
30411
30412 \size footnotesize
30413 IC_LEFT()
30414 \end_inset
30415 </cell>
30416 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30417 \begin_inset Text
30418
30419 \layout Standard
30420
30421
30422 \size footnotesize
30423 Push the operand into stack
30424 \end_inset
30425 </cell>
30426 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30427 \begin_inset Text
30428
30429 \layout Standard
30430
30431
30432 \size footnotesize
30433 NONE
30434 \end_inset
30435 </cell>
30436 </row>
30437 <row topline="true">
30438 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30439 \begin_inset Text
30440
30441 \layout Standard
30442
30443
30444 \size footnotesize
30445 IPOP
30446 \end_inset
30447 </cell>
30448 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30449 \begin_inset Text
30450
30451 \layout Standard
30452
30453
30454 \size footnotesize
30455 IC_LEFT()
30456 \end_inset
30457 </cell>
30458 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30459 \begin_inset Text
30460
30461 \layout Standard
30462
30463
30464 \size footnotesize
30465 Pop the operand from the stack
30466 \end_inset
30467 </cell>
30468 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30469 \begin_inset Text
30470
30471 \layout Standard
30472
30473
30474 \size footnotesize
30475 NONE
30476 \end_inset
30477 </cell>
30478 </row>
30479 <row topline="true">
30480 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30481 \begin_inset Text
30482
30483 \layout Standard
30484
30485
30486 \size footnotesize
30487 CALL
30488 \end_inset
30489 </cell>
30490 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30491 \begin_inset Text
30492
30493 \layout Standard
30494
30495
30496 \size footnotesize
30497 IC_LEFT() IC_RESULT()
30498 \end_inset
30499 </cell>
30500 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30501 \begin_inset Text
30502
30503 \layout Standard
30504
30505
30506 \size footnotesize
30507 Call the function represented by IC_LEFT
30508 \end_inset
30509 </cell>
30510 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30511 \begin_inset Text
30512
30513 \layout Standard
30514
30515
30516 \size footnotesize
30517 IC_RESULT = IC_LEFT();
30518 \end_inset
30519 </cell>
30520 </row>
30521 <row topline="true">
30522 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30523 \begin_inset Text
30524
30525 \layout Standard
30526
30527
30528 \size footnotesize
30529 PCALL
30530 \end_inset
30531 </cell>
30532 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30533 \begin_inset Text
30534
30535 \layout Standard
30536
30537
30538 \size footnotesize
30539 IC_LEFT() IC_RESULT()
30540 \end_inset
30541 </cell>
30542 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30543 \begin_inset Text
30544
30545 \layout Standard
30546
30547
30548 \size footnotesize
30549 Call via function pointer
30550 \end_inset
30551 </cell>
30552 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30553 \begin_inset Text
30554
30555 \layout Standard
30556
30557
30558 \size footnotesize
30559 IC_RESULT = (*IC_LEFT)();
30560 \end_inset
30561 </cell>
30562 </row>
30563 <row topline="true">
30564 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30565 \begin_inset Text
30566
30567 \layout Standard
30568
30569
30570 \size footnotesize
30571 RETURN
30572 \end_inset
30573 </cell>
30574 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30575 \begin_inset Text
30576
30577 \layout Standard
30578
30579
30580 \size footnotesize
30581 IC_LEFT()
30582 \end_inset
30583 </cell>
30584 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30585 \begin_inset Text
30586
30587 \layout Standard
30588
30589
30590 \size footnotesize
30591 Return the value in operand IC_LEFT
30592 \end_inset
30593 </cell>
30594 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30595 \begin_inset Text
30596
30597 \layout Standard
30598
30599
30600 \size footnotesize
30601 return IC_LEFT;
30602 \end_inset
30603 </cell>
30604 </row>
30605 <row topline="true">
30606 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30607 \begin_inset Text
30608
30609 \layout Standard
30610
30611
30612 \size footnotesize
30613 LABEL
30614 \end_inset
30615 </cell>
30616 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30617 \begin_inset Text
30618
30619 \layout Standard
30620
30621
30622 \size footnotesize
30623 IC_LABEL()
30624 \end_inset
30625 </cell>
30626 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30627 \begin_inset Text
30628
30629 \layout Standard
30630
30631
30632 \size footnotesize
30633 Label
30634 \end_inset
30635 </cell>
30636 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30637 \begin_inset Text
30638
30639 \layout Standard
30640
30641
30642 \size footnotesize
30643 IC_LABEL:
30644 \end_inset
30645 </cell>
30646 </row>
30647 <row topline="true">
30648 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30649 \begin_inset Text
30650
30651 \layout Standard
30652
30653
30654 \size footnotesize
30655 GOTO
30656 \end_inset
30657 </cell>
30658 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30659 \begin_inset Text
30660
30661 \layout Standard
30662
30663
30664 \size footnotesize
30665 IC_LABEL()
30666 \end_inset
30667 </cell>
30668 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30669 \begin_inset Text
30670
30671 \layout Standard
30672
30673
30674 \size footnotesize
30675 Goto label
30676 \end_inset
30677 </cell>
30678 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30679 \begin_inset Text
30680
30681 \layout Standard
30682
30683
30684 \size footnotesize
30685 goto IC_LABEL();
30686 \end_inset
30687 </cell>
30688 </row>
30689 <row topline="true">
30690 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30691 \begin_inset Text
30692
30693 \layout Standard
30694
30695
30696 \size footnotesize
30697 '+'
30698 \end_inset
30699 </cell>
30700 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30701 \begin_inset Text
30702
30703 \layout Standard
30704
30705
30706 \size footnotesize
30707 IC_LEFT() IC_RIGHT() IC_RESULT()
30708 \end_inset
30709 </cell>
30710 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30711 \begin_inset Text
30712
30713 \layout Standard
30714
30715
30716 \size footnotesize
30717 Addition
30718 \end_inset
30719 </cell>
30720 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30721 \begin_inset Text
30722
30723 \layout Standard
30724
30725
30726 \size footnotesize
30727 IC_RESULT = IC_LEFT + IC_RIGHT
30728 \end_inset
30729 </cell>
30730 </row>
30731 <row topline="true">
30732 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30733 \begin_inset Text
30734
30735 \layout Standard
30736
30737
30738 \size footnotesize
30739 '-'
30740 \end_inset
30741 </cell>
30742 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30743 \begin_inset Text
30744
30745 \layout Standard
30746
30747
30748 \size footnotesize
30749 IC_LEFT() IC_RIGHT() IC_RESULT()
30750 \end_inset
30751 </cell>
30752 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30753 \begin_inset Text
30754
30755 \layout Standard
30756
30757
30758 \size footnotesize
30759 Subtraction
30760 \end_inset
30761 </cell>
30762 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30763 \begin_inset Text
30764
30765 \layout Standard
30766
30767
30768 \size footnotesize
30769 IC_RESULT = IC_LEFT - IC_RIGHT
30770 \end_inset
30771 </cell>
30772 </row>
30773 <row topline="true">
30774 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30775 \begin_inset Text
30776
30777 \layout Standard
30778
30779
30780 \size footnotesize
30781 '*'
30782 \end_inset
30783 </cell>
30784 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30785 \begin_inset Text
30786
30787 \layout Standard
30788
30789
30790 \size footnotesize
30791 IC_LEFT() IC_RIGHT() IC_RESULT()
30792 \end_inset
30793 </cell>
30794 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30795 \begin_inset Text
30796
30797 \layout Standard
30798
30799
30800 \size footnotesize
30801 Multiplication
30802 \end_inset
30803 </cell>
30804 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30805 \begin_inset Text
30806
30807 \layout Standard
30808
30809
30810 \size footnotesize
30811 IC_RESULT = IC_LEFT * IC_RIGHT;
30812 \end_inset
30813 </cell>
30814 </row>
30815 <row topline="true">
30816 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30817 \begin_inset Text
30818
30819 \layout Standard
30820
30821
30822 \size footnotesize
30823 '/'
30824 \end_inset
30825 </cell>
30826 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30827 \begin_inset Text
30828
30829 \layout Standard
30830
30831
30832 \size footnotesize
30833 IC_LEFT() IC_RIGHT() IC_RESULT()
30834 \end_inset
30835 </cell>
30836 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30837 \begin_inset Text
30838
30839 \layout Standard
30840
30841
30842 \size footnotesize
30843 Division
30844 \end_inset
30845 </cell>
30846 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30847 \begin_inset Text
30848
30849 \layout Standard
30850
30851
30852 \size footnotesize
30853 IC_RESULT = IC_LEFT / IC_RIGHT;
30854 \end_inset
30855 </cell>
30856 </row>
30857 <row topline="true">
30858 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30859 \begin_inset Text
30860
30861 \layout Standard
30862
30863
30864 \size footnotesize
30865 '%'
30866 \end_inset
30867 </cell>
30868 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30869 \begin_inset Text
30870
30871 \layout Standard
30872
30873
30874 \size footnotesize
30875 IC_LEFT() IC_RIGHT() IC_RESULT()
30876 \end_inset
30877 </cell>
30878 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30879 \begin_inset Text
30880
30881 \layout Standard
30882
30883
30884 \size footnotesize
30885 Modulus
30886 \end_inset
30887 </cell>
30888 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30889 \begin_inset Text
30890
30891 \layout Standard
30892
30893
30894 \size footnotesize
30895 IC_RESULT = IC_LEFT % IC_RIGHT;
30896 \end_inset
30897 </cell>
30898 </row>
30899 <row topline="true">
30900 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30901 \begin_inset Text
30902
30903 \layout Standard
30904
30905
30906 \size footnotesize
30907 '<'
30908 \end_inset
30909 </cell>
30910 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30911 \begin_inset Text
30912
30913 \layout Standard
30914
30915
30916 \size footnotesize
30917 IC_LEFT() IC_RIGHT() IC_RESULT()
30918 \end_inset
30919 </cell>
30920 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30921 \begin_inset Text
30922
30923 \layout Standard
30924
30925
30926 \size footnotesize
30927 Less than
30928 \end_inset
30929 </cell>
30930 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30931 \begin_inset Text
30932
30933 \layout Standard
30934
30935
30936 \size footnotesize
30937 IC_RESULT = IC_LEFT < IC_RIGHT;
30938 \end_inset
30939 </cell>
30940 </row>
30941 <row topline="true">
30942 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30943 \begin_inset Text
30944
30945 \layout Standard
30946
30947
30948 \size footnotesize
30949 '>'
30950 \end_inset
30951 </cell>
30952 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30953 \begin_inset Text
30954
30955 \layout Standard
30956
30957
30958 \size footnotesize
30959 IC_LEFT() IC_RIGHT() IC_RESULT()
30960 \end_inset
30961 </cell>
30962 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30963 \begin_inset Text
30964
30965 \layout Standard
30966
30967
30968 \size footnotesize
30969 Greater than
30970 \end_inset
30971 </cell>
30972 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30973 \begin_inset Text
30974
30975 \layout Standard
30976
30977
30978 \size footnotesize
30979 IC_RESULT = IC_LEFT > IC_RIGHT;
30980 \end_inset
30981 </cell>
30982 </row>
30983 <row topline="true">
30984 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30985 \begin_inset Text
30986
30987 \layout Standard
30988
30989
30990 \size footnotesize
30991 EQ_OP
30992 \end_inset
30993 </cell>
30994 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30995 \begin_inset Text
30996
30997 \layout Standard
30998
30999
31000 \size footnotesize
31001 IC_LEFT() IC_RIGHT() IC_RESULT()
31002 \end_inset
31003 </cell>
31004 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31005 \begin_inset Text
31006
31007 \layout Standard
31008
31009
31010 \size footnotesize
31011 Equal to
31012 \end_inset
31013 </cell>
31014 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31015 \begin_inset Text
31016
31017 \layout Standard
31018
31019
31020 \size footnotesize
31021 IC_RESULT = IC_LEFT == IC_RIGHT;
31022 \end_inset
31023 </cell>
31024 </row>
31025 <row topline="true">
31026 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31027 \begin_inset Text
31028
31029 \layout Standard
31030
31031
31032 \size footnotesize
31033 AND_OP
31034 \end_inset
31035 </cell>
31036 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31037 \begin_inset Text
31038
31039 \layout Standard
31040
31041
31042 \size footnotesize
31043 IC_LEFT() IC_RIGHT() IC_RESULT()
31044 \end_inset
31045 </cell>
31046 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31047 \begin_inset Text
31048
31049 \layout Standard
31050
31051
31052 \size footnotesize
31053 Logical and operation
31054 \end_inset
31055 </cell>
31056 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31057 \begin_inset Text
31058
31059 \layout Standard
31060
31061
31062 \size footnotesize
31063 IC_RESULT = IC_LEFT && IC_RIGHT;
31064 \end_inset
31065 </cell>
31066 </row>
31067 <row topline="true">
31068 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31069 \begin_inset Text
31070
31071 \layout Standard
31072
31073
31074 \size footnotesize
31075 OR_OP
31076 \end_inset
31077 </cell>
31078 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31079 \begin_inset Text
31080
31081 \layout Standard
31082
31083
31084 \size footnotesize
31085 IC_LEFT() IC_RIGHT() IC_RESULT()
31086 \end_inset
31087 </cell>
31088 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31089 \begin_inset Text
31090
31091 \layout Standard
31092
31093
31094 \size footnotesize
31095 Logical or operation
31096 \end_inset
31097 </cell>
31098 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31099 \begin_inset Text
31100
31101 \layout Standard
31102
31103
31104 \size footnotesize
31105 IC_RESULT = IC_LEFT || IC_RIGHT;
31106 \end_inset
31107 </cell>
31108 </row>
31109 <row topline="true">
31110 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31111 \begin_inset Text
31112
31113 \layout Standard
31114
31115
31116 \size footnotesize
31117 '^'
31118 \end_inset
31119 </cell>
31120 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31121 \begin_inset Text
31122
31123 \layout Standard
31124
31125
31126 \size footnotesize
31127 IC_LEFT() IC_RIGHT() IC_RESULT()
31128 \end_inset
31129 </cell>
31130 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31131 \begin_inset Text
31132
31133 \layout Standard
31134
31135
31136 \size footnotesize
31137 Exclusive OR
31138 \end_inset
31139 </cell>
31140 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31141 \begin_inset Text
31142
31143 \layout Standard
31144
31145
31146 \size footnotesize
31147 IC_RESULT = IC_LEFT ^ IC_RIGHT;
31148 \end_inset
31149 </cell>
31150 </row>
31151 <row topline="true">
31152 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31153 \begin_inset Text
31154
31155 \layout Standard
31156
31157
31158 \size footnotesize
31159 '|'
31160 \end_inset
31161 </cell>
31162 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31163 \begin_inset Text
31164
31165 \layout Standard
31166
31167
31168 \size footnotesize
31169 IC_LEFT() IC_RIGHT() IC_RESULT()
31170 \end_inset
31171 </cell>
31172 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31173 \begin_inset Text
31174
31175 \layout Standard
31176
31177
31178 \size footnotesize
31179 Bitwise OR
31180 \end_inset
31181 </cell>
31182 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31183 \begin_inset Text
31184
31185 \layout Standard
31186
31187
31188 \size footnotesize
31189 IC_RESULT = IC_LEFT | IC_RIGHT;
31190 \end_inset
31191 </cell>
31192 </row>
31193 <row topline="true">
31194 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31195 \begin_inset Text
31196
31197 \layout Standard
31198
31199
31200 \size footnotesize
31201 BITWISEAND
31202 \end_inset
31203 </cell>
31204 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31205 \begin_inset Text
31206
31207 \layout Standard
31208
31209
31210 \size footnotesize
31211 IC_LEFT() IC_RIGHT() IC_RESULT()
31212 \end_inset
31213 </cell>
31214 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31215 \begin_inset Text
31216
31217 \layout Standard
31218
31219
31220 \size footnotesize
31221 Bitwise AND
31222 \end_inset
31223 </cell>
31224 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31225 \begin_inset Text
31226
31227 \layout Standard
31228
31229
31230 \size footnotesize
31231 IC_RESULT = IC_LEFT & IC_RIGHT;
31232 \end_inset
31233 </cell>
31234 </row>
31235 <row topline="true">
31236 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31237 \begin_inset Text
31238
31239 \layout Standard
31240
31241
31242 \size footnotesize
31243 LEFT_OP
31244 \end_inset
31245 </cell>
31246 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31247 \begin_inset Text
31248
31249 \layout Standard
31250
31251
31252 \size footnotesize
31253 IC_LEFT() IC_RIGHT() IC_RESULT()
31254 \end_inset
31255 </cell>
31256 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31257 \begin_inset Text
31258
31259 \layout Standard
31260
31261
31262 \size footnotesize
31263 Left shift
31264 \end_inset
31265 </cell>
31266 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31267 \begin_inset Text
31268
31269 \layout Standard
31270
31271
31272 \size footnotesize
31273 IC_RESULT = IC_LEFT << IC_RIGHT
31274 \end_inset
31275 </cell>
31276 </row>
31277 <row topline="true">
31278 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31279 \begin_inset Text
31280
31281 \layout Standard
31282
31283
31284 \size footnotesize
31285 RIGHT_OP
31286 \end_inset
31287 </cell>
31288 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31289 \begin_inset Text
31290
31291 \layout Standard
31292
31293
31294 \size footnotesize
31295 IC_LEFT() IC_RIGHT() IC_RESULT()
31296 \end_inset
31297 </cell>
31298 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31299 \begin_inset Text
31300
31301 \layout Standard
31302
31303
31304 \size footnotesize
31305 Right shift
31306 \end_inset
31307 </cell>
31308 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31309 \begin_inset Text
31310
31311 \layout Standard
31312
31313
31314 \size footnotesize
31315 IC_RESULT = IC_LEFT >> IC_RIGHT
31316 \end_inset
31317 </cell>
31318 </row>
31319 <row topline="true">
31320 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31321 \begin_inset Text
31322
31323 \layout Standard
31324
31325
31326 \size footnotesize
31327 GET_VALUE_
31328 \newline
31329 AT_ ADDRESS
31330 \end_inset
31331 </cell>
31332 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31333 \begin_inset Text
31334
31335 \layout Standard
31336
31337
31338 \size footnotesize
31339 IC_LEFT() IC_RESULT()
31340 \end_inset
31341 </cell>
31342 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31343 \begin_inset Text
31344
31345 \layout Standard
31346
31347
31348 \size footnotesize
31349 Indirect fetch
31350 \end_inset
31351 </cell>
31352 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31353 \begin_inset Text
31354
31355 \layout Standard
31356
31357
31358 \size footnotesize
31359 IC_RESULT = (*IC_LEFT);
31360 \end_inset
31361 </cell>
31362 </row>
31363 <row topline="true">
31364 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31365 \begin_inset Text
31366
31367 \layout Standard
31368
31369
31370 \size footnotesize
31371 POINTER_SET
31372 \end_inset
31373 </cell>
31374 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31375 \begin_inset Text
31376
31377 \layout Standard
31378
31379
31380 \size footnotesize
31381 IC_RIGHT() IC_RESULT()
31382 \end_inset
31383 </cell>
31384 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31385 \begin_inset Text
31386
31387 \layout Standard
31388
31389
31390 \size footnotesize
31391 Indirect set
31392 \end_inset
31393 </cell>
31394 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31395 \begin_inset Text
31396
31397 \layout Standard
31398
31399
31400 \size footnotesize
31401 (*IC_RESULT) = IC_RIGHT;
31402 \end_inset
31403 </cell>
31404 </row>
31405 <row topline="true">
31406 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31407 \begin_inset Text
31408
31409 \layout Standard
31410
31411
31412 \size footnotesize
31413 '='
31414 \end_inset
31415 </cell>
31416 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31417 \begin_inset Text
31418
31419 \layout Standard
31420
31421
31422 \size footnotesize
31423 IC_RIGHT() IC_RESULT()
31424 \end_inset
31425 </cell>
31426 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31427 \begin_inset Text
31428
31429 \layout Standard
31430
31431
31432 \size footnotesize
31433 Assignment
31434 \end_inset
31435 </cell>
31436 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31437 \begin_inset Text
31438
31439 \layout Standard
31440
31441
31442 \size footnotesize
31443 IC_RESULT = IC_RIGHT;
31444 \end_inset
31445 </cell>
31446 </row>
31447 <row topline="true">
31448 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31449 \begin_inset Text
31450
31451 \layout Standard
31452
31453
31454 \size footnotesize
31455 IFX
31456 \end_inset
31457 </cell>
31458 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31459 \begin_inset Text
31460
31461 \layout Standard
31462
31463
31464 \size footnotesize
31465 IC_COND IC_TRUE IC_LABEL
31466 \end_inset
31467 </cell>
31468 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31469 \begin_inset Text
31470
31471 \layout Standard
31472
31473
31474 \size footnotesize
31475 Conditional jump.
31476  If true label is present then jump to true label if condition is true else
31477  jump to false label if condition is false
31478 \end_inset
31479 </cell>
31480 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31481 \begin_inset Text
31482
31483 \layout Standard
31484
31485
31486 \size footnotesize
31487 if (IC_COND) goto IC_TRUE;
31488 \newline
31489 \SpecialChar ~
31490 \SpecialChar ~
31491 Or
31492 \newline
31493 If (!IC_COND) goto IC_FALSE;
31494 \end_inset
31495 </cell>
31496 </row>
31497 <row topline="true">
31498 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31499 \begin_inset Text
31500
31501 \layout Standard
31502
31503
31504 \size footnotesize
31505 ADDRESS_OF
31506 \end_inset
31507 </cell>
31508 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31509 \begin_inset Text
31510
31511 \layout Standard
31512
31513
31514 \size footnotesize
31515 IC_LEFT() IC_RESULT()
31516 \end_inset
31517 </cell>
31518 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31519 \begin_inset Text
31520
31521 \layout Standard
31522
31523
31524 \size footnotesize
31525 Address of
31526 \end_inset
31527 </cell>
31528 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31529 \begin_inset Text
31530
31531 \layout Standard
31532
31533
31534 \size footnotesize
31535 IC_RESULT = &IC_LEFT();
31536 \end_inset
31537 </cell>
31538 </row>
31539 <row topline="true">
31540 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31541 \begin_inset Text
31542
31543 \layout Standard
31544
31545
31546 \size footnotesize
31547 JUMPTABLE
31548 \end_inset
31549 </cell>
31550 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31551 \begin_inset Text
31552
31553 \layout Standard
31554
31555
31556 \size footnotesize
31557 IC_JTCOND IC_JTLABELS
31558 \end_inset
31559 </cell>
31560 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31561 \begin_inset Text
31562
31563 \layout Standard
31564
31565
31566 \size footnotesize
31567 Jump to list of labels depending on the value of JTCOND
31568 \end_inset
31569 </cell>
31570 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31571 \begin_inset Text
31572
31573 \layout Standard
31574
31575
31576 \size footnotesize
31577 Switch statement
31578 \end_inset
31579 </cell>
31580 </row>
31581 <row topline="true">
31582 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31583 \begin_inset Text
31584
31585 \layout Standard
31586
31587
31588 \size footnotesize
31589 CAST
31590 \end_inset
31591 </cell>
31592 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31593 \begin_inset Text
31594
31595 \layout Standard
31596
31597
31598 \size footnotesize
31599 IC_RIGHT() IC_LEFT() IC_RESULT()
31600 \end_inset
31601 </cell>
31602 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31603 \begin_inset Text
31604
31605 \layout Standard
31606
31607
31608 \size footnotesize
31609 Cast types
31610 \end_inset
31611 </cell>
31612 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31613 \begin_inset Text
31614
31615 \layout Standard
31616
31617
31618 \size footnotesize
31619 IC_RESULT = (typeof IC_LEFT) IC_RIGHT;
31620 \end_inset
31621 </cell>
31622 </row>
31623 <row topline="true">
31624 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31625 \begin_inset Text
31626
31627 \layout Standard
31628
31629
31630 \size footnotesize
31631 SEND
31632 \end_inset
31633 </cell>
31634 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31635 \begin_inset Text
31636
31637 \layout Standard
31638
31639
31640 \size footnotesize
31641 IC_LEFT()
31642 \end_inset
31643 </cell>
31644 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31645 \begin_inset Text
31646
31647 \layout Standard
31648
31649
31650 \size footnotesize
31651 This is used for passing parameters in registers;
31652 \newline
31653 move IC_LEFT to the next available parameter register.
31654 \end_inset
31655 </cell>
31656 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31657 \begin_inset Text
31658
31659 \layout Standard
31660
31661
31662 \size footnotesize
31663 None
31664 \end_inset
31665 </cell>
31666 </row>
31667 <row topline="true">
31668 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31669 \begin_inset Text
31670
31671 \layout Standard
31672
31673
31674 \size footnotesize
31675 RECV
31676 \end_inset
31677 </cell>
31678 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31679 \begin_inset Text
31680
31681 \layout Standard
31682
31683
31684 \size footnotesize
31685 IC_RESULT()
31686 \end_inset
31687 </cell>
31688 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31689 \begin_inset Text
31690
31691 \layout Standard
31692
31693
31694 \size footnotesize
31695 This is used for receiving parameters passed in registers;
31696 \newline
31697 Move the values in the next parameter register to IC_RESULT
31698 \end_inset
31699 </cell>
31700 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31701 \begin_inset Text
31702
31703 \layout Standard
31704
31705
31706 \size footnotesize
31707 None
31708 \end_inset
31709 </cell>
31710 </row>
31711 <row topline="true" bottomline="true">
31712 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31713 \begin_inset Text
31714
31715 \layout Standard
31716
31717
31718 \shape slanted
31719 \size footnotesize
31720 (some more have been added)
31721 \end_inset
31722 </cell>
31723 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31724 \begin_inset Text
31725
31726 \layout Standard
31727
31728 \end_inset
31729 </cell>
31730 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31731 \begin_inset Text
31732
31733 \layout Standard
31734
31735 \end_inset
31736 </cell>
31737 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31738 \begin_inset Text
31739
31740 \layout Standard
31741
31742
31743 \shape slanted
31744 \size footnotesize
31745 see f.e.
31746
31747 \family typewriter
31748 gen51Code()
31749 \family default
31750  in
31751 \family typewriter
31752 src/mcs51/gen.c
31753 \end_inset
31754 </cell>
31755 </row>
31756 </lyxtabular>
31757
31758 \end_inset
31759
31760
31761 \layout Comment
31762
31763 In the original article Figure II was announced to be downloadable on
31764 \shape italic
31765 Circuit Cellar
31766 \shape default
31767 's web site.
31768  ftp://ftp.circuitcellar.com/pub/Circuit_Cellar/2000/121/dutta.ZIP
31769 \layout Paragraph*
31770
31771 ICode Example
31772 \begin_inset LatexCommand \index{iCode}
31773
31774 \end_inset
31775
31776
31777 \layout Standard
31778
31779 This section shows some details of iCode.
31780  The example C code does not do anything useful; it is used as an example
31781  to illustrate the intermediate code generated by the compiler.
31782 \layout Verse
31783
31784
31785 \family typewriter
31786 1.\SpecialChar ~
31787 xdata int * p;
31788 \newline
31789 2.\SpecialChar ~
31790 int gint;
31791 \newline
31792 3.\SpecialChar ~
31793 /* This function does nothing useful.
31794  It is used
31795 \newline
31796 4.\SpecialChar ~
31797 \SpecialChar ~
31798 \SpecialChar ~
31799 \SpecialChar ~
31800 for the purpose of explaining iCode */
31801 \newline
31802 5.\SpecialChar ~
31803 short function (data int *x)
31804 \newline
31805 6.\SpecialChar ~
31806 {
31807 \newline
31808 7.\SpecialChar ~
31809 \SpecialChar ~
31810 \SpecialChar ~
31811 short i=10; \SpecialChar ~
31812 \SpecialChar ~
31813 /* dead initialization eliminated */
31814 \newline
31815 8.\SpecialChar ~
31816 \SpecialChar ~
31817 \SpecialChar ~
31818 short sum=10; /* dead initialization eliminated */
31819 \newline
31820 9.\SpecialChar ~
31821 \SpecialChar ~
31822 \SpecialChar ~
31823 short mul;
31824 \newline
31825 10.\SpecialChar ~
31826 \SpecialChar ~
31827 int j ;
31828 \newline
31829 11.\SpecialChar ~
31830 \SpecialChar ~
31831 while (*x) *x++ = *p++;
31832 \newline
31833 12.\SpecialChar ~
31834 \SpecialChar ~
31835 \SpecialChar ~
31836 \SpecialChar ~
31837 sum = 0 ;
31838 \newline
31839 13.\SpecialChar ~
31840 \SpecialChar ~
31841 mul = 0;
31842 \newline
31843 14.\SpecialChar ~
31844 \SpecialChar ~
31845 /* compiler detects i,j to be induction variables */
31846 \newline
31847 15.\SpecialChar ~
31848 \SpecialChar ~
31849 for (i = 0, j = 10 ; i < 10 ; i++, j
31850 \family default
31851 -
31852 \begin_inset ERT
31853 status Collapsed
31854
31855 \layout Standard
31856
31857 \backslash
31858 /
31859 \end_inset
31860
31861 -
31862 \family typewriter
31863 ) {
31864 \newline
31865 16.\SpecialChar ~
31866 \SpecialChar ~
31867 \SpecialChar ~
31868 \SpecialChar ~
31869 sum += i;
31870 \newline
31871 17.\SpecialChar ~
31872 \SpecialChar ~
31873 \SpecialChar ~
31874 \SpecialChar ~
31875 mul += i * 3; \SpecialChar ~
31876 \SpecialChar ~
31877 /* this multiplication remains */
31878 \newline
31879 18.\SpecialChar ~
31880 \SpecialChar ~
31881 \SpecialChar ~
31882 \SpecialChar ~
31883 gint += j * 3;\SpecialChar ~
31884 \SpecialChar ~
31885 /* this multiplication changed to addition */
31886 \newline
31887 19.\SpecialChar ~
31888 \SpecialChar ~
31889 }
31890 \newline
31891 20.\SpecialChar ~
31892 \SpecialChar ~
31893 return sum+mul;
31894 \newline
31895 21.\SpecialChar ~
31896 }
31897 \layout Standard
31898
31899 In addition to the operands each iCode contains information about the filename
31900  and line it corresponds to in the source file.
31901  The first field in the listing should be interpreted as follows:
31902 \newline
31903
31904 \shape italic
31905 \size footnotesize
31906 Filename(linenumber: iCode Execution sequence number : ICode hash table
31907  key : loop depth of the iCode).
31908 \shape default
31909 \size default
31910
31911 \newline
31912 Then follows the human readable form of the ICode operation.
31913  Each operand of this triplet form can be of three basic types a) compiler
31914  generated temporary b) user defined variable c) a constant value.
31915  Note that local variables and parameters are replaced by compiler generated
31916  temporaries.
31917  Live ranges
31918 \begin_inset LatexCommand \index{Live range analysis}
31919
31920 \end_inset
31921
31922  are computed only for temporaries (i.e.
31923  live ranges are not computed for global variables).
31924  Registers
31925 \begin_inset LatexCommand \index{Register allocation}
31926
31927 \end_inset
31928
31929  are allocated for temporaries only.
31930  Operands are formatted in the following manner:
31931 \newline
31932
31933 \shape italic
31934 \size footnotesize
31935 Operand Name [lr live-from : live-to ] { type information } [ registers
31936  allocated ].
31937 \shape default
31938 \size default
31939
31940 \newline
31941 As mentioned earlier the live ranges are computed in terms of the execution
31942  sequence number of the iCodes, for example
31943 \newline
31944 the iTemp0 is live from (i.e.
31945  first defined in iCode with execution sequence number 3, and is last used
31946  in the iCode with sequence number 5).
31947  For induction variables such as iTemp21 the live range computation extends
31948  the lifetime from the start to the end of the loop.
31949 \newline
31950 The register allocator used the live range information to allocate registers,
31951  the same registers may be used for different temporaries if their live
31952  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
31953  iTemp17 since their live ranges do not overlap.
31954  In addition the allocator also takes into consideration the type and usage
31955  of a temporary, for example itemp6 is a pointer to near space and is used
31956  as to fetch data from (i.e.
31957  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
31958  Some short lived temporaries are allocated to special registers which have
31959  meaning to the code generator e.g.
31960  iTemp13 is allocated to a pseudo register CC which tells the back end that
31961  the temporary is used only for a conditional jump the code generation makes
31962  use of this information to optimize a compare and jump ICode.
31963 \newline
31964 There are several loop optimizations
31965 \begin_inset LatexCommand \index{Loop optimization}
31966
31967 \end_inset
31968
31969  performed by the compiler.
31970  It can detect induction variables iTemp21(i) and iTemp23(j).
31971  Also note the compiler does selective strength reduction
31972 \begin_inset LatexCommand \index{Strength reduction}
31973
31974 \end_inset
31975
31976 , i.e.
31977  the multiplication of an induction variable in line 18 (gint = j * 3) is
31978  changed to addition, a new temporary iTemp17 is allocated and assigned
31979  a initial value, a constant 3 is then added for each iteration of the loop.
31980  The compiler does not change the multiplication
31981 \begin_inset LatexCommand \index{Multiplication}
31982
31983 \end_inset
31984
31985  in line 17 however since the processor does support an 8 * 8 bit multiplication.
31986 \newline
31987 Note the dead code elimination
31988 \begin_inset LatexCommand \index{Dead-code elimination}
31989
31990 \end_inset
31991
31992  optimization eliminated the dead assignments in line 7 & 8 to I and sum
31993  respectively.
31994 \newline
31995
31996 \layout Standard
31997
31998
31999 \size footnotesize
32000 Sample.c (5:1:0:0) _entry($9) :
32001 \layout Standard
32002
32003
32004 \size footnotesize
32005 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
32006 \layout Standard
32007
32008
32009 \size footnotesize
32010 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
32011 \layout Standard
32012
32013
32014 \size footnotesize
32015 Sample.c(11:4:53:0) preHeaderLbl0($11) :
32016 \layout Standard
32017
32018
32019 \size footnotesize
32020 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
32021  * int}[r2]
32022 \layout Standard
32023
32024
32025 \size footnotesize
32026 Sample.c(11:6:5:1) _whilecontinue_0($1) :
32027 \layout Standard
32028
32029
32030 \size footnotesize
32031 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
32032  int}[r0]]
32033 \layout Standard
32034
32035
32036 \size footnotesize
32037 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
32038 \layout Standard
32039
32040
32041 \size footnotesize
32042 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
32043  * int}
32044 \layout Standard
32045
32046
32047 \size footnotesize
32048 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
32049  {short}
32050 \layout Standard
32051
32052
32053 \size footnotesize
32054 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
32055  * int}[DPTR]]
32056 \layout Standard
32057
32058
32059 \size footnotesize
32060 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
32061 }[r2 r3]
32062 \layout Standard
32063
32064
32065 \size footnotesize
32066 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
32067  * int}[r0] + 0x2 {short}
32068 \layout Standard
32069
32070
32071 \size footnotesize
32072 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
32073 \layout Standard
32074
32075
32076 \size footnotesize
32077 Sample.c(11:17:21:0)_whilebreak_0($3) :
32078 \layout Standard
32079
32080
32081 \size footnotesize
32082 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
32083 \layout Standard
32084
32085
32086 \size footnotesize
32087 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
32088 \layout Standard
32089
32090
32091 \size footnotesize
32092 Sample.c(15:20:54:0)preHeaderLbl1($13) :
32093 \layout Standard
32094
32095
32096 \size footnotesize
32097 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
32098 \layout Standard
32099
32100
32101 \size footnotesize
32102 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
32103 \layout Standard
32104
32105
32106 \size footnotesize
32107 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
32108 \layout Standard
32109
32110
32111 \size footnotesize
32112 Sample.c(15:24:26:1)_forcond_0($4) :
32113 \layout Standard
32114
32115
32116 \size footnotesize
32117 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
32118  < 0xa {short}
32119 \layout Standard
32120
32121
32122 \size footnotesize
32123 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
32124 \layout Standard
32125
32126
32127 \size footnotesize
32128 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
32129  + ITemp21 [lr21:38]{short}[r4]
32130 \layout Standard
32131
32132
32133 \size footnotesize
32134 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
32135  * 0x3 {short}
32136 \layout Standard
32137
32138
32139 \size footnotesize
32140 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
32141  + iTemp15 [lr29:30]{short}[r1]
32142 \layout Standard
32143
32144
32145 \size footnotesize
32146 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
32147  r0]- 0x3 {short}
32148 \layout Standard
32149
32150
32151 \size footnotesize
32152 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
32153 int}[r7 r0]
32154 \layout Standard
32155
32156
32157 \size footnotesize
32158 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
32159  + 0x1 {short}
32160 \layout Standard
32161
32162
32163 \size footnotesize
32164 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
32165  r6]- 0x1 {short}
32166 \layout Standard
32167
32168
32169 \size footnotesize
32170 Sample.c(19:38:47:1) goto _forcond_0($4)
32171 \layout Standard
32172
32173
32174 \size footnotesize
32175 Sample.c(19:39:48:0)_forbreak_0($7) :
32176 \layout Standard
32177
32178
32179 \size footnotesize
32180 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
32181  + ITemp11 [lr19:40]{short}[r3]
32182 \layout Standard
32183
32184
32185 \size footnotesize
32186 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
32187 \layout Standard
32188
32189
32190 \size footnotesize
32191 Sample.c(20:42:51:0)_return($8) :
32192 \layout Standard
32193
32194
32195 \size footnotesize
32196 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
32197 \size default
32198
32199 \newline
32200
32201 \newline
32202 Finally the code generated for this function:
32203 \newline
32204
32205 \layout Standard
32206
32207
32208 \size footnotesize
32209 .area DSEG (DATA)
32210 \layout Standard
32211
32212
32213 \size footnotesize
32214 _p::
32215 \layout Standard
32216
32217
32218 \size footnotesize
32219 \SpecialChar ~
32220 \SpecialChar ~
32221 .ds 2
32222 \layout Standard
32223
32224
32225 \size footnotesize
32226 _gint::
32227 \layout Standard
32228
32229
32230 \size footnotesize
32231 \SpecialChar ~
32232 \SpecialChar ~
32233 .ds 2
32234 \layout Standard
32235
32236
32237 \size footnotesize
32238 ; sample.c 5
32239 \layout Standard
32240
32241
32242 \size footnotesize
32243 ; ----------------------------------------------
32244 \layout Standard
32245
32246
32247 \size footnotesize
32248 ; function function
32249 \layout Standard
32250
32251
32252 \size footnotesize
32253 ; ----------------------------------------------
32254 \layout Standard
32255
32256
32257 \size footnotesize
32258 _function:
32259 \layout Standard
32260
32261
32262 \size footnotesize
32263 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
32264 \layout Standard
32265
32266
32267 \size footnotesize
32268 \SpecialChar ~
32269 \SpecialChar ~
32270 mov r2,dpl
32271 \layout Standard
32272
32273
32274 \size footnotesize
32275 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
32276 \layout Standard
32277
32278
32279 \size footnotesize
32280 \SpecialChar ~
32281 \SpecialChar ~
32282 mov ar0,r2
32283 \layout Standard
32284
32285
32286 \size footnotesize
32287 ;_whilecontinue_0($1) :
32288 \layout Standard
32289
32290
32291 \size footnotesize
32292 00101$:
32293 \layout Standard
32294
32295
32296 \size footnotesize
32297 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
32298 \layout Standard
32299
32300
32301 \size footnotesize
32302 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
32303 \layout Standard
32304
32305
32306 \size footnotesize
32307 \SpecialChar ~
32308 \SpecialChar ~
32309 mov ar2,@r0
32310 \layout Standard
32311
32312
32313 \size footnotesize
32314 \SpecialChar ~
32315 \SpecialChar ~
32316 inc r0
32317 \layout Standard
32318
32319
32320 \size footnotesize
32321 \SpecialChar ~
32322 \SpecialChar ~
32323 mov ar3,@r0
32324 \layout Standard
32325
32326
32327 \size footnotesize
32328 \SpecialChar ~
32329 \SpecialChar ~
32330 dec r0
32331 \layout Standard
32332
32333
32334 \size footnotesize
32335 \SpecialChar ~
32336 \SpecialChar ~
32337 mov a,r2
32338 \layout Standard
32339
32340
32341 \size footnotesize
32342 \SpecialChar ~
32343 \SpecialChar ~
32344 orl a,r3
32345 \layout Standard
32346
32347
32348 \size footnotesize
32349 \SpecialChar ~
32350 \SpecialChar ~
32351 jz 00103$
32352 \layout Standard
32353
32354
32355 \size footnotesize
32356 00114$:
32357 \layout Standard
32358
32359
32360 \size footnotesize
32361 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
32362 \layout Standard
32363
32364
32365 \size footnotesize
32366 \SpecialChar ~
32367 \SpecialChar ~
32368 mov dpl,_p
32369 \layout Standard
32370
32371
32372 \size footnotesize
32373 \SpecialChar ~
32374 \SpecialChar ~
32375 mov dph,(_p + 1)
32376 \layout Standard
32377
32378
32379 \size footnotesize
32380 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
32381 \layout Standard
32382
32383
32384 \size footnotesize
32385 \SpecialChar ~
32386 \SpecialChar ~
32387 mov a,#0x02
32388 \layout Standard
32389
32390
32391 \size footnotesize
32392 \SpecialChar ~
32393 \SpecialChar ~
32394 add a,_p
32395 \layout Standard
32396
32397
32398 \size footnotesize
32399 \SpecialChar ~
32400 \SpecialChar ~
32401 mov _p,a
32402 \layout Standard
32403
32404
32405 \size footnotesize
32406 \SpecialChar ~
32407 \SpecialChar ~
32408 clr a
32409 \layout Standard
32410
32411
32412 \size footnotesize
32413 \SpecialChar ~
32414 \SpecialChar ~
32415 addc a,(_p + 1)
32416 \layout Standard
32417
32418
32419 \size footnotesize
32420 \SpecialChar ~
32421 \SpecialChar ~
32422 mov (_p + 1),a
32423 \layout Standard
32424
32425
32426 \size footnotesize
32427 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
32428 \layout Standard
32429
32430
32431 \size footnotesize
32432 \SpecialChar ~
32433 \SpecialChar ~
32434 movx a,@dptr
32435 \layout Standard
32436
32437
32438 \size footnotesize
32439 \SpecialChar ~
32440 \SpecialChar ~
32441 mov r2,a
32442 \layout Standard
32443
32444
32445 \size footnotesize
32446 \SpecialChar ~
32447 \SpecialChar ~
32448 inc dptr
32449 \layout Standard
32450
32451
32452 \size footnotesize
32453 \SpecialChar ~
32454 \SpecialChar ~
32455 movx a,@dptr
32456 \layout Standard
32457
32458
32459 \size footnotesize
32460 \SpecialChar ~
32461 \SpecialChar ~
32462 mov r3,a
32463 \layout Standard
32464
32465
32466 \size footnotesize
32467 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
32468 \layout Standard
32469
32470
32471 \size footnotesize
32472 \SpecialChar ~
32473 \SpecialChar ~
32474 mov @r0,ar2
32475 \layout Standard
32476
32477
32478 \size footnotesize
32479 \SpecialChar ~
32480 \SpecialChar ~
32481 inc r0
32482 \layout Standard
32483
32484
32485 \size footnotesize
32486 \SpecialChar ~
32487 \SpecialChar ~
32488 mov @r0,ar3
32489 \layout Standard
32490
32491
32492 \size footnotesize
32493 ; iTemp6 [lr5:16]{_near * int}[r0] =
32494 \layout Standard
32495
32496
32497 \size footnotesize
32498 ; iTemp6 [lr5:16]{_near * int}[r0] +
32499 \layout Standard
32500
32501
32502 \size footnotesize
32503 ; 0x2 {short}
32504 \layout Standard
32505
32506
32507 \size footnotesize
32508 \SpecialChar ~
32509 \SpecialChar ~
32510 inc r0
32511 \layout Standard
32512
32513
32514 \size footnotesize
32515 ; goto _whilecontinue_0($1)
32516 \layout Standard
32517
32518
32519 \size footnotesize
32520 \SpecialChar ~
32521 \SpecialChar ~
32522 sjmp 00101$
32523 \layout Standard
32524
32525
32526 \size footnotesize
32527 ; _whilebreak_0($3) :
32528 \layout Standard
32529
32530
32531 \size footnotesize
32532 00103$:
32533 \layout Standard
32534
32535
32536 \size footnotesize
32537 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
32538 \layout Standard
32539
32540
32541 \size footnotesize
32542 \SpecialChar ~
32543 \SpecialChar ~
32544 mov r2,#0x00
32545 \layout Standard
32546
32547
32548 \size footnotesize
32549 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
32550 \layout Standard
32551
32552
32553 \size footnotesize
32554 \SpecialChar ~
32555 \SpecialChar ~
32556 mov r3,#0x00
32557 \layout Standard
32558
32559
32560 \size footnotesize
32561 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
32562 \layout Standard
32563
32564
32565 \size footnotesize
32566 \SpecialChar ~
32567 \SpecialChar ~
32568 mov r4,#0x00
32569 \layout Standard
32570
32571
32572 \size footnotesize
32573 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
32574 \layout Standard
32575
32576
32577 \size footnotesize
32578 \SpecialChar ~
32579 \SpecialChar ~
32580 mov r5,#0x0A
32581 \layout Standard
32582
32583
32584 \size footnotesize
32585 \SpecialChar ~
32586 \SpecialChar ~
32587 mov r6,#0x00
32588 \layout Standard
32589
32590
32591 \size footnotesize
32592 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
32593 \layout Standard
32594
32595
32596 \size footnotesize
32597 \SpecialChar ~
32598 \SpecialChar ~
32599 mov r7,#0x1E
32600 \layout Standard
32601
32602
32603 \size footnotesize
32604 \SpecialChar ~
32605 \SpecialChar ~
32606 mov r0,#0x00
32607 \layout Standard
32608
32609
32610 \size footnotesize
32611 ; _forcond_0($4) :
32612 \layout Standard
32613
32614
32615 \size footnotesize
32616 00104$:
32617 \layout Standard
32618
32619
32620 \size footnotesize
32621 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
32622 \layout Standard
32623
32624
32625 \size footnotesize
32626 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
32627 \layout Standard
32628
32629
32630 \size footnotesize
32631 \SpecialChar ~
32632 \SpecialChar ~
32633 clr c
32634 \layout Standard
32635
32636
32637 \size footnotesize
32638 \SpecialChar ~
32639 \SpecialChar ~
32640 mov a,r4
32641 \layout Standard
32642
32643
32644 \size footnotesize
32645 \SpecialChar ~
32646 \SpecialChar ~
32647 xrl a,#0x80
32648 \layout Standard
32649
32650
32651 \size footnotesize
32652 \SpecialChar ~
32653 \SpecialChar ~
32654 subb a,#0x8a
32655 \layout Standard
32656
32657
32658 \size footnotesize
32659 \SpecialChar ~
32660 \SpecialChar ~
32661 jnc 00107$
32662 \layout Standard
32663
32664
32665 \size footnotesize
32666 00115$:
32667 \layout Standard
32668
32669
32670 \size footnotesize
32671 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
32672 \layout Standard
32673
32674
32675 \size footnotesize
32676 ; iTemp21 [lr21:38]{short}[r4]
32677 \layout Standard
32678
32679
32680 \size footnotesize
32681 \SpecialChar ~
32682 \SpecialChar ~
32683 mov a,r4
32684 \layout Standard
32685
32686
32687 \size footnotesize
32688 \SpecialChar ~
32689 \SpecialChar ~
32690 add a,r2
32691 \layout Standard
32692
32693
32694 \size footnotesize
32695 \SpecialChar ~
32696 \SpecialChar ~
32697 mov r2,a
32698 \layout Standard
32699
32700
32701 \size footnotesize
32702 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
32703 \layout Standard
32704
32705
32706 \size footnotesize
32707 \SpecialChar ~
32708 \SpecialChar ~
32709 mov b,#0x03
32710 \layout Standard
32711
32712
32713 \size footnotesize
32714 \SpecialChar ~
32715 \SpecialChar ~
32716 mov a,r4
32717 \layout Standard
32718
32719
32720 \size footnotesize
32721 \SpecialChar ~
32722 \SpecialChar ~
32723 mul ab
32724 \layout Standard
32725
32726
32727 \size footnotesize
32728 \SpecialChar ~
32729 \SpecialChar ~
32730 mov r1,a
32731 \layout Standard
32732
32733
32734 \size footnotesize
32735 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
32736 \layout Standard
32737
32738
32739 \size footnotesize
32740 ; iTemp15 [lr29:30]{short}[r1]
32741 \layout Standard
32742
32743
32744 \size footnotesize
32745 \SpecialChar ~
32746 \SpecialChar ~
32747 add a,r3
32748 \layout Standard
32749
32750
32751 \size footnotesize
32752 \SpecialChar ~
32753 \SpecialChar ~
32754 mov r3,a
32755 \layout Standard
32756
32757
32758 \size footnotesize
32759 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
32760 \layout Standard
32761
32762
32763 \size footnotesize
32764 \SpecialChar ~
32765 \SpecialChar ~
32766 mov a,r7
32767 \layout Standard
32768
32769
32770 \size footnotesize
32771 \SpecialChar ~
32772 \SpecialChar ~
32773 add a,#0xfd
32774 \layout Standard
32775
32776
32777 \size footnotesize
32778 \SpecialChar ~
32779 \SpecialChar ~
32780 mov r7,a
32781 \layout Standard
32782
32783
32784 \size footnotesize
32785 \SpecialChar ~
32786 \SpecialChar ~
32787 mov a,r0
32788 \layout Standard
32789
32790
32791 \size footnotesize
32792 \SpecialChar ~
32793 \SpecialChar ~
32794 addc a,#0xff
32795 \layout Standard
32796
32797
32798 \size footnotesize
32799 \SpecialChar ~
32800 \SpecialChar ~
32801 mov r0,a
32802 \layout Standard
32803
32804
32805 \size footnotesize
32806 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
32807 \layout Standard
32808
32809
32810 \size footnotesize
32811 \SpecialChar ~
32812 \SpecialChar ~
32813 mov a,r7
32814 \layout Standard
32815
32816
32817 \size footnotesize
32818 \SpecialChar ~
32819 \SpecialChar ~
32820 add a,_gint
32821 \layout Standard
32822
32823
32824 \size footnotesize
32825 \SpecialChar ~
32826 \SpecialChar ~
32827 mov _gint,a
32828 \layout Standard
32829
32830
32831 \size footnotesize
32832 \SpecialChar ~
32833 \SpecialChar ~
32834 mov a,r0
32835 \layout Standard
32836
32837
32838 \size footnotesize
32839 \SpecialChar ~
32840 \SpecialChar ~
32841 addc a,(_gint + 1)
32842 \layout Standard
32843
32844
32845 \size footnotesize
32846 \SpecialChar ~
32847 \SpecialChar ~
32848 mov (_gint + 1),a
32849 \layout Standard
32850
32851
32852 \size footnotesize
32853 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
32854 \layout Standard
32855
32856
32857 \size footnotesize
32858 \SpecialChar ~
32859 \SpecialChar ~
32860 inc r4
32861 \layout Standard
32862
32863
32864 \size footnotesize
32865 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
32866 \layout Standard
32867
32868
32869 \size footnotesize
32870 \SpecialChar ~
32871 \SpecialChar ~
32872 dec r5
32873 \layout Standard
32874
32875
32876 \size footnotesize
32877 \SpecialChar ~
32878 \SpecialChar ~
32879 cjne r5,#0xff,00104$
32880 \layout Standard
32881
32882
32883 \size footnotesize
32884 \SpecialChar ~
32885 \SpecialChar ~
32886 dec r6
32887 \layout Standard
32888
32889
32890 \size footnotesize
32891 ; goto _forcond_0($4)
32892 \layout Standard
32893
32894
32895 \size footnotesize
32896 \SpecialChar ~
32897 \SpecialChar ~
32898 sjmp 00104$
32899 \layout Standard
32900
32901
32902 \size footnotesize
32903 ; _forbreak_0($7) :
32904 \layout Standard
32905
32906
32907 \size footnotesize
32908 00107$:
32909 \layout Standard
32910
32911
32912 \size footnotesize
32913 ; ret iTemp24 [lr40:41]{short}
32914 \layout Standard
32915
32916
32917 \size footnotesize
32918 \SpecialChar ~
32919 \SpecialChar ~
32920 mov a,r3
32921 \layout Standard
32922
32923
32924 \size footnotesize
32925 \SpecialChar ~
32926 \SpecialChar ~
32927 add a,r2
32928 \layout Standard
32929
32930
32931 \size footnotesize
32932 \SpecialChar ~
32933 \SpecialChar ~
32934 mov dpl,a
32935 \layout Standard
32936
32937
32938 \size footnotesize
32939 ; _return($8) :
32940 \layout Standard
32941
32942
32943 \size footnotesize
32944 00108$:
32945 \layout Standard
32946
32947
32948 \size footnotesize
32949 \SpecialChar ~
32950 \SpecialChar ~
32951 ret
32952 \newline
32953
32954 \layout Section
32955
32956 A few words about basic block successors, predecessors and dominators
32957 \layout Standard
32958
32959 Successors are basic blocks
32960 \begin_inset LatexCommand \index{Basic blocks}
32961
32962 \end_inset
32963
32964  that might execute after this basic block.
32965 \newline
32966 Predecessors are basic blocks that might execute before reaching this basic
32967  block.
32968 \newline
32969 Dominators are basic blocks that WILL execute before reaching this basic
32970  block.
32971 \newline
32972
32973 \layout Standard
32974
32975 [basic block 1]
32976 \layout Standard
32977
32978 if (something)
32979 \layout Standard
32980
32981 \SpecialChar ~
32982 \SpecialChar ~
32983 \SpecialChar ~
32984 \SpecialChar ~
32985 [basic block 2]
32986 \layout Standard
32987
32988 else
32989 \layout Standard
32990
32991 \SpecialChar ~
32992 \SpecialChar ~
32993 \SpecialChar ~
32994 \SpecialChar ~
32995 [basic block 3]
32996 \layout Standard
32997
32998 [basic block 4]
32999 \newline
33000
33001 \layout Standard
33002
33003 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
33004 \layout Standard
33005
33006 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
33007 \layout Standard
33008
33009 c) domVect of [BB4] = BB1 ...
33010  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
33011  was executed.
33012 \layout Chapter
33013
33014 Acknowledgments
33015 \layout Standard
33016
33017
33018 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
33019
33020 \end_inset
33021
33022
33023 \newline
33024
33025 \newline
33026
33027 \emph on
33028 Thanks to all the other volunteer developers who have helped with coding,
33029  testing, web-page creation, distribution sets, etc.
33030  You know who you are :-)
33031 \emph default
33032
33033 \newline
33034
33035 \newline
33036
33037 \emph on
33038 Also thanks to Sourceforge
33039 \begin_inset LatexCommand \url{http://www.sf.net}
33040
33041 \end_inset
33042
33043  which has hosted the project since 1999 and donates significant download
33044  bandwidth and probably more than
33045 \begin_inset ERT
33046 status Collapsed
33047
33048 \layout Standard
33049 $10^{13}$
33050 \end_inset
33051
33052 CPU cycles per day.
33053 \newline
33054
33055 \begin_inset Note
33056 collapsed false
33057
33058 \layout Standard
33059
33060 more than 10^13 is an estimate: on my Athlon 2800+ it takes about (0.5+6.5+20)
33061  minutes for (configure+make+regression test), and there is (i386, amd64,
33062  alpha, ppc64, (mingw32), sparc, macosx).
33063
33064 \end_inset
33065
33066
33067 \layout Standard
33068
33069 This document was initially written by Sandeep Dutta
33070 \layout Standard
33071
33072 All product names mentioned herein may be trademarks
33073 \begin_inset LatexCommand \index{Trademarks}
33074
33075 \end_inset
33076
33077  of their respective companies.
33078
33079 \layout Section*
33080
33081 Alphabetical index
33082 \layout Standard
33083
33084 To avoid confusion, the installation and building options for SDCC itself
33085  (chapter 2) are not part of the index.
33086 \layout Standard
33087
33088
33089 \begin_inset LatexCommand \printindex{}
33090
33091 \end_inset
33092
33093
33094 \the_end