Eclipse SDCC

A small tutorial about how to use Eclipse IDE for SDCC projects under Linux 64-bit operating system (I'm working with Xubuntu 16.04 for now but I'll try to be distro agnostic). It is intended for advanced linux users that knows how to work in console and how to compile and install software from sources. If you don't have that kind of experience, maybe is time to start doing it, or just ask a friend. And almost forgot (as I remembered this after working on the third chapter of this article), this is for my board, Il Pinguino Rosso (PIC18F46K22), that has a serial bootloader. The generated applications will start from the 0x300 address in flash memory.

1. Installing the compiler and assembler


We will get the sources from their own repositories (if you have them already installed from your linux repository, please uninstall them). Lets prepare the folders for that. In your home folder (BTW, you need to have subversion already installed on your linux distro), create a folder named "toolchain" and some other two subfolders:

~$ cd ~
~$ mkdir toolchain
~$ cd toolchain
~/toolchain$ mkdir gputils
~/toolchain$ mkdir sdcc

Now, we will download gputils pic assembler sources from its repository, compile and install it under /usr/local system folder (you need to have sudo rights for that)

~/toolchain$ cd gputils
~/toolchain/gputils$ svn checkout svn://svn.code.sf.net/p/gputils/code/trunk .

Pay attention, at the end of the svn command, there is a dot - don't omit it (if you are a long time linux user, you know how important that is). Just see the image bellow where I point to it with the mouse pointer:



After download finished, we configure, compile and install the software:

~/toolchain/gputils$ cd gputils
~/toolchain/gputils/gputils$ ./configure
~/toolchain/gputils/gputils$ make 
~/toolchain/gputils/gputils$ sudo make install
~/toolchain/gputils/gputils$ cd ..
~/toolchain/gputils$ cd ..


Now that we are back in the toolchain folder, lets download, compile and install SDCC C compiler:

~/toolchain$ cd sdcc
~/toolchain/sdcc$ svn checkout svn://svn.code.sf.net/p/sdcc/code/trunk/sdcc .

Again, pay attention to the svn command, as at the end is a dot - don't miss it. If you screwed, delete the folders created by svn and start again with the proper and complete (including the dot) command. After finishing downloading the sources, we will configure, compile and install the software. The SDCC will compile also for other kind of microcontrollers, let it be as later you may want to migrate to STM8 micros, by example.

~/toolchain/sdcc$ ./configure
~/toolchain/sdcc$ make
~/toolchain/sdcc$ sudo make install
~/toolchain/sdcc$ cd ..


We done also with the SDCC installation, and we are back in toolchain folder. We don't need this anymore, but you may want to keep it, to regularly update to new versions, recompile and reinstall, always having a toolchain up to date.

For now, we go back to the home folder

~/toolchain$ cd ..

2. Eclipse install 


Fortunately, the plugin works also with the latest version of Eclipse so, I won't force you to install an older one. But to be exact, the plugin was modified and tested on Luna and Neon.3 versions of Eclipse. I prefer Luna, as is lighter than the last version, but we will go with Neon.3 for this tutorial.

So download Neon.3 for your Linux (well, it has to be a 64-bit OS):
Now, if you previously used eclipse and there is an eclipse folder on your home folder, just rename it - it won't break anything, as we really need to have the freshly downloaded eclipse archive expanded in home folder.

