Rules on editing schematics (was Re: [Milkymist-devel] reviews (was Re: [KiCad M1R4] First KiCad version for Milkymist One Schematics.))

Adam Wang adam at
Thu May 3 03:58:20 EDT 2012


This is for earlier Werner's reply about my schematic editing. :-)
Here's one wiki page:

On Wed, Apr 25, 2012 at 12:31 AM, Werner Almesberger <werner at
> wrote:

> Yes, the whole hierarchy is very chaotic and full of inconsistencies.
> We should also give many component more systematic names. And there
> are too many reasonably generic components that carry the name of a
> specific vendor part.

Regards to how generic components are, we can keep improvements on this

> Furthermore, some of the .lib files contain quite a few fairly
> distinct components. It would be better to have one per file, so
> that the revision history clearly identifies the component that got
> changed.
> I'm also unhappy that we have so many design-specific power symbols.
> Not sure what to do about them, though. KiCad doesn't allow editing
> of the symbol's name, so you need a separate symbol for each such
> net. Perhaps we should use project-local components in such cases.

Good idea ! Yeah, I moved few applicative power symbols locally. :)

> So this is still a construction site. Fortunately, it will be
> relatively easy to propagate changes of component names to the
> schematics (you can simply edit the .sch files with a text editor),
> and changes in the hierarchy won't affect the schematics at all.
> > about this KiCad M1r4, things to be reviewed/suggested:
> > 1. directions of global labels
> Yes, I see that you already made labels follow the direction of
> the signals. This is an important improvement over the original
> schematics.
> > 2. stupid wrong text, etc.
> Heh :-) Let's not forget component values. I suggest to follow the
> conventions we established for the gta02-core project:
> - the beginning of the discussion thread:
> - the conclusion:
> - the results:
> For example, resistor values would change as follows:
> 4.7K -> 4k7, 49.9 -> 49R9, 220 -> 220R.
> > 3. better look; like part's value and reference orientation, etc.
> Yes ! The original M1 schematics look very crowded at some places,
> which makes them confusing. Parts of the circuit should always
> expose their function clearly. The human brain is good at seeing
> patterns but it's very bad at keeping track of a million details.

Liked you pointed an A3 size for still be probably readable, the four banks
for fpga chip are split. :)

> When a sheet gets too crowded, it's usually better to move part
> of the circuit to a new sheet than to squeeze things into the
> last little corners. The next person who comes along to make a
> change will be thankful for a bit of room.

For Milkymist One schematic, only on Dram.sch I quite didn't realize how to
make a better outlook way to arrange vertical crowed resistors which is a
little against rules I edited in wiki. :)

> There are also simpler details. For example, NORFlash.sch has
> the following formal/visual issues:
> - the ground symbol on pin 32 (A0) overlaps the text "FLASH_A0",
> - FLASH_D15 is not aligned with FLASH_D0 through _D14,
> - TP37 doesn't need a pin number,
> - the wire coming from pin 14 (CE1) shouldn't have a junction
>  marker (fat dot),
> - the text "TP37" is only 30 mil tall, compared to 50-60 mil for
>  most of the other text,
> - the 3V3 on VPEN and BYTE# have much smaller text than the 3V3
>  on R183,
> - I'd also try to avoid having positive rails point downward or
>  ground point upward. E.g., I'd consider connecting pin 31
>  (BYTE#) to pin 15 (VPEN) and remove the 3V3 at BYTE#.
> This is just an example of how a sheet that looks nice and clean
> at a first glance can still be full of surprises.

yes, just cleaned. :)

> Speaking of which, did you notice that all the power symbols
> call their pin "3V3" ? (E.g., click on 1V8 in VideoIn.sch, select
> Pin 1, then it appears in the "Name" field in the status area.)
> This should be easy to fix by editing pwr.lib with a text editor.


> > next step:
> > to create modules(footprints)
> Reviews and cleanup first, please :)

yeah,do you have good idea to generate a good quality pdf  instead of using
KiCad's print ? So this way seems good for reviews without installing KiCad.

> > looking forward to hearing feedback from this and more people can join
> and
> > contribute. :)
> Yes, please ! :-) What needs doing:
> - review of the symbols:
>  - is the symbol understandable ?
>  - are all pins present ?
>  - do they have the correct name ?
>  - do they have the correct number ?
>  - does the pin type correspond to what the data sheet says ?
>  - is text large enough ? (0.050-0.060" for component reference
>    and value(s), 0.050" for pins and other text)
>  - more ?

I still recorded them above in wiki, if more extra-valuable
comments/replies, then add.

>    Regarding pin types, KiCad has "No connection" (NC) and
>    "Unspecified" (Unspec). NC produces an ERC complaint if
>    anything is connected to it at all. Unspec doesn't care what
>    is connected.
>    When a data sheet says "NC", this can mean "no internal
>    connection" or it can mean "do not connect anything here".
>    Sometimes, a data sheet clarifies that, many don't.
>    So we should use "NC" for anything says "do not connect" or
>    that lacks clarification while we should use "Unspec" only
>    if the data sheet says it's okay to connect something.

Good reminder. :)

