€•‹š      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ"/translations/zh_CN/usb/gadget_uvc”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ"/translations/zh_TW/usb/gadget_uvc”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ"/translations/it_IT/usb/gadget_uvc”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ"/translations/ja_JP/usb/gadget_uvc”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ"/translations/ko_KR/usb/gadget_uvc”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒPortuguese (Brazilian)”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ"/translations/pt_BR/usb/gadget_uvc”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh–sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ"/translations/sp_SP/usb/gadget_uvc”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒLinux UVC Gadget Driver”h]”hŒLinux UVC Gadget Driver”…””}”(hh¼h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhh·h²hh³Œ</var/lib/git/docbuild/linux/Documentation/usb/gadget_uvc.rst”h´Kubh¶)”}”(hhh]”(h»)”}”(hŒOverview”h]”hŒOverview”…””}”(hhÎh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhhËh²hh³hÊh´KubhŒ	paragraph”“”)”}”(hŒÃThe UVC Gadget driver is a driver for hardware on the *device* side of a USB
connection. It is intended to run on a Linux system that has USB device-side
hardware such as boards with an OTG port.”h]”(hŒ6The UVC Gadget driver is a driver for hardware on the ”…””}”(hhÞh²hh³Nh´NubhŒemphasis”“”)”}”(hŒ*device*”h]”hŒdevice”…””}”(hhèh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hæhhÞubhŒ… side of a USB
connection. It is intended to run on a Linux system that has USB device-side
hardware such as boards with an OTG port.”…””}”(hhÞh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´KhhËh²hubhÝ)”}”(hŒfOn the device system, once the driver is bound it appears as a V4L2 device with
the output capability.”h]”hŒfOn the device system, once the driver is bound it appears as a V4L2 device with
the output capability.”…””}”(hj   h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´KhhËh²hubhÝ)”}”(hX@  On the host side (once connected via USB cable), a device running the UVC Gadget
driver *and controlled by an appropriate userspace program* should appear as a UVC
specification compliant camera, and function appropriately with any program
designed to handle them. The userspace program running on the device system can
queue image buffers from a variety of sources to be transmitted via the USB
connection. Typically this would mean forwarding the buffers from a camera sensor
peripheral, but the source of the buffer is entirely dependent on the userspace
companion program.”h]”(hŒXOn the host side (once connected via USB cable), a device running the UVC Gadget
driver ”…””}”(hj  h²hh³Nh´Nubhç)”}”(hŒ4*and controlled by an appropriate userspace program*”h]”hŒ2and controlled by an appropriate userspace program”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hæhj  ubhX´   should appear as a UVC
specification compliant camera, and function appropriately with any program
designed to handle them. The userspace program running on the device system can
queue image buffers from a variety of sources to be transmitted via the USB
connection. Typically this would mean forwarding the buffers from a camera sensor
peripheral, but the source of the buffer is entirely dependent on the userspace
companion program.”…””}”(hj  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´KhhËh²hubeh}”(h]”Œoverview”ah ]”h"]”Œoverview”ah$]”h&]”uh1hµhh·h²hh³hÊh´Kubh¶)”}”(hhh]”(h»)”}”(hŒConfiguring the device kernel”h]”hŒConfiguring the device kernel”…””}”(hj9  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhj6  h²hh³hÊh´KubhÝ)”}”(hŒ‹The Kconfig options USB_CONFIGFS, USB_LIBCOMPOSITE, USB_CONFIGFS_F_UVC and
USB_F_UVC must be selected to enable support for the UVC gadget.”h]”hŒ‹The Kconfig options USB_CONFIGFS, USB_LIBCOMPOSITE, USB_CONFIGFS_F_UVC and
USB_F_UVC must be selected to enable support for the UVC gadget.”…””}”(hjG  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Khj6  h²hubeh}”(h]”Œconfiguring-the-device-kernel”ah ]”h"]”Œconfiguring the device kernel”ah$]”h&]”uh1hµhh·h²hh³hÊh´Kubh¶)”}”(hhh]”(h»)”}”(hŒ'Configuring the gadget through configfs”h]”hŒ'Configuring the gadget through configfs”…””}”(hj`  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhj]  h²hh³hÊh´KubhÝ)”}”(hŒÀThe UVC Gadget expects to be configured through configfs using the UVC function.
This allows a significant degree of flexibility, as many of a UVC device's
settings can be controlled this way.”h]”hŒÂThe UVC Gadget expects to be configured through configfs using the UVC function.
This allows a significant degree of flexibility, as many of a UVC deviceâ€™s
settings can be controlled this way.”…””}”(hjn  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Khj]  h²hubhÝ)”}”(hŒˆNot all of the available attributes are described here. For a complete enumeration
see Documentation/ABI/testing/configfs-usb-gadget-uvc”h]”hŒˆNot all of the available attributes are described here. For a complete enumeration
see Documentation/ABI/testing/configfs-usb-gadget-uvc”…””}”(hj|  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K"hj]  h²hubh¶)”}”(hhh]”(h»)”}”(hŒAssumptions”h]”hŒAssumptions”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhjŠ  h²hh³hÊh´K&ubhÝ)”}”(hŒ‡This section assumes that you have mounted configfs at `/sys/kernel/config` and
created a gadget as `/sys/kernel/config/usb_gadget/g1`.”h]”(hŒ7This section assumes that you have mounted configfs at ”…””}”(hj›  h²hh³Nh´NubhŒtitle_reference”“”)”}”(hŒ`/sys/kernel/config`”h]”hŒ/sys/kernel/config”…””}”(hj¥  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j£  hj›  ubhŒ and
created a gadget as ”…””}”(hj›  h²hh³Nh´Nubj¤  )”}”(hŒ"`/sys/kernel/config/usb_gadget/g1`”h]”hŒ /sys/kernel/config/usb_gadget/g1”…””}”(hj·  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j£  hj›  ubhŒ.”…””}”(hj›  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K'hjŠ  h²hubeh}”(h]”Œassumptions”ah ]”h"]”Œassumptions”ah$]”h&]”uh1hµhj]  h²hh³hÊh´K&ubh¶)”}”(hhh]”(h»)”}”(hŒThe UVC Function”h]”hŒThe UVC Function”…””}”(hjÚ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhj×  h²hh³hÊh´K+ubhÝ)”}”(hŒ-The first step is to create the UVC function:”h]”hŒ-The first step is to create the UVC function:”…””}”(hjè  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K-hj×  h²hubhŒliteral_block”“”)”}”(hŒ»# These variables will be assumed throughout the rest of the document
CONFIGFS="/sys/kernel/config"
GADGET="$CONFIGFS/usb_gadget/g1"
FUNCTION="$GADGET/functions/uvc.0"

mkdir -p $FUNCTION”h]”hŒ»# These variables will be assumed throughout the rest of the document
CONFIGFS="/sys/kernel/config"
GADGET="$CONFIGFS/usb_gadget/g1"
FUNCTION="$GADGET/functions/uvc.0"