After expanding the archive in home folder, we got a new eclipse folder which we have to rename it to eclipse_sdcc to keep things in check (now, if you previously had an eclipse folder that you had to rename it, change it back to eclipse, it won't affect us).

3. Installing the plugin and setting the Eclipse


I profoundly dislike the JAVA language, and partly because of its history - I won't go in detail here but I will tell you that I was fan Oberon. Anyway, I had to find a SDCC plugin for Eclipse and I found it. But... it was for the Intel 8051 microcontroller... Fortunately, there are two factors that allowed me to make changes:

  • the plugin interface is composed(described with) from text files, so it was modifiable;
  • the SDCC compiler ignores the parameters that are not suitable for the target microcontroller.

I started the modifications until I got an useful plugin, It still has its quirks but the functionality is there, it will help you generate the hex file from a simple build command. As for the original form of the plugin, you can find it on sourceforge net, under the eclipseSDCC name (I won't give a link, to avoid confusion - you really need my modifications). Many thanks to its author (Steve Jones, @jonesst99).

Note: I didn't touched the JAVA code, if you need and you can develop it further, go to sourceforge and download the original, it comes with JAVA sources (although, I didn't removed the sources from the package I offer). The another project of the same author may come in handy, Building Parsers with JAVA.

Lets continue...  you have to download the plugin from my Google Drive (click the link). After that, expand the archive into eclipse_sdcc folder. This is all. Now, lets configure the Eclipse IDE.

Next, lets start Eclipse for the first time from the eclipse_sdcc folder. On the "Eclipse launcher" window, it will ask you to specify the workspace folder. Choose "workspace_sdcc" to avoid overwriting previous working spaces. Attention, replace the "your_user_name" part from the path, with your real home folder. See the bellow image as example:


Next, we have to make changes for the way Eclipse editor reports language and syntax errors. As you know, the editor use a gnu gcc parser for the C language which is not quite good for our SDCC language. Many things that are correct in the SDCC C language, are wrong in gnu gcc C language and reported as errors by Eclipse editor. This will prevent a normal functionality. By example, you won't be able to see the content of identifiers as tooltips when hovering with the mouse pointer over them. So, lets disable that.

From the Window menu, chose the Preferences option (see bellow).



In the Preferences window, expand the C/C++ category from the left and chose Code Analysis option (as in image bellow):


Now scroll down the panel from the right, until the "Syntax and Semantic Errors" which must be unchecked (the entire tree will be unchecked). Press OK button (see image bellow):


That will be all for now...

4. Acquiring the board library and projects from its repository


Ok, we will download the board library and the projects created up until now from their repository. For this we are creating a folder in our(your) home folder, named rosso_src, moving there and uploading the sources from the svn repository. Lets do some linux commands in console ;P :


~$ cd ~
~$ mkdir rosso_src
~$ cd rosso_src
~/rosso_src$ svn checkout https://svn.code.sf.net/p/rossolib/code/ .

Again, watch out for the dot at the end of svn command. This is all. You may want to keep this folder to update it from the repository, as I have also a few libraries and projects to add. Now, lets import them inside the Eclipse IDE.

Note: Advanced Eclipse users could do this (and the following step) in one step only, importing directly from the repository if they have the plugin Subversive installed. But we won't cover this, as is quite a headache to make this working.

5. Importing the library and the projects into Eclipse IDE


Open Eclipse and close the Welcome page if it appears (uncheck the "Always show Welcome at start up" first). From the File menu, chose Import... option (see image bellow):


In the Import window, expand General category and chose Existing Projects Into Workspace option. Press the Next button (see image bellow):




From the next window, press the Browse... button (see where my mouse pointer is in the image bellow):



Then you have to select the folder rosso_src from your home folder. After that, in the same Import window, a list will be completed with all the projects found in the folder you just selected. Under that list (let those elements checked), it is a list of checkboxes named Options. Check the Copy projects into workspace box and then press Finish button (see image bellow, where I erased my home folder name for obvious reasons):


Now, the library and all the projects are imported in your Eclipse IDE, and listed in the Project Explorer left panel (see image bellow):



A few words about the sdcc_clib project... Although it can be compiled as a normal project, it will do nothing, as is just our library container. All the other projects depends on this one.

Important note: after importing the projects, you must tell Eclipse to reindex the projects, otherwise you won't be able to compile them. Select all the projects: select the first project with the mouse, press the left-shift-button and keep it pressed and click on the last project with the mouse (all will be selected), and then right-click on them to show the menu (see the image bellow):



Here is how it looks after successfully compiled the first project from the list (click on the image bellow):



Now you can compile all the projects and upload the .hex file into your board using the Microchip software from the AN1310 package.

Go here and download the PDF file and the archive containing the sources for the PC application and the bootloader firmware (it has to be modified to work on my board, or download the sources from the Files section of my rosso project - see bellow). The uploader application uses the Qt library.

Compiling the PC application for your system will be exclusively your job, I can't provide you with a binary. Please note that the application is designed to be cross platform. And, you need some experience in, at least, compiling Qt4 applications.

Note: The official address of rosso project on sourceforge.net is https://sourceforge.net/projects/rossolib/
And in the Files section of the project you'll find the schematics and pcb for the Il Pinguino Rosso board, the bootloader source modified by me and the Eclipse plugin (yes, also uploaded here). Moved all in the code repository, just "svn check-it" and you'll have everything, including the bootloader, schematic and pcb for the board, PC application for uploading firmware, etc. Only the Eclipse plug-in remains in the Files section.
 

6. Creating a new project


Good! We are now capable to compile the examples from the repository. But we can also create our own project for the Il Pinguino Rosso board. So, lets create one, a blink a LED project, to see what we need to set for that.Start the Eclipse IDE (is good to start it again, I have a couple of days delay between writing the chapters of this article).

Note: Pay attention! We will do a one time operation, setting the template for our main.c file. This template will be used by Eclipse when we will generate a source file for our project and, as you already saw it, all the projects (except our project-container, sdcc_clib) have only one C file, the main.c.

6.a. Setting the template for the main.c file


We opened the Eclipse IDE already, expand the sdcc_clib project and open the main.c in editor, as in image bellow:



This is the main.c skeleton for every new rosso project. Select the entire text and copy it in the clipboard (just Ctrl+C).

Next step is to simulate the addition of a new source file to an existing project, as we want to set our template. Right-click on the sdcc_clib project from the left panel to open the contextual menu. Hover the mouse pointer over the New option until a submenu will appear - chose the Source File option from there, as in image bellow:



In the window that appear, instead of completing the Source file field, we press the Configure... button, as in image bellow:



In the next window that appears, we will select the New... button - see image bellow:


In the New Template window, we will complete the Name: field with a suggestive name for our template. I went for the Rosso Template for main.c file name. - see image bellow:


Now it should be your choice to complete also the Description: field. But we go for the Pattern: panel anyway. So, move the cursor (caret?) into the Pattern: panel (field) and type Ctrl+A to select the entire content as in image bellow:



Now, type Ctrl+V to replace the content with the content from our clipboard where we copied the main.c file. And it should look like in the image bellow when the operation is done:


Now, just press OK button. The previous window (Preferences (Filtered)) should look like in the image bellow, showing the content of our main.c file as template:



Now you just press OK button and, in the previous window that remains, just press Cancel button, as we don't want to add a new source file to the sdcc_clib project.

This is all and once you've done it, you don't need to repeat it. We will use this template in creating our new project.

6.b. Creating a new project


You will repeat these operations for every project you want to create for Il Pinguino Rosso board using this combo of Eclipse IDE and SDCC C compiler.

So, open the File menu, hover with the mouse pointer over the New option until a submenu is opened: chose the C Project option from there - see image bellow




In the C Project window, write the Project Name: field as rosso_app_blink_led and expand the Others from Project type: list and chose Microchip PIC 16-bit element. Press Next > button as in image bellow:



In the next window, uncheck Debug and press Finish button (see image bellow).


In the Project Explorer left panel you'll see the newly created project:


Now, because we have to create the main.c file, right-click on our new project from the Project Explorer panel to get the contextual menu, Hover the mouse pointer over the New option and from the submenu that appears, chose Source File option:


In the New Source File window that appears, write main.c in the Source file: field, and choose the Rosso Template for main.c file option from the Template: combobox. Press Finish bitton - see image bellow:


We will get the following main.c file where we need to make only very minor modifications to get our on board LED blinking:


So lets modify our main function as bellow, disabling sei() function as we don't need the interrupts for now, and completing the while loop (we will use the precision delays defined inside rosso.h header to obtain a 500 millisecond delay, but we can also use the _delay_ms() function):


void main(void){
    AllDigital();
    OnBoardLED_dir = OUTPUT; 
    OnBoardButton_dir = INPUT; 
    OnBoardLED = OFF;
    //sei(); /* enable global interrupts */
    
    /* add your other initializations and code */
    while (1) {
  /* add your ever repeating code */
     OnBoardLED = ON;
     delay_150ms();
     delay_150ms();
     delay_100ms();
     delay_100ms();
     OnBoardLED = OFF;
     delay_150ms();
     delay_150ms();
     delay_100ms();
     delay_100ms();     
    }
}


Save the file. Now, for the project to compile we have to tune the settings. Right click on the project in the Project Explorer left panel, and chose the Properties option from the bottom of the contextual menu:


A window (well, I know is a modal dialog window, but not all are PC programmers) will appear, named Properties for rosso_app_blink_led. Select the Project References from the left panel and check the sdcc_clib project from the right panel as in image bellow (don't press yet the OK button as we still have more to do in this window - you will get bored by how much we have to do). This tells Eclipse that, when we will open our project, Eclipse will also open the rosso_clib project, as our project depends on rosso_clib project (all our projects will depend on rosso_clib project). Excuse the repetition but is the mother of learning.



Now, we have to tell Eclipse the path of the included folders and the name of the hex file we want to obtain. For this, expand the C/C++ Build element from the left panel and chose the Settings sub-element :



We will specify the name of the hex file. As you see, on the right zone of the window we have 5 Tabs and we will select the third one, named Build Artifact:


In the Artifact name: field, is the ${ProjName} text. We will change that with the main text as in image bellow:


Return back to the first Tab, named Tool Settings and select the Directories element. In the right panel we will add the paths for the included headers (see in the image bellow where my mouse points - press that button):


After pressing that button you will be allowed to browse your file system, adding paths to the header files for your SDCC compiler. First, we will add the paths relative to our working space. Press the Workspace... button from the windows that appears:



From the list that appears, select the sdcc_clib folder and press OK button as in image bellow:


Now, in the previous window, press OK button - see the image bellow:


I know, a lot of images but this is a tutorial for a beginner. Now the result is seen in the image bellow:


Pay attention now, as I won't show images for what is next, because we will add one more path from Workspace, exactly, the folder of our own project, named rosso_app_blink_led. and the result is as in image bellow:



Next, we will add two more paths but from the file system this time. Press Add button and in the window that appears. press the File system... button:


Now you will add the SDCC include folders from /usr/local/share/sdcc ... the final result looks as in image bellow:


Now, is essentially to press Apply button, as in image bellow:



Eventually (as is not happening all the time), you will be presented with another window that it will ask for rebuilding the index. You always answer with Yes but before, check the Remember my decision box:



This is all with the Directories for the SDCC Compiler. Next, we will specify the header path for the SDCC Assembler (nothing to do for the SDCC Linker section, as I did it in the plugin for you). Select the General sub-element under the SDCC Assembler element. Press the Add button from the right panel - as in image bellow:


This is also a file system path, I'll show you the result and you'll know what to do:



Now you can press OK button as we've done with the project setup. Eventually (as is not happening all the time), you will be presented with another window that it will ask for rebuilding the index. You always answer with Yes but before, check the Remember my decision box:


in the Project Explorer panel, you will see that on our project, include paths were added:



Now, select the project name from the Explorer, and press the "Hammer" button to compile the project:


The build should be successful (if not, restart the tutorial from scratch until your brain automates everything - until you get reflexes):


And this ends the chapter. What should I say next? I will add more libraries and project examples, but no promise...

This is all I got from this Eclipse plugin that wasn't designed for PIC microcontrollers. A more versed person than me, JAVA proficient, will be able to make a better and complete adaptation to PIC microcontrollers or even rewriting it from scratch.

It works well as it is now, but it is very "my board" oriented, the plugin needs to be more general, addressing all the PICs from both families supported by the SDCC compiler. Thank you for your patience in following this tutorial!

7. A few words about the PC application that helps us upload the hex files into Il Pinguino Rosso board


Well, what should be here? How to compile it under Linux and how to use it? I feel that is somehow redundant, you guys are smarter than me anyway... Will see... I need more time. Or your reaction...

No comments:

Post a Comment