doc/sdccman.lyx: Some re-formating plus example on using #pragma preproc_asm +/-

[fw/sdcc] / doc / sdccman.lyx

diff --git a/doc/sdccman.lyx b/doc/sdccman.lyx
index 4ebec3462c849c47be4609927bd45de00927d469..10d51908f072171fba9f8100f56d1313cbf02f2e 100644 (file)
--- a/doc/sdccman.lyx
+++ b/doc/sdccman.lyx
@@ -82,7 +82,7 @@ SDCC Compiler User Guide
 
 
 \size normal 
-SDCC 2.5.6
+SDCC 2.6.1
 \size footnotesize 
 
 \newline 
@@ -142,8 +142,8 @@ Sandeep Dutta
 
 , etc.), Dallas DS80C390 variants, Freescale (formerly Motorola) HC08 and
  Zilog Z80 based MCUs.
- It can be retargetted for other microprocessors, support for Microchip
- PIC, Atmel AVR is under development.
+ It can be retargeted for other microprocessors, support for Microchip PIC,
+ Atmel AVR is under development.
  The entire source code for the compiler is distributed under GPL.
  SDCC uses ASXXXX
 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
@@ -155,7 +155,7 @@ Sandeep Dutta
 
 \end_inset 
 
-, an open source retargettable assembler & linker.
+, an open source retargetable assembler & linker.
  SDCC has extensive language extensions suitable for utilizing various microcont
 rollers and underlying hardware effectively.
  
@@ -827,12 +827,13 @@ bit b;
 \SpecialChar ~
 b = ~b; /* equivalent to b=1 instead of toggling b */
 \begin_inset Marginal
-collapsed true
+collapsed false
 
 \layout Standard
 
 
 \series bold 
+\SpecialChar ~
 !
 \end_inset 
 
@@ -959,7 +960,7 @@ For most users it is sufficient to skip to either section
 \end_inset 
 
 .
- More detailled instructions follow below.
+ More detailed instructions follow below.
 \layout Section
 
 Configure Options
@@ -9573,7 +9574,7 @@ This is a data-type and a storage class specifier.
 
 
 \family typewriter 
-bit test_bit;
+__bit test_bit;
 \layout Standard
 
 Writing 1 to this variable generates the assembly code:
@@ -10470,6 +10471,7 @@ collapsed true
 
 
 \series bold 
+\SpecialChar ~
 !
 \end_inset 
 
@@ -10502,6 +10504,7 @@ collapsed true
 
 
 \series bold 
+\SpecialChar ~
 !
 \end_inset 
 
@@ -10572,7 +10575,7 @@ Absolute addresses can be specified for variables in all storage classes,
 
 
 \family typewriter 
-bit
+__bit
 \begin_inset LatexCommand \index{bit}
 
 \end_inset 
@@ -10602,19 +10605,19 @@ extern volatile
 
 \end_inset 
 
- bit MOSI;\SpecialChar ~
+ __bit MOSI;\SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 /* master out, slave in */
 \newline 
-extern volatile bit MISO;\SpecialChar ~
+extern volatile __bit MISO;\SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 /* master in, slave out */
 \newline 
-extern volatile bit MCLK;\SpecialChar ~
+extern volatile __bit MCLK;\SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
@@ -10750,7 +10753,7 @@ Then, someplace in the code for the first hardware you would use
 
 
 \family typewriter 
-bit __at
+__bit __at
 \begin_inset LatexCommand \index{at}
 
 \end_inset 
@@ -10766,13 +10769,13 @@ bit __at
 \SpecialChar ~
 /* I/O port 0, bit 0 */
 \newline 
-bit __at (0x81) MISO;\SpecialChar ~
+__bit __at (0x81) MISO;\SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 /* I/O port 0, bit 1 */
 \newline 
-bit __at (0x82) MCLK;\SpecialChar ~
+__bit __at (0x82) MCLK;\SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
@@ -10784,19 +10787,19 @@ Similarly, for the second hardware you would use
 
 
 \family typewriter 
-bit __at (0x83) MOSI;\SpecialChar ~
+__bit __at (0x83) MOSI;\SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 /* I/O port 0, bit 3 */
 \newline 
-bit __at (0x91) MISO;\SpecialChar ~
+__bit __at (0x91) MISO;\SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 /* I/O port 1, bit 1 */
 \newline 
-bit
+__bit
 \begin_inset LatexCommand \index{bit}
 
 \end_inset 
@@ -10978,19 +10981,19 @@ unsigned char foo()
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
-xdata unsigned char i;
+__xdata unsigned char i;
 \newline 
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
-bit bvar;
+__bit bvar;
 \newline 
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
 \SpecialChar ~
