# IA32-doc turns the Intel manual into YAML you can generate a header from

> IA32-doc is a Python project that transcribes Intel SDM definitions into machine-processable YAML and generates a C header from them. It is aimed at people writing hobby operating systems, hypervisors and register-level experiments, and its own README is unusually blunt about the errors and gaps in the transcription.

**ia32-doc/ia32-doc** — IA32-doc is a project which aims to put as many definitions from the Intel Manual into machine-processable format as possible

- Repository: https://github.com/ia32-doc/ia32-doc
- Stars: 715 · Forks: 97
- Language: C
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/ia32-doc-ia32-doc

## Why definitions get transcribed instead of copied from a kernel

The premise of IA32-doc is that the definitions you'd want when writing low-level x86 code are scattered and unevenly documented. The README argues that you can cherry-pick them from the Linux kernel source, from ReactOS, from the VirtualBox source or from EDK-II, but the set you end up with is limited and often poorly documented as a side effect.

The alternative is to transcribe the Intel documentation itself into a structured format. The source is stated plainly: the Intel 64 and IA-32 architectures software developer's manual, combined volumes 1, 2A, 2B, 2C, 2D, 3A, 3B, 3C, 3D and 4, in the May 2018 edition. Names and descriptions were also inspired by VirtualBox and TianoCore, which is where some of the wording conventions come from.

That date matters more than it first appears. The transcription reflects a 2018 edition of the manual, and the README explicitly says not to expect the maintainer to keep pace with each new release of the manual. A definition that changed after 2018 is a definition this project will not know about.

## YAML in, one C header out

The pipeline is small enough to describe in full. The definitions live as YAML files under the yaml/Intel directory, a configuration file selects how values are rendered, and a Python entry point reads one index and writes an output file. The README points at out/ia32.h as the thing this project is good for.

The interesting part is that the YAML is not just a data dump. It carries structure that a generator can act on. There is a template file, yaml/template.yml, that defines the expected format, and there is a configuration file, conf/default.yml, that holds values such as int_type_* settings, which control how integer types are named in the output. The output side is a class, DocCProcessor in ia32doc/processors/c_processor.py, and the README says that adding a generator for another language, Rust for instance, means deriving the DocProcessor class in ia32doc/processors/base.py.

So the architecture is a format plus a plugin point. The C generator is the one that ships, and the extension path is documented at the class level rather than left implicit.

## Running the generator on the Intel index

The whole tool is invoked with one command. The README gives the invocation with a configuration file and an index file:

```bash
$ python3 main.py -c conf/default.yml -f yaml/Intel/index.yml
```

The only dependency is PyYAML, and the README states that Python 3.7 or newer is needed. The repository ships a requirements.txt listing PyYAML and nothing else, so a virtual environment with that single package is enough. There is no build step to run, no compiler to install and no configuration to write before the first run.

What you should see after the run is the generated header in out/. The out directory is part of the repository layout, which means you can inspect a generated header before running anything at all, and use it as a reference for what the YAML actually turns into.

## What is actually transcribed: registers, MSRs, CPUID, paging and VMX

The README lists the transcribed areas, and the list is the best guide to the project's real coverage. Control registers are there (CR0, CR3, CR4, CR8), along with CPUID definitions for every EAX and ECX function found in the manual at the time, model specific registers, and paging structures for both 32-bit and 64-bit modes (PML4E, PDPTE, PDE, PTE). Segment descriptors for the GDT, LDT, IDT and TSS are included, along with VMX related definitions such as EPT and VMCS, the APIC, EFLAGS, and the memory types UC, WC, WT, WP and WB.

Two things stand out. First, the coverage is concentrated on the areas a hobby OS or hypervisor touches first, which is consistent with the stated purpose. Second, some of the entries are flat definitions while others are structures with subfields, and the TODO list includes an item to fix 32/64 bitfields for MSR registers and another to let a bitfield carry both UINT32 and UINT64 members. That means MSR bitfield handling is acknowledged as unfinished, not merely untested.

