“Building quality into embedded software doesn’t happen by accident.” Jacob Beningo - March 7th 2016
I like most developers enjoy getting my hands on the keyboard and solving problems. Problem is, whenever I start a new project I end up re-doing some of what I had previously done. Not only is this an incredible waste of time but can be frustrating when you override existing work and create new problems. An area of project development that has often ignored is how a proper start sequence really should be. Recently, I came across an article by Jacob Beningo of the EDN Network titled “Software start-up checklist gives quality a head-start”. After reading this I realized myself that sometimes I am a little too eager to jump on the keyboard and with some pre checklist things, I am able to save precious time. So let's go over some of the phases that Jacob suggests, revised for a more moderate embedded systems project.
Phase 1 - Project Setup
- Setup Revision control ( git, svn, mercurial, etc )
- Create the project
- Create the project directory structure
- White Space config/setup ( template if you have it )
“The first phase in project setup may look trivial but contains very critical steps to getting the quality ball rolling.” Amen. First step is to create that repository that will hold your work and be the tool that allows you to track your work. Git rules in this land for ease of use and coverage. Take for example the MikroElektronika repository:
https://github.com/MikroElektronika
Creating the project structure and the folders that go along with it, in my mind is crucial. It’s much more fun to have some organization before you start than to struggle to get control of the mess later on. I would add to this that code standards are adhered to. Nothing is more fun that looking at a mess of code that makes your blood boil and eyes to bleed.
Phase 2 – Configuration
- Doxy Templates and tool setup
- Import skeleton HAL/API templates
- Version Log
- Hardware configuration
“Developers who are configuring their project should also consider using source and header templates.“ Hallelujah. Having a template source and header file not only adds to the organization of the code, but gives you a clean slate to start with. Having a version log in that template is a great place to leave messages to those that come after you.
The HAL layer is a critical foundation to build on. Once you have a foundation you can build the walls. Without it, you are struggling to keep the walls from falling down.
Phase 3 – Code Analysis
- Setup a static analysis tool
- Setup Code Metrics
- Dynamic code analysis (if the tool is available to you)
“Many developers and teams are fairly bad at performing code analysis or metric measurements until it has gotten too late in the project.” No! That doesn’t happen, does it?
Many free static analysis tools exist and give you that second set of eyeballs on the code. They can catch those silly mistakes and sometimes dangerous ones as well. We’re all bug hunters, but sometimes we need some help ourselves. Cppcheck is the one I use mainly because the command line rules.
Phase 4 – Scheduler Setup
- Setup RTOS or bare metal scheduler
- Requires setting up a system timer / driver
- Create a single task to blink an LED as an indicator
For many of the embedded projects this is an optional step. RTOSes and when to choose to use one or not to use one is entirely a separate topic. But, when using one, this is the right advice.
Phase 5 – Setup Debug Messages
- Setup debug messages
- RTT through debugger
- UART driver
- Printf setup or equivalent RTT
- Configure assert
If you can re-route your debugging messages through the debugger, then do that. This will some a great deal of ROM space. Otherwise, using the UART as a debugging tool is a classic and has its origins somewhere in the digital middle ages. It might also be a great tool to have those debugging messages only triggered with in “debug” mode.
Example:
#ifdef DEBUG #define MSG( error_txt ) UART1_Write_Text( error_txt ) #else #define MSG( ... ) #endif
With this, your code will only print out those debugging messages with a debug mode selection, when in release, your messages will not be compiled into the final ROM size.
References
Jacob Beningo. "Software startup checklist gives quality a head start" EDN Network, March 07, 2016