Add generic IOCTL-like method to board

[bablokb]

There are a number of boards available that have special features not well covered by existing modules. Or some attributes are transient during boot and must be captured very early during board initialization. Another example is updating large LUTs.

Instead of inflating the board module with very specific methods, it might be better to add a generic method that is modeled more like the ioctl system call on Linux (note: I wouldn't call it ioctl). The method could take an int and optional bytes and return bytes. As far as I understand there could be a noop default using MP_WEAK so most boards would not have to implement the method.

If this is something you think is useful I would try to implement a first draft version.

[tannewt]

I wouldn't add a generic method because it is hard to document in the standard python way.

Instead, an LLM will make quick work of adding board specific accessors. What specific things did you have in mind?

[bablokb]

Instead, an LLM will make quick work of adding board specific accessors

I don't understand that. In my understanding, to be accessible from Python a method has to be defined in shared-bindings/board/__init__.*. So these board specific accessors would bloat the board implementation. And how would an LLM make a difference here compared to classical coding?!

it is hard to document in the standard python way.

Another thing I don't understand. A generic method that takes an int and a byte-sequence and returns a byte-sequence is as easy to document as any other method withing shared-bindings.

What specific things did you have in mind?

Most of the Pimoroni boards have some very intelligent hardware, that cannot be used by CP. These boards wake up by a button, but with CP the user has to press three seconds instead of jut tap them. And some designs have these buttons behind a shift-register, and the current implementation in CP cannot capture the state at power on. And then there a displays with different LUTs, that cannot be changed by update_refresh_mode(), since writing these LUTs is independent of the init-sequences (they are large blobs of binary data).

[tannewt]

In my understanding, to be accessible from Python a method has to be defined in shared-bindings/board/__init__.*. So these board specific accessors would bloat the board implementation.

The attributes on board module are set by the board in (misnamed) pins.c within the board directory. So, within that directory you can add special functions or objects.

The new yoto boards do this dynamically by setting values in board_init(): https://github.com/adafruit/circuitpython/blob/main/ports/espressif/boards/yoto_mini_2024/

Another thing I don't understand. A generic method that takes an int and a byte-sequence and returns a byte-sequence is as easy to document as any other method withing shared-bindings.

I disagree. A specific method ends up with a stub and doc string. The params can have names instead of being generic. IOCTL like ones usually abstract away the meaning of the int and byte sequence.

These boards wake up by a button, but with CP the user has to press three seconds instead of jut tap them.

Why is this? I don't know the specifics. Does board_init() need to do more?

And some designs have these buttons behind a shift-register, and the current implementation in CP cannot capture the state at power on.

Again, can't code in board_init() do this?

And then there a displays with different LUTs, that cannot be changed by update_refresh_mode(), since writing these LUTs is independent of the init-sequences (they are large blobs of binary data).

What types of displays are these? Wouldn't this be better done by expanding the API of the specific display type?

[bablokb]

The attributes on board module are set by the board in (misnamed) pins.c within the board directory. So, within that directory you can add special functions or objects.

I did not know about that. This sounds promising, although I did not find an example on how to add a function that takes arguments. Any pointers?! If the pins.c-method works, the generic IOCTL is indeed not necessary.

I disagree. A specific method ends up with a stub and doc string. The params can have names instead of being generic.

What about rtc.calibration? This is also generic and is documented as hardware-specific.

Why is this? I don't know the specifics. Does board_init() need to do more?

board_init() is too late. You can capture early state with static constructors that run before main(), e.g.:

static void get_btn_state(void) __attribute__((constructor(101)));

This would save the state, which then could be read by a board-attribute.

What types of displays are these? Wouldn't this be better done by expanding the API of the specific display type?

Of course you could add a method like EPaperDisplay.update_lut(). But then you would have to maintain and pass in byte-blobs from Python side. For boards with an integrated display it would be easier from user-side if it is just encapsulated into the board definition, e.g.

board.refresh_speed(board.SPEED_FAST)

[tannewt]

Any pointers?!

Yup! Look in shared-bindings. The classes and modules there have similar tables that point to the objects. (Created by macros that take in a function pointer to a corresponding C function.)

This would save the state, which then could be read by a board-attribute.
👍

What about rtc.calibration? This is also generic and is documented as hardware-specific.

This still feels more specific to me than an IOCTL with magic numbers as args.

For boards with an integrated display it would be easier from user-side if it is just encapsulated into the board definition, e.g.

Yup, I agree. I was going to argue that it should be on the driver IC display object to match how the driver IC library would have it. However, it really is a function of the display and not just the driver. This is board-specific enough I think it is fine to add it to board. Note that you can add a sub-module using patterns from shared-bindings to scope the constants if you want. So board.display.SPEED_FAST for example. Adding it to DISPLAY would be trickier.