Project Home
Project Home
Project Information
Project Info
wiki2811: BSPReleaseNotesGuidelines

BSP Release Notes Guidelines#

This wiki page documents the best practices to witting and formatting BSP Release Notes.

Since the release notes are on the wiki, we have some flexibility in the presentation. As such the most important is that the BSP release notes should be correct, useful and look nice.


The release notes need to have at minimum the following sections:

  • TOC
  • System Requirements
  • System Layout
  • Getting Started
  • Driver Command Summary
  • Addtional Sections
  • ...
  • ...
  • Known Issues

Additional sections can be added as required. For example, often graphic support needs special prose which can be put into an About Graphics section.

System Requirements#

This should give a quick overview of any host requirements and the target system for which the BSP was developed.

On the host side we need to just mention what version of Momentics is required to build, and what type of connections are required (Ethernet, serial, etc). Make sure to differentiate between a straight through serial cable, and a null modem one, as the two cable types are different. Also it is good to mention any special services that are required by the target such as tftp servers, or nfs servers and the like.

On the target side we need to document anything that we know might change between target revisions, such as the amount of memory installed, and the size of flash. Also if any special boot-loaders are expected that should be documented too.

System Layout#

Here is your chance to document the expected addresses of things in memory and flash that are used by the BSP in a single location.

Getting Started#

This section should document the steps required to build and download an ifs image to the board. Documenting how to write the ifs image to flash is also useful. Follows are some sections that could be considered, but depending on what is going on it can be different.

Building the BSP

How to modify and build the BSP is documented else where. So it just needs to be mentioned, no need to go into details. However, if the ifs image needs to be copied from the default location in the images directory that should be mentioned -- an example is that when booting from a tftp server.

Connect your Hardware

In this section document which ports are used for serial and Ethernet, as modern boards seem to have (∞-1) ports, and I hate trying to figure-out which one is the debug one, and I am too lazy to go to the board docs. Serial port settings would also be nice.

Setup you environment

This is optional if one can boot by skipping this step. Moving forward this should be documented somewhere else, but if you have it, include it for now.

Boot the IFS image

Show how to boot the ifs image.

Writing the IFS image to flash using the boot loader

If the boot loader supports writing to flash this is where you would document it. Make sure that you include any necessary changes to the build file that are different from booting over tftp.

Creating a flash partition

I am not sure that this should go here.

Driver Command Summary#

This section is basically a re-hash of the build file. Since most of the information is very brief it is presented in a table. Drivers that need a bit more explanation can get a small section after. Things that need significant documentation should get an About X section, where X is the thing that needs significant documentation.

Know Issues#

Note: The layout of this section is still TBD.

This section lists known issues that effect the BSP specifically, and not general annoyances.

Issues need to have a PR number, so that we can go back and check the status. PR's should have a note regarding the release notes that reference it.

Issues that have been fixed by a specific version of the BSP are shunted off to an ever popular The following issues have been resolved with the X.X.X release: section.

General Style Guide#


Paths to files, such as src/hardware/startup/boards/ should be in a mono-spaced font, using the double curly brace syntax like so:


Showing Input and Output#

Input is show in mono-space bold. Because users will often be following along with the wiki open in a window or a print out on their desk we want the commands to pop a little bit more from the page.

Inline commands are done like so: run make to build the BSP,

run __{{make}}__ to build the BSP

Multiple commands are put into a pre-formatted box:

echo Wiki Markup Style

cd sand/bsp

__ {{{ echo Wiki Markup Style cd sand/bsp make }}} __

Output and interactive items are shown in a pre-formatted box with dark blue with a light grey background, just to differentiate it from the input, and it looks like a screen shot.

++... Read from 0x07ee0000-0x07f00000 at 0xa1fe0000: .
... Read from 0x07ed3000-0x07ed4000 at 0xa1fff000: .

Clock input is 27 MHz
Booting from [NOR flash]
%%(color:darkblue; background-color:#eeeeee; width: 80em;) {{{

... ... ...

}}} %%


This is a note. It has a thin border. And starts off on a bold note. Notes should stand out.

This is also achieved via grievous abuse of css:

%%(border: solid; border-width: thin; width: 80em; padding: 0.5em;)  
__Note__:\\ ...