Table of ContentsScopeProjectsDirectory StructureVersion FileMake and Project FilesStartup CodeStack and Heap IssuesModulesGeneralTemplatesModule NamesVariablesNamesGlobal VariablesPortabilityFunctionsInterrupt Service RoutinesCommentsCoding ConventionsGeneralSpacing and IndentationC FormattingAssembly FormattingToolsComputersCompilers et alDebuggingA Firmware Development StandardVersion 1.2, Updated Jan, 2004Jack G. [email protected] Ganssle GroupPO Box 38346Baltimore, MD 21231 fax (647) 439-1454Firmware Development StandardTable of ContentsTable 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__________________________________________________Page 2© 1998, 2004 The Ganssle Group. This work may be used by anyone as a software standard. Publication rights reserved.Firmware Development StandardSpacing and Indentation____________________________________C Formatting_____________________________________________Assembly Formatting_______________________________________Tools__________________________________________________Computers_______________________________________________Compilers et al____________________________________________Debugging________________________________________________Page 3© 1998, 2004 The Ganssle Group. This work may be used by anyone as a software standard. Publication rights reserved.Firmware Development StandardScopeThis 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 acceptthese requirements. All consultants and contractors will also adhereto 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 theexception clearly documented in the comments, so during codereviews and later maintenance the current and future technical staff understand the reasons for the exception, and the nature of the exception. Page 4© 1998, 2004 The Ganssle Group. This work may be used by anyone as a software standard. Publication rights reserved.Firmware Development StandardProjectsDirectory StructureTo 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_namewhere- “/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 sizeof 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 - sourcecode. 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 theindividual programmer. It contains work-in-progress, whichis generally restricted to a single module. When the module is