######################################################################################### # GAYE Abdoulaye Walsimou, # 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 # (Version 2 or later) published by the Free Software Foundation. # # This program is distributed in the hope it will be useful, but WITHOUT # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or # FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License # for more details. # # You should have received a copy of the GNU General Public License along # with this program; if not, write to the Free Software Foundation, Inc., # 59 Temple Place - Suite 330, Boston MA 02111-1307, USA. ######################################################################################### # # \file README # \brief README for the SDCC/PIC18 (pic16 arch in sddc world) port. # \author GAYE Abdoulaye Walsimou, # \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 59 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 Requirements 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. NOTES: At this moment of writing you can compile demo application for all devices that have a script in FreeRTOS/Demo/PIC18_SDCC/lkr subdirectory. By default, when you compile a demo application, you compile it for pic18f452. To use another device just type: #make DEVICE=alternate_device or: #make DEVICE=alternate_device MAINFILE=alternate_main.c Where alternate_device is the device you want (i.e 18f87j60 or 18f4580) 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. NOTES: At this moment of writing you can simulate demo application for the following devices: 18f452 This is because gpsim only support pic18f452, for the moment. 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.