## Only C output, and only the names the config file allows

The FAQ is direct about output formats: no, no output other than a C header is available. The author's reasoning is that extending the Python code to generate another language should not be hard, which is a statement about the code rather than a promise of a branch or a pull request. Anyone who needs Rust or another language is expected to write the processor themselves.

Naming is configurable within a narrow axis. If the UINT-style names or the CamelCase style or the Doxygen comments do not suit you, the README says to change the int_type_* values in conf/default.yml for the integer naming, to modify the DocCProcessor class for anything about the output file itself, and to derive DocProcessor from ia32doc/processors/base.py to add a new output language.

The TODO list adds two structural limits worth knowing before you invest effort: the possibility of splitting the output into multiple .h files is still marked as an open idea, and a Doxygen main page has not been added. One header file is what you get, which is convenient for small projects and awkward for large ones.

## The README tells you to distrust its own output

The notes section is the most unusual part of the documentation. It says you should always consult the Intel manual anyway, unconditionally, and that once you get past hello world and decide to write an operating system or hypervisor there is no way you will succeed without reading it.

It also warns that there may be errors, typos and copy-paste errors in the YAML transcriptions, and that a lot is missing, since the author mainly transcribed what they personally needed. The FAQ on maintenance is blunter still: nobody is going to maintain it, maybe a miracle happens and someone forks the repo, and the author may add whatever they are interested in at any moment.

For an evaluation, that framing is the specification. This is a personal transcription with an open-ended TODO list, released under the MIT licence, with the last push to the main branch on 2026-07-06 and no GitHub releases at all. It is a reference and a starting point, and the documentation tells you to treat it that way.

## Conclusion

IA32-doc is worth adopting as a starting reference for hobby OS and hypervisor work, especially when you need register, MSR, CPUID and EPT definitions in a form a script can transform, and its YAML is easy to extend with new entries. It is the wrong tool for a production kernel or a firmware project that needs audited, citation-backed definitions, because the transcription may contain typos and the maintainer states nobody is maintaining it. Before you depend on it, check the generated out/ia32.h against the Intel manual for the registers you actually use, decide whether the single-file output and the missing 32/64 bitfield handling for MSR registers matter to you, and treat the absence of a fix for 32/64 bitfields in the TODO list as a known boundary rather than a bug to file.

## FAQ

### How do I run IA32-doc to generate the C header?

Run python3 main.py -c conf/default.yml -f yaml/Intel/index.yml from the repository root. The result is written as a C header in the out directory, where out/ia32.h is the file the README points to.

### What does IA32-doc need in terms of Python packages?

Only PyYAML, with Python 3.7 or newer. The repository ships a requirements.txt containing PyYAML and nothing else.

### Which CPU definitions does IA32-doc cover?

The transcribed set covers control registers CR0, CR3, CR4 and CR8, CPUID functions, model specific registers, paging structures for 32 and 64 bit modes, segment descriptors, VMX definitions such as EPT and VMCS, the APIC, EFLAGS and the memory types UC, WC, WT, WP and WB. AMD-specific definitions are not included.

### Can IA32-doc generate output in a language other than C?

Not out of the box, since only a C header is available. The README says extending the Python code to other languages should not be hard, and that a new yaml document processor is created by deriving the DocProcessor class in ia32doc/processors/base.py.

### How do I change the integer type names in the generated header?

The int_type_* values in conf/default.yml control how integers are named in the output. Anything about the output file itself is changed in the DocCProcessor class in ia32doc/processors/c_processor.py, and yaml/template.yml shows the expected format for new definitions.

## Sources

- [ia32-doc/ia32-doc on GitHub](https://github.com/ia32-doc/ia32-doc)
- [Issues](https://github.com/ia32-doc/ia32-doc/issues)
- [License: MIT](https://github.com/ia32-doc/ia32-doc/blob/main/LICENSE)
- [README](https://github.com/ia32-doc/ia32-doc/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ia32-doc-ia32-doc