mkdir -p $FUNCTION”…””}”hjø  sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”Œforce”‰Œlanguage”Œbash”Œhighlight_args”}”uh1jö  h³hÊh´K/hj×  h²hubeh}”(h]”Œthe-uvc-function”ah ]”h"]”Œthe uvc function”ah$]”h&]”uh1hµhj]  h²hh³hÊh´K+ubh¶)”}”(hhh]”(h»)”}”(hŒFormats and Frames”h]”hŒFormats and Frames”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhj  h²hh³hÊh´K9ubhÝ)”}”(hX—  You must configure the gadget by telling it which formats you support, as well
as the frame sizes and frame intervals that are supported for each format. In
the current implementation there is no way for the gadget to refuse to set a
format that the host instructs it to set, so it is important that this step is
completed *accurately* to ensure that the host never asks for a format that
can't be provided.”h]”(hXC  You must configure the gadget by telling it which formats you support, as well
as the frame sizes and frame intervals that are supported for each format. In
the current implementation there is no way for the gadget to refuse to set a
format that the host instructs it to set, so it is important that this step is
completed ”…””}”(hj&  h²hh³Nh´Nubhç)”}”(hŒ*accurately*”h]”hŒ
accurately”…””}”(hj.  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hæhj&  ubhŒJ to ensure that the host never asks for a format that
canâ€™t be provided.”…””}”(hj&  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K;hj  h²hubhÝ)”}”(hŒ£Formats are created under the streaming/uncompressed and streaming/mjpeg configfs
groups, with the framesizes created under the formats in the following
structure:”h]”hŒ£Formats are created under the streaming/uncompressed and streaming/mjpeg configfs
groups, with the framesizes created under the formats in the following
structure:”…””}”(hjF  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´KBhj  h²hubj÷  )”}”(hXY  uvc.0 +
      |
      + streaming +
                  |
                  + mjpeg +
                  |       |
                  |       + mjpeg +
                  |            |
                  |            + 720p
                  |            |
                  |            + 1080p
                  |
                  + uncompressed +
                                 |
                                 + yuyv +
                                        |
                                        + 720p
                                        |
                                        + 1080p”h]”hXY  uvc.0 +
      |
      + streaming +
                  |
                  + mjpeg +
                  |       |
                  |       + mjpeg +
                  |            |
                  |            + 720p
                  |            |
                  |            + 1080p
                  |
                  + uncompressed +
                                 |
                                 + yuyv +
                                        |
                                        + 720p
                                        |
                                        + 1080p”…””}”hjT  sbah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1jö  h³hÊh´KHhj  h²hubhÝ)”}”(hXŽ  Each frame can then be configured with a width and height, plus the maximum
buffer size required to store a single frame, and finally with the supported
frame intervals for that format and framesize. Width and height are enumerated in
units of pixels, frame interval in units of 100ns. To create the structure
above with 2, 15 and 100 fps frameintervals for each framesize for example you
might do:”h]”hXŽ  Each frame can then be configured with a width and height, plus the maximum
buffer size required to store a single frame, and finally with the supported
frame intervals for that format and framesize. Width and height are enumerated in
units of pixels, frame interval in units of 100ns. To create the structure
above with 2, 15 and 100 fps frameintervals for each framesize for example you
might do:”…””}”(hjb  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K\hj  h²hubj÷  )”}”(hXp  create_frame() {
        # Example usage:
        # create_frame <width> <height> <group> <format name>

        WIDTH=$1
        HEIGHT=$2
        FORMAT=$3
        NAME=$4

        wdir=$FUNCTION/streaming/$FORMAT/$NAME/${HEIGHT}p

        mkdir -p $wdir
        echo $WIDTH > $wdir/wWidth
        echo $HEIGHT > $wdir/wHeight
        echo $(( $WIDTH * $HEIGHT * 2 )) > $wdir/dwMaxVideoFrameBufferSize
        cat <<EOF > $wdir/dwFrameInterval
666666
100000
5000000
EOF
}

create_frame 1280 720 mjpeg mjpeg
create_frame 1920 1080 mjpeg mjpeg
create_frame 1280 720 uncompressed yuyv
create_frame 1920 1080 uncompressed yuyv”h]”hXp  create_frame() {
        # Example usage:
        # create_frame <width> <height> <group> <format name>

        WIDTH=$1
        HEIGHT=$2
        FORMAT=$3
        NAME=$4

        wdir=$FUNCTION/streaming/$FORMAT/$NAME/${HEIGHT}p

        mkdir -p $wdir
        echo $WIDTH > $wdir/wWidth
        echo $HEIGHT > $wdir/wHeight
        echo $(( $WIDTH * $HEIGHT * 2 )) > $wdir/dwMaxVideoFrameBufferSize
        cat <<EOF > $wdir/dwFrameInterval
666666
100000
5000000
EOF
}

