linker.txt

FreeRTOS 是一个源码公开的免费的嵌入式实时操作系统

CONTENTS
--------
* Linker Support
* Using MPLINK or a Single Module
* Restrictions on the DEMO edition
* Variables and Pointers
* Local Variables
* Header Files
* Using Ram Banks
* Bank Bit Updating
* Functions
* Using Code Sections
* Interrupts
* Call Level Checking
* Computed Goto
* Recommendations when using MPLINK
* MPLAB Support
* MPASM
* The MPLINK Script File
* EXAMPLE with 2 Modules



LINKER SUPPORT
--------------

CC8E supports the relocatable assembly format defined by Microchip.
This means that MPLINK can be used to link code modules generated
by CC8E, including MPASM assembly modules.

There are many details to be aware of. It is therefore recommended to
read this file carefully. The important issues are related to:

    - external functions and variables
    - ram bank updating
    - call level checking
    - MPLINK script files
    - MPLAB integration

The command line option '-rsc' (or '-r2' or '-r') makes CC8E
generate relocatable assembly. This file is then assembled by MPASM
and linked together with other C and assembly modules by MPLINK.
This can automated by using 'make' to build the whole application in
several stages.

NOTE that if you need the application program to be as compact as
possible, then it is recommended to use only ONE C module. Source
code modularity is obtained by using many C files and include these
in the main C module by using #include.

Command line options:

    -rsc[=<file.lkr>] : generate relocatable assembly and use
      separate logical sections for the interrupt routines. Also
      generate or update the complete linker script file. If the
      linker script file name is not specified, then the C module
      name will be used with the extension '.lkr'. The script file
      will only be generated when compiling the module containing
      main().

    -r2[=<file.lkr>] : generate relocatable assembly with separate
      logical sections for the interrupt routines. A partial linker
      script file (containing dynamic definitions of page and
      intserv8 or intserv18) is generated and should be included in
      the main linker script file. If the partial linker script file
      name is not specified, then the C module name will be used
      with the extension '.lkr'.

    -r : generate relocatable assembly without separate logical
      sections for the interrupt routines. NO linker script file
      is generated.

    -rx : make variables static by default

    // external assembler options
    -x<file> : assembler executable: -xC:\progra~1\mplab\mpasmwin.exe
    -X<option>: assembler option: -X/q (all options must be separate)

    // assembly file options (normally not used)
    -rb<N> : name on RAM bank 0 is BANK<N>, default BANK0
    -ro<N> : add offset <N> when generating local variable block name



USING MPLINK OR A SINGLE MODULE
-------------------------------

Currently it is best to use a single C module for several reasons.
MPLINK support was mainly offered to enable asm modules to be added.

Limitations when using MPLINK:
  1. Asm mode debugging only (C source code appear as comments)
  2. Multiple C modules does not allow the static local variable
     stack to be calculated for the whole program, meaning that much
     more RAM space will be used for local variables.
  3. Call level checking must be done manually
  4. Computed goto will be slower because the compiler can not check
     256 byte address boundary crossing.
  5. Inefficient RAM bank updating, meaning mode code.

  The main reasons for using multiple modules is probably:
  1. Faster build: However, CC8E is incredible fast.
  2. Module separation: However, sufficient module separation can be
     achieved by using multiple C files.
  3. Asm modules: Inline ASM is supported by CC8E.

C modules can be merged into a single module and still be viewed as
single modules. Such C modules can be used in several projects
without modification. The procedure is as follows:

1. Include the "separate modules" into the main module:

    #include "module1.c"
    #include "module2.c"
    // ..
    #include "moduleN.c"
    // ..
    void main( void) { .. }

2. Each merged "module" includes the required header files. This can
   be header files specific for the "module" or common header files:

    #include "header1.h"
    #include "header2.h"
    // ..
    #include "headerN.h"
    // ..
    // module functions

3. If the same header file is included in more than one "module", it
   will be required to prevent compiling the same header file
   definitions more than once. This is done by using the following
   header file framing:

    #ifndef  _HEADER_N_Symbol   // the first header file line
    #define _HEADER_N_Symbol    // compile this line once only
    // ..
    // header definitions as required
    // ..
    #endif  // the last header file line



RESTRICTIONS ON THE DEMO EDITION
--------------------------------

There are some restrictions when using relocatable assembly on the
CC8E DEMO:

 1. A single demo C module is possible, plus many assembly modules.
 2. The demo C module can call EXTERN functions and use extern
    variables defined in assembly modules.
 3. The demo C module is NOT allowed to export extern functions or
    variables.
 4. main() must be defined in the demo C module. The interrupt
    routines should preferably also be defined in the demo C module.
 5. The demo C module can maximum contain 1024 instructions



VARIABLES AND POINTERS
----------------------

Variables defined in other module can be accessed. CC8E needs to
know the type, and this is done by adding 'extern' in front of a
variable definition.

    extern char a;

All global variables that are not 'static' are made available for
other modules automatically. CC8E inserts 'GLOBAL' statements in the
generated assembly file.

CC8E will generate a 'MOVLW LOW (var_name+<offset>)' when using the
address operators '&var_name'.

