PIC18_SDCC: Start README writing

This patch start writing README file.

Signed-off-by: Abdoulaye Walsimou Gaye <walsimou@walsimou.com>

1 files changed, 128 insertions, 5 deletions

diff --git a/Demo/PIC18_SDCC/README b/Demo/PIC18_SDCC/README
index 3454a2de..edbff0c8 100644
--- a/Demo/PIC18_SDCC/README
+++ b/Demo/PIC18_SDCC/README
@@ -1,6 +1,6 @@
 #########################################################################################
 # GAYE Abdoulaye Walsimou, <walsimou@walsimou.com>
-# Copyright(C) 2009 GAYE Abdoulaye Walsimou, <walsimou@walsimou.com>  All rights reserved.
+# Copyright (C) 2009 GAYE Abdoulaye Walsimou. All rights reserved.
 #
 # This program is free software; you can distribute it and/or modify it
 # under the terms of the GNU General Public License
@@ -16,8 +16,131 @@
 # 59 Temple Place - Suite 330, Boston MA 02111-1307, USA.
 #########################################################################################
 #
-# \file         README
-# \brief	README of root project
-# \author       GAYE Abdoulaye Walsimou, <walsimou@walsimou.com>
-# \date         March 2009
+# \file		README
+# \brief	README for the SDCC/PIC18 (pic16 arch in sddc world) port.
+# \author	GAYE Abdoulaye Walsimou, <walsimou@walsimou.com>
+# \date		March 2009
 #########################################################################################
+
+0 Introduction
+
+Here you will find information on how to develop your realtime application using FreeRTOS
+as Kernel, SDCC/GPUTILS as development tools, and a Microchip PIC18 device as MCU.
+Both SDCC and GPUTILS run natively under GNU/Linux distributions, but can also run
+under BSD distrubutions and under Windows (in this case you need cygwin).
+Supported devices are theoretically all PIC18 supported by SDCC and GPUTILS together,
+something about 99 devices (see SDCC and GPUTILS website and documentation). But the
+porting task is done with pic18f452 MCU and gpsim as simulator.
+
+FreeRTOS: Realtime kernel
+SDCC: Small Device C Compiler
+GPutils: GNU PIC utils
+
+I Requierements
+
+Obviously you need FreeRTOS source tree and SDCC/GPUTILS installed in your workstation.
+This workstation can be either under GNU/Linux distribution, IMHO a very good choice, or
+under BSD distribution, FreeBSD is an excellent choice, or finally under Windows.
+
+I-0 Recommanded versions
+
+	SDCC-2.9.1
+	GPutils-0.13.7
+Another useful tool is gpsim (Gnu PIC simulator):
+	gpsim-0.22.0 (or later)
+
+I-1 GNU/Linux host
+
+Under GNU/Linux distribution, things are quite simple. Debian variant distributions, like
+Ubuntu, already include SDCC and GPutils packages. All you need to do is to use the
+package manager and install SDCC and GPutils. They also include gpsim. For Redhat like
+distributions, rpm packages also exist, here too you can use your package manager.
+Another alternative is to checkout SDCC and GPutils sources through their subversion
+repository and compile/install them by hand. But this is beyond the scope of this
+documentation.
+
+I-2 BSD host
+
+Under BSD distributions, SDCC, GPUTILS and gpsim packages exist too and are as simple to
+install as in GNU/Linux distributions. Please use your package manager to install them.
+
+I-3 Windows host
+
+Under Windows things are not so straightforward. Indeed, you need to install cygwin before.
+cygwin gives access to same command line tools as in GNU/Linux or BSD distributions.
+
+
+II How to run a demo application
+
+II-1 Compiling
+
+Say you have downloaded FreeRTOS source tree and installed SDCC, GPUTILS and gpsim, go
+to the location where FreeRTOS sources are stored. For this, use your console.
+
+ #cd /path/to/FreeRTOS
+
+Once there, you will find PIC18_SDCC demo applications in the subdirectory
+PIC18_SDCC. Demo applications are implemented in files: main.c, main2.c etc.
+To know what those demo application do, please read description in the
+corresponding main file.
+To compile the main.c demo application, go to PIC18_SDCC subdirectory:
+
+ #cd PIC18_SDCC
+
+and just type:
+
+ #make PIC16_LIB_PATH=/path/to/sdcc/share/lib/pic16
+
+where /path/to/sdcc/share/lib/pic16 indicates where SDCC installed pic16 libraries.
+To avoid having to always set PIC16_LIB_PATH, you can create PIC16_LIB_PATH environmental
+variable and give it /path/to/sdcc/share/lib/pic16 value.
+
+This will generate various files, including:
+ freertos.hex: file you will use to flash your PIC18 device.
+ freertos.cod: file you will use to simulate you application with gpsim.
+ freertos.map: file indicating memory mapping of your application.
+
+To compile another demo application, instead of the default (main.c), just type:
+
+ #make clean
+ #make MAINFILE=alternate_main.c
+
+where alternate_main.c indicates another existing main file.
+
+II-2 Simulating
+
+Assuming that you have installed gpsim and compiled a demo application, to run a
+simulation, just type (in FreeRTOS/Demo/PIC18_SDCC ):
+
+ #gpsim -s freertos.cod
+
+A simulation window will appear and let you to start the simulation if you click on run.
+In windows menu, you will have access to various item as:
+ Breadboard: shows you the device you simulate et pins state
+ Ram: shows you main RAM in an array.
+ Symbols: shows you your application variables and you PIC18 registers.
+ Watch: you can watch here symbols.
+
+III How to add your applications
+
+To add a new demo apllication, or your realtime application, add a file containing your
+main function and task function in the subdirectory FreeRTOS/Demo/PIC18_SDCC.
+And to compile your application, just type:
+
+ #make clean
+ #make MAINFILE=alternate_main.c
+
+Where alternate_main.c is the file containing your new application codes.
+This will generate same files as a demo application, but this time it's your application
+will be compiled.
+At this moment of writing, it is not possible split your realtime application in multiple
+.c/.h files, if you want to use the existing compiling infrastructure (Makefile).
+To this end, you need to write your own Makefile.
+
+IV TODO List
+
+ Modify the compiling infrastructure in order to be able compile multiple source files.
+ Add documentation on how to use IDEs like codeblocks, eclipse.
+ Add demo applications that use more FreeRTOS common demo applications.
+ Add demo applications that use more SDCC libraries (UART, ADC, etc.).
+ Add documentation on how to use others GNU tools to flash you PIC18 MCU.