OCP - Open Controller Platform
Users Manual by Jan Pedersen <jp>
Version 0.2

About OCP
OCP - Open Controller Platform is software platform that makes it easy to build a cross-compilation toolchain with C compiler, assembler, emulator and programming tools for embedded systems. This project is inspired by the buildroot project, but unlike buildroot, the target here is micro-controllers like Microchip PIC and Atmel AVR. If you are looking for a platform that is able to build a complete cross-compiled linux system for larger processors, you should have a look at the buildroot project instead.

OCP is useful mainly for people working with embedded systems. Embedded systems often use small micro controllers where an operating system like linux won’t fit in. They run with no operating system at all or a very tiny one like Salvo or FreeRTOS.

A compilation toolchain is the set of tools that allows to compile code for your target. It consists of a compiler, assembler, linker, libraries, emulators and programming tools. The system installed on your development station certainly already has a compilation toolchain that you can use to compile application that runs on your system. If you’re using a PC, your compilation toolchain runs on an x86 processor and generates code for a x86 processor. This compilation toolchain is called the “host compilation toolchain”, and more generally, the machine on which it is running, and on which you’re working is called the “host system”. The compilation toolchain is provided by your distribution, and OCP has nothing to do with it.

As said above, the compilation toolchain that comes with your system runs and generates code for the processor of your host system. As your embedded system has a different processor, you need a cross-compilation toolchain: it’s a compilation toolchain that runs on your host system but generates code for your target system (and target processor). For example, if your host system uses x86 and your target system uses ARM, the regular compilation toolchain of your host runs on x86 and generates code for x86, while the cross-compilation toolchain runs on x86 and generates code for ARM.You might wonder why a tool like OCP is needed when you can download and compile the cross-compiler, assembler and all the tools by hand. Of course, doing so is possible. But dealing with all configure options, with all problems of every compiler or assembler version etc. can be quite time-consuming and uninteresting. OCP automates this process, so you will get a set of tools that is known to work together. Further your micro contoller project will have OCP as it’s only dependency, making it easy to recompile it on another machine whether you’re running fedora, cygwin or possibly most other distributions.

Obtaining OCP
OCP is available as compressed snapshots or directly using SVN.The latest and previous snapshots is always available at http://TBD

