Chapter 1 Concepts for Developing Portable Firmware .............3Why Code Reuse Matters.................................................................................3Portable Firmware ............................................................................................5Modularity ......................................................................................................... 11Module Coupling and Cohesion.................................................................. 12Following A Standard .................................................................................... 14Portability Issues in C - Data Types ......................................................... 15Portability Issues in C - Structures and Unions................................... 17Portability Issues in C - Bit Fields............................................................. 18Portability Issues in C - Preprocessor Directives ............................... 19Hardware Abstraction Layers (HAL) ....................................................... 21Application Programming Interfaces (APIs) ........................................ 28Project Organization...................................................................................... 28Getting Started Writing Portable Firmware ......................................... 29Going Further ................................................................................................... 32Chapter 2 API and HAL Fundamentals.............................................37The Wonderful World of HALs ................................................................... 37APIs versus HALs............................................................................................. 38The API and HAL Landscape ....................................................................... 40The Good, Bad and Ugly................................................................................ 42Potential Issues and the Boogeyman....................................................... 42Characteristics Every HAL should Exhibit ............................................. 46To Build or Not to Build................................................................................ 56A First Look at a HAL...................................................................................... 58The API Scope ................................................................................................... 59API Characteristics to look for ................................................................... 60Designing your own APIs ............................................................................. 65A First Look at an API .................................................................................... 65Going Further ................................................................................................... 67Confidential - (c)2016 Jacob Beningo, All Rights Reserved, DRAFT A08Chapter 3 Device Driver Fundamentals in C..................................73Understanding the Memory Map...............................................................73Identifying Driver Interfaces.......................................................................77Design by Contract..........................................................................................80Assertion Fundamentals...............................................................................83Device Driver Models .....................................................................................85Polled versus Interrupt Driven Drivers ..................................................87Deciphering the volatile, const and static keywords .........................93Driver Module Definition..............................................................................93Naming Convention Recommendations..................................................95Object Oriented Programming in C...........................................................96Encapsulation and Data Hiding ...............................................................105Abstract Data Types.....................................................................................105Callback Functions .......................................................................................105Error Handling...............................................................................................110Expected Results and Recommendations............................................113Leverage Design Patterns..........................................................................114Going Further .................................................................................................114Chapter 4 Writing Reusable Drivers .............................................119It's All about the Interface.........................................................................119How much Abstraction is too much? .....................................................120Wrapping the Interface ..............................................................................120Memory Mapping Methodologies ...........................................................128Mapping Memory Directly.........................................................................129Mapping Memory with Pointers..............................................................130Mapping Memory with Structures..........................................................133Using Pointer Arrays in Driver Design .................................................136Creating a Timer Driver Overview.........................................................138Step #1 - Define the Timers Configuration Table ............................138Step #2 - Define the Timers Peripheral Channels............................140Step #3 - Populate the Timers Configuration Table........................141Step #4 - Create the Timer Pointer Arrays .........................................143Step #5 - Create the Initialization Function .......................................145Step #6 - Fill in the Timer Driver Interface ........................................150Step #7 - Maintain and Port the Design Pattern...............................150Selecting the Right Driver Implementation........................................151Going Further .................................................................................................152Chapter 5 Documenting Firmware with Doxygen...................157The Importance of Good Documentation ............................................157Easing the Documentation Load .............................................................159An Introduction to Doxygen .....................................................................162Confidential - (c)2016 Jacob Beningo, All Rights Reserved, DRAFT A08Installing Doxygen........................................................................................164Documentation Project Setup ..................................................................166Doxygen Comment Fundamentals..........................................................173Documenting enum and struct.................................................................174Documenting Functions..............................................................................175Documenting Modules ................................................................................181Creating a Reusable Template .................................................................183Generating a Main Page ..............................................................................18410 Tips for Commenting C Code...............................................................187Tip #1- Explain the Why not the How .........................................................188Tip #2 - Comment Before Coding..................................................................189Tip #3 - Use Doxygen Tags...............................................................................189Tip #4 - Adopt a Code Style Guide ................................................................190Tip #5 - Use a File Header ................................................................................190Tip #6 - Create a Commenting Template...................................................191Tip #7 - Consistent Comment Location......................................................191Tip #8 - Don't Comment Every Line ............................................................192Tip #9 - Start Mathematical type Identifiers with the Type..............193Tip #10 - Update Comments with Code Updates ...................................193A Few Final Thoughts on Documentation............................................194Going Further .................................................................................................194Chapter 6 The Hardware Abstraction Layer Design Process197Why use a HAL?..............................................................................................197Characteristics of a Good HAL ..................................................................199The HAL Design Process .............................................................................200Step #1 - Review the Microcontroller Peripheral Datasheet.......202Step #2 - Identify Peripheral Features .................................................203Step #3 - Design and Create the Interface ...........................................204Step #4 - Create Stubs and Documentation Templates ..................206Step #5 - Implement for Target Processor(s) ....................................208Step #6 - Test, Test, Test ............................................................................210Step #7 - Repeat for the Next Peripheral .............................................21210 Tips for Designing a HAL ......................................................................214Tip #1- Identify Core Features ........................................................................214Tip #2 - Avoid an All Encompassing HAL ..................................................215Tip #3 - Add Register Access Hooks ............................................................216Tip #4 - Use Doxygen to Outline the HAL ..................................................217Tip #5 - Get a Second set of Eyes ...................................................................218Tip #6 - Create a Commenting Template ...................................................219Tip #7 - Keep the View at 30,000 Feet........................................................220Tip #8 - Use Appropriate Naming Conventions......................................221Tip #9 - Include a Parameter for Initialization .......................................222Confidential - (c)2016 Jacob Beningo, All Rights Reserved, DRAFT A08Tip #10 - Deploy on Multiple Development Kits ................................... 223Going Further ................................................................................................. 224Chapter 7 HAL Design for GPIO .......................................................227An Overview of GPIO Peripherals ...........................................................227Step #1 - Review the GPIO Peripheral Datasheet.............................228Step #2 - GPIO Peripheral Features ......................................................230Step #3 - Design and Create the GPIO HAL Interface ......................232Step #4 - Create GPIO Stubs and Documentation Templates ......235Step #5 - Implement GPIO HAL for Target Processor .....................237Step #6 - Test, Test, Test ............................................................................239Step #7 - Repeat for the Next Peripheral ............................................241Going Further ................................................................................................. 242Chapter 8 HAL Design for SPI ...........................................................245An Overview of SPI Peripherals ..............................................................245Step #1 - Review the SPI Peripheral Datasheet ................................246Step #2 - SPI Peripheral Features ..........................................................249Step #3 - Design and Create the SPI HAL Interface ..........................251Step #4 - Create SPI Stubs and Documentation Templates ..........254Step #5 - Implement SPI HAL for Target Processor ........................256Step #6 - Test, Test, Test ............................................................................257Step #7 - Repeat for the Next Peripheral ............................................258Going Further ................................................................................................. 260Chapter 9 HAL Design for EEPROM and Memory Devices .....263An Overview of Memory Devices ............................................................263Step #1 - Review the EEPROM Peripheral Datasheet .....................266Step #2 - EEPROM Peripheral Features ...............................................269Step #3 - Design and Create the EEPROM HAL Interface ...............272Step #4 - Create EEPROM Stubs and Documentation Templates 275Step #5 - Implement EEPROM HAL for Target Processor .............277Step #6 - Test, Test, Test ............................................................................278Step #7 - Repeat for the Next Peripheral ............................................279Going Further ................................................................................................. 280Chapter 10 API Design for Embedded Applications ...............283Applications Made Easier ..........................................................................283Software Components .................................................................................285Application Frameworks ...........................................................................289Libraries ...........................................................................................................293The Real-time Operating System (RTOS).............................................296Open Source Software .................................................................................298Integration Nightmares ..............................................................................300Confidential - (c)2016 Jacob Beningo, All Rights Reserved, DRAFT A08Common Software Frameworks - System Configuration ..............303Common Software Frameworks - Console Applications................306Common Software Frameworks - Bootloaders ................................. 309Common Software Frameworks - Thread Tracing...........................312Common Software Frameworks - FAT File System ..........................315Going Further ................................................................................................. 320Chapter 11 Testing Portable Embedded Software ..................323Cross Your Fingers and Pray .....................................................................323Standard Interface .... Standard Tests ...................................................326Test Driven Development ..........................................................................328Taking Advantage of Cyclomatic Complexity for Testing ..............334Automating Tests ..........................................................................................338Python for Testing ........................................................................................342Developing GPIO Test Cases ......................................................................348Developing SPI Test Cases .........................................................................356Test Cases for EEPROM ...............................................................................360Using Trace to Verify Application Software ........................................364Going Further ................................................................................................. 366Chapter 12 A Practical Approach to Code Reuse ......................369Being Practical in an Unpractical Environment ................................369Phases and Baby Steps ................................................................................372Getting the Most from Metrics ..................................................................374Metrics Worth Tracking .............................................................................376Recognizing Design Patterns ....................................................................378Creating Templates and Checklists ........................................................380Version Control is your Best Friend .......................................................383Results - Decreasing Time-to-Market ...................................................385Results - Decreasing Development Costs ............................................387Results -Increased Quality ........................................................................389What is the Cost to do Nothing? ...............................................................391Going Further ................................................................................................. 394Appendix A ...............................................................................................398Appendix B ...............................................................................................415Appendix C ...............................................................................................430References ...............................................................................................445Glossary ....................................................................................................450
