linker.txt

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

manually in the C file. These definitions will also automatically
appear in the script file when using the -rsc option. 

    #pragma sectionDef IDLOC:idlocs 0x200000 - 0x200007  PROTECTED
    #pragma sectionDef CONFIGS:config 0x300000 - 0x30000D  PROTECTED
    #pragma sectionDef EEPROM:eedata 0xF00000 - 0xF000FF  PROTECTED
    #pragma sectionDef APPSEC:appdef1  0x1000 - 0x102F
    #pragma sectionDef PROG

Note the difference between using:
    #pragma origin 0x1000          => generates:  APPSEC CODE 0x1000
and
    #pragma origin SECTION(APPSEC) => generates:  APPSEC CODE

The first origin says "from the start of the APPSEC section", while
the last origin says "somewhere" in the APPSEC section". Locating
code from a specific address is sometimes useful, but note that
MPLINK does not allow the above origin statements to be mixed for
code belonging to the same section.

If the sections starting at address 0x200000 and 0x300000 are not
defined, then the compiler will automatically use section names
IDLOCS and CONFIG. However, it is recommended to use the above
definitions in the C file, especially when using the -rsc option.

The compiler estimate the current hex address, and use this to
detect when to insert the ISERVER8 and ISERVER18 sections when using
the '-rsc' or '-r2' options. Sometimes these sections should not be
inserted. This problem will occur infrequently and is easily
detected because MPLINK will report the conflict. This problem can
be solved by inserting the following statements at the right place:

    #pragma sectionDef PROG
    #pragma origin SECTION(PROG)

NOTE: It is recommended to use code sections of maximum 64k byte,
without crossing a 64k boundary ((START & 0xFF0000) should be equal
(END & 0xFF0000)).



INTERRUPTS
----------

CC8E requires that the interrupt functions are located at address 8
and 0x18. Writing the interrupt service routine in C using MPLINK
will require some care.

The best method is to use SEPARATE logical sections in the linker
script file for the interrupt service routines. This is a robust
solution. CC8E will generate a full (or partial) script file to
avoid manual address calculation. Node that #pragma origin 0x8 and
0x18 must be used for the interrupt routines.

It is also possible to design an assembly module containing the
interrupt service routines. Information on how to do this should be
found in the MPASM/MPLINK documentation.



CALL LEVEL CHECKING
-------------------

CC8E will normally check that the call level is not exceeded. This
is only partially possible when using MPLINK. CC8E can ONLY check
the current module, NOT the whole linked application.

When calling an external function from the C code, CC8E will assume
that the external call is one level deep. This checking is sometimes
enough, especially if all C code is put in one module, and the
assembly code modules are called from well known stack levels.
Calling C function from assembly will require manual analysis of
the call level.

Therefore, careful verification of the call structure is required to
avoid program crash when using too deep calls (max 31 levels). The
compiler generated *.fcs files can provide information for this
checking.

Calls to external functions is written in the *.fcs file. External
function calls are marked [EXTERN].



COMPUTED GOTO
-------------

CC8E will always use the long format when generating code for
skip(). It is not possible to use the -GS option in combination with
relocatable assembly.



RECOMMENDATIONS WHEN USING MPLINK
---------------------------------

1. Use as few C modules as possible because of:
    a) inefficient bank bit updating between modules
    b) local variable space can not be reused between modules
    c) only single 8 bit parameter in calls between modules
    d) only 8 or 1 bit return values between modules

2. Use definition header files that are shared between modules.
   Include the shared definition in all C modules to enable
   consistency checking.

    a) variables: add bank information
        // module1.c
        extern shrBank char b;
        #define ARRAY_SIZE 10
        extern bank0 char array[ARRAY_SIZE];
        // module3.asm
        extern bank1 char mulcnd, mulplr, H_byte, L_byte;

    b) constants, definitions, enumerations and type information
        #define MyGlobalDef  1
        enum { S1 = 10, S2, S3, S4 S5 };
        // names assigned to port pins
        #pragma bit in  @ PORTB.0
        #pragma bit out @ PORTB.1

