RKRM - AmigaDOS work in progress

[Thomas Richter]

Originally Posted by jman

How can I submit this patch? I mean, if you prefer you can also apply it yourself, it's attached here.

Thanks, that is the preferred way - or probably better, apply the patch to an issue report at gitlab, this way I can keep track of all the issues.


It's probably a litttle bit premature to look at typos at this time because I first want to complete the content, and then go through it all again (grammar is horrible in some places), fix up references and inconsistencies of typesetting, fixup the (in some places) terrible layout. The spell-checking is then probably the least problem - but nevertheless, your work is really appreciated (it's long enough already, indeed).


Greetings,
Thomas

[tomse]

Thank you very much!!


It's great to se old and new improvements are made (like the RKRM for OS3.2)

[Thomas Richter]

Originally Posted by mr.spiv

Having done just a quick overall look I would suggest adding a table somewhere in the intro that would have mapping between kickstarts (1.x, 2.x etc) to these v3x & v4x versions. Just for lazy people like me to have all essentials in one document

You mean you want to have an indication in which version a particular function appeared? That is a good idea - could you please open an issue on this on gitlab? If not, I have likely forgotten to do so for the second round.


Thanks,
Thomas

[copse]

Originally Posted by Thomas Richter

You mean you want to have an indication in which version a particular function appeared? That is a good idea - could you please open an issue on this on gitlab? If not, I have likely forgotten to do so for the second round.

This is a great idea. It's very valuable in for instance the Python documentation to be able to see what version of Python a feature appeared in.

[Thomas Richter]

Another milestone has reached with this project - a documentation of AmigaDOS, replacing the aged Bantam manual and the unavailable Guru book:

https://github.com/thorfdbg/rkrm-dos

This time, I included lots of information on the system handlers, mostly the console, the port handler ,the queue-handler and the FFS. Highlights are the new console mode that allows TAB expansion and the disk structure of the FFS.

The new console mode ("medium mode") is a new mode that came to the system with 3.2 and is a middle-way between the line editing "cooked mode" ("well done" mode) and the "raw mode". What "medium" does is that it sends for some keystrokes the complete line and the cursor position through a CSI sequence to its client which then performs TAB expansion or history editing. This is already documented in the ViNCEd guide, but as it became part of the Os, it is now documented there.

Another highlight is the documentation of the FFS block structure. What is documented here probably for the first time is the structure of the FFS directory cache, and the new FFS variants, namely the long filename variant which adds another block type and modifies the "T.SHORT" type, and the "compatible long file name" mode FFS\08 which extends some fields to offer 54 character long file names. It's quite hard to find documentation for these FFS flavours elsewhere.

The next bigger (and probably last) chapter is the AmigaDOS shell.

[kamelito]

Maybe you could add quotes from the Amiga team like it is done in the guru book it add history.

[tygre]

Thanks Thomas!

Cheers!

[Olaf Barthel]

Originally Posted by Thomas Richter

Another milestone has reached with this project - a documentation of AmigaDOS, replacing the aged Bantam manual and the unavailable Guru book:

https://github.com/thorfdbg/rkrm-dos

This time, I included lots of information on the system handlers, mostly the console, the port handler ,the queue-handler and the FFS. Highlights are the new console mode that allows TAB expansion and the disk structure of the FFS.

The new console mode ("medium mode") is a new mode that came to the system with 3.2 and is a middle-way between the line editing "cooked mode" ("well done" mode) and the "raw mode". What "medium" does is that it sends for some keystrokes the complete line and the cursor position through a CSI sequence to its client which then performs TAB expansion or history editing. This is already documented in the ViNCEd guide, but as it became part of the Os, it is now documented there.

Another highlight is the documentation of the FFS block structure. What is documented here probably for the first time is the structure of the FFS directory cache, and the new FFS variants, namely the long filename variant which adds another block type and modifies the "T.SHORT" type, and the "compatible long file name" mode FFS\08 which extends some fields to offer 54 character long file names. It's quite hard to find documentation for these FFS flavours elsewhere.

That's why I "hacked" the Wikipedia entry for the Amiga FastFileSystem to link to https://wiki.amigaos.net/wiki/DCFS_a...ata_Structures

That was back in 2017 and what is documented there should still be correct. The DCFS details were hard to come by but should be correct as is. This goes particularly for the missing "garbage collection" of partly filled directory list blocks.

What I did not cover was what you might find after the last entry of a directory list block. The original idea was to store deleted entries behind it, in case you needed to recover damaged/deleted files in the future. As far as I can tell, this feature was never implemented.

I just remembered something which is currently, as far as I can tell, not documented for the OFS/FFS root block. The root block contains a "Volume last altered date and time" DateStamp. That's all there is by way of documentation in all three AmigaDOS manuals: just the name. This DateStamp is not updated whenever the volume is changed. It is only changed if one condition is true: the bitmap was modified and needs to be written back to the disk. Typically, when the root directory is block is written back with the "bitmap is valid flag" set to DOSTRUE, then the "Volume last altered date and time" DateStamp will be updated, too.

The next bigger (and probably last) chapter is the AmigaDOS shell.

Ain't that the truth. It's a marvel to see how small the original CLI used to be in Kickstart 1.0-1.3 and how the shell we use today evolved alongsid the con-handler.

[Thomas Richter]

And here we go, I reached the next milestone of the AmigaDOS documentation project at:

https://github.com/thorfdbg/rkrm-dos

