RFD 552 Transparency in Hardware/Software Interfaces

The broadest and most powerful hardware/software interface is the instruction set architecture (ISA) defining the primitives that the hardware can execute. Instructions are at the heart of the stored-program computer, allowing for software to deliver the Jobsian "bicycle of the mind" whereby the computer can perform tasks its designers didn’t envision. While instructions can be written by hand, it is expected that instructions are generally the output of compilers, which take as their input expression in a higher-level language. This language may be general purpose (e.g., Rust) or domain-specific (e.g., P4). Similarly, the ISA may itself be general purpose (e.g., x86) or more special purpose (e.g., NVIDIA PTX). There is nuance within this: ISAs often have escape hatches that allow for system control functionality — and these hatches can look more like control interfaces (e.g., x86 and its model specific registers).

For hardware whose responsibility is to transit data, there will be data interfaces that define how that data is moved. For such parts, interfaces are often (but certainly not always!) robust. Though just as an ISA can have some elements of a control interface, a data interface can have elements of an ISA where programmability is introduced (e.g., control programs and their logical decendants).

All hardware have control interfaces that are responsible for the mechanics of configuring and operating the hardware. These interfaces are not the thing that the hardware does — that’s usually expressed in its instruction set architecture or its data interfaces — but rather the stuff that must be done to get the hardware to do what it does. Control interfaces are the hardware’s connection to the muck of reality; without them, the hardware is but a warm brick. Despite their essential role, however, these interfaces are often thought of as secondary to the primary function of the hardware; their neglect manifests itself in interfaces that are poorly documented and ill-defined. These control interfaces — which can take disparate forms like register manipulation (PCIe, memory-mapped, etc.) or messaging protocols to otherwise communicate with hardware — may only be documented in functioning code that itself is kept proprietary.

For purposes of this discussion, there are several hardware-adjacent concepts that do not in fact constitute hardware/software interfaces.

The ideal for a hardware/software interface is that it is publicly documented, available without NDA or encumbrance. At one point, this may have been the expectation for all hardware, but as hardware itself became increasingly sophisticated, this expectation has regrettably relaxed.

Example: STMicroelectronics and their microcontrollers and microprocessors. ST’s documentation serves as a model: it is complete, thorough, and (broadly!) correct.

While public documentation is our preference, it is not uncommon is that the interface we seek is be only documented internally, and perhaps then only loosely. This documentation is available upon request, and without encumbrance for the software built on top of it.

Example: Renesas digital phase controllers and their firmware update. Our Renesas regulators (e.g., RAA229618) can be loaded with new firmware payloads, which can be required as part of our own development of a new board. The control interface for this is documented only in internal presentations.

In some cases, there is no private documentation at all (or none that can be made available externally), but there exists an open source HAL that makes use of the interface. While we prefer formal documentation for myriad reasons, source code to a HAL is often sufficient for us to be able to use the necessary interfaces.

Example: AMD and their openSIL project. While openSIL did not make available new documentation, it made available source code that used interfaces that are only described in documentation that isn’t publicly available. While it would certainly be preferable to have these interfaces documented, the presence of the source code embodiment is sufficient to allow for alternative implementations.

In cases where no documentation or source code exists, aspects of a part may have been reverse engineered. Reverse engineering is highly technical and enormously time consuming, and a path that we only take under extenuating circumstances (e.g., our work reverse engineering the LPC55S69 ROM). But where reverse engineering by others has been made publicly available, this can stand in lieu of other documentation.

Example: Lattice Semiconductor is an FPGA maker whose iCE-40 bitstream format was reverse engineeered, allowing an explosion of open source EDA tooling. Despite an initial reaction of fear, Lattice quickly realized that there was much more to gain by enabling an open source community than there was to lose, and the company quickly came to support the community.

The least desirable level of transparency is an interface that is privately documented, but under terms that encumber our use with respect to our own ability to open source our software. Our objective is to open source every component in our stack; it is not acceptable in the long-term to have components for which we cannot make the source code available. We may still build on components, but we will be seeking for the interface to be in Tier 2 (or Tier 1). Where this is impossible, we will likely develop our own HAL (regrettably proprietary) as to not encumber the rest of our stack. We will use this as a lens for component selection and to understand shared values with respect to partnership as outlined in RFD 68.