To download OCP using SVN, you can simply follow the rules described on the “Subversion Access”-page (https://sourceforge.net/svn/?group_id=171951), and download the OCP SVN module. For the impatient, here’s a quick recip. Replace the version number x.y with the latest or the one you want.for svn:

$ svn co https://jp-ocp.svn.sourceforge.net/svnroot/jp-ocp/tags/x.y .

for snapshot::

$ wget TBD && tar -xzf ocp-x_y.tar.gz

Using OCP
Note that you can build everything as a normal user. There is no need to be root to configure and use OCP. By default, everything is enabled in the OCP configuration, so if you just want to get going, you can just build it by running make:

$ cd ocp
$ make

This command will download, configure and compile all the selected tools, so now go and grap a cup of coffee and lean back.If you intend to do an offline-build and just want to download all required sources so you have them stored locally then issue:

$ make download

Environment variables
OCP optionally honors some environment variables that are passed to make:

ARCH specifies for which architechtures to build tools for.

OCP_CONFIG_FILE  specifies an custom OCP configuration file.

An example that builds only the tools that a valid for the PIC16 and PIC18 architechtures:

$ make ARCH='PIC16 PIC18'

Customizing the OCP configuration
OCP is configurable, and you may want to customize it. The easiest way to customize it is to edit the default configuration file ocp/config.mk. Alternatively, make a copy of the default configurationan file and set OCP_CONFIG_FILE to the location of this when invoking make, like:

$ make OCP_CONFIG_FILE=ocp_myconfig.mk

How OCP works
As said above, OCP is basically a set of Makefiles that download, patches, configure and compiles software with the correct options.

There is basically one Makefile per software package, and they are named with the .mk extension. Each package is located in its own subdirectory in the package directory.

Each package directory contains at least a .mk file which is the Makefile that downloads, configures, compiles and installs the software.

The main Makefile do the job through the following stepsCreate the download directory (ocp/dl/ by default). This is where the tarballs will be downloaded. It is interesting to know that the tarballs are in this directory because it may be useful to save them somewhere to avoid further downloads.

Create the build directory (ocp/build/ by default). This is where all the downloaded software packages will be compiled.The toolchain generated by OCP by default is located in ocp/host/ The simplest way to use it is to build your application by using a makefile. This way, the ocp/host/ directory is automatically added to your PATH environnement variable so you can use sdcc, gpasm, gplib, etc. directly.

Important: do not try to move the toolchain to another directory, it won’t work. There are some hard-coded paths compiled into some of the tools. If you need to move it you will have to do a ‘make clean all’ afterwards to recompile everything.

A basic makefile using OCP
Given you have created a new directory hello_prj/ wherein you have an application hello.c you want to compile for a PIC16C84. You have fetched a copy of ocp into hello_prj/ocp.

Now, you can crate a very basic makefile hello_prj/Makefile like this:

1 all: ocp hello.hex
2 include ocp/ocp.mk
3
4 CC=sdcc -mpic14 -p16f84 --debug
5
6 hello.hex: hello.o
7 gplink -m -o $@ $^

line 1 defines what to build for the default/all target. An dependency to ocp is added before hello.hex. This will build ocp if it is not build, so you actually don’t need to remember to build ocp manually first.

When ocp/ocp.mk is included in line 2, the ocp/host/bin/ directory will automatically be added to the PATH variable, so sdcc and gplink can be called directly.In line 4, we define which compiler and options to use. Make already have an implicit rule that describes how to build .o files from .c files, so we just need the CC variable to tell that we want to use the sdcc cross-compiler by default instead the cc host compiler.

Line 6 describes how to make hello.hex from hello.o. Here, we use the gplink linker from gputils.Now, type ‘make’ and you should end up with a hello.hex, ready to program into your target.

Extending OCP with more software
This section will only consider the case in which you want to add additional software to the OCP build system.

Package directory.
First of all, create a directory under the package directory for your software, for example ocp/package/foo.The .mk fileCreate a file named ocp/package/foo/foo.mk. It will contain the build rules that are in charge of downloading, configuring, compiling and installing the software. Below is an example that we will comment afterwards.

1 #************************************************************************************
2 #** Foo
3 #************************************************************************************
4 FOO_VER=0.5
5 FOO_SOURCE=foo-$(FOO_VER).tar.gz
6 FOO_SITE=http://gforge.enseeiht.fr/frs/download.php/116
7 FOO_DIR=$(BUILD_DIR)/foo-$(FOO_VER)
8
9 $(DL_DIR)/$(FOO_SOURCE):
10 $(WGET) -P $(DL_DIR) $(FOO_SITE)/$(FOO_SOURCE)
11
12 $(FOO_DIR)/.unpacked: $(DL_DIR)/$(FOO_SOURCE)
13 zcat $(DL_DIR)/$(FOO_SOURCE) | tar -C $(BUILD_DIR) -xf -
14 touch $@
15
16 $(FOO_DIR)/.configured: $(FOO_DIR)/.unpacked
17 cd $(FOO_DIR) && ./configure --prefix=$(HOST_DIR)
18 touch $@
19
20 $(FOO_DIR)/.build: $(FOO_DIR)/.configured
21 $(MAKE) -C $(FOO_DIR)
22 $(MAKE) -C $(FOO_DIR) install
23 touch $@
24
25 foo: bar $(FOO_DIR)/.build
26
27
28 #************************************************************************************
29 #** Toplevel Makefile options
30 #************************************************************************************
31 ifeq ($(strip $(PACKAGE_FOO)),y)
32 TARGETS+=foo
33 endif

First of all, this Makefile example works for a single software package. For other software such as libraries or more complex stuff with multiple binaries, it should be adapted. Look at the other *.mk files in the package directory.

At lines 4-7, a couple of useful variables are defined:

FOO_VER: The version of foo that should be downloaded.
FOO_SOURCE: The name of the tarball of foo on the download website of FTP site. As you can see FOO_VER is used.
FOO_SITE: The HTTP or FTP site from which foo archive is downloaded. It must include the complete path to the directory where FOO_SOURCE can be found.
FOO_DIR: The directory into which the software will be configured and compiled. Basically, it’s a subdirectory of BUILD_DIR which is created upon decompression of the tarball.

Lines 9-10 defines a target that downloads the tarball from the remote site to the download directory (DL_DIR).

Lines 12-14 defines a target and associated rules that uncompress the downloaded tarball. As you can see, this target depends on the tarball file, so that the previous target (line 9-10) is called before executing the rules of the current target. Uncompressing is followed by touching a hidden file to mark the software has having been uncompressed. This trick is used everywhere in OCP Makefile to split steps (download, uncompress, configure, compile, install) while still having correct dependencies.

Lines 16-18 defines a target and associated rules that configures the software. It depends on the previous target (the hidden .unpacked file) so that we are sure the software has been uncompressed first. In order to configure it, it basically runs the well-known ./configure script. As we are doing cross-compilation, we might want to set target, host and build arguments. The prefix is set to $(HOST_DIR), which by default is ocp/host/ so the software will be installed locally in the project. Finally it creates a .configured file to mark the software as configured.

Lines 20-23 defines a target and a rule that compiles and installs the software. This target will create the binary file in the compilation directory, and depends on the software being already configured (hence the reference to the .configured file). It basically runs make inside the source directory.

Line 25 defines the main target of the software, the one that will be eventually be used by the top level Makefile to download, compile, and install this package. This target should first of all depend on all needed dependecies of the software (in our example, bar) which then will be build first, and also depend on the previous .build target. This last dependency will call all previous dependencies in the correct order.

Lines 28-33 adds the target foo to the list of targets to be compiled by OCP by first checking if the configuration option for this package has been enabled, and if so then “subscribes” this package to be compiled by adding it to the TARGETS global variable. The name added to the TARGETS global variable is the name of this package’s target, as defined on line 25, which is used by OCP to download, compile, and then install this package.As you can see, adding a software to OCP is simply a matter of writing a Makefile using an already existing example and to modify it according to the compilation process of the software.

If your software package might be useful for others, don’t forget to send a patch to the OCP developers!

Resources
To learn more about the software packages you will get with OCP you can visit these websites:
http://www.gnu.org/software/make
http://sdcc.sourceforge.net
http://gputils.sourceforge.net
http://vasco.gforge.enseeiht.fr/index.php?article=Odyssey.html
http://www.dattalo.com/gnupic/gpsim.html