HACKER Q&A
📣 linguae

Are There Any Fully-Documented Computers


I am writing an operating system as a side project. I am still in the design phase of the project, and I’ve been brushing up on my low-level programming skills. Recently there was a discussion here about the Asahi Linux team’s efforts reverse-engineering ARM Macs, and it had me thinking: are there any fully-documented modern computers? I know that RISC-V and POWER are open source. However, there are still other parts of a computer system to consider, such as boot firmware, buses, disk controllers, GPUs, networking devices, USB, etc. It would be cool to target fully-documented hardware for my OS project, but I don’t know if there are any complete stacks of fully-documented hardware.

  👤 johndoe0815 Accepted Answer ✓
Most popular modern SoCs are not fully documented - one part that usually lacks any documentation is the GPU. For most ARM-based SoCs, it's either one of ARM's Mali series or an Imagination Technologies product, most RISC-V based SoCs (e.g. the JH7110) also use Imagination Technologies GPUs.

Additional components also have documentation that's hard to find, especially those based on Synopsys' DesignWare IP. These are sometimes at least... strange (or should I say buggy?) effects such as with their "standard" 16550-compatible UART: https://lupyuen.github.io/articles/plic

The Vivante GPU in Freescale's i.MX8 SoCs was reverse engineered and is probably the closest you can find to a somewhat documented GPU (STM32MP SoCs also have a Vivante GPU). In general, the i.MX8 is well documented - one of the reasons why it is used in Purism's Librem 5 phone.

You can "cheat" and improve the GPU situation a bit by using a RISC-V board with a PCIe slot and an old AMD GPU.

When there's no documentation available, all you can do is reverse engineer the functionality of existing open source drivers. Linux drivers are often quite complex, I recommend looking at Net/OpenBSD and Plan9 drivers instead. For some RISC-V SoCs (SiFive Freedom U740 on the Unmatched board and JH7110), Haiku is also worth looking at.

An alternative which provides documented hardware is to use an FPGA-based SoC builder, e.g. LiteX: https://github.com/enjoy-digital/litex

Of course, this results in a significant degradation of performance...

Another option would be to use a regular x86-based PC and rely on the documented interfaces, such as VESA graphics, but then you have to deal with x86 and all the baggage of almost 45 years of PC evolution...

👤 thesuperbigfrog
There are some fully-documented computers that are intended for teaching:

https://en.wikipedia.org/wiki/Little_Computer_3

https://en.wikipedia.org/wiki/MMIX

I am not sure if there are any hardware implementations of these computers though.

👤 kjs3
There are some vintage computers that are meticulously documents (e.g. DEC VAX), and probably up to the i386 era you could completely understand your computer, but the trend for the last decade or two has strongly been to not completely document things. Worst are the modern SoCs, which are seemingly built of opaque black boxes tacked together.
👤 petabyt
Texas Instruments AM62 is pretty well documented I think. I've been doing RK3399 and RK3588 bring up for a year now and the lack of documentation sucks.
👤 znpy
The mnt reform should be close to what you’re looking for, i think.