OSDev.org

I have used nearly 7 weeks so far in the single topic of the KBC and Keyboard/Mouse commands and dependencies, trying to gather and document all interesting and practical details. You can see the results here so far (and still far from finished as no mouse or finished usable code is present but only disperse snippets, not very updated very first TOC entry contents, not very much double-checking, HTML not converted to UTF-8, etc.):

http://126.sytes.net/tutorials/KBC_SourceDoc

The question is whether it is a normal or acceptable result/time balance in general terms to attain this amount of results in such time (2 months and counting), when attempting to organize known information into a very detailed document and source code about how to actually use what the data sheets and other tutorials talk about (hardware commands, bit fields, correct command or data sequences, how to send and receive, etc.)?

What things do you consider that could be done to improve this iterative process?

The best thing I have come up with in this effort though, has been that it occurred me making a manual logic highlighting of the code, much more meaningful, instead of the duller syntax highlighting method that doesn't tell anything other than syntax structuration. It is very time consuming, and can be helped notably with a proper rich text editor control in a web page, but it helps me spot any error almost instantaneously with a fraction of the traditional manual code debugging in which one is required to read the code and try to figure out where the bugs are (such as wrong function name called, keep the flow of the code effortlessly, flow of results through variables or where they come from and where they go to, and one of the most important ones: is the result being placed correctly in the result register or variable, normally EAX in x86 assembly?).

In other words, this development time hasn't been limited to just try to document the KBC and peripherals, but to develop some new basic methods for an easier time.

Hi,

~ wrote:I have used nearly 7 weeks so far in the single topic of the KBC and Keyboard/Mouse commands and dependencies, trying to gather and document all interesting and practical details.

Can you break that 7 weeks up into pieces to see where it went?

For example, is that 7 weeks more like:

• 4 days setting up the web server
  3 days finding the relevant information on keyboard/mouse
  1 week writing and testing source code
  1 week writing the actual content for the web pages
  4 weeks fighting with CSS, html/xhtml, javascript and whatever else to get the actual content to look right

Note: I estimated 3 entire days for finding the information, because the information is scattered all over the internet in different datasheets, different web sites, etc, and because of this you'd need to do an "many to many" comparison of the information from each source to figure out what the best pieces of information are.

~ wrote:What things do you consider that could be done to improve this iterative process?

If you could avoid all the web related hassle then it'd be a lot faster as you'd only need to worry about the actual content. For the actual content, if you build on work already done by others (rather than creating all the content from scratch) then you could easily halve the amount of work that takes too.

Therefore, the best thing you could do to improve this iterative process is probably to add information to the OSdev wiki rather than making it harder for yourself to create (while also making it harder for people to find information by adding to the "scattered everywhere" problem I mentioned above). This has the added bonus that you don't need to find subtle ways to advertise your site.


Cheers,

Brendan

• Web server: None (installed in 2006)

• DHTML TOC programming and document templates: None (created in 2003)

• Finding the KBC information: None (but several months accumulated in 2005-2006)

• Reordering the archived information: ~3 days of first week

• Creating and testing DOS COM programs for primary random commands: 1 week

• Starting a draft of the tutorial: the rest of the first week

• Determining/Adding the usage of "basic" KBC/KB/Mouse commands and write it down: 2 weeks

• Starting a written draft of a keyboard driver explanation: 1 week

• Writing some keyboard driver kernel test to print scancodes separately: 1 week

• Enhancing this code to add a circular KB scancode buffer ala BIOS: 1 week

• Documenting and logic highlighting of every function/variable of this raw KB driver (serves as an implicit debugging method also): 2+ weeks

• Creating an HTML remover and other tools to get the source code into a project: this week and counting

As it looks, formally it has taken some more than 7 weeks (8-9 at most currently).

