drivers: video: migrate to use video-interfaces binding

josuah commented 4 weeks ago

Describe the situation

Following https://github.com/zephyrproject-rtos/zephyr/pull/74415, video drivers are in the middle of a migration away from an ad-hoc devicetree API.

Migration to use the video-interfaces binding is strongly recommended because of the following benefices:

We can actually use the remote-endpoint-label to retrieve the peer remote device object in the driver without the need of redundant direct phandle reference in DT.
We can avoid some sort of chicken-egg issue due to direct phandle reference as described here.
We can use the common properties defined in the video-interfaces binding to avoid declaring so many vendor custom properties in each vendor binding.

With the new video-interfaces binding, remote-endpoint must be replaced by remote-endpoint-label in the devicetree. The reason for it was https://github.com/zephyrproject-rtos/zephyr/issues/57708 and the workaround is https://github.com/zephyrproject-rtos/zephyr/pull/74415. A final conversion from remote-endpoint-label to remote-endpoint will need to happen once #57708 is addressed, but will be trivial to propagate.

Old API, drivers that need conversion

&source_dev {
        status = "okay";
};

&sink_dev {
        source = <&source_dev>;
        /* or */
        sensor = <&source_dev>;
        /* or nothing */
};

New API, drivers that got converted

&source_dev {
        status = "okay";
        port {
                source_dev_ep_out: endpoint {
                        remote-endpoint-label = "sink_dev_ep_in";
                };
        };
};

&sink_dev {
        port {
                sink_dev_ep_in: endpoint {
                        remote-endpoint-label = "source_dev_ep_out";
                };
        };
};

Impact

Need to also convert the board and shields
Only one API through the sources, more similar to Linux.
A stable API that covers complex situations.

Additional context

Zephyr v4.0 is in feature-freeze: not possible to rush every vendor to complete the migration of their driver in time.

This can be done gradually as here, as commented in the following PR, for example:

https://github.com/zephyrproject-rtos/zephyr/pull/79334

josuah commented 4 weeks ago

It might not be required to push any bugfix for v4.0.0:

Currently, the sensor drivers do not do anything with the remote-endpoint-label, so passing them remote-endpoint-label = "unused"; will work with MIPI/DVP controllers with the old API: not ideal but not broken.

Also, as pointed-out here, adding the remote-endpoint-label is not expected to break the compilation.

ngphibang commented 4 weeks ago

Thanks @josuah for creating the issue. I made some modifications in the description. Since it is not considered as "bug" with the current situation (i.e. declare remote-endpoint in DT but not use it in drivers and declare redundant phandle references source / sensor dev in DT) so I removed the bug label.

remote-endpoint is declared in some dts but not actually used in any Zephyr driver. And while we don't declare a binding for the endpoint, declaring or not the remote-endpoint or anything else doesn't matter, it still compiles.

However, migration to use the video-interfaces binding is strongly recommended because of the following benefits:

We can actually use the remote-endpoint-label to retrieve the peer remote device object in the driver without the need of extra direct phandle reference.
We can avoid some sort of chicken-egg issue due to direct phandle reference as described here.
We can use the common properties in the video-interfaces binding to avoid declaring so many vendor custom properties in each vendor binding.

zephyrproject-rtos / zephyr

drivers: video: migrate to use video-interfaces binding #80514