create_frame 1280 720 mjpeg mjpeg
create_frame 1920 1080 mjpeg mjpeg
create_frame 1280 720 uncompressed yuyv
create_frame 1920 1080 uncompressed yuyv”…””}”hjp  sbah}”(h]”h ]”h"]”h$]”h&]”j  j  j  ‰j	  Œbash”j  }”uh1jö  h³hÊh´Kchj  h²hubhÝ)”}”(hŒ‹The only uncompressed format currently supported is YUYV, which is detailed at
Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst.”h]”hŒ‹The only uncompressed format currently supported is YUYV, which is detailed at
Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst.”…””}”(hj€  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K€hj  h²hubeh}”(h]”Œformats-and-frames”ah ]”h"]”Œformats and frames”ah$]”h&]”uh1hµhj]  h²hh³hÊh´K9ubh¶)”}”(hhh]”(h»)”}”(hŒColor Matching Descriptors”h]”hŒColor Matching Descriptors”…””}”(hj™  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhj–  h²hh³hÊh´K„ubhÝ)”}”(hX  It's possible to specify some colometry information for each format you create.
This step is optional, and default information will be included if this step is
skipped; those default values follow those defined in the Color Matching Descriptor
section of the UVC specification.”h]”hX  Itâ€™s possible to specify some colometry information for each format you create.
This step is optional, and default information will be included if this step is
skipped; those default values follow those defined in the Color Matching Descriptor
section of the UVC specification.”…””}”(hj§  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K…hj–  h²hubhÝ)”}”(hŒºTo create a Color Matching Descriptor, create a configfs item and set its three
attributes to your desired settings and then link to it from the format you wish
it to be associated with:”h]”hŒºTo create a Color Matching Descriptor, create a configfs item and set its three
attributes to your desired settings and then link to it from the format you wish
it to be associated with:”…””}”(hjµ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´KŠhj–  h²hubj÷  )”}”(hX‹  # Create a new Color Matching Descriptor

mkdir $FUNCTION/streaming/color_matching/yuyv
pushd $FUNCTION/streaming/color_matching/yuyv

echo 1 > bColorPrimaries
echo 1 > bTransferCharacteristics
echo 4 > bMatrixCoefficients

popd

# Create a symlink to the Color Matching Descriptor from the format's config item
ln -s $FUNCTION/streaming/color_matching/yuyv $FUNCTION/streaming/uncompressed/yuyv”h]”hX‹  # Create a new Color Matching Descriptor

