From RTEMSWiki
Jump to: navigation, search

If RTEMS is to participate in Google Code-In, then we have to have a nice list of small tasks divided into the following categories. This is the list that participants can see for general information but the specific tasks will be in a spreadsheet imported into Melange.

Google Code-in



Run and Modify GSOC Hello World Procedure

This task can be performed once per student. It gives you "task credit" for installing the RTEMS development environment which is needed to perform some of the other tasks.

Task Description

This task consists of following the instructions at and helping improve the instructions.

We want you to use a GNU/Linux distribution but it does **NOT** have to be Fedora or CentOS as recommended in the GSOC instructions.

Directions for Students

Follow the instructions at **EXCEPT**:

Sequence with RTEMS Source Builder

The following is a sample set of commands with the RTEMS Source Builder.

$ git clone git://
Initialized empty Git repository in /tmp/rsb/rtems-source-builder/.git/
remote: Counting objects: 3262, done.
remote: Compressing objects: 100% (3019/3019), done.
remote: Total 3262 (delta 2113), reused 435 (delta 222)
Receiving objects: 100% (3262/3262), 2.13 MiB | 837 KiB/s, done.
Resolving deltas: 100% (2113/2113), done.
$ cd rtems-source-builder/
$ ./source-builder/sb-check 
RTEMS Source Builder - Check, v0.2.0
Environment is ok
$ cd rtems
$ ../source-builder/sb-set-builder \
     --log=l-sparc.txt \
     --prefix=${HOME}/rtems-4.11-work/tools 4.11/rtems-sparc

If you want tools for another architecture, replace **sparc** with another architecture such as arm or mips.

At this point, you should be able to clone RTEMS and build hello world.


Student Host OS RTEMS Target RPMs or RTEMS Source Builder Feedback
Adit C. Ubuntu 13.04 sparc-rtems4.11 Source Instructions were fairly straight forward, however I experience some trouble initially due to missing packages. I had to install the latest versions of bison, cvs, g++, flex, and texinfo. I may have had to do so since I am running Ubuntu 13.04 on a virtual machine in OSX Mavericks. I also had to python2.7-dev installed. Nonetheless, once these packages were installed, I was able to get things done relatively easily.
Daniel R. Fedora 19 sparc-rtems4.11 RPMs easy enough but GPG instructions required Google
Pavel Z. Ubuntu 13.04 sparc-rtems4.11 Source Overall the wiki was clear on what was required. The configuration file did not accept --enable-tests=samples, so I had to consult documentation to build the hello world application found in the git repository myself. Also RTEMS was very specific with the automake version it wanted: I had to compile 1.12.2 from source
Bryan D. Arch Linux sparc-rtems4.11 Source While compiling the tools and RTEMS I only encountered two problems. The first one was with binutils; for some reason, it refused to compile outside the source directory, so I compiled it in the source directory. The second problem was with building RTEMS itself. The error was easy to fix though and just required removing the --disable-posix flag when calling ./configure.
Chirayu D. Arch Linux sparc-rtems4.11 Source I had to install an older version of texinfo, but other than that it worked fine. I did not use the --disable-posix flag when calling ./configure.
Kevin F. Linux Mint 13 LTS sparc-rtems4.11 Source I made lots of errors myself, but overall the instructions were fairly clear. Perhaps the RSB Quick Start should explain moving executables a bit more (like where to find them) and the RTEMS Quick Start should have remarked that you should put export the PATH to the tools bin you compiled. I needed python2.7-dev installed.
Radu T. CentOs 6 sparc-rtems4.11 RPMs I've had some trouble following the instructions, though it's probably from the lack of experience. The Getting Started and the Quick Start page are pretty precise, but I had to go on Google a bunch of times and there was some code that didn't work (for example --disable-posix). Also, for some reason, I had to write the full path to the hello.exe when calling sparc-rtems4.11-gdb - otherwise it refused to find it. I found it a bit hard at first to generate the path, because the instructions weren't all in the same place and not exactly complete.
An Ha Arch Linux sparc-rtems4.11 Source The directions were easy to follow, however, when running the source-builder, sb-check and sb-set-builder, I had to change the first lines from /usr/bin/env python, to /usr/bin/env python2, otherwise it would run the code in python 3, not 2. I also had to install texinfo-legacy from AUR instead of texinfo to fix the problem when building binutils (as stated in the documentation). I also did not have to use the --disable-posix flag when calling ./configure.
Zsolt Sz. Xubuntu sparc-rtems4.11 Source I was having some troubles at the beginning, but now I hope that everything will work out fine.
C. Tan Ubuntu 13.10 64-bit sparc-rtems4.11 Source I had some trouble getting the RTEMS compiler to be compiled from source code, mainly the binutils and gcc, even though I had followed the Quick Start closely. These required some Googling, and I eventually found out I had to downgrade texinfo ( alternatively I believed I could have installed the patch: ) and install python-dev respectively. Other than that, the Quick Start was very concise and clear.
Evan M. Ubuntu sparc-rtems4.11 Source I found the directions straightforward, although I do admit I had some trouble from time to time. It also seemed like several pages contradicted each other, but that might have been on my side due to my lack of experience.
Kkvazar Q. Fedora 20 sparc-rtems4.11 Source I wasn't able to finish the task, because I got lost in the documentation, the pages weren't well related and were contradicting. Some useful pages weren't easy to find such as the git README.

I expected sb-check to tell me about missing devel libs, but it didn't. 'bootstrap' was hard to find and it failed on missing files. Most of the questions I had were asked online, but weren't answered.

Investigate a specific Problem Report

PRs Addressed in GCI2013

Please make the PR number a clickable link and you can use where NNN is the number.

Student PR Remaining Actions for Mentors
Daniel PR 1298 Apply patch
Daniel PR 1427 None, close PR
Daniel PR 1428 Apply patch
Daniel PR 1731 None, close PR
Daniel PR 2068 Apply patches to 4.10 and 4.9
Daniel PR 2124 Issue identified, decide how to patch bug (see text on PR)
Daniel PR 788 Issue identified, solution proposed, I will patch this if given the go ahead.
Daniel PR 1361 Apply patch to 4.10 and 4.9
Daniel PR 1735 None, close PR
Daniel PR 1704 Apply patch
Chirayu PR 1323
Chirayu PR 1548 Apply to 4.10 and 4.9
Chirayu PR 1960
Chirayu PR 1194
Chirayu PR 1360
Chirayu PR 1216
Chirayu PR 1422

Convert RTEMS Example Applications to Waf builds

Building RTEMS applications can be a daunting task for new users. How to fit their build requirements with the set of headers and libraries that comprise RTEMS can be challenging. This effort will help users by providing example applications that use a flexible build system, Waf, for compiling applications.

Task Description

This task involves creating a wscript in a subdirectory of the examples-v2.git RTEMS repository, adding the recurse() call in the parent directory to invoke the new wscript, and implementing the build logic for the new wscript based on the Makefile located in the same directory as the new wscript. The deliverable is a patch that contains a single commit with your new wscript and the requisite modification to the wscript in the parent directory.

Pre-requisite Steps

The conversion effort for examples-v2.git is being done on a branch of a fork of the upstream repository on github at

You should clone the modified examples-v2 repository for this task. If you have a github account, you may fork the repository to your account and then clone it to your workstation. The details for how to do this are beyond the scope of this write-up, but the GitHub Help may be useful. The waf modifications are on the waf_conversion branch, which you can get to by doing "git checkout -t remotes/origin/waf_conversion".

Once you have cloned the repository and checked out the waf_conversion branch, the next step is to make sure you can build what is already there. Building will require an RTEMS Tool Set and an installed RTEMS. If you have done the Getting Started task then you will already have a tool set. To install RTEMS you should do 'make install' after successfully doing 'make' for RTEMS. You will also need to download Waf by going to the Downloads tab and downloading of the "run from writable folder" files. You should place the waf file in a folder that is in your path. I use $HOME/bin. Now you should be able to build the already-converted examples by issuing the following commands:

waf configure --rtems=${INSTALLED_RTEMS_PREFIX} --rtems-tools=${INSTALLED_TOOLSET_PREFIX} --rtems-bsps=sparc/sis

This should not give any errors. If it does, then please ask for help. Now build:


And run the hello world sample:

${INSTALLED_TOOLSET}/bin/sparc-rtems4.11-run build/sparc-rtems4.11-sis/hello/hello_world_c/hello

And you should see the Hello World output. If you don't, please ask for help.

Now that you have verified that you can build an example with waf, it is time to get to work!

Directions for Students

If this is your first time doing one of these tasks, make sure you follow the pre-requisite steps above.

Your task description lists a specific subdirectory of the examples-v2 for you to add a wscript. There are two cases:

  1. If the directory only contains a Makefile and subdirectories, this is an easy task to finish. First inspect the Makefile. It should only contain some lines that add subdirectories to the SUBDIRS variable. Just copy the hello/wscript to your directory, and delete the bld.recurse('hello_world_c') line. Now add a bld.recurse() for your directory in the bld() function of the wscript file in the parent directory of your directory, which is probably the root directory of the examples-v2 repository. You're finished! (Almost.) Now "git commit" your work (remember to add the new wscript file!) and you can "git format-patch" to create your submission. Before you submit, you should verify your work by re-running the above "waf configure" and "waf". Since your bld() command does not do anything, you may like to try adding a print statement in your bld() command of the new wscript just to see that the recurse() is reaching your new wscript. (Do not submit a patch with the print statement.)
  2. Otherwise the directory contains a Makefile that builds an example application. TODO