-data __at
+__data __at
 \begin_inset LatexCommand \index{at}
 
 \end_inset 
@@ -12638,7 +12641,7 @@ Starting from a small snippet of c-code this example shows for the MCS51
 
 \family typewriter 
 \size footnotesize 
-unsigned char far
+unsigned char __far
 \begin_inset LatexCommand \index{far (storage class)}
 
 \end_inset 
@@ -12700,6 +12703,7 @@ collapsed false
 
 
 \series bold 
+\SpecialChar ~
 !
 \end_inset 
 
@@ -12936,7 +12940,7 @@ The new file buffer.c should compile with only one warning about the unreference
 
 \family typewriter 
 \size footnotesize 
-unsigned char far __at(0x7f00) buf[0x100];
+unsigned char __far __at(0x7f00) buf[0x100];
 \newline 
 unsigned char head, tail;
 \newline 
@@ -15461,6 +15465,100 @@ and
 not
 \emph default 
  support long variables and field widths).
+\layout Subsubsection
+
+<malloc.h>
+\begin_inset LatexCommand \index{malloc.h}
+
+\end_inset 
+
+
+\layout Standard
+
+Before using dynamic
+\begin_inset LatexCommand \index{dynamic}
+
+\end_inset 
+
+ memory allocation with SDCC, you have to provide heap
+\begin_inset LatexCommand \index{heap}
+
+\end_inset 
+
+ space for malloc to allocate memory from
+\family typewriter 
+.
+ 
+\family default 
+You can acomplish this by including the following code into your source:
+\layout Verse
+
+
+\family typewriter 
+#include <malloc.h>
+\begin_inset LatexCommand \index{malloc.h}
+
+\end_inset 
+
+ /* calloc
+\begin_inset LatexCommand \index{calloc}
+
+\end_inset 
+
+, malloc
+\begin_inset LatexCommand \index{malloc}
+
+\end_inset 
+
+, realloc
+\begin_inset LatexCommand \index{realloc}
+
+\end_inset 
+
+, and free
+\begin_inset LatexCommand \index{free}
+
+\end_inset 
+
+ */ 
+\newline 
+
+\newline 
+#define HEAPSIZE 0x1000 /* Adjust depending on available memory */ 
+\newline 
+unsigned char xdata myheap[HEAPSIZE]; /* The actual heap for dynamic memory
+ */ 
+\newline 
+
+\newline 
+void main (void) 
+\newline 
+{ 
+\newline 
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* Your variable declarations come here*/
+\newline 
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+\newline 
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+init_dynamic_memory((MEMHEADER xdata *)myheap, HEAPSIZE);
+\newline 
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+ /* Rest of your code*/
+\newline 
+} 
+\newline 
+
 \layout Subsection
 
 Math functions (sinf, powf, sqrtf etc.)
@@ -16154,6 +16252,68 @@ preproc_asm
 
  (+ | -) - switch _asm _endasm block preprocessing on / off.
  Default is on.
