# component symbols conventions

Werner Almesberger werner at openmoko.org
Wed May 13 15:30:21 CEST 2009

Dave Ball wrote:
> I think we should use something consistent for the project - rather than
> go with differing vendors conventions.

Yes, I think we'll be constrained anyway. The sooner or later, we'll
find a chip that uses some non-ASCII symbols to name a pin (e.g., I've
seen things like \Phi_1 for chip-internal signals already), and then
we'd have to depart from the vendor's naming scheme anyway.

However, I think we should try to stay as close to vendor names as
possible as long as this doesn't cause any conflicts.

> I don't think it matters what we use, but I'm in favour of overscore
> where possible, or /  in ascii.

Overscore is widely used and looks nice but would need some replacement
for ASCII.

There's also the issue that KiCad doesn't support this type yet, and if
we make it carry information (as opposed to being only a visual effect),
it would need to be translated inside KiCad as well, when it shows up
in places where overscore isn't possible. Getting this right might
actually need quite a lot of small changes.

An easier approach may be to work with an ASCII-compatible prefix and
only change the presentation, e.g., xFOO is displayed and printed as
\overline{FOO} or even \overline{xFOO}. This could also be implemented
incrementally.

/ has none of these problems. However, multi-purpose pins are often
called FOO/BAR, so there's a big conflict. Similar with things like
R/\overline{W}.

# seems to be free of such conflicts. It has the small issue that you
still need to translate it to generate identifiers in programs.

Let's see what our betters are doing:

- Samir Palnitkar uses FOObar (no pun intended) in "Verilog HDL"

- Tim Williams (The Circuit Designer's Companion), John Catsoulis
(Designing Embedded Hardware), and Steve Furber (ARM system-on-chip
architecture) all use overscore in text and diagrams

So they don't seem to be much help.

I think a (future) automated conversion of xFOO to \overline{FOO}
or \overline{xFOO} looks like a winner for presentation. I'd lean
towards using \overline{xFOO} despite the redundancy ("this ain't
no FOO"), because you can then use the same name everywhere for
searching, and people unaware of the convention should intuitively
get it right.

This leaves us with the quest for "x". My favourite would still be
"n" since it can be used directly as an identifier as well. On the
other hand, "#" sticks out more, which may be an advantage in some
cases.

So ... what shall it be ? Did anyone get bitten by using either of
them in some project ?

- Werner