Directions for Mentors


POSIX Compliance Improvement


The reason programs are able to work across different operating systems is because there are standard functions that a developer can expect to see on the system. In the early days, when these standards didn't exist, programmers had to keep reinventing the coding wheel. Now, developers of *nix operating systems, such as FreeBSD and Linux are working toward a standard interface called POSIX. Many *nix operating systems use a standard C library to ensure the functions developers expect to see in the C language are available for use, RTEMS uses Newlib. The evolving POSIX standards change which functions need the restrict keyword

Missing Restrict Keyword

Note: this description can be used for ~16 headers (or 16 tasks).

The restrict keyword prevents two addresses from pointing to the same address.

This task consists of generating a .diff with the restrict keyword in the indicated .h file and the .c file with the functions needing the restrict keyword.

This is a quick set of guidelines on what is needed to complete the task:

  • modifications to a .h file. When you add "__restrict", if the line length exceeds 80 characters, figure out how to break the line up nicely so the line length is less than 80.
  • modifications to zero or more .c files
    • some may be in newlib. There may be zero, one, or multiple copies in newlib which need to have __restrict added. Ignore files in newlib that are below a "linux" directory.
    • some may be in RTEMS. There will either be zero or one copy in RTEMS.
  • If you modify a.c file in newlib, check the top of the file for comments which are the documentation. That needs to be updated also.
  • You will end up with two or three deliverables:
    • patch for newlib
    • (maybe) patch for RTEMS
    • ChangeLog entry in its own file.

Students, see the details below the mentor instructions.

Mentor Instructions

Check the student's implementation against the POSIX 2013 documentation linked from the task description in Melange. Here are some additional guidelines:

  • .h file has restrict per POSIX specification
  • grep for function bodies (if they exist) in .c files in both Newlib and RTEMS, check that they have restrict added
  • Verify any docs in Newlib in file header comments need fixing.
    • only present if there is a body
  • need a name and email for change log entry
  • ChangeLog entry should be provided in the right format
  • newlib/RTEMS should compile

Detailed Instructions

To complete this task, generate a .diff that adds the restrict keyword. Below are some steps to make this happen. Please see and/or

0. check-out either the newlib cvs or rtems git

cvs -z 9 -d co newlib && cvs checkout mymodule

-- OR --

git clone git:// && git checkout -b mymodule

1. find the functions to add the restrict keyword to by looking up the header(s) in

2. find where the symbol needs to be changed

# change to the newlib directory, then find the files with the symbol
cd src/newlib && cscope -k `find . -name "*.[ch]"` 

-- AND/OR --

# change to the cpukit directory, then find the files with the symbol
cd rtems/cpukit && cscope -k `find . -name "*.[ch]"`

3. add the restrict keyword as done in the appropriate restrict examples below. (Note the use of __restrict not restrict.) This is necessary to ensure the code can support C89 as well as C99.

If the method is mentioned in a file with a name with a number as the extension (e.g., iconv.3), it is a man page source file. In this case use restrict NOT __restrict.

If the changes result in a line being longer than 80 columns in a .h file, then break the change into multiple lines but remain compact. This is part of an email from a newlib maintainer with an example:

>> -_EXFUN(iconv, (iconv_t, char **, size_t *, char **, size_t *));
>> +_EXFUN(iconv, (iconv_t, char **__restrict,
>> +               size_t *__restrict, 
>> +               char **__restrict, 
>> +               size_t *__restrict));
> ...this could be a bit more compact:
>   _EXFUN(iconv, (iconv_t, char **__restrict, size_t *__restrict,
> 		 char **__restrict, size_t *__restrict));

4. Make sure it builds OK. For both, you will need a toolset installed. Please take a hello world task for the tools. :)

Newlib short build instructions assuming the placement of newlib and its configure script and a sparc-rtems4.11 toolset.

mkdir b-newlib 
cd b-newlib
../newlib-cvs/src/configure --target=sparc-rtems4.11 --enable-threads
make >/dev/null
# You should see no warnings or errors from files you touched in the above
make info >/dev/null
# You should see no warnings or errors from files you touched in the above

Instructions for building RTEMS should be in the Hello World task.

5. generate the .diff

cvs diff -u > ../add_restrict.diff
-- OR --
git add filename && git commit filename
git format-patch master --stdout > fix_empty_poster.patch

6. submit the .diff or .patch, along with a ChangeLog entry in a separate file (named "ChangeLog") for the newlib modifications.

Newlib Patch Example

2013-07-19 Sahil Patnayakuni <>

	* libc/sys/linux/include/netdb.h, libc/sys/linux/net/getaddrinfo.c,
	libc/sys/linux/net/getnameinfo.c: Add restrict keyword to getnameinfo()
	and getaddrinfo() to increase standards compliance and match glibc.

Index: libc/sys/linux/include/netdb.h
RCS file: /cvs/src/src/newlib/libc/sys/linux/include/netdb.h,v
retrieving revision 1.2
diff -u -r1.2 netdb.h
--- libc/sys/linux/include/netdb.h	22 May 2008 21:30:23 -0000	1.2
+++ libc/sys/linux/include/netdb.h	19 Jul 2013 13:33:55 -0000
@@ -256,10 +256,12 @@
 /* void		sethostfile(const char *); */
 void		setnetent(int);
 void		setprotoent(int);
-int		getaddrinfo(const char *, const char *,
-			    const struct addrinfo *, struct addrinfo **);
-int		getnameinfo(const struct sockaddr *, socklen_t, char *,
-			    socklen_t, char *, socklen_t, unsigned int);
+int		getaddrinfo(const char *__restrict, const char *__restrict,
+			    const struct addrinfo *__restrict,
+			    struct addrinfo **__restrict);
+int		getnameinfo(const struct sockaddr *__restrict, socklen_t,
+			    char *__restrict, socklen_t, char *__restrict,
+			    socklen_t, unsigned int);
 void		freeaddrinfo(struct addrinfo *);
 char		*gai_strerror(int);
 int		setnetgrent(const char *);
Index: libc/sys/linux/net/getaddrinfo.c
RCS file: /cvs/src/src/newlib/libc/sys/linux/net/getaddrinfo.c,v
retrieving revision 1.3
diff -u -r1.3 getaddrinfo.c
--- libc/sys/linux/net/getaddrinfo.c	8 Sep 2008 22:25:14 -0000	1.3
+++ libc/sys/linux/net/getaddrinfo.c	19 Jul 2013 13:33:56 -0000
@@ -1473,8 +1473,9 @@
-getaddrinfo (const char *name, const char *service,
-	     const struct addrinfo *hints, struct addrinfo **pai)
+getaddrinfo (const char *__restrict name, const char *__restrict service,
+	     const struct addrinfo *__restrict hints,
+	     struct addrinfo **__restrict pai)
   int i = 0, j = 0, last_i = 0;
   int nresults = 0;
Index: libc/sys/linux/net/getnameinfo.c
RCS file: /cvs/src/src/newlib/libc/sys/linux/net/getnameinfo.c,v
retrieving revision 1.2
diff -u -r1.2 getnameinfo.c
--- libc/sys/linux/net/getnameinfo.c	22 May 2008 21:30:27 -0000	1.2
+++ libc/sys/linux/net/getnameinfo.c	19 Jul 2013 13:33:56 -0000
@@ -160,9 +160,9 @@
-getnameinfo (const struct sockaddr *sa, socklen_t addrlen, char *host,
-	     socklen_t hostlen, char *serv, socklen_t servlen,
-	     unsigned int flags)
+getnameinfo (const struct sockaddr *__restrict sa, socklen_t addrlen,
+	     char *__restrict host, socklen_t hostlen, char *__restrict serv,
+	     socklen_t servlen, unsigned int flags)
   int serrno = errno;
   int tmpbuflen = 1024;