+ You use this prama to define multilines of assembly code.
+ This will prevent the preprocessor from changing the formating required
+ by assembly code.
+ Below is an example on how to use this pragma.
+\layout Verse
+
+
+\family typewriter 
+#pragma preproc_asm -
+\begin_inset LatexCommand \index{\#pragma preproc\_asm}
+
+\end_inset 
+
+
+\newline 
+#define MYDELAY _asm
+\newline 
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+nop ;my assembly comment...
+\newline 
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+nop
+\newline 
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+nop
+\newline 
+_endasm
+\newline 
+#pragma preproc_asm +
+\newline 
+
+\newline 
+void foo (void) 
+\newline 
+{ 
+\newline 
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ ...
+ 
+\newline 
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ MYDELAY;
+\newline 
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ ...
+ 
+\newline 
+} 
+\newline 
+
 \layout Standard
 
 The pragma's are intended to be used to turn-on or off certain optimizations
@@ -16232,6 +16392,12 @@ int foo ()
 The compiler will generate a warning message when extra space is allocated.
  It is strongly recommended that the save and restore pragma's be used when
  changing options for a function.
+\newline 
+
+\newline 
+
+\newline 
+
 \layout Section
 
 Defines Created by the Compiler
@@ -16256,8 +16422,8 @@ The compiler creates the following #defines
 \begin_inset  Tabular
 <lyxtabular version="3" rows="11" columns="2">
 <features>
-<column alignment="left" valignment="top" leftline="true" width="0">
-<column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
+<column alignment="left" valignment="top" leftline="true" width="3in">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="3in">
 <row topline="true" bottomline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
@@ -16326,7 +16492,7 @@ SDCC_mcs51
 
 \end_inset 
 
-, etc
+, etc.
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -16334,7 +16500,7 @@ SDCC_mcs51
 
 \layout Standard
 
-depending on the model used (e.g.: -mds390
+depending on the model used (e.g.: -mds390)
 \end_inset 
 </cell>
 </row>
@@ -19585,7 +19751,7 @@ rest of the pointer
 
 \layout Standard
 
-descrption
+description
 \end_inset 
 </cell>
 </row>
@@ -20199,7 +20365,7 @@ void main(void)
 {
 \layout LyX-Code
 
-    stdout = STREAM_USER;    /* this is not necessery, since stdout points
+    stdout = STREAM_USER;    /* this is not necessary, since stdout points
 \layout LyX-Code
 
                               * by default to STREAM_USER */
@@ -20937,9 +21103,9 @@ use an on-target monitor.
  In this context a monitor is a small program which usually accepts commands
  via a serial line and allows to set program counter, to single step through
  a program and read/write memory locations.
- For the 8051 a good example of a monitor with a very liberal licence is
- paulmon (
-\begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/paulmon2.html}
+ For the 8051 good examples of monitors are paulmon and cmon51 (see section
+ 
+\begin_inset LatexCommand \ref{sec:Related-open-source-tools}
 
 \end_inset 
 
@@ -22611,7 +22777,10 @@ last
 \emph on 
 not
 \emph default 
- the same as endianness).check whether the keyword 
+ the same as endianness).
+\layout Itemize
+
+check whether the keyword 
 \emph on 
 volatile
 \emph default 
@@ -22652,8 +22821,12 @@ check whether timing loops result in proper timing (or preferably consider
  a rewrite of the code with timer based delays instead).
 \layout Itemize
 
-check for differences in printf parameters (some compilers push (va_arg)
- char variables as integers others as char).
+check for differences in printf parameters (some compilers push (va_arg
+\begin_inset LatexCommand \index{va\_arg}
+
+\end_inset 
+
+) char variables as integers others as char).
 \layout Itemize
 
 check the resulting memory layout.
@@ -23342,6 +23515,11 @@ f
 \layout Section
 
 Related open source tools
+\begin_inset LatexCommand \label{sec:Related-open-source-tools}
+
+\end_inset 
+
+
 \begin_inset LatexCommand \index{Related tools}
 
 \end_inset 
@@ -23351,7 +23529,7 @@ Related open source tools
 \align center 
 
 \begin_inset  Tabular
-<lyxtabular version="3" rows="13" columns="3">
+<lyxtabular version="3" rows="14" columns="3">
 <features>
 <column alignment="left" valignment="top" leftline="true" width="0pt">
 <column alignment="block" valignment="top" leftline="true" width="30line%">
@@ -23626,6 +23804,37 @@ Part of binutils (should be there anyway)
 
 \layout Standard
 
+cmon51
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+8051 monitor (hex up-/download, single step, disassemble)
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\begin_inset LatexCommand \url{http://sourceforge.net/projects/cmon51}
+
+\end_inset 
+
+
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
 doxygen
 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
 
@@ -23814,11 +24023,11 @@ Related documentation / recommended reading
 \align center 
 
 \begin_inset  Tabular
-<lyxtabular version="3" rows="6" columns="3">
+<lyxtabular version="3" rows="8" columns="3">
 <features>
-<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="left" valignment="top" leftline="true" width="0pt">
 <column alignment="block" valignment="top" leftline="true" width="30line%">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
 <row topline="true" bottomline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
@@ -23918,6 +24127,88 @@ C-FAQ-list
 \end_inset 
 
 
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+ISO/IEC 9899:TC2
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\begin_inset Quotes sld
+\end_inset 
+
+C-Standard
+\begin_inset Quotes srd
+\end_inset 
+
+
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\size footnotesize 
+
+\begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899}
+
+\end_inset 
+
+
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+ISO/IEC DTR 18037
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\begin_inset Quotes sld
+\end_inset 
+
+Extensions for Embedded C
+\begin_inset Quotes srd
+\end_inset 
+
+
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\size footnotesize 
+
+\begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1021.pdf}
+
+\end_inset 
+
+
 \end_inset 
 </cell>
 </row>
@@ -27599,6 +27890,20 @@ ANSI-Compliance
 \end_inset 
 
 
+\layout Standard
+
+The latest publically available version of the standard 
+\emph on 
+ISO/IEC 9899 - Programming languages - C
+\emph default 
+ should be available at: 
+\begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899}
+
+\end_inset 
+
+.
+\newline 
+
 \layout Standard
 
 Deviations from the compliance: