Symbol style guidelines

[russss]

Assuming we are willing to make some deviations from datasheets (which are usually awful), it would be good to have a consistent style for pin naming. For example:

• Clearly subscripted letters should be lowercase: Vcc rather than VCC
• Use +/- rather than P/N or A/C
• nRST should be ~RST~
• Clarify when we should specify alternate pin functions in the pin label
• How to name exposed pads if the datasheet doesn't specify a pin number

[adamgreig]

I like this idea.

• How to indicate alternate functions - "A/B" or "A_B" or something else? I think I like A/B better
• I think exposed pads should always be "EP" which we use a lot, even if otherwise given a pad number. Except for packages with multiple pads on the underside which are not just ground slugs, e.g. power transistors, LGA packages, etc, where do whatever the datasheet names/numbers them.
• This interacts a bit with #53 wrt how we name transistor pins and how those map to footprints
• How do we handle changing an existing symbol? Hopefully most people are using agg-kicad as a submodule (or directly copying files) so are only hit by changes when they specifically update it

[adamgreig]

Also maybe @cillian64 or @JMW95 will have some thoughts on this

[russss]

Regarding alternate functions:

• We should probably only specify a single, "most common" one, to stop symbol width getting comically large.
• Should we change the order so that the canonical pin name always ends up nearest the actual pin (i.e. PA1/SPI1_NSS if the pin is on the left of the symbol, but SPI1_NSS/PA1 if it's on the right)? (This will probably break if you rotate the symbol in eeschema.)
• I wonder if alternate functions should be listed in a different format to strapping pins?

[adamgreig]

I think for something like a microcontroller, each pin has too many alternate functions to make it sensible to list any. Even SPI1_NSS will appear in loads of different places and often on pins that are also I²C and UART at the same time. On devices with just one alternate function it might be more reasonable (e.g. the rpi symbol).

On the many special purpose chips where pins have maybe two functions (e.g. strapping as you mention, or trim/softstart on vregs) and they have both functions in the name on the datasheet then I think it makes more sense to name them like that.

Changing the order depending on side sounds like it will just lead to too much trouble thanks to rotation, so I don't think it's worth doing.

What different format can you think of? Like using A_B vs A/B?

[russss]

Well, the ESP32 symbol I added recently uses A-B, but I think the forwardslash is probably the best option for everything.

(Incidentally I believe even the RPi has the capability to remap pins but it seems like there's a very strong convention there.)

[cillian64]

• Subscripts becoming lowercase: I can see the logic but I am mildly against in the case of VCC, just because Vcc looks wrong to me. Then again this wouldn't affect me because I don't use agg-kicad power pins, and use voltage-specific rails anyway. Are there other instances of this change which have a more convincing benefit?
• Differential signals: whatever we choose needs to match KiCAD's notation for differential routing. I seem to recall it likes +- and PN but not AB?
• I agree with using ~RST instead of nRST
• Alternate functions: On microcontrollers you can't show all AFs, so I would say show none. However in some cases you have two functions where it's not clear which should be dominant. I'm thinking of the 6800/8080 memory interfaces where it's pretty confusing if you only show one set, and not too arduous to show both sets. So maybe if there is one primary function (uCs) we show that, or if there are 2 equal alternatives we show both? I like using A/B rather than A_B. I don't like swapping the order depending which side the pin is on: With 6800/8080 you use all of the first alternatives or all of the second alternatives. Swapping the order would confuse this.
• I think EPs should be named GND and numbered EP

[adamgreig]

@cillian64

• This is just about pin names on ICs, rather than the power pins.
• The name on the pins doesn't matter to kicad, which routes differential nets by the net name (which doesn't inherit from the pin name); the only reason to do this is to make the pin name match the likely net name. KiCAD uses + and - or _N and _P. A/C is anode/cathode for LEDs.

[adamgreig]

@russss
Right, so on something like the rpi where there's a strong convention to use a single alternate function I think it make sense to include it. Likewise on an Arduino where 0 and 1 are TX and RX, and it has PWM pins, etc, but only one thing per pin.