DOC

Firmware Development Standard

By Glenn Owens,2014-04-29 17:23
12 views 0
Firmware Development StandardFirm

    A Firmware Development Standard

    Version 1.4, Updated May, 2007

    Jack G. Ganssle

    jack@ganssle.com

    The Ganssle Group

    PO Box 38346

    Baltimore, MD 21231

     fax (647) 439-1454

    Firmware Development Standard

    Table of Contents

    Table of Contents _____________________________________2 Coding Conventions __________________________________ 17

    General _______________________________________________ 17 Scope _______________________________________________3

    Spacing and Indentation _________________________________ 17 Projects _____________________________________________4

    C Formatting __________________________________________ 17 Directory Structure _____________________________________ 4

    Assembly Formatting ____________________________________ 18 Version File ____________________________________________ 4 Make and Project Files ___________________________________ 5 Startup Code ___________________________________________ 5 Stack and Heap Issues ___________________________________ 6 Modules _____________________________________________8 General _______________________________________________ 8 Templates _____________________________________________ 8 Module Names _________________________________________ 9 Variables ___________________________________________11 Names _______________________________________________ 11 Global Variables _______________________________________ 11 Portability ____________________________________________ 12 Functions __________________________________________13 Interrupt Service Routines _____________________________14 Comments __________________________________________15

    Page 2 ? 1998, 2004 The Ganssle Group. This work may be used by anyone as a software standard. Publication rights reserved.

    Firmware Development Standard

    Scope

    This document defines the standard way all programmers will We recognize that no Standard can cover every eventuality. There create embedded firmware. Every programmer is expected to be may be times where it makes sense to take exception to one or intimately familiar with the Standard, and to understand and accept more of the requirements incorporated in this document. Every these requirements. All consultants and contractors will also exception must meet the following requirements: adhere to this Standard.

     ; Clear Reasons - Before making an exception to the Standard, The reason for the Standard is to insure all Company-developed the programmer(s) will clearly spell out and understand the firmware meets minimum levels of readability and maintainability. reasons involved, and will communicate these reasons to the Source code has two equally-important functions: it must work, project manager. The reasons must involve clear benefit to the and it must clearly communicate how it works to a future project and/or Company; stylistic motivations, or programmer programmer or the future version of yourself. Just as a standard preferences and idiosyncrasies are not adequate reasons for English grammar and spelling makes prose readable, standardized making an exception.

    coding conventions ease readability of one’s firmware. ; Approval - The project manager will approve all exceptions

     made

    Part of every code review is to insure the reviewed modules and ; Documentation Document the exception in the comments, so functions meet the requirements of the Standard. Code that does during code reviews and later maintenance the technical staff not meet this Standard will be rejected. understands the reasons and nature of the exception.

    Page 3

    ? 1998, 2004 The Ganssle Group. This work may be used by anyone as a software standard. Publication rights reserved.

    Firmware Development Standard

    Projects

    code every time a new version of the compiler or assembler Directory Structure comes out; the only alternative is to preserve old versions,

    forever, in the VCS. To simplify use of a version control system, and to deal with

    /projects/project-name/rom_name/headers - all unexpected programmer departures and sicknesses, every

    header files, such as .h or assemble include files, go here. programmer involved with each project will maintain identical

    - source /projects/project-name/rom_name/source directory structures for the source code associated with the project.

     code. This may be further broken down into header, C, and The general “root” directory for a project takes the form: assembly directories. The MAKE files are also stored here.

    /projects/project-name/rom_name /projects/project-name/rom_name/object - object

     code, including compiler/assembler objects and the linked where and located binaries.

    ; /projects” is the root of all firmware developed by the /projects/project-name/rom_name/test - This

    Company. By keeping all projects under one general directory directory is the one, and only one, that is not checked into

    version control and backup is simplified; it also reduces the size the VCS and whose subdirectory layout is entirely up to

    of the computer’s root directory. the individual programmer. It contains work-in-progress, ; /project-name” is the formal name of the project under which is generally restricted to a single module. When the

    development. module is released to the VCS or the rest of the

    development team, the developer must clean out the ; /rom_name” is the name of the ROM the code pertains to.

    directory and eliminate any file that is duplicated in the One project may involve several microprocessors, each of

    VCS. 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. Version File

    Each project will have a special module that provides firmware Required directories:

    version name, version date, and part number (typically the part /projects/project-name/tools - compilers, linkers,

    number on the ROM chips). This module will list, in order (with assemblers used by this project. All tools will be checked

    the newest changes at the top of the file), all changes made from into the VCS so in 5 to 10 years, when a change is required,

    version to version of the released code. the (now obsolete and unobtainable) tools will still be

     around. It’s impossible to recompile and retest the project

    Page 4

    ? 1998, 2004 The Ganssle Group. This work may be used by anyone as a software standard. Publication rights reserved.

    Firmware Development Standard

    * 07/12/97 - Version 1.0 - ROM ID 78-100 Remember that the production or repair departments may have to * Initial release support these products for years or decades. Documentation gets **************************************************/ lost and ROM labels may come adrift. To make it possible to # undef VERSION

    # define VERSION “Version 1.30” 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 Make and Project Files day in the future a technician - or yourself! - may then be able to

    Every executable will be generated via a MAKE file, or the identify the ROM by dumping the ROM’s contents. An example

    equivalent supported by the tool chain selected. The MAKE file definition is:

    # undef VERSION includes all of the information needed to automatically build the # define VERSION “Version 1.30” entire ROM image. This includes compiling and assembling source files, linking, locating (if needed), and whatever else must be done The Version file also contains the Abbreviations Table. See the to produce a final ROM image. section under “Variables” for more detail. An alternative version of the MAKE file may be provided to Example: generate debug versions of the code. Debug versions may include /************************************************** special diagnostic code, or might have a somewhat different format * Version Module - Project SAMPLE

    * of the binary image for use with debugging tools. * Copyright 1997 Company * All Rights Reserved In integrated development environments (like Visual C++) specify *

    * The information contained herein is confidential a PROJECT file that is saved with the source code to configure all

    * property of Company. The use, copying, transfer or MAKE-like dependencies. * disclosure of such information is prohibited except * by express written agreement with Company.

    In no case is any tool ever to be invoked by typing in a command, *

    * 12/18/97 - Version 1.3 - ROM ID 78-130 as invariably command line arguments “accumulate” over the * Modified module AD_TO_D to fix scaling course of a project… only to be quickly forgotten once version 1.0 * algorithm; instead of y=mx, it now ships. * 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 Startup Code * diagnostics mode.

    * 09/03/97 - Version 1.1 - ROM ID 78-110 Most ROM code, especially when a C compiler is used, requires an * Changed module ISR to properly handle initial startup module that sets up the compiler’s runtime package * non-reentrant math problem.

    Page 5 ? 1998, 2004 The Ganssle Group. This work may be used by anyone as a software standard. Publication rights reserved.

    Firmware Development Standard

    and initializes certain hardware on the processor itself, including Since few programmers have a reasonable way to determine chip selects, wait states, etc. maximum stack requirements, always assume your estimates will

     be incorrect. For each stack in the system, make sure the Startup code generally comes from the compiler or locator vendor, initialization code fills the entire amount of memory allocated to and is then modified by the project team to meet specific needs of the stack with the value 0x55. Later, when debugging, you can the project. It is invariably compiler- and locator-specific. view the stack and detect stack overflows by seeing no blocks of Therefore, the first modification made to the startup code is an 0x55 in that region. Be sure, though, that the code that fills the initial comment that describes the version numbers of all tools stack with 0x55 automatically detects the stack’s size, so a late (compiler, assembler, linker, and locator) used. night stack size change will not destroy this useful tool.

    Vendor-supplied startup code is notoriously poorly documented. Embedded systems are often intolerant of heap problems. To avoid creating difficult-to-track problems, never delete a line of Dynamically allocating ad freeing memory may, over time, code from the startup module. Simply comment-out unneeded lines, fragment the heap to the point that the program crashes due to an being careful to put a note in that you were responsible for inability to allocate more RAM. (Desktop programs are much less disabling the specific lines. This will ease re-enabling the code in susceptible to this as they typically run for much shorter periods of the future (for example, if you disable the floating point package time).

    initialization, one day it may need to be brought back in).

     So, be wary of the use of the malloc() function. When using a new Many of the peripherals may be initialized in the startup module. tool chain examine the malloc function, if possible, to see if it Be careful when using automatic code generation tools provided implements garbage collection to release fragmented blocks (note by the processor vendor (tools that automate chip select setup, for that this may bring in another problem, as during garbage example). Since many processor boot with RAM chip selects collection the system may not be responsive to interrupts). Never

    disabled, always include the chip select and wait state code in-line