3. Define bit variables to overlap with a char variable
    /* extern */ char myBits;
    bit b1 @ myBits.0;
    bit b2 @ myBits.1;
    // use 'extern char myBits;' for global bits and put the
    // definitions in a shared header file. Move definition
    // 'char myBits;' to one of the modules.

4. It is recommended to use the -rsc option to enable the compiler
   to AUTOMATICALLY generate and later update the linker script.

5. Set up a 'makefile' to enable automatic (re)compilation and
   linking. Follow the guidelines when using MPLAB. Edit and use
   the option '+reloc.inc' when compiling C modules.

6. Do the final call level checking manually

7. Update conventions in assembly functions called from C modules:
   The bank selection bits should be updated in the beginning of
   assembly functions that are called from C.



MPLAB SUPPORT
-------------

The following description is an example to show the basic steps
involved when configuring MPLAB to build and work on a multi-
module project using CC8E, MPASM and MPLINK.

1. Create the main project files. 

   First create a new folder for the project (or select an existing
   folder). Then use copy-and-paste in your favorite editor to
   create 5 files with contents found at the end of this file. When
   this is finished, you should have 3 new files in the folder:
   module1.c, module2.asm, globdef1.h. File 18f452.lkr should
   initially contain a single blank line when using the
   -rsc=18f452.lkr option.

   New files can be added to the project later.

2. Start MPLAB

3. The general installation of CC8E under MPLAB is described in
   file 'INSTALL.TXT'.


******* IMPORTANT ******


     MPLAB version 5 : follow the remaining steps

     MPLAB version 6.0 - 6.22 : upgrade to version 6.30 or later is
     strongly recommended. Otherwise use the temporary solution
     described on http://www.bknd.com/mplab6.shtml

     MPLAB version 6.30 and later : follow description in INSTALL.TXT



***** REMAINING STEPS IS FOR MPLAB 5 ONLY *****

   Ensure that the proper path and executable is selected
   for CC8E, MPASM and MPLINK. This is done by selecting the menu
   item Project->Install Language Tool. Change Language Suite to
   CC8E. Select each tool one by one (C-Compiler, MPASM, MPLINK).
   The executable should look like:

     c:\progra~1\cc8e\cc8e.exe
     c:\progra~1\mplab\mpasm.exe
     c:\progra~1\mplab\mplink.exe

   Each tool should have a mark in the Command-line box.

   NOTE: It is recommended to click the OK button after defining
   each executable. Defining several 'Tool Names' at the same time
   may cause MPLAB to say "Build Tool not installed properly". This
   weakness applies to MPLAB version 5.70.00 and probably other
   versions also.

4. Select Project->New Project

   In the New Project window, select the right Drive and Directory
   for the project (double-click on the folders to open or close
   them). Then write the project File Name, for example test1.pjt.
   Click OK.

5. Click on Change Development Mode. Then select the right
   Processor (PIC18F452), make other configuration changes, and click
   OK. MPLAB may pop up some notes. Just click OK.

   NOTE: if you want to debug the code using the built in simulator,
   make sure that MPLAB SIM Simulator is selected.

6. Change the Language Tool Suite to CC8E. Click OK on the warning
   generated.

7. Select the file name (test1[.hex]) in Project Files. Click on Node
   Properties. Change the Language Tool (upper right) to MPLINK.

   Add the name of the linker file (18f452.lkr) in the Additional
   Command Line Options window. Click OK.

   NOTE that the standard MPLAB linker script files (for example
   18f452.lkr) should be adapted according to the description found
   in this file.

