On Reference Code

Summary: Depending on reference code is not always wise.

Frequent correspondent Charles Manning sent a link (https://devzone.nordicsemi.com/question/33007/what-ble-profile-would-suit-a-ecg-signal-best-and-is-there-any-example-code-for-adc-in-to-that-profile/) to a question on Nordic Semiconductor's site. The entire question, verbatim, is "What BLE profile would suit a ECG signal best and is there any example code for ADC in to that profile? Have searched for a while and cant (sic) find any."

Charles - and I - were stunned. Someone is building a critical bit of medical equipment with what appears to be limited knowledge of the communications protocol they'll use. He is also planning to build this upon vendor-supplied reference code.

It's probably unfair to read too much into this question, despite the possibly-chilling repercussions for users. I don't want to knock the forums; they are a great way of sharing knowledge. Pre-Internet we all pretty much had to figure things out on our own, which was terribly inefficient. I can remember flying to vendors' facilities to talk to chip designers to get the inside scoop on some poorly-documented or broken bit of functionality.

And, believe me, I'm all for reuse, and think it's really our only hope of salvation as systems get bigger and more complex.

The person who phrased this question may be an extremely competent developer who will analyze the code before using it. But this is a symptom of two problems with the industry today.

The first is the aforementioned often-crummy quality of vendor-supplied code. In some cases it's so bad a semiconductor company will put a large team of their own engineers into a customer site to help get a product to market. Of course, this only happens for those buying enormous numbers of chips so the little folks, or even those buying hundreds of thousands, are stuck.

In some cases I know that the work these engineers do never makes it back into the reference code supplied to everyone else. There's never time to address any issue other than the immediate crisis, so doing an update is out of the question.

One has to have some sympathy for the vendors; after all, their mission is to sell chips. Reference code is free and therefore perceived as a loss leader. The stuff has to exist to push silicon out the door, but never gets the attention it needs. Modern MCUs are really complex. Even the bus fabric can baffle. Peripherals run in innumerable modes. Hundreds or even thousands of registers have to be set exactly right. Datasheets run 500, 1000 or more pages today. Reference software really can't address every mode and configuration. The cost to develop this stuff is enormous, the price is zero.

The second problem is the perennial issue of time to market. Customers simply don't have the time to figure out the nuances of handling all of these peripherals so rightly want solid code they can drop their applications on top of. Reusable reference code is a solution. If this were a perfect world, reuse would be at the object code level, all of the reused code would be qualified, and customers would have complete confidence in the code.

One wonders with the explosion of IoT devices coming our way if this problem will only get worse.

Unfortunately, there's a subtle meta-problem as well. Suppose a semiconductor vendor builds reference code that is absolutely perfect. No bugs, brilliantly documented and a testament to fine software engineering practices. Who would believe them? Decades of problems has create a general distrust. How would a vendor convince the skeptical that, now, for sure, they have produced what we really want?

When it comes to reuse it pays to think about the pyramids. They were built on incredibly strong foundations. In the firmware world, all too often that's inverted.

What is your experience with reference code?

Published March 26, 2015