Merge branch 'linus' of git://git.kernel.org/pub/scm/linux/kernel/git/herbert/crypto-2.6
[linux/fpc-iii.git] / Documentation / media / uapi / mediactl / media-ioc-enum-links.rst
blobd05be16ffaf66d6e5da9a73ad28ceb925dacf69a
1 .. -*- coding: utf-8; mode: rst -*-
3 .. _media_ioc_enum_links:
5 **************************
6 ioctl MEDIA_IOC_ENUM_LINKS
7 **************************
9 Name
10 ====
12 MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity
15 Synopsis
16 ========
18 .. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *argp )
19     :name: MEDIA_IOC_ENUM_LINKS
22 Arguments
23 =========
25 ``fd``
26     File descriptor returned by :ref:`open() <media-func-open>`.
28 ``argp``
31 Description
32 ===========
34 To enumerate pads and/or links for a given entity, applications set the
35 entity field of a struct :c:type:`media_links_enum`
36 structure and initialize the struct
37 :c:type:`media_pad_desc` and struct
38 :c:type:`media_link_desc` structure arrays pointed by
39 the ``pads`` and ``links`` fields. They then call the
40 MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this structure.
42 If the ``pads`` field is not NULL, the driver fills the ``pads`` array
43 with information about the entity's pads. The array must have enough
44 room to store all the entity's pads. The number of pads can be retrieved
45 with :ref:`MEDIA_IOC_ENUM_ENTITIES`.
47 If the ``links`` field is not NULL, the driver fills the ``links`` array
48 with information about the entity's outbound links. The array must have
49 enough room to store all the entity's outbound links. The number of
50 outbound links can be retrieved with :ref:`MEDIA_IOC_ENUM_ENTITIES`.
52 Only forward links that originate at one of the entity's source pads are
53 returned during the enumeration process.
56 .. c:type:: media_links_enum
58 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
60 .. flat-table:: struct media_links_enum
61     :header-rows:  0
62     :stub-columns: 0
63     :widths:       1 1 2
66     -  .. row 1
68        -  __u32
70        -  ``entity``
72        -  Entity id, set by the application.
74     -  .. row 2
76        -  struct :c:type:`media_pad_desc`
78        -  \*\ ``pads``
80        -  Pointer to a pads array allocated by the application. Ignored if
81           NULL.
83     -  .. row 3
85        -  struct :c:type:`media_link_desc`
87        -  \*\ ``links``
89        -  Pointer to a links array allocated by the application. Ignored if
90           NULL.
94 .. c:type:: media_pad_desc
96 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
98 .. flat-table:: struct media_pad_desc
99     :header-rows:  0
100     :stub-columns: 0
101     :widths:       1 1 2
104     -  .. row 1
106        -  __u32
108        -  ``entity``
110        -  ID of the entity this pad belongs to.
112     -  .. row 2
114        -  __u16
116        -  ``index``
118        -  0-based pad index.
120     -  .. row 3
122        -  __u32
124        -  ``flags``
126        -  Pad flags, see :ref:`media-pad-flag` for more details.
130 .. c:type:: media_link_desc
132 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
134 .. flat-table:: struct media_link_desc
135     :header-rows:  0
136     :stub-columns: 0
137     :widths:       1 1 2
140     -  .. row 1
142        -  struct :c:type:`media_pad_desc`
144        -  ``source``
146        -  Pad at the origin of this link.
148     -  .. row 2
150        -  struct :c:type:`media_pad_desc`
152        -  ``sink``
154        -  Pad at the target of this link.
156     -  .. row 3
158        -  __u32
160        -  ``flags``
162        -  Link flags, see :ref:`media-link-flag` for more details.
165 Return Value
166 ============
168 On success 0 is returned, on error -1 and the ``errno`` variable is set
169 appropriately. The generic error codes are described at the
170 :ref:`Generic Error Codes <gen-errors>` chapter.
172 EINVAL
173     The struct :c:type:`media_links_enum` ``id``
174     references a non-existing entity.