Request for community help - 32 bit documentation

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.

Quite so, Rick.

Duh.

Quite so, Rick.
Duh.

When you are writing for yourself, you can make your own choices with respect to what you use.
When you are writing for somebody else, it is essential to check, especially when that somebody else is a company.

When the request comes from the Managing Director of ROOL, who is a man completely au fait with the copyright situation of the documentation in question, we already know the answer.

When the request comes from the Managing Director of ROOL, who is a man completely au fait with the copyright situation of the documentation in question, we already know the answer.

Ho ho ho.

As someone who had their copyright ripped off by one of ROOL’s volunteers a couple of years ago, and ended up having to threaten a recourse to legal action in order to even get the volunteer to respond to me directly and get a distribution licence (let alone getting one of ROOL’s directors to take an interest in the situation playing out in their name on these forums), I’m sure that you’ll forgive my amusement at your confidence.

Steve did not make the matter clear in his original post, and Rick’s question was IMHO perfectly valid. I also notice that Steve’s not actually answered it yet…

When the request comes from the Managing Director of ROOL, who is a man completely au fait with the copyright situation of the documentation in question

As Steve F points out an unintentional breach did occur so people are right to be suitably cautious. Ask the question, get a swift answer, move on. Don’t ask, don’t get a suitable answer and things can go mightily wrong.

Steve did not make the matter clear in his original post, and Rick’s question was IMHO perfectly valid. I also notice that Steve’s not actually answered it yet…

We could speculate that either:
1. Having had the question posed Steve is off checking for a definitive answer.
2. Workloads noted, perhaps Steve has not seen the question or been back on the forums since in order answer the question.

Overall it sounds as though Rick and Chis are looking to do work on it, for my part I will chip in about things I don’t understand to pull the required competence level for understanding down a bit

Hi all. Just to chip in on the Copyright side of this, ROOL already agreed with Castle (three years ago!) that we’d make this migration so we can use the wording as-is where we see fit, or change as required. We don’t need to attribute the text to Castle because it’s actually mostly developer documentation, not stuff Castle themselves authored. Clearly, it’d be nice to have all this in the ROOL website style, which effectively comes for free by putting it in our wiki.

If there are any Castle Copyright notices on any of the pages or documents, then we should keep those.

I will chip in about things I don’t understand to pull the required competence level for understanding down a bit

That sounds great – if we can take the opportunity to make the existing documentation more accessible at the same time, all the better.

Here’s an interesting observation – the documentation on the Iyonix site basically falls into two categories:

1. Documentation on how to make code 32bit compatible so that it will run on RISC OS 5 (and probably RISC OS 6)
2. Documentation for new/changed OS features in RISC OS 5, e.g. PCI, HAL, GraphicsV

I’d expect the new documents to be structured such that there’ll be a single (index) page which will deal with #1. But what about #2? Do we want to make a page which is a summary of everything new that’s in RISC OS 5? At the moment we don’t really have anything like it – the PRM docs in the wiki are a mish-mash of RISC OS 3.1 era PRM text and new/updated RISC OS 5 docs.

A page which lists the new things in RISC OS 5 (compared to 4.0?) would probably be pretty useful both for developers and as a marketing tool, even if we don’t yet have full documentation for all the changes which have been made. And if we did have a list of new things which aren’t fully documented, then it could help to focus the efforts of people who are working on docs for the wiki.

I’d expect the new documents to be structured such that there’ll be a single (index) page which will deal with #1. (making code 32 bit compatible)

Presumably that would be a link on the index page to a tutorial as the current information on the Iyonix pages is a bit ‘thin’ and a decent job would probably occupy several screens of information, possibly many pages each covering a different aspect.

The documentation that I have in mind is going to be laid out something like this:

• Brief explanation of the issue
• How to convert:
  • Pure BASIC [no issues]
  • ABC compiled BASIC [rebuild with new tools]
  • C [rebuild with new tools]
  • BASIC with assembler or pure assembler [needs explanation/modification]

which will lead to the next section that dives into hardcore technical details (if they are assembler programmers they’ll understand) that explains the issues (26 vs 32 bit) and non-aligned loads.

As I said above – this is a niche document. Probably not so many people wanting to make 26 bit sources run on 32 bit machines that haven’t already done so. So I’m mindful of the fact that it is possibly a historical document even though it hasn’t even been written yet! ;-)

How to convert:
Pure BASIC [no issues]
ABC compiled BASIC [rebuild with new tools]
C [rebuild with new tools]
BASIC with assembler or pure assembler [needs explanation/modification]

