Oscar Software Framework Manual Development and Compilation
Go to Table of Contents.
Source code for software development based on the Oscar framework is divided into the following parts: application (App), oscar framework (Oscar) and an optional firmware application interface (Firmware). These three elements are usually maintained by an individual revision control repository.
The Oscar library is compiled for a specific board type (leanXcam, indXcam). In case of the indXcam, a dedicated Lgx module is required which defines the API for functionality provided by the on board CPLD.
The compilation order should be used as indicated above. The two resulting libraries are used for the application development.
The framework has been implemented in the open-source integrated development environment Eclipse http://www.eclipse.org/ with the CDT http://www.eclipse.org/cdt/ plugin. Project meta-data is also stored in the repository so developers can import it.
As a programming language, C is used in the Oscar framework for the following reasons:
- It produces very fast and compact code.
- It can easily be interfaced with by applications in C as well as C++.
- When designing and programming with discipline, the implementation can be structured in an object-oriented fashion with strict encapsulation, just like any object-oriented language. This improves the reusability and maintainability of the code.
- Interfacing with drivers and system calls is most natural in C.
To document the code, doxygen-style comments were used to produce automatically generated documentation. Since the target architecture, Blackfin http://en.wikipedia.org/wiki/Blackfin, does not feature an MMU http://en.wikipedia.org/wiki/Memory_management_unit and thus has no virtual memory, care is taken not to dynamically allocate and free any memory from the heap. This would create memory fragmentation over time and may result in not being able to allocate a sufficiently large block of memory even if there is enough available. The host platform does not suffer from this condition, which is why this restriction does not apply to the implementation for the host.
On the target, persistent variables and arrays are statically defined in the object structure belonging to each module. Memory only required temporarily either uses the stack (e.g. by declaring an array locally in the function), or one of these object members if the data is needed across different methods.
The lack of virtual memory also means that the stack is not growing dynamically, but rather has a fixed size. For this reason, recursive computations are avoided and the amount of variables allocated on the stack is kept low.
The compilation is managed by the GNU make program. The framework provides the following make targets:
- config: Configure the board an framework.
- all: Compile target as well as host library.
- target/tagetdbg: Create only the static library for the target
- host: Create only the static library for the host
- clean/distclean: Clean all generated files.
On compilation, all files required by a client application are moved to the staging/ directory. Therefore only the contents of this directory have to be copied to the directory where the application code resides. It contains the static libraries in the staging/lib/ folder as well as all required header files in the staging/inc/ directory.
- Copy the contents of the staging/ directory to the location of the application. The app-template makes use of soft links on make config.
- Include inc/oscar.h in the application. This indirectly includes all necessary information for all modules.
- Depending on the target platform:
- Define OSC_HOST and link with the host version of the library. In gcc for example:
gcc test.c lib/libosc_host.a -DOSC_HOST -o test
- Define OSC_TARGETand link with the target version of the library. In gcc for example:
bfin-uclinux-gcc test.c lib/libosc_target.a -DOSC_TARGET -o test -Wl,-elf2flt="-s 1048576"
Above example also increases the stack size to 1 MiB.
- Create a new folder with the name of your module
- Copy the contents of another module folder and adapt the module-name prefixes of the files.
- Change all references to the copied module name to the name of the new module in the source code.
- Adapt the dependencies in your module declaration (OscModule_xxx)
- Add the name of your module to the MODULES variable in the board files for all your supported architectures (e.g. oscar/boards/leanXcam.mk and oscar/boards/indXcam.mk)
- Add the header file with the global API declaration and structure definition to the oscar include directory (oscar/include/xxx.h)
- Create a new folder with the name of your module
- Copy the contents of another module folder and adapt the module-name prefixes of the files.
- Change all references to the copied module name to the name of the new module in the source code.
- Adjust the Makefile in your module folder to the correct file names.
- Add your module to the main Makefile by appending it to the MODULES variable (MODULES += ''module-name'')
- Add a new member with the name of your module to the framework object in oscar_intern.h.
- Add a test if your module has been unloaded in OSCDestroy() in oscar.c.
- Include your public header file in oscar.h.
- Choose a new error identifier offset in oscar_error.h and create an enum with your custom errors in your public header file starting with that number.