TEM Logo The Embedded Muse
Issue Number 343, February 5, 2018
Copyright 2018 The Ganssle Group

Editor: Jack Ganssle, jack@ganssle.com

   Jack Ganssle, Editor of The Embedded Muse

You may redistribute this newsletter for non-commercial purposes. For commercial use contact jack@ganssle.com. To subscribe or unsubscribe go here or drop Jack an email.

Editor's Notes

Wouldn't you want to be in the top tier of developers? That is part of what my one-day Better Firmware Faster seminar is all about: giving your team the tools they need to operate at a measurably world-class level, producing code with far fewer bugs in less time. It's fast-paced, fun, and uniquely covers the issues faced by embedded developers. Information here shows how your team can benefit by having this seminar presented at your facility.

Mat Kramer won the Siglent SDS1204X-E oscilloscope in last month's contest.

Quotes and Thoughts

"Digital? Any idiot can count to one." Bob Widlar, famous (and quirky) analog designer

Tools and Tips

Please submit clever ideas or thoughts about tools, techniques and resources you love or hate. Here are the tool reviews submitted in the past.

Do you control releases using a Version Description Document? There's a good write-up about these in the deceased and very-missed Dr. Dobb's Journal , and a sample here.

By the way, did you know the original title of that publication was Dr Dobb's Journal of Computing Calisthenics and Orthodontia (Running Light Without Overbyte)? It started as a quirky newsletter by the People's Computer Company (it was 1976, after all), and as the readers matured into professionals, it did as well. The first year's compendium is rather fun. It includes code for a Tiny Basic interpreter that needed just a couple of kB of memory; to achieve that remarkable goal the interpreter was written in a custom interpreted language. So a Basic program was interpreted twice as it executed. Very clever idea in an era when memory was in scant supply. It's copyright notification was: "@COPYLEFT ALL WRONGS RESERVED".

A Reason For Automatic-Reboots

Kevin Hess had some interesting comments about a router that routinely reboots itself:

Another subscriber pointed out that a router recently purchased had a built in date/time based reset feature.  Specifically: "Luca Matteini bought a TotoLink A3-AC1200 wi-fi router. It has a surprising feature." That feature automatically reboots the router every so often.

He wondered if this implied the existence of sufficient SW defects to warrant regular customer resets.  Perhaps you also considered this.  Here's my perspective.

There's no doubt such a feature can be used to mask a number of SW problems such as memory leaks.  And if you work in the world of Windows, you know that when something "goes wrong", the first thing to do is to reboot the machine.  No one can say a particular SW implementation is defect free.  So no router can be seen as completely secure.  

We also know from looking at information from the Toyota runaway vehicle cases that extremely bad embedded SW exists.  And from research we know high energy particles like cosmic rays can cause memory bit flips leading to errant operation and failure which requires reboots to recover.

All of these concerns can be justifications for a date/time forced reboot of router SW.  

However, security can be another justification for this feature.  The purpose of a router is to provide logical communications isolation between the local intranet and the big internet.  We employ routers to protect our systems from certain types of communication based attacks.  Other computer users benefit when the computers we manage are protected by a router are not misused.

Many router vendors, including HW independent router releases like DD-WRT, offer this date/time based reboot feature.  Automated reboot provides the ability to close all open connections and force users - particularly unauthorized users (hackers) - to go to the work of re-establishing logical connections.  For a black hat hacker, connections lost at inopportune times can disrupt stolen data transfers or attack sequences.  Attackers often use intermediate systems to carry out their attacks against targets.  Making your systems unavailable or too much work for black hat hackers benefits everyone.

The core concepts of Confidentiality, Availability and Integrity lead system designers to include features which increase overall security.  Specifically, availability does not mean universal access for all including unauthorized users intent on using your systems for evil purposes.  In this context it means availability exclusively to authorized users. User configurable timed reboots increases availability for authorized users and decreases it for unauthorized users.

I hope the foregoing explanation provides some justification for this feature and a reason to use it when appropriate.

On Requirements

While the news is full of stories of software disasters, it is instructive to look at successes, and nowhere is there more success than in avionics. DO-178C (AKA ED-12C in Europe) is the standard to which commercial avionics is developed. It's quite arcane. Leanna Rierson's book Developing Safety-Critical Software: A Practical Guide for Aviation Software and DO-178C Compliance is the best guide I've found for demystifying the guidelines. DO-178C stresses developing accurate requirements and then insuring that every requirement has associated tests, and no code exists for which there is no requirement. Traceability from requirements to low-level code is a must.

In her book Leanna spells out the characteristics of a well-thought-out requirement. She has kindly allowed my to cite her work:

Good requirements do not just happen. They require considerable effort, focus, and discipline. To write good requirements, it is important to understand the characteristics of such requirements. Requirements authors and reviewers should incorporate the following characteristics of good system requirements:

  • Atomic - each requirement should be a single requirement.
  • Complete - each requirement contains all of the necessary information to define the desired system functionality. Each requirement should be able to stand alone without further amplification.
  • Concise - each requirement should simply and clearly state what must be done and only what must be done. It should be easy to read and understand - even by nontechnical users of the system. In general, a textual requirement should not contain over 30-50 words. Requirements represented using graphics should also be concise.
  • Consistent - requirements should not contradict or duplicate other requirements. Consistent requirements also use the same terminology throughout the specification. Requirements are not the place to practice creative writing.
  • Correct - each requirement should be the right requirement for the system being defined. It should convey accurate information. This attribute is ensured by the requirement's validation effort.
  • Implementation free - each requirement should state what is required without identifying how to implement it. In general, requirements should not specify design or implementation. However, there may be some exceptions, such as interface or derived system requirements.
  • Necessary - each requirement should state an essential capability, characteristic, or quality factor. If the requirement is removed, a deficiency should exist.
  • Traceable - each requirement should be uniquely identified and easily traceable through to lower level requirements, design, and testing.
  • Unambiguous - each requirement should only have one interpretation.
  • Verifiable - it should be possible to confirm the implementation of each requirement. Therefore, requirements should be quantifiable and include tolerances, as appropriate. Each requirement should be written such that it can be verified by review, analysis, or test. Except for rare cases, if the behavior cannot be observed during verification, the requirement should be rewritten. For example, negative requirements are generally not verifiable and require a rewrite.
  • Viable - each requirement should be able to be implemented, usable when implemented, and helpful to the overall system construction.

Wise words.

I'm often asked about developing requirements. Karl Weigers' Software Requirements is an excellent resource.

A Free Metrics Tool

I'm an advocate of collecting and analyzing metrics in firmware engineering. After all, engineering is about three things:

  • Predict what is going to happen.
  • Make it happen.
  • Measure to see if it really happened the way you expected.

Leave off the third step and this is art, not engineering.

We have a lot of quantitative information about the nature of good code which should guide our development. And, there are a lot of great tools available for collecting the metrics. One of my favorites is a freebie called SourceMonitor by Campwood Software. You aim the tool at your source code and you'll get a screen like this:

The top window shows up first and gives numbers for the entire project. Double-click on that and the bottom window appears, which breaks things down by source file.

Some of the numbers are self-explanatory. Others include:

  • Average statements/function - well, that's pretty obvious, but is important as we know, in general, that we should restrict functions to about 50 lines of code.
  • Max Complexity is the cyclomatic complexity of the most complex function in the file. Ten to 15 is a good upper bound.
  • Max Depth is the most deeply-nested block in the code. Steve McConnell believes three is a good limit; other authorities will allow five. But the 7 in manage.c means one of the functions is too deep for mere mortals to grok.
  • % Comments is the percentage of non-blank lines that are comments, or that have comments. In Measuring Software Quality: A Case Study, Thomas Drake studied 30 million lines of code at NSA and found that the best code with the fewest problems averaged 60% comments. To quote from the paper: "This may raise some eyebrows, but NSA has a huge base of legacy code, some of which has been running for decades."

Click on one of the files and this appears:

This makes it easy to drill down and see where the problems are in the file.

Another option is to examine details about one of the files to get statistics about each function:

Double-click on a function name and an editor appears with the focus on the selected function.

The program is small and very fast. One annoying "feature" is that it doesn't remember what directory you've been in, and every time it starts you have to navigate from the Program Files directory to your code. It's for Windows only. Recommended.

This Week's Cool Product

Somehow I missed this when it came out a while ago. Express Logic, which sells the ThreadX RTOS, has a feature called "Modules." With most RTOSes one must link the entire product's code together as one executable. That's rather different from using, for instance, Windows, where many applications can be loaded and unloaded from memory. With Modules a deeply-embedded system can have the same sort of functionality. Applications can be built independently from the RTOS and loaded as needed, or can execute-in-place. There's a pretty good write-up here, and a glitzy sales page here. With an MPU or MMU each application can be completely isolated. I can see a lot of use for this in some systems.

In other RTOS news, Amazon has taken over FreeRTOS, and Richard Barry now works for them. It appears Amazon wants microcontroller-based devices to connect to their cloud. And with the company now offering FPGA instances, well, all one can say is "One Company to rule them all, One Company to find them, One Company to bring them all and in the darkness bind them, in the land of Amazon where the economy lies."

Note: This section is about something I personally find cool, interesting or important and want to pass along to readers. It is not influenced by vendors.


Let me know if you’re hiring embedded engineers. No recruiters please, and I reserve the right to edit ads to fit the format and intent of this newsletter. Please keep it to 100 words. There is no charge for a job ad.

Joke For The Week

Note: These jokes are archived at www.ganssle.com/jokes.htm.

A woman gets a $284 billion electric bill and wonders if it was because of her Christmas lights.

Advertise With Us

Advertise in The Embedded Muse! Over 27,000 embedded developers get this twice-monthly publication. .

About The Embedded Muse

The Embedded Muse is Jack Ganssle's newsletter. Send complaints, comments, and contributions to me at jack@ganssle.com.

The Embedded Muse is supported by The Ganssle Group, whose mission is to help embedded folks get better products to market faster.