Who owns the PRM copyright now?

This is probably a question for Andrew, but it might still be of interest to other forum readers so I’m posting it here:

There are several topics covered by the PRMs that aren’t in the ROOL wiki. I’ve seen some general advice in the past that the wiki content should not be copied and pasted from the PRMs due to copyright.

With RISC OS Developments now in the mix, what’s the current copyright status of the PRMs? Could we get permission to start bulking up the wiki with PRM content – with an aim of making it the definitive reference – or are there still issues around this?

Chris’s question seems to have gone unanswered, but I wonder if the problem isn’t so much copyright as a desire not to pollute the online PRM with out-of-date information.

Would it be acceptable to upload the old PRM content with a disclaimer at the top of the page? Perhaps something like “This page contains information sourced exclusively from the RISC OS 3 PRM and may not accurately represent how RISC OS 5 behaves. If you edit this page to include up-to-date information, please remove this notice.”

As a further aid, all such pages could be placed in an “OldPRM” category.

Just a thought…

I think the copyright status is secure because PDFs of the PRMs (Volumes 1 to 5a and the style guide) are included with the RCxx series of SD card image downloads available for the Raspberry Pi in the directory $.Documents.Book.PRMs and have been so included since the first RC5 distribution in October 2012.

Would it be acceptable to upload the old PRM content with a disclaimer at the top of the page?

Good way of starting an argument I suppose. I believe the standard advice for people wanting to look at the content of the old PRMs is to look here – after all why upload something that’s already avaialble on line?

I completely forgot that I asked this; I was going to give it a few days then email Andrew if he hadn’t seen it. But at the moment I’m too lazy :)

why upload something that’s already avaialble on line?

Because ROL’s site isn’t a wiki and will be perpetually out of date.

Because ROL’s site isn’t a wiki and will be perpetually out of date.

I think you’re missing the point:- It’s an old version of the PRMs describing the behaviour of an old version of the OS, neither is changing and therefore they remain perpetually as up to date as each other.
None of it was written to match RO5 in any subversion.

Now, consider that the wiki describes a regularly changing OS version and therefore needs to change to match each new sub-version while retaining the info of all the previous sub-versions. That’s why simply pasting in the content of the old PRM is wrong.

If we can’t paste in content from the old PRM then any behaviour that hasn’t changed needs to be redocumented from scratch.

I’m not proposing that we bulk import the entirety of the old PRM (however, Stuart seems to be) but rather that we can copy across old – but still relevant – content on an as-needed basis.

