Documentation/userspace-api/media/v4l/vidioc-subdev-g-routing.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2 .. c:namespace:: V4L
   3
   4 .. _VIDIOC_SUBDEV_G_ROUTING:
   5
   6 ******************************************************
   7 ioctl VIDIOC_SUBDEV_G_ROUTING, VIDIOC_SUBDEV_S_ROUTING
   8 ******************************************************
   9
  10 Name
  11 ====
  12
  13 VIDIOC_SUBDEV_G_ROUTING - VIDIOC_SUBDEV_S_ROUTING - Get or set routing between streams of media pads in a media entity.
  14
  15
  16 Synopsis
  17 ========
  18
  19 .. c:macro:: VIDIOC_SUBDEV_G_ROUTING
  20
  21 ``int ioctl(int fd, VIDIOC_SUBDEV_G_ROUTING, struct v4l2_subdev_routing *argp)``
  22
  23 .. c:macro:: VIDIOC_SUBDEV_S_ROUTING
  24
  25 ``int ioctl(int fd, VIDIOC_SUBDEV_S_ROUTING, struct v4l2_subdev_routing *argp)``
  26
  27 Arguments
  28 =========
  29
  30 ``fd``
  31     File descriptor returned by :ref:`open() <func-open>`.
  32
  33 ``argp``
  34     Pointer to struct :c:type:`v4l2_subdev_routing`.
  35
  36
  37 Description
  38 ===========
  39
  40 These ioctls are used to get and set the routing in a media entity.
  41 The routing configuration determines the flows of data inside an entity.
  42
  43 Drivers report their current routing tables using the
  44 ``VIDIOC_SUBDEV_G_ROUTING`` ioctl and application may enable or disable routes
  45 with the ``VIDIOC_SUBDEV_S_ROUTING`` ioctl, by adding or removing routes and
  46 setting or clearing flags of the  ``flags`` field of a
  47 struct :c:type:`v4l2_subdev_route`.
  48
  49 All stream configurations are reset when ``VIDIOC_SUBDEV_S_ROUTING`` is called. This
  50 means that the userspace must reconfigure all streams after calling the ioctl
  51 with e.g. ``VIDIOC_SUBDEV_S_FMT``.
  52
  53 Only subdevices which have both sink and source pads can support routing.
  54
  55 When inspecting routes through ``VIDIOC_SUBDEV_G_ROUTING`` and the application
  56 provided ``num_routes`` is not big enough to contain all the available routes
  57 the subdevice exposes, drivers return the ENOSPC error code and adjust the
  58 value of the ``num_routes`` field. Application should then reserve enough memory
  59 for all the route entries and call ``VIDIOC_SUBDEV_G_ROUTING`` again.
  60
  61 On a successful ``VIDIOC_SUBDEV_G_ROUTING`` call the driver updates the
  62 ``num_routes`` field to reflect the actual number of routes returned.
  63
  64 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  65
  66 .. c:type:: v4l2_subdev_routing
  67
  68 .. flat-table:: struct v4l2_subdev_routing
  69     :header-rows:  0
  70     :stub-columns: 0
  71     :widths:       1 1 2
  72
  73     * - __u32
  74       - ``which``
  75       - Format to modified, from enum
  76         :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
  77     * - struct :c:type:`v4l2_subdev_route`
  78       - ``routes[]``
  79       - Array of struct :c:type:`v4l2_subdev_route` entries
  80     * - __u32
  81       - ``num_routes``
  82       - Number of entries of the routes array
  83     * - __u32
  84       - ``reserved``\ [5]
  85       - Reserved for future extensions. Applications and drivers must set
  86         the array to zero.
  87
  88 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  89
  90 .. c:type:: v4l2_subdev_route
  91
  92 .. flat-table:: struct v4l2_subdev_route
  93     :header-rows:  0
  94     :stub-columns: 0
  95     :widths:       1 1 2
  96
  97     * - __u32
  98       - ``sink_pad``
  99       - Sink pad number.
 100     * - __u32
 101       - ``sink_stream``
 102       - Sink pad stream number.
 103     * - __u32
 104       - ``source_pad``
 105       - Source pad number.
 106     * - __u32
 107       - ``source_stream``
 108       - Source pad stream number.
 109     * - __u32
 110       - ``flags``
 111       - Route enable/disable flags
 112         :ref:`v4l2_subdev_routing_flags <v4l2-subdev-routing-flags>`.
 113     * - __u32
 114       - ``reserved``\ [5]
 115       - Reserved for future extensions. Applications and drivers must set
 116         the array to zero.
 117
 118 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 119
 120 .. _v4l2-subdev-routing-flags:
 121
 122 .. flat-table:: enum v4l2_subdev_routing_flags
 123     :header-rows:  0
 124     :stub-columns: 0
 125     :widths:       3 1 4
 126
 127     * - V4L2_SUBDEV_ROUTE_FL_ACTIVE
 128       - 0x0001
 129       - The route is enabled. Set by applications.
 130
 131 Return Value
 132 ============
 133
 134 On success 0 is returned, on error -1 and the ``errno`` variable is set
 135 appropriately. The generic error codes are described at the
 136 :ref:`Generic Error Codes <gen-errors>` chapter.
 137
 138 ENOSPC
 139    The application provided ``num_routes`` is not big enough to contain
 140    all the available routes the subdevice exposes.
 141
 142 EINVAL
 143    The sink or source pad identifiers reference a non-existing pad, or reference
 144    pads of different types (ie. the sink_pad identifiers refers to a source pad).
 145
 146 E2BIG
 147    The application provided ``num_routes`` for ``VIDIOC_SUBDEV_S_ROUTING`` is
 148    larger than the number of routes the driver can handle.