Do you think there is need for C with assembler (some things out there do have the mix)?

Further, do you think there is need to guide people in changing from assembler to C. Given that C source is a recompile with newer compiler settings while assembler is a walk through of the original and re-write of parts and we do have later processors with new requirements sliding into frame.

As I said above – this is a niche document. Probably not so many people wanting to make 26 bit sources run on 32 bit machines that haven’t already done so.

In some cases the authors are no longer around and although the readmes etc may state you can do with it what you wish they didn’t include source so reverse engineering with Armalyser or SID comes into play – but all that gives you is a mass of pure assembler (with some macros if you use SID)

Do you think there is need for C with assembler (some things out there do have the mix)?

I suspect that’s mostly going to be covered by what’s there already, especially pointing out the rules for the ‘new’ APCS-32 calling standard.

do you think there is need to guide people in changing from assembler to C?

That sounds like a different topic to me. I’m not saying it’s not an interesting one(!) but probably doesn’t need to be directly in this section of the wiki.

In some cases the authors are no longer around and although the readmes etc may state you can do with it what you wish they didn’t include source so reverse engineering with Armalyser or SID comes into play – but all that gives you is a mass of pure assembler (with some macros if you use SID)

That is one of the real world problems we’ve faced – the ARM BASIC Editor being an interesting recent example.

I like the structure Rick has proposed so my suggestion would be to make a start on it using the existing material and then we can look at all these ways to extend and improve it when that step is complete – or maybe even as we go, as long as that’s not too disruptive. :)

Do you think there is need for C with assembler (some things out there do have the mix)?

This would surely come under “pure assembler”? Even though the toolset is similar and programs can be linked of different parts written in different ways, I conceptually think of C and assembler as being two different things.

Further, do you think there is need to guide people in changing from assembler to C.

No. You do not need a mere guide such as this to help you convert assembler to C.
You first need to learn C. Then assembler (if you don’t already know). Then you need to pull apart the program to compartmentalise it into functions. Then you reproduce the behaviour in C.
It may well be quicker in the long run to become proficient in C and then just write something new that does what the older program did…

especially pointing out the rules for the ‘new’ APCS-32 calling standard.

How is this substantially different to the older APCS version, save for issues like non-preservation of flags? If you mean documenting the CLib startup for interworking C into assembler… Then no.

There is a need to properly document the 32 bit C library invocation, but it doesn’t belong here. Plus, that is a quite specialist subject and I’ve only ever come across one piece of software that did such a thing (hello Ample!). The compiler worries about this, and for most code, we pretty much just need to know that R0-R3 are trashable, the rest are not.

but all that gives you is a mass of pure assembler

While that is a valid point, I think such a task is best undertaken by somebody who is suitably “au fait” with assembler that some general hints and pointers will be sufficient. God help somebody who doesn’t have a moderate skill level with assembler trying to build a project from a disassembled executable. I mean, on the face of it, it’s not so hard in theory – you just replace the 26 bit code sequences with 32 bit ones. However if this should cause something to trip up along the way (for instance, something expected flags to be preserved over a function call which the original APCS did do) then you have the possibility of a range of subtle bugs that will require much effort and gnashing¹ of teeth in order to even locate said problem, never mind fix it.
If I was a newbie with no experience of assembler and I had the choice between converting a ~150K executable written in the RISC OS 2 days, or learning Japanese… やあ、お元気ですか?

to extend and improve it when that step is complete

The joy of wiki. ;-)

¹ Pronounced with a hard G which is wrong, but oh-so-satisfying.

While that is a valid point, I think such a task is best undertaken by somebody who is suitably “au fait” with assembler that some general hints and pointers will be sufficient.

Oh, good, you know of a long list of such people that are just itching to be given permission to do something.
Alternatively there’s the option where people get pointers on how to take the first steps. It might take a while for those people to move on a bit but the alternative is a diminishing pool of workers.

gnashing 1

I thought that was a chocolate dish :)

Alternatively there’s the option where people get pointers on how to take the first steps. It might take a while for those people to move on a bit

Do you program in assembler much? It is a completely different mindset to using higher level languages. There are no strings. There are no arrays. There are no objects. The evil GOTO is your only friend as you are mostly performing calculations and manipulations on information stored in areas of memory. There is no call to tell how long a string is until you have written one…after first defining what constitutes a string…

I would bet you a pint that if you compare people who think “yeah, I can do this” and do so versus those who think “oh my god” and throw in the towel….there will be a rather large pile of towels.

