Reusable Firmware Development (eBook)

Jacob Beningo is an embedded software consultant with over 15 years of experience in microcontroller based real-time embedded systems. After spending over ten years designing embedded systems for automotive,defense and space industries, Jacob founded Beningo Embedded Group in 2009. Jacob has worked with clients in more than a dozen countries to dramatically transform their businesses by improving product quality, cost and time to market. He has published more than 200 articles on embedded software development techniques, is a sought-after speaker and technical trainer who holds three degrees which include a Masters of Engineering from the University of Michigan.  Jacob is an avid writer, trainer, consultant and entrepreneur who transforms the complex into simple and understandable concepts that accelerate technological innovation. Jacob has demonstrated his leadership in the embedded systems industry by consulting and training at companies such as General Motors, Intel, Infineon and Renesas along with successfully completing over 50 projects. Jacob also speaks at and is involved in the embedded track selection committees at ARM Techcon, Embedded System Conferences and Sensor Expo. Jacob holds Bachelor’s degrees in Electrical Engineering, Physics and Mathematics from Central Michigan University and a Master’s degree in Space Systems Engineering from the University of Michigan.In his spare time, Jacob enjoys spending time with his family, reading, writing, playing hockey and golf. In clear skies, he can often be found outside with his telescope, sipping a fine scotch while imaging the sky.

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 – ©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 – ©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 – ©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 – ©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