My opinion of the ACPI specification

The following text is a rant that I wrote to let off steam. I believe that the facts stated here are precisely correct, but it is just remotely possible that some of them are portrayed in a slightly more negative light than they deserve. The opinions are of a frustrated programmer who finds himself required by circumstances to deal with the ACPI standard. Take them with a pinch of salt.

A thousand brain-damaged monkeys at a thousand typewriters could hardly have done a worse job. The parts of the specification that are most important tend to be the least clear. The index is worse than useless. Implicit forward declarations are the norm. It is full of implicit reliance upon many other standards and other technical documents. It contains many simply uncompleted fragments of text; footnotes and sentences that just leave off in the middle with little or no idea of where the author was headed. It is also full of editing disasters, mostly of the sort where an editor was changing "foo" into "bar" and ended up with "foo bar" or "bar foo"; these do not prevent comprehension, but they do slow it, and, until you realize that they are everywhere, I (at least) spent a good deal of time trying to construe sentences as they stood. Once I realized that the standard needs a competent editor, I made better speed.

The standard's internal references are often of the form "see the discussion of foo" with no information on what page, chapter, or section the discussion is in, or even whether it is in the ACPI standard or some other standard. In some cases, it is not clear whether references are intended to be internal or external. When section number references exist, they often (usually?) refer to non-existant section numbers. A great deal of the text is repeated in different contexts, usually not edited to fit that context correctly.

Most of the standard appears to have been written as a set of requirement documents for an eventual standard. These parts give themselves away by talking about what "the ACPI standard" should do. My best guess is that the authors ran out of time and realized that their requirements of a standard could be construed at isomorphic to any eventual standard that was written from those requirements, and hacked the requirements documents together to meet a deadline.

This means that to come close to understanding any single feature, you are likely to have to read about it in the ACPI Hardware Specification, the ACPI Software Programming Model, Configuration, Power Management, Processor Control, Waking and Sleeping, etc. ad nauseum. Of course, most features aren't documented in every chapter, but there's no complete reference to all the places where any feature is documented. The index is nearly entirely useless in this regard.

The exceptions to this are, at least, the ASL and AML specifications, which aren't too badly done, except for broken references sometimes, not nearly enough indexing, and an ordering that requires that you already know the structure of the language intimately before you can look anything up. But it's much easier to work with these sections than with the rest of the standard. Unfortunately, AML itself is not the world's best p-code language. To quote Andy Henroid's delicious irony: "Method bodies must be parsed separately as they are not LALR (method calls are just one example of the considerable forethought put into the design of AML)..."

The standard claims to be OS-neutral and CPU-neutral, but it assumes that the OS has a Windows-like architecture in many regards, and it also explicitly relies upon i386 IBM-compatible PC BIOS calls in multiple places.

Despite the fact that it was designed with Windows in mind; it is very clear why it took years for Microsoft to implement ACPI in MS Windows, and it is very clear why hardware vendor implementations are nearly uniformly faulty--the complexity of this standard far out-reaches the need for complexity. The job for which this standard was intended could have been done better by a standard one tenth the size, and that one-tenth-size document could have been more complete.

Now we are stuck with a monstrosity that only promises to be a bigger mess when version 2.0 comes out, because--get this--the authors of the spec refuse to listen even to suggestions unless you sign all sorts of papers to become part of their group. Unless you are a member of the ACPI clique, they are required by their bylaws to ignore what you say. In fact, one of the authors implied when speaking to me that if I said useful things to him, it would put pressure on them to make the spec worse to explicitly not take into account what I said.