install.txt

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

Using MPLINK and multiple modules:

After creating the project (as described earlier), MPLAB will
display a window at the left side where project files can be
inserted. It is required to create the files before they are added
to the project. By clicking on the right mouse button on the "Source
Files" item, it is possible to add source files. You can also do
this by selecting the menu item "Project->Add files to Project". It
is enough to add the source module files (.c and .asm) and the
linker script file (.lkr).

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.

Option '-rsc' allows the compiler to generate and update the
linker script file. Initially, it is enough to create a script file
with a blank line. Option '-rsc=<name.lkr>' allow script file name
different from the main C module name. For more details, please
refer to 'LINKER.TXT' in the CC8E package.

Other options can also be put into file 'reloc.inc'.

File 'LINKER.TXT' contains the main information on linker support.

The Build all (ctrl-F10) will build the project. The Output window
will state BUILD SUCCEEDED or BUILD FAILED. If build failed it will
be required to correct the wrong input. It possible to use POINT-
AND-CLICK on the error messages. For linker script errors, please
refer to MPLINK documentation.

On successful build it will be possible to run and debug the code in
ICD2 or the MPLAB simulator, or simply program the device for
normal target execution.

Note that it is MPASM/MPLINK that generates the COD file when using
multiple modules. The -CA and -CC compiler options will not have any
effect. Debugging (single step etc.) can only use the generated
assembly files as source when using MPLINK.


Example programs:

The example program found in file LINKER.TXT in the CC8E package can
be tried. Note that using an external linker like MPLINK is
significantly more difficult than the default single module mode.



MPLAB VERSION 5
---------------

NOTE that MPLAB version 6 and later have a separate description.

The CC8E compiler can be used inside the MPLAB suite. Note that CC8E
can only run in command-line mode.

Installing CC8E in MPLAB 5:

1. First install CC8E on your computer as described initially.

2. Then copy the files CC8E.MTC and TLCC8E.INI from the CC8E folder
   (directory) to the MPLAB folder (this folder contains other .ini
   and .mtc files).

3. Next time MPLAB is started, select the Project->Install Language
   Tool menu item. Select CC8E from the Language Suite. Then the
   Tool Name (C-Compiler). Then the right executable, for example:

     c:\progra~1\cc8e\cc8e.exe

   Note that the Browse button can be used to find the executable.
   Also mark the Command-line box. Then click OK. CC8E will then be
   one of the selectable tools in MPLAB.

The following is a brief description on how to use CC8E on a new
project under MPLAB. Please refer to the help information available
under MPLAB for a complete description.

1. Start MPLAB and create a new project (Project->New Project).
   Chose a project name (*.pjt) and a directory where to locate this
   file and the other project files (C,H,HEX,ASM). Type <Enter> or
   the OK button.

2. Edit Project is the next window. MPLAB suggests a Target Filename
   based on the project name. This is automatically changed during
   step 4. Include Path should preferably point to the CC8E
   directory to allow library header files to be included. "Library
   Path" and "Linker Script Path" are not used. Use Development Mode
   to select the processor and simulator/debugger (ignore any MPLAB
   warning at the current stage). Change Language Tool Suite to
   CC8E (this is one of the menu items if the installation steps was
   completed).

3. Double-click on the (target) name in the Project Files box. A
   window named Node Properties pops up. The typical command line
   options for CC8E are already marked. Options are disabled or
   enabled by clicking on the box (second column) after the option
   name. Note that the right Include Path (c:\progra~1\cc8e) is
   required to make CC8E find the header files. Click the OK button.

   MPLAB automatically supplies the processor type as a command line
   option to the compiler.

4. Click on the Add Node button. Type the name of your main C file
   or chose an existing C file (sample1.c). It is recommended to try
   one of the supplied example files initially. If the (sample) C
   file does not reside in the selected project directory, copy it
   to this directory first. Note that files included in the main C
   file (and nested include) must not be listed in the Project Files
   box. Click the OK button.