This isn’t to say that assembler is impossible (after all, I manage it!), it is however something that a person doesn’t just “dabble in” unless maybe they are masochistic enough to get aroused by the feeling of blood pouring down their face from the latest round of bashing their heads off the wall in frustration.
If you want to learn ARM code, I’ll enthusiastically help you to write small fragments in a larger program, little utilities and such. That’s how you start. You do not start by attempting to fix an auto-generated disassembly (that often contains gibberish labels), that’s akin to being told “Hi, this is a piano. For your first lesson, read this orchestral score for Beethoven’s Fifth and reproduce it in piano form – off you go now…”.

but the alternative is a diminishing pool of workers.

Depends, I guess, on whether or not they are scared away from ever trying anything else. Personally, I would think that attempting to track down the author and grovelling shamelessly for sources may have a more useful effect – at least if you can get your hands on the sources, you will have a much better chance of working out what is going on.
This isn’t always possible, but it’s worth trying.

Okay.

Beginnings are here. At this time (as Steve only replied re. copyright yesterday) it is all written from scratch.
Bloody Textile parser… Grrr…

https://www.riscosopen.org/wiki/documentation/show/Converting older software to run on 32 bit systems

Stops at the part that would describe how to convert assembly code. Well, that’s the fun bit so keeping you in suspense. :-)

Do you program in assembler much?

Not since the 1980’s and doing simple Z80 stuff on split beer mats in the pub¹ since then it’s only ever been assorted scripting languages on PeeCees, BBC BASIC for little stuff I happened to want at the time, fiddling with the odd C item, oh, and disassembling a few modules to twiddle them into a 32 bit form.²

The differences are explained in more detail here

Decent start.
Small point, I think the link to another site at that point needs altering to an equivalent page in the ROOL wiki

¹ There’s a story attached to that.

² Born awkward I suppose. Always did take things apart to see how they worked. Took the clock in my room apart totally when I was eight. It worked when I put it together again.

Rick the link for the Pure C line “If your program is written in pure C_, all you will need to do is to rebuild your project using the latest official development suite or GCCOS if you originally used that.”
is not rendering properly – I think Textile is winning the battle and you may need to do a “no textile” and HTML to get the effect.

Decent start.

Thanks.

Small point, I think the link to another site at that point needs altering to an equivalent page in the ROOL wiki

There will be a shorter definition to follow. However, if you think that the content is better on ROOL than my ARMwiki, the content on ARMwiki is CC-BY-SA. Help yourself.

Always did take things apart to see how they worked. Took the clock in my room apart totally when I was eight. It worked when I put it together again.

Me too. When I was maybe six or so, I took a washing machine apart. It was to be scrapped, so no need to put it back together again. I fixed a faulty auto-powerdown device on a record player at around the same time. For some weird reason I also took a door off its hinges to see how that worked, but was way too small to put it back again. Unfortunately my mother only noticed following the crash and much waaaah!ing – for I rather suspect that my removing the final screw from the top (balanced on a lot of books) followed by the door toppling on top of me might have passed as a crowning moment of funny to any observer. :-)

is not rendering properly – I think Textile is winning the battle

Yeah. Stupid parser can’t cope with _, and having underscores in link names seems to trip it up too. I will fix it in the next update (I hope). As there is no preview facility, don’t really fancy revealing a new page with 1,603 edits. :-)

Stupid parser can’t cope with _, and having underscores in link names seems to trip it up too.

Did a small edit to sort the underscore element in the link text, but unless I also took out the underscores round “pure C” it didn’t work.

I think the first set are not switching off the italicised effect and it is interfering with the escapes in the link.
So – no highlight on “pure C” and a working visible link text. OK?

I think the first set are not switching off the italicised effect and it is interfering with the escapes in the link.
So – no highlight on “pure C” and a working visible link text. OK?

Sure. I’ll just wrap it in <i> … </i> instead. [edit: done]

I also undid the "GCC\_for\_RISC\_OS" as that broke the link.

Wish the wiki spoke plain ordinary [[MediaWiki]], at least ’’that’’ is predictable! (^_^)

I also undid the “GCC\for\_RISC\OS” as that broke the link.

I find that when dealing with textile, it’s best to use HTML entities to avoid markup characters being unintentionally interpreted as markup.

* → &#42;
_ → &#95;
| → &#124;
[ → &#91;
] → &#93;

etc.

Let me know when you have something ready for proof-reading! I can already see a few fallacies in what Rick’s written ;-)

I can already see a few fallacies in what Rick’s written ;-)

A few ? I didn’t think I’d written enough yet to have fallacies in the plural! ;-)