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

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

 



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




[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