embedded software boot camp

Setting a bad example – final thoughts

Sunday, August 15th, 2010 by Nigel Jones

While I am sure that I could extend the setting a bad example  series of  articles I think it’s time to move on to other topics. Before I do so I’d like to give some final thoughts. The series has generated a lot of excellent comments. While the majority have been in response to a particular coding construct, a number of readers have expressed their frustration at how pervasive this problem is with vendor supplied code. My experience agrees with this assessment. In other words while this series has taken IAR to task, I don’t have the slightest doubt that if I had bought an ARM evaluation board from Keil, ImageCraft etc that I would have found similar things to complain about. In other words my experience is the norm and not the exception. Now I don’t think I’m going too far out on a limb by observing that  the code supplied with evaluation boards is very influential in that:

  1. It is likely to find itself incorporated into hundreds, if not thousands of products.
  2. Will be used both verbatim and as a template for future code by huge numbers of inexperienced engineers.

Thus the bottom line is that the code supplied with evaluation boards needs to be of the highest quality and to incorporate as many best practices as possible. While it would be great if this blog was influential enough to cause the vendors to change their ways, I suspect that little will really happen until people start complaining. Those of you that work for large organizations which buy a commensurate number of licenses are in the best position to make the change happen by loudly complaining to your sales representative every time you find some lousy code.

As always, thanks for reading.

