Part 1 of PRM

Happy New Year to you all….

I’m going to have a go at rewriting Part 1 of the PRM (Introduction to RISC OS), and I’m looking for some advice.

Things have obviously moved on quite a bit since the PRMs were written. Are there any elements of Part 1 that I should not include because its either wrong, or simply out-of-date information?

The ARM hardware part looks like a candidate to be snipped, but I thought I’d ask for some guidance from coders amongst you. If you could have a scan through your PRMs and let me know I’d appreciate it.

Nothing specific, just a reminder about:

http://www.riscos.info/index.php/RISC_OS_Documentation

Also, just a suggestion to make an effort with correct grammar/caps conventions and so forth in the online PRMs.

For example:

http://www.riscosopen.org/wiki/documentation/pages/Open_Window_Request/

Should be “A window’s size”, etc, and “pdf” should be “PDF”. elsewhere, etc. Obviously I can fix these myself, but running across such things can be jarring. I know it’s impossible to get it 100% right all the time; perhaps a suggestion for someone to proof read each newly added page. An ideal non-technical job for someone with only a little time on their hands.

Thanks.

After a quick skim through…

• “An introduction to RISC OS” probably needs to mention the HAL somewhere.
• “How RISC OS is supplied” is rather inaccurate, since both RISC OS 5 & 6 are typically supplied as downloads which are then either programmed into flash ROM or soft-loaded (either by RISC OS or an earlier boot loader).
• “The history of RISC OS” – well, good luck with that ;)
• “ARM Hardware” – mentioning VIDC, IOC/IOMD & MEMC is probably important for historical reasons, since there are so many RiscPC-era machines still knocking about. This is probably a good place to go into more detail about the HAL and its aim of removing RISC OS’s dependency on any one manufacturer’s proprietary chips.
• “The ARM processor” – mostly out of date as well. The new version of this section would probably have to deal with all the different variants of ARM architecture that RISC OS supports.
• “The VIDC chip”, “The IOC chip”, “The MEMC chip” – These sections should probably be ignored, or placed in an appendix somewhere, since they’re no longer required in a RISC OS machine. In place of the MEMC section it may be worth including generic information about the MMU (of which there are several versions, of course!)
• Various bits need updating to reflect 26/32bit neutrality issues – “Error handling – an introduction” talks about the PSR bits being in R15, “Technical details” (of SWIs) mentions using MOVS/ORRS to return from the SWI code, etc.
• “Hardware vectors” – The address exception vector isn’t used anymore (although I’m not sure what ARM architecture it was removed in). The reset vector has probably changed in behaviour quite a bit as well. The processor modes that are used won’t be quite as described either (e.g. there’s now an abort mode for handling data aborts)
• “Claiming hardware vectors” – OS_ClaimProcessorVector should be used

With regards to 26/32bit compatability stuff – ROOL would probably be the ones to give you an official answer, but I think it’s safe to say that anything with a 26bit-only CPU (i.e. pre-RiscPC/anything below ARM architecture 3) is now “obsolete”. RISC OS 5 won’t run on the machines, I’m fairly certain RISC OS 4/Select/6 won’t run on them, for several years GCC has defaulted to producing code that’s incompatible with them, etc. So with regards to documentation, all ARM code examples should assume ARMv3 or above (i.e. use MSR/MRS instructions to interact with the PSR), and be 26/32bit neutral. An appendix can be used to go into detail about 26bit-only CPUs/code and the old calling standards.

Also, as recently pointed out in the newsgroups, the whole “Interrupts and handling them” chapter seems to be missing from the PDF PRMs (or at least the version supplied on the tools CD). After checking my printed copy of the manuals I can see that a lot of that chapter is obsolete, as it goes into detail about the IRQ/FIQ device numbers of the Arc-era hardware, and even the IOC register map.

Cheers guys for all your informtion and advice. I’ll certainly take all of it into account when I start the rewrite. Some of the technical stuff I rewrite may well by invalid, due to lack of knowledge on my behalf. e.g. Although I know about PSR no longer being part of R15, I know nothing about MOV/ORRs commands that you mentioned ;(

And the suggestion of proof reading my work, by non-techincal person(s) who may want to help is a very good idea. Although my grammar is not terrible, it’s far from ideal, I and would welcome assistance in this area.

I’ll reply to this post, once I’ve got some documentation available.

In addition, if there are some people who would like to get involved in writing documentation, but perhaps are unsure about using learning how to use the wiki, I am willing to help anyone out. I can also perhaps produce a page showing how simple and straightforward the wiki codes are. If anyone is interested, let me know. I’m lonely ;)

I have put the word out:

http://www.riscos.info/index.php?title=Special:AWCforum&action=st/id122/RISC_OS_Documentation_Proofing_required

Hi Alan: I’d be willing to proof-read pages for you. I’ve no programming/developing expertise, but I did spend over 30 years in the book publishing & printing business, mostly on the production side, so if you’d like me to run a grammatically-aware eye over your stuff let me know.

George: great. Just making people aware that you’re doing it is sufficient. Start here:

http://www.riscosopen.org/wiki/documentation/pages/Programmer%27s+Reference+Manuals

Also, keep an eye on Wiki changes:

http://www.riscosopen.org/content/documents

In many cases, you should just be able to directly correct things without needing permission. In more complex cases you can of course ask here.

