GPIO documentation

I’m going back to change some code I got working a couple of years ago, that uses the GPIO module. I must have found documentation for the SWIs, but now I can’t find it.

This page https://www.riscosopen.org/wiki/documentation/show/GPIO%20SWI%20Calls for example is pretty much useless.

Have you tried the StrongHelp file hidden away on github?

Have you tried the StrongHelp file hidden away on github?

No – it seems to be hidden.

As I’ve never used any incarnation of Git – where would I start?

where would I start?

Try https://github.com/riscos-dot-info

EDIT: It’s not there. Where else had I seen it? Ah yes… here.

Beware, that is a very old version of the manual, and the SWIs have changed since! The latest version is usually supplied in Utilities.!Manuals on a ROOL disc image, and probably similarly on other disc images.

The documentation beyond very simple stuff is in a dire state though, you still need to refer back to old versions of the SWIs to find out what some of them actually do and what numbers mean, and the “Primer” section is just wrong in many places.

There is a StrongHelp file tucked away on github.

That’s the same one that’s included in the ROOL etc. disc image, I think. At first glance it’s certainly no more clear or correct!

So to the specific problem.
I have some hardware that produces timing pulses on two of the GPIO lines, and software that polls these lines from TickerV in order to do some event timing.
The code first sets up the pins using the following:

REM clear existing events
SYS “GPIO_WriteEvent”,startpin%,0
SYS “GPIO_WriteEvent”,finishpin%,0


I’m having problems with spurious events. The hardware is connected to GPIO 6 and 5. (Note that for test, I’m using 6 and 7 above – see later)
With 6 and 5 connected, initialised and monitored, I get 1 or 2 spurious events per day, and they occur 90% of the time on both pins simultaneously (i.e in the same cSec pass). In order to determine whether this is coming from my hardware, or something else I changed to using 6 and 7, where there is nothing connected to 7. I expected to get pulses on 6, and not 7, if it was a problems with my hardware.

Instead if I initialist 7 as above, I immediately get continuous detections on 7, and none on 6. The same happens if I use 8 instead of 7.
If I don’t initialise 7, but do monitor it, there are no spurious pulses on 7, and only the 1-2 per day on 6 as expected.

This leads me to suspect I’m initialising the pins incorrectly. As in the comments, I want them as inputs, with pull-ups and triggering on a falling edge. I can’t find remember I got the information about which bits to set to achieve that. I suspect the default is what I actually need – but WHY does it work almost perfectly if I initialise and monitor the pins with hardware connected, and goes wild if I use a pin with nothing connected.

It’s a PI3b+.

I have also tried the same code on a PI 1B with no external hardware, and no pulses are detected.

Both RPIs are running RO 5.28. Is there a significant hardware difference between the GPIO on a PI 3 vs a PI 1?

There is a StrongHelp file tucked away on github.

The path there references “Tankstage”. I suspect therefore it’s for the early module written by Tank, which has been replaced by an “Official” one, with a different API.

Alan, do you only get the spurious events when running another app that’s foreground polling as well as in your earlier thread? https://www.riscosopen.org/forum/forums/11/topics/16850

Alan, do you only get the spurious events when running another app that’s foreground polling as well as in your earlier thread?

Good question. I’ll do some testing.

If I initialise and monitor one of the pins with nothing connected, I still get the continuous events on that pin. I’ll leave it running monitoring the two connected pins and see what happens over the next few days.

My current suspicion is that it’s to do with the 3 volt supply from the rPi, which I’m using to feed the last stage of the hardware that drives the pins. I’m wondering whether decoupling that would help, but I don’t want to upset the pi by, for example, drawing a large current surge at switch-on.

Does anyone know what voltage a GPIO pin needs to be pulled down to? I’m thinking of using a diode in series to isolate the pin from some effects, but that means that a low level will be around 1 volt.

There seems to be a newer SH for GPIO here: https://gitlab.riscosopen.org/RiscOS/Sources/HWSupport/GPIO/-/blob/master/Docs/GPIO,3d6

The magic values for the mode control bits don’t seem to be in a header; they’re defined in gpio.c in the Sources/HWSupport/GPIO dir, where you’ll also see how they’re used. [Strangely I can’t see this particular source file on GitLab though it is in the source tarball…]

@Alan: You aren’t enabling the pullups – set bit 5 as well.

Alas, my Pi 3B is happily doing something else so I can’t build/test on that.

There seems to be a newer SH for GPIO here:

That’s still for the obsolete module.

I’ve done a bit more testing. As I said, if I initialise and monitor GPIO 7 or 8, I get continuous events. However checking one of the many (and inconsistent) pinout diagrams, I see that are shown as (CE0) and (CE1). I tried GPIO 17 instead, which seems to be a GPIO pin by default, and got no spurious events. This makes me more certain that I’m not initialising correctly. As I said in the earlier thread, trying to use GPIO 4 gave spurious events, and that pin too seems to have other uses.