Sorry if I’m being a little unclear; I didn’t get much sleep last night :(

An enormously helpful task would be to identify exactly which bits of the PRMs are still correct, which bits are entirely wrong (for RISC OS 5) and which bits are subtly changed. Also which SWIs have been added since PRM5a (just the number/name).

This information alone would allow a non-programmer to rough out ‘the changes’ and to identify the new SWIs (by name and number) albeit silent on what they do.

I agree that the majority of the PRMs is still relevant and they are a constant source of reference for me.

ROOL (perhaps inter alia as RISC OS Ltd have withdrawn the on-line PDFs and uploaded an HTML version) own the copyright and also hold the source text in a FrameMaker format which can produce PDF or HTML as its viewing medium.

I was referring to the 400+ pages that the wiki lists as “wanted”. If a page already exists, I would be inclined to leave it alone.

Let’s step back and consider the optics here. Roughly 12% of the PRM (in wiki page count if not word count) isn’t there at all. Somebody looking at this from outside might get the impression that we weren’t serious abut providing documentation, whereas most of us would prefer that the programmers concentrated on writing new code.

If ROOL could provide guidance on this point, so much the better.

From the point of view of a programmer, the documents exist. ROLtd, here, stronghelp… What would be more useful is definitions of changes between versions, when stuff was introduced, and some example code (especially for things like the USB stack).

Consider https://www.riscosopen.org/wiki/documentation/show/Wimp_Initialise – there is little info on what changes the version number actually introduces, which is all the more important when you get beyond 310…which isn’t documented at all…
Plus the understandable but incorrect assumption that Wimp version equals OS version.

I agree with Rick. But I long for the day again when I can look something up in one place and find the definitive answer how something works on all releases of RISC OS, rather than currently looking in several places and never being sure you have the fulll story. An updated PRM should not just be RO5.

+1 AND VERY MUCH SO MARTIN.
I didn’t mean to shout but my caps lock state was serendipitous.

An enormously helpful task would be to identify exactly which bits of the PRMs are still correct, which bits are entirely wrong (for RISC OS 5) and which bits are subtly changed. Also which SWIs have been added since PRM5a (just the number/name).

Extending that concept probably matches Martins wish if you tag/footnote every page to mark which bits hold true for which revisions starting with RO version – ah, decision time, but then as I’ve quoted further down guidance from ROOL or perhaps ROD is required.

So you take my earlier comment

the wiki describes a regularly changing OS version and therefore needs to change to match each new sub-version while retaining the info of all the previous sub-versions

and start with a base text that covers the earliest version under consideration and tags the changed items on from there.

As Stuart said:

If ROOL could provide guidance on this point, so much the better.

Ideas about how to mark the base text and the later variants are the bits to discuss until ROOL provide the “steer” on the base version.
Andrew could perhaps fill in any political aspect of documenting anything that relates to the RO branch.
Maybe we don’t need to tippy-toe around the issue these days.

Andrew could perhaps fill in any political aspect of documenting anything that relates to the RO branch.
Maybe we don’t need to tippy-toe around the issue these days.

My €0,02:

Yes, document ROLtd’s branches if stuff is known (this is why). It doesn’t make sense to document the Acorn versions and extensions for the ROOL version, yet miss out “the other branch”.

In fact, pretty much the only things that should be dropped are any mentions of RISC OS 2; basically because it was much simpler so the number of “This isn’t available on RISC OS 2” notices would get annoying (like it does in the 3.10 PRMs!).

Ideas about how to mark the base text and the later variants are the bits to discuss until ROOL

Given this is ROOL and the home of RISC OS 5, that should take precedence. Any API shown should be shown in its RO5/contemporary incarnation, with notes following to describe changes that apply for other versions of RISC OS. The only variation to this should be API elements specific to certain versions of RISC OS, which should make mention of this at the top – like “This call is available on RISC OS 3.80 or later” (example: TaskManager_StartTask) or “This call is only available on RISC OS 5” (example: Unicode FontManager).

Think if it from the point of view of a programmer.
Importance, basically:

1. The API name (so we know we’re looking at the right thing!)
2. What OS versions does it work on (if not “all”)?
3. What’s the API for the current builds of RISC OS?
4. Are there differences in behaviour for older versions?

You’ll notice I’ve put the “which versions” as second thing to look at, more important than the API description. It is. There’s no point looking at an API for a version of RISC OS different to the one you’re using/aiming for. That needs to be reasonably prominent, not a footnote. You’ll notice StrongHelp’s manuals tend to put this information in the window’s TITLE!

Given this is ROOL and the home of RISC OS 5, that should take precedence. Any API shown should be shown in its RO5/contemporary incarnation, with notes following to describe changes that apply for other versions of RISC OS.

I totally disagree. It is unjustifiable to describe some benign RO5 API and then add the footnote “Please note this call will erase the contents of all discs on other versions of RO but who cares about them, losers.” metaphorically speaking.

A concrete example that springs to mind is OS_ReadLine – an admittedly complicated case:

The resulting API, as documented on that page, is emergent – indeed the current RO5 implementation is not fully compliant (all it would take is one BIC added around line 64 of this file ).

Otherwise, your API would consist of

• First, read OS version
• If it’s 5.xx do this
• Otherwise do that

That’s a crap API.

There’s no point looking at an API for a version of RISC OS different to the one you’re using/aiming for

Utterly wrong and completely indefensible, and we’ve discussed this before.

Even if you’re planning on never distributing your program, writing for one specific version of an API locks you into using that version into perpetuity, or requiring you to fix obscure bugs once you upgrade/use a different device/decide to distribute.

The API transcends any particular release, but I’ll make the more general point in a separate post.

That’s a crap API.

It is, but when we have 26 bit and 32 bit to deal with, as well as two completely different branches of the OS, sometimes there’s no choice.
You might well say “do it properly”, but the fact is there are two different processor modes and two branches and potentially a decades worth of existing software to contend with.

Utterly wrong and completely indefensible,

What would you prefer? Document the initial incarnation of the API and then paste on paragraphs describing differences in each version in turn? That would put the only still developed version at the end of the list.

At any rate, documentation does need some TLC, that at least we can agree on.

We’re only disagreeing on emphasis – the API is bigger than the RO5 implementation, RO4 or even RO2. Some of it may even predate the Beeb.

One of the most important roles for the API reference here is to ensure that active OS developers are aware of the entire API. Otherwise we’ll have repeats of the OS_Byte 166 fiasco – where incredibly long-standing API gets broken because somebody didn’t know about it.

And here’s a tangential point: The sources are horrible – the struggle I had trying to find where the Kernel’s ReadLineV handler is located! It turns out it’s in a file called “Middle”, and doesn’t itself mention ReadLineV.

There ought to be a map. Here is this bit of API, and here are all the places it is implemented, and here is the documentation of how and why it is implemented like that.

Otherwise we’ll have repeats of the OS_Byte 166 fiasco

Ah, yes. VarStart. How does one represent a 32 bit address in 16 bits? :-)
It’s a left-over from the BBC MOS, so should probably be forgotten.

