DOC

Firmware Development Standard

By Glenn Owens,2014-04-29 17:23
11 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 blindly assume that allocating and freeing memory is cost- or (not as a subroutine). Be careful to initialize these selects at the problem-free.

    very top of the module, to allow future subroutine calls to operate,

    and since some debugging tools will not operate reliably until these If you chose to use malloc(), always check the return value and

    are set up. safely crash (with diagnostic information) if it fails.

    Stack and Heap Issues When using C, if possible (depending on resource issues and

    processor limitations), always include Walter Bright’s MEM Always initialize the stack on an even address. Resist the

    package (http://c.snippets.org/browser.php) with the code, at least temptation to set it to a odd value like 0xffff, since on a word

    for the debugging. machine an odd stack will cripple system performance.

    Page 6

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

    Firmware Development Standard

    MEM provides: ; Memory leak detection ; ISO/ANSI verification of allocation/reallocation functions ; Pointer checking ; Logging of all allocations and frees ; Out of memory handling ; Verifications of Frees

     Detection of pointer over- and under-runs. ;

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

    Firmware Development Standard

    Modules

    General Templates

    A Module is a single file of source code that contains one or more To encourage a uniform module look and feel, create module functions or routines, as well as the variables needed to support the templates named “module_template.c” and

    functions. module_template.asm”, stored in the source directory, that

     becomes part of the code base maintained by the VCS. Use one of Each module contains a number of related functions. For instance, these files as the base for all new modules. The module template an A/D converter module may include all A/D drivers in a single includes a standardized form for the header (the comment block file. Grouping functions in this manner makes it easier to find preceding all code), a standard spot for file includes and module-relevant sections of code, and allows more effective encapsulation. wide declarations, function prototypes and macros. The templates

     also include the standard format for functions. Encapsulation - hiding the details of a function’s operation, and

    keeping the variables used by the function local - is absolutely Here’s the template for C code:

    essential. Though C and assembly language don’t explicitly support

    /*************************************************** encapsulation, with careful coding you can get all of the benefits of * Module name: this powerful idea as do people using OOP languages. * * Copyright 1997 Company as an unpublished work.

    * All Rights Reserved. In C and assembly language you can define all variables and RAM * inside the modules that use those values. Encapsulate the data by * The information contained herein is confidential defining each variable for the scope of the functions that use these * property of Company. The user, copying, transfer or

    * disclosure of such information is prohibited except variables only. Keep them private within the function, or within the * by express written agreement with Company. module, that uses them. * * First written on xxxxx by xxxx.

    * Modules tend to grow large enough that they are unmanageable.

    * Module Description: Keep module sizes under 1000 lines to insure tools (source * (fill in a detailed description of the module’s debuggers, compilers, etc.) are not stressed to the point they * function here).

    become slow or unreliable, and to enhance clarity. *

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

    /* Include section

    * Add all #includes here

    Page 8

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

    Firmware Development Standard * ; First written on xxxxx by xxxx. ***************************************************/ ;

    /* Defines section ; Module Description:

    * Add all #defines here ; (fill in a detailed description of the module * ; here).

    ***************************************************/ ;

    /* Function Prototype Section ;*************************************************** * Add prototypes for all functions called by this ; Include section

    * module, with the exception of runtime routines. ; Add all “includes” here

    * ;*************************************************** ***************************************************/

    The template includes a section defining the general layout of functions, as follows: The template includes a section defining the general layout of functions, as follows: ;*************************************************** ; Routine name : foobar /************************************************** ; returns : return value(s) description * Function name : TYPE foo(TYPE arg1, TYPE arg2…) ; arg1 : description of arguments * returns : return value description ; arg2 : description * arg1 : description ; Created by : author’s name * arg2 : description ; Date created : date * Created by : author’s name ; Description : detailed description * Date created : date ; Notes : restrictions, odd modes * Description : detailed description ;************************************************** * Notes : restrictions, odd modes

    **************************************************/ Module Names

    Never include the project’s name or acronym as part of each

    module name. It’s much better to use separate directories for each The template for assembly modules is:

    project.

    ;**************************************************

    ; Module name: Big projects may require many dozens of modules; scrolling ; through a directory listing looking for the one containing function ; Copyright 1997 Company as an unpublished work.

    main() can be frustrating and confusing. Therefore store function ; All Rights Reserved.

    ; main() in a module named main.c or main.asm. ; The information contained herein is confidential ; property of Company. The user, copying, transfer or Filenames will be all lower case to enhance portability between ; disclosure of such information is prohibited except

    ; by express written agreement with Company. Windows and Linux/Unix systems. ;

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

    Firmware Development Standard File extensions will be: Directory Contents README C Source Code filename.c Build rules for make project.mak C Header File filename.h

    Assembler files filename.asm

    Assembler include files filename.inc

    Object Code filename.obj

    Libraries filename.lib

    Shell Scripts filename.bat

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

Report this document

For any questions or suggestions please email
cust-service@docsford.com