mkdir $FUNCTION/streaming/color_matching/yuyv
pushd $FUNCTION/streaming/color_matching/yuyv

echo 1 > bColorPrimaries
echo 1 > bTransferCharacteristics
echo 4 > bMatrixCoefficients

popd

# Create a symlink to the Color Matching Descriptor from the format's config item
ln -s $FUNCTION/streaming/color_matching/yuyv $FUNCTION/streaming/uncompressed/yuyv”…””}”hjÃ  sbah}”(h]”h ]”h"]”h$]”h&]”j  j  j  ‰j	  Œbash”j  }”uh1jö  h³hÊh´KŽhj–  h²hubhÝ)”}”(hX™  For details about the valid values, consult the UVC specification. Note that a
default color matching descriptor exists and is used by any format which does
not have a link to a different Color Matching Descriptor. It's possible to
change the attribute settings for the default descriptor, so bear in mind that if
you do that you are altering the defaults for any format that does not link to
a different one.”h]”hX›  For details about the valid values, consult the UVC specification. Note that a
default color matching descriptor exists and is used by any format which does
not have a link to a different Color Matching Descriptor. Itâ€™s possible to
change the attribute settings for the default descriptor, so bear in mind that if
you do that you are altering the defaults for any format that does not link to
a different one.”…””}”(hjÓ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Kžhj–  h²hubeh}”(h]”Œcolor-matching-descriptors”ah ]”h"]”Œcolor matching descriptors”ah$]”h&]”uh1hµhj]  h²hh³hÊh´K„ubh¶)”}”(hhh]”(h»)”}”(hŒHeader linking”h]”hŒHeader linking”…””}”(hjì  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhjé  h²hh³hÊh´K§ubhÝ)”}”(hX}  The UVC specification requires that Format and Frame descriptors be preceded by
Headers detailing things such as the number and cumulative size of the different
Format descriptors that follow. This and similar operations are achieved in
configfs by linking between the configfs item representing the header and the
config items representing those other descriptors, in this manner:”h]”hX}  The UVC specification requires that Format and Frame descriptors be preceded by
Headers detailing things such as the number and cumulative size of the different
Format descriptors that follow. This and similar operations are achieved in
configfs by linking between the configfs item representing the header and the
config items representing those other descriptors, in this manner:”…””}”(hjú  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K©hjé  h²hubj÷  )”}”(hXK  mkdir $FUNCTION/streaming/header/h

# This section links the format descriptors and their associated frames
# to the header
cd $FUNCTION/streaming/header/h
ln -s ../../uncompressed/yuyv
ln -s ../../mjpeg/mjpeg

# This section ensures that the header will be transmitted for each
# speed's set of descriptors. If support for a particular speed is not
# needed then it can be skipped here.
cd ../../class/fs
ln -s ../../header/h
cd ../../class/hs
ln -s ../../header/h
cd ../../class/ss
ln -s ../../header/h
cd ../../../control
mkdir header/h
ln -s header/h class/fs
ln -s header/h class/ss”h]”hXK  mkdir $FUNCTION/streaming/header/h

# This section links the format descriptors and their associated frames
# to the header
cd $FUNCTION/streaming/header/h
ln -s ../../uncompressed/yuyv
ln -s ../../mjpeg/mjpeg

