GPIO documentation

Say what now? It’s provided on every copy of the official RISC OS Pi image.

Thanks.

I spent some time trying to find the GPIO help file and failed. Then I looked more closely at your picture, and tried something I’ve not done before – I ran the StrongHelp program and then clicked on its iconbar icon. Usually I double-click on a StrongHelp file, or use Help from within an application.

It’s probably down to my preference – paper manuals such as the PRMs first, then online equivalents, and as a last resort StrongHelp.

Now the question is how to find the actual help file, as I want to copy it into StrongHelp on my Armx6, which doesn’t include it.

Meanwhile I tried Edit Page – nothing happened.

Now the question is how to find the actual help file, as I want to copy it into StrongHelp on my Armx6, which doesn’t include it.

It’s very likely to be in the !Manuals application, which is probably in $.!Boot.Resources.

One of the ideas of StrongHelp was that “global” manuals would be stored in this central resource, so that they are immediately accessible from StrongHelp (bear in mind that it was originally conceived as a way to do context-sensitive help in text editors, amongst other things). The manuals can be arranged in folders, too, and the StrongHelp GUI respects this as well.

It’s very likely to be in the !Manuals application, which is probably in $.!Boot.Resources.

I wouldn’t have found that. Thanks for the pointer.

[Edit]

It’s in resources on the ARMX6, and in Utilities on the RPi.

Interestingly, if I click on Edit Page on the ARMX6 it opens in StrongED.

If I click Edit Page on the rPi nothing happens. The default editor there is !Edit. I assume the lack of Throwback is the cause. If I run StrongED first, then it can be edited.

I’ve attempted to update some of the Wiki pages, but for the other pages I’ve not done I think it needs someone who a) understands the Wiki markup language better, and perhaps more importantly, b) someone who actually understands how the ReadMode/WriteMode/Info SWis actually work and can explain it in a way mere mortals can understand (hint, the SH manual is NOT comprehensible here).

As it was me editing the Wiki, someone else should probably go back and check it as I’m sure I will have done it ‘wrong’ to some extent.

Whilst we’re talking about the StrongHelp manual, why doesn’t it give any idication of a version number? It’s impossible to tell if the version you have is later or earlier than any other version. Most other SH manuals have a version number displayed somewhere.

Whilst we’re talking about the StrongHelp manual, why doesn’t it give any indication of a version number? It’s impossible to tell if the version you have is later or earlier than any other version. Most other SH manuals have a version number displayed somewhere.

And given that there are two incompatible GPIO modules around, it’s especially important in this case.

I’m tempted to have a look at writing some more descriptive documentation, though I’m not sure how to either add it to the Wiki (markup etc), or to the StrongHelp.

I think for exampke understanding WriteMode will require looking at the 200+ page Broadcom manual for the hardware. The StrongHelp manual documents the bits and their effect, but assumes the pin has been set as input. What happens on an output? Is there still a pull-up/down option? Can it trigger an event if its output state is changed?

I did spend some time with that manual when trying to use the GPIO in an ARMX6, which exists, but is not supported by the GPIO module.

It’s going to be interesting. GPIO_WriteMode seems to alter bits in several separate registers, so I would also have to understand the source code, where that mapping must be taking place. At the moment I’m finding the hardware documentation easier to understand than anything written in C.

54 GPIO pins, grouped together into a smaller number of registers, with a 1-bit or 3-bit selector for the pin number within the register. One register group decides input, output or alternate function number, another sets output high or low, another supplies the current level read from the pin, another two pullup/down enabled, and which way, others for edge/state detection, rising falling, high,low…

The point of the GPIO module is to offer an API that is consistent across all the platforms that it supports. This is not easy, as different chips have to be driven differently – for example, the code bits to set a particular function are not the same across all chips. The module, therefore, has to provide a means to look up those bits.

While I agree that the SH manual is not as clear is it could or should be, it’s untrue to say that it’s not comprehensible, because I’ve been there and used it to write stuff for use at home.

As for editing the Wiki, there are plenty of examples to look at (all you need to do is start to edit a page without making any changes – you can see all the markup – then cancel the edit without making any change). Again, been there, done that, lots of trial, almost as much error, just don’t give up until you have succeeded. And try just paragraphs of plain text before you launch into tables.

So I’ve written a few notes, which would I think make a useful introduction to the GPIO SWI definitions. See below. I can clarify some of these points in the future by experimenting, at least for RPI implementations. The RPI uses the BCM2835 GPIO, and the following refers to the datasheet for that.

GPIO notes

The GPIO module allows access to a small subset of the GPIO hardware’s capabilities.

