docs: pio_gpio_init claims it's not *needed* to enable input to a PIO

[Gadgetoid]

The comment (and by extension docs?) for pio_gpio_init states:

Note that this is not necessary for a state machine to be able to read the input value from a GPIO, but only for it to set the output value or output enable.

I think this is wrong on RP2350, which needs pio_gpio_init to call gpio_set_function which enables input and - crucially? - disables pad isolation?

pico-sdk/src/rp2_common/hardware_pio/include/hardware/pio.h

Lines 870 to 886 in ee68c78

	/*! \brief Setup the function select for a GPIO to use output from the given PIO instance
	* \ingroup hardware_pio
	*
	* PIO appears as an alternate function in the GPIO muxing, just like an SPI
	* or UART. This function configures that multiplexing to connect a given PIO
	* instance to a GPIO. Note that this is not necessary for a state machine to
	* be able to read the *input* value from a GPIO, but only for it to set the
	* output value or output enable.
	*
	* \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
	* \param pin the GPIO pin whose function select to set
	*/
	static inline void pio_gpio_init(PIO pio, uint pin) {
	check_pio_param(pio);
	valid_params_if(HARDWARE_PIO, pin < NUM_BANK0_GPIOS);
	gpio_set_function(pin, PIO_FUNCSEL_NUM(pio, pin));
	}

[lurch]

I believe that the intention behind the "this is not necessary for a state machine to be able to read the input value from a GPIO" comment is that you can use PIO input to "sniff" the values being read/written to the GPIO pin from another function-mode (e.g. you could use PIO input to sniff the UART TX). But if you haven't configured any other function-mode onto the GPIO pin, then I guess it would indeed make sense to use gpio_set_function to set PIO input? (This is just me guessing, until Graham is able to provide a definitive answer 😉 )

[Gadgetoid]

Thank you. I suspect the answer might well be "you should explicitly set up your pin as an input", but either way the documentation could probably be clearer about that!

( I stumbled into this looking into a MicroPython issue with the PIO's jmp_pin, where it worked fine on RP2040 but not RP2350... this is because the pin is never explicitly set-up. I need to figure out if I should call pio_gpio_init in both cases for this pin, or change the MicroPython docs to mention user must configure the pin 😆 )

( Nobody would ever want a jump pin as an output right.... right!? )

[lurch]

Be aware that if you change the docs to say "must configure the pin" then you might run into problems like #1601