SYS "OS_Byte", 166, 0, 255 TO , a, b
addr% = a + (b << 8)
SYS "OS_PlatformFeatures", 0 TO a%
IF ( a% AND (1 << 20) ) THEN addr% += &FFFF0000
PRINT ~addr%

This reads the address, adds in the high vector if necessary.

But there’s a simpler way.

>SYS "OS_ReadSysInfo", 6, 0, 71 TO ,,addr%
PRINT ~addr%
  FFFF08FA

;-)

So let me amend my earlier assertion. Not only do we have 26 bit and 32 bit API differences, we also have lingering 16 bit stuff from the BBC MOS!

The sources are horrible

Yes.

At least the kernel sources have names that sort-of-maybe indicate what might be inside of you’re really good at lateral thinking.
Try the Wimp sources. Most of them are “wimp” with a numerical suffix. Not only that, but it’s only sort-of-maybe that they are thematic. Wimp06 is all about loading templates, and appears to be. Wimp07, on the other hand, starts off about SendMessage, then covers StartTask before veering into ErrorHandler (is that for StartTask or is it the general error handler?). A little after is the routine saveFPregs (why here and not somewhere closer to Wimp_Poll? it’s because StartTask uses it…). Finally a huge swathe of code to deal with ReportError.

What I’d love to do is to tear the Wimp code apart, into maybe 30 files each with a clear purpose. Keyboard handling here. Redraw stuff here. It’s surely better than dropping all of the files into Zap and searching “all files” for things. But, then, I have to do that with the kernel too as…

It turns out it’s in a file called “Middle”, and doesn’t itself mention ReadLineV.

…and if that’s not bad enough, trying to find where stuff is defined and other stuff is used is no joke. Is it in Hdr? Exports? Somewhere behind the sofa?

There ought to be a map.

https://m.xkcd.com/1759/

Here is this bit of API, and here are all the places it is implemented, and here is the documentation of how and why it is implemented like that.

Here is this, here’s a ridiculous dependency list of where it is scattered around, here’s documentation for the API twenty seven years ago, and it is implemented like that because the programmer was smashed on coffee having been awake for 37 hours and 18 minutes and by this point he no longer cared which part of TWIN he was typing in, just that the damn thing would assemble before somebody came and took the dinosaur away…