The most natural argument against transparency is the fear that being transparent about an interface will allow a competitor to mimic a part. From a purely legalistic perspective, this claim is dubious: publicly documenting an interface does not give up any intellectual property rights surrounding it. NVIDIA’s PTX documentation is explicit in this regard:

Legal counter-arguments aside, the argument that transparency will lead to mimicry falls flat for all but the simplest chips, as the interface to a part is valueless without its implementation: even if an interface is greatly revealing as to its architecture, any competitor will be years behind in terms of execution. If it needs to be said, if a company cannot compete with a competitor who only knows how to ape its work, there is likely something much deeper amiss!

So not only does transparency not, in fact, allow a competitor to copy an interface, but any such copy would be years (and many millions of dollars!) away from being a true competitor.

Another common argument is concern that transparency will be a "support burden." This concern can be earnest: software teams within chip makers are often overburdened and on the critical path for next-generation silicon, and one is naturally very cautious about adding to their load. That said, this argument is absurd on its face: making documentation available clearly lowers support burden as it allows technologists to answer their own questions from the documentation. And indeed, for the interfaces that we are practically discussing — namely, very low-level control interfaces — the technologists who are consuming them are themselves experts. Moreover, any support sought for an aspect of the part that appears to be defective will be much better informed: technologists using the chip can use the documentation to very thoroughly do their own homework as to expected behavior before burdening anyone.

In sum: transparency with respect to hardware/software interface in fact reduces support burden.

An argument that was very common against open source in the 1990s and early 2000s was that open source constituted a security risk. These arguments have long since been dismissed among security practitioners as entirely fallacious, but they have apparently endured in the id of some hardware providers. To be clear: to believe that transparency is a security risk is to believe in security through obscurity, a notion that has been thoroughly rejected by security practitioners and standards bodies alike. When this argument is made by providers of silicon with respect to transparency of their own interfaces, it is especially weak and impossible to substantiate. (Indeed, requests for substantation will generally be met with abstract deflection, the details of which cannot be elaborated upon out of — of course! — security concerns.) If a chip maker believes that divulging a hardware/software interface represents a security concern, a crash course in Kerckhoff’s principle is clearly warranted — and the objection to transparency on those grounds should be rejected with extreme prejudice.

Another argument that a chip maker might make is that being transparent about an interface would violate an agreement that they have with a third-party (presumably with an IP provider). This is another argument that stretches credulity, because it assumes both that an IP component has its software interface simply passed through by the part and that an agreement is in place that treats such an interface as encumbered. While it is certainly possible for someone to enter into such an agreement, it would be foolhardy: the chip maker would be giving up their own rights with respect to their own software. But because it’s not impossible, this argument should be explored: with whom is the agreement, exactly — and what does it prevent? Unless the hardware provider is simply doing nothing else but passing IP interfaces (that is, they have no interface of their own), even the presence of such an agreement should allow for an easy compromise: leave only the interface(s) covered by third-party covenant as encumbered, and unencumber the rest of the interface.

Engineers are natural perfectionists: a chip doesn’t tape-out until it’s done — and it doesn’t ship until it works. But perfectionism can be an impediment, especially with respect to making documentation available: a chip is much more likely than documentation to be perfect. On the one hand, this is laudable — it’s great to have high expectations for our own work! — but on the other, documentation is too important to delay for perfectionism. Especially because any documentation is valuable — even if that documentation is autogenerated from RTL (not uncommon). This fear should be addressed directly: engineers should be assured that the audience for their documentation consists of other engineers — incompleteness is not just forgivable but expected.

Similarly, when a HAL layer is present, there may be concern about making the source code available because the software itself may have bugs. As with incomplete documentation, this fear should be assuaged: as anyone who does open source work can attest, having strangers on the Internet finding bugs in your code is a privilege not a punishment. All software is a work in progress, and interfaces should not remain proprietary while code is cleaned up or otherwise polished.

Another unspoken fear is the fear that public availability of an interface may reveal errors: it is not unusual to have the warts of an underlying system reflected in its interface, and this may include chip errata that a vendor does not wish to publicly expose. But this too is a dated concern: chip vendors have become refreshingly public about their errata.