Go here to sign up for The Embedded Muse.
The Embedded Muse Logo The Embedded Muse
Issue Number 452, August 15, 2022
Copyright 2022 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

SEGGER Embedded Studio cross platform IDE

Tip for sending me email: My email filters are super aggressive and I no longer look at the spam mailbox. If you include the phrase "embedded muse" in the subject line your email will wend its weighty way to me.

Quotes and Thoughts

Far better an approximate answer to the right question, which is often vague, than an exact answer to the wrong question, which can always be made precise. John Tukey

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.

The always-interesting Shape of Code blog has a quick study of estimation - in the building industry! (Scroll down to "Estimation accuracy in the (building|road) construction industry"). Like us, these folks have a hard time getting estimates right, though most come in under actual costs. It would have been interesting to see how this correlates to fixed-price- (if there are any in that business) versus cost-plus-jobs.

The Rust language gets a lot of press. But is it better than C? "Better" is, of course, a subjective term that should be modified by lots of caveats. However, this article thinks it's not a C replacement, at least in the embedded space.

Freebies and Discounts

The giveaway is on hiatus for the summer.

More on Documenting in English

The last issue's comments about documenting in English generated a lot of dialog. Some comments follow.

The always-thoughtful Vlad Z wrote:

> There were two general objections. The first is that English is an
> imprecise language that is easily abused. It's pretty easy to write
> sentences that are redundant, recursive, vague and open to multiple
> interpretations. I agree!

I do too. English, like all non-formal languages, is imprecise.  All human languages are imprecise because they are constantly evolving.  Actually, the PERL programming language is also imprecise.  When I was learning it, I stumbled in the manual on a consolation: "PERL will do the right thing most of the time."
We deal with that imprecision by removing all extraneous verbiage, and if we make ambiguous statements, they are qualified by the context.  In general, that is.  As has been stated in the Muse many times, the very existence of comments is controversial.

> The second objection was that English is far from a universal
> language. Wikipedia pegs the number of languages used in the world at
> as many as 7000. Should a Farsi speaker be required to document in
> English, which may be a very foreign lingo?

The objection is fallacious.  If the engineering is done in Iran, then, by all means, use Farsi as a commenting language.  But if the work is done in an English-speaking environment, then comments *must* be in English.  It may be bad English, and it might need to be corrected during the code review, but it must be English.  I did have to deal with comments like "start fire manger," and we fixed that with some laughs.  The process needs to be agreed upon.  Unfortunately, it seldom even exists, and corrections are not made because "who reads the comments anyway?" and for the fear of insulting the author.  I see it as just wrong.  It's better to strip bad comments altogether than to leave useless crap in the source.

Philip Johnson writes "make sure you understand something sufficiently before trying to code it". He continues:

I'm not really sympathetic to the general objections posed to documentation, because all of the objections can be stated equally with regard to source code. For example:

  • "C is an imprecise language that can be easily abused" (and often is), yet we are still here writing code in C. So why is it that an imprecise language that can be easily abused is good enough for writing the code, but one that provides more precision than the programming language is not suitable for documenting it? There are many more words in the English language than the "C" vocabulary provides, leading to a larger degree of possible precision. Whether or not someone is using a language precisely is a different factor to consider, and not the fault of the language itself.
  • "C is far from a universal language", yet we can write programs in it. So why is it ok for us to write programs in C, when it is far from universal?

And, I'm by no means an English maximalist (who cares? document in whatever language you want, as long as it meets the needs of your future team and customers).

Philip's exhortations to "make sure you understand something sufficiently before trying to code it" cannot be emphasized enough. I think the worst curse that plagues this industry is our very natural desire to jump in and start coding ASAP, all-too-often before we have a good understanding of the problem. Today some wags deprecate design. I have been told that "a design will emerge from the code." This is a reaction to the time needed to really think things through. If you think good design is expensive... try bad design.

Sergio Caprile echoes Philips thoughts on C:

> <https://www.ganssle.com/tem/tem449.html#quotesandthoughts> was "If you
> can't write it down in English, you can't code it." Not everyone agreed.
> There were two general objections. The first is that English is an
> imprecise language that is easily abused. It's pretty easy to write
> sentences that are redundant, recursive, vague and open to multiple
> interpretations.

That also sounds very much like C, isn't it ? Yet there is no excuse to properly express ourselves in C, because neither the compiler nor the processor will make any efforts to try to understand the actual meaning of what we are writing.