Ah, yes. VarStart. How does one represent a 32 bit address in 16 bits? :-)

You have walked into the trap I laid. That interface is not 16bit in RISC OS.

Some related OS_Bytes like 131-133 weren’t even 16bit on the BBC Micro.

How did Mark Twain put it?

It’s not what you don’t know that kills you,
it’s what you know for certain that just ain’t so

On the Beeb 166 was 16bit because MOSVAR is defined to be in the host, and that was defined to occupy addresses &FFFF0000 to &FFFFFFFF in the 4GB virtual address space (see OS_Byte 130), so it could only be 16bit (on MOS). But 131-133 could reside in the co-processor, so those OS_Bytes returned 23bit results on the BBC Micro. (And if you have a working 65Tube you could try it in there and observe the 23bit result).

The correct way to read OSHWM on the Beeb was:

A%=131:R%=USR&FFF4:OSHWM%=65535AND(R%DIV256)
IF(R%AND128)=0:OSHWM%=OSHWM%+(R%AND127)*65536

But to answer your question, on the 32bit processor (starting with Arthur), OS_Byte can return 32bit values. For example, here’s how to get a list of floppy disc formats:

SYS"OS_Byte",143,&6ATO,,addr%:PRINT~addr%

And for those OS_Bytes that returned an address in two registers on the Beeb (such as 166), the bottom eight bits are in the first register, and the other 24bits in the other register. So to read the start of the MOS vars in RISC OS one does:

SYS"OS_Byte",166,,255 TO ,X%,Y%
MOSVAR%=X%OR(Y%<<8)

And it has been that way since Arthur… until somebody broke it in RO5 because they knew for certain that “OS_Byte only returns bytes” (my MosVarFix module here fixes high-vector versions of RO5 until someone can be bothered to correct the oversight).

DO YOU SEE WHAT I MEAN NOW?

SYS “OS_Byte”, 166, 0, 255 TO , a, b
addr% = a + (b << 8)
SYS “OS_PlatformFeatures”, 0 TO a%
IF ( a% AND (1 << 20) ) THEN addr% += &FFFF0000
PRINT ~addr%

Yeah that’s dead wrong, for the reasons outlined above. Don’t do that.

SYS “OS_ReadSysInfo”, 6, 0, 71 TO ,,addr%

Yes, so we have the bizarre stupidity of code in RO5 being modified to do that call and then, if it returns an error or just doesn’t know the answer, doing the original OS_Byte instead. When it could have been left unchanged if someone hadn’t “known for certain” something that really, really, “just ain’t so”.

Look at the state of this, from InternationalKeyboard:

OlD cAlL Iz 16BIt sO MusT Do nEw cALl bUt if tHAt doESn’T WOrK GeT 32bIt rESUlt fROm OlD cAlL!!!

<facepalm> <facepalm> <facepalm>

I am prepared to believe that not everyone has been spelunking through Acorn operating systems as long as I have, but when OS developers aren’t sure what the API is what hope do mere mortals have? Hence my assertion that the API is bigger than whatever someone has made RO5 do… this week.

he no longer cared which part of TWIN he was typing in

I was bereft when Twin stopped working. Bereft. Still, I was just using Edit in MODE 0 using 65Tube an hour ago, so I feel better now.

Update: I had misremembered – Twin does work, as long as you don’t care about the Millennium Bug:

You have walked into the trap I laid. That interface is not 16bit in RISC OS. […] the bottom eight bits are in the first register, and the other 24bits in the other register

Sorry, I was not working on the assumption that OS_Byte only deals with bytes because it has “byte” in the name, nor was I falling into your carefully laid trap.

I was simply observing that the value returned for VarStart is a 16 bit value because that’s how it is defined in the source and these bytes are just blindly read and output. To handle it properly, the OS_Byte code would need to recognise that it needs to fudge the address as appropriate for high vector use.

