HAL documentation

I may have a go at moving this into the wiki sometime soon.

I’ll start with the simple stuff – copy & paste jobs of the existing HAL docs from Sources/Kernel/Docs/HAL – then move onto creating individual wiki pages to describe each API & individual function, and how well integrated everything is with the OS (and in which versions/machine types). Each page will have a list of references stating where the information was collected from – either stating that the documentation supercedes an existing doc, or for situations where no documentation exists, which source files were used to inferr the behaviour. Eventually we should end up with a much better documented HAL, including a list of all the horribly broken and ill-designed bits. This documentation will be particularly useful as the different branches of the source (main, Cortex, Psion Netbook?) start to expand the HAL in different areas.

Can you mention my fun but convoluted library castle/RiscOS/Sources/Lib/HALLib in your wiki page somewhere? I feel it hasn’t got the recognition it rightly deserves. :)

I didn’t know there were any documents on the HAL, so thank you for posting this :) That may be due to the fact that I can’t seem to open the main source archive (at least, not in Ubuntu), but I will try on my new (Emulated) RISC OS development system soon :)

Run that last one past me again, please. You can’t open the main source archive? Which one? Was this related to the post I answered about the archives at one point being called .tar.bz2 when in fact they were just tar archives?

• What archive are you talking about?
• When did you download it?
• How big is it?
• What command line are you using to extract its contents?

Inquiring minds need to know…

Progress so far…

https://www.riscosopen.org/wiki/documentation/pages/Hardware+Abstraction+Layer

That’s basically a copy & paste job of all the existing source docs, except the specifications for the individual HAL calls, and individual HAL device specifications. The formatting was mostly copied from the great work Alan Robertson’s done on the WIMP/PRM pages – although it looks like there are a few changes I need to make to some of the pages to get the intended effect.

I think I’ve tidied all the broken bits now – if anyone has any suggestions for further formatting improvements then please say so!

I’ve pretty much finished the first pass at the documentation. There’s still more that needs doing (pages for the DMA related HAL devices, and information about HALLib/HALTester), but those will have to wait until I have a bit less programming work to be getting on with!

Of particular note for ROOL is probably the HAL TODO page, which lists what I consider to be all the broken/undocumented/etc. bits of the HAL.