Hi Laurent,
On Sun, Aug 25, 2024 at 01:18:13AM +0300, Laurent Pinchart wrote:
> 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().
I missed earlier the pipeline traversal is its own section. Still, the
graph traversal itself is gone as a public API in the documentation. How
about e.g.:
- Accessing graph objects
- Working with graph objects
>
> > 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,
Sakari Ailus
