On Sat, Aug 24, 2024 at 10:10:53PM +0000, Sakari Ailus wrote:
> On Fri, Aug 23, 2024 at 12:24:43AM +0300, Laurent Pinchart wrote:
> > The graph walk API has been deprecated in commit eac564de0915 ("media:
> > mc: entity: Add entity iterator for media_pipeline") in favour of
> > pipelien iterators, but the MC documentation hasn't been updated
> > accordingly. It still documents the deprecated API as the only option.
> > Fix it by dropping the deprecated function, and documenting the new API.
> >
> > Signed-off-by: Laurent Pinchart <laurent.pinchart+renesas@xxxxxxxxxxxxxxxx>
> > ---
> > Documentation/driver-api/media/mc-core.rst | 67 +++++++++++++---------
> > 1 file changed, 41 insertions(+), 26 deletions(-)
> >
> > diff --git a/Documentation/driver-api/media/mc-core.rst b/Documentation/driver-api/media/mc-core.rst
> > index 2456950ce8ff..1d010bd7ec49 100644
> > --- a/Documentation/driver-api/media/mc-core.rst
> > +++ b/Documentation/driver-api/media/mc-core.rst
> > @@ -144,7 +144,8 @@ valid values are described at :c:func:`media_create_pad_link()` and
> > Graph traversal
>
> Perhaps this could be changed as well? The text below still mentions
> traversing graphs but no longer documents the API. Shouldn't we cease to
> mention it as well?
We can rename it. Do you have a proposal for a better name ? The section
documents the API that iterates over all entities/pads/links in the
graph, as well as some functions that perform some form of graph
traversal such as media_pad_remote_pad_first().
> Apart from this,
>
> Acked-by: Sakari Ailus <sakari.ailus@xxxxxxxxxxxxxxx>
>
> > ^^^^^^^^^^^^^^^
> >
> > -The media framework provides APIs to iterate over entities in a graph.
> > +The media framework provides APIs to traverse media graphs, locating connected
> > +entities and links.
> >
> > To iterate over all entities belonging to a media device, drivers can use
> > the media_device_for_each_entity macro, defined in
> > @@ -159,31 +160,6 @@ the media_device_for_each_entity macro, defined in
> > ...
> > }
> >
> > -Drivers might also need to iterate over all entities in a graph that can be
> > -reached only through enabled links starting at a given entity. The media
> > -framework provides a depth-first graph traversal API for that purpose.
> > -
> > -.. note::
> > -
> > - Graphs with cycles (whether directed or undirected) are **NOT**
> > - supported by the graph traversal API. To prevent infinite loops, the graph
> > - traversal code limits the maximum depth to ``MEDIA_ENTITY_ENUM_MAX_DEPTH``,
> > - currently defined as 16.
> > -
> > -Drivers initiate a graph traversal by calling
> > -:c:func:`media_graph_walk_start()`
> > -
> > -The graph structure, provided by the caller, is initialized to start graph
> > -traversal at the given entity.
> > -
> > -Drivers can then retrieve the next entity by calling
> > -:c:func:`media_graph_walk_next()`
> > -
> > -When the graph traversal is complete the function will return ``NULL``.
> > -
> > -Graph traversal can be interrupted at any moment. No cleanup function call
> > -is required and the graph structure can be freed normally.
> > -
> > Helper functions can be used to find a link between two given pads, or a pad
> > connected to another pad through an enabled link
> > (:c:func:`media_entity_find_link()`, :c:func:`media_pad_remote_pad_first()`,
> > @@ -276,6 +252,45 @@ Subsystems should facilitate link validation by providing subsystem specific
> > helper functions to provide easy access for commonly needed information, and
> > in the end provide a way to use driver-specific callbacks.
> >
> > +Pipeline traversal
> > +^^^^^^^^^^^^^^^^^^
> > +
> > +Once a pipeline has been constructed with :c:func:`media_pipeline_start()`,
> > +drivers can iterate over entities or pads in the pipeline with the
> > +:c:macro:´media_pipeline_for_each_entity` and
> > +:c:macro:´media_pipeline_for_each_pad` macros. Iterating over pads is
> > +straightforward:
> > +
> > +.. code-block:: c
> > +
> > + media_pipeline_pad_iter iter;
> > + struct media_pad *pad;
> > +
> > + media_pipeline_for_each_pad(pipe, &iter, pad) {
> > + /* 'pad' will point to each pad in turn */
> > + ...
> > + }
> > +
> > +To iterate over entities, the iterator needs to be initialized and cleaned up
> > +as an additional steps:
> > +
> > +.. code-block:: c
> > +
> > + media_pipeline_entity_iter iter;
> > + struct media_entity *entity;
> > + int ret;
> > +
> > + ret = media_pipeline_entity_iter_init(pipe, &iter);
> > + if (ret)
> > + ...;
> > +
> > + media_pipeline_for_each_entity(pipe, &iter, entity) {
> > + /* 'entity' will point to each entity in turn */
> > + ...
> > + }
> > +
> > + media_pipeline_entity_iter_cleanup(&iter);
> > +
> > Media Controller Device Allocator API
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >
--
Regards,
Laurent Pinchart
