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.2
  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
6152 \layout List
6153 \added_space_bottom bigskip \labelwidthstring 00.00.0000
6154
6155
6156 \series bold
6157 -Wp\SpecialChar ~
6158 preprocessorOption[,preprocessorOption]
6159 \series default
6160
6161 \begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
6162
6163 \end_inset
6164
6165 ...
6166  Pass the preprocessorOption to the preprocessor
6167 \family typewriter
6168 sdcpp
6169 \family default
6170
6171 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
6172
6173 \end_inset
6174
6175 .
6176  SDCC uses an adapted version of the preprocessor
6177 \emph on
6178 cpp
6179 \emph default
6180  of the GNU Compiler Collection
6181 \begin_inset LatexCommand \index{gcc (GNU Compiler Collection)}
6182
6183 \end_inset
6184
6185  (
6186 \emph on
6187 gcc
6188 \emph default
6189
6190 \begin_inset LatexCommand \url{http://gcc.gnu.org/}
6191
6192 \end_inset
6193
6194 ), if you need more dedicated options please refer to the GCC\SpecialChar ~
6195 4.1.1\SpecialChar ~
6196 CPP\SpecialChar ~
6197 Manual
6198  at
6199 \begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
6200
6201 \end_inset
6202
6203 .
6204 \layout Subsection
6205
6206 Linker Options
6207 \begin_inset LatexCommand \index{Options linker}
6208
6209 \end_inset
6210
6211
6212 \begin_inset LatexCommand \index{Linker options}
6213
6214 \end_inset
6215
6216
6217 \layout List
6218 \labelwidthstring 00.00.0000
6219
6220
6221 \series bold
6222 -L\SpecialChar ~
6223 -
6224 \series default
6225
6226 \begin_inset ERT
6227 status Collapsed
6228
6229 \layout Standard
6230
6231 \backslash
6232 /
6233 \end_inset
6234
6235
6236 \series bold
6237 -lib-path
6238 \begin_inset LatexCommand \index{-\/-lib-path <path>}
6239
6240 \end_inset
6241
6242
6243 \begin_inset LatexCommand \index{-L -\/-lib-path}
6244
6245 \end_inset
6246
6247
6248 \series default
6249 \SpecialChar ~
6250 <absolute path to additional libraries> This option is passed to the linkage
6251  editor's additional libraries
6252 \begin_inset LatexCommand \index{Libraries}
6253
6254 \end_inset
6255
6256  search path.
6257  The path name must be absolute.
6258  Additional library files may be specified in the command line.
6259  See section Compiling programs for more details.
6260 \layout List
6261 \labelwidthstring 00.00.0000
6262
6263
6264 \series bold
6265 -
6266 \begin_inset ERT
6267 status Collapsed
6268
6269 \layout Standard
6270
6271 \backslash
6272 /
6273 \end_inset
6274
6275 -xram-loc
6276 \series default
6277
6278 \begin_inset LatexCommand \index{-\/-xram-loc <Value>}
6279
6280 \end_inset
6281
6282 \SpecialChar ~
6283 <Value> The start location of the external ram
6284 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
6285
6286 \end_inset
6287
6288 , default value is 0.
6289  The value entered can be in Hexadecimal or Decimal format, e.g.: -
6290 \begin_inset ERT
6291 status Collapsed
6292
6293 \layout Standard
6294
6295 \backslash
6296 /
6297 \end_inset
6298
6299 -xram-loc 0x8000 or -
6300 \begin_inset ERT
6301 status Collapsed
6302
6303 \layout Standard
6304
6305 \backslash
6306 /
6307 \end_inset
6308
6309 -xram-loc 32768.
6310 \layout List
6311 \labelwidthstring 00.00.0000
6312
6313
6314 \series bold
6315 -
6316 \begin_inset ERT
6317 status Collapsed
6318
6319 \layout Standard
6320
6321 \backslash
6322 /
6323 \end_inset
6324
6325 -code-loc
6326 \series default
6327
6328 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
6329
6330 \end_inset
6331
6332 \SpecialChar ~
6333 <Value> The start location of the code
6334 \begin_inset LatexCommand \index{code}
6335
6336 \end_inset
6337
6338  segment, default value 0.
6339  Note when this option is used the interrupt vector table
6340 \begin_inset LatexCommand \index{interrupt vector table}
6341
6342 \end_inset
6343
6344  is also relocated to the given address.
6345  The value entered can be in Hexadecimal or Decimal format, e.g.: -
6346 \begin_inset ERT
6347 status Collapsed
6348
6349 \layout Standard
6350
6351 \backslash
6352 /
6353 \end_inset
6354
6355 -code-loc 0x8000 or -
6356 \begin_inset ERT
6357 status Collapsed
6358
6359 \layout Standard
6360
6361 \backslash
6362 /
6363 \end_inset
6364
6365 -code-loc 32768.
6366 \layout List
6367 \labelwidthstring 00.00.0000
6368
6369
6370 \series bold
6371 -
6372 \begin_inset ERT
6373 status Collapsed
6374
6375 \layout Standard
6376
6377 \backslash
6378 /
6379 \end_inset
6380
6381 -stack-loc
6382 \series default
6383
6384 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
6385
6386 \end_inset
6387
6388 \SpecialChar ~
6389 <Value> By default the stack
6390 \begin_inset LatexCommand \index{stack}
6391
6392 \end_inset
6393
6394  is placed after the data segment.
6395  Using this option the stack can be placed anywhere in the internal memory
6396  space of the 8051.
6397  The value entered can be in Hexadecimal or Decimal format, e.g.
6398  -
6399 \begin_inset ERT
6400 status Collapsed
6401
6402 \layout Standard
6403
6404 \backslash
6405 /
6406 \end_inset
6407
6408 -stack-loc 0x20 or -
6409 \begin_inset ERT
6410 status Collapsed
6411
6412 \layout Standard
6413
6414 \backslash
6415 /
6416 \end_inset
6417
6418 -stack-loc 32.
6419  Since the sp register is incremented before a push or call, the initial
6420  sp will be set to one byte prior the provided value.
6421  The provided value should not overlap any other memory areas such as used
6422  register banks or the data segment and with enough space for the current
6423  application.
6424  The
6425 \series bold
6426 -
6427 \begin_inset ERT
6428 status Collapsed
6429
6430 \layout Standard
6431
6432 \backslash
6433 /
6434 \end_inset
6435
6436 -pack-iram
6437 \series default
6438 \SpecialChar ~
6439
6440 \begin_inset LatexCommand \index{-\/-pack-iram}
6441
6442 \end_inset
6443
6444  option (which is now a default setting) will override this setting, so
6445  you should also specify the
6446 \series bold
6447 -
6448 \begin_inset ERT
6449 status Collapsed
6450
6451 \layout Standard
6452
6453 \backslash
6454 /
6455 \end_inset
6456
6457 -no-pack-iram
6458 \series default
6459 \SpecialChar ~
6460
6461 \begin_inset LatexCommand \index{-\/-no-pack-iram}
6462
6463 \end_inset
6464
6465  option if you need to manually place the stack.
6466 \layout List
6467 \labelwidthstring 00.00.0000
6468
6469
6470 \series bold
6471 -
6472 \begin_inset ERT
6473 status Collapsed
6474
6475 \layout Standard
6476
6477 \backslash
6478 /
6479 \end_inset
6480
6481 -xstack-loc
6482 \series default
6483
6484 \begin_inset LatexCommand \index{-\/-xstack-loc <Value>}
6485
6486 \end_inset
6487
6488 \SpecialChar ~
6489 <Value> By default the external stack
6490 \begin_inset LatexCommand \index{xstack}
6491
6492 \end_inset
6493
6494  is placed after the pdata
6495 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
6496
6497 \end_inset
6498
6499  segment.
6500  Using this option the xstack can be placed anywhere in the external memory
6501  space of the 8051.
6502  The value entered can be in Hexadecimal or Decimal format, e.g.
6503  -
6504 \begin_inset ERT
6505 status Collapsed
6506
6507 \layout Standard
6508
6509 \backslash
6510 /
6511 \end_inset
6512
6513 -xstack-loc 0x8000 or -
6514 \begin_inset ERT
6515 status Collapsed
6516
6517 \layout Standard
6518
6519 \backslash
6520 /
6521 \end_inset
6522
6523 -stack-loc 32768.
6524  The provided value should not overlap any other memory areas such as the
6525  pdata or xdata segment and with enough space for the current application.
6526 \layout List
6527 \labelwidthstring 00.00.0000
6528
6529
6530 \series bold
6531 -
6532 \begin_inset ERT
6533 status Collapsed
6534
6535 \layout Standard
6536
6537 \backslash
6538 /
6539 \end_inset
6540
6541 -data-loc
6542 \series default
6543
6544 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
6545
6546 \end_inset
6547
6548 \SpecialChar ~
6549 <Value> The start location of the internal ram data
6550 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
6551
6552 \end_inset
6553
6554  segment.
6555  The value entered can be in Hexadecimal or Decimal format, eg.
6556  -
6557 \begin_inset ERT
6558 status Collapsed
6559
6560 \layout Standard
6561
6562 \backslash
6563 /
6564 \end_inset
6565
6566 -data-loc 0x20 or -
6567 \begin_inset ERT
6568 status Collapsed
6569
6570 \layout Standard
6571
6572 \backslash
6573 /
6574 \end_inset
6575
6576 -data-loc 32.
6577  (By default, the start location of the internal ram data segment  is set
6578  as low as possible in memory, taking into account the used register banks
6579  and the bit segment at address 0x20.
6580  For example if register banks 0 and 1 are used without bit variables, the
6581  data segment will be set, if -
6582 \begin_inset ERT
6583 status Collapsed
6584
6585 \layout Standard
6586
6587 \backslash
6588 /
6589 \end_inset
6590
6591 -data-loc is not used, to location 0x10.)
6592 \layout List
6593 \labelwidthstring 00.00.0000
6594
6595
6596 \series bold
6597 -
6598 \begin_inset ERT
6599 status Collapsed
6600
6601 \layout Standard
6602
6603 \backslash
6604 /
6605 \end_inset
6606
6607 -idata-loc
6608 \series default
6609
6610 \begin_inset LatexCommand \index{-\/-idata-loc <Value>}
6611
6612 \end_inset
6613
6614 \SpecialChar ~
6615 <Value> The start location of the indirectly addressable internal ram
6616 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
6617
6618 \end_inset
6619
6620  of the 8051, default value is 0x80.
6621  The value entered can be in Hexadecimal or Decimal format, eg.
6622  -
6623 \begin_inset ERT
6624 status Collapsed
6625
6626 \layout Standard
6627
6628 \backslash
6629 /
6630 \end_inset
6631
6632 -idata-loc 0x88 or -
6633 \begin_inset ERT
6634 status Collapsed
6635
6636 \layout Standard
6637
6638 \backslash
6639 /
6640 \end_inset
6641
6642 -idata-loc 136.
6643 \layout List
6644 \labelwidthstring 00.00.0000
6645
6646
6647 \series bold
6648 -
6649 \begin_inset ERT
6650 status Collapsed
6651
6652 \layout Standard
6653
6654 \backslash
6655 /
6656 \end_inset
6657
6658 -bit-loc
6659 \series default
6660 \SpecialChar ~
6661 <Value> The start location of the bit
6662 \begin_inset LatexCommand \index{bit}
6663
6664 \end_inset
6665
6666  addressable internal ram of the 8051.
6667  This is
6668 \emph on
6669 not
6670 \emph default
6671  implemented yet.
6672  Instead an option can be passed directly to the linker: -Wl\SpecialChar ~
6673 -bBSEG=<Value>.
6674 \layout List
6675 \labelwidthstring 00.00.0000
6676
6677
6678 \series bold
6679 -
6680 \begin_inset ERT
6681 status Collapsed
6682
6683 \layout Standard
6684
6685 \backslash
6686 /
6687 \end_inset
6688
6689 -out-fmt-ihx
6690 \begin_inset LatexCommand \index{-\/-out-fmt-ihx}
6691
6692 \end_inset
6693
6694
6695 \bar under
6696
6697 \series default
6698 \bar default
6699 The linker output (final object code) is in Intel Hex format.
6700 \begin_inset LatexCommand \index{Intel hex format}
6701
6702 \end_inset
6703
6704  This is the default option.
6705  The format itself is documented in the documentation of srecord
6706 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
6707
6708 \end_inset
6709
6710 .
6711 \layout List
6712 \labelwidthstring 00.00.0000
6713
6714
6715 \series bold
6716 -
6717 \begin_inset ERT
6718 status Collapsed
6719
6720 \layout Standard
6721
6722 \backslash
6723 /
6724 \end_inset
6725
6726 -out-fmt-s19
6727 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
6728
6729 \end_inset
6730
6731
6732 \bar under
6733
6734 \series default
6735 \bar default
6736 The linker output (final object code) is in Motorola S19 format
6737 \begin_inset LatexCommand \index{Motorola S19 format}
6738
6739 \end_inset
6740
6741 .
6742  The format itself is documented in the documentation of srecord.
6743 \layout List
6744 \labelwidthstring 00.00.0000
6745
6746
6747 \series bold
6748 -
6749 \begin_inset ERT
6750 status Collapsed
6751
6752 \layout Standard
6753
6754 \backslash
6755 /
6756 \end_inset
6757
6758 -out-fmt-elf
6759 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
6760
6761 \end_inset
6762
6763
6764 \begin_inset LatexCommand \index{HC08!Options!-\/-out-fmt-elf}
6765
6766 \end_inset
6767
6768
6769 \bar under
6770
6771 \series default
6772 \bar default
6773 The linker output (final object code) is in ELF format
6774 \begin_inset LatexCommand \index{ELF format}
6775
6776 \end_inset
6777
6778 .
6779  (Currently only supported for the HC08
6780 \begin_inset LatexCommand \index{HC08}
6781
6782 \end_inset
6783
6784  processors)
6785 \layout List
6786 \added_space_bottom bigskip \labelwidthstring 00.00.0000
6787
6788
6789 \series bold
6790 -Wl\SpecialChar ~
6791 linkOption[,linkOption]
6792 \series default
6793
6794 \begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
6795
6796 \end_inset
6797
6798 ...
6799  Pass the linkOption to the linker.
6800  If a bootloader is used an option like
6801 \begin_inset Quotes sld
6802 \end_inset
6803
6804 -Wl\SpecialChar ~
6805 -bCSEG=0x1000
6806 \begin_inset Quotes srd
6807 \end_inset
6808
6809  would be typical to set the start of the code segment.
6810  See also #pragma constseg and #pragma codeseg in section
6811 \begin_inset LatexCommand \ref{sec:Pragmas}
6812
6813 \end_inset
6814
6815  .
6816  File sdcc/as/doc/asxhtm.html has more on linker options.
6817 \layout Subsection
6818
6819 MCS51 Options
6820 \begin_inset LatexCommand \index{Options MCS51}
6821
6822 \end_inset
6823
6824
6825 \begin_inset LatexCommand \index{MCS51 options}
6826
6827 \end_inset
6828
6829
6830 \layout List
6831 \labelwidthstring 00.00.0000
6832
6833
6834 \series bold
6835 -
6836 \begin_inset ERT
6837 status Collapsed
6838
6839 \layout Standard
6840
6841 \backslash
6842 /
6843 \end_inset
6844
6845 -model-small
6846 \begin_inset LatexCommand \index{-\/-model-small}
6847
6848 \end_inset
6849
6850
6851 \series default
6852 \size large
6853 \emph on
6854
6855 \size default
6856 \emph default
6857 Generate code for Small Model programs, see section Memory Models for more
6858  details.
6859  This is the default model.
6860 \layout List
6861 \labelwidthstring 00.00.0000
6862
6863
6864 \series bold
6865 -
6866 \begin_inset ERT
6867 status Collapsed
6868
6869 \layout Standard
6870
6871 \backslash
6872 /
6873 \end_inset
6874
6875 -model-medium
6876 \begin_inset LatexCommand \index{-\/-model-medium}
6877
6878 \end_inset
6879
6880
6881 \series default
6882  Generate code for Medium model programs, see section Memory Models for
6883  more details.
6884  If this option is used all source files in the project have to be compiled
6885  with this option.
6886  It must also be used when invoking the linker.
6887 \layout List
6888 \labelwidthstring 00.00.0000
6889
6890
6891 \series bold
6892 -
6893 \begin_inset ERT
6894 status Collapsed
6895
6896 \layout Standard
6897
6898 \backslash
6899 /
6900 \end_inset
6901
6902 -model-large
6903 \begin_inset LatexCommand \index{-\/-model-large}
6904
6905 \end_inset
6906
6907
6908 \series default
6909  Generate code for Large model programs, see section Memory Models for more
6910  details.
6911  If this option is used all source files in the project have to be compiled
6912  with this option.
6913  It must also be used when invoking the linker.
6914 \layout List
6915 \labelwidthstring 00.00.0000
6916
6917
6918 \series bold
6919 -
6920 \begin_inset ERT
6921 status Collapsed
6922
6923 \layout Standard
6924
6925 \backslash
6926 /
6927 \end_inset
6928
6929 -xstack
6930 \begin_inset LatexCommand \index{-\/-xstack}
6931
6932 \end_inset
6933
6934
6935 \series default
6936  Uses a pseudo stack in the pdata
6937 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
6938
6939 \end_inset
6940
6941  area (usually the first 256 bytes in the external ram) for allocating variables
6942  and passing parameters.
6943  See section
6944 \begin_inset LatexCommand \ref{sub:External-Stack}
6945
6946 \end_inset
6947
6948 \SpecialChar ~
6949  External Stack for more details.
6950 \layout List
6951 \labelwidthstring 00.00.0000
6952
6953
6954 \series bold
6955 -
6956 \begin_inset ERT
6957 status Collapsed
6958
6959 \layout Standard
6960
6961 \backslash
6962 /
6963 \end_inset
6964
6965 -iram-size
6966 \series default
6967 \SpecialChar ~
6968 <Value>
6969 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
6970
6971 \end_inset
6972
6973  Causes the linker to check if the internal ram usage is within limits of
6974  the given value.
6975 \layout List
6976 \labelwidthstring 00.00.0000
6977
6978
6979 \series bold
6980 -
6981 \begin_inset ERT
6982 status Collapsed
6983
6984 \layout Standard
6985
6986 \backslash
6987 /
6988 \end_inset
6989
6990 -xram-size
6991 \series default
6992 \SpecialChar ~
6993 <Value>
6994 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
6995
6996 \end_inset
6997
6998  Causes the linker to check if the external ram usage is within limits of
6999  the given value.
7000 \layout List
7001 \labelwidthstring 00.00.0000
7002
7003
7004 \series bold
7005 -
7006 \begin_inset ERT
7007 status Collapsed
7008
7009 \layout Standard
7010
7011 \backslash
7012 /
7013 \end_inset
7014
7015 -code-size
7016 \series default
7017 \SpecialChar ~
7018 <Value>
7019 \begin_inset LatexCommand \index{-\/-code-size <Value>}
7020
7021 \end_inset
7022
7023  Causes the linker to check if the code memory usage is within limits of
7024  the given value.
7025 \layout List
7026 \labelwidthstring 00.00.0000
7027
7028
7029 \series bold
7030 -
7031 \begin_inset ERT
7032 status Collapsed
7033
7034 \layout Standard
7035
7036 \backslash
7037 /
7038 \end_inset
7039
7040 -stack-size
7041 \series default
7042 \SpecialChar ~
7043 <Value>
7044 \begin_inset LatexCommand \index{-\/-stack-size <Value>}
7045
7046 \end_inset
7047
7048  Causes the linker to check if there is at minimum <Value> bytes for stack.
7049 \layout List
7050 \labelwidthstring 00.00.0000
7051
7052
7053 \series bold
7054 -
7055 \begin_inset ERT
7056 status Collapsed
7057
7058 \layout Standard
7059
7060 \backslash
7061 /
7062 \end_inset
7063
7064 -pack-iram
7065 \series default
7066 \SpecialChar ~
7067
7068 \begin_inset LatexCommand \index{-\/-pack-iram}
7069
7070 \end_inset
7071
7072  Causes the linker to use unused register banks for data variables and pack
7073  data, idata and stack together.
7074  This is the default now.
7075 \layout List
7076 \added_space_bottom bigskip \labelwidthstring 00.00.0000
7077
7078
7079 \series bold
7080 -
7081 \begin_inset ERT
7082 status Collapsed
7083
7084 \layout Standard
7085
7086 \backslash
7087 /
7088 \end_inset
7089
7090 -no-pack-iram
7091 \series default
7092 \SpecialChar ~
7093
7094 \begin_inset LatexCommand \index{-\/-no-pack-iram}
7095
7096 \end_inset
7097
7098  Causes the linker to use old style for allocating memory areas.
7099 \layout Subsection
7100
7101 DS390 / DS400 Options
7102 \begin_inset LatexCommand \index{Options DS390}
7103
7104 \end_inset
7105
7106
7107 \begin_inset LatexCommand \index{DS390}
7108
7109 \end_inset
7110
7111
7112 \layout List
7113 \labelwidthstring 00.00.0000
7114
7115
7116 \series bold
7117 -
7118 \begin_inset ERT
7119 status Collapsed
7120
7121 \layout Standard
7122
7123 \backslash
7124 /
7125 \end_inset
7126
7127 -model-flat24
7128 \series default
7129
7130 \begin_inset LatexCommand \index{DS390!Options!-\/-model-flat24}
7131
7132 \end_inset
7133
7134
7135 \size large
7136 \emph on
7137
7138 \size default
7139 \emph default
7140 Generate 24-bit flat mode code.
7141  This is the one and only that the ds390 code generator supports right now
7142  and is default when using
7143 \emph on
7144 -mds390
7145 \emph default
7146 .
7147  See section Memory Models for more details.
7148 \layout List
7149 \labelwidthstring 00.00.0000
7150
7151
7152 \series bold
7153 -
7154 \begin_inset ERT
7155 status Collapsed
7156
7157 \layout Standard
7158
7159 \backslash
7160 /
7161 \end_inset
7162
7163 -protect-sp-update
7164 \begin_inset LatexCommand \index{DS390!Options!-\/-protect-sp-update}
7165
7166 \end_inset
7167
7168
7169 \series default
7170  disable interrupts during ESP:SP updates.
7171 \layout List
7172 \labelwidthstring 00.00.0000
7173
7174
7175 \series bold
7176 -
7177 \begin_inset ERT
7178 status Collapsed
7179
7180 \layout Standard
7181
7182 \backslash
7183 /
7184 \end_inset
7185
7186 -stack-10bit
7187 \series default
7188
7189 \begin_inset LatexCommand \index{DS390!Options!-\/-stack-10bit}
7190
7191 \end_inset
7192
7193  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
7194  This is the one and only that the ds390 code generator supports right now
7195  and is default when using
7196 \emph on
7197 -mds390
7198 \emph default
7199 .
7200  In this mode, the stack is located in the lower 1K of the internal RAM,
7201  which is mapped to 0x400000.
7202  Note that the support is incomplete, since it still uses a single byte
7203  as the stack pointer.
7204  This means that only the lower 256 bytes of the potential 1K stack space
7205  will actually be used.
7206  However, this does allow you to reclaim the precious 256 bytes of low RAM
7207  for use for the DATA and IDATA segments.
7208  The compiler will not generate any code to put the processor into 10 bit
7209  stack mode.
7210  It is important to ensure that the processor is in this mode before calling
7211  any re-entrant functions compiled with this option.
7212  In principle, this should work with the
7213 \emph on
7214 -
7215 \begin_inset ERT
7216 status Collapsed
7217
7218 \layout Standard
7219
7220 \backslash
7221 /
7222 \end_inset
7223
7224 -stack-auto
7225 \begin_inset LatexCommand \index{-\/-stack-auto}
7226
7227 \end_inset
7228
7229
7230 \emph default
7231  option, but that has not been tested.
7232  It is incompatible with the
7233 \emph on
7234 -
7235 \begin_inset ERT
7236 status Collapsed
7237
7238 \layout Standard
7239
7240 \backslash
7241 /
7242 \end_inset
7243
7244 -xstack
7245 \begin_inset LatexCommand \index{-\/-xstack}
7246
7247 \end_inset
7248
7249
7250 \emph default
7251  option.
7252  It also only makes sense if the processor is in 24 bit contiguous addressing
7253  mode (see the
7254 \emph on
7255 -
7256 \begin_inset ERT
7257 status Collapsed
7258
7259 \layout Standard
7260
7261 \backslash
7262 /
7263 \end_inset
7264
7265 -model-flat24 option
7266 \emph default
7267 ).
7268 \layout List
7269 \labelwidthstring 00.00.0000
7270
7271
7272 \series bold
7273 -
7274 \begin_inset ERT
7275 status Collapsed
7276
7277 \layout Standard
7278
7279 \backslash
7280 /
7281 \end_inset
7282
7283 -stack-probe
7284 \begin_inset LatexCommand \index{DS390!Options!-\/-stack-probe}
7285
7286 \end_inset
7287
7288
7289 \series default
7290  insert call to function __stack_probe at each function prologue.
7291 \layout List
7292 \labelwidthstring 00.00.0000
7293
7294
7295 \series bold
7296 -
7297 \begin_inset ERT
7298 status Collapsed
7299
7300 \layout Standard
7301
7302 \backslash
7303 /
7304 \end_inset
7305
7306 -tini-libid
7307 \begin_inset LatexCommand \index{DS390!Options!-\/-tini-libid}
7308
7309 \end_inset
7310
7311
7312 \series default
7313  <nnnn> LibraryID used in -mTININative.
7314
7315 \layout List
7316 \added_space_bottom bigskip \labelwidthstring 00.00.0000
7317
7318
7319 \series bold
7320 -
7321 \begin_inset ERT
7322 status Collapsed
7323
7324 \layout Standard
7325
7326 \backslash
7327 /
7328 \end_inset
7329
7330 -use-accelerator
7331 \begin_inset LatexCommand \index{DS390!Options!-\/-use-accelerator}
7332
7333 \end_inset
7334
7335
7336 \series default
7337  generate code for DS390 Arithmetic Accelerator.
7338
7339 \layout Subsection
7340
7341 Z80 Options
7342 \begin_inset LatexCommand \index{Options Z80}
7343
7344 \end_inset
7345
7346
7347 \begin_inset LatexCommand \index{Z80}
7348
7349 \end_inset
7350
7351
7352 \layout List
7353 \labelwidthstring 00.00.0000
7354
7355
7356 \series bold
7357 -
7358 \begin_inset ERT
7359 status Collapsed
7360
7361 \layout Standard
7362
7363 \backslash
7364 /
7365 \end_inset
7366
7367 -callee-saves-bc
7368 \series default
7369
7370 \begin_inset LatexCommand \index{Z80!Options!-\/-callee-saves-bc}
7371
7372 \end_inset
7373
7374
7375 \size large
7376 \emph on
7377
7378 \size default
7379 \emph default
7380 Force a called function to always save BC.
7381 \layout List
7382 \added_space_bottom bigskip \labelwidthstring 00.00.0000
7383
7384
7385 \series bold
7386 -
7387 \begin_inset ERT
7388 status Collapsed
7389
7390 \layout Standard
7391
7392 \backslash
7393 /
7394 \end_inset
7395
7396 -no-std-crt0
7397 \series default
7398
7399 \begin_inset LatexCommand \index{Z80!Options!-\/-no-std-crt0}
7400
7401 \end_inset
7402
7403  When linking, skip the standard crt0.o object file.
7404  You must provide your own crt0.o for your system when linking.
7405
7406 \layout Subsection
7407
7408 Optimization Options
7409 \begin_inset LatexCommand \index{Options optimization}
7410
7411 \end_inset
7412
7413
7414 \begin_inset LatexCommand \index{Optimization options}
7415
7416 \end_inset
7417
7418
7419 \layout List
7420 \labelwidthstring 00.00.0000
7421
7422
7423 \series bold
7424 -
7425 \begin_inset ERT
7426 status Collapsed
7427
7428 \layout Standard
7429
7430 \backslash
7431 /
7432 \end_inset
7433
7434 -nogcse
7435 \begin_inset LatexCommand \index{-\/-nogcse}
7436
7437 \end_inset
7438
7439
7440 \series default
7441  Will not do global subexpression elimination, this option may be used when
7442  the compiler creates undesirably large stack/data spaces to store compiler
7443  temporaries (
7444 \emph on
7445 s
7446 \emph default
7447 pill
7448 \emph on
7449 loc
7450 \emph default
7451 ations, sloc
7452 \begin_inset LatexCommand \index{sloc (spill location)}
7453
7454 \end_inset
7455
7456 ).
7457  A warning message will be generated when this happens and the compiler
7458  will indicate the number of extra bytes it allocated.
7459  It is recommended that this option NOT be used, #pragma\SpecialChar ~
7460 nogcse
7461 \begin_inset LatexCommand \index{\#pragma nogcse}
7462
7463 \end_inset
7464
7465  can be used to turn off global subexpression elimination
7466 \begin_inset LatexCommand \index{Subexpression elimination}
7467
7468 \end_inset
7469
7470  for a given function only.
7471 \layout List
7472 \labelwidthstring 00.00.0000
7473
7474
7475 \series bold
7476 -
7477 \begin_inset ERT
7478 status Collapsed
7479
7480 \layout Standard
7481
7482 \backslash
7483 /
7484 \end_inset
7485
7486 -noinvariant
7487 \begin_inset LatexCommand \index{-\/-noinvariant}
7488
7489 \end_inset
7490
7491
7492 \series default
7493  Will not do loop invariant optimizations, this may be turned off for reasons
7494  explained for the previous option.
7495  For more details of loop optimizations performed see Loop Invariants in
7496  section
7497 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
7498
7499 \end_inset
7500
7501 .
7502  It is recommended that this option NOT be used, #pragma\SpecialChar ~
7503 noinvariant
7504 \begin_inset LatexCommand \index{\#pragma noinvariant}
7505
7506 \end_inset
7507
7508  can be used to turn off invariant optimizations for a given function only.
7509 \layout List
7510 \labelwidthstring 00.00.0000
7511
7512
7513 \series bold
7514 -
7515 \begin_inset ERT
7516 status Collapsed
7517
7518 \layout Standard
7519
7520 \backslash
7521 /
7522 \end_inset
7523
7524 -noinduction
7525 \begin_inset LatexCommand \index{-\/-noinduction}
7526
7527 \end_inset
7528
7529
7530 \series default
7531  Will not do loop induction optimizations, see section strength reduction
7532  for more details.
7533  It is recommended that this option is NOT used, #pragma\SpecialChar ~
7534 noinduction
7535 \begin_inset LatexCommand \index{\#pragma noinduction}
7536
7537 \end_inset
7538
7539  can be used to turn off induction optimizations for a given function only.
7540 \layout List
7541 \labelwidthstring 00.00.0000
7542
7543
7544 \series bold
7545 -
7546 \begin_inset ERT
7547 status Collapsed
7548
7549 \layout Standard
7550
7551 \backslash
7552 /
7553 \end_inset
7554
7555 -nojtbound
7556 \begin_inset LatexCommand \index{-\/-nojtbound}
7557
7558 \end_inset
7559
7560
7561 \size large
7562 \bar under
7563
7564 \series default
7565 \size default
7566 \bar default
7567  Will not generate boundary condition check when switch statements
7568 \begin_inset LatexCommand \index{switch statement}
7569
7570 \end_inset
7571
7572  are implemented using jump-tables.
7573  See section
7574 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
7575
7576 \end_inset
7577
7578 \SpecialChar ~
7579 Switch Statements for more details.
7580  It is recommended that this option is NOT used, #pragma\SpecialChar ~
7581 nojtbound
7582 \begin_inset LatexCommand \index{\#pragma nojtbound}
7583
7584 \end_inset
7585
7586  can be used to turn off boundary checking for jump tables for a given function
7587  only.
7588 \layout List
7589 \labelwidthstring 00.00.0000
7590
7591
7592 \series bold
7593 -
7594 \begin_inset ERT
7595 status Collapsed
7596
7597 \layout Standard
7598
7599 \backslash
7600 /
7601 \end_inset
7602
7603 -noloopreverse
7604 \begin_inset LatexCommand \index{-\/-noloopreverse}
7605
7606 \end_inset
7607
7608
7609 \series default
7610 \size large
7611
7612 \size default
7613 Will not do loop reversal
7614 \begin_inset LatexCommand \index{Loop reversing}
7615
7616 \end_inset
7617
7618 optimization.
7619 \layout List
7620 \labelwidthstring 00.00.0000
7621
7622 -
7623 \begin_inset ERT
7624 status Collapsed
7625
7626 \layout Standard
7627
7628 \backslash
7629 /
7630 \end_inset
7631
7632 -
7633 \series bold
7634 nolabelopt
7635 \series default
7636
7637 \begin_inset LatexCommand \index{-\/-nolabelopt }
7638
7639 \end_inset
7640
7641 Will not optimize labels (makes the dumpfiles more readable).
7642 \layout List
7643 \labelwidthstring 00.00.0000
7644
7645
7646 \series bold
7647 -
7648 \begin_inset ERT
7649 status Collapsed
7650
7651 \layout Standard
7652
7653 \backslash
7654 /
7655 \end_inset
7656
7657 -no-xinit-opt
7658 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
7659
7660 \end_inset
7661
7662
7663 \series default
7664  Will not memcpy initialized data from code space into xdata space.
7665  This saves a few bytes in code space if you don't have initialized data
7666 \begin_inset LatexCommand \index{Variable initialization}
7667
7668 \end_inset
7669
7670 .
7671 \layout List
7672 \labelwidthstring 00.00.0000
7673
7674
7675 \series bold
7676 -
7677 \begin_inset ERT
7678 status Collapsed
7679
7680 \layout Standard
7681
7682 \backslash
7683 /
7684 \end_inset
7685
7686 -nooverlay
7687 \begin_inset LatexCommand \index{-\/-nooverlay}
7688
7689 \end_inset
7690
7691
7692 \series default
7693   The compiler will not overlay parameters and local variables of any function,
7694  see section Parameters and local variables for more details.
7695 \layout List
7696 \labelwidthstring 00.00.0000
7697
7698
7699 \series bold
7700 -
7701 \begin_inset ERT
7702 status Collapsed
7703
7704 \layout Standard
7705
7706 \backslash
7707 /
7708 \end_inset
7709
7710 -no-peep
7711 \begin_inset LatexCommand \index{-\/-no-peep}
7712
7713 \end_inset
7714
7715
7716 \series default
7717  Disable peep-hole optimization with built-in rules.
7718 \layout List
7719 \labelwidthstring 00.00.0000
7720
7721
7722 \series bold
7723 -
7724 \begin_inset ERT
7725 status Collapsed
7726
7727 \layout Standard
7728
7729 \backslash
7730 /
7731 \end_inset
7732
7733 -peep-file
7734 \series default
7735
7736 \begin_inset LatexCommand \index{-\/-peep-file}
7737
7738 \end_inset
7739
7740 \SpecialChar ~
7741 <filename> This option can be used to use additional rules to be used by
7742  the peep hole optimizer.
7743  See section
7744 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
7745
7746 \end_inset
7747
7748 \SpecialChar ~
7749 Peep Hole optimizations for details on how to write these rules.
7750 \layout List
7751 \labelwidthstring 00.00.0000
7752
7753
7754 \series bold
7755 -
7756 \begin_inset ERT
7757 status Collapsed
7758
7759 \layout Standard
7760
7761 \backslash
7762 /
7763 \end_inset
7764
7765 -peep-asm
7766 \begin_inset LatexCommand \index{-\/-peep-asm}
7767
7768 \end_inset
7769
7770
7771 \series default
7772  Pass the inline assembler code through the peep hole optimizer.
7773  This can cause unexpected changes to inline assembler code, please go through
7774  the peephole optimizer
7775 \begin_inset LatexCommand \index{Peephole optimizer}
7776
7777 \end_inset
7778
7779  rules defined in the source file tree '<target>/peeph.def' before using
7780  this option.
7781 \layout List
7782 \labelwidthstring 00.00.0000
7783
7784
7785 \series bold
7786 -
7787 \begin_inset ERT
7788 status Collapsed
7789
7790 \layout Standard
7791
7792 \backslash
7793 /
7794 \end_inset
7795
7796 -opt-code-speed
7797 \begin_inset LatexCommand \index{-\/-opt-code-speed}
7798
7799 \end_inset
7800
7801
7802 \series default
7803  The compiler will optimize code generation towards fast code, possibly
7804  at the expense of code size.
7805 \layout List
7806 \added_space_bottom bigskip \labelwidthstring 00.00.0000
7807
7808
7809 \series bold
7810 -
7811 \begin_inset ERT
7812 status Collapsed
7813
7814 \layout Standard
7815
7816 \backslash
7817 /
7818 \end_inset
7819
7820 -opt-code-size
7821 \begin_inset LatexCommand \index{-\/-opt-code-size}
7822
7823 \end_inset
7824
7825
7826 \series default
7827  The compiler will optimize code generation towards compact code, possibly
7828  at the expense of code speed.
7829 \layout Subsection
7830
7831 Other Options
7832 \begin_inset LatexCommand \index{Options other}
7833
7834 \end_inset
7835
7836
7837 \layout List
7838 \labelwidthstring 00.00.0000
7839
7840
7841 \series bold
7842 -c\SpecialChar ~
7843 -
7844 \begin_inset ERT
7845 status Collapsed
7846
7847 \layout Standard
7848
7849 \backslash
7850 /
7851 \end_inset
7852
7853 -compile-only
7854 \begin_inset LatexCommand \index{-\/-compile-only}
7855
7856 \end_inset
7857
7858
7859 \begin_inset LatexCommand \index{-c -\/-compile-only}
7860
7861 \end_inset
7862
7863
7864 \series default
7865  will compile and assemble the source, but will not call the linkage editor.
7866 \layout List
7867 \labelwidthstring 00.00.0000
7868
7869
7870 \series bold
7871 -
7872 \series default
7873
7874 \begin_inset ERT
7875 status Collapsed
7876
7877 \layout Standard
7878
7879 \backslash
7880 /
7881 \end_inset
7882
7883
7884 \series bold
7885 -c1mode
7886 \begin_inset LatexCommand \index{-\/-c1mode}
7887
7888 \end_inset
7889
7890
7891 \series default
7892  reads the preprocessed source from standard input and compiles it.
7893  The file name for the assembler output must be specified using the -o option.
7894 \layout List
7895 \labelwidthstring 00.00.0000
7896
7897
7898 \series bold
7899 -E
7900 \begin_inset LatexCommand \index{-E}
7901
7902 \end_inset
7903
7904
7905 \series default
7906  Run only the C preprocessor.
7907  Preprocess all the C source files specified and output the results to standard
7908  output.
7909 \layout List
7910 \labelwidthstring 00.00.0000
7911
7912
7913 \series bold
7914 -o\SpecialChar ~
7915 <path/file>
7916 \begin_inset LatexCommand \index{-o <path/file>}
7917
7918 \end_inset
7919
7920
7921 \series default
7922 The output path resp.
7923  file where everything will be placed.
7924  If the parameter is a path, it must have a trailing slash (or backslash
7925  for the Windows binaries) to be recognized as a path.
7926
7927 \layout List
7928 \labelwidthstring 00.00.0000
7929
7930
7931 \series bold
7932 -
7933 \begin_inset ERT
7934 status Collapsed
7935
7936 \layout Standard
7937
7938 \backslash
7939 /
7940 \end_inset
7941
7942 -stack-auto
7943 \begin_inset LatexCommand \index{-\/-stack-auto}
7944
7945 \end_inset
7946
7947
7948 \series default
7949 \size large
7950 \emph on
7951
7952 \size default
7953 \emph default
7954 All functions in the source file will be compiled as
7955 \emph on
7956 reentrant
7957 \emph default
7958
7959 \begin_inset LatexCommand \index{reentrant}
7960
7961 \end_inset
7962
7963 , i.e.
7964  the parameters and local variables will be allocated on the stack
7965 \begin_inset LatexCommand \index{stack}
7966
7967 \end_inset
7968
7969 .
7970  See section
7971 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
7972
7973 \end_inset
7974
7975  Parameters and Local Variables for more details.
7976  If this option is used all source files in the project should be compiled
7977  with this option.
7978  It automatically implies --int-long-reent and --float-reent.
7979
7980 \layout List
7981 \labelwidthstring 00.00.0000
7982
7983
7984 \series bold
7985 -
7986 \begin_inset ERT
7987 status Collapsed
7988
7989 \layout Standard
7990
7991 \backslash
7992 /
7993 \end_inset
7994
7995 -callee-saves
7996 \begin_inset LatexCommand \index{-\/-callee-saves}
7997
7998 \end_inset
7999
8000  function1[,function2][,function3]....
8001
8002 \series default
8003  The compiler by default uses a caller saves convention for register saving
8004  across function calls, however this can cause unnecessary register pushing
8005  & popping when calling small functions from larger functions.
8006  This option can be used to switch the register saving convention for the
8007  function names specified.
8008  The compiler will not save registers when calling these functions, no extra
8009  code will be generated at the entry & exit (function prologue
8010 \series bold
8011
8012 \begin_inset LatexCommand \index{function prologue}
8013
8014 \end_inset
8015
8016
8017 \series default
8018  & epilogue
8019 \series bold
8020
8021 \begin_inset LatexCommand \index{function epilogue}
8022
8023 \end_inset
8024
8025
8026 \series default
8027 ) for these functions to save & restore the registers used by these functions,
8028  this can SUBSTANTIALLY reduce code & improve run time performance of the
8029  generated code.
8030  In the future the compiler (with inter procedural analysis) will be able
8031  to determine the appropriate scheme to use for each function call.
8032  DO NOT use this option for built-in functions such as _mulint..., if this
8033  option is used for a library function the appropriate library function
8034  needs to be recompiled with the same option.
8035  If the project consists of multiple source files then all the source file
8036  should be compiled with the same -
8037 \begin_inset ERT
8038 status Collapsed
8039
8040 \layout Standard
8041
8042 \backslash
8043 /
8044 \end_inset
8045
8046 -callee-saves option string.
8047  Also see #pragma\SpecialChar ~
8048 callee_saves
8049 \begin_inset LatexCommand \index{\#pragma callee\_saves}
8050
8051 \end_inset
8052
8053 .
8054 \layout List
8055 \labelwidthstring 00.00.0000
8056
8057
8058 \series bold
8059 -
8060 \begin_inset ERT
8061 status Collapsed
8062
8063 \layout Standard
8064
8065 \backslash
8066 /
8067 \end_inset
8068
8069 -debug
8070 \begin_inset LatexCommand \index{-\/-debug}
8071
8072 \end_inset
8073
8074
8075 \bar under
8076
8077 \series default
8078 \bar default
8079 When this option is used the compiler will generate debug information.
8080  The debug information collected in a file with .cdb extension can be used
8081  with the SDCDB.
8082  For more information see documentation for SDCDB.
8083  Another file with no extension contains debug information in AOMF or AOMF51
8084 \begin_inset LatexCommand \index{AOMF, AOMF51}
8085
8086 \end_inset
8087
8088  format which is commonly used by third party tools.
8089 \layout List
8090 \labelwidthstring 00.00.0000
8091
8092
8093 \series bold
8094 -S
8095 \begin_inset LatexCommand \index{-S}
8096
8097 \end_inset
8098
8099
8100 \size large
8101 \bar under
8102
8103 \series default
8104 \size default
8105 \bar default
8106 Stop after the stage of compilation proper; do not assemble.
8107  The output is an assembler code file for the input file specified.
8108 \layout List
8109 \labelwidthstring 00.00.0000
8110
8111
8112 \series bold
8113 -
8114 \begin_inset ERT
8115 status Collapsed
8116
8117 \layout Standard
8118
8119 \backslash
8120 /
8121 \end_inset
8122
8123 -int-long-reent
8124 \begin_inset LatexCommand \index{-\/-int-long-reent}
8125
8126 \end_inset
8127
8128
8129 \series default
8130  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
8131  Note by default these libraries are compiled as non-reentrant.
8132  See section Installation for more details.
8133 \layout List
8134 \labelwidthstring 00.00.0000
8135
8136
8137 \series bold
8138 -
8139 \begin_inset ERT
8140 status Collapsed
8141
8142 \layout Standard
8143
8144 \backslash
8145 /
8146 \end_inset
8147
8148 -cyclomatic
8149 \begin_inset LatexCommand \index{-\/-cyclomatic}
8150
8151 \end_inset
8152
8153
8154 \bar under
8155
8156 \series default
8157 \bar default
8158 This option will cause the compiler to generate an information message for
8159  each function in the source file.
8160  The message contains some
8161 \emph on
8162 important
8163 \emph default
8164  information about the function.
8165  The number of edges and nodes the compiler detected in the control flow
8166  graph of the function, and most importantly the
8167 \emph on
8168 cyclomatic complexity
8169 \begin_inset LatexCommand \index{Cyclomatic complexity}
8170
8171 \end_inset
8172
8173
8174 \emph default
8175  see section on Cyclomatic Complexity for more details.
8176 \layout List
8177 \labelwidthstring 00.00.0000
8178
8179
8180 \series bold
8181 -
8182 \begin_inset ERT
8183 status Collapsed
8184
8185 \layout Standard
8186
8187 \backslash
8188 /
8189 \end_inset
8190
8191 -float-reent
8192 \begin_inset LatexCommand \index{-\/-float-reent}
8193
8194 \end_inset
8195
8196
8197 \series default
8198  Floating point library is compiled as reentrant
8199 \begin_inset LatexCommand \index{reentrant}
8200
8201 \end_inset
8202
8203 .
8204  See section Installation for more details.
8205 \layout List
8206 \labelwidthstring 00.00.0000
8207
8208
8209 \series bold
8210 -
8211 \begin_inset ERT
8212 status Collapsed
8213
8214 \layout Standard
8215
8216 \backslash
8217 /
8218 \end_inset
8219
8220 -main-return
8221 \begin_inset LatexCommand \index{-\/-main-return}
8222
8223 \end_inset
8224
8225
8226 \series default
8227  This option can be used if the code generated is called by a monitor program
8228  or if the main routine includes an endless loop.
8229  This option results in slightly smaller code and saves two bytes of stack
8230  space.
8231  The return from the 'main'
8232 \begin_inset LatexCommand \index{main return}
8233
8234 \end_inset
8235
8236  function will return to the function calling main.
8237  The default setting is to lock up i.e.
8238  generate a '
8239 \family typewriter
8240 sjmp .
8241 \family default
8242 '.
8243 \layout List
8244 \labelwidthstring 00.00.0000
8245
8246
8247 \series bold
8248 -
8249 \begin_inset ERT
8250 status Collapsed
8251
8252 \layout Standard
8253
8254 \backslash
8255 /
8256 \end_inset
8257
8258 -nostdinc
8259 \begin_inset LatexCommand \index{-\/-nostdinc}
8260
8261 \end_inset
8262
8263
8264 \series default
8265  This will prevent the compiler from passing on the default include path
8266  to the preprocessor.
8267 \layout List
8268 \labelwidthstring 00.00.0000
8269
8270
8271 \series bold
8272 -
8273 \begin_inset ERT
8274 status Collapsed
8275
8276 \layout Standard
8277
8278 \backslash
8279 /
8280 \end_inset
8281
8282 -nostdlib
8283 \begin_inset LatexCommand \index{-\/-nostdlib}
8284
8285 \end_inset
8286
8287
8288 \series default
8289  This will prevent the compiler from passing on the default library
8290 \begin_inset LatexCommand \index{Libraries}
8291
8292 \end_inset
8293
8294  path to the linker.
8295 \layout List
8296 \labelwidthstring 00.00.0000
8297
8298
8299 \series bold
8300 -
8301 \begin_inset ERT
8302 status Collapsed
8303
8304 \layout Standard
8305
8306 \backslash
8307 /
8308 \end_inset
8309
8310 -verbose
8311 \begin_inset LatexCommand \index{-\/-verbose}
8312
8313 \end_inset
8314
8315
8316 \series default
8317  Shows the various actions the compiler is performing.
8318 \layout List
8319 \labelwidthstring 00.00.0000
8320
8321
8322 \series bold
8323 -V
8324 \begin_inset LatexCommand \index{-V}
8325
8326 \end_inset
8327
8328
8329 \series default
8330  Shows the actual commands the compiler is executing.
8331 \layout List
8332 \labelwidthstring 00.00.0000
8333
8334
8335 \series bold
8336 -
8337 \begin_inset ERT
8338 status Collapsed
8339
8340 \layout Standard
8341
8342 \backslash
8343 /
8344 \end_inset
8345
8346 -no-c-code-in-asm
8347 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
8348
8349 \end_inset
8350
8351
8352 \series default
8353  Hides your ugly and inefficient c-code from the asm file, so you can always
8354  blame the compiler :)
8355 \layout List
8356 \labelwidthstring 00.00.0000
8357
8358
8359 \series bold
8360 -
8361 \begin_inset ERT
8362 status Collapsed
8363
8364 \layout Standard
8365
8366 \backslash
8367 /
8368 \end_inset
8369
8370 -no-peep-comments
8371 \begin_inset LatexCommand \index{-\/-no-peep-comments}
8372
8373 \end_inset
8374
8375
8376 \series default
8377  Will not include peep-hole comments in the generated files.
8378 \layout List
8379 \labelwidthstring 00.00.0000
8380
8381
8382 \series bold
8383 -
8384 \begin_inset ERT
8385 status Collapsed
8386
8387 \layout Standard
8388
8389 \backslash
8390 /
8391 \end_inset
8392
8393 -i-code-in-asm
8394 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
8395
8396 \end_inset
8397
8398
8399 \series default
8400  Include i-codes in the asm file.
8401  Sounds like noise but is most helpful for debugging the compiler itself.
8402 \layout List
8403 \labelwidthstring 00.00.0000
8404
8405
8406 \series bold
8407 -
8408 \begin_inset ERT
8409 status Collapsed
8410
8411 \layout Standard
8412
8413 \backslash
8414 /
8415 \end_inset
8416
8417 -less-pedantic
8418 \begin_inset LatexCommand \index{-\/-less-pedantic}
8419
8420 \end_inset
8421
8422
8423 \series default
8424  Disable some of the more pedantic warnings
8425 \begin_inset LatexCommand \index{Warnings}
8426
8427 \end_inset
8428
8429  (jwk burps: please be more specific here, please!).
8430 \layout List
8431 \labelwidthstring 00.00.0000
8432
8433
8434 \series bold
8435 -
8436 \begin_inset ERT
8437 status Collapsed
8438
8439 \layout Standard
8440
8441 \backslash
8442 /
8443 \end_inset
8444
8445 -disable-warning\SpecialChar ~
8446 <nnnn>
8447 \begin_inset LatexCommand \index{-\/-disable-warning}
8448
8449 \end_inset
8450
8451
8452 \series default
8453  Disable specific warning with number <nnnn>.
8454 \layout List
8455 \labelwidthstring 00.00.0000
8456
8457
8458 \series bold
8459 -
8460 \begin_inset ERT
8461 status Collapsed
8462
8463 \layout Standard
8464
8465 \backslash
8466 /
8467 \end_inset
8468
8469 -print-search-dirs
8470 \begin_inset LatexCommand \index{-\/-print-search-dirs}
8471
8472 \end_inset
8473
8474
8475 \series default
8476  Display the directories in the compiler's search path
8477 \layout List
8478 \labelwidthstring 00.00.0000
8479
8480
8481 \series bold
8482 -
8483 \begin_inset ERT
8484 status Collapsed
8485
8486 \layout Standard
8487
8488 \backslash
8489 /
8490 \end_inset
8491
8492 -vc
8493 \begin_inset LatexCommand \index{-\/-vc}
8494
8495 \end_inset
8496
8497
8498 \series default
8499  Display errors and warnings using MSVC style, so you can use SDCC with
8500  the visual studio IDE
8501 \begin_inset LatexCommand \index{IDE}
8502
8503 \end_inset
8504
8505 .
8506  With SDCC both offering a GCC-like (the default) and a MSVC-like
8507 \begin_inset LatexCommand \index{MSVC output style}
8508
8509 \end_inset
8510
8511  output style, integration into most programming editors should be straightforwa
8512 rd.
8513 \layout List
8514 \labelwidthstring 00.00.0000
8515
8516
8517 \series bold
8518 -
8519 \begin_inset ERT
8520 status Collapsed
8521
8522 \layout Standard
8523
8524 \backslash
8525 /
8526 \end_inset
8527
8528 -use-stdout
8529 \begin_inset LatexCommand \index{-\/-use-stdout}
8530
8531 \end_inset
8532
8533
8534 \series default
8535  Send errors and warnings to stdout instead of stderr.
8536 \layout List
8537 \labelwidthstring 00.00.0000
8538
8539
8540 \series bold
8541 -Wa\SpecialChar ~
8542 asmOption[,asmOption]
8543 \series default
8544
8545 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
8546
8547 \end_inset
8548
8549 ...
8550  Pass the asmOption to the assembler
8551 \begin_inset LatexCommand \index{Options assembler}
8552
8553 \end_inset
8554
8555
8556 \begin_inset LatexCommand \index{Assembler options}
8557
8558 \end_inset
8559
8560 .
8561  See file sdcc/as/doc/asxhtm.html for assembler options.cd
8562 \layout List
8563 \labelwidthstring 00.00.0000
8564
8565
8566 \series bold
8567 -
8568 \begin_inset ERT
8569 status Collapsed
8570
8571 \layout Standard
8572
8573 \backslash
8574 /
8575 \end_inset
8576
8577 -std-sdcc89
8578 \begin_inset LatexCommand \index{-\/-std-sdcc89}
8579
8580 \end_inset
8581
8582
8583 \series default
8584  Generally follow the C89 standard, but allow SDCC features that conflict
8585  with the standard (default).
8586 \layout List
8587 \labelwidthstring 00.00.0000
8588
8589
8590 \series bold
8591 -
8592 \begin_inset ERT
8593 status Collapsed
8594
8595 \layout Standard
8596
8597 \backslash
8598 /
8599 \end_inset
8600
8601 -std-c89
8602 \begin_inset LatexCommand \index{-\/-std-c89}
8603
8604 \end_inset
8605
8606
8607 \series default
8608  Follow the C89 standard and disable SDCC features that conflict with the
8609  standard.
8610 \layout List
8611 \labelwidthstring 00.00.0000
8612
8613
8614 \series bold
8615 -
8616 \begin_inset ERT
8617 status Collapsed
8618
8619 \layout Standard
8620
8621 \backslash
8622 /
8623 \end_inset
8624
8625 -std-sdcc99
8626 \begin_inset LatexCommand \index{-\/-std-sdcc99}
8627
8628 \end_inset
8629
8630
8631 \series default
8632  Generally follow the C99 standard, but allow SDCC features that conflict
8633  with the standard (incomplete support).
8634 \layout List
8635 \labelwidthstring 00.00.0000
8636
8637
8638 \series bold
8639 -
8640 \begin_inset ERT
8641 status Collapsed
8642
8643 \layout Standard
8644
8645 \backslash
8646 /
8647 \end_inset
8648
8649 -std-c99
8650 \begin_inset LatexCommand \index{-\/-std-sdcc99}
8651
8652 \end_inset
8653
8654
8655 \series default
8656  Follow the C99 standard and disable SDCC features that conflict with the
8657  standard (incomplete support).
8658 \layout List
8659 \labelwidthstring 00.00.0000
8660
8661
8662 \series bold
8663 -
8664 \begin_inset ERT
8665 status Collapsed
8666
8667 \layout Standard
8668
8669 \backslash
8670 /
8671 \end_inset
8672
8673 -codeseg
8674 \series default
8675
8676 \begin_inset LatexCommand \index{-\/-codeseg <Value>}
8677
8678 \end_inset
8679
8680 \SpecialChar ~
8681 <Name> The name to be used for the code
8682 \begin_inset LatexCommand \index{code}
8683
8684 \end_inset
8685
8686  segment, default CSEG.
8687  This is useful if you need to tell the compiler to put the code in a special
8688  segment so you can later on tell the linker to put this segment in a special
8689  place in memory.
8690  Can be used for instance when using bank switching to put the code in a
8691  bank.
8692 \layout List
8693 \labelwidthstring 00.00.0000
8694
8695
8696 \series bold
8697 -
8698 \begin_inset ERT
8699 status Collapsed
8700
8701 \layout Standard
8702
8703 \backslash
8704 /
8705 \end_inset
8706
8707 -constseg
8708 \series default
8709
8710 \begin_inset LatexCommand \index{-\/-constseg <Value>}
8711
8712 \end_inset
8713
8714 \SpecialChar ~
8715 <Name> The name to be used for the const
8716 \begin_inset LatexCommand \index{code}
8717
8718 \end_inset
8719
8720  segment, default CONST.
8721  This is useful if you need to tell the compiler to put the const data in
8722  a special segment so you can later on tell the linker to put this segment
8723  in a special place in memory.
8724  Can be used for instance when using bank switching to put the const data
8725  in a bank.
8726 \layout List
8727 \added_space_bottom bigskip \labelwidthstring 00.00.0000
8728
8729
8730 \series bold
8731 more-pedantic
8732 \series default
8733  Actually this is
8734 \series bold
8735 \emph on
8736 not
8737 \series default
8738 \emph default
8739  a SDCC compiler option but if you want
8740 \emph on
8741 more
8742 \emph default
8743  warnings you can use a separate tool dedicated to syntax checking like
8744  splint
8745 \begin_inset LatexCommand \label{lyx:more-pedantic-SPLINT}
8746
8747 \end_inset
8748
8749
8750 \begin_inset LatexCommand \index{lint (syntax checking tool)}
8751
8752 \end_inset
8753
8754
8755 \begin_inset LatexCommand \url{http://www.splint.org}
8756
8757 \end_inset
8758
8759 .
8760  To make your source files parseable by splint you will have to include
8761
8762 \family sans
8763 lint.h
8764 \family default
8765
8766 \begin_inset LatexCommand \index{splint (syntax checking tool)}
8767
8768 \end_inset
8769
8770  in your source file and add brackets around extended keywords (like
8771 \family sans
8772
8773 \begin_inset Quotes sld
8774 \end_inset
8775
8776 __at\SpecialChar ~
8777
8778 \series bold
8779 (
8780 \series default
8781 0xab
8782 \series bold
8783 )
8784 \series default
8785
8786 \begin_inset Quotes srd
8787 \end_inset
8788
8789
8790 \family default
8791  and
8792 \family sans
8793
8794 \begin_inset Quotes sld
8795 \end_inset
8796
8797 __interrupt\SpecialChar ~
8798 (2)
8799 \begin_inset Quotes srd
8800 \end_inset
8801
8802
8803 \family default
8804 ).
8805
8806 \newline
8807 Splint has an excellent on line manual at
8808 \begin_inset LatexCommand \url{http://www.splint.org/manual/}
8809
8810 \end_inset
8811
8812  and it's capabilities go beyond pure syntax checking.
8813  You'll need to tell splint the location of SDCC's include files so a typical
8814  command line could look like this:
8815 \newline
8816
8817 \family sans
8818 splint\SpecialChar ~
8819 -I\SpecialChar ~
8820 /usr/local/share/sdcc/include/mcs51/\SpecialChar ~
8821 \SpecialChar ~
8822 myprogram.c
8823 \layout Subsection
8824
8825 Intermediate Dump Options
8826 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
8827
8828 \end_inset
8829
8830
8831 \begin_inset LatexCommand \index{Options intermediate dump}
8832
8833 \end_inset
8834
8835
8836 \begin_inset LatexCommand \index{Intermediate dump options}
8837
8838 \end_inset
8839
8840
8841 \layout Standard
8842
8843 The following options are provided for the purpose of retargetting and debugging
8844  the compiler.
8845  They provide a means to dump the intermediate code (iCode
8846 \begin_inset LatexCommand \index{iCode}
8847
8848 \end_inset
8849
8850 ) generated by the compiler in human readable form at various stages of
8851  the compilation process.
8852  More on iCodes see chapter
8853 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
8854
8855 \end_inset
8856
8857
8858 \begin_inset Quotes srd
8859 \end_inset
8860
8861 The anatomy of the compiler
8862 \begin_inset Quotes srd
8863 \end_inset
8864
8865 .
8866 \layout List
8867 \labelwidthstring 00.00.0000
8868
8869
8870 \series bold
8871 -
8872 \begin_inset ERT
8873 status Collapsed
8874
8875 \layout Standard
8876
8877 \backslash
8878 /
8879 \end_inset
8880
8881 -dumpraw
8882 \begin_inset LatexCommand \index{-\/-dumpraw}
8883
8884 \end_inset
8885
8886
8887 \series default
8888  This option will cause the compiler to dump the intermediate code into
8889  a file of named
8890 \emph on
8891 <source filename>.dumpraw
8892 \emph default
8893  just after the intermediate code has been generated for a function, i.e.
8894  before any optimizations are done.
8895  The basic blocks
8896 \begin_inset LatexCommand \index{Basic blocks}
8897
8898 \end_inset
8899
8900  at this stage ordered in the depth first number, so they may not be in
8901  sequence of execution.
8902 \layout List
8903 \labelwidthstring 00.00.0000
8904
8905
8906 \series bold
8907 -
8908 \begin_inset ERT
8909 status Collapsed
8910
8911 \layout Standard
8912
8913 \backslash
8914 /
8915 \end_inset
8916
8917 -dumpgcse
8918 \begin_inset LatexCommand \index{-\/-dumpgcse}
8919
8920 \end_inset
8921
8922
8923 \series default
8924  Will create a dump of iCode's, after global subexpression elimination
8925 \begin_inset LatexCommand \index{Global subexpression elimination}
8926
8927 \end_inset
8928
8929 , into a file named
8930 \emph on
8931 <source filename>.dumpgcse.
8932 \layout List
8933 \labelwidthstring 00.00.0000
8934
8935
8936 \series bold
8937 -
8938 \begin_inset ERT
8939 status Collapsed
8940
8941 \layout Standard
8942
8943 \backslash
8944 /
8945 \end_inset
8946
8947 -dumpdeadcode
8948 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
8949
8950 \end_inset
8951
8952
8953 \series default
8954  Will create a dump of iCode's, after deadcode elimination
8955 \begin_inset LatexCommand \index{Dead-code elimination}
8956
8957 \end_inset
8958
8959 , into a file named
8960 \emph on
8961 <source filename>.dumpdeadcode.
8962 \layout List
8963 \labelwidthstring 00.00.0000
8964
8965
8966 \series bold
8967 -
8968 \begin_inset ERT
8969 status Collapsed
8970
8971 \layout Standard
8972
8973 \backslash
8974 /
8975 \end_inset
8976
8977 -dumploop
8978 \begin_inset LatexCommand \index{-\/-dumploop}
8979
8980 \end_inset
8981
8982
8983 \series default
8984 \size large
8985
8986 \size default
8987 Will create a dump of iCode's, after loop optimizations
8988 \begin_inset LatexCommand \index{Loop optimization}
8989
8990 \end_inset
8991
8992 , into a file named
8993 \emph on
8994 <source filename>.dumploop.
8995 \layout List
8996 \labelwidthstring 00.00.0000
8997
8998
8999 \series bold
9000 -
9001 \begin_inset ERT
9002 status Collapsed
9003
9004 \layout Standard
9005
9006 \backslash
9007 /
9008 \end_inset
9009
9010 -dumprange
9011 \begin_inset LatexCommand \index{-\/-dumprange}
9012
9013 \end_inset
9014
9015
9016 \series default
9017 \size large
9018
9019 \size default
9020 Will create a dump of iCode's, after live range analysis
9021 \begin_inset LatexCommand \index{Live range analysis}
9022
9023 \end_inset
9024
9025 , into a file named
9026 \emph on
9027 <source filename>.dumprange.
9028 \layout List
9029 \labelwidthstring 00.00.0000
9030
9031
9032 \series bold
9033 -
9034 \begin_inset ERT
9035 status Collapsed
9036
9037 \layout Standard
9038
9039 \backslash
9040 /
9041 \end_inset
9042
9043 -dumlrange
9044 \begin_inset LatexCommand \index{-\/-dumlrange}
9045
9046 \end_inset
9047
9048
9049 \series default
9050  Will dump the life ranges
9051 \begin_inset LatexCommand \index{Live range analysis}
9052
9053 \end_inset
9054
9055  for all symbols.
9056 \layout List
9057 \labelwidthstring 00.00.0000
9058
9059
9060 \series bold
9061 -
9062 \begin_inset ERT
9063 status Collapsed
9064
9065 \layout Standard
9066
9067 \backslash
9068 /
9069 \end_inset
9070
9071 -dumpregassign
9072 \begin_inset LatexCommand \index{-\/-dumpregassign}
9073
9074 \end_inset
9075
9076
9077 \bar under
9078
9079 \series default
9080 \bar default
9081 Will create a dump of iCode's, after register assignment
9082 \begin_inset LatexCommand \index{Register assignment}
9083
9084 \end_inset
9085
9086 , into a file named
9087 \emph on
9088 <source filename>.dumprassgn.
9089 \layout List
9090 \labelwidthstring 00.00.0000
9091
9092
9093 \series bold
9094 -
9095 \begin_inset ERT
9096 status Collapsed
9097
9098 \layout Standard
9099
9100 \backslash
9101 /
9102 \end_inset
9103
9104 -dumplrange
9105 \begin_inset LatexCommand \index{-\/-dumplrange}
9106
9107 \end_inset
9108
9109
9110 \series default
9111  Will create a dump of the live ranges of iTemp's
9112 \layout List
9113 \added_space_bottom bigskip \labelwidthstring 00.00.0000
9114
9115
9116 \series bold
9117 -
9118 \begin_inset ERT
9119 status Collapsed
9120
9121 \layout Standard
9122
9123 \backslash
9124 /
9125 \end_inset
9126
9127 -dumpall
9128 \begin_inset LatexCommand \index{-\/-dumpall}
9129
9130 \end_inset
9131
9132
9133 \size large
9134 \bar under
9135
9136 \series default
9137 \size default
9138 \bar default
9139 Will cause all the above mentioned dumps to be created.
9140 \layout Subsection
9141
9142 Redirecting output on Windows Shells
9143 \layout Standard
9144 \added_space_bottom bigskip
9145 By default SDCC writes it's error messages to
9146 \begin_inset Quotes sld
9147 \end_inset
9148
9149 standard error
9150 \begin_inset Quotes srd
9151 \end_inset
9152
9153 .
9154  To force all messages to
9155 \begin_inset Quotes sld
9156 \end_inset
9157
9158 standard output
9159 \begin_inset Quotes srd
9160 \end_inset
9161
9162  use
9163 \series bold
9164 -
9165 \series default
9166 \emph on
9167
9168 \begin_inset ERT
9169 status Collapsed
9170
9171 \layout Standard
9172
9173 \backslash
9174 /
9175 \end_inset
9176
9177
9178 \series bold
9179 \emph default
9180 -
9181 \series default
9182 use-stdout
9183 \begin_inset LatexCommand \index{-\/-use-stdout}
9184
9185 \end_inset
9186
9187 .
9188  Additionally, if you happen to have visual studio installed in your windows
9189  machine, you can use it to compile your sources using a custom build and
9190  the SDCC -
9191 \emph on
9192
9193 \begin_inset ERT
9194 status Collapsed
9195
9196 \layout Standard
9197
9198 \backslash
9199 /
9200 \end_inset
9201
9202
9203 \emph default
9204 -vc
9205 \begin_inset LatexCommand \index{-\/-vc}
9206
9207 \end_inset
9208
9209  option.
9210  Something like this should work:
9211 \newline
9212
9213 \newline
9214
9215 \series bold
9216 c:
9217 \backslash
9218 sdcc
9219 \backslash
9220 bin
9221 \backslash
9222 sdcc.exe -
9223 \series default
9224 \emph on
9225
9226 \begin_inset ERT
9227 status Collapsed
9228
9229 \layout Standard
9230
9231 \backslash
9232 /
9233 \end_inset
9234
9235
9236 \series bold
9237 \emph default
9238 -vc -
9239 \series default
9240 \emph on
9241
9242 \begin_inset ERT
9243 status Collapsed
9244
9245 \layout Standard
9246
9247 \backslash
9248 /
9249 \end_inset
9250
9251
9252 \series bold
9253 \emph default
9254 -model-large -c $(InputPath)
9255 \layout Section
9256
9257 Environment variables
9258 \begin_inset LatexCommand \index{Environment variables}
9259
9260 \end_inset
9261
9262
9263 \layout Standard
9264
9265 SDCC recognizes the following environment variables:
9266 \layout List
9267 \labelwidthstring 00.00.0000
9268
9269
9270 \series bold
9271 SDCC_LEAVE_SIGNALS
9272 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
9273
9274 \end_inset
9275
9276
9277 \series default
9278  SDCC installs a signal handler
9279 \begin_inset LatexCommand \index{signal handler}
9280
9281 \end_inset
9282
9283  to be able to delete temporary files after an user break (^C) or an exception.
9284  If this environment variable is set, SDCC won't install the signal handler
9285  in order to be able to debug SDCC.
9286 \layout List
9287 \labelwidthstring 00.00.0000
9288
9289
9290 \series bold
9291 TMP,\SpecialChar ~
9292 TEMP,\SpecialChar ~
9293 TMPDIR
9294 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
9295
9296 \end_inset
9297
9298
9299 \series default
9300  Path, where temporary files will be created.
9301  The order of the variables is the search order.
9302  In a standard *nix environment these variables are not set, and there's
9303  no need to set them.
9304  On Windows it's recommended to set one of them.
9305 \layout List
9306 \labelwidthstring 00.00.0000
9307
9308
9309 \series bold
9310 SDCC_HOME
9311 \begin_inset LatexCommand \index{SDCC\_HOME}
9312
9313 \end_inset
9314
9315
9316 \series default
9317  Path, see section
9318 \begin_inset LatexCommand \ref{sub:Install-paths}
9319
9320 \end_inset
9321
9322 \SpecialChar ~
9323
9324 \begin_inset Quotes sld
9325 \end_inset
9326
9327  Install Paths
9328 \begin_inset Quotes srd
9329 \end_inset
9330
9331 .
9332 \layout List
9333 \labelwidthstring 00.00.0000
9334
9335
9336 \series bold
9337 SDCC_INCLUDE
9338 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
9339
9340 \end_inset
9341
9342
9343 \series default
9344  Path, see section
9345 \begin_inset LatexCommand \ref{sub:Search-Paths}
9346
9347 \end_inset
9348
9349 \SpecialChar ~
9350
9351 \begin_inset Quotes sld
9352 \end_inset
9353
9354 Search Paths
9355 \begin_inset Quotes srd
9356 \end_inset
9357
9358 .
9359 \layout List
9360 \labelwidthstring 00.00.0000
9361
9362
9363 \series bold
9364 SDCC_LIB
9365 \begin_inset LatexCommand \index{SDCC\_LIB}
9366
9367 \end_inset
9368
9369
9370 \series default
9371  Path, see section
9372 \begin_inset LatexCommand \ref{sub:Search-Paths}
9373
9374 \end_inset
9375
9376 \SpecialChar ~
9377
9378 \begin_inset Quotes sld
9379 \end_inset
9380
9381 Search Paths
9382 \begin_inset Quotes srd
9383 \end_inset
9384
9385 ..
9386 \layout Standard
9387 \added_space_bottom bigskip
9388 There are some more environment variables recognized by SDCC, but these
9389  are solely used for debugging purposes.
9390  They can change or disappear very quickly, and will never be documented.
9391 \layout Section
9392
9393 Storage Class Language Extensions
9394 \layout Subsection
9395
9396 MCS51/DS390 Storage Class
9397 \begin_inset LatexCommand \index{Storage class}
9398
9399 \end_inset
9400
9401  Language Extensions
9402 \layout Standard
9403
9404 In addition to the ANSI storage classes SDCC allows the following MCS51
9405  specific storage classes:
9406 \layout Subsubsection
9407
9408 data
9409 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
9410
9411 \end_inset
9412
9413
9414 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
9415
9416 \end_inset
9417
9418  / near
9419 \begin_inset LatexCommand \index{near (storage class)}
9420
9421 \end_inset
9422
9423
9424 \begin_inset LatexCommand \index{\_\_near (storage class)}
9425
9426 \end_inset
9427
9428
9429 \layout Standard
9430
9431 This is the
9432 \series bold
9433 default
9434 \series default
9435  storage class for the Small Memory model (
9436 \emph on
9437 data
9438 \emph default
9439  and
9440 \emph on
9441 near
9442 \emph default
9443  or the more ANSI-C compliant forms
9444 \emph on
9445 __data
9446 \emph default
9447  and
9448 \emph on
9449 __near
9450 \emph default
9451  can be used synonymously).
9452  Variables declared with this storage class will be allocated in the directly
9453  addressable portion of the internal RAM of a 8051, e.g.:
9454 \layout Verse
9455
9456
9457 \family typewriter
9458 __data unsigned char test_data;
9459 \layout Standard
9460
9461 Writing 0x01 to this variable generates the assembly code:
9462 \layout Verse
9463
9464
9465 \family typewriter
9466 75*00 01\SpecialChar ~
9467 \SpecialChar ~
9468 \SpecialChar ~
9469 mov\SpecialChar ~
9470 \SpecialChar ~
9471 _test_data,#0x01
9472 \layout Subsubsection
9473
9474 xdata
9475 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9476
9477 \end_inset
9478
9479
9480 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9481
9482 \end_inset
9483
9484  / far
9485 \begin_inset LatexCommand \index{far (storage class)}
9486
9487 \end_inset
9488
9489
9490 \begin_inset LatexCommand \index{\_\_far (storage class)}
9491
9492 \end_inset
9493
9494
9495 \layout Standard
9496
9497 Variables declared with this storage class will be placed in the external
9498  RAM.
9499  This is the
9500 \series bold
9501 default
9502 \series default
9503  storage class for the Large Memory model, e.g.:
9504 \layout Verse
9505
9506
9507 \family typewriter
9508 __xdata unsigned char test_xdata;
9509 \layout Standard
9510
9511 Writing 0x01 to this variable generates the assembly code:
9512 \layout Verse
9513
9514
9515 \family typewriter
9516 90s00r00\SpecialChar ~
9517 \SpecialChar ~
9518 \SpecialChar ~
9519 mov\SpecialChar ~
9520 \SpecialChar ~
9521 dptr,#_test_xdata
9522 \newline
9523 74\SpecialChar ~
9524 01\SpecialChar ~
9525 \SpecialChar ~
9526 \SpecialChar ~
9527 \SpecialChar ~
9528 \SpecialChar ~
9529 \SpecialChar ~
9530 mov\SpecialChar ~
9531 \SpecialChar ~
9532 a,#0x01
9533 \newline
9534 F0\SpecialChar ~
9535 \SpecialChar ~
9536 \SpecialChar ~
9537 \SpecialChar ~
9538 \SpecialChar ~
9539 \SpecialChar ~
9540 \SpecialChar ~
9541 \SpecialChar ~
9542 \SpecialChar ~
9543 movx\SpecialChar ~
9544 @dptr,a
9545 \layout Subsubsection
9546
9547 idata
9548 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
9549
9550 \end_inset
9551
9552
9553 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
9554
9555 \end_inset
9556
9557
9558 \layout Standard
9559
9560 Variables declared with this storage class will be allocated into the indirectly
9561  addressable portion of the internal ram of a 8051, e.g.:
9562 \layout Verse
9563
9564
9565 \family typewriter
9566 __idata unsigned char test_idata;
9567 \layout Standard
9568
9569 Writing 0x01 to this variable generates the assembly code:
9570 \layout Verse
9571
9572
9573 \family typewriter
9574 78r00\SpecialChar ~
9575 \SpecialChar ~
9576 \SpecialChar ~
9577 \SpecialChar ~
9578 \SpecialChar ~
9579 \SpecialChar ~
9580 \SpecialChar ~
9581 mov\SpecialChar ~
9582 \SpecialChar ~
9583 r0,#_test_idata
9584 \newline
9585 76\SpecialChar ~
9586 01\SpecialChar ~
9587 \SpecialChar ~
9588 \SpecialChar ~
9589 \SpecialChar ~
9590 \SpecialChar ~
9591 \SpecialChar ~
9592 \SpecialChar ~
9593 mov\SpecialChar ~
9594 \SpecialChar ~
9595 @r0,#0x01
9596 \layout Standard
9597
9598 Please note, the first 128 byte of idata physically access the same RAM
9599  as the data memory.
9600  The original 8051 had 128 byte idata memory, nowadays most devices have
9601  256 byte idata memory.
9602  The stack
9603 \begin_inset LatexCommand \index{stack}
9604
9605 \end_inset
9606
9607  is located in idata memory.
9608 \layout Subsubsection
9609
9610 pdata
9611 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
9612
9613 \end_inset
9614
9615
9616 \begin_inset LatexCommand \index{\_\_pdata (mcs51, ds390 storage class)}
9617
9618 \end_inset
9619
9620
9621 \layout Standard
9622
9623 Paged xdata access is just as straightforward as using the other addressing
9624  modes of a 8051.
9625  It is typically located at the start of xdata and has a maximum size of
9626  256 bytes.
9627  The following example writes 0x01 to the pdata variable.
9628  Please note, pdata access physically accesses xdata memory.
9629  The high byte of the address is determined by port P2
9630 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
9631
9632 \end_inset
9633
9634 (or in case of some 8051 variants by a separate Special Function Register,
9635  see section
9636 \begin_inset LatexCommand \ref{sub:MCS51-variants}
9637
9638 \end_inset
9639
9640 ).
9641  This is the
9642 \series bold
9643 default
9644 \series default
9645  storage class for the Medium Memory model, e.g.:
9646 \layout Verse
9647
9648
9649 \family typewriter
9650 __pdata unsigned char test_pdata;
9651 \layout Standard
9652
9653 Writing 0x01 to this variable generates the assembly code:
9654 \layout Verse
9655
9656
9657 \family typewriter
9658 78r00\SpecialChar ~
9659 \SpecialChar ~
9660 \SpecialChar ~
9661 \SpecialChar ~
9662 \SpecialChar ~
9663 \SpecialChar ~
9664 mov r0,#_test_pdata
9665 \newline
9666 74 01\SpecialChar ~
9667 \SpecialChar ~
9668 \SpecialChar ~
9669 \SpecialChar ~
9670 \SpecialChar ~
9671 \SpecialChar ~
9672 mov a,#0x01
9673 \newline
9674 F2\SpecialChar ~
9675 \SpecialChar ~
9676 \SpecialChar ~
9677 \SpecialChar ~
9678 \SpecialChar ~
9679 \SpecialChar ~
9680 \SpecialChar ~
9681 \SpecialChar ~
9682 \SpecialChar ~
9683 movx @r0,a
9684 \layout Standard
9685
9686 If the -
9687 \begin_inset ERT
9688 status Collapsed
9689
9690 \layout Standard
9691
9692 \backslash
9693 /
9694 \end_inset
9695
9696 -xstack
9697 \begin_inset LatexCommand \index{-\/-xstack}
9698
9699 \end_inset
9700
9701  option is used the pdata memory area is followed by the xstack memory area
9702  and the sum of their sizes is limited to 256 bytes.
9703 \layout Subsubsection
9704
9705 code
9706 \begin_inset LatexCommand \index{code}
9707
9708 \end_inset
9709
9710
9711 \begin_inset LatexCommand \index{\_\_code}
9712
9713 \end_inset
9714
9715
9716 \layout Standard
9717
9718 'Variables' declared with this storage class will be placed in the code
9719  memory:
9720 \layout Verse
9721
9722
9723 \family typewriter
9724 __code unsigned char test_code;
9725 \layout Standard
9726
9727 Read access to this variable generates the assembly code:
9728 \layout Verse
9729
9730
9731 \family typewriter
9732 90s00r6F\SpecialChar ~
9733 \SpecialChar ~
9734 \SpecialChar ~
9735 mov dptr,#_test_code
9736 \newline
9737 E4\SpecialChar ~
9738 \SpecialChar ~
9739 \SpecialChar ~
9740 \SpecialChar ~
9741 \SpecialChar ~
9742 \SpecialChar ~
9743 \SpecialChar ~
9744 \SpecialChar ~
9745 \SpecialChar ~
9746 clr a
9747 \newline
9748 93\SpecialChar ~
9749 \SpecialChar ~
9750 \SpecialChar ~
9751 \SpecialChar ~
9752 \SpecialChar ~
9753 \SpecialChar ~
9754 \SpecialChar ~
9755 \SpecialChar ~
9756 \SpecialChar ~
9757 movc a,@a+dptr
9758 \layout Standard
9759
9760
9761 \family typewriter
9762 char
9763 \family default
9764  indexed arrays of characters in code memory can be accessed efficiently:
9765 \layout Verse
9766
9767
9768 \family typewriter
9769 __code char test_array[] = {'c','h','e','a','p'};
9770 \layout Standard
9771
9772 Read access to this array using an 8-bit unsigned index generates the assembly
9773  code:
9774 \layout Verse
9775
9776
9777 \family typewriter
9778 E5*00\SpecialChar ~
9779 \SpecialChar ~
9780 \SpecialChar ~
9781 \SpecialChar ~
9782 \SpecialChar ~
9783 \SpecialChar ~
9784 mov a,_index
9785 \layout Verse
9786
9787
9788 \family typewriter
9789 90s00r41\SpecialChar ~
9790 \SpecialChar ~
9791 \SpecialChar ~
9792 mov dptr,#_test_array
9793 \layout Verse
9794
9795
9796 \family typewriter
9797 93\SpecialChar ~
9798 \SpecialChar ~
9799 \SpecialChar ~
9800 \SpecialChar ~
9801 \SpecialChar ~
9802 \SpecialChar ~
9803 \SpecialChar ~
9804 \SpecialChar ~
9805 \SpecialChar ~
9806 movc a,@a+dptr
9807 \layout Subsubsection
9808
9809 bit
9810 \begin_inset LatexCommand \index{bit}
9811
9812 \end_inset
9813
9814
9815 \begin_inset LatexCommand \index{\_\_bit}
9816
9817 \end_inset
9818
9819
9820 \layout Standard
9821
9822 This is a data-type and a storage class specifier.
9823  When a variable is declared as a bit, it is allocated into the bit addressable
9824  memory of 8051, e.g.:
9825 \layout Verse
9826
9827
9828 \family typewriter
9829 __bit test_bit;
9830 \layout Standard
9831
9832 Writing 1 to this variable generates the assembly code:
9833 \layout Verse
9834
9835
9836 \family typewriter
9837 D2*00\SpecialChar ~
9838 \SpecialChar ~
9839 \SpecialChar ~
9840 \SpecialChar ~
9841 \SpecialChar ~
9842 \SpecialChar ~
9843 \SpecialChar ~
9844 setb\SpecialChar ~
9845 _test_bit
9846 \layout Standard
9847
9848 The bit addressable memory consists of 128 bits which are located from 0x20
9849  to 0x2f in data memory.
9850
9851 \newline
9852 Apart from this 8051 specific storage class most architectures support ANSI-C
9853  bitfields
9854 \begin_inset LatexCommand \index{bitfields}
9855
9856 \end_inset
9857
9858
9859 \begin_inset Foot
9860 collapsed false
9861
9862 \layout Standard
9863
9864 Not really meant as examples, but nevertheless showing what bitfields are
9865  about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
9866 \end_inset
9867
9868 .
9869  In accordance with ISO/IEC 9899 bits and bitfields without an explicit
9870  signed modifier are implemented as unsigned.
9871 \layout Subsubsection
9872
9873 sfr
9874 \begin_inset LatexCommand \index{sfr}
9875
9876 \end_inset
9877
9878
9879 \begin_inset LatexCommand \index{\_\_sfr}
9880
9881 \end_inset
9882
9883  / sfr16
9884 \begin_inset LatexCommand \index{sfr16}
9885
9886 \end_inset
9887
9888
9889 \begin_inset LatexCommand \index{\_\_sfr16}
9890
9891 \end_inset
9892
9893  / sfr32
9894 \begin_inset LatexCommand \index{sfr32}
9895
9896 \end_inset
9897
9898
9899 \begin_inset LatexCommand \index{\_\_sfr32}
9900
9901 \end_inset
9902
9903  / sbit
9904 \begin_inset LatexCommand \index{\_\_sbit}
9905
9906 \end_inset
9907
9908
9909 \begin_inset LatexCommand \index{sbit}
9910
9911 \end_inset
9912
9913
9914 \layout Standard
9915
9916 Like the bit keyword,
9917 \emph on
9918 sfr / sfr16 / sfr32 / sbit
9919 \emph default
9920 signify both a data-type and storage class, they are used to describe the
9921
9922 \emph on
9923 s
9924 \emph default
9925 pecial
9926 \emph on
9927 f
9928 \emph default
9929 unction
9930 \emph on
9931 r
9932 \emph default
9933 egisters and
9934 \emph on
9935 s
9936 \emph default
9937 pecial
9938 \emph on
9939 bit
9940 \emph default
9941  variables of a 8051, eg:
9942 \layout Verse
9943
9944
9945 \family typewriter
9946 __sfr __at
9947 \begin_inset LatexCommand \index{at}
9948
9949 \end_inset
9950
9951
9952 \begin_inset LatexCommand \index{\_\_at}
9953
9954 \end_inset
9955
9956  (0x80) P0;\SpecialChar ~
9957  /* special function register P0 at location 0x80 */
9958 \newline
9959
9960 \newline
9961 /* 16 bit special function register combination for timer 0
9962 \newline
9963 \SpecialChar ~
9964 \SpecialChar ~
9965  with the high byte at location 0x8C and the low byte at location 0x8A */
9966 \newline
9967 __sfr16 __at (0x8C8A) TMR0;
9968 \newline
9969
9970 \newline
9971 __sbit __at
9972 \begin_inset LatexCommand \index{at}
9973
9974 \end_inset
9975
9976
9977 \begin_inset LatexCommand \index{\_\_at}
9978
9979 \end_inset
9980
9981  (0xd7) CY;\SpecialChar ~
9982  /* CY (Carry Flag
9983 \begin_inset LatexCommand \index{Flags}
9984
9985 \end_inset
9986
9987
9988 \begin_inset LatexCommand \index{Carry flag}
9989
9990 \end_inset
9991
9992 ) */
9993 \layout Standard
9994
9995 Special function registers which are located on an address dividable by
9996  8 are bit-addressable, an
9997 \emph on
9998  sbit
9999 \emph default
10000  addresses a specific bit within these sfr.
10001 \newline
10002 16 Bit and 32 bit special function register combinations which require a
10003  certain access order are better not declared using
10004 \emph on
10005 sfr16
10006 \emph default
10007  or
10008 \emph on
10009 sfr32.
10010
10011 \emph default
10012  Allthough SDCC usually accesses them Least Significant Byte (LSB) first,
10013  this is not guaranteed.
10014 \newline
10015
10016 \layout Standard
10017
10018 Please note, if you use a header file which was written for another compiler
10019  then the sfr / sfr16 / sfr32 / sbit Storage Class extensions will most
10020  likely be
10021 \emph on
10022 not
10023 \emph default
10024 compatible.
10025  Specifically the syntax
10026 \family typewriter
10027 \SpecialChar ~
10028 sfr P0 = 0x80;\SpecialChar ~
10029
10030 \family default
10031  is compiled
10032 \emph on
10033 without warning
10034 \emph default
10035  by SDCC to an assignment of 0x80 to a variable called P0
10036 \family typewriter
10037
10038 \begin_inset Marginal
10039 collapsed true
10040
10041 \layout Standard
10042
10043
10044 \series bold
10045 \SpecialChar ~
10046 !
10047 \end_inset
10048
10049 .
10050
10051 \family default
10052 Nevertheless it is possible to write header files
10053 \begin_inset LatexCommand \index{Header files}
10054
10055 \end_inset
10056
10057
10058 \begin_inset LatexCommand \index{Include files}
10059
10060 \end_inset
10061
10062  which can be shared among different compilers (see section
10063 \begin_inset LatexCommand \ref{sec:Porting-code-to-other-compilers}
10064
10065 \end_inset
10066
10067 ).
10068
10069 \layout Subsubsection
10070
10071 Pointers
10072 \begin_inset LatexCommand \index{Pointer}
10073
10074 \end_inset
10075
10076  to MCS51/DS390 specific memory spaces
10077 \layout Standard
10078
10079 SDCC allows (via language extensions) pointers to explicitly point to any
10080  of the memory spaces
10081 \begin_inset LatexCommand \index{Memory model}
10082
10083 \end_inset
10084
10085  of the 8051.
10086  In addition to the explicit pointers, the compiler uses (by default) generic
10087  pointers which can be used to point to any of the memory spaces.
10088 \newline
10089
10090 \newline
10091 Pointer declaration examples:
10092 \layout Verse
10093
10094
10095 \family typewriter
10096 /* pointer physically in internal ram pointing to object in external ram
10097  */
10098 \newline
10099 __xdata unsigned char * __data p;
10100 \newline
10101
10102 \newline
10103 /* pointer physically in external ram pointing to object in internal ram
10104  */
10105 \newline
10106 __data unsigned char * __xdata p;
10107 \newline
10108
10109 \newline
10110 /* pointer physically in code rom pointing to data in xdata space */
10111 \newline
10112 __xdata unsigned char * __code p;
10113 \newline
10114
10115 \newline
10116 /* pointer physically in code space pointing to data in code space */
10117 \newline
10118 __code unsigned char * __code p;
10119 \newline
10120
10121 \newline
10122 /* generic pointer physically located in xdata space */
10123 \newline
10124 unsigned char * __xdata p;
10125 \newline
10126
10127 \newline
10128 /* generic pointer physically located in default memory space */
10129 \newline
10130 unsigned char * p;
10131 \newline
10132
10133 \newline
10134 /* the following is a function pointer
10135 \begin_inset LatexCommand \index{function pointer}
10136
10137 \end_inset
10138
10139  physically located in data space */
10140 \newline
10141 char (* __data fp)(void);
10142 \layout Standard
10143
10144 Well you get the idea.
10145
10146 \newline
10147
10148 \newline
10149 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
10150 \emph on
10151 generic
10152 \emph default
10153  pointers.
10154
10155 \size small
10156
10157 \newline
10158
10159 \newline
10160
10161 \size default
10162 The highest order byte of the
10163 \emph on
10164 generic
10165 \emph default
10166  pointers contains the data space information.
10167  Assembler support routines are called whenever data is stored or retrieved
10168  using
10169 \emph on
10170 generic
10171 \emph default
10172  pointers.
10173  These are useful for developing reusable library
10174 \begin_inset LatexCommand \index{Libraries}
10175
10176 \end_inset
10177
10178  routines.
10179  Explicitly specifying the pointer
10180 \begin_inset LatexCommand \index{pointer}
10181
10182 \end_inset
10183
10184  type will generate the most efficient code.
10185 \layout Subsubsection
10186
10187 Notes on MCS51 memory
10188 \begin_inset LatexCommand \index{MCS51 memory}
10189
10190 \end_inset
10191
10192  layout
10193 \layout Standard
10194
10195 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
10196  RAM memory which is structured as follows:
10197 \newline
10198
10199 \newline
10200 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
10201
10202 \newline
10203 - Bytes 20-2F - 16 bytes to hold 128 bit
10204 \begin_inset LatexCommand \index{bit}
10205
10206 \end_inset
10207
10208  variables and,
10209 \newline
10210 - Bytes 30-7F - 80 bytes for general purpose use.
10211 \newline
10212
10213 \layout Standard
10214
10215 Additionally some members of the MCS51 family may have up to 128 bytes of
10216  additional, indirectly addressable, internal RAM memory (
10217 \emph on
10218 idata
10219 \emph default
10220
10221 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
10222
10223 \end_inset
10224
10225
10226 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
10227
10228 \end_inset
10229
10230 ).
10231  Furthermore, some chips may have some built in external memory (
10232 \emph on
10233 xdata
10234 \emph default
10235
10236 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
10237
10238 \end_inset
10239
10240
10241 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
10242
10243 \end_inset
10244
10245 ) which should not be confused with the internal, directly addressable RAM
10246  memory (
10247 \emph on
10248 data
10249 \emph default
10250
10251 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
10252
10253 \end_inset
10254
10255
10256 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
10257
10258 \end_inset
10259
10260 ).
10261  Sometimes this built in
10262 \emph on
10263 xdata
10264 \emph default
10265  memory has to be activated before using it (you can probably find this
10266  information on the datasheet of the microcontroller your are using, see
10267  also section
10268 \begin_inset LatexCommand \ref{sub:Startup-Code}
10269
10270 \end_inset
10271
10272 \SpecialChar ~
10273 Startup-Code).
10274 \layout Standard
10275
10276 Normally SDCC will only use the first bank
10277 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
10278
10279 \end_inset
10280
10281  of registers (register bank 0), but it is possible to specify that other
10282  banks of registers (keyword
10283 \emph on
10284 using
10285 \emph default
10286
10287 \emph on
10288
10289 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10290
10291 \end_inset
10292
10293
10294 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
10295
10296 \end_inset
10297
10298
10299 \emph default
10300 ) should be used in interrupt
10301 \begin_inset LatexCommand \index{interrupt}
10302
10303 \end_inset
10304
10305
10306 \begin_inset LatexCommand \index{\_\_interrupt}
10307
10308 \end_inset
10309
10310  routines.
10311  By default, the compiler will place the stack after the last byte of allocated
10312  memory for variables.
10313  For example, if the first 2 banks of registers are used, and only four
10314  bytes are used for
10315 \emph on
10316 data
10317 \emph default
10318  variables, it will position the base of the internal stack at address 20
10319  (0x14).
10320  This implies that as the stack
10321 \begin_inset LatexCommand \index{stack}
10322
10323 \end_inset
10324
10325  grows, it will use up the remaining register banks, and the 16 bytes used
10326  by the 128 bit variables, and 80 bytes for general purpose use.
10327  If any bit variables are used, the data variables will be placed in unused
10328  register banks and after the byte holding the last bit variable.
10329  For example, if register banks 0 and 1 are used, and there are 9 bit variables
10330  (two bytes used),
10331 \emph on
10332 data
10333 \emph default
10334  variables will be placed starting from address 0x10 to 0x20 and continue
10335  at address 0x22.
10336  You can also use -
10337 \begin_inset ERT
10338 status Collapsed
10339
10340 \layout Standard
10341
10342 \backslash
10343 /
10344 \end_inset
10345
10346 -data-loc
10347 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
10348
10349 \end_inset
10350
10351  to specify the start address of the
10352 \emph on
10353 data
10354 \emph default
10355  and -
10356 \begin_inset ERT
10357 status Collapsed
10358
10359 \layout Standard
10360
10361 \backslash
10362 /
10363 \end_inset
10364
10365 -iram-size
10366 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
10367
10368 \end_inset
10369
10370  to specify the size of the total internal RAM (
10371 \emph on
10372 data
10373 \emph default
10374 +
10375 \emph on
10376 idata
10377 \emph default
10378 ).
10379
10380 \newline
10381
10382 \layout Standard
10383
10384 By default the 8051 linker will place the stack after the last byte of (i)data
10385  variables.
10386  Option -
10387 \begin_inset ERT
10388 status Collapsed
10389
10390 \layout Standard
10391
10392 \backslash
10393 /
10394 \end_inset
10395
10396 -stack-loc
10397 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
10398
10399 \end_inset
10400
10401  allows you to specify the start of the stack, i.e.
10402  you could start it after any data in the general purpose area.
10403  If your microcontroller has additional indirectly addressable internal
10404  RAM (
10405 \emph on
10406 idata
10407 \emph default
10408 ) you can place the stack on it.
10409  You may also need to use -
10410 \begin_inset ERT
10411 status Collapsed
10412
10413 \layout Standard
10414
10415 \backslash
10416 /
10417 \end_inset
10418
10419 -xdata-loc
10420 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
10421
10422 \end_inset
10423
10424  to set the start address of the external RAM (
10425 \emph on
10426 xdata
10427 \emph default
10428 ) and -
10429 \begin_inset ERT
10430 status Collapsed
10431
10432 \layout Standard
10433
10434 \backslash
10435 /
10436 \end_inset
10437
10438 -xram-size
10439 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
10440
10441 \end_inset
10442
10443  to specify its size.
10444  Same goes for the code memory, using -
10445 \begin_inset ERT
10446 status Collapsed
10447
10448 \layout Standard
10449
10450 \backslash
10451 /
10452 \end_inset
10453
10454 -code-loc
10455 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
10456
10457 \end_inset
10458
10459  and -
10460 \begin_inset ERT
10461 status Collapsed
10462
10463 \layout Standard
10464
10465 \backslash
10466 /
10467 \end_inset
10468
10469 -code-size
10470 \begin_inset LatexCommand \index{-\/-code-size <Value>}
10471
10472 \end_inset
10473
10474 .
10475  If in doubt, don't specify any options and see if the resulting memory
10476  layout is appropriate, then you can adjust it.
10477 \layout Standard
10478 \added_space_bottom bigskip
10479 The linker generates two files with memory allocation information.
10480  The first, with extension .map
10481 \begin_inset LatexCommand \index{<file>.map}
10482
10483 \end_inset
10484
10485  shows all the variables and segments.
10486  The second with extension .mem
10487 \begin_inset LatexCommand \index{<file>.mem}
10488
10489 \end_inset
10490
10491  shows the final memory layout.
10492  The linker will complain either if memory segments overlap, there is not
10493  enough memory, or there is not enough space for stack.
10494  If you get any linking warnings and/or errors related to stack or segments
10495  allocation, take a look at either the .map or .mem files to find out what
10496  the problem is.
10497  The .mem file may even suggest a solution to the problem.
10498 \layout Subsection
10499
10500 Z80/Z180 Storage Class
10501 \begin_inset LatexCommand \index{Z80!Storage class}
10502
10503 \end_inset
10504
10505  Language Extensions
10506 \layout Subsubsection
10507
10508 sfr
10509 \begin_inset LatexCommand \index{sfr}
10510
10511 \end_inset
10512
10513
10514 \begin_inset LatexCommand \index{\_\_sfr}
10515
10516 \end_inset
10517
10518  (in/out to 8-bit addresses)
10519 \layout Standard
10520
10521 The Z80
10522 \begin_inset LatexCommand \index{Z80}
10523
10524 \end_inset
10525
10526  family has separate address spaces for memory and
10527 \emph on
10528 i
10529 \emph default
10530 nput/
10531 \emph on
10532 o
10533 \emph default
10534 utput memory.
10535  I/O memory
10536 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
10537
10538 \end_inset
10539
10540
10541 \begin_inset LatexCommand \index{Z80!I/O memory}
10542
10543 \end_inset
10544
10545
10546 \begin_inset LatexCommand \index{Z180!I/O memory}
10547
10548 \end_inset
10549
10550  is accessed with special instructions, e.g.:
10551 \layout Verse
10552
10553
10554 \family typewriter
10555 sfr at 0x78 IoPort;\SpecialChar ~
10556 \SpecialChar ~
10557 /* define a var in I/O space at 78h called IoPort */
10558
10559 \layout Standard
10560
10561 Writing 0x01 to this variable generates the assembly code:
10562 \layout Verse
10563
10564
10565 \family typewriter
10566 3E 01\SpecialChar ~
10567 \SpecialChar ~
10568 \SpecialChar ~
10569 \SpecialChar ~
10570 \SpecialChar ~
10571 \SpecialChar ~
10572 ld a,#0x01
10573 \newline
10574 D3 78\SpecialChar ~
10575 \SpecialChar ~
10576 \SpecialChar ~
10577 \SpecialChar ~
10578 \SpecialChar ~
10579 \SpecialChar ~
10580 out (_IoPort),a
10581 \layout Subsubsection
10582
10583 banked sfr
10584 \begin_inset LatexCommand \index{sfr}
10585
10586 \end_inset
10587
10588
10589 \begin_inset LatexCommand \index{\_\_sfr}
10590
10591 \end_inset
10592
10593  (in/out to 16-bit addresses)
10594 \layout Standard
10595
10596 The keyword
10597 \emph on
10598 banked
10599 \emph default
10600  is used to support 16 bit addresses in I/O memory e.g.:
10601 \layout Verse
10602
10603
10604 \family typewriter
10605 sfr banked at
10606 \begin_inset LatexCommand \index{at}
10607
10608 \end_inset
10609
10610
10611 \begin_inset LatexCommand \index{\_\_at}
10612
10613 \end_inset
10614
10615  0x123 IoPort;
10616 \layout Standard
10617
10618 Writing 0x01 to this variable generates the assembly code:
10619 \layout Verse
10620
10621
10622 \family typewriter
10623 01 23 01\SpecialChar ~
10624 \SpecialChar ~
10625 \SpecialChar ~
10626 ld bc,#_IoPort
10627 \newline
10628 3E 01\SpecialChar ~
10629 \SpecialChar ~
10630 \SpecialChar ~
10631 \SpecialChar ~
10632 \SpecialChar ~
10633 \SpecialChar ~
10634 ld a,#0x01
10635 \newline
10636 ED 79\SpecialChar ~
10637 \SpecialChar ~
10638 \SpecialChar ~
10639 \SpecialChar ~
10640 \SpecialChar ~
10641 \SpecialChar ~
10642 out (c),a
10643 \layout Subsubsection
10644
10645 sfr
10646 \begin_inset LatexCommand \index{sfr}
10647
10648 \end_inset
10649
10650
10651 \begin_inset LatexCommand \index{\_\_sfr}
10652
10653 \end_inset
10654
10655  (in0/out0 to 8 bit addresses on Z180
10656 \begin_inset LatexCommand \index{Z180}
10657
10658 \end_inset
10659
10660 /HD64180
10661 \begin_inset LatexCommand \index{HD64180 (see Z180)}
10662
10663 \end_inset
10664
10665 )
10666 \layout Standard
10667 \added_space_bottom bigskip
10668 The compiler option -
10669 \begin_inset ERT
10670 status Collapsed
10671
10672 \layout Standard
10673
10674 \backslash
10675 /
10676 \end_inset
10677
10678 -portmode
10679 \begin_inset LatexCommand \index{Z180!Options!-\/-portmode}
10680
10681 \end_inset
10682
10683 =180 (80) and a compiler #pragma\SpecialChar ~
10684 portmode
10685 \begin_inset LatexCommand \index{Z180!Pragmas!\#pragma portmode}
10686
10687 \end_inset
10688
10689  z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
10690 ns
10691 \family typewriter
10692 in0/out0
10693 \family default
10694  instead of
10695 \family typewriter
10696 in/out
10697 \family default
10698 .
10699  If you include the file z180.h this will be set automatically.
10700 \layout Subsection
10701
10702 HC08 Storage Class
10703 \begin_inset LatexCommand \index{HC08!Storage class}
10704
10705 \end_inset
10706
10707  Language Extensions
10708 \layout Subsubsection
10709
10710 data
10711 \begin_inset LatexCommand \index{data (hc08 storage class)}
10712
10713 \end_inset
10714
10715
10716 \begin_inset LatexCommand \index{\_\_data (hc08 storage class)}
10717
10718 \end_inset
10719
10720
10721 \layout Standard
10722
10723 The data storage class declares a variable that resides in the first 256
10724  bytes of memory (the direct page).
10725  The HC08
10726 \begin_inset LatexCommand \index{HC08}
10727
10728 \end_inset
10729
10730  is most efficient at accessing variables (especially pointers) stored here.
10731 \layout Subsubsection
10732
10733 xdata
10734 \begin_inset LatexCommand \index{xdata (hc08 storage class)}
10735
10736 \end_inset
10737
10738
10739 \begin_inset LatexCommand \index{\_\_xdata (hc08 storage class)}
10740
10741 \end_inset
10742
10743
10744 \layout Standard
10745 \added_space_bottom bigskip
10746 The xdata storage class declares a variable that can reside anywhere in
10747  memory.
10748  This is the default if no storage class is specified.
10749
10750 \layout Section
10751
10752 Absolute Addressing
10753 \begin_inset LatexCommand \index{Absolute addressing}
10754
10755 \end_inset
10756
10757
10758 \layout Standard
10759
10760 Data items can be assigned an absolute address with the
10761 \emph on
10762 at
10763 \begin_inset LatexCommand \index{at}
10764
10765 \end_inset
10766
10767
10768 \begin_inset LatexCommand \index{\_\_at}
10769
10770 \end_inset
10771
10772  <address>
10773 \emph default
10774  keyword, in addition to a storage class, e.g.:
10775 \layout Verse
10776
10777
10778 \family typewriter
10779 xdata
10780 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
10781
10782 \end_inset
10783
10784
10785 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
10786
10787 \end_inset
10788
10789  at
10790 \begin_inset LatexCommand \index{at}
10791
10792 \end_inset
10793
10794
10795 \begin_inset LatexCommand \index{\_\_at}
10796
10797 \end_inset
10798
10799  0x7ffe unsigned int chksum;
10800 \layout Standard
10801
10802 or, better conforming to ISO/IEC 9899 C:
10803 \layout Verse
10804
10805
10806 \family typewriter
10807 __xdata __at (0x7ffe) unsigned int chksum;
10808 \layout Standard
10809
10810 In the above example the variable chksum will be located at 0x7ffe and 0x7fff
10811  of the external ram.
10812  The compiler does
10813 \emph on
10814 not
10815 \emph default
10816  reserve any space for variables declared in this way
10817 \begin_inset Marginal
10818 collapsed true
10819
10820 \layout Standard
10821
10822
10823 \series bold
10824 \SpecialChar ~
10825 !
10826 \end_inset
10827
10828  (they are implemented with an equate in the assembler).
10829  Thus it is left to the programmer to make sure there are no overlaps with
10830  other variables that are declared without the absolute address.
10831  The assembler listing file (.lst
10832 \begin_inset LatexCommand \index{<file>.lst}
10833
10834 \end_inset
10835
10836 ) and the linker output files (.rst
10837 \begin_inset LatexCommand \index{<file>.rst}
10838
10839 \end_inset
10840
10841 ) and (.map
10842 \begin_inset LatexCommand \index{<file>.map}
10843
10844 \end_inset
10845
10846 ) are good places to look for such overlaps.
10847  Variables with an absolute address are
10848 \emph on
10849 not
10850 \begin_inset Marginal
10851 collapsed true
10852
10853 \layout Standard
10854
10855
10856 \series bold
10857 \SpecialChar ~
10858 !
10859 \end_inset
10860
10861
10862 \emph default
10863  initialized
10864 \begin_inset LatexCommand \index{Variable initialization}
10865
10866 \end_inset
10867
10868 .
10869 \layout Standard
10870
10871 In case of memory mapped I/O devices the keyword
10872 \emph on
10873 volatile
10874 \emph default
10875  has to be used to tell the compiler that accesses might not be removed:
10876 \layout Verse
10877
10878
10879 \family typewriter
10880 volatile
10881 \begin_inset LatexCommand \index{volatile}
10882
10883 \end_inset
10884
10885  __xdata
10886 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
10887
10888 \end_inset
10889
10890  __at
10891 \begin_inset LatexCommand \index{at}
10892
10893 \end_inset
10894
10895  (0x8000) unsigned char PORTA_8255;
10896 \layout Standard
10897
10898 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
10899 r) array
10900 \family typewriter
10901 \size footnotesize
10902
10903 \begin_inset LatexCommand \index{Aligned array}
10904
10905 \end_inset
10906
10907
10908 \family default
10909 \size default
10910  starts at a block (256 byte) boundary
10911 \begin_inset LatexCommand \index{block boundary}
10912
10913 \end_inset
10914
10915  (section
10916 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
10917
10918 \end_inset
10919
10920  has an example).
10921 \newline
10922 Absolute addresses can be specified for variables in all storage classes,
10923  e.g.:
10924 \layout Verse
10925
10926
10927 \family typewriter
10928 __bit
10929 \begin_inset LatexCommand \index{bit}
10930
10931 \end_inset
10932
10933  __at
10934 \begin_inset LatexCommand \index{at}
10935
10936 \end_inset
10937
10938  (0x02) bvar;
10939 \layout Standard
10940
10941 The above example will allocate the variable at offset 0x02 in the bit-addressab
10942 le space.
10943  There is no real advantage to assigning absolute addresses to variables
10944  in this manner, unless you want strict control over all the variables allocated.
10945  One possible use would be to write hardware portable code.
10946  For example, if you have a routine that uses one or more of the microcontroller
10947  I/O pins, and such pins are different for two different hardwares, you
10948  can declare the I/O pins in your routine using:
10949 \layout Verse
10950
10951
10952 \family typewriter
10953 extern volatile
10954 \begin_inset LatexCommand \index{volatile}
10955
10956 \end_inset
10957
10958  __bit MOSI;\SpecialChar ~
10959 \SpecialChar ~
10960 \SpecialChar ~
10961 \SpecialChar ~
10962 /* master out, slave in */
10963 \newline
10964 extern volatile __bit MISO;\SpecialChar ~
10965 \SpecialChar ~
10966 \SpecialChar ~
10967 \SpecialChar ~
10968 /* master in, slave out */
10969 \newline
10970 extern volatile __bit MCLK;\SpecialChar ~
10971 \SpecialChar ~
10972 \SpecialChar ~
10973 \SpecialChar ~
10974 /* master clock */
10975 \newline
10976
10977 \newline
10978 /* Input and Output of a byte on a 3-wire serial bus.
10979 \newline
10980 \SpecialChar ~
10981 \SpecialChar ~
10982 \SpecialChar ~
10983 If needed adapt polarity of clock, polarity of data and bit order
10984 \newline
10985 \SpecialChar ~
10986 */
10987 \newline
10988 unsigned char spi_io(unsigned char out_byte)
10989 \newline
10990 {
10991 \newline
10992 \SpecialChar ~
10993 \SpecialChar ~
10994 \SpecialChar ~
10995 \SpecialChar ~
10996 unsigned char i=8;
10997 \newline
10998 \SpecialChar ~
10999 \SpecialChar ~
11000 \SpecialChar ~
11001 \SpecialChar ~
11002 do {
11003 \newline
11004 \SpecialChar ~
11005 \SpecialChar ~
11006 \SpecialChar ~
11007 \SpecialChar ~
11008 \SpecialChar ~
11009 \SpecialChar ~
11010 \SpecialChar ~
11011 \SpecialChar ~
11012 MOSI = out_byte & 0x80;
11013 \newline
11014 \SpecialChar ~
11015 \SpecialChar ~
11016 \SpecialChar ~
11017 \SpecialChar ~
11018 \SpecialChar ~
11019 \SpecialChar ~
11020 \SpecialChar ~
11021 \SpecialChar ~
11022 out_byte <<= 1;
11023 \newline
11024 \SpecialChar ~
11025 \SpecialChar ~
11026 \SpecialChar ~
11027 \SpecialChar ~
11028 \SpecialChar ~
11029 \SpecialChar ~
11030 \SpecialChar ~
11031 \SpecialChar ~
11032 MCLK = 1;
11033 \newline
11034 \SpecialChar ~
11035 \SpecialChar ~
11036 \SpecialChar ~
11037 \SpecialChar ~
11038 \SpecialChar ~
11039 \SpecialChar ~
11040 \SpecialChar ~
11041 \SpecialChar ~
11042 /* _asm nop _endasm; */\SpecialChar ~
11043 \SpecialChar ~
11044 \SpecialChar ~
11045 \SpecialChar ~
11046 \SpecialChar ~
11047 \SpecialChar ~
11048 \SpecialChar ~
11049 \SpecialChar ~
11050 /* for slow peripherals */
11051 \newline
11052 \SpecialChar ~
11053 \SpecialChar ~
11054 \SpecialChar ~
11055 \SpecialChar ~
11056 \SpecialChar ~
11057 \SpecialChar ~
11058 \SpecialChar ~
11059 \SpecialChar ~
11060 if(MISO)
11061 \newline
11062 \SpecialChar ~
11063 \SpecialChar ~
11064 \SpecialChar ~
11065 \SpecialChar ~
11066 \SpecialChar ~
11067 \SpecialChar ~
11068 \SpecialChar ~
11069 \SpecialChar ~
11070 \SpecialChar ~
11071 \SpecialChar ~
11072 \SpecialChar ~
11073 \SpecialChar ~
11074 out_byte += 1;
11075 \newline
11076 \SpecialChar ~
11077 \SpecialChar ~
11078 \SpecialChar ~
11079 \SpecialChar ~
11080 \SpecialChar ~
11081 \SpecialChar ~
11082 \SpecialChar ~
11083 \SpecialChar ~
11084 MCLK = 0;
11085 \newline
11086 \SpecialChar ~
11087 \SpecialChar ~
11088 \SpecialChar ~
11089 \SpecialChar ~
11090 } while(--i);
11091 \newline
11092 \SpecialChar ~
11093 \SpecialChar ~
11094 \SpecialChar ~
11095 \SpecialChar ~
11096 return out_byte;
11097 \newline
11098 }
11099 \layout Standard
11100
11101 Then, someplace in the code for the first hardware you would use
11102 \layout Verse
11103
11104
11105 \family typewriter
11106 __bit __at
11107 \begin_inset LatexCommand \index{at}
11108
11109 \end_inset
11110
11111
11112 \begin_inset LatexCommand \index{\_\_at}
11113
11114 \end_inset
11115
11116  (0x80) MOSI;\SpecialChar ~
11117 \SpecialChar ~
11118 \SpecialChar ~
11119 \SpecialChar ~
11120 /* I/O port 0, bit 0 */
11121 \newline
11122 __bit __at (0x81) MISO;\SpecialChar ~
11123 \SpecialChar ~
11124 \SpecialChar ~
11125 \SpecialChar ~
11126 /* I/O port 0, bit 1 */
11127 \newline
11128 __bit __at (0x82) MCLK;\SpecialChar ~
11129 \SpecialChar ~
11130 \SpecialChar ~
11131 \SpecialChar ~
11132 /* I/O port 0, bit 2 */
11133 \layout Standard
11134
11135 Similarly, for the second hardware you would use
11136 \layout Verse
11137
11138
11139 \family typewriter
11140 __bit __at (0x83) MOSI;\SpecialChar ~
11141 \SpecialChar ~
11142 \SpecialChar ~
11143 \SpecialChar ~
11144 /* I/O port 0, bit 3 */
11145 \newline
11146 __bit __at (0x91) MISO;\SpecialChar ~
11147 \SpecialChar ~
11148 \SpecialChar ~
11149 \SpecialChar ~
11150 /* I/O port 1, bit 1 */
11151 \newline
11152 __bit
11153 \begin_inset LatexCommand \index{bit}
11154
11155 \end_inset
11156
11157  __at (0x92) MCLK;\SpecialChar ~
11158 \SpecialChar ~
11159 \SpecialChar ~
11160 \SpecialChar ~
11161 /* I/O port 1, bit 2 */
11162 \layout Standard
11163 \added_space_bottom bigskip
11164 and you can use the same hardware dependent routine without changes, as
11165  for example in a library.
11166  This is somehow similar to sbit, but only one absolute address has to be
11167  specified in the whole project.
11168 \layout Section
11169
11170 Parameters
11171 \begin_inset LatexCommand \index{Parameters}
11172
11173 \end_inset
11174
11175
11176 \begin_inset LatexCommand \index{function parameter}
11177
11178 \end_inset
11179
11180  & Local Variables
11181 \begin_inset LatexCommand \index{local variables}
11182
11183 \end_inset
11184
11185
11186 \begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
11187
11188 \end_inset
11189
11190
11191 \layout Standard
11192
11193 Automatic (local) variables and parameters to functions can either be placed
11194  on the stack or in data-space.
11195  The default action of the compiler is to place these variables in the internal
11196  RAM (for small model) or external RAM (for large model).
11197  This in fact makes them similar to
11198 \emph on
11199 static
11200 \begin_inset LatexCommand \index{static}
11201
11202 \end_inset
11203
11204
11205 \emph default
11206  so by default functions are non-reentrant
11207 \begin_inset LatexCommand \index{reentrant}
11208
11209 \end_inset
11210
11211 .
11212
11213 \newline
11214
11215 \newline
11216 They can be placed on the stack
11217 \begin_inset LatexCommand \index{stack}
11218
11219 \end_inset
11220
11221  by using the
11222 \emph on
11223  -
11224 \begin_inset ERT
11225 status Collapsed
11226
11227 \layout Standard
11228
11229 \backslash
11230 /
11231 \end_inset
11232
11233 -stack-auto
11234 \begin_inset LatexCommand \index{-\/-stack-auto}
11235
11236 \end_inset
11237
11238
11239 \emph default
11240  option, by using
11241 \emph on
11242 #pragma\SpecialChar ~
11243 stackauto
11244 \emph default
11245
11246 \begin_inset LatexCommand \index{\#pragma stackauto}
11247
11248 \end_inset
11249
11250  or by using the
11251 \emph on
11252 reentrant
11253 \begin_inset LatexCommand \index{reentrant}
11254
11255 \end_inset
11256
11257
11258 \emph default
11259  keyword in the function declaration, e.g.:
11260 \layout Verse
11261
11262
11263 \family typewriter
11264 unsigned char foo(char i) __reentrant
11265 \newline
11266 {
11267 \newline
11268 \SpecialChar ~
11269 \SpecialChar ~
11270 \SpecialChar ~
11271 \SpecialChar ~
11272 ...
11273
11274 \newline
11275 }
11276 \layout Standard
11277
11278 Since stack space on 8051 is limited, the
11279 \emph on
11280 reentrant
11281 \emph default
11282 keyword or the
11283 \emph on
11284  -
11285 \begin_inset ERT
11286 status Collapsed
11287
11288 \layout Standard
11289
11290 \backslash
11291 /
11292 \end_inset
11293
11294 -stack-auto
11295 \emph default
11296  option should be used sparingly.
11297  Note that the reentrant keyword just means that the parameters & local
11298  variables will be allocated to the stack, it
11299 \emph on
11300 does not
11301 \emph default
11302  mean that the function is register bank
11303 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
11304
11305 \end_inset
11306
11307  independent.
11308 \newline
11309
11310 \newline
11311 Local variables
11312 \begin_inset LatexCommand \index{local variables}
11313
11314 \end_inset
11315
11316  can be assigned storage classes and absolute
11317 \begin_inset LatexCommand \index{Absolute addressing}
11318
11319 \end_inset
11320
11321  addresses, e.g.:
11322 \layout Verse
11323
11324
11325 \family typewriter
11326 unsigned char foo()
11327 \newline
11328 {
11329 \newline
11330 \SpecialChar ~
11331 \SpecialChar ~
11332 \SpecialChar ~
11333 \SpecialChar ~
11334 __xdata unsigned char i;
11335 \newline
11336 \SpecialChar ~
11337 \SpecialChar ~
11338 \SpecialChar ~
11339 \SpecialChar ~
11340 __bit bvar;
11341 \newline
11342 \SpecialChar ~
11343 \SpecialChar ~
11344 \SpecialChar ~
11345 \SpecialChar ~
11346 __data __at
11347 \begin_inset LatexCommand \index{at}
11348
11349 \end_inset
11350
11351  (0x31) unsigned char j;
11352 \newline
11353 \SpecialChar ~
11354 \SpecialChar ~
11355 \SpecialChar ~
11356 \SpecialChar ~
11357 ...
11358
11359 \newline
11360 }
11361 \layout Standard
11362
11363 In the above example the variable
11364 \emph on
11365 i
11366 \emph default
11367  will be allocated in the external ram,
11368 \emph on
11369 bvar
11370 \emph default
11371  in bit addressable space and
11372 \emph on
11373  j
11374 \emph default
11375  in internal ram.
11376  When compiled with
11377 \emph on
11378 -
11379 \begin_inset ERT
11380 status Collapsed
11381
11382 \layout Standard
11383
11384 \backslash
11385 /
11386 \end_inset
11387
11388 -stack-auto
11389 \emph default
11390  or when a function is declared as
11391 \emph on
11392 reentrant
11393 \emph default
11394  this should only be done for static variables.
11395 \layout Standard
11396
11397 Parameters
11398 \begin_inset LatexCommand \index{function parameter}
11399
11400 \end_inset
11401
11402  however are not allowed any storage class
11403 \begin_inset LatexCommand \index{Storage class}
11404
11405 \end_inset
11406
11407 , (storage classes for parameters will be ignored), their allocation is
11408  governed by the memory model in use, and the reentrancy options.
11409 \layout Standard
11410
11411 It is however allowed to use bit parameters in reentrant functions and also
11412  non-static local bit variables are supported.
11413  Efficient use is limited to 8 semi-bitregisters in bit space.
11414  They are pushed and popped to stack
11415 \begin_inset LatexCommand \index{stack}
11416
11417 \end_inset
11418
11419  as a single byte just like the normal registers.
11420 \layout Section
11421
11422 Overlaying
11423 \begin_inset LatexCommand \label{sub:Overlaying}
11424
11425 \end_inset
11426
11427
11428 \begin_inset LatexCommand \index{Overlaying}
11429
11430 \end_inset
11431
11432
11433 \layout Standard
11434
11435 For non-reentrant
11436 \begin_inset LatexCommand \index{reentrant}
11437
11438 \end_inset
11439
11440  functions SDCC will try to reduce internal ram space usage by overlaying
11441  parameters and local variables of a function (if possible).
11442  Parameters and local variables
11443 \begin_inset LatexCommand \index{local variables}
11444
11445 \end_inset
11446
11447  of a function will be allocated to an overlayable segment if the function
11448  has
11449 \emph on
11450 no other function calls and the function is non-reentrant and the memory
11451  model
11452 \begin_inset LatexCommand \index{Memory model}
11453
11454 \end_inset
11455
11456  is small.
11457
11458 \emph default
11459  If an explicit storage class
11460 \begin_inset LatexCommand \index{Storage class}
11461
11462 \end_inset
11463
11464  is specified for a local variable, it will NOT be overlayed.
11465 \layout Standard
11466
11467 Note that the compiler (not the linkage editor) makes the decision for overlayin
11468 g the data items.
11469  Functions that are called from an interrupt service routine
11470 \begin_inset Marginal
11471 collapsed true
11472
11473 \layout Standard
11474
11475
11476 \series bold
11477 !
11478 \end_inset
11479
11480  should be preceded by a #pragma\SpecialChar ~
11481 nooverlay
11482 \begin_inset LatexCommand \index{\#pragma nooverlay}
11483
11484 \end_inset
11485
11486  if they are not reentrant.
11487 \layout Standard
11488
11489 Also note that the compiler does not do any processing of inline assembler
11490  code, so the compiler might incorrectly assign local variables and parameters
11491  of a function into the overlay segment if the inline assembler code calls
11492  other c-functions that might use the overlay.
11493  In that case the #pragma\SpecialChar ~
11494 nooverlay should be used.
11495 \layout Standard
11496
11497 Parameters and local variables of functions that contain 16 or 32 bit multiplica
11498 tion
11499 \begin_inset LatexCommand \index{Multiplication}
11500
11501 \end_inset
11502
11503  or division
11504 \begin_inset LatexCommand \index{Division}
11505
11506 \end_inset
11507
11508  will NOT be overlayed since these are implemented using external functions,
11509  e.g.:
11510 \layout Verse
11511
11512
11513 \family typewriter
11514 #pragma save
11515 \newline
11516 #pragma nooverlay
11517 \begin_inset LatexCommand \index{\#pragma nooverlay}
11518
11519 \end_inset
11520
11521
11522 \newline
11523 void set_error(unsigned char errcd)
11524 \newline
11525 {
11526 \newline
11527 \SpecialChar ~
11528 \SpecialChar ~
11529 \SpecialChar ~
11530 \SpecialChar ~
11531 P3 = errcd;
11532 \newline
11533 }
11534 \newline
11535 #pragma restore
11536 \newline
11537
11538 \newline
11539 void some_isr () __interrupt
11540 \begin_inset LatexCommand \index{interrupt}
11541
11542 \end_inset
11543
11544  (2)
11545 \newline
11546 {
11547 \newline
11548 \SpecialChar ~
11549 \SpecialChar ~
11550 \SpecialChar ~
11551 \SpecialChar ~
11552 ...
11553 \newline
11554 \SpecialChar ~
11555 \SpecialChar ~
11556 \SpecialChar ~
11557 \SpecialChar ~
11558 set_error(10);
11559 \newline
11560 \SpecialChar ~
11561 \SpecialChar ~
11562 \SpecialChar ~
11563 \SpecialChar ~
11564 ...
11565
11566 \newline
11567 }
11568 \layout Standard
11569 \added_space_bottom bigskip
11570 In the above example the parameter
11571 \emph on
11572 errcd
11573 \emph default
11574  for the function
11575 \emph on
11576 set_error
11577 \emph default
11578  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
11579 nooverlay was
11580  not present, this could cause unpredictable runtime behavior when called
11581  from an interrupt service routine.
11582  The #pragma\SpecialChar ~
11583 nooverlay ensures that the parameters and local variables for
11584  the function are NOT overlayed.
11585 \layout Section
11586
11587 Interrupt Service Routines
11588 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
11589
11590 \end_inset
11591
11592
11593 \layout Subsection
11594
11595 General Information
11596 \layout Standard
11597
11598 SDCC allows
11599 \emph on
11600 i
11601 \emph default
11602 nterrupt
11603 \emph on
11604 s
11605 \emph default
11606 ervice
11607 \emph on
11608 r
11609 \emph default
11610 outines to be coded in C, with some extended keywords.
11611 \layout Verse
11612
11613
11614 \family typewriter
11615 void timer_isr (void) __interrupt (1) __using (1)
11616 \newline
11617 {
11618 \newline
11619 \SpecialChar ~
11620 \SpecialChar ~
11621 \SpecialChar ~
11622 \SpecialChar ~
11623 ...
11624
11625 \newline
11626 }
11627 \layout Standard
11628
11629 The optional number following the
11630 \emph on
11631 interrupt
11632 \begin_inset LatexCommand \index{interrupt}
11633
11634 \end_inset
11635
11636
11637 \begin_inset LatexCommand \index{\_\_interrupt}
11638
11639 \end_inset
11640
11641
11642 \emph default
11643  keyword is the interrupt number this routine will service.
11644  When present, the compiler will insert a call to this routine in the interrupt
11645  vector table
11646 \begin_inset LatexCommand \index{interrupt vector table}
11647
11648 \end_inset
11649
11650  for the interrupt number specified.
11651  If you have multiple source files in your project, interrupt service routines
11652  can be present in any of them, but a prototype of the isr MUST be present
11653  or included in the file that contains the function
11654 \emph on
11655 main
11656 \emph default
11657 .
11658  The optional (8051 specific) keyword
11659 \emph on
11660 using
11661 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11662
11663 \end_inset
11664
11665
11666 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11667
11668 \end_inset
11669
11670
11671 \emph default
11672  can be used to tell the compiler to use the specified register bank when
11673  generating code for this function.
11674
11675 \newline
11676 Interrupt service routines open the door for some very interesting bugs:
11677 \layout Subsubsection
11678
11679
11680 \begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-volatile}
11681
11682 \end_inset
11683
11684 Common interrupt pitfall: variable not declared
11685 \emph on
11686 volatile
11687 \layout Standard
11688
11689 If an interrupt service routine changes variables which are accessed by
11690  other functions these variables have to be declared
11691 \emph on
11692 volatile
11693 \emph default
11694
11695 \begin_inset LatexCommand \index{volatile}
11696
11697 \end_inset
11698
11699 .
11700  See
11701 \begin_inset LatexCommand \url{http://en.wikipedia.org/wiki/Volatile_variable}
11702
11703 \end_inset
11704
11705  .
11706 \layout Subsubsection
11707
11708
11709 \begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-non-atomic}
11710
11711 \end_inset
11712
11713 Common interrupt pitfall:
11714 \emph on
11715 non-atomic access
11716 \layout Standard
11717
11718 If the access to these variables is not
11719 \emph on
11720 atomic
11721 \begin_inset LatexCommand \index{atomic}
11722
11723 \end_inset
11724
11725
11726 \emph default
11727  (i.e.
11728  the processor needs more than one instruction for the access and could
11729  be interrupted while accessing the variable) the interrupt must be disabled
11730  during the access to avoid inconsistent data.
11731
11732 \newline
11733 Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs and
11734  should be protected by disabling interrupts.
11735  You're not automatically on the safe side if you use 8 bit variables though.
11736  We need an example here: f.e.
11737  on the 8051 the harmless looking
11738 \begin_inset Quotes srd
11739 \end_inset
11740
11741
11742 \family typewriter
11743 flags\SpecialChar ~
11744 |=\SpecialChar ~
11745 0x80;
11746 \family default
11747
11748 \begin_inset Quotes sld
11749 \end_inset
11750
11751  is not atomic if
11752 \family typewriter
11753 flags
11754 \family default
11755  resides in xdata.
11756  Setting
11757 \begin_inset Quotes srd
11758 \end_inset
11759
11760
11761 \family typewriter
11762 flags\SpecialChar ~
11763 |=\SpecialChar ~
11764 0x40;
11765 \family default
11766
11767 \begin_inset Quotes sld
11768 \end_inset
11769
11770  from within an interrupt routine might get lost if the interrupt occurs
11771  at the wrong time.
11772
11773 \begin_inset Quotes sld
11774 \end_inset
11775
11776
11777 \family typewriter
11778 counter\SpecialChar ~
11779 +=\SpecialChar ~
11780 8;
11781 \family default
11782
11783 \begin_inset Quotes srd
11784 \end_inset
11785
11786  is not atomic on the 8051 even if
11787 \family typewriter
11788 counter
11789 \family default
11790  is located in data memory.
11791 \newline
11792 Bugs like these are hard to reproduce and can cause a lot of trouble.
11793
11794 \layout Subsubsection
11795
11796
11797 \begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-stack-overflow}
11798
11799 \end_inset
11800
11801 Common interrupt pitfall:
11802 \emph on
11803 stack overflow
11804 \layout Standard
11805
11806 The return address and the registers used in the interrupt service routine
11807  are saved on the stack
11808 \begin_inset LatexCommand \index{stack}
11809
11810 \end_inset
11811
11812  so there must be sufficient stack space.
11813  If there isn't variables or registers (or even the return address itself)
11814  will be corrupted.
11815  This
11816 \emph on
11817 stack overflow
11818 \emph default
11819
11820 \begin_inset LatexCommand \index{stack overflow}
11821
11822 \end_inset
11823
11824  is most likely to happen if the interrupt occurs during the
11825 \begin_inset Quotes sld
11826 \end_inset
11827
11828 deepest
11829 \begin_inset Quotes srd
11830 \end_inset
11831
11832  subroutine when the stack is already in use for f.e.
11833  many return addresses.
11834 \layout Subsubsection
11835
11836
11837 \begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-non-reentrant}
11838
11839 \end_inset
11840
11841 Common interrupt pitfall:
11842 \emph on
11843 use of non-reentrant functions
11844 \layout Standard
11845
11846 A special note here, int (16 bit) and long (32 bit) integer division
11847 \begin_inset LatexCommand \index{Division}
11848
11849 \end_inset
11850
11851 , multiplication
11852 \begin_inset LatexCommand \index{Multiplication}
11853
11854 \end_inset
11855
11856  & modulus
11857 \begin_inset LatexCommand \index{Modulus}
11858
11859 \end_inset
11860
11861  and floating-point
11862 \begin_inset LatexCommand \index{Floating point support}
11863
11864 \end_inset
11865
11866  operations are implemented using external support routines.
11867  If an interrupt service routine needs to do any of these operations then
11868  the support routines (as mentioned in a following section) will have to
11869  be recompiled using the
11870 \emph on
11871  -
11872 \begin_inset ERT
11873 status Collapsed
11874
11875 \layout Standard
11876
11877 \backslash
11878 /
11879 \end_inset
11880
11881 -stack-auto
11882 \begin_inset LatexCommand \index{-\/-stack-auto}
11883
11884 \end_inset
11885
11886
11887 \emph default
11888  option and the source file will need to be compiled using the
11889 \emph on
11890 -
11891 \begin_inset ERT
11892 status Collapsed
11893
11894 \layout Standard
11895
11896 \backslash
11897 /
11898 \end_inset
11899
11900 -int-long-reent
11901 \emph default
11902
11903 \begin_inset LatexCommand \index{-\/-int-long-reent}
11904
11905 \end_inset
11906
11907  compiler option.
11908
11909 \newline
11910 Note, the type promotion
11911 \begin_inset LatexCommand \index{type promotion}
11912
11913 \end_inset
11914
11915  required by ANSI C can cause 16 bit routines to be used
11916 \begin_inset Marginal
11917 collapsed true
11918
11919 \layout Standard
11920
11921
11922 \series bold
11923 \SpecialChar ~
11924 !
11925 \end_inset
11926
11927  without the programmer being aware of it.
11928  See f.e.
11929  the cast
11930 \family typewriter
11931 (unsigned char)(tail-1)
11932 \family default
11933  within the if clause in section
11934 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
11935
11936 \end_inset
11937
11938 .
11939 \layout Standard
11940 \added_space_bottom bigskip
11941 Calling other functions from an interrupt service routine is not recommended,
11942  avoid it if possible.
11943  Note that when some function is called from an interrupt service routine
11944  it should be preceded by a #pragma\SpecialChar ~
11945 nooverlay
11946 \begin_inset LatexCommand \index{\#pragma nooverlay}
11947
11948 \end_inset
11949
11950  if it is not reentrant.
11951  Furthermore nonreentrant functions should not be called from the main program
11952  while the interrupt service routine might be active.
11953  They also must not be called from low priority interrupt service routines
11954  while a high priority interrupt service routine might be active.
11955  You could use semaphores or make the function
11956 \emph on
11957  critical
11958 \emph default
11959  if all parameters are passed in registers.
11960 \newline
11961  Also see section
11962 \begin_inset LatexCommand \ref{sub:Overlaying}
11963
11964 \end_inset
11965
11966 \SpecialChar ~
11967 about Overlaying and section
11968 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
11969
11970 \end_inset
11971
11972 \SpecialChar ~
11973 about Functions using private register banks.
11974 \layout Subsection
11975
11976 MCS51/DS390 Interrupt Service Routines
11977 \layout Standard
11978
11979 Interrupt
11980 \begin_inset LatexCommand \index{interrupt}
11981
11982 \end_inset
11983
11984  numbers and the corresponding address & descriptions for the Standard 8051/8052
11985  are listed below.
11986  SDCC will automatically adjust the
11987 \begin_inset LatexCommand \index{interrupt vector table}
11988
11989 \end_inset
11990
11991  to the maximum interrupt number specified.
11992 \newline
11993
11994 \layout Standard
11995 \align center
11996
11997 \begin_inset  Tabular
11998 <lyxtabular version="3" rows="9" columns="3">
11999 <features>
12000 <column alignment="center" valignment="top" leftline="true" width="0in">
12001 <column alignment="left" valignment="top" leftline="true" width="0in">
12002 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
12003 <row topline="true" bottomline="true">
12004 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12005 \begin_inset Text
12006
12007 \layout Standard
12008
12009 Interrupt #
12010 \end_inset
12011 </cell>
12012 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12013 \begin_inset Text
12014
12015 \layout Standard
12016
12017 Description
12018 \end_inset
12019 </cell>
12020 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12021 \begin_inset Text
12022
12023 \layout Standard
12024
12025 Vector Address
12026 \end_inset
12027 </cell>
12028 </row>
12029 <row topline="true">
12030 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12031 \begin_inset Text
12032
12033 \layout Standard
12034
12035 0
12036 \end_inset
12037 </cell>
12038 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12039 \begin_inset Text
12040
12041 \layout Standard
12042
12043 External 0
12044 \end_inset
12045 </cell>
12046 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12047 \begin_inset Text
12048
12049 \layout Standard
12050
12051 0x0003
12052 \end_inset
12053 </cell>
12054 </row>
12055 <row topline="true">
12056 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12057 \begin_inset Text
12058
12059 \layout Standard
12060
12061 1
12062 \end_inset
12063 </cell>
12064 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12065 \begin_inset Text
12066
12067 \layout Standard
12068
12069 Timer 0
12070 \end_inset
12071 </cell>
12072 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12073 \begin_inset Text
12074
12075 \layout Standard
12076
12077 0x000b
12078 \end_inset
12079 </cell>
12080 </row>
12081 <row topline="true">
12082 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12083 \begin_inset Text
12084
12085 \layout Standard
12086
12087 2
12088 \end_inset
12089 </cell>
12090 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12091 \begin_inset Text
12092
12093 \layout Standard
12094
12095 External 1
12096 \end_inset
12097 </cell>
12098 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12099 \begin_inset Text
12100
12101 \layout Standard
12102
12103 0x0013
12104 \end_inset
12105 </cell>
12106 </row>
12107 <row topline="true">
12108 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12109 \begin_inset Text
12110
12111 \layout Standard
12112
12113 3
12114 \end_inset
12115 </cell>
12116 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12117 \begin_inset Text
12118
12119 \layout Standard
12120
12121 Timer 1
12122 \end_inset
12123 </cell>
12124 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12125 \begin_inset Text
12126
12127 \layout Standard
12128
12129 0x001b
12130 \end_inset
12131 </cell>
12132 </row>
12133 <row topline="true">
12134 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12135 \begin_inset Text
12136
12137 \layout Standard
12138
12139 4
12140 \end_inset
12141 </cell>
12142 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12143 \begin_inset Text
12144
12145 \layout Standard
12146
12147 Serial
12148 \end_inset
12149 </cell>
12150 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12151 \begin_inset Text
12152
12153 \layout Standard
12154
12155 0x0023
12156 \end_inset
12157 </cell>
12158 </row>
12159 <row topline="true">
12160 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12161 \begin_inset Text
12162
12163 \layout Standard
12164
12165 5
12166 \end_inset
12167 </cell>
12168 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12169 \begin_inset Text
12170
12171 \layout Standard
12172
12173 Timer 2 (8052)
12174 \end_inset
12175 </cell>
12176 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12177 \begin_inset Text
12178
12179 \layout Standard
12180
12181 0x002b
12182 \end_inset
12183 </cell>
12184 </row>
12185 <row topline="true">
12186 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12187 \begin_inset Text
12188
12189 \layout Standard
12190
12191 ...
12192 \end_inset
12193 </cell>
12194 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12195 \begin_inset Text
12196
12197 \layout Standard
12198
12199 \end_inset
12200 </cell>
12201 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12202 \begin_inset Text
12203
12204 \layout Standard
12205
12206 ...
12207 \end_inset
12208 </cell>
12209 </row>
12210 <row topline="true" bottomline="true">
12211 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12212 \begin_inset Text
12213
12214 \layout Standard
12215
12216 n
12217 \end_inset
12218 </cell>
12219 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12220 \begin_inset Text
12221
12222 \layout Standard
12223
12224 \end_inset
12225 </cell>
12226 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12227 \begin_inset Text
12228
12229 \layout Standard
12230
12231 0x0003 + 8*n
12232 \end_inset
12233 </cell>
12234 </row>
12235 </lyxtabular>
12236
12237 \end_inset
12238
12239
12240 \newline
12241
12242 \layout Standard
12243
12244 If the interrupt service routine is defined without
12245 \emph on
12246 using
12247 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
12248
12249 \end_inset
12250
12251
12252 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
12253
12254 \end_inset
12255
12256
12257 \emph default
12258  a register bank or with register bank 0 (
12259 \emph on
12260 using
12261 \emph default
12262  0), the compiler will save the registers used by itself on the stack upon
12263  entry and restore them at exit, however if such an interrupt service routine
12264  calls another function then the entire register bank will be saved on the
12265  stack.
12266  This scheme may be advantageous for small interrupt service routines which
12267  have low register usage.
12268 \layout Standard
12269 \added_space_bottom bigskip
12270 If the interrupt service routine is defined to be using a specific register
12271  bank then only
12272 \emph on
12273 a, b, dptr
12274 \emph default
12275  & psw are saved and restored, if such an interrupt service routine calls
12276  another function (using another register bank) then the entire register
12277  bank of the called function will be saved on the stack
12278 \begin_inset LatexCommand \index{stack}
12279
12280 \end_inset
12281
12282 .
12283  This scheme is recommended for larger interrupt service routines.
12284 \layout Subsection
12285
12286 HC08
12287 \begin_inset LatexCommand \index{HC08}
12288
12289 \end_inset
12290
12291  Interrupt Service Routines
12292 \layout Standard
12293 \added_space_bottom bigskip
12294 Since the number of interrupts
12295 \begin_inset LatexCommand \index{HC08!interrupt}
12296
12297 \end_inset
12298
12299  available is chip specific and the interrupt vector table always ends at
12300  the last byte of memory, the interrupt numbers corresponds to the interrupt
12301  vectors in reverse order of address.
12302  For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
12303  2 will use the interrupt vector at 0xfffa, and so on.
12304  However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
12305  this way; instead see section
12306 \begin_inset LatexCommand \ref{sub:Startup-Code}
12307
12308 \end_inset
12309
12310  for details on customizing startup.
12311 \layout Subsection
12312
12313 Z80 Interrupt Service Routines
12314 \layout Standard
12315
12316 The Z80
12317 \begin_inset LatexCommand \index{Z80}
12318
12319 \end_inset
12320
12321  uses several different methods for determining the correct interrupt
12322 \begin_inset LatexCommand \index{Z80!interrupt}
12323
12324 \end_inset
12325
12326  vector depending on the hardware implementation.
12327  Therefore, SDCC ignores the optional interrupt number and does not attempt
12328  to generate an interrupt vector table.
12329 \layout Standard
12330
12331 By default, SDCC generates code for a maskable interrupt, which uses a RETI
12332  instruction to return from the interrupt.
12333  To write an interrupt handler for the non-maskable interrupt, which needs
12334  a RETN instruction instead, add the
12335 \emph on
12336 critical
12337 \emph default
12338  keyword:
12339 \layout Verse
12340
12341
12342 \family typewriter
12343 void nmi_isr (void) critical interrupt
12344 \newline
12345 {
12346 \newline
12347 \SpecialChar ~
12348 \SpecialChar ~
12349 \SpecialChar ~
12350 \SpecialChar ~
12351 ...
12352
12353 \newline
12354 }
12355 \layout Standard
12356 \added_space_bottom bigskip
12357 However if you need to create a non-interruptable interrupt service routine
12358  you would also require the
12359 \emph on
12360 critical
12361 \emph default
12362  keyword.
12363  To distinguish between this and an nmi_isr you must provide an interrupt
12364  number.
12365 \layout Section
12366
12367 Enabling and Disabling Interrupts
12368 \layout Subsection
12369
12370 Critical Functions and Critical Statements
12371 \layout Standard
12372
12373 A special keyword may be associated with a block or a function declaring
12374  it as
12375 \emph on
12376 critical
12377 \emph default
12378 .
12379  SDCC will generate code to disable all interrupts
12380 \begin_inset LatexCommand \index{interrupt}
12381
12382 \end_inset
12383
12384  upon entry to a critical function and restore the interrupt enable to the
12385  previous state before returning.
12386  Nesting critical functions will need one additional byte on the stack
12387 \begin_inset LatexCommand \index{stack}
12388
12389 \end_inset
12390
12391  for each call.
12392 \layout Verse
12393
12394
12395 \family typewriter
12396 int foo () __critical
12397 \begin_inset LatexCommand \index{critical}
12398
12399 \end_inset
12400
12401
12402 \begin_inset LatexCommand \index{\_\_critical}
12403
12404 \end_inset
12405
12406
12407 \newline
12408 {
12409 \newline
12410 \SpecialChar ~
12411 \SpecialChar ~
12412 \SpecialChar ~
12413 \SpecialChar ~
12414 ...
12415
12416 \newline
12417 \SpecialChar ~
12418 \SpecialChar ~
12419 \SpecialChar ~
12420 \SpecialChar ~
12421 ...
12422
12423 \newline
12424 }
12425 \layout Standard
12426
12427 The critical attribute maybe used with other attributes like
12428 \emph on
12429 reentrant.
12430 \emph default
12431
12432 \newline
12433 The keyword
12434 \emph on
12435 critical
12436 \emph default
12437  may also be used to disable interrupts more locally:
12438 \layout Verse
12439
12440
12441 \family typewriter
12442 __critical{ i++; }
12443 \layout Standard
12444
12445 More than one statement could have been included in the block.
12446 \layout Subsection
12447
12448 Enabling and Disabling Interrupts directly
12449 \layout Standard
12450
12451 Interrupts
12452 \begin_inset LatexCommand \index{interrupt}
12453
12454 \end_inset
12455
12456  can also be disabled and enabled directly (8051):
12457 \layout Verse
12458
12459
12460 \family typewriter
12461 EA = 0;\SpecialChar ~
12462 \SpecialChar ~
12463 \SpecialChar ~
12464 \SpecialChar ~
12465 \SpecialChar ~
12466 \SpecialChar ~
12467 \SpecialChar ~
12468 \SpecialChar ~
12469 \SpecialChar ~
12470 \SpecialChar ~
12471 \SpecialChar ~
12472 \SpecialChar ~
12473 or:\SpecialChar ~
12474 \SpecialChar ~
12475 \SpecialChar ~
12476 \SpecialChar ~
12477 \SpecialChar ~
12478 \SpecialChar ~
12479 \SpecialChar ~
12480 \SpecialChar ~
12481 \SpecialChar ~
12482 \SpecialChar ~
12483 \SpecialChar ~
12484 EA_SAVE = EA;
12485 \layout Verse
12486
12487
12488 \family typewriter
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 \SpecialChar ~
12519 EA = 0;
12520 \layout Verse
12521
12522
12523 \family typewriter
12524 EA = 1;\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 \SpecialChar ~
12550 ...
12551 \layout Verse
12552
12553
12554 \family typewriter
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 \SpecialChar ~
12588 EA = EA_SAVE;
12589 \layout Standard
12590
12591 On other architectures which have seperate opcodes for enabling and disabling
12592  interrupts you might want to make use of defines with inline assembly
12593 \begin_inset LatexCommand \index{Assembler routines}
12594
12595 \end_inset
12596
12597  (HC08
12598 \begin_inset LatexCommand \index{HC08!interrupt}
12599
12600 \end_inset
12601
12602 ):
12603 \layout Verse
12604
12605
12606 \family typewriter
12607 #define CLI _asm
12608 \begin_inset LatexCommand \index{\_asm}
12609
12610 \end_inset
12611
12612 \SpecialChar ~
12613 \SpecialChar ~
12614 cli\SpecialChar ~
12615 \SpecialChar ~
12616 _endasm
12617 \begin_inset LatexCommand \index{\_endasm}
12618
12619 \end_inset
12620
12621 ;
12622 \layout Verse
12623
12624
12625 \family typewriter
12626 #define SEI _asm\SpecialChar ~
12627 \SpecialChar ~
12628 sei\SpecialChar ~
12629 \SpecialChar ~
12630 _endasm;
12631 \layout Verse
12632
12633
12634 \family typewriter
12635 ...
12636 \layout Standard
12637
12638 Note: it is sometimes sufficient to disable only a specific interrupt source
12639  like f.e.
12640  a timer or serial interrupt by manipulating an
12641 \emph on
12642 interrupt mask
12643 \begin_inset LatexCommand \index{interrupt mask}
12644
12645 \end_inset
12646
12647
12648 \emph default
12649  register.
12650
12651 \layout Standard
12652
12653 Usually the time during which interrupts are disabled should be kept as
12654  short as possible.
12655  This minimizes both
12656 \emph on
12657 interrupt latency
12658 \emph default
12659
12660 \begin_inset LatexCommand \index{interrupt latency}
12661
12662 \end_inset
12663
12664  (the time between the occurrence of the interrupt and the execution of
12665  the first code in the interrupt routine) and
12666 \emph on
12667 interrupt jitter
12668 \emph default
12669
12670 \begin_inset LatexCommand \index{interrupt jitter}
12671
12672 \end_inset
12673
12674  (the difference between the shortest and the longest interrupt latency).
12675  These really are something different, f.e.
12676  a serial interrupt has to be served before its buffer overruns so it cares
12677  for the maximum interrupt latency, whereas it does not care about jitter.
12678  On a loudspeaker driven via a digital to analog converter which is fed
12679  by an interrupt a latency of a few milliseconds might be tolerable, whereas
12680  a much smaller jitter will be very audible.
12681 \layout Standard
12682
12683 You can reenable interrupts within an interrupt routine and on some architecture
12684 s you can make use of two (or more) levels of
12685 \emph on
12686 interrupt priorities
12687 \emph default
12688
12689 \begin_inset LatexCommand \index{interrupt priority}
12690
12691 \end_inset
12692
12693 .
12694  On some architectures which don't support interrupt priorities these can
12695  be implemented by manipulating the interrupt mask and reenabling interrupts
12696  within the interrupt routine.
12697  Check there is sufficient space on the stack
12698 \begin_inset LatexCommand \index{stack}
12699
12700 \end_inset
12701
12702  and don't add complexity unless you have to.
12703
12704 \layout Subsection
12705
12706 Semaphore
12707 \begin_inset LatexCommand \index{semaphore}
12708
12709 \end_inset
12710
12711  locking (mcs51/ds390)
12712 \layout Standard
12713
12714 Some architectures (mcs51/ds390) have an atomic
12715 \begin_inset LatexCommand \index{atomic}
12716
12717 \end_inset
12718
12719  bit test and
12720 \emph on
12721
12722 \emph default
12723 clear
12724 \emph on
12725
12726 \emph default
12727 instruction.
12728  These type of instructions are typically used in preemptive multitasking
12729  systems, where a routine f.e.
12730  claims the use of a data structure ('acquires a lock
12731 \begin_inset LatexCommand \index{lock}
12732
12733 \end_inset
12734
12735  on it'), makes some modifications and then releases the lock when the data
12736  structure is consistent again.
12737  The instruction may also be used if interrupt and non-interrupt code have
12738  to compete for a resource.
12739  With the atomic bit test and clear instruction interrupts
12740 \begin_inset LatexCommand \index{interrupt}
12741
12742 \end_inset
12743
12744  don't have to be disabled for the locking operation.
12745
12746 \layout Standard
12747
12748 SDCC generates this instruction if the source follows this pattern:
12749 \layout Verse
12750
12751
12752 \family typewriter
12753 volatile
12754 \begin_inset LatexCommand \index{volatile}
12755
12756 \end_inset
12757
12758  bit resource_is_free;
12759 \newline
12760
12761 \newline
12762 if (resource_is_free)
12763 \newline
12764 \SpecialChar ~
12765 \SpecialChar ~
12766 {
12767 \newline
12768 \SpecialChar ~
12769 \SpecialChar ~
12770 \SpecialChar ~
12771 \SpecialChar ~
12772 resource_is_free=0;
12773 \newline
12774 \SpecialChar ~
12775 \SpecialChar ~
12776 \SpecialChar ~
12777 \SpecialChar ~
12778 ...
12779
12780 \newline
12781 \SpecialChar ~
12782 \SpecialChar ~
12783 \SpecialChar ~
12784 \SpecialChar ~
12785 resource_is_free=1;
12786 \newline
12787 \SpecialChar ~
12788 \SpecialChar ~
12789 }
12790 \layout Standard
12791
12792 Note, mcs51 and ds390 support only an atomic
12793 \begin_inset LatexCommand \index{atomic}
12794
12795 \end_inset
12796
12797  bit test and
12798 \emph on
12799 clear
12800 \emph default
12801  instruction (as opposed to atomic bit test and
12802 \emph on
12803 set).
12804 \layout Section
12805
12806 Functions using private register banks
12807 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
12808
12809 \end_inset
12810
12811  (mcs51/ds390)
12812 \layout Standard
12813
12814 Some architectures have support for quickly changing register sets.
12815  SDCC supports this feature with the
12816 \emph on
12817 using
12818 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
12819
12820 \end_inset
12821
12822
12823 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
12824
12825 \end_inset
12826
12827
12828 \emph default
12829  attribute (which tells the compiler to use a register bank
12830 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
12831
12832 \end_inset
12833
12834  other than the default bank zero).
12835  It should only be applied to
12836 \emph on
12837 interrupt
12838 \begin_inset LatexCommand \index{interrupt}
12839
12840 \end_inset
12841
12842
12843 \emph default
12844  functions (see footnote below).
12845  This will in most circumstances make the generated ISR code more efficient
12846  since it will not have to save registers on the stack.
12847 \layout Standard
12848
12849 The
12850 \emph on
12851 using
12852 \emph default
12853  attribute will have no effect on the generated code for a
12854 \emph on
12855 non-interrupt
12856 \emph default
12857  function (but may occasionally be useful anyway
12858 \begin_inset Foot
12859 collapsed false
12860
12861 \layout Standard
12862
12863 possible exception: if a function is called ONLY from 'interrupt' functions
12864  using a particular bank, it can be declared with the same 'using' attribute
12865  as the calling 'interrupt' functions.
12866  For instance, if you have several ISRs using bank one, and all of them
12867  call memcpy(), it might make sense to create a specialized version of memcpy()
12868  'using 1', since this would prevent the ISR from having to save bank zero
12869  to the stack on entry and switch to bank zero before calling the function
12870 \end_inset
12871
12872 ).
12873 \newline
12874
12875 \emph on
12876 (pending: Note, nowadays the
12877 \emph default
12878 using
12879 \emph on
12880  attribute has an effect on
12881 \emph default
12882
12883 \emph on
12884 the generated code for a
12885 \emph default
12886 non-interrupt
12887 \emph on
12888  function
12889 \emph default
12890 .
12891 \emph on
12892 )
12893 \layout Standard
12894
12895 An
12896 \emph on
12897 interrupt
12898 \emph default
12899  function using a non-zero bank will assume that it can trash that register
12900  bank, and will not save it.
12901  Since high-priority interrupts
12902 \begin_inset LatexCommand \index{interrupts}
12903
12904 \end_inset
12905
12906
12907 \begin_inset LatexCommand \index{interrupt priority}
12908
12909 \end_inset
12910
12911  can interrupt low-priority ones on the 8051 and friends, this means that
12912  if a high-priority ISR
12913 \emph on
12914 using
12915 \emph default
12916  a particular bank occurs while processing a low-priority ISR
12917 \emph on
12918 using
12919 \emph default
12920  the same bank, terrible and bad things can happen.
12921  To prevent this, no single register bank should be
12922 \emph on
12923 used
12924 \emph default
12925  by both a high priority and a low priority ISR.
12926  This is probably most easily done by having all high priority ISRs use
12927  one bank and all low priority ISRs use another.
12928  If you have an ISR which can change priority at runtime, you're on your
12929  own: I suggest using the default bank zero and taking the small performance
12930  hit.
12931 \layout Standard
12932 \added_space_bottom bigskip
12933 It is most efficient if your ISR calls no other functions.
12934  If your ISR must call other functions, it is most efficient if those functions
12935  use the same bank as the ISR (see note 1 below); the next best is if the
12936  called functions use bank zero.
12937  It is very inefficient to call a function using a different, non-zero bank
12938  from an ISR.
12939
12940 \layout Section
12941
12942 Startup Code
12943 \begin_inset LatexCommand \label{sub:Startup-Code}
12944
12945 \end_inset
12946
12947
12948 \begin_inset LatexCommand \index{Startup code}
12949
12950 \end_inset
12951
12952
12953 \layout Subsection
12954
12955 MCS51/DS390 Startup Code
12956 \layout Standard
12957
12958 The compiler inserts a call to the C routine
12959 \emph on
12960 _sdcc_external_startup()
12961 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
12962
12963 \end_inset
12964
12965
12966 \series bold
12967 \emph default
12968
12969 \series default
12970 at the start of the CODE area.
12971  This routine is in the runtime library
12972 \begin_inset LatexCommand \index{Runtime library}
12973
12974 \end_inset
12975
12976 .
12977  By default this routine returns 0, if this routine returns a non-zero value,
12978  the static & global variable initialization will be skipped and the function
12979  main will be invoked.
12980  Otherwise static & global variables will be initialized before the function
12981  main is invoked.
12982  You could add a
12983 \emph on
12984 _sdcc_external_startup()
12985 \emph default
12986  routine to your program to override the default if you need to setup hardware
12987  or perform some other critical operation prior to static & global variable
12988  initialization
12989 \begin_inset LatexCommand \index{Variable initialization}
12990
12991 \end_inset
12992
12993 .
12994  On some mcs51 variants xdata
12995 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
12996
12997 \end_inset
12998
12999  memory has to be explicitly enabled before it can be accessed or if the
13000  watchdog
13001 \begin_inset LatexCommand \index{watchdog}
13002
13003 \end_inset
13004
13005  needs to be disabled, this is the place to do it.
13006  The startup code clears all internal data memory, 256 bytes by default,
13007  but from 0 to n-1 if
13008 \emph on
13009 -
13010 \begin_inset ERT
13011 status Collapsed
13012
13013 \layout Standard
13014
13015 \backslash
13016 /
13017 \end_inset
13018
13019 -iram-size
13020 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
13021
13022 \end_inset
13023
13024 n
13025 \emph default
13026  is used.
13027  (recommended for Chipcon CC1010).
13028 \layout Standard
13029 \added_space_bottom bigskip
13030 See also the compiler options
13031 \emph on
13032 -
13033 \begin_inset ERT
13034 status Collapsed
13035
13036 \layout Standard
13037
13038 \backslash
13039 /
13040 \end_inset
13041
13042 -no-xinit
13043 \emph default
13044 -
13045 \emph on
13046 opt
13047 \emph default
13048
13049 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
13050
13051 \end_inset
13052
13053 ,
13054 \emph on
13055 -
13056 \begin_inset ERT
13057 status Collapsed
13058
13059 \layout Standard
13060
13061 \backslash
13062 /
13063 \end_inset
13064
13065 -main-return
13066 \emph default
13067
13068 \begin_inset LatexCommand \index{-\/-main-return}
13069
13070 \end_inset
13071
13072  and section
13073 \begin_inset LatexCommand \ref{sub:MCS51-variants}
13074
13075 \end_inset
13076
13077  about MCS51-variants.
13078 \layout Subsection
13079
13080 HC08 Startup Code
13081 \layout Standard
13082 \added_space_bottom bigskip
13083 The HC08
13084 \begin_inset LatexCommand \index{HC08}
13085
13086 \end_inset
13087
13088  startup code follows the same scheme as the MCS51 startup code.
13089 \layout Subsection
13090
13091 Z80 Startup Code
13092 \layout Standard
13093 \added_space_bottom bigskip
13094 On the Z80
13095 \begin_inset LatexCommand \index{Z80}
13096
13097 \end_inset
13098
13099  the startup code is inserted by linking with crt0.o which is generated from
13100  sdcc/device/lib/z80/crt0.s.
13101  If you need a different startup code you can use the compiler option
13102 \emph on
13103 -
13104 \series bold
13105 \emph default
13106
13107 \begin_inset ERT
13108 status Collapsed
13109
13110 \layout Standard
13111
13112 \backslash
13113 /
13114 \end_inset
13115
13116
13117 \series default
13118 \emph on
13119 -no-std-crt0
13120 \emph default
13121
13122 \begin_inset LatexCommand \index{-\/-no-std-crt0}
13123
13124 \end_inset
13125
13126  and provide your own crt0.o.
13127
13128 \layout Section
13129
13130 Inline Assembler Code
13131 \begin_inset LatexCommand \index{Assembler routines}
13132
13133 \end_inset
13134
13135
13136 \layout Subsection
13137
13138 A Step by Step Introduction
13139 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
13140
13141 \end_inset
13142
13143
13144 \layout Standard
13145
13146 Starting from a small snippet of c-code this example shows for the MCS51
13147  how to use inline assembly, access variables, a function parameter and
13148  an array in xdata memory.
13149  The example uses an MCS51 here but is easily adapted for other architectures.
13150  This is a buffer routine which should be optimized:
13151 \layout Verse
13152
13153
13154 \family typewriter
13155 \size footnotesize
13156 unsigned char __far
13157 \begin_inset LatexCommand \index{far (storage class)}
13158
13159 \end_inset
13160
13161
13162 \begin_inset LatexCommand \index{\_\_far (storage class)}
13163
13164 \end_inset
13165
13166  __at
13167 \begin_inset LatexCommand \index{at}
13168
13169 \end_inset
13170
13171
13172 \begin_inset LatexCommand \index{\_\_at}
13173
13174 \end_inset
13175
13176 (0x7f00) buf[0x100];
13177 \begin_inset LatexCommand \index{Aligned array}
13178
13179 \end_inset
13180
13181
13182 \newline
13183 unsigned char head, tail;\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 \SpecialChar ~
13200 /* if interrupts
13201 \begin_inset LatexCommand \index{interrupt}
13202
13203 \end_inset
13204
13205  are involved see
13206 \newline
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 \SpecialChar ~
13252 section
13253 \begin_inset LatexCommand \ref{sub:Common-interrupt-pitfall-volatile}
13254
13255 \end_inset
13256
13257  about
13258 \series bold
13259  volatile
13260 \series default
13261  */
13262 \newline
13263
13264 \newline
13265 void to_buffer( unsigned char c )
13266 \newline
13267 {
13268 \newline
13269 \SpecialChar ~
13270 \SpecialChar ~
13271 \SpecialChar ~
13272 \SpecialChar ~
13273 if( head != (unsigned char)(tail-1) )\SpecialChar ~
13274 /* cast
13275 \series bold
13276 needed
13277 \series default
13278  to avoid promotion
13279 \begin_inset LatexCommand \index{promotion to signed int}
13280
13281 \end_inset
13282
13283
13284 \begin_inset LatexCommand \index{type promotion}
13285
13286 \end_inset
13287
13288  to integer */
13289 \begin_inset Marginal
13290 collapsed true
13291
13292 \layout Standard
13293
13294
13295 \series bold
13296 \SpecialChar ~
13297 !
13298 \end_inset
13299
13300
13301 \newline
13302 \SpecialChar ~
13303 \SpecialChar ~
13304 \SpecialChar ~
13305 \SpecialChar ~
13306 \SpecialChar ~
13307 \SpecialChar ~
13308 \SpecialChar ~
13309 \SpecialChar ~
13310 buf[ head++ ] = c;\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 \SpecialChar ~
13326 /* access to a 256 byte aligned array */
13327 \newline
13328 }
13329 \layout Standard
13330
13331 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
13332  then a corresponding buffer.asm file is generated.
13333  We define a new function
13334 \family typewriter
13335 to_buffer_asm()
13336 \family default
13337  in file buffer.c in which we cut and paste the generated code, removing
13338  unwanted comments and some ':'.
13339  Then add
13340 \begin_inset Quotes sld
13341 \end_inset
13342
13343 _asm
13344 \begin_inset Quotes srd
13345 \end_inset
13346
13347  and
13348 \begin_inset Quotes sld
13349 \end_inset
13350
13351 _endasm;
13352 \begin_inset Quotes srd
13353 \end_inset
13354
13355  to the beginning and the end of the function body:
13356 \layout Verse
13357
13358
13359 \family typewriter
13360 \size footnotesize
13361 /* With a cut and paste from the .asm file, we have something to start with.
13362 \newline
13363 \SpecialChar ~
13364 \SpecialChar ~
13365 \SpecialChar ~
13366 The function is not yet OK! (registers aren't saved) */
13367 \newline
13368 void to_buffer_asm( unsigned char c )
13369 \newline
13370 {
13371 \newline
13372 \SpecialChar ~
13373 \SpecialChar ~
13374 \SpecialChar ~
13375 \SpecialChar ~
13376 _asm
13377 \begin_inset LatexCommand \index{\_asm}
13378
13379 \end_inset
13380
13381
13382 \begin_inset LatexCommand \index{\_\_asm}
13383
13384 \end_inset
13385
13386
13387 \newline
13388 \SpecialChar ~
13389 \SpecialChar ~
13390 \SpecialChar ~
13391 \SpecialChar ~
13392 mov\SpecialChar ~
13393 \SpecialChar ~
13394 r2,dpl
13395 \newline
13396 ;buffer.c if( head != (unsigned char)(tail-1) ) \SpecialChar ~
13397 /* cast
13398 \series bold
13399 needed
13400 \series default
13401  to avoid promotion
13402 \begin_inset LatexCommand \index{promotion to signed int}
13403
13404 \end_inset
13405
13406
13407 \begin_inset LatexCommand \index{type promotion}
13408
13409 \end_inset
13410
13411  to integer */
13412 \newline
13413 \SpecialChar ~
13414 \SpecialChar ~
13415 \SpecialChar ~
13416 \SpecialChar ~
13417 mov\SpecialChar ~
13418 \SpecialChar ~
13419 a,_tail
13420 \newline
13421 \SpecialChar ~
13422 \SpecialChar ~
13423 \SpecialChar ~
13424 \SpecialChar ~
13425 dec\SpecialChar ~
13426 \SpecialChar ~
13427 a
13428 \newline
13429 \SpecialChar ~
13430 \SpecialChar ~
13431 \SpecialChar ~
13432 \SpecialChar ~
13433 mov\SpecialChar ~
13434 \SpecialChar ~
13435 r3,a
13436 \newline
13437 \SpecialChar ~
13438 \SpecialChar ~
13439 \SpecialChar ~
13440 \SpecialChar ~
13441 mov\SpecialChar ~
13442 \SpecialChar ~
13443 a,_head
13444 \newline
13445 \SpecialChar ~
13446 \SpecialChar ~
13447 \SpecialChar ~
13448 \SpecialChar ~
13449 cjne a,ar3,00106$
13450 \newline
13451 \SpecialChar ~
13452 \SpecialChar ~
13453 \SpecialChar ~
13454 \SpecialChar ~
13455 ret
13456 \newline
13457 00106$:
13458 \newline
13459 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
13460 \begin_inset LatexCommand \index{Aligned array}
13461
13462 \end_inset
13463
13464
13465 \newline
13466 \SpecialChar ~
13467 \SpecialChar ~
13468 \SpecialChar ~
13469 \SpecialChar ~
13470 mov\SpecialChar ~
13471 \SpecialChar ~
13472 r3,_head
13473 \newline
13474 \SpecialChar ~
13475 \SpecialChar ~
13476 \SpecialChar ~
13477 \SpecialChar ~
13478 inc\SpecialChar ~
13479 \SpecialChar ~
13480 _head
13481 \newline
13482 \SpecialChar ~
13483 \SpecialChar ~
13484 \SpecialChar ~
13485 \SpecialChar ~
13486 mov\SpecialChar ~
13487 \SpecialChar ~
13488 dpl,r3
13489 \newline
13490 \SpecialChar ~
13491 \SpecialChar ~
13492 \SpecialChar ~
13493 \SpecialChar ~
13494 mov\SpecialChar ~
13495 \SpecialChar ~
13496 dph,#(_buf >> 8)
13497 \newline
13498 \SpecialChar ~
13499 \SpecialChar ~
13500 \SpecialChar ~
13501 \SpecialChar ~
13502 mov\SpecialChar ~
13503 \SpecialChar ~
13504 a,r2
13505 \newline
13506 \SpecialChar ~
13507 \SpecialChar ~
13508 \SpecialChar ~
13509 \SpecialChar ~
13510 movx @dptr,a
13511 \newline
13512 00103$:
13513 \newline
13514 \SpecialChar ~
13515 \SpecialChar ~
13516 \SpecialChar ~
13517 \SpecialChar ~
13518 ret
13519 \newline
13520 \SpecialChar ~
13521 \SpecialChar ~
13522 \SpecialChar ~
13523 \SpecialChar ~
13524 _endasm
13525 \begin_inset LatexCommand \index{\_endasm}
13526
13527 \end_inset
13528
13529
13530 \begin_inset LatexCommand \index{\_\_endasm}
13531
13532 \end_inset
13533
13534 ;
13535 \newline
13536 }
13537 \layout Standard
13538
13539 The new file buffer.c should compile with only one warning about the unreferenced
13540  function argument 'c'.
13541  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
13542  (1) and finally have:
13543 \layout Verse
13544
13545
13546 \family typewriter
13547 \size footnotesize
13548 unsigned char __far __at(0x7f00) buf[0x100];
13549 \newline
13550 unsigned char head, tail;
13551 \newline
13552 #define USE_ASSEMBLY (1)
13553 \newline
13554
13555 \newline
13556 #if !USE_ASSEMBLY
13557 \newline
13558
13559 \newline
13560 void to_buffer( unsigned char c )
13561 \newline
13562 {
13563 \newline
13564 \SpecialChar ~
13565 \SpecialChar ~
13566 \SpecialChar ~
13567 \SpecialChar ~
13568 if( head != (unsigned char)(tail-1) )
13569 \newline
13570 \SpecialChar ~
13571 \SpecialChar ~
13572 \SpecialChar ~
13573 \SpecialChar ~
13574 \SpecialChar ~
13575 \SpecialChar ~
13576 \SpecialChar ~
13577 \SpecialChar ~
13578 buf[ head++ ] = c;
13579 \newline
13580 }
13581 \newline
13582
13583 \newline
13584 #else
13585 \newline
13586
13587 \newline
13588 void to_buffer( unsigned char c )
13589 \newline
13590 {
13591 \newline
13592 \SpecialChar ~
13593 \SpecialChar ~
13594 \SpecialChar ~
13595 \SpecialChar ~
13596 c; // to avoid warning: unreferenced function argument
13597 \newline
13598 \SpecialChar ~
13599 \SpecialChar ~
13600 \SpecialChar ~
13601 \SpecialChar ~
13602 _asm
13603 \begin_inset LatexCommand \index{\_asm}
13604
13605 \end_inset
13606
13607
13608 \begin_inset LatexCommand \index{\_\_asm}
13609
13610 \end_inset
13611
13612
13613 \newline
13614 \SpecialChar ~
13615 \SpecialChar ~
13616 \SpecialChar ~
13617 \SpecialChar ~
13618 \SpecialChar ~
13619 \SpecialChar ~
13620 \SpecialChar ~
13621 \SpecialChar ~
13622 ; save used registers here.
13623
13624 \newline
13625 \SpecialChar ~
13626 \SpecialChar ~
13627 \SpecialChar ~
13628 \SpecialChar ~
13629 \SpecialChar ~
13630 \SpecialChar ~
13631 \SpecialChar ~
13632 \SpecialChar ~
13633 ; If we were still using r2,r3 we would have to push them here.
13634
13635 \newline
13636 ; if( head != (unsigned char)(tail-1) )
13637 \newline
13638 \SpecialChar ~
13639 \SpecialChar ~
13640 \SpecialChar ~
13641 \SpecialChar ~
13642 \SpecialChar ~
13643 \SpecialChar ~
13644 \SpecialChar ~
13645 \SpecialChar ~
13646 mov\SpecialChar ~
13647  a,_tail
13648 \newline
13649 \SpecialChar ~
13650 \SpecialChar ~
13651 \SpecialChar ~
13652 \SpecialChar ~
13653 \SpecialChar ~
13654 \SpecialChar ~
13655 \SpecialChar ~
13656 \SpecialChar ~
13657 dec\SpecialChar ~
13658  a
13659 \newline
13660 \SpecialChar ~
13661 \SpecialChar ~
13662 \SpecialChar ~
13663 \SpecialChar ~
13664 \SpecialChar ~
13665 \SpecialChar ~
13666 \SpecialChar ~
13667 \SpecialChar ~
13668 xrl\SpecialChar ~
13669  a,_head
13670 \newline
13671 \SpecialChar ~
13672 \SpecialChar ~
13673 \SpecialChar ~
13674 \SpecialChar ~
13675 \SpecialChar ~
13676 \SpecialChar ~
13677 \SpecialChar ~
13678 \SpecialChar ~
13679 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
13680 \newline
13681 \SpecialChar ~
13682 \SpecialChar ~
13683 \SpecialChar ~
13684 \SpecialChar ~
13685 \SpecialChar ~
13686 \SpecialChar ~
13687 \SpecialChar ~
13688 \SpecialChar ~
13689 jz\SpecialChar ~
13690 \SpecialChar ~
13691  t_b_end$
13692 \newline
13693 \SpecialChar ~
13694 \SpecialChar ~
13695 \SpecialChar ~
13696 \SpecialChar ~
13697 \SpecialChar ~
13698 \SpecialChar ~
13699 \SpecialChar ~
13700 \SpecialChar ~
13701 ;
13702 \newline
13703 ; buf[ head++ ] = c;
13704 \newline
13705 \SpecialChar ~
13706 \SpecialChar ~
13707 \SpecialChar ~
13708 \SpecialChar ~
13709 \SpecialChar ~
13710 \SpecialChar ~
13711 \SpecialChar ~
13712 \SpecialChar ~
13713 mov\SpecialChar ~
13714  a,dpl \SpecialChar ~
13715 \SpecialChar ~
13716 \SpecialChar ~
13717 \SpecialChar ~
13718 \SpecialChar ~
13719 \SpecialChar ~
13720 \SpecialChar ~
13721 ; dpl holds lower byte of function argument
13722 \newline
13723 \SpecialChar ~
13724 \SpecialChar ~
13725 \SpecialChar ~
13726 \SpecialChar ~
13727 \SpecialChar ~
13728 \SpecialChar ~
13729 \SpecialChar ~
13730 \SpecialChar ~
13731 mov\SpecialChar ~
13732  dpl,_head \SpecialChar ~
13733 \SpecialChar ~
13734 \SpecialChar ~
13735 ; buf is 0x100 byte aligned so head can be used directly
13736 \newline
13737 \SpecialChar ~
13738 \SpecialChar ~
13739 \SpecialChar ~
13740 \SpecialChar ~
13741 \SpecialChar ~
13742 \SpecialChar ~
13743 \SpecialChar ~
13744 \SpecialChar ~
13745 mov\SpecialChar ~
13746  dph,#(_buf>>8)
13747 \newline
13748 \SpecialChar ~
13749 \SpecialChar ~
13750 \SpecialChar ~
13751 \SpecialChar ~
13752 \SpecialChar ~
13753 \SpecialChar ~
13754 \SpecialChar ~
13755 \SpecialChar ~
13756 movx @dptr,a
13757 \newline
13758 \SpecialChar ~
13759 \SpecialChar ~
13760 \SpecialChar ~
13761 \SpecialChar ~
13762 \SpecialChar ~
13763 \SpecialChar ~
13764 \SpecialChar ~
13765 \SpecialChar ~
13766 inc \SpecialChar ~
13767 _head
13768 \newline
13769 \SpecialChar ~
13770 \SpecialChar ~
13771 \SpecialChar ~
13772 \SpecialChar ~
13773 \SpecialChar ~
13774 \SpecialChar ~
13775 \SpecialChar ~
13776 \SpecialChar ~
13777 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
13778 \newline
13779 t_b_end$:
13780 \newline
13781 \SpecialChar ~
13782 \SpecialChar ~
13783 \SpecialChar ~
13784 \SpecialChar ~
13785 \SpecialChar ~
13786 \SpecialChar ~
13787 \SpecialChar ~
13788 \SpecialChar ~
13789 ; restore used registers here
13790 \newline
13791 \SpecialChar ~
13792 \SpecialChar ~
13793 \SpecialChar ~
13794 \SpecialChar ~
13795 _endasm
13796 \begin_inset LatexCommand \index{\_endasm}
13797
13798 \end_inset
13799
13800
13801 \begin_inset LatexCommand \index{\_\_endasm}
13802
13803 \end_inset
13804
13805 ;
13806 \newline
13807 }
13808 \newline
13809 #endif
13810 \layout Standard
13811
13812 The inline assembler code can contain any valid code understood by the assembler
13813 , this includes any assembler directives and comment lines.
13814  The assembler does not like some characters like ':' or ''' in comments.
13815  You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
13816 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
13817
13818 \end_inset
13819
13820
13821 \begin_inset LatexCommand \index{Assembler documentation}
13822
13823 \end_inset
13824
13825  or online at
13826 \begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/as/doc/asxhtm.html}
13827
13828 \end_inset
13829
13830 \SpecialChar ~
13831 .
13832 \layout Standard
13833
13834 The compiler does not do any validation of the code within the
13835 \family typewriter
13836 _asm
13837 \begin_inset LatexCommand \index{\_asm}
13838
13839 \end_inset
13840
13841
13842 \begin_inset LatexCommand \index{\_\_asm}
13843
13844 \end_inset
13845
13846  ...
13847  _endasm
13848 \size footnotesize
13849
13850 \begin_inset LatexCommand \index{\_endasm}
13851
13852 \end_inset
13853
13854
13855 \begin_inset LatexCommand \index{\_\_endasm}
13856
13857 \end_inset
13858
13859
13860 \size default
13861 ;
13862 \family default
13863  keyword pair.
13864  Specifically it will not know which registers are used and thus register
13865  pushing/popping
13866 \begin_inset LatexCommand \index{push/pop}
13867
13868 \end_inset
13869
13870  has to be done manually.
13871
13872 \layout Standard
13873
13874 It is recommended that each assembly instruction (including labels) be placed
13875  in a separate line (as the example shows).
13876  When the -
13877 \begin_inset ERT
13878 status Collapsed
13879
13880 \layout Standard
13881
13882 \backslash
13883 /
13884 \end_inset
13885
13886 -
13887 \emph on
13888 peep-asm
13889 \begin_inset LatexCommand \index{-\/-peep-asm}
13890
13891 \end_inset
13892
13893
13894 \emph default
13895  command line option is used, the inline assembler code will be passed through
13896  the peephole optimizer
13897 \begin_inset LatexCommand \index{Peephole optimizer}
13898
13899 \end_inset
13900
13901 .
13902  There are only a few (if any) cases where this option makes sense, it might
13903  cause some unexpected changes in the inline assembler code.
13904  Please go through the peephole optimizer rules defined in file
13905 \emph on
13906 SDCCpeeph.def
13907 \emph default
13908  before using this option.
13909 \layout Subsection
13910
13911 Naked Functions
13912 \begin_inset LatexCommand \label{sub:Naked-Functions}
13913
13914 \end_inset
13915
13916
13917 \begin_inset LatexCommand \index{Naked functions}
13918
13919 \end_inset
13920
13921
13922 \layout Standard
13923
13924 A special keyword may be associated with a function declaring it as
13925 \emph on
13926 _naked
13927 \begin_inset LatexCommand \index{\_naked}
13928
13929 \end_inset
13930
13931
13932 \begin_inset LatexCommand \index{\_\_naked}
13933
13934 \end_inset
13935
13936 .
13937
13938 \emph default
13939 The
13940 \emph on
13941 _naked
13942 \emph default
13943  function modifier attribute prevents the compiler from generating prologue
13944 \begin_inset LatexCommand \index{function prologue}
13945
13946 \end_inset
13947
13948  and epilogue
13949 \begin_inset LatexCommand \index{function epilogue}
13950
13951 \end_inset
13952
13953  code for that function.
13954  This means that the user is entirely responsible for such things as saving
13955  any registers that may need to be preserved, selecting the proper register
13956  bank, generating the
13957 \emph on
13958 return
13959 \emph default
13960  instruction at the end, etc.
13961  Practically, this means that the contents of the function must be written
13962  in inline assembler.
13963  This is particularly useful for interrupt functions, which can have a large
13964  (and often unnecessary) prologue/epilogue.
13965  For example, compare the code generated by these two functions:
13966 \layout Verse
13967
13968
13969 \family typewriter
13970 volatile
13971 \begin_inset LatexCommand \index{volatile}
13972
13973 \end_inset
13974
13975  data unsigned char counter;
13976 \newline
13977
13978 \newline
13979 void simpleInterrupt(void) __interrupt
13980 \begin_inset LatexCommand \index{interrupt}
13981
13982 \end_inset
13983
13984
13985 \begin_inset LatexCommand \index{\_\_interrupt}
13986
13987 \end_inset
13988
13989  (1)
13990 \newline
13991 {
13992 \newline
13993 \SpecialChar ~
13994 \SpecialChar ~
13995 \SpecialChar ~
13996 \SpecialChar ~
13997 counter++;
13998 \newline
13999 }
14000 \newline
14001
14002 \newline
14003 void nakedInterrupt(void) __interrupt (2) __naked
14004 \newline
14005 {
14006 \newline
14007 \SpecialChar ~
14008 \SpecialChar ~
14009 \SpecialChar ~
14010 \SpecialChar ~
14011 _asm
14012 \begin_inset LatexCommand \index{\_asm}
14013
14014 \end_inset
14015
14016
14017 \begin_inset LatexCommand \index{\_\_asm}
14018
14019 \end_inset
14020
14021
14022 \newline
14023 \SpecialChar ~
14024 \SpecialChar ~
14025 \SpecialChar ~
14026 \SpecialChar ~
14027 \SpecialChar ~
14028 \SpecialChar ~
14029 inc\SpecialChar ~
14030 \SpecialChar ~
14031 \SpecialChar ~
14032 \SpecialChar ~
14033 \SpecialChar ~
14034 _counter ; does not change flags, no need to save psw
14035 \newline
14036 \SpecialChar ~
14037 \SpecialChar ~
14038 \SpecialChar ~
14039 \SpecialChar ~
14040 \SpecialChar ~
14041 \SpecialChar ~
14042 reti\SpecialChar ~
14043 \SpecialChar ~
14044 \SpecialChar ~
14045 \SpecialChar ~
14046 ; MUST explicitly include ret or reti in _naked function.
14047 \newline
14048 \SpecialChar ~
14049 \SpecialChar ~
14050 \SpecialChar ~
14051 \SpecialChar ~
14052 _endasm
14053 \begin_inset LatexCommand \index{\_endasm}
14054
14055 \end_inset
14056
14057
14058 \begin_inset LatexCommand \index{\_\_endasm}
14059
14060 \end_inset
14061
14062 ;
14063 \newline
14064 }
14065 \layout Standard
14066
14067 For an 8051 target, the generated simpleInterrupt looks like:
14068 \layout Verse
14069
14070
14071 \family typewriter
14072 Note, this is an
14073 \emph on
14074 outdated
14075 \emph default
14076  example, recent versions of SDCC generate
14077 \newline
14078 the
14079 \emph on
14080 same
14081 \emph default
14082  code for simpleInterrupt() and nakedInterrupt()!
14083 \newline
14084
14085 \newline
14086 _simpleInterrupt:
14087 \newline
14088 \SpecialChar ~
14089 \SpecialChar ~
14090 \SpecialChar ~
14091 \SpecialChar ~
14092 push\SpecialChar ~
14093 \SpecialChar ~
14094 \SpecialChar ~
14095 \SpecialChar ~
14096 acc
14097 \newline
14098 \SpecialChar ~
14099 \SpecialChar ~
14100 \SpecialChar ~
14101 \SpecialChar ~
14102 push\SpecialChar ~
14103 \SpecialChar ~
14104 \SpecialChar ~
14105 \SpecialChar ~
14106 b
14107 \newline
14108 \SpecialChar ~
14109 \SpecialChar ~
14110 \SpecialChar ~
14111 \SpecialChar ~
14112 push\SpecialChar ~
14113 \SpecialChar ~
14114 \SpecialChar ~
14115 \SpecialChar ~
14116 dpl
14117 \newline
14118 \SpecialChar ~
14119 \SpecialChar ~
14120 \SpecialChar ~
14121 \SpecialChar ~
14122 push\SpecialChar ~
14123 \SpecialChar ~
14124 \SpecialChar ~
14125 \SpecialChar ~
14126 dph
14127 \newline
14128 \SpecialChar ~
14129 \SpecialChar ~
14130 \SpecialChar ~
14131 \SpecialChar ~
14132 push\SpecialChar ~
14133 \SpecialChar ~
14134 \SpecialChar ~
14135 \SpecialChar ~
14136 psw
14137 \newline
14138 \SpecialChar ~
14139 \SpecialChar ~
14140 \SpecialChar ~
14141 \SpecialChar ~
14142 mov\SpecialChar ~
14143 \SpecialChar ~
14144 \SpecialChar ~
14145 \SpecialChar ~
14146 \SpecialChar ~
14147 psw,#0x00
14148 \newline
14149 \SpecialChar ~
14150 \SpecialChar ~
14151 \SpecialChar ~
14152 \SpecialChar ~
14153 inc\SpecialChar ~
14154 \SpecialChar ~
14155 \SpecialChar ~
14156 \SpecialChar ~
14157 \SpecialChar ~
14158 _counter
14159 \newline
14160 \SpecialChar ~
14161 \SpecialChar ~
14162 \SpecialChar ~
14163 \SpecialChar ~
14164 pop\SpecialChar ~
14165 \SpecialChar ~
14166 \SpecialChar ~
14167 \SpecialChar ~
14168 \SpecialChar ~
14169 psw
14170 \newline
14171 \SpecialChar ~
14172 \SpecialChar ~
14173 \SpecialChar ~
14174 \SpecialChar ~
14175 pop\SpecialChar ~
14176 \SpecialChar ~
14177 \SpecialChar ~
14178 \SpecialChar ~
14179 \SpecialChar ~
14180 dph
14181 \newline
14182 \SpecialChar ~
14183 \SpecialChar ~
14184 \SpecialChar ~
14185 \SpecialChar ~
14186 pop\SpecialChar ~
14187 \SpecialChar ~
14188 \SpecialChar ~
14189 \SpecialChar ~
14190 \SpecialChar ~
14191 dpl
14192 \newline
14193 \SpecialChar ~
14194 \SpecialChar ~
14195 \SpecialChar ~
14196 \SpecialChar ~
14197 pop\SpecialChar ~
14198 \SpecialChar ~
14199 \SpecialChar ~
14200 \SpecialChar ~
14201 \SpecialChar ~
14202 b
14203 \newline
14204 \SpecialChar ~
14205 \SpecialChar ~
14206 \SpecialChar ~
14207 \SpecialChar ~
14208 pop\SpecialChar ~
14209 \SpecialChar ~
14210 \SpecialChar ~
14211 \SpecialChar ~
14212 \SpecialChar ~
14213 acc
14214 \newline
14215 \SpecialChar ~
14216 \SpecialChar ~
14217 \SpecialChar ~
14218 \SpecialChar ~
14219 reti
14220 \layout Standard
14221
14222 whereas nakedInterrupt looks like:
14223 \layout Verse
14224
14225
14226 \family typewriter
14227 _nakedInterrupt:
14228 \newline
14229 \SpecialChar ~
14230 \SpecialChar ~
14231 \SpecialChar ~
14232 \SpecialChar ~
14233 inc\SpecialChar ~
14234 \SpecialChar ~
14235 \SpecialChar ~
14236 \SpecialChar ~
14237 _counter ; does not change flags, no need to save psw
14238 \newline
14239 \SpecialChar ~
14240 \SpecialChar ~
14241 \SpecialChar ~
14242 \SpecialChar ~
14243 reti\SpecialChar ~
14244 \SpecialChar ~
14245 \SpecialChar ~
14246 \SpecialChar ~
14247 \SpecialChar ~
14248 \SpecialChar ~
14249 \SpecialChar ~
14250 \SpecialChar ~
14251 \SpecialChar ~
14252 \SpecialChar ~
14253 \SpecialChar ~
14254 \SpecialChar ~
14255 ; MUST explicitly include ret or reti in _naked function
14256 \layout Standard
14257
14258 The related directive #pragma exclude
14259 \begin_inset LatexCommand \index{\#pragma exclude}
14260
14261 \end_inset
14262
14263  allows a more fine grained control over pushing & popping
14264 \begin_inset LatexCommand \index{push/pop}
14265
14266 \end_inset
14267
14268  the registers.
14269 \layout Standard
14270
14271 While there is nothing preventing you from writing C code inside a
14272 \family typewriter
14273 _naked
14274 \family default
14275  function, there are many ways to shoot yourself in the foot doing this,
14276  and it is recommended that you stick to inline assembler.
14277 \layout Subsection
14278
14279 Use of Labels within Inline Assembler
14280 \layout Standard
14281
14282 SDCC allows the use of in-line assembler with a few restrictions regarding
14283  labels.
14284  In older versions of the compiler all labels defined within inline assembler
14285  code
14286 \emph on
14287 had to be
14288 \emph default
14289  of the form
14290 \emph on
14291 nnnnn$
14292 \emph default
14293  where nnnn is a number less than 100 (which implies a limit of utmost 100
14294  inline assembler labels
14295 \emph on
14296 per function
14297 \emph default
14298 \noun on
14299 )
14300 \noun default
14301 .
14302
14303 \layout Verse
14304
14305
14306 \family typewriter
14307 _asm
14308 \begin_inset LatexCommand \index{\_asm}
14309
14310 \end_inset
14311
14312
14313 \begin_inset LatexCommand \index{\_\_asm}
14314
14315 \end_inset
14316
14317
14318 \newline
14319 \SpecialChar ~
14320 \SpecialChar ~
14321 \SpecialChar ~
14322 \SpecialChar ~
14323 mov\SpecialChar ~
14324 \SpecialChar ~
14325 \SpecialChar ~
14326 \SpecialChar ~
14327 \SpecialChar ~
14328 b,#10
14329 \newline
14330 00001$:
14331 \newline
14332 \SpecialChar ~
14333 \SpecialChar ~
14334 \SpecialChar ~
14335 \SpecialChar ~
14336 djnz\SpecialChar ~
14337 \SpecialChar ~
14338 \SpecialChar ~
14339 \SpecialChar ~
14340 b,00001$
14341 \newline
14342 _endasm
14343 \begin_inset LatexCommand \index{\_endasm}
14344
14345 \end_inset
14346
14347
14348 \begin_inset LatexCommand \index{\_\_endasm}
14349
14350 \end_inset
14351
14352  ;
14353 \layout Standard
14354
14355 Inline assembler code cannot reference any C-Labels, however it can reference
14356  labels
14357 \begin_inset LatexCommand \index{Labels}
14358
14359 \end_inset
14360
14361  defined by the inline assembler, e.g.:
14362 \layout Verse
14363
14364
14365 \family typewriter
14366 foo() {
14367 \newline
14368 \SpecialChar ~
14369 \SpecialChar ~
14370 \SpecialChar ~
14371 \SpecialChar ~
14372 /* some c code */
14373 \newline
14374 \SpecialChar ~
14375 \SpecialChar ~
14376 \SpecialChar ~
14377 \SpecialChar ~
14378 _asm
14379 \newline
14380 \SpecialChar ~
14381 \SpecialChar ~
14382 \SpecialChar ~
14383 \SpecialChar ~
14384 \SpecialChar ~
14385 \SpecialChar ~
14386 ; some assembler code
14387 \newline
14388 \SpecialChar ~
14389 \SpecialChar ~
14390 \SpecialChar ~
14391 \SpecialChar ~
14392 \SpecialChar ~
14393 \SpecialChar ~
14394 ljmp $0003
14395 \newline
14396 \SpecialChar ~
14397 \SpecialChar ~
14398 \SpecialChar ~
14399 \SpecialChar ~
14400 _endasm;
14401 \newline
14402 \SpecialChar ~
14403 \SpecialChar ~
14404 \SpecialChar ~
14405 \SpecialChar ~
14406 /* some more c code */
14407 \newline
14408 clabel:\SpecialChar ~
14409 \SpecialChar ~
14410 /* inline assembler cannot reference this label */
14411 \newline
14412 \SpecialChar ~
14413 \SpecialChar ~
14414 \SpecialChar ~
14415 \SpecialChar ~
14416 _asm
14417 \newline
14418 \SpecialChar ~
14419 \SpecialChar ~
14420 \SpecialChar ~
14421 \SpecialChar ~
14422 $0003: ;label (can be referenced by inline assembler only)
14423 \newline
14424 \SpecialChar ~
14425 \SpecialChar ~
14426 \SpecialChar ~
14427 \SpecialChar ~
14428 _endasm
14429 \begin_inset LatexCommand \index{\_endasm}
14430
14431 \end_inset
14432
14433
14434 \begin_inset LatexCommand \index{\_\_endasm}
14435
14436 \end_inset
14437
14438  ;
14439 \newline
14440 \SpecialChar ~
14441 \SpecialChar ~
14442 \SpecialChar ~
14443 \SpecialChar ~
14444 /* some more c code */
14445 \newline
14446 }
14447 \layout Standard
14448
14449 In other words inline assembly code can access labels defined in inline
14450  assembly within the scope of the function.
14451  The same goes the other way, i.e.
14452  labels defines in inline assembly can not be accessed by C statements.
14453 \layout Section
14454
14455 Interfacing with Assembler Code
14456 \begin_inset LatexCommand \index{Assembler routines}
14457
14458 \end_inset
14459
14460
14461 \layout Subsection
14462
14463 Global Registers used for Parameter Passing
14464 \begin_inset LatexCommand \index{Parameter passing}
14465
14466 \end_inset
14467
14468
14469 \layout Standard
14470
14471 The compiler always uses the global registers
14472 \emph on
14473 DPL, DPH
14474 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
14475
14476 \end_inset
14477
14478
14479 \begin_inset LatexCommand \index{DPTR}
14480
14481 \end_inset
14482
14483 , B
14484 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
14485
14486 \end_inset
14487
14488
14489 \emph default
14490 and
14491 \emph on
14492  ACC
14493 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
14494
14495 \end_inset
14496
14497
14498 \emph default
14499  to pass the first parameter to a routine.
14500  The second parameter onwards is either allocated on the stack (for reentrant
14501  routines or if -
14502 \begin_inset ERT
14503 status Collapsed
14504
14505 \layout Standard
14506
14507 \backslash
14508 /
14509 \end_inset
14510
14511 -stack-auto is used) or in data / xdata memory (depending on the memory
14512  model).
14513
14514 \layout Subsection
14515
14516 Assembler Routine (non-reentrant)
14517 \layout Standard
14518
14519 In the following example
14520 \begin_inset LatexCommand \index{reentrant}
14521
14522 \end_inset
14523
14524
14525 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
14526
14527 \end_inset
14528
14529  the function c_func calls an assembler routine asm_func, which takes two
14530  parameters
14531 \begin_inset LatexCommand \index{function parameter}
14532
14533 \end_inset
14534
14535 .
14536 \layout Verse
14537
14538
14539 \family typewriter
14540 extern int asm_func(unsigned char, unsigned char);
14541 \newline
14542
14543 \newline
14544 int c_func (unsigned char i, unsigned char j)
14545 \newline
14546 {
14547 \newline
14548 \SpecialChar ~
14549 \SpecialChar ~
14550 \SpecialChar ~
14551 \SpecialChar ~
14552 return asm_func(i,j);
14553 \newline
14554 }
14555 \newline
14556
14557 \newline
14558 int main()
14559 \newline
14560 {
14561 \newline
14562 \SpecialChar ~
14563 \SpecialChar ~
14564 \SpecialChar ~
14565 \SpecialChar ~
14566 return c_func(10,9);
14567 \newline
14568 }
14569 \layout Standard
14570
14571 The corresponding assembler function is:
14572 \layout Verse
14573
14574
14575 \family typewriter
14576 .globl _asm_func_PARM_2
14577 \newline
14578 \SpecialChar ~
14579 \SpecialChar ~
14580 \SpecialChar ~
14581 \SpecialChar ~
14582 \SpecialChar ~
14583 \SpecialChar ~
14584 \SpecialChar ~
14585 \SpecialChar ~
14586 .globl _asm_func
14587 \newline
14588 \SpecialChar ~
14589 \SpecialChar ~
14590 \SpecialChar ~
14591 \SpecialChar ~
14592 \SpecialChar ~
14593 \SpecialChar ~
14594 \SpecialChar ~
14595 \SpecialChar ~
14596 .area OSEG
14597 \newline
14598 _asm_func_PARM_2:
14599 \newline
14600 \SpecialChar ~
14601 \SpecialChar ~
14602 \SpecialChar ~
14603 \SpecialChar ~
14604 \SpecialChar ~
14605 \SpecialChar ~
14606 \SpecialChar ~
14607 \SpecialChar ~
14608 .ds    1
14609 \newline
14610 \SpecialChar ~
14611 \SpecialChar ~
14612 \SpecialChar ~
14613 \SpecialChar ~
14614 \SpecialChar ~
14615 \SpecialChar ~
14616 \SpecialChar ~
14617 \SpecialChar ~
14618 .area CSEG
14619 \newline
14620 _asm_func:
14621 \newline
14622 \SpecialChar ~
14623 \SpecialChar ~
14624 \SpecialChar ~
14625 \SpecialChar ~
14626 \SpecialChar ~
14627 \SpecialChar ~
14628 \SpecialChar ~
14629 \SpecialChar ~
14630 mov\SpecialChar ~
14631 \SpecialChar ~
14632 \SpecialChar ~
14633 \SpecialChar ~
14634 a,dpl
14635 \newline
14636 \SpecialChar ~
14637 \SpecialChar ~
14638 \SpecialChar ~
14639 \SpecialChar ~
14640 \SpecialChar ~
14641 \SpecialChar ~
14642 \SpecialChar ~
14643 \SpecialChar ~
14644 add\SpecialChar ~
14645 \SpecialChar ~
14646 \SpecialChar ~
14647 \SpecialChar ~
14648 a,_asm_func_PARM_2
14649 \newline
14650 \SpecialChar ~
14651 \SpecialChar ~
14652 \SpecialChar ~
14653 \SpecialChar ~
14654 \SpecialChar ~
14655 \SpecialChar ~
14656 \SpecialChar ~
14657 \SpecialChar ~
14658 mov\SpecialChar ~
14659 \SpecialChar ~
14660 \SpecialChar ~
14661 \SpecialChar ~
14662 dpl,a
14663 \newline
14664 \SpecialChar ~
14665 \SpecialChar ~
14666 \SpecialChar ~
14667 \SpecialChar ~
14668 \SpecialChar ~
14669 \SpecialChar ~
14670 \SpecialChar ~
14671 \SpecialChar ~
14672 mov\SpecialChar ~
14673 \SpecialChar ~
14674 \SpecialChar ~
14675 \SpecialChar ~
14676 dph
14677 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
14678
14679 \end_inset
14680
14681 ,#0x00
14682 \newline
14683 \SpecialChar ~
14684 \SpecialChar ~
14685 \SpecialChar ~
14686 \SpecialChar ~
14687 \SpecialChar ~
14688 \SpecialChar ~
14689 \SpecialChar ~
14690 \SpecialChar ~
14691 ret
14692 \layout Standard
14693
14694 Note here that the return values
14695 \begin_inset LatexCommand \index{return value}
14696
14697 \end_inset
14698
14699  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
14700  two byte values.
14701  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
14702 b' & 'acc' for four byte values.
14703 \layout Standard
14704
14705 The parameter naming convention is _<function_name>_PARM_<n>, where n is
14706  the parameter number starting from 1, and counting from the left.
14707  The first parameter is passed in
14708 \begin_inset Quotes eld
14709 \end_inset
14710
14711 dpl
14712 \begin_inset Quotes erd
14713 \end_inset
14714
14715  for a one byte parameter,
14716 \begin_inset Quotes eld
14717 \end_inset
14718
14719 dptr
14720 \begin_inset Quotes erd
14721 \end_inset
14722
14723  for two bytes,
14724 \begin_inset Quotes eld
14725 \end_inset
14726
14727 b,dptr
14728 \begin_inset Quotes erd
14729 \end_inset
14730
14731  for three bytes and
14732 \begin_inset Quotes eld
14733 \end_inset
14734
14735 acc,b,dptr
14736 \begin_inset Quotes erd
14737 \end_inset
14738
14739  for a four bytes parameter.
14740  The variable name for the second parameter will be _<function_name>_PARM_2.
14741 \newline
14742
14743 \newline
14744 Assemble the assembler routine with the following command:
14745 \newline
14746
14747 \newline
14748
14749 \family sans
14750 \series bold
14751 asx8051 -losg asmfunc.asm
14752 \newline
14753
14754 \newline
14755
14756 \family default
14757 \series default
14758 Then compile and link the assembler routine to the C source file with the
14759  following command:
14760 \newline
14761
14762 \newline
14763
14764 \family sans
14765 \series bold
14766 sdcc cfunc.c asmfunc.rel
14767 \layout Subsection
14768
14769 Assembler Routine (reentrant)
14770 \layout Standard
14771
14772 In this case
14773 \begin_inset LatexCommand \index{reentrant}
14774
14775 \end_inset
14776
14777
14778 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
14779
14780 \end_inset
14781
14782  the second parameter
14783 \begin_inset LatexCommand \index{function parameter}
14784
14785 \end_inset
14786
14787  onwards will be passed on the stack, the parameters are pushed from right
14788  to left i.e.
14789  after the call the leftmost parameter will be on the top of the stack.
14790  Here is an example:
14791 \layout Verse
14792
14793
14794 \family typewriter
14795 extern int asm_func(unsigned char, unsigned char);
14796 \newline
14797
14798 \newline
14799 int c_func (unsigned char i, unsigned char j) reentrant
14800 \newline
14801 {
14802 \newline
14803 \SpecialChar ~
14804 \SpecialChar ~
14805 \SpecialChar ~
14806 \SpecialChar ~
14807 return asm_func(i,j);
14808 \newline
14809 }
14810 \newline
14811
14812 \newline
14813 int main()
14814 \newline
14815 {
14816 \newline
14817 \SpecialChar ~
14818 \SpecialChar ~
14819 \SpecialChar ~
14820 \SpecialChar ~
14821 return c_func(10,9);
14822 \newline
14823 }
14824 \layout Standard
14825
14826 The corresponding assembler routine is:
14827 \layout Verse
14828
14829
14830 \family typewriter
14831 .globl _asm_func
14832 \newline
14833 _asm_func:
14834 \newline
14835 \SpecialChar ~
14836 \SpecialChar ~
14837 \SpecialChar ~
14838 \SpecialChar ~
14839 push  _bp
14840 \newline
14841 \SpecialChar ~
14842 \SpecialChar ~
14843 \SpecialChar ~
14844 \SpecialChar ~
14845 mov _bp,sp
14846 \newline
14847 \SpecialChar ~
14848 \SpecialChar ~
14849 \SpecialChar ~
14850 \SpecialChar ~
14851 mov r2,dpl
14852 \newline
14853 \SpecialChar ~
14854 \SpecialChar ~
14855 \SpecialChar ~
14856 \SpecialChar ~
14857 mov a,_bp
14858 \newline
14859 \SpecialChar ~
14860 \SpecialChar ~
14861 \SpecialChar ~
14862 \SpecialChar ~
14863 add a,#0xfd
14864 \newline
14865 \SpecialChar ~
14866 \SpecialChar ~
14867 \SpecialChar ~
14868 \SpecialChar ~
14869 mov r0,a
14870 \newline
14871 \SpecialChar ~
14872 \SpecialChar ~
14873 \SpecialChar ~
14874 \SpecialChar ~
14875 add  a,#0xfc ;?
14876 \newline
14877 \SpecialChar ~
14878 \SpecialChar ~
14879 \SpecialChar ~
14880 \SpecialChar ~
14881 mov  r1,a
14882 \newline
14883 \SpecialChar ~
14884 \SpecialChar ~
14885 \SpecialChar ~
14886 \SpecialChar ~
14887 mov  a,@r0
14888 \newline
14889 \SpecialChar ~
14890 \SpecialChar ~
14891 \SpecialChar ~
14892 \SpecialChar ~
14893 add  a,r2 ;?
14894 \newline
14895 \SpecialChar ~
14896 \SpecialChar ~
14897 \SpecialChar ~
14898 \SpecialChar ~
14899 mov  dpl,a
14900 \newline
14901 \SpecialChar ~
14902 \SpecialChar ~
14903 \SpecialChar ~
14904 \SpecialChar ~
14905 mov  dph,#0x00
14906 \newline
14907 \SpecialChar ~
14908 \SpecialChar ~
14909 \SpecialChar ~
14910 \SpecialChar ~
14911 mov  sp,_bp
14912 \newline
14913 \SpecialChar ~
14914 \SpecialChar ~
14915 \SpecialChar ~
14916 \SpecialChar ~
14917 pop  _bp
14918 \newline
14919 \SpecialChar ~
14920 \SpecialChar ~
14921 \SpecialChar ~
14922 \SpecialChar ~
14923 ret
14924 \layout Standard
14925 \added_space_bottom bigskip
14926 The compiling and linking procedure remains the same, however note the extra
14927  entry & exit linkage required for the assembler code, _bp is the stack
14928  frame pointer and is used to compute the offset into the stack for parameters
14929  and local variables.
14930 \layout Section
14931
14932 int (16 bit)
14933 \begin_inset LatexCommand \index{int (16 bit)}
14934
14935 \end_inset
14936
14937  and long (32 bit)
14938 \begin_inset LatexCommand \index{long (32 bit)}
14939
14940 \end_inset
14941
14942  Support
14943 \layout Standard
14944
14945 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
14946  multiplication and modulus operations are implemented by support routines.
14947  These support routines are all developed in ANSI-C to facilitate porting
14948  to other MCUs, although some model specific assembler optimizations are
14949  used.
14950  The following files contain the described routines, all of them can be
14951  found in <installdir>/share/sdcc/lib.
14952 \newline
14953
14954 \layout Standard
14955 \align center
14956
14957 \begin_inset  Tabular
14958 <lyxtabular version="3" rows="11" columns="2">
14959 <features>
14960 <column alignment="left" valignment="top" leftline="true" width="0">
14961 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
14962 <row topline="true" bottomline="true">
14963 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14964 \begin_inset Text
14965
14966 \layout Standard
14967
14968
14969 \series bold
14970 Function
14971 \end_inset
14972 </cell>
14973 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14974 \begin_inset Text
14975
14976 \layout Standard
14977
14978
14979 \series bold
14980 Description
14981 \end_inset
14982 </cell>
14983 </row>
14984 <row topline="true">
14985 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14986 \begin_inset Text
14987
14988 \layout Standard
14989
14990 _mulint.c
14991 \end_inset
14992 </cell>
14993 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14994 \begin_inset Text
14995
14996 \layout Standard
14997
14998 16 bit multiplication
14999 \end_inset
15000 </cell>
15001 </row>
15002 <row topline="true">
15003 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15004 \begin_inset Text
15005
15006 \layout Standard
15007
15008 _divsint.c
15009 \end_inset
15010 </cell>
15011 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15012 \begin_inset Text
15013
15014 \layout Standard
15015
15016  signed 16 bit division (calls _divuint)
15017 \end_inset
15018 </cell>
15019 </row>
15020 <row topline="true">
15021 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15022 \begin_inset Text
15023
15024 \layout Standard
15025
15026 _divuint.c
15027 \end_inset
15028 </cell>
15029 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15030 \begin_inset Text
15031
15032 \layout Standard
15033
15034  unsigned 16 bit division
15035 \end_inset
15036 </cell>
15037 </row>
15038 <row topline="true">
15039 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15040 \begin_inset Text
15041
15042 \layout Standard
15043
15044 _modsint.c
15045 \end_inset
15046 </cell>
15047 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15048 \begin_inset Text
15049
15050 \layout Standard
15051
15052 signed 16 bit modulus (calls _moduint)
15053 \end_inset
15054 </cell>
15055 </row>
15056 <row topline="true">
15057 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15058 \begin_inset Text
15059
15060 \layout Standard
15061
15062 _moduint.c
15063 \end_inset
15064 </cell>
15065 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15066 \begin_inset Text
15067
15068 \layout Standard
15069
15070 unsigned 16 bit modulus
15071 \end_inset
15072 </cell>
15073 </row>
15074 <row topline="true">
15075 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15076 \begin_inset Text
15077
15078 \layout Standard
15079
15080 _mullong.c
15081 \end_inset
15082 </cell>
15083 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15084 \begin_inset Text
15085
15086 \layout Standard
15087
15088 32 bit multiplication
15089 \end_inset
15090 </cell>
15091 </row>
15092 <row topline="true">
15093 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15094 \begin_inset Text
15095
15096 \layout Standard
15097
15098 _divslong.c
15099 \end_inset
15100 </cell>
15101 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15102 \begin_inset Text
15103
15104 \layout Standard
15105
15106  signed 32 division (calls _divulong)
15107 \end_inset
15108 </cell>
15109 </row>
15110 <row topline="true">
15111 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15112 \begin_inset Text
15113
15114 \layout Standard
15115
15116 _divulong.c
15117 \end_inset
15118 </cell>
15119 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15120 \begin_inset Text
15121
15122 \layout Standard
15123
15124 unsigned 32 division
15125 \end_inset
15126 </cell>
15127 </row>
15128 <row topline="true">
15129 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15130 \begin_inset Text
15131
15132 \layout Standard
15133
15134 _modslong.c
15135 \end_inset
15136 </cell>
15137 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15138 \begin_inset Text
15139
15140 \layout Standard
15141
15142  signed 32 bit modulus (calls _modulong)
15143 \end_inset
15144 </cell>
15145 </row>
15146 <row topline="true" bottomline="true">
15147 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15148 \begin_inset Text
15149
15150 \layout Standard
15151
15152 _modulong.c
15153 \end_inset
15154 </cell>
15155 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15156 \begin_inset Text
15157
15158 \layout Standard
15159
15160 unsigned 32 bit modulus
15161 \end_inset
15162 </cell>
15163 </row>
15164 </lyxtabular>
15165
15166 \end_inset
15167
15168
15169 \newline
15170
15171 \layout Standard
15172
15173 Since they are compiled as
15174 \emph on
15175 non-reentrant
15176 \emph default
15177
15178 \begin_inset LatexCommand \index{reentrant}
15179
15180 \end_inset
15181
15182 , interrupt
15183 \begin_inset LatexCommand \index{interrupt}
15184
15185 \end_inset
15186
15187  service routines should not do any of the above operations.
15188  If this is unavoidable then the above routines will need to be compiled
15189  with the
15190 \emph on
15191 -
15192 \begin_inset ERT
15193 status Collapsed
15194
15195 \layout Standard
15196
15197 \backslash
15198 /
15199 \end_inset
15200
15201 -stack-auto
15202 \begin_inset LatexCommand \index{-\/-stack-auto}
15203
15204 \end_inset
15205
15206
15207 \emph default
15208  option, after which the source program will have to be compiled with
15209 \emph on
15210 -
15211 \begin_inset ERT
15212 status Collapsed
15213
15214 \layout Standard
15215
15216 \backslash
15217 /
15218 \end_inset
15219
15220 -int-long-reent
15221 \begin_inset LatexCommand \index{-\/-int-long-reent}
15222
15223 \end_inset
15224
15225
15226 \emph default
15227  option.
15228  Notice that you don't have to call these routines directly.
15229  The compiler will use them automatically every time an integer operation
15230  is required.
15231 \layout Section
15232
15233 Floating Point Support
15234 \begin_inset LatexCommand \index{Floating point support}
15235
15236 \end_inset
15237
15238
15239 \layout Standard
15240
15241 SDCC supports IEEE (single precision 4 bytes) floating point numbers.
15242  The floating point support routines are derived from gcc's floatlib.c and
15243  consist of the following routines:
15244 \newline
15245
15246 \layout Standard
15247 \align center
15248
15249 \size footnotesize
15250
15251 \begin_inset  Tabular
15252 <lyxtabular version="3" rows="17" columns="2">
15253 <features>
15254 <column alignment="left" valignment="top" leftline="true" width="0">
15255 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
15256 <row topline="true" bottomline="true">
15257 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15258 \begin_inset Text
15259
15260 \layout Standard
15261
15262
15263 \family roman
15264 \series medium
15265 \shape up
15266 \size normal
15267 \emph off
15268 \bar no
15269 \noun off
15270 \color none
15271 Function
15272 \end_inset
15273 </cell>
15274 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15275 \begin_inset Text
15276
15277 \layout Standard
15278
15279 Description
15280 \end_inset
15281 </cell>
15282 </row>
15283 <row topline="true">
15284 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15285 \begin_inset Text
15286
15287 \layout Standard
15288
15289
15290 \family roman
15291 \series medium
15292 \shape up
15293 \size normal
15294 \emph off
15295 \bar no
15296 \noun off
15297 \color none
15298 _fsadd.c
15299 \end_inset
15300 </cell>
15301 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15302 \begin_inset Text
15303
15304 \layout Standard
15305
15306
15307 \family roman
15308 \series medium
15309 \shape up
15310 \size normal
15311 \emph off
15312 \bar no
15313 \noun off
15314 \color none
15315 add floating point numbers
15316 \end_inset
15317 </cell>
15318 </row>
15319 <row topline="true">
15320 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15321 \begin_inset Text
15322
15323 \layout Standard
15324
15325
15326 \family roman
15327 \series medium
15328 \shape up
15329 \size normal
15330 \emph off
15331 \bar no
15332 \noun off
15333 \color none
15334 _fssub.c
15335 \end_inset
15336 </cell>
15337 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15338 \begin_inset Text
15339
15340 \layout Standard
15341
15342
15343 \family roman
15344 \series medium
15345 \shape up
15346 \size normal
15347 \emph off
15348 \bar no
15349 \noun off
15350 \color none
15351 subtract floating point numbers
15352 \end_inset
15353 </cell>
15354 </row>
15355 <row topline="true">
15356 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15357 \begin_inset Text
15358
15359 \layout Standard
15360
15361
15362 \family roman
15363 \series medium
15364 \shape up
15365 \size normal
15366 \emph off
15367 \bar no
15368 \noun off
15369 \color none
15370 _fsdiv.c
15371 \end_inset
15372 </cell>
15373 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15374 \begin_inset Text
15375
15376 \layout Standard
15377
15378
15379 \family roman
15380 \series medium
15381 \shape up
15382 \size normal
15383 \emph off
15384 \bar no
15385 \noun off
15386 \color none
15387 divide floating point numbers
15388 \end_inset
15389 </cell>
15390 </row>
15391 <row topline="true">
15392 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15393 \begin_inset Text
15394
15395 \layout Standard
15396
15397
15398 \family roman
15399 \series medium
15400 \shape up
15401 \size normal
15402 \emph off
15403 \bar no
15404 \noun off
15405 \color none
15406 _fsmul.c
15407 \end_inset
15408 </cell>
15409 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15410 \begin_inset Text
15411
15412 \layout Standard
15413
15414
15415 \family roman
15416 \series medium
15417 \shape up
15418 \size normal
15419 \emph off
15420 \bar no
15421 \noun off
15422 \color none
15423 multiply floating point numbers
15424 \end_inset
15425 </cell>
15426 </row>
15427 <row topline="true">
15428 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15429 \begin_inset Text
15430
15431 \layout Standard
15432
15433
15434 \family roman
15435 \series medium
15436 \shape up
15437 \size normal
15438 \emph off
15439 \bar no
15440 \noun off
15441 \color none
15442 _fs2uchar.c
15443 \end_inset
15444 </cell>
15445 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15446 \begin_inset Text
15447
15448 \layout Standard
15449
15450
15451 \family roman
15452 \series medium
15453 \shape up
15454 \size normal
15455 \emph off
15456 \bar no
15457 \noun off
15458 \color none
15459 convert floating point to unsigned char
15460 \end_inset
15461 </cell>
15462 </row>
15463 <row topline="true">
15464 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15465 \begin_inset Text
15466
15467 \layout Standard
15468
15469
15470 \family roman
15471 \series medium
15472 \shape up
15473 \size normal
15474 \emph off
15475 \bar no
15476 \noun off
15477 \color none
15478 _fs2char.c
15479 \end_inset
15480 </cell>
15481 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15482 \begin_inset Text
15483
15484 \layout Standard
15485
15486
15487 \family roman
15488 \series medium
15489 \shape up
15490 \size normal
15491 \emph off
15492 \bar no
15493 \noun off
15494 \color none
15495 convert floating point to signed char
15496 \end_inset
15497 </cell>
15498 </row>
15499 <row topline="true">
15500 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15501 \begin_inset Text
15502
15503 \layout Standard
15504
15505
15506 \family roman
15507 \series medium
15508 \shape up
15509 \size normal
15510 \emph off
15511 \bar no
15512 \noun off
15513 \color none
15514 _fs2uint.c
15515 \end_inset
15516 </cell>
15517 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15518 \begin_inset Text
15519
15520 \layout Standard
15521
15522
15523 \family roman
15524 \series medium
15525 \shape up
15526 \size normal
15527 \emph off
15528 \bar no
15529 \noun off
15530 \color none
15531 convert floating point to unsigned int
15532 \end_inset
15533 </cell>
15534 </row>
15535 <row topline="true">
15536 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15537 \begin_inset Text
15538
15539 \layout Standard
15540
15541
15542 \family roman
15543 \series medium
15544 \shape up
15545 \size normal
15546 \emph off
15547 \bar no
15548 \noun off
15549 \color none
15550 _fs2int.c
15551 \end_inset
15552 </cell>
15553 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15554 \begin_inset Text
15555
15556 \layout Standard
15557
15558
15559 \family roman
15560 \series medium
15561 \shape up
15562 \size normal
15563 \emph off
15564 \bar no
15565 \noun off
15566 \color none
15567 convert floating point to signed int
15568 \end_inset
15569 </cell>
15570 </row>
15571 <row topline="true">
15572 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15573 \begin_inset Text
15574
15575 \layout Standard
15576
15577
15578 \family roman
15579 \series medium
15580 \shape up
15581 \size normal
15582 \emph off
15583 \bar no
15584 \noun off
15585 \color none
15586 _fs2ulong.
15587 \family default
15588 \series default
15589 \shape default
15590 \size default
15591 \emph default
15592 \bar default
15593 \noun default
15594 \color default
15595 c
15596 \end_inset
15597 </cell>
15598 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15599 \begin_inset Text
15600
15601 \layout Standard
15602
15603
15604 \family roman
15605 \series medium
15606 \shape up
15607 \size normal
15608 \emph off
15609 \bar no
15610 \noun off
15611 \color none
15612 convert floating point to unsigned long
15613 \end_inset
15614 </cell>
15615 </row>
15616 <row topline="true">
15617 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15618 \begin_inset Text
15619
15620 \layout Standard
15621
15622
15623 \family roman
15624 \series medium
15625 \shape up
15626 \size normal
15627 \emph off
15628 \bar no
15629 \noun off
15630 \color none
15631 _fs2long.c
15632 \end_inset
15633 </cell>
15634 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15635 \begin_inset Text
15636
15637 \layout Standard
15638
15639
15640 \family roman
15641 \series medium
15642 \shape up
15643 \size normal
15644 \emph off
15645 \bar no
15646 \noun off
15647 \color none
15648 convert floating point to signed long
15649 \end_inset
15650 </cell>
15651 </row>
15652 <row topline="true">
15653 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15654 \begin_inset Text
15655
15656 \layout Standard
15657
15658
15659 \family roman
15660 \series medium
15661 \shape up
15662 \size normal
15663 \emph off
15664 \bar no
15665 \noun off
15666 \color none
15667 _uchar2fs.c
15668 \end_inset
15669 </cell>
15670 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15671 \begin_inset Text
15672
15673 \layout Standard
15674
15675
15676 \family roman
15677 \series medium
15678 \shape up
15679 \size normal
15680 \emph off
15681 \bar no
15682 \noun off
15683 \color none
15684 convert unsigned char to floating point
15685 \end_inset
15686 </cell>
15687 </row>
15688 <row topline="true">
15689 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15690 \begin_inset Text
15691
15692 \layout Standard
15693
15694
15695 \family roman
15696 \series medium
15697 \shape up
15698 \size normal
15699 \emph off
15700 \bar no
15701 \noun off
15702 \color none
15703 _char2fs.c
15704 \end_inset
15705 </cell>
15706 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15707 \begin_inset Text
15708
15709 \layout Standard
15710
15711
15712 \family roman
15713 \series medium
15714 \shape up
15715 \size normal
15716 \emph off
15717 \bar no
15718 \noun off
15719 \color none
15720 convert char to floating point number
15721 \end_inset
15722 </cell>
15723 </row>
15724 <row topline="true">
15725 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15726 \begin_inset Text
15727
15728 \layout Standard
15729
15730
15731 \family roman
15732 \series medium
15733 \shape up
15734 \size normal
15735 \emph off
15736 \bar no
15737 \noun off
15738 \color none
15739 _uint2fs.c
15740 \end_inset
15741 </cell>
15742 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15743 \begin_inset Text
15744
15745 \layout Standard
15746
15747
15748 \family roman
15749 \series medium
15750 \shape up
15751 \size normal
15752 \emph off
15753 \bar no
15754 \noun off
15755 \color none
15756 convert unsigned int to floating point
15757 \end_inset
15758 </cell>
15759 </row>
15760 <row topline="true">
15761 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15762 \begin_inset Text
15763
15764 \layout Standard
15765
15766
15767 \family roman
15768 \series medium
15769 \shape up
15770 \size normal
15771 \emph off
15772 \bar no
15773 \noun off
15774 \color none
15775 _int2fs.c
15776 \end_inset
15777 </cell>
15778 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15779 \begin_inset Text
15780
15781 \layout Standard
15782
15783
15784 \family roman
15785 \series medium
15786 \shape up
15787 \size normal
15788 \emph off
15789 \bar no
15790 \noun off
15791 \color none
15792 convert int to floating point numbers
15793 \end_inset
15794 </cell>
15795 </row>
15796 <row topline="true">
15797 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15798 \begin_inset Text
15799
15800 \layout Standard
15801
15802
15803 \family roman
15804 \series medium
15805 \shape up
15806 \size normal
15807 \emph off
15808 \bar no
15809 \noun off
15810 \color none
15811 _ulong2fs.c
15812 \end_inset
15813 </cell>
15814 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15815 \begin_inset Text
15816
15817 \layout Standard
15818
15819
15820 \family roman
15821 \series medium
15822 \shape up
15823 \size normal
15824 \emph off
15825 \bar no
15826 \noun off
15827 \color none
15828 convert unsigned long to floating point number
15829 \end_inset
15830 </cell>
15831 </row>
15832 <row topline="true" bottomline="true">
15833 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15834 \begin_inset Text
15835
15836 \layout Standard
15837
15838
15839 \family roman
15840 \series medium
15841 \shape up
15842 \size normal
15843 \emph off
15844 \bar no
15845 \noun off
15846 \color none
15847 _long2fs.c
15848 \end_inset
15849 </cell>
15850 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15851 \begin_inset Text
15852
15853 \layout Standard
15854
15855
15856 \family roman
15857 \series medium
15858 \shape up
15859 \size normal
15860 \emph off
15861 \bar no
15862 \noun off
15863 \color none
15864 convert long to floating point number
15865 \end_inset
15866 </cell>
15867 </row>
15868 </lyxtabular>
15869
15870 \end_inset
15871
15872
15873 \newline
15874
15875 \layout Standard
15876 \added_space_bottom bigskip
15877 These support routines are developed in ANSI-C so there is room for space
15878  and speed improvement
15879 \begin_inset Foot
15880 collapsed false
15881
15882 \layout Standard
15883
15884 These floating point routines (
15885 \emph on
15886 not
15887 \emph default
15888  sinf(), cosf(), ...) for the mcs51 are implemented in assembler.
15889
15890 \end_inset
15891
15892 .
15893  Note if all these routines are used simultaneously the data space might
15894  overflow.
15895  For serious floating point usage the large model might be needed.
15896  Also notice that you don't have to call this routines directly.
15897  The compiler will use them automatically every time a floating point operation
15898  is required.
15899 \layout Section
15900
15901 Library Routines
15902 \begin_inset LatexCommand \index{Libraries}
15903
15904 \end_inset
15905
15906
15907 \layout Standard
15908
15909
15910 \emph on
15911 <pending: this is messy and incomplete - a little more information is in
15912  sdcc/doc/libdoc.txt
15913 \emph default
15914  >
15915 \layout Subsection
15916
15917 Compiler support routines (_gptrget, _mulint etc.)
15918 \layout Subsection
15919
15920 Stdclib functions (puts, printf, strcat etc.)
15921 \layout Subsubsection
15922
15923 <stdio.h>
15924 \layout Standard
15925
15926
15927 \begin_inset LatexCommand \index{<stdio.h>}
15928
15929 \end_inset
15930
15931 As usual on embedded systems you have to provide your own
15932 \family typewriter
15933 getchar()
15934 \begin_inset LatexCommand \index{getchar()}
15935
15936 \end_inset
15937
15938
15939 \family default
15940 and
15941 \family typewriter
15942 putchar()
15943 \begin_inset LatexCommand \index{putchar()}
15944
15945 \end_inset
15946
15947
15948 \family default
15949  routines.
15950  SDCC does not know whether the system connects to a serial line with or
15951  without handshake, LCD, keyboard or other device.
15952  And whether a
15953 \family typewriter
15954 lf
15955 \family default
15956  to
15957 \family typewriter
15958 crlf
15959 \family default
15960  conversion within
15961 \family typewriter
15962 putchar()
15963 \family default
15964  is intended.
15965  You'll find examples for serial routines f.e.
15966  in sdcc/device/lib.
15967 \layout Standard
15968
15969 The default
15970 \family typewriter
15971  printf()
15972 \begin_inset LatexCommand \index{printf()}
15973
15974 \end_inset
15975
15976
15977 \family default
15978 implementation in
15979 \family typewriter
15980  printf_large.c
15981 \family default
15982  does not support float (except on ds390).
15983  To enable this recompile it with the option
15984 \emph on
15985 -
15986 \begin_inset ERT
15987 status Collapsed
15988
15989 \layout Standard
15990
15991 \backslash
15992 /
15993 \end_inset
15994
15995 DUSE_FLOATS=1
15996 \begin_inset LatexCommand \index{USE\_FLOATS}
15997
15998 \end_inset
15999
16000
16001 \emph default
16002  on the command line.
16003  Use
16004 \emph on
16005  -
16006 \begin_inset ERT
16007 status Collapsed
16008
16009 \layout Standard
16010
16011 \backslash
16012 /
16013 \end_inset
16014
16015 -model-large
16016 \begin_inset LatexCommand \index{-\/-model-large}
16017
16018 \end_inset
16019
16020
16021 \emph default
16022  for the mcs51 port, since this uses a lot of memory.
16023 \layout Standard
16024
16025 If you're short on memory you might want to use
16026 \family typewriter
16027 printf_small()
16028 \begin_inset LatexCommand \index{printf\_small()}
16029
16030 \end_inset
16031
16032
16033 \family default
16034
16035 \emph on
16036 instead
16037 \emph default
16038  of
16039 \family typewriter
16040  printf().
16041
16042 \family default
16043  For the mcs51 there additionally are assembly versions
16044 \family typewriter
16045 printf_tiny()
16046 \begin_inset LatexCommand \index{printf\_tiny() (mcs51)}
16047
16048 \end_inset
16049
16050
16051 \family default
16052  (subset of printf using less than 270 bytes) and
16053 \family typewriter
16054 printf_fast()
16055 \begin_inset LatexCommand \index{printf\_fast() (mcs51)}
16056
16057 \end_inset
16058
16059
16060 \family default
16061 and
16062 \family typewriter
16063  printf_fast_f()
16064 \begin_inset LatexCommand \index{printf\_fast\_f() (mcs51)}
16065
16066 \end_inset
16067
16068
16069 \family default
16070  (floating-point aware version of printf_fast) which should fit the requirements
16071  of many embedded systems (printf_fast() can be customized by unsetting
16072  #defines to
16073 \emph on
16074 not
16075 \emph default
16076  support long variables and field widths).
16077 \layout Subsubsection
16078
16079 <malloc.h>
16080 \begin_inset LatexCommand \index{malloc.h}
16081
16082 \end_inset
16083
16084
16085 \layout Standard
16086
16087 As of SDCC 2.6.2 you no longer need to call an initialization routine before
16088  using dynamic memory allocation
16089 \begin_inset LatexCommand \index{dynamic memory allocation (malloc)}
16090
16091 \end_inset
16092
16093  and a default heap
16094 \begin_inset LatexCommand \index{heap (malloc)}
16095
16096 \end_inset
16097
16098  space of 1024 bytes is provided for malloc to allocate memory from.
16099  If you need a different heap size you need to recompile _heap.c with the
16100  required size defined in HEAP_SIZE.
16101  It is recommended to make a copy of this file into your project directory
16102  and compile it there with:
16103 \layout Verse
16104
16105
16106 \family typewriter
16107 sdcc -c _heap.c -D HEAD_SIZE=2048
16108 \newline
16109
16110 \family default
16111 And then link it with:
16112 \layout Verse
16113
16114
16115 \family typewriter
16116 sdcc main.rel _heap.rel
16117 \newline
16118
16119 \layout Subsection
16120
16121 Math functions (sinf, powf, sqrtf etc.)
16122 \layout Subsubsection
16123
16124 <math.h>
16125 \layout Standard
16126
16127 See definitions in file <math.h>.
16128 \layout Subsection
16129
16130 Other libraries
16131 \layout Standard
16132
16133 Libraries
16134 \begin_inset LatexCommand \index{Libraries}
16135
16136 \end_inset
16137
16138  included in SDCC should have a license at least as liberal as the GNU Lesser
16139  General Public License
16140 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
16141
16142 \end_inset
16143
16144
16145 \emph on
16146 LGPL
16147 \emph default
16148 .
16149 \layout Comment
16150
16151 license statements for the libraries are missing.
16152  sdcc/device/lib/ser_ir.c
16153 \layout Comment
16154
16155 or _decdptr f.e.
16156  come with a GPL (as opposed to LGPL) License - this will not be liberal
16157  enough for many embedded programmers.
16158 \layout Standard
16159
16160 If you have ported some library or want to share experience about some code
16161  which f.e.
16162  falls into any of these categories Busses (I
16163 \begin_inset Formula $^{\textrm{2}}$
16164 \end_inset
16165
16166 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
16167  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
16168  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
16169 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
16170
16171 \end_inset
16172
16173 \SpecialChar ~
16174 would certainly like to hear about it.
16175 \layout Standard
16176 \added_space_bottom bigskip
16177 Programmers coding for embedded systems are not especially famous for being
16178  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
16179 e these references are very valuable.
16180  Let's help to create a climate where information is shared.
16181 \layout Section
16182
16183 Memory Models
16184 \layout Subsection
16185
16186 MCS51 Memory Models
16187 \begin_inset LatexCommand \index{Memory model}
16188
16189 \end_inset
16190
16191
16192 \begin_inset LatexCommand \index{MCS51 memory model}
16193
16194 \end_inset
16195
16196
16197 \layout Subsubsection
16198
16199 Small, Medium and Large
16200 \layout Standard
16201
16202 SDCC allows three memory models for MCS51 code,
16203 \shape slanted
16204 small, medium
16205 \shape default
16206  and
16207 \shape slanted
16208 large
16209 \shape default
16210 .
16211  Modules compiled with different memory models should
16212 \emph on
16213 never
16214 \emph default
16215  be combined together or the results would be unpredictable.
16216  The library routines supplied with the compiler are compiled as small,
16217  medium and large.
16218  The compiled library modules are contained in separate directories as small,
16219  medium and large so that you can link to the appropriate set.
16220 \layout Standard
16221
16222 When the medium or large model is used all variables declared without a
16223  storage class will be allocated into the external ram, this includes all
16224  parameters and local variables (for non-reentrant
16225 \begin_inset LatexCommand \index{reentrant}
16226
16227 \end_inset
16228
16229  functions).
16230  When the small model is used variables without storage class are allocated
16231  in the internal ram.
16232 \layout Standard
16233
16234 Judicious usage of the processor specific storage classes
16235 \begin_inset LatexCommand \index{Storage class}
16236
16237 \end_inset
16238
16239  and the 'reentrant' function type will yield much more efficient code,
16240  than using the large model.
16241  Several optimizations are disabled when the program is compiled using the
16242  large model, it is therefore recommended that the small model be used unless
16243  absolutely required.
16244 \layout Subsubsection
16245
16246 External Stack
16247 \begin_inset LatexCommand \label{sub:External-Stack}
16248
16249 \end_inset
16250
16251
16252 \begin_inset LatexCommand \index{stack}
16253
16254 \end_inset
16255
16256
16257 \begin_inset LatexCommand \index{External stack (mcs51)}
16258
16259 \end_inset
16260
16261
16262 \layout Standard
16263
16264 The external stack (-
16265 \begin_inset ERT
16266 status Collapsed
16267
16268 \layout Standard
16269
16270 \backslash
16271 /
16272 \end_inset
16273
16274 -xstack option
16275 \begin_inset LatexCommand \index{-\/-xstack}
16276
16277 \end_inset
16278
16279 ) is located in pdata
16280 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
16281
16282 \end_inset
16283
16284  memory (usually at the start of the external ram segment) and uses all
16285  unused space in pdata (max.
16286  256 bytes).
16287  When -
16288 \begin_inset ERT
16289 status Collapsed
16290
16291 \layout Standard
16292
16293 \backslash
16294 /
16295 \end_inset
16296
16297 -xstack option is used to compile the program, the parameters and local
16298  variables
16299 \begin_inset LatexCommand \index{local variables}
16300
16301 \end_inset
16302
16303  of all reentrant functions are allocated in this area.
16304  This option is provided for programs with large stack space requirements.
16305  When used with the -
16306 \begin_inset ERT
16307 status Collapsed
16308
16309 \layout Standard
16310
16311 \backslash
16312 /
16313 \end_inset
16314
16315 -stack-auto
16316 \begin_inset LatexCommand \index{-\/-stack-auto}
16317
16318 \end_inset
16319
16320  option, all parameters and local variables are allocated on the external
16321  stack (note: support libraries will need to be recompiled with the same
16322  options.
16323  There is a predefined target in the library makefile).
16324 \layout Standard
16325
16326 The compiler outputs the higher order address byte of the external ram segment
16327  into port P2
16328 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
16329
16330 \end_inset
16331
16332  (see also section
16333 \begin_inset LatexCommand \ref{sub:MCS51-variants}
16334
16335 \end_inset
16336
16337 ), therefore when using the External Stack option, this port
16338 \emph on
16339 may not
16340 \emph default
16341  be used by the application program.
16342 \layout Subsection
16343
16344 DS390 Memory Model
16345 \begin_inset LatexCommand \index{Memory model}
16346
16347 \end_inset
16348
16349
16350 \begin_inset LatexCommand \index{DS390 memory model}
16351
16352 \end_inset
16353
16354
16355 \layout Standard
16356
16357 The only model supported is Flat 24
16358 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
16359
16360 \end_inset
16361
16362 .
16363  This generates code for the 24 bit contiguous addressing mode of the Dallas
16364  DS80C390 part.
16365  In this mode, up to four meg of external RAM or code space can be directly
16366  addressed.
16367  See the data sheets at www.dalsemi.com for further information on this part.
16368 \newline
16369
16370 \newline
16371 Note that the compiler does not generate any code to place the processor
16372  into 24 bitmode (although
16373 \emph on
16374 tinibios
16375 \emph default
16376  in the ds390 libraries will do that for you).
16377  If you don't use
16378 \emph on
16379 tinibios
16380 \emph default
16381
16382 \begin_inset LatexCommand \index{Tinibios (DS390)}
16383
16384 \end_inset
16385
16386 , the boot loader or similar code must ensure that the processor is in 24
16387  bit contiguous addressing mode before calling the SDCC startup code.
16388 \newline
16389
16390 \newline
16391 Like the
16392 \emph on
16393 -
16394 \begin_inset ERT
16395 status Collapsed
16396
16397 \layout Standard
16398
16399 \backslash
16400 /
16401 \end_inset
16402
16403 -model-large
16404 \emph default
16405  option, variables will by default be placed into the XDATA segment.
16406
16407 \newline
16408
16409 \newline
16410 Segments may be placed anywhere in the 4 meg address space using the usual
16411  -
16412 \begin_inset ERT
16413 status Collapsed
16414
16415 \layout Standard
16416
16417 \backslash
16418 /
16419 \end_inset
16420
16421 -*-loc options.
16422  Note that if any segments are located above 64K, the -r flag must be passed
16423  to the linker to generate the proper segment relocations, and the Intel
16424  HEX output format must be used.
16425  The -r flag can be passed to the linker by using the option
16426 \emph on
16427 -Wl-r
16428 \emph default
16429  on the SDCC command line.
16430  However, currently the linker can not handle code segments > 64k.
16431 \layout Section
16432
16433 Pragmas
16434 \begin_inset LatexCommand \label{sec:Pragmas}
16435
16436 \end_inset
16437
16438
16439 \begin_inset LatexCommand \index{Pragmas}
16440
16441 \end_inset
16442
16443
16444 \layout Standard
16445
16446 SDCC supports the following #pragma directives:
16447 \layout Itemize
16448
16449
16450 \series bold
16451 save
16452 \series default
16453
16454 \begin_inset LatexCommand \index{\#pragma save}
16455
16456 \end_inset
16457
16458  - this will save most current options to the save/restore stack.
16459  See #pragma\SpecialChar ~
16460 restore.
16461 \layout Itemize
16462
16463
16464 \series bold
16465 restore
16466 \series default
16467
16468 \begin_inset LatexCommand \index{\#pragma restore}
16469
16470 \end_inset
16471
16472  - will restore saved options from the last save.
16473  saves & restores can be nested.
16474  SDCC uses a save/restore stack: save pushes current options to the stack,
16475  restore pulls current options from the stack.
16476  See #pragma\SpecialChar ~
16477 save.
16478 \newline
16479
16480 \layout Itemize
16481
16482
16483 \series bold
16484 callee_saves
16485 \series default
16486
16487 \begin_inset LatexCommand \index{\#pragma callee\_saves}
16488
16489 \end_inset
16490
16491
16492 \begin_inset LatexCommand \index{function prologue}
16493
16494 \end_inset
16495
16496  function1[,function2[,function3...]] - The compiler by default uses a caller
16497  saves convention for register saving across function calls, however this
16498  can cause unnecessary register pushing & popping
16499 \begin_inset LatexCommand \index{push/pop}
16500
16501 \end_inset
16502
16503  when calling small functions from larger functions.
16504  This option can be used to switch off the register saving convention for
16505  the function names specified.
16506  The compiler will not save registers when calling these functions, extra
16507  code need to be manually inserted at the entry & exit for these functions
16508  to save & restore the registers used by these functions, this can SUBSTANTIALLY
16509  reduce code & improve run time performance of the generated code.
16510  In the future the compiler (with inter procedural analysis) may be able
16511  to determine the appropriate scheme to use for each function call.
16512  If -
16513 \begin_inset ERT
16514 status Collapsed
16515
16516 \layout Standard
16517
16518 \backslash
16519 /
16520 \end_inset
16521
16522 -callee-saves command line option is used, the function names specified
16523  in #pragma\SpecialChar ~
16524 callee_saves
16525 \begin_inset LatexCommand \index{\#pragma callee\_saves}
16526
16527 \end_inset
16528
16529  is appended to the list of functions specified in the command line.
16530 \layout Itemize
16531
16532
16533 \series bold
16534 exclude
16535 \series default
16536
16537 \begin_inset LatexCommand \index{\#pragma exclude}
16538
16539 \end_inset
16540
16541  none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
16542  of pairs of push/pop
16543 \begin_inset LatexCommand \index{push/pop}
16544
16545 \end_inset
16546
16547  instructions in
16548 \emph on
16549 I
16550 \emph default
16551 nterrupt
16552 \begin_inset LatexCommand \index{interrupt}
16553
16554 \end_inset
16555
16556
16557 \emph on
16558 S
16559 \emph default
16560 ervice
16561 \emph on
16562 R
16563 \emph default
16564 outines.
16565  The directive should be placed immediately before the ISR function definition
16566  and it affects ALL ISR functions following it.
16567  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
16568 exclude\SpecialChar ~
16569 none
16570 \begin_inset LatexCommand \index{\#pragma exclude}
16571
16572 \end_inset
16573
16574 .
16575  See also the related keyword _naked
16576 \begin_inset LatexCommand \index{\_naked}
16577
16578 \end_inset
16579
16580
16581 \begin_inset LatexCommand \index{\_\_naked}
16582
16583 \end_inset
16584
16585 .
16586 \layout Itemize
16587
16588
16589 \series bold
16590 less_pedantic
16591 \series default
16592
16593 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
16594
16595 \end_inset
16596
16597  - the compiler will not warn you anymore for obvious mistakes, you'r on
16598  your own now ;-(
16599 \layout Itemize
16600
16601
16602 \series bold
16603 disable_warning
16604 \series default
16605  <nnnn>
16606 \begin_inset LatexCommand \index{\#pragma disable\_warning}
16607
16608 \end_inset
16609
16610  - the compiler will not warn you anymore about warning number <nnnn>.
16611 \layout Itemize
16612
16613
16614 \series bold
16615 nogcse
16616 \series default
16617
16618 \begin_inset LatexCommand \index{\#pragma nogcse}
16619
16620 \end_inset
16621
16622  - will stop global common subexpression elimination.
16623 \layout Itemize
16624
16625
16626 \series bold
16627 noinduction
16628 \series default
16629
16630 \begin_inset LatexCommand \index{\#pragma noinduction}
16631
16632 \end_inset
16633
16634  - will stop loop induction optimizations.
16635 \layout Itemize
16636
16637
16638 \series bold
16639 noinvariant
16640 \series default
16641
16642 \begin_inset LatexCommand \index{\#pragma noinvariant}
16643
16644 \end_inset
16645
16646  - will not do loop invariant optimizations.
16647  For more details see Loop Invariants in section
16648 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
16649
16650 \end_inset
16651
16652 .
16653 \layout Itemize
16654
16655
16656 \series bold
16657 noiv
16658 \series default
16659
16660 \begin_inset LatexCommand \index{\#pragma noiv}
16661
16662 \end_inset
16663
16664  - Do not generate interrupt
16665 \begin_inset LatexCommand \index{interrupt}
16666
16667 \end_inset
16668
16669  vector table
16670 \begin_inset LatexCommand \index{interrupt vector table}
16671
16672 \end_inset
16673
16674  entries for all ISR functions defined after the pragma.
16675  This is useful in cases where the interrupt vector table must be defined
16676  manually, or when there is a secondary, manually defined interrupt vector
16677  table (e.g.
16678  for the autovector feature of the Cypress EZ-USB FX2).
16679  More elegantly this can be achieved by obmitting the optional interrupt
16680  number after the interrupt keyword, see section
16681 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
16682
16683 \end_inset
16684
16685 \SpecialChar ~
16686 about interrupts.
16687 \layout Itemize
16688
16689
16690 \series bold
16691 nojtbound
16692 \series default
16693
16694 \begin_inset LatexCommand \index{\#pragma nojtbound}
16695
16696 \end_inset
16697
16698  - will not generate code for boundary value checking, when switch statements
16699  are turned into jump-tables (dangerous).
16700  For more details see section
16701 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
16702
16703 \end_inset
16704
16705 .
16706 \layout Itemize
16707
16708
16709 \series bold
16710 noloopreverse
16711 \series default
16712
16713 \begin_inset LatexCommand \index{\#pragma noloopreverse}
16714
16715 \end_inset
16716
16717  - Will not do loop reversal optimization
16718 \layout Itemize
16719
16720
16721 \series bold
16722 nooverlay
16723 \series default
16724
16725 \begin_inset LatexCommand \index{\#pragma nooverlay}
16726
16727 \end_inset
16728
16729  - the compiler will not overlay the parameters and local variables of a
16730  function.
16731 \layout Itemize
16732
16733
16734 \series bold
16735 stackauto
16736 \series default
16737
16738 \begin_inset LatexCommand \index{\#pragma stackauto}
16739
16740 \end_inset
16741
16742 - See option -
16743 \begin_inset ERT
16744 status Collapsed
16745
16746 \layout Standard
16747
16748 \backslash
16749 /
16750 \end_inset
16751
16752 -stack-auto
16753 \begin_inset LatexCommand \index{-\/-stack-auto}
16754
16755 \end_inset
16756
16757  and section
16758 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
16759
16760 \end_inset
16761
16762  Parameters and Local Variables.
16763 \layout Itemize
16764
16765
16766 \series bold
16767 opt_code_speed
16768 \series default
16769
16770 \begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
16771
16772 \end_inset
16773
16774 - The compiler will optimize code generation towards fast code, possibly
16775  at the expense of code size.
16776  Currently this has little effect.
16777 \layout Itemize
16778
16779
16780 \series bold
16781 opt_code_size
16782 \series default
16783
16784 \begin_inset LatexCommand \index{\#pragma opt\_code\_size}
16785
16786 \end_inset
16787
16788 - The compiler will optimize code generation towards compact code, possibly
16789  at the expense of code speed.
16790  Currently this has little effect.
16791 \layout Itemize
16792
16793
16794 \series bold
16795 opt_code_balanced
16796 \series default
16797
16798 \begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
16799
16800 \end_inset
16801
16802 - The compiler will attempt to generate code that is both compact and fast,
16803  as long as meeting one goal is not a detriment to the other (this is the
16804  default).
16805
16806 \layout Itemize
16807
16808
16809 \series bold
16810 std_sdcc89
16811 \series default
16812
16813 \begin_inset LatexCommand \index{\#pragma std\_sdcc89}
16814
16815 \end_inset
16816
16817 - Generally follow the C89 standard, but allow SDCC features that conflict
16818  with the standard (default).
16819 \layout Itemize
16820
16821
16822 \series bold
16823 std_c89
16824 \series default
16825
16826 \begin_inset LatexCommand \index{\#pragma std\_c89}
16827
16828 \end_inset
16829
16830 - Follow the C89 standard and disable SDCC features that conflict with the
16831  standard.
16832 \layout Itemize
16833
16834
16835 \series bold
16836 std_sdcc99
16837 \series default
16838
16839 \begin_inset LatexCommand \index{\#pragma std\_sdcc99}
16840
16841 \end_inset
16842
16843 - Generally follow the C99 standard, but allow SDCC features that conflict
16844  with the standard (incomplete support).
16845 \layout Itemize
16846
16847
16848 \series bold
16849 std_c99
16850 \series default
16851
16852 \begin_inset LatexCommand \index{\#pragma std\_c99}
16853
16854 \end_inset
16855
16856 - Follow the C99 standard and disable SDCC features that conflict with the
16857  standard (incomplete support).
16858 \layout Itemize
16859
16860
16861 \series bold
16862 codeseg
16863 \series default
16864  <name>
16865 \begin_inset LatexCommand \index{\#pragma codeseg}
16866
16867 \end_inset
16868
16869 - Use this name (max.
16870  8 characters) for the code segment.
16871  See option -
16872 \begin_inset ERT
16873 status Collapsed
16874
16875 \layout Standard
16876
16877 \backslash
16878 /
16879 \end_inset
16880
16881 -codeseg.
16882 \layout Itemize
16883
16884
16885 \series bold
16886 constseg
16887 \series default
16888  <name>
16889 \begin_inset LatexCommand \index{\#pragma constseg}
16890
16891 \end_inset
16892
16893 - Use this name (max.
16894  8 characters) for the const segment.
16895  See option -
16896 \begin_inset ERT
16897 status Collapsed
16898
16899 \layout Standard
16900
16901 \backslash
16902 /
16903 \end_inset
16904
16905 -constseg.
16906 \layout Standard
16907
16908 The preprocessor SDCPP
16909 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
16910
16911 \end_inset
16912
16913  supports the following #pragma directives:
16914 \layout Itemize
16915
16916
16917 \series bold
16918 preproc_asm
16919 \series default
16920
16921 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
16922
16923 \end_inset
16924
16925  (+ | -) - switch _asm _endasm block preprocessing on / off.
16926  Default is on.
16927  You use this prama to define multilines of assembly code.
16928  This will prevent the preprocessor from changing the formating required
16929  by assembly code.
16930  Below is an example on how to use this pragma.
16931 \layout Verse
16932
16933
16934 \family typewriter
16935 #pragma preproc_asm -
16936 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
16937
16938 \end_inset
16939
16940
16941 \newline
16942 #define MYDELAY _asm
16943 \newline
16944 \SpecialChar ~
16945 \SpecialChar ~
16946 \SpecialChar ~
16947 nop ;my assembly comment...
16948 \newline
16949 \SpecialChar ~
16950 \SpecialChar ~
16951 \SpecialChar ~
16952 nop
16953 \newline
16954 \SpecialChar ~
16955 \SpecialChar ~
16956 \SpecialChar ~
16957 nop
16958 \newline
16959 _endasm
16960 \newline
16961 #pragma preproc_asm +
16962 \newline
16963
16964 \newline
16965 void foo (void)
16966 \newline
16967 {
16968 \newline
16969 \SpecialChar ~
16970 \SpecialChar ~
16971 \SpecialChar ~
16972  ...
16973
16974 \newline
16975 \SpecialChar ~
16976 \SpecialChar ~
16977 \SpecialChar ~
16978  MYDELAY;
16979 \newline
16980 \SpecialChar ~
16981 \SpecialChar ~
16982 \SpecialChar ~
16983  ...
16984
16985 \newline
16986 }
16987 \newline
16988
16989 \layout Itemize
16990
16991
16992 \series bold
16993 pedantic_parse_number
16994 \series default
16995
16996 \begin_inset LatexCommand \index{\#pragma pedantic\_parse\_number}
16997
16998 \end_inset
16999
17000  (+ | -) - Pedantic parse numbers so that situations like 0xfe-LO_B(3) are
17001  parsed properly and the macro LO_B(3) gets expanded.
17002  Default is off.
17003  Below is an example on how to use this pragma.
17004
17005 \emph on
17006  Note: this functionality is not in conformance with standard!
17007
17008 \layout Verse
17009
17010
17011 \family typewriter
17012 #pragma pedantic_parse_number +
17013 \begin_inset LatexCommand \index{\#pragma pedantic\_parse\_number}
17014
17015 \end_inset
17016
17017
17018 \newline
17019 \newline
17020 #define LO_B(x) ((x) & 0xff)
17021 \newline
17022 \newline
17023 unsigned char foo(void)
17024 \newline
17025 \InsetSpace ~
17026 \InsetSpace ~
17027 \InsetSpace ~
17028 unsigned char c=0xfe-LO_B(3);
17029 \newline
17030 \newline
17031 \InsetSpace ~
17032 \InsetSpace ~
17033 \InsetSpace ~
17034
17035 return c;
17036 \newline
17037 }
17038 \newline
17039
17040 \layout Standard
17041
17042 The pragma's are intended to be used to turn-on or off certain optimizations
17043  which might cause the compiler to generate extra stack / data space to
17044  store compiler generated temporary variables.
17045  This usually happens in large functions.
17046  Pragma directives should be used as shown in the following example, they
17047  are used to control options & optimizations for a given function; pragmas
17048  should be placed before and/or after a function, placing pragma's inside
17049  a function body could have unpredictable results.
17050 \layout Verse
17051
17052
17053 \family typewriter
17054 #pragma save
17055 \begin_inset LatexCommand \index{\#pragma save}
17056
17057 \end_inset
17058
17059  \SpecialChar ~
17060 \SpecialChar ~
17061 \SpecialChar ~
17062 \SpecialChar ~
17063 \SpecialChar ~
17064 \SpecialChar ~
17065 \SpecialChar ~
17066 /* save the current settings */
17067 \newline
17068 #pragma nogcse
17069 \begin_inset LatexCommand \index{\#pragma nogcse}
17070
17071 \end_inset
17072
17073  \SpecialChar ~
17074 \SpecialChar ~
17075 \SpecialChar ~
17076 \SpecialChar ~
17077 \SpecialChar ~
17078 /* turnoff global subexpression elimination */
17079 \newline
17080 #pragma noinduction
17081 \begin_inset LatexCommand \index{\#pragma noinduction}
17082
17083 \end_inset
17084
17085  /* turn off induction optimizations */
17086 \newline
17087 int foo ()
17088 \newline
17089 {
17090 \newline
17091 \SpecialChar ~
17092  \SpecialChar ~
17093  ...
17094
17095 \newline
17096 \SpecialChar ~
17097  \SpecialChar ~
17098  /* large code */
17099 \newline
17100 \SpecialChar ~
17101  \SpecialChar ~
17102  ...
17103
17104 \newline
17105 }
17106 \newline
17107 #pragma restore
17108 \begin_inset LatexCommand \index{\#pragma restore}
17109
17110 \end_inset
17111
17112  /* turn the optimizations back on */
17113 \layout Standard
17114
17115 The compiler will generate a warning message when extra space is allocated.
17116  It is strongly recommended that the save and restore pragma's be used when
17117  changing options for a function.
17118 \newline
17119
17120 \newline
17121
17122 \newline
17123
17124 \layout Section
17125
17126 Defines Created by the Compiler
17127 \layout Standard
17128
17129 The compiler creates the following #defines
17130 \begin_inset LatexCommand \index{\#defines}
17131
17132 \end_inset
17133
17134
17135 \begin_inset LatexCommand \index{Defines created by the compiler}
17136
17137 \end_inset
17138
17139 :
17140 \newline
17141
17142 \layout Standard
17143
17144
17145 \begin_inset  Tabular
17146 <lyxtabular version="3" rows="11" columns="2">
17147 <features>
17148 <column alignment="left" valignment="top" leftline="true" width="3in">
17149 <column alignment="left" valignment="top" leftline="true" rightline="true" width="3in">
17150 <row topline="true" bottomline="true">
17151 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17152 \begin_inset Text
17153
17154 \layout Standard
17155
17156
17157 \series bold
17158 #define
17159 \end_inset
17160 </cell>
17161 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17162 \begin_inset Text
17163
17164 \layout Standard
17165
17166
17167 \series bold
17168 Description
17169 \end_inset
17170 </cell>
17171 </row>
17172 <row topline="true">
17173 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17174 \begin_inset Text
17175
17176 \layout Standard
17177
17178 SDCC
17179 \begin_inset LatexCommand \index{SDCC}
17180
17181 \end_inset
17182
17183
17184 \end_inset
17185 </cell>
17186 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17187 \begin_inset Text
17188
17189 \layout Standard
17190
17191 Always defined.
17192  Since version 2.5.6 the version number as an int (ex.
17193  256)
17194 \end_inset
17195 </cell>
17196 </row>
17197 <row topline="true">
17198 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17199 \begin_inset Text
17200
17201 \layout Standard
17202
17203 SDCC_mcs51
17204 \begin_inset LatexCommand \index{SDCC\_mcs51}
17205
17206 \end_inset
17207
17208  or SDCC_ds390
17209 \begin_inset LatexCommand \index{SDCC\_ds390}
17210
17211 \end_inset
17212
17213  or SDCC_z80
17214 \begin_inset LatexCommand \index{SDCC\_z80}
17215
17216 \end_inset
17217
17218 , etc.
17219 \end_inset
17220 </cell>
17221 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17222 \begin_inset Text
17223
17224 \layout Standard
17225
17226 depending on the model used (e.g.: -mds390)
17227 \end_inset
17228 </cell>
17229 </row>
17230 <row topline="true">
17231 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17232 \begin_inset Text
17233
17234 \layout Standard
17235
17236 __mcs51
17237 \begin_inset LatexCommand \index{\_\_mcs51}
17238
17239 \end_inset
17240
17241 , __ds390
17242 \begin_inset LatexCommand \index{\_\_ds390}
17243
17244 \end_inset
17245
17246 , __hc08
17247 \begin_inset LatexCommand \index{\_\_hc08}
17248
17249 \end_inset
17250
17251 , __z80
17252 \begin_inset LatexCommand \index{\_\_z80}
17253
17254 \end_inset
17255
17256 , etc
17257 \end_inset
17258 </cell>
17259 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17260 \begin_inset Text
17261
17262 \layout Standard
17263
17264 depending on the model used (e.g.
17265  -mz80)
17266 \end_inset
17267 </cell>
17268 </row>
17269 <row topline="true">
17270 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17271 \begin_inset Text
17272
17273 \layout Standard
17274
17275 SDCC_STACK_AUTO
17276 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
17277
17278 \end_inset
17279
17280
17281 \end_inset
17282 </cell>
17283 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17284 \begin_inset Text
17285
17286 \layout Standard
17287
17288 when
17289 \emph on
17290 -
17291 \begin_inset ERT
17292 status Collapsed
17293
17294 \layout Standard
17295
17296 \backslash
17297 /
17298 \end_inset
17299
17300 -stack-auto
17301 \emph default
17302  option is used
17303 \end_inset
17304 </cell>
17305 </row>
17306 <row topline="true">
17307 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17308 \begin_inset Text
17309
17310 \layout Standard
17311
17312 SDCC_MODEL_SMALL
17313 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
17314
17315 \end_inset
17316
17317
17318 \end_inset
17319 </cell>
17320 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17321 \begin_inset Text
17322
17323 \layout Standard
17324
17325 when
17326 \emph on
17327 -
17328 \begin_inset ERT
17329 status Collapsed
17330
17331 \layout Standard
17332
17333 \backslash
17334 /
17335 \end_inset
17336
17337 -model-small
17338 \emph default
17339  is used
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_MODEL_MEDIUM
17350 \begin_inset LatexCommand \index{SDCC\_MODEL\_MEDIUM}
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 -model-medium
17375 \emph default
17376  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_LARGE
17387 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
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-large
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_USE_XSTACK
17424 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
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 -xstack
17449 \emph default
17450  option 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_STACK_TENBIT
17461 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
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 -mds390
17476 \emph default
17477  is used
17478 \end_inset
17479 </cell>
17480 </row>
17481 <row topline="true" bottomline="true">
17482 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17483 \begin_inset Text
17484
17485 \layout Standard
17486
17487 SDCC_MODEL_FLAT24
17488 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
17489
17490 \end_inset
17491
17492
17493 \end_inset
17494 </cell>
17495 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17496 \begin_inset Text
17497
17498 \layout Standard
17499
17500 when
17501 \emph on
17502 -mds390
17503 \emph default
17504  is used
17505 \end_inset
17506 </cell>
17507 </row>
17508 </lyxtabular>
17509
17510 \end_inset
17511
17512
17513 \layout Chapter
17514
17515 Notes on supported Processors
17516 \layout Section
17517
17518 MCS51 variants
17519 \begin_inset LatexCommand \label{sub:MCS51-variants}
17520
17521 \end_inset
17522
17523
17524 \begin_inset LatexCommand \index{MCS51 variants}
17525
17526 \end_inset
17527
17528
17529 \layout Standard
17530
17531 MCS51 processors are available from many vendors and come in many different
17532  flavours.
17533  While they might differ considerably in respect to Special Function Registers
17534  the core MCS51 is usually not modified or is kept compatible.
17535
17536 \layout Subsection
17537
17538 pdata access by SFR
17539 \layout Standard
17540
17541 With the upcome of devices with internal xdata and flash memory devices
17542  using port P2
17543 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
17544
17545 \end_inset
17546
17547  as dedicated I/O port is becoming more popular.
17548  Switching the high byte for pdata
17549 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
17550
17551 \end_inset
17552
17553  access which was formerly done by port P2 is then achieved by a Special
17554  Function Register
17555 \begin_inset LatexCommand \index{sfr}
17556
17557 \end_inset
17558
17559 .
17560  In well-established MCS51 tradition the address of this
17561 \emph on
17562 sfr
17563 \emph default
17564  is where the chip designers decided to put it.
17565  Needless to say that they didn't agree on a common name either.
17566  So that the startup code can correctly initialize xdata variables, you
17567  should define an sfr with the name _XPAGE
17568 \family typewriter
17569
17570 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
17571
17572 \end_inset
17573
17574
17575 \family default
17576  at the appropriate location if the default, port P2, is not used for this.
17577  Some examples are:
17578 \layout Verse
17579
17580
17581 \family typewriter
17582 __sfr __at (0x92) _XPAGE; /* Cypress EZ-USB family */
17583 \layout Verse
17584
17585
17586 \family typewriter
17587 __sfr __at (0xaf) _XPAGE; /* some Silicon Labs (Cygnal) chips */
17588 \layout Verse
17589
17590
17591 \family typewriter
17592 __sfr __at (0xaa) _XPAGE; /* some Silicon Labs (Cygnal) chips */
17593 \layout Standard
17594
17595 For more exotic implementations further customizations may be needed.
17596  See section
17597 \begin_inset LatexCommand \ref{sub:Startup-Code}
17598
17599 \end_inset
17600
17601  for other possibilities.
17602 \layout Subsection
17603
17604 Other Features available by SFR
17605 \layout Standard
17606 \added_space_bottom bigskip
17607 Some MCS51 variants offer features like Double DPTR
17608 \begin_inset LatexCommand \index{DPTR}
17609
17610 \end_inset
17611
17612 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
17613  These are currently not used for the MCS51 port.
17614  If you absolutely need them you can fall back to inline assembly or submit
17615  a patch to SDCC.
17616 \layout Section
17617
17618 DS400 port
17619 \layout Standard
17620 \added_space_bottom bigskip
17621 The DS80C400
17622 \begin_inset LatexCommand \index{DS80C400}
17623
17624 \end_inset
17625
17626
17627 \begin_inset LatexCommand \index{DS400}
17628
17629 \end_inset
17630
17631  microcontroller has a rich set of peripherals.
17632  In its built-in ROM library it includes functions to access some of the
17633  features, among them is a TCP stack with IP4 and IP6 support.
17634  Library headers (currently in beta status) and other files are provided
17635  at
17636 \size footnotesize
17637
17638 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
17639
17640 \end_inset
17641
17642 .
17643
17644 \layout Section
17645
17646 The Z80 and gbz80 port
17647 \layout Standard
17648
17649 SDCC can target both the Zilog Z80
17650 \begin_inset LatexCommand \index{Z80}
17651
17652 \end_inset
17653
17654  and the Nintendo Gameboy's Z80-like gbz80
17655 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
17656
17657 \end_inset
17658
17659 .
17660  The Z80 port is passed through the same
17661 \emph on
17662 regressions tests
17663 \begin_inset LatexCommand \index{Regression test}
17664
17665 \end_inset
17666
17667
17668 \emph default
17669  (see section
17670 \begin_inset LatexCommand \ref{sec:Quality-control}
17671
17672 \end_inset
17673
17674 ) as the MCS51 and DS390 ports, so floating point support, support for long
17675  variables and bitfield support is fine.
17676  See mailing lists and forums about interrupt routines.
17677 \layout Standard
17678 \added_space_bottom bigskip
17679 As always, the code is the authoritative reference - see z80/ralloc.c and
17680  z80/gen.c.
17681  The stack
17682 \begin_inset LatexCommand \index{Z80!stack}
17683
17684 \end_inset
17685
17686  frame is similar to that generated by the IAR Z80 compiler.
17687  IX is used as the base pointer, HL and IY are used as a temporary registers,
17688  and BC and DE are available for holding variables.
17689  Return values
17690 \begin_inset LatexCommand \index{Z80!return value}
17691
17692 \end_inset
17693
17694  for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
17695  bytes).
17696  The gbz80 port use the same set of registers for the return values, but
17697  in a different order of significance: E (one byte), DE (two bytes), or
17698  HLDE (four bytes).
17699 \layout Section
17700
17701 The HC08 port
17702 \layout Standard
17703
17704 The port to the Freescale/Motorola HC08
17705 \begin_inset LatexCommand \index{HC08}
17706
17707 \end_inset
17708
17709  family has been added in October 2003, and is still undergoing some basic
17710  development.
17711  The code generator is complete, but the register allocation is still quite
17712  unoptimized.
17713  Some of the SDCC's standard C library functions have embedded non-HC08
17714  inline assembly and so are not yet usable.
17715 \layout Standard
17716 \added_space_bottom bigskip
17717 The HC08 port passes the regression test suite (see section
17718 \begin_inset LatexCommand \ref{sec:Quality-control}
17719
17720 \end_inset
17721
17722 ).
17723 \layout Section
17724 \pagebreak_top
17725 The PIC14 port
17726 \layout Standard
17727
17728 The 14bit PIC
17729 \begin_inset LatexCommand \index{PIC14}
17730
17731 \end_inset
17732
17733  port still requires a major effort from the development community.
17734  However it can work for simple code.
17735  It passes its (smaller set of) regression tests
17736 \begin_inset LatexCommand \index{Regression test (PIC14)}
17737
17738 \end_inset
17739
17740  in the directory
17741 \shape italic
17742 sdcc/src/regression
17743 \shape default
17744 .
17745 \layout Subsection
17746
17747 C code and 14bit PIC code page
17748 \begin_inset LatexCommand \index{code page (pic14)}
17749
17750 \end_inset
17751
17752  and RAM banks
17753 \begin_inset LatexCommand \index{RAM bank (pic14)}
17754
17755 \end_inset
17756
17757
17758 \layout Standard
17759
17760 The linker organizes allocation for the code page and RAM banks.
17761  It does not have intimate knowledge of the code flow.
17762  It will put all the code section of a single asm file into a single code
17763  page.
17764  In order to make use of multiple code pages, separate asm files must be
17765  used.
17766  The compiler treats all functions of a single C file as being in the same
17767  code page unless it is non static.
17768  The compiler treats all local variables of a single C file as being in
17769  the same RAM bank unless it is an extern.
17770 \newline
17771
17772 \newline
17773 To get the best follow these guide lines:
17774 \layout Enumerate
17775
17776 make local functions static, as non static functions require code page selection
17777  overhead.
17778 \layout Enumerate
17779
17780 Make local variables static as extern variables require RAM bank selection
17781  overhead.
17782 \layout Enumerate
17783
17784 For devices that have multiple code pages it is more efficient to use the
17785  same number of files as pages, i.e.
17786  for the 16F877 use 4 separate files and i.e.
17787  for the 16F874 use 2 separate files.
17788  This way the linker can put the code for each file into different code
17789  pages and the compiler can allocate reusable variables more efficiently
17790  and there's less page selection overhead.
17791  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
17792  instruction set) use 'unsigned char' whereever possible instead of 'int'.
17793 \layout Subsection
17794
17795 Creating a device include file
17796 \layout Standard
17797
17798 For generating a device include file
17799 \begin_inset LatexCommand \index{PIC14!Header files}
17800
17801 \end_inset
17802
17803  use the support perl script inc2h.pl kept in directory support/script.
17804 \layout Subsection
17805
17806 Interrupt code
17807 \layout Standard
17808
17809 For the interrupt function, use the keyword 'interrupt'
17810 \begin_inset LatexCommand \index{PIC14!interrupt}
17811
17812 \end_inset
17813
17814  with level number of 0 (PIC14 only has 1 interrupt so this number is only
17815  there to avoid a syntax error - it ought to be fixed).
17816  E.g.:
17817 \layout Verse
17818
17819
17820 \family typewriter
17821 void Intr(void) interrupt 0
17822 \newline
17823 {
17824 \newline
17825 \SpecialChar ~
17826 \SpecialChar ~
17827 T0IF = 0; /* Clear timer interrupt */
17828 \newline
17829 }
17830 \layout Subsection
17831
17832 Linking and assembling
17833 \layout Standard
17834
17835 For assembling you can use either GPUTILS'
17836 \begin_inset LatexCommand \index{gputils (pic tools)}
17837
17838 \end_inset
17839
17840  gpasm.exe or MPLAB's mpasmwin.exe.
17841  GPUTILS is available from
17842 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
17843
17844 \end_inset
17845
17846 .
17847  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
17848  If you use MPLAB and an interrupt function then the linker script file
17849  vectors section will need to be enlarged to link with mplink.
17850 \newline
17851
17852 \newline
17853 Here is a
17854 \family typewriter
17855 Makefile
17856 \family default
17857  using GPUTILS:
17858 \layout Verse
17859
17860
17861 \family typewriter
17862 .c.o:
17863 \newline
17864 \SpecialChar ~
17865 \SpecialChar ~
17866 \SpecialChar ~
17867 \SpecialChar ~
17868 \SpecialChar ~
17869 \SpecialChar ~
17870 \SpecialChar ~
17871 \SpecialChar ~
17872 sdcc -S -V -mpic14 -p16F877 $<
17873 \newline
17874 \SpecialChar ~
17875 \SpecialChar ~
17876 \SpecialChar ~
17877 \SpecialChar ~
17878 \SpecialChar ~
17879 \SpecialChar ~
17880 \SpecialChar ~
17881 \SpecialChar ~
17882 gpasm -c $*.asm
17883 \newline
17884
17885 \newline
17886 $(PRJ).hex: $(OBJS)
17887 \newline
17888 \SpecialChar ~
17889 \SpecialChar ~
17890 \SpecialChar ~
17891 \SpecialChar ~
17892 \SpecialChar ~
17893 \SpecialChar ~
17894 \SpecialChar ~
17895 \SpecialChar ~
17896 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS) libsdcc.lib
17897 \layout Standard
17898
17899 Here is a
17900 \family typewriter
17901 Makefile
17902 \family default
17903  using MPLAB:
17904 \layout Verse
17905
17906
17907 \family typewriter
17908 .c.o:
17909 \newline
17910 \SpecialChar ~
17911 \SpecialChar ~
17912 \SpecialChar ~
17913 \SpecialChar ~
17914 \SpecialChar ~
17915 \SpecialChar ~
17916 \SpecialChar ~
17917 \SpecialChar ~
17918 sdcc -S -V -mpic14 -p16F877 $<
17919 \newline
17920 \SpecialChar ~
17921 \SpecialChar ~
17922 \SpecialChar ~
17923 \SpecialChar ~
17924 \SpecialChar ~
17925 \SpecialChar ~
17926 \SpecialChar ~
17927 \SpecialChar ~
17928 mpasmwin /q /o $*.asm
17929 \newline
17930
17931 \newline
17932 $(PRJ).hex: $(OBJS)
17933 \newline
17934 \SpecialChar ~
17935 \SpecialChar ~
17936 \SpecialChar ~
17937 \SpecialChar ~
17938 \SpecialChar ~
17939 \SpecialChar ~
17940 \SpecialChar ~
17941 \SpecialChar ~
17942 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS) libsdcc.lib
17943 \layout Standard
17944
17945 Please note that indentations within a
17946 \family typewriter
17947  Makefile
17948 \family default
17949  have to be done with a tabulator character.
17950 \layout Subsection
17951
17952 Command-line options
17953 \layout Standard
17954
17955 Besides the switches common to all SDCC backends, the PIC14 port accepts
17956  the following options (for an updated list see sdcc -
17957 \begin_inset ERT
17958 status Collapsed
17959
17960 \layout Standard
17961
17962 \backslash
17963 /
17964 \end_inset
17965
17966 -help):
17967 \layout List
17968 \labelwidthstring 00.00.0000
17969
17970 -
17971 \begin_inset ERT
17972 status Collapsed
17973
17974 \layout Standard
17975
17976 \backslash
17977 /
17978 \end_inset
17979
17980 -debug-extra
17981 \begin_inset LatexCommand \index{PIC14!Options!-\/-debug-extra}
17982
17983 \end_inset
17984
17985  emit debug info in assembly output
17986 \layout List
17987 \labelwidthstring 00.00.0000
17988
17989 -
17990 \begin_inset ERT
17991 status Collapsed
17992
17993 \layout Standard
17994
17995 \backslash
17996 /
17997 \end_inset
17998
17999 -no-pcode-opt
18000 \begin_inset LatexCommand \index{PIC14!Options!-\/-no-pcode-opt}
18001
18002 \end_inset
18003
18004  disable (slightly faulty) optimization on pCode
18005 \layout Subsection
18006
18007 The library
18008 \layout Subsubsection
18009
18010 error: missing definition for symbol
18011 \begin_inset Quotes sld
18012 \end_inset
18013
18014 __gptrget1
18015 \begin_inset Quotes srd
18016 \end_inset
18017
18018
18019 \layout Standard
18020
18021 The PIC14 port uses library routines to provide more complex operations
18022  like multiplication, division/modulus and (generic) pointer dereferencing.
18023  In order to add these routines to your project, you must link with PIC14's
18024
18025 \family typewriter
18026 libsdcc.lib
18027 \family default
18028 .
18029  For single source file projects this is done automatically, more complex
18030  projects must add
18031 \family typewriter
18032 libsdcc.lib
18033 \family default
18034  to the linker's arguments.
18035  Make sure you also add an include path for the library (using the -I switch
18036  to the linker)!
18037 \layout Subsubsection
18038
18039 Processor mismatch in file
18040 \begin_inset Quotes sld
18041 \end_inset
18042
18043 XXX
18044 \begin_inset Quotes srd
18045 \end_inset
18046
18047 .
18048 \layout Standard
18049
18050 This warning can usually be ignored due to the very good compatibility amongst
18051  14 bit PIC
18052 \begin_inset LatexCommand \index{PIC14}
18053
18054 \end_inset
18055
18056  devices.
18057 \layout Standard
18058
18059 You might also consider recompiling the library for your specific device
18060  by changing the ARCH=p16f877 (default target) entry in
18061 \family typewriter
18062 device/lib/pic/Makefile.in
18063 \family default
18064  and
18065 \family typewriter
18066 device/lib/pic/Makefile
18067 \family default
18068  to reflect your device.
18069  This might even improve performance for smaller devices as unneccesary
18070  BANKSELs migth be removed.
18071 \layout Subsection
18072
18073 Known bugs
18074 \layout Subsubsection
18075
18076 initialized data
18077 \layout Standard
18078
18079 Currently, data can only be initialized if it resides in the source file
18080  together with
18081 \emph on
18082 main()
18083 \emph default
18084 .
18085  Data in other source files will silently
18086 \series bold
18087 not
18088 \series default
18089  be initialized.
18090 \family typewriter
18091 \size footnotesize
18092
18093 \begin_inset Marginal
18094 collapsed true
18095
18096 \layout Standard
18097
18098
18099 \series bold
18100 \SpecialChar ~
18101 !
18102 \end_inset
18103
18104
18105 \layout Section
18106 \pagebreak_top
18107 The PIC16
18108 \begin_inset LatexCommand \index{PIC16}
18109
18110 \end_inset
18111
18112  port
18113 \layout Standard
18114
18115 The PIC16
18116 \begin_inset LatexCommand \index{PIC16}
18117
18118 \end_inset
18119
18120  port is the portion of SDCC that is responsible to produce code for the
18121  Microchip
18122 \begin_inset LatexCommand \index{Microchip}
18123
18124 \end_inset
18125
18126 (TM) microcontrollers with 16 bit core.
18127  Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
18128  Currently supported devices are:
18129 \layout Standard
18130 \align center
18131
18132 \begin_inset  Tabular
18133 <lyxtabular version="3" rows="4" columns="6">
18134 <features>
18135 <column alignment="center" valignment="top" leftline="true" width="0">
18136 <column alignment="center" valignment="top" leftline="true" width="0">
18137 <column alignment="center" valignment="top" leftline="true" width="0">
18138 <column alignment="center" valignment="top" leftline="true" width="0">
18139 <column alignment="center" valignment="top" leftline="true" width="0">
18140 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18141 <row topline="true">
18142 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18143 \begin_inset Text
18144
18145 \layout Standard
18146
18147 18F242
18148 \end_inset
18149 </cell>
18150 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18151 \begin_inset Text
18152
18153 \layout Standard
18154
18155 18F248
18156 \end_inset
18157 </cell>
18158 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18159 \begin_inset Text
18160
18161 \layout Standard
18162
18163 18F252
18164 \end_inset
18165 </cell>
18166 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18167 \begin_inset Text
18168
18169 \layout Standard
18170
18171 18F258
18172 \end_inset
18173 </cell>
18174 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18175 \begin_inset Text
18176
18177 \layout Standard
18178
18179 18F442
18180 \end_inset
18181 </cell>
18182 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18183 \begin_inset Text
18184
18185 \layout Standard
18186
18187 18F448
18188 \end_inset
18189 </cell>
18190 </row>
18191 <row topline="true">
18192 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18193 \begin_inset Text
18194
18195 \layout Standard
18196
18197 18F452
18198 \end_inset
18199 </cell>
18200 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18201 \begin_inset Text
18202
18203 \layout Standard
18204
18205 18F458
18206 \end_inset
18207 </cell>
18208 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18209 \begin_inset Text
18210
18211 \layout Standard
18212
18213 18F1220
18214 \end_inset
18215 </cell>
18216 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18217 \begin_inset Text
18218
18219 \layout Standard
18220
18221 18F2220
18222 \end_inset
18223 </cell>
18224 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18225 \begin_inset Text
18226
18227 \layout Standard
18228
18229 18F2550
18230 \end_inset
18231 </cell>
18232 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18233 \begin_inset Text
18234
18235 \layout Standard
18236
18237 18F4331
18238 \end_inset
18239 </cell>
18240 </row>
18241 <row topline="true">
18242 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18243 \begin_inset Text
18244
18245 \layout Standard
18246
18247 18F4455
18248 \end_inset
18249 </cell>
18250 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18251 \begin_inset Text
18252
18253 \layout Standard
18254
18255 18F6520
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 18F6620
18264 \end_inset
18265 </cell>
18266 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18267 \begin_inset Text
18268
18269 \layout Standard
18270
18271 18F6680
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 18F6720
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 18F8520
18288 \end_inset
18289 </cell>
18290 </row>
18291 <row topline="true" bottomline="true">
18292 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18293 \begin_inset Text
18294
18295 \layout Standard
18296
18297 18F8620
18298 \end_inset
18299 </cell>
18300 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18301 \begin_inset Text
18302
18303 \layout Standard
18304
18305 18F8680
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 18F8720
18314 \end_inset
18315 </cell>
18316 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18317 \begin_inset Text
18318
18319 \layout Standard
18320
18321 \end_inset
18322 </cell>
18323 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18324 \begin_inset Text
18325
18326 \layout Standard
18327
18328 \end_inset
18329 </cell>
18330 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18331 \begin_inset Text
18332
18333 \layout Standard
18334
18335 \end_inset
18336 </cell>
18337 </row>
18338 </lyxtabular>
18339
18340 \end_inset
18341
18342
18343 \layout Subsection
18344
18345 Global Options
18346 \layout Standard
18347
18348 PIC16 port supports the standard command line arguments as supposed, with
18349  the exception of certain cases that will be mentioned in the following
18350  list:
18351 \layout List
18352 \labelwidthstring 00.00.0000
18353
18354 -
18355 \begin_inset ERT
18356 status Collapsed
18357
18358 \layout Standard
18359
18360 \backslash
18361 /
18362 \end_inset
18363
18364 -callee-saves
18365 \begin_inset LatexCommand \index{PIC16!Options!-\/-callee-saves}
18366
18367 \end_inset
18368
18369  See -
18370 \begin_inset ERT
18371 status Collapsed
18372
18373 \layout Standard
18374
18375 \backslash
18376 /
18377 \end_inset
18378
18379 -all-callee-saves
18380 \layout List
18381 \labelwidthstring 00.00.0000
18382
18383 -
18384 \begin_inset ERT
18385 status Collapsed
18386
18387 \layout Standard
18388
18389 \backslash
18390 /
18391 \end_inset
18392
18393 -all-callee-saves
18394 \begin_inset LatexCommand \index{PIC16!Options!-\/-all-callee-saves}
18395
18396 \end_inset
18397
18398  All function arguments are passed on stack by default.
18399
18400 \emph on
18401 There is no need to specify this in the command line.
18402 \layout List
18403 \labelwidthstring 00.00.0000
18404
18405 -
18406 \begin_inset ERT
18407 status Collapsed
18408
18409 \layout Standard
18410
18411 \backslash
18412 /
18413 \end_inset
18414
18415 -fommit-frame-pointer
18416 \begin_inset LatexCommand \index{PIC16!Options!-\/-fommit-frame-pointer}
18417
18418 \end_inset
18419
18420  Frame pointer will be omitted when the function uses no local variables.
18421 \layout Subsection
18422
18423 Port Specific Options
18424 \begin_inset LatexCommand \index{Options PIC16}
18425
18426 \end_inset
18427
18428
18429 \layout Standard
18430
18431 The port specific options appear after the global options in the sdcc --help
18432  output.
18433 \layout Subsubsection
18434
18435 General Options
18436 \layout Standard
18437
18438 General options enable certain port features and optimizations.
18439 \layout List
18440 \labelwidthstring 00.00.0000
18441
18442 -
18443 \begin_inset ERT
18444 status Collapsed
18445
18446 \layout Standard
18447
18448 \backslash
18449 /
18450 \end_inset
18451
18452 -stack-model=[model] Used in conjuction with the command above.
18453  Defines the stack model to be used, valid stack models are :
18454 \begin_deeper
18455 \layout List
18456 \labelwidthstring 00.00.0000
18457
18458
18459 \emph on
18460 small
18461 \emph default
18462  Selects small stack model.
18463  8 bit stack and frame pointers.
18464  Supports 256 bytes stack size.
18465 \layout List
18466 \labelwidthstring 00.00.0000
18467
18468
18469 \emph on
18470 large
18471 \emph default
18472  Selects large stack model.
18473  16 bit stack and frame pointers.
18474  Supports 65536 bytes stack size.
18475 \end_deeper
18476 \layout List
18477 \labelwidthstring 00.00.0000
18478
18479 -
18480 \begin_inset ERT
18481 status Collapsed
18482
18483 \layout Standard
18484
18485 \backslash
18486 /
18487 \end_inset
18488
18489 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
18490  unitialized data variables with [kword].
18491  Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
18492 \layout List
18493 \labelwidthstring 00.00.0000
18494
18495 -
18496 \begin_inset ERT
18497 status Collapsed
18498
18499 \layout Standard
18500
18501 \backslash
18502 /
18503 \end_inset
18504
18505 -ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
18506  Useful for bootloaders.
18507 \layout List
18508 \labelwidthstring 00.00.0000
18509
18510 -
18511 \begin_inset ERT
18512 status Collapsed
18513
18514 \layout Standard
18515
18516 \backslash
18517 /
18518 \end_inset
18519
18520 -asm= sets the full path and name of an external assembler to call.
18521 \layout List
18522 \labelwidthstring 00.00.0000
18523
18524 -
18525 \begin_inset ERT
18526 status Collapsed
18527
18528 \layout Standard
18529
18530 \backslash
18531 /
18532 \end_inset
18533
18534 -link= sets the full path and name of an external linker to call.
18535 \layout List
18536 \labelwidthstring 00.00.0000
18537
18538 -
18539 \begin_inset ERT
18540 status Collapsed
18541
18542 \layout Standard
18543
18544 \backslash
18545 /
18546 \end_inset
18547
18548 -mplab-comp MPLAB
18549 \begin_inset LatexCommand \index{PIC16!MPLAB}
18550
18551 \end_inset
18552
18553  compatibility option.
18554  Currently only suppresses special gpasm directives.
18555 \layout Subsubsection
18556
18557 Optimization Options
18558 \layout List
18559 \labelwidthstring 00.00.0000
18560
18561 -
18562 \begin_inset ERT
18563 status Collapsed
18564
18565 \layout Standard
18566
18567 \backslash
18568 /
18569 \end_inset
18570
18571 -optimize-goto Try to use (conditional) BRA instead of GOTO
18572 \layout List
18573 \labelwidthstring 00.00.0000
18574
18575 -
18576 \begin_inset ERT
18577 status Collapsed
18578
18579 \layout Standard
18580
18581 \backslash
18582 /
18583 \end_inset
18584
18585 -optimize-cmp Try to optimize some compares.
18586 \layout List
18587 \labelwidthstring 00.00.0000
18588
18589 -
18590 \begin_inset ERT
18591 status Collapsed
18592
18593 \layout Standard
18594
18595 \backslash
18596 /
18597 \end_inset
18598
18599 -optimize-df Analyze the dataflow of the generated code and improve it.
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 -obanksel=nn Set optimization level for inserting BANKSELs.
18614 \newline
18615
18616 \begin_deeper
18617 \layout List
18618 \labelwidthstring 00.00.0000
18619
18620 0 no optimization
18621 \layout List
18622 \labelwidthstring 00.00.0000
18623
18624 1 checks previous used register and if it is the same then does not emit
18625  BANKSEL, accounts only for labels.
18626 \layout List
18627 \labelwidthstring 00.00.0000
18628
18629 2 tries to check the location of (even different) symbols and removes BANKSELs
18630  if they are in the same bank.
18631
18632 \newline
18633
18634 \emph on
18635 Important: There might be problems if the linker script has data sections
18636  across bank borders!
18637 \end_deeper
18638 \layout Subsubsection
18639
18640 Linking Options
18641 \layout List
18642 \labelwidthstring 00.00.0000
18643
18644 -
18645 \begin_inset ERT
18646 status Collapsed
18647
18648 \layout Standard
18649
18650 \backslash
18651 /
18652 \end_inset
18653
18654 -nodefaultlibs do not link default libraries when linking
18655 \layout List
18656 \labelwidthstring 00.00.0000
18657
18658 -
18659 \begin_inset ERT
18660 status Collapsed
18661
18662 \layout Standard
18663
18664 \backslash
18665 /
18666 \end_inset
18667
18668 -no-crt Don't link the default run-time modules
18669 \layout List
18670 \labelwidthstring 00.00.0000
18671
18672 -
18673 \begin_inset ERT
18674 status Collapsed
18675
18676 \layout Standard
18677
18678 \backslash
18679 /
18680 \end_inset
18681
18682 -use-crt= Use a custom run-time module instead of the defaults.
18683 \layout Subsubsection
18684
18685 Debugging Options
18686 \layout Standard
18687
18688 Debugging options enable extra debugging information in the output files.
18689 \layout List
18690 \labelwidthstring 00.00.0000
18691
18692 -
18693 \begin_inset ERT
18694 status Collapsed
18695
18696 \layout Standard
18697
18698 \backslash
18699 /
18700 \end_inset
18701
18702 -debug-xtra Similar to -
18703 \begin_inset ERT
18704 status Collapsed
18705
18706 \layout Standard
18707
18708 \backslash
18709 /
18710 \end_inset
18711
18712 -debug
18713 \begin_inset LatexCommand \index{-\/-debug}
18714
18715 \end_inset
18716
18717 , but dumps more information.
18718 \layout List
18719 \labelwidthstring 00.00.0000
18720
18721 -
18722 \begin_inset ERT
18723 status Collapsed
18724
18725 \layout Standard
18726
18727 \backslash
18728 /
18729 \end_inset
18730
18731 -debug-ralloc Force register allocator to dump <source>.d file with debugging
18732  information.
18733  <source> is the name of the file compiled.
18734 \layout List
18735 \labelwidthstring 00.00.0000
18736
18737 -
18738 \begin_inset ERT
18739 status Collapsed
18740
18741 \layout Standard
18742
18743 \backslash
18744 /
18745 \end_inset
18746
18747 -pcode-verbose Enable pcode debugging information in translation.
18748 \layout List
18749 \labelwidthstring 00.00.0000
18750
18751 -
18752 \begin_inset ERT
18753 status Collapsed
18754
18755 \layout Standard
18756
18757 \backslash
18758 /
18759 \end_inset
18760
18761 -denable-peeps Force the usage of peepholes.
18762  Use with care.
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 -gstack Trace push/pops for stack pointer overflow
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 -call-tree dump call tree in .calltree file
18791 \layout Subsection
18792
18793 Enviromental Variables
18794 \layout Standard
18795
18796 There is a number of enviromental variables that can be used when running
18797  SDCC to enable certain optimizations or force a specific program behaviour.
18798  these variables are primarily for debugging purposes so they can be enabled/dis
18799 abled at will.
18800 \layout Standard
18801
18802 Currently there is only two such variables available:
18803 \layout List
18804 \labelwidthstring 00.00.0000
18805
18806 OPTIMIZE_BITFIELD_POINTER_GET when this variable exists reading of structure
18807  bitfields is optimized by directly loading FSR0 with the address of the
18808  bitfield structure.
18809  Normally SDCC will cast the bitfield structure to a bitfield pointer and
18810  then load FSR0.
18811  This step saves data ram and code space for functions that perform heavy
18812  use of bitfields.
18813  (ie.
18814  80 bytes of code space are saved when compiling malloc.c with this option).
18815
18816 \layout List
18817 \labelwidthstring 00.00.0000
18818
18819 NO_REG_OPT do not perform pCode registers optimization.
18820  This should be used for debugging purposes.
18821  In some where bugs in the pcode optimizer are found, users can benefit
18822  from temporarily disabling the optimizer until the bug is fixed.
18823 \layout Subsection
18824
18825 Preprocessor Macros
18826 \layout Standard
18827
18828 PIC16
18829 \begin_inset LatexCommand \index{PIC16}
18830
18831 \end_inset
18832
18833  port defines the following preprocessor macros while translating a source.
18834 \layout Standard
18835 \align center
18836
18837 \begin_inset  Tabular
18838 <lyxtabular version="3" rows="6" columns="2">
18839 <features>
18840 <column alignment="center" valignment="top" leftline="true" width="0">
18841 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18842 <row topline="true" bottomline="true">
18843 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18844 \begin_inset Text
18845
18846 \layout Standard
18847
18848 Macro
18849 \end_inset
18850 </cell>
18851 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18852 \begin_inset Text
18853
18854 \layout Standard
18855
18856 Description
18857 \end_inset
18858 </cell>
18859 </row>
18860 <row topline="true">
18861 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18862 \begin_inset Text
18863
18864 \layout Standard
18865
18866 SDCC_pic16
18867 \end_inset
18868 </cell>
18869 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18870 \begin_inset Text
18871
18872 \layout Standard
18873
18874 Port identification
18875 \end_inset
18876 </cell>
18877 </row>
18878 <row topline="true">
18879 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18880 \begin_inset Text
18881
18882 \layout Standard
18883
18884 _
18885 \begin_inset ERT
18886 status Collapsed
18887
18888 \layout Standard
18889
18890 \backslash
18891 /
18892 \end_inset
18893
18894 _pic16
18895 \end_inset
18896 </cell>
18897 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18898 \begin_inset Text
18899
18900 \layout Standard
18901
18902 Port identification (same as above)
18903 \end_inset
18904 </cell>
18905 </row>
18906 <row topline="true">
18907 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18908 \begin_inset Text
18909
18910 \layout Standard
18911
18912 pic18fxxxx
18913 \end_inset
18914 </cell>
18915 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18916 \begin_inset Text
18917
18918 \layout Standard
18919
18920 MCU Identification.
18921
18922 \emph on
18923 xxxx
18924 \emph default
18925  is the microcontrol identification number, i.e.
18926  452, 6620, etc
18927 \end_inset
18928 </cell>
18929 </row>
18930 <row topline="true">
18931 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18932 \begin_inset Text
18933
18934 \layout Standard
18935
18936 _
18937 \begin_inset ERT
18938 status Collapsed
18939
18940 \layout Standard
18941
18942 \backslash
18943 /
18944 \end_inset
18945
18946 _18Fxxxx
18947 \end_inset
18948 </cell>
18949 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18950 \begin_inset Text
18951
18952 \layout Standard
18953
18954 MCU Identification (same as above)
18955 \end_inset
18956 </cell>
18957 </row>
18958 <row topline="true" bottomline="true">
18959 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18960 \begin_inset Text
18961
18962 \layout Standard
18963
18964 STACK_MODEL_nnn
18965 \end_inset
18966 </cell>
18967 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18968 \begin_inset Text
18969
18970 \layout Standard
18971
18972 nnn = SMALL or LARGE respectively according to the stack model used
18973 \end_inset
18974 </cell>
18975 </row>
18976 </lyxtabular>
18977
18978 \end_inset
18979
18980
18981 \layout Standard
18982
18983 In addition the following macros are defined when calling assembler:
18984 \layout Standard
18985 \align center
18986
18987 \begin_inset  Tabular
18988 <lyxtabular version="3" rows="4" columns="2">
18989 <features>
18990 <column alignment="center" valignment="top" leftline="true" width="0">
18991 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18992 <row topline="true" bottomline="true">
18993 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18994 \begin_inset Text
18995
18996 \layout Standard
18997
18998 Macro
18999 \end_inset
19000 </cell>
19001 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19002 \begin_inset Text
19003
19004 \layout Standard
19005
19006 Description
19007 \end_inset
19008 </cell>
19009 </row>
19010 <row topline="true">
19011 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19012 \begin_inset Text
19013
19014 \layout Standard
19015
19016 __18Fxxxx
19017 \end_inset
19018 </cell>
19019 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19020 \begin_inset Text
19021
19022 \layout Standard
19023
19024 MCU Identification.
19025
19026 \emph on
19027 xxxx
19028 \emph default
19029  is the microcontrol identification number, i.e.
19030  452, 6620, etc
19031 \end_inset
19032 </cell>
19033 </row>
19034 <row topline="true">
19035 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19036 \begin_inset Text
19037
19038 \layout Standard
19039
19040 SDCC_MODEL_nnn
19041 \end_inset
19042 </cell>
19043 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19044 \begin_inset Text
19045
19046 \layout Standard
19047
19048 nnn = SMALL or LARGE respectively according to the memory model used for
19049  SDCC
19050 \end_inset
19051 </cell>
19052 </row>
19053 <row topline="true" bottomline="true">
19054 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19055 \begin_inset Text
19056
19057 \layout Standard
19058
19059 STACK_MODEL_nnn
19060 \end_inset
19061 </cell>
19062 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19063 \begin_inset Text
19064
19065 \layout Standard
19066
19067 nnn = SMALL or LARGE respectively according to the stack model used
19068 \end_inset
19069 </cell>
19070 </row>
19071 </lyxtabular>
19072
19073 \end_inset
19074
19075
19076 \layout Subsection
19077
19078 Directories
19079 \layout Standard
19080
19081 PIC16
19082 \begin_inset LatexCommand \index{PIC16}
19083
19084 \end_inset
19085
19086  port uses the following directories for searching header files and libraries.
19087 \layout Standard
19088 \align center
19089
19090 \begin_inset  Tabular
19091 <lyxtabular version="3" rows="3" columns="4">
19092 <features>
19093 <column alignment="center" valignment="top" leftline="true" width="0">
19094 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19095 <column alignment="center" valignment="top" width="0">
19096 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19097 <row topline="true" bottomline="true">
19098 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19099 \begin_inset Text
19100
19101 \layout Standard
19102
19103 Directory
19104 \end_inset
19105 </cell>
19106 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19107 \begin_inset Text
19108
19109 \layout Standard
19110
19111 Description
19112 \end_inset
19113 </cell>
19114 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19115 \begin_inset Text
19116
19117 \layout Standard
19118
19119 Target
19120 \end_inset
19121 </cell>
19122 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19123 \begin_inset Text
19124
19125 \layout Standard
19126
19127 Command prefix
19128 \end_inset
19129 </cell>
19130 </row>
19131 <row topline="true">
19132 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19133 \begin_inset Text
19134
19135 \layout Standard
19136
19137 PREFIX/sdcc/include/pic16
19138 \end_inset
19139 </cell>
19140 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19141 \begin_inset Text
19142
19143 \layout Standard
19144
19145 PIC16 specific headers
19146 \end_inset
19147 </cell>
19148 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19149 \begin_inset Text
19150
19151 \layout Standard
19152
19153 Compiler
19154 \end_inset
19155 </cell>
19156 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19157 \begin_inset Text
19158
19159 \layout Standard
19160
19161 -I
19162 \end_inset
19163 </cell>
19164 </row>
19165 <row topline="true" bottomline="true">
19166 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19167 \begin_inset Text
19168
19169 \layout Standard
19170
19171 PREFIX/sdcc/lib/pic16
19172 \end_inset
19173 </cell>
19174 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19175 \begin_inset Text
19176
19177 \layout Standard
19178
19179 PIC16 specific libraries
19180 \end_inset
19181 </cell>
19182 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19183 \begin_inset Text
19184
19185 \layout Standard
19186
19187 Linker
19188 \end_inset
19189 </cell>
19190 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19191 \begin_inset Text
19192
19193 \layout Standard
19194
19195 -L
19196 \end_inset
19197 </cell>
19198 </row>
19199 </lyxtabular>
19200
19201 \end_inset
19202
19203
19204 \layout Subsection
19205
19206 Pragmas
19207 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
19208
19209 \end_inset
19210
19211
19212 \layout Standard
19213
19214 PIC16
19215 \begin_inset LatexCommand \index{PIC16}
19216
19217 \end_inset
19218
19219  port currently supports the following pragmas:
19220 \layout List
19221 \labelwidthstring 00.00.0000
19222
19223 stack
19224 \begin_inset LatexCommand \index{PIC16!Pragmas!\#pragma stack}
19225
19226 \end_inset
19227
19228  pragma stack
19229 \begin_inset LatexCommand \index{PIC16!stack}
19230
19231 \end_inset
19232
19233  forces the code generator to initialize the stack & frame pointers at a
19234  specific address.
19235  This is an adhoc solution for cases where no STACK directive is available
19236  in the linker script or gplink is not instructed to create a stack section.
19237 \newline
19238 The stack pragma should be used only once in a project.
19239  Multiple pragmas may result in indeterminate behaviour of the program.
19240 \begin_inset Foot
19241 collapsed false
19242
19243 \layout Standard
19244
19245 The old format (ie.
19246  #pragma stack 0x5ff) is deprecated and will cause the stack pointer to
19247  cross page boundaries (or even exceed the available data RAM) and crash
19248  the program.
19249  Make sure that stack does not cross page boundaries when using the SMALL
19250  stack model.
19251 \end_inset
19252
19253
19254 \newline
19255 The format is as follows:
19256 \layout LyX-Code
19257
19258 #pragma stack bottom_address [stack_size]
19259 \layout Standard
19260
19261
19262 \emph on
19263 bottom_address
19264 \emph default
19265  is the lower bound of the stack section.
19266  The stack pointer initially will point at address (bottom_address+stack_size-1).
19267 \layout LyX-Code
19268
19269 Example:
19270 \layout LyX-Code
19271
19272 \layout LyX-Code
19273
19274 /* initializes stack of 100 bytes at RAM address 0x200 */
19275 \layout LyX-Code
19276
19277 #pragma stack 0x200 100
19278 \layout Standard
19279
19280 If the stack_size field is omitted then a stack is created with the default
19281  size of 64.
19282  This size might be enough for most programs, but its not enough for operations
19283  with deep function nesting or excessive stack usage.
19284 \layout List
19285 \labelwidthstring 00.00.0000
19286
19287 code
19288 \begin_inset LatexCommand \index{PIC16!Pragmas!\#pragma code}
19289
19290 \end_inset
19291
19292  place a function symbol at static FLASH address
19293 \layout LyX-Code
19294
19295 Example:
19296 \layout LyX-Code
19297
19298 \layout LyX-Code
19299
19300 /* place function test_func at 0x4000 */
19301 \layout LyX-Code
19302
19303 #pragma code test_func 0x4000
19304 \layout LyX-Code
19305
19306 \layout List
19307 \labelwidthstring 00.00.0000
19308
19309 library instructs the linker to use a library module.
19310 \newline
19311 Usage:
19312 \layout LyX-Code
19313
19314 #pragma library module_name
19315 \layout Standard
19316
19317
19318 \emph on
19319 module_name
19320 \emph default
19321  can be any library or object file (including its path).
19322  Note that there are four reserved keywords which have special meaning.
19323  These are:
19324 \layout Standard
19325 \align center
19326
19327 \begin_inset  Tabular
19328 <lyxtabular version="3" rows="6" columns="3">
19329 <features>
19330 <column alignment="center" valignment="top" leftline="true" width="0">
19331 <column alignment="block" valignment="top" leftline="true" width="20page%">
19332 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
19333 <row topline="true" bottomline="true">
19334 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19335 \begin_inset Text
19336
19337 \layout Standard
19338
19339 Keyword
19340 \end_inset
19341 </cell>
19342 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19343 \begin_inset Text
19344
19345 \layout Standard
19346
19347 Description
19348 \end_inset
19349 </cell>
19350 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19351 \begin_inset Text
19352
19353 \layout Standard
19354
19355 Module to link
19356 \end_inset
19357 </cell>
19358 </row>
19359 <row topline="true">
19360 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19361 \begin_inset Text
19362
19363 \layout Standard
19364
19365
19366 \series bold
19367 ignore
19368 \end_inset
19369 </cell>
19370 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19371 \begin_inset Text
19372
19373 \layout Standard
19374
19375 ignore all library pragmas
19376 \end_inset
19377 </cell>
19378 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19379 \begin_inset Text
19380
19381 \layout Standard
19382
19383
19384 \emph on
19385 (none)
19386 \end_inset
19387 </cell>
19388 </row>
19389 <row topline="true">
19390 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19391 \begin_inset Text
19392
19393 \layout Standard
19394
19395
19396 \series bold
19397 c
19398 \end_inset
19399 </cell>
19400 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19401 \begin_inset Text
19402
19403 \layout Standard
19404
19405 link the C library
19406 \end_inset
19407 </cell>
19408 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19409 \begin_inset Text
19410
19411 \layout Standard
19412
19413
19414 \emph on
19415 libc18f
19416 \emph default
19417 .lib
19418 \end_inset
19419 </cell>
19420 </row>
19421 <row topline="true">
19422 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19423 \begin_inset Text
19424
19425 \layout Standard
19426
19427
19428 \series bold
19429 math
19430 \end_inset
19431 </cell>
19432 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19433 \begin_inset Text
19434
19435 \layout Standard
19436
19437 link the Math libarary
19438 \end_inset
19439 </cell>
19440 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19441 \begin_inset Text
19442
19443 \layout Standard
19444
19445
19446 \emph on
19447 libm18f
19448 \emph default
19449 .lib
19450 \end_inset
19451 </cell>
19452 </row>
19453 <row topline="true">
19454 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19455 \begin_inset Text
19456
19457 \layout Standard
19458
19459
19460 \series bold
19461 io
19462 \end_inset
19463 </cell>
19464 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19465 \begin_inset Text
19466
19467 \layout Standard
19468
19469 link the I/O library
19470 \end_inset
19471 </cell>
19472 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19473 \begin_inset Text
19474
19475 \layout Standard
19476
19477
19478 \emph on
19479 libio18f*
19480 \emph default
19481 .lib
19482 \end_inset
19483 </cell>
19484 </row>
19485 <row topline="true" bottomline="true">
19486 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19487 \begin_inset Text
19488
19489 \layout Standard
19490
19491
19492 \series bold
19493 debug
19494 \end_inset
19495 </cell>
19496 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19497 \begin_inset Text
19498
19499 \layout Standard
19500
19501 link the debug library
19502 \end_inset
19503 </cell>
19504 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19505 \begin_inset Text
19506
19507 \layout Standard
19508
19509
19510 \emph on
19511 libdebug
19512 \emph default
19513 .lib
19514 \end_inset
19515 </cell>
19516 </row>
19517 </lyxtabular>
19518
19519 \end_inset
19520
19521
19522 \newline
19523 * is the device number, i.e.
19524  452 for PIC18F452 MCU.
19525 \layout Standard
19526
19527 This feature allows for linking with specific libraries withoug having to
19528  explicit name them in the command line.
19529  Note that the
19530 \noun on
19531 ignore
19532 \noun default
19533  keyword will reject all modules specified by the library pragma.
19534 \layout List
19535 \labelwidthstring 00.00.0000
19536
19537 udata pragma udata instructs the compiler to emit code so that linker will
19538  place a variable at a specific memory bank
19539 \layout LyX-Code
19540
19541 Example:
19542 \layout LyX-Code
19543
19544 \layout LyX-Code
19545
19546 /* places variable foo at bank2 */
19547 \layout LyX-Code
19548
19549 #pragma udata bank2 foo
19550 \layout LyX-Code
19551
19552 char foo;
19553 \layout Standard
19554
19555 In order for this pragma to work extra SECTION directives should be added
19556  in the .lkr script.
19557  In the following example a sample .lkr file is shown:
19558 \layout LyX-Code
19559
19560 \layout LyX-Code
19561
19562 // Sample linker script for the PIC18F452 processor
19563 \layout LyX-Code
19564
19565 LIBPATH .
19566 \layout LyX-Code
19567
19568 CODEPAGE   NAME=vectors    START=0x0            END=0x29           PROTECTED
19569 \layout LyX-Code
19570
19571 CODEPAGE   NAME=page       START=0x2A           END=0x7FFF
19572 \layout LyX-Code
19573
19574 CODEPAGE   NAME=idlocs     START=0x200000       END=0x200007       PROTECTED
19575 \layout LyX-Code
19576
19577 CODEPAGE   NAME=config     START=0x300000       END=0x30000D       PROTECTED
19578 \layout LyX-Code
19579
19580 CODEPAGE   NAME=devid      START=0x3FFFFE       END=0x3FFFFF       PROTECTED
19581 \layout LyX-Code
19582
19583 CODEPAGE   NAME=eedata     START=0xF00000       END=0xF000FF       PROTECTED
19584 \layout LyX-Code
19585
19586 ACCESSBANK NAME=accessram  START=0x0            END=0x7F
19587 \layout LyX-Code
19588
19589 \layout LyX-Code
19590
19591 DATABANK   NAME=gpr0       START=0x80           END=0xFF
19592 \layout LyX-Code
19593
19594 DATABANK   NAME=gpr1       START=0x100          END=0x1FF
19595 \layout LyX-Code
19596
19597 DATABANK   NAME=gpr2       START=0x200          END=0x2FF
19598 \layout LyX-Code
19599
19600 DATABANK   NAME=gpr3       START=0x300          END=0x3FF
19601 \layout LyX-Code
19602
19603 DATABANK   NAME=gpr4       START=0x400          END=0x4FF
19604 \layout LyX-Code
19605
19606 DATABANK   NAME=gpr5       START=0x500          END=0x5FF
19607 \layout LyX-Code
19608
19609 ACCESSBANK NAME=accesssfr  START=0xF80          END=0xFFF          PROTECTED
19610 \layout LyX-Code
19611
19612 \layout LyX-Code
19613
19614 SECTION    NAME=CONFIG     ROM=config
19615 \layout LyX-Code
19616
19617 \layout LyX-Code
19618
19619 SECTION    NAME=bank0      RAM=gpr0       # these SECTION directives
19620 \layout LyX-Code
19621
19622 SECTION    NAME=bank1      RAM=gpr1       # should be added to link
19623 \layout LyX-Code
19624
19625 SECTION    NAME=bank2      RAM=gpr2       # section name 'bank?' with
19626 \layout LyX-Code
19627
19628 SECTION    NAME=bank3      RAM=gpr3       # a specific DATABANK name
19629 \layout LyX-Code
19630
19631 SECTION    NAME=bank4      RAM=gpr4
19632 \layout LyX-Code
19633
19634 SECTION    NAME=bank5      RAM=gpr5
19635 \layout Standard
19636
19637 The linker will recognise the section name set in the pragma statement and
19638  will position the variable at the memory bank set with the RAM field at
19639  the SECTION line in the linker script file.
19640 \layout Subsection
19641
19642 Header Files
19643 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
19644
19645 \end_inset
19646
19647
19648 \layout Standard
19649
19650 There is one main header file
19651 \begin_inset LatexCommand \index{PIC16!Header files}
19652
19653 \end_inset
19654
19655  that can be included to the source files using the pic16
19656 \begin_inset LatexCommand \index{PIC16}
19657
19658 \end_inset
19659
19660  port.
19661  That file is the
19662 \series bold
19663 pic18fregs.h
19664 \series default
19665 .
19666  This header file contains the definitions for the processor special registers,
19667  so it is necessary if the source accesses them.
19668  It can be included by adding the following line in the beginning of the
19669  file:
19670 \layout LyX-Code
19671
19672 #include <pic18fregs.h>
19673 \layout Standard
19674
19675 The specific microcontroller is selected within the pic18fregs.h automatically,
19676  so the same source can be used with a variety of devices.
19677 \layout Subsection
19678
19679 Libraries
19680 \layout Standard
19681
19682 The libraries
19683 \begin_inset LatexCommand \index{PIC16!Libraries}
19684
19685 \end_inset
19686
19687  that PIC16
19688 \begin_inset LatexCommand \index{PIC16}
19689
19690 \end_inset
19691
19692  port depends on are the microcontroller device libraries which contain
19693  the symbol definitions for the microcontroller special function registers.
19694  These libraries have the format pic18fxxxx.lib, where
19695 \emph on
19696 xxxx
19697 \emph default
19698  is the microcontroller identification number.
19699  The specific library is selected automatically by the compiler at link
19700  stage according to the selected device.
19701 \layout Standard
19702
19703 Libraries are created with gplib which is part of the gputils package
19704 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
19705
19706 \end_inset
19707
19708 .
19709 \layout Subsubsection*
19710
19711 Building the libraries
19712 \layout Standard
19713
19714 Before using SDCC/pic16 there are some libraries that need to be compiled.
19715  This process is not done automatically by SDCC since not all users use
19716  SDCC for pic16 projects.
19717  So each user should compile the libraries separately.
19718 \layout Standard
19719
19720 The steps to compile the pic16 libraries under Linux are:
19721 \layout LyX-Code
19722
19723 cd device/lib/pic16
19724 \layout LyX-Code
19725
19726 ./configure
19727 \layout LyX-Code
19728
19729 make
19730 \layout LyX-Code
19731
19732 cd ..
19733 \layout LyX-Code
19734
19735 make model-pic16
19736 \layout LyX-Code
19737
19738 su -c 'make install'     # install the libraries, you need the root password
19739 \layout Standard
19740
19741 If you need to install the headers too, do:
19742 \layout LyX-Code
19743
19744 cd device/include
19745 \layout LyX-Code
19746
19747 su -c 'make install'     # install the headers, you need the root password
19748 \layout Standard
19749
19750 There exist a special target to build the I/O libraries.
19751  This target is not automatically build because it will build the I/O library
19752  for
19753 \emph on
19754 every
19755 \emph default
19756  supported device.
19757  This way building will take quite a lot of time.
19758  Users are advised to edit the
19759 \series bold
19760 device/lib/pic16/pics.build
19761 \series default
19762  file and then execute:
19763 \layout LyX-Code
19764
19765 make lib-io
19766 \layout Subsection
19767
19768 Memory Models
19769 \layout Standard
19770
19771 The following memory models are supported by the PIC16 port:
19772 \layout Itemize
19773
19774 small model
19775 \layout Itemize
19776
19777 large model
19778 \layout Standard
19779
19780 Memory model affects the default size of pointers within the source.
19781  The sizes are shown in the next table:
19782 \layout Standard
19783 \align center
19784
19785 \begin_inset  Tabular
19786 <lyxtabular version="3" rows="3" columns="3">
19787 <features>
19788 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19789 <column alignment="center" valignment="top" leftline="true" width="0">
19790 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19791 <row topline="true" bottomline="true">
19792 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19793 \begin_inset Text
19794
19795 \layout Standard
19796
19797 Pointer sizes according to memory model
19798 \end_inset
19799 </cell>
19800 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19801 \begin_inset Text
19802
19803 \layout Standard
19804
19805 small model
19806 \end_inset
19807 </cell>
19808 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19809 \begin_inset Text
19810
19811 \layout Standard
19812
19813 large model
19814 \end_inset
19815 </cell>
19816 </row>
19817 <row topline="true" bottomline="true">
19818 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19819 \begin_inset Text
19820
19821 \layout Standard
19822
19823 code pointers
19824 \end_inset
19825 </cell>
19826 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19827 \begin_inset Text
19828
19829 \layout Standard
19830
19831 16-bits
19832 \end_inset
19833 </cell>
19834 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19835 \begin_inset Text
19836
19837 \layout Standard
19838
19839 24-bits
19840 \end_inset
19841 </cell>
19842 </row>
19843 <row topline="true" bottomline="true">
19844 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19845 \begin_inset Text
19846
19847 \layout Standard
19848
19849 data pointers
19850 \end_inset
19851 </cell>
19852 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
19853 \begin_inset Text
19854
19855 \layout Standard
19856
19857 16-bits
19858 \end_inset
19859 </cell>
19860 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19861 \begin_inset Text
19862
19863 \layout Standard
19864
19865 16-bits
19866 \end_inset
19867 </cell>
19868 </row>
19869 </lyxtabular>
19870
19871 \end_inset
19872
19873
19874 \layout Standard
19875
19876 It is advisable that all sources within a project are compiled with the
19877  same memory model.
19878  If one wants to override the default memory model, this can be done by
19879  declaring a pointer as
19880 \series bold
19881 far
19882 \series default
19883  or
19884 \series bold
19885 near
19886 \series default
19887 .
19888  Far selects large memory model's pointers, while near selects small memory
19889  model's pointers.
19890 \layout Standard
19891
19892 The standard device libraries (see
19893 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
19894
19895 \end_inset
19896
19897 ) contain no reference to pointers, so they can be used with both memory
19898  models.
19899 \layout Subsection
19900
19901 Stack
19902 \layout Standard
19903
19904 The stack
19905 \begin_inset LatexCommand \index{PIC16!stack}
19906
19907 \end_inset
19908
19909  implementation for the PIC16 port uses two indirect registers, FSR1 and
19910  FSR2.
19911 \layout List
19912 \labelwidthstring 00.00.0000
19913
19914 FSR1 is assigned as stack pointer
19915 \layout List
19916 \labelwidthstring 00.00.0000
19917
19918 FSR2 is assigned as frame pointer
19919 \layout Standard
19920
19921 The following stack models are supported by the PIC16 port
19922 \layout Itemize
19923
19924
19925 \noun on
19926 small
19927 \noun default
19928  model
19929 \layout Itemize
19930
19931
19932 \noun on
19933 large
19934 \noun default
19935  model
19936 \layout Standard
19937
19938
19939 \noun on
19940 Small
19941 \noun default
19942  model means that only the FSRxL byte is used to access stack and frame,
19943  while
19944 \emph on
19945 \noun on
19946 large
19947 \emph default
19948 \noun default
19949  uses both FSRxL and FSRxH registers.
19950  The following table shows the stack/frame pointers sizes according to stack
19951  model and the maximum space they can address:
19952 \layout Standard
19953 \align center
19954
19955 \begin_inset  Tabular
19956 <lyxtabular version="3" rows="3" columns="3">
19957 <features>
19958 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19959 <column alignment="center" valignment="top" leftline="true" width="0">
19960 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19961 <row topline="true" bottomline="true">
19962 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19963 \begin_inset Text
19964
19965 \layout Standard
19966
19967 Stack & Frame pointer sizes according to stack model
19968 \end_inset
19969 </cell>
19970 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19971 \begin_inset Text
19972
19973 \layout Standard
19974
19975 small
19976 \end_inset
19977 </cell>
19978 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19979 \begin_inset Text
19980
19981 \layout Standard
19982
19983 large
19984 \end_inset
19985 </cell>
19986 </row>
19987 <row topline="true">
19988 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19989 \begin_inset Text
19990
19991 \layout Standard
19992
19993 Stack pointer FSR1
19994 \end_inset
19995 </cell>
19996 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19997 \begin_inset Text
19998
19999 \layout Standard
20000
20001 8-bits
20002 \end_inset
20003 </cell>
20004 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20005 \begin_inset Text
20006
20007 \layout Standard
20008
20009 16-bits
20010 \end_inset
20011 </cell>
20012 </row>
20013 <row topline="true" bottomline="true">
20014 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20015 \begin_inset Text
20016
20017 \layout Standard
20018
20019 Frame pointer FSR2
20020 \end_inset
20021 </cell>
20022 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20023 \begin_inset Text
20024
20025 \layout Standard
20026
20027 8-bits
20028 \end_inset
20029 </cell>
20030 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20031 \begin_inset Text
20032
20033 \layout Standard
20034
20035 16-bits
20036 \end_inset
20037 </cell>
20038 </row>
20039 </lyxtabular>
20040
20041 \end_inset
20042
20043
20044 \layout Standard
20045
20046
20047 \noun on
20048 Large
20049 \noun default
20050 stack model is currently not working properly throughout the code generator.
20051  So its use is not advised.
20052  Also there are some other points that need special care:
20053 \newline
20054
20055 \layout Enumerate
20056
20057 Do not create stack sections with size more than one physical bank (that
20058  is 256 bytes)
20059 \layout Enumerate
20060
20061 Stack sections should no cross physical bank limits (i.e.
20062  #pragma stack 0x50 0x100)
20063 \layout Standard
20064
20065 These limitations are caused by the fact that only FSRxL is modified when
20066  using SMALL stack model, so no more than 256 bytes of stack can be used.
20067  This problem will disappear after LARGE model is fully implemented.
20068 \layout Subsection
20069
20070 Functions
20071 \layout Standard
20072
20073 In addition to the standard SDCC function keywords, PIC16
20074 \begin_inset LatexCommand \index{PIC16}
20075
20076 \end_inset
20077
20078  port makes available two more:
20079 \layout List
20080 \labelwidthstring 00.00.0000
20081
20082 wparam
20083 \begin_inset LatexCommand \index{PIC16!wparam}
20084
20085 \end_inset
20086
20087  Use the WREG to pass one byte of the first function argument.
20088  This improves speed but you may not use this for functions with arguments
20089  that are called via function pointers, otherwise the first byte of the
20090  first parameter will get lost.
20091  Usage:
20092 \layout LyX-Code
20093
20094 void func_wparam(int a) wparam
20095 \layout LyX-Code
20096
20097 {
20098 \layout LyX-Code
20099
20100     /* WREG hold the lower part of a */
20101 \layout LyX-Code
20102
20103     /* the high part of a is stored in FSR2+2 (or +3 for large stack model)
20104  */
20105 \layout LyX-Code
20106
20107 ...
20108 \layout LyX-Code
20109
20110 }
20111 \layout List
20112 \labelwidthstring 00.00.0000
20113
20114 shadowregs
20115 \begin_inset LatexCommand \index{PIC16!shadowregs}
20116
20117 \end_inset
20118
20119  When entering/exiting an ISR, it is possible to take advantage of the PIC18F
20120  hardware shadow registers which hold the values of WREG, STATUS and BSR
20121  registers.
20122  This can be done by adding the keyword
20123 \emph on
20124 shadowregs
20125 \emph default
20126  before the
20127 \emph on
20128 interrupt
20129 \emph default
20130  keyword in the function's header.
20131 \layout LyX-Code
20132
20133 void isr_shadow(void) shadowregs interrupt 1
20134 \layout LyX-Code
20135
20136 {
20137 \layout LyX-Code
20138
20139 ...
20140 \layout LyX-Code
20141
20142 }
20143 \layout Standard
20144
20145
20146 \emph on
20147 shadowregs
20148 \emph default
20149  instructs the code generator not to store/restore WREG, STATUS, BSR when
20150  entering/exiting the ISR.
20151 \layout Subsection
20152
20153 Function return values
20154 \layout Standard
20155
20156 Return values from functions are placed to the appropriate registers following
20157  a modified Microchip policy optimized for SDCC.
20158  The following table shows these registers:
20159 \layout Standard
20160 \align center
20161
20162 \begin_inset  Tabular
20163 <lyxtabular version="3" rows="6" columns="2">
20164 <features>
20165 <column alignment="center" valignment="top" leftline="true" width="0">
20166 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20167 <row topline="true" bottomline="true">
20168 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20169 \begin_inset Text
20170
20171 \layout Standard
20172
20173 size
20174 \end_inset
20175 </cell>
20176 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20177 \begin_inset Text
20178
20179 \layout Standard
20180
20181 destination register
20182 \end_inset
20183 </cell>
20184 </row>
20185 <row topline="true">
20186 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20187 \begin_inset Text
20188
20189 \layout Standard
20190
20191 8 bits
20192 \end_inset
20193 </cell>
20194 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20195 \begin_inset Text
20196
20197 \layout Standard
20198
20199 WREG
20200 \end_inset
20201 </cell>
20202 </row>
20203 <row topline="true">
20204 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20205 \begin_inset Text
20206
20207 \layout Standard
20208
20209 16 bits
20210 \end_inset
20211 </cell>
20212 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20213 \begin_inset Text
20214
20215 \layout Standard
20216
20217 PRODL:WREG
20218 \end_inset
20219 </cell>
20220 </row>
20221 <row topline="true">
20222 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20223 \begin_inset Text
20224
20225 \layout Standard
20226
20227 24 bits
20228 \end_inset
20229 </cell>
20230 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20231 \begin_inset Text
20232
20233 \layout Standard
20234
20235 PRODH:PRODL:WREG
20236 \end_inset
20237 </cell>
20238 </row>
20239 <row topline="true">
20240 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20241 \begin_inset Text
20242
20243 \layout Standard
20244
20245 32 bits
20246 \end_inset
20247 </cell>
20248 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20249 \begin_inset Text
20250
20251 \layout Standard
20252
20253 FSR0L:PRODH:PRODL:WREG
20254 \end_inset
20255 </cell>
20256 </row>
20257 <row topline="true" bottomline="true">
20258 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20259 \begin_inset Text
20260
20261 \layout Standard
20262
20263 >32 bits
20264 \end_inset
20265 </cell>
20266 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20267 \begin_inset Text
20268
20269 \layout Standard
20270
20271 on stack, FSR0 points to the beginning
20272 \end_inset
20273 </cell>
20274 </row>
20275 </lyxtabular>
20276
20277 \end_inset
20278
20279
20280 \layout Subsection
20281
20282 Interrupts
20283 \layout Standard
20284
20285 An interrupt
20286 \begin_inset LatexCommand \index{PIC16!interrupt}
20287
20288 \end_inset
20289
20290  service routine (ISR) is declared using the
20291 \emph on
20292 interrupt
20293 \emph default
20294  keyword.
20295 \layout LyX-Code
20296
20297 void isr(void) interrupt
20298 \emph on
20299 n
20300 \layout LyX-Code
20301
20302 {
20303 \layout LyX-Code
20304
20305 ...
20306 \layout LyX-Code
20307
20308 }
20309 \layout Standard
20310
20311
20312 \emph on
20313 n
20314 \emph default
20315  is the interrupt number, which for PIC18F devices can be:
20316 \layout Standard
20317 \align center
20318
20319 \begin_inset  Tabular
20320 <lyxtabular version="3" rows="4" columns="3">
20321 <features>
20322 <column alignment="center" valignment="top" leftline="true" width="0">
20323 <column alignment="center" valignment="top" leftline="true" width="0">
20324 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20325 <row topline="true" bottomline="true">
20326 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20327 \begin_inset Text
20328
20329 \layout Standard
20330
20331
20332 \emph on
20333 n
20334 \end_inset
20335 </cell>
20336 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20337 \begin_inset Text
20338
20339 \layout Standard
20340
20341 Interrupt Vector
20342 \end_inset
20343 </cell>
20344 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20345 \begin_inset Text
20346
20347 \layout Standard
20348
20349 Interrupt Vector Address
20350 \end_inset
20351 </cell>
20352 </row>
20353 <row topline="true">
20354 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20355 \begin_inset Text
20356
20357 \layout Standard
20358
20359 0
20360 \end_inset
20361 </cell>
20362 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20363 \begin_inset Text
20364
20365 \layout Standard
20366
20367 RESET vector
20368 \end_inset
20369 </cell>
20370 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20371 \begin_inset Text
20372
20373 \layout Standard
20374
20375 0x000000
20376 \end_inset
20377 </cell>
20378 </row>
20379 <row topline="true">
20380 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20381 \begin_inset Text
20382
20383 \layout Standard
20384
20385
20386 \family roman
20387 \series medium
20388 \shape up
20389 \size normal
20390 \emph off
20391 \bar no
20392 \noun off
20393 \color none
20394 1
20395 \end_inset
20396 </cell>
20397 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20398 \begin_inset Text
20399
20400 \layout Standard
20401
20402
20403 \family roman
20404 \series medium
20405 \shape up
20406 \size normal
20407 \emph off
20408 \bar no
20409 \noun off
20410 \color none
20411 HIGH priority interrupts
20412 \end_inset
20413 </cell>
20414 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20415 \begin_inset Text
20416
20417 \layout Standard
20418
20419 0x000008
20420 \end_inset
20421 </cell>
20422 </row>
20423 <row topline="true" bottomline="true">
20424 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20425 \begin_inset Text
20426
20427 \layout Standard
20428
20429 2
20430 \end_inset
20431 </cell>
20432 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20433 \begin_inset Text
20434
20435 \layout Standard
20436
20437 LOW priority interrupts
20438 \end_inset
20439 </cell>
20440 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20441 \begin_inset Text
20442
20443 \layout Standard
20444
20445 0x000018
20446 \end_inset
20447 </cell>
20448 </row>
20449 </lyxtabular>
20450
20451 \end_inset
20452
20453
20454 \layout Standard
20455
20456 When generating assembly code for ISR the code generator places a
20457 \noun on
20458 goto
20459 \noun default
20460 instruction at the
20461 \emph on
20462 Interrupt Vector Address
20463 \emph default
20464  which points at the genetated ISR.
20465  This single GOTO instruction is part of an automatically generated
20466 \emph on
20467 interrupt entry point
20468 \emph default
20469  function.
20470  The actuall ISR code is placed as normally would in the code space.
20471  Upon interrupt request, the GOTO instruction is executed which jumps to
20472  the ISR code.
20473  When declaring interrupt functions as _naked this GOTO instruction is
20474 \series bold
20475 not
20476 \series default
20477  generated.
20478  The whole interrupt functions is therefore placed at the Interrupt Vector
20479  Address of the specific interrupt.
20480  This is not a problem for the LOW priority interrupts, but it is a problem
20481  for the RESET and the HIGH priority interrupts because code may be written
20482  at the next interrupt´s vector address and cause undeterminate program
20483  behaviour if that interrupt is raised.
20484 \begin_inset Foot
20485 collapsed false
20486
20487 \layout Standard
20488
20489 This is not a problem when
20490 \layout Enumerate
20491
20492 this is a HIGH interrupt ISR and LOW interrupts are
20493 \emph on
20494 disabled
20495 \emph default
20496  or not used.
20497 \layout Enumerate
20498
20499 when the ISR is small enough not to reach the next interrupt´s vector address.
20500 \end_inset
20501
20502
20503 \layout Standard
20504
20505
20506 \emph on
20507 n
20508 \emph default
20509  is possible to be omitted.
20510  This way a function is generated similar to an ISR, but it is not assigned
20511  to any interrupt.
20512 \layout Standard
20513
20514 When entering an interrupt, currently the PIC16
20515 \begin_inset LatexCommand \index{PIC16}
20516
20517 \end_inset
20518
20519  port automatically saves the following registers:
20520 \layout Itemize
20521
20522 WREG
20523 \layout Itemize
20524
20525 STATUS
20526 \layout Itemize
20527
20528 BSR
20529 \layout Itemize
20530
20531 PROD (PRODL and PRODH)
20532 \layout Itemize
20533
20534 FSR0 (FSR0L and FSR0H)
20535 \layout Standard
20536
20537 These registers are restored upon return from the interrupt routine.
20538 \begin_inset Foot
20539 collapsed false
20540
20541 \layout Standard
20542
20543 NOTE that when the _naked attribute is specified for an interrupt routine,
20544  then NO registers are stored or restored.
20545 \end_inset
20546
20547
20548 \layout Subsection
20549
20550 Generic Pointers
20551 \layout Standard
20552
20553 Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types.
20554  There are 3 types of generic pointers currently implemented data, code
20555  and eeprom pointers.
20556  They are differentiated by the value of the 7th and 6th bits of the upper
20557  byte:
20558 \layout Standard
20559 \align center
20560
20561 \begin_inset  Tabular
20562 <lyxtabular version="3" rows="5" columns="5">
20563 <features>
20564 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20565 <column alignment="center" valignment="top" width="0">
20566 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20567 <column alignment="center" valignment="top" width="0">
20568 <column alignment="left" valignment="top" rightline="true" width="0">
20569 <row topline="true" bottomline="true">
20570 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20571 \begin_inset Text
20572
20573 \layout Standard
20574
20575 pointer type
20576 \end_inset
20577 </cell>
20578 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20579 \begin_inset Text
20580
20581 \layout Standard
20582
20583 7th bit
20584 \end_inset
20585 </cell>
20586 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20587 \begin_inset Text
20588
20589 \layout Standard
20590
20591 6th bit
20592 \end_inset
20593 </cell>
20594 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20595 \begin_inset Text
20596
20597 \layout Standard
20598
20599 rest of the pointer
20600 \end_inset
20601 </cell>
20602 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20603 \begin_inset Text
20604
20605 \layout Standard
20606
20607 description
20608 \end_inset
20609 </cell>
20610 </row>
20611 <row topline="true" bottomline="true">
20612 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20613 \begin_inset Text
20614
20615 \layout Standard
20616
20617 data
20618 \end_inset
20619 </cell>
20620 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20621 \begin_inset Text
20622
20623 \layout Standard
20624
20625 1
20626 \end_inset
20627 </cell>
20628 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20629 \begin_inset Text
20630
20631 \layout Standard
20632
20633 0
20634 \end_inset
20635 </cell>
20636 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20637 \begin_inset Text
20638
20639 \layout Standard
20640
20641
20642 \family typewriter
20643 \shape slanted
20644 \emph on
20645 uuuuuu uuuuxxxx xxxxxxxx
20646 \end_inset
20647 </cell>
20648 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20649 \begin_inset Text
20650
20651 \layout Standard
20652
20653 a 12-bit data pointer in data RAM memory
20654 \end_inset
20655 </cell>
20656 </row>
20657 <row bottomline="true">
20658 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20659 \begin_inset Text
20660
20661 \layout Standard
20662
20663 code
20664 \end_inset
20665 </cell>
20666 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20667 \begin_inset Text
20668
20669 \layout Standard
20670
20671 0
20672 \end_inset
20673 </cell>
20674 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20675 \begin_inset Text
20676
20677 \layout Standard
20678
20679 0
20680 \end_inset
20681 </cell>
20682 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20683 \begin_inset Text
20684
20685 \layout Standard
20686
20687
20688 \family typewriter
20689 \shape slanted
20690 \emph on
20691 uxxxxx xxxxxxxx xxxxxxxx
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 a 21-bit code pointer in FLASH memory
20700 \end_inset
20701 </cell>
20702 </row>
20703 <row bottomline="true">
20704 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20705 \begin_inset Text
20706
20707 \layout Standard
20708
20709 eeprom
20710 \end_inset
20711 </cell>
20712 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20713 \begin_inset Text
20714
20715 \layout Standard
20716
20717 0
20718 \end_inset
20719 </cell>
20720 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20721 \begin_inset Text
20722
20723 \layout Standard
20724
20725 1
20726 \end_inset
20727 </cell>
20728 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20729 \begin_inset Text
20730
20731 \layout Standard
20732
20733
20734 \family typewriter
20735 \shape slanted
20736 \emph on
20737 uuuuuu uuuuuuxx xxxxxxxx
20738 \end_inset
20739 </cell>
20740 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20741 \begin_inset Text
20742
20743 \layout Standard
20744
20745 a 10-bit eeprom pointer in EEPROM memory
20746 \end_inset
20747 </cell>
20748 </row>
20749 <row bottomline="true">
20750 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20751 \begin_inset Text
20752
20753 \layout Standard
20754
20755 (unimplemented)
20756 \end_inset
20757 </cell>
20758 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20759 \begin_inset Text
20760
20761 \layout Standard
20762
20763 1
20764 \end_inset
20765 </cell>
20766 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20767 \begin_inset Text
20768
20769 \layout Standard
20770
20771 1
20772 \end_inset
20773 </cell>
20774 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20775 \begin_inset Text
20776
20777 \layout Standard
20778
20779
20780 \family typewriter
20781 \shape slanted
20782 \emph on
20783 xxxxxx xxxxxxxx xxxxxxxx
20784 \end_inset
20785 </cell>
20786 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20787 \begin_inset Text
20788
20789 \layout Standard
20790
20791 unimplemented pointer type
20792 \end_inset
20793 </cell>
20794 </row>
20795 </lyxtabular>
20796
20797 \end_inset
20798
20799
20800 \layout Standard
20801
20802 Generic pointer are read and written with a set of library functions which
20803  read/write 1, 2, 3, 4 bytes.
20804 \layout Subsection
20805
20806 PIC16 C Libraries
20807 \layout Subsubsection
20808
20809 Standard I/O Streams
20810 \layout Standard
20811
20812 In the
20813 \emph on
20814 stdio.h
20815 \emph default
20816  the type FILE is defined as:
20817 \layout LyX-Code
20818
20819 typedef char * FILE;
20820 \layout Standard
20821
20822 This type is the stream type implemented I/O in the PIC18F devices.
20823  Also the standard input and output streams are declared in stdio.h:
20824 \layout LyX-Code
20825
20826 extern FILE * stdin;
20827 \layout LyX-Code
20828
20829 extern FILE * stdout;
20830 \layout Standard
20831
20832 The FILE type is actually a generic pointer which defines one more type
20833  of generic pointers, the
20834 \emph on
20835 stream
20836 \emph default
20837 pointer.
20838  This new type has the format:
20839 \layout Standard
20840 \align center
20841
20842 \begin_inset  Tabular
20843 <lyxtabular version="3" rows="2" columns="7">
20844 <features>
20845 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20846 <column alignment="center" valignment="top" width="0">
20847 <column alignment="center" valignment="top" leftline="true" width="0">
20848 <column alignment="center" valignment="top" leftline="true" width="0">
20849 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20850 <column alignment="center" valignment="top" width="0">
20851 <column alignment="left" valignment="top" rightline="true" width="0">
20852 <row topline="true" bottomline="true">
20853 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20854 \begin_inset Text
20855
20856 \layout Standard
20857
20858 pointer type
20859 \end_inset
20860 </cell>
20861 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20862 \begin_inset Text
20863
20864 \layout Standard
20865
20866 <7:6>
20867 \end_inset
20868 </cell>
20869 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20870 \begin_inset Text
20871
20872 \layout Standard
20873
20874 <5>
20875 \end_inset
20876 </cell>
20877 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20878 \begin_inset Text
20879
20880 \layout Standard
20881
20882 <4>
20883 \end_inset
20884 </cell>
20885 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20886 \begin_inset Text
20887
20888 \layout Standard
20889
20890 <3:0>
20891 \end_inset
20892 </cell>
20893 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20894 \begin_inset Text
20895
20896 \layout Standard
20897
20898 rest of the pointer
20899 \end_inset
20900 </cell>
20901 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20902 \begin_inset Text
20903
20904 \layout Standard
20905
20906 descrption
20907 \end_inset
20908 </cell>
20909 </row>
20910 <row topline="true" bottomline="true">
20911 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20912 \begin_inset Text
20913
20914 \layout Standard
20915
20916 stream
20917 \end_inset
20918 </cell>
20919 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20920 \begin_inset Text
20921
20922 \layout Standard
20923
20924 00
20925 \end_inset
20926 </cell>
20927 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20928 \begin_inset Text
20929
20930 \layout Standard
20931
20932 1
20933 \end_inset
20934 </cell>
20935 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20936 \begin_inset Text
20937
20938 \layout Standard
20939
20940 0
20941 \end_inset
20942 </cell>
20943 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20944 \begin_inset Text
20945
20946 \layout Standard
20947
20948 nnnn
20949 \end_inset
20950 </cell>
20951 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20952 \begin_inset Text
20953
20954 \layout Standard
20955
20956
20957 \family typewriter
20958 \shape slanted
20959 \emph on
20960 uuuuuuuu uuuuuuuu
20961 \end_inset
20962 </cell>
20963 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20964 \begin_inset Text
20965
20966 \layout Standard
20967
20968 upper byte high nubble is 0x2n, the rest are zeroes
20969 \end_inset
20970 </cell>
20971 </row>
20972 </lyxtabular>
20973
20974 \end_inset
20975
20976
20977 \layout Standard
20978
20979 Currently implemented there are 3 types of streams defined:
20980 \layout Standard
20981 \align center
20982
20983 \begin_inset  Tabular
20984 <lyxtabular version="3" rows="4" columns="4">
20985 <features>
20986 <column alignment="center" valignment="top" leftline="true" width="0">
20987 <column alignment="center" valignment="top" leftline="true" width="0">
20988 <column alignment="center" valignment="top" leftline="true" width="0">
20989 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20990 <row topline="true" bottomline="true">
20991 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20992 \begin_inset Text
20993
20994 \layout Standard
20995
20996 stream type
20997 \end_inset
20998 </cell>
20999 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21000 \begin_inset Text
21001
21002 \layout Standard
21003
21004 value
21005 \end_inset
21006 </cell>
21007 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21008 \begin_inset Text
21009
21010 \layout Standard
21011
21012 module
21013 \end_inset
21014 </cell>
21015 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21016 \begin_inset Text
21017
21018 \layout Standard
21019
21020 description
21021 \end_inset
21022 </cell>
21023 </row>
21024 <row topline="true">
21025 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21026 \begin_inset Text
21027
21028 \layout Standard
21029
21030 STREAM_USART
21031 \end_inset
21032 </cell>
21033 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21034 \begin_inset Text
21035
21036 \layout Standard
21037
21038
21039 \family typewriter
21040 0x200000UL
21041 \end_inset
21042 </cell>
21043 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21044 \begin_inset Text
21045
21046 \layout Standard
21047
21048 USART
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 Writes/Reads characters via the USART peripheral
21057 \end_inset
21058 </cell>
21059 </row>
21060 <row topline="true">
21061 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21062 \begin_inset Text
21063
21064 \layout Standard
21065
21066 STREAM_MSSP
21067 \end_inset
21068 </cell>
21069 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21070 \begin_inset Text
21071
21072 \layout Standard
21073
21074
21075 \family typewriter
21076 0x210000UL
21077 \end_inset
21078 </cell>
21079 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21080 \begin_inset Text
21081
21082 \layout Standard
21083
21084 MSSP
21085 \end_inset
21086 </cell>
21087 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21088 \begin_inset Text
21089
21090 \layout Standard
21091
21092 Writes/Reads characters via the MSSP peripheral
21093 \end_inset
21094 </cell>
21095 </row>
21096 <row topline="true" bottomline="true">
21097 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21098 \begin_inset Text
21099
21100 \layout Standard
21101
21102 STREAM_USER
21103 \end_inset
21104 </cell>
21105 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21106 \begin_inset Text
21107
21108 \layout Standard
21109
21110
21111 \family typewriter
21112 0x2f0000UL
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 (none)
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 Writes/Reads characters via used defined functions
21129 \end_inset
21130 </cell>
21131 </row>
21132 </lyxtabular>
21133
21134 \end_inset
21135
21136
21137 \layout Standard
21138
21139 The stream identifiers are declared as macros in the stdio.h header.
21140 \layout Standard
21141
21142 In the libc library there exist the functions that are used to write to
21143  each of the above streams.
21144  These are
21145 \layout List
21146 \labelwidthstring 00.00.0000
21147
21148 _
21149 \begin_inset ERT
21150 status Collapsed
21151
21152 \layout Standard
21153
21154 \backslash
21155 /
21156 \end_inset
21157
21158 _stream_usart_putchar writes a character at the USART stream
21159 \layout List
21160 \labelwidthstring 00.00.0000
21161
21162 _
21163 \begin_inset ERT
21164 status Collapsed
21165
21166 \layout Standard
21167
21168 \backslash
21169 /
21170 \end_inset
21171
21172 _stream_mssp_putchar writes a character at the MSSP stream
21173 \layout List
21174 \labelwidthstring 00.00.0000
21175
21176 putchar dummy function.
21177  This writes a character to a user specified manner.
21178 \layout Standard
21179
21180 In order to increase performance
21181 \emph on
21182 putchar
21183 \emph default
21184 is declared in stdio.h as having its parameter in WREG (it has the wparam
21185  keyword).
21186  In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function
21187  in a user-friendly way.
21188
21189 \emph on
21190 arg
21191 \emph default
21192  is the name of the variable that holds the character to print.
21193  An example follows:
21194 \layout LyX-Code
21195
21196 #include <pic18fregs.h>
21197 \newline
21198 #include <stdio.h>
21199 \newline
21200
21201 \newline
21202 PUTCHAR( c )
21203 \layout LyX-Code
21204
21205 {
21206 \layout LyX-Code
21207
21208     PORTA = c;    /* dump character c to PORTA */
21209 \layout LyX-Code
21210
21211 }
21212 \newline
21213
21214 \newline
21215 void main(void)
21216 \layout LyX-Code
21217
21218 {
21219 \layout LyX-Code
21220
21221     stdout = STREAM_USER;    /* this is not necessary, since stdout points
21222 \layout LyX-Code
21223
21224                               * by default to STREAM_USER */
21225 \layout LyX-Code
21226
21227     printf (¨This is a printf test
21228 \backslash
21229 n¨);
21230 \layout LyX-Code
21231
21232 }
21233 \layout LyX-Code
21234
21235 \layout Subsubsection
21236
21237 Printing functions
21238 \layout Standard
21239
21240 PIC16 contains an implementation of the printf-family of functions.
21241  There exist the following functions:
21242 \layout LyX-Code
21243
21244 extern unsigned int sprintf(char *buf, char *fmt, ...);
21245 \layout LyX-Code
21246
21247 extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
21248 \layout LyX-Code
21249
21250 \layout LyX-Code
21251
21252 extern unsigned int printf(char *fmt, ...);
21253 \layout LyX-Code
21254
21255 extern unsigned int vprintf(char *fmt, va_lista ap);
21256 \layout LyX-Code
21257
21258 \layout LyX-Code
21259
21260 extern unsigned int fprintf(FILE *fp, char *fmt, ...);
21261 \layout LyX-Code
21262
21263 extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
21264 \layout Standard
21265
21266 For sprintf and vsprintf
21267 \emph on
21268 buf
21269 \emph default
21270 should normally be a data pointer where the resulting string will be placed.
21271  No range checking is done so the user should allocate the necessery buffer.
21272  For fprintf and vfprintf
21273 \emph on
21274 fp
21275 \emph default
21276  should be a stream pointer (i.e.
21277  stdout, STREAM_MSSP, etc...).
21278 \layout Subsubsection
21279
21280 Signals
21281 \layout Standard
21282
21283 The PIC18F family of microcontrollers supports a number of interrupt sources.
21284  A list of these interrupts is shown in the following table:
21285 \layout Standard
21286 \align center
21287
21288 \begin_inset  Tabular
21289 <lyxtabular version="3" rows="11" columns="4">
21290 <features>
21291 <column alignment="left" valignment="top" leftline="true" width="0">
21292 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
21293 <column alignment="left" valignment="top" leftline="true" width="0">
21294 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
21295 <row topline="true" bottomline="true">
21296 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21297 \begin_inset Text
21298
21299 \layout Standard
21300
21301 signal name
21302 \end_inset
21303 </cell>
21304 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21305 \begin_inset Text
21306
21307 \layout Standard
21308
21309 description
21310 \end_inset
21311 </cell>
21312 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21313 \begin_inset Text
21314
21315 \layout Standard
21316
21317 signal name
21318 \end_inset
21319 </cell>
21320 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21321 \begin_inset Text
21322
21323 \layout Standard
21324
21325 descritpion
21326 \end_inset
21327 </cell>
21328 </row>
21329 <row topline="true">
21330 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21331 \begin_inset Text
21332
21333 \layout Standard
21334
21335 SIG_RB
21336 \end_inset
21337 </cell>
21338 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21339 \begin_inset Text
21340
21341 \layout Standard
21342
21343 PORTB change interrupt
21344 \end_inset
21345 </cell>
21346 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21347 \begin_inset Text
21348
21349 \layout Standard
21350
21351 SIG_EE
21352 \end_inset
21353 </cell>
21354 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21355 \begin_inset Text
21356
21357 \layout Standard
21358
21359 EEPROM/FLASH write complete interrupt
21360 \end_inset
21361 </cell>
21362 </row>
21363 <row topline="true">
21364 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21365 \begin_inset Text
21366
21367 \layout Standard
21368
21369 SIG_INT0
21370 \end_inset
21371 </cell>
21372 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21373 \begin_inset Text
21374
21375 \layout Standard
21376
21377 INT0 external interrupt
21378 \end_inset
21379 </cell>
21380 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21381 \begin_inset Text
21382
21383 \layout Standard
21384
21385 SIG_BCOL
21386 \end_inset
21387 </cell>
21388 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21389 \begin_inset Text
21390
21391 \layout Standard
21392
21393 Bus collision interrupt
21394 \end_inset
21395 </cell>
21396 </row>
21397 <row topline="true">
21398 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21399 \begin_inset Text
21400
21401 \layout Standard
21402
21403 SIG_INT1
21404 \end_inset
21405 </cell>
21406 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21407 \begin_inset Text
21408
21409 \layout Standard
21410
21411 INT1 external interrupt
21412 \end_inset
21413 </cell>
21414 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21415 \begin_inset Text
21416
21417 \layout Standard
21418
21419 SIG_LVD
21420 \end_inset
21421 </cell>
21422 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21423 \begin_inset Text
21424
21425 \layout Standard
21426
21427 Low voltage detect interrupt
21428 \end_inset
21429 </cell>
21430 </row>
21431 <row topline="true">
21432 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21433 \begin_inset Text
21434
21435 \layout Standard
21436
21437 SIG_INT2
21438 \end_inset
21439 </cell>
21440 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21441 \begin_inset Text
21442
21443 \layout Standard
21444
21445 INT2 external interrupt
21446 \end_inset
21447 </cell>
21448 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21449 \begin_inset Text
21450
21451 \layout Standard
21452
21453 SIG_PSP
21454 \end_inset
21455 </cell>
21456 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21457 \begin_inset Text
21458
21459 \layout Standard
21460
21461 Parallel slave port interrupt
21462 \end_inset
21463 </cell>
21464 </row>
21465 <row topline="true">
21466 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21467 \begin_inset Text
21468
21469 \layout Standard
21470
21471 SIG_CCP1
21472 \end_inset
21473 </cell>
21474 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21475 \begin_inset Text
21476
21477 \layout Standard
21478
21479 CCP1 module interrupt
21480 \end_inset
21481 </cell>
21482 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21483 \begin_inset Text
21484
21485 \layout Standard
21486
21487 SIG_AD
21488 \end_inset
21489 </cell>
21490 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21491 \begin_inset Text
21492
21493 \layout Standard
21494
21495 AD convertion complete interrupt
21496 \end_inset
21497 </cell>
21498 </row>
21499 <row topline="true">
21500 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21501 \begin_inset Text
21502
21503 \layout Standard
21504
21505 SIG_CCP2
21506 \end_inset
21507 </cell>
21508 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21509 \begin_inset Text
21510
21511 \layout Standard
21512
21513 CCP2 module interrupt
21514 \end_inset
21515 </cell>
21516 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21517 \begin_inset Text
21518
21519 \layout Standard
21520
21521 SIG_RC
21522 \end_inset
21523 </cell>
21524 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21525 \begin_inset Text
21526
21527 \layout Standard
21528
21529 USART receive interrupt
21530 \end_inset
21531 </cell>
21532 </row>
21533 <row topline="true">
21534 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21535 \begin_inset Text
21536
21537 \layout Standard
21538
21539 SIG_TMR0
21540 \end_inset
21541 </cell>
21542 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21543 \begin_inset Text
21544
21545 \layout Standard
21546
21547 TMR0 overflow interrupt
21548 \end_inset
21549 </cell>
21550 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21551 \begin_inset Text
21552
21553 \layout Standard
21554
21555 SIG_TX
21556 \end_inset
21557 </cell>
21558 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21559 \begin_inset Text
21560
21561 \layout Standard
21562
21563 USART transmit interrupt
21564 \end_inset
21565 </cell>
21566 </row>
21567 <row topline="true">
21568 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21569 \begin_inset Text
21570
21571 \layout Standard
21572
21573 SIG_TMR1
21574 \end_inset
21575 </cell>
21576 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21577 \begin_inset Text
21578
21579 \layout Standard
21580
21581 TMR1 overflow interrupt
21582 \end_inset
21583 </cell>
21584 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21585 \begin_inset Text
21586
21587 \layout Standard
21588
21589 SIG_MSSP
21590 \end_inset
21591 </cell>
21592 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21593 \begin_inset Text
21594
21595 \layout Standard
21596
21597 SSP receive/transmit interrupt
21598 \end_inset
21599 </cell>
21600 </row>
21601 <row topline="true">
21602 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21603 \begin_inset Text
21604
21605 \layout Standard
21606
21607 SIG_TMR2
21608 \end_inset
21609 </cell>
21610 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21611 \begin_inset Text
21612
21613 \layout Standard
21614
21615 TMR2 matches PR2 interrupt
21616 \end_inset
21617 </cell>
21618 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21619 \begin_inset Text
21620
21621 \layout Standard
21622
21623 \end_inset
21624 </cell>
21625 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21626 \begin_inset Text
21627
21628 \layout Standard
21629
21630 \end_inset
21631 </cell>
21632 </row>
21633 <row topline="true" bottomline="true">
21634 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21635 \begin_inset Text
21636
21637 \layout Standard
21638
21639 SIG_TMR3
21640 \end_inset
21641 </cell>
21642 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21643 \begin_inset Text
21644
21645 \layout Standard
21646
21647 TMR3 overflow interrupt
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 \end_inset
21656 </cell>
21657 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21658 \begin_inset Text
21659
21660 \layout Standard
21661
21662 \end_inset
21663 </cell>
21664 </row>
21665 </lyxtabular>
21666
21667 \end_inset
21668
21669
21670 \layout Standard
21671
21672 The prototypes for these names are defined in the header file
21673 \emph on
21674 signal.h
21675 \emph default
21676  .
21677 \layout Standard
21678
21679 In order to simplify signal handling, a number of macros is provided:
21680 \layout List
21681 \labelwidthstring 00.00.0000
21682
21683 DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for
21684  high priority interrupts.
21685
21686 \emph on
21687 name
21688 \emph default
21689  is the function name to use.
21690 \layout List
21691 \labelwidthstring 00.00.0000
21692
21693 DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo
21694  low priority interrupt.
21695
21696 \emph on
21697 name
21698 \emph default
21699  is the function name to use.
21700 \layout List
21701 \labelwidthstring 00.00.0000
21702
21703 DEF_HANDLER(sig,handler) define a handler for signal
21704 \emph on
21705 sig.
21706 \layout List
21707 \labelwidthstring 00.00.0000
21708
21709 END_DEF end the declaration of the dispatch table.
21710 \layout Standard
21711
21712 Additionally there are two more macros to simplify the declaration of the
21713  signal handler:
21714 \layout List
21715 \labelwidthstring 00.00.0000
21716
21717
21718 \series medium
21719 SIGHANDLER(handler)
21720 \series default
21721 this declares the function prototype for the
21722 \emph on
21723 handler
21724 \emph default
21725  function.
21726 \layout List
21727 \labelwidthstring 00.00.0000
21728
21729 SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function.
21730 \layout Standard
21731
21732 An example of using the macros above is shown below:
21733 \layout LyX-Code
21734
21735 #include <pic18fregs.h>
21736 \layout LyX-Code
21737
21738 #include <signal.h>
21739 \newline
21740
21741 \newline
21742 DEF_INTHIGH(high_int)
21743 \layout LyX-Code
21744
21745 DEF_HANDLER(SIG_TMR0, _tmr0_handler)
21746 \layout LyX-Code
21747
21748 DEF_HANDLER(SIG_BCOL, _bcol_handler)
21749 \layout LyX-Code
21750
21751 END_DEF
21752 \newline
21753
21754 \newline
21755 SIGHANDLER(_tmr0_handler)
21756 \layout LyX-Code
21757
21758 {
21759 \layout LyX-Code
21760
21761   /* action to be taken when timer 0 overflows */
21762 \layout LyX-Code
21763
21764 }
21765 \newline
21766
21767 \newline
21768 SIGHANDLERNAKED(_bcol_handler)
21769 \layout LyX-Code
21770
21771 {
21772 \layout LyX-Code
21773
21774   _asm
21775 \layout LyX-Code
21776
21777     /* action to be taken when bus collision occurs */
21778 \layout LyX-Code
21779
21780     retfie
21781 \layout LyX-Code
21782
21783  _endasm;
21784 \layout LyX-Code
21785
21786 }
21787 \layout Standard
21788
21789
21790 \series bold
21791 NOTES:
21792 \series default
21793  Special care should be taken when using the above scheme:
21794 \layout Itemize
21795
21796 do not place a colon (;) at the end of the DEF_* and END_DEF macros.
21797 \layout Itemize
21798
21799 when declaring SIGHANDLERNAKED handler never forget to use
21800 \emph on
21801 retfie
21802 \emph default
21803  for proper returning.
21804 \layout Subsection
21805
21806 PIC16 Port -- Tips
21807 \layout Standard
21808
21809 Here you can find some general tips for compiling programs with SDCC/pic16.
21810 \layout Subsubsection
21811
21812 Stack size
21813 \layout Standard
21814
21815 The default stack
21816 \begin_inset LatexCommand \index{PIC16!stack}
21817
21818 \end_inset
21819
21820  size (that is 64 bytes) probably is enough for many programs.
21821  One must take care that when there are many levels of function nesting,
21822  or there is excessive usage of stack, its size should be extended.
21823  An example of such a case is the printf/sprintf family of functions.
21824  If you encounter problems like not being able to print integers, then you
21825  need to set the stack size around the maximum (256 for small stack model).
21826  The following diagram shows what happens when calling printf to print an
21827  integer:
21828 \layout LyX-Code
21829
21830 printf () --> ltoa () --> ultoa () --> divschar ()
21831 \layout Standard
21832
21833 It is should be understood that stack is easily consumed when calling complicate
21834 d functions.
21835  Using command line arguments like -
21836 \begin_inset ERT
21837 status Collapsed
21838
21839 \layout Standard
21840
21841 \backslash
21842 /
21843 \end_inset
21844
21845 -fommit-frame-pointer might reduce stack usage by not creating unnecessery
21846  stack frames.
21847  Other ways to reduce stack usage may exist.
21848 \layout Subsection
21849
21850 Known bugs
21851 \layout Standard
21852
21853 The PIC16 Port currently does not pass SDCC's regression test
21854 \begin_inset LatexCommand \index{Regression test (PIC16)}
21855
21856 \end_inset
21857
21858  suite (see section
21859 \begin_inset LatexCommand \ref{sec:Quality-control}
21860
21861 \end_inset
21862
21863 ) and thus the nightly regression tests for the PIC16 target are currently
21864  disabled for all hosts except for
21865 \emph on
21866 Linux on Opteron.
21867
21868 \emph default
21869  This means you can see the result of the PIC16 regression tests f.e.
21870  by checking the log files in
21871 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/regression_test_results/amd64-unknown-linux2.3/}
21872
21873 \end_inset
21874
21875  (pick the most up to date file there, scroll down, lend a hand).
21876 \layout Chapter
21877
21878 Debugging
21879 \layout Standard
21880
21881 There are several approaches to debugging your code.
21882  This chapter is meant to show your options and to give detail on some of
21883  them:
21884 \newline
21885
21886 \newline
21887 When writing your code:
21888 \layout Itemize
21889
21890 write your code with debugging in mind (avoid duplicating code, put conceptually
21891  similar variables into structs, use structured code, have strategic points
21892  within your code where all variables are consistent, ...)
21893 \layout Itemize
21894
21895 run a syntax-checking tool like splint
21896 \begin_inset LatexCommand \index{splint (syntax checking tool)}
21897
21898 \end_inset
21899
21900
21901 \begin_inset LatexCommand \index{lint (syntax checking tool)}
21902
21903 \end_inset
21904
21905  (see -
21906 \begin_inset ERT
21907 status Collapsed
21908
21909 \layout Standard
21910
21911 \backslash
21912 /
21913 \end_inset
21914
21915 -more-pedantic
21916 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
21917
21918 \end_inset
21919
21920 ) over the code.
21921 \layout Itemize
21922
21923 for the high level code use a C-compiler (like f.e.
21924  GCC) to compile run and debug the code on your host.
21925  See (see -
21926 \begin_inset ERT
21927 status Collapsed
21928
21929 \layout Standard
21930
21931 \backslash
21932 /
21933 \end_inset
21934
21935 -more-pedantic
21936 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
21937
21938 \end_inset
21939
21940  ) on howto handle syntax extensions like __xdata, __at(), ...
21941
21942 \layout Itemize
21943
21944 use another C-compiler to compile code for your target.
21945  Always an option but not recommended:) And not very likely to help you.
21946  If you seriously consider walking this path you should at least occasionally
21947  check portability of your code.
21948  Most commercial compiler vendors will offer an evaluation version so you
21949  can test compile your code or snippets of your code.
21950 \layout Standard
21951
21952 Debugging on a simulator:
21953 \layout Itemize
21954
21955 there is a separate section about SDCDB (section
21956 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
21957
21958 \end_inset
21959
21960 ) below.
21961 \layout Itemize
21962
21963 or (8051 specific) use a freeware/commercial simulator which interfaces
21964  to the AOMF
21965 \begin_inset LatexCommand \index{AOMF, AOMF51}
21966
21967 \end_inset
21968
21969  file (see
21970 \begin_inset LatexCommand \ref{OMF file}
21971
21972 \end_inset
21973
21974 ) optionally generated by SDCC.
21975 \layout Standard
21976
21977 Debugging On-target:
21978 \layout Itemize
21979
21980 use a MCU port pin to serially output debug data to the RS232 port of your
21981  host.
21982  You'll probably want some level shifting device typically involving a MAX232
21983  or similar IC.
21984  If the hardware serial port of the MCU is not available search for 'Software
21985  UART' in your favourite search machine.
21986 \layout Itemize
21987
21988 use an on-target monitor.
21989  In this context a monitor is a small program which usually accepts commands
21990  via a serial line and allows to set program counter, to single step through
21991  a program and read/write memory locations.
21992  For the 8051 good examples of monitors are paulmon and cmon51 (see section
21993
21994 \begin_inset LatexCommand \ref{sec:Related-open-source-tools}
21995
21996 \end_inset
21997
21998 ).
21999 \layout Itemize
22000
22001 toggle MCU port pins at strategic points within your code and use an oscilloscop
22002 e.
22003  A
22004 \emph on
22005 digital oscilloscope
22006 \emph default
22007
22008 \begin_inset LatexCommand \index{Oscilloscope}
22009
22010 \end_inset
22011
22012  with deep trace memory is really helpful especially if you have to debug
22013  a realtime application.
22014  If you need to monitor more pins than your oscilloscope provides you can
22015  sometimes get away with a small R-2R network.
22016  On a single channel oscilloscope you could f.e.
22017  monitor 2 push-pull driven pins by connecting one via a 10\SpecialChar ~
22018 k
22019 \begin_inset Formula $\Omega$
22020 \end_inset
22021
22022  resistor and the other one by a 5\SpecialChar ~
22023 k
22024 \begin_inset Formula $\Omega$
22025 \end_inset
22026
22027  resistor to the oscilloscope probe (check output drive capability of the
22028  pins you want to monitor).
22029  If you need to monitor many more pins a
22030 \emph on
22031 logic analyzer
22032 \emph default
22033  will be handy.
22034 \layout Itemize
22035
22036 use an ICE (
22037 \emph on
22038 i
22039 \emph default
22040 n
22041 \emph on
22042 c
22043 \emph default
22044 ircuit
22045 \emph on
22046 e
22047 \emph default
22048 mulator
22049 \begin_inset LatexCommand \index{ICE (in circuit emulator)}
22050
22051 \end_inset
22052
22053 ).
22054  Usually very expensive.
22055  And very nice to have too.
22056  And usually locks you (for years...) to the devices the ICE can emulate.
22057
22058 \layout Itemize
22059
22060 use a remote debugger.
22061  In most 8-bit systems the symbol information is not available on the target,
22062  and a complete debugger is too bulky for the target system.
22063  Therefore usually a debugger on the host system connects to an on-target
22064  debugging stub which accepts only primitive commands.
22065
22066 \newline
22067 Terms to enter into your favourite search engine could be 'remote debugging',
22068  'gdb stub' or 'inferior debugger'.
22069  (is there one?)
22070 \layout Itemize
22071
22072 use an on target hardware debugger.
22073  Some of the more modern MCUs include hardware support for setting break
22074  points and monitoring/changing variables by using dedicated hardware pins.
22075  This facility doesn't require additional code to run on the target and
22076
22077 \emph on
22078 usually
22079 \emph default
22080  doesn't affect runtime behaviour until a breakpoint is hit.
22081  For the mcs51 most hardware debuggers use the AOMF
22082 \begin_inset LatexCommand \index{AOMF, AOMF51}
22083
22084 \end_inset
22085
22086  file (see
22087 \begin_inset LatexCommand \ref{OMF file}
22088
22089 \end_inset
22090
22091 ) as input file.
22092
22093 \layout Standard
22094
22095 Last not least:
22096 \layout Itemize
22097
22098 if you are not familiar with any of the following terms you're likely to
22099  run into problems rather sooner than later:
22100 \emph on
22101 volatile
22102 \emph default
22103 ,
22104 \emph on
22105 atomic
22106 \emph default
22107 ,
22108 \emph on
22109 memory map
22110 \emph default
22111 ,
22112 \emph on
22113 overlay
22114 \emph default
22115 .
22116  As an embedded programmer you
22117 \emph on
22118 have
22119 \emph default
22120  to know them so why not look them up
22121 \emph on
22122 before
22123 \emph default
22124  you have problems?)
22125 \layout Itemize
22126
22127 tell someone else about your problem (actually this is a surprisingly effective
22128  means to hunt down the bug even if the listener is not familiar with your
22129  environment).
22130  As 'failure to communicate' is probably one of the job-induced deformations
22131  of an embedded programmer this is highly encouraged.
22132 \layout Section
22133
22134 Debugging with SDCDB
22135 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
22136
22137 \end_inset
22138
22139
22140 \begin_inset LatexCommand \index{SDCDB (debugger)}
22141
22142 \end_inset
22143
22144
22145 \layout Standard
22146
22147 SDCC is distributed with a source level debugger
22148 \begin_inset LatexCommand \index{Debugger}
22149
22150 \end_inset
22151
22152 .
22153  The debugger uses a command line interface, the command repertoire of the
22154  debugger has been kept as close to gdb
22155 \begin_inset LatexCommand \index{gdb}
22156
22157 \end_inset
22158
22159  (the GNU debugger) as possible.
22160  The configuration and build process is part of the standard compiler installati
22161 on, which also builds and installs the debugger in the target directory
22162  specified during configuration.
22163  The debugger allows you debug BOTH at the C source and at the ASM source
22164  level.
22165 \layout Subsection
22166
22167 Compiling for Debugging
22168 \layout Standard
22169
22170 The -
22171 \begin_inset ERT
22172 status Collapsed
22173
22174 \layout Standard
22175
22176 \backslash
22177 /
22178 \end_inset
22179
22180 -debug
22181 \begin_inset LatexCommand \index{-\/-debug}
22182
22183 \end_inset
22184
22185  option must be specified for all files for which debug information is to
22186  be generated.
22187  The compiler generates a .adb file for each of these files.
22188  The linker creates the .cdb
22189 \begin_inset LatexCommand \index{<file>.cdb}
22190
22191 \end_inset
22192
22193  file from the .adb
22194 \begin_inset LatexCommand \index{<file>.adb}
22195
22196 \end_inset
22197
22198  files and the address information.
22199  This .cdb is used by the debugger.
22200 \layout Subsection
22201
22202 How the Debugger Works
22203 \layout Standard
22204
22205 When the -
22206 \begin_inset ERT
22207 status Collapsed
22208
22209 \layout Standard
22210
22211 \backslash
22212 /
22213 \end_inset
22214
22215 -debug option is specified the compiler generates extra symbol information
22216  some of which are put into the assembler source and some are put into the
22217  .adb file.
22218  Then the linker creates the .cdb file from the individual .adb files with
22219  the address information for the symbols.
22220  The debugger reads the symbolic information generated by the compiler &
22221  the address information generated by the linker.
22222  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
22223  execution is controlled by the debugger.
22224  When a command is issued for the debugger, it translates it into appropriate
22225  commands for the simulator.
22226  (Currently SDCDM only connects to the simulator but
22227 \emph on
22228 newcdb
22229 \emph default
22230  at
22231 \begin_inset LatexCommand \url{http://ec2drv.sf.net/}
22232
22233 \end_inset
22234
22235  is an effort to connect directly to the hardware.)
22236 \layout Subsection
22237
22238 Starting the Debugger SDCDB
22239 \layout Standard
22240
22241 The debugger can be started using the following command line.
22242  (Assume the file you are debugging has the file name foo).
22243 \newline
22244
22245 \newline
22246
22247 \family sans
22248 \series bold
22249 sdcdb foo
22250 \newline
22251
22252 \family default
22253 \series default
22254
22255 \newline
22256 The debugger will look for the following files.
22257 \layout Itemize
22258
22259 foo.c - the source file.
22260 \layout Itemize
22261
22262 foo.cdb - the debugger symbol information file.
22263 \layout Itemize
22264
22265 foo.ihx - the Intel hex format
22266 \begin_inset LatexCommand \index{Intel hex format}
22267
22268 \end_inset
22269
22270  object file.
22271 \layout Subsection
22272
22273 SDCDB Command Line Options
22274 \layout Itemize
22275
22276 -
22277 \begin_inset ERT
22278 status Collapsed
22279
22280 \layout Standard
22281
22282 \backslash
22283 /
22284 \end_inset
22285
22286 -directory=<source file directory> this option can used to specify the directory
22287  search list.
22288  The debugger will look into the directory list specified for source, cdb
22289  & ihx files.
22290  The items in the directory list must be separated by ':', e.g.
22291  if the source files can be in the directories /home/src1 and /home/src2,
22292  the -
22293 \begin_inset ERT
22294 status Collapsed
22295
22296 \layout Standard
22297
22298 \backslash
22299 /
22300 \end_inset
22301
22302 -directory option should be -
22303 \begin_inset ERT
22304 status Collapsed
22305
22306 \layout Standard
22307
22308 \backslash
22309 /
22310 \end_inset
22311
22312 -directory=/home/src1:/home/src2.
22313  Note there can be no spaces in the option.
22314
22315 \layout Itemize
22316
22317 -cd <directory> - change to the <directory>.
22318 \layout Itemize
22319
22320 -fullname - used by GUI front ends.
22321 \layout Itemize
22322
22323 -cpu <cpu-type> - this argument is passed to the simulator please see the
22324  simulator docs for details.
22325 \layout Itemize
22326
22327 -X <Clock frequency > this options is passed to the simulator please see
22328  the simulator docs for details.
22329 \layout Itemize
22330
22331 -s <serial port file> passed to simulator see the simulator docs for details.
22332 \layout Itemize
22333
22334 -S <serial in,out> passed to simulator see the simulator docs for details.
22335 \layout Itemize
22336
22337 -k <port number> passed to simulator see the simulator docs for details.
22338 \layout Subsection
22339
22340 SDCDB Debugger Commands
22341 \layout Standard
22342
22343 As mentioned earlier the command interface for the debugger has been deliberatel
22344 y kept as close the GNU debugger gdb, as possible.
22345  This will help the integration with existing graphical user interfaces
22346  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
22347  If you use a graphical user interface for the debugger you can skip this
22348  section.
22349 \layout Subsubsection*
22350
22351 break [line | file:line | function | file:function]
22352 \layout Standard
22353
22354 Set breakpoint at specified line or function:
22355 \newline
22356
22357 \newline
22358
22359 \family sans
22360 \series bold
22361 sdcdb>break 100
22362 \newline
22363 sdcdb>break foo.c:100
22364 \newline
22365 sdcdb>break funcfoo
22366 \newline
22367 sdcdb>break foo.c:funcfoo
22368 \layout Subsubsection*
22369
22370 clear [line | file:line | function | file:function ]
22371 \layout Standard
22372
22373 Clear breakpoint at specified line or function:
22374 \newline
22375
22376 \newline
22377
22378 \family sans
22379 \series bold
22380 sdcdb>clear 100
22381 \newline
22382 sdcdb>clear foo.c:100
22383 \newline
22384 sdcdb>clear funcfoo
22385 \newline
22386 sdcdb>clear foo.c:funcfoo
22387 \layout Subsubsection*
22388
22389 continue
22390 \layout Standard
22391
22392 Continue program being debugged, after breakpoint.
22393 \layout Subsubsection*
22394
22395 finish
22396 \layout Standard
22397
22398 Execute till the end of the current function.
22399 \layout Subsubsection*
22400
22401 delete [n]
22402 \layout Standard
22403
22404 Delete breakpoint number 'n'.
22405  If used without any option clear ALL user defined break points.
22406 \layout Subsubsection*
22407
22408 info [break | stack | frame | registers ]
22409 \layout Itemize
22410
22411 info break - list all breakpoints
22412 \layout Itemize
22413
22414 info stack - show the function call stack.
22415 \layout Itemize
22416
22417 info frame - show information about the current execution frame.
22418 \layout Itemize
22419
22420 info registers - show content of all registers.
22421 \layout Subsubsection*
22422
22423 step
22424 \layout Standard
22425
22426 Step program until it reaches a different source line.
22427  Note: pressing <return> repeats the last command.
22428 \layout Subsubsection*
22429
22430 next
22431 \layout Standard
22432
22433 Step program, proceeding through subroutine calls.
22434 \layout Subsubsection*
22435
22436 run
22437 \layout Standard
22438
22439 Start debugged program.
22440 \layout Subsubsection*
22441
22442 ptype variable
22443 \layout Standard
22444
22445 Print type information of the variable.
22446 \layout Subsubsection*
22447
22448 print variable
22449 \layout Standard
22450
22451 print value of variable.
22452 \layout Subsubsection*
22453
22454 file filename
22455 \layout Standard
22456
22457 load the given file name.
22458  Note this is an alternate method of loading file for debugging.
22459 \layout Subsubsection*
22460
22461 frame
22462 \layout Standard
22463
22464 print information about current frame.
22465 \layout Subsubsection*
22466
22467 set srcmode
22468 \layout Standard
22469
22470 Toggle between C source & assembly source.
22471 \layout Subsubsection*
22472
22473 ! simulator command
22474 \layout Standard
22475
22476 Send the string following '!' to the simulator, the simulator response is
22477  displayed.
22478  Note the debugger does not interpret the command being sent to the simulator,
22479  so if a command like 'go' is sent the debugger can loose its execution
22480  context and may display incorrect values.
22481 \layout Subsubsection*
22482
22483 quit
22484 \layout Standard
22485
22486 "Watch me now.
22487  Iam going Down.
22488  My name is Bobby Brown"
22489 \layout Subsection
22490
22491 Interfacing SDCDB with DDD
22492 \layout Comment
22493
22494 The screenshot was converted from png to eps with:
22495 \begin_inset Quotes sld
22496 \end_inset
22497
22498 bmeps -c -e8f -p3 ddd_example.png >ddd_example.eps
22499 \begin_inset Quotes srd
22500 \end_inset
22501
22502  which produces a pretty compact eps file which is free from compression
22503  artifacts.
22504 \layout Comment
22505
22506 The screenshot was included in sdccman.lyx cvs version 1.120 but later removed
22507  as this broke the build system on Sourceforge (pdf-file was broken.
22508  pdflatex does not accept eps files).
22509 \layout Standard
22510
22511 The
22512 \emph on
22513 p
22514 \emph default
22515 ortable
22516 \emph on
22517 n
22518 \emph default
22519 etwork
22520 \emph on
22521 g
22522 \emph default
22523 raphics File
22524 \size footnotesize
22525
22526 \begin_inset LatexCommand \url{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/doc/figures/ddd_example.png}
22527
22528 \end_inset
22529
22530
22531 \size default
22532  shows a screenshot of a debugging session with DDD
22533 \begin_inset LatexCommand \index{DDD (debugger)}
22534
22535 \end_inset
22536
22537  (Unix only) on a simulated 8032.
22538  The debugging session might not run as smoothly as the screenshot suggests.
22539  The debugger allows setting of breakpoints, displaying and changing variables,
22540  single stepping through C and assembler code.
22541
22542 \newline
22543 The source was compiled with
22544 \family sans
22545 \series bold
22546
22547 \newline
22548
22549 \newline
22550 sdcc -
22551 \family default
22552 \series default
22553
22554 \begin_inset ERT
22555 status Collapsed
22556
22557 \layout Standard
22558
22559 \backslash
22560 /
22561 \end_inset
22562
22563
22564 \family sans
22565 \series bold
22566 -debug ddd_example.c
22567 \family default
22568 \series default
22569
22570 \family sans
22571 \series bold
22572
22573 \newline
22574
22575 \family default
22576 \series default
22577
22578 \newline
22579 and DDD was invoked with
22580 \family sans
22581 \series bold
22582
22583 \newline
22584
22585 \newline
22586 ddd -debugger 'sdcdb -cpu 8032 ddd_example'
22587 \layout Subsection
22588
22589 Interfacing SDCDB with XEmacs
22590 \begin_inset LatexCommand \index{XEmacs}
22591
22592 \end_inset
22593
22594
22595 \begin_inset LatexCommand \index{Emacs}
22596
22597 \end_inset
22598
22599
22600 \layout Standard
22601
22602 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
22603  sdcdb.el and sdcdbsrc.el.
22604  These two files can be found in the $(prefix)/bin directory after the installat
22605 ion is complete.
22606  These files need to be loaded into XEmacs for the interface to work.
22607  This can be done at XEmacs startup time by inserting the following into
22608  your '.xemacs' file (which can be found in your HOME directory):
22609 \newline
22610
22611 \newline
22612
22613 \family typewriter
22614 (load-file sdcdbsrc.el)
22615 \family default
22616
22617 \newline
22618
22619 \newline
22620 .xemacs is a lisp file so the () around the command is REQUIRED.
22621  The files can also be loaded dynamically while XEmacs is running, set the
22622  environment variable 'EMACSLOADPATH' to the installation bin directory
22623  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
22624  To start the interface enter the following command:
22625 \newline
22626
22627 \newline
22628
22629 \family sans
22630 \series bold
22631 ESC-x sdcdbsrc
22632 \family default
22633 \series default
22634
22635 \newline
22636
22637 \newline
22638 You will prompted to enter the file name to be debugged.
22639
22640 \newline
22641
22642 \newline
22643 The command line options that are passed to the simulator directly are bound
22644  to default values in the file sdcdbsrc.el.
22645  The variables are listed below, these values maybe changed as required.
22646 \layout Itemize
22647
22648 sdcdbsrc-cpu-type '51
22649 \layout Itemize
22650
22651 sdcdbsrc-frequency '11059200
22652 \layout Itemize
22653
22654 sdcdbsrc-serial nil
22655 \layout Standard
22656
22657 The following is a list of key mapping for the debugger interface.
22658 \layout Standard
22659
22660 \SpecialChar ~
22661
22662 \family typewriter
22663
22664 \newline
22665 ;;\SpecialChar ~
22666 Current Listing ::
22667 \newline
22668 ;;key\SpecialChar ~
22669 \SpecialChar ~
22670 \SpecialChar ~
22671 \SpecialChar ~
22672 \SpecialChar ~
22673 \SpecialChar ~
22674 \SpecialChar ~
22675 \SpecialChar ~
22676 \SpecialChar ~
22677 \SpecialChar ~
22678 \SpecialChar ~
22679 \SpecialChar ~
22680 \SpecialChar ~
22681 \SpecialChar ~
22682 binding\SpecialChar ~
22683 \SpecialChar ~
22684 \SpecialChar ~
22685 \SpecialChar ~
22686 \SpecialChar ~
22687 \SpecialChar ~
22688 \SpecialChar ~
22689 \SpecialChar ~
22690 \SpecialChar ~
22691 \SpecialChar ~
22692 \SpecialChar ~
22693 \SpecialChar ~
22694 \SpecialChar ~
22695 \SpecialChar ~
22696 \SpecialChar ~
22697 \SpecialChar ~
22698 \SpecialChar ~
22699 \SpecialChar ~
22700 \SpecialChar ~
22701 \SpecialChar ~
22702 \SpecialChar ~
22703 \SpecialChar ~
22704 Comment
22705 \newline
22706 ;;---\SpecialChar ~
22707 \SpecialChar ~
22708 \SpecialChar ~
22709 \SpecialChar ~
22710 \SpecialChar ~
22711 \SpecialChar ~
22712 \SpecialChar ~
22713 \SpecialChar ~
22714 \SpecialChar ~
22715 \SpecialChar ~
22716 \SpecialChar ~
22717 \SpecialChar ~
22718 \SpecialChar ~
22719 \SpecialChar ~
22720 -------\SpecialChar ~
22721 \SpecialChar ~
22722 \SpecialChar ~
22723 \SpecialChar ~
22724 \SpecialChar ~
22725 \SpecialChar ~
22726 \SpecialChar ~
22727 \SpecialChar ~
22728 \SpecialChar ~
22729 \SpecialChar ~
22730 \SpecialChar ~
22731 \SpecialChar ~
22732 \SpecialChar ~
22733 \SpecialChar ~
22734 \SpecialChar ~
22735 \SpecialChar ~
22736 \SpecialChar ~
22737 \SpecialChar ~
22738 \SpecialChar ~
22739 \SpecialChar ~
22740 \SpecialChar ~
22741 \SpecialChar ~
22742 -------
22743 \newline
22744 ;;
22745 \newline
22746 ;;\SpecialChar ~
22747 n\SpecialChar ~
22748 \SpecialChar ~
22749 \SpecialChar ~
22750 \SpecialChar ~
22751 \SpecialChar ~
22752 \SpecialChar ~
22753 \SpecialChar ~
22754 \SpecialChar ~
22755 \SpecialChar ~
22756 \SpecialChar ~
22757 \SpecialChar ~
22758 \SpecialChar ~
22759 \SpecialChar ~
22760 \SpecialChar ~
22761 \SpecialChar ~
22762 sdcdb-next-from-src\SpecialChar ~
22763 \SpecialChar ~
22764 \SpecialChar ~
22765 \SpecialChar ~
22766 \SpecialChar ~
22767 \SpecialChar ~
22768 \SpecialChar ~
22769 \SpecialChar ~
22770 \SpecialChar ~
22771 \SpecialChar ~
22772 SDCDB next command
22773 \newline
22774 ;;\SpecialChar ~
22775 b\SpecialChar ~
22776 \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 sdcdb-back-from-src\SpecialChar ~
22791 \SpecialChar ~
22792 \SpecialChar ~
22793 \SpecialChar ~
22794 \SpecialChar ~
22795 \SpecialChar ~
22796 \SpecialChar ~
22797 \SpecialChar ~
22798 \SpecialChar ~
22799 \SpecialChar ~
22800 SDCDB back command
22801 \newline
22802 ;;\SpecialChar ~
22803 c\SpecialChar ~
22804 \SpecialChar ~
22805 \SpecialChar ~
22806 \SpecialChar ~
22807 \SpecialChar ~
22808 \SpecialChar ~
22809 \SpecialChar ~
22810 \SpecialChar ~
22811 \SpecialChar ~
22812 \SpecialChar ~
22813 \SpecialChar ~
22814 \SpecialChar ~
22815 \SpecialChar ~
22816 \SpecialChar ~
22817 \SpecialChar ~
22818 sdcdb-cont-from-src\SpecialChar ~
22819 \SpecialChar ~
22820 \SpecialChar ~
22821 \SpecialChar ~
22822 \SpecialChar ~
22823 \SpecialChar ~
22824 \SpecialChar ~
22825 \SpecialChar ~
22826 \SpecialChar ~
22827 \SpecialChar ~
22828 SDCDB continue command
22829 \newline
22830 ;;\SpecialChar ~
22831 s\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 sdcdb-step-from-src\SpecialChar ~
22847 \SpecialChar ~
22848 \SpecialChar ~
22849 \SpecialChar ~
22850 \SpecialChar ~
22851 \SpecialChar ~
22852 \SpecialChar ~
22853 \SpecialChar ~
22854 \SpecialChar ~
22855 \SpecialChar ~
22856 SDCDB step command
22857 \newline
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 \SpecialChar ~
22871 \SpecialChar ~
22872 \SpecialChar ~
22873 \SpecialChar ~
22874 sdcdb-whatis-c-sexp\SpecialChar ~
22875 \SpecialChar ~
22876 \SpecialChar ~
22877 \SpecialChar ~
22878 \SpecialChar ~
22879 \SpecialChar ~
22880 \SpecialChar ~
22881 \SpecialChar ~
22882 \SpecialChar ~
22883 \SpecialChar ~
22884 SDCDB ptypecommand for data at
22885 \newline
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 \SpecialChar ~
22899 \SpecialChar ~
22900 \SpecialChar ~
22901 \SpecialChar ~
22902 \SpecialChar ~
22903 \SpecialChar ~
22904 \SpecialChar ~
22905 \SpecialChar ~
22906 \SpecialChar ~
22907 \SpecialChar ~
22908 \SpecialChar ~
22909 \SpecialChar ~
22910 \SpecialChar ~
22911 \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 \SpecialChar ~
22927 \SpecialChar ~
22928 \SpecialChar ~
22929 \SpecialChar ~
22930 \SpecialChar ~
22931 \SpecialChar ~
22932 \SpecialChar ~
22933 buffer point
22934 \newline
22935 ;;\SpecialChar ~
22936 x\SpecialChar ~
22937 \SpecialChar ~
22938 \SpecialChar ~
22939 \SpecialChar ~
22940 \SpecialChar ~
22941 \SpecialChar ~
22942 \SpecialChar ~
22943 \SpecialChar ~
22944 \SpecialChar ~
22945 \SpecialChar ~
22946 \SpecialChar ~
22947 \SpecialChar ~
22948 \SpecialChar ~
22949 \SpecialChar ~
22950 \SpecialChar ~
22951 sdcdbsrc-delete\SpecialChar ~
22952 \SpecialChar ~
22953 \SpecialChar ~
22954 \SpecialChar ~
22955 \SpecialChar ~
22956 \SpecialChar ~
22957 \SpecialChar ~
22958 \SpecialChar ~
22959 \SpecialChar ~
22960 \SpecialChar ~
22961 \SpecialChar ~
22962 \SpecialChar ~
22963 \SpecialChar ~
22964 \SpecialChar ~
22965 SDCDB Delete all breakpoints if no arg
22966 \newline
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 \SpecialChar ~
22983 \SpecialChar ~
22984 \SpecialChar ~
22985 \SpecialChar ~
22986 \SpecialChar ~
22987 \SpecialChar ~
22988 \SpecialChar ~
22989 \SpecialChar ~
22990 \SpecialChar ~
22991 \SpecialChar ~
22992 \SpecialChar ~
22993 \SpecialChar ~
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 given or delete arg (C-u arg x)
23015 \newline
23016 ;;\SpecialChar ~
23017 m\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 sdcdbsrc-frame\SpecialChar ~
23033 \SpecialChar ~
23034 \SpecialChar ~
23035 \SpecialChar ~
23036 \SpecialChar ~
23037 \SpecialChar ~
23038 \SpecialChar ~
23039 \SpecialChar ~
23040 \SpecialChar ~
23041 \SpecialChar ~
23042 \SpecialChar ~
23043 \SpecialChar ~
23044 \SpecialChar ~
23045 \SpecialChar ~
23046 \SpecialChar ~
23047 SDCDB Display current frame if no arg,
23048 \newline
23049 ;;\SpecialChar ~
23050 \SpecialChar ~
23051 \SpecialChar ~
23052 \SpecialChar ~
23053 \SpecialChar ~
23054 \SpecialChar ~
23055 \SpecialChar ~
23056 \SpecialChar ~
23057 \SpecialChar ~
23058 \SpecialChar ~
23059 \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 \SpecialChar ~
23074 \SpecialChar ~
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 given or display frame arg
23097 \newline
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 \SpecialChar ~
23123 \SpecialChar ~
23124 \SpecialChar ~
23125 \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 \SpecialChar ~
23141 \SpecialChar ~
23142 \SpecialChar ~
23143 \SpecialChar ~
23144 \SpecialChar ~
23145 buffer point
23146 \newline
23147 ;;\SpecialChar ~
23148 !\SpecialChar ~
23149 \SpecialChar ~
23150 \SpecialChar ~
23151 \SpecialChar ~
23152 \SpecialChar ~
23153 \SpecialChar ~
23154 \SpecialChar ~
23155 \SpecialChar ~
23156 \SpecialChar ~
23157 \SpecialChar ~
23158 \SpecialChar ~
23159 \SpecialChar ~
23160 \SpecialChar ~
23161 \SpecialChar ~
23162 \SpecialChar ~
23163 sdcdbsrc-goto-sdcdb\SpecialChar ~
23164 \SpecialChar ~
23165 \SpecialChar ~
23166 \SpecialChar ~
23167 \SpecialChar ~
23168 \SpecialChar ~
23169 \SpecialChar ~
23170 \SpecialChar ~
23171 \SpecialChar ~
23172 \SpecialChar ~
23173 Goto the SDCDB output buffer
23174 \newline
23175 ;;\SpecialChar ~
23176 p\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 sdcdb-print-c-sexp\SpecialChar ~
23192 \SpecialChar ~
23193 \SpecialChar ~
23194 \SpecialChar ~
23195 \SpecialChar ~
23196 \SpecialChar ~
23197 \SpecialChar ~
23198 \SpecialChar ~
23199 \SpecialChar ~
23200 \SpecialChar ~
23201 \SpecialChar ~
23202 SDCDB print command for data at
23203 \newline
23204 ;;\SpecialChar ~
23205 \SpecialChar ~
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 buffer point
23252 \newline
23253 ;;\SpecialChar ~
23254 g\SpecialChar ~
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 sdcdbsrc-goto-sdcdb\SpecialChar ~
23270 \SpecialChar ~
23271 \SpecialChar ~
23272 \SpecialChar ~
23273 \SpecialChar ~
23274 \SpecialChar ~
23275 \SpecialChar ~
23276 \SpecialChar ~
23277 \SpecialChar ~
23278 \SpecialChar ~
23279 Goto the SDCDB output buffer
23280 \newline
23281 ;;\SpecialChar ~
23282 t\SpecialChar ~
23283 \SpecialChar ~
23284 \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 sdcdbsrc-mode\SpecialChar ~
23298 \SpecialChar ~
23299 \SpecialChar ~
23300 \SpecialChar ~
23301 \SpecialChar ~
23302 \SpecialChar ~
23303 \SpecialChar ~
23304 \SpecialChar ~
23305 \SpecialChar ~
23306 \SpecialChar ~
23307 \SpecialChar ~
23308 \SpecialChar ~
23309 \SpecialChar ~
23310 \SpecialChar ~
23311 \SpecialChar ~
23312 \SpecialChar ~
23313 Toggles Sdcdbsrc mode (turns it off)
23314 \newline
23315 ;;
23316 \newline
23317 ;;\SpecialChar ~
23318 C-c\SpecialChar ~
23319 C-f\SpecialChar ~
23320 \SpecialChar ~
23321 \SpecialChar ~
23322 \SpecialChar ~
23323 \SpecialChar ~
23324 \SpecialChar ~
23325 \SpecialChar ~
23326 \SpecialChar ~
23327 \SpecialChar ~
23328 sdcdb-finish-from-src\SpecialChar ~
23329 \SpecialChar ~
23330 \SpecialChar ~
23331 \SpecialChar ~
23332 \SpecialChar ~
23333 \SpecialChar ~
23334 \SpecialChar ~
23335 \SpecialChar ~
23336 SDCDB finish command
23337 \newline
23338 ;;
23339 \newline
23340 ;;\SpecialChar ~
23341 C-x\SpecialChar ~
23342 SPC\SpecialChar ~
23343 \SpecialChar ~
23344 \SpecialChar ~
23345 \SpecialChar ~
23346 \SpecialChar ~
23347 \SpecialChar ~
23348 \SpecialChar ~
23349 \SpecialChar ~
23350 \SpecialChar ~
23351 sdcdb-break\SpecialChar ~
23352 \SpecialChar ~
23353 \SpecialChar ~
23354 \SpecialChar ~
23355 \SpecialChar ~
23356 \SpecialChar ~
23357 \SpecialChar ~
23358 \SpecialChar ~
23359 \SpecialChar ~
23360 \SpecialChar ~
23361 \SpecialChar ~
23362 \SpecialChar ~
23363 \SpecialChar ~
23364 \SpecialChar ~
23365 \SpecialChar ~
23366 \SpecialChar ~
23367 \SpecialChar ~
23368 \SpecialChar ~
23369 Set break for line with point
23370 \newline
23371 ;;\SpecialChar ~
23372 ESC\SpecialChar ~
23373 t\SpecialChar ~
23374 \SpecialChar ~
23375 \SpecialChar ~
23376 \SpecialChar ~
23377 \SpecialChar ~
23378 \SpecialChar ~
23379 \SpecialChar ~
23380 \SpecialChar ~
23381 \SpecialChar ~
23382 \SpecialChar ~
23383 \SpecialChar ~
23384 sdcdbsrc-mode\SpecialChar ~
23385 \SpecialChar ~
23386 \SpecialChar ~
23387 \SpecialChar ~
23388 \SpecialChar ~
23389 \SpecialChar ~
23390 \SpecialChar ~
23391 \SpecialChar ~
23392 \SpecialChar ~
23393 \SpecialChar ~
23394 \SpecialChar ~
23395 \SpecialChar ~
23396 \SpecialChar ~
23397 \SpecialChar ~
23398 \SpecialChar ~
23399 \SpecialChar ~
23400 Toggle Sdcdbsrc mode
23401 \newline
23402 ;;\SpecialChar ~
23403 ESC\SpecialChar ~
23404 m\SpecialChar ~
23405 \SpecialChar ~
23406 \SpecialChar ~
23407 \SpecialChar ~
23408 \SpecialChar ~
23409 \SpecialChar ~
23410 \SpecialChar ~
23411 \SpecialChar ~
23412 \SpecialChar ~
23413 \SpecialChar ~
23414 \SpecialChar ~
23415 sdcdbsrc-srcmode\SpecialChar ~
23416 \SpecialChar ~
23417 \SpecialChar ~
23418 \SpecialChar ~
23419 \SpecialChar ~
23420 \SpecialChar ~
23421 \SpecialChar ~
23422 \SpecialChar ~
23423 \SpecialChar ~
23424 \SpecialChar ~
23425 \SpecialChar ~
23426 \SpecialChar ~
23427 \SpecialChar ~
23428 Toggle list mode
23429 \newline
23430 ;;
23431 \newline
23432
23433 \layout Chapter
23434 \pagebreak_top
23435 TIPS
23436 \layout Standard
23437
23438 Here are a few guidelines that will help the compiler generate more efficient
23439  code, some of the tips are specific to this compiler others are generally
23440  good programming practice.
23441 \layout Itemize
23442
23443 Use the smallest data type to represent your data-value.
23444  If it is known in advance that the value is going to be less than 256 then
23445  use an 'unsigned char' instead of a 'short' or 'int'.
23446  Please note, that ANSI C requires both signed and unsigned chars to be
23447  promoted to 'signed int'
23448 \begin_inset LatexCommand \index{promotion to signed int}
23449
23450 \end_inset
23451
23452
23453 \begin_inset Marginal
23454 collapsed true
23455
23456 \layout Standard
23457
23458
23459 \series bold
23460 \SpecialChar ~
23461 !
23462 \end_inset
23463
23464  before doing any operation.
23465  This promotion
23466 \begin_inset LatexCommand \index{type promotion}
23467
23468 \end_inset
23469
23470
23471 \begin_inset LatexCommand \label{type promotion}
23472
23473 \end_inset
23474
23475  can be omitted, if the result is the same.
23476  The effect of the promotion rules together with the sign-extension is often
23477  surprising:
23478 \begin_deeper
23479 \layout Verse
23480
23481
23482 \family typewriter
23483 unsigned char uc = 0xfe;
23484 \newline
23485 if (uc * uc < 0) /* this is true! */
23486 \newline
23487 {
23488 \newline
23489 \SpecialChar ~
23490 \SpecialChar ~
23491 \SpecialChar ~
23492 \SpecialChar ~
23493 ....
23494 \newline
23495 }
23496 \layout Standard
23497
23498
23499 \family typewriter
23500 uc * uc
23501 \family default
23502  is evaluated as
23503 \family typewriter
23504 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
23505 \family default
23506 .
23507
23508 \newline
23509 Another one:
23510 \layout Verse
23511
23512
23513 \family typewriter
23514 (unsigned char) -12 / (signed char) -3 = ...
23515 \layout Standard
23516
23517 No, the result is not 4:
23518 \layout Verse
23519
23520
23521 \family typewriter
23522 (int) (unsigned char) -12 / (int) (signed char) -3 =
23523 \newline
23524 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
23525 \newline
23526 (int) 0x00f4 / (int) 0xfffd =
23527 \newline
23528 (int) 0x00f4 / (int) 0xfffd =
23529 \newline
23530 (int) 244 / (int) -3 =
23531 \newline
23532 (int) -81 = (int) 0xffaf;
23533 \layout Standard
23534
23535 Don't complain, that gcc gives you a different result.
23536  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
23537  Therefore the results are different.
23538 \newline
23539 From
23540 \begin_inset Quotes sld
23541 \end_inset
23542
23543 comp.lang.c FAQ
23544 \begin_inset Quotes srd
23545 \end_inset
23546
23547 :
23548 \layout Quote
23549
23550
23551 \emph on
23552 If well-defined overflow characteristics are important and negative values
23553  are not, or if you want to steer clear of sign-extension problems when
23554  manipulating bits or bytes, use one of the corresponding unsigned types.
23555  (Beware when mixing signed and unsigned values in expressions, though.)
23556 \newline
23557 Although character types (especially unsigned char) can be used as "tiny"
23558  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
23559 ble sign extension and increased code size.
23560 \end_deeper
23561 \layout Itemize
23562
23563 Use unsigned when it is known in advance that the value is not going to
23564  be negative.
23565  This helps especially if you are doing division or multiplication, bit-shifting
23566  or are using an array index.
23567 \layout Itemize
23568
23569 NEVER jump into a LOOP.
23570 \layout Itemize
23571
23572 Declare the variables to be local
23573 \begin_inset LatexCommand \index{local variables}
23574
23575 \end_inset
23576
23577  whenever possible, especially loop control variables (induction).
23578 \layout Itemize
23579
23580 Since the compiler does not always do implicit integral promotion, the programme
23581 r should do an explicit cast when integral promotion is required.
23582 \layout Itemize
23583
23584 Reducing the size of division, multiplication & modulus operations can reduce
23585  code size substantially.
23586  Take the following code for example.
23587 \begin_deeper
23588 \layout Verse
23589
23590
23591 \family typewriter
23592 foobar(unsigned int p1, unsigned char ch)
23593 \newline
23594 {
23595 \newline
23596 \SpecialChar ~
23597 \SpecialChar ~
23598 \SpecialChar ~
23599 \SpecialChar ~
23600 unsigned char ch1 = p1 % ch ;
23601 \newline
23602 \SpecialChar ~
23603 \SpecialChar ~
23604 \SpecialChar ~
23605 \SpecialChar ~
23606 ....
23607 \newline
23608 }
23609 \layout Standard
23610
23611 For the modulus operation the variable ch will be promoted to unsigned int
23612  first then the modulus operation will be performed (this will lead to a
23613  call to support routine _moduint()), and the result will be casted to a
23614  char.
23615  If the code is changed to
23616 \layout Verse
23617
23618
23619 \family typewriter
23620 foobar(unsigned int p1, unsigned char ch)
23621 \newline
23622 {
23623 \newline
23624 \SpecialChar ~
23625 \SpecialChar ~
23626 \SpecialChar ~
23627 \SpecialChar ~
23628 unsigned char ch1 = (unsigned char)p1 % ch ;
23629 \newline
23630 \SpecialChar ~
23631 \SpecialChar ~
23632 \SpecialChar ~
23633 \SpecialChar ~
23634 ....
23635 \newline
23636 }
23637 \layout Standard
23638
23639 It would substantially reduce the code generated (future versions of the
23640  compiler will be smart enough to detect such optimization opportunities).
23641 \end_deeper
23642 \layout Itemize
23643
23644 Have a look at the assembly listing to get a
23645 \begin_inset Quotes sld
23646 \end_inset
23647
23648 feeling
23649 \begin_inset Quotes srd
23650 \end_inset
23651
23652  for the code generation.
23653 \layout Section
23654
23655 Porting code from or to other compilers
23656 \begin_inset LatexCommand \label{sec:Porting-code-to-other-compilers}
23657
23658 \end_inset
23659
23660
23661 \layout Itemize
23662
23663 check whether endianness of the compilers differs and adapt where needed.
23664 \layout Itemize
23665
23666 check the device specific header files
23667 \begin_inset LatexCommand \index{Header files}
23668
23669 \end_inset
23670
23671
23672 \begin_inset LatexCommand \index{Include files}
23673
23674 \end_inset
23675
23676  for compiler specific syntax.
23677  Eventually include the file <compiler.h
23678 \begin_inset LatexCommand \index{compiler.h (include file)}
23679
23680 \end_inset
23681
23682 >
23683 \begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/device/include/mcs51/compiler.h?view=markup}
23684
23685 \end_inset
23686
23687  to allow using common header files.
23688  (see f.e.
23689  cc2510fx.h
23690 \begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/device/include/mcs51/cc2510fx.h?view=markup}
23691
23692 \end_inset
23693
23694 ).
23695 \layout Itemize
23696
23697 check whether the startup code contains the correct initialization (watchdog,
23698  peripherals).
23699 \layout Itemize
23700
23701 check whether the sizes of short, int, long match.
23702 \layout Itemize
23703
23704 check if some 16 or 32 bit hardware registers require a specific addressing
23705  order (least significant or most significant byte first) and adapt if needed
23706  (
23707 \emph on
23708 first
23709 \emph default
23710  and
23711 \emph on
23712 last
23713 \emph default
23714  relate to time and not to lower/upper memory location here, so this is
23715
23716 \emph on
23717 not
23718 \emph default
23719  the same as endianness).
23720 \layout Itemize
23721
23722 check whether the keyword
23723 \emph on
23724 volatile
23725 \emph default
23726  is used where needed.
23727  The compilers might differ in their optimization characteristics (as different
23728  versions of the same compiler might also use more clever optimizations
23729  this is good idea anyway).
23730  See section
23731 \begin_inset LatexCommand \ref{sub:Common-interrupt-pitfall-volatile}
23732
23733 \end_inset
23734
23735 .
23736 \layout Itemize
23737
23738 check that the compilers are not told to supress warnings.
23739 \layout Itemize
23740
23741 check and convert compiler specific extensions (interrupts, memory areas,
23742  pragmas etc.).
23743 \layout Itemize
23744
23745 check for differences in type promotion.
23746  Especially check for math operations on
23747 \family typewriter
23748 char
23749 \family default
23750  or
23751 \family typewriter
23752 unsigned char
23753 \family default
23754  variables.
23755  For the sake of C99 compatibility SDCC will probably promote these to
23756 \family typewriter
23757 int
23758 \family default
23759  more often than other compilers.
23760  Eventually insert explicit casts to
23761 \family typewriter
23762 (char)
23763 \family default
23764 or
23765 \family typewriter
23766  (unsigned char)
23767 \family default
23768 .
23769  Also check that the ~\SpecialChar ~
23770 operator
23771 \begin_inset LatexCommand \index{\~\/ Operator}
23772
23773 \end_inset
23774
23775  is not used on
23776 \family typewriter
23777 bit
23778 \begin_inset LatexCommand \index{bit}
23779
23780 \end_inset
23781
23782
23783 \family default
23784  variables, use the !\SpecialChar ~
23785 operator instead.
23786  See sections
23787 \begin_inset LatexCommand \ref{type promotion}
23788
23789 \end_inset
23790
23791  and
23792 \begin_inset LatexCommand \ref{sec:Compatibility-with-previous}
23793
23794 \end_inset
23795
23796 .
23797 \layout Itemize
23798
23799 check the assembly code generated for interrupt routines (f.e.
23800  for calls to possibly non-reentrant library functions).
23801 \layout Itemize
23802
23803 check whether timing loops result in proper timing (or preferably consider
23804  a rewrite of the code with timer based delays instead).
23805 \layout Itemize
23806
23807 check for differences in printf parameters (some compilers push (va_arg
23808 \begin_inset LatexCommand \index{vararg, va\_arg}
23809
23810 \end_inset
23811
23812 ) char variables as
23813 \family typewriter
23814 int
23815 \family default
23816  others push them as
23817 \family typewriter
23818 char
23819 \family default
23820 .
23821  See section
23822 \begin_inset LatexCommand \ref{sec:Compatibility-with-previous}
23823
23824 \end_inset
23825
23826 ).
23827 \layout Itemize
23828
23829 check the resulting memory map
23830 \begin_inset LatexCommand \index{Memory map}
23831
23832 \end_inset
23833
23834 .
23835  Usage of different memory spaces: code, stack, data (for mcs51/ds390 additional
23836 ly idata, pdata, xdata).
23837  Eventually check if unexpected library functions are included.
23838 \layout Section
23839
23840 Tools
23841 \begin_inset LatexCommand \index{Tools}
23842
23843 \end_inset
23844
23845  included in the distribution
23846 \layout Standard
23847 \align left
23848
23849 \begin_inset  Tabular
23850 <lyxtabular version="3" rows="12" columns="3">
23851 <features>
23852 <column alignment="left" valignment="top" leftline="true" width="0pt">
23853 <column alignment="left" valignment="top" leftline="true" width="0pt">
23854 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
23855 <row topline="true" bottomline="true">
23856 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23857 \begin_inset Text
23858
23859 \layout Standard
23860
23861 Name
23862 \end_inset
23863 </cell>
23864 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23865 \begin_inset Text
23866
23867 \layout Standard
23868
23869 Purpose
23870 \end_inset
23871 </cell>
23872 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23873 \begin_inset Text
23874
23875 \layout Standard
23876
23877 Directory
23878 \end_inset
23879 </cell>
23880 </row>
23881 <row topline="true">
23882 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23883 \begin_inset Text
23884
23885 \layout Standard
23886
23887 ucSsim
23888 \end_inset
23889 </cell>
23890 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23891 \begin_inset Text
23892
23893 \layout Standard
23894
23895 Simulator for various architectures
23896 \end_inset
23897 </cell>
23898 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23899 \begin_inset Text
23900
23901 \layout Standard
23902
23903 sdcc/sim/ucsim
23904 \end_inset
23905 </cell>
23906 </row>
23907 <row topline="true">
23908 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23909 \begin_inset Text
23910
23911 \layout Standard
23912
23913 keil2sdcc.pl
23914 \end_inset
23915 </cell>
23916 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23917 \begin_inset Text
23918
23919 \layout Standard
23920
23921 header file
23922 \begin_inset LatexCommand \index{Header files}
23923
23924 \end_inset
23925
23926
23927 \begin_inset LatexCommand \index{Include files}
23928
23929 \end_inset
23930
23931  conversion
23932 \end_inset
23933 </cell>
23934 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23935 \begin_inset Text
23936
23937 \layout Standard
23938
23939 sdcc/support/scripts
23940 \end_inset
23941 </cell>
23942 </row>
23943 <row topline="true">
23944 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23945 \begin_inset Text
23946
23947 \layout Standard
23948
23949 mh2h.c
23950 \end_inset
23951 </cell>
23952 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23953 \begin_inset Text
23954
23955 \layout Standard
23956
23957 header file conversion
23958 \end_inset
23959 </cell>
23960 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23961 \begin_inset Text
23962
23963 \layout Standard
23964
23965 sdcc/support/scripts
23966 \end_inset
23967 </cell>
23968 </row>
23969 <row topline="true">
23970 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23971 \begin_inset Text
23972
23973 \layout Standard
23974
23975 as-gbz80
23976 \end_inset
23977 </cell>
23978 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23979 \begin_inset Text
23980
23981 \layout Standard
23982
23983 Assembler
23984 \end_inset
23985 </cell>
23986 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23987 \begin_inset Text
23988
23989 \layout Standard
23990
23991
23992 \family roman
23993 \series medium
23994 \shape up
23995 \size normal
23996 \emph off
23997 \bar no
23998 \noun off
23999 \color none
24000 sdcc/bin
24001 \end_inset
24002 </cell>
24003 </row>
24004 <row topline="true">
24005 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24006 \begin_inset Text
24007
24008 \layout Standard
24009
24010 as-z80
24011 \end_inset
24012 </cell>
24013 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24014 \begin_inset Text
24015
24016 \layout Standard
24017
24018 Assembler
24019 \end_inset
24020 </cell>
24021 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24022 \begin_inset Text
24023
24024 \layout Standard
24025
24026
24027 \family roman
24028 \series medium
24029 \shape up
24030 \size normal
24031 \emph off
24032 \bar no
24033 \noun off
24034 \color none
24035 sdcc/bin
24036 \end_inset
24037 </cell>
24038 </row>
24039 <row topline="true">
24040 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24041 \begin_inset Text
24042
24043 \layout Standard
24044
24045 asx8051
24046 \end_inset
24047 </cell>
24048 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24049 \begin_inset Text
24050
24051 \layout Standard
24052
24053 Assembler
24054 \end_inset
24055 </cell>
24056 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24057 \begin_inset Text
24058
24059 \layout Standard
24060
24061
24062 \family roman
24063 \series medium
24064 \shape up
24065 \size normal
24066 \emph off
24067 \bar no
24068 \noun off
24069 \color none
24070 sdcc/bin
24071 \end_inset
24072 </cell>
24073 </row>
24074 <row topline="true">
24075 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24076 \begin_inset Text
24077
24078 \layout Standard
24079
24080 SDCDB
24081 \end_inset
24082 </cell>
24083 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24084 \begin_inset Text
24085
24086 \layout Standard
24087
24088 Simulator
24089 \end_inset
24090 </cell>
24091 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24092 \begin_inset Text
24093
24094 \layout Standard
24095
24096
24097 \family roman
24098 \series medium
24099 \shape up
24100 \size normal
24101 \emph off
24102 \bar no
24103 \noun off
24104 \color none
24105 sdcc/bin
24106 \end_inset
24107 </cell>
24108 </row>
24109 <row topline="true">
24110 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24111 \begin_inset Text
24112
24113 \layout Standard
24114
24115 aslink
24116 \end_inset
24117 </cell>
24118 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24119 \begin_inset Text
24120
24121 \layout Standard
24122
24123 Linker
24124 \end_inset
24125 </cell>
24126 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24127 \begin_inset Text
24128
24129 \layout Standard
24130
24131
24132 \family roman
24133 \series medium
24134 \shape up
24135 \size normal
24136 \emph off
24137 \bar no
24138 \noun off
24139 \color none
24140 sdcc/bin
24141 \end_inset
24142 </cell>
24143 </row>
24144 <row topline="true">
24145 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24146 \begin_inset Text
24147
24148 \layout Standard
24149
24150 link-z80
24151 \end_inset
24152 </cell>
24153 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24154 \begin_inset Text
24155
24156 \layout Standard
24157
24158 Linker
24159 \end_inset
24160 </cell>
24161 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24162 \begin_inset Text
24163
24164 \layout Standard
24165
24166
24167 \family roman
24168 \series medium
24169 \shape up
24170 \size normal
24171 \emph off
24172 \bar no
24173 \noun off
24174 \color none
24175 sdcc/bin
24176 \end_inset
24177 </cell>
24178 </row>
24179 <row topline="true">
24180 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24181 \begin_inset Text
24182
24183 \layout Standard
24184
24185 link-gbz80
24186 \end_inset
24187 </cell>
24188 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24189 \begin_inset Text
24190
24191 \layout Standard
24192
24193 Linker
24194 \end_inset
24195 </cell>
24196 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24197 \begin_inset Text
24198
24199 \layout Standard
24200
24201
24202 \family roman
24203 \series medium
24204 \shape up
24205 \size normal
24206 \emph off
24207 \bar no
24208 \noun off
24209 \color none
24210 sdcc/bin
24211 \end_inset
24212 </cell>
24213 </row>
24214 <row topline="true" bottomline="true">
24215 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24216 \begin_inset Text
24217
24218 \layout Standard
24219
24220 packihx
24221 \end_inset
24222 </cell>
24223 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24224 \begin_inset Text
24225
24226 \layout Standard
24227
24228 Intel Hex packer
24229 \begin_inset LatexCommand \index{packihx (tool)}
24230
24231 \end_inset
24232
24233
24234 \end_inset
24235 </cell>
24236 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24237 \begin_inset Text
24238
24239 \layout Standard
24240
24241
24242 \family roman
24243 \series medium
24244 \shape up
24245 \size normal
24246 \emph off
24247 \bar no
24248 \noun off
24249 \color none
24250 sdcc/bin
24251 \end_inset
24252 </cell>
24253 </row>
24254 </lyxtabular>
24255
24256 \end_inset
24257
24258
24259 \newline
24260
24261 \layout Section
24262
24263 Documentation
24264 \begin_inset LatexCommand \index{Documentation}
24265
24266 \end_inset
24267
24268  included in the distribution
24269 \layout Standard
24270 \align left
24271
24272 \begin_inset  Tabular
24273 <lyxtabular version="3" rows="10" columns="2">
24274 <features>
24275 <column alignment="left" valignment="top" leftline="true" width="0">
24276 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
24277 <row topline="true" bottomline="true">
24278 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24279 \begin_inset Text
24280
24281 \layout Standard
24282
24283 Subject / Title
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 Where to get / filename
24292 \end_inset
24293 </cell>
24294 </row>
24295 <row topline="true">
24296 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24297 \begin_inset Text
24298
24299 \layout Standard
24300
24301 SDCC Compiler User Guide
24302 \end_inset
24303 </cell>
24304 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24305 \begin_inset Text
24306
24307 \layout Standard
24308
24309 You're reading it right now
24310 \end_inset
24311 </cell>
24312 </row>
24313 <row topline="true">
24314 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24315 \begin_inset Text
24316
24317 \layout Standard
24318
24319 Changelog of SDCC
24320 \end_inset
24321 </cell>
24322 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24323 \begin_inset Text
24324
24325 \layout Standard
24326
24327 sdcc/Changelog
24328 \end_inset
24329 </cell>
24330 </row>
24331 <row topline="true">
24332 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24333 \begin_inset Text
24334
24335 \layout Standard
24336
24337 ASXXXX
24338 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
24339
24340 \end_inset
24341
24342
24343 \begin_inset LatexCommand \index{Assembler documentation}
24344
24345 \end_inset
24346
24347  Assemblers and ASLINK
24348 \begin_inset LatexCommand \index{aslink}
24349
24350 \end_inset
24351
24352
24353 \begin_inset LatexCommand \index{Linker documentation}
24354
24355 \end_inset
24356
24357  Relocating Linker
24358 \end_inset
24359 </cell>
24360 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24361 \begin_inset Text
24362
24363 \layout Standard
24364
24365 sdcc/as/doc/asxhtm.html
24366 \end_inset
24367 </cell>
24368 </row>
24369 <row topline="true">
24370 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24371 \begin_inset Text
24372
24373 \layout Standard
24374
24375 SDCC regression test
24376 \begin_inset LatexCommand \index{Regression test}
24377
24378 \end_inset
24379
24380
24381 \end_inset
24382 </cell>
24383 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24384 \begin_inset Text
24385
24386 \layout Standard
24387
24388 sdcc/doc/test_suite_spec.pdf
24389 \end_inset
24390 </cell>
24391 </row>
24392 <row topline="true">
24393 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24394 \begin_inset Text
24395
24396 \layout Standard
24397
24398 Various notes
24399 \end_inset
24400 </cell>
24401 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24402 \begin_inset Text
24403
24404 \layout Standard
24405
24406 sdcc/doc/*
24407 \end_inset
24408 </cell>
24409 </row>
24410 <row topline="true">
24411 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24412 \begin_inset Text
24413
24414 \layout Standard
24415
24416 Notes on debugging with SDCDB
24417 \begin_inset LatexCommand \index{SDCDB (debugger)}
24418
24419 \end_inset
24420
24421
24422 \end_inset
24423 </cell>
24424 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24425 \begin_inset Text
24426
24427 \layout Standard
24428
24429 sdcc/debugger/README
24430 \end_inset
24431 </cell>
24432 </row>
24433 <row topline="true">
24434 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24435 \begin_inset Text
24436
24437 \layout Standard
24438
24439 Software simulator for microcontrollers
24440 \end_inset
24441 </cell>
24442 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24443 \begin_inset Text
24444
24445 \layout Standard
24446
24447
24448 \family roman
24449 \series medium
24450 \shape up
24451 \size normal
24452 \emph off
24453 \bar no
24454 \noun off
24455 \color none
24456 sdcc/sim/ucsim/doc
24457 \family default
24458 \series default
24459 \shape default
24460 \size default
24461 \emph default
24462 \bar default
24463 \noun default
24464 \color default
24465 /index.html
24466 \end_inset
24467 </cell>
24468 </row>
24469 <row topline="true">
24470 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24471 \begin_inset Text
24472
24473 \layout Standard
24474
24475 Temporary notes on the pic16
24476 \begin_inset LatexCommand \index{PIC16}
24477
24478 \end_inset
24479
24480  port
24481 \end_inset
24482 </cell>
24483 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24484 \begin_inset Text
24485
24486 \layout Standard
24487
24488 sdcc/src/pic16/NOTES
24489 \end_inset
24490 </cell>
24491 </row>
24492 <row topline="true" bottomline="true">
24493 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24494 \begin_inset Text
24495
24496 \layout Standard
24497
24498 SDCC internal documentation (debugging file format)
24499 \end_inset
24500 </cell>
24501 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24502 \begin_inset Text
24503
24504 \layout Standard
24505
24506 sdcc/doc/
24507 \family roman
24508 \series medium
24509 \shape up
24510 \size normal
24511 \emph off
24512 \bar no
24513 \noun off
24514 \color none
24515 cdbfileformat.pd
24516 \family default
24517 \series default
24518 \shape default
24519 \size default
24520 \emph default
24521 \bar default
24522 \noun default
24523 \color default
24524 f
24525 \end_inset
24526 </cell>
24527 </row>
24528 </lyxtabular>
24529
24530 \end_inset
24531
24532
24533 \newline
24534
24535 \layout Section
24536
24537 Related open source tools
24538 \begin_inset LatexCommand \label{sec:Related-open-source-tools}
24539
24540 \end_inset
24541
24542
24543 \begin_inset LatexCommand \index{Related tools}
24544
24545 \end_inset
24546
24547
24548 \layout Standard
24549 \align left
24550
24551 \begin_inset  Tabular
24552 <lyxtabular version="3" rows="14" columns="3">
24553 <features>
24554 <column alignment="left" valignment="top" leftline="true" width="0pt">
24555 <column alignment="block" valignment="top" leftline="true" width="30line%">
24556 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
24557 <row topline="true" bottomline="true">
24558 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24559 \begin_inset Text
24560
24561 \layout Standard
24562
24563 Name
24564 \end_inset
24565 </cell>
24566 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24567 \begin_inset Text
24568
24569 \layout Standard
24570
24571 Purpose
24572 \end_inset
24573 </cell>
24574 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24575 \begin_inset Text
24576
24577 \layout Standard
24578
24579 Where to get
24580 \end_inset
24581 </cell>
24582 </row>
24583 <row topline="true">
24584 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24585 \begin_inset Text
24586
24587 \layout Standard
24588
24589 gpsim
24590 \begin_inset LatexCommand \index{gpsim (pic simulator)}
24591
24592 \end_inset
24593
24594
24595 \end_inset
24596 </cell>
24597 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24598 \begin_inset Text
24599
24600 \layout Standard
24601
24602 PIC simulator
24603 \end_inset
24604 </cell>
24605 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24606 \begin_inset Text
24607
24608 \layout Standard
24609
24610
24611 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
24612
24613 \end_inset
24614
24615
24616 \end_inset
24617 </cell>
24618 </row>
24619 <row topline="true">
24620 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24621 \begin_inset Text
24622
24623 \layout Standard
24624
24625 gputils
24626 \begin_inset LatexCommand \index{gputils (pic tools)}
24627
24628 \end_inset
24629
24630
24631 \end_inset
24632 </cell>
24633 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24634 \begin_inset Text
24635
24636 \layout Standard
24637
24638 GNU PIC utilities
24639 \end_inset
24640 </cell>
24641 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24642 \begin_inset Text
24643
24644 \layout Standard
24645
24646
24647 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
24648
24649 \end_inset
24650
24651
24652 \end_inset
24653 </cell>
24654 </row>
24655 <row topline="true">
24656 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24657 \begin_inset Text
24658
24659 \layout Standard
24660
24661 flP5
24662 \end_inset
24663 </cell>
24664 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24665 \begin_inset Text
24666
24667 \layout Standard
24668
24669 PIC programmer
24670 \end_inset
24671 </cell>
24672 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24673 \begin_inset Text
24674
24675 \layout Standard
24676
24677
24678 \begin_inset LatexCommand \url{http://freshmeat.net/projects/flp5/}
24679
24680 \end_inset
24681
24682
24683 \end_inset
24684 </cell>
24685 </row>
24686 <row topline="true">
24687 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24688 \begin_inset Text
24689
24690 \layout Standard
24691
24692 ec2drv/newcdb
24693 \end_inset
24694 </cell>
24695 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24696 \begin_inset Text
24697
24698 \layout Standard
24699
24700 Tools for Silicon Laboratories JTAG debug adapter, partly based on SDCDB
24701  (Unix only)
24702 \end_inset
24703 </cell>
24704 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24705 \begin_inset Text
24706
24707 \layout Standard
24708
24709
24710 \begin_inset LatexCommand \url{http://sourceforge.net/projects/ec2drv}
24711
24712 \end_inset
24713
24714
24715 \end_inset
24716 </cell>
24717 </row>
24718 <row topline="true">
24719 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24720 \begin_inset Text
24721
24722 \layout Standard
24723
24724 indent
24725 \begin_inset LatexCommand \index{indent (source formatting tool)}
24726
24727 \end_inset
24728
24729
24730 \end_inset
24731 </cell>
24732 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24733 \begin_inset Text
24734
24735 \layout Standard
24736
24737 Formats C source - Master of the white spaces
24738 \end_inset
24739 </cell>
24740 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24741 \begin_inset Text
24742
24743 \layout Standard
24744
24745
24746 \begin_inset LatexCommand \url{http://directory.fsf.org/GNU/indent.html}
24747
24748 \end_inset
24749
24750
24751 \end_inset
24752 </cell>
24753 </row>
24754 <row topline="true">
24755 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24756 \begin_inset Text
24757
24758 \layout Standard
24759
24760 srecord
24761 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
24762
24763 \end_inset
24764
24765
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 Object file conversion, checksumming, ...
24774 \end_inset
24775 </cell>
24776 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24777 \begin_inset Text
24778
24779 \layout Standard
24780
24781
24782 \begin_inset LatexCommand \url{http://sourceforge.net/projects/srecord}
24783
24784 \end_inset
24785
24786
24787 \end_inset
24788 </cell>
24789 </row>
24790 <row topline="true">
24791 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24792 \begin_inset Text
24793
24794 \layout Standard
24795
24796 objdump
24797 \begin_inset LatexCommand \index{objdump (tool)}
24798
24799 \end_inset
24800
24801
24802 \end_inset
24803 </cell>
24804 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24805 \begin_inset Text
24806
24807 \layout Standard
24808
24809 Object file conversion, ...
24810 \end_inset
24811 </cell>
24812 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24813 \begin_inset Text
24814
24815 \layout Standard
24816
24817 Part of binutils (should be there anyway)
24818 \end_inset
24819 </cell>
24820 </row>
24821 <row topline="true">
24822 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24823 \begin_inset Text
24824
24825 \layout Standard
24826
24827 cmon51
24828 \end_inset
24829 </cell>
24830 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24831 \begin_inset Text
24832
24833 \layout Standard
24834
24835 8051 monitor (hex up-/download, single step, disassemble)
24836 \end_inset
24837 </cell>
24838 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24839 \begin_inset Text
24840
24841 \layout Standard
24842
24843
24844 \begin_inset LatexCommand \url{http://sourceforge.net/projects/cmon51}
24845
24846 \end_inset
24847
24848
24849 \end_inset
24850 </cell>
24851 </row>
24852 <row topline="true">
24853 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24854 \begin_inset Text
24855
24856 \layout Standard
24857
24858 doxygen
24859 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
24860
24861 \end_inset
24862
24863
24864 \end_inset
24865 </cell>
24866 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24867 \begin_inset Text
24868
24869 \layout Standard
24870
24871 Source code documentation system
24872 \end_inset
24873 </cell>
24874 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24875 \begin_inset Text
24876
24877 \layout Standard
24878
24879
24880 \begin_inset LatexCommand \url{http://www.doxygen.org}
24881
24882 \end_inset
24883
24884
24885 \end_inset
24886 </cell>
24887 </row>
24888 <row topline="true">
24889 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24890 \begin_inset Text
24891
24892 \layout Standard
24893
24894 kdevelop
24895 \end_inset
24896 </cell>
24897 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24898 \begin_inset Text
24899
24900 \layout Standard
24901
24902 IDE (has anyone tried integrating SDCC & SDCDB? Unix only)
24903 \end_inset
24904 </cell>
24905 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24906 \begin_inset Text
24907
24908 \layout Standard
24909
24910
24911 \begin_inset LatexCommand \url{http://www.kdevelop.org}
24912
24913 \end_inset
24914
24915
24916 \end_inset
24917 </cell>
24918 </row>
24919 <row topline="true">
24920 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24921 \begin_inset Text
24922
24923 \layout Standard
24924
24925 paulmon
24926 \end_inset
24927 </cell>
24928 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24929 \begin_inset Text
24930
24931 \layout Standard
24932
24933 8051 monitor (hex up-/download, single step, disassemble)
24934 \end_inset
24935 </cell>
24936 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24937 \begin_inset Text
24938
24939 \layout Standard
24940
24941
24942 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/paulmon2.html}
24943
24944 \end_inset
24945
24946
24947 \end_inset
24948 </cell>
24949 </row>
24950 <row topline="true">
24951 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24952 \begin_inset Text
24953
24954 \layout Standard
24955
24956 splint
24957 \begin_inset LatexCommand \index{splint (syntax checking tool)}
24958
24959 \end_inset
24960
24961
24962 \end_inset
24963 </cell>
24964 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24965 \begin_inset Text
24966
24967 \layout Standard
24968
24969 Statically checks c sources (see
24970 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
24971
24972 \end_inset
24973
24974 )
24975 \end_inset
24976 </cell>
24977 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24978 \begin_inset Text
24979
24980 \layout Standard
24981
24982
24983 \begin_inset LatexCommand \url{http://www.splint.org}
24984
24985 \end_inset
24986
24987
24988 \end_inset
24989 </cell>
24990 </row>
24991 <row topline="true" bottomline="true">
24992 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24993 \begin_inset Text
24994
24995 \layout Standard
24996
24997 ddd
24998 \begin_inset LatexCommand \index{DDD (debugger)}
24999
25000 \end_inset
25001
25002
25003 \end_inset
25004 </cell>
25005 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25006 \begin_inset Text
25007
25008 \layout Standard
25009
25010 Debugger, serves nicely as GUI to SDCDB
25011 \begin_inset LatexCommand \index{SDCDB (debugger)}
25012
25013 \end_inset
25014
25015  (Unix only)
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
25024 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
25025
25026 \end_inset
25027
25028
25029 \end_inset
25030 </cell>
25031 </row>
25032 </lyxtabular>
25033
25034 \end_inset
25035
25036
25037 \newline
25038
25039 \layout Section
25040
25041 Related documentation / recommended reading
25042 \layout Standard
25043 \align left
25044
25045 \begin_inset  Tabular
25046 <lyxtabular version="3" rows="7" columns="3">
25047 <features>
25048 <column alignment="left" valignment="top" leftline="true" width="0pt">
25049 <column alignment="center" valignment="top" leftline="true" width="0">
25050 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
25051 <row topline="true" bottomline="true">
25052 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25053 \begin_inset Text
25054
25055 \layout Standard
25056
25057 Name
25058 \end_inset
25059 </cell>
25060 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25061 \begin_inset Text
25062
25063 \layout Standard
25064
25065 Subject / Title
25066 \end_inset
25067 </cell>
25068 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25069 \begin_inset Text
25070
25071 \layout Standard
25072
25073 Where to get
25074 \end_inset
25075 </cell>
25076 </row>
25077 <row topline="true">
25078 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25079 \begin_inset Text
25080
25081 \layout Standard
25082
25083
25084 \family roman
25085 \series medium
25086 \shape up
25087 \size normal
25088 \emph off
25089 \bar no
25090 \noun off
25091 \color none
25092 c-refcard.pdf
25093 \end_inset
25094 </cell>
25095 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25096 \begin_inset Text
25097
25098 \layout Standard
25099
25100 C Reference Card
25101 \begin_inset LatexCommand \index{C Reference card}
25102
25103 \end_inset
25104
25105 , 2 pages
25106 \end_inset
25107 </cell>
25108 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25109 \begin_inset Text
25110
25111 \layout Standard
25112
25113
25114 \begin_inset LatexCommand \url{http://refcards.com/refcards/c/index.html}
25115
25116 \end_inset
25117
25118
25119 \end_inset
25120 </cell>
25121 </row>
25122 <row topline="true">
25123 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25124 \begin_inset Text
25125
25126 \layout Standard
25127
25128 c-faq
25129 \end_inset
25130 </cell>
25131 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25132 \begin_inset Text
25133
25134 \layout Standard
25135
25136 C-FAQ
25137 \begin_inset LatexCommand \index{C FAQ}
25138
25139 \end_inset
25140
25141
25142 \end_inset
25143 </cell>
25144 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25145 \begin_inset Text
25146
25147 \layout Standard
25148
25149
25150 \begin_inset LatexCommand \url{http://www.c-faq.com}
25151
25152 \end_inset
25153
25154
25155 \end_inset
25156 </cell>
25157 </row>
25158 <row topline="true">
25159 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25160 \begin_inset Text
25161
25162 \layout Standard
25163
25164 ISO/IEC 9899:TC2
25165 \end_inset
25166 </cell>
25167 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25168 \begin_inset Text
25169
25170 \layout Standard
25171
25172
25173 \begin_inset Quotes sld
25174 \end_inset
25175
25176 C-Standard
25177 \begin_inset Quotes srd
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 \size footnotesize
25190
25191 \begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899}
25192
25193 \end_inset
25194
25195
25196 \end_inset
25197 </cell>
25198 </row>
25199 <row topline="true">
25200 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25201 \begin_inset Text
25202
25203 \layout Standard
25204
25205 ISO/IEC DTR 18037
25206 \end_inset
25207 </cell>
25208 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25209 \begin_inset Text
25210
25211 \layout Standard
25212
25213
25214 \begin_inset Quotes sld
25215 \end_inset
25216
25217 Extensions for Embedded C
25218 \begin_inset Quotes srd
25219 \end_inset
25220
25221
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 \size footnotesize
25231
25232 \begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1021.pdf}
25233
25234 \end_inset
25235
25236
25237 \end_inset
25238 </cell>
25239 </row>
25240 <row topline="true">
25241 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25242 \begin_inset Text
25243
25244 \layout Standard
25245
25246 \end_inset
25247 </cell>
25248 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25249 \begin_inset Text
25250
25251 \layout Standard
25252
25253 Latest datasheet of target CPU
25254 \end_inset
25255 </cell>
25256 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25257 \begin_inset Text
25258
25259 \layout Standard
25260
25261 vendor
25262 \end_inset
25263 </cell>
25264 </row>
25265 <row topline="true" bottomline="true">
25266 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25267 \begin_inset Text
25268
25269 \layout Standard
25270
25271 \end_inset
25272 </cell>
25273 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25274 \begin_inset Text
25275
25276 \layout Standard
25277
25278 Revision history of datasheet
25279 \end_inset
25280 </cell>
25281 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25282 \begin_inset Text
25283
25284 \layout Standard
25285
25286 vendor
25287 \end_inset
25288 </cell>
25289 </row>
25290 </lyxtabular>
25291
25292 \end_inset
25293
25294
25295 \newline
25296
25297 \layout Section
25298
25299 Application notes specifically for SDCC
25300 \layout Standard
25301
25302 SDCC makes no claims about the completeness of this list and about up-to-datenes
25303 s or correctness of the application notes
25304 \begin_inset LatexCommand \index{Application notes}
25305
25306 \end_inset
25307
25308 .
25309 \layout Standard
25310 \align left
25311
25312 \size footnotesize
25313
25314 \begin_inset  Tabular
25315 <lyxtabular version="3" rows="7" columns="3">
25316 <features>
25317 <column alignment="block" valignment="top" leftline="true" width="17col%">
25318 <column alignment="block" valignment="top" leftline="true" width="27col%">
25319 <column alignment="block" valignment="top" leftline="true" rightline="true" width="57col%">
25320 <row topline="true" bottomline="true">
25321 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25322 \begin_inset Text
25323
25324 \layout Standard
25325
25326
25327 \size footnotesize
25328 Vendor
25329 \end_inset
25330 </cell>
25331 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
25332 \begin_inset Text
25333
25334 \layout Standard
25335
25336
25337 \size footnotesize
25338 Subject / Title
25339 \end_inset
25340 </cell>
25341 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25342 \begin_inset Text
25343
25344 \layout Standard
25345
25346
25347 \size footnotesize
25348 Where to get
25349 \end_inset
25350 </cell>
25351 </row>
25352 <row topline="true">
25353 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25354 \begin_inset Text
25355
25356 \layout Standard
25357
25358
25359 \size footnotesize
25360 Maxim / Dallas
25361 \end_inset
25362 </cell>
25363 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25364 \begin_inset Text
25365
25366 \layout Standard
25367
25368
25369 \size footnotesize
25370 Using the SDCC Compiler for the DS80C400
25371 \begin_inset LatexCommand \index{DS80C400}
25372
25373 \end_inset
25374
25375
25376 \end_inset
25377 </cell>
25378 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25379 \begin_inset Text
25380
25381 \layout Standard
25382
25383
25384 \size footnotesize
25385
25386 \begin_inset LatexCommand \url{http://pdfserv.maxim-ic.com/en/an/AN3346.pdf}
25387
25388 \end_inset
25389
25390
25391 \end_inset
25392 </cell>
25393 </row>
25394 <row topline="true">
25395 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25396 \begin_inset Text
25397
25398 \layout Standard
25399
25400
25401 \size footnotesize
25402 Maxim / Dallas
25403 \end_inset
25404 </cell>
25405 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none" width="30line%">
25406 \begin_inset Text
25407
25408 \layout Standard
25409
25410
25411 \size footnotesize
25412 Using the Free SDCC C Compiler to Develop Firmware for the DS89C420/430/440/450
25413 \begin_inset LatexCommand \index{DS89C4x0}
25414
25415 \end_inset
25416
25417  Family of Microcontrollers
25418 \end_inset
25419 </cell>
25420 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25421 \begin_inset Text
25422
25423 \layout Standard
25424
25425
25426 \size footnotesize
25427
25428 \begin_inset LatexCommand \url{http://pdfserv.maxim-ic.com/en/an/AN3477.pdf}
25429
25430 \end_inset
25431
25432
25433 \end_inset
25434 </cell>
25435 </row>
25436 <row topline="true">
25437 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25438 \begin_inset Text
25439
25440 \layout Standard
25441
25442
25443 \size footnotesize
25444 Silicon Laboratories / Cygnal
25445 \end_inset
25446 </cell>
25447 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25448 \begin_inset Text
25449
25450 \layout Standard
25451
25452
25453 \size footnotesize
25454 Integrating SDCC 8051 Tools Into The Silicon Labs IDE
25455 \begin_inset LatexCommand \index{IDE}
25456
25457 \end_inset
25458
25459
25460 \end_inset
25461 </cell>
25462 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25463 \begin_inset Text
25464
25465 \layout Standard
25466
25467
25468 \size footnotesize
25469
25470 \begin_inset LatexCommand \url{http://www.silabs.com/public/documents/tpub_doc/anote/Microcontrollers/en/an198.pdf}
25471
25472 \end_inset
25473
25474
25475 \end_inset
25476 </cell>
25477 </row>
25478 <row topline="true">
25479 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25480 \begin_inset Text
25481
25482 \layout Standard
25483
25484
25485 \size footnotesize
25486 Ramtron / Goal Semiconductor
25487 \end_inset
25488 </cell>
25489 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25490 \begin_inset Text
25491
25492 \layout Standard
25493
25494
25495 \size footnotesize
25496 Interfacing SDCC to Syn and Textpad
25497 \end_inset
25498 </cell>
25499 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25500 \begin_inset Text
25501
25502 \layout Standard
25503
25504
25505 \size footnotesize
25506
25507 \begin_inset LatexCommand \url{http://www.ramtron.com/doc/Products/Microcontroller/Support_Tools.asp}
25508
25509 \end_inset
25510
25511
25512 \end_inset
25513 </cell>
25514 </row>
25515 <row topline="true">
25516 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25517 \begin_inset Text
25518
25519 \layout Standard
25520
25521
25522 \size footnotesize
25523 Ramtron / Goal Semiconductor
25524 \end_inset
25525 </cell>
25526 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25527 \begin_inset Text
25528
25529 \layout Standard
25530
25531
25532 \size footnotesize
25533 Installing and Configuring SDCC and Crimson Editor
25534 \end_inset
25535 </cell>
25536 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25537 \begin_inset Text
25538
25539 \layout Standard
25540
25541
25542 \size footnotesize
25543
25544 \begin_inset LatexCommand \url{http://www.ramtron.com/doc/Products/Microcontroller/Support_Tools.asp}
25545
25546 \end_inset
25547
25548
25549 \end_inset
25550 </cell>
25551 </row>
25552 <row topline="true" bottomline="true">
25553 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25554 \begin_inset Text
25555
25556 \layout Standard
25557
25558
25559 \size footnotesize
25560 Texas Instruments
25561 \end_inset
25562 </cell>
25563 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25564 \begin_inset Text
25565
25566 \layout Standard
25567
25568
25569 \size footnotesize
25570 MSC12xx Programming with SDCC
25571 \end_inset
25572 </cell>
25573 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25574 \begin_inset Text
25575
25576 \layout Standard
25577
25578
25579 \size footnotesize
25580
25581 \begin_inset LatexCommand \url{http://focus.ti.com/general/docs/lit/getliterature.tsp?literatureNumber=sbaa109&fileType=pdf}
25582
25583 \end_inset
25584
25585
25586 \end_inset
25587 </cell>
25588 </row>
25589 </lyxtabular>
25590
25591 \end_inset
25592
25593
25594 \layout Section
25595
25596 Some Questions
25597 \layout Standard
25598
25599 Some questions answered, some pointers given - it might be time to in turn
25600  ask
25601 \emph on
25602 you
25603 \emph default
25604  some questions:
25605 \layout Itemize
25606
25607 can you solve your project with the selected microcontroller? Would you
25608  find out early or rather late that your target is too small/slow/whatever?
25609  Can you switch to a slightly better device if it doesn't fit?
25610 \layout Itemize
25611
25612 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
25613  and/or another programming language be more adequate? Would an operating
25614  system on the target device help?
25615 \layout Itemize
25616
25617 if you solved the problem, will the marketing department be happy?
25618 \layout Itemize
25619
25620 if the marketing department is happy, will customers be happy?
25621 \layout Itemize
25622
25623 if you're the project manager, marketing department and maybe even the customer
25624  in one person, have you tried to see the project from the outside?
25625 \layout Itemize
25626
25627 is the project done if you think it is done? Or is just that other interface/pro
25628 tocol/feature/configuration/option missing? How about website, manual(s),
25629  internationali(z|s)ation, packaging, labels, 2nd source for components,
25630  electromagnetic compatability/interference, documentation for production,
25631  production test software, update mechanism, patent issues?
25632 \layout Itemize
25633
25634 is your project adequately positioned in that magic triangle: fame, fortune,
25635  fun?
25636 \layout Standard
25637
25638 Maybe not all answers to these questions are known and some answers may
25639  even be
25640 \emph on
25641 no
25642 \emph default
25643 , nevertheless knowing these questions may help you to avoid burnout
25644 \begin_inset Foot
25645 collapsed false
25646
25647 \layout Standard
25648
25649 burnout is bad for electronic devices, programmers and motorcycle tyres
25650 \end_inset
25651
25652 .
25653  Chances are you didn't want to hear some of them...
25654 \layout Chapter
25655
25656 Support
25657 \begin_inset LatexCommand \index{Support}
25658
25659 \end_inset
25660
25661
25662 \layout Standard
25663
25664 SDCC has grown to be a large project.
25665  The compiler alone (without the preprocessor, assembler and linker) is
25666  well over 150,000 lines of code (blank stripped).
25667  The open source nature of this project is a key to its continued growth
25668  and support.
25669  You gain the benefit and support of many active software developers and
25670  end users.
25671  Is SDCC perfect? No, that's why we need your help.
25672  The developers take pride in fixing reported bugs.
25673  You can help by reporting the bugs and helping other SDCC users.
25674  There are lots of ways to contribute, and we encourage you to take part
25675  in making SDCC a great software package.
25676
25677 \layout Standard
25678
25679 The SDCC project is hosted on the SDCC sourceforge site at
25680 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
25681
25682 \end_inset
25683
25684 .
25685  You'll find the complete set of mailing lists
25686 \begin_inset LatexCommand \index{Mailing list(s)}
25687
25688 \end_inset
25689
25690 , forums, bug reporting system, patch submission
25691 \begin_inset LatexCommand \index{Patch submission}
25692
25693 \end_inset
25694
25695  system, download
25696 \begin_inset LatexCommand \index{download}
25697
25698 \end_inset
25699
25700  area and Subversion code repository
25701 \begin_inset LatexCommand \index{Subversion code repository}
25702
25703 \end_inset
25704
25705  there.
25706 \layout Section
25707
25708 Reporting Bugs
25709 \begin_inset LatexCommand \index{Bug reporting}
25710
25711 \end_inset
25712
25713
25714 \begin_inset LatexCommand \index{Reporting bugs}
25715
25716 \end_inset
25717
25718
25719 \layout Standard
25720
25721 The recommended way of reporting bugs is using the infrastructure of the
25722  sourceforge site.
25723  You can follow the status of bug reports there and have an overview about
25724  the known bugs.
25725 \layout Standard
25726
25727 Bug reports are automatically forwarded to the developer mailing list and
25728  will be fixed ASAP.
25729  When reporting a bug, it is very useful to include a small test program
25730  (the smaller the better) which reproduces the problem.
25731  If you can isolate the problem by looking at the generated assembly code,
25732  this can be very helpful.
25733  Compiling your program with the -
25734 \begin_inset ERT
25735 status Collapsed
25736
25737 \layout Standard
25738
25739 \backslash
25740 /
25741 \end_inset
25742
25743 -dumpall
25744 \begin_inset LatexCommand \index{-\/-dumpall}
25745
25746 \end_inset
25747
25748  option can sometimes be useful in locating optimization problems.
25749  When reporting a bug please make sure you:
25750 \layout Enumerate
25751
25752 Attach the code you are compiling with SDCC.
25753
25754 \layout Enumerate
25755
25756 Specify the exact command you use to run SDCC, or attach your Makefile.
25757
25758 \layout Enumerate
25759
25760 Specify the SDCC version (type "
25761 \family sans
25762 \series bold
25763 sdcc -v
25764 \family default
25765 \series default
25766 "), your platform, and operating system.
25767
25768 \layout Enumerate
25769
25770 Provide an exact copy of any error message or incorrect output.
25771
25772 \layout Enumerate
25773
25774 Put something meaningful in the subject of your message.
25775 \layout Standard
25776
25777 Please attempt to include these 5 important parts, as applicable, in all
25778  requests for support or when reporting any problems or bugs with SDCC.
25779  Though this will make your message lengthy, it will greatly improve your
25780  chance that SDCC users and developers will be able to help you.
25781  Some SDCC developers are frustrated by bug reports without code provided
25782  that they can use to reproduce and ultimately fix the problem, so please
25783  be sure to provide sample code if you are reporting a bug!
25784 \layout Standard
25785
25786 Please have a short check that you are using a recent version of SDCC and
25787  the bug is not yet known.
25788  This is the link for reporting bugs:
25789 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
25790
25791 \end_inset
25792
25793 .
25794  With SDCC on average having more than 200 downloads
25795 \begin_inset LatexCommand \index{download}
25796
25797 \end_inset
25798
25799  on sourceforge per day
25800 \begin_inset Foot
25801 collapsed false
25802
25803 \layout Standard
25804
25805 220 daily downloads on average Jan-Sept 2006 and about 150 daily downloads
25806  between 2002 and 2005.
25807  This does not include other methods of distribution.
25808 \end_inset
25809
25810  there must be some users.
25811  So it's not exactly easy to find a new bug.
25812  If you find one we need it:
25813 \emph on
25814 reporting bugs is good
25815 \emph default
25816 .
25817 \layout Section
25818
25819 Requesting Features
25820 \begin_inset LatexCommand \label{sub:Requesting-Features}
25821
25822 \end_inset
25823
25824
25825 \begin_inset LatexCommand \index{Feature request}
25826
25827 \end_inset
25828
25829
25830 \begin_inset LatexCommand \index{Requesting features}
25831
25832 \end_inset
25833
25834
25835 \layout Standard
25836
25837 Like bug reports feature requests are forwarded to the developer mailing
25838  list.
25839  This is the link for requesting features:
25840 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
25841
25842 \end_inset
25843
25844 .
25845 \layout Section
25846
25847 Submitting patches
25848 \layout Standard
25849
25850 Like bug reports contributed patches are forwarded to the developer mailing
25851  list.
25852  This is the link for submitting patches
25853 \begin_inset LatexCommand \index{Patch submission}
25854
25855 \end_inset
25856
25857 :
25858 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
25859
25860 \end_inset
25861
25862 .
25863 \layout Standard
25864
25865 You need to specify some parameters to the
25866 \family typewriter
25867 diff
25868 \family default
25869  command for the patches to be useful.
25870  If you modified more than one file a patch created f.e.
25871  with
25872 \family sans
25873 \series bold
25874
25875 \begin_inset Quotes sld
25876 \end_inset
25877
25878 diff -Naur unmodified_directory modified_directory >my_changes.patch
25879 \begin_inset Quotes srd
25880 \end_inset
25881
25882
25883 \family default
25884 \series default
25885  will be fine, otherwise
25886 \family sans
25887 \series bold
25888
25889 \begin_inset Quotes sld
25890 \end_inset
25891
25892 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
25893 \begin_inset Quotes srd
25894 \end_inset
25895
25896
25897 \series default
25898
25899 \family default
25900 will do.
25901 \layout Section
25902
25903 Getting Help
25904 \layout Standard
25905
25906 These links should take you directly to the
25907 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
25908
25909 \end_inset
25910
25911
25912 \begin_inset Foot
25913 collapsed false
25914
25915 \layout Standard
25916
25917 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
25918  automated messages (mid 2003)
25919 \end_inset
25920
25921  and the
25922 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
25923
25924 \end_inset
25925
25926 , lists
25927 \begin_inset LatexCommand \index{Mailing list(s)}
25928
25929 \end_inset
25930
25931  and forums are archived and searchable so if you are lucky someone already
25932  had a similar problem.
25933  While mails to the lists themselves are delivered promptly their web front
25934  end on sourceforge sometimes shows a severe time lag (up to several weeks),
25935  if you're seriously using SDCC please consider subscribing to the lists.
25936 \layout Section
25937
25938 ChangeLog
25939 \layout Standard
25940
25941 You can follow the status of the Subversion version
25942 \begin_inset LatexCommand \index{version}
25943
25944 \end_inset
25945
25946  of SDCC by watching the Changelog
25947 \begin_inset LatexCommand \index{Changelog}
25948
25949 \end_inset
25950
25951  in the Subversion repository
25952 \size footnotesize
25953
25954 \begin_inset LatexCommand \htmlurl{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/ChangeLog}
25955
25956 \end_inset
25957
25958 .
25959 \layout Section
25960
25961 Subversion Source Code Repository
25962 \layout Standard
25963
25964 The output of
25965 \family sans
25966 \series bold
25967 sdcc --version
25968 \family default
25969 \series default
25970  or the filenames of the snapshot versions of SDCC include date and its
25971  Subversion
25972 \begin_inset LatexCommand \index{Subversion code repository}
25973
25974 \end_inset
25975
25976  number.
25977  Subversion allows to download the source of recent or previous versions
25978
25979 \begin_inset LatexCommand \url{http://sourceforge.net/svn/?group_id=599}
25980
25981 \end_inset
25982
25983  (by number or by date).
25984  An on-line source code browser and detailled instructions are also available
25985  there.
25986  SDCC versions starting from 1999 up to now are available (currently the
25987  versions prior to the conversion from cvs
25988 \begin_inset LatexCommand \index{cvs|see{Subversion}}
25989
25990 \end_inset
25991
25992  to Subversion (April 2006) are either by accessible by Subversion or by
25993  cvs).
25994 \layout Section
25995
25996 Release policy
25997 \begin_inset LatexCommand \index{Release policy}
25998
25999 \end_inset
26000
26001
26002 \layout Standard
26003
26004 Historically there often were long delays between official releases and
26005  the sourceforge download area tends to get not updated at all.
26006  Excuses in the past might have referred to problems with live range analysis,
26007  but as this was fixed a while ago, the current problem is that another
26008  excuse has to be found.
26009  Kidding aside, we have to get better there! On the other hand there are
26010  daily snapshots available at
26011 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
26012
26013 \end_inset
26014
26015 , and you can always build the very last version (hopefully with many bugs
26016  fixed, and features added) from the source code available at
26017 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
26018
26019 \end_inset
26020
26021 .
26022  A release wiki
26023 \begin_inset LatexCommand \index{wiki}
26024
26025 \end_inset
26026
26027
26028 \begin_inset LatexCommand \index{Release wiki}
26029
26030 \end_inset
26031
26032  at
26033 \begin_inset LatexCommand \url{http://sdcc.sf.net/release_wiki/}
26034
26035 \end_inset
26036
26037  also holds some information about past and future releases.
26038 \layout Section
26039
26040 Examples
26041 \begin_inset LatexCommand \index{Examples}
26042
26043 \end_inset
26044
26045
26046 \layout Standard
26047
26048 You'll find some small examples in the directory
26049 \emph on
26050 sdcc/device/examples/.
26051
26052 \emph default
26053 More examples and libraries are available at
26054 \emph on
26055  The SDCC Open Knowledge Resource
26056 \begin_inset LatexCommand \url{http://sdccokr.dl9sec.de/}
26057
26058 \end_inset
26059
26060
26061 \emph default
26062 web site or at
26063 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
26064
26065 \end_inset
26066
26067 .
26068 \layout Comment
26069
26070 I did insert a reference to Paul's web site here although it seems rather
26071  dedicated to a specific 8032 board (I think it's okay because it f.e.
26072  shows LCD/Harddisc interface and has a free 8051 monitor.
26073  Independent 8032 board vendors face hard competition of heavily subsidized
26074  development boards anyway).
26075 \layout Comment
26076
26077 Maybe we should include some links to real world applications.
26078  Preferably pointer to pointers (one for each architecture) so this stays
26079  manageable here?
26080 \layout Section
26081
26082 Quality control
26083 \begin_inset LatexCommand \label{sec:Quality-control}
26084
26085 \end_inset
26086
26087
26088 \begin_inset LatexCommand \index{Quality control}
26089
26090 \end_inset
26091
26092
26093 \layout Standard
26094
26095 The compiler is passed through nightly compile and build checks.
26096  The so called
26097 \shape italic
26098 regression tests
26099 \shape default
26100
26101 \begin_inset LatexCommand \index{Regression test}
26102
26103 \end_inset
26104
26105  check that SDCC itself compiles flawlessly on several host platforms (i386,
26106  Opteron, 64 bit Alpha, ppc64, MacOS X on PPC, Solaris on Sparc) and checks
26107  the quality of the code generated by SDCC by running the code for several
26108  target platforms through simulators.
26109  The regression test suite comprises more than 100 files which expand to
26110  more than 500 test cases which include more than 4500 tests.
26111  The results of these tests are published daily on SDCC's snapshot page
26112  (click on the red or green symbols on the right side of
26113 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
26114
26115 \end_inset
26116
26117 ).
26118 \layout Standard
26119
26120 There is a separate document
26121 \shape italic
26122 test_suite.pdf
26123 \begin_inset LatexCommand \index{Test suite}
26124
26125 \end_inset
26126
26127
26128 \shape default
26129
26130 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/test_suite_spec.pdf}
26131
26132 \end_inset
26133
26134  about the regression test suite.
26135 \layout Standard
26136
26137 You'll find the test code in the directory
26138 \shape italic
26139 sdcc/support/regression
26140 \shape default
26141 .
26142  You can run these tests manually by running
26143 \family sans
26144 make
26145 \family default
26146  in this directory (or f.e.
26147
26148 \family sans
26149 \series bold
26150
26151 \begin_inset Quotes sld
26152 \end_inset
26153
26154 make test-mcs51
26155 \begin_inset Quotes srd
26156 \end_inset
26157
26158
26159 \family default
26160 \series default
26161  if you don't want to run the complete tests).
26162  The test code might also be interesting if you want to look for examples
26163 \begin_inset LatexCommand \index{Examples}
26164
26165 \end_inset
26166
26167  checking corner cases of SDCC or if you plan to submit patches
26168 \begin_inset LatexCommand \index{Patch submission}
26169
26170 \end_inset
26171
26172 .
26173 \layout Standard
26174
26175 The 14bit pic port uses a different set of regression tests
26176 \begin_inset LatexCommand \index{Regression test (PIC14)}
26177
26178 \end_inset
26179
26180 , you'll find them in the directory
26181 \shape italic
26182 sdcc/src/regression
26183 \shape default
26184 .
26185 \layout Section
26186
26187 Use of SDCC in Education
26188 \layout Standard
26189
26190 In short:
26191 \emph on
26192 highly
26193 \emph default
26194  encouraged
26195 \begin_inset Foot
26196 collapsed false
26197
26198 \layout Standard
26199
26200 the phrase "use in education" might evoke the association "
26201 \emph on
26202 only
26203 \emph default
26204  fit for use in education".
26205  This connotation is not intended but nevertheless risked as the licensing
26206  of SDCC makes it difficult to offer educational discounts
26207 \end_inset
26208
26209 .
26210  If your rationales are to:
26211 \layout Enumerate
26212
26213 give students a chance to understand the
26214 \emph on
26215 complete
26216 \emph default
26217  steps of code generation
26218 \layout Enumerate
26219
26220 have a curriculum that can be extended for years.
26221  Then you could use an fpga board as target and your curriculum will seamlessly
26222  extend from logic synthesis (
26223 \begin_inset LatexCommand \url[http://www.opencores.org]{opencores.org}
26224
26225 \end_inset
26226
26227 ,
26228 \begin_inset LatexCommand \url[Oregano]{http://www.oregano.at/ip/ip01.htm}
26229
26230 \end_inset
26231
26232 ), over assembly programming, to C to FPGA compilers (
26233 \begin_inset LatexCommand \url[FPGAC]{http://sf.net/projects/fpgac}
26234
26235 \end_inset
26236
26237 ) and to C.
26238 \layout Enumerate
26239
26240 be able to insert excursions about skills like using a revision control
26241  system, submitting/applying patches, using a type-setting (as opposed to
26242  word-processing) engine LyX/LaTeX, using
26243 \begin_inset LatexCommand \url[SourceForge]{http://www.sf.net}
26244
26245 \end_inset
26246
26247 , following some
26248 \begin_inset LatexCommand \url[netiquette]{http://en.wikipedia.org/wiki/Netiquette}
26249
26250 \end_inset
26251
26252 , understanding BSD/LGPL/GPL/Proprietary licensing, growth models of Open
26253  Source Software, CPU simulation, compiler regression tests
26254 \begin_inset LatexCommand \index{Regression test}
26255
26256 \end_inset
26257
26258 .
26259
26260 \newline
26261 And if there should be a shortage of ideas then you can always point students
26262  to the ever-growing feature request list
26263 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
26264
26265 \end_inset
26266
26267 .
26268 \layout Enumerate
26269
26270 not tie students to a specific host platform and instead allow them to use
26271  a host platform of
26272 \emph on
26273 their
26274 \emph default
26275  choice (among them Alpha, i386, i386_64, MacOs, Mips, Sparc, Windows and
26276  eventually
26277 \begin_inset LatexCommand \url[OLPC]{http://www.laptop.org}
26278
26279 \end_inset
26280
26281 )
26282 \layout Enumerate
26283
26284 not encourage students to use illegal copies of educational software
26285 \layout Enumerate
26286
26287 be immune to licensing/availability/price changes of the chosen tool chain
26288 \layout Enumerate
26289
26290 be able to change to a new target platform without having to adopt a new
26291  tool chain
26292 \layout Enumerate
26293
26294 have complete control over and insight into the tool chain
26295 \layout Enumerate
26296
26297 make your students aware about the pros and cons of open source software
26298  development
26299 \layout Enumerate
26300
26301 give back to the public as you are probably at least partially publically
26302  funded
26303 \layout Enumerate
26304
26305 give students a chance to publically prove their skills and to possibly
26306  see a world wide impact
26307 \layout Standard
26308
26309 then SDCC is probably among the first choices.
26310  Well, probably SDCC might be the only choice.
26311 \layout Chapter
26312 \pagebreak_top
26313 SDCC Technical Data
26314 \layout Section
26315
26316 Optimizations
26317 \begin_inset LatexCommand \index{Optimizations}
26318
26319 \end_inset
26320
26321
26322 \layout Standard
26323
26324 SDCC performs a host of standard optimizations in addition to some MCU specific
26325  optimizations.
26326
26327 \layout Subsection
26328
26329 Sub-expression Elimination
26330 \begin_inset LatexCommand \index{Subexpression elimination}
26331
26332 \end_inset
26333
26334
26335 \layout Standard
26336
26337 The compiler does local and
26338 \emph on
26339 g
26340 \emph default
26341 lobal
26342 \emph on
26343 c
26344 \emph default
26345 ommon
26346 \emph on
26347 s
26348 \emph default
26349 ubexpression
26350 \emph on
26351 e
26352 \emph default
26353 limination, e.g.:
26354 \layout Verse
26355
26356
26357 \family typewriter
26358 i = x + y + 1;
26359 \newline
26360 j = x + y;
26361 \layout Standard
26362
26363 will be translated to
26364 \layout Verse
26365
26366
26367 \family typewriter
26368 iTemp = x + y;
26369 \newline
26370 i = iTemp + 1;
26371 \newline
26372 j = iTemp;
26373 \layout Standard
26374
26375 Some subexpressions are not as obvious as the above example, e.g.:
26376 \layout Verse
26377
26378
26379 \family typewriter
26380 a->b[i].c = 10;
26381 \newline
26382 a->b[i].d = 11;
26383 \layout Standard
26384
26385 In this case the address arithmetic a->b[i] will be computed only once;
26386  the equivalent code in C would be.
26387 \layout Verse
26388
26389
26390 \family typewriter
26391 iTemp = a->b[i];
26392 \newline
26393 iTemp.c = 10;
26394 \newline
26395 iTemp.d = 11;
26396 \layout Standard
26397
26398 The compiler will try to keep these temporary variables in registers.
26399 \layout Subsection
26400
26401 Dead-Code Elimination
26402 \begin_inset LatexCommand \index{Dead-code elimination}
26403
26404 \end_inset
26405
26406
26407 \layout Verse
26408
26409
26410 \family typewriter
26411 int global;
26412 \newline
26413
26414 \newline
26415 void f () {
26416 \newline
26417 \SpecialChar ~
26418 \SpecialChar ~
26419 int i;
26420 \newline
26421 \SpecialChar ~
26422 \SpecialChar ~
26423 i = 1; \SpecialChar ~
26424 \SpecialChar ~
26425 \SpecialChar ~
26426 \SpecialChar ~
26427 \SpecialChar ~
26428 /* dead store */
26429 \newline
26430 \SpecialChar ~
26431 \SpecialChar ~
26432 global = 1;\SpecialChar ~
26433 /* dead store */
26434 \newline
26435 \SpecialChar ~
26436 \SpecialChar ~
26437 global = 2;
26438 \newline
26439 \SpecialChar ~
26440 \SpecialChar ~
26441 return;
26442 \newline
26443 \SpecialChar ~
26444 \SpecialChar ~
26445 global = 3;\SpecialChar ~
26446 /* unreachable */
26447 \newline
26448 }
26449 \layout Standard
26450
26451 will be changed to
26452 \layout Verse
26453
26454
26455 \family typewriter
26456 int global;
26457 \newline
26458
26459 \newline
26460 void f () {
26461 \newline
26462 \SpecialChar ~
26463 \SpecialChar ~
26464 global = 2;
26465 \newline
26466 }
26467 \layout Subsection
26468
26469 Copy-Propagation
26470 \begin_inset LatexCommand \index{Copy propagation}
26471
26472 \end_inset
26473
26474
26475 \layout Verse
26476
26477
26478 \family typewriter
26479 int f() {
26480 \newline
26481 \SpecialChar ~
26482 \SpecialChar ~
26483 int i, j;
26484 \newline
26485 \SpecialChar ~
26486 \SpecialChar ~
26487 i = 10;
26488 \newline
26489 \SpecialChar ~
26490 \SpecialChar ~
26491 j = i;
26492 \newline
26493 \SpecialChar ~
26494 \SpecialChar ~
26495 return j;
26496 \newline
26497 }
26498 \layout Standard
26499
26500 will be changed to
26501 \layout Verse
26502
26503
26504 \family typewriter
26505 int f() {
26506 \newline
26507 \SpecialChar ~
26508 \SpecialChar ~
26509 int i, j;
26510 \newline
26511 \SpecialChar ~
26512 \SpecialChar ~
26513 i = 10;
26514 \newline
26515 \SpecialChar ~
26516 \SpecialChar ~
26517 j = 10;
26518 \newline
26519 \SpecialChar ~
26520 \SpecialChar ~
26521 return 10;
26522 \newline
26523 }
26524 \layout Standard
26525
26526 Note: the dead stores created by this copy propagation will be eliminated
26527  by dead-code elimination.
26528 \layout Subsection
26529
26530 Loop Optimizations
26531 \begin_inset LatexCommand \index{Loop optimization}
26532
26533 \end_inset
26534
26535
26536 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
26537
26538 \end_inset
26539
26540
26541 \layout Standard
26542
26543 Two types of loop optimizations are done by SDCC
26544 \emph on
26545 loop invariant
26546 \emph default
26547  lifting and
26548 \emph on
26549  strength reduction
26550 \emph default
26551  of loop induction variables.
26552  In addition to the strength reduction the optimizer marks the induction
26553  variables and the register allocator tries to keep the induction variables
26554  in registers for the duration of the loop.
26555  Because of this preference of the register allocator
26556 \begin_inset LatexCommand \index{Register allocation}
26557
26558 \end_inset
26559
26560 , loop induction optimization causes an increase in register pressure, which
26561  may cause unwanted spilling of other temporary variables into the stack
26562 \begin_inset LatexCommand \index{stack}
26563
26564 \end_inset
26565
26566  / data space.
26567  The compiler will generate a warning message when it is forced to allocate
26568  extra space either on the stack or data space.
26569  If this extra space allocation is undesirable then induction optimization
26570  can be eliminated either for the entire source file (with -
26571 \begin_inset ERT
26572 status Collapsed
26573
26574 \layout Standard
26575
26576 \backslash
26577 /
26578 \end_inset
26579
26580 -noinduction option) or for a given function only using #pragma\SpecialChar ~
26581 noinduction
26582 \begin_inset LatexCommand \index{\#pragma noinduction}
26583
26584 \end_inset
26585
26586 .
26587 \newline
26588
26589 \newline
26590 Loop Invariant:
26591 \layout Verse
26592
26593
26594 \family typewriter
26595 for (i = 0 ; i < 100 ; i ++)
26596 \newline
26597 \SpecialChar ~
26598 \SpecialChar ~
26599 \SpecialChar ~
26600 \SpecialChar ~
26601 f += k + l;
26602 \layout Standard
26603
26604 changed to
26605 \layout Verse
26606
26607
26608 \family typewriter
26609 itemp = k + l;
26610 \newline
26611 for (i = 0; i < 100; i++)
26612 \newline
26613 \SpecialChar ~
26614 \SpecialChar ~
26615 \SpecialChar ~
26616 \SpecialChar ~
26617 f += itemp;
26618 \layout Standard
26619
26620 As mentioned previously some loop invariants are not as apparent, all static
26621  address computations are also moved out of the loop.
26622 \newline
26623
26624 \newline
26625 Strength Reduction
26626 \begin_inset LatexCommand \index{Strength reduction}
26627
26628 \end_inset
26629
26630 , this optimization substitutes an expression by a cheaper expression:
26631 \layout Verse
26632
26633
26634 \family typewriter
26635 for (i=0;i < 100; i++)
26636 \newline
26637 \SpecialChar ~
26638 \SpecialChar ~
26639 \SpecialChar ~
26640 \SpecialChar ~
26641 ar[i*5] = i*3;
26642 \layout Standard
26643
26644 changed to
26645 \layout Verse
26646
26647
26648 \family typewriter
26649 itemp1 = 0;
26650 \newline
26651 itemp2 = 0;
26652 \newline
26653 for (i=0;i< 100;i++) {
26654 \newline
26655 \SpecialChar ~
26656 \SpecialChar ~
26657 \SpecialChar ~
26658 \SpecialChar ~
26659 ar[itemp1] = itemp2;
26660 \newline
26661 \SpecialChar ~
26662 \SpecialChar ~
26663 \SpecialChar ~
26664 \SpecialChar ~
26665 itemp1 += 5;
26666 \newline
26667 \SpecialChar ~
26668 \SpecialChar ~
26669 \SpecialChar ~
26670 \SpecialChar ~
26671 itemp2 += 3;
26672 \newline
26673 }
26674 \layout Standard
26675
26676 The more expensive multiplication
26677 \begin_inset LatexCommand \index{Multiplication}
26678
26679 \end_inset
26680
26681  is changed to a less expensive addition.
26682 \layout Subsection
26683
26684 Loop Reversing
26685 \begin_inset LatexCommand \index{Loop reversing}
26686
26687 \end_inset
26688
26689
26690 \layout Standard
26691
26692 This optimization is done to reduce the overhead of checking loop boundaries
26693  for every iteration.
26694  Some simple loops can be reversed and implemented using a
26695 \begin_inset Quotes eld
26696 \end_inset
26697
26698 decrement and jump if not zero
26699 \begin_inset Quotes erd
26700 \end_inset
26701
26702  instruction.
26703  SDCC checks for the following criterion to determine if a loop is reversible
26704  (note: more sophisticated compilers use data-dependency analysis to make
26705  this determination, SDCC uses a more simple minded analysis).
26706 \layout Itemize
26707
26708 The 'for' loop is of the form
26709 \newline
26710
26711 \newline
26712
26713 \family typewriter
26714 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
26715  += 1])
26716 \newline
26717 \SpecialChar ~
26718 \SpecialChar ~
26719 \SpecialChar ~
26720 \SpecialChar ~
26721 <for body>
26722 \layout Itemize
26723
26724 The <for body> does not contain
26725 \begin_inset Quotes eld
26726 \end_inset
26727
26728 continue
26729 \begin_inset Quotes erd
26730 \end_inset
26731
26732  or 'break
26733 \begin_inset Quotes erd
26734 \end_inset
26735
26736 .
26737 \layout Itemize
26738
26739 All goto's are contained within the loop.
26740 \layout Itemize
26741
26742 No function calls within the loop.
26743 \layout Itemize
26744
26745 The loop control variable <sym> is not assigned any value within the loop
26746 \layout Itemize
26747
26748 The loop control variable does NOT participate in any arithmetic operation
26749  within the loop.
26750 \layout Itemize
26751
26752 There are NO switch statements in the loop.
26753 \layout Subsection
26754
26755 Algebraic Simplifications
26756 \layout Standard
26757
26758 SDCC does numerous algebraic simplifications, the following is a small sub-set
26759  of these optimizations.
26760 \layout Verse
26761
26762
26763 \family typewriter
26764 i = j + 0;\SpecialChar ~
26765 \SpecialChar ~
26766 \SpecialChar ~
26767 \SpecialChar ~
26768  /* changed to: */\SpecialChar ~
26769 \SpecialChar ~
26770 \SpecialChar ~
26771 \SpecialChar ~
26772  i = j;
26773 \newline
26774 i /= 2;\SpecialChar ~
26775 \SpecialChar ~
26776 \SpecialChar ~
26777 \SpecialChar ~
26778 \SpecialChar ~
26779 \SpecialChar ~
26780 \SpecialChar ~
26781  /* changed to: */\SpecialChar ~
26782 \SpecialChar ~
26783 \SpecialChar ~
26784 \SpecialChar ~
26785  i >>= 1;
26786 \newline
26787 i = j - j;\SpecialChar ~
26788 \SpecialChar ~
26789 \SpecialChar ~
26790 \SpecialChar ~
26791  /* changed to: */\SpecialChar ~
26792 \SpecialChar ~
26793 \SpecialChar ~
26794 \SpecialChar ~
26795  i = 0;
26796 \newline
26797 i = j / 1;\SpecialChar ~
26798 \SpecialChar ~
26799 \SpecialChar ~
26800 \SpecialChar ~
26801  /* changed to: */\SpecialChar ~
26802 \SpecialChar ~
26803 \SpecialChar ~
26804 \SpecialChar ~
26805  i = j;
26806 \layout Standard
26807
26808 Note the subexpressions
26809 \begin_inset LatexCommand \index{Subexpression}
26810
26811 \end_inset
26812
26813  given above are generally introduced by macro expansions or as a result
26814  of copy/constant propagation.
26815 \layout Subsection
26816
26817 'switch' Statements
26818 \begin_inset LatexCommand \label{sub:'switch'-Statements}
26819
26820 \end_inset
26821
26822
26823 \begin_inset LatexCommand \index{switch statement}
26824
26825 \end_inset
26826
26827
26828 \layout Standard
26829
26830 SDCC can optimize switch statements to jump tables
26831 \begin_inset LatexCommand \index{jump tables}
26832
26833 \end_inset
26834
26835 .
26836  It makes the decision based on an estimate of the generated code size.
26837  SDCC is quite liberal in the requirements for jump table generation:
26838 \layout Itemize
26839
26840 The labels need not be in order, and the starting number need not be one
26841  or zero, the case labels are in numerical sequence or not too many case
26842  labels are missing.
26843 \begin_deeper
26844 \layout Verse
26845
26846
26847 \family typewriter
26848 switch(i) {\SpecialChar ~
26849 \SpecialChar ~
26850 \SpecialChar ~
26851 \SpecialChar ~
26852 \SpecialChar ~
26853 \SpecialChar ~
26854 \SpecialChar ~
26855 \SpecialChar ~
26856 \SpecialChar ~
26857 \SpecialChar ~
26858 \SpecialChar ~
26859 \SpecialChar ~
26860 \SpecialChar ~
26861 \SpecialChar ~
26862 \SpecialChar ~
26863 \SpecialChar ~
26864 \SpecialChar ~
26865 \SpecialChar ~
26866 \SpecialChar ~
26867 \SpecialChar ~
26868 \SpecialChar ~
26869 \SpecialChar ~
26870 \SpecialChar ~
26871 \SpecialChar ~
26872 \SpecialChar ~
26873 \SpecialChar ~
26874 switch (i) {
26875 \newline
26876 \SpecialChar ~
26877 \SpecialChar ~
26878 \SpecialChar ~
26879 case 4: ...\SpecialChar ~
26880 \SpecialChar ~
26881 \SpecialChar ~
26882 \SpecialChar ~
26883 \SpecialChar ~
26884 \SpecialChar ~
26885 \SpecialChar ~
26886 \SpecialChar ~
26887 \SpecialChar ~
26888 \SpecialChar ~
26889 \SpecialChar ~
26890 \SpecialChar ~
26891 \SpecialChar ~
26892 \SpecialChar ~
26893 \SpecialChar ~
26894 \SpecialChar ~
26895 \SpecialChar ~
26896 \SpecialChar ~
26897 \SpecialChar ~
26898 \SpecialChar ~
26899 \SpecialChar ~
26900 \SpecialChar ~
26901 \SpecialChar ~
26902 \SpecialChar ~
26903 \SpecialChar ~
26904 \SpecialChar ~
26905 case 0: ...
26906
26907 \newline
26908 \SpecialChar ~
26909 \SpecialChar ~
26910 \SpecialChar ~
26911 case 5: ...\SpecialChar ~
26912 \SpecialChar ~
26913 \SpecialChar ~
26914 \SpecialChar ~
26915 \SpecialChar ~
26916 \SpecialChar ~
26917 \SpecialChar ~
26918 \SpecialChar ~
26919 \SpecialChar ~
26920 \SpecialChar ~
26921 \SpecialChar ~
26922 \SpecialChar ~
26923 \SpecialChar ~
26924 \SpecialChar ~
26925 \SpecialChar ~
26926 \SpecialChar ~
26927 \SpecialChar ~
26928 \SpecialChar ~
26929 \SpecialChar ~
26930 \SpecialChar ~
26931 \SpecialChar ~
26932 \SpecialChar ~
26933 \SpecialChar ~
26934 \SpecialChar ~
26935 \SpecialChar ~
26936 \SpecialChar ~
26937 case 1: ...
26938
26939 \newline
26940 \SpecialChar ~
26941 \SpecialChar ~
26942 \SpecialChar ~
26943 case 3: ...\SpecialChar ~
26944 \SpecialChar ~
26945 \SpecialChar ~
26946 \SpecialChar ~
26947 \SpecialChar ~
26948 \SpecialChar ~
26949 \SpecialChar ~
26950 \SpecialChar ~
26951 \SpecialChar ~
26952 \SpecialChar ~
26953 \SpecialChar ~
26954 \SpecialChar ~
26955 \SpecialChar ~
26956 \SpecialChar ~
26957 \SpecialChar ~
26958 \SpecialChar ~
26959 \SpecialChar ~
26960 \SpecialChar ~
26961 \SpecialChar ~
26962 \SpecialChar ~
26963 \SpecialChar ~
26964 \SpecialChar ~
26965 \SpecialChar ~
26966 \SpecialChar ~
26967 \SpecialChar ~
26968 \SpecialChar ~
26969
26970 \newline
26971 \SpecialChar ~
26972 \SpecialChar ~
26973 \SpecialChar ~
26974 case 6: ...\SpecialChar ~
26975 \SpecialChar ~
26976 \SpecialChar ~
26977 \SpecialChar ~
26978 \SpecialChar ~
26979 \SpecialChar ~
26980 \SpecialChar ~
26981 \SpecialChar ~
26982 \SpecialChar ~
26983 \SpecialChar ~
26984 \SpecialChar ~
26985 \SpecialChar ~
26986 \SpecialChar ~
26987 \SpecialChar ~
26988 \SpecialChar ~
26989 \SpecialChar ~
26990 \SpecialChar ~
26991 \SpecialChar ~
26992 \SpecialChar ~
26993 \SpecialChar ~
26994 \SpecialChar ~
26995 \SpecialChar ~
26996 \SpecialChar ~
26997 \SpecialChar ~
26998 \SpecialChar ~
26999 \SpecialChar ~
27000 case 3: ...
27001
27002 \newline
27003 \SpecialChar ~
27004 \SpecialChar ~
27005 \SpecialChar ~
27006 case 7: ...\SpecialChar ~
27007 \SpecialChar ~
27008 \SpecialChar ~
27009 \SpecialChar ~
27010 \SpecialChar ~
27011 \SpecialChar ~
27012 \SpecialChar ~
27013 \SpecialChar ~
27014 \SpecialChar ~
27015 \SpecialChar ~
27016 \SpecialChar ~
27017 \SpecialChar ~
27018 \SpecialChar ~
27019 \SpecialChar ~
27020 \SpecialChar ~
27021 \SpecialChar ~
27022 \SpecialChar ~
27023 \SpecialChar ~
27024 \SpecialChar ~
27025 \SpecialChar ~
27026 \SpecialChar ~
27027 \SpecialChar ~
27028 \SpecialChar ~
27029 \SpecialChar ~
27030 \SpecialChar ~
27031 \SpecialChar ~
27032 case 4: ...
27033
27034 \newline
27035 \SpecialChar ~
27036 \SpecialChar ~
27037 \SpecialChar ~
27038 case 8: ...\SpecialChar ~
27039 \SpecialChar ~
27040 \SpecialChar ~
27041 \SpecialChar ~
27042 \SpecialChar ~
27043 \SpecialChar ~
27044 \SpecialChar ~
27045 \SpecialChar ~
27046 \SpecialChar ~
27047 \SpecialChar ~
27048 \SpecialChar ~
27049 \SpecialChar ~
27050 \SpecialChar ~
27051 \SpecialChar ~
27052 \SpecialChar ~
27053 \SpecialChar ~
27054 \SpecialChar ~
27055 \SpecialChar ~
27056 \SpecialChar ~
27057 \SpecialChar ~
27058 \SpecialChar ~
27059 \SpecialChar ~
27060 \SpecialChar ~
27061 \SpecialChar ~
27062 \SpecialChar ~
27063 \SpecialChar ~
27064 case 5: ...
27065
27066 \newline
27067 \SpecialChar ~
27068 \SpecialChar ~
27069 \SpecialChar ~
27070 case 9: ...\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 \SpecialChar ~
27090 \SpecialChar ~
27091 \SpecialChar ~
27092 \SpecialChar ~
27093 \SpecialChar ~
27094 \SpecialChar ~
27095 \SpecialChar ~
27096 case 6: ...
27097
27098 \newline
27099 \SpecialChar ~
27100 \SpecialChar ~
27101 \SpecialChar ~
27102 case 10: ...\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 \SpecialChar ~
27121 \SpecialChar ~
27122 \SpecialChar ~
27123 \SpecialChar ~
27124 \SpecialChar ~
27125 \SpecialChar ~
27126 \SpecialChar ~
27127 case 7: ...
27128
27129 \newline
27130 \SpecialChar ~
27131 \SpecialChar ~
27132 \SpecialChar ~
27133 case 11: ...\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 \SpecialChar ~
27153 \SpecialChar ~
27154 \SpecialChar ~
27155 \SpecialChar ~
27156 \SpecialChar ~
27157 \SpecialChar ~
27158 case 8: ...
27159
27160 \newline
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 \SpecialChar ~
27185 \SpecialChar ~
27186 \SpecialChar ~
27187 \SpecialChar ~
27188 \SpecialChar ~
27189 \SpecialChar ~
27190 \SpecialChar ~
27191 \SpecialChar ~
27192 \SpecialChar ~
27193 \SpecialChar ~
27194 \SpecialChar ~
27195 \SpecialChar ~
27196 \SpecialChar ~
27197 }
27198 \layout Standard
27199
27200 Both the above switch statements will be implemented using a jump-table.
27201  The example to the right side is slightly more efficient as the check for
27202  the lower boundary of the jump-table is not needed.
27203 \end_deeper
27204 \layout Itemize
27205
27206 The number of case labels is not larger than supported by the target architectur
27207 e.
27208 \layout Itemize
27209
27210 If the case labels are not in numerical sequence ('gaps' between cases)
27211  SDCC checks whether a jump table with additionally inserted dummy cases
27212  is still attractive.
27213
27214 \layout Itemize
27215
27216 If the starting number is not zero and a check for the lower boundary of
27217  the jump-table can thus be eliminated SDCC might insert dummy cases 0,
27218  ...
27219  .
27220 \layout Standard
27221
27222 Switch statements which have large gaps in the numeric sequence or those
27223  that have too many case labels can be split into more than one switch statement
27224  for efficient code generation, e.g.:
27225 \layout Verse
27226
27227
27228 \family typewriter
27229 switch (i) {
27230 \newline
27231 \SpecialChar ~
27232 \SpecialChar ~
27233 case 1: ...
27234
27235 \newline
27236 \SpecialChar ~
27237 \SpecialChar ~
27238 case 2: ...
27239
27240 \newline
27241 \SpecialChar ~
27242 \SpecialChar ~
27243 case 3: ...
27244
27245 \newline
27246 \SpecialChar ~
27247 \SpecialChar ~
27248 case 4: ...
27249
27250 \newline
27251 \SpecialChar ~
27252 \SpecialChar ~
27253 case 5: ...
27254
27255 \newline
27256 \SpecialChar ~
27257 \SpecialChar ~
27258 case 6: ...
27259
27260 \newline
27261 \SpecialChar ~
27262 \SpecialChar ~
27263 case 7: ...
27264
27265 \newline
27266 \SpecialChar ~
27267 \SpecialChar ~
27268 case 101: ...
27269
27270 \newline
27271 \SpecialChar ~
27272 \SpecialChar ~
27273 case 102: ...
27274
27275 \newline
27276 \SpecialChar ~
27277 \SpecialChar ~
27278 case 103: ...
27279
27280 \newline
27281 \SpecialChar ~
27282 \SpecialChar ~
27283 case 104: ...
27284
27285 \newline
27286 \SpecialChar ~
27287 \SpecialChar ~
27288 case 105: ...
27289
27290 \newline
27291 \SpecialChar ~
27292 \SpecialChar ~
27293 case 106: ...
27294
27295 \newline
27296 \SpecialChar ~
27297 \SpecialChar ~
27298 case 107: ...
27299
27300 \newline
27301 }
27302 \layout Standard
27303
27304 If the above switch statement is broken down into two switch statements
27305 \layout Verse
27306
27307
27308 \family typewriter
27309 switch (i) {
27310 \newline
27311 \SpecialChar ~
27312 \SpecialChar ~
27313 case 1: ...
27314
27315 \newline
27316 \SpecialChar ~
27317 \SpecialChar ~
27318 case 2: ...
27319
27320 \newline
27321 \SpecialChar ~
27322 \SpecialChar ~
27323 case 3: ...
27324
27325 \newline
27326 \SpecialChar ~
27327 \SpecialChar ~
27328 case 4: ...
27329
27330 \newline
27331 \SpecialChar ~
27332 \SpecialChar ~
27333 case 5: ...
27334
27335 \newline
27336 \SpecialChar ~
27337 \SpecialChar ~
27338 case 6: ...
27339
27340 \newline
27341 \SpecialChar ~
27342 \SpecialChar ~
27343 case 7: ...
27344
27345 \newline
27346 }
27347 \layout Standard
27348
27349 and
27350 \layout Verse
27351
27352
27353 \family typewriter
27354 switch (i) {
27355 \newline
27356 \SpecialChar ~
27357 \SpecialChar ~
27358 case 101: ...
27359
27360 \newline
27361 \SpecialChar ~
27362 \SpecialChar ~
27363 case 102: ...
27364
27365 \newline
27366 \SpecialChar ~
27367 \SpecialChar ~
27368 case 103: ...
27369
27370 \newline
27371 \SpecialChar ~
27372 \SpecialChar ~
27373 case 104: ...
27374
27375 \newline
27376 \SpecialChar ~
27377 \SpecialChar ~
27378 case 105: ...
27379
27380 \newline
27381 \SpecialChar ~
27382 \SpecialChar ~
27383 case 106: ...
27384
27385 \newline
27386 \SpecialChar ~
27387 \SpecialChar ~
27388 case 107: ...
27389
27390 \newline
27391 }
27392 \layout Standard
27393
27394 then both the switch statements will be implemented using jump-tables whereas
27395  the unmodified switch statement will not be.
27396 \layout Comment
27397
27398 There might be reasons which SDCC cannot know about to either favour or
27399  not favour jump tables.
27400  If the target system has to be as quick for the last switch case as for
27401  the first (pro jump table), or if the switch argument is known to be zero
27402  in the majority of the cases (contra jump table).
27403 \layout Standard
27404
27405 The pragma nojtbound
27406 \begin_inset LatexCommand \index{\#pragma nojtbound}
27407
27408 \end_inset
27409
27410  can be used to turn off checking the
27411 \emph on
27412 j
27413 \emph default
27414 ump
27415 \emph on
27416 t
27417 \emph default
27418 able
27419 \emph on
27420 bound
27421 \emph default
27422 aries.
27423  It has no effect if a default label is supplied.
27424  Use of this pragma is dangerous: if the switch
27425 \begin_inset LatexCommand \index{switch statement}
27426
27427 \end_inset
27428
27429  argument is not matched by a case statement the processor will happily
27430  jump into Nirvana.
27431 \layout Subsection
27432
27433 Bit-shifting Operations
27434 \begin_inset LatexCommand \index{Bit shifting}
27435
27436 \end_inset
27437
27438 .
27439 \layout Standard
27440
27441 Bit shifting is one of the most frequently used operation in embedded programmin
27442 g.
27443  SDCC tries to implement bit-shift operations in the most efficient way
27444  possible, e.g.:
27445 \layout Verse
27446
27447
27448 \family typewriter
27449 unsigned char i;
27450 \newline
27451 ...
27452
27453 \newline
27454 i >>= 4;
27455 \newline
27456 ...
27457 \layout Standard
27458
27459 generates the following code:
27460 \layout Verse
27461
27462
27463 \family typewriter
27464 mov\SpecialChar ~
27465  a,_i
27466 \newline
27467 swap a
27468 \newline
27469 anl\SpecialChar ~
27470  a,#0x0f
27471 \newline
27472 mov\SpecialChar ~
27473  _i,a
27474 \layout Standard
27475
27476 In general SDCC will never setup a loop if the shift count is known.
27477  Another example:
27478 \layout Verse
27479
27480
27481 \family typewriter
27482 unsigned int i;
27483 \newline
27484 ...
27485
27486 \newline
27487 i >>= 9;
27488 \newline
27489 ...
27490 \layout Standard
27491
27492 will generate:
27493 \layout Verse
27494
27495
27496 \family typewriter
27497 mov\SpecialChar ~
27498 \SpecialChar ~
27499 a,(_i + 1)
27500 \newline
27501 mov\SpecialChar ~
27502 \SpecialChar ~
27503 (_i + 1),#0x00
27504 \newline
27505 clr\SpecialChar ~
27506 \SpecialChar ~
27507 c
27508 \newline
27509 rrc\SpecialChar ~
27510 \SpecialChar ~
27511 a
27512 \newline
27513 mov\SpecialChar ~
27514 \SpecialChar ~
27515 _i,a
27516 \layout Subsection
27517
27518 Bit-rotation
27519 \begin_inset LatexCommand \index{Bit rotation}
27520
27521 \end_inset
27522
27523
27524 \layout Standard
27525
27526 A special case of the bit-shift operation is bit rotation
27527 \begin_inset LatexCommand \index{rotating bits}
27528
27529 \end_inset
27530
27531 , SDCC recognizes the following expression to be a left bit-rotation:
27532 \layout Verse
27533
27534
27535 \family typewriter
27536 \series bold
27537 unsigned
27538 \series default
27539 \SpecialChar ~
27540 \SpecialChar ~
27541 char i;\SpecialChar ~
27542 \SpecialChar ~
27543 \SpecialChar ~
27544 \SpecialChar ~
27545 \SpecialChar ~
27546 \SpecialChar ~
27547 \SpecialChar ~
27548 \SpecialChar ~
27549 \SpecialChar ~
27550 \SpecialChar ~
27551 \SpecialChar ~
27552 /* unsigned is needed for rotation */
27553 \newline
27554 ...
27555
27556 \newline
27557 i = ((i << 1) | (i >> 7));
27558 \family default
27559
27560 \newline
27561
27562 \family typewriter
27563 ...
27564 \layout Standard
27565
27566 will generate the following code:
27567 \layout Verse
27568
27569
27570 \family typewriter
27571 mov\SpecialChar ~
27572 \SpecialChar ~
27573 a,_i
27574 \newline
27575 rl\SpecialChar ~
27576 \SpecialChar ~
27577 \SpecialChar ~
27578 a
27579 \newline
27580 mov\SpecialChar ~
27581 \SpecialChar ~
27582 _i,a
27583 \layout Standard
27584
27585 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
27586 ns of this case will also be recognized as bit-rotation, i.e.:
27587 \layout Verse
27588
27589
27590 \family typewriter
27591 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
27592 \layout Subsection
27593
27594 Nibble and Byte Swapping
27595 \layout Standard
27596
27597 Other special cases of the bit-shift operations are nibble or byte swapping
27598 \begin_inset LatexCommand \index{swapping nibbles/bytes}
27599
27600 \end_inset
27601
27602 , SDCC recognizes the following expressions:
27603 \layout Verse
27604
27605
27606 \family typewriter
27607 \series bold
27608 unsigned
27609 \series default
27610 \SpecialChar ~
27611 \SpecialChar ~
27612 char i;
27613 \newline
27614
27615 \series bold
27616 unsigned
27617 \series default
27618 \SpecialChar ~
27619 \SpecialChar ~
27620 int j;
27621 \newline
27622 ...
27623
27624 \newline
27625 i = ((i << 4) | (i >> 4));
27626 \family default
27627
27628 \newline
27629
27630 \family typewriter
27631 j = ((j << 8) | (j >> 8));
27632 \layout Standard
27633
27634 and generates a swap instruction for the nibble swapping
27635 \begin_inset LatexCommand \index{Nibble swapping}
27636
27637 \end_inset
27638
27639  or move instructions for the byte swapping
27640 \begin_inset LatexCommand \index{Byte swapping}
27641
27642 \end_inset
27643
27644 .
27645  The
27646 \begin_inset Quotes sld
27647 \end_inset
27648
27649 j
27650 \begin_inset Quotes srd
27651 \end_inset
27652
27653  example can be used to convert from little to big-endian or vice versa.
27654  If you want to change the endianness of a
27655 \emph on
27656 signed
27657 \emph default
27658  integer you have to cast to
27659 \family typewriter
27660 (unsigned int)
27661 \family default
27662  first.
27663 \layout Standard
27664
27665 Note that SDCC stores numbers in little-endian
27666 \begin_inset Foot
27667 collapsed false
27668
27669 \layout Standard
27670
27671 Usually 8-bit processors don't care much about endianness.
27672  This is not the case for the standard 8051 which only has an instruction
27673  to increment its
27674 \emph on
27675 dptr
27676 \emph default
27677
27678 \begin_inset LatexCommand \index{DPTR}
27679
27680 \end_inset
27681
27682 -datapointer
27683 \emph on
27684
27685 \emph default
27686 so little-endian is the more efficient byte order.
27687 \end_inset
27688
27689
27690 \begin_inset LatexCommand \index{little-endian}
27691
27692 \end_inset
27693
27694
27695 \begin_inset LatexCommand \index{Endianness}
27696
27697 \end_inset
27698
27699  format (i.e.
27700  lowest order first).
27701 \layout Subsection
27702
27703 Highest Order Bit
27704 \begin_inset LatexCommand \index{Highest Order Bit}
27705
27706 \end_inset
27707
27708  / Any Order Bit
27709 \begin_inset LatexCommand \index{Any Order Bit}
27710
27711 \end_inset
27712
27713
27714 \layout Standard
27715
27716 It is frequently required to obtain the highest order bit of an integral
27717  type (long, int, short or char types).
27718  Also obtaining any other order bit is not uncommon.
27719  SDCC recognizes the following expressions to yield the highest order bit
27720  and generates optimized code for it, e.g.:
27721 \layout Verse
27722
27723
27724 \family typewriter
27725 unsigned int gint;
27726 \newline
27727
27728 \newline
27729 foo () {
27730 \newline
27731 \SpecialChar ~
27732 \SpecialChar ~
27733 unsigned char hob1, aob1;
27734 \newline
27735 \SpecialChar ~
27736 \SpecialChar ~
27737 bit hob2, hob3, aob2, aob3;
27738 \newline
27739 \SpecialChar ~
27740 \SpecialChar ~
27741 ...
27742
27743 \newline
27744 \SpecialChar ~
27745 \SpecialChar ~
27746 hob1 = (gint >> 15) & 1;
27747 \newline
27748 \SpecialChar ~
27749 \SpecialChar ~
27750 hob2 = (gint >> 15) & 1;
27751 \newline
27752 \SpecialChar ~
27753 \SpecialChar ~
27754 hob3 = gint & 0x8000;
27755 \newline
27756 \SpecialChar ~
27757 \SpecialChar ~
27758 aob1 = (gint >> 9) & 1;
27759 \newline
27760 \SpecialChar ~
27761 \SpecialChar ~
27762 aob2 = (gint >> 8) & 1;
27763 \newline
27764 \SpecialChar ~
27765 \SpecialChar ~
27766 aob3 = gint & 0x0800;
27767 \newline
27768 \SpecialChar ~
27769 \SpecialChar ~
27770 ..
27771
27772 \newline
27773 }
27774 \layout Standard
27775
27776 will generate the following code:
27777 \layout Verse
27778
27779
27780 \family typewriter
27781 \SpecialChar ~
27782 \SpecialChar ~
27783 \SpecialChar ~
27784 \SpecialChar ~
27785 \SpecialChar ~
27786 \SpecialChar ~
27787 \SpecialChar ~
27788 \SpecialChar ~
27789 \SpecialChar ~
27790 \SpecialChar ~
27791 \SpecialChar ~
27792 \SpecialChar ~
27793 \SpecialChar ~
27794 \SpecialChar ~
27795 \SpecialChar ~
27796 \SpecialChar ~
27797 \SpecialChar ~
27798 \SpecialChar ~
27799 \SpecialChar ~
27800 \SpecialChar ~
27801 \SpecialChar ~
27802 \SpecialChar ~
27803 \SpecialChar ~
27804 \SpecialChar ~
27805 \SpecialChar ~
27806  61 ;\SpecialChar ~
27807  hob.c 7
27808 \newline
27809 000A E5*01\SpecialChar ~
27810 \SpecialChar ~
27811 \SpecialChar ~
27812 \SpecialChar ~
27813 \SpecialChar ~
27814 \SpecialChar ~
27815 \SpecialChar ~
27816 \SpecialChar ~
27817 \SpecialChar ~
27818 \SpecialChar ~
27819 \SpecialChar ~
27820 \SpecialChar ~
27821 \SpecialChar ~
27822 \SpecialChar ~
27823 \SpecialChar ~
27824  62\SpecialChar ~
27825 \SpecialChar ~
27826 \SpecialChar ~
27827 \SpecialChar ~
27828 \SpecialChar ~
27829 \SpecialChar ~
27830 \SpecialChar ~
27831 \SpecialChar ~
27832  mov\SpecialChar ~
27833 \SpecialChar ~
27834  a,(_gint + 1)
27835 \newline
27836 000C 23\SpecialChar ~
27837 \SpecialChar ~
27838 \SpecialChar ~
27839 \SpecialChar ~
27840 \SpecialChar ~
27841 \SpecialChar ~
27842 \SpecialChar ~
27843 \SpecialChar ~
27844 \SpecialChar ~
27845 \SpecialChar ~
27846 \SpecialChar ~
27847 \SpecialChar ~
27848 \SpecialChar ~
27849 \SpecialChar ~
27850 \SpecialChar ~
27851 \SpecialChar ~
27852 \SpecialChar ~
27853 \SpecialChar ~
27854  63\SpecialChar ~
27855 \SpecialChar ~
27856 \SpecialChar ~
27857 \SpecialChar ~
27858 \SpecialChar ~
27859 \SpecialChar ~
27860 \SpecialChar ~
27861 \SpecialChar ~
27862  rl\SpecialChar ~
27863 \SpecialChar ~
27864 \SpecialChar ~
27865  a
27866 \newline
27867 000D 54 01\SpecialChar ~
27868 \SpecialChar ~
27869 \SpecialChar ~
27870 \SpecialChar ~
27871 \SpecialChar ~
27872 \SpecialChar ~
27873 \SpecialChar ~
27874 \SpecialChar ~
27875 \SpecialChar ~
27876 \SpecialChar ~
27877 \SpecialChar ~
27878 \SpecialChar ~
27879 \SpecialChar ~
27880 \SpecialChar ~
27881 \SpecialChar ~
27882  64\SpecialChar ~
27883 \SpecialChar ~
27884 \SpecialChar ~
27885 \SpecialChar ~
27886 \SpecialChar ~
27887 \SpecialChar ~
27888 \SpecialChar ~
27889 \SpecialChar ~
27890  anl\SpecialChar ~
27891 \SpecialChar ~
27892  a,#0x01
27893 \newline
27894 000F F5*02\SpecialChar ~
27895 \SpecialChar ~
27896 \SpecialChar ~
27897 \SpecialChar ~
27898 \SpecialChar ~
27899 \SpecialChar ~
27900 \SpecialChar ~
27901 \SpecialChar ~
27902 \SpecialChar ~
27903 \SpecialChar ~
27904 \SpecialChar ~
27905 \SpecialChar ~
27906 \SpecialChar ~
27907 \SpecialChar ~
27908 \SpecialChar ~
27909  65\SpecialChar ~
27910 \SpecialChar ~
27911 \SpecialChar ~
27912 \SpecialChar ~
27913 \SpecialChar ~
27914 \SpecialChar ~
27915 \SpecialChar ~
27916 \SpecialChar ~
27917  mov\SpecialChar ~
27918 \SpecialChar ~
27919  _foo_hob1_1_1,a
27920 \newline
27921 \SpecialChar ~
27922 \SpecialChar ~
27923 \SpecialChar ~
27924 \SpecialChar ~
27925 \SpecialChar ~
27926 \SpecialChar ~
27927 \SpecialChar ~
27928 \SpecialChar ~
27929 \SpecialChar ~
27930 \SpecialChar ~
27931 \SpecialChar ~
27932 \SpecialChar ~
27933 \SpecialChar ~
27934 \SpecialChar ~
27935 \SpecialChar ~
27936 \SpecialChar ~
27937 \SpecialChar ~
27938 \SpecialChar ~
27939 \SpecialChar ~
27940 \SpecialChar ~
27941 \SpecialChar ~
27942 \SpecialChar ~
27943 \SpecialChar ~
27944 \SpecialChar ~
27945 \SpecialChar ~
27946  66 ;\SpecialChar ~
27947  hob.c 8
27948 \newline
27949 0011 E5*01\SpecialChar ~
27950 \SpecialChar ~
27951 \SpecialChar ~
27952 \SpecialChar ~
27953 \SpecialChar ~
27954 \SpecialChar ~
27955 \SpecialChar ~
27956 \SpecialChar ~
27957 \SpecialChar ~
27958 \SpecialChar ~
27959 \SpecialChar ~
27960 \SpecialChar ~
27961 \SpecialChar ~
27962 \SpecialChar ~
27963 \SpecialChar ~
27964  67\SpecialChar ~
27965 \SpecialChar ~
27966 \SpecialChar ~
27967 \SpecialChar ~
27968 \SpecialChar ~
27969 \SpecialChar ~
27970 \SpecialChar ~
27971 \SpecialChar ~
27972  mov\SpecialChar ~
27973 \SpecialChar ~
27974  a,(_gint + 1)
27975 \newline
27976 0013 33\SpecialChar ~
27977 \SpecialChar ~
27978 \SpecialChar ~
27979 \SpecialChar ~
27980 \SpecialChar ~
27981 \SpecialChar ~
27982 \SpecialChar ~
27983 \SpecialChar ~
27984 \SpecialChar ~
27985 \SpecialChar ~
27986 \SpecialChar ~
27987 \SpecialChar ~
27988 \SpecialChar ~
27989 \SpecialChar ~
27990 \SpecialChar ~
27991 \SpecialChar ~
27992 \SpecialChar ~
27993 \SpecialChar ~
27994  68\SpecialChar ~
27995 \SpecialChar ~
27996 \SpecialChar ~
27997 \SpecialChar ~
27998 \SpecialChar ~
27999 \SpecialChar ~
28000 \SpecialChar ~
28001 \SpecialChar ~
28002  rlc\SpecialChar ~
28003 \SpecialChar ~
28004  a
28005 \newline
28006 0014 92*00\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  69\SpecialChar ~
28022 \SpecialChar ~
28023 \SpecialChar ~
28024 \SpecialChar ~
28025 \SpecialChar ~
28026 \SpecialChar ~
28027 \SpecialChar ~
28028 \SpecialChar ~
28029  mov\SpecialChar ~
28030 \SpecialChar ~
28031  _foo_hob2_1_1,c
28032 \newline
28033 \SpecialChar ~
28034 \SpecialChar ~
28035 \SpecialChar ~
28036 \SpecialChar ~
28037 \SpecialChar ~
28038 \SpecialChar ~
28039 \SpecialChar ~
28040 \SpecialChar ~
28041 \SpecialChar ~
28042 \SpecialChar ~
28043 \SpecialChar ~
28044 \SpecialChar ~
28045 \SpecialChar ~
28046 \SpecialChar ~
28047 \SpecialChar ~
28048 \SpecialChar ~
28049 \SpecialChar ~
28050 \SpecialChar ~
28051 \SpecialChar ~
28052 \SpecialChar ~
28053 \SpecialChar ~
28054 \SpecialChar ~
28055 \SpecialChar ~
28056 \SpecialChar ~
28057 \SpecialChar ~
28058  66 ;\SpecialChar ~
28059  hob.c 9
28060 \newline
28061 0016 E5*01\SpecialChar ~
28062 \SpecialChar ~
28063 \SpecialChar ~
28064 \SpecialChar ~
28065 \SpecialChar ~
28066 \SpecialChar ~
28067 \SpecialChar ~
28068 \SpecialChar ~
28069 \SpecialChar ~
28070 \SpecialChar ~
28071 \SpecialChar ~
28072 \SpecialChar ~
28073 \SpecialChar ~
28074 \SpecialChar ~
28075 \SpecialChar ~
28076  67\SpecialChar ~
28077 \SpecialChar ~
28078 \SpecialChar ~
28079 \SpecialChar ~
28080 \SpecialChar ~
28081 \SpecialChar ~
28082 \SpecialChar ~
28083 \SpecialChar ~
28084  mov\SpecialChar ~
28085 \SpecialChar ~
28086  a,(_gint + 1)
28087 \newline
28088 0018 33\SpecialChar ~
28089 \SpecialChar ~
28090 \SpecialChar ~
28091 \SpecialChar ~
28092 \SpecialChar ~
28093 \SpecialChar ~
28094 \SpecialChar ~
28095 \SpecialChar ~
28096 \SpecialChar ~
28097 \SpecialChar ~
28098 \SpecialChar ~
28099 \SpecialChar ~
28100 \SpecialChar ~
28101 \SpecialChar ~
28102 \SpecialChar ~
28103 \SpecialChar ~
28104 \SpecialChar ~
28105 \SpecialChar ~
28106  68\SpecialChar ~
28107 \SpecialChar ~
28108 \SpecialChar ~
28109 \SpecialChar ~
28110 \SpecialChar ~
28111 \SpecialChar ~
28112 \SpecialChar ~
28113 \SpecialChar ~
28114  rlc\SpecialChar ~
28115 \SpecialChar ~
28116  a
28117 \newline
28118 0019 92*01\SpecialChar ~
28119 \SpecialChar ~
28120 \SpecialChar ~
28121 \SpecialChar ~
28122 \SpecialChar ~
28123 \SpecialChar ~
28124 \SpecialChar ~
28125 \SpecialChar ~
28126 \SpecialChar ~
28127 \SpecialChar ~
28128 \SpecialChar ~
28129 \SpecialChar ~
28130 \SpecialChar ~
28131 \SpecialChar ~
28132 \SpecialChar ~
28133  69\SpecialChar ~
28134 \SpecialChar ~
28135 \SpecialChar ~
28136 \SpecialChar ~
28137 \SpecialChar ~
28138 \SpecialChar ~
28139 \SpecialChar ~
28140 \SpecialChar ~
28141  mov\SpecialChar ~
28142 \SpecialChar ~
28143  _foo_hob3_1_1,c
28144 \newline
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 \SpecialChar ~
28162 \SpecialChar ~
28163 \SpecialChar ~
28164 \SpecialChar ~
28165 \SpecialChar ~
28166 \SpecialChar ~
28167 \SpecialChar ~
28168 \SpecialChar ~
28169 \SpecialChar ~
28170  70 ;\SpecialChar ~
28171  hob.c 10
28172 \newline
28173 001B E5*01\SpecialChar ~
28174 \SpecialChar ~
28175 \SpecialChar ~
28176 \SpecialChar ~
28177 \SpecialChar ~
28178 \SpecialChar ~
28179 \SpecialChar ~
28180 \SpecialChar ~
28181 \SpecialChar ~
28182 \SpecialChar ~
28183 \SpecialChar ~
28184 \SpecialChar ~
28185 \SpecialChar ~
28186 \SpecialChar ~
28187 \SpecialChar ~
28188  71\SpecialChar ~
28189 \SpecialChar ~
28190 \SpecialChar ~
28191 \SpecialChar ~
28192 \SpecialChar ~
28193 \SpecialChar ~
28194 \SpecialChar ~
28195 \SpecialChar ~
28196  mov\SpecialChar ~
28197 \SpecialChar ~
28198  a,(_gint + 1)
28199 \newline
28200 001D 03\SpecialChar ~
28201 \SpecialChar ~
28202 \SpecialChar ~
28203 \SpecialChar ~
28204 \SpecialChar ~
28205 \SpecialChar ~
28206 \SpecialChar ~
28207 \SpecialChar ~
28208 \SpecialChar ~
28209 \SpecialChar ~
28210 \SpecialChar ~
28211 \SpecialChar ~
28212 \SpecialChar ~
28213 \SpecialChar ~
28214 \SpecialChar ~
28215 \SpecialChar ~
28216 \SpecialChar ~
28217 \SpecialChar ~
28218  72\SpecialChar ~
28219 \SpecialChar ~
28220 \SpecialChar ~
28221 \SpecialChar ~
28222 \SpecialChar ~
28223 \SpecialChar ~
28224 \SpecialChar ~
28225 \SpecialChar ~
28226  rr\SpecialChar ~
28227 \SpecialChar ~
28228 \SpecialChar ~
28229  a
28230 \newline
28231 001E 54 01\SpecialChar ~
28232 \SpecialChar ~
28233 \SpecialChar ~
28234 \SpecialChar ~
28235 \SpecialChar ~
28236 \SpecialChar ~
28237 \SpecialChar ~
28238 \SpecialChar ~
28239 \SpecialChar ~
28240 \SpecialChar ~
28241 \SpecialChar ~
28242 \SpecialChar ~
28243 \SpecialChar ~
28244 \SpecialChar ~
28245 \SpecialChar ~
28246  73\SpecialChar ~
28247 \SpecialChar ~
28248 \SpecialChar ~
28249 \SpecialChar ~
28250 \SpecialChar ~
28251 \SpecialChar ~
28252 \SpecialChar ~
28253 \SpecialChar ~
28254  anl\SpecialChar ~
28255 \SpecialChar ~
28256  a,#0x01
28257 \newline
28258 0020 F5*03\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  74\SpecialChar ~
28274 \SpecialChar ~
28275 \SpecialChar ~
28276 \SpecialChar ~
28277 \SpecialChar ~
28278 \SpecialChar ~
28279 \SpecialChar ~
28280 \SpecialChar ~
28281  mov\SpecialChar ~
28282 \SpecialChar ~
28283  _foo_aob1_1_1,a
28284 \newline
28285 \SpecialChar ~
28286 \SpecialChar ~
28287 \SpecialChar ~
28288 \SpecialChar ~
28289 \SpecialChar ~
28290 \SpecialChar ~
28291 \SpecialChar ~
28292 \SpecialChar ~
28293 \SpecialChar ~
28294 \SpecialChar ~
28295 \SpecialChar ~
28296 \SpecialChar ~
28297 \SpecialChar ~
28298 \SpecialChar ~
28299 \SpecialChar ~
28300 \SpecialChar ~
28301 \SpecialChar ~
28302 \SpecialChar ~
28303 \SpecialChar ~
28304 \SpecialChar ~
28305 \SpecialChar ~
28306 \SpecialChar ~
28307 \SpecialChar ~
28308 \SpecialChar ~
28309 \SpecialChar ~
28310  75 ;\SpecialChar ~
28311  hob.c 11
28312 \newline
28313 0022 E5*01\SpecialChar ~
28314 \SpecialChar ~
28315 \SpecialChar ~
28316 \SpecialChar ~
28317 \SpecialChar ~
28318 \SpecialChar ~
28319 \SpecialChar ~
28320 \SpecialChar ~
28321 \SpecialChar ~
28322 \SpecialChar ~
28323 \SpecialChar ~
28324 \SpecialChar ~
28325 \SpecialChar ~
28326 \SpecialChar ~
28327 \SpecialChar ~
28328  76\SpecialChar ~
28329 \SpecialChar ~
28330 \SpecialChar ~
28331 \SpecialChar ~
28332 \SpecialChar ~
28333 \SpecialChar ~
28334 \SpecialChar ~
28335 \SpecialChar ~
28336  mov\SpecialChar ~
28337 \SpecialChar ~
28338  a,(_gint + 1)
28339 \newline
28340 0024 13\SpecialChar ~
28341 \SpecialChar ~
28342 \SpecialChar ~
28343 \SpecialChar ~
28344 \SpecialChar ~
28345 \SpecialChar ~
28346 \SpecialChar ~
28347 \SpecialChar ~
28348 \SpecialChar ~
28349 \SpecialChar ~
28350 \SpecialChar ~
28351 \SpecialChar ~
28352 \SpecialChar ~
28353 \SpecialChar ~
28354 \SpecialChar ~
28355 \SpecialChar ~
28356 \SpecialChar ~
28357 \SpecialChar ~
28358  77\SpecialChar ~
28359 \SpecialChar ~
28360 \SpecialChar ~
28361 \SpecialChar ~
28362 \SpecialChar ~
28363 \SpecialChar ~
28364 \SpecialChar ~
28365 \SpecialChar ~
28366  rrc\SpecialChar ~
28367 \SpecialChar ~
28368  a
28369 \newline
28370 0025 92*02\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  78\SpecialChar ~
28386 \SpecialChar ~
28387 \SpecialChar ~
28388 \SpecialChar ~
28389 \SpecialChar ~
28390 \SpecialChar ~
28391 \SpecialChar ~
28392 \SpecialChar ~
28393  mov\SpecialChar ~
28394 \SpecialChar ~
28395  _foo_aob2_1_1,c
28396 \newline
28397 \SpecialChar ~
28398 \SpecialChar ~
28399 \SpecialChar ~
28400 \SpecialChar ~
28401 \SpecialChar ~
28402 \SpecialChar ~
28403 \SpecialChar ~
28404 \SpecialChar ~
28405 \SpecialChar ~
28406 \SpecialChar ~
28407 \SpecialChar ~
28408 \SpecialChar ~
28409 \SpecialChar ~
28410 \SpecialChar ~
28411 \SpecialChar ~
28412 \SpecialChar ~
28413 \SpecialChar ~
28414 \SpecialChar ~
28415 \SpecialChar ~
28416 \SpecialChar ~
28417 \SpecialChar ~
28418 \SpecialChar ~
28419 \SpecialChar ~
28420 \SpecialChar ~
28421 \SpecialChar ~
28422  79 ;\SpecialChar ~
28423  hob.c 12
28424 \newline
28425 0027 E5*01\SpecialChar ~
28426 \SpecialChar ~
28427 \SpecialChar ~
28428 \SpecialChar ~
28429 \SpecialChar ~
28430 \SpecialChar ~
28431 \SpecialChar ~
28432 \SpecialChar ~
28433 \SpecialChar ~
28434 \SpecialChar ~
28435 \SpecialChar ~
28436 \SpecialChar ~
28437 \SpecialChar ~
28438 \SpecialChar ~
28439 \SpecialChar ~
28440  80\SpecialChar ~
28441 \SpecialChar ~
28442 \SpecialChar ~
28443 \SpecialChar ~
28444 \SpecialChar ~
28445 \SpecialChar ~
28446 \SpecialChar ~
28447 \SpecialChar ~
28448  mov\SpecialChar ~
28449 \SpecialChar ~
28450  a,(_gint + 1)
28451 \newline
28452 0029 A2 E3\SpecialChar ~
28453 \SpecialChar ~
28454 \SpecialChar ~
28455 \SpecialChar ~
28456 \SpecialChar ~
28457 \SpecialChar ~
28458 \SpecialChar ~
28459 \SpecialChar ~
28460 \SpecialChar ~
28461 \SpecialChar ~
28462 \SpecialChar ~
28463 \SpecialChar ~
28464 \SpecialChar ~
28465 \SpecialChar ~
28466 \SpecialChar ~
28467  81\SpecialChar ~
28468 \SpecialChar ~
28469 \SpecialChar ~
28470 \SpecialChar ~
28471 \SpecialChar ~
28472 \SpecialChar ~
28473 \SpecialChar ~
28474 \SpecialChar ~
28475  mov\SpecialChar ~
28476 \SpecialChar ~
28477  c,acc[3]
28478 \newline
28479 002B 92*03\SpecialChar ~
28480 \SpecialChar ~
28481 \SpecialChar ~
28482 \SpecialChar ~
28483 \SpecialChar ~
28484 \SpecialChar ~
28485 \SpecialChar ~
28486 \SpecialChar ~
28487 \SpecialChar ~
28488 \SpecialChar ~
28489 \SpecialChar ~
28490 \SpecialChar ~
28491 \SpecialChar ~
28492 \SpecialChar ~
28493 \SpecialChar ~
28494  82\SpecialChar ~
28495 \SpecialChar ~
28496 \SpecialChar ~
28497 \SpecialChar ~
28498 \SpecialChar ~
28499 \SpecialChar ~
28500 \SpecialChar ~
28501 \SpecialChar ~
28502  mov\SpecialChar ~
28503 \SpecialChar ~
28504  _foo_aob3_1_1,c
28505 \layout Standard
28506
28507 Other variations of these cases however will
28508 \emph on
28509 not
28510 \emph default
28511  be recognized.
28512  They are standard C expressions, so I heartily recommend these be the only
28513  way to get the highest order bit, (it is portable).
28514  Of course it will be recognized even if it is embedded in other expressions,
28515  e.g.:
28516 \layout Verse
28517
28518
28519 \family typewriter
28520 xyz = gint + ((gint >> 15) & 1);
28521 \layout Standard
28522
28523 will still be recognized.
28524 \layout Subsection
28525
28526 Higher Order Byte
28527 \begin_inset LatexCommand \index{Higher Order Byte}
28528
28529 \end_inset
28530
28531  / Higher Order Word
28532 \begin_inset LatexCommand \index{Higher Order Word}
28533
28534 \end_inset
28535
28536
28537 \layout Standard
28538
28539 It is also frequently required to obtain a higher order byte or word of
28540  a larger integral type (long, int or short types).
28541  SDCC recognizes the following expressions to yield the higher order byte
28542  or word and generates optimized code for it, e.g.:
28543 \layout Verse
28544
28545
28546 \family typewriter
28547 unsigned int gint;
28548 \newline
28549 unsigned long int glong;
28550 \newline
28551
28552 \newline
28553 foo () {
28554 \newline
28555 \SpecialChar ~
28556 \SpecialChar ~
28557 unsigned char hob1, hob2;
28558 \newline
28559 \SpecialChar ~
28560 \SpecialChar ~
28561 unsigned int how1, how2;
28562 \newline
28563 \SpecialChar ~
28564 \SpecialChar ~
28565 ...
28566
28567 \newline
28568 \SpecialChar ~
28569 \SpecialChar ~
28570 hob1 = (gint >> 8) & 0xFF;
28571 \newline
28572 \SpecialChar ~
28573 \SpecialChar ~
28574 hob2 = glong >> 24;
28575 \newline
28576 \SpecialChar ~
28577 \SpecialChar ~
28578 how1 = (glong >> 16) & 0xFFFF;
28579 \newline
28580 \SpecialChar ~
28581 \SpecialChar ~
28582 how2 = glong >> 8;
28583 \newline
28584 \SpecialChar ~
28585 \SpecialChar ~
28586 ..
28587
28588 \newline
28589 }
28590 \layout Standard
28591
28592 will generate the following code:
28593 \layout Verse
28594
28595
28596 \family typewriter
28597 \SpecialChar ~
28598 \SpecialChar ~
28599 \SpecialChar ~
28600 \SpecialChar ~
28601 \SpecialChar ~
28602 \SpecialChar ~
28603 \SpecialChar ~
28604 \SpecialChar ~
28605 \SpecialChar ~
28606 \SpecialChar ~
28607 \SpecialChar ~
28608 \SpecialChar ~
28609 \SpecialChar ~
28610 \SpecialChar ~
28611 \SpecialChar ~
28612 \SpecialChar ~
28613 \SpecialChar ~
28614 \SpecialChar ~
28615 \SpecialChar ~
28616 \SpecialChar ~
28617 \SpecialChar ~
28618 \SpecialChar ~
28619 \SpecialChar ~
28620 \SpecialChar ~
28621 \SpecialChar ~
28622  91 ;\SpecialChar ~
28623  hob.c 15
28624 \newline
28625 0037 85*01*06\SpecialChar ~
28626 \SpecialChar ~
28627 \SpecialChar ~
28628 \SpecialChar ~
28629 \SpecialChar ~
28630 \SpecialChar ~
28631 \SpecialChar ~
28632 \SpecialChar ~
28633 \SpecialChar ~
28634 \SpecialChar ~
28635 \SpecialChar ~
28636 \SpecialChar ~
28637  92\SpecialChar ~
28638 \SpecialChar ~
28639 \SpecialChar ~
28640 \SpecialChar ~
28641 \SpecialChar ~
28642 \SpecialChar ~
28643 \SpecialChar ~
28644 \SpecialChar ~
28645  mov\SpecialChar ~
28646 \SpecialChar ~
28647  _foo_hob1_1_1,(_gint + 1)
28648 \newline
28649 \SpecialChar ~
28650 \SpecialChar ~
28651 \SpecialChar ~
28652 \SpecialChar ~
28653 \SpecialChar ~
28654 \SpecialChar ~
28655 \SpecialChar ~
28656 \SpecialChar ~
28657 \SpecialChar ~
28658 \SpecialChar ~
28659 \SpecialChar ~
28660 \SpecialChar ~
28661 \SpecialChar ~
28662 \SpecialChar ~
28663 \SpecialChar ~
28664 \SpecialChar ~
28665 \SpecialChar ~
28666 \SpecialChar ~
28667 \SpecialChar ~
28668 \SpecialChar ~
28669 \SpecialChar ~
28670 \SpecialChar ~
28671 \SpecialChar ~
28672 \SpecialChar ~
28673 \SpecialChar ~
28674  93 ;\SpecialChar ~
28675  hob.c 16
28676 \newline
28677 003A 85*05*07\SpecialChar ~
28678 \SpecialChar ~
28679 \SpecialChar ~
28680 \SpecialChar ~
28681 \SpecialChar ~
28682 \SpecialChar ~
28683 \SpecialChar ~
28684 \SpecialChar ~
28685 \SpecialChar ~
28686 \SpecialChar ~
28687 \SpecialChar ~
28688 \SpecialChar ~
28689  94\SpecialChar ~
28690 \SpecialChar ~
28691 \SpecialChar ~
28692 \SpecialChar ~
28693 \SpecialChar ~
28694 \SpecialChar ~
28695 \SpecialChar ~
28696 \SpecialChar ~
28697  mov\SpecialChar ~
28698 \SpecialChar ~
28699  _foo_hob2_1_1,(_glong + 3)
28700 \newline
28701 \SpecialChar ~
28702 \SpecialChar ~
28703 \SpecialChar ~
28704 \SpecialChar ~
28705 \SpecialChar ~
28706 \SpecialChar ~
28707 \SpecialChar ~
28708 \SpecialChar ~
28709 \SpecialChar ~
28710 \SpecialChar ~
28711 \SpecialChar ~
28712 \SpecialChar ~
28713 \SpecialChar ~
28714 \SpecialChar ~
28715 \SpecialChar ~
28716 \SpecialChar ~
28717 \SpecialChar ~
28718 \SpecialChar ~
28719 \SpecialChar ~
28720 \SpecialChar ~
28721 \SpecialChar ~
28722 \SpecialChar ~
28723 \SpecialChar ~
28724 \SpecialChar ~
28725 \SpecialChar ~
28726  95 ;\SpecialChar ~
28727  hob.c 17
28728 \newline
28729 003D 85*04*08\SpecialChar ~
28730 \SpecialChar ~
28731 \SpecialChar ~
28732 \SpecialChar ~
28733 \SpecialChar ~
28734 \SpecialChar ~
28735 \SpecialChar ~
28736 \SpecialChar ~
28737 \SpecialChar ~
28738 \SpecialChar ~
28739 \SpecialChar ~
28740 \SpecialChar ~
28741  96\SpecialChar ~
28742 \SpecialChar ~
28743 \SpecialChar ~
28744 \SpecialChar ~
28745 \SpecialChar ~
28746 \SpecialChar ~
28747 \SpecialChar ~
28748 \SpecialChar ~
28749  mov\SpecialChar ~
28750 \SpecialChar ~
28751  _foo_how1_1_1,(_glong + 2)
28752 \newline
28753 0040 85*05*09\SpecialChar ~
28754 \SpecialChar ~
28755 \SpecialChar ~
28756 \SpecialChar ~
28757 \SpecialChar ~
28758 \SpecialChar ~
28759 \SpecialChar ~
28760 \SpecialChar ~
28761 \SpecialChar ~
28762 \SpecialChar ~
28763 \SpecialChar ~
28764 \SpecialChar ~
28765  97\SpecialChar ~
28766 \SpecialChar ~
28767 \SpecialChar ~
28768 \SpecialChar ~
28769 \SpecialChar ~
28770 \SpecialChar ~
28771 \SpecialChar ~
28772 \SpecialChar ~
28773  mov\SpecialChar ~
28774 \SpecialChar ~
28775  (_foo_how1_1_1 + 1),(_glong + 3)
28776 \newline
28777 0043 85*03*0A\SpecialChar ~
28778 \SpecialChar ~
28779 \SpecialChar ~
28780 \SpecialChar ~
28781 \SpecialChar ~
28782 \SpecialChar ~
28783 \SpecialChar ~
28784 \SpecialChar ~
28785 \SpecialChar ~
28786 \SpecialChar ~
28787 \SpecialChar ~
28788 \SpecialChar ~
28789  98\SpecialChar ~
28790 \SpecialChar ~
28791 \SpecialChar ~
28792 \SpecialChar ~
28793 \SpecialChar ~
28794 \SpecialChar ~
28795 \SpecialChar ~
28796 \SpecialChar ~
28797  mov\SpecialChar ~
28798 \SpecialChar ~
28799  _foo_how2_1_1,(_glong + 1)
28800 \newline
28801 0046 85*04*0B\SpecialChar ~
28802 \SpecialChar ~
28803 \SpecialChar ~
28804 \SpecialChar ~
28805 \SpecialChar ~
28806 \SpecialChar ~
28807 \SpecialChar ~
28808 \SpecialChar ~
28809 \SpecialChar ~
28810 \SpecialChar ~
28811 \SpecialChar ~
28812 \SpecialChar ~
28813  99\SpecialChar ~
28814 \SpecialChar ~
28815 \SpecialChar ~
28816 \SpecialChar ~
28817 \SpecialChar ~
28818 \SpecialChar ~
28819 \SpecialChar ~
28820 \SpecialChar ~
28821  mov\SpecialChar ~
28822 \SpecialChar ~
28823  (_foo_how2_1_1 + 1),(_glong + 2)
28824 \layout Standard
28825
28826 Again, variations of these cases may
28827 \emph on
28828 not
28829 \emph default
28830  be recognized.
28831  They are standard C expressions, so I heartily recommend these be the only
28832  way to get the higher order byte/word, (it is portable).
28833  Of course it will be recognized even if it is embedded in other expressions,
28834  e.g.:
28835 \layout Verse
28836
28837
28838 \family typewriter
28839 xyz = gint + ((gint >> 8) & 0xFF);
28840 \layout Standard
28841
28842 will still be recognized.
28843 \layout Subsection
28844
28845 Peephole Optimizer
28846 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
28847
28848 \end_inset
28849
28850
28851 \begin_inset LatexCommand \index{Peephole optimizer}
28852
28853 \end_inset
28854
28855
28856 \layout Standard
28857
28858 The compiler uses a rule based, pattern matching and re-writing mechanism
28859  for peep-hole optimization.
28860  It is inspired by
28861 \emph on
28862 copt
28863 \emph default
28864  a peep-hole optimizer by Christopher W.
28865  Fraser (cwfraser\SpecialChar ~
28866 @\SpecialChar ~
28867 microsoft.com).
28868  A default set of rules are compiled into the compiler, additional rules
28869  may be added with the
28870 \emph on
28871 -
28872 \begin_inset ERT
28873 status Collapsed
28874
28875 \layout Standard
28876
28877 \backslash
28878 /
28879 \end_inset
28880
28881 -peep-file
28882 \begin_inset LatexCommand \index{-\/-peep-file}
28883
28884 \end_inset
28885
28886  <filename>
28887 \emph default
28888  option.
28889  The rule language is best illustrated with examples.
28890 \layout Verse
28891
28892
28893 \family typewriter
28894 replace {
28895 \newline
28896 \SpecialChar ~
28897 \SpecialChar ~
28898 mov %1,a
28899 \newline
28900 \SpecialChar ~
28901 \SpecialChar ~
28902 mov a,%1
28903 \newline
28904 } by {
28905 \newline
28906 \SpecialChar ~
28907 \SpecialChar ~
28908 mov %1,a
28909 \newline
28910 }
28911 \layout Standard
28912
28913 The above rule will change the following assembly
28914 \begin_inset LatexCommand \index{Assembler routines}
28915
28916 \end_inset
28917
28918  sequence:
28919 \layout Verse
28920
28921
28922 \family typewriter
28923 mov r1,a
28924 \newline
28925 mov a,r1
28926 \layout Standard
28927
28928 to
28929 \layout Verse
28930
28931
28932 \family typewriter
28933 mov r1,a
28934 \layout Standard
28935
28936 Note: All occurrences of a
28937 \emph on
28938 %n
28939 \emph default
28940  (pattern variable) must denote the same string.
28941  With the above rule, the assembly sequence:
28942 \layout Verse
28943
28944
28945 \family typewriter
28946 mov r1,a
28947 \newline
28948 mov a,r2
28949 \layout Standard
28950
28951 will remain unmodified.
28952 \newline
28953
28954 \newline
28955 Other special case optimizations may be added by the user (via
28956 \emph on
28957 -
28958 \begin_inset ERT
28959 status Collapsed
28960
28961 \layout Standard
28962
28963 \backslash
28964 /
28965 \end_inset
28966
28967 -peep-file option
28968 \emph default
28969 ).
28970  E.g.
28971  some variants of the 8051 MCU
28972 \begin_inset LatexCommand \index{MCS51 variants}
28973
28974 \end_inset
28975
28976  allow only
28977 \family typewriter
28978 ajmp
28979 \family default
28980  and
28981 \family typewriter
28982 acall
28983 \family default
28984 .
28985  The following two rules will change all
28986 \family typewriter
28987 ljmp
28988 \family default
28989  and
28990 \family typewriter
28991 lcall
28992 \family default
28993  to
28994 \family typewriter
28995 ajmp
28996 \family default
28997  and
28998 \family typewriter
28999 acall
29000 \layout Verse
29001
29002
29003 \family typewriter
29004 replace { lcall %1 } by { acall %1 }
29005 \newline
29006 replace { ljmp %1 } by { ajmp %1 }
29007 \layout Standard
29008
29009 The
29010 \emph on
29011 inline-assembler code
29012 \emph default
29013  is also passed through the peep hole optimizer, thus the peephole optimizer
29014  can also be used as an assembly level macro expander.
29015  The rules themselves are MCU dependent whereas the rule language infra-structur
29016 e is MCU independent.
29017  Peephole optimization rules for other MCU can be easily programmed using
29018  the rule language.
29019 \newline
29020
29021 \newline
29022 The syntax for a rule is as follows:
29023 \layout Verse
29024
29025
29026 \family typewriter
29027 rule := replace [ restart ] '{' <assembly sequence> '
29028 \backslash
29029 n'
29030 \newline
29031 \SpecialChar ~
29032  \SpecialChar ~
29033  \SpecialChar ~
29034  \SpecialChar ~
29035  \SpecialChar ~
29036  \SpecialChar ~
29037  \SpecialChar ~
29038  \SpecialChar ~
29039  \SpecialChar ~
29040  \SpecialChar ~
29041  \SpecialChar ~
29042  \SpecialChar ~
29043  \SpecialChar ~
29044  \SpecialChar ~
29045  '}' by '{' '
29046 \backslash
29047 n'
29048 \newline
29049 \SpecialChar ~
29050  \SpecialChar ~
29051  \SpecialChar ~
29052  \SpecialChar ~
29053  \SpecialChar ~
29054  \SpecialChar ~
29055  \SpecialChar ~
29056  \SpecialChar ~
29057  \SpecialChar ~
29058  \SpecialChar ~
29059  \SpecialChar ~
29060  \SpecialChar ~
29061  \SpecialChar ~
29062  \SpecialChar ~
29063  \SpecialChar ~
29064  \SpecialChar ~
29065  <assembly sequence> '
29066 \backslash
29067 n'
29068 \newline
29069 \SpecialChar ~
29070  \SpecialChar ~
29071  \SpecialChar ~
29072  \SpecialChar ~
29073  \SpecialChar ~
29074  \SpecialChar ~
29075  \SpecialChar ~
29076  \SpecialChar ~
29077  \SpecialChar ~
29078  \SpecialChar ~
29079  \SpecialChar ~
29080  \SpecialChar ~
29081  \SpecialChar ~
29082  \SpecialChar ~
29083  '}' [if <functionName> ] '
29084 \backslash
29085 n'
29086 \layout Standard
29087
29088 <assembly sequence> := assembly instruction (each instruction including
29089  labels must be on a separate line).
29090 \newline
29091
29092 \newline
29093 The optimizer will apply to the rules one by one from the top in the sequence
29094  of their appearance, it will terminate when all rules are exhausted.
29095  If the 'restart' option is specified, then the optimizer will start matching
29096  the rules again from the top, this option for a rule is expensive (performance)
29097 , it is intended to be used in situations where a transformation will trigger
29098  the same rule again.
29099  An example of this (not a good one, it has side effects) is the following
29100  rule:
29101 \layout Verse
29102
29103
29104 \family typewriter
29105 replace restart {
29106 \newline
29107 \SpecialChar ~
29108 \SpecialChar ~
29109 pop %1
29110 \newline
29111 \SpecialChar ~
29112 \SpecialChar ~
29113 push %1 } by {
29114 \newline
29115 \SpecialChar ~
29116 \SpecialChar ~
29117 ; nop
29118 \newline
29119 }
29120 \layout Standard
29121
29122 Note that the replace pattern cannot be a blank, but can be a comment line.
29123  Without the 'restart' option only the innermost 'pop' 'push' pair would
29124  be eliminated, i.e.:
29125 \layout Verse
29126
29127
29128 \family typewriter
29129 pop ar1
29130 \newline
29131 pop ar2
29132 \newline
29133 push ar2
29134 \newline
29135 push ar1
29136 \layout Standard
29137
29138 would result in:
29139 \layout Verse
29140
29141
29142 \family typewriter
29143 pop ar1
29144 \newline
29145 ; nop
29146 \newline
29147 push ar1
29148 \layout Standard
29149
29150
29151 \emph on
29152 with
29153 \emph default
29154  the restart option the rule will be applied again to the resulting code
29155  and then all the pop-push pairs will be eliminated to yield:
29156 \layout Verse
29157
29158
29159 \family typewriter
29160 ; nop
29161 \newline
29162 ; nop
29163 \layout Standard
29164
29165 A conditional function can be attached to a rule.
29166  Attaching rules are somewhat more involved, let me illustrate this with
29167  an example.
29168 \layout Verse
29169
29170
29171 \family typewriter
29172 replace {
29173 \newline
29174 \SpecialChar ~
29175  \SpecialChar ~
29176  \SpecialChar ~
29177 ljmp %5
29178 \newline
29179 %2:
29180 \newline
29181 } by {
29182 \newline
29183 \SpecialChar ~
29184  \SpecialChar ~
29185  \SpecialChar ~
29186 sjmp %5
29187 \newline
29188 %2:
29189 \newline
29190 } if labelInRange
29191 \layout Standard
29192
29193 The optimizer does a look-up of a function name table defined in function
29194
29195 \emph on
29196 callFuncByName
29197 \emph default
29198  in the source file SDCCpeeph.c, with the name
29199 \emph on
29200 labelInRange
29201 \emph default
29202 .
29203  If it finds a corresponding entry the function is called.
29204  Note there can be no parameters specified for these functions, in this
29205  case the use of
29206 \emph on
29207 %5
29208 \emph default
29209  is crucial, since the function
29210 \emph on
29211 labelInRange
29212 \emph default
29213  expects to find the label in that particular variable (the hash table containin
29214 g the variable bindings is passed as a parameter).
29215  If you want to code more such functions, take a close look at the function
29216  labelInRange and the calling mechanism in source file SDCCpeeph.c.
29217  Currently implemented are
29218 \emph on
29219 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
29220  24bitMode, portIsDS390, 24bitModeAndPortDS390
29221 \emph default
29222 and
29223 \emph on
29224  notVolatile
29225 \emph default
29226 .
29227 \layout Standard
29228
29229 I know this whole thing is a little kludgey, but maybe some day we will
29230  have some better means.
29231  If you are looking at this file, you will see the default rules that are
29232  compiled into the compiler, you can add your own rules in the default set
29233  there if you get tired of specifying the -
29234 \begin_inset ERT
29235 status Collapsed
29236
29237 \layout Standard
29238
29239 \backslash
29240 /
29241 \end_inset
29242
29243 -peep-file option.
29244 \layout Section
29245
29246 ANSI-Compliance
29247 \begin_inset LatexCommand \index{ANSI-compliance}
29248
29249 \end_inset
29250
29251
29252 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
29253
29254 \end_inset
29255
29256
29257 \layout Standard
29258
29259 The latest publically available version of the standard
29260 \emph on
29261 ISO/IEC 9899 - Programming languages - C
29262 \emph default
29263  should be available at:
29264 \begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899}
29265
29266 \end_inset
29267
29268 .
29269 \newline
29270
29271 \layout Standard
29272
29273 Deviations from the compliance:
29274 \layout Itemize
29275
29276 functions are not reentrant
29277 \begin_inset LatexCommand \index{reentrant}
29278
29279 \end_inset
29280
29281  unless explicitly declared as such or the
29282 \series bold
29283 -
29284 \begin_inset ERT
29285 status Collapsed
29286
29287 \layout Standard
29288
29289 \backslash
29290 /
29291 \end_inset
29292
29293 -stack-auto
29294 \begin_inset LatexCommand \index{-\/-stack-auto}
29295
29296 \end_inset
29297
29298
29299 \series default
29300  command line option is specified.
29301 \layout Itemize
29302
29303 structures
29304 \begin_inset LatexCommand \index{struct}
29305
29306 \end_inset
29307
29308  and unions
29309 \begin_inset LatexCommand \index{union}
29310
29311 \end_inset
29312
29313  cannot be assigned values directly, cannot be passed as function parameters
29314  or assigned to each other and cannot be a return value
29315 \begin_inset LatexCommand \index{return value}
29316
29317 \end_inset
29318
29319  from a function, e.g.:
29320 \begin_deeper
29321 \layout Verse
29322
29323
29324 \family typewriter
29325 struct s { ...
29326  };
29327 \newline
29328 struct s s1, s2;
29329 \newline
29330 foo()
29331 \newline
29332 {
29333 \newline
29334 \SpecialChar ~
29335 \SpecialChar ~
29336 \SpecialChar ~
29337 \SpecialChar ~
29338 ...
29339
29340 \newline
29341 \SpecialChar ~
29342 \SpecialChar ~
29343 \SpecialChar ~
29344 \SpecialChar ~
29345 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
29346 \newline
29347 \SpecialChar ~
29348 \SpecialChar ~
29349 \SpecialChar ~
29350 \SpecialChar ~
29351 ...
29352
29353 \newline
29354 }
29355 \newline
29356
29357 \series bold
29358 struct
29359 \series default
29360  s foo1 (
29361 \series bold
29362 struct
29363 \series default
29364  s parms) /* invalid in SDCC although allowed in ANSI */
29365 \newline
29366 {
29367 \newline
29368 \SpecialChar ~
29369 \SpecialChar ~
29370 \SpecialChar ~
29371 \SpecialChar ~
29372 struct s rets;
29373 \newline
29374 \SpecialChar ~
29375 \SpecialChar ~
29376 \SpecialChar ~
29377 \SpecialChar ~
29378 ...
29379
29380 \newline
29381 \SpecialChar ~
29382 \SpecialChar ~
29383 \SpecialChar ~
29384 \SpecialChar ~
29385 return rets; /* is invalid in SDCC although allowed in ANSI */
29386 \newline
29387 }
29388 \end_deeper
29389 \layout Itemize
29390
29391 initialization of structure arrays must be fully braced.
29392 \begin_deeper
29393 \layout Verse
29394
29395
29396 \family typewriter
29397 struct s { char x } a[] = {1, 2};\SpecialChar ~
29398 \SpecialChar ~
29399 \SpecialChar ~
29400 \SpecialChar ~
29401 \SpecialChar ~
29402 /* invalid in SDCC */
29403 \newline
29404 struct s { char x } a[] = {{1}, {2}}; /* OK */
29405 \end_deeper
29406 \layout Itemize
29407
29408 'long long
29409 \begin_inset LatexCommand \index{long long (not supported)}
29410
29411 \end_inset
29412
29413 ' (64 bit integers
29414 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
29415
29416 \end_inset
29417
29418 ) not supported.
29419 \layout Itemize
29420
29421 'double
29422 \begin_inset LatexCommand \index{double (not supported)}
29423
29424 \end_inset
29425
29426 ' precision floating point
29427 \begin_inset LatexCommand \index{Floating point support}
29428
29429 \end_inset
29430
29431 not supported.
29432 \layout Itemize
29433
29434 Old K&R style
29435 \begin_inset LatexCommand \index{K\&R style}
29436
29437 \end_inset
29438
29439  function declarations are NOT allowed.
29440 \begin_deeper
29441 \layout Verse
29442
29443
29444 \family typewriter
29445 foo(i,j) /* this old style of function declarations */
29446 \newline
29447 int i,j; /* are valid in ANSI but not valid in SDCC */
29448 \newline
29449 {
29450 \newline
29451 \SpecialChar ~
29452 \SpecialChar ~
29453 \SpecialChar ~
29454 \SpecialChar ~
29455 ...
29456
29457 \newline
29458 }
29459 \end_deeper
29460 \layout Itemize
29461
29462 Most enhancements in C99 are not supported, f.e.:
29463 \begin_deeper
29464 \layout Verse
29465
29466
29467 \family typewriter
29468 \series bold
29469 inline
29470 \begin_inset LatexCommand \index{inline (not supported)}
29471
29472 \end_inset
29473
29474
29475 \series default
29476  int increment (int a) { return a+1; } /* is invalid in SDCC although allowed
29477  in C99.
29478  An empty define
29479 \emph on
29480 #define inline
29481 \emph default
29482  can be used as a work around */
29483 \newline
29484
29485 \newline
29486 for (
29487 \series bold
29488 int
29489 \series default
29490  i=0; i<10; i++) /* is invalid in SDCC although allowed in C99 */
29491 \end_deeper
29492 \layout Itemize
29493
29494 Certain words that are valid identifiers in the standard may be reserved
29495  words in SDCC unless the
29496 \series bold
29497 -
29498 \begin_inset ERT
29499 status Collapsed
29500
29501 \layout Standard
29502
29503 \backslash
29504 /
29505 \end_inset
29506
29507 -std-c89
29508 \begin_inset LatexCommand \index{-\/-std-c89}
29509
29510 \end_inset
29511
29512  or -
29513 \begin_inset ERT
29514 status Collapsed
29515
29516 \layout Standard
29517
29518 \backslash
29519 /
29520 \end_inset
29521
29522 -std-c99
29523 \begin_inset LatexCommand \index{-\/-std-c99}
29524
29525 \end_inset
29526
29527
29528 \series default
29529  command line options are used.
29530  These may include (depending on the selected processor): 'at', 'banked',
29531  'bit', 'code', 'critical', 'data', 'eeprom', 'far', 'flash', 'idata', 'interrup
29532 t', 'near', 'nonbanked', 'pdata', 'reentrant', 'sbit', 'sfr', 'shadowregs',
29533  'sram', 'using', 'wparam', 'xdata', '_overlay', '_asm', '_endasm', and
29534  '_naked'.
29535  Compliant equivalents of these keywords are always available in a form
29536  that begin with two underscores
29537 \begin_inset LatexCommand \index{\_\_ (prefix for extended keywords)}
29538
29539 \end_inset
29540
29541 , f.e.
29542  '__data' instead of 'data'.
29543 \layout Section
29544
29545 Cyclomatic Complexity
29546 \begin_inset LatexCommand \index{Cyclomatic complexity}
29547
29548 \end_inset
29549
29550
29551 \layout Standard
29552
29553 Cyclomatic complexity of a function is defined as the number of independent
29554  paths the program can take during execution of the function.
29555  This is an important number since it defines the number test cases you
29556  have to generate to validate the function.
29557  The accepted industry standard for complexity number is 10, if the cyclomatic
29558  complexity reported by SDCC exceeds 10 you should think about simplification
29559  of the function logic.
29560  Note that the complexity level is not related to the number of lines of
29561  code in a function.
29562  Large functions can have low complexity, and small functions can have large
29563  complexity levels.
29564
29565 \newline
29566
29567 \newline
29568 SDCC uses the following formula to compute the complexity:
29569 \newline
29570
29571 \layout Standard
29572
29573 complexity = (number of edges in control flow graph) - (number of nodes
29574  in control flow graph) + 2;
29575 \newline
29576
29577 \newline
29578 Having said that the industry standard is 10, you should be aware that in
29579  some cases it be may unavoidable to have a complexity level of less than
29580  10.
29581  For example if you have switch statement with more than 10 case labels,
29582  each case label adds one to the complexity level.
29583  The complexity level is by no means an absolute measure of the algorithmic
29584  complexity of the function, it does however provide a good starting point
29585  for which functions you might look at for further optimization.
29586 \layout Section
29587
29588 Retargetting for other Processors
29589 \layout Standard
29590
29591 The issues for retargetting the compiler are far too numerous to be covered
29592  by this document.
29593  What follows is a brief description of each of the seven phases of the
29594  compiler and its MCU dependency.
29595 \layout Itemize
29596
29597 Parsing the source and building the annotated parse tree.
29598  This phase is largely MCU independent (except for the language extensions).
29599  Syntax & semantic checks are also done in this phase, along with some initial
29600  optimizations like back patching labels and the pattern matching optimizations
29601  like bit-rotation etc.
29602 \layout Itemize
29603
29604 The second phase involves generating an intermediate code which can be easy
29605  manipulated during the later phases.
29606  This phase is entirely MCU independent.
29607  The intermediate code generation assumes the target machine has unlimited
29608  number of registers, and designates them with the name iTemp.
29609  The compiler can be made to dump a human readable form of the code generated
29610  by using the -
29611 \begin_inset ERT
29612 status Collapsed
29613
29614 \layout Standard
29615
29616 \backslash
29617 /
29618 \end_inset
29619
29620 -dumpraw option.
29621 \layout Itemize
29622
29623 This phase does the bulk of the standard optimizations and is also MCU independe
29624 nt.
29625  This phase can be broken down into several sub-phases:
29626 \newline
29627
29628 \newline
29629 Break down intermediate code (iCode) into basic blocks.
29630 \newline
29631 Do control flow & data flow analysis on the basic blocks.
29632 \newline
29633 Do local common subexpression elimination, then global subexpression elimination
29634 \newline
29635 Dead code elimination
29636 \newline
29637 Loop optimizations
29638 \newline
29639 If loop optimizations caused any changes then do 'global subexpression eliminati
29640 on' and 'dead code elimination' again.
29641 \layout Itemize
29642
29643 This phase determines the live-ranges; by live range I mean those iTemp
29644  variables defined by the compiler that still survive after all the optimization
29645 s.
29646  Live range analysis
29647 \begin_inset LatexCommand \index{Live range analysis}
29648
29649 \end_inset
29650
29651  is essential for register allocation, since these computation determines
29652  which of these iTemps will be assigned to registers, and for how long.
29653 \layout Itemize
29654
29655 Phase five is register allocation.
29656  There are two parts to this process.
29657 \newline
29658
29659 \newline
29660 The first part I call 'register packing' (for lack of a better term).
29661  In this case several MCU specific expression folding is done to reduce
29662  register pressure.
29663 \newline
29664
29665 \newline
29666 The second part is more MCU independent and deals with allocating registers
29667  to the remaining live ranges.
29668  A lot of MCU specific code does creep into this phase because of the limited
29669  number of index registers available in the 8051.
29670 \layout Itemize
29671
29672 The Code generation phase is (unhappily), entirely MCU dependent and very
29673  little (if any at all) of this code can be reused for other MCU.
29674  However the scheme for allocating a homogenized assembler operand for each
29675  iCode operand may be reused.
29676 \layout Itemize
29677
29678 As mentioned in the optimization section the peep-hole optimizer is rule
29679  based system, which can reprogrammed for other MCUs.
29680 \layout Standard
29681
29682 More information is available in a wiki
29683 \begin_inset LatexCommand \index{wiki}
29684
29685 \end_inset
29686
29687  (preliminary link
29688 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/release_wiki/index.php?page=SDCC+internals+and+porting}
29689
29690 \end_inset
29691
29692 ) and in the thread
29693 \begin_inset LatexCommand \url{http://sf.net/mailarchive/message.php?msg_id=13954144}
29694
29695 \end_inset
29696
29697  .
29698 \layout Chapter
29699
29700 Compiler internals
29701 \begin_inset LatexCommand \index{Compiler internals}
29702
29703 \end_inset
29704
29705
29706 \layout Section
29707
29708 The anatomy of the compiler
29709 \begin_inset LatexCommand \label{sub:The-anatomy-of}
29710
29711 \end_inset
29712
29713
29714 \layout Standard
29715
29716
29717 \shape italic
29718 This is an excerpt from an article published in Circuit Cellar Magazine
29719  in
29720 \series bold
29721 August 2000
29722 \series default
29723 .
29724  It's a little outdated (the compiler is much more efficient now and user/develo
29725 per friendly), but pretty well exposes the guts of it all.
29726 \shape default
29727
29728 \newline
29729
29730 \newline
29731 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
29732  It is fairly easy to retarget for other 8-bit MCU.
29733  Here we take a look at some of the internals of the compiler.
29734
29735 \layout Paragraph*
29736
29737 Parsing
29738 \begin_inset LatexCommand \index{Parsing}
29739
29740 \end_inset
29741
29742
29743 \layout Standard
29744
29745 Parsing the input source file and creating an AST (Annotated Syntax Tree
29746 \begin_inset LatexCommand \index{Annotated syntax tree}
29747
29748 \end_inset
29749
29750 ).
29751  This phase also involves propagating types (annotating each node of the
29752  parse tree with type information) and semantic analysis.
29753  There are some MCU specific parsing rules.
29754  For example the storage classes, the extended storage classes are MCU specific
29755  while there may be a xdata storage class for 8051 there is no such storage
29756  class for z80 or Atmel AVR.
29757  SDCC allows MCU specific storage class extensions, i.e.
29758  xdata will be treated as a storage class specifier when parsing 8051 C
29759  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
29760  C code.
29761 \layout Paragraph*
29762
29763 Generating iCode
29764 \begin_inset LatexCommand \index{iCode}
29765
29766 \end_inset
29767
29768
29769 \layout Standard
29770
29771 Intermediate code generation.
29772  In this phase the AST is broken down into three-operand form (iCode).
29773  These three operand forms are represented as doubly linked lists.
29774  ICode is the term given to the intermediate form generated by the compiler.
29775  ICode example section shows some examples of iCode generated for some simple
29776  C source functions.
29777 \layout Paragraph*
29778
29779 Optimizations
29780 \begin_inset LatexCommand \index{Optimizations}
29781
29782 \end_inset
29783
29784 .
29785 \layout Standard
29786
29787 Bulk of the target independent optimizations is performed in this phase.
29788  The optimizations include constant propagation, common sub-expression eliminati
29789 on, loop invariant code movement, strength reduction of loop induction variables
29790  and dead-code elimination.
29791 \layout Paragraph*
29792
29793 Live range analysis
29794 \begin_inset LatexCommand \index{Live range analysis}
29795
29796 \end_inset
29797
29798
29799 \layout Standard
29800
29801 During intermediate code generation phase, the compiler assumes the target
29802  machine has infinite number of registers and generates a lot of temporary
29803  variables.
29804  The live range computation determines the lifetime of each of these compiler-ge
29805 nerated temporaries.
29806  A picture speaks a thousand words.
29807  ICode example sections show the live range annotations for each of the
29808  operand.
29809  It is important to note here, each iCode is assigned a number in the order
29810  of its execution in the function.
29811  The live ranges are computed in terms of these numbers.
29812  The from number is the number of the iCode which first defines the operand
29813  and the to number signifies the iCode which uses this operand last.
29814 \layout Paragraph*
29815
29816 Register Allocation
29817 \begin_inset LatexCommand \index{Register allocation}
29818
29819 \end_inset
29820
29821
29822 \layout Standard
29823
29824 The register allocation determines the type and number of registers needed
29825  by each operand.
29826  In most MCUs only a few registers can be used for indirect addressing.
29827  In case of 8051 for example the registers R0 & R1 can be used to indirectly
29828  address the internal ram and DPTR to indirectly address the external ram.
29829  The compiler will try to allocate the appropriate register to pointer variables
29830  if it can.
29831  ICode example section shows the operands annotated with the registers assigned
29832  to them.
29833  The compiler will try to keep operands in registers as much as possible;
29834  there are several schemes the compiler uses to do achieve this.
29835  When the compiler runs out of registers the compiler will check to see
29836  if there are any live operands which is not used or defined in the current
29837  basic block being processed, if there are any found then it will push that
29838  operand and use the registers in this block, the operand will then be popped
29839  at the end of the basic block.
29840
29841 \layout Standard
29842
29843 There are other MCU specific considerations in this phase.
29844  Some MCUs have an accumulator; very short-lived operands could be assigned
29845  to the accumulator instead of a general-purpose register.
29846 \layout Paragraph*
29847
29848 Code generation
29849 \layout Standard
29850
29851 Figure II gives a table of iCode
29852 \begin_inset LatexCommand \index{iCode}
29853
29854 \end_inset
29855
29856  operations supported by the compiler.
29857  The code generation involves translating these operations into corresponding
29858  assembly code for the processor.
29859  This sounds overly simple but that is the essence of code generation.
29860  Some of the iCode operations are generated on a MCU specific manner for
29861  example, the z80 port does not use registers to pass parameters so the
29862  SEND and RECV iCode operations will not be generated, and it also does
29863  not support JUMPTABLES.
29864
29865 \newline
29866
29867 \layout Standard
29868
29869
29870 \size footnotesize
29871 Figure II
29872 \begin_inset  Tabular
29873 <lyxtabular version="3" rows="39" columns="4">
29874 <features islongtable="true" headBottomDL="true">
29875 <column alignment="block" valignment="top" leftline="true" width="13col%">
29876 <column alignment="left" valignment="top" leftline="true" width="13col%">
29877 <column alignment="block" valignment="top" leftline="true" width="22col%">
29878 <column alignment="block" valignment="top" leftline="true" rightline="true" width="40col%">
29879 <row topline="true" bottomline="true" endhead="true">
29880 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29881 \begin_inset Text
29882
29883 \layout Standard
29884
29885
29886 \series bold
29887 iCode
29888 \series default
29889
29890 \begin_inset LatexCommand \index{iCode}
29891
29892 \end_inset
29893
29894
29895 \end_inset
29896 </cell>
29897 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29898 \begin_inset Text
29899
29900 \layout Standard
29901
29902
29903 \series bold
29904 Operands
29905 \end_inset
29906 </cell>
29907 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29908 \begin_inset Text
29909
29910 \layout Standard
29911
29912
29913 \series bold
29914 Description
29915 \end_inset
29916 </cell>
29917 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29918 \begin_inset Text
29919
29920 \layout Standard
29921
29922
29923 \series bold
29924 C Equivalent
29925 \end_inset
29926 </cell>
29927 </row>
29928 <row topline="true">
29929 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29930 \begin_inset Text
29931
29932 \layout Standard
29933
29934
29935 \size footnotesize
29936 '!'
29937 \end_inset
29938 </cell>
29939 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29940 \begin_inset Text
29941
29942 \layout Standard
29943
29944
29945 \size footnotesize
29946 IC_LEFT() IC_RESULT()
29947 \end_inset
29948 </cell>
29949 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29950 \begin_inset Text
29951
29952 \layout Standard
29953
29954
29955 \size footnotesize
29956 NOT operation
29957 \end_inset
29958 </cell>
29959 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29960 \begin_inset Text
29961
29962 \layout Standard
29963
29964
29965 \size footnotesize
29966 IC_RESULT = ! IC_LEFT;
29967 \end_inset
29968 </cell>
29969 </row>
29970 <row topline="true">
29971 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29972 \begin_inset Text
29973
29974 \layout Standard
29975
29976
29977 \size footnotesize
29978 '~'
29979 \end_inset
29980 </cell>
29981 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29982 \begin_inset Text
29983
29984 \layout Standard
29985
29986
29987 \size footnotesize
29988 IC_LEFT() IC_RESULT()
29989 \end_inset
29990 </cell>
29991 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29992 \begin_inset Text
29993
29994 \layout Standard
29995
29996
29997 \size footnotesize
29998 Bitwise complement of
29999 \end_inset
30000 </cell>
30001 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30002 \begin_inset Text
30003
30004 \layout Standard
30005
30006
30007 \size footnotesize
30008 IC_RESULT = ~IC_LEFT;
30009 \end_inset
30010 </cell>
30011 </row>
30012 <row topline="true">
30013 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30014 \begin_inset Text
30015
30016 \layout Standard
30017
30018
30019 \size footnotesize
30020 RRC
30021 \end_inset
30022 </cell>
30023 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30024 \begin_inset Text
30025
30026 \layout Standard
30027
30028
30029 \size footnotesize
30030 IC_LEFT() IC_RESULT()
30031 \end_inset
30032 </cell>
30033 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30034 \begin_inset Text
30035
30036 \layout Standard
30037
30038
30039 \size footnotesize
30040 Rotate right with carry
30041 \end_inset
30042 </cell>
30043 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30044 \begin_inset Text
30045
30046 \layout Standard
30047
30048
30049 \size footnotesize
30050 IC_RESULT = (IC_LEFT << 1) | (IC_LEFT >> (sizeof(IC_LEFT)*8-1));
30051 \end_inset
30052 </cell>
30053 </row>
30054 <row topline="true">
30055 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30056 \begin_inset Text
30057
30058 \layout Standard
30059
30060
30061 \size footnotesize
30062 RLC
30063 \end_inset
30064 </cell>
30065 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30066 \begin_inset Text
30067
30068 \layout Standard
30069
30070
30071 \size footnotesize
30072 IC_LEFT() IC_RESULT()
30073 \end_inset
30074 </cell>
30075 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30076 \begin_inset Text
30077
30078 \layout Standard
30079
30080
30081 \size footnotesize
30082 Rotate left with carry
30083 \end_inset
30084 </cell>
30085 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30086 \begin_inset Text
30087
30088 \layout Standard
30089
30090
30091 \size footnotesize
30092 IC_RESULT = (IC_LEFT << (sizeof(LC_LEFT)*8-1) ) | (IC_LEFT >> 1);
30093 \end_inset
30094 </cell>
30095 </row>
30096 <row topline="true">
30097 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30098 \begin_inset Text
30099
30100 \layout Standard
30101
30102
30103 \size footnotesize
30104 GETHBIT
30105 \end_inset
30106 </cell>
30107 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30108 \begin_inset Text
30109
30110 \layout Standard
30111
30112
30113 \size footnotesize
30114 IC_LEFT() IC_RESULT()
30115 \end_inset
30116 </cell>
30117 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30118 \begin_inset Text
30119
30120 \layout Standard
30121
30122
30123 \size footnotesize
30124 Get the highest order bit of IC_LEFT
30125 \end_inset
30126 </cell>
30127 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30128 \begin_inset Text
30129
30130 \layout Standard
30131
30132
30133 \size footnotesize
30134 IC_RESULT = (IC_LEFT >> (sizeof(IC_LEFT)*8 -1));
30135 \end_inset
30136 </cell>
30137 </row>
30138 <row topline="true">
30139 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30140 \begin_inset Text
30141
30142 \layout Standard
30143
30144
30145 \size footnotesize
30146 UNARYMINUS
30147 \end_inset
30148 </cell>
30149 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30150 \begin_inset Text
30151
30152 \layout Standard
30153
30154
30155 \size footnotesize
30156 IC_LEFT() IC_RESULT()
30157 \end_inset
30158 </cell>
30159 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30160 \begin_inset Text
30161
30162 \layout Standard
30163
30164
30165 \size footnotesize
30166 Unary minus
30167 \end_inset
30168 </cell>
30169 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30170 \begin_inset Text
30171
30172 \layout Standard
30173
30174
30175 \size footnotesize
30176 IC_RESULT = - IC_LEFT;
30177 \end_inset
30178 </cell>
30179 </row>
30180 <row topline="true">
30181 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30182 \begin_inset Text
30183
30184 \layout Standard
30185
30186
30187 \size footnotesize
30188 IPUSH
30189 \end_inset
30190 </cell>
30191 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30192 \begin_inset Text
30193
30194 \layout Standard
30195
30196
30197 \size footnotesize
30198 IC_LEFT()
30199 \end_inset
30200 </cell>
30201 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30202 \begin_inset Text
30203
30204 \layout Standard
30205
30206
30207 \size footnotesize
30208 Push the operand into stack
30209 \end_inset
30210 </cell>
30211 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30212 \begin_inset Text
30213
30214 \layout Standard
30215
30216
30217 \size footnotesize
30218 NONE
30219 \end_inset
30220 </cell>
30221 </row>
30222 <row topline="true">
30223 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30224 \begin_inset Text
30225
30226 \layout Standard
30227
30228
30229 \size footnotesize
30230 IPOP
30231 \end_inset
30232 </cell>
30233 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30234 \begin_inset Text
30235
30236 \layout Standard
30237
30238
30239 \size footnotesize
30240 IC_LEFT()
30241 \end_inset
30242 </cell>
30243 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30244 \begin_inset Text
30245
30246 \layout Standard
30247
30248
30249 \size footnotesize
30250 Pop the operand from the stack
30251 \end_inset
30252 </cell>
30253 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30254 \begin_inset Text
30255
30256 \layout Standard
30257
30258
30259 \size footnotesize
30260 NONE
30261 \end_inset
30262 </cell>
30263 </row>
30264 <row topline="true">
30265 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30266 \begin_inset Text
30267
30268 \layout Standard
30269
30270
30271 \size footnotesize
30272 CALL
30273 \end_inset
30274 </cell>
30275 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30276 \begin_inset Text
30277
30278 \layout Standard
30279
30280
30281 \size footnotesize
30282 IC_LEFT() IC_RESULT()
30283 \end_inset
30284 </cell>
30285 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30286 \begin_inset Text
30287
30288 \layout Standard
30289
30290
30291 \size footnotesize
30292 Call the function represented by IC_LEFT
30293 \end_inset
30294 </cell>
30295 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30296 \begin_inset Text
30297
30298 \layout Standard
30299
30300
30301 \size footnotesize
30302 IC_RESULT = IC_LEFT();
30303 \end_inset
30304 </cell>
30305 </row>
30306 <row topline="true">
30307 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30308 \begin_inset Text
30309
30310 \layout Standard
30311
30312
30313 \size footnotesize
30314 PCALL
30315 \end_inset
30316 </cell>
30317 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30318 \begin_inset Text
30319
30320 \layout Standard
30321
30322
30323 \size footnotesize
30324 IC_LEFT() IC_RESULT()
30325 \end_inset
30326 </cell>
30327 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30328 \begin_inset Text
30329
30330 \layout Standard
30331
30332
30333 \size footnotesize
30334 Call via function pointer
30335 \end_inset
30336 </cell>
30337 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30338 \begin_inset Text
30339
30340 \layout Standard
30341
30342
30343 \size footnotesize
30344 IC_RESULT = (*IC_LEFT)();
30345 \end_inset
30346 </cell>
30347 </row>
30348 <row topline="true">
30349 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30350 \begin_inset Text
30351
30352 \layout Standard
30353
30354
30355 \size footnotesize
30356 RETURN
30357 \end_inset
30358 </cell>
30359 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30360 \begin_inset Text
30361
30362 \layout Standard
30363
30364
30365 \size footnotesize
30366 IC_LEFT()
30367 \end_inset
30368 </cell>
30369 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30370 \begin_inset Text
30371
30372 \layout Standard
30373
30374
30375 \size footnotesize
30376 Return the value in operand IC_LEFT
30377 \end_inset
30378 </cell>
30379 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30380 \begin_inset Text
30381
30382 \layout Standard
30383
30384
30385 \size footnotesize
30386 return IC_LEFT;
30387 \end_inset
30388 </cell>
30389 </row>
30390 <row topline="true">
30391 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30392 \begin_inset Text
30393
30394 \layout Standard
30395
30396
30397 \size footnotesize
30398 LABEL
30399 \end_inset
30400 </cell>
30401 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30402 \begin_inset Text
30403
30404 \layout Standard
30405
30406
30407 \size footnotesize
30408 IC_LABEL()
30409 \end_inset
30410 </cell>
30411 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30412 \begin_inset Text
30413
30414 \layout Standard
30415
30416
30417 \size footnotesize
30418 Label
30419 \end_inset
30420 </cell>
30421 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30422 \begin_inset Text
30423
30424 \layout Standard
30425
30426
30427 \size footnotesize
30428 IC_LABEL:
30429 \end_inset
30430 </cell>
30431 </row>
30432 <row topline="true">
30433 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30434 \begin_inset Text
30435
30436 \layout Standard
30437
30438
30439 \size footnotesize
30440 GOTO
30441 \end_inset
30442 </cell>
30443 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30444 \begin_inset Text
30445
30446 \layout Standard
30447
30448
30449 \size footnotesize
30450 IC_LABEL()
30451 \end_inset
30452 </cell>
30453 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30454 \begin_inset Text
30455
30456 \layout Standard
30457
30458
30459 \size footnotesize
30460 Goto label
30461 \end_inset
30462 </cell>
30463 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30464 \begin_inset Text
30465
30466 \layout Standard
30467
30468
30469 \size footnotesize
30470 goto IC_LABEL();
30471 \end_inset
30472 </cell>
30473 </row>
30474 <row topline="true">
30475 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30476 \begin_inset Text
30477
30478 \layout Standard
30479
30480
30481 \size footnotesize
30482 '+'
30483 \end_inset
30484 </cell>
30485 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30486 \begin_inset Text
30487
30488 \layout Standard
30489
30490
30491 \size footnotesize
30492 IC_LEFT() IC_RIGHT() IC_RESULT()
30493 \end_inset
30494 </cell>
30495 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30496 \begin_inset Text
30497
30498 \layout Standard
30499
30500
30501 \size footnotesize
30502 Addition
30503 \end_inset
30504 </cell>
30505 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30506 \begin_inset Text
30507
30508 \layout Standard
30509
30510
30511 \size footnotesize
30512 IC_RESULT = IC_LEFT + IC_RIGHT
30513 \end_inset
30514 </cell>
30515 </row>
30516 <row topline="true">
30517 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30518 \begin_inset Text
30519
30520 \layout Standard
30521
30522
30523 \size footnotesize
30524 '-'
30525 \end_inset
30526 </cell>
30527 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30528 \begin_inset Text
30529
30530 \layout Standard
30531
30532
30533 \size footnotesize
30534 IC_LEFT() IC_RIGHT() IC_RESULT()
30535 \end_inset
30536 </cell>
30537 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30538 \begin_inset Text
30539
30540 \layout Standard
30541
30542
30543 \size footnotesize
30544 Subtraction
30545 \end_inset
30546 </cell>
30547 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30548 \begin_inset Text
30549
30550 \layout Standard
30551
30552
30553 \size footnotesize
30554 IC_RESULT = IC_LEFT - IC_RIGHT
30555 \end_inset
30556 </cell>
30557 </row>
30558 <row topline="true">
30559 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30560 \begin_inset Text
30561
30562 \layout Standard
30563
30564
30565 \size footnotesize
30566 '*'
30567 \end_inset
30568 </cell>
30569 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30570 \begin_inset Text
30571
30572 \layout Standard
30573
30574
30575 \size footnotesize
30576 IC_LEFT() IC_RIGHT() IC_RESULT()
30577 \end_inset
30578 </cell>
30579 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30580 \begin_inset Text
30581
30582 \layout Standard
30583
30584
30585 \size footnotesize
30586 Multiplication
30587 \end_inset
30588 </cell>
30589 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30590 \begin_inset Text
30591
30592 \layout Standard
30593
30594
30595 \size footnotesize
30596 IC_RESULT = IC_LEFT * IC_RIGHT;
30597 \end_inset
30598 </cell>
30599 </row>
30600 <row topline="true">
30601 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30602 \begin_inset Text
30603
30604 \layout Standard
30605
30606
30607 \size footnotesize
30608 '/'
30609 \end_inset
30610 </cell>
30611 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30612 \begin_inset Text
30613
30614 \layout Standard
30615
30616
30617 \size footnotesize
30618 IC_LEFT() IC_RIGHT() IC_RESULT()
30619 \end_inset
30620 </cell>
30621 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30622 \begin_inset Text
30623
30624 \layout Standard
30625
30626
30627 \size footnotesize
30628 Division
30629 \end_inset
30630 </cell>
30631 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30632 \begin_inset Text
30633
30634 \layout Standard
30635
30636
30637 \size footnotesize
30638 IC_RESULT = IC_LEFT / IC_RIGHT;
30639 \end_inset
30640 </cell>
30641 </row>
30642 <row topline="true">
30643 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30644 \begin_inset Text
30645
30646 \layout Standard
30647
30648
30649 \size footnotesize
30650 '%'
30651 \end_inset
30652 </cell>
30653 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30654 \begin_inset Text
30655
30656 \layout Standard
30657
30658
30659 \size footnotesize
30660 IC_LEFT() IC_RIGHT() IC_RESULT()
30661 \end_inset
30662 </cell>
30663 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30664 \begin_inset Text
30665
30666 \layout Standard
30667
30668
30669 \size footnotesize
30670 Modulus
30671 \end_inset
30672 </cell>
30673 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30674 \begin_inset Text
30675
30676 \layout Standard
30677
30678
30679 \size footnotesize
30680 IC_RESULT = IC_LEFT % IC_RIGHT;
30681 \end_inset
30682 </cell>
30683 </row>
30684 <row topline="true">
30685 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30686 \begin_inset Text
30687
30688 \layout Standard
30689
30690
30691 \size footnotesize
30692 '<'
30693 \end_inset
30694 </cell>
30695 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30696 \begin_inset Text
30697
30698 \layout Standard
30699
30700
30701 \size footnotesize
30702 IC_LEFT() IC_RIGHT() IC_RESULT()
30703 \end_inset
30704 </cell>
30705 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30706 \begin_inset Text
30707
30708 \layout Standard
30709
30710
30711 \size footnotesize
30712 Less than
30713 \end_inset
30714 </cell>
30715 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30716 \begin_inset Text
30717
30718 \layout Standard
30719
30720
30721 \size footnotesize
30722 IC_RESULT = IC_LEFT < IC_RIGHT;
30723 \end_inset
30724 </cell>
30725 </row>
30726 <row topline="true">
30727 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30728 \begin_inset Text
30729
30730 \layout Standard
30731
30732
30733 \size footnotesize
30734 '>'
30735 \end_inset
30736 </cell>
30737 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30738 \begin_inset Text
30739
30740 \layout Standard
30741
30742
30743 \size footnotesize
30744 IC_LEFT() IC_RIGHT() IC_RESULT()
30745 \end_inset
30746 </cell>
30747 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30748 \begin_inset Text
30749
30750 \layout Standard
30751
30752
30753 \size footnotesize
30754 Greater than
30755 \end_inset
30756 </cell>
30757 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30758 \begin_inset Text
30759
30760 \layout Standard
30761
30762
30763 \size footnotesize
30764 IC_RESULT = IC_LEFT > IC_RIGHT;
30765 \end_inset
30766 </cell>
30767 </row>
30768 <row topline="true">
30769 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30770 \begin_inset Text
30771
30772 \layout Standard
30773
30774
30775 \size footnotesize
30776 EQ_OP
30777 \end_inset
30778 </cell>
30779 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30780 \begin_inset Text
30781
30782 \layout Standard
30783
30784
30785 \size footnotesize
30786 IC_LEFT() IC_RIGHT() IC_RESULT()
30787 \end_inset
30788 </cell>
30789 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30790 \begin_inset Text
30791
30792 \layout Standard
30793
30794
30795 \size footnotesize
30796 Equal to
30797 \end_inset
30798 </cell>
30799 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30800 \begin_inset Text
30801
30802 \layout Standard
30803
30804
30805 \size footnotesize
30806 IC_RESULT = IC_LEFT == IC_RIGHT;
30807 \end_inset
30808 </cell>
30809 </row>
30810 <row topline="true">
30811 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30812 \begin_inset Text
30813
30814 \layout Standard
30815
30816
30817 \size footnotesize
30818 AND_OP
30819 \end_inset
30820 </cell>
30821 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30822 \begin_inset Text
30823
30824 \layout Standard
30825
30826
30827 \size footnotesize
30828 IC_LEFT() IC_RIGHT() IC_RESULT()
30829 \end_inset
30830 </cell>
30831 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30832 \begin_inset Text
30833
30834 \layout Standard
30835
30836
30837 \size footnotesize
30838 Logical and operation
30839 \end_inset
30840 </cell>
30841 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30842 \begin_inset Text
30843
30844 \layout Standard
30845
30846
30847 \size footnotesize
30848 IC_RESULT = IC_LEFT && IC_RIGHT;
30849 \end_inset
30850 </cell>
30851 </row>
30852 <row topline="true">
30853 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30854 \begin_inset Text
30855
30856 \layout Standard
30857
30858
30859 \size footnotesize
30860 OR_OP
30861 \end_inset
30862 </cell>
30863 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30864 \begin_inset Text
30865
30866 \layout Standard
30867
30868
30869 \size footnotesize
30870 IC_LEFT() IC_RIGHT() IC_RESULT()
30871 \end_inset
30872 </cell>
30873 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30874 \begin_inset Text
30875
30876 \layout Standard
30877
30878
30879 \size footnotesize
30880 Logical or operation
30881 \end_inset
30882 </cell>
30883 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30884 \begin_inset Text
30885
30886 \layout Standard
30887
30888
30889 \size footnotesize
30890 IC_RESULT = IC_LEFT || IC_RIGHT;
30891 \end_inset
30892 </cell>
30893 </row>
30894 <row topline="true">
30895 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30896 \begin_inset Text
30897
30898 \layout Standard
30899
30900
30901 \size footnotesize
30902 '^'
30903 \end_inset
30904 </cell>
30905 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30906 \begin_inset Text
30907
30908 \layout Standard
30909
30910
30911 \size footnotesize
30912 IC_LEFT() IC_RIGHT() IC_RESULT()
30913 \end_inset
30914 </cell>
30915 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30916 \begin_inset Text
30917
30918 \layout Standard
30919
30920
30921 \size footnotesize
30922 Exclusive OR
30923 \end_inset
30924 </cell>
30925 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30926 \begin_inset Text
30927
30928 \layout Standard
30929
30930
30931 \size footnotesize
30932 IC_RESULT = IC_LEFT ^ IC_RIGHT;
30933 \end_inset
30934 </cell>
30935 </row>
30936 <row topline="true">
30937 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30938 \begin_inset Text
30939
30940 \layout Standard
30941
30942
30943 \size footnotesize
30944 '|'
30945 \end_inset
30946 </cell>
30947 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30948 \begin_inset Text
30949
30950 \layout Standard
30951
30952
30953 \size footnotesize
30954 IC_LEFT() IC_RIGHT() IC_RESULT()
30955 \end_inset
30956 </cell>
30957 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30958 \begin_inset Text
30959
30960 \layout Standard
30961
30962
30963 \size footnotesize
30964 Bitwise OR
30965 \end_inset
30966 </cell>
30967 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30968 \begin_inset Text
30969
30970 \layout Standard
30971
30972
30973 \size footnotesize
30974 IC_RESULT = IC_LEFT | IC_RIGHT;
30975 \end_inset
30976 </cell>
30977 </row>
30978 <row topline="true">
30979 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30980 \begin_inset Text
30981
30982 \layout Standard
30983
30984
30985 \size footnotesize
30986 BITWISEAND
30987 \end_inset
30988 </cell>
30989 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30990 \begin_inset Text
30991
30992 \layout Standard
30993
30994
30995 \size footnotesize
30996 IC_LEFT() IC_RIGHT() IC_RESULT()
30997 \end_inset
30998 </cell>
30999 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31000 \begin_inset Text
31001
31002 \layout Standard
31003
31004
31005 \size footnotesize
31006 Bitwise AND
31007 \end_inset
31008 </cell>
31009 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31010 \begin_inset Text
31011
31012 \layout Standard
31013
31014
31015 \size footnotesize
31016 IC_RESULT = IC_LEFT & IC_RIGHT;
31017 \end_inset
31018 </cell>
31019 </row>
31020 <row topline="true">
31021 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31022 \begin_inset Text
31023
31024 \layout Standard
31025
31026
31027 \size footnotesize
31028 LEFT_OP
31029 \end_inset
31030 </cell>
31031 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31032 \begin_inset Text
31033
31034 \layout Standard
31035
31036
31037 \size footnotesize
31038 IC_LEFT() IC_RIGHT() IC_RESULT()
31039 \end_inset
31040 </cell>
31041 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31042 \begin_inset Text
31043
31044 \layout Standard
31045
31046
31047 \size footnotesize
31048 Left shift
31049 \end_inset
31050 </cell>
31051 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31052 \begin_inset Text
31053
31054 \layout Standard
31055
31056
31057 \size footnotesize
31058 IC_RESULT = IC_LEFT << IC_RIGHT
31059 \end_inset
31060 </cell>
31061 </row>
31062 <row topline="true">
31063 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31064 \begin_inset Text
31065
31066 \layout Standard
31067
31068
31069 \size footnotesize
31070 RIGHT_OP
31071 \end_inset
31072 </cell>
31073 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31074 \begin_inset Text
31075
31076 \layout Standard
31077
31078
31079 \size footnotesize
31080 IC_LEFT() IC_RIGHT() IC_RESULT()
31081 \end_inset
31082 </cell>
31083 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31084 \begin_inset Text
31085
31086 \layout Standard
31087
31088
31089 \size footnotesize
31090 Right shift
31091 \end_inset
31092 </cell>
31093 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31094 \begin_inset Text
31095
31096 \layout Standard
31097
31098
31099 \size footnotesize
31100 IC_RESULT = IC_LEFT >> IC_RIGHT
31101 \end_inset
31102 </cell>
31103 </row>
31104 <row topline="true">
31105 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31106 \begin_inset Text
31107
31108 \layout Standard
31109
31110
31111 \size footnotesize
31112 GET_VALUE_
31113 \newline
31114 AT_ ADDRESS
31115 \end_inset
31116 </cell>
31117 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31118 \begin_inset Text
31119
31120 \layout Standard
31121
31122
31123 \size footnotesize
31124 IC_LEFT() IC_RESULT()
31125 \end_inset
31126 </cell>
31127 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31128 \begin_inset Text
31129
31130 \layout Standard
31131
31132
31133 \size footnotesize
31134 Indirect fetch
31135 \end_inset
31136 </cell>
31137 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31138 \begin_inset Text
31139
31140 \layout Standard
31141
31142
31143 \size footnotesize
31144 IC_RESULT = (*IC_LEFT);
31145 \end_inset
31146 </cell>
31147 </row>
31148 <row topline="true">
31149 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31150 \begin_inset Text
31151
31152 \layout Standard
31153
31154
31155 \size footnotesize
31156 POINTER_SET
31157 \end_inset
31158 </cell>
31159 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31160 \begin_inset Text
31161
31162 \layout Standard
31163
31164
31165 \size footnotesize
31166 IC_RIGHT() IC_RESULT()
31167 \end_inset
31168 </cell>
31169 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31170 \begin_inset Text
31171
31172 \layout Standard
31173
31174
31175 \size footnotesize
31176 Indirect set
31177 \end_inset
31178 </cell>
31179 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31180 \begin_inset Text
31181
31182 \layout Standard
31183
31184
31185 \size footnotesize
31186 (*IC_RESULT) = IC_RIGHT;
31187 \end_inset
31188 </cell>
31189 </row>
31190 <row topline="true">
31191 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31192 \begin_inset Text
31193
31194 \layout Standard
31195
31196
31197 \size footnotesize
31198 '='
31199 \end_inset
31200 </cell>
31201 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31202 \begin_inset Text
31203
31204 \layout Standard
31205
31206
31207 \size footnotesize
31208 IC_RIGHT() IC_RESULT()
31209 \end_inset
31210 </cell>
31211 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31212 \begin_inset Text
31213
31214 \layout Standard
31215
31216
31217 \size footnotesize
31218 Assignment
31219 \end_inset
31220 </cell>
31221 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31222 \begin_inset Text
31223
31224 \layout Standard
31225
31226
31227 \size footnotesize
31228 IC_RESULT = IC_RIGHT;
31229 \end_inset
31230 </cell>
31231 </row>
31232 <row topline="true">
31233 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31234 \begin_inset Text
31235
31236 \layout Standard
31237
31238
31239 \size footnotesize
31240 IFX
31241 \end_inset
31242 </cell>
31243 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31244 \begin_inset Text
31245
31246 \layout Standard
31247
31248
31249 \size footnotesize
31250 IC_COND IC_TRUE IC_LABEL
31251 \end_inset
31252 </cell>
31253 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31254 \begin_inset Text
31255
31256 \layout Standard
31257
31258
31259 \size footnotesize
31260 Conditional jump.
31261  If true label is present then jump to true label if condition is true else
31262  jump to false label if condition is false
31263 \end_inset
31264 </cell>
31265 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31266 \begin_inset Text
31267
31268 \layout Standard
31269
31270
31271 \size footnotesize
31272 if (IC_COND) goto IC_TRUE;
31273 \newline
31274 \SpecialChar ~
31275 \SpecialChar ~
31276 Or
31277 \newline
31278 If (!IC_COND) goto IC_FALSE;
31279 \end_inset
31280 </cell>
31281 </row>
31282 <row topline="true">
31283 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31284 \begin_inset Text
31285
31286 \layout Standard
31287
31288
31289 \size footnotesize
31290 ADDRESS_OF
31291 \end_inset
31292 </cell>
31293 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31294 \begin_inset Text
31295
31296 \layout Standard
31297
31298
31299 \size footnotesize
31300 IC_LEFT() IC_RESULT()
31301 \end_inset
31302 </cell>
31303 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31304 \begin_inset Text
31305
31306 \layout Standard
31307
31308
31309 \size footnotesize
31310 Address of
31311 \end_inset
31312 </cell>
31313 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31314 \begin_inset Text
31315
31316 \layout Standard
31317
31318
31319 \size footnotesize
31320 IC_RESULT = &IC_LEFT();
31321 \end_inset
31322 </cell>
31323 </row>
31324 <row topline="true">
31325 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31326 \begin_inset Text
31327
31328 \layout Standard
31329
31330
31331 \size footnotesize
31332 JUMPTABLE
31333 \end_inset
31334 </cell>
31335 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31336 \begin_inset Text
31337
31338 \layout Standard
31339
31340
31341 \size footnotesize
31342 IC_JTCOND IC_JTLABELS
31343 \end_inset
31344 </cell>
31345 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31346 \begin_inset Text
31347
31348 \layout Standard
31349
31350
31351 \size footnotesize
31352 Jump to list of labels depending on the value of JTCOND
31353 \end_inset
31354 </cell>
31355 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31356 \begin_inset Text
31357
31358 \layout Standard
31359
31360
31361 \size footnotesize
31362 Switch statement
31363 \end_inset
31364 </cell>
31365 </row>
31366 <row topline="true">
31367 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31368 \begin_inset Text
31369
31370 \layout Standard
31371
31372
31373 \size footnotesize
31374 CAST
31375 \end_inset
31376 </cell>
31377 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31378 \begin_inset Text
31379
31380 \layout Standard
31381
31382
31383 \size footnotesize
31384 IC_RIGHT() IC_LEFT() IC_RESULT()
31385 \end_inset
31386 </cell>
31387 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31388 \begin_inset Text
31389
31390 \layout Standard
31391
31392
31393 \size footnotesize
31394 Cast types
31395 \end_inset
31396 </cell>
31397 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31398 \begin_inset Text
31399
31400 \layout Standard
31401
31402
31403 \size footnotesize
31404 IC_RESULT = (typeof IC_LEFT) IC_RIGHT;
31405 \end_inset
31406 </cell>
31407 </row>
31408 <row topline="true">
31409 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31410 \begin_inset Text
31411
31412 \layout Standard
31413
31414
31415 \size footnotesize
31416 SEND
31417 \end_inset
31418 </cell>
31419 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31420 \begin_inset Text
31421
31422 \layout Standard
31423
31424
31425 \size footnotesize
31426 IC_LEFT()
31427 \end_inset
31428 </cell>
31429 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31430 \begin_inset Text
31431
31432 \layout Standard
31433
31434
31435 \size footnotesize
31436 This is used for passing parameters in registers;
31437 \newline
31438 move IC_LEFT to the next available parameter register.
31439 \end_inset
31440 </cell>
31441 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31442 \begin_inset Text
31443
31444 \layout Standard
31445
31446
31447 \size footnotesize
31448 None
31449 \end_inset
31450 </cell>
31451 </row>
31452 <row topline="true">
31453 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31454 \begin_inset Text
31455
31456 \layout Standard
31457
31458
31459 \size footnotesize
31460 RECV
31461 \end_inset
31462 </cell>
31463 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31464 \begin_inset Text
31465
31466 \layout Standard
31467
31468
31469 \size footnotesize
31470 IC_RESULT()
31471 \end_inset
31472 </cell>
31473 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31474 \begin_inset Text
31475
31476 \layout Standard
31477
31478
31479 \size footnotesize
31480 This is used for receiving parameters passed in registers;
31481 \newline
31482 Move the values in the next parameter register to IC_RESULT
31483 \end_inset
31484 </cell>
31485 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31486 \begin_inset Text
31487
31488 \layout Standard
31489
31490
31491 \size footnotesize
31492 None
31493 \end_inset
31494 </cell>
31495 </row>
31496 <row topline="true" bottomline="true">
31497 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31498 \begin_inset Text
31499
31500 \layout Standard
31501
31502
31503 \shape slanted
31504 \size footnotesize
31505 (some more have been added)
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 \end_inset
31514 </cell>
31515 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31516 \begin_inset Text
31517
31518 \layout Standard
31519
31520 \end_inset
31521 </cell>
31522 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31523 \begin_inset Text
31524
31525 \layout Standard
31526
31527
31528 \shape slanted
31529 \size footnotesize
31530 see f.e.
31531
31532 \family typewriter
31533 gen51Code()
31534 \family default
31535  in
31536 \family typewriter
31537 src/mcs51/gen.c
31538 \end_inset
31539 </cell>
31540 </row>
31541 </lyxtabular>
31542
31543 \end_inset
31544
31545
31546 \layout Comment
31547
31548 In the original article Figure II was announced to be downloadable on
31549 \shape italic
31550 Circuit Cellar
31551 \shape default
31552 's web site.
31553  ftp://ftp.circuitcellar.com/pub/Circuit_Cellar/2000/121/dutta.ZIP
31554 \layout Paragraph*
31555
31556 ICode Example
31557 \begin_inset LatexCommand \index{iCode}
31558
31559 \end_inset
31560
31561
31562 \layout Standard
31563
31564 This section shows some details of iCode.
31565  The example C code does not do anything useful; it is used as an example
31566  to illustrate the intermediate code generated by the compiler.
31567 \layout Verse
31568
31569
31570 \family typewriter
31571 1.\SpecialChar ~
31572 xdata int * p;
31573 \newline
31574 2.\SpecialChar ~
31575 int gint;
31576 \newline
31577 3.\SpecialChar ~
31578 /* This function does nothing useful.
31579  It is used
31580 \newline
31581 4.\SpecialChar ~
31582 \SpecialChar ~
31583 \SpecialChar ~
31584 \SpecialChar ~
31585 for the purpose of explaining iCode */
31586 \newline
31587 5.\SpecialChar ~
31588 short function (data int *x)
31589 \newline
31590 6.\SpecialChar ~
31591 {
31592 \newline
31593 7.\SpecialChar ~
31594 \SpecialChar ~
31595 \SpecialChar ~
31596 short i=10; \SpecialChar ~
31597 \SpecialChar ~
31598 /* dead initialization eliminated */
31599 \newline
31600 8.\SpecialChar ~
31601 \SpecialChar ~
31602 \SpecialChar ~
31603 short sum=10; /* dead initialization eliminated */
31604 \newline
31605 9.\SpecialChar ~
31606 \SpecialChar ~
31607 \SpecialChar ~
31608 short mul;
31609 \newline
31610 10.\SpecialChar ~
31611 \SpecialChar ~
31612 int j ;
31613 \newline
31614 11.\SpecialChar ~
31615 \SpecialChar ~
31616 while (*x) *x++ = *p++;
31617 \newline
31618 12.\SpecialChar ~
31619 \SpecialChar ~
31620 \SpecialChar ~
31621 \SpecialChar ~
31622 sum = 0 ;
31623 \newline
31624 13.\SpecialChar ~
31625 \SpecialChar ~
31626 mul = 0;
31627 \newline
31628 14.\SpecialChar ~
31629 \SpecialChar ~
31630 /* compiler detects i,j to be induction variables */
31631 \newline
31632 15.\SpecialChar ~
31633 \SpecialChar ~
31634 for (i = 0, j = 10 ; i < 10 ; i++, j
31635 \family default
31636 -
31637 \begin_inset ERT
31638 status Collapsed
31639
31640 \layout Standard
31641
31642 \backslash
31643 /
31644 \end_inset
31645
31646 -
31647 \family typewriter
31648 ) {
31649 \newline
31650 16.\SpecialChar ~
31651 \SpecialChar ~
31652 \SpecialChar ~
31653 \SpecialChar ~
31654 sum += i;
31655 \newline
31656 17.\SpecialChar ~
31657 \SpecialChar ~
31658 \SpecialChar ~
31659 \SpecialChar ~
31660 mul += i * 3; \SpecialChar ~
31661 \SpecialChar ~
31662 /* this multiplication remains */
31663 \newline
31664 18.\SpecialChar ~
31665 \SpecialChar ~
31666 \SpecialChar ~
31667 \SpecialChar ~
31668 gint += j * 3;\SpecialChar ~
31669 \SpecialChar ~
31670 /* this multiplication changed to addition */
31671 \newline
31672 19.\SpecialChar ~
31673 \SpecialChar ~
31674 }
31675 \newline
31676 20.\SpecialChar ~
31677 \SpecialChar ~
31678 return sum+mul;
31679 \newline
31680 21.\SpecialChar ~
31681 }
31682 \layout Standard
31683
31684 In addition to the operands each iCode contains information about the filename
31685  and line it corresponds to in the source file.
31686  The first field in the listing should be interpreted as follows:
31687 \newline
31688
31689 \shape italic
31690 \size footnotesize
31691 Filename(linenumber: iCode Execution sequence number : ICode hash table
31692  key : loop depth of the iCode).
31693 \shape default
31694 \size default
31695
31696 \newline
31697 Then follows the human readable form of the ICode operation.
31698  Each operand of this triplet form can be of three basic types a) compiler
31699  generated temporary b) user defined variable c) a constant value.
31700  Note that local variables and parameters are replaced by compiler generated
31701  temporaries.
31702  Live ranges
31703 \begin_inset LatexCommand \index{Live range analysis}
31704
31705 \end_inset
31706
31707  are computed only for temporaries (i.e.
31708  live ranges are not computed for global variables).
31709  Registers
31710 \begin_inset LatexCommand \index{Register allocation}
31711
31712 \end_inset
31713
31714  are allocated for temporaries only.
31715  Operands are formatted in the following manner:
31716 \newline
31717
31718 \shape italic
31719 \size footnotesize
31720 Operand Name [lr live-from : live-to ] { type information } [ registers
31721  allocated ].
31722 \shape default
31723 \size default
31724
31725 \newline
31726 As mentioned earlier the live ranges are computed in terms of the execution
31727  sequence number of the iCodes, for example
31728 \newline
31729 the iTemp0 is live from (i.e.
31730  first defined in iCode with execution sequence number 3, and is last used
31731  in the iCode with sequence number 5).
31732  For induction variables such as iTemp21 the live range computation extends
31733  the lifetime from the start to the end of the loop.
31734 \newline
31735 The register allocator used the live range information to allocate registers,
31736  the same registers may be used for different temporaries if their live
31737  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
31738  iTemp17 since their live ranges do not overlap.
31739  In addition the allocator also takes into consideration the type and usage
31740  of a temporary, for example itemp6 is a pointer to near space and is used
31741  as to fetch data from (i.e.
31742  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
31743  Some short lived temporaries are allocated to special registers which have
31744  meaning to the code generator e.g.
31745  iTemp13 is allocated to a pseudo register CC which tells the back end that
31746  the temporary is used only for a conditional jump the code generation makes
31747  use of this information to optimize a compare and jump ICode.
31748 \newline
31749 There are several loop optimizations
31750 \begin_inset LatexCommand \index{Loop optimization}
31751
31752 \end_inset
31753
31754  performed by the compiler.
31755  It can detect induction variables iTemp21(i) and iTemp23(j).
31756  Also note the compiler does selective strength reduction
31757 \begin_inset LatexCommand \index{Strength reduction}
31758
31759 \end_inset
31760
31761 , i.e.
31762  the multiplication of an induction variable in line 18 (gint = j * 3) is
31763  changed to addition, a new temporary iTemp17 is allocated and assigned
31764  a initial value, a constant 3 is then added for each iteration of the loop.
31765  The compiler does not change the multiplication
31766 \begin_inset LatexCommand \index{Multiplication}
31767
31768 \end_inset
31769
31770  in line 17 however since the processor does support an 8 * 8 bit multiplication.
31771 \newline
31772 Note the dead code elimination
31773 \begin_inset LatexCommand \index{Dead-code elimination}
31774
31775 \end_inset
31776
31777  optimization eliminated the dead assignments in line 7 & 8 to I and sum
31778  respectively.
31779 \newline
31780
31781 \layout Standard
31782
31783
31784 \size footnotesize
31785 Sample.c (5:1:0:0) _entry($9) :
31786 \layout Standard
31787
31788
31789 \size footnotesize
31790 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
31791 \layout Standard
31792
31793
31794 \size footnotesize
31795 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
31796 \layout Standard
31797
31798
31799 \size footnotesize
31800 Sample.c(11:4:53:0) preHeaderLbl0($11) :
31801 \layout Standard
31802
31803
31804 \size footnotesize
31805 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
31806  * int}[r2]
31807 \layout Standard
31808
31809
31810 \size footnotesize
31811 Sample.c(11:6:5:1) _whilecontinue_0($1) :
31812 \layout Standard
31813
31814
31815 \size footnotesize
31816 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
31817  int}[r0]]
31818 \layout Standard
31819
31820
31821 \size footnotesize
31822 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
31823 \layout Standard
31824
31825
31826 \size footnotesize
31827 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
31828  * int}
31829 \layout Standard
31830
31831
31832 \size footnotesize
31833 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
31834  {short}
31835 \layout Standard
31836
31837
31838 \size footnotesize
31839 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
31840  * int}[DPTR]]
31841 \layout Standard
31842
31843
31844 \size footnotesize
31845 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
31846 }[r2 r3]
31847 \layout Standard
31848
31849
31850 \size footnotesize
31851 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
31852  * int}[r0] + 0x2 {short}
31853 \layout Standard
31854
31855
31856 \size footnotesize
31857 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
31858 \layout Standard
31859
31860
31861 \size footnotesize
31862 Sample.c(11:17:21:0)_whilebreak_0($3) :
31863 \layout Standard
31864
31865
31866 \size footnotesize
31867 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
31868 \layout Standard
31869
31870
31871 \size footnotesize
31872 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
31873 \layout Standard
31874
31875
31876 \size footnotesize
31877 Sample.c(15:20:54:0)preHeaderLbl1($13) :
31878 \layout Standard
31879
31880
31881 \size footnotesize
31882 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
31883 \layout Standard
31884
31885
31886 \size footnotesize
31887 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
31888 \layout Standard
31889
31890
31891 \size footnotesize
31892 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
31893 \layout Standard
31894
31895
31896 \size footnotesize
31897 Sample.c(15:24:26:1)_forcond_0($4) :
31898 \layout Standard
31899
31900
31901 \size footnotesize
31902 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
31903  < 0xa {short}
31904 \layout Standard
31905
31906
31907 \size footnotesize
31908 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
31909 \layout Standard
31910
31911
31912 \size footnotesize
31913 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
31914  + ITemp21 [lr21:38]{short}[r4]
31915 \layout Standard
31916
31917
31918 \size footnotesize
31919 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
31920  * 0x3 {short}
31921 \layout Standard
31922
31923
31924 \size footnotesize
31925 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
31926  + iTemp15 [lr29:30]{short}[r1]
31927 \layout Standard
31928
31929
31930 \size footnotesize
31931 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
31932  r0]- 0x3 {short}
31933 \layout Standard
31934
31935
31936 \size footnotesize
31937 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
31938 int}[r7 r0]
31939 \layout Standard
31940
31941
31942 \size footnotesize
31943 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
31944  + 0x1 {short}
31945 \layout Standard
31946
31947
31948 \size footnotesize
31949 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
31950  r6]- 0x1 {short}
31951 \layout Standard
31952
31953
31954 \size footnotesize
31955 Sample.c(19:38:47:1) goto _forcond_0($4)
31956 \layout Standard
31957
31958
31959 \size footnotesize
31960 Sample.c(19:39:48:0)_forbreak_0($7) :
31961 \layout Standard
31962
31963
31964 \size footnotesize
31965 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
31966  + ITemp11 [lr19:40]{short}[r3]
31967 \layout Standard
31968
31969
31970 \size footnotesize
31971 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
31972 \layout Standard
31973
31974
31975 \size footnotesize
31976 Sample.c(20:42:51:0)_return($8) :
31977 \layout Standard
31978
31979
31980 \size footnotesize
31981 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
31982 \size default
31983
31984 \newline
31985
31986 \newline
31987 Finally the code generated for this function:
31988 \newline
31989
31990 \layout Standard
31991
31992
31993 \size footnotesize
31994 .area DSEG (DATA)
31995 \layout Standard
31996
31997
31998 \size footnotesize
31999 _p::
32000 \layout Standard
32001
32002
32003 \size footnotesize
32004 \SpecialChar ~
32005 \SpecialChar ~
32006 .ds 2
32007 \layout Standard
32008
32009
32010 \size footnotesize
32011 _gint::
32012 \layout Standard
32013
32014
32015 \size footnotesize
32016 \SpecialChar ~
32017 \SpecialChar ~
32018 .ds 2
32019 \layout Standard
32020
32021
32022 \size footnotesize
32023 ; sample.c 5
32024 \layout Standard
32025
32026
32027 \size footnotesize
32028 ; ----------------------------------------------
32029 \layout Standard
32030
32031
32032 \size footnotesize
32033 ; function function
32034 \layout Standard
32035
32036
32037 \size footnotesize
32038 ; ----------------------------------------------
32039 \layout Standard
32040
32041
32042 \size footnotesize
32043 _function:
32044 \layout Standard
32045
32046
32047 \size footnotesize
32048 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
32049 \layout Standard
32050
32051
32052 \size footnotesize
32053 \SpecialChar ~
32054 \SpecialChar ~
32055 mov r2,dpl
32056 \layout Standard
32057
32058
32059 \size footnotesize
32060 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
32061 \layout Standard
32062
32063
32064 \size footnotesize
32065 \SpecialChar ~
32066 \SpecialChar ~
32067 mov ar0,r2
32068 \layout Standard
32069
32070
32071 \size footnotesize
32072 ;_whilecontinue_0($1) :
32073 \layout Standard
32074
32075
32076 \size footnotesize
32077 00101$:
32078 \layout Standard
32079
32080
32081 \size footnotesize
32082 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
32083 \layout Standard
32084
32085
32086 \size footnotesize
32087 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
32088 \layout Standard
32089
32090
32091 \size footnotesize
32092 \SpecialChar ~
32093 \SpecialChar ~
32094 mov ar2,@r0
32095 \layout Standard
32096
32097
32098 \size footnotesize
32099 \SpecialChar ~
32100 \SpecialChar ~
32101 inc r0
32102 \layout Standard
32103
32104
32105 \size footnotesize
32106 \SpecialChar ~
32107 \SpecialChar ~
32108 mov ar3,@r0
32109 \layout Standard
32110
32111
32112 \size footnotesize
32113 \SpecialChar ~
32114 \SpecialChar ~
32115 dec r0
32116 \layout Standard
32117
32118
32119 \size footnotesize
32120 \SpecialChar ~
32121 \SpecialChar ~
32122 mov a,r2
32123 \layout Standard
32124
32125
32126 \size footnotesize
32127 \SpecialChar ~
32128 \SpecialChar ~
32129 orl a,r3
32130 \layout Standard
32131
32132
32133 \size footnotesize
32134 \SpecialChar ~
32135 \SpecialChar ~
32136 jz 00103$
32137 \layout Standard
32138
32139
32140 \size footnotesize
32141 00114$:
32142 \layout Standard
32143
32144
32145 \size footnotesize
32146 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
32147 \layout Standard
32148
32149
32150 \size footnotesize
32151 \SpecialChar ~
32152 \SpecialChar ~
32153 mov dpl,_p
32154 \layout Standard
32155
32156
32157 \size footnotesize
32158 \SpecialChar ~
32159 \SpecialChar ~
32160 mov dph,(_p + 1)
32161 \layout Standard
32162
32163
32164 \size footnotesize
32165 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
32166 \layout Standard
32167
32168
32169 \size footnotesize
32170 \SpecialChar ~
32171 \SpecialChar ~
32172 mov a,#0x02
32173 \layout Standard
32174
32175
32176 \size footnotesize
32177 \SpecialChar ~
32178 \SpecialChar ~
32179 add a,_p
32180 \layout Standard
32181
32182
32183 \size footnotesize
32184 \SpecialChar ~
32185 \SpecialChar ~
32186 mov _p,a
32187 \layout Standard
32188
32189
32190 \size footnotesize
32191 \SpecialChar ~
32192 \SpecialChar ~
32193 clr a
32194 \layout Standard
32195
32196
32197 \size footnotesize
32198 \SpecialChar ~
32199 \SpecialChar ~
32200 addc a,(_p + 1)
32201 \layout Standard
32202
32203
32204 \size footnotesize
32205 \SpecialChar ~
32206 \SpecialChar ~
32207 mov (_p + 1),a
32208 \layout Standard
32209
32210
32211 \size footnotesize
32212 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
32213 \layout Standard
32214
32215
32216 \size footnotesize
32217 \SpecialChar ~
32218 \SpecialChar ~
32219 movx a,@dptr
32220 \layout Standard
32221
32222
32223 \size footnotesize
32224 \SpecialChar ~
32225 \SpecialChar ~
32226 mov r2,a
32227 \layout Standard
32228
32229
32230 \size footnotesize
32231 \SpecialChar ~
32232 \SpecialChar ~
32233 inc dptr
32234 \layout Standard
32235
32236
32237 \size footnotesize
32238 \SpecialChar ~
32239 \SpecialChar ~
32240 movx a,@dptr
32241 \layout Standard
32242
32243
32244 \size footnotesize
32245 \SpecialChar ~
32246 \SpecialChar ~
32247 mov r3,a
32248 \layout Standard
32249
32250
32251 \size footnotesize
32252 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
32253 \layout Standard
32254
32255
32256 \size footnotesize
32257 \SpecialChar ~
32258 \SpecialChar ~
32259 mov @r0,ar2
32260 \layout Standard
32261
32262
32263 \size footnotesize
32264 \SpecialChar ~
32265 \SpecialChar ~
32266 inc r0
32267 \layout Standard
32268
32269
32270 \size footnotesize
32271 \SpecialChar ~
32272 \SpecialChar ~
32273 mov @r0,ar3
32274 \layout Standard
32275
32276
32277 \size footnotesize
32278 ; iTemp6 [lr5:16]{_near * int}[r0] =
32279 \layout Standard
32280
32281
32282 \size footnotesize
32283 ; iTemp6 [lr5:16]{_near * int}[r0] +
32284 \layout Standard
32285
32286
32287 \size footnotesize
32288 ; 0x2 {short}
32289 \layout Standard
32290
32291
32292 \size footnotesize
32293 \SpecialChar ~
32294 \SpecialChar ~
32295 inc r0
32296 \layout Standard
32297
32298
32299 \size footnotesize
32300 ; goto _whilecontinue_0($1)
32301 \layout Standard
32302
32303
32304 \size footnotesize
32305 \SpecialChar ~
32306 \SpecialChar ~
32307 sjmp 00101$
32308 \layout Standard
32309
32310
32311 \size footnotesize
32312 ; _whilebreak_0($3) :
32313 \layout Standard
32314
32315
32316 \size footnotesize
32317 00103$:
32318 \layout Standard
32319
32320
32321 \size footnotesize
32322 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
32323 \layout Standard
32324
32325
32326 \size footnotesize
32327 \SpecialChar ~
32328 \SpecialChar ~
32329 mov r2,#0x00
32330 \layout Standard
32331
32332
32333 \size footnotesize
32334 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
32335 \layout Standard
32336
32337
32338 \size footnotesize
32339 \SpecialChar ~
32340 \SpecialChar ~
32341 mov r3,#0x00
32342 \layout Standard
32343
32344
32345 \size footnotesize
32346 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
32347 \layout Standard
32348
32349
32350 \size footnotesize
32351 \SpecialChar ~
32352 \SpecialChar ~
32353 mov r4,#0x00
32354 \layout Standard
32355
32356
32357 \size footnotesize
32358 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
32359 \layout Standard
32360
32361
32362 \size footnotesize
32363 \SpecialChar ~
32364 \SpecialChar ~
32365 mov r5,#0x0A
32366 \layout Standard
32367
32368
32369 \size footnotesize
32370 \SpecialChar ~
32371 \SpecialChar ~
32372 mov r6,#0x00
32373 \layout Standard
32374
32375
32376 \size footnotesize
32377 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
32378 \layout Standard
32379
32380
32381 \size footnotesize
32382 \SpecialChar ~
32383 \SpecialChar ~
32384 mov r7,#0x1E
32385 \layout Standard
32386
32387
32388 \size footnotesize
32389 \SpecialChar ~
32390 \SpecialChar ~
32391 mov r0,#0x00
32392 \layout Standard
32393
32394
32395 \size footnotesize
32396 ; _forcond_0($4) :
32397 \layout Standard
32398
32399
32400 \size footnotesize
32401 00104$:
32402 \layout Standard
32403
32404
32405 \size footnotesize
32406 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
32407 \layout Standard
32408
32409
32410 \size footnotesize
32411 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
32412 \layout Standard
32413
32414
32415 \size footnotesize
32416 \SpecialChar ~
32417 \SpecialChar ~
32418 clr c
32419 \layout Standard
32420
32421
32422 \size footnotesize
32423 \SpecialChar ~
32424 \SpecialChar ~
32425 mov a,r4
32426 \layout Standard
32427
32428
32429 \size footnotesize
32430 \SpecialChar ~
32431 \SpecialChar ~
32432 xrl a,#0x80
32433 \layout Standard
32434
32435
32436 \size footnotesize
32437 \SpecialChar ~
32438 \SpecialChar ~
32439 subb a,#0x8a
32440 \layout Standard
32441
32442
32443 \size footnotesize
32444 \SpecialChar ~
32445 \SpecialChar ~
32446 jnc 00107$
32447 \layout Standard
32448
32449
32450 \size footnotesize
32451 00115$:
32452 \layout Standard
32453
32454
32455 \size footnotesize
32456 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
32457 \layout Standard
32458
32459
32460 \size footnotesize
32461 ; iTemp21 [lr21:38]{short}[r4]
32462 \layout Standard
32463
32464
32465 \size footnotesize
32466 \SpecialChar ~
32467 \SpecialChar ~
32468 mov a,r4
32469 \layout Standard
32470
32471
32472 \size footnotesize
32473 \SpecialChar ~
32474 \SpecialChar ~
32475 add a,r2
32476 \layout Standard
32477
32478
32479 \size footnotesize
32480 \SpecialChar ~
32481 \SpecialChar ~
32482 mov r2,a
32483 \layout Standard
32484
32485
32486 \size footnotesize
32487 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
32488 \layout Standard
32489
32490
32491 \size footnotesize
32492 \SpecialChar ~
32493 \SpecialChar ~
32494 mov b,#0x03
32495 \layout Standard
32496
32497
32498 \size footnotesize
32499 \SpecialChar ~
32500 \SpecialChar ~
32501 mov a,r4
32502 \layout Standard
32503
32504
32505 \size footnotesize
32506 \SpecialChar ~
32507 \SpecialChar ~
32508 mul ab
32509 \layout Standard
32510
32511
32512 \size footnotesize
32513 \SpecialChar ~
32514 \SpecialChar ~
32515 mov r1,a
32516 \layout Standard
32517
32518
32519 \size footnotesize
32520 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
32521 \layout Standard
32522
32523
32524 \size footnotesize
32525 ; iTemp15 [lr29:30]{short}[r1]
32526 \layout Standard
32527
32528
32529 \size footnotesize
32530 \SpecialChar ~
32531 \SpecialChar ~
32532 add a,r3
32533 \layout Standard
32534
32535
32536 \size footnotesize
32537 \SpecialChar ~
32538 \SpecialChar ~
32539 mov r3,a
32540 \layout Standard
32541
32542
32543 \size footnotesize
32544 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
32545 \layout Standard
32546
32547
32548 \size footnotesize
32549 \SpecialChar ~
32550 \SpecialChar ~
32551 mov a,r7
32552 \layout Standard
32553
32554
32555 \size footnotesize
32556 \SpecialChar ~
32557 \SpecialChar ~
32558 add a,#0xfd
32559 \layout Standard
32560
32561
32562 \size footnotesize
32563 \SpecialChar ~
32564 \SpecialChar ~
32565 mov r7,a
32566 \layout Standard
32567
32568
32569 \size footnotesize
32570 \SpecialChar ~
32571 \SpecialChar ~
32572 mov a,r0
32573 \layout Standard
32574
32575
32576 \size footnotesize
32577 \SpecialChar ~
32578 \SpecialChar ~
32579 addc a,#0xff
32580 \layout Standard
32581
32582
32583 \size footnotesize
32584 \SpecialChar ~
32585 \SpecialChar ~
32586 mov r0,a
32587 \layout Standard
32588
32589
32590 \size footnotesize
32591 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
32592 \layout Standard
32593
32594
32595 \size footnotesize
32596 \SpecialChar ~
32597 \SpecialChar ~
32598 mov a,r7
32599 \layout Standard
32600
32601
32602 \size footnotesize
32603 \SpecialChar ~
32604 \SpecialChar ~
32605 add a,_gint
32606 \layout Standard
32607
32608
32609 \size footnotesize
32610 \SpecialChar ~
32611 \SpecialChar ~
32612 mov _gint,a
32613 \layout Standard
32614
32615
32616 \size footnotesize
32617 \SpecialChar ~
32618 \SpecialChar ~
32619 mov a,r0
32620 \layout Standard
32621
32622
32623 \size footnotesize
32624 \SpecialChar ~
32625 \SpecialChar ~
32626 addc a,(_gint + 1)
32627 \layout Standard
32628
32629
32630 \size footnotesize
32631 \SpecialChar ~
32632 \SpecialChar ~
32633 mov (_gint + 1),a
32634 \layout Standard
32635
32636
32637 \size footnotesize
32638 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
32639 \layout Standard
32640
32641
32642 \size footnotesize
32643 \SpecialChar ~
32644 \SpecialChar ~
32645 inc r4
32646 \layout Standard
32647
32648
32649 \size footnotesize
32650 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
32651 \layout Standard
32652
32653
32654 \size footnotesize
32655 \SpecialChar ~
32656 \SpecialChar ~
32657 dec r5
32658 \layout Standard
32659
32660
32661 \size footnotesize
32662 \SpecialChar ~
32663 \SpecialChar ~
32664 cjne r5,#0xff,00104$
32665 \layout Standard
32666
32667
32668 \size footnotesize
32669 \SpecialChar ~
32670 \SpecialChar ~
32671 dec r6
32672 \layout Standard
32673
32674
32675 \size footnotesize
32676 ; goto _forcond_0($4)
32677 \layout Standard
32678
32679
32680 \size footnotesize
32681 \SpecialChar ~
32682 \SpecialChar ~
32683 sjmp 00104$
32684 \layout Standard
32685
32686
32687 \size footnotesize
32688 ; _forbreak_0($7) :
32689 \layout Standard
32690
32691
32692 \size footnotesize
32693 00107$:
32694 \layout Standard
32695
32696
32697 \size footnotesize
32698 ; ret iTemp24 [lr40:41]{short}
32699 \layout Standard
32700
32701
32702 \size footnotesize
32703 \SpecialChar ~
32704 \SpecialChar ~
32705 mov a,r3
32706 \layout Standard
32707
32708
32709 \size footnotesize
32710 \SpecialChar ~
32711 \SpecialChar ~
32712 add a,r2
32713 \layout Standard
32714
32715
32716 \size footnotesize
32717 \SpecialChar ~
32718 \SpecialChar ~
32719 mov dpl,a
32720 \layout Standard
32721
32722
32723 \size footnotesize
32724 ; _return($8) :
32725 \layout Standard
32726
32727
32728 \size footnotesize
32729 00108$:
32730 \layout Standard
32731
32732
32733 \size footnotesize
32734 \SpecialChar ~
32735 \SpecialChar ~
32736 ret
32737 \newline
32738
32739 \layout Section
32740
32741 A few words about basic block successors, predecessors and dominators
32742 \layout Standard
32743
32744 Successors are basic blocks
32745 \begin_inset LatexCommand \index{Basic blocks}
32746
32747 \end_inset
32748
32749  that might execute after this basic block.
32750 \newline
32751 Predecessors are basic blocks that might execute before reaching this basic
32752  block.
32753 \newline
32754 Dominators are basic blocks that WILL execute before reaching this basic
32755  block.
32756 \newline
32757
32758 \layout Standard
32759
32760 [basic block 1]
32761 \layout Standard
32762
32763 if (something)
32764 \layout Standard
32765
32766 \SpecialChar ~
32767 \SpecialChar ~
32768 \SpecialChar ~
32769 \SpecialChar ~
32770 [basic block 2]
32771 \layout Standard
32772
32773 else
32774 \layout Standard
32775
32776 \SpecialChar ~
32777 \SpecialChar ~
32778 \SpecialChar ~
32779 \SpecialChar ~
32780 [basic block 3]
32781 \layout Standard
32782
32783 [basic block 4]
32784 \newline
32785
32786 \layout Standard
32787
32788 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
32789 \layout Standard
32790
32791 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
32792 \layout Standard
32793
32794 c) domVect of [BB4] = BB1 ...
32795  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
32796  was executed.
32797 \layout Chapter
32798
32799 Acknowledgments
32800 \layout Standard
32801
32802
32803 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
32804
32805 \end_inset
32806
32807
32808 \newline
32809
32810 \newline
32811
32812 \emph on
32813 Thanks to all the other volunteer developers who have helped with coding,
32814  testing, web-page creation, distribution sets, etc.
32815  You know who you are :-)
32816 \emph default
32817
32818 \newline
32819
32820 \newline
32821
32822 \emph on
32823 Also thanks to Sourceforge
32824 \begin_inset LatexCommand \url{http://www.sf.net}
32825
32826 \end_inset
32827
32828  which has hosted the project since 1999 and donates significant download
32829  bandwidth and probably more than
32830 \begin_inset ERT
32831 status Collapsed
32832
32833 \layout Standard
32834 $10^{13}$
32835 \end_inset
32836
32837 CPU cycles per day.
32838 \newline
32839
32840 \begin_inset Note
32841 collapsed false
32842
32843 \layout Standard
32844
32845 more than 10^13 is an estimate: on my Athlon 2800+ it takes about (0.5+6.5+20)
32846  minutes for (configure+make+regression test), and there is (i386, amd64,
32847  alpha, ppc64, (mingw32), sparc, macosx).
32848
32849 \end_inset
32850
32851
32852 \layout Standard
32853
32854 This document was initially written by Sandeep Dutta
32855 \layout Standard
32856
32857 All product names mentioned herein may be trademarks
32858 \begin_inset LatexCommand \index{Trademarks}
32859
32860 \end_inset
32861
32862  of their respective companies.
32863
32864 \layout Section*
32865
32866 Alphabetical index
32867 \layout Standard
32868
32869 To avoid confusion, the installation and building options for SDCC itself
32870  (chapter 2) are not part of the index.
32871 \layout Standard
32872
32873
32874 \begin_inset LatexCommand \printindex{}
32875
32876 \end_inset
32877
32878
32879 \the_end