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.
