Hardware description documentation for Glasgow revC3

[gsuberland]

Adds technical documentation for the Glasgow revC3 hardware.

Outstanding tasks:

• Format review (was written in markdown and then converted to rst, so might have some conversion errors)
• Technical correctness review
• TODO item for VIO on hierarchical sheet symbol (search "todo" in document)
• TODO item for SYNC connector usage examples (search "todo" in document)

[attie]

Look great, thanks!

[whitequark]

@gsuberland By the way, if you turn on GH Actions and Pages in your fork, it'll build the docs automatically and you will have a public link you could show for others to see.

[whitequark]

Style question: should we go for "100mA" or "100 mA"? I believe that from a typesetting perspective, the latter is the correct option, and I've tried to consistently stick to it in applets. For example in memory-onfi:

We should choose one option and use it consistently. I do agree in principle that separating the unit, as in "100 mA", feels appropriate to the nature of the format: the value and the unit are separate things. I also acknowledge that in engineering it's very common to glue them together, and there is a certain practicality to it.

[attie]

Separated (e.g: "100 mA") is technically correct, and I'd agree to stick with that.

And it would also be good to fix on capital 'V' for Volts - "5 V" and "500 mV"... (even if "5v" feels more natural to me)

[whitequark]

And it would also be good to fix on capital 'V' for Volts - "5 V" and "500 mV"... (even if "5v" feels more natural to me)

We shouldn't have "5v" anywhere unless I missed some--I will insist on proper capitalization for units since "5v" could as well be "multiply variable v by 5".

[gsuberland]

Regarding the units, saying 5 V, 2 A, 100 Ω, 4.7 uF, etc. feels very weird to me, at least in terms of prioritising readability in documentation.

Since units are technically applied as a product (e.g. 20mA equals "20 multiplied by 10^-3 multiplied by one amp), both in the case of numeric values and compound units, it always felt correct and natural to me to combine them without spacing (or with a • between component SI units for readability, in the case of compound units).

The other downside to spacing them is that word wrap can end up separating the value from its unit.

I'll aquiesce if others have a strong opinion in the other direction, but I personally have a significant preference for no spaces.

Regarding differences between the way units are written in the documentation and applet output, I think it's ok to have an inconsistency if there's a justification for it, and the difference in notation is itself consistent, e.g. if we felt that spaced units read better in the case of terminal output in a likely-monospaced display context, but non-spaced units read better in continuous prose within documentation. I don't have any strong opinion one way or the other on this front though.

[whitequark]

The other downside to spacing them is that word wrap can end up separating the value from its unit.

We can fix this with a post-processing stage that adds  ; it looks like it's fairly easy to bulk post-process the HTML.

[gsuberland]

Additional thought: the docs refer to the power rails by net names (e.g. "the +1.2V rail" meaning the power net with the name +1.2V) so we'd end up using non-spaced measurements there anyway.

[whitequark]

Additional thought: the docs refer to the power rails by net names (e.g. "the +1.2V rail" meaning the power net with the name +1.2V) so we'd end up using non-spaced measurements there anyway.

I think this is an argument in favor of adding spaces in measurements. Here's why:

• +1.2V is then clearly an identifier (of a net, in this case). It is not a measurement on that net, and indeed, you could in principle have 3.3 V on +1.2V. (The iCE40 even survives that, inexplicably. It stops being low power though)
• +1.2 V is a measurement.

Of course there is value in distinguishing these further (we don't really have negative voltages so most measurements would be just 1.2 V, and we also have HTML markup), but I like having this as a baseline.

[gsuberland]

I was about to edit to mention that upside, but you beat me to it :)

Seems like spacing is the way we're going so I'll make the changes.

[whitequark]

Thanks! That definitely makes me feel a lot better about just hitting Merge on this after technical review.

[gsuberland]

Cool, should all be good to go at this point. I've given it a good read through and can't spot any obvious faults at this point.

Do we want to ping any specific folks for a final technical review?

[whitequark]

I think this is all off--AFAICT FX2 doesn't have weak pull-ups. I checked it with glasgow flash --remove-firmware just now, seems to be no current whatsoever

[gsuberland]

Good point, if it's hi-Z then both upper and lower FETs on the IO driver on the FX2 will be off and no current will flow, aside from a tiny leakage.

[whitequark]

Suggested change

	| 101001X [1]_ | U2 | CAT24M01X | 1Mbit flash memory for ICE40 FPGA |
	| 101001X [1]_ | U2 | CAT24M01X | 1 Mbit flash memory for ICE40 FPGA |

Also, it is worth noting that the iCE40HX8K bitstream is about 3 KB bigger than 1 Mbit and so the tail end of it lives in U3, which is horrible but what else would you do?

[gsuberland]

Ooh, funky. Definitely worth mentioning, I can see that coming up in a debugging/repair context. I'll add a note about that.

[whitequark]

Looks great! One last stylistic comment: in ReST documents, we use two blank lines before headings, like this:

Blah blah I am a paragraph.


.. _heading:

Heading
-------

I am next paragraph.

For the location, I propose placing the document into docs/manual/src/revisions/revC3.rst. I'll link it up myself, that seems easier.

[whitequark]

Also, once you are done, can you rebase/squash please, with our standard commit message format? I'll then add one more commit linking up the page from revisions.rst and it's good to go!

[whitequark]

Also I think you'd have to rebase on tip of main either way due to the way our CI works

[whitequark]

Suggested change

	The system LEDs (FX2, ICE, ACT, ERR) are under control of the FX2 firmware, which is responsible for producing the behaviour described above. In the event that the FX2 firmware does not run (e.g. no firmware is present), the LED IO pins default to a high-impedance input state and will either all light dimly or all be off.
	The system LEDs (FX2, ICE, ACT, ERR) are under control of the FX2 firmware, which is responsible for producing the behaviour described above. In the event that the FX2 firmware does not run (e.g. no firmware is present), the LED IO pins default to a high-impedance input state and will all be off.