Anyone who has worked with OS development, especially beginners like me, has probably encountered problems with documentation. I am not writing this as a complaint or an attack on documentation. I simply want to share some of the frustrations I have experienced while developing my kernel.
When Documentation Does Not Tell You What to Do
I have faced many frustrating situations that had nothing to do with triple faults or similar problems. The real difficulty was figuring out how to implement something using documentation alone, without relying on AI.
That does not mean documentation is useless. Quite the opposite. It is extremely valuable and provides a great deal of help. The problem is that when you do not know what to do, documentation often does not explain the implementation directly.
For example, consider the OSDev Wiki documentation about the PIC:
Each chip (master and slave) has a command port and a data port, as shown in the table below. When no command is issued, the data port allows access to the interrupt mask register of the 8259 PIC.
Chip Purpose I/O Port
Master PIC Command 0x0020
Master PIC Data 0x0021
Slave PIC Command 0x00A0
Slave PIC Data 0x00A1
The documentation also explains that PIC vector offsets must be divisible by 8, that changing them requires reinitializing the PIC, and that the previous configuration must be restored when returning to real mode.
All of that information is useful. However, it does not directly explain what I should actually do to configure the PIC in my kernel.
And before someone says, “It does explain it. You just did not read it properly or skipped the fundamentals.”
No. I read the documentation before going to AI.
Learning Through Implementation
I use AI to teach me and provide instructions when I get stuck. I then implement the concepts myself based on what I learn.
For example, after studying the PIC documentation, I learned how to remap the interrupt vectors and initialize the master and slave PICs.
Here is the actual PIC remapping code from my kernel:
outb(0x20, 0x11);
outb(0xA0, 0x11);
outb(0x21, offset1);
outb(0xA1, offset2);
outb(0x21, 0x04);
outb(0xA1, 0x02);
outb(0x21, 0x01);
outb(0xA1, 0x01);
outb(0x21, 0x00);
outb(0xA1, 0x00);
The point is not that I cannot read documentation. The point is that understanding a technical description and knowing how to turn it into working code are two different skills.
Documentation can tell you what a register does, which ports exist, and what values mean. But when you are still learning, the gap between that information and a working implementation can be enormous.
What I Am Trying to Say
I am not asking for documentation to explain every line of code. That would be unrealistic.
What I am saying is that beginners often need more than a description of the hardware. They need to understand the sequence of operations, why those operations are necessary, and how the different pieces fit together.
That is where I have found AI useful. Not as a replacement for documentation, but as a way to understand what the documentation is trying to tell me.
I still have a lot to learn about OS development, and I am sure I will encounter many more situations like this.
That is all I wanted to share. If anyone has advice on how to study documentation more effectively, especially when working on low-level systems, I would be glad to hear it.
Top comments (2)
The 8259 is the worst offender in that category, and it isn't you reading badly: the datasheet describes the chip, not the initialization protocol. What it never spells out is that ICW1-ICW4 must land as an uninterrupted sequence — any other write in between resets the state machine. So: ICW1 to the command port (0x20/0xA0), then ICW2, ICW3, ICW4 to the data port. The 'divisible by 8' rule exists because ICW2 only carries the high bits — 0x20 gives the master vectors 0x20-0x27, the slave 0x28-0x2F.
Two traps that got me after the sequence was finally right: the slave cascades into the master's IRQ2, so ICW3 has to say so (0x04 master, 0x02 slave), and without an EOI write to 0x20 at the end of the handler you get exactly one interrupt ever — which looks like a broken handler and isn't one. Which source actually clicked for you, osdev wiki or the Intel manual directly?
Thanks for the detailed explanation! I implemented the PIC remapping in my kernel while learning with the help of AI. At the time, I was still trying to understand how the initialization sequence worked.
I intend to read Intel’s documentation directly to get a deeper understanding of the 8259 and its initialization protocol.
Your comment helped me identify some details I need to study further, especially the ICW sequence and EOI handling.