Who owns the PRM copyright now?

And I’ve said a few times now that that API returns a sixteen bit value.

And you continue to confuse one implementation with the API in general.

There is clear obvious evidence that under RISC OS it is sixteen bit

This is an implementation detail. It is not the API.

your assertion that it was 32 bit on the BBC MOS is also clearly wrong

I haven’t asserted that. I said this:

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.

It’s not like you to resort to straw men.

unless you happen to know some sort of magic to have a 24 bit value held in a register on an 8 bit processor

Again, I must direct you to OS_Byte 131 on the Beeb, which returns up to 23bits in A,Y,X (in that order).

Here’s the code from the 2nd processor OS that returns OSHWM from OSBYTE &83:

FAB5 : A9 01    : ©A  : LDA  #&01	; &010000
FAB7 : A2 00    : ¢@  : LDX  #&00
FAB9 : A0 00    :  @  : LDY  #&00
FABB : 60       : `   : RTS

And here’s the code for OSBYTE &84:

FAC6 : A9 04    : ©D  : LDA  #&04	; &040000
FAC8 : A2 00    : ¢@  : LDX  #&00
FACA : A0 00    :  @  : LDY  #&00
FACC : 60       : `   : RTS

OS Byte, that returns at most two eight bit values

This is absolutely wrong, as the above code demonstrates.

Surely you’re not going to argue that this Acorn implementation ‘counts’, but that Acorn implementation doesn’t count? That won’t wash.

You are simply wrong in your assertion that OSBYTE can only return 16bit addresses. It has been returning greater than 16bit addresses since the 1980s. This isn’t a matter of opinion.

If you don’t believe me, the Advanced User Guide or actual Acorn code, please peruse any other documentation of OSBYTE, such as the BeebWiki at MDFS.

In not talking about what other OS Bytes may or may not do. I’m responding simply to:

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.

It’s not a fiasco, it has only ever had a high byte and a low byte, hence a 16 bit value. Look at the MOS source. Look at any incarnation of RISC OS. There was another call to read the upper 16 bits of the co processor address.

It’s not a fiasco, it’s just unfortunate that finally something has happened that means the call now returns gibberish.

BTW, if the OS Byte can return 23 (24?) bit results, surely even that would have been inadequate to give any &FFxxxxxx address? Hence the separate call.

<more repetitions of individual implementations instead of reading the API definition>

Does this help you understand the difference between API and implementation?

if the OS Byte can return 23 (24?) bit results

On BBC MOS. No one has suggested that RISC OS returns large addresses like that. The RISC OS convention has already been given above, but is:

SWI     OS_Byte
ORR     Rn, R1, R2, LSL#8

Which is a 32bit result.

Here’s how I described it before:

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

I’ve also named an RO5 module that does that. Do you want me to list all the modules that do that? I would have though that one would be sufficient, but name your threshold.

Again, I must direct you to OS_Byte 131 on the Beeb, which returns up to 23bits in A,Y,X (in that order).

Actual Beeb user guide:

This call is used to return the address of the first free location in memory above that required for the operating system. The value is returned in X and Y with Y containing the most significant byte and X containing the least significant byte. [page 416]

Advanced User Guide:

On exit, X and Y contain the OSHWM address (X=low-byte, Y= high-byte)

The New Advanced User Guide says that for OSBYTE, A is preserved.
The Master User Guide is rubbish and describes nothing technical.

BBC MOS 1.20:

*************************************************************************
*                                                                       *
*                 OSBYTE 131 READ OSHWM (PAGE in BASIC)                 *
*                                                                       *
*************************************************************************

F085 LDY &0244  ; read current OSHWM
F088 LDX #&00   ;
F08A RTS        ;

Clearly:

1, The use of A to return extra bits appears to have been retrofitted for some uses of the Tube coprocessor. Documentation of its use doesn’t seem to be mentioned in the official user guide (issue 1) nor the AUG (issue unknown, the one at http://stardot.org.uk/mirrors/www.bbcdocs.com/filebase/essentials/BBC%20Microcomputer%20Advanced%20User%20Guide.pdf).
2, the official documentation, the other documentation, and the MOS itself imply it’s a simple value returned in X,Y and A is preserved.

Therefore I would contend that whatever it is that passes larger values using the A register is the anomaly (whether out of necessity or not) as the BBC MOS and all of its documentation as well as the RISC OS implementation all seem to agree – it’s a low byte and a high byte and nothing more. That is the API that is documented, that is the API visible by looking at the code of the respective operating systems. That is the API. Whatever it is that actually mucks around with the A register is just plain wrong as the published documentation of the API states that A is preserved.

However, I will grant you, the idea of the code and the documentation doing entirely different things, I believe we’ve been here before. A lot.

I rest my case.

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

You are simply wrong in your assertion that OSBYTE can only return 16bit addresses. It has been returning greater than 16bit addresses since 1982. This isn’t a matter of opinion.

If you don’t believe me, the Advanced User Guide […]

OK, then…

OSBYTE &83 (131)

Read top of operating system RAM address (OSHWM)

No entry parameters

On exit, X and Y contain the OSHWM address (X=low-byte, Y=high-byte)

This call is used by BASIC to initialise the value of PAGE.

After call,
    A is preserved
    C is undefined

(p155, Bray, Dickens and Holmes, August 1983).

The following two pages, for OSBYTEs 132 and 133, are very similar – although there’s a clear typo on the OSBYTE 132 page. They refer to “low-byte” and “high-byte”, which is very definitely 16-bit.

What subtle word-play have I missed here?

The use of A to return extra bits appears to have been retrofitted for some uses of the Tube coprocessor.

Correct (finally!) – by Acorn. Extending the API at that point.

The fact that documentation already distributed and manuals already printed did not spontaneously change is regrettable but to be expected.

I would contend that whatever it is that passes larger values using the A register is the anomaly

So every change Acorn made to the original Beeb API is an “anomaly”? This is a degree of retropurity that even I cannot subscribe to. Which is why I wrote earlier:

Surely you’re not going to argue that this Acorn implementation ‘counts’,
but that Acorn implementation doesn’t count? That won’t wash.

the API visible by looking at the code of the respective operating systems

Which we have done, hence revealing the 23bit form of that API, introduced in order to return values greater than 16bit on the Beeb. (And all of this banter about OSBYTE is missing the point that OS_Byte has always returned values that are not bytes – OS_Byte 143 is definitive.)

I still feel you’re misunderstanding the relationship between API and implementation.

If an API says “R0 shall be returned as a value between 0 and 7” but there are official implementations that return 42, then the API documentation is wrong – the code has revealed that.

But if the API says “R0 shall return a value between 0 and 7” and every implementation you can find returns 4, that does not mean the documented API is wrong.

Here’s a concrete example: The published API for RemV says:

Exit	 
R0	Next byte to be removed (examine option), or corrupted (remove option)
R1	Preserved
R2	Byte removed (remove option), or corrupted (examine operation)
C flag set if buffer was empty on entry

You’ll note the strange asymmetry regarding which register holds the byte – R0 under some circumstances, R2 under others. But the published API is clear.

It’s also wrong.

To see why you have to delve into the depths of the Kernel’s RdchVHandler which, after checking that it’s not expanding a function key, calls RemV with V clear in order to remove a byte from the keyboard buffer. As you can see above, this ought to be in R2. However, the very next thing it does is set R2 to zero, and thereafter assume that R0 contained the byte.

It has done this in every single version of RISC OS from right now all the way back to Arthur 0.30. So regardless of the sincere belief of whoever wrote that documentation all those years ago, the OS depends on the byte removed being in R0. Always has.

Therefore, every implementation of RemV – the kernel, BufferManager, DeepKeys etc, has always had to return the byte in R0, otherwise the OS doesn’t work. However, they also have to return it in R2, because of the documented API that third parties may have relied on. So for RemV, R0=R2.

If at this point you’re beginning to feel it’s rather unfair that I keep pulling out examples like this… does that not prove my point about the importance of having a definitive document of the actual API, and what better place than here? Which is where we started.

Steve asked

What subtle word-play have I missed here?

Must be an M128 Turbo thing, so that would be ~1985?

I mentioned the AUG because of this definitive promise:

This call returns the start address of the memory used by the
operating system to store its internal variables.

Not because of its superseded assertion about the 6502’s A register.

the importance of having a definitive document of the actual API, and what better place than here? Which is where we started.

So, not only have we established that the documentation being proposed in the wiki needs to properly reflect the implemented behaviour¹, but also if the information is to correctly reflect the implementation in older versions of the OS we can not use the old documentation except as guidance for what might be true.
Perhaps if people discuss the content/layout so that a sample page indicates what versions any particular text refers to – hopefully without too much extraneous page content (subtle markers near text rather than big shouty) – then we get somewhere.

¹ Accurate documents might help programmers a little, might even help point out where OS developers need to correct long standing mistakes.

Must be an M128 Turbo thing, so that would be ~1985?

OK. So we have a RISC OS API that examination of the source tells us has been resolutely 16 bit since Arthur, and is documented as being 16 bit even on the Beeb MOS. But we’re not allowed to document it as 16 bit in the RISC OS PRM because Acorn broke the documented MOS API in one version of MOS by corrupting a preserved register on return. Only we can’t find this MOS API change documented anywhere official, nor agree exactly which version of MOS it was in. And the RISC OS developers dropped it anyway.

I think I’m following this argument. :-)

