GoogleCodeInProjects

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

Contents






Code

Tasks related to writing or refactoring code

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.

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.

Directions

  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 

                                                        cpukit/example.c
/* @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.

Notes
  • 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 http://www.doxygen.org 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
 */

/*
 * COPYRIGHT
 * 
 * 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 Headers in a File

Desired Format (in the middle of the file): 

    ...                                              cpukit/example/example.c
    rtems_random_call();
    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
Notes

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
  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

There is a shell script do_doxygen in the same ftp directory as the list of files to edit http://rtems.org/ftp/pub/rtems/people/joel/Doxygen_Tasks/. 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 http://wiki.rtems.org/wiki/index.php/RTEMS_GIT_Repository#GIT_Access_for_users, and http://wiki.rtems.org/wiki/index.php/Git_Users. 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
 */

/*
 *  COPYRIGHT...
 */

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

grep
  -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.

Break Long Lines

Lines longer than 80 characters should be split into multiple lines.

Desired format if, while, and for loops have their condition expressions aligned and broken on separate lines. When the conditions have to be broken, none go on the first line with the if, while, or for statement, and none go on the last line with the closing parenthesis and (optional) curly brace. Long statements are broken up and indented at operators, with an operator always being the last token on a line. No blank spaces should be left at the end of any line. Here is an example with a for loop. 

for ( initialization = statement; a + really + long + statement + that + evaluates + to < a + boolean; another + statement++ ) {
  z = a + really + long + statement + that + needs + two + lines + gets + indented + four + more + spaces + on + the + second + and + subsequent + lines + and + broken + up + at + operators;
}

Should be replaced with 

for (
  initialization = statement;
  a + really + long + statement + that + evaluates + to <
  a + boolean;
  another + statement++
) {
  z = a + really + long + statement + that + needs +
      two + lines + gets + indented + four + more +
      spaces + on + the + second + and + subsequent +
      lines + and + broken + up + at + operators;
}

Note that indentations should use space characters, not tabs.

Similarly, 

