Documentation patches for the MC next gen
Subsystems (2)
cover Documentation patches for the MC next gen
Those patches complete the kernel-doc for the dvbdev changes and documents the uAPI defined by the media controller next generation.
Mauro Carvalho Chehab (6):
dvbdev: Document the new MC-related fields
[media] DocBook: MC: add the concept of interfaces [media] DocBook: move data types to a separate section [media] Docbook: media-types.xml: update the existing tables [media] DocBook: add a table for Media Controller interfaces [media] DocBook: Document MEDIA_IOC_G_TOPOLOGY
.../DocBook/media/v4l/media-controller.xml | 44 ++- .../DocBook/media/v4l/media-ioc-enum-entities.xml | 104 ------ .../DocBook/media/v4l/media-ioc-enum-links.xml | 56 --- .../DocBook/media/v4l/media-ioc-g-topology.xml | 391 +++++++++++++++++++++ Documentation/DocBook/media/v4l/media-types.xml | 240 +++++++++++++ drivers/media/dvb-core/dvbdev.h | 12 +- 6 files changed, 671 insertions(+), 176 deletions(-) create mode 100644 Documentation/DocBook/media/v4l/media-ioc-g-topology.xml create mode 100644 Documentation/DocBook/media/v4l/media-types.xml
Signature · 1 line
2.5.0
PATCH 1/6 dvbdev: Document the new MC-related fields
The Media Controller next gen patchset added several new fields to be used with it. Document them.
Signed-off-by Mauro Carvalho Chehab <[email protected]>
--- drivers/media/dvb-core/dvbdev.h | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-)
drivers/media/dvb-core/dvbdev.h +10 -2
@@ -120,6 +120,11 @@ struct dvb_adapter {* @entity: pointer to struct media_entity associated with the device node * @pads: pointer to struct media_pad associated with @entity; * @priv: private data +* @intf_devnode: Pointer to media_intf_devnode. Used by the dvbdev core to +* store the MC device node interface +* @tsout_num_entities: Number of Transport Stream output entities +* @tsout_entity: array with MC entities associated to each TS output node +* @tsout_pads: array with the source pads for each @tsout_entity * * This structure is used by the DVB core (frontend, CA, net, demux) in * order to create the device nodes. Usually, driver should not initialize
@@ -188,8 +193,11 @@ int dvb_unregister_adapter(struct dvb_adapter *adap);* stored * @template: Template used to create &pdvbdev; * @priv: private data -* @type: type of the device: DVB_DEVICE_SEC, DVB_DEVICE_FRONTEND, -* DVB_DEVICE_DEMUX, DVB_DEVICE_DVR, DVB_DEVICE_CA, DVB_DEVICE_NET +* @type: type of the device: %DVB_DEVICE_SEC, %DVB_DEVICE_FRONTEND, +* %DVB_DEVICE_DEMUX, %DVB_DEVICE_DVR, %DVB_DEVICE_CA, +* %DVB_DEVICE_NET +* @demux_sink_pads: Number of demux outputs, to be used to create the TS +* outputs via the Media Controller. */ int dvb_register_device(struct dvb_adapter *adap, struct dvb_device **pdvbdev,
Signature · 1 line
2.5.0
PATCH 2/6 DocBook: MC: add the concept of interfaces
In reply to Mauro Carvalho ChehabThe Media Controller next generation patches added a new graph element type: interfaces. It also allows links between interfaces and entities. Update the docbook to reflect that.
Signed-off-by Mauro Carvalho Chehab <[email protected]>
--- .../DocBook/media/v4l/media-controller.xml | 40 ++++++++++++++-------- 1 file changed, 26 insertions(+), 14 deletions(-)
Documentation/DocBook/media/v4l/media-controller.xml +26 -14
@@ -58,20 +58,32 @@ <title>Media device model</title> <para>Discovering a device internal topology, and configuring it at runtime, is one of the goals of the media controller API. To achieve this, hardware - devices are modelled as an oriented graph of building blocks called entities - connected through pads.</para> - <para>An entity is a basic media hardware or software building block. It can - correspond to a large variety of logical blocks such as physical hardware - devices (CMOS sensor for instance), logical hardware devices (a building - block in a System-on-Chip image processing pipeline), DMA channels or - physical connectors.</para> - <para>A pad is a connection endpoint through which an entity can interact - with other entities. Data (not restricted to video) produced by an entity - flows from the entity's output to one or more entity inputs. Pads should not - be confused with physical pins at chip boundaries.</para> - <para>A link is a point-to-point oriented connection between two pads, - either on the same entity or on different entities. Data flows from a source - pad to a sink pad.</para> + devices and Linux Kernel interfaces are modelled as graph objects on + an oriented graph. The object types that constitute the graph are:</para> + <itemizedlist> + <listitem><para>An <emphasis role="bold">entity</emphasis> + is a basic media hardware or software building block. It can correspond to + a large variety of logical blocks such as physical hardware devices + (CMOS sensor for instance), logical hardware devices (a building block in + a System-on-Chip image processing pipeline), DMA channels or physical + connectors.</para></listitem> + <listitem><para>An <emphasis role="bold">interface</emphasis> + is a graph representation of a Linux Kernel userspace API interface, + like a device node or a sysfs file that controls one or more entities + in the graph.</para></listitem> + <listitem><para>A <emphasis role="bold">pad</emphasis> + is a data connection endpoint through which an entity can interact with + other entities. Data (not restricted to video) produced by an entity + flows from the entity's output to one or more entity inputs. Pads should + not be confused with physical pins at chip boundaries.</para></listitem> + <listitem><para>A <emphasis role="bold">data link</emphasis> + is a point-to-point oriented connection between two pads, either on the + same entity or on different entities. Data flows from a source pad to a + sink pad.</para></listitem> + <listitem><para>An <emphasis role="bold">interface link</emphasis> + is a point-to-point bidirectional control connection between a Linux + Kernel interface and an entity.m</para></listitem> + </itemizedlist> </section> </chapter>
Signature · 1 line
2.5.0
PATCH 3/6 DocBook: move data types to a separate section
In reply to Mauro Carvalho ChehabAs MEDIA_IOC_G_TOPOLOGY shares the data types already declared for entities, pads and links, we should move those to a separate part of the document, and use cross-references where needed.
So, move the following tables to a separate section at the DocBook:
media-entity-type
media-entity-flag
media-pad-flag
media-link-flag
Signed-off-by Mauro Carvalho Chehab <[email protected]>
--- .../DocBook/media/v4l/media-controller.xml | 3 + .../DocBook/media/v4l/media-ioc-enum-entities.xml | 104 ------------- .../DocBook/media/v4l/media-ioc-enum-links.xml | 56 ------- Documentation/DocBook/media/v4l/media-types.xml | 166 +++++++++++++++++++++ 4 files changed, 169 insertions(+), 160 deletions(-) create mode 100644 Documentation/DocBook/media/v4l/media-types.xml
Documentation/DocBook/media/v4l/media-controller.xml +3 -0
@@ -85,6 +85,9 @@ Kernel interface and an entity.m</para></listitem> </itemizedlist> </section> + + <!-- All non-ioctl specific data types go here. --> + &sub-media-types; </chapter> <appendix id="media-user-func">
Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml +0 -104
110 lines not on this page · raw message
Documentation/DocBook/media/v4l/media-ioc-enum-links.xml +0 -56
68 lines not on this page · raw message
Documentation/DocBook/media/v4l/media-types.xml new file +166 -0
166 lines not on this page · raw message
Signature · 1 line
2.5.0
PATCH 4/6 Docbook: media-types.xml: update the existing tables
In reply to Mauro Carvalho ChehabThere were some changes on the media types that were not reflected on the types tables. Update them to reflect the upstream changes.
Signed-off-by Mauro Carvalho Chehab <[email protected]>
--- Documentation/DocBook/media/v4l/media-types.xml | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-)
Documentation/DocBook/media/v4l/media-types.xml +14 -1
@@ -33,7 +33,7 @@ <entry>Digital TV demodulator entity.</entry> </row> <row> - <entry><constant>MEDIA_ENT_F_MPEG_TS_DEMUX</constant></entry> + <entry><constant>MEDIA_ENT_F_TS_DEMUX</constant></entry> <entry>MPEG Transport stream demux entity. Could be implemented on hardware or in Kernelspace by the Linux DVB subsystem.</entry> </row> <row>
@@ -101,6 +101,10 @@ <entry>Default entity for its type. Used to discover the default audio, VBI and video devices, the default camera sensor, ...</entry> </row> + <row> + <entry><constant>MEDIA_ENT_FL_CONNECTOR</constant></entry> + <entry>The entity represents a data conector</entry> + </row> </tbody> </tgroup> </table>
@@ -159,6 +163,15 @@ <entry>The link enabled state can be modified during streaming. This flag is set by drivers and is read-only for applications.</entry> </row> + <row> + <entry><constant>MEDIA_LNK_FL_LINK_TYPE</constant></entry> + <entry><para>This is a bitmask that defines the type of the link. + Currently, two types of links are supported:</para> + <para><constant>MEDIA_LNK_FL_DATA_LINK</constant> + if the link is between two pads</para> + <para><constant>MEDIA_LNK_FL_INTERFACE_LINK</constant> + if the link is between an interface and an entity</para></entry> + </row> </tbody> </tgroup> </table>
Signature · 1 line
2.5.0
PATCH 5/6 DocBook: add a table for Media Controller interfaces
In reply to Mauro Carvalho ChehabDocument the media controller interfaces at the media uAPI docbook.
Signed-off-by Mauro Carvalho Chehab <[email protected]>
--- Documentation/DocBook/media/v4l/media-types.xml | 61 +++++++++++++++++++++++++ 1 file changed, 61 insertions(+)
Documentation/DocBook/media/v4l/media-types.xml +61 -0
@@ -109,6 +109,67 @@ </tgroup> </table> + <table frame="none" pgwide="1" id="media-intf-type"> + <title>Media interface types</title> + <tgroup cols="3"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <colspec colname="c3"/> + <tbody valign="top"> + <row> + <entry><constant>MEDIA_INTF_T_DVB_FE</constant></entry> + <entry>Device node interface for the Digital TV frontend</entry> + <entry>typically, /dev/dvb/adapter?/frontend?</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_DVB_DEMUX</constant></entry> + <entry>Device node interface for the Digital TV demux</entry> + <entry>typically, /dev/dvb/adapter?/demux?</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_DVB_DVR</constant></entry> + <entry>Device node interface for the Digital TV DVR</entry> + <entry>typically, /dev/dvb/adapter?/dvr?</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_DVB_CA</constant></entry> + <entry>Device node interface for the Digital TV Conditional Access</entry> + <entry>typically, /dev/dvb/adapter?/ca?</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_DVB_FE</constant></entry> + <entry>Device node interface for the Digital TV network control</entry> + <entry>typically, /dev/dvb/adapter?/net?</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_V4L_VIDEO</constant></entry> + <entry>Device node interface for video (V4L)</entry> + <entry>typically, /dev/video?</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_V4L_VBI</constant></entry> + <entry>Device node interface for VBI (V4L)</entry> + <entry>typically, /dev/vbi?</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_V4L_RADIO</constant></entry> + <entry>Device node interface for radio (V4L)</entry> + <entry>typically, /dev/vbi?</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_V4L_SUBDEV</constant></entry> + <entry>Device node interface for a V4L subdevice</entry> + <entry>typically, /dev/v4l-subdev?</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_V4L_SWRADIO</constant></entry> + <entry>Device node interface for Software Defined Radio (V4L)</entry> + <entry>typically, /dev/swradio?</entry> + </row> + </tbody> + </tgroup> + </table> + <table frame="none" pgwide="1" id="media-pad-flag"> <title>Media pad flags</title> <tgroup cols="2">
Signature · 1 line
2.5.0
PATCH 6/6 DocBook: Document MEDIA_IOC_G_TOPOLOGY
In reply to Mauro Carvalho ChehabAdd description for this new media controller ioctl.
Signed-off-by Mauro Carvalho Chehab <[email protected]>
--- .../DocBook/media/v4l/media-controller.xml | 1 + .../DocBook/media/v4l/media-ioc-g-topology.xml | 391 +++++++++++++++++++++ 2 files changed, 392 insertions(+) create mode 100644 Documentation/DocBook/media/v4l/media-ioc-g-topology.xml
Documentation/DocBook/media/v4l/media-controller.xml +1 -0
@@ -98,6 +98,7 @@ &sub-media-func-ioctl; <!-- All ioctls go here. --> &sub-media-ioc-device-info; + &sub-media-ioc-g-topology; &sub-media-ioc-enum-entities; &sub-media-ioc-enum-links; &sub-media-ioc-setup-link;
Documentation/DocBook/media/v4l/media-ioc-g-topology.xml new file +391 -0
391 lines not on this page · raw message
Signature · 1 line
2.5.0