-
Notifications
You must be signed in to change notification settings - Fork 9
Developer Guidelines
- Preface
- General overview
- Coding and commit conventions
- Building and testing
- Reporting bugs and other issues
- Submitting patches
This is the Developer’s Guide to the ReconOS project. It’s purpose is to show newcomers how to find their way around the repository quickly, and to establish a common basis for collaboration. It’s not meant to impose restrictions, but to give a set of sensible directions to ease collaboration. If, for example, all source code follows a certain set of design guides, it is easier for a contributor from one area of the project to find his way around another part in the source tree.
After all, the Guidelines, too, are open to change. If you have any suggestions for changes, improvements, or additions, please do not hesitate to discuss your ideas on the reconos-devel mailing list.
If you just want to use ReconOS for your own multithreaded applications, you should refer to the ReconOS User’s Guide. At this point, however, it is very likely that using ReconOS means participating in the development of ReconOS itself, so these Developer Guidelines are also a valuable source for information for new users.
There are currently two active mailing lists for ReconOS:
- reconos-devel — carries all discussions and requests regarding the development of ReconOS. This is currently also the place to ask any questions regarding the installation of ReconOS and how to program multithreaded applications using it. TODO: link archives
- reconos-git — receives all commit emails from the github.com/luebbers/reconos repository. It is highly recommended for active developers to subscribe to this list; this way we can catch erroneous checkins and bugs early. This list sets its Reply-To header to the reconos-devel mailing list.
There are three main sources for documentation:
- Publications
- User’s Guide
- Developer Documentation
Currently the best way to get an overview of the concepts of ReconOS are the journal and conference publications.
The most comprehensive summary is probably given in
Enno Lübbers and Marco Platzner. ReconOS: Multithreaded Programming for Reconfigurable Computers. ACM Transactions on Embedded Computing Systems (TECS). Volume 9, Number 1, October 2009, ACM. Link to Publisher
A more extensive description can be found in
Enno Lübbers. Multithreaded Programming and Execution Models for Reconfigurable Hardware. PhD thesis, Computer Science Department, University of Paderborn, ISBN: 978-3-8325-2463-0, 2010. Logos Verlag Berlin. Download PDF
Beyond this, you should probably refer to the User’s Guide and the Developer Documentation. All ReconOS-related publications are centrally referenced here.
The User’s Guide details the ReconOS APIs, installation instructions, tool usage, and generally includes information useful for applying the ReconOS programming model and tool chain to build multithreaded HW/SW applications.
It can be found at the main ReconOS web site. FIXME
The User’s Guide is generated from TeXinfo sources located in the main ReconOS repository.
Contributions to the User’s Guide (e.g., tutorials, tool documentation, API examples etc.) are always and especially welcome.
The Developer Documentation is a collection of articles explaining the internals of the ReconOS infrastructure. They are currently located within this wiki (see the list of pages on the right). See also the “Code to read” section below.
As you will by now probably have gathered, ReconOS builds on top of existing software operating systems, such as eCos and Linux, and extends them to supports hardware threads executed on reconfigurable devices. The main areas of ReconOS are thus
- Hardware threads — these are the executable units of an application mapped to the FPGA
- Hardware infrastructure — this includes the OSIF as well as supporting hardware modules
- OS integration — this is software for managing hardware threads and integrating them with the respective OS kernel
If you are comfortable with C, C++ and/or VHDL, a look at the sources will lead to a better understanding of the way ReconOS works If you come from a hardware design background (i.e. you know VHDL or Verilog), start from top to bottom (i.e., start with the hardware threads and read the OS integration last); if you come from a software background (i.e. you know your way around the eCos or Linux kernel), it may be better to start from bottom to top. This way you’ll see the things first where you’re more likely to contribute in the beginning.
In order to understand ReconOS, knowledge of the following certainly helps and is sometimes ssumed throughout the documentation (listed in order of importance):
- C
- VHDL
- Xilinx tools for FPGA synthesis and implementation (especially the EDK for building reconfigurable SoCs)
- digital logic design
- Python and shell scripting
On the other hand, working with and on ReconOS is a sure way to become more familiar with the above — and there are always people on the mailing list willing to help or give pointers in the right direction!
Hardware threads are written in VHDL and structured in a certain way. A number of good examples for hardware threads are present in the repository under /demos:
- sort_demo
- sort8k.vhd — this thread sorts 8kByte chunks of data and uses message boxes and shared memory
TODO: more examples!
The API used by hardware threads to interact with the operating system is defined in the /core/pcores/reconos package.
The main component of a ReconOS system is the operating system interface (OSIF). The OSIF is built in a modular way so that it can be easily adapted to new bus architectures. Its mein functionality resides in the /core/pcores/osif_core. The individual bus-specific wrappers all refer back to osif_core (see, for example, xps_osif, which incorporates the PLBv46 bus interface).
TODO
The suggested (FIXME) directory structure of the ReconOS repository is as follows:
-
core — source code for central ReconOS components (both software and hardware)
- pcores — all Xilinx EDK IP ores and libraries required by ReconOS. This is where most of the hardware infrastructure is defined
- ecos — official eCos repository augmented with ReconOS extensions
- linux — linux device drivers for ReconOS components; ReconOS-specific kernel patches
- demos — complete ReconOS projects serving as examples
- doc — static ReconOS documentation (User’s Guide, documentation templates)
- support — supporting files and materials (reference designs, code templates, command definitions)
- tests — automated tests (components, simulations, integration tests) including the respective testing frameworks
- tools — components of the ReconOS tool chain
For more details of the respective subdirectories, refer to the README files within.
Version (or release) numbers within ReconOS mostly follow the scheme used for Xilinx IP cores, e.g.:
<ComponentName>_v<Major>_<Minor>_<Micro>where Major is the major release number, minor is a two-digit minor release number, and Micro is a single-letter mirco release identifier. For example, the ReconOS VHDL library package with Major ‘2’, Minor ‘1’ and Micro ‘a’ is located in
reconos_v2_01_aUsually, cores and components used together always have the exact same version identifier. There is an environment variable $RECONOS_VER which is used by the build scripts to choose which core versions to use.
Use
git config --global user.name Foo Bar
git config --global user.email foo@bar.netbefore committing anything to your local repository. This makes sure that your changes are linked to your github account when pushing them to the ReconOS repository. It also makes sense to use the same name and e-mail for all commits, or at least to mention all email addresses in your github account.
Do that now. :)
Keep your commit message summaries short, and one line (< 50 characters is a sensible limit, and actually hinted on when using vim to edit commit messages). These summary messages are used widely within git and github, so try and make them meaningful. Preferably start the summary with a capital letter.
If you want to add a more elaborate description of your commit (which is a good thing), seperate it from the first summary line by a newline, and insert linebreaks at 72 characters, e.g.:
Add workaround for error during partial reconfiguration It seems that the order in which the prmX_YYY_routed_partial.bit.o files are linked to produce the final application .elf file is significant. However, we are unsure whether sorting them by name (as this fix does) helps.
or alternatively, as a list:
Added feature 'foo' to 'bar'
* command XY will now do Z
* function A now expects an additional parameter P
* interface I is now public
See also this blog post by Tim Pope.
The standard convention is to use 4 (four) spaces for indentation in all source files. This has mainly historical reasons; it’s what the eCos sources do, and most existing code in the repository is formatted this way.
If you are using vi(m), use the following configuration:
set shiftwidth=4 set smarttab set expandtab set softtabstop=4
To see whether an existing file uses spaces or tabs (in order not to mess it up when editing), issue:
set listchars=tab:>-,eol:$,trail:.,extends:# set list
FIXME: Emacs users can use the following (haven’t tested this):
(setq c-basic-offset 4) (setq indent-tabs-mode nil)
TODO: We might embed this into the source files themselves.
There are existing tools for automatic formatting of source code. For VHDL, this is vhdl-beautify in tools/bin. For C/C++, you can use indent with the following options:
indent -kr -nut -prs
It is not required to run every file through these filters before submitting patches or commiting into the repository — they are mainly meant as references to keep the style as consistent as possible.
TODO: This style is not consistently carried out within the repository. Change that?
TODO
TODO
TODO