| Message ID | 20240822212445.2037-5-laurent.pinchart+renesas@ideasonboard.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | media: Drop one user of the deprecated graph walk API | expand |
Hi Laurent, 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@ideasonboard.com> > --- > 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? Apart from this, Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com> > ^^^^^^^^^^^^^^^ > > -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 > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ >
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@ideasonboard.com> > > --- > > 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@linux.intel.com> > > > ^^^^^^^^^^^^^^^ > > > > -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 > > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > >
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@ideasonboard.com> > > > --- > > > 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@linux.intel.com> > > > > > ^^^^^^^^^^^^^^^ > > > > > > -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 > > > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > > >
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 ^^^^^^^^^^^^^^^ -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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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@ideasonboard.com> --- Documentation/driver-api/media/mc-core.rst | 67 +++++++++++++--------- 1 file changed, 41 insertions(+), 26 deletions(-)