Mmm – sound a bit like Brexit :-|

guidance for what might be true

Yes and no. I see it as a ratchet: APIs do change over time, but they should only go one way – more capable, not less. The published API is a contract with the programmer.

Sometimes an API must be obsoleted due to lack of foresight, such as OS_HeapSort – address bits used as flags is untenable now. However, breaking a RISC OS API because of some perceived restriction of the BBC Micro’s 6502 is indefensible, and the ReadLineV case of processor mode selecting incompatible APIs is deeply regrettable (and that API is still not unified).

The API must consist of the superset of published documentation and official implementations. This will inevitably require some predication: “This flag is only available from version x.xx…”.

I think I’m following this argument.

It’s very simple. The API says

This call returns the start address of the memory used by the
operating system to store its internal variables.

A promise kept through every version of the OS (and how that was implemented does not matter one jot in this case – it was supposed to return the address, it returned the address).

That was then broken because of a philosophical belief – that OS_Byte couldn’t return arbitrary values – despite 1) that not being true, and 2) the existing code already working perfectly when a 32bit value is returned.

It was a mistake. The 6502 is irrelevant.

Acorn broke the documented MOS API

They extended it. It’s happened a lot since then.

by corrupting a preserved register on return

It’s not corrupted. If b7 is set it is preserved. If b7 is clear it’s the top 7 bits of a 23bit value.

‘Corrupted’ implies undefined, liable to be any value. It isn’t, it is unambiguously defined… but it’s only relevant to OSBYTE, not to OS_Byte.

we’re not allowed to document it as 16 bit in the RISC OS PRM

OS_Byte is not 16bit for crying out loud! Do SYS"OS_Byte",143,&6ATO,,addr%:PRINT~addr% and explain what you get! Crikey.

OS_Byte takes and emits word-sized parameters. The Kernel treats R0 as a byte by ANDing it with 255, but other ByteV claimants can and do implement OS_Bytes > 255 (such as VProtect, off the top of my head). Some OS_Bytes return word-sized results in a single register. Others are defined to return a result in two registers, and those registers must be combined using ORR Rn,R1,R2,LSL#8 to produce a 32bit result. There are many parts of the OS that do this.

That someone in 2019 is trying to argue that what has been 32bit for 32 years should somehow be 16bit because of the 6502 when OSBYTE wasn’t even 16bit is beyond parody.

This will inevitably require some predication: “This flag is only available from version x.xx…”.

I think you meant to say¹ “This flag is only available from version x.xx…”.(assumes unity of developmental threads) or for certain circumstances “This flag is only available in these versions x.xx to x.xx +n.”
There’s also the implementation specific variants to consider where the hardware feature only appears on certain boards so no one put that feature in the build.² ADFS not in the OMAP3 build are the first instance that comes to mind.

¹ Because I’m such a nice person I will assume you missed out the possibility that something was moved, changed or added in the ROL branch that doesn’t exist in other versions that were before or parallel.
²All fine, but if the application tries to do something fairly inconsequential and then goes A-over-T on initial run because there’s no ADFS module present…

Correct (finally!) – by Acorn. Extending the API at that point.

Something which doesn’t appear to be mentioned anywhere other than the one source.

You know why you’re checking bit 7? Because it is a bodge. A half assed quick hack to make do rather than putting it in OSWORD where “big values” belong. You’re checking bit 7 because the API is supposed to preserve A.

I still feel you’re misunderstanding the relationship between API and implementation.

I still feel you’re misunderstanding that a bodge does not instantly revise the API. I’ve provided references both pre and post the Tube. Everything, read again EVERYTHING, including source, treats it as a low byte and a high byte.

I mentioned the AUG because of this definitive promise:

Irrelevant. The promise that A is preserved came first and I don’t like the idea of arbitrarily retconning an API.

’Corrupted’ implies undefined,

Christ almighty – you’re using Tory party logic now.
Corrupted means “different on exit than it was on entry”. Some times this is indeed the intended behaviour, sometimes the register is “corrupted” as a side effect. A is supposed to be preserved, it isn’t, and farting around with bit 7 is ample proof of this discrepancy.

They extended it. It’s happened a lot since then.

Yup. “TASK” and magic values in the Wimp. It’s shameful. I’m still wondering what will happen with a window defined as a pane on Select, the exact same bit appears to mean two different things. Did I mention it was shameful?

That someone in 2019 is trying to argue that what has been 32bit for 32 years should somehow be 16bit because of the 6502 when OSBYTE wasn’t even 16bit is beyond parody.

That somebody is desperately clinging to the notion that a specific API is different to all of the documentation and source that exists aside from this one implementation is beyond parody.