# This section ensures that the header will be transmitted for each
# speed's set of descriptors. If support for a particular speed is not
# needed then it can be skipped here.
cd ../../class/fs
ln -s ../../header/h
cd ../../class/hs
ln -s ../../header/h
cd ../../class/ss
ln -s ../../header/h
cd ../../../control
mkdir header/h
ln -s header/h class/fs
ln -s header/h class/ss”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”j  j  j  ‰j	  Œbash”j  }”uh1jö  h³hÊh´K¯hjé  h²hubeh}”(h]”Œheader-linking”ah ]”h"]”Œheader linking”ah$]”h&]”uh1hµhj]  h²hh³hÊh´K§ubh¶)”}”(hhh]”(h»)”}”(hŒExtension Unit Support”h]”hŒExtension Unit Support”…””}”(hj#  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhj   h²hh³hÊh´KÉubhÝ)”}”(hX|  A UVC Extension Unit (XU) basically provides a distinct unit to which control set
and get requests can be addressed. The meaning of those control requests is
entirely implementation dependent, but may be used to control settings outside
of the UVC specification (for example enabling or disabling video effects). An
XU can be inserted into the UVC unit chain or left free-hanging.”h]”hX|  A UVC Extension Unit (XU) basically provides a distinct unit to which control set
and get requests can be addressed. The meaning of those control requests is
entirely implementation dependent, but may be used to control settings outside
of the UVC specification (for example enabling or disabling video effects). An
XU can be inserted into the UVC unit chain or left free-hanging.”…””}”(hj1  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´KËhj   h²hubhÝ)”}”(hŒˆConfiguring an extension unit involves creating an entry in the appropriate
directory and setting its attributes appropriately, like so:”h]”hŒˆConfiguring an extension unit involves creating an entry in the appropriate
directory and setting its attributes appropriately, like so:”…””}”(hj?  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´KÑhj   h²hubj÷  )”}”(hX2  mkdir $FUNCTION/control/extensions/xu.0
pushd $FUNCTION/control/extensions/xu.0

# Set the bUnitID of the Processing Unit as the source for this
# Extension Unit
echo 2 > baSourceID

# Set this XU as the source of the default output terminal. This inserts
# the XU into the UVC chain between the PU and OT such that the final
# chain is IT > PU > XU.0 > OT
cat bUnitID > ../../terminal/output/default/baSourceID

# Flag some controls as being available for use. The bmControl field is
# a bitmap with each bit denoting the availability of a particular
# control. For example to flag the 0th, 2nd and 3rd controls available:
echo 0x0d > bmControls

# Set the GUID; this is a vendor-specific code identifying the XU.
echo -e -n "\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f\x10" > guidExtensionCode

popd”h]”hX2  mkdir $FUNCTION/control/extensions/xu.0
pushd $FUNCTION/control/extensions/xu.0

# Set the bUnitID of the Processing Unit as the source for this
# Extension Unit
echo 2 > baSourceID

# Set this XU as the source of the default output terminal. This inserts
# the XU into the UVC chain between the PU and OT such that the final
# chain is IT > PU > XU.0 > OT
cat bUnitID > ../../terminal/output/default/baSourceID

# Flag some controls as being available for use. The bmControl field is
# a bitmap with each bit denoting the availability of a particular
# control. For example to flag the 0th, 2nd and 3rd controls available:
echo 0x0d > bmControls

# Set the GUID; this is a vendor-specific code identifying the XU.
echo -e -n "\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f\x10" > guidExtensionCode

popd”…””}”hjM  sbah}”(h]”h ]”h"]”h$]”h&]”j  j  j  ‰j	  Œbash”j  }”uh1jö  h³hÊh´KÔhj   h²hubhÝ)”}”(hX   The bmControls attribute and the baSourceID attribute are multi-value attributes.
This means that you may write multiple newline separated values to them. For
example to flag the 1st, 2nd, 9th and 10th controls as being available you would
need to write two values to bmControls, like so:”h]”hX   The bmControls attribute and the baSourceID attribute are multi-value attributes.
This means that you may write multiple newline separated values to them. For
example to flag the 1st, 2nd, 9th and 10th controls as being available you would
need to write two values to bmControls, like so:”…””}”(hj]  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Kìhj   h²hubj÷  )”}”(hŒ%cat << EOF > bmControls
0x03
0x03
EOF”h]”hŒ%cat << EOF > bmControls
0x03
0x03
EOF”…””}”hjk  sbah}”(h]”h ]”h"]”h$]”h&]”j  j  j  ‰j	  Œbash”j  }”uh1jö  h³hÊh´Kñhj   h²hubhÝ)”}”(hŒThe multi-value nature of the baSourceID attribute belies the fact that XUs can
be multiple-input, though note that this currently has no significant effect.”h]”hŒThe multi-value nature of the baSourceID attribute belies the fact that XUs can
be multiple-input, though note that this currently has no significant effect.”…””}”(hj{  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Køhj   h²hubhÝ)”}”(hXœ  The bControlSize attribute reflects the size of the bmControls attribute, and
similarly bNrInPins reflects the size of the baSourceID attributes. Both
attributes are automatically increased / decreased as you set bmControls and
baSourceID. It is also possible to manually increase or decrease bControlSize
which has the effect of truncating entries to the new size, or padding entries
out with 0x00, for example:”h]”hXœ  The bControlSize attribute reflects the size of the bmControls attribute, and
similarly bNrInPins reflects the size of the baSourceID attributes. Both
attributes are automatically increased / decreased as you set bmControls and
baSourceID. It is also possible to manually increase or decrease bControlSize
which has the effect of truncating entries to the new size, or padding entries
out with 0x00, for example:”…””}”(hj‰  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Kûhj   h²hubj÷  )”}”(hŒ“$ cat bmControls
0x03
0x05

$ cat bControlSize
2

$ echo 1 > bControlSize
$ cat bmControls
0x03

$ echo 2 > bControlSize
$ cat bmControls
0x03
0x00”h]”hŒ“$ cat bmControls
0x03
0x05

