Request for community help - 32 bit documentation

Hi. We (I) often bang on about how over-worked all the ROOL volunteers are and a common response is that we should get more people to help with stuff we need to get done. So here’s your opportunity to prove this great time-saving scheme by jumping at the chance to do a bit of highly exciting ROOL work… :)

One of the jobs on the ROOL ToDo list that looks like a good candidate for handing-out to a knowledgeable and enthusiastic volunteer in the community is to update our website to host a pile of important 32 bit documentation that is currently only found on the www.iyonix.com web site.

All of this documentation is rather lost in its current location. It’s also grown rather crusty and misleading so needs quite a bit of updating, including pointing people at the correct locations for downloads, etc.

What we need is for someone to grab all this stuff (we have a tarball of it) and update it to bring it into the present day, then hand it to ROOL in a format that will be as straightforward as possible to integrate into our website (TBD). We can then arrange to have the iyonix.com site redirect to RISC OS Open.

Note: we’re not after updating all of the technical documentation; that’d take a long time; all we’re looking for is the main over-arching wording to be current and correct, for everything to be linking to valid locations and for all the pages to be migrated into the ROOL site style.

One suggestion for where all this could go is: somewhere in our wiki. That’d save any requirement for handing stuff over to ROOL and us having to do lots of messing about sorting out formatting and styles.

Please get in touch on this thread if you’re interested in taking this on…

Sticking it directly into the wiki would be good, especially as it already hosts some related documentation (e.g. the ARMv7 compatibility primer)

I’d be interested in looking at this. I’ve done a bit of work on the PRMs section of the wiki. In fact, while working on updating Chars, I already added the UCS Font Manager spec, which you can take a look at here:

https://www.riscosopen.org/wiki/documentation/show/UCS%20Font%20Manager

Is this the kind of thing you had in mind?

Yeah – something along those lines. The best first step would probably be to review what’s currently on the 32 bit site and post here with a proposal of (broadly) how you’d like to (re)structure it and how it’d be linked to from the top of the wiki. If that all looks like a goer, then I see no reason not to just get cracking…

Incidentally, to grab the current stuff, I just did:

wget -v -r -L -np -k -l inf http://www.iyonix.com/32bit/32bit.shtml

which amounted to less than 3MiB of stuff…

The page linked says you should do this to detect 32 bit mode:

    TEQ R0, R0    ; Set Z flag
    TEQ PC, PC    ; Set Z flag if in 32-bit mode

Why not just use:

    CMP PC, PC    ; Is EQ if in 32-bit mode

To compare PC with PC (EQ=32 bit) or PC with PC+PSR (NE=26 bit).

On a 26bit system, in user mode, with NZCVIF flags clear, the PSR flags will all be zero. Which means that TEQ PC,PC (or CMP PC,PC) will return EQ. Inserting a TEQ R0,R0 works around that by guaranteeing that at least one of the PSR flags is non-zero by the time the second TEQ is reached.

If you’re not in user mode (or can guarantee that at least one of the NZCVIF flags are set) then the TEQ R0,R0 isn’t needed and can safely be omitted.

CMP PC, PC ; Is EQ if in 32-bit mode

You mean as in creating a simple (bit naff) 26/32 exit:

   CMP PC, PC              ; Is EQ if in 32-bit mode

   LDMEQFD R13!,{PC}	   ; exit here if 32 bit

   LDMFD   R13!,{PC}^	   ; original 26 bit exit

OK, the LDM is not good on single registers and if you really did want the flags you’re a bit stuffed.

You mean as in creating a simple (bit naff) 26/32 exit

Yes, that’s one use for the code. Another common use is for determining whether you should use TEQP or MSR/MRS for changing processor mode, e.g. as in the example given here.

Another common use is for determining whether you should use TEQP or MSR/MRS for changing processor mode, e.g. as in the example given here.

That stuff was what prompted me to add the first two lines of my extract on the code I’m corrupting¹. I’m fascinated that so far what I’ve done seems to work.

¹ I reasoned that a simple test for 32 bit and bail out via 32 bit code if positive and fall through to the original if not (i.e. 26 bit) was a quick hack.

somewhere in our wiki

If the wiki may still be (slightly) broken ¹ then will website content be periodically archived just in case? It’d be a shame for someone to update and add markup/links etc. if the content itself risks being lost.

¹ Or if not, then maybe that one can be closed!

I’ll let Andrew answer about the wiki and backup situation.

Are there any takers for this one?

Are there any takers for this one?

What is the copyright situation of that documentation? It shouldn’t be too hard if it is mostly a cut’n’paste with some tweaks/updates along the way (ought to mention the unaligned loads issue if this hasn’t been covered); the “hard part” in that case will be bashing Textile into submission.
If, on the other hand, it has to be completely rewritten…that’s a slightly bigger issue.

OK, the LDM is not good on single registers and if you really did want the flags you’re a bit stuffed.

Stuffed? Not really.
You load the flags into the SPSR then use our old friend MOVS PC,R14 which will send a coded message to the processor to also copy across the flags stored in SPSR into CPSR on exit.
Obviously this implies being in a privileged mode (else no SPSR).

You load the flags into the SPSR then use our old friend MOVS PC,R14

32 bit? http://www.iyonix.com/32bit/32bitTech.shtml scroll down to the PSR manipulations heading and look at the para above the para above:

Many existing APIs do not actually require flag preservation, such as service call entries. In this case, simply changing MOVS PC… to MOV PC… and LDM {}^ to LDM {} is sufficient to achieve 32-bit compatibility.

Indeed. For preserving flags is a bit PITA, so it was better/simpler to specify them as not needing to be preserved.

I was responding to your comment re. if you really did want the flags you’re a bit stuffed – as there may be times when you need to restore the exact processor state (think of intercepting various events – you can’t arbitrarily modify the flags on some of them).

However, as you rightly point out, just doing away with the preservation will work for a huge majority of conversions. Preserving flags in a 32 bit world is a more special-case thing these days.

However, as you rightly point out, just doing away with the preservation will work for a huge majority of conversions. Preserving flags in a 32 bit world is a more special-case thing these days.

It was more the point that you replied with a suggestion that if you wanted to keep the flags you could use MOVS PC,R14 which is the very non-32bit safe instruction you were probably trying to avoid. In a few cases the flags are important, but MOVS isn’t the solution.

To be honest¹ what I’d like to see is documentation that points people at the use of a set of macros where you replace a small item with a macro name and let the DDE sort out what code gets inserted.² Although that does remove the “fun” of figuring out ARM assembler while rebuilding something with 26 bit dependencies.
Specific instances of required flag preservation need highlighting in the documentation, probably with an example of a typical substitution (with a macro?)

¹ Strange phrase, it rather implies that the speaker is normally dishonest

² Some might note that ARMC does a decent job of identifying many required assembler source code file changes

In a few cases the flags are important, but MOVS isn’t the solution.

It isn’t? I suspect we are talking cross-purpose here. This sort of stuff is not user mode level code. For that, there isn’t a lot of flag preservation needed. :-)
http://infocenter.arm.com/help/topic/com.arm.doc.ddi0344b/ch02s15s08.html

Specific instances of required flag preservation need highlighting in the documentation

Much of these? https://www.riscosopen.org/wiki/documentation/show/Software%20Vector%20Numbers

It isn’t? I suspect we are talking cross-purpose here.

Possibly. I thought R14 and R14_svc were different. Some sort of reference to private registers for each mode IIRC

Could be wrong, trying to learn and remember while doing two jobs, latterly training a newbie.

I thought R14 and R14_svc were different.

That’s right. The different modes generally have a private stack (R13) and return address (R14), plus a few more (R8+) for FIQ mode.

However, you don’t access these registers by different name, you access them by virtue of the mode you are in. If you are in IRQ mode, you will stack stuff at R13 as normal, but it’ll be R13_irq because it is the one appropriate for the mode.
[it is possible to access user mode registers in a privileged mode, but not vice versa]

You have my sympathies re. The Newbie. At work, since I’m the floater that often covers the “washing up” (in an industrial sense), I can say that there are only ever two types of Newbie. The first is a gung-ho capable type that doesn’t quite know what is happening but is willing to give it a go and doesn’t mind getting soaked many times over – so far in five years I’ve met exactly two girls like that.
The second type, and the majority by several depressing orders of magnitude, are the people so ****ing stupid you actually wonder how they survived being born. I mean, “take the stuff out of the big machine, rinse it off, put it into this big basket”, it is hardly a difficult instruction¹. Yet, I checked up on a girl to see she was just taking stuff and tossing it “in the direction of” the basket.
I could tell you some real Newbies-should-be-shot-on-sight stories, but many of them are traumatic incidents that I am actively trying to forget. Suffice to say I have actually told somebody that they are so awful I would rather struggle through things alone. That is big, me having an opinion² and anybody in this job feeling they would do it better without the help. But, you know, some people…

¹ If that sounds boring, don’t contemplate working on the production line. When I do, I swear I can feel bits of my brain actually dying of boredom. When I used to do the clean-down at night, I took an MP3 player with some songs and a Japanese audio course. But I usually listened to the songs, or The World Tonight streamed off Radio4.

² If anybody at work knew who Yuki Nagato is, they’d probably comment that we could be siblings. Except I’m real…possibly.

I think we have an example of the problem here. Steve appeals for help on a simple topic. The response is to argue over the content of what’s there already – and even to question the copyright. No progress, and it’s consumed some of Steve’s valuable time.

If anyone really does want to help, my suggestion is to take the task on and don’t argue about it. Errors and omissions can be corrected later.

I’m not volunteering; as you probably know, I’m busy doing something else that should help RISC OS.

I was going to offer to help if no-one else did.

Are you still interested in it, Chris?

Yup, just been super-busy :) As soon as I get some time, I was planning to take a good look and review the documents, as Steve suggested, then others can chime in. At the very least I could move the docs over to the wiki, and perhaps others more knowledgable could review the technical contents to make sure they’re still accurate.

and even to question the copyright.

Duh. So whether or not we can make use of what has already been written is “not important”? You are advocating what? Take the content then worry about consequences later?

No progress, and it’s consumed some of Steve’s valuable time.

Actually I have started putting some ideas in a text file. It is a very niche topic really, so needs to be worded correctly. ;-)
But, as yet, it is all original content as the “unimportant” question regarding copyright is unanswered.

Duh. So whether or not we can make use of what has already been written is “not important”? You are advocating what? Take the content then worry about consequences later?

I doubt Steve would have worded his initial post the way he did if we didn’t have permission to copy-and-paste large parts of the docs.

Also a lot of the technical docs on the Iyonix website are just HTML versions of text files from CVS!