[libre-riscv-dev] API design article "Abstracting Away Correctness"

[Luke Kenneth Casson Leighton]

On Tue, Jul 7, 2020 at 7:20 AM Jacob Lifshay <programmerjake at gmail.com> wrote:
>
> I found a nice article discussing API design in the context of Go and Rust,
> describing using counterexamples from Go's standard library why designing
> using types and interfaces that are impossible to accidentally misuse is
> important.
>
> https://fasterthanli.me/articles/abstracting-away-correctness

"Oh no. That's one situation where "there's options" is definitely a bad thing."

i've made it really clear over a number of years now, learning from
designing EOMA68 and also from the simple example that my lecturer at
Imperial College taught me (the X.25 interface), you absolutely cannot
have "options" in a standard.  and an API is also a standard.

X.25 had - has - a way to do "escape-sequences" in hardware.  you
raise a control line (either way) to say that the data being sent was
now "control information" rather than "data".

however it was sometimes the case that either of those TX/RX control
lines broke (X.25 was designed for long-distance transmission - the
JANET network used it) or it was just more convenient, so it was
allowed to have *software* escape-sequences, exactly as is seen in
RIL-GSM "framing", today.

the fact that you *never knew* if the other end had the capability to
support hardware-control lines meant that you *HAD* to support
software-control escape-sequencing...

... making it completely and utterly pointless to even have the
hardware-control lines.

and that in turn meant that on the 9-pin X.25 interface, *four* pins
were completely and utterly wasted (TX-CTL on both ends, RX-CTL on
both ends).

that in turn meant that, given that X.25 was a synchronous design
(where RS232 is isochronous), you had to have a USD $15 *external
clock plus power supply* rather than a $1 cable in the case of RS232.

if they had thought through the implications of "optional hardware,
optional software" properly, right at the design phase, those two
redundant pins could have been used instead for TX-CLK and RX-CLK *in
both directions*, and X.25 would have had a future as an interface
similar to RS232, except much much faster.

this example deeply ingrained for me the care and attention to detail
that is needed for APIs and standards.  interestingly, the POWER
architecture standard violates these criteria in several places.

l.