GPIO_WriteOE uses values of 0 and 1 to select input or output for a pin. The register that this goes to can also take values from 2 to 7, to select one of 6 possible alternative functions, such as hardware-generated clocks. It is not clear whether these can be selected using the GPIO module. This can probably be determined by experiment.

The GPIO can be set up to generate interrupts to the ARM processor. This facility is not available via the GPIO module.
Events which would have caused an interrupt can be detected by polling with GPIO_ReadEvent, and cleared by writing 1 to GPIO_WriteEvent.

GPIO_WriteMode can supply setup information for the pin functions. As an input the pin can be set to generate an event when the input voltage is low, is high, goes from low to high, or goes from high to low. The hardware also has the capability to apply hysteresis to the pin, so that the low voltage threshold is lower than the high voltage threshold. This can help to eliminate multiple events when the signal is noisy. This feature is not available via the GPIO module.

It is not clear (requires experiment) whether input events can be caused by an output pin changing state.

GPIO_WriteMode can also specify whether a pullup or pulldown load is applied to the input, or whether it is left floating.

It is not clear whether the pullup-pulldown is also applied when the pin is defined as an output. While it would be somewhat illogical to do so, the functional diagram for a pin suggests that it is applied if configured. It would be wise therefore when defining an output pin, to clear mode bit 5 (pull enable).

The hardware when used as an output can have various drive levels set, from 1 to 16mA. (Note that these are not current limits – it’s still possible to source or sink damaging currents when these are set.) The GPIO module doesn’t provide access to this function, so the default drive level must be assumed.

So my setup has shown up something odd. I can’t be sure whether it’s hardware or software induced.

Pulses are sent to two of the GPIO pins from a pair of retriggerable 74123 monostables which act as debounce, by stretching the incoming pulse to around half a second in duration. Most of the time this works fine. The pins are set to generate an event on a falling edge.

The polling code, which runs from TickerV, checks each pin for an event. If it finds one it clears the event for that pin and records a timestamp. This works for pulses arriving simultaneously on both pins, and for pulses arriving with a separation greater than 2 centiseconds.

However if the pulses on the two channels arrive separated by one or two centiseconds I get a double reading. The first pulse is recorded, then on the next TickerV cycle, when the second one arrives I get the first one repeated.

My first thought was that this could occur if there was a delay within the GPIO hardware clearing the event. However if that was the case then every incoming pulse would be doubled.

I can’t see a way for cross-talk to occur in the electronics. The 74123 has been around for decades, and if this produced spurious outputs, I’m sure it would have been fixed. I’ve tried several different circuits driving the pins, and ended up with the simplest one. The pins have a pull-up enabled, and a diode goes to the monostable output, which pulls down the pin. (It can’t feed the 5 volt logic high to the pin, due to the diode). Previous circuits used a level-shifting transistor to the 3.3 volt line with or without an isolating diode. All these give the same effect.

I don’t have a digital storage scope, so I can’t see what’s happening at the pins by that route.

The circuit diagram (zipped draw file) is here:
http://www.adamshome.org.uk/RiscOS/hardware.zip

Here’s the code that runs once for each TickerV entry.

DEF FNtestpin(pass%)
[OPT pass%
; R12 points to data space. Pollword is first entry there
; R7 counts events handled in this pass of isr
; R6 returns the bitmask for the events found
;
; did a pin cause an event?
                mov r6,#0           ; CLEAR bit mask
                mov r7,#0           ; clear count
                mov r0,#startpin%   ; try this pin
                FNswi("XGPIO_ReadEvent")
                bvs isr_error       ; clean up AND exit ISR
                cmp r0,#1           ; RETURN 1 IF active, but 0 if not
                bne nextpin
                ;
                add r7,r7,#1        ; increment COUNT OF events
                orr r6,r6,#startmask%
                mov r0,#startpin%   ; reset the event
                mov r1,#0           ; CLEAR it
                FNswi("XGPIO_WriteEvent")
                bvs isr_error       ; clean up AND exit ISR
.nextpin
                mov r0,#finishpin%  ; try this pin
                FNswi("XGPIO_ReadEvent") ; test
                bvs isr_error       ; clean up and exit ISR
                cmp r0,#1           ; RETURN 1 IF active, but 0 if not
                bne testpin_exit         ; all done
                ;
                add r7,r7,#1        ; increment COUNT OF events
                orr r6,r6,#finishmask%
                mov r0,#finishpin%  ; reset the event
                mov r1,#0           ; CLEAR it
                FNswi("XGPIO_WriteEvent")
                bvs isr_error       ; clean up and exit ISR
.testpin_exit
                ldr r5,[r12]        ; GET current pollword
                orr r6,r6,r5        ; add in the bits FOR this pass
                str r6,[r12]        ; store back
]
=""