>    Why make the distinction ? Because it can sometimes be
>    convenient for the layout to be able to route a signal
>    through an NC pin. But that only works if the pin truly isn't
>    connected to anything on the inside of the package.
>    Regarding pin names, we should follow whatever the data sheets
>    use, unless the data sheets are obviously wrong or misleading.
>    (I've seen pins named "ON" that turn something off ...)
>    One issue: what to do with pin names that aren't valid C
>    identifiers ? (*) Particularly inverted signals often have a
>    lot of presentations that are a pain to use in a program: e.g.,
>    nRESET, RESET_N, RESET#, /RESET, or RESET with a line on top.
>    Of these, only nRESET and RESET_N can be directly used in a
>    program.

I picked nRESET style for KiCad m1r4 sch now. :)

>    (*) I pick C here as an example for an identifier syntax shared
>        by most programming languages.
>    Names that aren't identifiers could still be transcribed but
>    this easily results in confusion. Possible remedies:
>    - always use C-friendly names in components,
>    - define transcription rules and hope for the best,
>    - a mix of both, e.g., use a C-friendly convention for inverted
>      signals, leave the rest (FOO+, etc.) to transcription.

With C-friendly names did really save me suffer from some troubles while I
edited m1r4. Like I used it for url link.

>    Note that this doesn't affect alternate pin names. E.g., if we
>    have a pin calles, say, GPIO1/TX/MOSI, then one would normally
>    pick the name corresponding to the respective function or the
>    most generic one, depending on context. So the / aren't part
>    of any identifier.
>  The components/symbols are in
>  "make sch" will bring up the schematics editor configured for
>  editing all the components we have. To edit/examine a component,
>  click on "Library editor" in the top icon bar, then select the
>  library with "Select working library", and the component with
>  "Load component".
>  There is a "catalog" that exposes a bit more information here:
>  Note that some of the symbols are not drawn correctly in the
>  catalog, due to bugs in KiCad's printing subsystem. E.g., in
>  74X1G00_5 the arc is reversed. When in doubt, what the component
>  editor shows is what matters.
> - review of the schematics:
>  - do they show the same circuit as in the original M1r4
>    schematics ?
>  - are the values the same ?
>  - are things free from overlaps ?
>  - is text readable ? (When adding a symbol from the component
>    library to schematics, a copy is made of the fields. So if
>    the text size is/was later changed in the library, this isn't
>    automatically reflected in the schematics and the two may
>    diverge.)
>  - can text be unambiguously associated with components ?
>  - are component references on top or the left of values and/or
>    part numbers ?
>  - are comments/explanations understandable ?
>  - when wires join in a T, is there a junction mark ?
>  - are there no junction marks anywhere else ? In particular,
>    do we only have crossings of the types 2b, 3b, and the right
>    side of 3a, but never 1a or 2a ?
>  - are connections straight and clear ? Here are some style
>    suggestions:
>  - do positive rails point up, ground (and negative rails, but we
>    don't have that in M1) down wherever reasonable ?
>  - do labels point in the direction of the signal ? (This is all
>    wrong in the original M1 schematics.)
>  - more ?

just overall embellished upon above ideas/rules. :-)

>  The schematics live in
>  "make sch" will fire up the schematics editor. Then double-click
>  on the respective sub-sheet.
>  Before too long, we should also have the graphical schematics
>  history back up. That will include an automatically generated
>  PDF of the complete design. That'll be at

Not sure if schhist can apply for m1r4 now.

> I would suggest to start with the components/symbols first, and
> only then proceed to the schematics. That way, we avoid hitting
> the same problems twice.

Although I overall reviewed symbols and modified most for the same size
text and pins style, but still welcome to review them. :)

> If someone reviews a component, please let us know even if you
> don't find any problems. That way, we can keep track of which
> components have been reviewed and which still need attention.
> Note that our components library contains items not only from
> Milkymist but also from other projects. E.g.,
> Unclassified/werner-17042012 has things from ben-wpan and so on.
> So don't be surprised to find strange parts like antennas :-)
yes, if one discovers new problems or comments given.

- adam
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <>

More information about the discussion mailing list