$ cat bControlSize
2

$ echo 1 > bControlSize
$ cat bmControls
0x03

$ echo 2 > bControlSize
$ cat bmControls
0x03
0x00”…””}”hj—  sbah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1jö  h³hÊh´Mhj   h²hubhÝ)”}”(hŒ2bNrInPins and baSourceID function in the same way.”h]”hŒ2bNrInPins and baSourceID function in the same way.”…””}”(hj¥  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Mhj   h²hubeh}”(h]”Œextension-unit-support”ah ]”h"]”Œextension unit support”ah$]”h&]”uh1hµhj]  h²hh³hÊh´KÉubh¶)”}”(hhh]”(h»)”}”(hŒFConfiguring Supported Controls for Camera Terminal and Processing Unit”h]”hŒFConfiguring Supported Controls for Camera Terminal and Processing Unit”…””}”(hj¾  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhj»  h²hh³hÊh´MubhÝ)”}”(hX}  The Camera Terminal and Processing Units in the UVC chain also have bmControls
attributes which function similarly to the same field in an Extension Unit.
Unlike XUs however, the meaning of the bitflag for these units is defined in
the UVC specification; you should consult the "Camera Terminal Descriptor" and
"Processing Unit Descriptor" sections for an enumeration of the flags.”h]”hX…  The Camera Terminal and Processing Units in the UVC chain also have bmControls
attributes which function similarly to the same field in an Extension Unit.
Unlike XUs however, the meaning of the bitflag for these units is defined in
the UVC specification; you should consult the â€œCamera Terminal Descriptorâ€ and
â€œProcessing Unit Descriptorâ€ sections for an enumeration of the flags.”…””}”(hjÌ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Mhj»  h²hubj÷  )”}”(hXP  # Set the Processing Unit's bmControls, flagging Brightness, Contrast
# and Hue as available controls:
echo 0x05 > $FUNCTION/control/processing/default/bmControls

# Set the Camera Terminal's bmControls, flagging Focus Absolute and
# Focus Relative as available controls:
echo 0x60 > $FUNCTION/control/terminal/camera/default/bmControls”h]”hXP  # Set the Processing Unit's bmControls, flagging Brightness, Contrast
# and Hue as available controls:
echo 0x05 > $FUNCTION/control/processing/default/bmControls

# Set the Camera Terminal's bmControls, flagging Focus Absolute and
# Focus Relative as available controls:
echo 0x60 > $FUNCTION/control/terminal/camera/default/bmControls”…””}”hjÚ  sbah}”(h]”h ]”h"]”h$]”h&]”j  j  j  ‰j	  Œbash”j  }”uh1jö  h³hÊh´Mhj»  h²hubhÝ)”}”(hŒòIf you do not set these fields then by default the Auto-Exposure Mode control
for the Camera Terminal and the Brightness control for the Processing Unit will
be flagged as available; if they are not supported you should set the field to
0x00.”h]”hŒòIf you do not set these fields then by default the Auto-Exposure Mode control
for the Camera Terminal and the Brightness control for the Processing Unit will
be flagged as available; if they are not supported you should set the field to
0x00.”…””}”(hjê  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´M)hj»  h²hubhÝ)”}”(hŒ«Note that the size of the bmControls field for a Camera Terminal or Processing
Unit is fixed by the UVC specification, and so the bControlSize attribute is
read-only here.”h]”hŒ«Note that the size of the bmControls field for a Camera Terminal or Processing
Unit is fixed by the UVC specification, and so the bControlSize attribute is
read-only here.”…””}”(hjø  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´M.hj»  h²hubeh}”(h]”ŒFconfiguring-supported-controls-for-camera-terminal-and-processing-unit”ah ]”h"]”ŒFconfiguring supported controls for camera terminal and processing unit”ah$]”h&]”uh1hµhj]  h²hh³hÊh´Mubh¶)”}”(hhh]”(h»)”}”(hŒCustom Strings Support”h]”hŒCustom Strings Support”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhj  h²hh³hÊh´M3ubhÝ)”}”(hX  String descriptors that provide a textual description for various parts of a
USB device can be defined in the usual place within USB configfs, and may then
be linked to from the UVC function root or from Extension Unit directories to
assign those strings as descriptors:”h]”hX  String descriptors that provide a textual description for various parts of a
USB device can be defined in the usual place within USB configfs, and may then
be linked to from the UVC function root or from Extension Unit directories to
assign those strings as descriptors:”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´M5hj  h²hubj÷  )”}”(hXN  # Create a string descriptor in us-EN and link to it from the function
# root. The name of the link is significant here, as it declares this
# descriptor to be intended for the Interface Association Descriptor.
# Other significant link names at function root are vs0_desc and vs1_desc
# For the VideoStreaming Interface 0/1 Descriptors.

mkdir -p $GADGET/strings/0x409/iad_desc
echo -n "Interface Associaton Descriptor" > $GADGET/strings/0x409/iad_desc/s
ln -s $GADGET/strings/0x409/iad_desc $FUNCTION/iad_desc

# Because the link to a String Descriptor from an Extension Unit clearly
# associates the two, the name of this link is not significant and may
# be set freely.

mkdir -p $GADGET/strings/0x409/xu.0
echo -n "A Very Useful Extension Unit" > $GADGET/strings/0x409/xu.0/s
ln -s $GADGET/strings/0x409/xu.0 $FUNCTION/control/extensions/xu.0”h]”hXN  # Create a string descriptor in us-EN and link to it from the function
# root. The name of the link is significant here, as it declares this
# descriptor to be intended for the Interface Association Descriptor.
# Other significant link names at function root are vs0_desc and vs1_desc
# For the VideoStreaming Interface 0/1 Descriptors.