Where can I find the definition of bits to set for the GPIO_WriteMode SWI?

Missing the pull-up bit would make sense, as I had to add an external pull-up resistor.

they’re defined in gpio.c in the Sources/HWSupport/GPIO dir, where you’ll also see how they’re used.

So I followed your link, backed up to the GPIO directory, but gpio.c isn’t there.

So I followed your link, backed up to the GPIO directory, but gpio.c isn’t there.

Confusing, huh? Just grab the current BCM2835Dev tarball from https://www.riscosopen.org/content/downloads/risc-os-tarballs – lo and behold… Perhaps it’s copied from somewhere else!?!

Thanks. The tarball not only contains the gpio.c file, but also, in Docs, a GPIO Stronghelp file which is up to date. It seems suspiciously familiar, which leads me to think that someone found me a copy a couple of years ago when I first wrote this stuff.

Do you set up any GPIO in your config/txt? I see that the HAL GPIO assumes an initial state for the GPIO pullup/down/enable which may not be 100% correct if something in the boot process has fiddled with it. The HAL GPIO keeps a soft copy of the state so that when a SWI GPIO_WriteMode calls through to the HAL, it compares the desired pullup/down/enable state for a pin with the current soft state and does nothing if it’s already the same. Which it might not be if a gpio directive has been encountered.

Perhaps it’s copied from somewhere else!?!

You can find a later one by navigating to https://gitlab.riscosopen.org/RiscOS/Sources/HWSupport/GPIO/-/blob/HAL/Docs/GPIO,3d6 (it’s hidden in the HAL branch, not Master).

EDIT: That is of course the StrongHelp manual, not the C source. But GPIO.c is only a few mouse clicks away, now that you’re in the HAL branch.

Both those Stronghelp files seem to contain the same information.

I’m a little confused – the description of WriteMode says R1 should have pin info in the lowets 5 bits, but the examples have those bits as zero.

Now that I’ve enabled pull-up/down as well as defining it as pull-up, it’s stopped the random events on pins with no hardware connected. Obviously they were floating and picking up noise. It makes me think I ought to do the same for all the inputs that I’m not using.

There’s nothing in config/txt that refers to GPIO.

Best stick to reading the source, Alan. The doc is sh*te.

Best stick to reading the source, Alan. The doc is sh*te.

Agree about the docs. However C is not something I find readable.

Having tried – the mystery deepens. As far as I can see, the WriteMode SWI is masking off the mode requested, allowing only bits 0 to 4. However the mode should be contained in bits 5 to 9. ???

I also can’t work out where anything actually executes – it looks like a lot of things are being moved around in memory, but where it is being sent to the hardware?

For example, what does device->dev.Activate(&device->dev)) actually do?

I well remember C being described as a “write-only language”.

I’m a little confused – the description of WriteMode says R1 should have pin info in the lowets 5 bits, but the examples have those bits as zero.

When you enumerated the pin, you got back a pin info descriptor, right? In StrongHelp, click on the highlighted pin info link or go direct from GPIO_Info.

I’m unsure whether you’re interested in making it input or output, but in the pin info descriptor you’ll find an entry for GPIO, and the 5 mode bits needed for GPIO_WriteMode. In StrongHelp the 5 mode bits are linked back to GPIO_WriteMode for fun circularity.

The examples presumably refer to a Raspberry Pi, where by chance GPIO mode needs 0 in those bits (as the pin info descriptor would tell you), other platforms may need other values. Rather than ferreting though C code this seems more like a case of having read the docs but not yet understood them – the words are all there in the 2 pages ‘GPIO_WriteMode’ and ‘Pin information structure’.

The examples presumably refer to a Raspberry Pi, where by chance GPIO mode needs 0 in those bits (as the pin info descriptor would tell you), other platforms may need other values.

Thanks. That at least explains the confusion.

I’ve not needed to enumerate the pins, as I already know the pin numbers I want to use. As you say, in the examples those bits are zero, and that worked for me as I’m also on RPI.

The underlying problem is that the information on the ROOL pages, under Documentation, only has descriptions for two of the ten SWIs. The others are simply placeholders. The StrongHelp file seems to be tucked away in the source tree, not in a public place. And it could do with clarification.

The StrongHelp file seems to be tucked away in the source tree, not in a public place.

Say what now? It’s provided on every copy of the official RISC OS Pi image. I’m baffled why anyone would attempt to go rummaging in Git as the first option, that’s a path of great pain for little gain.

And it could do with clarification.

If you think something needs clarification just Menu click on the page, select Edit page and start typing, email the result to ROOL (avoids having to mess about with Git). Job done.

And since we’re going down that line, I’d also note (as someone else did to me the other week) that with respect to…

The underlying problem is that the information on the ROOL pages, under Documentation, only has descriptions for two of the ten SWIs.

…the ROOL Wiki is a Wiki, so anyone can add or edit pages as they think is required. If you see something that needs improvement, improve it!