> The second objection was that English is far from a universal language.
> Wikipedia <https://en.wikipedia.org/wiki/Language> pegs the number of
> languages used in the world at as many as 7000. Should a Farsi speaker
> be required to document in English, which may be a very foreign lingo?

I don't know how many programming languages there are, but if we expect the technological equivalent of "someone to talk to" we'll use a common enough language in order to get decent programmers, a decent compiler, a decent optimizer, at least.

Hence, the same applies to the comments language...

Imagine if the first scientific books would have been written in any local language... Latin was the common language for that and any respectable science practitioner would learn Latin. Same for English these days.

I don't imagine learning French to grasp Fourier series, then Danish to understand the Doppler effect, then Italian for the relativity principle, then German for the general relativity theory, and so on...

Well, English is now the common language and hence comments should be written in English unless you are willing to be limited by the reach of your language (like in your Czech example, great btw)

John Carter writes:

I have slightly conflicted views on it.

Your choice of programming language should be the most precise and concise language to documentation of how it works.

Your unit tests are the most accurate and reliable documentation of what it does. (So design them so it is readable as such)

You only need the English for the "why" your code is that way or does this.

On the other extreme, like the sign at the top of the proverbial ladder,  "Start Other Side".

I wish we would _start_ with the sales brochure and user documentation.

If you can't explain simply and clearly to a user what the value of the feature is, what it does and how to use it.... it's not going to be valued, it's not going to sell, it is not going to be used, and it's going to be hell to build and test, and is going to be buggy because nobody is quite sure what it is meant to do.

And if you can't do any of that, go away and build something you can.

Jan Woellhaf makes an interesting point about English as the lingua franca in aviation:

Apropos to commenting code in English, the language of international aviation is English. At a large airport in France, for example, controllers are supposed to speak ONLY English, even when talking to pilots who are native French speakers. The fact that this convention is not always observed has led to several near disasters, such as almost landing on top of another airplane!

A professional pilot addresses this issue in his video at https://www.youtube.com/watch?v=_WkxkrtrFsg&t=20s.

Martin Buchanan comes at this from the standpoint of a documenter:

From January 1985 to October 1989 I was technical publications manager (and first writer, starting the department) or lead writer and team lead for our operating system documentation at BiiN, the Intel/Siemens joint venture to build a new hardware, software, and systems architecture that was performant, high-security, fault tolerant, concurrent, and object-oriented in the hardware. Our capability-based operating system was written entirely in Ada and the operating system documentation was perhaps a third of the 57 manuals and 15,000 pages of documentation the writers produced.

Early on I struck a bargain with the operating system managers, that the writers owned the comments in the OS package specifications' source code and the developers owned the code. We created tools to verify that writers did not accidentally change the code and tools to generate the OS manuals directly from the comments, an early form of single-sourcing multiple documentation formats. Our OS API reference manual was about 3,000 pages spread across multiple printed volumes and generated automatically. Ruthless editing plus readability scoring tools meant that our OS documentation could be used by an eighth grader, if the eighth grader was a systems programmer fluent in Ada.

I mention all this to recommend the same approach today. Let the writers own the interface comments and the programmers own the rest of the code, regardless of which tools are being used to turn comments into documentation. A good technical writer can document your interfaces better than most developers can.