George – you might need to co-ordinate a bit because we’ve got Alan entering the documents and you and Gavin Wraith proofing. Can you and he have a chat to make sure you’re not duplicating by checking the same bits? Email me at info@riscosopen.org so I can hook you up.

The online PRMs, even with the limitations of our current Wiki, are very handy from time to time. I forgot to put StrongHelp manuals onto my VRPC-running laptop when I went Up North over Christmas; the Wiki-based SWI documentation was a very useful substitute when I was working on SuperChain.

Thanks for the offer of help George. I’ll be in touch soon, but if you wish to have a look over the introduction, overview and technical details of the Window Manager section that would be marvellous. It has an awful lot of text that needs checking. Take your time, there is no rush.

I’d be happy to do the odd bit of proofreading every now and again. I can’t promise to be the most diligent worker, and unlike George I have no relevant experience (apart from doing a couple of pages for http://www.pgdp.net/ a while ago), but if you give me specific pages or sections I’ll try to do a page or two every now and again.

Hi Rich Sorry for not being in touch sooner, but my internet connection has been down for the past week, and have only managed to get temporary access at my brother’s house today. Many thanks for the offer of help. Delighted to have more help.

I’ve just uploaded quite a few pages at Introduction. I’m halfway through the vectors section, all other sections beyond have yet to be done.

As an aside from proof reading, if I could ask to check that all the links to within a page work. e.g. within the SWI section check the overview, paramaters and results, error handling etc links work

Jeffrey, thanks for the great work on documenting HAL hardware for PRM’s. I’m really quite happy with how the wiki PRM is shaping up.

I was trying to write up the Hardware vectors section last night. I was using the PRM5a for the most up-to-date informtion on it, but am still confused about the pre-veneers. Are they still relevant? It seems that they were used to ensure that the correct processor mode was used, but now that its completely 32-bit, I’m guessing I can safely remove any mention of Pre-veneers?

Anyone with knowledge in this area and feels like sharing, please feel free!

Yeah, the pre-veneer stuff isn’t relevant to RISC OS 5.

If you’re not mentioning the pre-veneers, does that mean that the goal with these PRMs is to only cover RISC OS 5 stuff? I was under the impression that we were aiming for something that would cover RISC OS 3.5+ – or at the least, RISC OS 4+.

Well, yes. But the PRMs, and most of the RISC OS SWIs and other APIs are nominally backward compatible to RISC OS 3.1, so it’s pretty hard to avoid not mentioning old stuff.

In practice, this kind of stuff can be mentioning just in passing to say that it was relevant on old versions of hardware/OS. But certainly we want to focus on at least RO4. The number of people doing non-legacy activities on even 3.7 is very very small.

Thanks for the information.

I’m trying to produce documents that cover RISC OS in general (with the exception of the Select branch) which has nothing to do with ROOL’s branch of code.

I must admit I was intending to remove the pre-veneers informtion as I didn’t think it was relevant to RISC OS, but as you say it did make up part of the RISC OS once-upon-a-time. I’ll keep this in mind for all future documents.

Thanks again for the informtion.

Quickie: are the VDU Codes listed under Tables deliberately omitted for the mo? I’m happy to import the page from the PDFs but am hesitant to interfere with your work, Alan.

Just got my internet access back! I am delieriously happy :-B

I can’t recall any reason why I never uploaded them, so feel free to have a go and upload them. The more people involved in documenting RISC OS, the happier I become.

I’ve opened the PRM PDFs and compared it against the StrongHelp VDU codes. I’m not sure which method of displaying the codes are best. The hieracrhical method (StrongHelp) or simply listing them all in one large table (PRMs). Probably the latter.

Upload and it and see how you get on. Although beware that the StrongHelp version may be more up-to-date than the PRMs.

Imported tables are from the PRM PDFs, rather than StrongHelp. There are a apparent omissions (in a few additional ctrl codes) compared to my printed copy. Will also compare with the StrongHelp version when able to.

Although beware that the StrongHelp version may be more up-to-date than the PRMs.

Alan, I’ve compared with StrongHelp. Some of the info (e.g. VDU 23,2-5) refers to Archimedes pixels, etc. so probably needs amending. I think the inclusion of VDU 23,x,y,etc. in the main table is unsuited to including the further detail shown in StrongHelp. Therefore, perhaps separate pages should be created for some of the commands where the parameters (extra bytes) require detailed explanation and can’t easily fit within the main table. What do you think? Thanks.

The Textile quick reference has been a great help to me. However, the (incomplete) table at the end of Character Sets page doesn’t render in the wiki as it does in the Textile testing/conversion thing I referred to in the Wish lists->Textile tutorial .

Pointers to further advice would be helpful.

Also, I anticipate difficulty with Unicode characters. They don’t all seem to be easily availble under HTML.

If you move the = to before the {} style info then it works (I only worked this out after realising that Alan had already done a style-based table for the register list on the Archimedes Hardware page)

For Unicode characters, it should be possible to specify their decimal code like so: 〹 You can use hex too, if that’s easier: ꯍ There’s a big reference list here, which may be useful.

Also, for the VDU codes – I think it would be best for any code which takes extra parameters to link to a seperate page describing the parameters (apart form VDU 1, which is fairly self-explanatory). That way there’ll be enough space to describe whether coordinates are 0-based or 1-based, whether they’re relative to the screen or the text/graphics window, whether colours are GCOL values or R/G/B, etc.

Thanks for the formatinng advice. I also agree about the VDU codes being more clearly explained via individual pages.