5. Open the main C file (File->Open or Ctrl-O). Compile the file
   using Project->Make Project (or F10). Note that Project->Build
   Node (Alt-F10) requires that the main C file is in the current
   active window. Double-click on the error messages (if any) and
   correct the C code. Repeat the compilation until there are no
   error messages.

   NOTE: If MPLAB says 'Build Failed' and there are no error
   messages generated by the compiler, please go to main paragraph
   'TROUBLESHOOTING' in this file.

   Use File->Open to inspect the generated files. The *.occ file
   contains compiler output information.

   IMPORTANT: If you selected the Error File command line option,
   then MPLAB will suppress the output from the compiler and display
   the content of the *.err file only. Change this option to your
   preferred setting. It may also be necessary to change some of the
   command line options (Processor, Hex Format) if MPLAB pops up a
   warning window.

6. CC8E allows simulation in C or assembly mode using the COD file.
   This is one of the compiler options: Debugging mode (C) or (ASM).
   Change the compiler options setting by selecting the Project->
   Edit project menu item. Double-click on the (target) file in the
   Project Files. Click OK. If you need many command line options,
   please read last paragraph 'USING OPTIONS IN A FILE'.

7. Options->Development Mode can be used to set/change the debugging
   tool (MPLAB-SIM Simulator, SIMICE, Emulator, etc.). You are then
   ready to trace program execution.

8. Watching variable contents during tracing:
   MPLAB allows Watch windows containing variables to be defined.
   Select Window->Watch Windows->New Watch Window. Select the
   variable name. Select Properties. Select the right size (8,16,24,
   32 bit). Select the Low:High byte order if the variable size if
   more than 8 bit. Select the desired format (Hex,Decimal,
   ASCII,..). It is possible to watch the same variable using
   different formats. Close the Add Watch Symbol window when
   finished. The INS key can be used to add a new symbol to the
   current active Watch window.

   Bit variables: it is recommended to first define a char variable
   and use an overlay definition to define the bit.
       char cx;
       bit bx @ cx.0;
   This simplifies watching the bit value.




TROUBLESHOOTING
---------------

Problem A: MPLAB 5 says 'Build Failed' and there are no error messages
           generated by the compiler.

   i) One cause is that CC8E was not started.
      This can happen if the installation was not successful.

      Cure: Select the Project->Install Language Tool menu item. Use
      the Browse button to find the executable (cc8e.exe). Then
      click OK.

   ii) MPLAB may fail to compile if the command line including
       options that starts cc8e is too long (around 148 characters
       seems to be critical). This can happen if long path names are
       used (for the include directory and/or the executable).

      Cure: remove most command line options found in
      Project->Edit Project..(target)..Node Properties.
      This window tells which command line options are used. Click
      OK. Then try to compile (using F10). It may be required to put
      the command line options in a separate file to avoid this
      problem (check next paragraph).

      If compilation still fails, please count the number of
      characters in the command line generated by MPLAB (Build
      Results). If this command line which starts cc8e contains more
      than 147 characters, please remove more options. It may even
      be necessary to move the folders used closer to the root to
      avoid very long path names. It should be easy to detect the
      path names that are very long.


Problem B: Project Build (F10) in MPLAB produces an empty window.

   Cure: Same as Problem A, point ii).


Generally, it is recommended to use one of the supplied examples
initially. Also FEW command line options until a successful
compilation is found.



USING OPTIONS IN A FILE
-----------------------

All compiler options can be put in a file. Just separate them with a
space or a new line. Also check the supplied file op.inc for details.

The options that reside in a file should be disabled in MPLAB.
Select Project->Edit Project..(target)..Node Properties, and make
sure these options are disabled. Also, under additional command line
options, add +op.inc (or another file name including path).

The path to the option file can be omitted if the option file is
put in the same folder as the other project files.

It is possible to use several option files.