(And I'm not job-hunting with these comments, as I work full-time for a Laramie startup as a senior software engineer.)

Finally, Claus Waldersdorff Knudsen makes the amusing point: "Maybe we should learn to document our work IKEA style?"

Cooperative Multitasking

Daniel McBrearty is a fan of cooperative multitasking:

I finally had time to obtain a copy of this book which you reviewed a while ago, and have a good look at it. I have a few comments I'd like to pass on.

I learned quite a bit from the book, particularly on the subject of verifying timing when an RTOS is involved, and the existence of static analysis tools for doing so.

However, I was quite surprised to see an almost complete absence of discussion of bare metal systems using a co-operative scheduler. For me this has been a "goto" approach for hard real-time control which I have found to be very reliable over several projects.

Gliwa does discuss bare-metal applications briefly on pages 38-40, presenting two applications which are in my opinion a bit naive in their simplicity. He then goes on to say (p40):

"Experience shows that such approaches are expanded over time ... (until) ... configuration and implementation are wildly mixed. In such cases the development team has failed to make a timely switch to the use of an operating system."

The rest of the book then goes on to discuss ways of validating system timing when an RTOS is used, which is not simple, given the complexities of configuring task priorities, allowing for timing variations due to context switching, and also the use of cache and pipelines on top of that.

It seems to me that the author has not at all done justice to the possibilities of a cooperative scheduler on bare metal. A few years ago I implemented (on a 32 bit PIC) such a system which accepted and responded to serial commands via UART, simultaneously activated and controlled 3 stepper motors (with a constant acceleration profile to get to minimise forces on the load), while also reading a laser sensor, using averaged readings from which to find edges of objects in the path and report them back. All of this was achieved without an RTOS and has been extremely stable over several years of daily use. (In fact so solid that I would have to get the source code out to remember how I did a lot of it.)

The basis of such a system is of course a scheduler where all tasks MUST complete before the next timer tick occurs. I took the inspiration for mine from RIOS ( https://www.cs.ucr.edu/~vahid/rios/ ) which I then refined to add debug printing from a buffer in the "dead" zone, a "run" LED which also served as a simple load monitor, and other niceties. There are of course a few considerations with such a system:

1. obviously all tasks must complete in the allotted time, or you have a fatal error.

2. everything is single thread, so generally atomicity is only a problem for memory objects which are accessed in ISRs. The general rule to only write to shared buffers etc from ONE (higher priority) source serves very well here, but specific cases do need to be thought through.

3. tasks needing finer granularity than the timer tick (in my case, actual generation of pulses for the motors) can operate in higher priority interrupts, driven from additional timers or other sources.

4. If tasks are kept reasonably simple, determining worst case timing is pretty easy - you just measure the worst case for each task, take the worst case sum, and add the worst case time given to ISRs. This for me is the KEY advantage. (No worries about task switching overhead or when certain tasks might pop up and throw things out. They all run, every time.)

5. Obviously blocking in a task (or an ISR) is a complete no-no. Many tasks end up being little state machines.

Eventually the system becomes a group of state machines with separate responsibilities, which communicate via their APIs.

C lends itself to this approach quite well if you see each .c/.h pair as an "object". (These days I might have multiple files in a folder, with only one "external API", to allow for unit testing within a module using Ceedling.) In such a way, separation of concerns and modularity is quite achievable. In modern systems, for instance certain SOC's that combine several embedded processors with FPGA real estate, such an approach could be hugely powerful - one bare metal processor (with hardware support as needed) does the hard RT stuff, the other perhaps runs embedded Linux or similar to provide networking and higher level tasks.

All in all it seems to me that this approach has many advantages over an RTOS, at least until a certain level of complexity, from the point of view of ensuring hard real time performance.

I find it a bit prosaic that Gliwa has entirely passed over such an approach in a book dedicated to the subject of timing in real time systems, and particularly the implication that anything more than the simplest tasks must use an RTOS. For me, one of the key factors in building systems successfully is to select the simplest and most appropriate techniques of "getting it done". I think that Gliwa has fallen back on the "defaults" of the auto industry here (well-proven though they may be) and bypassed a very important class of simpler solutions.

With cooperative multitasking there is no preemptive scheduling. A task runs for its allotted time and then returns execution to the scheduler. It's based on the assumption that tasks will be well-behaved and won't starve the CPU. Few tools ever existed to support this. Z World's Dynamic C was a strange compiler that had built-in cooperative multitasking. It was a mild success for a time. It seems to still be available, though only for the Rabbit MCU.

Failure of the Week

From Stephen:

From Boi Okken:

Have you submitted a Failure of the Week? I'm getting a ton of these and yours was added to the queue.

This Week's Cool Product

Dave Marpleshas been on Open Source tooling for ARM CORTEX Debug and Trace in collaboration with Vegard Eriksen in Norway. They now have a low cost interface, known as ORBTrace, which can act both as a 'regular' JTAG/SWD debug interface, and as a SWO or TRACE interface too. It's not really aimed at 'professional engineers' (although they're welcome to use it!). If you depend on your tools to put food on the table then you should be buying something from Segger, Keil, Lauterbach or one of the other organisations that are structured to offer proper support. It _is_ aimed at the cohort who can't access that quality of kit; hobbyists and university students/professors should all benefit from having access to this stuff, and in exchange they'll improve it too by scratching their own itches.

As Dave writes: Please take a look at https://orbcode.org.  This will either resonate with you and you can see possibilities, or you'll hit the delete key... I hope it's the former, but I certain won't be offended if it's the latter.  There is (a bit) of hardware available, but sales are not the aim of the game here and we've pushed the price right down because we want adoption of these technologies.

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

These jokes are archived here.

From Jon:

My Function Generator has a setting for "dental trauma tsunami"
The output produced is a sore-tooth wave.

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.