At this point, the first iteration of the text should be complete, and it covers everything I considered I had to put into. The highlight of this edition is the shell chapter and how to write a custom shell. The shell startup mechanism can be best described as "bizarre", but it got better with version 3.2 as two legacy protocols could be removed. A discussion of the dos.library base and its structures completes this work.
Thus, this is essentially the "Shell.guide" and the ShellInternals you found on Aminet already, just in a condensed way and only the official parts of it.

At this time, I'm asking whether there are any particular topics you believe are missing, or whether you already found known defects. If so, please report this as an issue on github. I would prefer to have it centrally available there as it is otherwise hard to track.

[admiral]

Originally Posted by Thomas Richter

At this time, I'm asking whether there are any particular topics you believe are missing, or whether you already found known defects. If so, please report this as an issue on github. I would prefer to have it centrally available there as it is otherwise hard to track.

Perhaps more on the startup process. e.g.: how does doslib know where to boot from? How does this change across versions?

[Minuous]

There doesn't seem to be any margin between the footer and the bottom of each page.

[Thomas Richter]

Originally Posted by admiral

Perhaps more on the startup process. e.g.: how does doslib know where to boot from? How does this change across versions?

The decision on the boot process is actually made much earlier, namely by the strap module. At the time the dos.library is starting, the boot volume is already set. The strap module is described in the RKRM devices volume. However, what I could do is to describe the system-startup. As I'm currently in the second iteration through the book, I would not be able to write it immediately, but please open up a defect report on the git page so I won't forget.

[Thomas Richter]

Folks,

the next mile stone of this book project has been reached and can be found at its repository: https://github.com/thorfdbg/rkrm-dos

This milestone finished the second iteration through the material and fixed many many defects and technical inaccuracies, and I also cross-checked with the available literature. Thus, hopefully, the quality should have improved significantly.

For those of you that provided feedback already or made issue reports on github, I'm sorry that I haven't had the time to respond yet and include them in the work. This will be part of the third iteration, which will start soon.

What is new in this iteration is a description of the boot block, and the boot procedure (as far as AmigaDOS is concerned), after all, System-Startup is a new module and I do not want to hide in any way what it does. Hightlights in this edition are probably the source code of a mini-handler - that's probably a skeleton code for own experiments, and a similar source code of a very primitive shell which should hopefully demystify the internals of the shell startup mechanism. Even though this was significantly simplified in 3.2, it still looks a bit like black art.

Thus, again, sorry to let you wait, but now for the third iteration I will spend time on reader feedback. Thus, please grab a copy and report technical inaccuracies and I'll work on them. It is still too early for spell-checking, that will be the very last step before releasing the project.

[jman]

Thank you Thomas for continuing this work!


I opened a ticket on github about adding a clickable table of contents. Just a small suggestion for the final stage of refinements.

I also want to mention that this work should deserve recognition. In case you want to open a funding channel to allow people throw a bit of money at you, I'll be happy to contribute a small donation.

[hooverphonique]

@Thor Do you document how all those things you mention work for all major kickstart releases (e.g. 1.3,2.0,3.0,3.2), or just 3.2?

[Thomas Richter]

Originally Posted by hooverphonique

@Thor Do you document how all those things you mention work for all major kickstart releases (e.g. 1.3,2.0,3.0), or just 3.2?

This is mostly for 3.2, though I document which functions and features became available in which AmigaDOS version. For example, if I would have to document version 33, I would need to document how the global vector works and how it is populated - but this stuff is all obsolete, and I really do not want to waste my time with this legacy cruft you should not depend upon anyhow.

[Olaf Barthel]

Originally Posted by Thomas Richter

This is mostly for 3.2, though I document which functions and features became available in which AmigaDOS version. For example, if I would have to document version 33, I would need to document how the global vector works and how it is populated - but this stuff is all obsolete, and I really do not want to waste my time with this legacy cruft you should not depend upon anyhow.

You know, it does not have to be covered in the kind of detail which would be likely to lure the curious developers into giving the TRIPOS API layer a shot, and getting swallowed up by the darkness.

dos.library being such a strange beast, at least some light shed on why the fusion of an exec shared library with parts of the TRIPOS kernel, file systems and shell made sense would be helpful. What justified this approach, what doomed this approach? Is there a middle ground or is everything just sliding along the edge of a very sharp razor blade? What traps and pitfalls tumbled out of this design which, at the end of the day, made it possible for the Amiga to ship in 1986?

[Thomas Richter]

Frankly, I'm not sure whether this is the right book to answer such types of questions. After all, this book is supposed to be a practical manual to give developers a hand on how to use the AmigaDOS library (and probably the AmigaDOS developers some valuable information where to check for bugs - hint, hint...), in particular in areas that are not very well covered in the original Tripos - pardon me - AmigaDOS manual. Such as "how do I write a handler" "how do I write a shell"?

Even more so, I'm not even sure whether I would be the right author for the topics you mention as I lack the historic background and thus qualification. That would probably something for Dr. Tim King (and not for Dr. Thomas Richter), if he had any interest.

I would rather hope that dos.library becomes a regular library at some point. Such as "yes, you really must load a6 with the library basis" and "yes, the global vector is really gone now and we can retire support for it". That would be more my party time. (Well noted that OsGrind already checks for these kind of violations - failing to load a6 properly, or attempting to use the GV).

[kamelito]

Regular API for 3.4 isn’t it already the case for 4.1?

[hooverphonique]

Originally Posted by Thomas Richter

Frankly, I'm not sure whether this is the right book to answer such types of questions.

I agree.. Not that it isn't an interesting topic, but that story isn't really for a reference manual.. well, unless you use it as a preface or something.