* doc/sdccman.lyx: update documentation about stack pragma, added

some info for stack memory models

git-svn-id: https://sdcc.svn.sourceforge.net/svnroot/sdcc/trunk/sdcc@3632 4a8a32a2-be11-0410-ad9d-d568d2c75423

diff --git a/ChangeLog b/ChangeLog
index 316ba2c15f4b4e5529634e63d23619c5318b8c3a..67364bd19de13e015fbf239433ca8d78fbacff81 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2005-01-11 Vangelis Rokas <vrokas AT otenet.gr>
+
+       * doc/sdccman.lyx: update documentation about stack pragma, added
+       some info for stack memory models
+
 2005-01-08 Jesus Calvino-Fraga <jesusc AT ece.ubc.ca>
 
        * src/pic16/gen.c (DEBUGpc): MSVC 6 does not support macro variable arguments

diff --git a/doc/sdccman.lyx b/doc/sdccman.lyx
index a5a057e2a17df3d9b8deb9e5c0bcbac9fd80c84a..0e5c14bbe5f8d871933e3684f0645b00f19db89f 100644 (file)
--- a/doc/sdccman.lyx
+++ b/doc/sdccman.lyx
@@ -15929,25 +15929,24 @@ PIC16 port currently supports the following pragmas:
 
 stack pragma stack forces the code generator to initialize the stack & frame
  pointers at a specific address.
- This is an adhoc solution since gplink does not support yet stack.
- When the gplink issue is resolved the pragma will be deprecated
-\begin_inset Foot
-collapsed true
+ This is an adhoc solution for cases where no STACK directive is available
+ in the linker script or gplink is not instructed to create a stack section.
+\newline 
+The stack pragma should be used only once in a project.
+ Multiple pragmas may result in indeterminate behaviour of the program.
+\newline 
+The format is as follows:
+\layout LyX-Code
 
+#pragma stack bottom_address [stack_size]
 \layout Standard
 
 
 \emph on 
-It is important to initialize the stack, otherwise strange things can happen.
- Stack is not initialized by default because there are some sources that
- do not require it.
- (like library sources)
-\end_inset 
-
-.
-\newline 
-The stack pragma should be used only once in a project.
- Multiple pragmas may result in indeterminate behaviour of the program.
+bottom_address
+\emph default 
+ is the lower bound of the stack section.
+ The stack pointer initially will point at address (bottom_address+stack_size-1).
 \layout LyX-Code
 
 Example:
@@ -15955,10 +15954,10 @@ Example:
 
 \layout LyX-Code
 
-/* initializes stack at RAM address 0x5ff */
+/* initializes stack of 100 bytes at RAM address 0x200 */
 \layout LyX-Code
 
-#pragma stack 0x5ff
+#pragma stack 0x200 100
 \layout List
 \labelwidthstring 00.00.0000
 
@@ -16288,10 +16287,18 @@ FSR2 is assigned as frame pointer
 The following stack models are supported by the PIC16 port
 \layout Itemize
 
-small model
+
+\noun on 
+small
+\noun default 
+ model
 \layout Itemize
 
-large model
+
+\noun on 
+large
+\noun default 
+ model
 \layout Standard
 
 
@@ -16403,16 +16410,25 @@ Frame pointer FSR2
 \layout Standard
 
 
-\series bold 
-Currently stack and frame pointers should be initialized explicit by the
- user at the desired Data RAM position (see 
-\begin_inset LatexCommand \ref{sub:PIC16_Pragmas}
+\noun on 
+Large 
+\noun default 
+stack model is currently not working properly throughout the code generator.
+ So its use is not advised.
+ Also there are some other points that need special care:
+\layout Enumerate
 
-\end_inset 
+Do not create stack sections with size more than one physical bank (that
+ is 256 bytes)
+\layout Enumerate
+
+Stack sections should no cross physical bank limits (i.e.
+ #pragma stack 0x50 0x100)
+\layout Standard
 
- Pragma stack).
- Uninitialized stack and frame pointers can result in unexpected behavior
- of the resulting binary.
+These limitations are caused by the fact that only FSRxL is modified when
+ using SMALL stack model, so no more than 256 bytes of stack can be used.
+ This problem will disappear after LARGE model is fully implemented.
 \layout Subsection
 
 Function return values