mkdir -p $GADGET/strings/0x409/iad_desc
echo -n "Interface Associaton Descriptor" > $GADGET/strings/0x409/iad_desc/s
ln -s $GADGET/strings/0x409/iad_desc $FUNCTION/iad_desc

# Because the link to a String Descriptor from an Extension Unit clearly
# associates the two, the name of this link is not significant and may
# be set freely.

mkdir -p $GADGET/strings/0x409/xu.0
echo -n "A Very Useful Extension Unit" > $GADGET/strings/0x409/xu.0/s
ln -s $GADGET/strings/0x409/xu.0 $FUNCTION/control/extensions/xu.0”…””}”hj-  sbah}”(h]”h ]”h"]”h$]”h&]”j  j  j  ‰j	  Œbash”j  }”uh1jö  h³hÊh´M:hj  h²hubeh}”(h]”Œcustom-strings-support”ah ]”h"]”Œcustom strings support”ah$]”h&]”uh1hµhj]  h²hh³hÊh´M3ubh¶)”}”(hhh]”(h»)”}”(hŒThe interrupt endpoint”h]”hŒThe interrupt endpoint”…””}”(hjH  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhjE  h²hh³hÊh´MOubhÝ)”}”(hX·  The VideoControl interface has an optional interrupt endpoint which is by default
disabled. This is intended to support delayed response control set requests for
UVC (which should respond through the interrupt endpoint rather than tying up
endpoint 0). At present support for sending data through this endpoint is missing
and so it is left disabled to avoid confusion. If you wish to enable it you can
do so through the configfs attribute:”h]”hX·  The VideoControl interface has an optional interrupt endpoint which is by default
disabled. This is intended to support delayed response control set requests for
UVC (which should respond through the interrupt endpoint rather than tying up
endpoint 0). At present support for sending data through this endpoint is missing
and so it is left disabled to avoid confusion. If you wish to enable it you can
do so through the configfs attribute:”…””}”(hjV  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´MQhjE  h²hubj÷  )”}”(hŒ.echo 1 > $FUNCTION/control/enable_interrupt_ep”h]”hŒ.echo 1 > $FUNCTION/control/enable_interrupt_ep”…””}”hjd  sbah}”(h]”h ]”h"]”h$]”h&]”j  j  j  ‰j	  Œbash”j  }”uh1jö  h³hÊh´MXhjE  h²hubeh}”(h]”Œthe-interrupt-endpoint”ah ]”h"]”Œthe interrupt endpoint”ah$]”h&]”uh1hµhj]  h²hh³hÊh´MOubh¶)”}”(hhh]”(h»)”}”(hŒBandwidth configuration”h]”hŒBandwidth configuration”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhj|  h²hh³hÊh´M]ubhÝ)”}”(hŒ‹There are three attributes which control the bandwidth of the USB connection.
These live in the function root and can be set within limits:”h]”hŒ‹There are three attributes which control the bandwidth of the USB connection.
These live in the function root and can be set within limits:”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´M_hj|  h²hubj÷  )”}”(hX<  # streaming_interval sets bInterval. Values range from 1..255
echo 1 > $FUNCTION/streaming_interval

# streaming_maxpacket sets wMaxPacketSize. Valid values are 1024/2048/3072
echo 3072 > $FUNCTION/streaming_maxpacket

# streaming_maxburst sets bMaxBurst. Valid values are 1..15
echo 1 > $FUNCTION/streaming_maxburst”h]”hX<  # streaming_interval sets bInterval. Values range from 1..255
echo 1 > $FUNCTION/streaming_interval

