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 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  62
  63 .. c:type:: v4l2_subdev_routing
  64
  65 .. flat-table:: struct v4l2_subdev_routing
  66     :header-rows:  0
  67     :stub-columns: 0
  68     :widths:       1 1 2
  69
  70     * - __u32
  71       - ``which``
  72       - Format to modified, from enum
  73         :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
  74     * - struct :c:type:`v4l2_subdev_route`
  75       - ``routes[]``
  76       - Array of struct :c:type:`v4l2_subdev_route` entries
  77     * - __u32
  78       - ``num_routes``
  79       - Number of entries of the routes array
  80     * - __u32
  81       - ``reserved``\ [5]
  82       - Reserved for future extensions. Applications and drivers must set
  83         the array to zero.
  84
  85 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  86
  87 .. c:type:: v4l2_subdev_route
  88
  89 .. flat-table:: struct v4l2_subdev_route
  90     :header-rows:  0
  91     :stub-columns: 0
  92     :widths:       1 1 2
  93
  94     * - __u32
  95       - ``sink_pad``
  96       - Sink pad number.
  97     * - __u32
  98       - ``sink_stream``
  99       - Sink pad stream number.
 100     * - __u32
 101       - ``source_pad``
 102       - Source pad number.
 103     * - __u32
 104       - ``source_stream``
 105       - Source pad stream number.
 106     * - __u32
 107       - ``flags``
 108       - Route enable/disable flags
 109         :ref:`v4l2_subdev_routing_flags <v4l2-subdev-routing-flags>`.
 110     * - __u32
 111       - ``reserved``\ [5]
 112       - Reserved for future extensions. Applications and drivers must set
 113         the array to zero.
 114
 115 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 116
 117 .. _v4l2-subdev-routing-flags:
 118
 119 .. flat-table:: enum v4l2_subdev_routing_flags
 120     :header-rows:  0
 121     :stub-columns: 0
 122     :widths:       3 1 4
 123
 124     * - V4L2_SUBDEV_ROUTE_FL_ACTIVE
 125       - 0x0001
 126       - The route is enabled. Set by applications.
 127
 128 Return Value
 129 ============
 130
 131 On success 0 is returned, on error -1 and the ``errno`` variable is set
 132 appropriately. The generic error codes are described at the
 133 :ref:`Generic Error Codes <gen-errors>` chapter.
 134
 135 ENOSPC
 136    The application provided ``num_routes`` is not big enough to contain
 137    all the available routes the subdevice exposes.
 138
 139 EINVAL
 140    The sink or source pad identifiers reference a non-existing pad, or reference
 141    pads of different types (ie. the sink_pad identifiers refers to a source pad)
 142    or the sink or source stream identifiers reference a non-existing stream on
 143    the sink or source pad.
 144
 145 E2BIG
 146    The application provided ``num_routes`` for ``VIDIOC_SUBDEV_S_ROUTING`` is
 147    larger than the number of routes the driver can handle.