8. Click on Add Node. Select the modules (*.c, *.asm) to be added to
   the project one by one (click OK for each selected). Repeat for
   all modules in the project (c and asm).

   Change the node properties for each node (file) by first
   selecting the node and then click Node Properties. Add the
   option /q for asm files (quiet operation). Click Ok.

   Note that the file 'reloc.inc' need to be found in the current
   project directory. You can either copy the supplied reloc.inc
   found in the CC8E directory, or use nested include of this
   file (with full path name): +c:\progra~1\cc8e\reloc.inc

   The folder path to the assembler in file 'reloc.inc' may have to
   be changed depending on the installation of MPLAB/MPASM.

   Note that options to the C modules can be put in an options file
   (reloc.inc or another file). See also the supplied op.inc in the
   CC8E package for more details. The option file is included in the
   same way as reloc.inc (remember to use space to separate the
   options).

   CC8E need to locate the header file defining the processor used.
   This file can be copied to the current directory, or better, the
   include path can be supplied as a command line option to CC8E,
   for example: -Ic:\progra~1\cc8e

   Default options for MPASM: /e+ /l+ /x- /c+ /pXXXXX /o+

   Click OK to close the Edit Project window.

9. Make Project (F10) should now compile and link the project.

   Note that MPASM will generate its own warnings and messages.
   These should normally be ignored. MPASM do not know about the
   automatic bank bit updating and will display messages about
   this. MPASM have generated the message if the .asm file
   extension is used in the message.

10. Debugging. If you are using the MPLAB simulator, you can start
    execution for example by using the step command (F7). MPLAB
    will now display the assembly file.

    Program execution tracing will always use the assembly file as
    source when using the -r (-rsc) option and MPASM/MPLINK. This
    should work fine, because CC8E prints the C statements as
    comments in the generated assembly file.

    IMPORTANT: MPLAB will NOT reload the generated assembly file
    when recompiling a C file. This means that the asm file used for
    tracing must be CLOSED manually when recompiling. Otherwise the
    source line displayed when tracing will be wrong.




MPASM
-----

MPASM can generate object code from assembly modules. There are
some restrictions and additions when using relocatable modules
compared to using a single assembly module.

CC8E does not support the object code directly, but generates
relocatable assembly that MPASM use to generate the object file.
MPASM is started from within the CC8E so that no extra command
is required (only the right command line options).

Case Sensitivity option in MPASM is by default On, and should remain
On because C use case dependent identifiers.

Options to start MPASM and generate relocatable object code:

    -xC:\progra~1\mplab\mpasmwin.exe -X/o -X/q

Options when assembling and linking a single file:

    -xC:\progra~1\mplab\mpasmwin.exe -X/q

If the CC8E error file option (-F) is missing, CC8E will read the
error file generated by MPASM and write the error and warnings found
there to the screen and the output file (*.occ). The error file is
then deleted.

If the CC8E error file option (-F) is present, CC8E will write error
and warnings to the error file (*.err) and append the error and
warnings generated by MPASM at the end of this file.

Note that MPLAB will automatically show the contents of the error
file if it is non-empty. Otherwise the screen output is displayed
in 'Build Results' window.




THE MPLINK SCRIPT FILE
----------------------

The compiler is able to generate the FULL linker script file. This
is done when using command line option -rsc[=<file.lkr>]. The
compiler will automatically do the following when the C module
contains interrupt routine(s):

  a) Generate or update a complete script. If the file exists
     initially, then it should preferably contain an empty line.
     The script file will only be generated when compiling the
     module containing main().

  b) Add, remove and adjust definitions that are maintained by the
     compiler.

  c) Forward code section definitions to the script file, and allow
     the definitions to be used in #pragma origin statements etc.:

      #pragma sectionDef <secID>[:<secDef> <start> - <last> [<PROTECTED>]]

      #pragma sectionDef IDLOC:idlocs 0x200000 - 0x200007  PROTECTED
      #pragma sectionDef CONFIGS:config 0x300000 - 0x30000D  PROTECTED