# streaming_maxpacket sets wMaxPacketSize. Valid values are 1024/2048/3072
echo 3072 > $FUNCTION/streaming_maxpacket

# streaming_maxburst sets bMaxBurst. Valid values are 1..15
echo 1 > $FUNCTION/streaming_maxburst”…””}”hj›  sbah}”(h]”h ]”h"]”h$]”h&]”j  j  j  ‰j	  Œbash”j  }”uh1jö  h³hÊh´Mbhj|  h²hubhÝ)”}”(hX  The values passed here will be clamped to valid values according to the UVC
specification (which depend on the speed of the USB connection). To understand
how the settings influence bandwidth you should consult the UVC specifications,
but a rule of thumb is that increasing the streaming_maxpacket setting will
improve bandwidth (and thus the maximum possible framerate), whilst the same is
true for streaming_maxburst provided the USB connection is running at SuperSpeed.
Increasing streaming_interval will reduce bandwidth and framerate.”h]”hX  The values passed here will be clamped to valid values according to the UVC
specification (which depend on the speed of the USB connection). To understand
how the settings influence bandwidth you should consult the UVC specifications,
but a rule of thumb is that increasing the streaming_maxpacket setting will
improve bandwidth (and thus the maximum possible framerate), whilst the same is
true for streaming_maxburst provided the USB connection is running at SuperSpeed.
Increasing streaming_interval will reduce bandwidth and framerate.”…””}”(hj«  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Mnhj|  h²hubeh}”(h]”Œbandwidth-configuration”ah ]”h"]”Œbandwidth configuration”ah$]”h&]”uh1hµhj]  h²hh³hÊh´M]ubeh}”(h]”Œ'configuring-the-gadget-through-configfs”ah ]”h"]”Œ'configuring the gadget through configfs”ah$]”h&]”uh1hµhh·h²hh³hÊh´Kubh¶)”}”(hhh]”(h»)”}”(hŒThe userspace application”h]”hŒThe userspace application”…””}”(hjÌ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhjÉ  h²hh³hÊh´MwubhÝ)”}”(hX§  By itself, the UVC Gadget driver cannot do anything particularly interesting. It
must be paired with a userspace program that responds to UVC control requests and
fills buffers to be queued to the V4L2 device that the driver creates. How those
things are achieved is implementation dependent and beyond the scope of this
document, but a reference application can be found at https://gitlab.freedesktop.org/camera/uvc-gadget”h]”(hXw  By itself, the UVC Gadget driver cannot do anything particularly interesting. It
must be paired with a userspace program that responds to UVC control requests and
fills buffers to be queued to the V4L2 device that the driver creates. How those
things are achieved is implementation dependent and beyond the scope of this
document, but a reference application can be found at ”…””}”(hjÚ  h²hh³Nh´NubhŒ	reference”“”)”}”(hŒ0https://gitlab.freedesktop.org/camera/uvc-gadget”h]”hŒ0https://gitlab.freedesktop.org/camera/uvc-gadget”…””}”(hjä  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”jæ  uh1jâ  hjÚ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´MxhjÉ  h²hubeh}”(h]”Œthe-userspace-application”ah ]”h"]”Œthe userspace application”ah$]”h&]”uh1hµhh·h²hh³hÊh´Mwubeh}”(h]”Œlinux-uvc-gadget-driver”ah ]”h"]”Œlinux uvc gadget driver”ah$]”h&]”uh1hµhhh²hh³hÊh´Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”hÊuh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(hºNŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”j,  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”hÊŒ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(j  j  j3  j0  jZ  jW  jÆ  jÃ  jÔ  jÑ  j  j  j“  j  jæ  jã  j  j  j¸  jµ  j  j  jB  j?  jy  jv  j¾  j»  jþ  jû  uŒ	nametypes”}”(j  ‰j3  ‰jZ  ‰jÆ  ‰jÔ  ‰j  ‰j“  ‰jæ  ‰j  ‰j¸  ‰j  ‰jB  ‰jy  ‰j¾  ‰jþ  ‰uh}”(j  h·j0  hËjW  j6  jÃ  j]  jÑ  jŠ  j  j×  j  j  jã  j–  j  jé  jµ  j   j  j»  j?  j  jv  jE  j»  j|  jû  jÉ  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nh²hub.