RTEMS Patch Example

 diff --git a/cpukit/libcsupport/src/readdir_r.c b/cpukit/libcsupport/src/readdir_r.c
 index ba0e53a..0347f25 100644
 --- a/cpukit/libcsupport/src/readdir_r.c
 +++ b/cpukit/libcsupport/src/readdir_r.c
 @@ -20,7 +20,11 @@
   *  The RTEMS version of readdir is already thread-safe.
   *  This routine is reentrant version of readdir().
 -int readdir_r(DIR *dirp, struct dirent *entry, struct dirent **result)
 +int readdir_r(
 +  DIR *__restrict dirp,
 +  struct dirent *__restrict entry,
 +  struct dirent **__restrict result
       *result = readdir(dirp);
       if (*result)

6. ChangeLog entry in GNU format. Notice there are two spaces after the date and a tab in front of each line of the text block. Not that the individual methods must be listed. This is an example:

2013-11-21  Julio Gutierrez <>

        * libc/include/glob.h (glob): Add restrict keyword.
        * libc/posix/glob.c (glob): Ditto.

2. XSI Conformance

There are 22 header files to review. Each header file is considered a GCI task. Some of these will likely not result in code modifications. Others will.

This task is similar to the CX one except the Open Group "code" is different. Some XSI annotations specify additional or modified requirements. Some methods are additions. [1] is an example of an extension. The C macro used to guard the methods definition is TBD.

More in depth task description to be added later

The standard for XSI conformance is: An example of how a user would use XSI conformance is:

XSI Conformance Deliverable

A .diff with the appropriate guards added

XSI Conformance Method

  1. follow the steps above to checkout a branch for either newlib or rtems.
  2. Look up the functions that need to be guarded in the indicated header by changing clicking on and changing dirent.h to match the header being worked on in the URL
  3. add compiler guards to the indicated functions
    1. [OB XSI] #if __XSI_VISIBLE < 700
    2. [OB XSI] #endif /* __XSI_VISIBLE < 700 */
    3. [XSI] use compiler flags to match (change dirent.h to match the header being worked on)
  4. format a patch using the steps above, and submit it to melange

XSI Conformance Example

void     seekdir(DIR *, long);
long     telldir(DIR *);
#endif /* __XSI_VISIBLE */

Mentor Guidelines

  1. Verify the style matches
  2. Verify the patch applies
  3. Verify the software (either newlib or rtems) builds

3. CX Conformance

There are 14 header files to review. Each header file is considered a GCI task. Some of these will likely not result in code modifications. Others will.

CX is POSIX shorthand notation for Extension to the ISO C standard. Any methods marked in the standard as CX are related in come way to the C99 standard. Some of these include additional functional requirements. For this project, we are focused on the methods and constants that were NOT part of C99 but are part of POSIX 2008. These should be wrapped in a conditional such as __USE_XOPEN2K8. The exact conditional depends on when the method was added. [2] is an example page for a method that is an addition to the C99 standard.

This meaning of CX is explicitly defined here: POSIX 2008+

"Extension to the ISO C standard

The functionality described is an extension to the ISO C standard. Application developers may make use of an extension as it is supported on all POSIX.1-2008-conforming systems.

With each function or header from the ISO C standard, a statement to the effect that "any conflict is unintentional" is included. That is intended to refer to a direct conflict. POSIX.1-2008 acts in part as a profile of the ISO C standard, and it may choose to further constrain behaviors allowed to vary by the ISO C standard. Such limitations and other compatible differences are not considered conflicts, even if a CX mark is missing. The markings are for information only.

Where additional semantics apply to a function or header, the material is identified by use of the CX margin legend."

CX Annotation for Newlib Headers

Add a note above any function that is marked by a CX in the Open Group header definition and is defined to be "added from..."

NOTE: observe there are two spaces before NOTE: and two spaces after NOTE:

NOTE: line length less than 80 characters

NOTE: one line of white space above NOTE:

 * ...
 *  Definitions of the following may be omitted if the value is >= stated
 *  minimum but is indeterminate.
 *  NOTE:  LOGIN_NAME_MAX is named LOGNAME_MAX under Solaris 2.x.  Perhaps
 *         the draft specification will be changing.  jrs 05/24/96
 *  NOTE:  The functionality described is an extension to the ISO C standard,
 *         any conflict with the ISO C standard is unintentional. your initials mm/dd/yy
CX Annotation for RTEMS Headers

NOTE: line length less than 80 characters

NOTE: one line of white space above @remark

 * Pun for SunOS prior to 3.2.  SunOS 3.2 and later support TIOCGWINSZ
 * and TIOCSWINSZ (yes, even 3.2-3.5, the fact that it wasn't documented
 * notwithstanding). 
 * @remark The functionality described is an extension to the ISO C standard,
 * any conflict with the ISO C standard is unintentional. your initials mm/yy/dd


Given a first pass of which files we would like to improve Doxygen in, there are at least 55 tasks in this category assuming 10 files per GCI task.

Tasks related to improved RTEMS "Doxygenation"; you should also read through Doxygen_Recommendations.

Add Doxygen File Headers

Special thanks to Gedare Bloom, Jennifer Averett, and Sebastian Huber for instructions on writing and checking Doxygen comments. The RTEMS source base has been in a long process to use Doxygen. But since Doxygen is newer than RTEMS, there are still lots of files which don't have the bare minimum of even a proper Doxygen file header comment block. These tasks consist of editing a set of files to provide a proper Doxygen style file header comment block to RTEMS source files, and merging any comments that precede any method declaration in the .c file into the Doxygen comment block preceding the method's prototype in the approriate .h file.

Check out the Doxygen Recommendations for BSPs page for a detailed guide useful in completing these tasks.

This task is a little tricky: there are two desired header formats:

  1. The top of the file has an @file, @ingroup, and @brief
  2. The middle of the file has an @ingroup and @brief

The format of the @brief is different for the top of the file and the end of the file.

  1. locate the .h file for a .c file
  2. Add the headers
  3. Check your work
  4. Continue to check your work until you're ready to submit
  5. Format the patch
  6. Submit your work
Locating the .h file for a .c File

Identifying the group a function is in is one of the key points of having Doxygen headers. To identify which group a function is in, locate the .h file where the function is, and use the group defined in the @defgroup tag. For example, for cpukis/score/src/watchdoginsert.c, the @ingroup would be based on this line from cpukit/score/include/rtems/score/watchdog.h:

Identifying the Group
/* @file                                                cpukit/example/include/example.h
 * @defgroup ScoreWatchdog Watchdog Handler

The tag above defines the handle ScoreWatchdog and says it has the printable name Watchdog Handler. Thus cpukit/score/src/watchdog.c would use

/* @file // only used for the first header in a file
 * @ingroup ScoreWatchdog
Locating the File

To locate the .h file where the @defgroup (for the @ingroup) is, you can use grep as follows:

cd rtems/cpukit/DIRECTORY
grep -r rtems\_random\_function include

DIRECTORY should be replaced with the appropriate subdirectory based on the file being edited. For the first tasks of this type, this will be score, rtems, sapi, or posix.

  • If you locate the prototype for the method in the RTEMS source, then merge the comments in the .c file into the appropriate .h file. Please put the the comments from the .c file to the .h file Doxygen comment block above the function.
  • If you do not find the function in a .h, do NOT remove the comments above the function in the .c file. Edit any existing comments to turn them into proper Doxygen comments. Some functions in the cpukit/posix/src or cpukit/libcsupport directories are prototyped by the C library, so you may not find their prototypes.
  • Examples: The methods in cpukit/rtems/include/rtems/rtems/event.h provide a good example of how RTEMS uses Doxygen. When in doubt, there is online documentation for Doxygen at and you can always ask questions via the Google Code In site or in #rtems on IRC freenode.
Add the Headers

Once the @ingroup is found, the next step is to add the headers. For each file, there are two types of headers. The first header has an @file, an @ingroup and a Table of Contents @brief. The other headers DO NOT have an @file, but DO have an @ingroup and a Topic Sentence @brief. Please see the examples.

First Header in a File

Desired Format (at the top of the file):

line 1                                                cpukit/example/example.c
 * @file
 * @ingroup GROUP_FROM_dot_h_FILE
 * @brief Brief Description for Table of Contents

 * The copyright should exist in every file already, but the header will have 
 * to be edited and the copyright remain below and in a separate comment block.

Advice on first header in file @brief contents: The @brief text for classes and files is what will show up in a Table of Contents. The key is short, English suitable for Table of Contents. For a file with a single method, it might be the method's name in English. For example: The file with the _Chain_Initialize() method should use something like "Initialize a Chain" for the @brief text. In many cases, the .h file with this method prototyped will have an @brief which is suitable for use. In other words, you can use the @brief text from the .h file description of the same method. See above for instructions on locating the appropriate .h file. Some guidelines:

  • The first header's @brief text for classes and files will show up in Table of Contents. Use capitalization like section or chapter headings
  • Do not end the first header's @brief with a period
Other Comments in a File

Desired Format (in the middle of the file):

    ...                                              cpukit/example/example.c
    return 55;
line 10+
 * @ingroup GROUP_FROM_dot_h_FILE
 * @brief Topic sentence describing a function, if it goes over 79
 * characters, please put on the next line.
  • Other header's @brief text for classes and files will show up in Function Descriptions. Use a topic sentence structure.
  • End the other header's @brief with a period

Make sure there are no tab characters embedded in the changes. RTEMS does not embed the tab character. Check your editor setting and look for one that inserts spaces and not tab characters. The tab default size is 2.

Checking Your Work (How to Run Doxygen)

One way to quickly become a quality coder is to make sure your code does what it's supposed to. This code is used to generate cross-references needed for certifying RTEMS in safety critical applications, as well as, telling our users (such as embedded software developers working for car manufacturers and aerospace corporations) what each function does. There are several ways to see what html is produced by the Doxygen comments written.

Advice: please just use ONE method.

Method 1 Calling Doxygen Directly
  1. Install doxygen
  2. Get the Doxyfile
    1. Copy the File:Doxyfile.diff to a directory outside of the RTEMS directory.
    2. Rename Doxyfile.diff to Doxyfile.tar.gz
    3. Extract it outside the RTEMS directory
    4. Open the Doxyfile in a text editor and edit line 577 to point it at the directory you want to generate documentation for, as well as lines 28 and 41 to rename the resulting folder
  3. call doxygen from the rtems directory
~/rtems> doxygen ../Doxyfile
~/rtems> firefox cpukit_doxy/html/index.html
  1. Click on Modules
  2. Click on your module
  3. ctrl+f Function Documentation

Once you're done looking, delete the cpukit_doxy

~/rtems> rm -rf cpukit_doxy
Method 2 Using the do_doxygen script

UPDATED: There is a newer do_doxygen script available at [3]. Your environment needs to have the root directory of rtems set in the variable r so that $r prints the path to rtems, and the script takes as argument a relative directory from there to generate the doxygen, for example to generate the doxygen for all of libbsp you would do:

export r=~/rtems
./do_doxygen c/src/lib/libbsp

And it should just work.

Outdated: There is a shell script do_doxygen in the same ftp directory as the list of files to edit It assumes the directory layout in the RTEMS Virtual Machine. There is another shell script in that directory named build_doxygen which takes command line arguments.

Format the Patch (How to Run Doxygen)

Please submit a patch generated by git.

Please select a suitable name by replacing "gci-doxygen-task2.diff" with something that relates to your task. You can add an extra '-2' to the name, for example "gci-doxygen-task2-2.diff" if you need to submit more than one diff as a result of reviews.

You can do this with a git command similar to:

$ git diff > gci-doxygen-task2.diff
Directions for RTEMS Mentors

Task Count: Across 4 directories, a search indicates there are ~800 files with this problem. If students are given a set of 10 files, then there are ~80 of these tasks. This task can be expanded to include other directories.

What to Submit: The student will be editing the comments in RTEMS source code and submitting a patch. Git instructions for RTEMS are at, and If there is a need for simpler instructions geared to GCI, a mentor will create them.

Mentor Guidelines: The student will submit a patch which will likely need to be directly emailed to a mentor for review. This is necessary because the rtems-devel mailing list only accepts email from subscribers and students are not expected to subscribe. The mentor will review the patch for correctness. When correct, if the mentor doesn't have git write permission, they should post the patch to rtems-devel. If the mentor does have write permission, they are free to commit it. In either case, we need the student's name and email to give credit in the commit message.

Fix Comment Block at Top of Header Files

This is very similar to the task above (Add Doxygen File Headers) except that you are working with a .h file. It should have a comment block at the top that is like this:

Desired Format':

 * @file
 * @brief Brief Description for Table of Contents
 * Optional paragraph


Many are missing the comment block entirely, others are missing the @brief, etc.

See the Add Doxygen File Headers task for further guidance on patching, format, review, etc.

Cleanup Doxygen

The cleanup tasks consist of changes to make Doxygen use consistent with the Doxygen Recommendations. The submission consists of a patch ("diff"), and the student's name and email address for the commit message.

Students will submit a patch generated by git. You can do this with a git command similar to:

$ git diff > gci-doxygen-taskXYZ.diff

Use sentences for function @brief

Convert function @brief from "Table of Contents" to "Topic sentence" style. The descriptive text of a function's @brief is used to start a paragraph, so it should be a simple, concise sentence describing the function that begins with an active, present tense verb. See Doxygen_Recommendations#Declaring_functions for an example. When the description begins with a noun, rewrite the description so that the action of the function comes first. Eliminate any redundant wording such as "Function that does..." or "This function...".

Use @param to document function parameters

Replace @a with @param. See Doxygen_Recommendations#Declaring_functions for an example. If you cannot determine whether a parameter is "in", "out", or "in,out" then ask for assistance.

Use @retval to document function return values

Replace @return with @retval statements. See Doxygen_Recommendations#Declaring_functions for an example. If you cannot determine the possible return values for a particular function then ask for assistance.

Hierarchy formatting and correctness

There are multiple levels of groupings that RTEMS functions fall into. We want to represent this in Doxygen. To determine the subsystem (higher level grouping) that a group falls into. This task is designed to put the RTEMS Modules into a logical hierarchy.

  1. Add missing @defgroup
  2. Nest subgroups
    1. Find the @defgroup / @addtogroup
    2. Add an @ingroup indicating the "subsystem" for the @defgroup
  3. Put all @{ for @defgroup, @name statements in the same comment block as the defgroup/name statement. See Doxygen_Recommendations#Using_.40defgroup_for_group_definitions for an example.
  4. Ensure all @{ have matching @}. See Doxygen_Recommendations#Ending_the_file for how this should be done at the end of a header file for the primary defgroup. If you cannot determine where to place the terminator for a @defgroup or @name then ask for assistance.
Add missing @defgroup

Identify what @ingroup do not have a @defgroup, and add @defgroup for the missing ones. This task comprises searching for @ingroup labels and matching them with a @defgroup. A little bit of scripting should help, for example:

$> cd rtems/cpukit
$> grep ingroup score/include/rtems/score/thread.h
 *  @ingroup Score
$> grep -R defgroup * | grep "Score"
score/include/rtems/score/object.h: * @defgroup Score SuperCore

Would be a way to find the group definition for the Score group. If you get no results for the defgroup query, then probably the group has not been defined. If you get too many results, you can do additional filtering, for example:

$> grep -R defgroup * | grep "Score "
score/include/rtems/score/object.h: * @defgroup Score SuperCore
  -R means recursively look into every file
  * means every folder
  | means pipe the output through
grep "Score" means filter for "Score"

Use the knowledge there is a space after the group's name for the group's description to filter the results to exactly the defgroup you want to find.

Nest Subgroups
look at the subfolder in cpukit that contains the file.
  • cpukit/rtems -> Classic API
  • cpukit/posix -> POSIX API
  • cpukit/score -> SuperCore
  • cpukit/libfs -> (1) Filesystems (2) filesystem X
  • cpukit/libcsupport -> Subsystem (Higher Level Grouping) = Libc Support, keep the lower level grouping as determined from file.
Using Doxygen Subgroups

Doxygen is used to put groups into subsystems by using @defgroup or @addtogroup. The difference between @defgroup and @addtogroup is that @defgroup forces each call to be unique, while @addtogroup merges multiple groups with the same name together. For expediency and robustness of the Doxygen system for RTEMS, @addtogroup may be preferable.

To use Doxygen subgrouping add the following to the comments Example: Malloc is a subgroup of Libc Support

 * @defgroup Malloc                             malloc.h // the file with the @defgroup
 * @ingroup Libc Support                                 // this is what we want to add
 * @brief Brief In Table of Contents Style*              // *Style depends on where the 
 */                                                      // comment is in the file

Doxygen Grouping Example

Mentor Guidelines: The student will submit a patch that should be reviewed for correctness. When correct, if the mentor doesn't have git write permission, they should post the patch to rtems-devel. If the mentor does have write permission, they are free to commit it. In either case, we need the student's name and email to give credit in the commit message.

Structuring Doxygen in libbsp

The existing doxygen in the libbsp directory has been added in ad hoc and without any real structure. This makes navigating through the resulting documentation very difficult, and virtually impossible if the libbsp doxygen is ever to be compiled with the cpukit doxygen. Tasks in this of this type would work towards refactoring the existing doxygen within the libbsp directory to conform to a structure that more closely resembles the structure and heirarchy of the libbsp directory itself. The end goal is to have a single "Board Support Packages" module, with submodules for each cpu architecture and each specific board support package.

These tasks will involve renaming and reordering old @defgroup declarations, as well as adding in new @defgroup and @ingroup declarations to conform the structure of doxygen to be more like how libbsp is ordered.

Check out the Doxygen Recommendations for BSPs for more specifics on the implementation of the structure outline that follows.

Outline of Structure

The structure of the doxygen in libbsp should match the structure of libbsp itself as closely as possible. Let's start by looking carefully at how libbsp is structured.

The libbsp directory itself is very well ordered. Considered at the root, the first level contains directories of each cpu architecture RTEMS currently supports, along with a folder containing files and headers shared between all architectures.

$ cd c/src/lib/libbsp
$ ls
arm  lm32  m68k             mips   no_cpu         README  sparc
avr   h8300   m32c      moxie  powerpc        sh      sparc64
bfin  i386    m32r  MERGE.PROCEDURE  nios2  shared  v850

If we cd into a specific architecture, we see that a similar structure is employed. libbsp/arm/ contains directories for each Board Support Package for boards with an ARM cpu, along with a folder for files and .h's shared by all BSPs of that architecture.

$ cd arm
$ ls
acinclude.m4  edb7312    gumstix    realview-pbx-a9  stm32f4  gba        lm3s69xx  nds            rtl22xx          xilinx-zynq
csb336        gdbarmsim  lpc24xx  shared
csb337        gp32       lpc32xx   raspberrypi    smdk2410

Finally, if we cd into a specific BSP, we see the files and .h's that compose the package for that particular board.

$ cd raspberrypi
$ ls
bsp_specs  include  make         misc           README
clock      console       irq  startup

The goal is for someone to be able to search through the doxygen is a very similar way. The way to accomplish this would be to have a single libbsp parent module that would contain a submodule for each cpu architechture, which in turn would contain submodules for each BSP. Modules for shared and generic functions would be defined at each level, whenever appropriate. Rememember, our goal is for the structure of doxygen modules and submodules to match the structure of libbsp as closely as possible.

The overarching parent module that all other modules should belong to is bsp_kit, whose @defgroup is found in /shared/include/bootcard.h Consider this to be the "root directory" for libbsp doxygen purposes.

c/src/lib/libbsp/shared/include/bootcard.h: @defgroup bsp_kit Board Support Package

The first thing that should be @ingroup to this bsp_kit module (I will use module and group interchangably) should be submodules for each architechture. This group should have the "@defgroup *bsp_architechture*" placed in one of shared header files that is sufficiently generic. The specific location of this @defgroup does not matter, you can place the @defgroup in a file and not add the file to the group (even though you should add it, unless it belongs in a more specific submodule). For example, the @defgroup for the arm architecture is found in arm/shared/include/start.h


 * @defgroup bsp_arm ARM
 * @ingroup bsp_kit
 * @brief ARM Board Support Packages.

Once all the architectures have their own respective @defgroup defining a module, a final module should defined and added to bsp_kit to house the doxygen for files that are shared by all the architectures. This "Shared" module should be defined in any header in the shared directory, and doxygen for generic implementations should be added to it, or more specific submodules within.

Now we can move on to the next level, and look at the board support packages themselves. The modules for each specific BSP should be contained within the module for their respective architecture. For example, the raspberrypi module should be "@ingroup bsp_arm", because the raspberry pi board is of the arm architecture. This @defgroup can be found within raspberrypi/include/bsp.h


 * @defgroup arm_raspberrypi Raspberry Pi Support
 * @ingroup bsp_arm
 * @brief Raspberry Pi support package

Again, once modules are in place for all BSP's, a module should be defined to house the doxygen documenting the files shared across all BSPs.

Finally, we have reached a group we can really work with, the specific group of the BSP, in this case arm_raspberrypi. You can work with this module the same way you would for using doxygen in general, and can follow the standard doxygen instructions given here and elsewhere. @defgroup new headers in .h files (remembering @ingroup any new headers you define into the BSP group), move protoypes and function comments to the .h and include @briefs, @ingroup relevant .c files, etc etc. These directions can be found in the section Add Doxygen File Headers, and other doxygen reccomendations can be found here

Notes, tips, tricks

  • Most BSP's will contain groups that are similar. This is because each board has to implement some form of interrupt support, memory management, and other features. If you're ever not sure what you should name a group, or whether something should be its own group, or what group a .c should be a part of, just take a look at how another board with finished doxygen handles those files.
  • If you're ever working on adding doxygen for a specific board support package and you find a group of .c files that logically belong together but find no common .h file included in all of them, check to see if there is a shared .h in the cpu architecture module that would provide a good group to include these files in. Often times some or all of these .c files are implementations or hooks of a more generic prototype found in one of the cpu headers. A good example of this is the start up code in the raspberrypi bsp having a "@ingroup arm_start" tag, which is defined in arm/shared/include/start.h.
  • Look at how groups are named. If you haven't put this together already, group names should always have the form *parent-group*_*submodule*. Some examples of this would be "bsp_arm", "arm_start", and "arm_raspberrypi". The only exception to this rule is the all inclusive bsp-kit. This convention makes it a lot easier to tell what module the group belongs to, and gives a good idea of the structure without actually having to generate the documentation. In the case of arm_start, you aren't just working on any old start module, your working on the start submodule of arm.

Add a POSIX Timing Test

Invoking rtems-testing/rtems-test-template/mktest

To create a test, you'll need to be in the rtems/testsuite/your_pattern directory. This task consists of adding a benchmark test to the RTEMS POSIX Timing Test Suite. There are templates for each benchmark pattern we have identified. The task consists of identifying the correct pattern, instantiating it using the "mktest" script, and then filling that in with the appropriate calls. For example:


You'll need to specify the source (-s), the destination (-d), and the test number (-n). Change the location to match where you put rtems-testing. For example:

~/rtems/testsuites/psxtmtests> ~/rtems-testing/rtems-test-template/mktest \
-s ~/rtems-testing/rtems-test-template/psxtmtest_unblocking_preempt \
-d psxtmcond04 \
-n 4

Adding the Test to the Build System

To add a test to the build system, you'll need to add it to and Then you'll need to ./bootstrap it.

Changes to

 SUBDIRS += psxtmthread01
 SUBDIRS += psxtmthread03
 SUBDIRS += psxtmcond04 # Add a SUBDIRS entry to the bottom

Changes to


Now bootstrap it

cd ~/rtems
~/rtems> ./bootstrap

Now build...

cd ../b-sis
../rtems/configure --options --used --to --configure

Finding an Example

Now that the test has been added to the build system, find working examples of the functions to call. One way to do that is to use grep -r. From the terminal, there may be characters that have to be "escaped" \. For example to create a test of pthread_cond_init() put the following in the command line:

grep -r pthread\_cond\_init ~/rtems/testsuites/


Finally use a simulator/emulator See

Lather, Rinse, Repeat

Add all the #includes, at the top, compare the macros at the bottom, cut-and-paste from working example of the source code into the generated test, see what happens.

After each change, clean the build directory, rebuild the source, and try again, depending on the simulator something like:

~/b-sis make clean
~/b-sis ../rtems/configure --options --to --configure
~/b-sis make
~/b-sis sparc-rtems4.11-gdb `find . -name ticker.exe`

This is a particularly challenging task, so asking questions, and making suggestions for improving the directions on this task would be greatly appreciated.

Posix Time Test Plan (for generating more GCI tasks)

This task can be instantiated for multiple areas in POSIX but the following is a typical set for communications and synchronization objects. A GSOC 2011 project implemented many tests for semaphores, message queues, etc., but there are still many left to implement. The following is a link to the Comma Separated Value (e.g., .csv) file which is exported from the spreadsheet used to track the status of this effort.

There are likely 50-100 instances of this task possible.

Mentor Guidelines: This should be evaluated as a normal code submission. You need to review and run the test to ensure it is correct. It should be based upon the templates in rtems-testing. The student should provide a name and email for proper attribution. If you have write permission, commit it. Otherwise, send it to rtems-devel for another developer to commit with commentary indicating it is acceptable and from GCI.

sp09 Refactoring

The sptest sp09 was written in the days when download time dominated testing and there were no CPU simulators. The test is too large for some target boards and tests errors from multiple managers. The goal of these tasks is to take a set of related API error cases and split them into a new sptest.

sp09 is divided into screens which actually corresponded to 80x24 output on a VT-100. The task description will tell you which screen(s) to focus on. Move that testing to a new test (the name will be given). Then reduce the configuration parameters (CONFIGURE_XXX) in sp09. Ensure the new test is properly formed with a doc file, etc. and the doc file in sp09 is updated. Both sp09 and your new test should run.

The basic steps for students and mentors should be similar to that of adding a POSIX Timing Test. Deliverables are the same

Refactoring Board Support Packages

Please read all instructions before proceeding.


The following task requires refactoring some pieces of code present in the Board Support Packages. During GSOC, a set of rules were devised that identified standard patterns of code implementation and file inclusion across all BSPs. Some of the example tasks in this category are to move a function definition from its current source file location to another file, or moving a file to another location within the BSP subdirectory.

Modifying BSP : 101

A BSP is a set of code files that provides the glue between RTEMS and a device mother-board. All the BSP code is concentrated in the directory c/src/lib/libbsp which is further subdivided based on CPU family and BSP.

For Example, c/src/lib/libbsp/arm directory contains the BSPs for the 'arm' family, and c/src/lib/libbsp/arm/gumstix refers to the 'gumstix' BSP.

The set of rules pertaining to the standardization of file location and function definitions each file must contain can be found here.

After making changes to any of the files, you'll need to make sure to compile it so that no errors are left. The quick start guide can help you in learning how to compile a BSP for the first time.

RTEMS uses the GNU Autotools for its build system. The, part of Automake, present in each BSP directory contains the list of source files which have to be compiled. The 'libbsp_a_SOURCES' container consists of space seperated values of the path to source files which will be compiled. So in case a new file is created in the BSP, the entry for that newly created file needs to be added to 'libbsp_a_SOURCES'.

First things first

The first thing to do is to have a working build of the BSP. Ideally, you will already have followed the GSOC Getting Started Guide from completing the previous GCI task. Now you'll need to repeat the effort for the CPU and BSP of the task that you are undertaking, which may require installing a new RTEMS Toolset so that you can cross-compile the BSP. Once you verify that the BSP builds "cleanly", you can start your task. (For these tasks we do not require proof of execution, only of correct compilation.)

In the following points we'll take a look at the kind of tasks that this category can contain.

Move a function to a new file

cpu_family/bsp : Move bsp_reset() in startup/bspstart.c to  bsp/startup/bspreset.c
  • Create a branch on git for your work. This will make managing your patch easier.
git checkout master
git pull
git checkout -b bspreset
  • Ensure your checkout compiles without errors by running 'make' in your build directory.
  • If the target file does not exist, create it.
    • Add the name of the new file to
    • Re-run bootstrap -p and bootstrap from the libbsp directory, e.g.
cd c/src/lib/libbsp
../../../../bootstrap -p
  • Move the function definition from the current file to the target file.
  • Include the same headers as in the previous file.
  • Compile and check for any errors.
    • You can re-compile RTEMS without re-running configure, just run 'make' as you did when compiling RTEMS the first time for this BSP.
  • Generate a patch for evaluation
    • Add the modified files to git and create a commit.
    • Create a patch as the following shows, where you replace bsp with the name of the bsp.
cd c/src/lib/libbsp
git add cpu/bsp/startup/bspreset.c
git commit -a -m "bsp: Move bsp_reset() to bsp/startup/bspreset.c"
# verify the commit message and contents look right, and that your name and email address appear
git format-patch HEAD^ -o ../../../../../
  • Upload the patch to Melange for your submission.

Move a file within a bsp

Some of the details are given in the above section on moving a function to a new file. See those instructions for clarification of the following steps if needed.

cpu_family/bsp : irq.c should be moved to irq/irq.c
  • Move the given file from it's current location to the target location.
  • Update the path entry of this file in
  • Re-run bootstrap -p and bootstrap from the libbsp directory, as above.
  • Compile and check for any errors.
  • Submit the patch for evaluation.


Tasks related to creating/editing documents and helping others learn more

Classic API Requirements Document

We expect approximately 30 tasks in this category for the first round. There can be followup tasks sets to further refine them.

This task is part of the RTEMS project's effort to reduce certification costs by easing requirements traceability. As we want our developers to spend more time on adding technical value (instead of updating duplicate documentation), we will want to merge as much of this documentation as possible.

We have several existing classic API documents and converting each into chapter into reStructuredText will provide a baseline which is easier for further automated processing and updates. The focus will be on the final versions of the RTEID and ORKID specifications.

Classic API Requirements Document (Phase I Deliverables)

The deliverable is a .rst

Classic API Requirements Document (Phase I Method)

  1. Copy the contents of the file into an RST editor
  2. Format the .rst to match the example and the original pdf
  3. Limit line length to 80 characters
  4. If the numbering is
    1. like 3, chapter-level, use === to underline,
    2. like 3.5, section-level, use --- to underline
    3. like 3.5.7, subsection-level, use C Rempel (talk) to underline
  5. Separate paragraphs with a blank line
  6. Use tables to format the Completion Status
  7. use linux-style line endings
  8. Look for spelling errors
  9. use ```` on items that are supposed to be code
  10. Upload to melange, ask the mentor to review the .rst

Classic API Requirements Document (Phase I Example)

.. contents:: Table of Contents
.. section-numbering::


Nodes are the building bricks of ORKID systems, referenced by a node identifier
and containing a single set of ORKID data structures. Nodes will typically
contain a single CPU, but multi-CPU nodes are equally possible.

Specifying how nodes are created and configured is outside the scope of this
standard. However, certain basic operations for node handling will be needed in
all ORKID implementations and are defined in the following sections.

Obtain the identifier of a node with a given name.


``node_ident( name, nid )``

**Input Parameters**

``name: string``
   user defined node name

**Output Parameters**

``nid: node_id``
   system defined node identifier

**Literal Values**

``name = WHO_AM_I``
   returns nid of calling task

**Completion Status**

===================== ========================================
``OK``                 ``node_ident`` successful
``ILLEGAL_USE``        ``node_ident`` not callable from ISR
``INVALID_PARAMETER``  a parameter refers to an invalid address
``NAME_NOT_FOUND``     no node with this name
===================== ========================================


This operation returns the node identifier for the node with the given name. 
No assumption is made on how this identifier is obtained. If there is more 
than one mode with the same name in the system, then the ``nid`` of the first
one found is returned.

Note to Mentors

  1. Verify the .rst renders in the RST editor
  2. Verify the format matches the example
  3. Look for optical character recognition type spelling errors

Classic API Manual Examples

Our manual is pretty good but we do not have easy to read and understand example implementations of the typical usage patterns as presented in textbooks. This task consists of taking an existing example from another source and modifying it to use the RTEMS Classic API or POSIX API. The code must be presentable enough where it could be included in a user manual.

One search that yields a fair number of classic API examples is:

site: "rtems.h" filetype:c

The deliverable is a .diff of the classic api manual containing the example.

This task can be instantiated at least 20 times.

Create a Basic Program (or Modify an Existing Open Source Project) to Help with Doxygen (or other .diff type) Tasks

This task would involve creating a program to help other students finish Doxygen tasks. The program would be used by many different operating systems so using a cross-platform technology is key. Ideally, a cross-platform API, such as Python, could be used to ensure strong cross-platform support.

The goal is to make, or modify, a program that allows editing of RTEMS source code (such as, RTEMS Doxygen comments and headers on the fly). The ultimate goal is to be able to complete a Doxygen task within a minute or even a couple seconds with this program.

  • The user has the option of loading a file with a list of files to modify, similar to the “Doxygen Tasks” file such as this and the program will display all the filenames on a sidebar located on the left.
  • Once clicked on an element in the sidebar, the file contents of the clicked file will appear in the middle. We have the ability to modify this text and if we change an element or exit the application, the program will save the modified contents.

Mentor Guidelines: The student will submit the source code to their program which will be reviewed by a mentor. The mentor should keep user interface and quality of code in mind while reviewing code.

After this task is completed, more tasks which add more features to this program can be created such as:

  • An option to locate the corresponding .h or .c file and open it as a tab on the current interface.
  • An autofill feature.
  • “@return” to “@retval” replacer.
  • Correct @brief detection, to check whether the @briefs are in the proper format such as sentence or title.
  • Feature to generate a .diff patch.

POSIX Compliance Spreadsheet

If you are a spreadsheet wizard, this is a task for you. RTEMS has a Google Docs spreadsheet to track compliance with the Open Group's Single UNIX Specification. This spreadsheet has most of the raw compliance information already entered but is missing the formulas that would check which features RTEMS has and see how compliant we are with the four POSIX profiles. A profile is simply a subset of the calls defined in the full standard.

Finish a POSIX API Chapter

RTEMS has permission to use information from the Open Group's Single UNIX Specification in our RTEMS POSIX API User's Guide. Each of the chapters in this manual is incomplete to a greater or lesser extent. The document is written in texinfo. This task consists of completing a chapter.

This task can be instantiated for the following chapters:

  • Process Creation and Execution Manager
  • Process Environment Manager
  • Files and Directories Manager
  • Input and Output Primitives Manager
  • Device- and Class- Specific Functions Manager
  • Language-Specific Services for the C Programming Language Manager
  • System Databases Manager
  • Semaphore Manager
  • Mutex Manager
  • Condition Variable Manager
  • Memory Management Manager
  • Scheduler Manager
  • Clock Manager
  • Timer Manager
  • Key Manager
  • Thread Cancellation Manager


The .diff for the .texi

To generate a .diff

~$ cd rtems
~/rtems$ git diff > gci-texi-task2.diff

One way to locate the texi file to edit

1. Look at the chapter in the RTEMS POSIX API User's Guide, and identify a function in the chapter. 2. Get the source

~$ git clone git://

3. Look for the function in the users guide

~$ grep -r posix\_function doc/posix_users .

The chapter should be one of those files.

BSP Wiki Pages Info Boxes

RTEMS uses a Mediawiki installation for its wiki. Each embedded board supported by RTEMS is supposed to have its own wiki page. There is an Infobox on the upper right hand side of each BSP wiki page. Some BSPs do not have BSPs and even those that do have pages created do not always have a completed Infobox. This is because we learned how to implement the Infoboxes after the pages were added, most of them are just stubs. The Infobox template is here and is the complete view of the fields available. A reasonably good example of a filled in Infobox is the Blackfin BF537 Stamp BSP page.

This task consists of finding the vendor specification on a particular board (which should be publicly available) and filling in the Infobox. The master list of Board Support Package pages is on the Board Support Package Information page. There are approximately 100 pages in this group.

To request an account scroll up to the top of the page and click on the Sign In / Request Account and fill out the form.

To find the architecture go to: , find the board, then find the architecture to the left of the board. If the board is not in README.configure, you may note Architecture: Unknown. To find the RTEMS Alias, look to the left of the -- on this page. For example: the alias of the Cogent CSB336 is csb336.

This task can be instantiated for each of the BSP wiki pages. Tasks are possible for the BSPs below (some were completed in the past and are listed following):

Completed Wiki Infobox Pages

Special thanks to the students and mentors that make quality information readily available to the embedded systems developers.

Check the list left against was done in GCI 2011 before publishing a task.


Tasks related to community management and outreach/marketing

Tasks related to studying a problem and recommending solutions

Update List of Citations

Task Description

This task consists of updating the list of published references to RTEMS.

Directions for Students

You will need an account on the RTEMS Wiki.

You should use the search link provided in the task description on Melange. For completeness, the search was constructed as follows: Use Google Scholar to search for "RTEMS". Deselect "Include Citations" and make sure that "Include Patents" also is not selected, and choose "Custom Search" entering the start and end year as the one given in your task. Click "Search English pages" and make sure your results show 10 per page, and go to the page that your task specifies.

For each English language search result that appears to be relevant to the RTEMS Operating System on that page, click "Cite" and copy the "Chicago" style citation. Paste it into the list on RTEMSReferences under the correct year for the publication if the citation has not already been added. If the citation exists, double-check that it is correct. If a PDF result is listed to the right of the citation in Google Scholar, add a link to the PDF after the citation on the RTEMS Wiki page. Make sure the links are correct. Make a text file that contains a copy of all the entries you added to the wiki page. After you have finished with all 10 results on the search page, upload the text file and submit the task for review. Note: You may find it easiest to copy the citations and links into the text file, and then copy from your text file into the wiki page when you finish processing the search results.

Directions for Mentors

Use the search link provided in the task description on Melange. Ensure the relevant RTEMS search results on the page number given in the task have been added to the list of RTEMSReferences, check that the uploaded text file matches the results, and check that any links to PDF files work.

As with all Wiki tasks, reviewing the recent change history on the page can be very helpful. Ensure that no other citations were altered.

Presentation to peers on RTEMS

This task consists of creating a presentation in either PowerPoint of OpenOffice Impress on RTEMS which is targeted at persons who would be of the appropriate age for Google Code-In (13-18). The presentation should include speaker notes and be about 20 minutes in length.

New Logos for RTEMS

This task consists of creating a designing a new logo for RTEMS. We would like the result to be modifiable in in an open source tool and either a vector graphic or a high resolution bitmapped image. If the RTEMS developers like it, we can follow this up with another task to produce the graphics in various sizes and with transparency layers. We will want to be able to use it on web sites, print, t-shirts, stickers, etc.

Design an RTEMS T-Shirt

This task consists of creating a designing a t-shirt design for RTEMS. We would like the result to be modifiable in in an open source tool and either a vector graphic or a high resolution bitmapped image. If the RTEMS developers like it, we can follow this up with another task to produce the graphics in various sizes and with transparency layers. We will want to be able to use it on web sites, print, t-shirts, etc.

Getting Started for your Peers

As a project, we try to make RTEMS approachable for new comers. Help us by making our existing getting started howto's even easier. There is a Getting Started manual (HTML) and a number of wiki pages. But they are written by people who are familiar with RTEMS and how to install it. Review one of the Getting Started documents and give us guidance.

Info for flyers for various projects using RTEMS

The RTEMS Project has a number of flyers on various projects which have used RTEMS. Each of these flyers is based upon a Wiki page about that project with the same text and pictures. This task consists of preparing a wiki page on a an RTEMS application which consists of approximately one page of text, 2 or more nice pictures or figures about the project, and a few URLs of reference for more details. The information on the flyers is presented in a very uniform manner.

Some hints:

  • When you take one of these tasks, you may be given an email address of a contact for that project to obtain information from.
  • When you search for a project, search for the project by itself. Then search again and include RTEMS in the search terms. For example, "Mitre Centaur robot" and "Mitre Centaur robot RTEMS" should turn up different results. The first gives general information about the project and should include some cool pictures. The second should turn up more specific information on how RTEMS was used on the project.
  • If you can figure out the exact role of RTEMS in the project, include it. Information on the target hardware RTEMS was run on is always interesting.
  • For space applications, you will usually find a NASA/ESA/JPL page with nice figures, possibly some RTEMS mailing list postings, and some published papers. All are suitable references.
  • Pictures and figures should be properly credited as to the source.

This task can be instantiated for at least the following projects:

  • Stanford Linear Accelerator Center (SLAC)
  • Canadian Light Source
  • Brookhaven National Laboratories
  • Mitre Centaur Robot
  • NASA Express Logistics Carrier (ELC)
  • BMW Superbike

There should be more applications we can identify if this is a popular task.

Identify a Timeline Visualization Tool

RTEMS systems have the option to capture timestamped data about what is happening in the system. But reading long files with timestamped messages is not a good way to get insight into the run-time behavior of a system. Find us a free, open source timeline visualization tool which can be taught to read the RTEMS captured information.

Ideal solution would be one which dynamically updates as input arrives and is flexible on input sources (e.g. files, sockets, etc).

This could be multiple tasks if there are multiple visualization tools.

Find RTEMS References

This task consists of finding published references to RTEMS and placing them on RTEMSReferences. Students can use Google Scholar to assist them with their research. This task should have the student to find at least 15 new references.

Create an RTEMS Promo Video

This task consists of creating an interesting and cool 'What is RTEMS?' type video. The video should be at least 1 minute and 10 seconds long and should contain a lot of action/fun and applications of RTEMS (along with music where appropriate). The video will help potential developers and potential students kindle an interest in the RTEMS project.

(Remember to use Media in compliance with its license)

Note: Windows Movie Maker type videos aren't ideal for this task.

Quality Assurance

Tasks related to testing and ensuring code is of high quality.

Write a Test Description

The RTEMS project needs to reduce certification costs for our end-users. One of our end-users' biggest expense is verifying that the required functions/features are fully tested. To reduce certification costs, the RTEMS project has chosen to add documentation which aids in verifying that all functions/features of the software has been fully tested.

Test Description Deliverables

A .rst Test Description in the required format.

Test Description Requirements

The format of the test-descriptions is designed to be simple enough to be maintainable, while also meeting certification requirements. The language the descriptions is: reStructuredText (reST)

There are several parts to a test description:

  1. Copyright (Copyright your name, 2013 or 2014)
  2. License (License:
  3. Test Name (this is the name of the directory the test is in)
  4. Test Purpose (broad purpose(s) statement)
  5. Methods/Directives Tested (primary intent)
  6. Specific Test Cases normal functionality, or error handling? If error handling, which errors are being handled?

How to Write a Test Description

Below is a suggested sequence of steps that, if followed, will guide the student through completing the task successfully.

  1. follow the link provided in melange to find the folder containing the test to describe.
  2. look through the code in the folder
    1. open the .c file(s)
    2. ctrl+f printf -- see what would be printed
  3. fill in the test description using a Restructured Text Editor
  4. copy, and save the text every 5-10 minutes or so into a file with the name of the folder with a .rst extension
  5. submit the .rst to melange, ask for the mentor to evaluate the test description

Example Test Description (tmck.rst)

Copyright |copy| 2013, Your Name

.. |copy| unicode:: 0xA9
.. The license and distribution terms for this file may be
.. found in the file LICENSE in this distribution or at

Test Name: tmck
Checks the timer before running additional tests.

Requirement Number: TBD

Requirement Description: TBD

Environment Scenario:
- The environment scenario can be found in rtems/testsuites/tmtests/tmck/system.h

Test Description:
Pseudo-code for tmck
.. look at rtems_task Init
- disable subtracting the overhead
- create a task
- start Task_1
- delete Task_1

.. look for printed error statements (usually CAPS with !!)
Test fails if it takes too long, or the time is in microseconds, otherwise it succeeds.

Expected Results:
The time taken, and END OF TIME CHECKER is displayed

Assumptions, Constraints and Comments:
Normal functionality

Mentor Guidelines

The issues the users are having at this point are more a matter of existence than quality, so use a check the box approach to grading.

  1. Are all the items in the requirements listed?
  2. Does the test description render properly in a rst editor ?
  3. Does the description (however vaguely) describe the test?

Generating .scn (Screen Shots)

There are many tests RTEMS has that have no documentation at all. Not only does generating test documentation helps show that RTEMS meets safety critical certification standards, which in turn makes RTEMS more usable in satellites, airplanes, automobiles, etc, performing this task was the starting point for RTEMS's Google Summer of Code students last summer. By performing this task, you will have cross-compiled and cross-debugged an application, which is a starting point for futher work in the area of embedded systems development.

  • The first step is to get a cross-development platform: two options are the Quick_Start guide and the Virtual_Machines_for_RTEMS_Development. The Sparc Instruction Simulator (SIS) seems to be popular for beginning RTEMS development, so should be well supported. Please Note: the directions for the VM are for sample tests, please follow the steps below to generate ALL the tests.
  • The second step is to configure and build RTEMS to develop ALL the tests.

Clean out the old build system

rm -rf rtems-4.11-work/b-sis/*

Navigate to the build directory

cd rtems-4.11-work/b-sis

Tell Bash where to find the compiler

export PATH=$PATH:/opt/rtems-4.11/bin

Now that Bash can find the compiler, configure the source, for the SPARC architecture, Board Support Package (BSP) is Sparc Instruction Simulator (SIS), and enable all the tests

../rtems/configure --target=sparc-rtems4.11 --enable-rtemsbsp=sis --enable-tests

Build the tests

gmake all

Wait 30+ minutes... :)

  • The third step is to run the Gnu cross-DeBugger (GDB) to get the screen-shot, note: replace ticker with the name of the executable you are documenting.

1.a. Find the executable

bash-4.1$ find . -name test1.exe

2.a. Debug the executable

bash-4.1$ sparc-rtems4.11-gdb ./path/to/test1.exe
(gdb) tar sim
Connected to the simulator.
(gdb) load
(gdb) r

3.a Copy and paste the text into NameOfTest1.scn and upload the file

1.b Find the executable

bash-4.1$ find . -name test2.exe

2.b Debug the executable

bash-4.1$ sparc-rtems4.11-gdb ./path/to/test2.exe
(gdb) tar sim
Connected to the simulator.
(gdb) load
(gdb) r

3.b Copy the text produced and paste it into a NameOfTest2.scn and upload the file Repeat third step until done getting screen-shots.

  • The fourth step is to submit your name, email (for credit), and 5 .scn s.
  • The fifth step is to add any problems with the tests in

At the completion of this task, you will have successfully cross-compiled, cross-debugged, and contributed to an open source project.

Mentor Instructions

Treat this submission as any other .diff submission.

Write a Test Document File

This task consists of reading a .scn and writing a .doc in the correct format.


a .doc in the correct format... An example can be found below


  1. copy the example
  2. replace testsuites/fstests/fserror/fserror.doc to what's appropriate for the test
  3. replace On-Line Applications Research Corporation (OAR). with your name
  4. replace the test set name with the name of the test
  5. fill in the directives
    1. open the .scn indicated in the task
    2. find the functions tested
  6. fill in the concepts
    1. open the .scn indicated in the task
    2. write a sentence describing what was tested in the .scn
  7. submit the .doc, ensure the name matches the test

Each task will do this for a single test program.

Test Documentation Files update

This task consists of reading an existing test and its associated Test Description File (TDF) and verifying that the TDF accurately represents the contents of the test and is in the correct format.

Each task will do this for a single test program. There are approximately 280 TDFs in RTEMS so this task can be instantiated a significant number of times.

Location of Test Documentation Files

These files are located in the testsuites folder click in the folder and there should be a .doc which is the test document and a .scn which is the screen that should appear when the test is ran.

Format for Test Documentation Files

The correct format for the test documentation files is:

  1. If there is a copyright notice, please leave it intact
  2. Please use claim your work by adding your name and/or email
  3. "This file describes the directives and concepts tested by this test set."
  4. Test set name: name of the folder
  5. Directives: all the directives called in the test.c
  6. Concepts: describe what the test is doing -- it may help to look at the .scn which are the desired return values

Example of a Five Directive Test

#  testsuites/fstests/fserror/fserror.doc
#  COPYRIGHT (c) 1989-2009.
#  On-Line Applications Research Corporation (OAR). 
#  Copyright (c) 2013 First Last <>.
#  The license and distribution terms for this file may be
#  found in the file LICENSE in this distribution or at
This file describes the directives and concepts tested by this test set.

test set name: fserror

+ open 
+ write
+ read
+ mkdir
+ unlink
+ rmdir


+ Exercise the tests to make them fail and check the errno

B. Convert an rtems-testing/covoar/mkExplanation function to python (and test it)

Note: this depends on the Refactor mkExplanation task.

This task can be done for: toggle() usage() getopts() getopts_errorcheck()

1. Check out rtems-testing

git clone git://

2. Rewrite the function into a Python module, and put it in a file in the rtems-testing/covoar folder with the function name. For example: toggle() would go into a file called rtems-testing/covoar/

Note: some functions MAY take arguments. For example: getopts_errorcheck() MAY be re-written to take a string representing the option, a boolean, and an error message.

3. Write a test-class to demonstrate it works, and put it in a file under the rtems-testing/tests subfolder with the function_name-test. For example: toggle() would have a test class in a file called rtems-testing/tests/

4. Submit a patch against rtems-testing

C. Rewrite rtems-testing/covoar/mkExplanation in python

Note: this depends on the Convert an rtems-testing/covoar/mkExplanation function to python task, and that it's been completed for each function

1. Check out rtems-testing

git clone git://

2. Using covoar/ covoar/ covoar/ covoar/ modules, re-write mkExplanation python and put into a file called

3. Submit a patch against rtems-testing -->

User Interface

Tasks related to user experience research or user interface design and interaction.

Integrated Development Environment Research

This task is about researching how to make quality RTEMS plugins for eclipse. The deliverable for this task is a half- to one-page report containing annotated links to

  1. source-code repositories
  2. wiki pages, and
  3. emails of maintainers
  4. initial impression trying to use the software (your experience, no link)
  5. problems encountered
  6. how does this help an RTEMS developer (may or may not use a link)

that help the RTEMS project achieve the stated goal. This task can be instantiated once for each item on the list.

  1. Use the Linux Trace Toolkit eclipse plugin to visualize data.
  2. Use eclipse to cross-compile an application
  3. Use eclipse to automatically generate doxygen comments
  4. Use eclipse as an oscilloscope
  5. Use eclipse to launch qemu
  6. Use eclipse to launch SkyEye

Note to Mentor: Look for items on the list. Follow the links, see where they go.

Test Coverage Report Improvements

The RTEMS developers are not web experts and we are sure there are ways in which the information presented in the test coverage reports can be improved. Your task is to identify how we can improve the presentation. Possible areas are using some JavaScript to make the reported data more dynamically accessible, reformatting to improve readability, etc. This task consists of modifying the existing Bourne shell script that generates the primary table of results per target. An example of this can be found in the RTEMS CVS Head Coverage Results for erc32.

The scripts are in the rtems-testing git module. You will need to be familiar with git and Bourne Shell programming. Ask for sample data to use when working on this task. You will not need to run our test suite -- just generate reports based on their output.

This is a single task with no instantiation option but it consists of multiple phases. If a student completes the first phase, we will add tasks for the next step in the process.

The steps are as follows:

  • Break out the current one page per target with a section per test configuration with a table into separate pages. The top level table will consist only of links to a set of pages per test configuration. The new pages will consist of the table. The plotted data of multiple test configurations should be removed. Instead each "per test configuration" page should include a plot of the data ONLY for that configuration.
  • Adjust scripts to stop using "d" or "D" to indicate Core or Developmental configuration. Generated files should be in tarballs and directories with names like BSP-O[s2][pP]-[CONFIGURATION]-DATE-TIME where configuration is either "core" or "full". Full is the new name for Developmental. Script will need to support old and new names as equivalent and reported on single page.
  • Rename all current tarballs using "d" or "D" to indicate Core or Full configuration. Adjust script to remove support for old naming.
  • Add more configurations. The goal is to generate a test report for each source directory that is in "Full" test configuration.

Adapt Linux Trace Toolkit (LTT) Visualization Tool

Investigate the use of the LTT Visualization Tool and its input file format(s). The goal is to use it to display traces from the RTEMS Capture Engine. Your goal is to get it to display an arbitrary timeline.

This will provide us with the definition of the input files so the RTEMS Capture Engine's output can be visualized using the LTT Visualization Tool.

The timeline you use as a test case could be from sports or a famous event like the John F. Kennedy Assassination. Whatever you use as a test case, please ensure it has events of various types and demonstrates what is possible with the tools.

Mentor Guidelines: The goal of this task is to see if the LTT visualization support is a good general tool for RTEMS trace logs to be fed into (after some scripted massaging) for visualization. Finding a roadblock or limitation is acceptable. But if the tool is powerful enough, then demonstrating what can be done with it is important. If there remain questions to be investigated after this task is complete, create another task geared for that.

Adapt an Eclipse Plug-In Module For Use In RTEMS Development

RTEMS is not a GUI application. Most RTEMS users only see a GUI when they are doing development. The most frequently used GUI development environment used by RTEMS developers is Eclipse. Take one of the Eclipse plugin modules identified as a research focused project and adapt it for use by the RTEMS community.

The student may adapt a plugin, or propose one for adaptation.

Phase I: Identify an Eclipse Plug-In Module For Use In RTEMS Development

Find an eclipse plugin module that would be of interest to the RTEMS community, and might be worth adapting. Write a brief description of the plugin, to give another student an idea for a plugin to adapt.

Phase I: Deliverable

The deliverables is an entry below this task on this wiki page consisting of the following:

  1. a link to the source code of a plugin module that might be adapted
  2. one sentence describing what the plugin is for
  3. why it might be useful
  4. one sentence describing how many hours the student thinks it would take to adapt the plugin

Phase I: Suggested Method

  1. Request an RTEMS wiki account by scrolling to the top of the page, and trying to sign-in
  2. Either look at for an interesting plugin or use a search engine, such as Google, to find an interesting plugin
  3. using a text editor, write-down the fields based on the search results (to find the source code, it may be useful to search for your plugin's name and the words source code
  4. login to this wiki page, scroll to the bottom, and make an entry using the wiki format

Mentor Guidelines: Verify the student has written an entry at the bottom of this page with the above fields.

Mentor Guideline: Ensure this works.

Personal tools

Gedare's Special Help