A Firmware Development Standard

Table of Contents


Table of Contents___






Scope______






Projects____






Directory Structure_






Version File________






Make and Project Files____






Startup Code____






Stack and Heap Issues___






Modules___






General__






Templates






Module Names___






Variables_






Names__






Global Variables






Portability_______






Functions_






Interrupt Service Routines__






Comments_






Coding Conventions_________






General_






Spacing and Indentation_______






C Formatting_______






Assembly Formatting_______






Tools_____






Computers_______






Compilers et al____






Debugging_______










Scope


This document defines the standard way all programmers will create embedded firmware. Every programmer is expected to be intimately familiar with the Standard, and to understand and accept these requirements. All consultants and contractors will also adhere to this Standard.




The reason for the Standard is to insure all Company-developed firmware meets minimum levels of readability and maintainability. Source code has two equally-important functions: it must work, and it must clearly communicate how it works to a future programmer or the future version of yourself. Just as a standard English grammar and spelling makes prose readable, standardized coding conventions ease readability of one’s firmware.




Part of every code review is to insure the reviewed modules and functions meet the requirements of the Standard. Code that does not meet this Standard will be rejected.




We recognize that no Standard can cover every eventuality. There may be times where it makes sense to take exception to one or more of the requirements incorporated in this document. Every exception must meet the following requirements:




?        Clear Reasons - Before making an exception to the Standard, the programmer(s) will clearly spell out and understand the reasons involved, and will communicate these reasons to the project manager. The reasons must involve clear benefit to the project and/or Company; stylistic motivations, or programmer preferences and idiosyncrasies are not adequate reasons for making an exception.

?        Approval - The project manager will approve all exceptions made

?        Documentation - The effected module or function will have the exception clearly documented in the comments, so during code reviews and later maintenance the current and future technical staff understand the reasons for the exception, and the nature of the exception.














Projects


Directory Structure
To simplify use of a version control system, and to deal with unexpected programmer departures and sicknesses, every programmer involved with each project will maintain identical directory structures for the source code associated with the project.




The general “root” directory for a project takes the form:

/projects/project-name/rom_name




where

?        “/projects” is the root of all firmware developed by the Company. By keeping all projects under one general directory version control and backup is simplified; it also reduces the size of the computer’s root directory.






?        “/project-name” is the formal name of the project under development.






?        “/rom_name” is the name of the ROM the code pertains to. One project may involve several microprocessors, each of which has its own set of ROMs and code. Or, a single project may have multiple binary images, each of which goes into its own set of ROMs.




Required directories:

/projects/project-name/tools - compilers, linkers, assemblers used by this project. All tools will be checked into the VCS so in 5 to 10 years, when a change is required, the (now obsolete and unobtainable) tools will still be around. It’s impossible to recompile and retest the project code every time a new version of the compiler or assembler comes out; the only alternative is to preserve old versions, forever, in the VCS.

/projects/project-name/rom_name/headers - all header files, such as .h or assemble include files, go here.

/projects/project-name/rom_name/source - source code. This may be further broken down into header, C, and assembly directories. The MAKE files are also stored here.






/projects/project-name/rom_name/object - object code, including compiler/assembler objects and the linked and located binaries.






/projects/project-name/rom_name/test - This directory is the one, and only one, that is not checked into the VCS and whose subdirectory layout is entirely up to the individual programmer. It contains work-in-progress, which is generally restricted to a single module. When the module is released to the VCS or the rest of the development team, the developer must clean out the directory and eliminate any file that is duplicated in the VCS.









Version File
Each project will have a special module that provides firmware version name, version date, and part number (typically the part number on the ROM chips). This module will list, in order (with the newest changes at the top of the file), all changes made from version to version of the released code.




Remember that the production or repair departments may have to support these products for years or decades. Documentation gets lost and ROM labels may come adrift. To make it possible to correlate problems to ROM versions, even after the version label is long gone, the Version file should generate only one bit of “code” - a string that indicates, in ASCII, the current ROM version. Some day in the future a technician - or yourself! - may then be able to identify the ROM by dumping the ROM’s contents. An example definition is:

# undef VERSION






# define VERSION “Version 1.30”












Example:

/**************************************************






* Version Module - Project SAMPLE






*






* Copyright 1997 Company






* All Rights Reserved






*






* The information contained herein is confidential






* property of Company. The use, copying, transfer or






* disclosure of such information is prohibited except






* by express written agreement with Company.






*






* 12/18/97 - Version 1.3 - ROM ID 78-130






*       Modified module AD_TO_D to fix scaling






*       algorithm; instead of y=mx, it now






*       computes y=mx+b.






* 10/29/97 - Version 1.2 - ROM ID 78-120






*       Changed modules DISPLAY_LED and READ_DIP






*      to incorporate marketing’s request for a






*       diagnostics mode.






* 09/03/97 - Version 1.1 - ROM ID 78-110






*       Changed module ISR to properly handle






*       non-reentrant math problem.






* 07/12/97 - Version 1.0 - ROM ID 78-100






*       Initial release






**************************************************/






# undef VERSION






# define VERSION “Version 1.30”









Make and Project Files
Every executable will be generated via a MAKE file, or the equivalent supported by the tool chain selected. The MAKE file includes all of the information needed to automatically build the entire ROM image. This includes compiling and assembling source files, linking, locating (if needed), and whatever else must be done to produce a final ROM image.




An alternative version of the MAKE file may be provided to generate debug versions of the code. Debug versions may include special diagnostic code, or might have a somewhat different format of the binary image for use with debugging tools.




In integrated development environments (like Visual C++) specify a PROJECT file that is saved with the source code to configure all MAKE-like dependencies.




In no case is any tool ever to be invoked by typing in a command, as invariably command line arguments “accumulate” over the course of a project… only to be quickly forgotten once version 1.0 ships.




Startup Code
Most ROM code, especially when a C compiler is used, requires an initial startup module that sets up the compiler’s runtime package and initializes certain hardware on the processor itself, including chip selects, wait states, etc.




Startup code generally comes from the compiler or locator vendor, and is then modified by the project team to meet specific needs of the project. It is invariably compiler- and locator-specific. Therefore, the first modification made to the startup code is an initial comment that describes the version numbers of all tools (compiler, assembler, linker, and locator) used.




Vendor-supplied startup code is notoriously poorly documented. To avoid creating difficult-to-track problems, never delete a line of code from the startup module. Simply comment-out unneeded lines, being careful to put a note in that you were responsible for disabling the specific lines. This will ease re-enabling the code in the future (for example, if you disable the floating point package initialization, one day it may need to be brought back in).

Many of the peripherals may be initialized in the startup module. Be careful when using automatic code generation tools provided by the processor vendor (tools that automate chip select setup, for example). Since many processor boot with RAM chip selects disabled, always include the chip select and wait state code in-line (not as a subroutine). Be careful to initialize these selects at the very top of the module, to allow future subroutine calls to operate, and since some debugging tools will not operate reliably until these are set up.

http://www.ganssle.com/misc/fsm.doc