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:
Additional sections can be added as required. For example, often graphic support needs special prose which can be put into an About Graphics section.
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.
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.
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.
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.
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.
Paths to files, such as src/hardware/startup/boards/ should be in a mono-spaced font, using the double curly brace syntax like so:
{{src/hardware/startup/boards/}}
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 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]
... ... ...
}}} %%
This is also achieved via grievous abuse of css:
%%(border: solid; border-width: thin; width: 80em; padding: 0.5em;) __Note__:\\ ... %%