RISC OS didn’t suffer a lack of memory. It would not have been hard to allocate a word (just two extra bytes) and a couple of instructions to mush the extra 24 bits into place. They did not, they treated it as a two byte, or 16 bit, value. Asides from – what was it, HighBasic or something? – asides from that OSHWM is a 16 bit value.
The evidence supporting this is all over the place. You appear to be able to point to one version of the API that actually breaks the API.

End of.

It’s worth noting that there seems to be some confusion (obfuscation?) along the way regarding whether or not OS_Byte handles values larger than a byte.

This is not what I’m arguing. Clearly X,Y were byte sized on the Beeb but can easily be word sized on RISC OS (such as the deprecated OS_Byte 143). In order to handle “big modes”, OS_Byte and anything that calls it will need to cope with words – it’s perfectly feasible to have more than 256 text columns on screen now…

Anyway, what I am arguing is this hideously broken hack pushing crap into the A register on the Beeb in order to add some extra address bits. Why is this bad? Because there exists an OSBYTE that provides the high order address bits of the machine – namely OSBYTE &82.
Therefore, in theory, a full address (of it doesn’t fit into 16 bits) could validly be built by calling the call we’re arguing about, then this one, then merging the two. Is there anything other than the Beeb family, your co processor, and RISC OS that implements OSHWM? Did the x86/Z80 devices? How do they handle this, if they did?

The problem we’re running into is it is essentially an API developed for an eight bit processor with sixteen bit addressing range (sorry nemo, history requires the 6502 to be anything but irrelevant, it is why this stuff is the way it is), that was later botched into returning larger values for some reason (interesting that it appears to be 6502 code returning addresses the 6502 cannot directly address!), which was subsequently ignored, and was then implemented on RISC OS in the same manner as the BBC MOS “because it worked” (due to page zero use) but was in effect rubbish liable to break the moment the address went over 64K (remember, nemo, it’s held in two bytes in the kernel workspace, it is implicitly 16 bit).
It looks like it’s taken far too bloody long for there to be a proper SWI call to handle 32 bit addresses correctly. But, then, I guess it’s the same “it’ll do” mentality that thought stuffing extra bits into the accumulator was acceptable…

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

Of course everyone should try to avoid this, but – hey – API must change too.
And sometimes, implementations prove to be more correct than the API description.

The documentation IS NOT the API, but the textual description of the API.
The code IS NOT the API, but the implementation of the API.

Another chicken and egg problem.

The documentation IS NOT the API, but the textual description of the API.
The code IS NOT the API, but the implementation of the API.

From a Tech Author’s pov, this is precisely the point.

You know that phenomenon where you wake up with the solution to a knotty problem?!

Rick, I realise that we are talking slightly at cross-purposes. You have been adamant about the 8bit/16bit restriction, and yet I’ve demonstrated with various OSBYTEs and OS_Bytes that there is no such restriction.

Well of course there is a restriction for some of them: The MOSVARs themselves. There’s little point returning the address of the THE MOSVARs without defining what that points at – the MOSVARs are bytes. So although the OS_Byte API would seem to support 32bit MOSVARs (the AND and EOR masks can be 32bit), the ability to read/write them direct requires them to be bytes.

(And the ability to peek and poke them is a defined part of the API, as it is intended to allow access without having to enable interrupts for the duration of the lengthy OS_Byte call).

However, and this is the crucial point:

The address of the MOSVARs is not itself a MOSVAR.

Let’s list the many ways it is not a MOSVAR:

1. You cannot write to it – that is defined.
2. The OS does not read from it. The address is hard-wired, so it is not a variable.
3. It has a different API – the MOSVARs are manipulated using AND/EOR masks.
4. It is impossible to read as bytes – to do so you’d have to know the address already.

I realise that it is confusing that this call was implemented using the same code in the BBC MOS, but that’s an implementational wheeze to allow the OS to implement the call to return the address in only two bytes of ROM, by reusing the MOSVAR code (and at the cost of two bytes of RAM).

Otherwise the MOS would have had to do:

CMP #&A6
BNE next
LDX #lo
LDY #hi
RTS

A saving of seven bytes, when ROM bytes were scarce.

I’ll respond to any other points you’ve made after my morning’s conference calls!

You have been adamant about the 8bit/16bit restriction, and yet I’ve demonstrated with various OSBYTEs and OS_Bytes that there is no such restriction.

<facepalm>
I’ve been adamant that that one variable is two bytes giving a 16 bit result. My reason for concern has nothing to do with whether other calls are or are not byte sized. My concern is that if there is a 16 bit result, is there a legal other way of getting the extra address bits (other than the one you indicated)…

Sorry for the delay, I’ve had a busy week.

I’ve been adamant that that one variable is two byte

It’s not a variable. I even put it in bold.

is there a legal other way of getting the extra address bits

ORR Rn,R1,R2,LSL#8