Enhancements to Pico(W) gpio driver

[UncleGrumpy]

Modifies the Pico gpio dirver to accept atoms for the special wl_gpio pins present in the Pico-W.

• Adds support for {wl, 0..1} as output pins in gpio:digital_write/2.
• Adds support for {wl, 2} as an input pin in gpio:digital_read/1.
• Raises error badarg instead of returning error

These changes are made under both the "Apache 2.0" and the "GNU Lesser General
Public License 2.1 or later" license terms (dual license).

SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later

[pguyot]

Does this match gpio module type?
I read pin() is a number or a tuple with an atom and a number.
Should we change the pin() type?

[UncleGrumpy]

Does this match gpio module type? I read pin() is a number or a tuple with an atom and a number. Should we change the pin() type?

Fixed now.

[UncleGrumpy]

Does this match gpio module type? I read pin() is a number or a tuple with an atom and a number. Should we change the pin() type?

Fixed now.

[pguyot]

I'm not convinced returning error tuples is the best semantic, but ERROR_ATOM was also wrong. I would prefer we raise badarg with bad arguments detected before making the platform API call (for example gpio_set_dir) and reserve error tuples for errors from the platform's API.

[UncleGrumpy]

We will need to rewrite the edoc for the driver if we are going to require try catch statement for some of the functions, otherwise deciphering the stack trace and looking up in the source where their code went wrong is a lot more work to decipher than an informative error return.

[pguyot]

This is Erlang, we don't need try / catch but just let the processes die 😁

[fadushin]

In general our pattern has been to raise an error on badarg (see the VALIDATE_VALUE macro, which we use extensively). As far as the docs, I don’t know if we need to fix every function with a @raises entry. OTP doesn’t go that far. And yeah, it’s Erlang, so “let it fail”.

[UncleGrumpy]

I guess I missed the point of #894.

[fadushin]

Here is an example from OTP:

6> try math:cos(srer) catch C:E:S -> {C, E, S} end. 
{error,badarg,
       [{math,cos,
              [srer],
              [{error_info,#{module => erl_stdlib_errors}}]},
        {erl_eval,do_apply,6,[{file,"erl_eval.erl"},{line,689}]},
        {erl_eval,try_clauses,8,[{file,"erl_eval.erl"},{line,919}]},
        {shell,exprs,7,[{file,"shell.erl"},{line,686}]},
        {shell,eval_exprs,7,[{file,"shell.erl"},{line,642}]},
        {shell,eval_loop,3,[{file,"shell.erl"},{line,627}]}]}

And here is the OTP doc: https://www.erlang.org/doc/man/math

(not pointing to OTP as the purveyors of perfect documentation, but…)

[fadushin]

I guess I missed the point of #894.

I think my point there was we need to change error to {error, Reason} in the API spec and behavior for the GPIO interface, which is a breaking API change (hence the new breaking label on the issue). We did something recently for the SPI and I2C interfaces. I am not sure if we looked at UART, as well, but we should.

As far as raising errors, exits, throws, etc (I think we use error), that is a separate issue, yes.

[UncleGrumpy]

But from this conversation it sounds like we want to raise bagarg not return error or {error, Reason}. Personally I think it is better to keep the behavior of the device divers consistent.

[fadushin]

But from this conversation it sounds like we want to raise bagarg not return error or {error, Reason}. Personally I think it is better to keep the behavior of the device divers consistent.

I think @pguyot ’s point (which I agree with) is that we raise errors on any parameter checks the user has supplied. These are almost always the equivalent of calling erlang:error(bardarg).

When we get to the point of implementing the logic of the function (e.g., interfacing with whatever system we are dealing with), and we get an error back from some API (usually an integer code, or something), we encode that error into something meaningful to the user, like an atom, or even a string if it makes sense (though we have to be careful with size, etc), and we return that error as a tuple: {error, Reason}.

I believe this is fairly established OTP behavior, if not AtomVM behavior.

The whole discussion of throw vs return is fraught with debate and not easy to untangle. I think even the idea of try-catch was not without controversy in OTP. Maybe one way to look at it is to distinguish between the kinds of error that are due to the programmer (bad args) and those that are due to the deployment or environment (case {error, Reason}) where the Reason can be logged, or even operated on, programmatically.

[bettio]

What about using the tuple semantic, so we can have {wl, 0} instead of creating new ad-hoc additions to the general semantic?

[fadushin]

I would use a mnemonic define here for -1.

[fadushin]

There is no throw in C. Use the RAISE_ERROR macro

[fadushin]

RAISE_ERROR

[UncleGrumpy]

What about using the tuple semantic, so we can have {wl, 0} instead of creating new ad-hoc additions to the general semantic?

That is a very good point that I didn't even consider... I think that makes a lot more sense, I will go back and make that change.

[UncleGrumpy]

I pushed changes using a pin_tuple rather than atom, and cleaned up a few other places where VALIDATE_VALUE should have been used instead of if clauses.

[pguyot]

I realize a lot of effort has been put in this PR and it is very good work. The pico gpio code was just a draft and the platform will soon have something on par with the others in this domain. Thank you @UncleGrumpy