embedded software boot camp

Hardware vs. firmware naming conventions

Sunday, March 28th, 2010 by Nigel Jones

Today’s post is motivated in part by Gary Stringham. Gary is the newest member of EmbeddedGurus and he consults and blogs on what he calls the bridge between hardware and firmware. Since I work on both hardware and firmware, I’m looking forward to what Gary has to say in the coming months. Anyway, I’d recently read his posting on Early hardware / firmware collaboration when I found myself looking at a fairly complex schematic. The microprocessor had a lot of IO pins, most of which were being used. When I looked at the code to gain insight on how some of the IO was being used I found that the hardware engineer and firmware engineer had adopted completely different naming conventions. For example, what appeared on the schematic as “Relay 6″ appeared in the code as “ALARM_RELAY_2″. As a result the only way I could reconcile the schematic and the code was to look at a signal’s port pin assignment on the schematic and then search the code to see what name was associated with that port pin. After I’d done this a few times, I realized I needed a more systematic approach and ended up going through all the port pin assignments in the code and using them to hand mark up the schematic. Clearly this was not only a colossal time waster, it also had the potential for introducing stupid bugs.

So how had this come about? Well if you have ever designed hardware, you will know that naming nets is essentially optional. In other words one can create a perfectly correct schematic without naming any of the nets. Instead all you have to do is ensure that their connectivity is correct. (This is loosely analogous in firmware to referring to variables via their absolute addresses instead of assigning a name to the variable and using it. However, the consequences for the hardware design are nowhere near as dire). Furthermore, if the engineer does decide to name a net, then in most schematic packages I’ve seen, one is free to use virtually any combination of characters. For example “~LED A” would be a perfectly valid net name – but is most definitely not a valid C variable name. If one throws in the usual issue of numbering things from zero or one (should the first of four LED’s be named LED0 or LED1?), together with hardware engineer’s frequent (and understandable) desire to indicate if a signal is active low or active high by using some form of naming convention, then one has the recipe for a real mess.

So what’s to be done? Well here are my suggestions:

  1. The hardware team should have a rigorously enforced naming standards convention (in much the same way that most companies have a coding standards manual).
  2. All nets that are used by firmware must be named on the schematic.
  3. The net names must adhere to the C standard for naming variables.
  4. The firmware must use the identical name to that appearing on the schematic.

Clearly this can be facilitated by having very early meetings between the hardware and firmware teams, such that when the first version of the schematic is released, there is complete agreement on the net names. If you read Gary’s blog post you’ll see that this is his point too – albeit in a slightly different field.

9 Responses to “Hardware vs. firmware naming conventions”

  1. Jeff Gros says:

    Good post. This begs the question…what hardware naming standards do you use?

    For example, at my company, and signal that is active low has a / somewhere in the name, such as CS_/OLED. The use of backslash of course, is not C friendly. So the firmware engineers will replace the ‘/’ with a ‘n’ in lowercase. We also put the ‘n’ at the front of the symbol (which the rest is in uppercase) so that it is easily identifiable to be active low: nCS_OLED.

    As you can see, the names don’t match 100%, but we’ve allowed enough freedom so that either party can do want (within reason), and it is still easily identifiable that the two names correspond.

    I would be interested to hear what conventions you and others at your company use. Perhaps it would make a good blog post?

  2. Nigel Jones says:

    Good question Jeff. The answer is rather long, so as you suggest I’ll save it for another blog post.

  3. Jeff,

    While CS_/OLED and nCS_OLED are easily identifiable to the human being that they are the same, it makes it more cumbersome for automated means to identify them both as the same. If there are several nets that need to be correlated, then human verification becomes cumbersome. Automated verification would be desired to ensure that every hardware net is properly accounted for in the firmware code. So making the names spelled exactly the same, is highly desirable.

  4. Carlos Pando says:

    A few months ago when naming the port pins for the project I’m curretly working at, I took the schematics and tried to name every pin in the same way they were named by the HW engineers, and that worked fairly good untill I found some problems like:

    * 3.5_volt where the dot gave me a hard time
    * X_emergency and Y_emergency where X was active low while Y was active high

    I think the idea of requiring the HW team to adhere to the same naming conventions is a very nice one.

  5. Kyle Bostian says:

    This post reminds me of a tool that I’ve always thought would be helpful, but have never seen: a tool that could take the back-annotation data from a board layout, and apply it to change reference designators in any file – a word document, VHDL source, or C code.

  6. Lundin says:

    I think the hw guys will have to adapt their signal naming to the sw guys and not the other way around, because the hw guys just need to print some text out in silk screen, it doesn’t need to compile. CAD programs usually allow any name for signals, while they may have naming standards for the components themselves. But the components aren’t strictly related to the software, only the signals are.

    Another hint which is nothing but common sense: name everything the same.
    If the project is called “project x motor drive”, the circuit board is named “motor_drive_x” and the program is named “motor_driver”, that is not helpful to humans. Particularly the production folks will be grateful if the “motor_drive_x” program should be downloaded into the PCB labelled “motor_drive_x”, and then mounted in the product “Motor drive X”.

    • Nigel Jones says:

      An excellent suggestion Daniel. I have lost track of the number of projects that I have worked on that started off being called ‘X’ and by the time production rolls around, marketing is calling the product ‘Y’. By this time all the engineering documentation refers to ‘X’, and yet production and the rest of the world know the product as ‘Y’. Very confusing! I have tried in the past to get agreement on product names before any documentation is created – and I’ve failed almost every time.

  7. jiameifang says:

    If the target does not change, it is good, but when target platform changed (upgrade for new function or whatever)and the new target is not pin to pin compatible with the old one, the hardware name maybe need to change, firmware need to change correspondingly.

    What I want to emphasize here is that program according to the abstract interface. For example, turn on a LED maybe just output a high signal, but firmware need to handle different IO on different target, if firmware keeps the TurnOnLed() interface unchanged, it’s easy to port to another platform.

Leave a Reply