Reusable Firmware Development : A Practical Approach to APIs, HALs and Drivers

Gain the knowledge and skills necessary to improve your embedded software and benefit from author Jacob Beningo’s more than 15 years developing reusable and portable software for resource-constrained microcontroller-based systems. You will explore APIs, HALs, and driver development among other topics to acquire a solid foundation for improving your own software. Reusable Firmware Development: A Practical Approach to APIs, HALs and Drivers not only explains critical concepts, but also provides a plethora of examples, exercises, and case studies on how to use and implement the concepts. What You'll Learn • Develop portable firmware using the C programming language • Discover APIs and HALs, explore their differences, and see why they are important to developers of resource-constrained software • Master microcontroller driver development concepts, strategies, and examples • Write drivers that are reusable across multiple MCU families and vendors • Improve the way software documented • Design APIs and HALs for microcontroller-based systems Who This Book Is For Those with some prior experience with embedded programming. Table of Contents 5 About the Author 13 About the Technical Reviewers 14 Acknowledgments 16 Preface 17 Introduction 19 Chapter 1: Concepts for Developing Portable Firmware 21 Why Code Reuse Matters 21 Portable Firmware 23 Modularity 29 Module Coupling and Cohesion 30 Following a Standard 32 Portability Issues in C—Data Types 33 Portability Issues in C—Structures and Unions 34 Portability Issues in C—Bit Fields 35 Portability Issues in C—Preprocessor Directives 36 Embedded-Software Architecture 38 Hardware Abstraction Layers (HAL)5 41 Application Programming Interfaces (APIs)6 43 Project Organization 44 Getting Started Writing Portable Firmware 45 Going Further 48 Chapter 2: API and HAL Fundamentals 49 The Wonderful World of HALs 49 APIs Versus HALs 50 The API and HAL Landscape 51 The Good, Bad, and Ugly 53 Potential Issues and the Boogeyman 53 Characteristics Every HAL Should Exhibit 56 Characteristic #1: Contains a Well-Defined Coding Standard 57 Characteristic #2: Reasonable Documentation and Comments 57 Characteristic #3: Written in C99 58 Characteristic #4: Can Be Compiled in Any Modern Compiler 58 Characteristic #5: Abstract Useful Hardware Features 59 Characteristic #6: Easily Extensible 60 Characteristic #7: Modular and Adaptable 60 Characteristic #8: Deterministic and Well-Understood Behavior 61 Characteristic #9: Error-Handling and Diagnostic Capabilities 62 Characteristic #10: Integrated Regression Testing 63 Evaluating HAL Characteristics 64 To Build or Not to Build 65 A First Look at a HAL 67 The API Scope 68 API Characteristics to Look For 69 Characteristic #1: Using const Frequently 69 Characteristic #2: Easily Understood Naming Conventions 70 Characteristics #3: Consistent Look and Feel 73 Characteristic #4: Well Documented 73 Characteristic #5: Flexible and Configurable 73 Designing Your Own APIs 73 A First Look at an API 74 Wrapping APIs 75 Why Design Your Own APIs and HALs? 77 Comparing APIs and HALs 78 Going Further 78 Chapter 3: Device Driver Fundamentals in C 81 Understanding the Memory Map 81 Planning the Driver Interfaces 84 Design by Contract 86 Assertion Fundamentals 88 Device Driver Models 90 Polling Versus Interrupt-Driven Drivers 91 Driver Component Definition 96 Naming Convention Recommendations 98 Object-Oriented Programming in C 99 Abstractions and Abstract Data Types (ADTs) 100 Encapsulation and Data Hiding 106 Callback Functions 106 Error Handling 109 Leverage Design Patterns 110 Expected Results and Recommendations 111 Going Further 112 Chapter 4: Writing Reusable Drivers 114 Reusable Drivers 114 Deciphering the extern and static Keywords 114 Deciphering the volatile Keyword 117 Deciphering the const Keyword 118 Memory-Mapping Methodologies 120 Mapping Memory Directly 120 Mapping Memory with Pointers 121 Mapping Memory with Structures 124 Using Pointer Arrays in Driver Design 125 Creating a Timer Driver Overview 126 Step #1: Define the Timer’s Configuration Table 127 Step #2: Define the Timer’s Peripheral Channels 128 Step #3: Populate the Timer’s Configuration Table 129 Step #4: Create the Timer’s Pointer Arrays 130 Step #5: Create the Initialization Function 131 Step #6: Fill in the Timer Driver Interface 135 Step #7: Maintain and Port the Design Pattern 135 Selecting the Right Driver Implementation 136 Going Further 137 Chapter 5: Documenting Firmware with Doxygen 139 The Importance of Good Documentation 139 Easing the Documentation Load 140 An Introduction to Doxygen 142 Installing Doxygen 144 Documentation Project Setup 145 Doxygen Comment Fundamentals 149 Documenting enum and struct 150 Documenting Functions 151 Documenting Modules 155 Creating a Reusable Template 157 Generating a Main Page 158 Ten Tips for Commenting C Code 160 Tip #1: Explain the Why, Not the How 161 Tip #2: Comment Before Coding 161 Tip #3: Use Doxygen Tags 162 Tip #4: Adopt a Code Style Guide 162 Tip #5: Use a File Header 163 Tip #6: Create a Commenting Template 163 Tip #7: Have a Consistent Comment Location 164 Tip #8: Don’t Comment Every Line 164 Tip #9: Start Mathematical Type Identifiers with the Type 164 Tip #10: Update Comments with Code Updates 165 A Few Final Thoughts on Documentation 165 Going Further 166 Chapter 6: The Hardware Abstraction Layer Design Process 167 Why Use a HAL? 167 A Good HAL’s Characteristics 168 The HAL Design Process 169 Step #1: Review the Microcontroller Peripheral Datasheet 170 Step #2: Identify Peripheral Features 170 Step #3: Design and Create the Interface 171 Step #4: Create Stubs and Documentation Templates 173 Step #5: Implement for Target Processor(s) 176 Step #6: Test, Test, Test 176 Step #7: Repeat for the Next Peripheral 178 10 Tips for Designing a HAL 179 Tip #1: Identify Core Features 179 Tip #2: Avoid an All-Encompassing HAL 179 Tip #3: Add Register-Access Hooks 180 Tip #4: Use Doxygen to Outline the HAL 180 Tip #5: Get a Second Set of Eyes 180 Tip #6: Don’t Be Afraid to Iterate 181 Tip #7: Keep the View at 30,000 Feet 181 Tip #8: Use Appropriate Naming Conventions 182 Tip #9: Include a Parameter for Initialization 182 Tip #10: Deploy on Multiple Development Kits 182 Going Further 183 Chapter 7: HAL Design for GPIO 184 GPIO Peripherals Overview 184 Step #1: Review the GPIO Peripheral Datasheet 184 Step #2: GPIO Peripheral Features 185 Step #3: Design and Create the GPIO HAL Interface 186 Step #4: Create GPIO Stubs and Documentation Templates 189 Step #5: Implement GPIO HAL for Target Processor 209 Step #6: Test, Test, Test 215 Step #7: Repeat for the Next Peripheral 215 Going Further 216 Chapter 8: HAL Design for SPI 218 An Overview of SPI Peripherals 218 Step #1: Review the SPI Peripheral Datasheet 219 Step #2: SPI Peripheral Features 220 Step #3: Design and Create the SPI HAL Interface 221 Step #4: Create SPI Stubs and Documentation Templates 222 Step #5: Implement SPI HAL for Target Processor 226 Step #6: Test, Test, Test 232 Step #7: Repeat for the Next Peripheral 233 Going Further 233 Chapter 9: HAL Design for EEPROM and Memory Devices 235 An Overview of Memory Devices 235 Step #1: Review the EEPROM Peripheral Datasheet 237 Step #2: EEPROM Peripheral Features 238 Step #3: Design and Create the EEPROM HAL Interface 240 Step #4: Create EEPROM Stubs and Documentation Templates 243 Step #5: Implement EEPROM HAL for Target Processor 247 Step #6: Test, Test, Test 253 Step #7: Repeat for the Next Peripheral 253 Extending the EEPROM HAL 253 Going Further 256 Chapter 10: API Design for Embedded Applications 258 Applications Made Easier 258 Designing APIs 260 Application Frameworks 261 Creating Your Own APIs 262 Common Software Frameworks—RTOS and Schedulers 263 Common Software Frameworks— Console Applications 265 Common Software Frameworks—Bootloaders 267 Common Software Frameworks—FAT File System 269 Going Further 271 Chapter 11: Testing Portable Embedded Software 272 Cross Your Fingers and Pray 272 Unit Testing 273 Taking Advantage of Cyclomatic Complexity for Unit Testing 275 Standard Interface . . . Standard Tests 278 Functional Testing 279 Test-Driven Development 280 Hardware In-Loop Testing 281 Regression Testing 283 Automating Tests 284 Using Trace to Verify Application Software 285 A Modern Example: The Renesas SynergyTM Platform 287 Going Further 289 Chapter 12: A Practical Approach to Code Reuse 291 Being Practical in an Unpractical Environment 291 Phases and Baby Steps 292 Identifying Desired Results and Outcomes 294 Desired Results: Decreasing Time to Market 295 Desired Results: Decreasing Development Costs 296 Desired Results: Increased Quality 297 Evaluating Where You Are 298 Defining How to Get There 298 Getting the Most from Metrics 299 Metrics Worth Tracking 299 Assess the Results 302 Recognizing Design Patterns 302 Creating Templates and Checklists 303 Version Control Is Your Best Friend 306 Tip #1: Commit Frequently 307 Tip #2: Fill in the commit log 307 Tip #3: Don’t forget to add files to the VCS 308 Tip #4: Define a commit process 308 Tip #5: Lock modules that are in process 308 Tip #6: Utilize the code-comparison tools 309 Tip #7: Don’t fear merging code branches 309 What Is the Cost to Do Nothing? 309 Final Thoughts 311 Going Further 312 Index 314 Gain the knowledge and skills necessary to improve your embedded software and benefit from author Jacob Beningo's more than 15 years developing reusable and portable software for resource-constrained microcontroller-based systems. You will explore APIs, HALs, and driver development among other topics to acquire a solid foundation for improving your own software. Reusable Firmware Development: A Practical Approach to APIs, HALs and Drivers not only explains critical concepts, but also provides a plethora of examples, exercises, and case studies on how to use and implement the concepts. You will: Develop portable firmware using the C programming language Discover APIs and HALs, explore their differences, and see why they are important to developers of resource-constrained software Master microcontroller driver development concepts, strategies, and examples Write drivers that are reusable across multiple MCU families and vendors Improve the way software documented Design APIs and HALs for microcontroller-based systems Gain the knowledge and skills necessary to improve your embedded software and benefit from author Jacob Beningos more than 15 years developing reusable and portable software for resource-constrained microcontroller-based systems. You will explore APIs, HALs, and driver development among other topics to acquire a solid foundation for improving your own software.⥵sable Firmware Development: A Practical Approach to APIs, HALs and Drivers#xEBF4; only explains critical concepts, but also provides a plethora of examples, exercises, and case studies on how to use and implement the concepts. You will: Develop portable firmware using the C programming language Discover APIs and HALs, explore their differences, and see why they are important to developers of resource-constrained software͡ster microcontroller driver development concepts, strategies, and examples Write drivers that are reusable across multiple MCU families and vendors Improve the way software documented Design APIs and HALs for microcontroller-based systems Front Matter ....Pages i-xxii Concepts for Developing Portable Firmware (Jacob Beningo)....Pages 1-28 API and HAL Fundamentals (Jacob Beningo)....Pages 29-60 Device Driver Fundamentals in C (Jacob Beningo)....Pages 61-93 Writing Reusable Drivers (Jacob Beningo)....Pages 95-119 Documenting Firmware with Doxygen (Jacob Beningo)....Pages 121-148 The Hardware Abstraction Layer Design Process (Jacob Beningo)....Pages 149-165 HAL Design for GPIO (Jacob Beningo)....Pages 167-200 HAL Design for SPI (Jacob Beningo)....Pages 201-217 HAL Design for EEPROM and Memory Devices (Jacob Beningo)....Pages 219-241 API Design for Embedded Applications (Jacob Beningo)....Pages 243-256 Testing Portable Embedded Software (Jacob Beningo)....Pages 257-275 A Practical Approach to Code Reuse (Jacob Beningo)....Pages 277-299 Back Matter ....Pages 301-308