Re: [PATCH 4/4] media: Documentation: mc: Replace deprecated graph walk API

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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




[Index of Archives]     [Linux Input]     [Video for Linux]     [Gstreamer Embedded]     [Mplayer Users]     [Linux USB Devel]     [Linux Audio Users]     [Linux Kernel]     [Linux SCSI]     [Yosemite Backpacking]

  Powered by Linux