if ( this + that < those && this + these < that && this + those < these && this < those && those < that ) {

should be broken up like 

if (
  this + that < those &&
  this + these < that &&
  this + those < these &&
  this < those &&
  those < that
) {

Note that each expression that resolves to a boolean goes on its own line.

When a line is long because of a comment at the end, move the comment to just before the line, for example 

#define A_LONG_MACRO_NAME (AND + EXPANSION) /* Plus + a + really + long + comment */

can be replaced with 

/* Plus + a + really + long + comment */
#define A_LONG_MACRO_NAME (AND + EXPANSION)

C Preprocessor macros need to be broken up with some care, because the preprocessor does not understand that it should eat newline characters. So 

#define A_LONG_MACRO_NAME (AND + EXCESSIVELY + LONG + EXPANSION + WITH + LOTS + OF + EXTRA + STUFF + DEFINED)

would become 

#define A_LONG_MACRO_NAME ( \
  AND + EXCESSIVELY + LONG + EXPANSION + WITH + LOTS + OF + EXTRA + STUFF + \
  DEFINED \
)

Notice that each line is terminated by a backslash then the carriage return. The backslash tells the preprocessor to eat the newline.

Function declarations can be broken up at each argument, for example 

int this_is_a_function( int arg1, int arg2, int arg3, int arg4, int arg5, int arg6, int arg7, int arg8, int arg9 );

would be broken up as 

int this_is_a_function(
  int arg1,
  int arg2,
  int arg3,
  int arg4,
  int arg5,
  int arg6,
  int arg7,
  int arg8,
  int arg9
);

Excessively long comments should be broken up at a word boundary or somewhere that makes sense, for example 

/* Excessively long comments should be broken up at a word boundary or somewhere that makes sense, for example */

would be 

/* Excessively long comments should be broken up at a word boundary or
 * somewhere that makes sense, for example */

Note that multiline comments have a single asterisk aligned with the asterisk in the opening /*. The closing */ should go at the end of the last line.

For any questions about how to break up a peculiar long line, please ask.

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, the mentor should post the patch to rtems-devel. If the mentor does have write permission, they are free to commit it with care. In either case, we need the student's name and email to give credit in the commit message.

Merged RSS Feed

RTEMS is used by multiple applications that have their own RSS feeds. We would like to provide a single RSS feed for the set of applications using RTEMS.

Identify a tool that merges RSS feeds and use that to merge a few RSS feeds for us. We will want to make this available via our website.

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.

TBD: RTEMS folks look in other places for specific examples. For example, write bounded buffer in terms of RTEMS Classic API or POSIX services.

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.

Documentation

Tasks related to creating/editing documents

Finalize Requirements Document

These tasks will take the output from the Merge and Cleanup tasks (below) and create a single document that re-captures the original standards document.

Students will download the merged document and modify it to improve its use of document processing features. In particular,

  • Convert chapter and appendix names to Word Chapters with automatic numbering that matches the original.
  • Convert section headers/numbers to Word Section Headers with automatic numbering that matches the original.
  • Convert tables (if tables exist) to Word Tables. Add captions (if captions exist).
  • Generate a Table of Contents.
  • Generate a List of Tables (if tables exist).
  • Add page numbers.

We have four documents to finalize, each of which is a separate task.

Mentor Guidelines: The student will submit a .docx file. The mentor will review this document for correctness, paying attention to formatting, correct pagination, proper content, page numbers, and correctly generated table of contents and list of tables (if tables exist).

Merge and Cleanup Requirements Document

These tasks will take the output from the Convert PDF to Text tasks (below) and create a single document that re-captures the original standards document.

Students will download the separate documents and merge them all into a single (.docx) document and do some formatting and cleanup. In particular,

  • Ensure that all page breaks are done with manually inserted page breaks, and NOT with blank lines.
  • Check that all page breaks are in the original locations as the individual documents.
  • Attempt to use a single, consistent format that maintains the look and feel of the original standards document.
    • Convert source code listings and function prototypes to monospace typeface, for example Courier. (Tip: use the Format Paintbrush.)
    • Use the same typeface and size for all regular text. Source code may be formatted in a different size, but all source code should be the same size and in monospace.
    • Ensure font face and size modifications do not cause pages to overflow their original length.

We have four documents to assemble, each of which is a separate task.

Mentor Guidelines: The student will submit a .docx file. The mentor will review this document for correctness, paying attention to formatting, correct pagination, and proper content.

Convert PDF to Text for Original Requirements Documents

RTEMS was originally written to adhere to the proposed Real-Time Executive Interface Definition (RTEID) and Open Real-Time Kernel Interface Definition (ORKID) standards. These efforts disbanded before reaching official status but RTEMS exists today and was originally based on those proposals. We have scans of the original 20+ year old documents and would like students to:

  • feed them into Google Drive for initial conversion to text
  • If the file is over 2M you will have to use a pdf splitting utility, such as http://foxyutils.com/splitpdf/
  • proofread the result of that
  • perform basic formatting including page breaks, etc. to get basic look of original document
  • ensure that paragraphs in the document are still paragraphs (e.g. no embedded carriage returns) in the new version
  • do NOT bold, italize or change the font. Try to limit yourself to basic layout formatting. If in doubt, ask a question and ensure this page gets updated with the recommendation.
  • Do NOT use blank lines to force page breaks!!! Use "Insert Page Break"
  • merge all the pages of your project into one document on Google Drive
  • Download As Microsoft Word .docx
  • submit the Google Doc version of those pages by pasting links to them as your submission, and submit the downloaded .docx file.

We have a total of ~375 pages in 4 documents. Three of those are higher priority to have converted. We have broken these documents into fragments of 5 pages. Google Drive will only scan the first 10 pages of up to 10 MB. This ensures we stay under that limit.

The task will be to do this on two PDF files which will be 10 pages or less of the original document. Your submission for this work will be one Google Document which corresponds to the scanned files. Use similar names as the original, so we can track them. Merge the two 5-page subset into a single 10-page Google Document. Include the link (read-only with anyone who has the link) to the Google Documents in the submission, and Download As the Google Document as a .docx and upload the .docx file.

Mentor Guidelines: The student will submit a Google Document and a .docx file. The mentor will review this document for correctness, paying attention to formatting and spelling issues caused by OCR.

At some point, these will be placed on the ftp site with the scans and merged into complete documents. They may also be used in the future to derive requirements documents.

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

Deliverables

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://git.rtems.org/rtems.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: http://git.rtems.org/rtems/tree/README.configure , 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:

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.

Outreach/Research

Tasks related to community management and outreach/marketing

Tasks related to studying a problem and recommending solutions

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 at least 10 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 new microprocessor architectures appropriate for RTEMS

Although most computer users are only familiar with the x86, PowerPC (Mac), and ARM (phones, etc.), there are at least a dozen other microprocessor architectures used in embedded systems. Identify one which RTEMS is not available for and determine if it is feasible to port RTEMS to it. If it is not feasible, identify why. If it is feasible, look at the features of the architecture that would be important to the person porting RTEMS to this architecture.

Some of the criteria include: a 16/32 bit architecture, memory over 2 MB, an evaluation board, specific hardware application, or simulator...

The expected result is a short paper.

Test Coverage Status Reporting 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..

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.

eBook Formats for RTEMS Documentation

It would be nice to offer the RTEMS Document Set in an ebook format so it is available in a suitable format for cell phones, eReaders, PDAs, etc. This project is to evaluate how various eBbook formats can be produced using our Texinfo documentation source. The goal is to produce a version of the RTEMS User's Guide in the specified mobile format along with instructions.

The conversion process should:

  1. NOT use PDF format and
  2. should ONLY use open source tools that run on linux.

The formats of interest are:

Building the RTEMS Documentation: In order to get from the RTEMS Documentation Texinfo to any other format, you will need to be able to build the documentation on your own machine. The RTEMS Documentation build procedure generates some files so you MUST build the documentation first into html, pdf, etc. Then you can experiment on a single manual. This will require checking the RTEMS source out from git, running bootstrap (which implies you have the RTEMS autoconf and automake tools installed, and then build. This is likely very much easier for a GCI student if you have the RTEMS Virtual Machine and ask questions on irc as needed. The instructions for building the documentation in the source tree: 

cd ...../rtems/doc
../bootstrap
./configure --enable-maintainer-mode 
make

At that point, you should be able to cd user and then experiment with other texinfo tools.

References:

This task can be instanced once per eBook format identified.

Mentor Guidelines: The student will submit a howto (e.g. instructions) for converting the RTEMS User's Guide into the desired format. They should also submit a file in the appropriate format. If a documented sequence fails and the mentor can't help get by that issue, then that is a passing point. The problem will have to be fed upstream by the mentor. If successful, the output file should be loaded into the appropriate reader to ensure it is at least in the right format. The student is not responsible for perfect output although if the style of the output can vary by adding arguments to the conversion commands, we need to know that. Similarly if there are other tools to do the conversion, we want to know that. Even if the student did not use those options or alternative tools. Ultimately the quality of the output is dependent on the input and the conversion tools. We can't make them responsible for that -- only proving a path works or does not work.

Assess New Software

RTEMS Toolkits - We are defining collections of libraries and support programs which make it easier to get started for certain types of applications. Each potential component must be evaluated for license and appropriateness for use in an embedded environment like RTEMS. Here are the toolkits areas identified so far:

The task consists of taking the proposed software package within the kit and determining the license and language of each package. The deliverable is a .txt (or edit the toolkit page directly) with the type of license (i.e. sleepy cat, gnu public license version 2, etc.), and the language the package is written in (C, C++, Fortran, Java, etc.)

For example: the ExampleKit.txt might look like: 

                                    Examplekit.txt
SOFTWARE         LICENSE      LANGUAGE
libexamplehttpd, sleepycat,   C
trivialexample,  gpl v2,      Java
libsomthing,     mit license, Fortran

Research New Software

RTEMS Toolkits - We are defining collections of libraries and support programs which make it easier to get started for certain types of applications. We haven't identified all potential toolkits or components. Please see above for toolkit areas identified so far.

This task consist of identifying an additional toolkit that would be beneficial for embedded systems development. To see what some other embedded systems developers are doing see: Buildroot Packages. To see how other major *nix-like distributors gather software, see: FreeBSD ports, Fedora packages, and Debian packages. The deliverable is a .txt with a one paragraph explanation of the problem the kit addresses, and example software that would illustrate what type of software goes in the package (licensing would not be an issue at this stage of the proposal).

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.

Add a POSIX Timing Test

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.

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

To create a test, you'll need to be in the rtems/testsuite/your_pattern directory.

For example: 

~/rtems/testsuites/psxtmtests>

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 configure.ac and Makefile.am. Then you'll need to ./bootstrap it.

Changes to Makefile.am 

                          rtems/testsuites/psxtmtests/Makefile.am
 SUBDIRS += psxtmthread01
 SUBDIRS += psxtmthread03
 SUBDIRS += psxtmcond04 # Add a SUBDIRS entry to the bottom
endif

Changes to configure.ac 

                          rtems/testsuites/psxtmtests/configure.ac
 psxtmthread01/Makefile
 psxtmthread03/Makefile
 psxtmcond04/Makefile
])
AC_OUTPUT

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/

Simulator/Emulator

Finally use a simulator/emulator See http://www.rtems.org/wiki/index.php/Quick_Start

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.

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 http://tinyurl.com/rtems-ft

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.

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 http://git.rtems.org/rtems/tree/testsuites/ 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). 
#  Edited on 12/1/2012 by First Last <first.last@gmail.com> as part of Google Code In
#
#  The license and distribution terms for this file may be
#  found in the file LICENSE in this distribution or at
#  http://www.rtems.com/license/LICENSE.
#
This file describes the directives and concepts tested by this test set.

test set name: fserror

directives:
+ open 
+ write
+ read
+ mkdir
+ unlink
+ rmdir

concepts:

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

Fix Known Bugs

Browse through the RTEMS bug database and search for an interesting bug. Try to evaluate if the bug is still present. Get all information necessary to tackle the bug and fix it.

User Interface

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

Test Coverage Report Improvements

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.

Mentor Guideline: Ensure this works.

Retrieved from "http://www.rtems.org/wiki/index.php?title=GoogleCodeInProjects&oldid=12096"
Personal tools
Namespaces

Variants
Actions
Navigation
Gedare's Special Help
Toolbox