13 Responses to “Setting a bad example – final thoughts”

  1. Jeff Gros says:

    A general practice in the industry for silicon vendors (and as you’ve shown, compiler vendors) is to use interns and new engineers to write the sample code. This has its pros and cons.

    PROS:
    It helps familiarize the soon-to-be FAEs learn about the hardware they should be supporting.
    It keeps them from causing too much damage to their internal IP.

    CONS (taken from your post):
    It is likely to find itself incorporated into hundreds, if not thousands of products.
    Will be used both verbatim and as a template for future code by huge numbers of inexperienced engineers.

    Since I’m on the receiving end, and would be using the sample code, I would obviously prefer that it was written by someone with a bit of gray hair (but not too much!).

    Even if the sample code is an example of godliness, you still have to worry about the people using the sample code. I have consulted for many a company who want to have their team, which consists of cheap (read overseas) labor, take over after we finish. People who don’t even know what an errata sheet is, and who don’t want to follow it when you show it to them. All we can do is pray that these product gets stuck in limbo.

    Now stop and think about all those products that go into medical, aviation, automotive and other safety critical fields. Does V & V testing, hazard analysis and the like, prove that a device is 100% safe to use in all cases?

    Don’t get me wrong. I think that these sorts of tests are a good thing. But does it prove that the product is safe?That’s the sort of question that keeps me up at night.

  2. Bernhard Weller says:

    I think you are very right with your assumptions on how the example code ends up.

    First thing I got to do as I started working with the MSP430 was: “Take those examples from TI and familiarize yourself with the mcus.”

    Well luckily I happen to be someone who is not a big friend of copy and paste, especially in embedded software where a set bit really can set you back, so after getting an idea on how to do stuff, I took the User Guides and read carefully the explanations for the modules I needed and wrote everything myself.
    But I guess I’m one of the few who actually had the luxury of time to do so. If I only had a very short time to do things, I guess I’d also copy examples, maybe even put two different examples together. Ending up in a big mess because some examples use the watchdog as reset timer, others as delay timer, and if you mix both you will fail horribly.

    So I’m all in for high quality code supplied by manufacturers.

  3. D Wellesley says:

    Really nice set of articles. It was an eye opener for me.

  4. CiaránMacA says:

    A few yrs ago I spent a number of years working in TI on silicon validation and co-simulation. I was leading a team charged with the responsibility of providing the infrastructure and process for junior engineers who were developing low level software to validate TI silicon. It was an enormous challenge. Many of the team were not experienced with software – though some were very knowledgeable about silicon development. I repeatedly had to explain the difference between a linker error and a compile error. The agressive dealines and sheer scale of the efforst (massive multicore systems on a chip) and the complexity of the team (at one stage our team had people in six countries – configuring clearcase and enforcing discipline there was fun!). Given the low level of software knowledge, I saw it as something of a miracle by the silicon designers that these machines worked at all. Some of our sw people could not have been capable of designing and writing good scenarios of cache/mmu usage.

    I am confident that my work brought the team from pretty much zero in SW discipline to something almost passable. But much more work was required (in the end I moved on to other things). A big problem was managment buy-in: managers were predominantly silicon people and neither understood nor valued the software. They wanted ‘tape out’.

    Some of the SW our team wrote was then lifted by the application guys. There was a vision of more re-use. But given the lack of investment and lack of championing for making the validation team top class, this was a shocking prospect.

    • Jeff Gros says:

      Thanks for the behind the scenes look at TI! If anyone else has some inside knowledge, feel free to speak up! This is good stuff!

      My hope is that TI is starting to understand the value of giving away good software in order to sell chips. In recent years we have seen SimpliciTI, the remoTI stack, ZStack, the USB stacks, etc. It’s not always great software, or reliable, but at least they are making an effort.

      As a user of the TI chips, thank you for pushing them in the right direction! 🙂

  5. Lundin says:

    Come to think of it, I remember getting handed some horrible example code to some TI radio chip a few years back. It was so full with poor programming, non-standard C and reliance on undefined/implementation-specific behavior, it simply couldn’t be used. Luckily we picked another chip instead.

    It would be interesting to see some code “setting a good example”. Are there any startup kits etc out there that actually come with state of the art code?

    • Nigel Jones says:

      Great question. It’s interesting no one has mentioned an evaluation board that they thought came with great code. If anyone knows of such a beast then perhaps they could post it here?

  6. Ian Willats says:

    Thanks for a very interesting set of articles – it’s reassuring to see that I’m not alone in finding some of the code shipped with evaluation kits to be pretty awful.

    You asked for examples of great code coming with an eval kit: coincidentally I’m just starting a project using a Stellaris (Cortex-M3) part, and the eval kit comes with a swathe of what looks like very good example code called Stellarisware. This includes drivers for on-chip peripherals, as well as a small graphics library. Presumably it was written by Luminary Microsystems before TI acquired them.

    While investigating this code to see what it includes, I have been impressed by the consistency of coding style, the quality of documentation, and generally the level of polish that seems to have been applied. I should say I haven’t actually used this software yet, but on the basis of what I can see it seems to be well engineered and, in my opinion at least, sets a high standard as free example code.

  7. Michael says:

    Nice series. I was especially impressed with the quality of the comments. It’s nice to see not just the ‘religious’ style arguments on topics like Single/Multiple Exit, but also some well thought out options for dealing with the downsides of either option.

    I’m curious if IAR have responded to any of this?!?!

    For all of us – instead of suggesting that ‘we’ would be better off if the supplied example code was better I think we need to come up with some convincing reasons for why the vendors themselves would be better off if they provided better quality examples. Off the top of my head I don’t have too many, other than minimising support effort, not sure what the ROI on that would be.

    • Nigel Jones says:

      I agree about the standard of comments. I think my overarching theme on engineering in general is that there is no substitute for thought – and most of the comments posted here are very thoughtful.
      As to whether IAR responded to any of this – no they didn’t which is not surprising since there wouldn’t be too much benefit to them doing so. For me the best argument for vendors providing better code is that it reflects well upon them and ultimately leads to a higher perceived quality of their product in the market place.
      For what it’s worth BTW, I noticed on the back of the IAR board the notation http://www.olimex.com. If you go to this site you will find it’s a Bulgarian company that specializes in designing ‘Development boards’. Given the wide range of boards they have to offer, it may well be that every vendor out there is using them, which might in turn explain the consistency of people’s experience! Thus the fact that it doesn’t appear to be IAR developed code is comforting – but it still doesn’t absolve them of the fact that their name is on it.

  8. Balan says:

    Thanks for the informative articles and comments.

    May be off topic
    1) The initial few chapters of the book “Large Scale C++ Design” by John Lakos contains some points on the physical design like where to place the globals, defines..etc to reduce compile time, coupling. I don’t have the book readily with me

  9. Hank says:

    I got here because I had googled the author’s name to figure out where this ‘stuff’ originated from :^)

    Like many of the rest of you I’m concerned with the net effect on the industry where this code is taken to be an introduction to the standard style for coding embedded devices. Coming from the Windows side, I’ve already seen the long term (30 years and counting) handcuffing that occurs when a dominate player establishes a poor approach to system design and implementation (C++/MFC…).

    In the embedded world, the benefits to embedded C++ seems to be totally off the radar of the CMSIS designers and the demonstration coders. The style seems to be totally locked into the early ’80s, and coded for the lowest common denominator compiler.

    If anyone is interested in a well thought out software approach, I invite you to read.
    http://wiki.qt-project.org/API_Design_Principles

    Now all we have to do is convince ARM, STM, ATMEL, SILABS that they’d sell more product if only the example code didn’t slow down us down from getting our products to market.

Leave a Reply