And it has been that way since Arthur…

And of that code hasn’t been specially altered recently, it could just as easily have been returning 16 bit values (as implied by the workspace definition) since Arthur. When all your top bits are zero, it’s the same thing……..until suddenly all your top bits aren’t zero and oops it’s broken.

OlD cAlL Iz 16BIt sO MusT Do nEw cALl bUt if tHAt doESn’T WOrK GeT 32bIt rESUlt fROm OlD cAlL!!!

How about “try new call and if that doesn’t work then the OS is not high vector so the old call will suffice”.

I ask again, when the OS_Byte code is returning a value from two bytes of workspace, please enlighten me as to how it is supposed to construct a 32 bit value?
Really, it probably ought to trap &A6 and do whatever the ReadSysInfo call does so it can return a valid 24 bits in the other register.

Twin does work

I know. I ported it. As did, I’d imagine, a bunch of other people, since I’m aware of a few other incarnations floating around. There’s one with really messed up colours due to machines like the Pi not having anything less than 256 colour modes.

Okay then. Here is the corresponding code from RISC OS 2:

Full size: https://i.imgur.com/z4KzTxh.jpg

The byte is loaded from workplace. The AND/EOR stuff is done. The old value is returned in R1, and the value of the next byte is returned in R2.
Therefore RISC OS has always treated these values as being sixteen bit. It returns two bytes, it is stored in workspace as two bytes. What more do you need to understand that?

If it was a 32 bit thing on the Beeb, then it’s Acorn that cocked this one up, not ROOL.

It’s a fairly literal translation of the code in the BBC MOS…

E99C TAY.        ;Y=A
E99D LDA &0190,Y ;i.e. A=&190 +osbyte call!
E9A0 TAX         ;preserve this
E9A1 AND &F1.    ;new value = OLD value AND Y EOR X!
E9A3 EOR &F0.    ;
E9A5 STA &0190,Y ;store it
E9A8 LDA &0191,Y ;get value of next byte into A
E9AB TAY.        ;Y=A
E9AC RTS.        ;and exit

http://mdfs.net/Docs/Comp/BBC/OS1-20/E887

Note, that’s 16 bit too. ;-)

Therefore RISC OS has always treated

No, you are mistaking the implementation in one version for the API in general.

OS_Byte 131 is hard-wired to return &8000 in RISC OS… but if you do it in 65Tube you’ll get &0800 (if there’s a language ROM running).

As I’ve said a few times now, the API transcends any particular implementation.

until suddenly all your top bits aren’t zero and oops it’s broken.

You are indeed describing the error the developer made, yes.

a fairly literal translation of the code in the BBC MOS…

And for similar reasons. Now look in the OS of the 6502 second processor and explain what you find.

The API transcends any particular implementation. This is why “what RO5 does” is only part of the API.

And finally, one last try…

I ask again, when the OS_Byte code is returning a value from two bytes of workspace

OS_Byte 166 is not defined to be returning the value of two bytes of workspace, even if there are implementations that do that – there are also implementations that do not. It is defined as returning the address of the start of the MOS vars. It is also defined that you cannot write the value with this OS_Byte, even if there are implementations that uselessly and erroneously allow you to. And note that the BBC MOS does not, naturally enough, return the same value as RISC OS:

Bray, Dickens and Holmes, 1983.

As I’ve said a few times now, the API transcends any particular implementation.

And I’ve said a few times now that that API returns a sixteen bit value. There is clear obvious evidence that under RISC OS it is sixteen bit, and your assertion that it was 32 bit on the BBC MOS is also clearly wrong unless you happen to know some sort of magic to have a 24 bit value held in a register on an 8 bit processor.

You seem to be conflating OS Byte, that returns at most two eight bit values (on the Beeb), with co processor addresses given to OSWORD.

If you’re looking for the other 16 bits of the address, try OSBYTE &82.