_____________________________________________________
_____________________________________________________
_____________________________________________________
It's not my intention to advertise my site. I don't get personally identifiable credit for that. I don't earn anything out of it (zero advertising just like you) and not enough bandwidth, storage or horsepower for a database/forum/wiki or anything above that. I actually back-link to many other sites with more information, and have back-linked one of your posts about reading the RTC properly in the first Alexei Frounze tutorial I analyzed, to correct and explain a wrong algorithm used there. Plus, all that I write is 100% public domain, so I don't complain about the use it is given. I am just interested in developing more available information and its accompanying source code, and more methodologies whenever possible.

The wiki can be edited by everyone and thus cannot help me as a stable history where I can distinguish what I'm achieving orderly.

I need a scratch pad with more capabilities than the forum and I won't use the OSDev Wiki for that, for I'm still in the incipient process to correct and decipher what exists for a codebase (personally it's currently my best way to reliably know what I'm doing and actually understanding stuff and advancing to something instead of just trying) and it wouldn't be very suitable for the wiki as is. It's more like working locally in my PC, even offline which I very often need, and making it available online for discussion and to know where I'm wrong, right, etc.; everyone can potentially be benefited, which is the point of forums. And also I need a structure different from a plain wiki for more "colorful" or varied formats for presenting stuff, more convenient for ebook-like documents and other variants, as many others here have by publishing their tutorials. I am obligated to present my website then (I have done so almost since I participate in these forums).

As you can see, the massive time it takes me to decipher and come up with correct information, documenting it and making extensively explained code for it (which isn't even near from properly finished yet) leaves me no more time than for just dumping a (partial!) copy of these documents into the wiki. If my method of coloring the HTML text is painful as is, I objectively don't even know how to do just that or how difficult it is in the wiki interface. That's the best my time would allow at the same time I apply the study discipline I require to learn. Further documentation reformatting/copying could be done with the combined effort and cooperation of somebody else. I consider it disgusting to dump copies, but I don't know what you'd think about it, and I wouldn't do that.

I have pointed out some small errors in the wiki as well as dead links in the past anyway, and will continue to do so since I use it and is the most my current situation allows me.

______________________________________________
______________________________________________
______________________________________________
That's what I'm doing right now, and I see your point. I agree about the time consumption involved in web programming, but fortunately for me I already experimented it several years ago and have enough of it to center mostly in OS concepts, hardware, algorithms and such things, so it's not too much of a problem anymore. And it's an useful tool currently. I even keep on programming my test compiler in Javascript/HTML since last year, so it's a necessary part of the cycle. Much easier than programming in C for newly-learned algorithms and fundamental program structuration.

The hardest stage of the process is actually figuring out the hardware behavior in this case without misinterpreting it, and then take the time to describe it, describe the required sequences to program it (which doesn't seem to be found anywhere else or I have been for a very long time ywithout being able to find it). Then, repeat it for every single command (one of the most time consuming things), describe it and double-check it is accurate (justify what I have deciphered against actual runs on hardware, and many combinations, and document any strange problems and actually explain them when the issue is properly reasoned and its cause proven).

BUT, it seems a much faster way to "debug" because in the long run, what would have taken me to correct wrong assumptions along the way are corrected right from the start, because I need to justify what I am saying/writing to myself and see if it is coherent with reality when inspecting the hardware behavior and the effects caused over it.

Then the question would be, do you still face this kind of development times currently at least occasionally, did you face them when you were just starting in OS theory in exchange of a reusable library of useful resources you made, or is it a permanent normal characteristic development cycle time for attempting to thoroughly understand and document the required knowledge cumulatively, progressively, at increasing levels, trying to leave minimal room to assumptions, and actually build runnable source code from it?

Or are there some other methodology tutorials that would help? Admittedly the "Indispensable PC Hardware Book" helped me in actually figuring out to use a circular buffer, and the "Graphics Programming Black Book" could have helped me somehow in bettering a little my programming, with the chapters I have read from it so far.

But is there something else, or am I in an acceptable path of development at this stage?