Global bit variables is a challenge. It is recommended to first
define a char variable and then use 'bit bx @ ch.0;'. Otherwise CC8E
will defines a global char variable with random name. This name have
the format '_Gbit<X><X>' where <X> is (more or less) random
selected letters. This variable is reserved by a RES statement and
used in the assembly file when generating relocatable assembly.

    bit b1;
    b1 = 0;   // BCF _GbitQB+0,0

The variable file (*.var) is slightly modified when generating
relocatable assembly. Note that most addresses stated in the
variable file are reallocated by MPLINK.

Option -rx will make variables static by default. This means that
variables will not be visible outside the module unless 'extern' is
added in front of the type definition. Note that option -rx requires
that an extern pointer definition need to be stated before the
allocation of the pointer.

  extern char *px;  // definition only, no allocation of space
  char *px;         // space is allocated for the pointer

IMPORTANT: 'const' data can not be 'extern' because MPLINK does not
support the const access functions generated by CC8E. Identifiers
with the 'const' modifier will not be made visible outside the
module. This also applies to struct objects with const pointers.

IMPORTANT: Allocation of pointers is slightly different when using
relocatable assembly. The main reason for this is that CC8E can not
trace how addresses are assigned to pointers between different
modules. There is no change on local and static pointers. An extern
visible pointer without a size modifier (size1/size2) will be 16 bit
wide.

An extern visible pointer with the size1 modifier will access
addresses from 0 - 255. An error is printed if the pointer is
assigned higher addresses. However, it is possible to force an
extern 8 bit pointer to access a specific bank by a pragma
statement:

  extern size1 char *px;
  #pragma assume *px in rambank 2

Note that 8 bit pointers in a struct can only access addresses
from 0 - 255, even if the struct is static or local.



LOCAL VARIABLES
---------------

CC8E uses a different naming strategy on local variables when generating
relocatable assembly. CC8E reserves a continuous block in each ram bank
(or access bank) and use this name when accessing local variables.

IMPORTANT RESTRICTION:
The main() routine, interrupt service routines and all extern
functions are defined as independent call trees or paths. A function
called from two independent call paths can not contain local
variables or parameters because address sharing can not be computed
in advance. CC8E detects this and generates an error message.

The name of the local RAM blocks are _LcRA, _LcRB, etc. The last
letter is related to the RAM bank and the second last to the module
name. Adding option -ro1 will for example change name _LcAA to
_LcBA. This can be used if there is a collision between local
variable block defined in separate C modules. MPLINK detects such
collisions.

    -ro<N> : add offset <N> when generating local variable block name

Local variables for external available functions are allocated
separately. One block for each extern function. This often means
inefficiently use of RAM. It is therefore recommended to use
'extern' only on those functions that have to be extern, and use few
local variables in the extern functions. Also consider using global
variables.



HEADER FILES
------------

It is recommended to make common header files that contains global
definitions that are included in all C modules. Such files can
contain definitions (#define), IO variable names, etc.



USING RAM BANKS
---------------

RAM bank definitions only applies to devices with RAM located
in more than one bank.

Note that the RAM bank of ALL variables have to be known (defined)
during compilation. Otherwise the bank bit updating will not be
correct. The bank is defined by using '#pragma rambank' between the
variable definition statements, also for 'extern' variables. An
alternative is to use the bank type modifier (bank0..bank3, shrBank).

   #pragma rambank 0
    char a,b;

   #pragma rambank 1
    extern char array1[10];

   #pragma rambank -
    extern char ex;   // access RAM



BANK BIT UPDATING
-----------------

CC8E use an advanced algorithm to update the bank selection
bits. However, it is not possible to trace calls to external
functions. Therefore, calling an external function or allowing
incoming calls makes CC8E assume that the bank bits are undefined.
This often means that more code compared to the optimal bank bit
update strategy.

It is therefore recommended to only use 'extern' on those functions
that have to be extern, and keep the number of calls between modules
to a minimum.



FUNCTIONS
---------

Functions residing in other modules can be called. Functions defined
can be called from other modules (also from assembly modules).

NOTE that ALL functions that are called from another module needs
an 'extern' first. This is an extra requirement that is optional in
C. The reason is that the compiler needs to decide the strategy on
bank bit updating and local variables allocation. It is most
efficient to use FEW extern functions.

    extern void func1(void);  // defined in another module

    extern void func2(void) { .. }  // can be called from another module

NOTE that extern functions can only have a single 8 bit parameter which
is transferred in W (not const/pointer/bit). This is because local
storage information is not shared between modules. The return value
can not be larger than 8 bit for the same reason (bit values are
returned in Carry).

    Supported extern function parameter types:  char, uns8, int8
    Supported extern function return types:  char, uns8, bit

CC8E inserts a 'GLOBAL <function>' in the generated assembly
code for all external available functions. 'EXTERN <function>'
is inserted for functions defined in other modules.

If the C module contains main(), then a 'goto main' is inserted in
the STARTUP section.



USING CODE SECTIONS
-------------------

It is possible to use #pragma origin and #pragma cdata when the
compiler know the section the following code should be placed in.
The compiler automatically knows the STARTUP, ISERVER8, ISERVER18
and PROG sections. In addition it is possible to define sections