diff options
Diffstat (limited to 'Documentation/DocBook')
246 files changed, 0 insertions, 90203 deletions
diff --git a/Documentation/DocBook/.gitignore b/Documentation/DocBook/.gitignore deleted file mode 100644 index e05da3f7aa21..000000000000 --- a/Documentation/DocBook/.gitignore +++ /dev/null @@ -1,17 +0,0 @@ -*.xml -*.ps -*.pdf -*.html -*.9.gz -*.9 -*.aux -*.dvi -*.log -*.out -*.png -*.gif -*.svg -*.proc -*.db -media-indices.tmpl -media-entities.tmpl diff --git a/Documentation/DocBook/80211.tmpl b/Documentation/DocBook/80211.tmpl deleted file mode 100644 index f9b9ad7894f5..000000000000 --- a/Documentation/DocBook/80211.tmpl +++ /dev/null @@ -1,583 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> -<set> - <setinfo> - <title>The 802.11 subsystems – for kernel developers</title> - <subtitle> - Explaining wireless 802.11 networking in the Linux kernel - </subtitle> - - <copyright> - <year>2007-2009</year> - <holder>Johannes Berg</holder> - </copyright> - - <authorgroup> - <author> - <firstname>Johannes</firstname> - <surname>Berg</surname> - <affiliation> - <address><email>johannes@sipsolutions.net</email></address> - </affiliation> - </author> - </authorgroup> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License version 2 as published by the Free Software Foundation. - </para> - <para> - This documentation is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - <para> - You should have received a copy of the GNU General Public - License along with this documentation; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - - <abstract> - <para> - These books attempt to give a description of the - various subsystems that play a role in 802.11 wireless - networking in Linux. Since these books are for kernel - developers they attempts to document the structures - and functions used in the kernel as well as giving a - higher-level overview. - </para> - <para> - The reader is expected to be familiar with the 802.11 - standard as published by the IEEE in 802.11-2007 (or - possibly later versions). References to this standard - will be given as "802.11-2007 8.1.5". - </para> - </abstract> - </setinfo> - <book id="cfg80211-developers-guide"> - <bookinfo> - <title>The cfg80211 subsystem</title> - - <abstract> -!Pinclude/net/cfg80211.h Introduction - </abstract> - </bookinfo> - <chapter> - <title>Device registration</title> -!Pinclude/net/cfg80211.h Device registration -!Finclude/net/cfg80211.h ieee80211_band -!Finclude/net/cfg80211.h ieee80211_channel_flags -!Finclude/net/cfg80211.h ieee80211_channel -!Finclude/net/cfg80211.h ieee80211_rate_flags -!Finclude/net/cfg80211.h ieee80211_rate -!Finclude/net/cfg80211.h ieee80211_sta_ht_cap -!Finclude/net/cfg80211.h ieee80211_supported_band -!Finclude/net/cfg80211.h cfg80211_signal_type -!Finclude/net/cfg80211.h wiphy_params_flags -!Finclude/net/cfg80211.h wiphy_flags -!Finclude/net/cfg80211.h wiphy -!Finclude/net/cfg80211.h wireless_dev -!Finclude/net/cfg80211.h wiphy_new -!Finclude/net/cfg80211.h wiphy_register -!Finclude/net/cfg80211.h wiphy_unregister -!Finclude/net/cfg80211.h wiphy_free - -!Finclude/net/cfg80211.h wiphy_name -!Finclude/net/cfg80211.h wiphy_dev -!Finclude/net/cfg80211.h wiphy_priv -!Finclude/net/cfg80211.h priv_to_wiphy -!Finclude/net/cfg80211.h set_wiphy_dev -!Finclude/net/cfg80211.h wdev_priv -!Finclude/net/cfg80211.h ieee80211_iface_limit -!Finclude/net/cfg80211.h ieee80211_iface_combination -!Finclude/net/cfg80211.h cfg80211_check_combinations - </chapter> - <chapter> - <title>Actions and configuration</title> -!Pinclude/net/cfg80211.h Actions and configuration -!Finclude/net/cfg80211.h cfg80211_ops -!Finclude/net/cfg80211.h vif_params -!Finclude/net/cfg80211.h key_params -!Finclude/net/cfg80211.h survey_info_flags -!Finclude/net/cfg80211.h survey_info -!Finclude/net/cfg80211.h cfg80211_beacon_data -!Finclude/net/cfg80211.h cfg80211_ap_settings -!Finclude/net/cfg80211.h station_parameters -!Finclude/net/cfg80211.h rate_info_flags -!Finclude/net/cfg80211.h rate_info -!Finclude/net/cfg80211.h station_info -!Finclude/net/cfg80211.h monitor_flags -!Finclude/net/cfg80211.h mpath_info_flags -!Finclude/net/cfg80211.h mpath_info -!Finclude/net/cfg80211.h bss_parameters -!Finclude/net/cfg80211.h ieee80211_txq_params -!Finclude/net/cfg80211.h cfg80211_crypto_settings -!Finclude/net/cfg80211.h cfg80211_auth_request -!Finclude/net/cfg80211.h cfg80211_assoc_request -!Finclude/net/cfg80211.h cfg80211_deauth_request -!Finclude/net/cfg80211.h cfg80211_disassoc_request -!Finclude/net/cfg80211.h cfg80211_ibss_params -!Finclude/net/cfg80211.h cfg80211_connect_params -!Finclude/net/cfg80211.h cfg80211_pmksa -!Finclude/net/cfg80211.h cfg80211_rx_mlme_mgmt -!Finclude/net/cfg80211.h cfg80211_auth_timeout -!Finclude/net/cfg80211.h cfg80211_rx_assoc_resp -!Finclude/net/cfg80211.h cfg80211_assoc_timeout -!Finclude/net/cfg80211.h cfg80211_tx_mlme_mgmt -!Finclude/net/cfg80211.h cfg80211_ibss_joined -!Finclude/net/cfg80211.h cfg80211_connect_result -!Finclude/net/cfg80211.h cfg80211_roamed -!Finclude/net/cfg80211.h cfg80211_disconnected -!Finclude/net/cfg80211.h cfg80211_ready_on_channel -!Finclude/net/cfg80211.h cfg80211_remain_on_channel_expired -!Finclude/net/cfg80211.h cfg80211_new_sta -!Finclude/net/cfg80211.h cfg80211_rx_mgmt -!Finclude/net/cfg80211.h cfg80211_mgmt_tx_status -!Finclude/net/cfg80211.h cfg80211_cqm_rssi_notify -!Finclude/net/cfg80211.h cfg80211_cqm_pktloss_notify -!Finclude/net/cfg80211.h cfg80211_michael_mic_failure - </chapter> - <chapter> - <title>Scanning and BSS list handling</title> -!Pinclude/net/cfg80211.h Scanning and BSS list handling -!Finclude/net/cfg80211.h cfg80211_ssid -!Finclude/net/cfg80211.h cfg80211_scan_request -!Finclude/net/cfg80211.h cfg80211_scan_done -!Finclude/net/cfg80211.h cfg80211_bss -!Finclude/net/cfg80211.h cfg80211_inform_bss -!Finclude/net/cfg80211.h cfg80211_inform_bss_frame_data -!Finclude/net/cfg80211.h cfg80211_inform_bss_data -!Finclude/net/cfg80211.h cfg80211_unlink_bss -!Finclude/net/cfg80211.h cfg80211_find_ie -!Finclude/net/cfg80211.h ieee80211_bss_get_ie - </chapter> - <chapter> - <title>Utility functions</title> -!Pinclude/net/cfg80211.h Utility functions -!Finclude/net/cfg80211.h ieee80211_channel_to_frequency -!Finclude/net/cfg80211.h ieee80211_frequency_to_channel -!Finclude/net/cfg80211.h ieee80211_get_channel -!Finclude/net/cfg80211.h ieee80211_get_response_rate -!Finclude/net/cfg80211.h ieee80211_hdrlen -!Finclude/net/cfg80211.h ieee80211_get_hdrlen_from_skb -!Finclude/net/cfg80211.h ieee80211_radiotap_iterator - </chapter> - <chapter> - <title>Data path helpers</title> -!Pinclude/net/cfg80211.h Data path helpers -!Finclude/net/cfg80211.h ieee80211_data_to_8023 -!Finclude/net/cfg80211.h ieee80211_data_from_8023 -!Finclude/net/cfg80211.h ieee80211_amsdu_to_8023s -!Finclude/net/cfg80211.h cfg80211_classify8021d - </chapter> - <chapter> - <title>Regulatory enforcement infrastructure</title> -!Pinclude/net/cfg80211.h Regulatory enforcement infrastructure -!Finclude/net/cfg80211.h regulatory_hint -!Finclude/net/cfg80211.h wiphy_apply_custom_regulatory -!Finclude/net/cfg80211.h freq_reg_info - </chapter> - <chapter> - <title>RFkill integration</title> -!Pinclude/net/cfg80211.h RFkill integration -!Finclude/net/cfg80211.h wiphy_rfkill_set_hw_state -!Finclude/net/cfg80211.h wiphy_rfkill_start_polling -!Finclude/net/cfg80211.h wiphy_rfkill_stop_polling - </chapter> - <chapter> - <title>Test mode</title> -!Pinclude/net/cfg80211.h Test mode -!Finclude/net/cfg80211.h cfg80211_testmode_alloc_reply_skb -!Finclude/net/cfg80211.h cfg80211_testmode_reply -!Finclude/net/cfg80211.h cfg80211_testmode_alloc_event_skb -!Finclude/net/cfg80211.h cfg80211_testmode_event - </chapter> - </book> - <book id="mac80211-developers-guide"> - <bookinfo> - <title>The mac80211 subsystem</title> - <abstract> -!Pinclude/net/mac80211.h Introduction -!Pinclude/net/mac80211.h Warning - </abstract> - </bookinfo> - - <toc></toc> - - <!-- - Generally, this document shall be ordered by increasing complexity. - It is important to note that readers should be able to read only - the first few sections to get a working driver and only advanced - usage should require reading the full document. - --> - - <part> - <title>The basic mac80211 driver interface</title> - <partintro> - <para> - You should read and understand the information contained - within this part of the book while implementing a driver. - In some chapters, advanced usage is noted, that may be - skipped at first. - </para> - <para> - This part of the book only covers station and monitor mode - functionality, additional information required to implement - the other modes is covered in the second part of the book. - </para> - </partintro> - - <chapter id="basics"> - <title>Basic hardware handling</title> - <para>TBD</para> - <para> - This chapter shall contain information on getting a hw - struct allocated and registered with mac80211. - </para> - <para> - Since it is required to allocate rates/modes before registering - a hw struct, this chapter shall also contain information on setting - up the rate/mode structs. - </para> - <para> - Additionally, some discussion about the callbacks and - the general programming model should be in here, including - the definition of ieee80211_ops which will be referred to - a lot. - </para> - <para> - Finally, a discussion of hardware capabilities should be done - with references to other parts of the book. - </para> - <!-- intentionally multiple !F lines to get proper order --> -!Finclude/net/mac80211.h ieee80211_hw -!Finclude/net/mac80211.h ieee80211_hw_flags -!Finclude/net/mac80211.h SET_IEEE80211_DEV -!Finclude/net/mac80211.h SET_IEEE80211_PERM_ADDR -!Finclude/net/mac80211.h ieee80211_ops -!Finclude/net/mac80211.h ieee80211_alloc_hw -!Finclude/net/mac80211.h ieee80211_register_hw -!Finclude/net/mac80211.h ieee80211_unregister_hw -!Finclude/net/mac80211.h ieee80211_free_hw - </chapter> - - <chapter id="phy-handling"> - <title>PHY configuration</title> - <para>TBD</para> - <para> - This chapter should describe PHY handling including - start/stop callbacks and the various structures used. - </para> -!Finclude/net/mac80211.h ieee80211_conf -!Finclude/net/mac80211.h ieee80211_conf_flags - </chapter> - - <chapter id="iface-handling"> - <title>Virtual interfaces</title> - <para>TBD</para> - <para> - This chapter should describe virtual interface basics - that are relevant to the driver (VLANs, MGMT etc are not.) - It should explain the use of the add_iface/remove_iface - callbacks as well as the interface configuration callbacks. - </para> - <para>Things related to AP mode should be discussed there.</para> - <para> - Things related to supporting multiple interfaces should be - in the appropriate chapter, a BIG FAT note should be here about - this though and the recommendation to allow only a single - interface in STA mode at first! - </para> -!Finclude/net/mac80211.h ieee80211_vif - </chapter> - - <chapter id="rx-tx"> - <title>Receive and transmit processing</title> - <sect1> - <title>what should be here</title> - <para>TBD</para> - <para> - This should describe the receive and transmit - paths in mac80211/the drivers as well as - transmit status handling. - </para> - </sect1> - <sect1> - <title>Frame format</title> -!Pinclude/net/mac80211.h Frame format - </sect1> - <sect1> - <title>Packet alignment</title> -!Pnet/mac80211/rx.c Packet alignment - </sect1> - <sect1> - <title>Calling into mac80211 from interrupts</title> -!Pinclude/net/mac80211.h Calling mac80211 from interrupts - </sect1> - <sect1> - <title>functions/definitions</title> -!Finclude/net/mac80211.h ieee80211_rx_status -!Finclude/net/mac80211.h mac80211_rx_flags -!Finclude/net/mac80211.h mac80211_tx_info_flags -!Finclude/net/mac80211.h mac80211_tx_control_flags -!Finclude/net/mac80211.h mac80211_rate_control_flags -!Finclude/net/mac80211.h ieee80211_tx_rate -!Finclude/net/mac80211.h ieee80211_tx_info -!Finclude/net/mac80211.h ieee80211_tx_info_clear_status -!Finclude/net/mac80211.h ieee80211_rx -!Finclude/net/mac80211.h ieee80211_rx_ni -!Finclude/net/mac80211.h ieee80211_rx_irqsafe -!Finclude/net/mac80211.h ieee80211_tx_status -!Finclude/net/mac80211.h ieee80211_tx_status_ni -!Finclude/net/mac80211.h ieee80211_tx_status_irqsafe -!Finclude/net/mac80211.h ieee80211_rts_get -!Finclude/net/mac80211.h ieee80211_rts_duration -!Finclude/net/mac80211.h ieee80211_ctstoself_get -!Finclude/net/mac80211.h ieee80211_ctstoself_duration -!Finclude/net/mac80211.h ieee80211_generic_frame_duration -!Finclude/net/mac80211.h ieee80211_wake_queue -!Finclude/net/mac80211.h ieee80211_stop_queue -!Finclude/net/mac80211.h ieee80211_wake_queues -!Finclude/net/mac80211.h ieee80211_stop_queues -!Finclude/net/mac80211.h ieee80211_queue_stopped - </sect1> - </chapter> - - <chapter id="filters"> - <title>Frame filtering</title> -!Pinclude/net/mac80211.h Frame filtering -!Finclude/net/mac80211.h ieee80211_filter_flags - </chapter> - - <chapter id="workqueue"> - <title>The mac80211 workqueue</title> -!Pinclude/net/mac80211.h mac80211 workqueue -!Finclude/net/mac80211.h ieee80211_queue_work -!Finclude/net/mac80211.h ieee80211_queue_delayed_work - </chapter> - </part> - - <part id="advanced"> - <title>Advanced driver interface</title> - <partintro> - <para> - Information contained within this part of the book is - of interest only for advanced interaction of mac80211 - with drivers to exploit more hardware capabilities and - improve performance. - </para> - </partintro> - - <chapter id="led-support"> - <title>LED support</title> - <para> - Mac80211 supports various ways of blinking LEDs. Wherever possible, - device LEDs should be exposed as LED class devices and hooked up to - the appropriate trigger, which will then be triggered appropriately - by mac80211. - </para> -!Finclude/net/mac80211.h ieee80211_get_tx_led_name -!Finclude/net/mac80211.h ieee80211_get_rx_led_name -!Finclude/net/mac80211.h ieee80211_get_assoc_led_name -!Finclude/net/mac80211.h ieee80211_get_radio_led_name -!Finclude/net/mac80211.h ieee80211_tpt_blink -!Finclude/net/mac80211.h ieee80211_tpt_led_trigger_flags -!Finclude/net/mac80211.h ieee80211_create_tpt_led_trigger - </chapter> - - <chapter id="hardware-crypto-offload"> - <title>Hardware crypto acceleration</title> -!Pinclude/net/mac80211.h Hardware crypto acceleration - <!-- intentionally multiple !F lines to get proper order --> -!Finclude/net/mac80211.h set_key_cmd -!Finclude/net/mac80211.h ieee80211_key_conf -!Finclude/net/mac80211.h ieee80211_key_flags -!Finclude/net/mac80211.h ieee80211_get_tkip_p1k -!Finclude/net/mac80211.h ieee80211_get_tkip_p1k_iv -!Finclude/net/mac80211.h ieee80211_get_tkip_p2k - </chapter> - - <chapter id="powersave"> - <title>Powersave support</title> -!Pinclude/net/mac80211.h Powersave support - </chapter> - - <chapter id="beacon-filter"> - <title>Beacon filter support</title> -!Pinclude/net/mac80211.h Beacon filter support -!Finclude/net/mac80211.h ieee80211_beacon_loss - </chapter> - - <chapter id="qos"> - <title>Multiple queues and QoS support</title> - <para>TBD</para> -!Finclude/net/mac80211.h ieee80211_tx_queue_params - </chapter> - - <chapter id="AP"> - <title>Access point mode support</title> - <para>TBD</para> - <para>Some parts of the if_conf should be discussed here instead</para> - <para> - Insert notes about VLAN interfaces with hw crypto here or - in the hw crypto chapter. - </para> - <section id="ps-client"> - <title>support for powersaving clients</title> -!Pinclude/net/mac80211.h AP support for powersaving clients -!Finclude/net/mac80211.h ieee80211_get_buffered_bc -!Finclude/net/mac80211.h ieee80211_beacon_get -!Finclude/net/mac80211.h ieee80211_sta_eosp -!Finclude/net/mac80211.h ieee80211_frame_release_type -!Finclude/net/mac80211.h ieee80211_sta_ps_transition -!Finclude/net/mac80211.h ieee80211_sta_ps_transition_ni -!Finclude/net/mac80211.h ieee80211_sta_set_buffered -!Finclude/net/mac80211.h ieee80211_sta_block_awake - </section> - </chapter> - - <chapter id="multi-iface"> - <title>Supporting multiple virtual interfaces</title> - <para>TBD</para> - <para> - Note: WDS with identical MAC address should almost always be OK - </para> - <para> - Insert notes about having multiple virtual interfaces with - different MAC addresses here, note which configurations are - supported by mac80211, add notes about supporting hw crypto - with it. - </para> -!Finclude/net/mac80211.h ieee80211_iterate_active_interfaces -!Finclude/net/mac80211.h ieee80211_iterate_active_interfaces_atomic - </chapter> - - <chapter id="station-handling"> - <title>Station handling</title> - <para>TODO</para> -!Finclude/net/mac80211.h ieee80211_sta -!Finclude/net/mac80211.h sta_notify_cmd -!Finclude/net/mac80211.h ieee80211_find_sta -!Finclude/net/mac80211.h ieee80211_find_sta_by_ifaddr - </chapter> - - <chapter id="hardware-scan-offload"> - <title>Hardware scan offload</title> - <para>TBD</para> -!Finclude/net/mac80211.h ieee80211_scan_completed - </chapter> - - <chapter id="aggregation"> - <title>Aggregation</title> - <sect1> - <title>TX A-MPDU aggregation</title> -!Pnet/mac80211/agg-tx.c TX A-MPDU aggregation -!Cnet/mac80211/agg-tx.c - </sect1> - <sect1> - <title>RX A-MPDU aggregation</title> -!Pnet/mac80211/agg-rx.c RX A-MPDU aggregation -!Cnet/mac80211/agg-rx.c -!Finclude/net/mac80211.h ieee80211_ampdu_mlme_action - </sect1> - </chapter> - - <chapter id="smps"> - <title>Spatial Multiplexing Powersave (SMPS)</title> -!Pinclude/net/mac80211.h Spatial multiplexing power save -!Finclude/net/mac80211.h ieee80211_request_smps -!Finclude/net/mac80211.h ieee80211_smps_mode - </chapter> - </part> - - <part id="rate-control"> - <title>Rate control interface</title> - <partintro> - <para>TBD</para> - <para> - This part of the book describes the rate control algorithm - interface and how it relates to mac80211 and drivers. - </para> - </partintro> - <chapter id="ratecontrol-api"> - <title>Rate Control API</title> - <para>TBD</para> -!Finclude/net/mac80211.h ieee80211_start_tx_ba_session -!Finclude/net/mac80211.h ieee80211_start_tx_ba_cb_irqsafe -!Finclude/net/mac80211.h ieee80211_stop_tx_ba_session -!Finclude/net/mac80211.h ieee80211_stop_tx_ba_cb_irqsafe -!Finclude/net/mac80211.h ieee80211_rate_control_changed -!Finclude/net/mac80211.h ieee80211_tx_rate_control -!Finclude/net/mac80211.h rate_control_send_low - </chapter> - </part> - - <part id="internal"> - <title>Internals</title> - <partintro> - <para>TBD</para> - <para> - This part of the book describes mac80211 internals. - </para> - </partintro> - - <chapter id="key-handling"> - <title>Key handling</title> - <sect1> - <title>Key handling basics</title> -!Pnet/mac80211/key.c Key handling basics - </sect1> - <sect1> - <title>MORE TBD</title> - <para>TBD</para> - </sect1> - </chapter> - - <chapter id="rx-processing"> - <title>Receive processing</title> - <para>TBD</para> - </chapter> - - <chapter id="tx-processing"> - <title>Transmit processing</title> - <para>TBD</para> - </chapter> - - <chapter id="sta-info"> - <title>Station info handling</title> - <sect1> - <title>Programming information</title> -!Fnet/mac80211/sta_info.h sta_info -!Fnet/mac80211/sta_info.h ieee80211_sta_info_flags - </sect1> - <sect1> - <title>STA information lifetime rules</title> -!Pnet/mac80211/sta_info.c STA information lifetime rules - </sect1> - </chapter> - - <chapter id="aggregation-internals"> - <title>Aggregation</title> -!Fnet/mac80211/sta_info.h sta_ampdu_mlme -!Fnet/mac80211/sta_info.h tid_ampdu_tx -!Fnet/mac80211/sta_info.h tid_ampdu_rx - </chapter> - - <chapter id="synchronisation"> - <title>Synchronisation</title> - <para>TBD</para> - <para>Locking, lots of RCU</para> - </chapter> - </part> - </book> -</set> diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile deleted file mode 100644 index d70f9b68174e..000000000000 --- a/Documentation/DocBook/Makefile +++ /dev/null @@ -1,261 +0,0 @@ -### -# This makefile is used to generate the kernel documentation, -# primarily based on in-line comments in various source files. -# See Documentation/kernel-doc-nano-HOWTO.txt for instruction in how -# to document the SRC - and how to read it. -# To add a new book the only step required is to add the book to the -# list of DOCBOOKS. - -DOCBOOKS := z8530book.xml device-drivers.xml \ - kernel-hacking.xml kernel-locking.xml deviceiobook.xml \ - writing_usb_driver.xml networking.xml \ - kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \ - gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \ - genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \ - 80211.xml debugobjects.xml sh.xml regulator.xml \ - alsa-driver-api.xml writing-an-alsa-driver.xml \ - tracepoint.xml gpu.xml media_api.xml w1.xml \ - writing_musb_glue_layer.xml crypto-API.xml iio.xml - -include Documentation/DocBook/media/Makefile - -### -# The build process is as follows (targets): -# (xmldocs) [by docproc] -# file.tmpl --> file.xml +--> file.ps (psdocs) [by db2ps or xmlto] -# +--> file.pdf (pdfdocs) [by db2pdf or xmlto] -# +--> DIR=file (htmldocs) [by xmlto] -# +--> man/ (mandocs) [by xmlto] - - -# for PDF and PS output you can choose between xmlto and docbook-utils tools -PDF_METHOD = $(prefer-db2x) -PS_METHOD = $(prefer-db2x) - - -### -# The targets that may be used. -PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs - -targets += $(DOCBOOKS) -BOOKS := $(addprefix $(obj)/,$(DOCBOOKS)) -xmldocs: $(BOOKS) -sgmldocs: xmldocs - -PS := $(patsubst %.xml, %.ps, $(BOOKS)) -psdocs: $(PS) - -PDF := $(patsubst %.xml, %.pdf, $(BOOKS)) -pdfdocs: $(PDF) - -HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS))) -htmldocs: $(HTML) - $(call cmd,build_main_index) - $(call install_media_images) - -MAN := $(patsubst %.xml, %.9, $(BOOKS)) -mandocs: $(MAN) - find $(obj)/man -name '*.9' | xargs gzip -nf - -installmandocs: mandocs - mkdir -p /usr/local/man/man9/ - find $(obj)/man -name '*.9.gz' -printf '%h %f\n' | \ - sort -k 2 -k 1 | uniq -f 1 | sed -e 's: :/:' | \ - xargs install -m 644 -t /usr/local/man/man9/ - -### -#External programs used -KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref -KERNELDOC = $(srctree)/scripts/kernel-doc -DOCPROC = $(objtree)/scripts/docproc -CHECK_LC_CTYPE = $(objtree)/scripts/check-lc_ctype - -# Use a fixed encoding - UTF-8 if the C library has support built-in -# or ASCII if not -LC_CTYPE := $(call try-run, LC_CTYPE=C.UTF-8 $(CHECK_LC_CTYPE),C.UTF-8,C) -export LC_CTYPE - -XMLTOFLAGS = -m $(srctree)/$(src)/stylesheet.xsl -XMLTOFLAGS += --skip-validation - -### -# DOCPROC is used for two purposes: -# 1) To generate a dependency list for a .tmpl file -# 2) To preprocess a .tmpl file and call kernel-doc with -# appropriate parameters. -# The following rules are used to generate the .xml documentation -# required to generate the final targets. (ps, pdf, html). -quiet_cmd_docproc = DOCPROC $@ - cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $< >$@ -define rule_docproc - set -e; \ - $(if $($(quiet)cmd_$(1)),echo ' $($(quiet)cmd_$(1))';) \ - $(cmd_$(1)); \ - ( \ - echo 'cmd_$@ := $(cmd_$(1))'; \ - echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`; \ - ) > $(dir $@).$(notdir $@).cmd -endef - -%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE - $(call if_changed_rule,docproc) - -# Tell kbuild to always build the programs -always := $(hostprogs-y) - -notfoundtemplate = echo "*** You have to install docbook-utils or xmlto ***"; \ - exit 1 -db2xtemplate = db2TYPE -o $(dir $@) $< -xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $< - -# determine which methods are available -ifeq ($(shell which db2ps >/dev/null 2>&1 && echo found),found) - use-db2x = db2x - prefer-db2x = db2x -else - use-db2x = notfound - prefer-db2x = $(use-xmlto) -endif -ifeq ($(shell which xmlto >/dev/null 2>&1 && echo found),found) - use-xmlto = xmlto - prefer-xmlto = xmlto -else - use-xmlto = notfound - prefer-xmlto = $(use-db2x) -endif - -# the commands, generated from the chosen template -quiet_cmd_db2ps = PS $@ - cmd_db2ps = $(subst TYPE,ps, $($(PS_METHOD)template)) -%.ps : %.xml - $(call cmd,db2ps) - -quiet_cmd_db2pdf = PDF $@ - cmd_db2pdf = $(subst TYPE,pdf, $($(PDF_METHOD)template)) -%.pdf : %.xml - $(call cmd,db2pdf) - - -index = index.html -main_idx = $(obj)/$(index) -quiet_cmd_build_main_index = HTML $(main_idx) - cmd_build_main_index = rm -rf $(main_idx); \ - echo '<h1>Linux Kernel HTML Documentation</h1>' >> $(main_idx) && \ - echo '<h2>Kernel Version: $(KERNELVERSION)</h2>' >> $(main_idx) && \ - cat $(HTML) >> $(main_idx) - -quiet_cmd_db2html = HTML $@ - cmd_db2html = xmlto html $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \ - echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \ - $(patsubst %.html,%,$(notdir $@))</a><p>' > $@ - -### -# Rules to create an aux XML and .db, and use them to re-process the DocBook XML -# to fill internal hyperlinks - gen_aux_xml = : - quiet_gen_aux_xml = echo ' XMLREF $@' -silent_gen_aux_xml = : -%.aux.xml: %.xml - @$($(quiet)gen_aux_xml) - @rm -rf $@ - @(cat $< | egrep "^<refentry id" | egrep -o "\".*\"" | cut -f 2 -d \" > $<.db) - @$(KERNELDOCXMLREF) -db $<.db $< > $@ -.PRECIOUS: %.aux.xml - -%.html: %.aux.xml - @(which xmlto > /dev/null 2>&1) || \ - (echo "*** You need to install xmlto ***"; \ - exit 1) - @rm -rf $@ $(patsubst %.html,%,$@) - $(call cmd,db2html) - @if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \ - cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi - -quiet_cmd_db2man = MAN $@ - cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man/$(*F) $< ; fi -%.9 : %.xml - @(which xmlto > /dev/null 2>&1) || \ - (echo "*** You need to install xmlto ***"; \ - exit 1) - $(Q)mkdir -p $(obj)/man/$(*F) - $(call cmd,db2man) - @touch $@ - -### -# Rules to generate postscripts and PNG images from .fig format files -quiet_cmd_fig2eps = FIG2EPS $@ - cmd_fig2eps = fig2dev -Leps $< $@ - -%.eps: %.fig - @(which fig2dev > /dev/null 2>&1) || \ - (echo "*** You need to install transfig ***"; \ - exit 1) - $(call cmd,fig2eps) - -quiet_cmd_fig2png = FIG2PNG $@ - cmd_fig2png = fig2dev -Lpng $< $@ - -%.png: %.fig - @(which fig2dev > /dev/null 2>&1) || \ - (echo "*** You need to install transfig ***"; \ - exit 1) - $(call cmd,fig2png) - -### -# Rule to convert a .c file to inline XML documentation - gen_xml = : - quiet_gen_xml = echo ' GEN $@' -silent_gen_xml = : -%.xml: %.c - @$($(quiet)gen_xml) - @( \ - echo "<programlisting>"; \ - expand --tabs=8 < $< | \ - sed -e "s/&/\\&/g" \ - -e "s/</\\</g" \ - -e "s/>/\\>/g"; \ - echo "</programlisting>") > $@ - -### -# Help targets as used by the top-level makefile -dochelp: - @echo ' Linux kernel internal documentation in different formats:' - @echo ' htmldocs - HTML' - @echo ' pdfdocs - PDF' - @echo ' psdocs - Postscript' - @echo ' xmldocs - XML DocBook' - @echo ' mandocs - man pages' - @echo ' installmandocs - install man pages generated by mandocs' - @echo ' cleandocs - clean all generated DocBook files' - @echo - @echo 'make DOCBOOKS="s1.xml s2.xml" [target] Generate only docs s1.xml s2.xml' - @echo ' valid values for DOCBOOKS are: $(DOCBOOKS)' - - -### -# Temporary files left by various tools -clean-files := $(DOCBOOKS) \ - $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \ - $(patsubst %.xml, %.aux, $(DOCBOOKS)) \ - $(patsubst %.xml, %.tex, $(DOCBOOKS)) \ - $(patsubst %.xml, %.log, $(DOCBOOKS)) \ - $(patsubst %.xml, %.out, $(DOCBOOKS)) \ - $(patsubst %.xml, %.ps, $(DOCBOOKS)) \ - $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \ - $(patsubst %.xml, %.html, $(DOCBOOKS)) \ - $(patsubst %.xml, %.9, $(DOCBOOKS)) \ - $(patsubst %.xml, %.aux.xml, $(DOCBOOKS)) \ - $(patsubst %.xml, %.xml.db, $(DOCBOOKS)) \ - $(patsubst %.xml, %.xml, $(DOCBOOKS)) \ - $(index) - -clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man - -cleandocs: cleanmediadocs - $(Q)rm -f $(call objectify, $(clean-files)) - $(Q)rm -rf $(call objectify, $(clean-dirs)) - -# Declare the contents of the .PHONY variable as phony. We keep that -# information in a variable se we can use it in if_changed and friends. - -.PHONY: $(PHONY) diff --git a/Documentation/DocBook/alsa-driver-api.tmpl b/Documentation/DocBook/alsa-driver-api.tmpl deleted file mode 100644 index 53f439dcc94b..000000000000 --- a/Documentation/DocBook/alsa-driver-api.tmpl +++ /dev/null @@ -1,142 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<!-- ****************************************************** --> -<!-- Header --> -<!-- ****************************************************** --> -<book id="ALSA-Driver-API"> - <bookinfo> - <title>The ALSA Driver API</title> - - <legalnotice> - <para> - This document is free; you can redistribute it and/or modify it - under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - </para> - - <para> - This document is distributed in the hope that it will be useful, - but <emphasis>WITHOUT ANY WARRANTY</emphasis>; without even the - implied warranty of <emphasis>MERCHANTABILITY or FITNESS FOR A - PARTICULAR PURPOSE</emphasis>. See the GNU General Public License - for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - </legalnotice> - - </bookinfo> - -<toc></toc> - - <chapter><title>Management of Cards and Devices</title> - <sect1><title>Card Management</title> -!Esound/core/init.c - </sect1> - <sect1><title>Device Components</title> -!Esound/core/device.c - </sect1> - <sect1><title>Module requests and Device File Entries</title> -!Esound/core/sound.c - </sect1> - <sect1><title>Memory Management Helpers</title> -!Esound/core/memory.c -!Esound/core/memalloc.c - </sect1> - </chapter> - <chapter><title>PCM API</title> - <sect1><title>PCM Core</title> -!Esound/core/pcm.c -!Esound/core/pcm_lib.c -!Esound/core/pcm_native.c -!Iinclude/sound/pcm.h - </sect1> - <sect1><title>PCM Format Helpers</title> -!Esound/core/pcm_misc.c - </sect1> - <sect1><title>PCM Memory Management</title> -!Esound/core/pcm_memory.c - </sect1> - <sect1><title>PCM DMA Engine API</title> -!Esound/core/pcm_dmaengine.c -!Iinclude/sound/dmaengine_pcm.h - </sect1> - </chapter> - <chapter><title>Control/Mixer API</title> - <sect1><title>General Control Interface</title> -!Esound/core/control.c - </sect1> - <sect1><title>AC97 Codec API</title> -!Esound/pci/ac97/ac97_codec.c -!Esound/pci/ac97/ac97_pcm.c - </sect1> - <sect1><title>Virtual Master Control API</title> -!Esound/core/vmaster.c -!Iinclude/sound/control.h - </sect1> - </chapter> - <chapter><title>MIDI API</title> - <sect1><title>Raw MIDI API</title> -!Esound/core/rawmidi.c - </sect1> - <sect1><title>MPU401-UART API</title> -!Esound/drivers/mpu401/mpu401_uart.c - </sect1> - </chapter> - <chapter><title>Proc Info API</title> - <sect1><title>Proc Info Interface</title> -!Esound/core/info.c - </sect1> - </chapter> - <chapter><title>Compress Offload</title> - <sect1><title>Compress Offload API</title> -!Esound/core/compress_offload.c -!Iinclude/uapi/sound/compress_offload.h -!Iinclude/uapi/sound/compress_params.h -!Iinclude/sound/compress_driver.h - </sect1> - </chapter> - <chapter><title>ASoC</title> - <sect1><title>ASoC Core API</title> -!Iinclude/sound/soc.h -!Esound/soc/soc-core.c -<!-- !Esound/soc/soc-cache.c no docbook comments here --> -!Esound/soc/soc-devres.c -!Esound/soc/soc-io.c -!Esound/soc/soc-pcm.c -!Esound/soc/soc-ops.c -!Esound/soc/soc-compress.c - </sect1> - <sect1><title>ASoC DAPM API</title> -!Esound/soc/soc-dapm.c - </sect1> - <sect1><title>ASoC DMA Engine API</title> -!Esound/soc/soc-generic-dmaengine-pcm.c - </sect1> - </chapter> - <chapter><title>Miscellaneous Functions</title> - <sect1><title>Hardware-Dependent Devices API</title> -!Esound/core/hwdep.c - </sect1> - <sect1><title>Jack Abstraction Layer API</title> -!Iinclude/sound/jack.h -!Esound/core/jack.c -!Esound/soc/soc-jack.c - </sect1> - <sect1><title>ISA DMA Helpers</title> -!Esound/core/isadma.c - </sect1> - <sect1><title>Other Helper Macros</title> -!Iinclude/sound/core.h - </sect1> - </chapter> - -</book> diff --git a/Documentation/DocBook/crypto-API.tmpl b/Documentation/DocBook/crypto-API.tmpl deleted file mode 100644 index 07df23ea06e4..000000000000 --- a/Documentation/DocBook/crypto-API.tmpl +++ /dev/null @@ -1,2124 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="KernelCryptoAPI"> - <bookinfo> - <title>Linux Kernel Crypto API</title> - - <authorgroup> - <author> - <firstname>Stephan</firstname> - <surname>Mueller</surname> - <affiliation> - <address> - <email>smueller@chronox.de</email> - </address> - </affiliation> - </author> - <author> - <firstname>Marek</firstname> - <surname>Vasut</surname> - <affiliation> - <address> - <email>marek@denx.de</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2014</year> - <holder>Stephan Mueller</holder> - </copyright> - - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - - <toc></toc> - - <chapter id="Intro"> - <title>Kernel Crypto API Interface Specification</title> - - <sect1><title>Introduction</title> - - <para> - The kernel crypto API offers a rich set of cryptographic ciphers as - well as other data transformation mechanisms and methods to invoke - these. This document contains a description of the API and provides - example code. - </para> - - <para> - To understand and properly use the kernel crypto API a brief - explanation of its structure is given. Based on the architecture, - the API can be separated into different components. Following the - architecture specification, hints to developers of ciphers are - provided. Pointers to the API function call documentation are - given at the end. - </para> - - <para> - The kernel crypto API refers to all algorithms as "transformations". - Therefore, a cipher handle variable usually has the name "tfm". - Besides cryptographic operations, the kernel crypto API also knows - compression transformations and handles them the same way as ciphers. - </para> - - <para> - The kernel crypto API serves the following entity types: - - <itemizedlist> - <listitem> - <para>consumers requesting cryptographic services</para> - </listitem> - <listitem> - <para>data transformation implementations (typically ciphers) - that can be called by consumers using the kernel crypto - API</para> - </listitem> - </itemizedlist> - </para> - - <para> - This specification is intended for consumers of the kernel crypto - API as well as for developers implementing ciphers. This API - specification, however, does not discuss all API calls available - to data transformation implementations (i.e. implementations of - ciphers and other transformations (such as CRC or even compression - algorithms) that can register with the kernel crypto API). - </para> - - <para> - Note: The terms "transformation" and cipher algorithm are used - interchangeably. - </para> - </sect1> - - <sect1><title>Terminology</title> - <para> - The transformation implementation is an actual code or interface - to hardware which implements a certain transformation with precisely - defined behavior. - </para> - - <para> - The transformation object (TFM) is an instance of a transformation - implementation. There can be multiple transformation objects - associated with a single transformation implementation. Each of - those transformation objects is held by a crypto API consumer or - another transformation. Transformation object is allocated when a - crypto API consumer requests a transformation implementation. - The consumer is then provided with a structure, which contains - a transformation object (TFM). - </para> - - <para> - The structure that contains transformation objects may also be - referred to as a "cipher handle". Such a cipher handle is always - subject to the following phases that are reflected in the API calls - applicable to such a cipher handle: - </para> - - <orderedlist> - <listitem> - <para>Initialization of a cipher handle.</para> - </listitem> - <listitem> - <para>Execution of all intended cipher operations applicable - for the handle where the cipher handle must be furnished to - every API call.</para> - </listitem> - <listitem> - <para>Destruction of a cipher handle.</para> - </listitem> - </orderedlist> - - <para> - When using the initialization API calls, a cipher handle is - created and returned to the consumer. Therefore, please refer - to all initialization API calls that refer to the data - structure type a consumer is expected to receive and subsequently - to use. The initialization API calls have all the same naming - conventions of crypto_alloc_*. - </para> - - <para> - The transformation context is private data associated with - the transformation object. - </para> - </sect1> - </chapter> - - <chapter id="Architecture"><title>Kernel Crypto API Architecture</title> - <sect1><title>Cipher algorithm types</title> - <para> - The kernel crypto API provides different API calls for the - following cipher types: - - <itemizedlist> - <listitem><para>Symmetric ciphers</para></listitem> - <listitem><para>AEAD ciphers</para></listitem> - <listitem><para>Message digest, including keyed message digest</para></listitem> - <listitem><para>Random number generation</para></listitem> - <listitem><para>User space interface</para></listitem> - </itemizedlist> - </para> - </sect1> - - <sect1><title>Ciphers And Templates</title> - <para> - The kernel crypto API provides implementations of single block - ciphers and message digests. In addition, the kernel crypto API - provides numerous "templates" that can be used in conjunction - with the single block ciphers and message digests. Templates - include all types of block chaining mode, the HMAC mechanism, etc. - </para> - - <para> - Single block ciphers and message digests can either be directly - used by a caller or invoked together with a template to form - multi-block ciphers or keyed message digests. - </para> - - <para> - A single block cipher may even be called with multiple templates. - However, templates cannot be used without a single cipher. - </para> - - <para> - See /proc/crypto and search for "name". For example: - - <itemizedlist> - <listitem><para>aes</para></listitem> - <listitem><para>ecb(aes)</para></listitem> - <listitem><para>cmac(aes)</para></listitem> - <listitem><para>ccm(aes)</para></listitem> - <listitem><para>rfc4106(gcm(aes))</para></listitem> - <listitem><para>sha1</para></listitem> - <listitem><para>hmac(sha1)</para></listitem> - <listitem><para>authenc(hmac(sha1),cbc(aes))</para></listitem> - </itemizedlist> - </para> - - <para> - In these examples, "aes" and "sha1" are the ciphers and all - others are the templates. - </para> - </sect1> - - <sect1><title>Synchronous And Asynchronous Operation</title> - <para> - The kernel crypto API provides synchronous and asynchronous - API operations. - </para> - - <para> - When using the synchronous API operation, the caller invokes - a cipher operation which is performed synchronously by the - kernel crypto API. That means, the caller waits until the - cipher operation completes. Therefore, the kernel crypto API - calls work like regular function calls. For synchronous - operation, the set of API calls is small and conceptually - similar to any other crypto library. - </para> - - <para> - Asynchronous operation is provided by the kernel crypto API - which implies that the invocation of a cipher operation will - complete almost instantly. That invocation triggers the - cipher operation but it does not signal its completion. Before - invoking a cipher operation, the caller must provide a callback - function the kernel crypto API can invoke to signal the - completion of the cipher operation. Furthermore, the caller - must ensure it can handle such asynchronous events by applying - appropriate locking around its data. The kernel crypto API - does not perform any special serialization operation to protect - the caller's data integrity. - </para> - </sect1> - - <sect1><title>Crypto API Cipher References And Priority</title> - <para> - A cipher is referenced by the caller with a string. That string - has the following semantics: - - <programlisting> - template(single block cipher) - </programlisting> - - where "template" and "single block cipher" is the aforementioned - template and single block cipher, respectively. If applicable, - additional templates may enclose other templates, such as - - <programlisting> - template1(template2(single block cipher))) - </programlisting> - </para> - - <para> - The kernel crypto API may provide multiple implementations of a - template or a single block cipher. For example, AES on newer - Intel hardware has the following implementations: AES-NI, - assembler implementation, or straight C. Now, when using the - string "aes" with the kernel crypto API, which cipher - implementation is used? The answer to that question is the - priority number assigned to each cipher implementation by the - kernel crypto API. When a caller uses the string to refer to a - cipher during initialization of a cipher handle, the kernel - crypto API looks up all implementations providing an - implementation with that name and selects the implementation - with the highest priority. - </para> - - <para> - Now, a caller may have the need to refer to a specific cipher - implementation and thus does not want to rely on the - priority-based selection. To accommodate this scenario, the - kernel crypto API allows the cipher implementation to register - a unique name in addition to common names. When using that - unique name, a caller is therefore always sure to refer to - the intended cipher implementation. - </para> - - <para> - The list of available ciphers is given in /proc/crypto. However, - that list does not specify all possible permutations of - templates and ciphers. Each block listed in /proc/crypto may - contain the following information -- if one of the components - listed as follows are not applicable to a cipher, it is not - displayed: - </para> - - <itemizedlist> - <listitem> - <para>name: the generic name of the cipher that is subject - to the priority-based selection -- this name can be used by - the cipher allocation API calls (all names listed above are - examples for such generic names)</para> - </listitem> - <listitem> - <para>driver: the unique name of the cipher -- this name can - be used by the cipher allocation API calls</para> - </listitem> - <listitem> - <para>module: the kernel module providing the cipher - implementation (or "kernel" for statically linked ciphers)</para> - </listitem> - <listitem> - <para>priority: the priority value of the cipher implementation</para> - </listitem> - <listitem> - <para>refcnt: the reference count of the respective cipher - (i.e. the number of current consumers of this cipher)</para> - </listitem> - <listitem> - <para>selftest: specification whether the self test for the - cipher passed</para> - </listitem> - <listitem> - <para>type: - <itemizedlist> - <listitem> - <para>blkcipher for synchronous block ciphers</para> - </listitem> - <listitem> - <para>ablkcipher for asynchronous block ciphers</para> - </listitem> - <listitem> - <para>cipher for single block ciphers that may be used with - an additional template</para> - </listitem> - <listitem> - <para>shash for synchronous message digest</para> - </listitem> - <listitem> - <para>ahash for asynchronous message digest</para> - </listitem> - <listitem> - <para>aead for AEAD cipher type</para> - </listitem> - <listitem> - <para>compression for compression type transformations</para> - </listitem> - <listitem> - <para>rng for random number generator</para> - </listitem> - <listitem> - <para>givcipher for cipher with associated IV generator - (see the geniv entry below for the specification of the - IV generator type used by the cipher implementation)</para> - </listitem> - </itemizedlist> - </para> - </listitem> - <listitem> - <para>blocksize: blocksize of cipher in bytes</para> - </listitem> - <listitem> - <para>keysize: key size in bytes</para> - </listitem> - <listitem> - <para>ivsize: IV size in bytes</para> - </listitem> - <listitem> - <para>seedsize: required size of seed data for random number - generator</para> - </listitem> - <listitem> - <para>digestsize: output size of the message digest</para> - </listitem> - <listitem> - <para>geniv: IV generation type: - <itemizedlist> - <listitem> - <para>eseqiv for encrypted sequence number based IV - generation</para> - </listitem> - <listitem> - <para>seqiv for sequence number based IV generation</para> - </listitem> - <listitem> - <para>chainiv for chain iv generation</para> - </listitem> - <listitem> - <para><builtin> is a marker that the cipher implements - IV generation and handling as it is specific to the given - cipher</para> - </listitem> - </itemizedlist> - </para> - </listitem> - </itemizedlist> - </sect1> - - <sect1><title>Key Sizes</title> - <para> - When allocating a cipher handle, the caller only specifies the - cipher type. Symmetric ciphers, however, typically support - multiple key sizes (e.g. AES-128 vs. AES-192 vs. AES-256). - These key sizes are determined with the length of the provided - key. Thus, the kernel crypto API does not provide a separate - way to select the particular symmetric cipher key size. - </para> - </sect1> - - <sect1><title>Cipher Allocation Type And Masks</title> - <para> - The different cipher handle allocation functions allow the - specification of a type and mask flag. Both parameters have - the following meaning (and are therefore not covered in the - subsequent sections). - </para> - - <para> - The type flag specifies the type of the cipher algorithm. - The caller usually provides a 0 when the caller wants the - default handling. Otherwise, the caller may provide the - following selections which match the the aforementioned - cipher types: - </para> - - <itemizedlist> - <listitem> - <para>CRYPTO_ALG_TYPE_CIPHER Single block cipher</para> - </listitem> - <listitem> - <para>CRYPTO_ALG_TYPE_COMPRESS Compression</para> - </listitem> - <listitem> - <para>CRYPTO_ALG_TYPE_AEAD Authenticated Encryption with - Associated Data (MAC)</para> - </listitem> - <listitem> - <para>CRYPTO_ALG_TYPE_BLKCIPHER Synchronous multi-block cipher</para> - </listitem> - <listitem> - <para>CRYPTO_ALG_TYPE_ABLKCIPHER Asynchronous multi-block cipher</para> - </listitem> - <listitem> - <para>CRYPTO_ALG_TYPE_GIVCIPHER Asynchronous multi-block - cipher packed together with an IV generator (see geniv field - in the /proc/crypto listing for the known IV generators)</para> - </listitem> - <listitem> - <para>CRYPTO_ALG_TYPE_DIGEST Raw message digest</para> - </listitem> - <listitem> - <para>CRYPTO_ALG_TYPE_HASH Alias for CRYPTO_ALG_TYPE_DIGEST</para> - </listitem> - <listitem> - <para>CRYPTO_ALG_TYPE_SHASH Synchronous multi-block hash</para> - </listitem> - <listitem> - <para>CRYPTO_ALG_TYPE_AHASH Asynchronous multi-block hash</para> - </listitem> - <listitem> - <para>CRYPTO_ALG_TYPE_RNG Random Number Generation</para> - </listitem> - <listitem> - <para>CRYPTO_ALG_TYPE_PCOMPRESS Enhanced version of - CRYPTO_ALG_TYPE_COMPRESS allowing for segmented compression / - decompression instead of performing the operation on one - segment only. CRYPTO_ALG_TYPE_PCOMPRESS is intended to replace - CRYPTO_ALG_TYPE_COMPRESS once existing consumers are converted.</para> - </listitem> - </itemizedlist> - - <para> - The mask flag restricts the type of cipher. The only allowed - flag is CRYPTO_ALG_ASYNC to restrict the cipher lookup function - to asynchronous ciphers. Usually, a caller provides a 0 for the - mask flag. - </para> - - <para> - When the caller provides a mask and type specification, the - caller limits the search the kernel crypto API can perform for - a suitable cipher implementation for the given cipher name. - That means, even when a caller uses a cipher name that exists - during its initialization call, the kernel crypto API may not - select it due to the used type and mask field. - </para> - </sect1> - - <sect1><title>Internal Structure of Kernel Crypto API</title> - - <para> - The kernel crypto API has an internal structure where a cipher - implementation may use many layers and indirections. This section - shall help to clarify how the kernel crypto API uses - various components to implement the complete cipher. - </para> - - <para> - The following subsections explain the internal structure based - on existing cipher implementations. The first section addresses - the most complex scenario where all other scenarios form a logical - subset. - </para> - - <sect2><title>Generic AEAD Cipher Structure</title> - - <para> - The following ASCII art decomposes the kernel crypto API layers - when using the AEAD cipher with the automated IV generation. The - shown example is used by the IPSEC layer. - </para> - - <para> - For other use cases of AEAD ciphers, the ASCII art applies as - well, but the caller may not use the AEAD cipher with a separate - IV generator. In this case, the caller must generate the IV. - </para> - - <para> - The depicted example decomposes the AEAD cipher of GCM(AES) based - on the generic C implementations (gcm.c, aes-generic.c, ctr.c, - ghash-generic.c, seqiv.c). The generic implementation serves as an - example showing the complete logic of the kernel crypto API. - </para> - - <para> - It is possible that some streamlined cipher implementations (like - AES-NI) provide implementations merging aspects which in the view - of the kernel crypto API cannot be decomposed into layers any more. - In case of the AES-NI implementation, the CTR mode, the GHASH - implementation and the AES cipher are all merged into one cipher - implementation registered with the kernel crypto API. In this case, - the concept described by the following ASCII art applies too. However, - the decomposition of GCM into the individual sub-components - by the kernel crypto API is not done any more. - </para> - - <para> - Each block in the following ASCII art is an independent cipher - instance obtained from the kernel crypto API. Each block - is accessed by the caller or by other blocks using the API functions - defined by the kernel crypto API for the cipher implementation type. - </para> - - <para> - The blocks below indicate the cipher type as well as the specific - logic implemented in the cipher. - </para> - - <para> - The ASCII art picture also indicates the call structure, i.e. who - calls which component. The arrows point to the invoked block - where the caller uses the API applicable to the cipher type - specified for the block. - </para> - - <programlisting> -<![CDATA[ -kernel crypto API | IPSEC Layer - | -+-----------+ | -| | (1) -| aead | <----------------------------------- esp_output -| (seqiv) | ---+ -+-----------+ | - | (2) -+-----------+ | -| | <--+ (2) -| aead | <----------------------------------- esp_input -| (gcm) | ------------+ -+-----------+ | - | (3) | (5) - v v -+-----------+ +-----------+ -| | | | -| ablkcipher| | ahash | -| (ctr) | ---+ | (ghash) | -+-----------+ | +-----------+ - | -+-----------+ | (4) -| | <--+ -| cipher | -| (aes) | -+-----------+ -]]> - </programlisting> - - <para> - The following call sequence is applicable when the IPSEC layer - triggers an encryption operation with the esp_output function. During - configuration, the administrator set up the use of rfc4106(gcm(aes)) as - the cipher for ESP. The following call sequence is now depicted in the - ASCII art above: - </para> - - <orderedlist> - <listitem> - <para> - esp_output() invokes crypto_aead_encrypt() to trigger an encryption - operation of the AEAD cipher with IV generator. - </para> - - <para> - In case of GCM, the SEQIV implementation is registered as GIVCIPHER - in crypto_rfc4106_alloc(). - </para> - - <para> - The SEQIV performs its operation to generate an IV where the core - function is seqiv_geniv(). - </para> - </listitem> - - <listitem> - <para> - Now, SEQIV uses the AEAD API function calls to invoke the associated - AEAD cipher. In our case, during the instantiation of SEQIV, the - cipher handle for GCM is provided to SEQIV. This means that SEQIV - invokes AEAD cipher operations with the GCM cipher handle. - </para> - - <para> - During instantiation of the GCM handle, the CTR(AES) and GHASH - ciphers are instantiated. The cipher handles for CTR(AES) and GHASH - are retained for later use. - </para> - - <para> - The GCM implementation is responsible to invoke the CTR mode AES and - the GHASH cipher in the right manner to implement the GCM - specification. - </para> - </listitem> - - <listitem> - <para> - The GCM AEAD cipher type implementation now invokes the ABLKCIPHER API - with the instantiated CTR(AES) cipher handle. - </para> - - <para> - During instantiation of the CTR(AES) cipher, the CIPHER type - implementation of AES is instantiated. The cipher handle for AES is - retained. - </para> - - <para> - That means that the ABLKCIPHER implementation of CTR(AES) only - implements the CTR block chaining mode. After performing the block - chaining operation, the CIPHER implementation of AES is invoked. - </para> - </listitem> - - <listitem> - <para> - The ABLKCIPHER of CTR(AES) now invokes the CIPHER API with the AES - cipher handle to encrypt one block. - </para> - </listitem> - - <listitem> - <para> - The GCM AEAD implementation also invokes the GHASH cipher - implementation via the AHASH API. - </para> - </listitem> - </orderedlist> - - <para> - When the IPSEC layer triggers the esp_input() function, the same call - sequence is followed with the only difference that the operation starts - with step (2). - </para> - </sect2> - - <sect2><title>Generic Block Cipher Structure</title> - <para> - Generic block ciphers follow the same concept as depicted with the ASCII - art picture above. - </para> - - <para> - For example, CBC(AES) is implemented with cbc.c, and aes-generic.c. The - ASCII art picture above applies as well with the difference that only - step (4) is used and the ABLKCIPHER block chaining mode is CBC. - </para> - </sect2> - - <sect2><title>Generic Keyed Message Digest Structure</title> - <para> - Keyed message digest implementations again follow the same concept as - depicted in the ASCII art picture above. - </para> - - <para> - For example, HMAC(SHA256) is implemented with hmac.c and - sha256_generic.c. The following ASCII art illustrates the - implementation: - </para> - - <programlisting> -<![CDATA[ -kernel crypto API | Caller - | -+-----------+ (1) | -| | <------------------ some_function -| ahash | -| (hmac) | ---+ -+-----------+ | - | (2) -+-----------+ | -| | <--+ -| shash | -| (sha256) | -+-----------+ -]]> - </programlisting> - - <para> - The following call sequence is applicable when a caller triggers - an HMAC operation: - </para> - - <orderedlist> - <listitem> - <para> - The AHASH API functions are invoked by the caller. The HMAC - implementation performs its operation as needed. - </para> - - <para> - During initialization of the HMAC cipher, the SHASH cipher type of - SHA256 is instantiated. The cipher handle for the SHA256 instance is - retained. - </para> - - <para> - At one time, the HMAC implementation requires a SHA256 operation - where the SHA256 cipher handle is used. - </para> - </listitem> - - <listitem> - <para> - The HMAC instance now invokes the SHASH API with the SHA256 - cipher handle to calculate the message digest. - </para> - </listitem> - </orderedlist> - </sect2> - </sect1> - </chapter> - - <chapter id="Development"><title>Developing Cipher Algorithms</title> - <sect1><title>Registering And Unregistering Transformation</title> - <para> - There are three distinct types of registration functions in - the Crypto API. One is used to register a generic cryptographic - transformation, while the other two are specific to HASH - transformations and COMPRESSion. We will discuss the latter - two in a separate chapter, here we will only look at the - generic ones. - </para> - - <para> - Before discussing the register functions, the data structure - to be filled with each, struct crypto_alg, must be considered - -- see below for a description of this data structure. - </para> - - <para> - The generic registration functions can be found in - include/linux/crypto.h and their definition can be seen below. - The former function registers a single transformation, while - the latter works on an array of transformation descriptions. - The latter is useful when registering transformations in bulk. - </para> - - <programlisting> - int crypto_register_alg(struct crypto_alg *alg); - int crypto_register_algs(struct crypto_alg *algs, int count); - </programlisting> - - <para> - The counterparts to those functions are listed below. - </para> - - <programlisting> - int crypto_unregister_alg(struct crypto_alg *alg); - int crypto_unregister_algs(struct crypto_alg *algs, int count); - </programlisting> - - <para> - Notice that both registration and unregistration functions - do return a value, so make sure to handle errors. A return - code of zero implies success. Any return code < 0 implies - an error. - </para> - - <para> - The bulk registration / unregistration functions require - that struct crypto_alg is an array of count size. These - functions simply loop over that array and register / - unregister each individual algorithm. If an error occurs, - the loop is terminated at the offending algorithm definition. - That means, the algorithms prior to the offending algorithm - are successfully registered. Note, the caller has no way of - knowing which cipher implementations have successfully - registered. If this is important to know, the caller should - loop through the different implementations using the single - instance *_alg functions for each individual implementation. - </para> - </sect1> - - <sect1><title>Single-Block Symmetric Ciphers [CIPHER]</title> - <para> - Example of transformations: aes, arc4, ... - </para> - - <para> - This section describes the simplest of all transformation - implementations, that being the CIPHER type used for symmetric - ciphers. The CIPHER type is used for transformations which - operate on exactly one block at a time and there are no - dependencies between blocks at all. - </para> - - <sect2><title>Registration specifics</title> - <para> - The registration of [CIPHER] algorithm is specific in that - struct crypto_alg field .cra_type is empty. The .cra_u.cipher - has to be filled in with proper callbacks to implement this - transformation. - </para> - - <para> - See struct cipher_alg below. - </para> - </sect2> - - <sect2><title>Cipher Definition With struct cipher_alg</title> - <para> - Struct cipher_alg defines a single block cipher. - </para> - - <para> - Here are schematics of how these functions are called when - operated from other part of the kernel. Note that the - .cia_setkey() call might happen before or after any of these - schematics happen, but must not happen during any of these - are in-flight. - </para> - - <para> - <programlisting> - KEY ---. PLAINTEXT ---. - v v - .cia_setkey() -> .cia_encrypt() - | - '-----> CIPHERTEXT - </programlisting> - </para> - - <para> - Please note that a pattern where .cia_setkey() is called - multiple times is also valid: - </para> - - <para> - <programlisting> - - KEY1 --. PLAINTEXT1 --. KEY2 --. PLAINTEXT2 --. - v v v v - .cia_setkey() -> .cia_encrypt() -> .cia_setkey() -> .cia_encrypt() - | | - '---> CIPHERTEXT1 '---> CIPHERTEXT2 - </programlisting> - </para> - - </sect2> - </sect1> - - <sect1><title>Multi-Block Ciphers [BLKCIPHER] [ABLKCIPHER]</title> - <para> - Example of transformations: cbc(aes), ecb(arc4), ... - </para> - - <para> - This section describes the multi-block cipher transformation - implementations for both synchronous [BLKCIPHER] and - asynchronous [ABLKCIPHER] case. The multi-block ciphers are - used for transformations which operate on scatterlists of - data supplied to the transformation functions. They output - the result into a scatterlist of data as well. - </para> - - <sect2><title>Registration Specifics</title> - - <para> - The registration of [BLKCIPHER] or [ABLKCIPHER] algorithms - is one of the most standard procedures throughout the crypto API. - </para> - - <para> - Note, if a cipher implementation requires a proper alignment - of data, the caller should use the functions of - crypto_blkcipher_alignmask() or crypto_ablkcipher_alignmask() - respectively to identify a memory alignment mask. The kernel - crypto API is able to process requests that are unaligned. - This implies, however, additional overhead as the kernel - crypto API needs to perform the realignment of the data which - may imply moving of data. - </para> - </sect2> - - <sect2><title>Cipher Definition With struct blkcipher_alg and ablkcipher_alg</title> - <para> - Struct blkcipher_alg defines a synchronous block cipher whereas - struct ablkcipher_alg defines an asynchronous block cipher. - </para> - - <para> - Please refer to the single block cipher description for schematics - of the block cipher usage. The usage patterns are exactly the same - for [ABLKCIPHER] and [BLKCIPHER] as they are for plain [CIPHER]. - </para> - </sect2> - - <sect2><title>Specifics Of Asynchronous Multi-Block Cipher</title> - <para> - There are a couple of specifics to the [ABLKCIPHER] interface. - </para> - - <para> - First of all, some of the drivers will want to use the - Generic ScatterWalk in case the hardware needs to be fed - separate chunks of the scatterlist which contains the - plaintext and will contain the ciphertext. Please refer - to the ScatterWalk interface offered by the Linux kernel - scatter / gather list implementation. - </para> - </sect2> - </sect1> - - <sect1><title>Hashing [HASH]</title> - - <para> - Example of transformations: crc32, md5, sha1, sha256,... - </para> - - <sect2><title>Registering And Unregistering The Transformation</title> - - <para> - There are multiple ways to register a HASH transformation, - depending on whether the transformation is synchronous [SHASH] - or asynchronous [AHASH] and the amount of HASH transformations - we are registering. You can find the prototypes defined in - include/crypto/internal/hash.h: - </para> - - <programlisting> - int crypto_register_ahash(struct ahash_alg *alg); - - int crypto_register_shash(struct shash_alg *alg); - int crypto_register_shashes(struct shash_alg *algs, int count); - </programlisting> - - <para> - The respective counterparts for unregistering the HASH - transformation are as follows: - </para> - - <programlisting> - int crypto_unregister_ahash(struct ahash_alg *alg); - - int crypto_unregister_shash(struct shash_alg *alg); - int crypto_unregister_shashes(struct shash_alg *algs, int count); - </programlisting> - </sect2> - - <sect2><title>Cipher Definition With struct shash_alg and ahash_alg</title> - <para> - Here are schematics of how these functions are called when - operated from other part of the kernel. Note that the .setkey() - call might happen before or after any of these schematics happen, - but must not happen during any of these are in-flight. Please note - that calling .init() followed immediately by .finish() is also a - perfectly valid transformation. - </para> - - <programlisting> - I) DATA -----------. - v - .init() -> .update() -> .final() ! .update() might not be called - ^ | | at all in this scenario. - '----' '---> HASH - - II) DATA -----------.-----------. - v v - .init() -> .update() -> .finup() ! .update() may not be called - ^ | | at all in this scenario. - '----' '---> HASH - - III) DATA -----------. - v - .digest() ! The entire process is handled - | by the .digest() call. - '---------------> HASH - </programlisting> - - <para> - Here is a schematic of how the .export()/.import() functions are - called when used from another part of the kernel. - </para> - - <programlisting> - KEY--. DATA--. - v v ! .update() may not be called - .setkey() -> .init() -> .update() -> .export() at all in this scenario. - ^ | | - '-----' '--> PARTIAL_HASH - - ----------- other transformations happen here ----------- - - PARTIAL_HASH--. DATA1--. - v v - .import -> .update() -> .final() ! .update() may not be called - ^ | | at all in this scenario. - '----' '--> HASH1 - - PARTIAL_HASH--. DATA2-. - v v - .import -> .finup() - | - '---------------> HASH2 - </programlisting> - </sect2> - - <sect2><title>Specifics Of Asynchronous HASH Transformation</title> - <para> - Some of the drivers will want to use the Generic ScatterWalk - in case the implementation needs to be fed separate chunks of the - scatterlist which contains the input data. The buffer containing - the resulting hash will always be properly aligned to - .cra_alignmask so there is no need to worry about this. - </para> - </sect2> - </sect1> - </chapter> - - <chapter id="User"><title>User Space Interface</title> - <sect1><title>Introduction</title> - <para> - The concepts of the kernel crypto API visible to kernel space is fully - applicable to the user space interface as well. Therefore, the kernel - crypto API high level discussion for the in-kernel use cases applies - here as well. - </para> - - <para> - The major difference, however, is that user space can only act as a - consumer and never as a provider of a transformation or cipher algorithm. - </para> - - <para> - The following covers the user space interface exported by the kernel - crypto API. A working example of this description is libkcapi that - can be obtained from [1]. That library can be used by user space - applications that require cryptographic services from the kernel. - </para> - - <para> - Some details of the in-kernel kernel crypto API aspects do not - apply to user space, however. This includes the difference between - synchronous and asynchronous invocations. The user space API call - is fully synchronous. - </para> - - <para> - [1] <ulink url="http://www.chronox.de/libkcapi.html">http://www.chronox.de/libkcapi.html</ulink> - </para> - - </sect1> - - <sect1><title>User Space API General Remarks</title> - <para> - The kernel crypto API is accessible from user space. Currently, - the following ciphers are accessible: - </para> - - <itemizedlist> - <listitem> - <para>Message digest including keyed message digest (HMAC, CMAC)</para> - </listitem> - - <listitem> - <para>Symmetric ciphers</para> - </listitem> - - <listitem> - <para>AEAD ciphers</para> - </listitem> - - <listitem> - <para>Random Number Generators</para> - </listitem> - </itemizedlist> - - <para> - The interface is provided via socket type using the type AF_ALG. - In addition, the setsockopt option type is SOL_ALG. In case the - user space header files do not export these flags yet, use the - following macros: - </para> - - <programlisting> -#ifndef AF_ALG -#define AF_ALG 38 -#endif -#ifndef SOL_ALG -#define SOL_ALG 279 -#endif - </programlisting> - - <para> - A cipher is accessed with the same name as done for the in-kernel - API calls. This includes the generic vs. unique naming schema for - ciphers as well as the enforcement of priorities for generic names. - </para> - - <para> - To interact with the kernel crypto API, a socket must be - created by the user space application. User space invokes the cipher - operation with the send()/write() system call family. The result of the - cipher operation is obtained with the read()/recv() system call family. - </para> - - <para> - The following API calls assume that the socket descriptor - is already opened by the user space application and discusses only - the kernel crypto API specific invocations. - </para> - - <para> - To initialize the socket interface, the following sequence has to - be performed by the consumer: - </para> - - <orderedlist> - <listitem> - <para> - Create a socket of type AF_ALG with the struct sockaddr_alg - parameter specified below for the different cipher types. - </para> - </listitem> - - <listitem> - <para> - Invoke bind with the socket descriptor - </para> - </listitem> - - <listitem> - <para> - Invoke accept with the socket descriptor. The accept system call - returns a new file descriptor that is to be used to interact with - the particular cipher instance. When invoking send/write or recv/read - system calls to send data to the kernel or obtain data from the - kernel, the file descriptor returned by accept must be used. - </para> - </listitem> - </orderedlist> - </sect1> - - <sect1><title>In-place Cipher operation</title> - <para> - Just like the in-kernel operation of the kernel crypto API, the user - space interface allows the cipher operation in-place. That means that - the input buffer used for the send/write system call and the output - buffer used by the read/recv system call may be one and the same. - This is of particular interest for symmetric cipher operations where a - copying of the output data to its final destination can be avoided. - </para> - - <para> - If a consumer on the other hand wants to maintain the plaintext and - the ciphertext in different memory locations, all a consumer needs - to do is to provide different memory pointers for the encryption and - decryption operation. - </para> - </sect1> - - <sect1><title>Message Digest API</title> - <para> - The message digest type to be used for the cipher operation is - selected when invoking the bind syscall. bind requires the caller - to provide a filled struct sockaddr data structure. This data - structure must be filled as follows: - </para> - - <programlisting> -struct sockaddr_alg sa = { - .salg_family = AF_ALG, - .salg_type = "hash", /* this selects the hash logic in the kernel */ - .salg_name = "sha1" /* this is the cipher name */ -}; - </programlisting> - - <para> - The salg_type value "hash" applies to message digests and keyed - message digests. Though, a keyed message digest is referenced by - the appropriate salg_name. Please see below for the setsockopt - interface that explains how the key can be set for a keyed message - digest. - </para> - - <para> - Using the send() system call, the application provides the data that - should be processed with the message digest. The send system call - allows the following flags to be specified: - </para> - - <itemizedlist> - <listitem> - <para> - MSG_MORE: If this flag is set, the send system call acts like a - message digest update function where the final hash is not - yet calculated. If the flag is not set, the send system call - calculates the final message digest immediately. - </para> - </listitem> - </itemizedlist> - - <para> - With the recv() system call, the application can read the message - digest from the kernel crypto API. If the buffer is too small for the - message digest, the flag MSG_TRUNC is set by the kernel. - </para> - - <para> - In order to set a message digest key, the calling application must use - the setsockopt() option of ALG_SET_KEY. If the key is not set the HMAC - operation is performed without the initial HMAC state change caused by - the key. - </para> - </sect1> - - <sect1><title>Symmetric Cipher API</title> - <para> - The operation is very similar to the message digest discussion. - During initialization, the struct sockaddr data structure must be - filled as follows: - </para> - - <programlisting> -struct sockaddr_alg sa = { - .salg_family = AF_ALG, - .salg_type = "skcipher", /* this selects the symmetric cipher */ - .salg_name = "cbc(aes)" /* this is the cipher name */ -}; - </programlisting> - - <para> - Before data can be sent to the kernel using the write/send system - call family, the consumer must set the key. The key setting is - described with the setsockopt invocation below. - </para> - - <para> - Using the sendmsg() system call, the application provides the data that should be processed for encryption or decryption. In addition, the IV is - specified with the data structure provided by the sendmsg() system call. - </para> - - <para> - The sendmsg system call parameter of struct msghdr is embedded into the - struct cmsghdr data structure. See recv(2) and cmsg(3) for more - information on how the cmsghdr data structure is used together with the - send/recv system call family. That cmsghdr data structure holds the - following information specified with a separate header instances: - </para> - - <itemizedlist> - <listitem> - <para> - specification of the cipher operation type with one of these flags: - </para> - <itemizedlist> - <listitem> - <para>ALG_OP_ENCRYPT - encryption of data</para> - </listitem> - <listitem> - <para>ALG_OP_DECRYPT - decryption of data</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para> - specification of the IV information marked with the flag ALG_SET_IV - </para> - </listitem> - </itemizedlist> - - <para> - The send system call family allows the following flag to be specified: - </para> - - <itemizedlist> - <listitem> - <para> - MSG_MORE: If this flag is set, the send system call acts like a - cipher update function where more input data is expected - with a subsequent invocation of the send system call. - </para> - </listitem> - </itemizedlist> - - <para> - Note: The kernel reports -EINVAL for any unexpected data. The caller - must make sure that all data matches the constraints given in - /proc/crypto for the selected cipher. - </para> - - <para> - With the recv() system call, the application can read the result of - the cipher operation from the kernel crypto API. The output buffer - must be at least as large as to hold all blocks of the encrypted or - decrypted data. If the output data size is smaller, only as many - blocks are returned that fit into that output buffer size. - </para> - </sect1> - - <sect1><title>AEAD Cipher API</title> - <para> - The operation is very similar to the symmetric cipher discussion. - During initialization, the struct sockaddr data structure must be - filled as follows: - </para> - - <programlisting> -struct sockaddr_alg sa = { - .salg_family = AF_ALG, - .salg_type = "aead", /* this selects the symmetric cipher */ - .salg_name = "gcm(aes)" /* this is the cipher name */ -}; - </programlisting> - - <para> - Before data can be sent to the kernel using the write/send system - call family, the consumer must set the key. The key setting is - described with the setsockopt invocation below. - </para> - - <para> - In addition, before data can be sent to the kernel using the - write/send system call family, the consumer must set the authentication - tag size. To set the authentication tag size, the caller must use the - setsockopt invocation described below. - </para> - - <para> - Using the sendmsg() system call, the application provides the data that should be processed for encryption or decryption. In addition, the IV is - specified with the data structure provided by the sendmsg() system call. - </para> - - <para> - The sendmsg system call parameter of struct msghdr is embedded into the - struct cmsghdr data structure. See recv(2) and cmsg(3) for more - information on how the cmsghdr data structure is used together with the - send/recv system call family. That cmsghdr data structure holds the - following information specified with a separate header instances: - </para> - - <itemizedlist> - <listitem> - <para> - specification of the cipher operation type with one of these flags: - </para> - <itemizedlist> - <listitem> - <para>ALG_OP_ENCRYPT - encryption of data</para> - </listitem> - <listitem> - <para>ALG_OP_DECRYPT - decryption of data</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para> - specification of the IV information marked with the flag ALG_SET_IV - </para> - </listitem> - - <listitem> - <para> - specification of the associated authentication data (AAD) with the - flag ALG_SET_AEAD_ASSOCLEN. The AAD is sent to the kernel together - with the plaintext / ciphertext. See below for the memory structure. - </para> - </listitem> - </itemizedlist> - - <para> - The send system call family allows the following flag to be specified: - </para> - - <itemizedlist> - <listitem> - <para> - MSG_MORE: If this flag is set, the send system call acts like a - cipher update function where more input data is expected - with a subsequent invocation of the send system call. - </para> - </listitem> - </itemizedlist> - - <para> - Note: The kernel reports -EINVAL for any unexpected data. The caller - must make sure that all data matches the constraints given in - /proc/crypto for the selected cipher. - </para> - - <para> - With the recv() system call, the application can read the result of - the cipher operation from the kernel crypto API. The output buffer - must be at least as large as defined with the memory structure below. - If the output data size is smaller, the cipher operation is not performed. - </para> - - <para> - The authenticated decryption operation may indicate an integrity error. - Such breach in integrity is marked with the -EBADMSG error code. - </para> - - <sect2><title>AEAD Memory Structure</title> - <para> - The AEAD cipher operates with the following information that - is communicated between user and kernel space as one data stream: - </para> - - <itemizedlist> - <listitem> - <para>plaintext or ciphertext</para> - </listitem> - - <listitem> - <para>associated authentication data (AAD)</para> - </listitem> - - <listitem> - <para>authentication tag</para> - </listitem> - </itemizedlist> - - <para> - The sizes of the AAD and the authentication tag are provided with - the sendmsg and setsockopt calls (see there). As the kernel knows - the size of the entire data stream, the kernel is now able to - calculate the right offsets of the data components in the data - stream. - </para> - - <para> - The user space caller must arrange the aforementioned information - in the following order: - </para> - - <itemizedlist> - <listitem> - <para> - AEAD encryption input: AAD || plaintext - </para> - </listitem> - - <listitem> - <para> - AEAD decryption input: AAD || ciphertext || authentication tag - </para> - </listitem> - </itemizedlist> - - <para> - The output buffer the user space caller provides must be at least as - large to hold the following data: - </para> - - <itemizedlist> - <listitem> - <para> - AEAD encryption output: ciphertext || authentication tag - </para> - </listitem> - - <listitem> - <para> - AEAD decryption output: plaintext - </para> - </listitem> - </itemizedlist> - </sect2> - </sect1> - - <sect1><title>Random Number Generator API</title> - <para> - Again, the operation is very similar to the other APIs. - During initialization, the struct sockaddr data structure must be - filled as follows: - </para> - - <programlisting> -struct sockaddr_alg sa = { - .salg_family = AF_ALG, - .salg_type = "rng", /* this selects the symmetric cipher */ - .salg_name = "drbg_nopr_sha256" /* this is the cipher name */ -}; - </programlisting> - - <para> - Depending on the RNG type, the RNG must be seeded. The seed is provided - using the setsockopt interface to set the key. For example, the - ansi_cprng requires a seed. The DRBGs do not require a seed, but - may be seeded. - </para> - - <para> - Using the read()/recvmsg() system calls, random numbers can be obtained. - The kernel generates at most 128 bytes in one call. If user space - requires more data, multiple calls to read()/recvmsg() must be made. - </para> - - <para> - WARNING: The user space caller may invoke the initially mentioned - accept system call multiple times. In this case, the returned file - descriptors have the same state. - </para> - - </sect1> - - <sect1><title>Zero-Copy Interface</title> - <para> - In addition to the send/write/read/recv system call family, the AF_ALG - interface can be accessed with the zero-copy interface of splice/vmsplice. - As the name indicates, the kernel tries to avoid a copy operation into - kernel space. - </para> - - <para> - The zero-copy operation requires data to be aligned at the page boundary. - Non-aligned data can be used as well, but may require more operations of - the kernel which would defeat the speed gains obtained from the zero-copy - interface. - </para> - - <para> - The system-interent limit for the size of one zero-copy operation is - 16 pages. If more data is to be sent to AF_ALG, user space must slice - the input into segments with a maximum size of 16 pages. - </para> - - <para> - Zero-copy can be used with the following code example (a complete working - example is provided with libkcapi): - </para> - - <programlisting> -int pipes[2]; - -pipe(pipes); -/* input data in iov */ -vmsplice(pipes[1], iov, iovlen, SPLICE_F_GIFT); -/* opfd is the file descriptor returned from accept() system call */ -splice(pipes[0], NULL, opfd, NULL, ret, 0); -read(opfd, out, outlen); - </programlisting> - - </sect1> - - <sect1><title>Setsockopt Interface</title> - <para> - In addition to the read/recv and send/write system call handling - to send and retrieve data subject to the cipher operation, a consumer - also needs to set the additional information for the cipher operation. - This additional information is set using the setsockopt system call - that must be invoked with the file descriptor of the open cipher - (i.e. the file descriptor returned by the accept system call). - </para> - - <para> - Each setsockopt invocation must use the level SOL_ALG. - </para> - - <para> - The setsockopt interface allows setting the following data using - the mentioned optname: - </para> - - <itemizedlist> - <listitem> - <para> - ALG_SET_KEY -- Setting the key. Key setting is applicable to: - </para> - <itemizedlist> - <listitem> - <para>the skcipher cipher type (symmetric ciphers)</para> - </listitem> - <listitem> - <para>the hash cipher type (keyed message digests)</para> - </listitem> - <listitem> - <para>the AEAD cipher type</para> - </listitem> - <listitem> - <para>the RNG cipher type to provide the seed</para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para> - ALG_SET_AEAD_AUTHSIZE -- Setting the authentication tag size - for AEAD ciphers. For a encryption operation, the authentication - tag of the given size will be generated. For a decryption operation, - the provided ciphertext is assumed to contain an authentication tag - of the given size (see section about AEAD memory layout below). - </para> - </listitem> - </itemizedlist> - - </sect1> - - <sect1><title>User space API example</title> - <para> - Please see [1] for libkcapi which provides an easy-to-use wrapper - around the aforementioned Netlink kernel interface. [1] also contains - a test application that invokes all libkcapi API calls. - </para> - - <para> - [1] <ulink url="http://www.chronox.de/libkcapi.html">http://www.chronox.de/libkcapi.html</ulink> - </para> - - </sect1> - - </chapter> - - <chapter id="API"><title>Programming Interface</title> - <para> - Please note that the kernel crypto API contains the AEAD givcrypt - API (crypto_aead_giv* and aead_givcrypt_* function calls in - include/crypto/aead.h). This API is obsolete and will be removed - in the future. To obtain the functionality of an AEAD cipher with - internal IV generation, use the IV generator as a regular cipher. - For example, rfc4106(gcm(aes)) is the AEAD cipher with external - IV generation and seqniv(rfc4106(gcm(aes))) implies that the kernel - crypto API generates the IV. Different IV generators are available. - </para> - <sect1><title>Block Cipher Context Data Structures</title> -!Pinclude/linux/crypto.h Block Cipher Context Data Structures -!Finclude/crypto/aead.h aead_request - </sect1> - <sect1><title>Block Cipher Algorithm Definitions</title> -!Pinclude/linux/crypto.h Block Cipher Algorithm Definitions -!Finclude/linux/crypto.h crypto_alg -!Finclude/linux/crypto.h ablkcipher_alg -!Finclude/crypto/aead.h aead_alg -!Finclude/linux/crypto.h blkcipher_alg -!Finclude/linux/crypto.h cipher_alg -!Finclude/crypto/rng.h rng_alg - </sect1> - <sect1><title>Asynchronous Block Cipher API</title> -!Pinclude/linux/crypto.h Asynchronous Block Cipher API -!Finclude/linux/crypto.h crypto_alloc_ablkcipher -!Finclude/linux/crypto.h crypto_free_ablkcipher -!Finclude/linux/crypto.h crypto_has_ablkcipher -!Finclude/linux/crypto.h crypto_ablkcipher_ivsize -!Finclude/linux/crypto.h crypto_ablkcipher_blocksize -!Finclude/linux/crypto.h crypto_ablkcipher_setkey -!Finclude/linux/crypto.h crypto_ablkcipher_reqtfm -!Finclude/linux/crypto.h crypto_ablkcipher_encrypt -!Finclude/linux/crypto.h crypto_ablkcipher_decrypt - </sect1> - <sect1><title>Asynchronous Cipher Request Handle</title> -!Pinclude/linux/crypto.h Asynchronous Cipher Request Handle -!Finclude/linux/crypto.h crypto_ablkcipher_reqsize -!Finclude/linux/crypto.h ablkcipher_request_set_tfm -!Finclude/linux/crypto.h ablkcipher_request_alloc -!Finclude/linux/crypto.h ablkcipher_request_free -!Finclude/linux/crypto.h ablkcipher_request_set_callback -!Finclude/linux/crypto.h ablkcipher_request_set_crypt - </sect1> - <sect1><title>Authenticated Encryption With Associated Data (AEAD) Cipher API</title> -!Pinclude/crypto/aead.h Authenticated Encryption With Associated Data (AEAD) Cipher API -!Finclude/crypto/aead.h crypto_alloc_aead -!Finclude/crypto/aead.h crypto_free_aead -!Finclude/crypto/aead.h crypto_aead_ivsize -!Finclude/crypto/aead.h crypto_aead_authsize -!Finclude/crypto/aead.h crypto_aead_blocksize -!Finclude/crypto/aead.h crypto_aead_setkey -!Finclude/crypto/aead.h crypto_aead_setauthsize -!Finclude/crypto/aead.h crypto_aead_encrypt -!Finclude/crypto/aead.h crypto_aead_decrypt - </sect1> - <sect1><title>Asynchronous AEAD Request Handle</title> -!Pinclude/crypto/aead.h Asynchronous AEAD Request Handle -!Finclude/crypto/aead.h crypto_aead_reqsize -!Finclude/crypto/aead.h aead_request_set_tfm -!Finclude/crypto/aead.h aead_request_alloc -!Finclude/crypto/aead.h aead_request_free -!Finclude/crypto/aead.h aead_request_set_callback -!Finclude/crypto/aead.h aead_request_set_crypt -!Finclude/crypto/aead.h aead_request_set_assoc -!Finclude/crypto/aead.h aead_request_set_ad - </sect1> - <sect1><title>Synchronous Block Cipher API</title> -!Pinclude/linux/crypto.h Synchronous Block Cipher API -!Finclude/linux/crypto.h crypto_alloc_blkcipher -!Finclude/linux/crypto.h crypto_free_blkcipher -!Finclude/linux/crypto.h crypto_has_blkcipher -!Finclude/linux/crypto.h crypto_blkcipher_name -!Finclude/linux/crypto.h crypto_blkcipher_ivsize -!Finclude/linux/crypto.h crypto_blkcipher_blocksize -!Finclude/linux/crypto.h crypto_blkcipher_setkey -!Finclude/linux/crypto.h crypto_blkcipher_encrypt -!Finclude/linux/crypto.h crypto_blkcipher_encrypt_iv -!Finclude/linux/crypto.h crypto_blkcipher_decrypt -!Finclude/linux/crypto.h crypto_blkcipher_decrypt_iv -!Finclude/linux/crypto.h crypto_blkcipher_set_iv -!Finclude/linux/crypto.h crypto_blkcipher_get_iv - </sect1> - <sect1><title>Single Block Cipher API</title> -!Pinclude/linux/crypto.h Single Block Cipher API -!Finclude/linux/crypto.h crypto_alloc_cipher -!Finclude/linux/crypto.h crypto_free_cipher -!Finclude/linux/crypto.h crypto_has_cipher -!Finclude/linux/crypto.h crypto_cipher_blocksize -!Finclude/linux/crypto.h crypto_cipher_setkey -!Finclude/linux/crypto.h crypto_cipher_encrypt_one -!Finclude/linux/crypto.h crypto_cipher_decrypt_one - </sect1> - <sect1><title>Synchronous Message Digest API</title> -!Pinclude/linux/crypto.h Synchronous Message Digest API -!Finclude/linux/crypto.h crypto_alloc_hash -!Finclude/linux/crypto.h crypto_free_hash -!Finclude/linux/crypto.h crypto_has_hash -!Finclude/linux/crypto.h crypto_hash_blocksize -!Finclude/linux/crypto.h crypto_hash_digestsize -!Finclude/linux/crypto.h crypto_hash_init -!Finclude/linux/crypto.h crypto_hash_update -!Finclude/linux/crypto.h crypto_hash_final -!Finclude/linux/crypto.h crypto_hash_digest -!Finclude/linux/crypto.h crypto_hash_setkey - </sect1> - <sect1><title>Message Digest Algorithm Definitions</title> -!Pinclude/crypto/hash.h Message Digest Algorithm Definitions -!Finclude/crypto/hash.h hash_alg_common -!Finclude/crypto/hash.h ahash_alg -!Finclude/crypto/hash.h shash_alg - </sect1> - <sect1><title>Asynchronous Message Digest API</title> -!Pinclude/crypto/hash.h Asynchronous Message Digest API -!Finclude/crypto/hash.h crypto_alloc_ahash -!Finclude/crypto/hash.h crypto_free_ahash -!Finclude/crypto/hash.h crypto_ahash_init -!Finclude/crypto/hash.h crypto_ahash_digestsize -!Finclude/crypto/hash.h crypto_ahash_reqtfm -!Finclude/crypto/hash.h crypto_ahash_reqsize -!Finclude/crypto/hash.h crypto_ahash_setkey -!Finclude/crypto/hash.h crypto_ahash_finup -!Finclude/crypto/hash.h crypto_ahash_final -!Finclude/crypto/hash.h crypto_ahash_digest -!Finclude/crypto/hash.h crypto_ahash_export -!Finclude/crypto/hash.h crypto_ahash_import - </sect1> - <sect1><title>Asynchronous Hash Request Handle</title> -!Pinclude/crypto/hash.h Asynchronous Hash Request Handle -!Finclude/crypto/hash.h ahash_request_set_tfm -!Finclude/crypto/hash.h ahash_request_alloc -!Finclude/crypto/hash.h ahash_request_free -!Finclude/crypto/hash.h ahash_request_set_callback -!Finclude/crypto/hash.h ahash_request_set_crypt - </sect1> - <sect1><title>Synchronous Message Digest API</title> -!Pinclude/crypto/hash.h Synchronous Message Digest API -!Finclude/crypto/hash.h crypto_alloc_shash -!Finclude/crypto/hash.h crypto_free_shash -!Finclude/crypto/hash.h crypto_shash_blocksize -!Finclude/crypto/hash.h crypto_shash_digestsize -!Finclude/crypto/hash.h crypto_shash_descsize -!Finclude/crypto/hash.h crypto_shash_setkey -!Finclude/crypto/hash.h crypto_shash_digest -!Finclude/crypto/hash.h crypto_shash_export -!Finclude/crypto/hash.h crypto_shash_import -!Finclude/crypto/hash.h crypto_shash_init -!Finclude/crypto/hash.h crypto_shash_update -!Finclude/crypto/hash.h crypto_shash_final -!Finclude/crypto/hash.h crypto_shash_finup - </sect1> - <sect1><title>Crypto API Random Number API</title> -!Pinclude/crypto/rng.h Random number generator API -!Finclude/crypto/rng.h crypto_alloc_rng -!Finclude/crypto/rng.h crypto_rng_alg -!Finclude/crypto/rng.h crypto_free_rng -!Finclude/crypto/rng.h crypto_rng_get_bytes -!Finclude/crypto/rng.h crypto_rng_reset -!Finclude/crypto/rng.h crypto_rng_seedsize -!Cinclude/crypto/rng.h - </sect1> - </chapter> - - <chapter id="Code"><title>Code Examples</title> - <sect1><title>Code Example For Asynchronous Block Cipher Operation</title> - <programlisting> - -struct tcrypt_result { - struct completion completion; - int err; -}; - -/* tie all data structures together */ -struct ablkcipher_def { - struct scatterlist sg; - struct crypto_ablkcipher *tfm; - struct ablkcipher_request *req; - struct tcrypt_result result; -}; - -/* Callback function */ -static void test_ablkcipher_cb(struct crypto_async_request *req, int error) -{ - struct tcrypt_result *result = req->data; - - if (error == -EINPROGRESS) - return; - result->err = error; - complete(&result->completion); - pr_info("Encryption finished successfully\n"); -} - -/* Perform cipher operation */ -static unsigned int test_ablkcipher_encdec(struct ablkcipher_def *ablk, - int enc) -{ - int rc = 0; - - if (enc) - rc = crypto_ablkcipher_encrypt(ablk->req); - else - rc = crypto_ablkcipher_decrypt(ablk->req); - - switch (rc) { - case 0: - break; - case -EINPROGRESS: - case -EBUSY: - rc = wait_for_completion_interruptible( - &ablk->result.completion); - if (!rc && !ablk->result.err) { - reinit_completion(&ablk->result.completion); - break; - } - default: - pr_info("ablkcipher encrypt returned with %d result %d\n", - rc, ablk->result.err); - break; - } - init_completion(&ablk->result.completion); - - return rc; -} - -/* Initialize and trigger cipher operation */ -static int test_ablkcipher(void) -{ - struct ablkcipher_def ablk; - struct crypto_ablkcipher *ablkcipher = NULL; - struct ablkcipher_request *req = NULL; - char *scratchpad = NULL; - char *ivdata = NULL; - unsigned char key[32]; - int ret = -EFAULT; - - ablkcipher = crypto_alloc_ablkcipher("cbc-aes-aesni", 0, 0); - if (IS_ERR(ablkcipher)) { - pr_info("could not allocate ablkcipher handle\n"); - return PTR_ERR(ablkcipher); - } - - req = ablkcipher_request_alloc(ablkcipher, GFP_KERNEL); - if (IS_ERR(req)) { - pr_info("could not allocate request queue\n"); - ret = PTR_ERR(req); - goto out; - } - - ablkcipher_request_set_callback(req, CRYPTO_TFM_REQ_MAY_BACKLOG, - test_ablkcipher_cb, - &ablk.result); - - /* AES 256 with random key */ - get_random_bytes(&key, 32); - if (crypto_ablkcipher_setkey(ablkcipher, key, 32)) { - pr_info("key could not be set\n"); - ret = -EAGAIN; - goto out; - } - - /* IV will be random */ - ivdata = kmalloc(16, GFP_KERNEL); - if (!ivdata) { - pr_info("could not allocate ivdata\n"); - goto out; - } - get_random_bytes(ivdata, 16); - - /* Input data will be random */ - scratchpad = kmalloc(16, GFP_KERNEL); - if (!scratchpad) { - pr_info("could not allocate scratchpad\n"); - goto out; - } - get_random_bytes(scratchpad, 16); - - ablk.tfm = ablkcipher; - ablk.req = req; - - /* We encrypt one block */ - sg_init_one(&ablk.sg, scratchpad, 16); - ablkcipher_request_set_crypt(req, &ablk.sg, &ablk.sg, 16, ivdata); - init_completion(&ablk.result.completion); - - /* encrypt data */ - ret = test_ablkcipher_encdec(&ablk, 1); - if (ret) - goto out; - - pr_info("Encryption triggered successfully\n"); - -out: - if (ablkcipher) - crypto_free_ablkcipher(ablkcipher); - if (req) - ablkcipher_request_free(req); - if (ivdata) - kfree(ivdata); - if (scratchpad) - kfree(scratchpad); - return ret; -} - </programlisting> - </sect1> - - <sect1><title>Code Example For Synchronous Block Cipher Operation</title> - <programlisting> - -static int test_blkcipher(void) -{ - struct crypto_blkcipher *blkcipher = NULL; - char *cipher = "cbc(aes)"; - // AES 128 - charkey = -"\x12\x34\x56\x78\x90\xab\xcd\xef\x12\x34\x56\x78\x90\xab\xcd\xef"; - chariv = -"\x12\x34\x56\x78\x90\xab\xcd\xef\x12\x34\x56\x78\x90\xab\xcd\xef"; - unsigned int ivsize = 0; - char *scratchpad = NULL; // holds plaintext and ciphertext - struct scatterlist sg; - struct blkcipher_desc desc; - int ret = -EFAULT; - - blkcipher = crypto_alloc_blkcipher(cipher, 0, 0); - if (IS_ERR(blkcipher)) { - printk("could not allocate blkcipher handle for %s\n", cipher); - return -PTR_ERR(blkcipher); - } - - if (crypto_blkcipher_setkey(blkcipher, key, strlen(key))) { - printk("key could not be set\n"); - ret = -EAGAIN; - goto out; - } - - ivsize = crypto_blkcipher_ivsize(blkcipher); - if (ivsize) { - if (ivsize != strlen(iv)) - printk("IV length differs from expected length\n"); - crypto_blkcipher_set_iv(blkcipher, iv, ivsize); - } - - scratchpad = kmalloc(crypto_blkcipher_blocksize(blkcipher), GFP_KERNEL); - if (!scratchpad) { - printk("could not allocate scratchpad for %s\n", cipher); - goto out; - } - /* get some random data that we want to encrypt */ - get_random_bytes(scratchpad, crypto_blkcipher_blocksize(blkcipher)); - - desc.flags = 0; - desc.tfm = blkcipher; - sg_init_one(&sg, scratchpad, crypto_blkcipher_blocksize(blkcipher)); - - /* encrypt data in place */ - crypto_blkcipher_encrypt(&desc, &sg, &sg, - crypto_blkcipher_blocksize(blkcipher)); - - /* decrypt data in place - * crypto_blkcipher_decrypt(&desc, &sg, &sg, - */ crypto_blkcipher_blocksize(blkcipher)); - - - printk("Cipher operation completed\n"); - return 0; - -out: - if (blkcipher) - crypto_free_blkcipher(blkcipher); - if (scratchpad) - kzfree(scratchpad); - return ret; -} - </programlisting> - </sect1> - - <sect1><title>Code Example For Use of Operational State Memory With SHASH</title> - <programlisting> - -struct sdesc { - struct shash_desc shash; - char ctx[]; -}; - -static struct sdescinit_sdesc(struct crypto_shash *alg) -{ - struct sdescsdesc; - int size; - - size = sizeof(struct shash_desc) + crypto_shash_descsize(alg); - sdesc = kmalloc(size, GFP_KERNEL); - if (!sdesc) - return ERR_PTR(-ENOMEM); - sdesc->shash.tfm = alg; - sdesc->shash.flags = 0x0; - return sdesc; -} - -static int calc_hash(struct crypto_shashalg, - const unsigned chardata, unsigned int datalen, - unsigned chardigest) { - struct sdescsdesc; - int ret; - - sdesc = init_sdesc(alg); - if (IS_ERR(sdesc)) { - pr_info("trusted_key: can't alloc %s\n", hash_alg); - return PTR_ERR(sdesc); - } - - ret = crypto_shash_digest(&sdesc->shash, data, datalen, digest); - kfree(sdesc); - return ret; -} - </programlisting> - </sect1> - - <sect1><title>Code Example For Random Number Generator Usage</title> - <programlisting> - -static int get_random_numbers(u8 *buf, unsigned int len) -{ - struct crypto_rngrng = NULL; - chardrbg = "drbg_nopr_sha256"; /* Hash DRBG with SHA-256, no PR */ - int ret; - - if (!buf || !len) { - pr_debug("No output buffer provided\n"); - return -EINVAL; - } - - rng = crypto_alloc_rng(drbg, 0, 0); - if (IS_ERR(rng)) { - pr_debug("could not allocate RNG handle for %s\n", drbg); - return -PTR_ERR(rng); - } - - ret = crypto_rng_get_bytes(rng, buf, len); - if (ret < 0) - pr_debug("generation of random numbers failed\n"); - else if (ret == 0) - pr_debug("RNG returned no data"); - else - pr_debug("RNG returned %d bytes of data\n", ret); - -out: - crypto_free_rng(rng); - return ret; -} - </programlisting> - </sect1> - </chapter> - </book> diff --git a/Documentation/DocBook/debugobjects.tmpl b/Documentation/DocBook/debugobjects.tmpl deleted file mode 100644 index 24979f691e3e..000000000000 --- a/Documentation/DocBook/debugobjects.tmpl +++ /dev/null @@ -1,441 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="debug-objects-guide"> - <bookinfo> - <title>Debug objects life time</title> - - <authorgroup> - <author> - <firstname>Thomas</firstname> - <surname>Gleixner</surname> - <affiliation> - <address> - <email>tglx@linutronix.de</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2008</year> - <holder>Thomas Gleixner</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License version 2 as published by the Free Software Foundation. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="intro"> - <title>Introduction</title> - <para> - debugobjects is a generic infrastructure to track the life time - of kernel objects and validate the operations on those. - </para> - <para> - debugobjects is useful to check for the following error patterns: - <itemizedlist> - <listitem><para>Activation of uninitialized objects</para></listitem> - <listitem><para>Initialization of active objects</para></listitem> - <listitem><para>Usage of freed/destroyed objects</para></listitem> - </itemizedlist> - </para> - <para> - debugobjects is not changing the data structure of the real - object so it can be compiled in with a minimal runtime impact - and enabled on demand with a kernel command line option. - </para> - </chapter> - - <chapter id="howto"> - <title>Howto use debugobjects</title> - <para> - A kernel subsystem needs to provide a data structure which - describes the object type and add calls into the debug code at - appropriate places. The data structure to describe the object - type needs at minimum the name of the object type. Optional - functions can and should be provided to fixup detected problems - so the kernel can continue to work and the debug information can - be retrieved from a live system instead of hard core debugging - with serial consoles and stack trace transcripts from the - monitor. - </para> - <para> - The debug calls provided by debugobjects are: - <itemizedlist> - <listitem><para>debug_object_init</para></listitem> - <listitem><para>debug_object_init_on_stack</para></listitem> - <listitem><para>debug_object_activate</para></listitem> - <listitem><para>debug_object_deactivate</para></listitem> - <listitem><para>debug_object_destroy</para></listitem> - <listitem><para>debug_object_free</para></listitem> - <listitem><para>debug_object_assert_init</para></listitem> - </itemizedlist> - Each of these functions takes the address of the real object and - a pointer to the object type specific debug description - structure. - </para> - <para> - Each detected error is reported in the statistics and a limited - number of errors are printk'ed including a full stack trace. - </para> - <para> - The statistics are available via /sys/kernel/debug/debug_objects/stats. - They provide information about the number of warnings and the - number of successful fixups along with information about the - usage of the internal tracking objects and the state of the - internal tracking objects pool. - </para> - </chapter> - <chapter id="debugfunctions"> - <title>Debug functions</title> - <sect1 id="prototypes"> - <title>Debug object function reference</title> -!Elib/debugobjects.c - </sect1> - <sect1 id="debug_object_init"> - <title>debug_object_init</title> - <para> - This function is called whenever the initialization function - of a real object is called. - </para> - <para> - When the real object is already tracked by debugobjects it is - checked, whether the object can be initialized. Initializing - is not allowed for active and destroyed objects. When - debugobjects detects an error, then it calls the fixup_init - function of the object type description structure if provided - by the caller. The fixup function can correct the problem - before the real initialization of the object happens. E.g. it - can deactivate an active object in order to prevent damage to - the subsystem. - </para> - <para> - When the real object is not yet tracked by debugobjects, - debugobjects allocates a tracker object for the real object - and sets the tracker object state to ODEBUG_STATE_INIT. It - verifies that the object is not on the callers stack. If it is - on the callers stack then a limited number of warnings - including a full stack trace is printk'ed. The calling code - must use debug_object_init_on_stack() and remove the object - before leaving the function which allocated it. See next - section. - </para> - </sect1> - - <sect1 id="debug_object_init_on_stack"> - <title>debug_object_init_on_stack</title> - <para> - This function is called whenever the initialization function - of a real object which resides on the stack is called. - </para> - <para> - When the real object is already tracked by debugobjects it is - checked, whether the object can be initialized. Initializing - is not allowed for active and destroyed objects. When - debugobjects detects an error, then it calls the fixup_init - function of the object type description structure if provided - by the caller. The fixup function can correct the problem - before the real initialization of the object happens. E.g. it - can deactivate an active object in order to prevent damage to - the subsystem. - </para> - <para> - When the real object is not yet tracked by debugobjects - debugobjects allocates a tracker object for the real object - and sets the tracker object state to ODEBUG_STATE_INIT. It - verifies that the object is on the callers stack. - </para> - <para> - An object which is on the stack must be removed from the - tracker by calling debug_object_free() before the function - which allocates the object returns. Otherwise we keep track of - stale objects. - </para> - </sect1> - - <sect1 id="debug_object_activate"> - <title>debug_object_activate</title> - <para> - This function is called whenever the activation function of a - real object is called. - </para> - <para> - When the real object is already tracked by debugobjects it is - checked, whether the object can be activated. Activating is - not allowed for active and destroyed objects. When - debugobjects detects an error, then it calls the - fixup_activate function of the object type description - structure if provided by the caller. The fixup function can - correct the problem before the real activation of the object - happens. E.g. it can deactivate an active object in order to - prevent damage to the subsystem. - </para> - <para> - When the real object is not yet tracked by debugobjects then - the fixup_activate function is called if available. This is - necessary to allow the legitimate activation of statically - allocated and initialized objects. The fixup function checks - whether the object is valid and calls the debug_objects_init() - function to initialize the tracking of this object. - </para> - <para> - When the activation is legitimate, then the state of the - associated tracker object is set to ODEBUG_STATE_ACTIVE. - </para> - </sect1> - - <sect1 id="debug_object_deactivate"> - <title>debug_object_deactivate</title> - <para> - This function is called whenever the deactivation function of - a real object is called. - </para> - <para> - When the real object is tracked by debugobjects it is checked, - whether the object can be deactivated. Deactivating is not - allowed for untracked or destroyed objects. - </para> - <para> - When the deactivation is legitimate, then the state of the - associated tracker object is set to ODEBUG_STATE_INACTIVE. - </para> - </sect1> - - <sect1 id="debug_object_destroy"> - <title>debug_object_destroy</title> - <para> - This function is called to mark an object destroyed. This is - useful to prevent the usage of invalid objects, which are - still available in memory: either statically allocated objects - or objects which are freed later. - </para> - <para> - When the real object is tracked by debugobjects it is checked, - whether the object can be destroyed. Destruction is not - allowed for active and destroyed objects. When debugobjects - detects an error, then it calls the fixup_destroy function of - the object type description structure if provided by the - caller. The fixup function can correct the problem before the - real destruction of the object happens. E.g. it can deactivate - an active object in order to prevent damage to the subsystem. - </para> - <para> - When the destruction is legitimate, then the state of the - associated tracker object is set to ODEBUG_STATE_DESTROYED. - </para> - </sect1> - - <sect1 id="debug_object_free"> - <title>debug_object_free</title> - <para> - This function is called before an object is freed. - </para> - <para> - When the real object is tracked by debugobjects it is checked, - whether the object can be freed. Free is not allowed for - active objects. When debugobjects detects an error, then it - calls the fixup_free function of the object type description - structure if provided by the caller. The fixup function can - correct the problem before the real free of the object - happens. E.g. it can deactivate an active object in order to - prevent damage to the subsystem. - </para> - <para> - Note that debug_object_free removes the object from the - tracker. Later usage of the object is detected by the other - debug checks. - </para> - </sect1> - - <sect1 id="debug_object_assert_init"> - <title>debug_object_assert_init</title> - <para> - This function is called to assert that an object has been - initialized. - </para> - <para> - When the real object is not tracked by debugobjects, it calls - fixup_assert_init of the object type description structure - provided by the caller, with the hardcoded object state - ODEBUG_NOT_AVAILABLE. The fixup function can correct the problem - by calling debug_object_init and other specific initializing - functions. - </para> - <para> - When the real object is already tracked by debugobjects it is - ignored. - </para> - </sect1> - </chapter> - <chapter id="fixupfunctions"> - <title>Fixup functions</title> - <sect1 id="debug_obj_descr"> - <title>Debug object type description structure</title> -!Iinclude/linux/debugobjects.h - </sect1> - <sect1 id="fixup_init"> - <title>fixup_init</title> - <para> - This function is called from the debug code whenever a problem - in debug_object_init is detected. The function takes the - address of the object and the state which is currently - recorded in the tracker. - </para> - <para> - Called from debug_object_init when the object state is: - <itemizedlist> - <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem> - </itemizedlist> - </para> - <para> - The function returns 1 when the fixup was successful, - otherwise 0. The return value is used to update the - statistics. - </para> - <para> - Note, that the function needs to call the debug_object_init() - function again, after the damage has been repaired in order to - keep the state consistent. - </para> - </sect1> - - <sect1 id="fixup_activate"> - <title>fixup_activate</title> - <para> - This function is called from the debug code whenever a problem - in debug_object_activate is detected. - </para> - <para> - Called from debug_object_activate when the object state is: - <itemizedlist> - <listitem><para>ODEBUG_STATE_NOTAVAILABLE</para></listitem> - <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem> - </itemizedlist> - </para> - <para> - The function returns 1 when the fixup was successful, - otherwise 0. The return value is used to update the - statistics. - </para> - <para> - Note that the function needs to call the debug_object_activate() - function again after the damage has been repaired in order to - keep the state consistent. - </para> - <para> - The activation of statically initialized objects is a special - case. When debug_object_activate() has no tracked object for - this object address then fixup_activate() is called with - object state ODEBUG_STATE_NOTAVAILABLE. The fixup function - needs to check whether this is a legitimate case of a - statically initialized object or not. In case it is it calls - debug_object_init() and debug_object_activate() to make the - object known to the tracker and marked active. In this case - the function should return 0 because this is not a real fixup. - </para> - </sect1> - - <sect1 id="fixup_destroy"> - <title>fixup_destroy</title> - <para> - This function is called from the debug code whenever a problem - in debug_object_destroy is detected. - </para> - <para> - Called from debug_object_destroy when the object state is: - <itemizedlist> - <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem> - </itemizedlist> - </para> - <para> - The function returns 1 when the fixup was successful, - otherwise 0. The return value is used to update the - statistics. - </para> - </sect1> - <sect1 id="fixup_free"> - <title>fixup_free</title> - <para> - This function is called from the debug code whenever a problem - in debug_object_free is detected. Further it can be called - from the debug checks in kfree/vfree, when an active object is - detected from the debug_check_no_obj_freed() sanity checks. - </para> - <para> - Called from debug_object_free() or debug_check_no_obj_freed() - when the object state is: - <itemizedlist> - <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem> - </itemizedlist> - </para> - <para> - The function returns 1 when the fixup was successful, - otherwise 0. The return value is used to update the - statistics. - </para> - </sect1> - <sect1 id="fixup_assert_init"> - <title>fixup_assert_init</title> - <para> - This function is called from the debug code whenever a problem - in debug_object_assert_init is detected. - </para> - <para> - Called from debug_object_assert_init() with a hardcoded state - ODEBUG_STATE_NOTAVAILABLE when the object is not found in the - debug bucket. - </para> - <para> - The function returns 1 when the fixup was successful, - otherwise 0. The return value is used to update the - statistics. - </para> - <para> - Note, this function should make sure debug_object_init() is - called before returning. - </para> - <para> - The handling of statically initialized objects is a special - case. The fixup function should check if this is a legitimate - case of a statically initialized object or not. In this case only - debug_object_init() should be called to make the object known to - the tracker. Then the function should return 0 because this is not - a real fixup. - </para> - </sect1> - </chapter> - <chapter id="bugs"> - <title>Known Bugs And Assumptions</title> - <para> - None (knock on wood). - </para> - </chapter> -</book> diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl deleted file mode 100644 index cdd8b24db68d..000000000000 --- a/Documentation/DocBook/device-drivers.tmpl +++ /dev/null @@ -1,540 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="LinuxDriversAPI"> - <bookinfo> - <title>Linux Device Drivers</title> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="Basics"> - <title>Driver Basics</title> - <sect1><title>Driver Entry and Exit points</title> -!Iinclude/linux/init.h - </sect1> - - <sect1><title>Atomic and pointer manipulation</title> -!Iarch/x86/include/asm/atomic.h - </sect1> - - <sect1><title>Delaying, scheduling, and timer routines</title> -!Iinclude/linux/sched.h -!Ekernel/sched/core.c -!Ikernel/sched/cpupri.c -!Ikernel/sched/fair.c -!Iinclude/linux/completion.h -!Ekernel/time/timer.c - </sect1> - <sect1><title>Wait queues and Wake events</title> -!Iinclude/linux/wait.h -!Ekernel/sched/wait.c - </sect1> - <sect1><title>High-resolution timers</title> -!Iinclude/linux/ktime.h -!Iinclude/linux/hrtimer.h -!Ekernel/time/hrtimer.c - </sect1> - <sect1><title>Workqueues and Kevents</title> -!Iinclude/linux/workqueue.h -!Ekernel/workqueue.c - </sect1> - <sect1><title>Internal Functions</title> -!Ikernel/exit.c -!Ikernel/signal.c -!Iinclude/linux/kthread.h -!Ekernel/kthread.c - </sect1> - - <sect1><title>Kernel objects manipulation</title> -<!-- -X!Iinclude/linux/kobject.h ---> -!Elib/kobject.c - </sect1> - - <sect1><title>Kernel utility functions</title> -!Iinclude/linux/kernel.h -!Ekernel/printk/printk.c -!Ekernel/panic.c -!Ekernel/sys.c -!Ekernel/rcu/srcu.c -!Ekernel/rcu/tree.c -!Ekernel/rcu/tree_plugin.h -!Ekernel/rcu/update.c - </sect1> - - <sect1><title>Device Resource Management</title> -!Edrivers/base/devres.c - </sect1> - - </chapter> - - <chapter id="devdrivers"> - <title>Device drivers infrastructure</title> - <sect1><title>The Basic Device Driver-Model Structures </title> -!Iinclude/linux/device.h - </sect1> - <sect1><title>Device Drivers Base</title> -!Idrivers/base/init.c -!Edrivers/base/driver.c -!Edrivers/base/core.c -!Edrivers/base/syscore.c -!Edrivers/base/class.c -!Idrivers/base/node.c -!Edrivers/base/firmware_class.c -!Edrivers/base/transport_class.c -<!-- Cannot be included, because - attribute_container_add_class_device_adapter - and attribute_container_classdev_to_container - exceed allowed 44 characters maximum -X!Edrivers/base/attribute_container.c ---> -!Edrivers/base/dd.c -<!-- -X!Edrivers/base/interface.c ---> -!Iinclude/linux/platform_device.h -!Edrivers/base/platform.c -!Edrivers/base/bus.c - </sect1> - <sect1><title>Device Drivers DMA Management</title> -!Edrivers/dma-buf/dma-buf.c -!Edrivers/dma-buf/fence.c -!Edrivers/dma-buf/seqno-fence.c -!Iinclude/linux/fence.h -!Iinclude/linux/seqno-fence.h -!Edrivers/dma-buf/reservation.c -!Iinclude/linux/reservation.h -!Edrivers/base/dma-coherent.c -!Edrivers/base/dma-mapping.c - </sect1> - <sect1><title>Device Drivers Power Management</title> -!Edrivers/base/power/main.c - </sect1> - <sect1><title>Device Drivers ACPI Support</title> -<!-- Internal functions only -X!Edrivers/acpi/sleep/main.c -X!Edrivers/acpi/sleep/wakeup.c -X!Edrivers/acpi/motherboard.c -X!Edrivers/acpi/bus.c ---> -!Edrivers/acpi/scan.c -!Idrivers/acpi/scan.c -<!-- No correct structured comments -X!Edrivers/acpi/pci_bind.c ---> - </sect1> - <sect1><title>Device drivers PnP support</title> -!Idrivers/pnp/core.c -<!-- No correct structured comments -X!Edrivers/pnp/system.c - --> -!Edrivers/pnp/card.c -!Idrivers/pnp/driver.c -!Edrivers/pnp/manager.c -!Edrivers/pnp/support.c - </sect1> - <sect1><title>Userspace IO devices</title> -!Edrivers/uio/uio.c -!Iinclude/linux/uio_driver.h - </sect1> - </chapter> - - <chapter id="parportdev"> - <title>Parallel Port Devices</title> -!Iinclude/linux/parport.h -!Edrivers/parport/ieee1284.c -!Edrivers/parport/share.c -!Idrivers/parport/daisy.c - </chapter> - - <chapter id="message_devices"> - <title>Message-based devices</title> - <sect1><title>Fusion message devices</title> -!Edrivers/message/fusion/mptbase.c -!Idrivers/message/fusion/mptbase.c -!Edrivers/message/fusion/mptscsih.c -!Idrivers/message/fusion/mptscsih.c -!Idrivers/message/fusion/mptctl.c -!Idrivers/message/fusion/mptspi.c -!Idrivers/message/fusion/mptfc.c -!Idrivers/message/fusion/mptlan.c - </sect1> - </chapter> - - <chapter id="snddev"> - <title>Sound Devices</title> -!Iinclude/sound/core.h -!Esound/sound_core.c -!Iinclude/sound/pcm.h -!Esound/core/pcm.c -!Esound/core/device.c -!Esound/core/info.c -!Esound/core/rawmidi.c -!Esound/core/sound.c -!Esound/core/memory.c -!Esound/core/pcm_memory.c -!Esound/core/init.c -!Esound/core/isadma.c -!Esound/core/control.c -!Esound/core/pcm_lib.c -!Esound/core/hwdep.c -!Esound/core/pcm_native.c -!Esound/core/memalloc.c -<!-- FIXME: Removed for now since no structured comments in source -X!Isound/sound_firmware.c ---> - </chapter> - - <chapter id="mediadev"> - <title>Media Devices</title> - - <sect1><title>Video2Linux devices</title> -!Iinclude/media/tuner.h -!Iinclude/media/tuner-types.h -!Iinclude/media/tveeprom.h -!Iinclude/media/v4l2-async.h -!Iinclude/media/v4l2-ctrls.h -!Iinclude/media/v4l2-dv-timings.h -!Iinclude/media/v4l2-event.h -!Iinclude/media/v4l2-flash-led-class.h -!Iinclude/media/v4l2-mediabus.h -!Iinclude/media/v4l2-mem2mem.h -!Iinclude/media/v4l2-of.h -!Iinclude/media/v4l2-subdev.h -!Iinclude/media/videobuf2-core.h -!Iinclude/media/videobuf2-v4l2.h -!Iinclude/media/videobuf2-memops.h - </sect1> - <sect1><title>Digital TV (DVB) devices</title> - <sect1><title>Digital TV Common functions</title> -!Idrivers/media/dvb-core/dvb_math.h -!Idrivers/media/dvb-core/dvb_ringbuffer.h -!Idrivers/media/dvb-core/dvbdev.h - </sect1> - <sect1><title>Digital TV Frontend kABI</title> -!Pdrivers/media/dvb-core/dvb_frontend.h Digital TV Frontend -!Idrivers/media/dvb-core/dvb_frontend.h - </sect1> - <sect1><title>Digital TV Demux kABI</title> -!Pdrivers/media/dvb-core/demux.h Digital TV Demux - <sect1><title>Demux Callback API</title> -!Pdrivers/media/dvb-core/demux.h Demux Callback - </sect1> -!Idrivers/media/dvb-core/demux.h - </sect1> - <sect1><title>Digital TV Conditional Access kABI</title> -!Idrivers/media/dvb-core/dvb_ca_en50221.h - </sect1> - </sect1> - <sect1><title>Remote Controller devices</title> -!Iinclude/media/rc-core.h -!Iinclude/media/lirc_dev.h - </sect1> - <sect1><title>Media Controller devices</title> -!Pinclude/media/media-device.h Media Controller -!Iinclude/media/media-device.h -!Iinclude/media/media-devnode.h -!Iinclude/media/media-entity.h - </sect1> - - </chapter> - - <chapter id="uart16x50"> - <title>16x50 UART Driver</title> -!Edrivers/tty/serial/serial_core.c -!Edrivers/tty/serial/8250/8250_core.c - </chapter> - - <chapter id="fbdev"> - <title>Frame Buffer Library</title> - - <para> - The frame buffer drivers depend heavily on four data structures. - These structures are declared in include/linux/fb.h. They are - fb_info, fb_var_screeninfo, fb_fix_screeninfo and fb_monospecs. - The last three can be made available to and from userland. - </para> - - <para> - fb_info defines the current state of a particular video card. - Inside fb_info, there exists a fb_ops structure which is a - collection of needed functions to make fbdev and fbcon work. - fb_info is only visible to the kernel. - </para> - - <para> - fb_var_screeninfo is used to describe the features of a video card - that are user defined. With fb_var_screeninfo, things such as - depth and the resolution may be defined. - </para> - - <para> - The next structure is fb_fix_screeninfo. This defines the - properties of a card that are created when a mode is set and can't - be changed otherwise. A good example of this is the start of the - frame buffer memory. This "locks" the address of the frame buffer - memory, so that it cannot be changed or moved. - </para> - - <para> - The last structure is fb_monospecs. In the old API, there was - little importance for fb_monospecs. This allowed for forbidden things - such as setting a mode of 800x600 on a fix frequency monitor. With - the new API, fb_monospecs prevents such things, and if used - correctly, can prevent a monitor from being cooked. fb_monospecs - will not be useful until kernels 2.5.x. - </para> - - <sect1><title>Frame Buffer Memory</title> -!Edrivers/video/fbdev/core/fbmem.c - </sect1> -<!-- - <sect1><title>Frame Buffer Console</title> -X!Edrivers/video/console/fbcon.c - </sect1> ---> - <sect1><title>Frame Buffer Colormap</title> -!Edrivers/video/fbdev/core/fbcmap.c - </sect1> -<!-- FIXME: - drivers/video/fbgen.c has no docs, which stuffs up the sgml. Comment - out until somebody adds docs. KAO - <sect1><title>Frame Buffer Generic Functions</title> -X!Idrivers/video/fbgen.c - </sect1> -KAO --> - <sect1><title>Frame Buffer Video Mode Database</title> -!Idrivers/video/fbdev/core/modedb.c -!Edrivers/video/fbdev/core/modedb.c - </sect1> - <sect1><title>Frame Buffer Macintosh Video Mode Database</title> -!Edrivers/video/fbdev/macmodes.c - </sect1> - <sect1><title>Frame Buffer Fonts</title> - <para> - Refer to the file lib/fonts/fonts.c for more information. - </para> -<!-- FIXME: Removed for now since no structured comments in source -X!Ilib/fonts/fonts.c ---> - </sect1> - </chapter> - - <chapter id="input_subsystem"> - <title>Input Subsystem</title> - <sect1><title>Input core</title> -!Iinclude/linux/input.h -!Edrivers/input/input.c -!Edrivers/input/ff-core.c -!Edrivers/input/ff-memless.c - </sect1> - <sect1><title>Multitouch Library</title> -!Iinclude/linux/input/mt.h -!Edrivers/input/input-mt.c - </sect1> - <sect1><title>Polled input devices</title> -!Iinclude/linux/input-polldev.h -!Edrivers/input/input-polldev.c - </sect1> - <sect1><title>Matrix keyboars/keypads</title> -!Iinclude/linux/input/matrix_keypad.h - </sect1> - <sect1><title>Sparse keymap support</title> -!Iinclude/linux/input/sparse-keymap.h -!Edrivers/input/sparse-keymap.c - </sect1> - </chapter> - - <chapter id="spi"> - <title>Serial Peripheral Interface (SPI)</title> - <para> - SPI is the "Serial Peripheral Interface", widely used with - embedded systems because it is a simple and efficient - interface: basically a multiplexed shift register. - Its three signal wires hold a clock (SCK, often in the range - of 1-20 MHz), a "Master Out, Slave In" (MOSI) data line, and - a "Master In, Slave Out" (MISO) data line. - SPI is a full duplex protocol; for each bit shifted out the - MOSI line (one per clock) another is shifted in on the MISO line. - Those bits are assembled into words of various sizes on the - way to and from system memory. - An additional chipselect line is usually active-low (nCS); - four signals are normally used for each peripheral, plus - sometimes an interrupt. - </para> - <para> - The SPI bus facilities listed here provide a generalized - interface to declare SPI busses and devices, manage them - according to the standard Linux driver model, and perform - input/output operations. - At this time, only "master" side interfaces are supported, - where Linux talks to SPI peripherals and does not implement - such a peripheral itself. - (Interfaces to support implementing SPI slaves would - necessarily look different.) - </para> - <para> - The programming interface is structured around two kinds of driver, - and two kinds of device. - A "Controller Driver" abstracts the controller hardware, which may - be as simple as a set of GPIO pins or as complex as a pair of FIFOs - connected to dual DMA engines on the other side of the SPI shift - register (maximizing throughput). Such drivers bridge between - whatever bus they sit on (often the platform bus) and SPI, and - expose the SPI side of their device as a - <structname>struct spi_master</structname>. - SPI devices are children of that master, represented as a - <structname>struct spi_device</structname> and manufactured from - <structname>struct spi_board_info</structname> descriptors which - are usually provided by board-specific initialization code. - A <structname>struct spi_driver</structname> is called a - "Protocol Driver", and is bound to a spi_device using normal - driver model calls. - </para> - <para> - The I/O model is a set of queued messages. Protocol drivers - submit one or more <structname>struct spi_message</structname> - objects, which are processed and completed asynchronously. - (There are synchronous wrappers, however.) Messages are - built from one or more <structname>struct spi_transfer</structname> - objects, each of which wraps a full duplex SPI transfer. - A variety of protocol tweaking options are needed, because - different chips adopt very different policies for how they - use the bits transferred with SPI. - </para> -!Iinclude/linux/spi/spi.h -!Fdrivers/spi/spi.c spi_register_board_info -!Edrivers/spi/spi.c - </chapter> - - <chapter id="i2c"> - <title>I<superscript>2</superscript>C and SMBus Subsystem</title> - - <para> - I<superscript>2</superscript>C (or without fancy typography, "I2C") - is an acronym for the "Inter-IC" bus, a simple bus protocol which is - widely used where low data rate communications suffice. - Since it's also a licensed trademark, some vendors use another - name (such as "Two-Wire Interface", TWI) for the same bus. - I2C only needs two signals (SCL for clock, SDA for data), conserving - board real estate and minimizing signal quality issues. - Most I2C devices use seven bit addresses, and bus speeds of up - to 400 kHz; there's a high speed extension (3.4 MHz) that's not yet - found wide use. - I2C is a multi-master bus; open drain signaling is used to - arbitrate between masters, as well as to handshake and to - synchronize clocks from slower clients. - </para> - - <para> - The Linux I2C programming interfaces support only the master - side of bus interactions, not the slave side. - The programming interface is structured around two kinds of driver, - and two kinds of device. - An I2C "Adapter Driver" abstracts the controller hardware; it binds - to a physical device (perhaps a PCI device or platform_device) and - exposes a <structname>struct i2c_adapter</structname> representing - each I2C bus segment it manages. - On each I2C bus segment will be I2C devices represented by a - <structname>struct i2c_client</structname>. Those devices will - be bound to a <structname>struct i2c_driver</structname>, - which should follow the standard Linux driver model. - (At this writing, a legacy model is more widely used.) - There are functions to perform various I2C protocol operations; at - this writing all such functions are usable only from task context. - </para> - - <para> - The System Management Bus (SMBus) is a sibling protocol. Most SMBus - systems are also I2C conformant. The electrical constraints are - tighter for SMBus, and it standardizes particular protocol messages - and idioms. Controllers that support I2C can also support most - SMBus operations, but SMBus controllers don't support all the protocol - options that an I2C controller will. - There are functions to perform various SMBus protocol operations, - either using I2C primitives or by issuing SMBus commands to - i2c_adapter devices which don't support those I2C operations. - </para> - -!Iinclude/linux/i2c.h -!Fdrivers/i2c/i2c-boardinfo.c i2c_register_board_info -!Edrivers/i2c/i2c-core.c - </chapter> - - <chapter id="hsi"> - <title>High Speed Synchronous Serial Interface (HSI)</title> - - <para> - High Speed Synchronous Serial Interface (HSI) is a - serial interface mainly used for connecting application - engines (APE) with cellular modem engines (CMT) in cellular - handsets. - - HSI provides multiplexing for up to 16 logical channels, - low-latency and full duplex communication. - </para> - -!Iinclude/linux/hsi/hsi.h -!Edrivers/hsi/hsi.c - </chapter> - - <chapter id="pwm"> - <title>Pulse-Width Modulation (PWM)</title> - <para> - Pulse-width modulation is a modulation technique primarily used to - control power supplied to electrical devices. - </para> - <para> - The PWM framework provides an abstraction for providers and consumers - of PWM signals. A controller that provides one or more PWM signals is - registered as <structname>struct pwm_chip</structname>. Providers are - expected to embed this structure in a driver-specific structure. This - structure contains fields that describe a particular chip. - </para> - <para> - A chip exposes one or more PWM signal sources, each of which exposed - as a <structname>struct pwm_device</structname>. Operations can be - performed on PWM devices to control the period, duty cycle, polarity - and active state of the signal. - </para> - <para> - Note that PWM devices are exclusive resources: they can always only be - used by one consumer at a time. - </para> -!Iinclude/linux/pwm.h -!Edrivers/pwm/core.c - </chapter> - -</book> diff --git a/Documentation/DocBook/deviceiobook.tmpl b/Documentation/DocBook/deviceiobook.tmpl deleted file mode 100644 index 54199a0dcf9a..000000000000 --- a/Documentation/DocBook/deviceiobook.tmpl +++ /dev/null @@ -1,323 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="DoingIO"> - <bookinfo> - <title>Bus-Independent Device Accesses</title> - - <authorgroup> - <author> - <firstname>Matthew</firstname> - <surname>Wilcox</surname> - <affiliation> - <address> - <email>matthew@wil.cx</email> - </address> - </affiliation> - </author> - </authorgroup> - - <authorgroup> - <author> - <firstname>Alan</firstname> - <surname>Cox</surname> - <affiliation> - <address> - <email>alan@lxorguk.ukuu.org.uk</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2001</year> - <holder>Matthew Wilcox</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="intro"> - <title>Introduction</title> - <para> - Linux provides an API which abstracts performing IO across all busses - and devices, allowing device drivers to be written independently of - bus type. - </para> - </chapter> - - <chapter id="bugs"> - <title>Known Bugs And Assumptions</title> - <para> - None. - </para> - </chapter> - - <chapter id="mmio"> - <title>Memory Mapped IO</title> - <sect1 id="getting_access_to_the_device"> - <title>Getting Access to the Device</title> - <para> - The most widely supported form of IO is memory mapped IO. - That is, a part of the CPU's address space is interpreted - not as accesses to memory, but as accesses to a device. Some - architectures define devices to be at a fixed address, but most - have some method of discovering devices. The PCI bus walk is a - good example of such a scheme. This document does not cover how - to receive such an address, but assumes you are starting with one. - Physical addresses are of type unsigned long. - </para> - - <para> - This address should not be used directly. Instead, to get an - address suitable for passing to the accessor functions described - below, you should call <function>ioremap</function>. - An address suitable for accessing the device will be returned to you. - </para> - - <para> - After you've finished using the device (say, in your module's - exit routine), call <function>iounmap</function> in order to return - the address space to the kernel. Most architectures allocate new - address space each time you call <function>ioremap</function>, and - they can run out unless you call <function>iounmap</function>. - </para> - </sect1> - - <sect1 id="accessing_the_device"> - <title>Accessing the device</title> - <para> - The part of the interface most used by drivers is reading and - writing memory-mapped registers on the device. Linux provides - interfaces to read and write 8-bit, 16-bit, 32-bit and 64-bit - quantities. Due to a historical accident, these are named byte, - word, long and quad accesses. Both read and write accesses are - supported; there is no prefetch support at this time. - </para> - - <para> - The functions are named <function>readb</function>, - <function>readw</function>, <function>readl</function>, - <function>readq</function>, <function>readb_relaxed</function>, - <function>readw_relaxed</function>, <function>readl_relaxed</function>, - <function>readq_relaxed</function>, <function>writeb</function>, - <function>writew</function>, <function>writel</function> and - <function>writeq</function>. - </para> - - <para> - Some devices (such as framebuffers) would like to use larger - transfers than 8 bytes at a time. For these devices, the - <function>memcpy_toio</function>, <function>memcpy_fromio</function> - and <function>memset_io</function> functions are provided. - Do not use memset or memcpy on IO addresses; they - are not guaranteed to copy data in order. - </para> - - <para> - The read and write functions are defined to be ordered. That is the - compiler is not permitted to reorder the I/O sequence. When the - ordering can be compiler optimised, you can use <function> - __readb</function> and friends to indicate the relaxed ordering. Use - this with care. - </para> - - <para> - While the basic functions are defined to be synchronous with respect - to each other and ordered with respect to each other the busses the - devices sit on may themselves have asynchronicity. In particular many - authors are burned by the fact that PCI bus writes are posted - asynchronously. A driver author must issue a read from the same - device to ensure that writes have occurred in the specific cases the - author cares. This kind of property cannot be hidden from driver - writers in the API. In some cases, the read used to flush the device - may be expected to fail (if the card is resetting, for example). In - that case, the read should be done from config space, which is - guaranteed to soft-fail if the card doesn't respond. - </para> - - <para> - The following is an example of flushing a write to a device when - the driver would like to ensure the write's effects are visible prior - to continuing execution. - </para> - -<programlisting> -static inline void -qla1280_disable_intrs(struct scsi_qla_host *ha) -{ - struct device_reg *reg; - - reg = ha->iobase; - /* disable risc and host interrupts */ - WRT_REG_WORD(&reg->ictrl, 0); - /* - * The following read will ensure that the above write - * has been received by the device before we return from this - * function. - */ - RD_REG_WORD(&reg->ictrl); - ha->flags.ints_enabled = 0; -} -</programlisting> - - <para> - In addition to write posting, on some large multiprocessing systems - (e.g. SGI Challenge, Origin and Altix machines) posted writes won't - be strongly ordered coming from different CPUs. Thus it's important - to properly protect parts of your driver that do memory-mapped writes - with locks and use the <function>mmiowb</function> to make sure they - arrive in the order intended. Issuing a regular <function>readX - </function> will also ensure write ordering, but should only be used - when the driver has to be sure that the write has actually arrived - at the device (not that it's simply ordered with respect to other - writes), since a full <function>readX</function> is a relatively - expensive operation. - </para> - - <para> - Generally, one should use <function>mmiowb</function> prior to - releasing a spinlock that protects regions using <function>writeb - </function> or similar functions that aren't surrounded by <function> - readb</function> calls, which will ensure ordering and flushing. The - following pseudocode illustrates what might occur if write ordering - isn't guaranteed via <function>mmiowb</function> or one of the - <function>readX</function> functions. - </para> - -<programlisting> -CPU A: spin_lock_irqsave(&dev_lock, flags) -CPU A: ... -CPU A: writel(newval, ring_ptr); -CPU A: spin_unlock_irqrestore(&dev_lock, flags) - ... -CPU B: spin_lock_irqsave(&dev_lock, flags) -CPU B: writel(newval2, ring_ptr); -CPU B: ... -CPU B: spin_unlock_irqrestore(&dev_lock, flags) -</programlisting> - - <para> - In the case above, newval2 could be written to ring_ptr before - newval. Fixing it is easy though: - </para> - -<programlisting> -CPU A: spin_lock_irqsave(&dev_lock, flags) -CPU A: ... -CPU A: writel(newval, ring_ptr); -CPU A: mmiowb(); /* ensure no other writes beat us to the device */ -CPU A: spin_unlock_irqrestore(&dev_lock, flags) - ... -CPU B: spin_lock_irqsave(&dev_lock, flags) -CPU B: writel(newval2, ring_ptr); -CPU B: ... -CPU B: mmiowb(); -CPU B: spin_unlock_irqrestore(&dev_lock, flags) -</programlisting> - - <para> - See tg3.c for a real world example of how to use <function>mmiowb - </function> - </para> - - <para> - PCI ordering rules also guarantee that PIO read responses arrive - after any outstanding DMA writes from that bus, since for some devices - the result of a <function>readb</function> call may signal to the - driver that a DMA transaction is complete. In many cases, however, - the driver may want to indicate that the next - <function>readb</function> call has no relation to any previous DMA - writes performed by the device. The driver can use - <function>readb_relaxed</function> for these cases, although only - some platforms will honor the relaxed semantics. Using the relaxed - read functions will provide significant performance benefits on - platforms that support it. The qla2xxx driver provides examples - of how to use <function>readX_relaxed</function>. In many cases, - a majority of the driver's <function>readX</function> calls can - safely be converted to <function>readX_relaxed</function> calls, since - only a few will indicate or depend on DMA completion. - </para> - </sect1> - - </chapter> - - <chapter id="port_space_accesses"> - <title>Port Space Accesses</title> - <sect1 id="port_space_explained"> - <title>Port Space Explained</title> - - <para> - Another form of IO commonly supported is Port Space. This is a - range of addresses separate to the normal memory address space. - Access to these addresses is generally not as fast as accesses - to the memory mapped addresses, and it also has a potentially - smaller address space. - </para> - - <para> - Unlike memory mapped IO, no preparation is required - to access port space. - </para> - - </sect1> - <sect1 id="accessing_port_space"> - <title>Accessing Port Space</title> - <para> - Accesses to this space are provided through a set of functions - which allow 8-bit, 16-bit and 32-bit accesses; also - known as byte, word and long. These functions are - <function>inb</function>, <function>inw</function>, - <function>inl</function>, <function>outb</function>, - <function>outw</function> and <function>outl</function>. - </para> - - <para> - Some variants are provided for these functions. Some devices - require that accesses to their ports are slowed down. This - functionality is provided by appending a <function>_p</function> - to the end of the function. There are also equivalents to memcpy. - The <function>ins</function> and <function>outs</function> - functions copy bytes, words or longs to the given port. - </para> - </sect1> - - </chapter> - - <chapter id="pubfunctions"> - <title>Public Functions Provided</title> -!Iarch/x86/include/asm/io.h -!Elib/pci_iomap.c - </chapter> - -</book> diff --git a/Documentation/DocBook/filesystems.tmpl b/Documentation/DocBook/filesystems.tmpl deleted file mode 100644 index 6006b6358c86..000000000000 --- a/Documentation/DocBook/filesystems.tmpl +++ /dev/null @@ -1,381 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="Linux-filesystems-API"> - <bookinfo> - <title>Linux Filesystems API</title> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="vfs"> - <title>The Linux VFS</title> - <sect1 id="the_filesystem_types"><title>The Filesystem types</title> -!Iinclude/linux/fs.h - </sect1> - <sect1 id="the_directory_cache"><title>The Directory Cache</title> -!Efs/dcache.c -!Iinclude/linux/dcache.h - </sect1> - <sect1 id="inode_handling"><title>Inode Handling</title> -!Efs/inode.c -!Efs/bad_inode.c - </sect1> - <sect1 id="registration_and_superblocks"><title>Registration and Superblocks</title> -!Efs/super.c - </sect1> - <sect1 id="file_locks"><title>File Locks</title> -!Efs/locks.c -!Ifs/locks.c - </sect1> - <sect1 id="other_functions"><title>Other Functions</title> -!Efs/mpage.c -!Efs/namei.c -!Efs/buffer.c -!Eblock/bio.c -!Efs/seq_file.c -!Efs/filesystems.c -!Efs/fs-writeback.c -!Efs/block_dev.c - </sect1> - </chapter> - - <chapter id="proc"> - <title>The proc filesystem</title> - - <sect1 id="sysctl_interface"><title>sysctl interface</title> -!Ekernel/sysctl.c - </sect1> - - <sect1 id="proc_filesystem_interface"><title>proc filesystem interface</title> -!Ifs/proc/base.c - </sect1> - </chapter> - - <chapter id="fs_events"> - <title>Events based on file descriptors</title> -!Efs/eventfd.c - </chapter> - - <chapter id="sysfs"> - <title>The Filesystem for Exporting Kernel Objects</title> -!Efs/sysfs/file.c -!Efs/sysfs/symlink.c - </chapter> - - <chapter id="debugfs"> - <title>The debugfs filesystem</title> - - <sect1 id="debugfs_interface"><title>debugfs interface</title> -!Efs/debugfs/inode.c -!Efs/debugfs/file.c - </sect1> - </chapter> - - <chapter id="LinuxJDBAPI"> - <chapterinfo> - <title>The Linux Journalling API</title> - - <authorgroup> - <author> - <firstname>Roger</firstname> - <surname>Gammans</surname> - <affiliation> - <address> - <email>rgammans@computer-surgery.co.uk</email> - </address> - </affiliation> - </author> - </authorgroup> - - <authorgroup> - <author> - <firstname>Stephen</firstname> - <surname>Tweedie</surname> - <affiliation> - <address> - <email>sct@redhat.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2002</year> - <holder>Roger Gammans</holder> - </copyright> - </chapterinfo> - - <title>The Linux Journalling API</title> - - <sect1 id="journaling_overview"> - <title>Overview</title> - <sect2 id="journaling_details"> - <title>Details</title> -<para> -The journalling layer is easy to use. You need to -first of all create a journal_t data structure. There are -two calls to do this dependent on how you decide to allocate the physical -media on which the journal resides. The jbd2_journal_init_inode() call -is for journals stored in filesystem inodes, or the jbd2_journal_init_dev() -call can be used for journal stored on a raw device (in a continuous range -of blocks). A journal_t is a typedef for a struct pointer, so when -you are finally finished make sure you call jbd2_journal_destroy() on it -to free up any used kernel memory. -</para> - -<para> -Once you have got your journal_t object you need to 'mount' or load the journal -file. The journalling layer expects the space for the journal was already -allocated and initialized properly by the userspace tools. When loading the -journal you must call jbd2_journal_load() to process journal contents. If the -client file system detects the journal contents does not need to be processed -(or even need not have valid contents), it may call jbd2_journal_wipe() to -clear the journal contents before calling jbd2_journal_load(). -</para> - -<para> -Note that jbd2_journal_wipe(..,0) calls jbd2_journal_skip_recovery() for you if -it detects any outstanding transactions in the journal and similarly -jbd2_journal_load() will call jbd2_journal_recover() if necessary. I would -advise reading ext4_load_journal() in fs/ext4/super.c for examples on this -stage. -</para> - -<para> -Now you can go ahead and start modifying the underlying -filesystem. Almost. -</para> - -<para> - -You still need to actually journal your filesystem changes, this -is done by wrapping them into transactions. Additionally you -also need to wrap the modification of each of the buffers -with calls to the journal layer, so it knows what the modifications -you are actually making are. To do this use jbd2_journal_start() which -returns a transaction handle. -</para> - -<para> -jbd2_journal_start() -and its counterpart jbd2_journal_stop(), which indicates the end of a -transaction are nestable calls, so you can reenter a transaction if necessary, -but remember you must call jbd2_journal_stop() the same number of times as -jbd2_journal_start() before the transaction is completed (or more accurately -leaves the update phase). Ext4/VFS makes use of this feature to simplify -handling of inode dirtying, quota support, etc. -</para> - -<para> -Inside each transaction you need to wrap the modifications to the -individual buffers (blocks). Before you start to modify a buffer you -need to call jbd2_journal_get_{create,write,undo}_access() as appropriate, -this allows the journalling layer to copy the unmodified data if it -needs to. After all the buffer may be part of a previously uncommitted -transaction. -At this point you are at last ready to modify a buffer, and once -you are have done so you need to call jbd2_journal_dirty_{meta,}data(). -Or if you've asked for access to a buffer you now know is now longer -required to be pushed back on the device you can call jbd2_journal_forget() -in much the same way as you might have used bforget() in the past. -</para> - -<para> -A jbd2_journal_flush() may be called at any time to commit and checkpoint -all your transactions. -</para> - -<para> -Then at umount time , in your put_super() you can then call jbd2_journal_destroy() -to clean up your in-core journal object. -</para> - -<para> -Unfortunately there a couple of ways the journal layer can cause a deadlock. -The first thing to note is that each task can only have -a single outstanding transaction at any one time, remember nothing -commits until the outermost jbd2_journal_stop(). This means -you must complete the transaction at the end of each file/inode/address -etc. operation you perform, so that the journalling system isn't re-entered -on another journal. Since transactions can't be nested/batched -across differing journals, and another filesystem other than -yours (say ext4) may be modified in a later syscall. -</para> - -<para> -The second case to bear in mind is that jbd2_journal_start() can -block if there isn't enough space in the journal for your transaction -(based on the passed nblocks param) - when it blocks it merely(!) needs to -wait for transactions to complete and be committed from other tasks, -so essentially we are waiting for jbd2_journal_stop(). So to avoid -deadlocks you must treat jbd2_journal_start/stop() as if they -were semaphores and include them in your semaphore ordering rules to prevent -deadlocks. Note that jbd2_journal_extend() has similar blocking behaviour to -jbd2_journal_start() so you can deadlock here just as easily as on -jbd2_journal_start(). -</para> - -<para> -Try to reserve the right number of blocks the first time. ;-). This will -be the maximum number of blocks you are going to touch in this transaction. -I advise having a look at at least ext4_jbd.h to see the basis on which -ext4 uses to make these decisions. -</para> - -<para> -Another wriggle to watch out for is your on-disk block allocation strategy. -Why? Because, if you do a delete, you need to ensure you haven't reused any -of the freed blocks until the transaction freeing these blocks commits. If you -reused these blocks and crash happens, there is no way to restore the contents -of the reallocated blocks at the end of the last fully committed transaction. - -One simple way of doing this is to mark blocks as free in internal in-memory -block allocation structures only after the transaction freeing them commits. -Ext4 uses journal commit callback for this purpose. -</para> - -<para> -With journal commit callbacks you can ask the journalling layer to call a -callback function when the transaction is finally committed to disk, so that -you can do some of your own management. You ask the journalling layer for -calling the callback by simply setting journal->j_commit_callback function -pointer and that function is called after each transaction commit. You can also -use transaction->t_private_list for attaching entries to a transaction that -need processing when the transaction commits. -</para> - -<para> -JBD2 also provides a way to block all transaction updates via -jbd2_journal_{un,}lock_updates(). Ext4 uses this when it wants a window with a -clean and stable fs for a moment. E.g. -</para> - -<programlisting> - - jbd2_journal_lock_updates() //stop new stuff happening.. - jbd2_journal_flush() // checkpoint everything. - ..do stuff on stable fs - jbd2_journal_unlock_updates() // carry on with filesystem use. -</programlisting> - -<para> -The opportunities for abuse and DOS attacks with this should be obvious, -if you allow unprivileged userspace to trigger codepaths containing these -calls. -</para> - - </sect2> - - <sect2 id="jbd_summary"> - <title>Summary</title> -<para> -Using the journal is a matter of wrapping the different context changes, -being each mount, each modification (transaction) and each changed buffer -to tell the journalling layer about them. -</para> - - </sect2> - - </sect1> - - <sect1 id="data_types"> - <title>Data Types</title> - <para> - The journalling layer uses typedefs to 'hide' the concrete definitions - of the structures used. As a client of the JBD2 layer you can - just rely on the using the pointer as a magic cookie of some sort. - - Obviously the hiding is not enforced as this is 'C'. - </para> - <sect2 id="structures"><title>Structures</title> -!Iinclude/linux/jbd2.h - </sect2> - </sect1> - - <sect1 id="functions"> - <title>Functions</title> - <para> - The functions here are split into two groups those that - affect a journal as a whole, and those which are used to - manage transactions - </para> - <sect2 id="journal_level"><title>Journal Level</title> -!Efs/jbd2/journal.c -!Ifs/jbd2/recovery.c - </sect2> - <sect2 id="transaction_level"><title>Transasction Level</title> -!Efs/jbd2/transaction.c - </sect2> - </sect1> - <sect1 id="see_also"> - <title>See also</title> - <para> - <citation> - <ulink url="http://kernel.org/pub/linux/kernel/people/sct/ext3/journal-design.ps.gz"> - Journaling the Linux ext2fs Filesystem, LinuxExpo 98, Stephen Tweedie - </ulink> - </citation> - </para> - <para> - <citation> - <ulink url="http://olstrans.sourceforge.net/release/OLS2000-ext3/OLS2000-ext3.html"> - Ext3 Journalling FileSystem, OLS 2000, Dr. Stephen Tweedie - </ulink> - </citation> - </para> - </sect1> - - </chapter> - - <chapter id="splice"> - <title>splice API</title> - <para> - splice is a method for moving blocks of data around inside the - kernel, without continually transferring them between the kernel - and user space. - </para> -!Ffs/splice.c - </chapter> - - <chapter id="pipes"> - <title>pipes API</title> - <para> - Pipe interfaces are all for in-kernel (builtin image) use. - They are not exported for use by modules. - </para> -!Iinclude/linux/pipe_fs_i.h -!Ffs/pipe.c - </chapter> - -</book> diff --git a/Documentation/DocBook/gadget.tmpl b/Documentation/DocBook/gadget.tmpl deleted file mode 100644 index 641629221176..000000000000 --- a/Documentation/DocBook/gadget.tmpl +++ /dev/null @@ -1,793 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="USB-Gadget-API"> - <bookinfo> - <title>USB Gadget API for Linux</title> - <date>20 August 2004</date> - <edition>20 August 2004</edition> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - <copyright> - <year>2003-2004</year> - <holder>David Brownell</holder> - </copyright> - - <author> - <firstname>David</firstname> - <surname>Brownell</surname> - <affiliation> - <address><email>dbrownell@users.sourceforge.net</email></address> - </affiliation> - </author> - </bookinfo> - -<toc></toc> - -<chapter id="intro"><title>Introduction</title> - -<para>This document presents a Linux-USB "Gadget" -kernel mode -API, for use within peripherals and other USB devices -that embed Linux. -It provides an overview of the API structure, -and shows how that fits into a system development project. -This is the first such API released on Linux to address -a number of important problems, including: </para> - -<itemizedlist> - <listitem><para>Supports USB 2.0, for high speed devices which - can stream data at several dozen megabytes per second. - </para></listitem> - <listitem><para>Handles devices with dozens of endpoints just as - well as ones with just two fixed-function ones. Gadget drivers - can be written so they're easy to port to new hardware. - </para></listitem> - <listitem><para>Flexible enough to expose more complex USB device - capabilities such as multiple configurations, multiple interfaces, - composite devices, - and alternate interface settings. - </para></listitem> - <listitem><para>USB "On-The-Go" (OTG) support, in conjunction - with updates to the Linux-USB host side. - </para></listitem> - <listitem><para>Sharing data structures and API models with the - Linux-USB host side API. This helps the OTG support, and - looks forward to more-symmetric frameworks (where the same - I/O model is used by both host and device side drivers). - </para></listitem> - <listitem><para>Minimalist, so it's easier to support new device - controller hardware. I/O processing doesn't imply large - demands for memory or CPU resources. - </para></listitem> -</itemizedlist> - - -<para>Most Linux developers will not be able to use this API, since they -have USB "host" hardware in a PC, workstation, or server. -Linux users with embedded systems are more likely to -have USB peripheral hardware. -To distinguish drivers running inside such hardware from the -more familiar Linux "USB device drivers", -which are host side proxies for the real USB devices, -a different term is used: -the drivers inside the peripherals are "USB gadget drivers". -In USB protocol interactions, the device driver is the master -(or "client driver") -and the gadget driver is the slave (or "function driver"). -</para> - -<para>The gadget API resembles the host side Linux-USB API in that both -use queues of request objects to package I/O buffers, and those requests -may be submitted or canceled. -They share common definitions for the standard USB -<emphasis>Chapter 9</emphasis> messages, structures, and constants. -Also, both APIs bind and unbind drivers to devices. -The APIs differ in detail, since the host side's current -URB framework exposes a number of implementation details -and assumptions that are inappropriate for a gadget API. -While the model for control transfers and configuration -management is necessarily different (one side is a hardware-neutral master, -the other is a hardware-aware slave), the endpoint I/0 API used here -should also be usable for an overhead-reduced host side API. -</para> - -</chapter> - -<chapter id="structure"><title>Structure of Gadget Drivers</title> - -<para>A system running inside a USB peripheral -normally has at least three layers inside the kernel to handle -USB protocol processing, and may have additional layers in -user space code. -The "gadget" API is used by the middle layer to interact -with the lowest level (which directly handles hardware). -</para> - -<para>In Linux, from the bottom up, these layers are: -</para> - -<variablelist> - - <varlistentry> - <term><emphasis>USB Controller Driver</emphasis></term> - - <listitem> - <para>This is the lowest software level. - It is the only layer that talks to hardware, - through registers, fifos, dma, irqs, and the like. - The <filename><linux/usb/gadget.h></filename> API abstracts - the peripheral controller endpoint hardware. - That hardware is exposed through endpoint objects, which accept - streams of IN/OUT buffers, and through callbacks that interact - with gadget drivers. - Since normal USB devices only have one upstream - port, they only have one of these drivers. - The controller driver can support any number of different - gadget drivers, but only one of them can be used at a time. - </para> - - <para>Examples of such controller hardware include - the PCI-based NetChip 2280 USB 2.0 high speed controller, - the SA-11x0 or PXA-25x UDC (found within many PDAs), - and a variety of other products. - </para> - - </listitem></varlistentry> - - <varlistentry> - <term><emphasis>Gadget Driver</emphasis></term> - - <listitem> - <para>The lower boundary of this driver implements hardware-neutral - USB functions, using calls to the controller driver. - Because such hardware varies widely in capabilities and restrictions, - and is used in embedded environments where space is at a premium, - the gadget driver is often configured at compile time - to work with endpoints supported by one particular controller. - Gadget drivers may be portable to several different controllers, - using conditional compilation. - (Recent kernels substantially simplify the work involved in - supporting new hardware, by <emphasis>autoconfiguring</emphasis> - endpoints automatically for many bulk-oriented drivers.) - Gadget driver responsibilities include: - </para> - <itemizedlist> - <listitem><para>handling setup requests (ep0 protocol responses) - possibly including class-specific functionality - </para></listitem> - <listitem><para>returning configuration and string descriptors - </para></listitem> - <listitem><para>(re)setting configurations and interface - altsettings, including enabling and configuring endpoints - </para></listitem> - <listitem><para>handling life cycle events, such as managing - bindings to hardware, - USB suspend/resume, remote wakeup, - and disconnection from the USB host. - </para></listitem> - <listitem><para>managing IN and OUT transfers on all currently - enabled endpoints - </para></listitem> - </itemizedlist> - - <para> - Such drivers may be modules of proprietary code, although - that approach is discouraged in the Linux community. - </para> - </listitem></varlistentry> - - <varlistentry> - <term><emphasis>Upper Level</emphasis></term> - - <listitem> - <para>Most gadget drivers have an upper boundary that connects - to some Linux driver or framework in Linux. - Through that boundary flows the data which the gadget driver - produces and/or consumes through protocol transfers over USB. - Examples include: - </para> - <itemizedlist> - <listitem><para>user mode code, using generic (gadgetfs) - or application specific files in - <filename>/dev</filename> - </para></listitem> - <listitem><para>networking subsystem (for network gadgets, - like the CDC Ethernet Model gadget driver) - </para></listitem> - <listitem><para>data capture drivers, perhaps video4Linux or - a scanner driver; or test and measurement hardware. - </para></listitem> - <listitem><para>input subsystem (for HID gadgets) - </para></listitem> - <listitem><para>sound subsystem (for audio gadgets) - </para></listitem> - <listitem><para>file system (for PTP gadgets) - </para></listitem> - <listitem><para>block i/o subsystem (for usb-storage gadgets) - </para></listitem> - <listitem><para>... and more </para></listitem> - </itemizedlist> - </listitem></varlistentry> - - <varlistentry> - <term><emphasis>Additional Layers</emphasis></term> - - <listitem> - <para>Other layers may exist. - These could include kernel layers, such as network protocol stacks, - as well as user mode applications building on standard POSIX - system call APIs such as - <emphasis>open()</emphasis>, <emphasis>close()</emphasis>, - <emphasis>read()</emphasis> and <emphasis>write()</emphasis>. - On newer systems, POSIX Async I/O calls may be an option. - Such user mode code will not necessarily be subject to - the GNU General Public License (GPL). - </para> - </listitem></varlistentry> - - -</variablelist> - -<para>OTG-capable systems will also need to include a standard Linux-USB -host side stack, -with <emphasis>usbcore</emphasis>, -one or more <emphasis>Host Controller Drivers</emphasis> (HCDs), -<emphasis>USB Device Drivers</emphasis> to support -the OTG "Targeted Peripheral List", -and so forth. -There will also be an <emphasis>OTG Controller Driver</emphasis>, -which is visible to gadget and device driver developers only indirectly. -That helps the host and device side USB controllers implement the -two new OTG protocols (HNP and SRP). -Roles switch (host to peripheral, or vice versa) using HNP -during USB suspend processing, and SRP can be viewed as a -more battery-friendly kind of device wakeup protocol. -</para> - -<para>Over time, reusable utilities are evolving to help make some -gadget driver tasks simpler. -For example, building configuration descriptors from vectors of -descriptors for the configurations interfaces and endpoints is -now automated, and many drivers now use autoconfiguration to -choose hardware endpoints and initialize their descriptors. - -A potential example of particular interest -is code implementing standard USB-IF protocols for -HID, networking, storage, or audio classes. -Some developers are interested in KDB or KGDB hooks, to let -target hardware be remotely debugged. -Most such USB protocol code doesn't need to be hardware-specific, -any more than network protocols like X11, HTTP, or NFS are. -Such gadget-side interface drivers should eventually be combined, -to implement composite devices. -</para> - -</chapter> - - -<chapter id="api"><title>Kernel Mode Gadget API</title> - -<para>Gadget drivers declare themselves through a -<emphasis>struct usb_gadget_driver</emphasis>, which is responsible for -most parts of enumeration for a <emphasis>struct usb_gadget</emphasis>. -The response to a set_configuration usually involves -enabling one or more of the <emphasis>struct usb_ep</emphasis> objects -exposed by the gadget, and submitting one or more -<emphasis>struct usb_request</emphasis> buffers to transfer data. -Understand those four data types, and their operations, and -you will understand how this API works. -</para> - -<note><title>Incomplete Data Type Descriptions</title> - -<para>This documentation was prepared using the standard Linux -kernel <filename>docproc</filename> tool, which turns text -and in-code comments into SGML DocBook and then into usable -formats such as HTML or PDF. -Other than the "Chapter 9" data types, most of the significant -data types and functions are described here. -</para> - -<para>However, docproc does not understand all the C constructs -that are used, so some relevant information is likely omitted from -what you are reading. -One example of such information is endpoint autoconfiguration. -You'll have to read the header file, and use example source -code (such as that for "Gadget Zero"), to fully understand the API. -</para> - -<para>The part of the API implementing some basic -driver capabilities is specific to the version of the -Linux kernel that's in use. -The 2.6 kernel includes a <emphasis>driver model</emphasis> -framework that has no analogue on earlier kernels; -so those parts of the gadget API are not fully portable. -(They are implemented on 2.4 kernels, but in a different way.) -The driver model state is another part of this API that is -ignored by the kerneldoc tools. -</para> -</note> - -<para>The core API does not expose -every possible hardware feature, only the most widely available ones. -There are significant hardware features, such as device-to-device DMA -(without temporary storage in a memory buffer) -that would be added using hardware-specific APIs. -</para> - -<para>This API allows drivers to use conditional compilation to handle -endpoint capabilities of different hardware, but doesn't require that. -Hardware tends to have arbitrary restrictions, relating to -transfer types, addressing, packet sizes, buffering, and availability. -As a rule, such differences only matter for "endpoint zero" logic -that handles device configuration and management. -The API supports limited run-time -detection of capabilities, through naming conventions for endpoints. -Many drivers will be able to at least partially autoconfigure -themselves. -In particular, driver init sections will often have endpoint -autoconfiguration logic that scans the hardware's list of endpoints -to find ones matching the driver requirements -(relying on those conventions), to eliminate some of the most -common reasons for conditional compilation. -</para> - -<para>Like the Linux-USB host side API, this API exposes -the "chunky" nature of USB messages: I/O requests are in terms -of one or more "packets", and packet boundaries are visible to drivers. -Compared to RS-232 serial protocols, USB resembles -synchronous protocols like HDLC -(N bytes per frame, multipoint addressing, host as the primary -station and devices as secondary stations) -more than asynchronous ones -(tty style: 8 data bits per frame, no parity, one stop bit). -So for example the controller drivers won't buffer -two single byte writes into a single two-byte USB IN packet, -although gadget drivers may do so when they implement -protocols where packet boundaries (and "short packets") -are not significant. -</para> - -<sect1 id="lifecycle"><title>Driver Life Cycle</title> - -<para>Gadget drivers make endpoint I/O requests to hardware without -needing to know many details of the hardware, but driver -setup/configuration code needs to handle some differences. -Use the API like this: -</para> - -<orderedlist numeration='arabic'> - -<listitem><para>Register a driver for the particular device side -usb controller hardware, -such as the net2280 on PCI (USB 2.0), -sa11x0 or pxa25x as found in Linux PDAs, -and so on. -At this point the device is logically in the USB ch9 initial state -("attached"), drawing no power and not usable -(since it does not yet support enumeration). -Any host should not see the device, since it's not -activated the data line pullup used by the host to -detect a device, even if VBUS power is available. -</para></listitem> - -<listitem><para>Register a gadget driver that implements some higher level -device function. That will then bind() to a usb_gadget, which -activates the data line pullup sometime after detecting VBUS. -</para></listitem> - -<listitem><para>The hardware driver can now start enumerating. -The steps it handles are to accept USB power and set_address requests. -Other steps are handled by the gadget driver. -If the gadget driver module is unloaded before the host starts to -enumerate, steps before step 7 are skipped. -</para></listitem> - -<listitem><para>The gadget driver's setup() call returns usb descriptors, -based both on what the bus interface hardware provides and on the -functionality being implemented. -That can involve alternate settings or configurations, -unless the hardware prevents such operation. -For OTG devices, each configuration descriptor includes -an OTG descriptor. -</para></listitem> - -<listitem><para>The gadget driver handles the last step of enumeration, -when the USB host issues a set_configuration call. -It enables all endpoints used in that configuration, -with all interfaces in their default settings. -That involves using a list of the hardware's endpoints, enabling each -endpoint according to its descriptor. -It may also involve using <function>usb_gadget_vbus_draw</function> -to let more power be drawn from VBUS, as allowed by that configuration. -For OTG devices, setting a configuration may also involve reporting -HNP capabilities through a user interface. -</para></listitem> - -<listitem><para>Do real work and perform data transfers, possibly involving -changes to interface settings or switching to new configurations, until the -device is disconnect()ed from the host. -Queue any number of transfer requests to each endpoint. -It may be suspended and resumed several times before being disconnected. -On disconnect, the drivers go back to step 3 (above). -</para></listitem> - -<listitem><para>When the gadget driver module is being unloaded, -the driver unbind() callback is issued. That lets the controller -driver be unloaded. -</para></listitem> - -</orderedlist> - -<para>Drivers will normally be arranged so that just loading the -gadget driver module (or statically linking it into a Linux kernel) -allows the peripheral device to be enumerated, but some drivers -will defer enumeration until some higher level component (like -a user mode daemon) enables it. -Note that at this lowest level there are no policies about how -ep0 configuration logic is implemented, -except that it should obey USB specifications. -Such issues are in the domain of gadget drivers, -including knowing about implementation constraints -imposed by some USB controllers -or understanding that composite devices might happen to -be built by integrating reusable components. -</para> - -<para>Note that the lifecycle above can be slightly different -for OTG devices. -Other than providing an additional OTG descriptor in each -configuration, only the HNP-related differences are particularly -visible to driver code. -They involve reporting requirements during the SET_CONFIGURATION -request, and the option to invoke HNP during some suspend callbacks. -Also, SRP changes the semantics of -<function>usb_gadget_wakeup</function> -slightly. -</para> - -</sect1> - -<sect1 id="ch9"><title>USB 2.0 Chapter 9 Types and Constants</title> - -<para>Gadget drivers -rely on common USB structures and constants -defined in the -<filename><linux/usb/ch9.h></filename> -header file, which is standard in Linux 2.6 kernels. -These are the same types and constants used by host -side drivers (and usbcore). -</para> - -!Iinclude/linux/usb/ch9.h -</sect1> - -<sect1 id="core"><title>Core Objects and Methods</title> - -<para>These are declared in -<filename><linux/usb/gadget.h></filename>, -and are used by gadget drivers to interact with -USB peripheral controller drivers. -</para> - - <!-- yeech, this is ugly in nsgmls PDF output. - - the PDF bookmark and refentry output nesting is wrong, - and the member/argument documentation indents ugly. - - plus something (docproc?) adds whitespace before the - descriptive paragraph text, so it can't line up right - unless the explanations are trivial. - --> - -!Iinclude/linux/usb/gadget.h -</sect1> - -<sect1 id="utils"><title>Optional Utilities</title> - -<para>The core API is sufficient for writing a USB Gadget Driver, -but some optional utilities are provided to simplify common tasks. -These utilities include endpoint autoconfiguration. -</para> - -!Edrivers/usb/gadget/usbstring.c -!Edrivers/usb/gadget/config.c -<!-- !Edrivers/usb/gadget/epautoconf.c --> -</sect1> - -<sect1 id="composite"><title>Composite Device Framework</title> - -<para>The core API is sufficient for writing drivers for composite -USB devices (with more than one function in a given configuration), -and also multi-configuration devices (also more than one function, -but not necessarily sharing a given configuration). -There is however an optional framework which makes it easier to -reuse and combine functions. -</para> - -<para>Devices using this framework provide a <emphasis>struct -usb_composite_driver</emphasis>, which in turn provides one or -more <emphasis>struct usb_configuration</emphasis> instances. -Each such configuration includes at least one -<emphasis>struct usb_function</emphasis>, which packages a user -visible role such as "network link" or "mass storage device". -Management functions may also exist, such as "Device Firmware -Upgrade". -</para> - -!Iinclude/linux/usb/composite.h -!Edrivers/usb/gadget/composite.c - -</sect1> - -<sect1 id="functions"><title>Composite Device Functions</title> - -<para>At this writing, a few of the current gadget drivers have -been converted to this framework. -Near-term plans include converting all of them, except for "gadgetfs". -</para> - -!Edrivers/usb/gadget/function/f_acm.c -!Edrivers/usb/gadget/function/f_ecm.c -!Edrivers/usb/gadget/function/f_subset.c -!Edrivers/usb/gadget/function/f_obex.c -!Edrivers/usb/gadget/function/f_serial.c - -</sect1> - - -</chapter> - -<chapter id="controllers"><title>Peripheral Controller Drivers</title> - -<para>The first hardware supporting this API was the NetChip 2280 -controller, which supports USB 2.0 high speed and is based on PCI. -This is the <filename>net2280</filename> driver module. -The driver supports Linux kernel versions 2.4 and 2.6; -contact NetChip Technologies for development boards and product -information. -</para> - -<para>Other hardware working in the "gadget" framework includes: -Intel's PXA 25x and IXP42x series processors -(<filename>pxa2xx_udc</filename>), -Toshiba TC86c001 "Goku-S" (<filename>goku_udc</filename>), -Renesas SH7705/7727 (<filename>sh_udc</filename>), -MediaQ 11xx (<filename>mq11xx_udc</filename>), -Hynix HMS30C7202 (<filename>h7202_udc</filename>), -National 9303/4 (<filename>n9604_udc</filename>), -Texas Instruments OMAP (<filename>omap_udc</filename>), -Sharp LH7A40x (<filename>lh7a40x_udc</filename>), -and more. -Most of those are full speed controllers. -</para> - -<para>At this writing, there are people at work on drivers in -this framework for several other USB device controllers, -with plans to make many of them be widely available. -</para> - -<!-- !Edrivers/usb/gadget/net2280.c --> - -<para>A partial USB simulator, -the <filename>dummy_hcd</filename> driver, is available. -It can act like a net2280, a pxa25x, or an sa11x0 in terms -of available endpoints and device speeds; and it simulates -control, bulk, and to some extent interrupt transfers. -That lets you develop some parts of a gadget driver on a normal PC, -without any special hardware, and perhaps with the assistance -of tools such as GDB running with User Mode Linux. -At least one person has expressed interest in adapting that -approach, hooking it up to a simulator for a microcontroller. -Such simulators can help debug subsystems where the runtime hardware -is unfriendly to software development, or is not yet available. -</para> - -<para>Support for other controllers is expected to be developed -and contributed -over time, as this driver framework evolves. -</para> - -</chapter> - -<chapter id="gadget"><title>Gadget Drivers</title> - -<para>In addition to <emphasis>Gadget Zero</emphasis> -(used primarily for testing and development with drivers -for usb controller hardware), other gadget drivers exist. -</para> - -<para>There's an <emphasis>ethernet</emphasis> gadget -driver, which implements one of the most useful -<emphasis>Communications Device Class</emphasis> (CDC) models. -One of the standards for cable modem interoperability even -specifies the use of this ethernet model as one of two -mandatory options. -Gadgets using this code look to a USB host as if they're -an Ethernet adapter. -It provides access to a network where the gadget's CPU is one host, -which could easily be bridging, routing, or firewalling -access to other networks. -Since some hardware can't fully implement the CDC Ethernet -requirements, this driver also implements a "good parts only" -subset of CDC Ethernet. -(That subset doesn't advertise itself as CDC Ethernet, -to avoid creating problems.) -</para> - -<para>Support for Microsoft's <emphasis>RNDIS</emphasis> -protocol has been contributed by Pengutronix and Auerswald GmbH. -This is like CDC Ethernet, but it runs on more slightly USB hardware -(but less than the CDC subset). -However, its main claim to fame is being able to connect directly to -recent versions of Windows, using drivers that Microsoft bundles -and supports, making it much simpler to network with Windows. -</para> - -<para>There is also support for user mode gadget drivers, -using <emphasis>gadgetfs</emphasis>. -This provides a <emphasis>User Mode API</emphasis> that presents -each endpoint as a single file descriptor. I/O is done using -normal <emphasis>read()</emphasis> and <emphasis>read()</emphasis> calls. -Familiar tools like GDB and pthreads can be used to -develop and debug user mode drivers, so that once a robust -controller driver is available many applications for it -won't require new kernel mode software. -Linux 2.6 <emphasis>Async I/O (AIO)</emphasis> -support is available, so that user mode software -can stream data with only slightly more overhead -than a kernel driver. -</para> - -<para>There's a USB Mass Storage class driver, which provides -a different solution for interoperability with systems such -as MS-Windows and MacOS. -That <emphasis>Mass Storage</emphasis> driver uses a -file or block device as backing store for a drive, -like the <filename>loop</filename> driver. -The USB host uses the BBB, CB, or CBI versions of the mass -storage class specification, using transparent SCSI commands -to access the data from the backing store. -</para> - -<para>There's a "serial line" driver, useful for TTY style -operation over USB. -The latest version of that driver supports CDC ACM style -operation, like a USB modem, and so on most hardware it can -interoperate easily with MS-Windows. -One interesting use of that driver is in boot firmware (like a BIOS), -which can sometimes use that model with very small systems without -real serial lines. -</para> - -<para>Support for other kinds of gadget is expected to -be developed and contributed -over time, as this driver framework evolves. -</para> - -</chapter> - -<chapter id="otg"><title>USB On-The-GO (OTG)</title> - -<para>USB OTG support on Linux 2.6 was initially developed -by Texas Instruments for -<ulink url="http://www.omap.com">OMAP</ulink> 16xx and 17xx -series processors. -Other OTG systems should work in similar ways, but the -hardware level details could be very different. -</para> - -<para>Systems need specialized hardware support to implement OTG, -notably including a special <emphasis>Mini-AB</emphasis> jack -and associated transceiver to support <emphasis>Dual-Role</emphasis> -operation: -they can act either as a host, using the standard -Linux-USB host side driver stack, -or as a peripheral, using this "gadget" framework. -To do that, the system software relies on small additions -to those programming interfaces, -and on a new internal component (here called an "OTG Controller") -affecting which driver stack connects to the OTG port. -In each role, the system can re-use the existing pool of -hardware-neutral drivers, layered on top of the controller -driver interfaces (<emphasis>usb_bus</emphasis> or -<emphasis>usb_gadget</emphasis>). -Such drivers need at most minor changes, and most of the calls -added to support OTG can also benefit non-OTG products. -</para> - -<itemizedlist> - <listitem><para>Gadget drivers test the <emphasis>is_otg</emphasis> - flag, and use it to determine whether or not to include - an OTG descriptor in each of their configurations. - </para></listitem> - <listitem><para>Gadget drivers may need changes to support the - two new OTG protocols, exposed in new gadget attributes - such as <emphasis>b_hnp_enable</emphasis> flag. - HNP support should be reported through a user interface - (two LEDs could suffice), and is triggered in some cases - when the host suspends the peripheral. - SRP support can be user-initiated just like remote wakeup, - probably by pressing the same button. - </para></listitem> - <listitem><para>On the host side, USB device drivers need - to be taught to trigger HNP at appropriate moments, using - <function>usb_suspend_device()</function>. - That also conserves battery power, which is useful even - for non-OTG configurations. - </para></listitem> - <listitem><para>Also on the host side, a driver must support the - OTG "Targeted Peripheral List". That's just a whitelist, - used to reject peripherals not supported with a given - Linux OTG host. - <emphasis>This whitelist is product-specific; - each product must modify <filename>otg_whitelist.h</filename> - to match its interoperability specification. - </emphasis> - </para> - <para>Non-OTG Linux hosts, like PCs and workstations, - normally have some solution for adding drivers, so that - peripherals that aren't recognized can eventually be supported. - That approach is unreasonable for consumer products that may - never have their firmware upgraded, and where it's usually - unrealistic to expect traditional PC/workstation/server kinds - of support model to work. - For example, it's often impractical to change device firmware - once the product has been distributed, so driver bugs can't - normally be fixed if they're found after shipment. - </para></listitem> -</itemizedlist> - -<para> -Additional changes are needed below those hardware-neutral -<emphasis>usb_bus</emphasis> and <emphasis>usb_gadget</emphasis> -driver interfaces; those aren't discussed here in any detail. -Those affect the hardware-specific code for each USB Host or Peripheral -controller, and how the HCD initializes (since OTG can be active only -on a single port). -They also involve what may be called an <emphasis>OTG Controller -Driver</emphasis>, managing the OTG transceiver and the OTG state -machine logic as well as much of the root hub behavior for the -OTG port. -The OTG controller driver needs to activate and deactivate USB -controllers depending on the relevant device role. -Some related changes were needed inside usbcore, so that it -can identify OTG-capable devices and respond appropriately -to HNP or SRP protocols. -</para> - -</chapter> - -</book> -<!-- - vim:syntax=sgml:sw=4 ---> diff --git a/Documentation/DocBook/genericirq.tmpl b/Documentation/DocBook/genericirq.tmpl deleted file mode 100644 index 59fb5c077541..000000000000 --- a/Documentation/DocBook/genericirq.tmpl +++ /dev/null @@ -1,520 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="Generic-IRQ-Guide"> - <bookinfo> - <title>Linux generic IRQ handling</title> - - <authorgroup> - <author> - <firstname>Thomas</firstname> - <surname>Gleixner</surname> - <affiliation> - <address> - <email>tglx@linutronix.de</email> - </address> - </affiliation> - </author> - <author> - <firstname>Ingo</firstname> - <surname>Molnar</surname> - <affiliation> - <address> - <email>mingo@elte.hu</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2005-2010</year> - <holder>Thomas Gleixner</holder> - </copyright> - <copyright> - <year>2005-2006</year> - <holder>Ingo Molnar</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License version 2 as published by the Free Software Foundation. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="intro"> - <title>Introduction</title> - <para> - The generic interrupt handling layer is designed to provide a - complete abstraction of interrupt handling for device drivers. - It is able to handle all the different types of interrupt controller - hardware. Device drivers use generic API functions to request, enable, - disable and free interrupts. The drivers do not have to know anything - about interrupt hardware details, so they can be used on different - platforms without code changes. - </para> - <para> - This documentation is provided to developers who want to implement - an interrupt subsystem based for their architecture, with the help - of the generic IRQ handling layer. - </para> - </chapter> - - <chapter id="rationale"> - <title>Rationale</title> - <para> - The original implementation of interrupt handling in Linux uses - the __do_IRQ() super-handler, which is able to deal with every - type of interrupt logic. - </para> - <para> - Originally, Russell King identified different types of handlers to - build a quite universal set for the ARM interrupt handler - implementation in Linux 2.5/2.6. He distinguished between: - <itemizedlist> - <listitem><para>Level type</para></listitem> - <listitem><para>Edge type</para></listitem> - <listitem><para>Simple type</para></listitem> - </itemizedlist> - During the implementation we identified another type: - <itemizedlist> - <listitem><para>Fast EOI type</para></listitem> - </itemizedlist> - In the SMP world of the __do_IRQ() super-handler another type - was identified: - <itemizedlist> - <listitem><para>Per CPU type</para></listitem> - </itemizedlist> - </para> - <para> - This split implementation of high-level IRQ handlers allows us to - optimize the flow of the interrupt handling for each specific - interrupt type. This reduces complexity in that particular code path - and allows the optimized handling of a given type. - </para> - <para> - The original general IRQ implementation used hw_interrupt_type - structures and their ->ack(), ->end() [etc.] callbacks to - differentiate the flow control in the super-handler. This leads to - a mix of flow logic and low-level hardware logic, and it also leads - to unnecessary code duplication: for example in i386, there is an - ioapic_level_irq and an ioapic_edge_irq IRQ-type which share many - of the low-level details but have different flow handling. - </para> - <para> - A more natural abstraction is the clean separation of the - 'irq flow' and the 'chip details'. - </para> - <para> - Analysing a couple of architecture's IRQ subsystem implementations - reveals that most of them can use a generic set of 'irq flow' - methods and only need to add the chip-level specific code. - The separation is also valuable for (sub)architectures - which need specific quirks in the IRQ flow itself but not in the - chip details - and thus provides a more transparent IRQ subsystem - design. - </para> - <para> - Each interrupt descriptor is assigned its own high-level flow - handler, which is normally one of the generic - implementations. (This high-level flow handler implementation also - makes it simple to provide demultiplexing handlers which can be - found in embedded platforms on various architectures.) - </para> - <para> - The separation makes the generic interrupt handling layer more - flexible and extensible. For example, an (sub)architecture can - use a generic IRQ-flow implementation for 'level type' interrupts - and add a (sub)architecture specific 'edge type' implementation. - </para> - <para> - To make the transition to the new model easier and prevent the - breakage of existing implementations, the __do_IRQ() super-handler - is still available. This leads to a kind of duality for the time - being. Over time the new model should be used in more and more - architectures, as it enables smaller and cleaner IRQ subsystems. - It's deprecated for three years now and about to be removed. - </para> - </chapter> - <chapter id="bugs"> - <title>Known Bugs And Assumptions</title> - <para> - None (knock on wood). - </para> - </chapter> - - <chapter id="Abstraction"> - <title>Abstraction layers</title> - <para> - There are three main levels of abstraction in the interrupt code: - <orderedlist> - <listitem><para>High-level driver API</para></listitem> - <listitem><para>High-level IRQ flow handlers</para></listitem> - <listitem><para>Chip-level hardware encapsulation</para></listitem> - </orderedlist> - </para> - <sect1 id="Interrupt_control_flow"> - <title>Interrupt control flow</title> - <para> - Each interrupt is described by an interrupt descriptor structure - irq_desc. The interrupt is referenced by an 'unsigned int' numeric - value which selects the corresponding interrupt description structure - in the descriptor structures array. - The descriptor structure contains status information and pointers - to the interrupt flow method and the interrupt chip structure - which are assigned to this interrupt. - </para> - <para> - Whenever an interrupt triggers, the low-level architecture code calls - into the generic interrupt code by calling desc->handle_irq(). - This high-level IRQ handling function only uses desc->irq_data.chip - primitives referenced by the assigned chip descriptor structure. - </para> - </sect1> - <sect1 id="Highlevel_Driver_API"> - <title>High-level Driver API</title> - <para> - The high-level Driver API consists of following functions: - <itemizedlist> - <listitem><para>request_irq()</para></listitem> - <listitem><para>free_irq()</para></listitem> - <listitem><para>disable_irq()</para></listitem> - <listitem><para>enable_irq()</para></listitem> - <listitem><para>disable_irq_nosync() (SMP only)</para></listitem> - <listitem><para>synchronize_irq() (SMP only)</para></listitem> - <listitem><para>irq_set_irq_type()</para></listitem> - <listitem><para>irq_set_irq_wake()</para></listitem> - <listitem><para>irq_set_handler_data()</para></listitem> - <listitem><para>irq_set_chip()</para></listitem> - <listitem><para>irq_set_chip_data()</para></listitem> - </itemizedlist> - See the autogenerated function documentation for details. - </para> - </sect1> - <sect1 id="Highlevel_IRQ_flow_handlers"> - <title>High-level IRQ flow handlers</title> - <para> - The generic layer provides a set of pre-defined irq-flow methods: - <itemizedlist> - <listitem><para>handle_level_irq</para></listitem> - <listitem><para>handle_edge_irq</para></listitem> - <listitem><para>handle_fasteoi_irq</para></listitem> - <listitem><para>handle_simple_irq</para></listitem> - <listitem><para>handle_percpu_irq</para></listitem> - <listitem><para>handle_edge_eoi_irq</para></listitem> - <listitem><para>handle_bad_irq</para></listitem> - </itemizedlist> - The interrupt flow handlers (either pre-defined or architecture - specific) are assigned to specific interrupts by the architecture - either during bootup or during device initialization. - </para> - <sect2 id="Default_flow_implementations"> - <title>Default flow implementations</title> - <sect3 id="Helper_functions"> - <title>Helper functions</title> - <para> - The helper functions call the chip primitives and - are used by the default flow implementations. - The following helper functions are implemented (simplified excerpt): - <programlisting> -default_enable(struct irq_data *data) -{ - desc->irq_data.chip->irq_unmask(data); -} - -default_disable(struct irq_data *data) -{ - if (!delay_disable(data)) - desc->irq_data.chip->irq_mask(data); -} - -default_ack(struct irq_data *data) -{ - chip->irq_ack(data); -} - -default_mask_ack(struct irq_data *data) -{ - if (chip->irq_mask_ack) { - chip->irq_mask_ack(data); - } else { - chip->irq_mask(data); - chip->irq_ack(data); - } -} - -noop(struct irq_data *data)) -{ -} - - </programlisting> - </para> - </sect3> - </sect2> - <sect2 id="Default_flow_handler_implementations"> - <title>Default flow handler implementations</title> - <sect3 id="Default_Level_IRQ_flow_handler"> - <title>Default Level IRQ flow handler</title> - <para> - handle_level_irq provides a generic implementation - for level-triggered interrupts. - </para> - <para> - The following control flow is implemented (simplified excerpt): - <programlisting> -desc->irq_data.chip->irq_mask_ack(); -handle_irq_event(desc->action); -desc->irq_data.chip->irq_unmask(); - </programlisting> - </para> - </sect3> - <sect3 id="Default_FASTEOI_IRQ_flow_handler"> - <title>Default Fast EOI IRQ flow handler</title> - <para> - handle_fasteoi_irq provides a generic implementation - for interrupts, which only need an EOI at the end of - the handler. - </para> - <para> - The following control flow is implemented (simplified excerpt): - <programlisting> -handle_irq_event(desc->action); -desc->irq_data.chip->irq_eoi(); - </programlisting> - </para> - </sect3> - <sect3 id="Default_Edge_IRQ_flow_handler"> - <title>Default Edge IRQ flow handler</title> - <para> - handle_edge_irq provides a generic implementation - for edge-triggered interrupts. - </para> - <para> - The following control flow is implemented (simplified excerpt): - <programlisting> -if (desc->status & running) { - desc->irq_data.chip->irq_mask_ack(); - desc->status |= pending | masked; - return; -} -desc->irq_data.chip->irq_ack(); -desc->status |= running; -do { - if (desc->status & masked) - desc->irq_data.chip->irq_unmask(); - desc->status &= ~pending; - handle_irq_event(desc->action); -} while (status & pending); -desc->status &= ~running; - </programlisting> - </para> - </sect3> - <sect3 id="Default_simple_IRQ_flow_handler"> - <title>Default simple IRQ flow handler</title> - <para> - handle_simple_irq provides a generic implementation - for simple interrupts. - </para> - <para> - Note: The simple flow handler does not call any - handler/chip primitives. - </para> - <para> - The following control flow is implemented (simplified excerpt): - <programlisting> -handle_irq_event(desc->action); - </programlisting> - </para> - </sect3> - <sect3 id="Default_per_CPU_flow_handler"> - <title>Default per CPU flow handler</title> - <para> - handle_percpu_irq provides a generic implementation - for per CPU interrupts. - </para> - <para> - Per CPU interrupts are only available on SMP and - the handler provides a simplified version without - locking. - </para> - <para> - The following control flow is implemented (simplified excerpt): - <programlisting> -if (desc->irq_data.chip->irq_ack) - desc->irq_data.chip->irq_ack(); -handle_irq_event(desc->action); -if (desc->irq_data.chip->irq_eoi) - desc->irq_data.chip->irq_eoi(); - </programlisting> - </para> - </sect3> - <sect3 id="EOI_Edge_IRQ_flow_handler"> - <title>EOI Edge IRQ flow handler</title> - <para> - handle_edge_eoi_irq provides an abnomination of the edge - handler which is solely used to tame a badly wreckaged - irq controller on powerpc/cell. - </para> - </sect3> - <sect3 id="BAD_IRQ_flow_handler"> - <title>Bad IRQ flow handler</title> - <para> - handle_bad_irq is used for spurious interrupts which - have no real handler assigned.. - </para> - </sect3> - </sect2> - <sect2 id="Quirks_and_optimizations"> - <title>Quirks and optimizations</title> - <para> - The generic functions are intended for 'clean' architectures and chips, - which have no platform-specific IRQ handling quirks. If an architecture - needs to implement quirks on the 'flow' level then it can do so by - overriding the high-level irq-flow handler. - </para> - </sect2> - <sect2 id="Delayed_interrupt_disable"> - <title>Delayed interrupt disable</title> - <para> - This per interrupt selectable feature, which was introduced by Russell - King in the ARM interrupt implementation, does not mask an interrupt - at the hardware level when disable_irq() is called. The interrupt is - kept enabled and is masked in the flow handler when an interrupt event - happens. This prevents losing edge interrupts on hardware which does - not store an edge interrupt event while the interrupt is disabled at - the hardware level. When an interrupt arrives while the IRQ_DISABLED - flag is set, then the interrupt is masked at the hardware level and - the IRQ_PENDING bit is set. When the interrupt is re-enabled by - enable_irq() the pending bit is checked and if it is set, the - interrupt is resent either via hardware or by a software resend - mechanism. (It's necessary to enable CONFIG_HARDIRQS_SW_RESEND when - you want to use the delayed interrupt disable feature and your - hardware is not capable of retriggering an interrupt.) - The delayed interrupt disable is not configurable. - </para> - </sect2> - </sect1> - <sect1 id="Chiplevel_hardware_encapsulation"> - <title>Chip-level hardware encapsulation</title> - <para> - The chip-level hardware descriptor structure irq_chip - contains all the direct chip relevant functions, which - can be utilized by the irq flow implementations. - <itemizedlist> - <listitem><para>irq_ack()</para></listitem> - <listitem><para>irq_mask_ack() - Optional, recommended for performance</para></listitem> - <listitem><para>irq_mask()</para></listitem> - <listitem><para>irq_unmask()</para></listitem> - <listitem><para>irq_eoi() - Optional, required for EOI flow handlers</para></listitem> - <listitem><para>irq_retrigger() - Optional</para></listitem> - <listitem><para>irq_set_type() - Optional</para></listitem> - <listitem><para>irq_set_wake() - Optional</para></listitem> - </itemizedlist> - These primitives are strictly intended to mean what they say: ack means - ACK, masking means masking of an IRQ line, etc. It is up to the flow - handler(s) to use these basic units of low-level functionality. - </para> - </sect1> - </chapter> - - <chapter id="doirq"> - <title>__do_IRQ entry point</title> - <para> - The original implementation __do_IRQ() was an alternative entry - point for all types of interrupts. It no longer exists. - </para> - <para> - This handler turned out to be not suitable for all - interrupt hardware and was therefore reimplemented with split - functionality for edge/level/simple/percpu interrupts. This is not - only a functional optimization. It also shortens code paths for - interrupts. - </para> - </chapter> - - <chapter id="locking"> - <title>Locking on SMP</title> - <para> - The locking of chip registers is up to the architecture that - defines the chip primitives. The per-irq structure is - protected via desc->lock, by the generic layer. - </para> - </chapter> - - <chapter id="genericchip"> - <title>Generic interrupt chip</title> - <para> - To avoid copies of identical implementations of IRQ chips the - core provides a configurable generic interrupt chip - implementation. Developers should check carefully whether the - generic chip fits their needs before implementing the same - functionality slightly differently themselves. - </para> -!Ekernel/irq/generic-chip.c - </chapter> - - <chapter id="structs"> - <title>Structures</title> - <para> - This chapter contains the autogenerated documentation of the structures which are - used in the generic IRQ layer. - </para> -!Iinclude/linux/irq.h -!Iinclude/linux/interrupt.h - </chapter> - - <chapter id="pubfunctions"> - <title>Public Functions Provided</title> - <para> - This chapter contains the autogenerated documentation of the kernel API functions - which are exported. - </para> -!Ekernel/irq/manage.c -!Ekernel/irq/chip.c - </chapter> - - <chapter id="intfunctions"> - <title>Internal Functions Provided</title> - <para> - This chapter contains the autogenerated documentation of the internal functions. - </para> -!Ikernel/irq/irqdesc.c -!Ikernel/irq/handle.c -!Ikernel/irq/chip.c - </chapter> - - <chapter id="credits"> - <title>Credits</title> - <para> - The following people have contributed to this document: - <orderedlist> - <listitem><para>Thomas Gleixner<email>tglx@linutronix.de</email></para></listitem> - <listitem><para>Ingo Molnar<email>mingo@elte.hu</email></para></listitem> - </orderedlist> - </para> - </chapter> -</book> diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl deleted file mode 100644 index a8669330b456..000000000000 --- a/Documentation/DocBook/gpu.tmpl +++ /dev/null @@ -1,3499 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="gpuDevelopersGuide"> - <bookinfo> - <title>Linux GPU Driver Developer's Guide</title> - - <authorgroup> - <author> - <firstname>Jesse</firstname> - <surname>Barnes</surname> - <contrib>Initial version</contrib> - <affiliation> - <orgname>Intel Corporation</orgname> - <address> - <email>jesse.barnes@intel.com</email> - </address> - </affiliation> - </author> - <author> - <firstname>Laurent</firstname> - <surname>Pinchart</surname> - <contrib>Driver internals</contrib> - <affiliation> - <orgname>Ideas on board SPRL</orgname> - <address> - <email>laurent.pinchart@ideasonboard.com</email> - </address> - </affiliation> - </author> - <author> - <firstname>Daniel</firstname> - <surname>Vetter</surname> - <contrib>Contributions all over the place</contrib> - <affiliation> - <orgname>Intel Corporation</orgname> - <address> - <email>daniel.vetter@ffwll.ch</email> - </address> - </affiliation> - </author> - <author> - <firstname>Lukas</firstname> - <surname>Wunner</surname> - <contrib>vga_switcheroo documentation</contrib> - <affiliation> - <address> - <email>lukas@wunner.de</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2008-2009</year> - <year>2013-2014</year> - <holder>Intel Corporation</holder> - </copyright> - <copyright> - <year>2012</year> - <holder>Laurent Pinchart</holder> - </copyright> - <copyright> - <year>2015</year> - <holder>Lukas Wunner</holder> - </copyright> - - <legalnotice> - <para> - The contents of this file may be used under the terms of the GNU - General Public License version 2 (the "GPL") as distributed in - the kernel source COPYING file. - </para> - </legalnotice> - - <revhistory> - <!-- Put document revisions here, newest first. --> - <revision> - <revnumber>1.0</revnumber> - <date>2012-07-13</date> - <authorinitials>LP</authorinitials> - <revremark>Added extensive documentation about driver internals. - </revremark> - </revision> - <revision> - <revnumber>1.1</revnumber> - <date>2015-10-11</date> - <authorinitials>LW</authorinitials> - <revremark>Added vga_switcheroo documentation. - </revremark> - </revision> - </revhistory> - </bookinfo> - -<toc></toc> - -<part id="drmCore"> - <title>DRM Core</title> - <partintro> - <para> - This first part of the GPU Driver Developer's Guide documents core DRM - code, helper libraries for writing drivers and generic userspace - interfaces exposed by DRM drivers. - </para> - </partintro> - - <chapter id="drmIntroduction"> - <title>Introduction</title> - <para> - The Linux DRM layer contains code intended to support the needs - of complex graphics devices, usually containing programmable - pipelines well suited to 3D graphics acceleration. Graphics - drivers in the kernel may make use of DRM functions to make - tasks like memory management, interrupt handling and DMA easier, - and provide a uniform interface to applications. - </para> - <para> - A note on versions: this guide covers features found in the DRM - tree, including the TTM memory manager, output configuration and - mode setting, and the new vblank internals, in addition to all - the regular features found in current kernels. - </para> - <para> - [Insert diagram of typical DRM stack here] - </para> - <sect1> - <title>Style Guidelines</title> - <para> - For consistency this documentation uses American English. Abbreviations - are written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and so - on. To aid in reading, documentations make full use of the markup - characters kerneldoc provides: @parameter for function parameters, @member - for structure members, &structure to reference structures and - function() for functions. These all get automatically hyperlinked if - kerneldoc for the referenced objects exists. When referencing entries in - function vtables please use ->vfunc(). Note that kerneldoc does - not support referencing struct members directly, so please add a reference - to the vtable struct somewhere in the same paragraph or at least section. - </para> - <para> - Except in special situations (to separate locked from unlocked variants) - locking requirements for functions aren't documented in the kerneldoc. - Instead locking should be check at runtime using e.g. - <code>WARN_ON(!mutex_is_locked(...));</code>. Since it's much easier to - ignore documentation than runtime noise this provides more value. And on - top of that runtime checks do need to be updated when the locking rules - change, increasing the chances that they're correct. Within the - documentation the locking rules should be explained in the relevant - structures: Either in the comment for the lock explaining what it - protects, or data fields need a note about which lock protects them, or - both. - </para> - <para> - Functions which have a non-<code>void</code> return value should have a - section called "Returns" explaining the expected return values in - different cases and their meanings. Currently there's no consensus whether - that section name should be all upper-case or not, and whether it should - end in a colon or not. Go with the file-local style. Other common section - names are "Notes" with information for dangerous or tricky corner cases, - and "FIXME" where the interface could be cleaned up. - </para> - </sect1> - </chapter> - - <!-- Internals --> - - <chapter id="drmInternals"> - <title>DRM Internals</title> - <para> - This chapter documents DRM internals relevant to driver authors - and developers working to add support for the latest features to - existing drivers. - </para> - <para> - First, we go over some typical driver initialization - requirements, like setting up command buffers, creating an - initial output configuration, and initializing core services. - Subsequent sections cover core internals in more detail, - providing implementation notes and examples. - </para> - <para> - The DRM layer provides several services to graphics drivers, - many of them driven by the application interfaces it provides - through libdrm, the library that wraps most of the DRM ioctls. - These include vblank event handling, memory - management, output management, framebuffer management, command - submission & fencing, suspend/resume support, and DMA - services. - </para> - - <!-- Internals: driver init --> - - <sect1> - <title>Driver Initialization</title> - <para> - At the core of every DRM driver is a <structname>drm_driver</structname> - structure. Drivers typically statically initialize a drm_driver structure, - and then pass it to <function>drm_dev_alloc()</function> to allocate a - device instance. After the device instance is fully initialized it can be - registered (which makes it accessible from userspace) using - <function>drm_dev_register()</function>. - </para> - <para> - The <structname>drm_driver</structname> structure contains static - information that describes the driver and features it supports, and - pointers to methods that the DRM core will call to implement the DRM API. - We will first go through the <structname>drm_driver</structname> static - information fields, and will then describe individual operations in - details as they get used in later sections. - </para> - <sect2> - <title>Driver Information</title> - <sect3> - <title>Driver Features</title> - <para> - Drivers inform the DRM core about their requirements and supported - features by setting appropriate flags in the - <structfield>driver_features</structfield> field. Since those flags - influence the DRM core behaviour since registration time, most of them - must be set to registering the <structname>drm_driver</structname> - instance. - </para> - <synopsis>u32 driver_features;</synopsis> - <variablelist> - <title>Driver Feature Flags</title> - <varlistentry> - <term>DRIVER_USE_AGP</term> - <listitem><para> - Driver uses AGP interface, the DRM core will manage AGP resources. - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRIVER_REQUIRE_AGP</term> - <listitem><para> - Driver needs AGP interface to function. AGP initialization failure - will become a fatal error. - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRIVER_PCI_DMA</term> - <listitem><para> - Driver is capable of PCI DMA, mapping of PCI DMA buffers to - userspace will be enabled. Deprecated. - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRIVER_SG</term> - <listitem><para> - Driver can perform scatter/gather DMA, allocation and mapping of - scatter/gather buffers will be enabled. Deprecated. - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRIVER_HAVE_DMA</term> - <listitem><para> - Driver supports DMA, the userspace DMA API will be supported. - Deprecated. - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRIVER_HAVE_IRQ</term><term>DRIVER_IRQ_SHARED</term> - <listitem><para> - DRIVER_HAVE_IRQ indicates whether the driver has an IRQ handler - managed by the DRM Core. The core will support simple IRQ handler - installation when the flag is set. The installation process is - described in <xref linkend="drm-irq-registration"/>.</para> - <para>DRIVER_IRQ_SHARED indicates whether the device & handler - support shared IRQs (note that this is required of PCI drivers). - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRIVER_GEM</term> - <listitem><para> - Driver use the GEM memory manager. - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRIVER_MODESET</term> - <listitem><para> - Driver supports mode setting interfaces (KMS). - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRIVER_PRIME</term> - <listitem><para> - Driver implements DRM PRIME buffer sharing. - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRIVER_RENDER</term> - <listitem><para> - Driver supports dedicated render nodes. - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRIVER_ATOMIC</term> - <listitem><para> - Driver supports atomic properties. In this case the driver - must implement appropriate obj->atomic_get_property() vfuncs - for any modeset objects with driver specific properties. - </para></listitem> - </varlistentry> - </variablelist> - </sect3> - <sect3> - <title>Major, Minor and Patchlevel</title> - <synopsis>int major; -int minor; -int patchlevel;</synopsis> - <para> - The DRM core identifies driver versions by a major, minor and patch - level triplet. The information is printed to the kernel log at - initialization time and passed to userspace through the - DRM_IOCTL_VERSION ioctl. - </para> - <para> - The major and minor numbers are also used to verify the requested driver - API version passed to DRM_IOCTL_SET_VERSION. When the driver API changes - between minor versions, applications can call DRM_IOCTL_SET_VERSION to - select a specific version of the API. If the requested major isn't equal - to the driver major, or the requested minor is larger than the driver - minor, the DRM_IOCTL_SET_VERSION call will return an error. Otherwise - the driver's set_version() method will be called with the requested - version. - </para> - </sect3> - <sect3> - <title>Name, Description and Date</title> - <synopsis>char *name; -char *desc; -char *date;</synopsis> - <para> - The driver name is printed to the kernel log at initialization time, - used for IRQ registration and passed to userspace through - DRM_IOCTL_VERSION. - </para> - <para> - The driver description is a purely informative string passed to - userspace through the DRM_IOCTL_VERSION ioctl and otherwise unused by - the kernel. - </para> - <para> - The driver date, formatted as YYYYMMDD, is meant to identify the date of - the latest modification to the driver. However, as most drivers fail to - update it, its value is mostly useless. The DRM core prints it to the - kernel log at initialization time and passes it to userspace through the - DRM_IOCTL_VERSION ioctl. - </para> - </sect3> - </sect2> - <sect2> - <title>Device Instance and Driver Handling</title> -!Pdrivers/gpu/drm/drm_drv.c driver instance overview -!Edrivers/gpu/drm/drm_drv.c - </sect2> - <sect2> - <title>Driver Load</title> - <sect3 id="drm-irq-registration"> - <title>IRQ Registration</title> - <para> - The DRM core tries to facilitate IRQ handler registration and - unregistration by providing <function>drm_irq_install</function> and - <function>drm_irq_uninstall</function> functions. Those functions only - support a single interrupt per device, devices that use more than one - IRQs need to be handled manually. - </para> - <sect4> - <title>Managed IRQ Registration</title> - <para> - <function>drm_irq_install</function> starts by calling the - <methodname>irq_preinstall</methodname> driver operation. The operation - is optional and must make sure that the interrupt will not get fired by - clearing all pending interrupt flags or disabling the interrupt. - </para> - <para> - The passed-in IRQ will then be requested by a call to - <function>request_irq</function>. If the DRIVER_IRQ_SHARED driver - feature flag is set, a shared (IRQF_SHARED) IRQ handler will be - requested. - </para> - <para> - The IRQ handler function must be provided as the mandatory irq_handler - driver operation. It will get passed directly to - <function>request_irq</function> and thus has the same prototype as all - IRQ handlers. It will get called with a pointer to the DRM device as the - second argument. - </para> - <para> - Finally the function calls the optional - <methodname>irq_postinstall</methodname> driver operation. The operation - usually enables interrupts (excluding the vblank interrupt, which is - enabled separately), but drivers may choose to enable/disable interrupts - at a different time. - </para> - <para> - <function>drm_irq_uninstall</function> is similarly used to uninstall an - IRQ handler. It starts by waking up all processes waiting on a vblank - interrupt to make sure they don't hang, and then calls the optional - <methodname>irq_uninstall</methodname> driver operation. The operation - must disable all hardware interrupts. Finally the function frees the IRQ - by calling <function>free_irq</function>. - </para> - </sect4> - <sect4> - <title>Manual IRQ Registration</title> - <para> - Drivers that require multiple interrupt handlers can't use the managed - IRQ registration functions. In that case IRQs must be registered and - unregistered manually (usually with the <function>request_irq</function> - and <function>free_irq</function> functions, or their devm_* equivalent). - </para> - <para> - When manually registering IRQs, drivers must not set the DRIVER_HAVE_IRQ - driver feature flag, and must not provide the - <methodname>irq_handler</methodname> driver operation. They must set the - <structname>drm_device</structname> <structfield>irq_enabled</structfield> - field to 1 upon registration of the IRQs, and clear it to 0 after - unregistering the IRQs. - </para> - </sect4> - </sect3> - <sect3> - <title>Memory Manager Initialization</title> - <para> - Every DRM driver requires a memory manager which must be initialized at - load time. DRM currently contains two memory managers, the Translation - Table Manager (TTM) and the Graphics Execution Manager (GEM). - This document describes the use of the GEM memory manager only. See - <xref linkend="drm-memory-management"/> for details. - </para> - </sect3> - <sect3> - <title>Miscellaneous Device Configuration</title> - <para> - Another task that may be necessary for PCI devices during configuration - is mapping the video BIOS. On many devices, the VBIOS describes device - configuration, LCD panel timings (if any), and contains flags indicating - device state. Mapping the BIOS can be done using the pci_map_rom() call, - a convenience function that takes care of mapping the actual ROM, - whether it has been shadowed into memory (typically at address 0xc0000) - or exists on the PCI device in the ROM BAR. Note that after the ROM has - been mapped and any necessary information has been extracted, it should - be unmapped; on many devices, the ROM address decoder is shared with - other BARs, so leaving it mapped could cause undesired behaviour like - hangs or memory corruption. - <!--!Fdrivers/pci/rom.c pci_map_rom--> - </para> - </sect3> - </sect2> - <sect2> - <title>Bus-specific Device Registration and PCI Support</title> - <para> - A number of functions are provided to help with device registration. - The functions deal with PCI and platform devices respectively and are - only provided for historical reasons. These are all deprecated and - shouldn't be used in new drivers. Besides that there's a few - helpers for pci drivers. - </para> -!Edrivers/gpu/drm/drm_pci.c -!Edrivers/gpu/drm/drm_platform.c - </sect2> - </sect1> - - <!-- Internals: memory management --> - - <sect1 id="drm-memory-management"> - <title>Memory management</title> - <para> - Modern Linux systems require large amount of graphics memory to store - frame buffers, textures, vertices and other graphics-related data. Given - the very dynamic nature of many of that data, managing graphics memory - efficiently is thus crucial for the graphics stack and plays a central - role in the DRM infrastructure. - </para> - <para> - The DRM core includes two memory managers, namely Translation Table Maps - (TTM) and Graphics Execution Manager (GEM). TTM was the first DRM memory - manager to be developed and tried to be a one-size-fits-them all - solution. It provides a single userspace API to accommodate the need of - all hardware, supporting both Unified Memory Architecture (UMA) devices - and devices with dedicated video RAM (i.e. most discrete video cards). - This resulted in a large, complex piece of code that turned out to be - hard to use for driver development. - </para> - <para> - GEM started as an Intel-sponsored project in reaction to TTM's - complexity. Its design philosophy is completely different: instead of - providing a solution to every graphics memory-related problems, GEM - identified common code between drivers and created a support library to - share it. GEM has simpler initialization and execution requirements than - TTM, but has no video RAM management capabilities and is thus limited to - UMA devices. - </para> - <sect2> - <title>The Translation Table Manager (TTM)</title> - <para> - TTM design background and information belongs here. - </para> - <sect3> - <title>TTM initialization</title> - <warning><para>This section is outdated.</para></warning> - <para> - Drivers wishing to support TTM must fill out a drm_bo_driver - structure. The structure contains several fields with function - pointers for initializing the TTM, allocating and freeing memory, - waiting for command completion and fence synchronization, and memory - migration. See the radeon_ttm.c file for an example of usage. - </para> - <para> - The ttm_global_reference structure is made up of several fields: - </para> - <programlisting> - struct ttm_global_reference { - enum ttm_global_types global_type; - size_t size; - void *object; - int (*init) (struct ttm_global_reference *); - void (*release) (struct ttm_global_reference *); - }; - </programlisting> - <para> - There should be one global reference structure for your memory - manager as a whole, and there will be others for each object - created by the memory manager at runtime. Your global TTM should - have a type of TTM_GLOBAL_TTM_MEM. The size field for the global - object should be sizeof(struct ttm_mem_global), and the init and - release hooks should point at your driver-specific init and - release routines, which probably eventually call - ttm_mem_global_init and ttm_mem_global_release, respectively. - </para> - <para> - Once your global TTM accounting structure is set up and initialized - by calling ttm_global_item_ref() on it, - you need to create a buffer object TTM to - provide a pool for buffer object allocation by clients and the - kernel itself. The type of this object should be TTM_GLOBAL_TTM_BO, - and its size should be sizeof(struct ttm_bo_global). Again, - driver-specific init and release functions may be provided, - likely eventually calling ttm_bo_global_init() and - ttm_bo_global_release(), respectively. Also, like the previous - object, ttm_global_item_ref() is used to create an initial reference - count for the TTM, which will call your initialization function. - </para> - </sect3> - </sect2> - <sect2 id="drm-gem"> - <title>The Graphics Execution Manager (GEM)</title> - <para> - The GEM design approach has resulted in a memory manager that doesn't - provide full coverage of all (or even all common) use cases in its - userspace or kernel API. GEM exposes a set of standard memory-related - operations to userspace and a set of helper functions to drivers, and let - drivers implement hardware-specific operations with their own private API. - </para> - <para> - The GEM userspace API is described in the - <ulink url="http://lwn.net/Articles/283798/"><citetitle>GEM - the Graphics - Execution Manager</citetitle></ulink> article on LWN. While slightly - outdated, the document provides a good overview of the GEM API principles. - Buffer allocation and read and write operations, described as part of the - common GEM API, are currently implemented using driver-specific ioctls. - </para> - <para> - GEM is data-agnostic. It manages abstract buffer objects without knowing - what individual buffers contain. APIs that require knowledge of buffer - contents or purpose, such as buffer allocation or synchronization - primitives, are thus outside of the scope of GEM and must be implemented - using driver-specific ioctls. - </para> - <para> - On a fundamental level, GEM involves several operations: - <itemizedlist> - <listitem>Memory allocation and freeing</listitem> - <listitem>Command execution</listitem> - <listitem>Aperture management at command execution time</listitem> - </itemizedlist> - Buffer object allocation is relatively straightforward and largely - provided by Linux's shmem layer, which provides memory to back each - object. - </para> - <para> - Device-specific operations, such as command execution, pinning, buffer - read & write, mapping, and domain ownership transfers are left to - driver-specific ioctls. - </para> - <sect3> - <title>GEM Initialization</title> - <para> - Drivers that use GEM must set the DRIVER_GEM bit in the struct - <structname>drm_driver</structname> - <structfield>driver_features</structfield> field. The DRM core will - then automatically initialize the GEM core before calling the - <methodname>load</methodname> operation. Behind the scene, this will - create a DRM Memory Manager object which provides an address space - pool for object allocation. - </para> - <para> - In a KMS configuration, drivers need to allocate and initialize a - command ring buffer following core GEM initialization if required by - the hardware. UMA devices usually have what is called a "stolen" - memory region, which provides space for the initial framebuffer and - large, contiguous memory regions required by the device. This space is - typically not managed by GEM, and must be initialized separately into - its own DRM MM object. - </para> - </sect3> - <sect3> - <title>GEM Objects Creation</title> - <para> - GEM splits creation of GEM objects and allocation of the memory that - backs them in two distinct operations. - </para> - <para> - GEM objects are represented by an instance of struct - <structname>drm_gem_object</structname>. Drivers usually need to extend - GEM objects with private information and thus create a driver-specific - GEM object structure type that embeds an instance of struct - <structname>drm_gem_object</structname>. - </para> - <para> - To create a GEM object, a driver allocates memory for an instance of its - specific GEM object type and initializes the embedded struct - <structname>drm_gem_object</structname> with a call to - <function>drm_gem_object_init</function>. The function takes a pointer to - the DRM device, a pointer to the GEM object and the buffer object size - in bytes. - </para> - <para> - GEM uses shmem to allocate anonymous pageable memory. - <function>drm_gem_object_init</function> will create an shmfs file of - the requested size and store it into the struct - <structname>drm_gem_object</structname> <structfield>filp</structfield> - field. The memory is used as either main storage for the object when the - graphics hardware uses system memory directly or as a backing store - otherwise. - </para> - <para> - Drivers are responsible for the actual physical pages allocation by - calling <function>shmem_read_mapping_page_gfp</function> for each page. - Note that they can decide to allocate pages when initializing the GEM - object, or to delay allocation until the memory is needed (for instance - when a page fault occurs as a result of a userspace memory access or - when the driver needs to start a DMA transfer involving the memory). - </para> - <para> - Anonymous pageable memory allocation is not always desired, for instance - when the hardware requires physically contiguous system memory as is - often the case in embedded devices. Drivers can create GEM objects with - no shmfs backing (called private GEM objects) by initializing them with - a call to <function>drm_gem_private_object_init</function> instead of - <function>drm_gem_object_init</function>. Storage for private GEM - objects must be managed by drivers. - </para> - </sect3> - <sect3> - <title>GEM Objects Lifetime</title> - <para> - All GEM objects are reference-counted by the GEM core. References can be - acquired and release by <function>calling drm_gem_object_reference</function> - and <function>drm_gem_object_unreference</function> respectively. The - caller must hold the <structname>drm_device</structname> - <structfield>struct_mutex</structfield> lock when calling - <function>drm_gem_object_reference</function>. As a convenience, GEM - provides <function>drm_gem_object_unreference_unlocked</function> - functions that can be called without holding the lock. - </para> - <para> - When the last reference to a GEM object is released the GEM core calls - the <structname>drm_driver</structname> - <methodname>gem_free_object</methodname> operation. That operation is - mandatory for GEM-enabled drivers and must free the GEM object and all - associated resources. - </para> - <para> - <synopsis>void (*gem_free_object) (struct drm_gem_object *obj);</synopsis> - Drivers are responsible for freeing all GEM object resources. This includes - the resources created by the GEM core, which need to be released with - <function>drm_gem_object_release</function>. - </para> - </sect3> - <sect3> - <title>GEM Objects Naming</title> - <para> - Communication between userspace and the kernel refers to GEM objects - using local handles, global names or, more recently, file descriptors. - All of those are 32-bit integer values; the usual Linux kernel limits - apply to the file descriptors. - </para> - <para> - GEM handles are local to a DRM file. Applications get a handle to a GEM - object through a driver-specific ioctl, and can use that handle to refer - to the GEM object in other standard or driver-specific ioctls. Closing a - DRM file handle frees all its GEM handles and dereferences the - associated GEM objects. - </para> - <para> - To create a handle for a GEM object drivers call - <function>drm_gem_handle_create</function>. The function takes a pointer - to the DRM file and the GEM object and returns a locally unique handle. - When the handle is no longer needed drivers delete it with a call to - <function>drm_gem_handle_delete</function>. Finally the GEM object - associated with a handle can be retrieved by a call to - <function>drm_gem_object_lookup</function>. - </para> - <para> - Handles don't take ownership of GEM objects, they only take a reference - to the object that will be dropped when the handle is destroyed. To - avoid leaking GEM objects, drivers must make sure they drop the - reference(s) they own (such as the initial reference taken at object - creation time) as appropriate, without any special consideration for the - handle. For example, in the particular case of combined GEM object and - handle creation in the implementation of the - <methodname>dumb_create</methodname> operation, drivers must drop the - initial reference to the GEM object before returning the handle. - </para> - <para> - GEM names are similar in purpose to handles but are not local to DRM - files. They can be passed between processes to reference a GEM object - globally. Names can't be used directly to refer to objects in the DRM - API, applications must convert handles to names and names to handles - using the DRM_IOCTL_GEM_FLINK and DRM_IOCTL_GEM_OPEN ioctls - respectively. The conversion is handled by the DRM core without any - driver-specific support. - </para> - <para> - GEM also supports buffer sharing with dma-buf file descriptors through - PRIME. GEM-based drivers must use the provided helpers functions to - implement the exporting and importing correctly. See <xref linkend="drm-prime-support" />. - Since sharing file descriptors is inherently more secure than the - easily guessable and global GEM names it is the preferred buffer - sharing mechanism. Sharing buffers through GEM names is only supported - for legacy userspace. Furthermore PRIME also allows cross-device - buffer sharing since it is based on dma-bufs. - </para> - </sect3> - <sect3 id="drm-gem-objects-mapping"> - <title>GEM Objects Mapping</title> - <para> - Because mapping operations are fairly heavyweight GEM favours - read/write-like access to buffers, implemented through driver-specific - ioctls, over mapping buffers to userspace. However, when random access - to the buffer is needed (to perform software rendering for instance), - direct access to the object can be more efficient. - </para> - <para> - The mmap system call can't be used directly to map GEM objects, as they - don't have their own file handle. Two alternative methods currently - co-exist to map GEM objects to userspace. The first method uses a - driver-specific ioctl to perform the mapping operation, calling - <function>do_mmap</function> under the hood. This is often considered - dubious, seems to be discouraged for new GEM-enabled drivers, and will - thus not be described here. - </para> - <para> - The second method uses the mmap system call on the DRM file handle. - <synopsis>void *mmap(void *addr, size_t length, int prot, int flags, int fd, - off_t offset);</synopsis> - DRM identifies the GEM object to be mapped by a fake offset passed - through the mmap offset argument. Prior to being mapped, a GEM object - must thus be associated with a fake offset. To do so, drivers must call - <function>drm_gem_create_mmap_offset</function> on the object. - </para> - <para> - Once allocated, the fake offset value - must be passed to the application in a driver-specific way and can then - be used as the mmap offset argument. - </para> - <para> - The GEM core provides a helper method <function>drm_gem_mmap</function> - to handle object mapping. The method can be set directly as the mmap - file operation handler. It will look up the GEM object based on the - offset value and set the VMA operations to the - <structname>drm_driver</structname> <structfield>gem_vm_ops</structfield> - field. Note that <function>drm_gem_mmap</function> doesn't map memory to - userspace, but relies on the driver-provided fault handler to map pages - individually. - </para> - <para> - To use <function>drm_gem_mmap</function>, drivers must fill the struct - <structname>drm_driver</structname> <structfield>gem_vm_ops</structfield> - field with a pointer to VM operations. - </para> - <para> - <synopsis>struct vm_operations_struct *gem_vm_ops - - struct vm_operations_struct { - void (*open)(struct vm_area_struct * area); - void (*close)(struct vm_area_struct * area); - int (*fault)(struct vm_area_struct *vma, struct vm_fault *vmf); - };</synopsis> - </para> - <para> - The <methodname>open</methodname> and <methodname>close</methodname> - operations must update the GEM object reference count. Drivers can use - the <function>drm_gem_vm_open</function> and - <function>drm_gem_vm_close</function> helper functions directly as open - and close handlers. - </para> - <para> - The fault operation handler is responsible for mapping individual pages - to userspace when a page fault occurs. Depending on the memory - allocation scheme, drivers can allocate pages at fault time, or can - decide to allocate memory for the GEM object at the time the object is - created. - </para> - <para> - Drivers that want to map the GEM object upfront instead of handling page - faults can implement their own mmap file operation handler. - </para> - </sect3> - <sect3> - <title>Memory Coherency</title> - <para> - When mapped to the device or used in a command buffer, backing pages - for an object are flushed to memory and marked write combined so as to - be coherent with the GPU. Likewise, if the CPU accesses an object - after the GPU has finished rendering to the object, then the object - must be made coherent with the CPU's view of memory, usually involving - GPU cache flushing of various kinds. This core CPU<->GPU - coherency management is provided by a device-specific ioctl, which - evaluates an object's current domain and performs any necessary - flushing or synchronization to put the object into the desired - coherency domain (note that the object may be busy, i.e. an active - render target; in that case, setting the domain blocks the client and - waits for rendering to complete before performing any necessary - flushing operations). - </para> - </sect3> - <sect3> - <title>Command Execution</title> - <para> - Perhaps the most important GEM function for GPU devices is providing a - command execution interface to clients. Client programs construct - command buffers containing references to previously allocated memory - objects, and then submit them to GEM. At that point, GEM takes care to - bind all the objects into the GTT, execute the buffer, and provide - necessary synchronization between clients accessing the same buffers. - This often involves evicting some objects from the GTT and re-binding - others (a fairly expensive operation), and providing relocation - support which hides fixed GTT offsets from clients. Clients must take - care not to submit command buffers that reference more objects than - can fit in the GTT; otherwise, GEM will reject them and no rendering - will occur. Similarly, if several objects in the buffer require fence - registers to be allocated for correct rendering (e.g. 2D blits on - pre-965 chips), care must be taken not to require more fence registers - than are available to the client. Such resource management should be - abstracted from the client in libdrm. - </para> - </sect3> - </sect2> - <sect2> - <title>GEM Function Reference</title> -!Edrivers/gpu/drm/drm_gem.c -!Iinclude/drm/drm_gem.h - </sect2> - <sect2> - <title>VMA Offset Manager</title> -!Pdrivers/gpu/drm/drm_vma_manager.c vma offset manager -!Edrivers/gpu/drm/drm_vma_manager.c -!Iinclude/drm/drm_vma_manager.h - </sect2> - <sect2 id="drm-prime-support"> - <title>PRIME Buffer Sharing</title> - <para> - PRIME is the cross device buffer sharing framework in drm, originally - created for the OPTIMUS range of multi-gpu platforms. To userspace - PRIME buffers are dma-buf based file descriptors. - </para> - <sect3> - <title>Overview and Driver Interface</title> - <para> - Similar to GEM global names, PRIME file descriptors are - also used to share buffer objects across processes. They offer - additional security: as file descriptors must be explicitly sent over - UNIX domain sockets to be shared between applications, they can't be - guessed like the globally unique GEM names. - </para> - <para> - Drivers that support the PRIME - API must set the DRIVER_PRIME bit in the struct - <structname>drm_driver</structname> - <structfield>driver_features</structfield> field, and implement the - <methodname>prime_handle_to_fd</methodname> and - <methodname>prime_fd_to_handle</methodname> operations. - </para> - <para> - <synopsis>int (*prime_handle_to_fd)(struct drm_device *dev, - struct drm_file *file_priv, uint32_t handle, - uint32_t flags, int *prime_fd); -int (*prime_fd_to_handle)(struct drm_device *dev, - struct drm_file *file_priv, int prime_fd, - uint32_t *handle);</synopsis> - Those two operations convert a handle to a PRIME file descriptor and - vice versa. Drivers must use the kernel dma-buf buffer sharing framework - to manage the PRIME file descriptors. Similar to the mode setting - API PRIME is agnostic to the underlying buffer object manager, as - long as handles are 32bit unsigned integers. - </para> - <para> - While non-GEM drivers must implement the operations themselves, GEM - drivers must use the <function>drm_gem_prime_handle_to_fd</function> - and <function>drm_gem_prime_fd_to_handle</function> helper functions. - Those helpers rely on the driver - <methodname>gem_prime_export</methodname> and - <methodname>gem_prime_import</methodname> operations to create a dma-buf - instance from a GEM object (dma-buf exporter role) and to create a GEM - object from a dma-buf instance (dma-buf importer role). - </para> - <para> - <synopsis>struct dma_buf * (*gem_prime_export)(struct drm_device *dev, - struct drm_gem_object *obj, - int flags); -struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev, - struct dma_buf *dma_buf);</synopsis> - These two operations are mandatory for GEM drivers that support - PRIME. - </para> - </sect3> - <sect3> - <title>PRIME Helper Functions</title> -!Pdrivers/gpu/drm/drm_prime.c PRIME Helpers - </sect3> - </sect2> - <sect2> - <title>PRIME Function References</title> -!Edrivers/gpu/drm/drm_prime.c - </sect2> - <sect2> - <title>DRM MM Range Allocator</title> - <sect3> - <title>Overview</title> -!Pdrivers/gpu/drm/drm_mm.c Overview - </sect3> - <sect3> - <title>LRU Scan/Eviction Support</title> -!Pdrivers/gpu/drm/drm_mm.c lru scan roaster - </sect3> - </sect2> - <sect2> - <title>DRM MM Range Allocator Function References</title> -!Edrivers/gpu/drm/drm_mm.c -!Iinclude/drm/drm_mm.h - </sect2> - <sect2> - <title>CMA Helper Functions Reference</title> -!Pdrivers/gpu/drm/drm_gem_cma_helper.c cma helpers -!Edrivers/gpu/drm/drm_gem_cma_helper.c -!Iinclude/drm/drm_gem_cma_helper.h - </sect2> - </sect1> - - <!-- Internals: mode setting --> - - <sect1 id="drm-mode-setting"> - <title>Mode Setting</title> - <para> - Drivers must initialize the mode setting core by calling - <function>drm_mode_config_init</function> on the DRM device. The function - initializes the <structname>drm_device</structname> - <structfield>mode_config</structfield> field and never fails. Once done, - mode configuration must be setup by initializing the following fields. - </para> - <itemizedlist> - <listitem> - <synopsis>int min_width, min_height; -int max_width, max_height;</synopsis> - <para> - Minimum and maximum width and height of the frame buffers in pixel - units. - </para> - </listitem> - <listitem> - <synopsis>struct drm_mode_config_funcs *funcs;</synopsis> - <para>Mode setting functions.</para> - </listitem> - </itemizedlist> - <sect2> - <title>Display Modes Function Reference</title> -!Iinclude/drm/drm_modes.h -!Edrivers/gpu/drm/drm_modes.c - </sect2> - <sect2> - <title>Atomic Mode Setting Function Reference</title> -!Edrivers/gpu/drm/drm_atomic.c -!Idrivers/gpu/drm/drm_atomic.c - </sect2> - <sect2> - <title>Frame Buffer Abstraction</title> - <para> - Frame buffers are abstract memory objects that provide a source of - pixels to scanout to a CRTC. Applications explicitly request the - creation of frame buffers through the DRM_IOCTL_MODE_ADDFB(2) ioctls and - receive an opaque handle that can be passed to the KMS CRTC control, - plane configuration and page flip functions. - </para> - <para> - Frame buffers rely on the underneath memory manager for low-level memory - operations. When creating a frame buffer applications pass a memory - handle (or a list of memory handles for multi-planar formats) through - the <parameter>drm_mode_fb_cmd2</parameter> argument. For drivers using - GEM as their userspace buffer management interface this would be a GEM - handle. Drivers are however free to use their own backing storage object - handles, e.g. vmwgfx directly exposes special TTM handles to userspace - and so expects TTM handles in the create ioctl and not GEM handles. - </para> - <para> - The lifetime of a drm framebuffer is controlled with a reference count, - drivers can grab additional references with - <function>drm_framebuffer_reference</function>and drop them - again with <function>drm_framebuffer_unreference</function>. For - driver-private framebuffers for which the last reference is never - dropped (e.g. for the fbdev framebuffer when the struct - <structname>drm_framebuffer</structname> is embedded into the fbdev - helper struct) drivers can manually clean up a framebuffer at module - unload time with - <function>drm_framebuffer_unregister_private</function>. - </para> - </sect2> - <sect2> - <title>Dumb Buffer Objects</title> - <para> - The KMS API doesn't standardize backing storage object creation and - leaves it to driver-specific ioctls. Furthermore actually creating a - buffer object even for GEM-based drivers is done through a - driver-specific ioctl - GEM only has a common userspace interface for - sharing and destroying objects. While not an issue for full-fledged - graphics stacks that include device-specific userspace components (in - libdrm for instance), this limit makes DRM-based early boot graphics - unnecessarily complex. - </para> - <para> - Dumb objects partly alleviate the problem by providing a standard - API to create dumb buffers suitable for scanout, which can then be used - to create KMS frame buffers. - </para> - <para> - To support dumb objects drivers must implement the - <methodname>dumb_create</methodname>, - <methodname>dumb_destroy</methodname> and - <methodname>dumb_map_offset</methodname> operations. - </para> - <itemizedlist> - <listitem> - <synopsis>int (*dumb_create)(struct drm_file *file_priv, struct drm_device *dev, - struct drm_mode_create_dumb *args);</synopsis> - <para> - The <methodname>dumb_create</methodname> operation creates a driver - object (GEM or TTM handle) suitable for scanout based on the - width, height and depth from the struct - <structname>drm_mode_create_dumb</structname> argument. It fills the - argument's <structfield>handle</structfield>, - <structfield>pitch</structfield> and <structfield>size</structfield> - fields with a handle for the newly created object and its line - pitch and size in bytes. - </para> - </listitem> - <listitem> - <synopsis>int (*dumb_destroy)(struct drm_file *file_priv, struct drm_device *dev, - uint32_t handle);</synopsis> - <para> - The <methodname>dumb_destroy</methodname> operation destroys a dumb - object created by <methodname>dumb_create</methodname>. - </para> - </listitem> - <listitem> - <synopsis>int (*dumb_map_offset)(struct drm_file *file_priv, struct drm_device *dev, - uint32_t handle, uint64_t *offset);</synopsis> - <para> - The <methodname>dumb_map_offset</methodname> operation associates an - mmap fake offset with the object given by the handle and returns - it. Drivers must use the - <function>drm_gem_create_mmap_offset</function> function to - associate the fake offset as described in - <xref linkend="drm-gem-objects-mapping"/>. - </para> - </listitem> - </itemizedlist> - <para> - Note that dumb objects may not be used for gpu acceleration, as has been - attempted on some ARM embedded platforms. Such drivers really must have - a hardware-specific ioctl to allocate suitable buffer objects. - </para> - </sect2> - <sect2> - <title>Output Polling</title> - <synopsis>void (*output_poll_changed)(struct drm_device *dev);</synopsis> - <para> - This operation notifies the driver that the status of one or more - connectors has changed. Drivers that use the fb helper can just call the - <function>drm_fb_helper_hotplug_event</function> function to handle this - operation. - </para> - </sect2> - <sect2> - <title>Locking</title> - <para> - Beside some lookup structures with their own locking (which is hidden - behind the interface functions) most of the modeset state is protected - by the <code>dev-<mode_config.lock</code> mutex and additionally - per-crtc locks to allow cursor updates, pageflips and similar operations - to occur concurrently with background tasks like output detection. - Operations which cross domains like a full modeset always grab all - locks. Drivers there need to protect resources shared between crtcs with - additional locking. They also need to be careful to always grab the - relevant crtc locks if a modset functions touches crtc state, e.g. for - load detection (which does only grab the <code>mode_config.lock</code> - to allow concurrent screen updates on live crtcs). - </para> - </sect2> - </sect1> - - <!-- Internals: kms initialization and cleanup --> - - <sect1 id="drm-kms-init"> - <title>KMS Initialization and Cleanup</title> - <para> - A KMS device is abstracted and exposed as a set of planes, CRTCs, encoders - and connectors. KMS drivers must thus create and initialize all those - objects at load time after initializing mode setting. - </para> - <sect2> - <title>CRTCs (struct <structname>drm_crtc</structname>)</title> - <para> - A CRTC is an abstraction representing a part of the chip that contains a - pointer to a scanout buffer. Therefore, the number of CRTCs available - determines how many independent scanout buffers can be active at any - given time. The CRTC structure contains several fields to support this: - a pointer to some video memory (abstracted as a frame buffer object), a - display mode, and an (x, y) offset into the video memory to support - panning or configurations where one piece of video memory spans multiple - CRTCs. - </para> - <sect3> - <title>CRTC Initialization</title> - <para> - A KMS device must create and register at least one struct - <structname>drm_crtc</structname> instance. The instance is allocated - and zeroed by the driver, possibly as part of a larger structure, and - registered with a call to <function>drm_crtc_init</function> with a - pointer to CRTC functions. - </para> - </sect3> - </sect2> - <sect2> - <title>Planes (struct <structname>drm_plane</structname>)</title> - <para> - A plane represents an image source that can be blended with or overlayed - on top of a CRTC during the scanout process. Planes are associated with - a frame buffer to crop a portion of the image memory (source) and - optionally scale it to a destination size. The result is then blended - with or overlayed on top of a CRTC. - </para> - <para> - The DRM core recognizes three types of planes: - <itemizedlist> - <listitem> - DRM_PLANE_TYPE_PRIMARY represents a "main" plane for a CRTC. Primary - planes are the planes operated upon by CRTC modesetting and flipping - operations described in the page_flip hook in <structname>drm_crtc_funcs</structname>. - </listitem> - <listitem> - DRM_PLANE_TYPE_CURSOR represents a "cursor" plane for a CRTC. Cursor - planes are the planes operated upon by the DRM_IOCTL_MODE_CURSOR and - DRM_IOCTL_MODE_CURSOR2 ioctls. - </listitem> - <listitem> - DRM_PLANE_TYPE_OVERLAY represents all non-primary, non-cursor planes. - Some drivers refer to these types of planes as "sprites" internally. - </listitem> - </itemizedlist> - For compatibility with legacy userspace, only overlay planes are made - available to userspace by default. Userspace clients may set the - DRM_CLIENT_CAP_UNIVERSAL_PLANES client capability bit to indicate that - they wish to receive a universal plane list containing all plane types. - </para> - <sect3> - <title>Plane Initialization</title> - <para> - To create a plane, a KMS drivers allocates and - zeroes an instances of struct <structname>drm_plane</structname> - (possibly as part of a larger structure) and registers it with a call - to <function>drm_universal_plane_init</function>. The function takes a bitmask - of the CRTCs that can be associated with the plane, a pointer to the - plane functions, a list of format supported formats, and the type of - plane (primary, cursor, or overlay) being initialized. - </para> - <para> - Cursor and overlay planes are optional. All drivers should provide - one primary plane per CRTC (although this requirement may change in - the future); drivers that do not wish to provide special handling for - primary planes may make use of the helper functions described in - <xref linkend="drm-kms-planehelpers"/> to create and register a - primary plane with standard capabilities. - </para> - </sect3> - </sect2> - <sect2> - <title>Encoders (struct <structname>drm_encoder</structname>)</title> - <para> - An encoder takes pixel data from a CRTC and converts it to a format - suitable for any attached connectors. On some devices, it may be - possible to have a CRTC send data to more than one encoder. In that - case, both encoders would receive data from the same scanout buffer, - resulting in a "cloned" display configuration across the connectors - attached to each encoder. - </para> - <sect3> - <title>Encoder Initialization</title> - <para> - As for CRTCs, a KMS driver must create, initialize and register at - least one struct <structname>drm_encoder</structname> instance. The - instance is allocated and zeroed by the driver, possibly as part of a - larger structure. - </para> - <para> - Drivers must initialize the struct <structname>drm_encoder</structname> - <structfield>possible_crtcs</structfield> and - <structfield>possible_clones</structfield> fields before registering the - encoder. Both fields are bitmasks of respectively the CRTCs that the - encoder can be connected to, and sibling encoders candidate for cloning. - </para> - <para> - After being initialized, the encoder must be registered with a call to - <function>drm_encoder_init</function>. The function takes a pointer to - the encoder functions and an encoder type. Supported types are - <itemizedlist> - <listitem> - DRM_MODE_ENCODER_DAC for VGA and analog on DVI-I/DVI-A - </listitem> - <listitem> - DRM_MODE_ENCODER_TMDS for DVI, HDMI and (embedded) DisplayPort - </listitem> - <listitem> - DRM_MODE_ENCODER_LVDS for display panels - </listitem> - <listitem> - DRM_MODE_ENCODER_TVDAC for TV output (Composite, S-Video, Component, - SCART) - </listitem> - <listitem> - DRM_MODE_ENCODER_VIRTUAL for virtual machine displays - </listitem> - </itemizedlist> - </para> - <para> - Encoders must be attached to a CRTC to be used. DRM drivers leave - encoders unattached at initialization time. Applications (or the fbdev - compatibility layer when implemented) are responsible for attaching the - encoders they want to use to a CRTC. - </para> - </sect3> - </sect2> - <sect2> - <title>Connectors (struct <structname>drm_connector</structname>)</title> - <para> - A connector is the final destination for pixel data on a device, and - usually connects directly to an external display device like a monitor - or laptop panel. A connector can only be attached to one encoder at a - time. The connector is also the structure where information about the - attached display is kept, so it contains fields for display data, EDID - data, DPMS & connection status, and information about modes - supported on the attached displays. - </para> - <sect3> - <title>Connector Initialization</title> - <para> - Finally a KMS driver must create, initialize, register and attach at - least one struct <structname>drm_connector</structname> instance. The - instance is created as other KMS objects and initialized by setting the - following fields. - </para> - <variablelist> - <varlistentry> - <term><structfield>interlace_allowed</structfield></term> - <listitem><para> - Whether the connector can handle interlaced modes. - </para></listitem> - </varlistentry> - <varlistentry> - <term><structfield>doublescan_allowed</structfield></term> - <listitem><para> - Whether the connector can handle doublescan. - </para></listitem> - </varlistentry> - <varlistentry> - <term><structfield>display_info - </structfield></term> - <listitem><para> - Display information is filled from EDID information when a display - is detected. For non hot-pluggable displays such as flat panels in - embedded systems, the driver should initialize the - <structfield>display_info</structfield>.<structfield>width_mm</structfield> - and - <structfield>display_info</structfield>.<structfield>height_mm</structfield> - fields with the physical size of the display. - </para></listitem> - </varlistentry> - <varlistentry> - <term id="drm-kms-connector-polled"><structfield>polled</structfield></term> - <listitem><para> - Connector polling mode, a combination of - <variablelist> - <varlistentry> - <term>DRM_CONNECTOR_POLL_HPD</term> - <listitem><para> - The connector generates hotplug events and doesn't need to be - periodically polled. The CONNECT and DISCONNECT flags must not - be set together with the HPD flag. - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_CONNECTOR_POLL_CONNECT</term> - <listitem><para> - Periodically poll the connector for connection. - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_CONNECTOR_POLL_DISCONNECT</term> - <listitem><para> - Periodically poll the connector for disconnection. - </para></listitem> - </varlistentry> - </variablelist> - Set to 0 for connectors that don't support connection status - discovery. - </para></listitem> - </varlistentry> - </variablelist> - <para> - The connector is then registered with a call to - <function>drm_connector_init</function> with a pointer to the connector - functions and a connector type, and exposed through sysfs with a call to - <function>drm_connector_register</function>. - </para> - <para> - Supported connector types are - <itemizedlist> - <listitem>DRM_MODE_CONNECTOR_VGA</listitem> - <listitem>DRM_MODE_CONNECTOR_DVII</listitem> - <listitem>DRM_MODE_CONNECTOR_DVID</listitem> - <listitem>DRM_MODE_CONNECTOR_DVIA</listitem> - <listitem>DRM_MODE_CONNECTOR_Composite</listitem> - <listitem>DRM_MODE_CONNECTOR_SVIDEO</listitem> - <listitem>DRM_MODE_CONNECTOR_LVDS</listitem> - <listitem>DRM_MODE_CONNECTOR_Component</listitem> - <listitem>DRM_MODE_CONNECTOR_9PinDIN</listitem> - <listitem>DRM_MODE_CONNECTOR_DisplayPort</listitem> - <listitem>DRM_MODE_CONNECTOR_HDMIA</listitem> - <listitem>DRM_MODE_CONNECTOR_HDMIB</listitem> - <listitem>DRM_MODE_CONNECTOR_TV</listitem> - <listitem>DRM_MODE_CONNECTOR_eDP</listitem> - <listitem>DRM_MODE_CONNECTOR_VIRTUAL</listitem> - </itemizedlist> - </para> - <para> - Connectors must be attached to an encoder to be used. For devices that - map connectors to encoders 1:1, the connector should be attached at - initialization time with a call to - <function>drm_mode_connector_attach_encoder</function>. The driver must - also set the <structname>drm_connector</structname> - <structfield>encoder</structfield> field to point to the attached - encoder. - </para> - <para> - Finally, drivers must initialize the connectors state change detection - with a call to <function>drm_kms_helper_poll_init</function>. If at - least one connector is pollable but can't generate hotplug interrupts - (indicated by the DRM_CONNECTOR_POLL_CONNECT and - DRM_CONNECTOR_POLL_DISCONNECT connector flags), a delayed work will - automatically be queued to periodically poll for changes. Connectors - that can generate hotplug interrupts must be marked with the - DRM_CONNECTOR_POLL_HPD flag instead, and their interrupt handler must - call <function>drm_helper_hpd_irq_event</function>. The function will - queue a delayed work to check the state of all connectors, but no - periodic polling will be done. - </para> - </sect3> - <sect3> - <title>Connector Operations</title> - <note><para> - Unless otherwise state, all operations are mandatory. - </para></note> - <sect4> - <title>DPMS</title> - <synopsis>void (*dpms)(struct drm_connector *connector, int mode);</synopsis> - <para> - The DPMS operation sets the power state of a connector. The mode - argument is one of - <itemizedlist> - <listitem><para>DRM_MODE_DPMS_ON</para></listitem> - <listitem><para>DRM_MODE_DPMS_STANDBY</para></listitem> - <listitem><para>DRM_MODE_DPMS_SUSPEND</para></listitem> - <listitem><para>DRM_MODE_DPMS_OFF</para></listitem> - </itemizedlist> - </para> - <para> - In all but DPMS_ON mode the encoder to which the connector is attached - should put the display in low-power mode by driving its signals - appropriately. If more than one connector is attached to the encoder - care should be taken not to change the power state of other displays as - a side effect. Low-power mode should be propagated to the encoders and - CRTCs when all related connectors are put in low-power mode. - </para> - </sect4> - <sect4> - <title>Modes</title> - <synopsis>int (*fill_modes)(struct drm_connector *connector, uint32_t max_width, - uint32_t max_height);</synopsis> - <para> - Fill the mode list with all supported modes for the connector. If the - <parameter>max_width</parameter> and <parameter>max_height</parameter> - arguments are non-zero, the implementation must ignore all modes wider - than <parameter>max_width</parameter> or higher than - <parameter>max_height</parameter>. - </para> - <para> - The connector must also fill in this operation its - <structfield>display_info</structfield> - <structfield>width_mm</structfield> and - <structfield>height_mm</structfield> fields with the connected display - physical size in millimeters. The fields should be set to 0 if the value - isn't known or is not applicable (for instance for projector devices). - </para> - </sect4> - <sect4> - <title>Connection Status</title> - <para> - The connection status is updated through polling or hotplug events when - supported (see <xref linkend="drm-kms-connector-polled"/>). The status - value is reported to userspace through ioctls and must not be used - inside the driver, as it only gets initialized by a call to - <function>drm_mode_getconnector</function> from userspace. - </para> - <synopsis>enum drm_connector_status (*detect)(struct drm_connector *connector, - bool force);</synopsis> - <para> - Check to see if anything is attached to the connector. The - <parameter>force</parameter> parameter is set to false whilst polling or - to true when checking the connector due to user request. - <parameter>force</parameter> can be used by the driver to avoid - expensive, destructive operations during automated probing. - </para> - <para> - Return connector_status_connected if something is connected to the - connector, connector_status_disconnected if nothing is connected and - connector_status_unknown if the connection state isn't known. - </para> - <para> - Drivers should only return connector_status_connected if the connection - status has really been probed as connected. Connectors that can't detect - the connection status, or failed connection status probes, should return - connector_status_unknown. - </para> - </sect4> - </sect3> - </sect2> - <sect2> - <title>Cleanup</title> - <para> - The DRM core manages its objects' lifetime. When an object is not needed - anymore the core calls its destroy function, which must clean up and - free every resource allocated for the object. Every - <function>drm_*_init</function> call must be matched with a - corresponding <function>drm_*_cleanup</function> call to cleanup CRTCs - (<function>drm_crtc_cleanup</function>), planes - (<function>drm_plane_cleanup</function>), encoders - (<function>drm_encoder_cleanup</function>) and connectors - (<function>drm_connector_cleanup</function>). Furthermore, connectors - that have been added to sysfs must be removed by a call to - <function>drm_connector_unregister</function> before calling - <function>drm_connector_cleanup</function>. - </para> - <para> - Connectors state change detection must be cleanup up with a call to - <function>drm_kms_helper_poll_fini</function>. - </para> - </sect2> - <sect2> - <title>Output discovery and initialization example</title> - <programlisting><![CDATA[ -void intel_crt_init(struct drm_device *dev) -{ - struct drm_connector *connector; - struct intel_output *intel_output; - - intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL); - if (!intel_output) - return; - - connector = &intel_output->base; - drm_connector_init(dev, &intel_output->base, - &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA); - - drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs, - DRM_MODE_ENCODER_DAC); - - drm_mode_connector_attach_encoder(&intel_output->base, - &intel_output->enc); - - /* Set up the DDC bus. */ - intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A"); - if (!intel_output->ddc_bus) { - dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration " - "failed.\n"); - return; - } - - intel_output->type = INTEL_OUTPUT_ANALOG; - connector->interlace_allowed = 0; - connector->doublescan_allowed = 0; - - drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs); - drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs); - - drm_connector_register(connector); -}]]></programlisting> - <para> - In the example above (taken from the i915 driver), a CRTC, connector and - encoder combination is created. A device-specific i2c bus is also - created for fetching EDID data and performing monitor detection. Once - the process is complete, the new connector is registered with sysfs to - make its properties available to applications. - </para> - </sect2> - <sect2> - <title>KMS API Functions</title> -!Edrivers/gpu/drm/drm_crtc.c - </sect2> - <sect2> - <title>KMS Data Structures</title> -!Iinclude/drm/drm_crtc.h - </sect2> - <sect2> - <title>KMS Locking</title> -!Pdrivers/gpu/drm/drm_modeset_lock.c kms locking -!Iinclude/drm/drm_modeset_lock.h -!Edrivers/gpu/drm/drm_modeset_lock.c - </sect2> - </sect1> - - <!-- Internals: kms helper functions --> - - <sect1> - <title>Mode Setting Helper Functions</title> - <para> - The plane, CRTC, encoder and connector functions provided by the drivers - implement the DRM API. They're called by the DRM core and ioctl handlers - to handle device state changes and configuration request. As implementing - those functions often requires logic not specific to drivers, mid-layer - helper functions are available to avoid duplicating boilerplate code. - </para> - <para> - The DRM core contains one mid-layer implementation. The mid-layer provides - implementations of several plane, CRTC, encoder and connector functions - (called from the top of the mid-layer) that pre-process requests and call - lower-level functions provided by the driver (at the bottom of the - mid-layer). For instance, the - <function>drm_crtc_helper_set_config</function> function can be used to - fill the struct <structname>drm_crtc_funcs</structname> - <structfield>set_config</structfield> field. When called, it will split - the <methodname>set_config</methodname> operation in smaller, simpler - operations and call the driver to handle them. - </para> - <para> - To use the mid-layer, drivers call <function>drm_crtc_helper_add</function>, - <function>drm_encoder_helper_add</function> and - <function>drm_connector_helper_add</function> functions to install their - mid-layer bottom operations handlers, and fill the - <structname>drm_crtc_funcs</structname>, - <structname>drm_encoder_funcs</structname> and - <structname>drm_connector_funcs</structname> structures with pointers to - the mid-layer top API functions. Installing the mid-layer bottom operation - handlers is best done right after registering the corresponding KMS object. - </para> - <para> - The mid-layer is not split between CRTC, encoder and connector operations. - To use it, a driver must provide bottom functions for all of the three KMS - entities. - </para> - <sect2> - <title>Atomic Modeset Helper Functions Reference</title> - <sect3> - <title>Overview</title> -!Pdrivers/gpu/drm/drm_atomic_helper.c overview - </sect3> - <sect3> - <title>Implementing Asynchronous Atomic Commit</title> -!Pdrivers/gpu/drm/drm_atomic_helper.c implementing async commit - </sect3> - <sect3> - <title>Atomic State Reset and Initialization</title> -!Pdrivers/gpu/drm/drm_atomic_helper.c atomic state reset and initialization - </sect3> -!Iinclude/drm/drm_atomic_helper.h -!Edrivers/gpu/drm/drm_atomic_helper.c - </sect2> - <sect2> - <title>Modeset Helper Reference for Common Vtables</title> -!Iinclude/drm/drm_modeset_helper_vtables.h -!Pinclude/drm/drm_modeset_helper_vtables.h overview - </sect2> - <sect2> - <title>Legacy CRTC/Modeset Helper Functions Reference</title> -!Edrivers/gpu/drm/drm_crtc_helper.c -!Pdrivers/gpu/drm/drm_crtc_helper.c overview - </sect2> - <sect2> - <title>Output Probing Helper Functions Reference</title> -!Pdrivers/gpu/drm/drm_probe_helper.c output probing helper overview -!Edrivers/gpu/drm/drm_probe_helper.c - </sect2> - <sect2> - <title>fbdev Helper Functions Reference</title> -!Pdrivers/gpu/drm/drm_fb_helper.c fbdev helpers -!Edrivers/gpu/drm/drm_fb_helper.c -!Iinclude/drm/drm_fb_helper.h - </sect2> - <sect2> - <title>Display Port Helper Functions Reference</title> -!Pdrivers/gpu/drm/drm_dp_helper.c dp helpers -!Iinclude/drm/drm_dp_helper.h -!Edrivers/gpu/drm/drm_dp_helper.c - </sect2> - <sect2> - <title>Display Port MST Helper Functions Reference</title> -!Pdrivers/gpu/drm/drm_dp_mst_topology.c dp mst helper -!Iinclude/drm/drm_dp_mst_helper.h -!Edrivers/gpu/drm/drm_dp_mst_topology.c - </sect2> - <sect2> - <title>MIPI DSI Helper Functions Reference</title> -!Pdrivers/gpu/drm/drm_mipi_dsi.c dsi helpers -!Iinclude/drm/drm_mipi_dsi.h -!Edrivers/gpu/drm/drm_mipi_dsi.c - </sect2> - <sect2> - <title>EDID Helper Functions Reference</title> -!Edrivers/gpu/drm/drm_edid.c - </sect2> - <sect2> - <title>Rectangle Utilities Reference</title> -!Pinclude/drm/drm_rect.h rect utils -!Iinclude/drm/drm_rect.h -!Edrivers/gpu/drm/drm_rect.c - </sect2> - <sect2> - <title>Flip-work Helper Reference</title> -!Pinclude/drm/drm_flip_work.h flip utils -!Iinclude/drm/drm_flip_work.h -!Edrivers/gpu/drm/drm_flip_work.c - </sect2> - <sect2> - <title>HDMI Infoframes Helper Reference</title> - <para> - Strictly speaking this is not a DRM helper library but generally useable - by any driver interfacing with HDMI outputs like v4l or alsa drivers. - But it nicely fits into the overall topic of mode setting helper - libraries and hence is also included here. - </para> -!Iinclude/linux/hdmi.h -!Edrivers/video/hdmi.c - </sect2> - <sect2> - <title id="drm-kms-planehelpers">Plane Helper Reference</title> -!Edrivers/gpu/drm/drm_plane_helper.c -!Pdrivers/gpu/drm/drm_plane_helper.c overview - </sect2> - <sect2> - <title>Tile group</title> -!Pdrivers/gpu/drm/drm_crtc.c Tile group - </sect2> - <sect2> - <title>Bridges</title> - <sect3> - <title>Overview</title> -!Pdrivers/gpu/drm/drm_bridge.c overview - </sect3> - <sect3> - <title>Default bridge callback sequence</title> -!Pdrivers/gpu/drm/drm_bridge.c bridge callbacks - </sect3> -!Edrivers/gpu/drm/drm_bridge.c - </sect2> - </sect1> - - <!-- Internals: kms properties --> - - <sect1 id="drm-kms-properties"> - <title>KMS Properties</title> - <para> - Drivers may need to expose additional parameters to applications than - those described in the previous sections. KMS supports attaching - properties to CRTCs, connectors and planes and offers a userspace API to - list, get and set the property values. - </para> - <para> - Properties are identified by a name that uniquely defines the property - purpose, and store an associated value. For all property types except blob - properties the value is a 64-bit unsigned integer. - </para> - <para> - KMS differentiates between properties and property instances. Drivers - first create properties and then create and associate individual instances - of those properties to objects. A property can be instantiated multiple - times and associated with different objects. Values are stored in property - instances, and all other property information are stored in the property - and shared between all instances of the property. - </para> - <para> - Every property is created with a type that influences how the KMS core - handles the property. Supported property types are - <variablelist> - <varlistentry> - <term>DRM_MODE_PROP_RANGE</term> - <listitem><para>Range properties report their minimum and maximum - admissible values. The KMS core verifies that values set by - application fit in that range.</para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_PROP_ENUM</term> - <listitem><para>Enumerated properties take a numerical value that - ranges from 0 to the number of enumerated values defined by the - property minus one, and associate a free-formed string name to each - value. Applications can retrieve the list of defined value-name pairs - and use the numerical value to get and set property instance values. - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_PROP_BITMASK</term> - <listitem><para>Bitmask properties are enumeration properties that - additionally restrict all enumerated values to the 0..63 range. - Bitmask property instance values combine one or more of the - enumerated bits defined by the property.</para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_PROP_BLOB</term> - <listitem><para>Blob properties store a binary blob without any format - restriction. The binary blobs are created as KMS standalone objects, - and blob property instance values store the ID of their associated - blob object.</para> - <para>Blob properties are only used for the connector EDID property - and cannot be created by drivers.</para></listitem> - </varlistentry> - </variablelist> - </para> - <para> - To create a property drivers call one of the following functions depending - on the property type. All property creation functions take property flags - and name, as well as type-specific arguments. - <itemizedlist> - <listitem> - <synopsis>struct drm_property *drm_property_create_range(struct drm_device *dev, int flags, - const char *name, - uint64_t min, uint64_t max);</synopsis> - <para>Create a range property with the given minimum and maximum - values.</para> - </listitem> - <listitem> - <synopsis>struct drm_property *drm_property_create_enum(struct drm_device *dev, int flags, - const char *name, - const struct drm_prop_enum_list *props, - int num_values);</synopsis> - <para>Create an enumerated property. The <parameter>props</parameter> - argument points to an array of <parameter>num_values</parameter> - value-name pairs.</para> - </listitem> - <listitem> - <synopsis>struct drm_property *drm_property_create_bitmask(struct drm_device *dev, - int flags, const char *name, - const struct drm_prop_enum_list *props, - int num_values);</synopsis> - <para>Create a bitmask property. The <parameter>props</parameter> - argument points to an array of <parameter>num_values</parameter> - value-name pairs.</para> - </listitem> - </itemizedlist> - </para> - <para> - Properties can additionally be created as immutable, in which case they - will be read-only for applications but can be modified by the driver. To - create an immutable property drivers must set the DRM_MODE_PROP_IMMUTABLE - flag at property creation time. - </para> - <para> - When no array of value-name pairs is readily available at property - creation time for enumerated or range properties, drivers can create - the property using the <function>drm_property_create</function> function - and manually add enumeration value-name pairs by calling the - <function>drm_property_add_enum</function> function. Care must be taken to - properly specify the property type through the <parameter>flags</parameter> - argument. - </para> - <para> - After creating properties drivers can attach property instances to CRTC, - connector and plane objects by calling the - <function>drm_object_attach_property</function>. The function takes a - pointer to the target object, a pointer to the previously created property - and an initial instance value. - </para> - <sect2> - <title>Existing KMS Properties</title> - <para> - The following table gives description of drm properties exposed by various - modules/drivers. - </para> - <table border="1" cellpadding="0" cellspacing="0"> - <tbody> - <tr style="font-weight: bold;"> - <td valign="top" >Owner Module/Drivers</td> - <td valign="top" >Group</td> - <td valign="top" >Property Name</td> - <td valign="top" >Type</td> - <td valign="top" >Property Values</td> - <td valign="top" >Object attached</td> - <td valign="top" >Description/Restrictions</td> - </tr> - <tr> - <td rowspan="37" valign="top" >DRM</td> - <td valign="top" >Generic</td> - <td valign="top" >“rotation”</td> - <td valign="top" >BITMASK</td> - <td valign="top" >{ 0, "rotate-0" }, - { 1, "rotate-90" }, - { 2, "rotate-180" }, - { 3, "rotate-270" }, - { 4, "reflect-x" }, - { 5, "reflect-y" }</td> - <td valign="top" >CRTC, Plane</td> - <td valign="top" >rotate-(degrees) rotates the image by the specified amount in degrees - in counter clockwise direction. reflect-x and reflect-y reflects the - image along the specified axis prior to rotation</td> - </tr> - <tr> - <td rowspan="5" valign="top" >Connector</td> - <td valign="top" >“EDID”</td> - <td valign="top" >BLOB | IMMUTABLE</td> - <td valign="top" >0</td> - <td valign="top" >Connector</td> - <td valign="top" >Contains id of edid blob ptr object.</td> - </tr> - <tr> - <td valign="top" >“DPMS”</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ “On”, “Standby”, “Suspend”, “Off” }</td> - <td valign="top" >Connector</td> - <td valign="top" >Contains DPMS operation mode value.</td> - </tr> - <tr> - <td valign="top" >“PATH”</td> - <td valign="top" >BLOB | IMMUTABLE</td> - <td valign="top" >0</td> - <td valign="top" >Connector</td> - <td valign="top" >Contains topology path to a connector.</td> - </tr> - <tr> - <td valign="top" >“TILE”</td> - <td valign="top" >BLOB | IMMUTABLE</td> - <td valign="top" >0</td> - <td valign="top" >Connector</td> - <td valign="top" >Contains tiling information for a connector.</td> - </tr> - <tr> - <td valign="top" >“CRTC_ID”</td> - <td valign="top" >OBJECT</td> - <td valign="top" >DRM_MODE_OBJECT_CRTC</td> - <td valign="top" >Connector</td> - <td valign="top" >CRTC that connector is attached to (atomic)</td> - </tr> - <tr> - <td rowspan="11" valign="top" >Plane</td> - <td valign="top" >“type”</td> - <td valign="top" >ENUM | IMMUTABLE</td> - <td valign="top" >{ "Overlay", "Primary", "Cursor" }</td> - <td valign="top" >Plane</td> - <td valign="top" >Plane type</td> - </tr> - <tr> - <td valign="top" >“SRC_X”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=UINT_MAX</td> - <td valign="top" >Plane</td> - <td valign="top" >Scanout source x coordinate in 16.16 fixed point (atomic)</td> - </tr> - <tr> - <td valign="top" >“SRC_Y”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=UINT_MAX</td> - <td valign="top" >Plane</td> - <td valign="top" >Scanout source y coordinate in 16.16 fixed point (atomic)</td> - </tr> - <tr> - <td valign="top" >“SRC_W”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=UINT_MAX</td> - <td valign="top" >Plane</td> - <td valign="top" >Scanout source width in 16.16 fixed point (atomic)</td> - </tr> - <tr> - <td valign="top" >“SRC_H”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=UINT_MAX</td> - <td valign="top" >Plane</td> - <td valign="top" >Scanout source height in 16.16 fixed point (atomic)</td> - </tr> - <tr> - <td valign="top" >“CRTC_X”</td> - <td valign="top" >SIGNED_RANGE</td> - <td valign="top" >Min=INT_MIN, Max=INT_MAX</td> - <td valign="top" >Plane</td> - <td valign="top" >Scanout CRTC (destination) x coordinate (atomic)</td> - </tr> - <tr> - <td valign="top" >“CRTC_Y”</td> - <td valign="top" >SIGNED_RANGE</td> - <td valign="top" >Min=INT_MIN, Max=INT_MAX</td> - <td valign="top" >Plane</td> - <td valign="top" >Scanout CRTC (destination) y coordinate (atomic)</td> - </tr> - <tr> - <td valign="top" >“CRTC_W”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=UINT_MAX</td> - <td valign="top" >Plane</td> - <td valign="top" >Scanout CRTC (destination) width (atomic)</td> - </tr> - <tr> - <td valign="top" >“CRTC_H”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=UINT_MAX</td> - <td valign="top" >Plane</td> - <td valign="top" >Scanout CRTC (destination) height (atomic)</td> - </tr> - <tr> - <td valign="top" >“FB_ID”</td> - <td valign="top" >OBJECT</td> - <td valign="top" >DRM_MODE_OBJECT_FB</td> - <td valign="top" >Plane</td> - <td valign="top" >Scanout framebuffer (atomic)</td> - </tr> - <tr> - <td valign="top" >“CRTC_ID”</td> - <td valign="top" >OBJECT</td> - <td valign="top" >DRM_MODE_OBJECT_CRTC</td> - <td valign="top" >Plane</td> - <td valign="top" >CRTC that plane is attached to (atomic)</td> - </tr> - <tr> - <td rowspan="2" valign="top" >DVI-I</td> - <td valign="top" >“subconnector”</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ “Unknown”, “DVI-D”, “DVI-A” }</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“select subconnector”</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ “Automatic”, “DVI-D”, “DVI-A” }</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td rowspan="13" valign="top" >TV</td> - <td valign="top" >“subconnector”</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ "Unknown", "Composite", "SVIDEO", "Component", "SCART" }</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“select subconnector”</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ "Automatic", "Composite", "SVIDEO", "Component", "SCART" }</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“mode”</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc.</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“left margin”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=100</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“right margin”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=100</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“top margin”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=100</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“bottom margin”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=100</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“brightness”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=100</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“contrast”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=100</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“flicker reduction”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=100</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“overscan”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=100</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“saturation”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=100</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“hue”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=100</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td rowspan="2" valign="top" >Virtual GPU</td> - <td valign="top" >“suggested X”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=0xffffffff</td> - <td valign="top" >Connector</td> - <td valign="top" >property to suggest an X offset for a connector</td> - </tr> - <tr> - <td valign="top" >“suggested Y”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=0xffffffff</td> - <td valign="top" >Connector</td> - <td valign="top" >property to suggest an Y offset for a connector</td> - </tr> - <tr> - <td rowspan="3" valign="top" >Optional</td> - <td valign="top" >“scaling mode”</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ "None", "Full", "Center", "Full aspect" }</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >"aspect ratio"</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ "None", "4:3", "16:9" }</td> - <td valign="top" >Connector</td> - <td valign="top" >DRM property to set aspect ratio from user space app. - This enum is made generic to allow addition of custom aspect - ratios.</td> - </tr> - <tr> - <td valign="top" >“dirty”</td> - <td valign="top" >ENUM | IMMUTABLE</td> - <td valign="top" >{ "Off", "On", "Annotate" }</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td rowspan="20" valign="top" >i915</td> - <td rowspan="2" valign="top" >Generic</td> - <td valign="top" >"Broadcast RGB"</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ "Automatic", "Full", "Limited 16:235" }</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“audio”</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ "force-dvi", "off", "auto", "on" }</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td rowspan="17" valign="top" >SDVO-TV</td> - <td valign="top" >“mode”</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc.</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >"left_margin"</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >"right_margin"</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >"top_margin"</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >"bottom_margin"</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“hpos”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“vpos”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“contrast”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“saturation”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“hue”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“sharpness”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“flicker_filter”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“flicker_filter_adaptive”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“flicker_filter_2d”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“tv_chroma_filter”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“tv_luma_filter”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“dot_crawl”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=1</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >SDVO-TV/LVDS</td> - <td valign="top" >“brightness”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td rowspan="2" valign="top" >CDV gma-500</td> - <td rowspan="2" valign="top" >Generic</td> - <td valign="top" >"Broadcast RGB"</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ “Full”, “Limited 16:235” }</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >"Broadcast RGB"</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ “off”, “auto”, “on” }</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td rowspan="19" valign="top" >Poulsbo</td> - <td rowspan="1" valign="top" >Generic</td> - <td valign="top" >“backlight”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=100</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td rowspan="17" valign="top" >SDVO-TV</td> - <td valign="top" >“mode”</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc.</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >"left_margin"</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >"right_margin"</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >"top_margin"</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >"bottom_margin"</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“hpos”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“vpos”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“contrast”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“saturation”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“hue”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“sharpness”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“flicker_filter”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“flicker_filter_adaptive”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“flicker_filter_2d”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“tv_chroma_filter”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“tv_luma_filter”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“dot_crawl”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=1</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >SDVO-TV/LVDS</td> - <td valign="top" >“brightness”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max= SDVO dependent</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td rowspan="11" valign="top" >armada</td> - <td rowspan="2" valign="top" >CRTC</td> - <td valign="top" >"CSC_YUV"</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ "Auto" , "CCIR601", "CCIR709" }</td> - <td valign="top" >CRTC</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >"CSC_RGB"</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ "Auto", "Computer system", "Studio" }</td> - <td valign="top" >CRTC</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td rowspan="9" valign="top" >Overlay</td> - <td valign="top" >"colorkey"</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=0xffffff</td> - <td valign="top" >Plane</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >"colorkey_min"</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=0xffffff</td> - <td valign="top" >Plane</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >"colorkey_max"</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=0xffffff</td> - <td valign="top" >Plane</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >"colorkey_val"</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=0xffffff</td> - <td valign="top" >Plane</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >"colorkey_alpha"</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=0xffffff</td> - <td valign="top" >Plane</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >"colorkey_mode"</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ "disabled", "Y component", "U component" - , "V component", "RGB", “R component", "G component", "B component" }</td> - <td valign="top" >Plane</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >"brightness"</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=256 + 255</td> - <td valign="top" >Plane</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >"contrast"</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=0x7fff</td> - <td valign="top" >Plane</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >"saturation"</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=0x7fff</td> - <td valign="top" >Plane</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td rowspan="2" valign="top" >exynos</td> - <td valign="top" >CRTC</td> - <td valign="top" >“mode”</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ "normal", "blank" }</td> - <td valign="top" >CRTC</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >Overlay</td> - <td valign="top" >“zpos”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=MAX_PLANE-1</td> - <td valign="top" >Plane</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td rowspan="2" valign="top" >i2c/ch7006_drv</td> - <td valign="top" >Generic</td> - <td valign="top" >“scale”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=2</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td rowspan="1" valign="top" >TV</td> - <td valign="top" >“mode”</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ "PAL", "PAL-M","PAL-N"}, ”PAL-Nc" - , "PAL-60", "NTSC-M", "NTSC-J" }</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td rowspan="15" valign="top" >nouveau</td> - <td rowspan="6" valign="top" >NV10 Overlay</td> - <td valign="top" >"colorkey"</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=0x01ffffff</td> - <td valign="top" >Plane</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“contrast”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=8192-1</td> - <td valign="top" >Plane</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“brightness”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=1024</td> - <td valign="top" >Plane</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“hue”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=359</td> - <td valign="top" >Plane</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“saturation”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=8192-1</td> - <td valign="top" >Plane</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“iturbt_709”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=1</td> - <td valign="top" >Plane</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td rowspan="2" valign="top" >Nv04 Overlay</td> - <td valign="top" >“colorkey”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=0x01ffffff</td> - <td valign="top" >Plane</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“brightness”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=1024</td> - <td valign="top" >Plane</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td rowspan="7" valign="top" >Display</td> - <td valign="top" >“dithering mode”</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ "auto", "off", "on" }</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“dithering depth”</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ "auto", "off", "on", "static 2x2", "dynamic 2x2", "temporal" }</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“underscan”</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ "auto", "6 bpc", "8 bpc" }</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“underscan hborder”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=128</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“underscan vborder”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=128</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“vibrant hue”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=180</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >“color vibrance”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=200</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >omap</td> - <td valign="top" >Generic</td> - <td valign="top" >“zorder”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=3</td> - <td valign="top" >CRTC, Plane</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >qxl</td> - <td valign="top" >Generic</td> - <td valign="top" >“hotplug_mode_update"</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=1</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td rowspan="9" valign="top" >radeon</td> - <td valign="top" >DVI-I</td> - <td valign="top" >“coherent”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=1</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >DAC enable load detect</td> - <td valign="top" >“load detection”</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=1</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >TV Standard</td> - <td valign="top" >"tv standard"</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ "ntsc", "pal", "pal-m", "pal-60", "ntsc-j" - , "scart-pal", "pal-cn", "secam" }</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >legacy TMDS PLL detect</td> - <td valign="top" >"tmds_pll"</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ "driver", "bios" }</td> - <td valign="top" >-</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td rowspan="3" valign="top" >Underscan</td> - <td valign="top" >"underscan"</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ "off", "on", "auto" }</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >"underscan hborder"</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=128</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >"underscan vborder"</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=128</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >Audio</td> - <td valign="top" >“audio”</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ "off", "on", "auto" }</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >FMT Dithering</td> - <td valign="top" >“dither”</td> - <td valign="top" >ENUM</td> - <td valign="top" >{ "off", "on" }</td> - <td valign="top" >Connector</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td rowspan="3" valign="top" >rcar-du</td> - <td rowspan="3" valign="top" >Generic</td> - <td valign="top" >"alpha"</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=255</td> - <td valign="top" >Plane</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >"colorkey"</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=0, Max=0x01ffffff</td> - <td valign="top" >Plane</td> - <td valign="top" >TBD</td> - </tr> - <tr> - <td valign="top" >"zpos"</td> - <td valign="top" >RANGE</td> - <td valign="top" >Min=1, Max=7</td> - <td valign="top" >Plane</td> - <td valign="top" >TBD</td> - </tr> - </tbody> - </table> - </sect2> - </sect1> - - <!-- Internals: vertical blanking --> - - <sect1 id="drm-vertical-blank"> - <title>Vertical Blanking</title> - <para> - Vertical blanking plays a major role in graphics rendering. To achieve - tear-free display, users must synchronize page flips and/or rendering to - vertical blanking. The DRM API offers ioctls to perform page flips - synchronized to vertical blanking and wait for vertical blanking. - </para> - <para> - The DRM core handles most of the vertical blanking management logic, which - involves filtering out spurious interrupts, keeping race-free blanking - counters, coping with counter wrap-around and resets and keeping use - counts. It relies on the driver to generate vertical blanking interrupts - and optionally provide a hardware vertical blanking counter. Drivers must - implement the following operations. - </para> - <itemizedlist> - <listitem> - <synopsis>int (*enable_vblank) (struct drm_device *dev, int crtc); -void (*disable_vblank) (struct drm_device *dev, int crtc);</synopsis> - <para> - Enable or disable vertical blanking interrupts for the given CRTC. - </para> - </listitem> - <listitem> - <synopsis>u32 (*get_vblank_counter) (struct drm_device *dev, int crtc);</synopsis> - <para> - Retrieve the value of the vertical blanking counter for the given - CRTC. If the hardware maintains a vertical blanking counter its value - should be returned. Otherwise drivers can use the - <function>drm_vblank_count</function> helper function to handle this - operation. - </para> - </listitem> - </itemizedlist> - <para> - Drivers must initialize the vertical blanking handling core with a call to - <function>drm_vblank_init</function> in their - <methodname>load</methodname> operation. The function will set the struct - <structname>drm_device</structname> - <structfield>vblank_disable_allowed</structfield> field to 0. This will - keep vertical blanking interrupts enabled permanently until the first mode - set operation, where <structfield>vblank_disable_allowed</structfield> is - set to 1. The reason behind this is not clear. Drivers can set the field - to 1 after <function>calling drm_vblank_init</function> to make vertical - blanking interrupts dynamically managed from the beginning. - </para> - <para> - Vertical blanking interrupts can be enabled by the DRM core or by drivers - themselves (for instance to handle page flipping operations). The DRM core - maintains a vertical blanking use count to ensure that the interrupts are - not disabled while a user still needs them. To increment the use count, - drivers call <function>drm_vblank_get</function>. Upon return vertical - blanking interrupts are guaranteed to be enabled. - </para> - <para> - To decrement the use count drivers call - <function>drm_vblank_put</function>. Only when the use count drops to zero - will the DRM core disable the vertical blanking interrupts after a delay - by scheduling a timer. The delay is accessible through the vblankoffdelay - module parameter or the <varname>drm_vblank_offdelay</varname> global - variable and expressed in milliseconds. Its default value is 5000 ms. - Zero means never disable, and a negative value means disable immediately. - Drivers may override the behaviour by setting the - <structname>drm_device</structname> - <structfield>vblank_disable_immediate</structfield> flag, which when set - causes vblank interrupts to be disabled immediately regardless of the - drm_vblank_offdelay value. The flag should only be set if there's a - properly working hardware vblank counter present. - </para> - <para> - When a vertical blanking interrupt occurs drivers only need to call the - <function>drm_handle_vblank</function> function to account for the - interrupt. - </para> - <para> - Resources allocated by <function>drm_vblank_init</function> must be freed - with a call to <function>drm_vblank_cleanup</function> in the driver - <methodname>unload</methodname> operation handler. - </para> - <sect2> - <title>Vertical Blanking and Interrupt Handling Functions Reference</title> -!Edrivers/gpu/drm/drm_irq.c -!Finclude/drm/drmP.h drm_crtc_vblank_waitqueue - </sect2> - </sect1> - - <!-- Internals: open/close, file operations and ioctls --> - - <sect1> - <title>Open/Close, File Operations and IOCTLs</title> - <sect2> - <title>Open and Close</title> - <synopsis>int (*firstopen) (struct drm_device *); -void (*lastclose) (struct drm_device *); -int (*open) (struct drm_device *, struct drm_file *); -void (*preclose) (struct drm_device *, struct drm_file *); -void (*postclose) (struct drm_device *, struct drm_file *);</synopsis> - <abstract>Open and close handlers. None of those methods are mandatory. - </abstract> - <para> - The <methodname>firstopen</methodname> method is called by the DRM core - for legacy UMS (User Mode Setting) drivers only when an application - opens a device that has no other opened file handle. UMS drivers can - implement it to acquire device resources. KMS drivers can't use the - method and must acquire resources in the <methodname>load</methodname> - method instead. - </para> - <para> - Similarly the <methodname>lastclose</methodname> method is called when - the last application holding a file handle opened on the device closes - it, for both UMS and KMS drivers. Additionally, the method is also - called at module unload time or, for hot-pluggable devices, when the - device is unplugged. The <methodname>firstopen</methodname> and - <methodname>lastclose</methodname> calls can thus be unbalanced. - </para> - <para> - The <methodname>open</methodname> method is called every time the device - is opened by an application. Drivers can allocate per-file private data - in this method and store them in the struct - <structname>drm_file</structname> <structfield>driver_priv</structfield> - field. Note that the <methodname>open</methodname> method is called - before <methodname>firstopen</methodname>. - </para> - <para> - The close operation is split into <methodname>preclose</methodname> and - <methodname>postclose</methodname> methods. Drivers must stop and - cleanup all per-file operations in the <methodname>preclose</methodname> - method. For instance pending vertical blanking and page flip events must - be cancelled. No per-file operation is allowed on the file handle after - returning from the <methodname>preclose</methodname> method. - </para> - <para> - Finally the <methodname>postclose</methodname> method is called as the - last step of the close operation, right before calling the - <methodname>lastclose</methodname> method if no other open file handle - exists for the device. Drivers that have allocated per-file private data - in the <methodname>open</methodname> method should free it here. - </para> - <para> - The <methodname>lastclose</methodname> method should restore CRTC and - plane properties to default value, so that a subsequent open of the - device will not inherit state from the previous user. It can also be - used to execute delayed power switching state changes, e.g. in - conjunction with the vga_switcheroo infrastructure (see - <xref linkend="vga_switcheroo"/>). Beyond that KMS drivers should not - do any further cleanup. Only legacy UMS drivers might need to clean up - device state so that the vga console or an independent fbdev driver - could take over. - </para> - </sect2> - <sect2> - <title>File Operations</title> - <synopsis>const struct file_operations *fops</synopsis> - <abstract>File operations for the DRM device node.</abstract> - <para> - Drivers must define the file operations structure that forms the DRM - userspace API entry point, even though most of those operations are - implemented in the DRM core. The <methodname>open</methodname>, - <methodname>release</methodname> and <methodname>ioctl</methodname> - operations are handled by - <programlisting> - .owner = THIS_MODULE, - .open = drm_open, - .release = drm_release, - .unlocked_ioctl = drm_ioctl, - #ifdef CONFIG_COMPAT - .compat_ioctl = drm_compat_ioctl, - #endif - </programlisting> - </para> - <para> - Drivers that implement private ioctls that requires 32/64bit - compatibility support must provide their own - <methodname>compat_ioctl</methodname> handler that processes private - ioctls and calls <function>drm_compat_ioctl</function> for core ioctls. - </para> - <para> - The <methodname>read</methodname> and <methodname>poll</methodname> - operations provide support for reading DRM events and polling them. They - are implemented by - <programlisting> - .poll = drm_poll, - .read = drm_read, - .llseek = no_llseek, - </programlisting> - </para> - <para> - The memory mapping implementation varies depending on how the driver - manages memory. Pre-GEM drivers will use <function>drm_mmap</function>, - while GEM-aware drivers will use <function>drm_gem_mmap</function>. See - <xref linkend="drm-gem"/>. - <programlisting> - .mmap = drm_gem_mmap, - </programlisting> - </para> - <para> - No other file operation is supported by the DRM API. - </para> - </sect2> - <sect2> - <title>IOCTLs</title> - <synopsis>struct drm_ioctl_desc *ioctls; -int num_ioctls;</synopsis> - <abstract>Driver-specific ioctls descriptors table.</abstract> - <para> - Driver-specific ioctls numbers start at DRM_COMMAND_BASE. The ioctls - descriptors table is indexed by the ioctl number offset from the base - value. Drivers can use the DRM_IOCTL_DEF_DRV() macro to initialize the - table entries. - </para> - <para> - <programlisting>DRM_IOCTL_DEF_DRV(ioctl, func, flags)</programlisting> - <para> - <parameter>ioctl</parameter> is the ioctl name. Drivers must define - the DRM_##ioctl and DRM_IOCTL_##ioctl macros to the ioctl number - offset from DRM_COMMAND_BASE and the ioctl number respectively. The - first macro is private to the device while the second must be exposed - to userspace in a public header. - </para> - <para> - <parameter>func</parameter> is a pointer to the ioctl handler function - compatible with the <type>drm_ioctl_t</type> type. - <programlisting>typedef int drm_ioctl_t(struct drm_device *dev, void *data, - struct drm_file *file_priv);</programlisting> - </para> - <para> - <parameter>flags</parameter> is a bitmask combination of the following - values. It restricts how the ioctl is allowed to be called. - <itemizedlist> - <listitem><para> - DRM_AUTH - Only authenticated callers allowed - </para></listitem> - <listitem><para> - DRM_MASTER - The ioctl can only be called on the master file - handle - </para></listitem> - <listitem><para> - DRM_ROOT_ONLY - Only callers with the SYSADMIN capability allowed - </para></listitem> - <listitem><para> - DRM_CONTROL_ALLOW - The ioctl can only be called on a control - device - </para></listitem> - <listitem><para> - DRM_UNLOCKED - The ioctl handler will be called without locking - the DRM global mutex. This is the enforced default for kms drivers - (i.e. using the DRIVER_MODESET flag) and hence shouldn't be used - any more for new drivers. - </para></listitem> - </itemizedlist> - </para> - </para> -!Edrivers/gpu/drm/drm_ioctl.c - </sect2> - </sect1> - <sect1> - <title>Legacy Support Code</title> - <para> - The section very briefly covers some of the old legacy support code which - is only used by old DRM drivers which have done a so-called shadow-attach - to the underlying device instead of registering as a real driver. This - also includes some of the old generic buffer management and command - submission code. Do not use any of this in new and modern drivers. - </para> - - <sect2> - <title>Legacy Suspend/Resume</title> - <para> - The DRM core provides some suspend/resume code, but drivers wanting full - suspend/resume support should provide save() and restore() functions. - These are called at suspend, hibernate, or resume time, and should perform - any state save or restore required by your device across suspend or - hibernate states. - </para> - <synopsis>int (*suspend) (struct drm_device *, pm_message_t state); - int (*resume) (struct drm_device *);</synopsis> - <para> - Those are legacy suspend and resume methods which - <emphasis>only</emphasis> work with the legacy shadow-attach driver - registration functions. New driver should use the power management - interface provided by their bus type (usually through - the struct <structname>device_driver</structname> dev_pm_ops) and set - these methods to NULL. - </para> - </sect2> - - <sect2> - <title>Legacy DMA Services</title> - <para> - This should cover how DMA mapping etc. is supported by the core. - These functions are deprecated and should not be used. - </para> - </sect2> - </sect1> - </chapter> - -<!-- TODO - -- Add a glossary -- Document the struct_mutex catch-all lock -- Document connector properties - -- Why is the load method optional? -- What are drivers supposed to set the initial display state to, and how? - Connector's DPMS states are not initialized and are thus equal to - DRM_MODE_DPMS_ON. The fbcon compatibility layer calls - drm_helper_disable_unused_functions(), which disables unused encoders and - CRTCs, but doesn't touch the connectors' DPMS state, and - drm_helper_connector_dpms() in reaction to fbdev blanking events. Do drivers - that don't implement (or just don't use) fbcon compatibility need to call - those functions themselves? -- KMS drivers must call drm_vblank_pre_modeset() and drm_vblank_post_modeset() - around mode setting. Should this be done in the DRM core? -- vblank_disable_allowed is set to 1 in the first drm_vblank_post_modeset() - call and never set back to 0. It seems to be safe to permanently set it to 1 - in drm_vblank_init() for KMS driver, and it might be safe for UMS drivers as - well. This should be investigated. -- crtc and connector .save and .restore operations are only used internally in - drivers, should they be removed from the core? -- encoder mid-layer .save and .restore operations are only used internally in - drivers, should they be removed from the core? -- encoder mid-layer .detect operation is only used internally in drivers, - should it be removed from the core? ---> - - <!-- External interfaces --> - - <chapter id="drmExternals"> - <title>Userland interfaces</title> - <para> - The DRM core exports several interfaces to applications, - generally intended to be used through corresponding libdrm - wrapper functions. In addition, drivers export device-specific - interfaces for use by userspace drivers & device-aware - applications through ioctls and sysfs files. - </para> - <para> - External interfaces include: memory mapping, context management, - DMA operations, AGP management, vblank control, fence - management, memory management, and output management. - </para> - <para> - Cover generic ioctls and sysfs layout here. We only need high-level - info, since man pages should cover the rest. - </para> - - <!-- External: render nodes --> - - <sect1> - <title>Render nodes</title> - <para> - DRM core provides multiple character-devices for user-space to use. - Depending on which device is opened, user-space can perform a different - set of operations (mainly ioctls). The primary node is always created - and called card<num>. Additionally, a currently - unused control node, called controlD<num> is also - created. The primary node provides all legacy operations and - historically was the only interface used by userspace. With KMS, the - control node was introduced. However, the planned KMS control interface - has never been written and so the control node stays unused to date. - </para> - <para> - With the increased use of offscreen renderers and GPGPU applications, - clients no longer require running compositors or graphics servers to - make use of a GPU. But the DRM API required unprivileged clients to - authenticate to a DRM-Master prior to getting GPU access. To avoid this - step and to grant clients GPU access without authenticating, render - nodes were introduced. Render nodes solely serve render clients, that - is, no modesetting or privileged ioctls can be issued on render nodes. - Only non-global rendering commands are allowed. If a driver supports - render nodes, it must advertise it via the DRIVER_RENDER - DRM driver capability. If not supported, the primary node must be used - for render clients together with the legacy drmAuth authentication - procedure. - </para> - <para> - If a driver advertises render node support, DRM core will create a - separate render node called renderD<num>. There will - be one render node per device. No ioctls except PRIME-related ioctls - will be allowed on this node. Especially GEM_OPEN will be - explicitly prohibited. Render nodes are designed to avoid the - buffer-leaks, which occur if clients guess the flink names or mmap - offsets on the legacy interface. Additionally to this basic interface, - drivers must mark their driver-dependent render-only ioctls as - DRM_RENDER_ALLOW so render clients can use them. Driver - authors must be careful not to allow any privileged ioctls on render - nodes. - </para> - <para> - With render nodes, user-space can now control access to the render node - via basic file-system access-modes. A running graphics server which - authenticates clients on the privileged primary/legacy node is no longer - required. Instead, a client can open the render node and is immediately - granted GPU access. Communication between clients (or servers) is done - via PRIME. FLINK from render node to legacy node is not supported. New - clients must not use the insecure FLINK interface. - </para> - <para> - Besides dropping all modeset/global ioctls, render nodes also drop the - DRM-Master concept. There is no reason to associate render clients with - a DRM-Master as they are independent of any graphics server. Besides, - they must work without any running master, anyway. - Drivers must be able to run without a master object if they support - render nodes. If, on the other hand, a driver requires shared state - between clients which is visible to user-space and accessible beyond - open-file boundaries, they cannot support render nodes. - </para> - </sect1> - - <!-- External: vblank handling --> - - <sect1> - <title>VBlank event handling</title> - <para> - The DRM core exposes two vertical blank related ioctls: - <variablelist> - <varlistentry> - <term>DRM_IOCTL_WAIT_VBLANK</term> - <listitem> - <para> - This takes a struct drm_wait_vblank structure as its argument, - and it is used to block or request a signal when a specified - vblank event occurs. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>DRM_IOCTL_MODESET_CTL</term> - <listitem> - <para> - This was only used for user-mode-settind drivers around - modesetting changes to allow the kernel to update the vblank - interrupt after mode setting, since on many devices the vertical - blank counter is reset to 0 at some point during modeset. Modern - drivers should not call this any more since with kernel mode - setting it is a no-op. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </sect1> - - </chapter> -</part> -<part id="drmDrivers"> - <title>DRM Drivers</title> - - <partintro> - <para> - This second part of the GPU Driver Developer's Guide documents driver - code, implementation details and also all the driver-specific userspace - interfaces. Especially since all hardware-acceleration interfaces to - userspace are driver specific for efficiency and other reasons these - interfaces can be rather substantial. Hence every driver has its own - chapter. - </para> - </partintro> - - <chapter id="drmI915"> - <title>drm/i915 Intel GFX Driver</title> - <para> - The drm/i915 driver supports all (with the exception of some very early - models) integrated GFX chipsets with both Intel display and rendering - blocks. This excludes a set of SoC platforms with an SGX rendering unit, - those have basic support through the gma500 drm driver. - </para> - <sect1> - <title>Core Driver Infrastructure</title> - <para> - This section covers core driver infrastructure used by both the display - and the GEM parts of the driver. - </para> - <sect2> - <title>Runtime Power Management</title> -!Pdrivers/gpu/drm/i915/intel_runtime_pm.c runtime pm -!Idrivers/gpu/drm/i915/intel_runtime_pm.c -!Idrivers/gpu/drm/i915/intel_uncore.c - </sect2> - <sect2> - <title>Interrupt Handling</title> -!Pdrivers/gpu/drm/i915/i915_irq.c interrupt handling -!Fdrivers/gpu/drm/i915/i915_irq.c intel_irq_init intel_irq_init_hw intel_hpd_init -!Fdrivers/gpu/drm/i915/i915_irq.c intel_runtime_pm_disable_interrupts -!Fdrivers/gpu/drm/i915/i915_irq.c intel_runtime_pm_enable_interrupts - </sect2> - <sect2> - <title>Intel GVT-g Guest Support(vGPU)</title> -!Pdrivers/gpu/drm/i915/i915_vgpu.c Intel GVT-g guest support -!Idrivers/gpu/drm/i915/i915_vgpu.c - </sect2> - </sect1> - <sect1> - <title>Display Hardware Handling</title> - <para> - This section covers everything related to the display hardware including - the mode setting infrastructure, plane, sprite and cursor handling and - display, output probing and related topics. - </para> - <sect2> - <title>Mode Setting Infrastructure</title> - <para> - The i915 driver is thus far the only DRM driver which doesn't use the - common DRM helper code to implement mode setting sequences. Thus it - has its own tailor-made infrastructure for executing a display - configuration change. - </para> - </sect2> - <sect2> - <title>Frontbuffer Tracking</title> -!Pdrivers/gpu/drm/i915/intel_frontbuffer.c frontbuffer tracking -!Idrivers/gpu/drm/i915/intel_frontbuffer.c -!Fdrivers/gpu/drm/i915/i915_gem.c i915_gem_track_fb - </sect2> - <sect2> - <title>Display FIFO Underrun Reporting</title> -!Pdrivers/gpu/drm/i915/intel_fifo_underrun.c fifo underrun handling -!Idrivers/gpu/drm/i915/intel_fifo_underrun.c - </sect2> - <sect2> - <title>Plane Configuration</title> - <para> - This section covers plane configuration and composition with the - primary plane, sprites, cursors and overlays. This includes the - infrastructure to do atomic vsync'ed updates of all this state and - also tightly coupled topics like watermark setup and computation, - framebuffer compression and panel self refresh. - </para> - </sect2> - <sect2> - <title>Atomic Plane Helpers</title> -!Pdrivers/gpu/drm/i915/intel_atomic_plane.c atomic plane helpers -!Idrivers/gpu/drm/i915/intel_atomic_plane.c - </sect2> - <sect2> - <title>Output Probing</title> - <para> - This section covers output probing and related infrastructure like the - hotplug interrupt storm detection and mitigation code. Note that the - i915 driver still uses most of the common DRM helper code for output - probing, so those sections fully apply. - </para> - </sect2> - <sect2> - <title>Hotplug</title> -!Pdrivers/gpu/drm/i915/intel_hotplug.c Hotplug -!Idrivers/gpu/drm/i915/intel_hotplug.c - </sect2> - <sect2> - <title>High Definition Audio</title> -!Pdrivers/gpu/drm/i915/intel_audio.c High Definition Audio over HDMI and Display Port -!Idrivers/gpu/drm/i915/intel_audio.c -!Iinclude/drm/i915_component.h - </sect2> - <sect2> - <title>Panel Self Refresh PSR (PSR/SRD)</title> -!Pdrivers/gpu/drm/i915/intel_psr.c Panel Self Refresh (PSR/SRD) -!Idrivers/gpu/drm/i915/intel_psr.c - </sect2> - <sect2> - <title>Frame Buffer Compression (FBC)</title> -!Pdrivers/gpu/drm/i915/intel_fbc.c Frame Buffer Compression (FBC) -!Idrivers/gpu/drm/i915/intel_fbc.c - </sect2> - <sect2> - <title>Display Refresh Rate Switching (DRRS)</title> -!Pdrivers/gpu/drm/i915/intel_dp.c Display Refresh Rate Switching (DRRS) -!Fdrivers/gpu/drm/i915/intel_dp.c intel_dp_set_drrs_state -!Fdrivers/gpu/drm/i915/intel_dp.c intel_edp_drrs_enable -!Fdrivers/gpu/drm/i915/intel_dp.c intel_edp_drrs_disable -!Fdrivers/gpu/drm/i915/intel_dp.c intel_edp_drrs_invalidate -!Fdrivers/gpu/drm/i915/intel_dp.c intel_edp_drrs_flush -!Fdrivers/gpu/drm/i915/intel_dp.c intel_dp_drrs_init - - </sect2> - <sect2> - <title>DPIO</title> -!Pdrivers/gpu/drm/i915/i915_reg.h DPIO - </sect2> - - <sect2> - <title>CSR firmware support for DMC</title> -!Pdrivers/gpu/drm/i915/intel_csr.c csr support for dmc -!Idrivers/gpu/drm/i915/intel_csr.c - </sect2> - </sect1> - - <sect1> - <title>Memory Management and Command Submission</title> - <para> - This sections covers all things related to the GEM implementation in the - i915 driver. - </para> - <sect2> - <title>Batchbuffer Parsing</title> -!Pdrivers/gpu/drm/i915/i915_cmd_parser.c batch buffer command parser -!Idrivers/gpu/drm/i915/i915_cmd_parser.c - </sect2> - <sect2> - <title>Batchbuffer Pools</title> -!Pdrivers/gpu/drm/i915/i915_gem_batch_pool.c batch pool -!Idrivers/gpu/drm/i915/i915_gem_batch_pool.c - </sect2> - <sect2> - <title>Logical Rings, Logical Ring Contexts and Execlists</title> -!Pdrivers/gpu/drm/i915/intel_lrc.c Logical Rings, Logical Ring Contexts and Execlists -!Idrivers/gpu/drm/i915/intel_lrc.c - </sect2> - <sect2> - <title>Global GTT views</title> -!Pdrivers/gpu/drm/i915/i915_gem_gtt.c Global GTT views -!Idrivers/gpu/drm/i915/i915_gem_gtt.c - </sect2> - <sect2> - <title>GTT Fences and Swizzling</title> -!Idrivers/gpu/drm/i915/i915_gem_fence.c - <sect3> - <title>Global GTT Fence Handling</title> -!Pdrivers/gpu/drm/i915/i915_gem_fence.c fence register handling - </sect3> - <sect3> - <title>Hardware Tiling and Swizzling Details</title> -!Pdrivers/gpu/drm/i915/i915_gem_fence.c tiling swizzling details - </sect3> - </sect2> - <sect2> - <title>Object Tiling IOCTLs</title> -!Idrivers/gpu/drm/i915/i915_gem_tiling.c -!Pdrivers/gpu/drm/i915/i915_gem_tiling.c buffer object tiling - </sect2> - <sect2> - <title>Buffer Object Eviction</title> - <para> - This section documents the interface functions for evicting buffer - objects to make space available in the virtual gpu address spaces. - Note that this is mostly orthogonal to shrinking buffer objects - caches, which has the goal to make main memory (shared with the gpu - through the unified memory architecture) available. - </para> -!Idrivers/gpu/drm/i915/i915_gem_evict.c - </sect2> - <sect2> - <title>Buffer Object Memory Shrinking</title> - <para> - This section documents the interface function for shrinking memory - usage of buffer object caches. Shrinking is used to make main memory - available. Note that this is mostly orthogonal to evicting buffer - objects, which has the goal to make space in gpu virtual address - spaces. - </para> -!Idrivers/gpu/drm/i915/i915_gem_shrinker.c - </sect2> - </sect1> - <sect1> - <title>GuC</title> - <sect2> - <title>GuC-specific firmware loader</title> -!Pdrivers/gpu/drm/i915/intel_guc_loader.c GuC-specific firmware loader -!Idrivers/gpu/drm/i915/intel_guc_loader.c - </sect2> - <sect2> - <title>GuC-based command submission</title> -!Pdrivers/gpu/drm/i915/i915_guc_submission.c GuC-based command submission -!Idrivers/gpu/drm/i915/i915_guc_submission.c - </sect2> - <sect2> - <title>GuC Firmware Layout</title> -!Pdrivers/gpu/drm/i915/intel_guc_fwif.h GuC Firmware Layout - </sect2> - </sect1> - - <sect1> - <title> Tracing </title> - <para> - This sections covers all things related to the tracepoints implemented in - the i915 driver. - </para> - <sect2> - <title> i915_ppgtt_create and i915_ppgtt_release </title> -!Pdrivers/gpu/drm/i915/i915_trace.h i915_ppgtt_create and i915_ppgtt_release tracepoints - </sect2> - <sect2> - <title> i915_context_create and i915_context_free </title> -!Pdrivers/gpu/drm/i915/i915_trace.h i915_context_create and i915_context_free tracepoints - </sect2> - <sect2> - <title> switch_mm </title> -!Pdrivers/gpu/drm/i915/i915_trace.h switch_mm tracepoint - </sect2> - </sect1> - - </chapter> -!Cdrivers/gpu/drm/i915/i915_irq.c -</part> - -<part id="vga_switcheroo"> - <title>vga_switcheroo</title> - <partintro> -!Pdrivers/gpu/vga/vga_switcheroo.c Overview - </partintro> - - <chapter id="modes_of_use"> - <title>Modes of Use</title> - <sect1> - <title>Manual switching and manual power control</title> -!Pdrivers/gpu/vga/vga_switcheroo.c Manual switching and manual power control - </sect1> - <sect1> - <title>Driver power control</title> -!Pdrivers/gpu/vga/vga_switcheroo.c Driver power control - </sect1> - </chapter> - - <chapter id="api"> - <title>API</title> - <sect1> - <title>Public functions</title> -!Edrivers/gpu/vga/vga_switcheroo.c - </sect1> - <sect1> - <title>Public structures</title> -!Finclude/linux/vga_switcheroo.h vga_switcheroo_handler -!Finclude/linux/vga_switcheroo.h vga_switcheroo_client_ops - </sect1> - <sect1> - <title>Public constants</title> -!Finclude/linux/vga_switcheroo.h vga_switcheroo_client_id -!Finclude/linux/vga_switcheroo.h vga_switcheroo_state - </sect1> - <sect1> - <title>Private structures</title> -!Fdrivers/gpu/vga/vga_switcheroo.c vgasr_priv -!Fdrivers/gpu/vga/vga_switcheroo.c vga_switcheroo_client - </sect1> - </chapter> - - <chapter id="handlers"> - <title>Handlers</title> - <sect1> - <title>apple-gmux Handler</title> -!Pdrivers/platform/x86/apple-gmux.c Overview -!Pdrivers/platform/x86/apple-gmux.c Interrupt - <sect2> - <title>Graphics mux</title> -!Pdrivers/platform/x86/apple-gmux.c Graphics mux - </sect2> - <sect2> - <title>Power control</title> -!Pdrivers/platform/x86/apple-gmux.c Power control - </sect2> - <sect2> - <title>Backlight control</title> -!Pdrivers/platform/x86/apple-gmux.c Backlight control - </sect2> - </sect1> - </chapter> - -!Cdrivers/gpu/vga/vga_switcheroo.c -!Cinclude/linux/vga_switcheroo.h -!Cdrivers/platform/x86/apple-gmux.c -</part> - -</book> diff --git a/Documentation/DocBook/iio.tmpl b/Documentation/DocBook/iio.tmpl deleted file mode 100644 index f525bf56d1dd..000000000000 --- a/Documentation/DocBook/iio.tmpl +++ /dev/null @@ -1,697 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="iioid"> - <bookinfo> - <title>Industrial I/O driver developer's guide </title> - - <authorgroup> - <author> - <firstname>Daniel</firstname> - <surname>Baluta</surname> - <affiliation> - <address> - <email>daniel.baluta@intel.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2015</year> - <holder>Intel Corporation</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License version 2. - </para> - </legalnotice> - </bookinfo> - - <toc></toc> - - <chapter id="intro"> - <title>Introduction</title> - <para> - The main purpose of the Industrial I/O subsystem (IIO) is to provide - support for devices that in some sense perform either analog-to-digital - conversion (ADC) or digital-to-analog conversion (DAC) or both. The aim - is to fill the gap between the somewhat similar hwmon and input - subsystems. - Hwmon is directed at low sample rate sensors used to monitor and - control the system itself, like fan speed control or temperature - measurement. Input is, as its name suggests, focused on human interaction - input devices (keyboard, mouse, touchscreen). In some cases there is - considerable overlap between these and IIO. - </para> - <para> - Devices that fall into this category include: - <itemizedlist> - <listitem> - analog to digital converters (ADCs) - </listitem> - <listitem> - accelerometers - </listitem> - <listitem> - capacitance to digital converters (CDCs) - </listitem> - <listitem> - digital to analog converters (DACs) - </listitem> - <listitem> - gyroscopes - </listitem> - <listitem> - inertial measurement units (IMUs) - </listitem> - <listitem> - color and light sensors - </listitem> - <listitem> - magnetometers - </listitem> - <listitem> - pressure sensors - </listitem> - <listitem> - proximity sensors - </listitem> - <listitem> - temperature sensors - </listitem> - </itemizedlist> - Usually these sensors are connected via SPI or I2C. A common use case of the - sensors devices is to have combined functionality (e.g. light plus proximity - sensor). - </para> - </chapter> - <chapter id='iiosubsys'> - <title>Industrial I/O core</title> - <para> - The Industrial I/O core offers: - <itemizedlist> - <listitem> - a unified framework for writing drivers for many different types of - embedded sensors. - </listitem> - <listitem> - a standard interface to user space applications manipulating sensors. - </listitem> - </itemizedlist> - The implementation can be found under <filename> - drivers/iio/industrialio-*</filename> - </para> - <sect1 id="iiodevice"> - <title> Industrial I/O devices </title> - -!Finclude/linux/iio/iio.h iio_dev -!Fdrivers/iio/industrialio-core.c iio_device_alloc -!Fdrivers/iio/industrialio-core.c iio_device_free -!Fdrivers/iio/industrialio-core.c iio_device_register -!Fdrivers/iio/industrialio-core.c iio_device_unregister - - <para> - An IIO device usually corresponds to a single hardware sensor and it - provides all the information needed by a driver handling a device. - Let's first have a look at the functionality embedded in an IIO - device then we will show how a device driver makes use of an IIO - device. - </para> - <para> - There are two ways for a user space application to interact - with an IIO driver. - <itemizedlist> - <listitem> - <filename>/sys/bus/iio/iio:deviceX/</filename>, this - represents a hardware sensor and groups together the data - channels of the same chip. - </listitem> - <listitem> - <filename>/dev/iio:deviceX</filename>, character device node - interface used for buffered data transfer and for events information - retrieval. - </listitem> - </itemizedlist> - </para> - A typical IIO driver will register itself as an I2C or SPI driver and will - create two routines, <function> probe </function> and <function> remove - </function>. At <function>probe</function>: - <itemizedlist> - <listitem>call <function>iio_device_alloc</function>, which allocates memory - for an IIO device. - </listitem> - <listitem> initialize IIO device fields with driver specific information - (e.g. device name, device channels). - </listitem> - <listitem>call <function> iio_device_register</function>, this registers the - device with the IIO core. After this call the device is ready to accept - requests from user space applications. - </listitem> - </itemizedlist> - At <function>remove</function>, we free the resources allocated in - <function>probe</function> in reverse order: - <itemizedlist> - <listitem><function>iio_device_unregister</function>, unregister the device - from the IIO core. - </listitem> - <listitem><function>iio_device_free</function>, free the memory allocated - for the IIO device. - </listitem> - </itemizedlist> - - <sect2 id="iioattr"> <title> IIO device sysfs interface </title> - <para> - Attributes are sysfs files used to expose chip info and also allowing - applications to set various configuration parameters. For device - with index X, attributes can be found under - <filename>/sys/bus/iio/iio:deviceX/ </filename> directory. - Common attributes are: - <itemizedlist> - <listitem><filename>name</filename>, description of the physical - chip. - </listitem> - <listitem><filename>dev</filename>, shows the major:minor pair - associated with <filename>/dev/iio:deviceX</filename> node. - </listitem> - <listitem><filename>sampling_frequency_available</filename>, - available discrete set of sampling frequency values for - device. - </listitem> - </itemizedlist> - Available standard attributes for IIO devices are described in the - <filename>Documentation/ABI/testing/sysfs-bus-iio </filename> file - in the Linux kernel sources. - </para> - </sect2> - <sect2 id="iiochannel"> <title> IIO device channels </title> -!Finclude/linux/iio/iio.h iio_chan_spec structure. - <para> - An IIO device channel is a representation of a data channel. An - IIO device can have one or multiple channels. For example: - <itemizedlist> - <listitem> - a thermometer sensor has one channel representing the - temperature measurement. - </listitem> - <listitem> - a light sensor with two channels indicating the measurements in - the visible and infrared spectrum. - </listitem> - <listitem> - an accelerometer can have up to 3 channels representing - acceleration on X, Y and Z axes. - </listitem> - </itemizedlist> - An IIO channel is described by the <type> struct iio_chan_spec - </type>. A thermometer driver for the temperature sensor in the - example above would have to describe its channel as follows: - <programlisting> - static const struct iio_chan_spec temp_channel[] = { - { - .type = IIO_TEMP, - .info_mask_separate = BIT(IIO_CHAN_INFO_PROCESSED), - }, - }; - - </programlisting> - Channel sysfs attributes exposed to userspace are specified in - the form of <emphasis>bitmasks</emphasis>. Depending on their - shared info, attributes can be set in one of the following masks: - <itemizedlist> - <listitem><emphasis>info_mask_separate</emphasis>, attributes will - be specific to this channel</listitem> - <listitem><emphasis>info_mask_shared_by_type</emphasis>, - attributes are shared by all channels of the same type</listitem> - <listitem><emphasis>info_mask_shared_by_dir</emphasis>, attributes - are shared by all channels of the same direction </listitem> - <listitem><emphasis>info_mask_shared_by_all</emphasis>, - attributes are shared by all channels</listitem> - </itemizedlist> - When there are multiple data channels per channel type we have two - ways to distinguish between them: - <itemizedlist> - <listitem> set <emphasis> .modified</emphasis> field of <type> - iio_chan_spec</type> to 1. Modifiers are specified using - <emphasis>.channel2</emphasis> field of the same - <type>iio_chan_spec</type> structure and are used to indicate a - physically unique characteristic of the channel such as its direction - or spectral response. For example, a light sensor can have two channels, - one for infrared light and one for both infrared and visible light. - </listitem> - <listitem> set <emphasis>.indexed </emphasis> field of - <type>iio_chan_spec</type> to 1. In this case the channel is - simply another instance with an index specified by the - <emphasis>.channel</emphasis> field. - </listitem> - </itemizedlist> - Here is how we can make use of the channel's modifiers: - <programlisting> - static const struct iio_chan_spec light_channels[] = { - { - .type = IIO_INTENSITY, - .modified = 1, - .channel2 = IIO_MOD_LIGHT_IR, - .info_mask_separate = BIT(IIO_CHAN_INFO_RAW), - .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ), - }, - { - .type = IIO_INTENSITY, - .modified = 1, - .channel2 = IIO_MOD_LIGHT_BOTH, - .info_mask_separate = BIT(IIO_CHAN_INFO_RAW), - .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ), - }, - { - .type = IIO_LIGHT, - .info_mask_separate = BIT(IIO_CHAN_INFO_PROCESSED), - .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ), - }, - - } - </programlisting> - This channel's definition will generate two separate sysfs files - for raw data retrieval: - <itemizedlist> - <listitem> - <filename>/sys/bus/iio/iio:deviceX/in_intensity_ir_raw</filename> - </listitem> - <listitem> - <filename>/sys/bus/iio/iio:deviceX/in_intensity_both_raw</filename> - </listitem> - </itemizedlist> - one file for processed data: - <itemizedlist> - <listitem> - <filename>/sys/bus/iio/iio:deviceX/in_illuminance_input - </filename> - </listitem> - </itemizedlist> - and one shared sysfs file for sampling frequency: - <itemizedlist> - <listitem> - <filename>/sys/bus/iio/iio:deviceX/sampling_frequency. - </filename> - </listitem> - </itemizedlist> - </para> - <para> - Here is how we can make use of the channel's indexing: - <programlisting> - static const struct iio_chan_spec light_channels[] = { - { - .type = IIO_VOLTAGE, - .indexed = 1, - .channel = 0, - .info_mask_separate = BIT(IIO_CHAN_INFO_RAW), - }, - { - .type = IIO_VOLTAGE, - .indexed = 1, - .channel = 1, - .info_mask_separate = BIT(IIO_CHAN_INFO_RAW), - }, - } - </programlisting> - This will generate two separate attributes files for raw data - retrieval: - <itemizedlist> - <listitem> - <filename>/sys/bus/iio/devices/iio:deviceX/in_voltage0_raw</filename>, - representing voltage measurement for channel 0. - </listitem> - <listitem> - <filename>/sys/bus/iio/devices/iio:deviceX/in_voltage1_raw</filename>, - representing voltage measurement for channel 1. - </listitem> - </itemizedlist> - </para> - </sect2> - </sect1> - - <sect1 id="iiobuffer"> <title> Industrial I/O buffers </title> -!Finclude/linux/iio/buffer.h iio_buffer -!Edrivers/iio/industrialio-buffer.c - - <para> - The Industrial I/O core offers a way for continuous data capture - based on a trigger source. Multiple data channels can be read at once - from <filename>/dev/iio:deviceX</filename> character device node, - thus reducing the CPU load. - </para> - - <sect2 id="iiobuffersysfs"> - <title>IIO buffer sysfs interface </title> - <para> - An IIO buffer has an associated attributes directory under <filename> - /sys/bus/iio/iio:deviceX/buffer/</filename>. Here are the existing - attributes: - <itemizedlist> - <listitem> - <emphasis>length</emphasis>, the total number of data samples - (capacity) that can be stored by the buffer. - </listitem> - <listitem> - <emphasis>enable</emphasis>, activate buffer capture. - </listitem> - </itemizedlist> - - </para> - </sect2> - <sect2 id="iiobuffersetup"> <title> IIO buffer setup </title> - <para>The meta information associated with a channel reading - placed in a buffer is called a <emphasis> scan element </emphasis>. - The important bits configuring scan elements are exposed to - userspace applications via the <filename> - /sys/bus/iio/iio:deviceX/scan_elements/</filename> directory. This - file contains attributes of the following form: - <itemizedlist> - <listitem><emphasis>enable</emphasis>, used for enabling a channel. - If and only if its attribute is non zero, then a triggered capture - will contain data samples for this channel. - </listitem> - <listitem><emphasis>type</emphasis>, description of the scan element - data storage within the buffer and hence the form in which it is - read from user space. Format is <emphasis> - [be|le]:[s|u]bits/storagebitsXrepeat[>>shift] </emphasis>. - <itemizedlist> - <listitem> <emphasis>be</emphasis> or <emphasis>le</emphasis>, specifies - big or little endian. - </listitem> - <listitem> - <emphasis>s </emphasis>or <emphasis>u</emphasis>, specifies if - signed (2's complement) or unsigned. - </listitem> - <listitem><emphasis>bits</emphasis>, is the number of valid data - bits. - </listitem> - <listitem><emphasis>storagebits</emphasis>, is the number of bits - (after padding) that it occupies in the buffer. - </listitem> - <listitem> - <emphasis>shift</emphasis>, if specified, is the shift that needs - to be applied prior to masking out unused bits. - </listitem> - <listitem> - <emphasis>repeat</emphasis>, specifies the number of bits/storagebits - repetitions. When the repeat element is 0 or 1, then the repeat - value is omitted. - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - For example, a driver for a 3-axis accelerometer with 12 bit - resolution where data is stored in two 8-bits registers as - follows: - <programlisting> - 7 6 5 4 3 2 1 0 - +---+---+---+---+---+---+---+---+ - |D3 |D2 |D1 |D0 | X | X | X | X | (LOW byte, address 0x06) - +---+---+---+---+---+---+---+---+ - - 7 6 5 4 3 2 1 0 - +---+---+---+---+---+---+---+---+ - |D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIGH byte, address 0x07) - +---+---+---+---+---+---+---+---+ - </programlisting> - - will have the following scan element type for each axis: - <programlisting> - $ cat /sys/bus/iio/devices/iio:device0/scan_elements/in_accel_y_type - le:s12/16>>4 - </programlisting> - A user space application will interpret data samples read from the - buffer as two byte little endian signed data, that needs a 4 bits - right shift before masking out the 12 valid bits of data. - </para> - <para> - For implementing buffer support a driver should initialize the following - fields in <type>iio_chan_spec</type> definition: - <programlisting> - struct iio_chan_spec { - /* other members */ - int scan_index - struct { - char sign; - u8 realbits; - u8 storagebits; - u8 shift; - u8 repeat; - enum iio_endian endianness; - } scan_type; - }; - </programlisting> - The driver implementing the accelerometer described above will - have the following channel definition: - <programlisting> - struct struct iio_chan_spec accel_channels[] = { - { - .type = IIO_ACCEL, - .modified = 1, - .channel2 = IIO_MOD_X, - /* other stuff here */ - .scan_index = 0, - .scan_type = { - .sign = 's', - .realbits = 12, - .storagebits = 16, - .shift = 4, - .endianness = IIO_LE, - }, - } - /* similar for Y (with channel2 = IIO_MOD_Y, scan_index = 1) - * and Z (with channel2 = IIO_MOD_Z, scan_index = 2) axis - */ - } - </programlisting> - </para> - <para> - Here <emphasis> scan_index </emphasis> defines the order in which - the enabled channels are placed inside the buffer. Channels with a lower - scan_index will be placed before channels with a higher index. Each - channel needs to have a unique scan_index. - </para> - <para> - Setting scan_index to -1 can be used to indicate that the specific - channel does not support buffered capture. In this case no entries will - be created for the channel in the scan_elements directory. - </para> - </sect2> - </sect1> - - <sect1 id="iiotrigger"> <title> Industrial I/O triggers </title> -!Finclude/linux/iio/trigger.h iio_trigger -!Edrivers/iio/industrialio-trigger.c - <para> - In many situations it is useful for a driver to be able to - capture data based on some external event (trigger) as opposed - to periodically polling for data. An IIO trigger can be provided - by a device driver that also has an IIO device based on hardware - generated events (e.g. data ready or threshold exceeded) or - provided by a separate driver from an independent interrupt - source (e.g. GPIO line connected to some external system, timer - interrupt or user space writing a specific file in sysfs). A - trigger may initiate data capture for a number of sensors and - also it may be completely unrelated to the sensor itself. - </para> - - <sect2 id="iiotrigsysfs"> <title> IIO trigger sysfs interface </title> - There are two locations in sysfs related to triggers: - <itemizedlist> - <listitem><filename>/sys/bus/iio/devices/triggerY</filename>, - this file is created once an IIO trigger is registered with - the IIO core and corresponds to trigger with index Y. Because - triggers can be very different depending on type there are few - standard attributes that we can describe here: - <itemizedlist> - <listitem> - <emphasis>name</emphasis>, trigger name that can be later - used for association with a device. - </listitem> - <listitem> - <emphasis>sampling_frequency</emphasis>, some timer based - triggers use this attribute to specify the frequency for - trigger calls. - </listitem> - </itemizedlist> - </listitem> - <listitem> - <filename>/sys/bus/iio/devices/iio:deviceX/trigger/</filename>, this - directory is created once the device supports a triggered - buffer. We can associate a trigger with our device by writing - the trigger's name in the <filename>current_trigger</filename> file. - </listitem> - </itemizedlist> - </sect2> - - <sect2 id="iiotrigattr"> <title> IIO trigger setup</title> - - <para> - Let's see a simple example of how to setup a trigger to be used - by a driver. - - <programlisting> - struct iio_trigger_ops trigger_ops = { - .set_trigger_state = sample_trigger_state, - .validate_device = sample_validate_device, - } - - struct iio_trigger *trig; - - /* first, allocate memory for our trigger */ - trig = iio_trigger_alloc(dev, "trig-%s-%d", name, idx); - - /* setup trigger operations field */ - trig->ops = &trigger_ops; - - /* now register the trigger with the IIO core */ - iio_trigger_register(trig); - </programlisting> - </para> - </sect2> - - <sect2 id="iiotrigsetup"> <title> IIO trigger ops</title> -!Finclude/linux/iio/trigger.h iio_trigger_ops - <para> - Notice that a trigger has a set of operations attached: - <itemizedlist> - <listitem> - <function>set_trigger_state</function>, switch the trigger on/off - on demand. - </listitem> - <listitem> - <function>validate_device</function>, function to validate the - device when the current trigger gets changed. - </listitem> - </itemizedlist> - </para> - </sect2> - </sect1> - <sect1 id="iiotriggered_buffer"> - <title> Industrial I/O triggered buffers </title> - <para> - Now that we know what buffers and triggers are let's see how they - work together. - </para> - <sect2 id="iiotrigbufsetup"> <title> IIO triggered buffer setup</title> -!Edrivers/iio/buffer/industrialio-triggered-buffer.c -!Finclude/linux/iio/iio.h iio_buffer_setup_ops - - - <para> - A typical triggered buffer setup looks like this: - <programlisting> - const struct iio_buffer_setup_ops sensor_buffer_setup_ops = { - .preenable = sensor_buffer_preenable, - .postenable = sensor_buffer_postenable, - .postdisable = sensor_buffer_postdisable, - .predisable = sensor_buffer_predisable, - }; - - irqreturn_t sensor_iio_pollfunc(int irq, void *p) - { - pf->timestamp = iio_get_time_ns(); - return IRQ_WAKE_THREAD; - } - - irqreturn_t sensor_trigger_handler(int irq, void *p) - { - u16 buf[8]; - int i = 0; - - /* read data for each active channel */ - for_each_set_bit(bit, active_scan_mask, masklength) - buf[i++] = sensor_get_data(bit) - - iio_push_to_buffers_with_timestamp(indio_dev, buf, timestamp); - - iio_trigger_notify_done(trigger); - return IRQ_HANDLED; - } - - /* setup triggered buffer, usually in probe function */ - iio_triggered_buffer_setup(indio_dev, sensor_iio_polfunc, - sensor_trigger_handler, - sensor_buffer_setup_ops); - </programlisting> - </para> - The important things to notice here are: - <itemizedlist> - <listitem><function> iio_buffer_setup_ops</function>, the buffer setup - functions to be called at predefined points in the buffer configuration - sequence (e.g. before enable, after disable). If not specified, the - IIO core uses the default <type>iio_triggered_buffer_setup_ops</type>. - </listitem> - <listitem><function>sensor_iio_pollfunc</function>, the function that - will be used as top half of poll function. It should do as little - processing as possible, because it runs in interrupt context. The most - common operation is recording of the current timestamp and for this reason - one can use the IIO core defined <function>iio_pollfunc_store_time - </function> function. - </listitem> - <listitem><function>sensor_trigger_handler</function>, the function that - will be used as bottom half of the poll function. This runs in the - context of a kernel thread and all the processing takes place here. - It usually reads data from the device and stores it in the internal - buffer together with the timestamp recorded in the top half. - </listitem> - </itemizedlist> - </sect2> - </sect1> - </chapter> - <chapter id='iioresources'> - <title> Resources </title> - IIO core may change during time so the best documentation to read is the - source code. There are several locations where you should look: - <itemizedlist> - <listitem> - <filename>drivers/iio/</filename>, contains the IIO core plus - and directories for each sensor type (e.g. accel, magnetometer, - etc.) - </listitem> - <listitem> - <filename>include/linux/iio/</filename>, contains the header - files, nice to read for the internal kernel interfaces. - </listitem> - <listitem> - <filename>include/uapi/linux/iio/</filename>, contains files to be - used by user space applications. - </listitem> - <listitem> - <filename>tools/iio/</filename>, contains tools for rapidly - testing buffers, events and device creation. - </listitem> - <listitem> - <filename>drivers/staging/iio/</filename>, contains code for some - drivers or experimental features that are not yet mature enough - to be moved out. - </listitem> - </itemizedlist> - <para> - Besides the code, there are some good online documentation sources: - <itemizedlist> - <listitem> - <ulink url="http://marc.info/?l=linux-iio"> Industrial I/O mailing - list </ulink> - </listitem> - <listitem> - <ulink url="http://wiki.analog.com/software/linux/docs/iio/iio"> - Analog Device IIO wiki page </ulink> - </listitem> - <listitem> - <ulink url="https://fosdem.org/2015/schedule/event/iiosdr/"> - Using the Linux IIO framework for SDR, Lars-Peter Clausen's - presentation at FOSDEM </ulink> - </listitem> - </itemizedlist> - </para> - </chapter> -</book> - -<!-- -vim: softtabstop=2:shiftwidth=2:expandtab:textwidth=72 ---> diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl deleted file mode 100644 index ecfd0ea40661..000000000000 --- a/Documentation/DocBook/kernel-api.tmpl +++ /dev/null @@ -1,331 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="LinuxKernelAPI"> - <bookinfo> - <title>The Linux Kernel API</title> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="adt"> - <title>Data Types</title> - <sect1><title>Doubly Linked Lists</title> -!Iinclude/linux/list.h - </sect1> - </chapter> - - <chapter id="libc"> - <title>Basic C Library Functions</title> - - <para> - When writing drivers, you cannot in general use routines which are - from the C Library. Some of the functions have been found generally - useful and they are listed below. The behaviour of these functions - may vary slightly from those defined by ANSI, and these deviations - are noted in the text. - </para> - - <sect1><title>String Conversions</title> -!Elib/vsprintf.c -!Finclude/linux/kernel.h kstrtol -!Finclude/linux/kernel.h kstrtoul -!Elib/kstrtox.c - </sect1> - <sect1><title>String Manipulation</title> -<!-- All functions are exported at now -X!Ilib/string.c - --> -!Elib/string.c - </sect1> - <sect1><title>Bit Operations</title> -!Iarch/x86/include/asm/bitops.h - </sect1> - </chapter> - - <chapter id="kernel-lib"> - <title>Basic Kernel Library Functions</title> - - <para> - The Linux kernel provides more basic utility functions. - </para> - - <sect1><title>Bitmap Operations</title> -!Elib/bitmap.c -!Ilib/bitmap.c - </sect1> - - <sect1><title>Command-line Parsing</title> -!Elib/cmdline.c - </sect1> - - <sect1 id="crc"><title>CRC Functions</title> -!Elib/crc7.c -!Elib/crc16.c -!Elib/crc-itu-t.c -!Elib/crc32.c -!Elib/crc-ccitt.c - </sect1> - - <sect1 id="idr"><title>idr/ida Functions</title> -!Pinclude/linux/idr.h idr sync -!Plib/idr.c IDA description -!Elib/idr.c - </sect1> - </chapter> - - <chapter id="mm"> - <title>Memory Management in Linux</title> - <sect1><title>The Slab Cache</title> -!Iinclude/linux/slab.h -!Emm/slab.c -!Emm/util.c - </sect1> - <sect1><title>User Space Memory Access</title> -!Iarch/x86/include/asm/uaccess_32.h -!Earch/x86/lib/usercopy_32.c - </sect1> - <sect1><title>More Memory Management Functions</title> -!Emm/readahead.c -!Emm/filemap.c -!Emm/memory.c -!Emm/vmalloc.c -!Imm/page_alloc.c -!Emm/mempool.c -!Emm/dmapool.c -!Emm/page-writeback.c -!Emm/truncate.c - </sect1> - </chapter> - - - <chapter id="ipc"> - <title>Kernel IPC facilities</title> - - <sect1><title>IPC utilities</title> -!Iipc/util.c - </sect1> - </chapter> - - <chapter id="kfifo"> - <title>FIFO Buffer</title> - <sect1><title>kfifo interface</title> -!Iinclude/linux/kfifo.h - </sect1> - </chapter> - - <chapter id="relayfs"> - <title>relay interface support</title> - - <para> - Relay interface support - is designed to provide an efficient mechanism for tools and - facilities to relay large amounts of data from kernel space to - user space. - </para> - - <sect1><title>relay interface</title> -!Ekernel/relay.c -!Ikernel/relay.c - </sect1> - </chapter> - - <chapter id="modload"> - <title>Module Support</title> - <sect1><title>Module Loading</title> -!Ekernel/kmod.c - </sect1> - <sect1><title>Inter Module support</title> - <para> - Refer to the file kernel/module.c for more information. - </para> -<!-- FIXME: Removed for now since no structured comments in source -X!Ekernel/module.c ---> - </sect1> - </chapter> - - <chapter id="hardware"> - <title>Hardware Interfaces</title> - <sect1><title>Interrupt Handling</title> -!Ekernel/irq/manage.c - </sect1> - - <sect1><title>DMA Channels</title> -!Ekernel/dma.c - </sect1> - - <sect1><title>Resources Management</title> -!Ikernel/resource.c -!Ekernel/resource.c - </sect1> - - <sect1><title>MTRR Handling</title> -!Earch/x86/kernel/cpu/mtrr/main.c - </sect1> - - <sect1><title>PCI Support Library</title> -!Edrivers/pci/pci.c -!Edrivers/pci/pci-driver.c -!Edrivers/pci/remove.c -!Edrivers/pci/search.c -!Edrivers/pci/msi.c -!Edrivers/pci/bus.c -!Edrivers/pci/access.c -!Edrivers/pci/irq.c -!Edrivers/pci/htirq.c -<!-- FIXME: Removed for now since no structured comments in source -X!Edrivers/pci/hotplug.c ---> -!Edrivers/pci/probe.c -!Edrivers/pci/slot.c -!Edrivers/pci/rom.c -!Edrivers/pci/iov.c -!Idrivers/pci/pci-sysfs.c - </sect1> - <sect1><title>PCI Hotplug Support Library</title> -!Edrivers/pci/hotplug/pci_hotplug_core.c - </sect1> - </chapter> - - <chapter id="firmware"> - <title>Firmware Interfaces</title> - <sect1><title>DMI Interfaces</title> -!Edrivers/firmware/dmi_scan.c - </sect1> - <sect1><title>EDD Interfaces</title> -!Idrivers/firmware/edd.c - </sect1> - </chapter> - - <chapter id="security"> - <title>Security Framework</title> -!Isecurity/security.c -!Esecurity/inode.c - </chapter> - - <chapter id="audit"> - <title>Audit Interfaces</title> -!Ekernel/audit.c -!Ikernel/auditsc.c -!Ikernel/auditfilter.c - </chapter> - - <chapter id="accounting"> - <title>Accounting Framework</title> -!Ikernel/acct.c - </chapter> - - <chapter id="blkdev"> - <title>Block Devices</title> -!Eblock/blk-core.c -!Iblock/blk-core.c -!Eblock/blk-map.c -!Iblock/blk-sysfs.c -!Eblock/blk-settings.c -!Eblock/blk-exec.c -!Eblock/blk-flush.c -!Eblock/blk-lib.c -!Eblock/blk-tag.c -!Iblock/blk-tag.c -!Eblock/blk-integrity.c -!Ikernel/trace/blktrace.c -!Iblock/genhd.c -!Eblock/genhd.c - </chapter> - - <chapter id="chrdev"> - <title>Char devices</title> -!Efs/char_dev.c - </chapter> - - <chapter id="miscdev"> - <title>Miscellaneous Devices</title> -!Edrivers/char/misc.c - </chapter> - - <chapter id="clk"> - <title>Clock Framework</title> - - <para> - The clock framework defines programming interfaces to support - software management of the system clock tree. - This framework is widely used with System-On-Chip (SOC) platforms - to support power management and various devices which may need - custom clock rates. - Note that these "clocks" don't relate to timekeeping or real - time clocks (RTCs), each of which have separate frameworks. - These <structname>struct clk</structname> instances may be used - to manage for example a 96 MHz signal that is used to shift bits - into and out of peripherals or busses, or otherwise trigger - synchronous state machine transitions in system hardware. - </para> - - <para> - Power management is supported by explicit software clock gating: - unused clocks are disabled, so the system doesn't waste power - changing the state of transistors that aren't in active use. - On some systems this may be backed by hardware clock gating, - where clocks are gated without being disabled in software. - Sections of chips that are powered but not clocked may be able - to retain their last state. - This low power state is often called a <emphasis>retention - mode</emphasis>. - This mode still incurs leakage currents, especially with finer - circuit geometries, but for CMOS circuits power is mostly used - by clocked state changes. - </para> - - <para> - Power-aware drivers only enable their clocks when the device - they manage is in active use. Also, system sleep states often - differ according to which clock domains are active: while a - "standby" state may allow wakeup from several active domains, a - "mem" (suspend-to-RAM) state may require a more wholesale shutdown - of clocks derived from higher speed PLLs and oscillators, limiting - the number of possible wakeup event sources. A driver's suspend - method may need to be aware of system-specific clock constraints - on the target sleep state. - </para> - - <para> - Some platforms support programmable clock generators. These - can be used by external chips of various kinds, such as other - CPUs, multimedia codecs, and devices with strict requirements - for interface clocking. - </para> - -!Iinclude/linux/clk.h - </chapter> - -</book> diff --git a/Documentation/DocBook/kernel-hacking.tmpl b/Documentation/DocBook/kernel-hacking.tmpl deleted file mode 100644 index 589b40cc5eb5..000000000000 --- a/Documentation/DocBook/kernel-hacking.tmpl +++ /dev/null @@ -1,1312 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="lk-hacking-guide"> - <bookinfo> - <title>Unreliable Guide To Hacking The Linux Kernel</title> - - <authorgroup> - <author> - <firstname>Rusty</firstname> - <surname>Russell</surname> - <affiliation> - <address> - <email>rusty@rustcorp.com.au</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2005</year> - <holder>Rusty Russell</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - - <releaseinfo> - This is the first release of this document as part of the kernel tarball. - </releaseinfo> - - </bookinfo> - - <toc></toc> - - <chapter id="introduction"> - <title>Introduction</title> - <para> - Welcome, gentle reader, to Rusty's Remarkably Unreliable Guide to Linux - Kernel Hacking. This document describes the common routines and - general requirements for kernel code: its goal is to serve as a - primer for Linux kernel development for experienced C - programmers. I avoid implementation details: that's what the - code is for, and I ignore whole tracts of useful routines. - </para> - <para> - Before you read this, please understand that I never wanted to - write this document, being grossly under-qualified, but I always - wanted to read it, and this was the only way. I hope it will - grow into a compendium of best practice, common starting points - and random information. - </para> - </chapter> - - <chapter id="basic-players"> - <title>The Players</title> - - <para> - At any time each of the CPUs in a system can be: - </para> - - <itemizedlist> - <listitem> - <para> - not associated with any process, serving a hardware interrupt; - </para> - </listitem> - - <listitem> - <para> - not associated with any process, serving a softirq or tasklet; - </para> - </listitem> - - <listitem> - <para> - running in kernel space, associated with a process (user context); - </para> - </listitem> - - <listitem> - <para> - running a process in user space. - </para> - </listitem> - </itemizedlist> - - <para> - There is an ordering between these. The bottom two can preempt - each other, but above that is a strict hierarchy: each can only be - preempted by the ones above it. For example, while a softirq is - running on a CPU, no other softirq will preempt it, but a hardware - interrupt can. However, any other CPUs in the system execute - independently. - </para> - - <para> - We'll see a number of ways that the user context can block - interrupts, to become truly non-preemptable. - </para> - - <sect1 id="basics-usercontext"> - <title>User Context</title> - - <para> - User context is when you are coming in from a system call or other - trap: like userspace, you can be preempted by more important tasks - and by interrupts. You can sleep, by calling - <function>schedule()</function>. - </para> - - <note> - <para> - You are always in user context on module load and unload, - and on operations on the block device layer. - </para> - </note> - - <para> - In user context, the <varname>current</varname> pointer (indicating - the task we are currently executing) is valid, and - <function>in_interrupt()</function> - (<filename>include/linux/interrupt.h</filename>) is <returnvalue>false - </returnvalue>. - </para> - - <caution> - <para> - Beware that if you have preemption or softirqs disabled - (see below), <function>in_interrupt()</function> will return a - false positive. - </para> - </caution> - </sect1> - - <sect1 id="basics-hardirqs"> - <title>Hardware Interrupts (Hard IRQs)</title> - - <para> - Timer ticks, <hardware>network cards</hardware> and - <hardware>keyboard</hardware> are examples of real - hardware which produce interrupts at any time. The kernel runs - interrupt handlers, which services the hardware. The kernel - guarantees that this handler is never re-entered: if the same - interrupt arrives, it is queued (or dropped). Because it - disables interrupts, this handler has to be fast: frequently it - simply acknowledges the interrupt, marks a 'software interrupt' - for execution and exits. - </para> - - <para> - You can tell you are in a hardware interrupt, because - <function>in_irq()</function> returns <returnvalue>true</returnvalue>. - </para> - <caution> - <para> - Beware that this will return a false positive if interrupts are disabled - (see below). - </para> - </caution> - </sect1> - - <sect1 id="basics-softirqs"> - <title>Software Interrupt Context: Softirqs and Tasklets</title> - - <para> - Whenever a system call is about to return to userspace, or a - hardware interrupt handler exits, any 'software interrupts' - which are marked pending (usually by hardware interrupts) are - run (<filename>kernel/softirq.c</filename>). - </para> - - <para> - Much of the real interrupt handling work is done here. Early in - the transition to <acronym>SMP</acronym>, there were only 'bottom - halves' (BHs), which didn't take advantage of multiple CPUs. Shortly - after we switched from wind-up computers made of match-sticks and snot, - we abandoned this limitation and switched to 'softirqs'. - </para> - - <para> - <filename class="headerfile">include/linux/interrupt.h</filename> lists the - different softirqs. A very important softirq is the - timer softirq (<filename - class="headerfile">include/linux/timer.h</filename>): you can - register to have it call functions for you in a given length of - time. - </para> - - <para> - Softirqs are often a pain to deal with, since the same softirq - will run simultaneously on more than one CPU. For this reason, - tasklets (<filename - class="headerfile">include/linux/interrupt.h</filename>) are more - often used: they are dynamically-registrable (meaning you can have - as many as you want), and they also guarantee that any tasklet - will only run on one CPU at any time, although different tasklets - can run simultaneously. - </para> - <caution> - <para> - The name 'tasklet' is misleading: they have nothing to do with 'tasks', - and probably more to do with some bad vodka Alexey Kuznetsov had at the - time. - </para> - </caution> - - <para> - You can tell you are in a softirq (or tasklet) - using the <function>in_softirq()</function> macro - (<filename class="headerfile">include/linux/interrupt.h</filename>). - </para> - <caution> - <para> - Beware that this will return a false positive if a bh lock (see below) - is held. - </para> - </caution> - </sect1> - </chapter> - - <chapter id="basic-rules"> - <title>Some Basic Rules</title> - - <variablelist> - <varlistentry> - <term>No memory protection</term> - <listitem> - <para> - If you corrupt memory, whether in user context or - interrupt context, the whole machine will crash. Are you - sure you can't do what you want in userspace? - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>No floating point or <acronym>MMX</acronym></term> - <listitem> - <para> - The <acronym>FPU</acronym> context is not saved; even in user - context the <acronym>FPU</acronym> state probably won't - correspond with the current process: you would mess with some - user process' <acronym>FPU</acronym> state. If you really want - to do this, you would have to explicitly save/restore the full - <acronym>FPU</acronym> state (and avoid context switches). It - is generally a bad idea; use fixed point arithmetic first. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>A rigid stack limit</term> - <listitem> - <para> - Depending on configuration options the kernel stack is about 3K to 6K for most 32-bit architectures: it's - about 14K on most 64-bit archs, and often shared with interrupts - so you can't use it all. Avoid deep recursion and huge local - arrays on the stack (allocate them dynamically instead). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>The Linux kernel is portable</term> - <listitem> - <para> - Let's keep it that way. Your code should be 64-bit clean, - and endian-independent. You should also minimize CPU - specific stuff, e.g. inline assembly should be cleanly - encapsulated and minimized to ease porting. Generally it - should be restricted to the architecture-dependent part of - the kernel tree. - </para> - </listitem> - </varlistentry> - </variablelist> - </chapter> - - <chapter id="ioctls"> - <title>ioctls: Not writing a new system call</title> - - <para> - A system call generally looks like this - </para> - - <programlisting> -asmlinkage long sys_mycall(int arg) -{ - return 0; -} - </programlisting> - - <para> - First, in most cases you don't want to create a new system call. - You create a character device and implement an appropriate ioctl - for it. This is much more flexible than system calls, doesn't have - to be entered in every architecture's - <filename class="headerfile">include/asm/unistd.h</filename> and - <filename>arch/kernel/entry.S</filename> file, and is much more - likely to be accepted by Linus. - </para> - - <para> - If all your routine does is read or write some parameter, consider - implementing a <function>sysfs</function> interface instead. - </para> - - <para> - Inside the ioctl you're in user context to a process. When a - error occurs you return a negated errno (see - <filename class="headerfile">include/linux/errno.h</filename>), - otherwise you return <returnvalue>0</returnvalue>. - </para> - - <para> - After you slept you should check if a signal occurred: the - Unix/Linux way of handling signals is to temporarily exit the - system call with the <constant>-ERESTARTSYS</constant> error. The - system call entry code will switch back to user context, process - the signal handler and then your system call will be restarted - (unless the user disabled that). So you should be prepared to - process the restart, e.g. if you're in the middle of manipulating - some data structure. - </para> - - <programlisting> -if (signal_pending(current)) - return -ERESTARTSYS; - </programlisting> - - <para> - If you're doing longer computations: first think userspace. If you - <emphasis>really</emphasis> want to do it in kernel you should - regularly check if you need to give up the CPU (remember there is - cooperative multitasking per CPU). Idiom: - </para> - - <programlisting> -cond_resched(); /* Will sleep */ - </programlisting> - - <para> - A short note on interface design: the UNIX system call motto is - "Provide mechanism not policy". - </para> - </chapter> - - <chapter id="deadlock-recipes"> - <title>Recipes for Deadlock</title> - - <para> - You cannot call any routines which may sleep, unless: - </para> - <itemizedlist> - <listitem> - <para> - You are in user context. - </para> - </listitem> - - <listitem> - <para> - You do not own any spinlocks. - </para> - </listitem> - - <listitem> - <para> - You have interrupts enabled (actually, Andi Kleen says - that the scheduling code will enable them for you, but - that's probably not what you wanted). - </para> - </listitem> - </itemizedlist> - - <para> - Note that some functions may sleep implicitly: common ones are - the user space access functions (*_user) and memory allocation - functions without <symbol>GFP_ATOMIC</symbol>. - </para> - - <para> - You should always compile your kernel - <symbol>CONFIG_DEBUG_ATOMIC_SLEEP</symbol> on, and it will warn - you if you break these rules. If you <emphasis>do</emphasis> break - the rules, you will eventually lock up your box. - </para> - - <para> - Really. - </para> - </chapter> - - <chapter id="common-routines"> - <title>Common Routines</title> - - <sect1 id="routines-printk"> - <title> - <function>printk()</function> - <filename class="headerfile">include/linux/kernel.h</filename> - </title> - - <para> - <function>printk()</function> feeds kernel messages to the - console, dmesg, and the syslog daemon. It is useful for debugging - and reporting errors, and can be used inside interrupt context, - but use with caution: a machine which has its console flooded with - printk messages is unusable. It uses a format string mostly - compatible with ANSI C printf, and C string concatenation to give - it a first "priority" argument: - </para> - - <programlisting> -printk(KERN_INFO "i = %u\n", i); - </programlisting> - - <para> - See <filename class="headerfile">include/linux/kernel.h</filename>; - for other KERN_ values; these are interpreted by syslog as the - level. Special case: for printing an IP address use - </para> - - <programlisting> -__be32 ipaddress; -printk(KERN_INFO "my ip: %pI4\n", &ipaddress); - </programlisting> - - <para> - <function>printk()</function> internally uses a 1K buffer and does - not catch overruns. Make sure that will be enough. - </para> - - <note> - <para> - You will know when you are a real kernel hacker - when you start typoing printf as printk in your user programs :) - </para> - </note> - - <!--- From the Lions book reader department --> - - <note> - <para> - Another sidenote: the original Unix Version 6 sources had a - comment on top of its printf function: "Printf should not be - used for chit-chat". You should follow that advice. - </para> - </note> - </sect1> - - <sect1 id="routines-copy"> - <title> - <function>copy_[to/from]_user()</function> - / - <function>get_user()</function> - / - <function>put_user()</function> - <filename class="headerfile">include/asm/uaccess.h</filename> - </title> - - <para> - <emphasis>[SLEEPS]</emphasis> - </para> - - <para> - <function>put_user()</function> and <function>get_user()</function> - are used to get and put single values (such as an int, char, or - long) from and to userspace. A pointer into userspace should - never be simply dereferenced: data should be copied using these - routines. Both return <constant>-EFAULT</constant> or 0. - </para> - <para> - <function>copy_to_user()</function> and - <function>copy_from_user()</function> are more general: they copy - an arbitrary amount of data to and from userspace. - <caution> - <para> - Unlike <function>put_user()</function> and - <function>get_user()</function>, they return the amount of - uncopied data (ie. <returnvalue>0</returnvalue> still means - success). - </para> - </caution> - [Yes, this moronic interface makes me cringe. The flamewar comes up every year or so. --RR.] - </para> - <para> - The functions may sleep implicitly. This should never be called - outside user context (it makes no sense), with interrupts - disabled, or a spinlock held. - </para> - </sect1> - - <sect1 id="routines-kmalloc"> - <title><function>kmalloc()</function>/<function>kfree()</function> - <filename class="headerfile">include/linux/slab.h</filename></title> - - <para> - <emphasis>[MAY SLEEP: SEE BELOW]</emphasis> - </para> - - <para> - These routines are used to dynamically request pointer-aligned - chunks of memory, like malloc and free do in userspace, but - <function>kmalloc()</function> takes an extra flag word. - Important values: - </para> - - <variablelist> - <varlistentry> - <term> - <constant> - GFP_KERNEL - </constant> - </term> - <listitem> - <para> - May sleep and swap to free memory. Only allowed in user - context, but is the most reliable way to allocate memory. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <constant> - GFP_ATOMIC - </constant> - </term> - <listitem> - <para> - Don't sleep. Less reliable than <constant>GFP_KERNEL</constant>, - but may be called from interrupt context. You should - <emphasis>really</emphasis> have a good out-of-memory - error-handling strategy. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <constant> - GFP_DMA - </constant> - </term> - <listitem> - <para> - Allocate ISA DMA lower than 16MB. If you don't know what that - is you don't need it. Very unreliable. - </para> - </listitem> - </varlistentry> - </variablelist> - - <para> - If you see a <errorname>sleeping function called from invalid - context</errorname> warning message, then maybe you called a - sleeping allocation function from interrupt context without - <constant>GFP_ATOMIC</constant>. You should really fix that. - Run, don't walk. - </para> - - <para> - If you are allocating at least <constant>PAGE_SIZE</constant> - (<filename class="headerfile">include/asm/page.h</filename>) bytes, - consider using <function>__get_free_pages()</function> - - (<filename class="headerfile">include/linux/mm.h</filename>). It - takes an order argument (0 for page sized, 1 for double page, 2 - for four pages etc.) and the same memory priority flag word as - above. - </para> - - <para> - If you are allocating more than a page worth of bytes you can use - <function>vmalloc()</function>. It'll allocate virtual memory in - the kernel map. This block is not contiguous in physical memory, - but the <acronym>MMU</acronym> makes it look like it is for you - (so it'll only look contiguous to the CPUs, not to external device - drivers). If you really need large physically contiguous memory - for some weird device, you have a problem: it is poorly supported - in Linux because after some time memory fragmentation in a running - kernel makes it hard. The best way is to allocate the block early - in the boot process via the <function>alloc_bootmem()</function> - routine. - </para> - - <para> - Before inventing your own cache of often-used objects consider - using a slab cache in - <filename class="headerfile">include/linux/slab.h</filename> - </para> - </sect1> - - <sect1 id="routines-current"> - <title><function>current</function> - <filename class="headerfile">include/asm/current.h</filename></title> - - <para> - This global variable (really a macro) contains a pointer to - the current task structure, so is only valid in user context. - For example, when a process makes a system call, this will - point to the task structure of the calling process. It is - <emphasis>not NULL</emphasis> in interrupt context. - </para> - </sect1> - - <sect1 id="routines-udelay"> - <title><function>mdelay()</function>/<function>udelay()</function> - <filename class="headerfile">include/asm/delay.h</filename> - <filename class="headerfile">include/linux/delay.h</filename> - </title> - - <para> - The <function>udelay()</function> and <function>ndelay()</function> functions can be used for small pauses. - Do not use large values with them as you risk - overflow - the helper function <function>mdelay()</function> is useful - here, or consider <function>msleep()</function>. - </para> - </sect1> - - <sect1 id="routines-endian"> - <title><function>cpu_to_be32()</function>/<function>be32_to_cpu()</function>/<function>cpu_to_le32()</function>/<function>le32_to_cpu()</function> - <filename class="headerfile">include/asm/byteorder.h</filename> - </title> - - <para> - The <function>cpu_to_be32()</function> family (where the "32" can - be replaced by 64 or 16, and the "be" can be replaced by "le") are - the general way to do endian conversions in the kernel: they - return the converted value. All variations supply the reverse as - well: <function>be32_to_cpu()</function>, etc. - </para> - - <para> - There are two major variations of these functions: the pointer - variation, such as <function>cpu_to_be32p()</function>, which take - a pointer to the given type, and return the converted value. The - other variation is the "in-situ" family, such as - <function>cpu_to_be32s()</function>, which convert value referred - to by the pointer, and return void. - </para> - </sect1> - - <sect1 id="routines-local-irqs"> - <title><function>local_irq_save()</function>/<function>local_irq_restore()</function> - <filename class="headerfile">include/linux/irqflags.h</filename> - </title> - - <para> - These routines disable hard interrupts on the local CPU, and - restore them. They are reentrant; saving the previous state in - their one <varname>unsigned long flags</varname> argument. If you - know that interrupts are enabled, you can simply use - <function>local_irq_disable()</function> and - <function>local_irq_enable()</function>. - </para> - </sect1> - - <sect1 id="routines-softirqs"> - <title><function>local_bh_disable()</function>/<function>local_bh_enable()</function> - <filename class="headerfile">include/linux/interrupt.h</filename></title> - - <para> - These routines disable soft interrupts on the local CPU, and - restore them. They are reentrant; if soft interrupts were - disabled before, they will still be disabled after this pair - of functions has been called. They prevent softirqs and tasklets - from running on the current CPU. - </para> - </sect1> - - <sect1 id="routines-processorids"> - <title><function>smp_processor_id</function>() - <filename class="headerfile">include/asm/smp.h</filename></title> - - <para> - <function>get_cpu()</function> disables preemption (so you won't - suddenly get moved to another CPU) and returns the current - processor number, between 0 and <symbol>NR_CPUS</symbol>. Note - that the CPU numbers are not necessarily continuous. You return - it again with <function>put_cpu()</function> when you are done. - </para> - <para> - If you know you cannot be preempted by another task (ie. you are - in interrupt context, or have preemption disabled) you can use - smp_processor_id(). - </para> - </sect1> - - <sect1 id="routines-init"> - <title><type>__init</type>/<type>__exit</type>/<type>__initdata</type> - <filename class="headerfile">include/linux/init.h</filename></title> - - <para> - After boot, the kernel frees up a special section; functions - marked with <type>__init</type> and data structures marked with - <type>__initdata</type> are dropped after boot is complete: similarly - modules discard this memory after initialization. <type>__exit</type> - is used to declare a function which is only required on exit: the - function will be dropped if this file is not compiled as a module. - See the header file for use. Note that it makes no sense for a function - marked with <type>__init</type> to be exported to modules with - <function>EXPORT_SYMBOL()</function> - this will break. - </para> - - </sect1> - - <sect1 id="routines-init-again"> - <title><function>__initcall()</function>/<function>module_init()</function> - <filename class="headerfile">include/linux/init.h</filename></title> - <para> - Many parts of the kernel are well served as a module - (dynamically-loadable parts of the kernel). Using the - <function>module_init()</function> and - <function>module_exit()</function> macros it is easy to write code - without #ifdefs which can operate both as a module or built into - the kernel. - </para> - - <para> - The <function>module_init()</function> macro defines which - function is to be called at module insertion time (if the file is - compiled as a module), or at boot time: if the file is not - compiled as a module the <function>module_init()</function> macro - becomes equivalent to <function>__initcall()</function>, which - through linker magic ensures that the function is called on boot. - </para> - - <para> - The function can return a negative error number to cause - module loading to fail (unfortunately, this has no effect if - the module is compiled into the kernel). This function is - called in user context with interrupts enabled, so it can sleep. - </para> - </sect1> - - <sect1 id="routines-moduleexit"> - <title> <function>module_exit()</function> - <filename class="headerfile">include/linux/init.h</filename> </title> - - <para> - This macro defines the function to be called at module removal - time (or never, in the case of the file compiled into the - kernel). It will only be called if the module usage count has - reached zero. This function can also sleep, but cannot fail: - everything must be cleaned up by the time it returns. - </para> - - <para> - Note that this macro is optional: if it is not present, your - module will not be removable (except for 'rmmod -f'). - </para> - </sect1> - - <sect1 id="routines-module-use-counters"> - <title> <function>try_module_get()</function>/<function>module_put()</function> - <filename class="headerfile">include/linux/module.h</filename></title> - - <para> - These manipulate the module usage count, to protect against - removal (a module also can't be removed if another module uses one - of its exported symbols: see below). Before calling into module - code, you should call <function>try_module_get()</function> on - that module: if it fails, then the module is being removed and you - should act as if it wasn't there. Otherwise, you can safely enter - the module, and call <function>module_put()</function> when you're - finished. - </para> - - <para> - Most registerable structures have an - <structfield>owner</structfield> field, such as in the - <structname>file_operations</structname> structure. Set this field - to the macro <symbol>THIS_MODULE</symbol>. - </para> - </sect1> - - <!-- add info on new-style module refcounting here --> - </chapter> - - <chapter id="queues"> - <title>Wait Queues - <filename class="headerfile">include/linux/wait.h</filename> - </title> - <para> - <emphasis>[SLEEPS]</emphasis> - </para> - - <para> - A wait queue is used to wait for someone to wake you up when a - certain condition is true. They must be used carefully to ensure - there is no race condition. You declare a - <type>wait_queue_head_t</type>, and then processes which want to - wait for that condition declare a <type>wait_queue_t</type> - referring to themselves, and place that in the queue. - </para> - - <sect1 id="queue-declaring"> - <title>Declaring</title> - - <para> - You declare a <type>wait_queue_head_t</type> using the - <function>DECLARE_WAIT_QUEUE_HEAD()</function> macro, or using the - <function>init_waitqueue_head()</function> routine in your - initialization code. - </para> - </sect1> - - <sect1 id="queue-waitqueue"> - <title>Queuing</title> - - <para> - Placing yourself in the waitqueue is fairly complex, because you - must put yourself in the queue before checking the condition. - There is a macro to do this: - <function>wait_event_interruptible()</function> - - <filename class="headerfile">include/linux/wait.h</filename> The - first argument is the wait queue head, and the second is an - expression which is evaluated; the macro returns - <returnvalue>0</returnvalue> when this expression is true, or - <returnvalue>-ERESTARTSYS</returnvalue> if a signal is received. - The <function>wait_event()</function> version ignores signals. - </para> - - </sect1> - - <sect1 id="queue-waking"> - <title>Waking Up Queued Tasks</title> - - <para> - Call <function>wake_up()</function> - - <filename class="headerfile">include/linux/wait.h</filename>;, - which will wake up every process in the queue. The exception is - if one has <constant>TASK_EXCLUSIVE</constant> set, in which case - the remainder of the queue will not be woken. There are other variants - of this basic function available in the same header. - </para> - </sect1> - </chapter> - - <chapter id="atomic-ops"> - <title>Atomic Operations</title> - - <para> - Certain operations are guaranteed atomic on all platforms. The - first class of operations work on <type>atomic_t</type> - - <filename class="headerfile">include/asm/atomic.h</filename>; this - contains a signed integer (at least 32 bits long), and you must use - these functions to manipulate or read atomic_t variables. - <function>atomic_read()</function> and - <function>atomic_set()</function> get and set the counter, - <function>atomic_add()</function>, - <function>atomic_sub()</function>, - <function>atomic_inc()</function>, - <function>atomic_dec()</function>, and - <function>atomic_dec_and_test()</function> (returns - <returnvalue>true</returnvalue> if it was decremented to zero). - </para> - - <para> - Yes. It returns <returnvalue>true</returnvalue> (i.e. != 0) if the - atomic variable is zero. - </para> - - <para> - Note that these functions are slower than normal arithmetic, and - so should not be used unnecessarily. - </para> - - <para> - The second class of atomic operations is atomic bit operations on an - <type>unsigned long</type>, defined in - - <filename class="headerfile">include/linux/bitops.h</filename>. These - operations generally take a pointer to the bit pattern, and a bit - number: 0 is the least significant bit. - <function>set_bit()</function>, <function>clear_bit()</function> - and <function>change_bit()</function> set, clear, and flip the - given bit. <function>test_and_set_bit()</function>, - <function>test_and_clear_bit()</function> and - <function>test_and_change_bit()</function> do the same thing, - except return true if the bit was previously set; these are - particularly useful for atomically setting flags. - </para> - - <para> - It is possible to call these operations with bit indices greater - than BITS_PER_LONG. The resulting behavior is strange on big-endian - platforms though so it is a good idea not to do this. - </para> - </chapter> - - <chapter id="symbols"> - <title>Symbols</title> - - <para> - Within the kernel proper, the normal linking rules apply - (ie. unless a symbol is declared to be file scope with the - <type>static</type> keyword, it can be used anywhere in the - kernel). However, for modules, a special exported symbol table is - kept which limits the entry points to the kernel proper. Modules - can also export symbols. - </para> - - <sect1 id="sym-exportsymbols"> - <title><function>EXPORT_SYMBOL()</function> - <filename class="headerfile">include/linux/export.h</filename></title> - - <para> - This is the classic method of exporting a symbol: dynamically - loaded modules will be able to use the symbol as normal. - </para> - </sect1> - - <sect1 id="sym-exportsymbols-gpl"> - <title><function>EXPORT_SYMBOL_GPL()</function> - <filename class="headerfile">include/linux/export.h</filename></title> - - <para> - Similar to <function>EXPORT_SYMBOL()</function> except that the - symbols exported by <function>EXPORT_SYMBOL_GPL()</function> can - only be seen by modules with a - <function>MODULE_LICENSE()</function> that specifies a GPL - compatible license. It implies that the function is considered - an internal implementation issue, and not really an interface. - Some maintainers and developers may however - require EXPORT_SYMBOL_GPL() when adding any new APIs or functionality. - </para> - </sect1> - </chapter> - - <chapter id="conventions"> - <title>Routines and Conventions</title> - - <sect1 id="conventions-doublelinkedlist"> - <title>Double-linked lists - <filename class="headerfile">include/linux/list.h</filename></title> - - <para> - There used to be three sets of linked-list routines in the kernel - headers, but this one is the winner. If you don't have some - particular pressing need for a single list, it's a good choice. - </para> - - <para> - In particular, <function>list_for_each_entry</function> is useful. - </para> - </sect1> - - <sect1 id="convention-returns"> - <title>Return Conventions</title> - - <para> - For code called in user context, it's very common to defy C - convention, and return <returnvalue>0</returnvalue> for success, - and a negative error number - (eg. <returnvalue>-EFAULT</returnvalue>) for failure. This can be - unintuitive at first, but it's fairly widespread in the kernel. - </para> - - <para> - Using <function>ERR_PTR()</function> - - <filename class="headerfile">include/linux/err.h</filename>; to - encode a negative error number into a pointer, and - <function>IS_ERR()</function> and <function>PTR_ERR()</function> - to get it back out again: avoids a separate pointer parameter for - the error number. Icky, but in a good way. - </para> - </sect1> - - <sect1 id="conventions-borkedcompile"> - <title>Breaking Compilation</title> - - <para> - Linus and the other developers sometimes change function or - structure names in development kernels; this is not done just to - keep everyone on their toes: it reflects a fundamental change - (eg. can no longer be called with interrupts on, or does extra - checks, or doesn't do checks which were caught before). Usually - this is accompanied by a fairly complete note to the linux-kernel - mailing list; search the archive. Simply doing a global replace - on the file usually makes things <emphasis>worse</emphasis>. - </para> - </sect1> - - <sect1 id="conventions-initialising"> - <title>Initializing structure members</title> - - <para> - The preferred method of initializing structures is to use - designated initialisers, as defined by ISO C99, eg: - </para> - <programlisting> -static struct block_device_operations opt_fops = { - .open = opt_open, - .release = opt_release, - .ioctl = opt_ioctl, - .check_media_change = opt_media_change, -}; - </programlisting> - <para> - This makes it easy to grep for, and makes it clear which - structure fields are set. You should do this because it looks - cool. - </para> - </sect1> - - <sect1 id="conventions-gnu-extns"> - <title>GNU Extensions</title> - - <para> - GNU Extensions are explicitly allowed in the Linux kernel. - Note that some of the more complex ones are not very well - supported, due to lack of general use, but the following are - considered standard (see the GCC info page section "C - Extensions" for more details - Yes, really the info page, the - man page is only a short summary of the stuff in info). - </para> - <itemizedlist> - <listitem> - <para> - Inline functions - </para> - </listitem> - <listitem> - <para> - Statement expressions (ie. the ({ and }) constructs). - </para> - </listitem> - <listitem> - <para> - Declaring attributes of a function / variable / type - (__attribute__) - </para> - </listitem> - <listitem> - <para> - typeof - </para> - </listitem> - <listitem> - <para> - Zero length arrays - </para> - </listitem> - <listitem> - <para> - Macro varargs - </para> - </listitem> - <listitem> - <para> - Arithmetic on void pointers - </para> - </listitem> - <listitem> - <para> - Non-Constant initializers - </para> - </listitem> - <listitem> - <para> - Assembler Instructions (not outside arch/ and include/asm/) - </para> - </listitem> - <listitem> - <para> - Function names as strings (__func__). - </para> - </listitem> - <listitem> - <para> - __builtin_constant_p() - </para> - </listitem> - </itemizedlist> - - <para> - Be wary when using long long in the kernel, the code gcc generates for - it is horrible and worse: division and multiplication does not work - on i386 because the GCC runtime functions for it are missing from - the kernel environment. - </para> - - <!-- FIXME: add a note about ANSI aliasing cleanness --> - </sect1> - - <sect1 id="conventions-cplusplus"> - <title>C++</title> - - <para> - Using C++ in the kernel is usually a bad idea, because the - kernel does not provide the necessary runtime environment - and the include files are not tested for it. It is still - possible, but not recommended. If you really want to do - this, forget about exceptions at least. - </para> - </sect1> - - <sect1 id="conventions-ifdef"> - <title>#if</title> - - <para> - It is generally considered cleaner to use macros in header files - (or at the top of .c files) to abstract away functions rather than - using `#if' pre-processor statements throughout the source code. - </para> - </sect1> - </chapter> - - <chapter id="submitting"> - <title>Putting Your Stuff in the Kernel</title> - - <para> - In order to get your stuff into shape for official inclusion, or - even to make a neat patch, there's administrative work to be - done: - </para> - <itemizedlist> - <listitem> - <para> - Figure out whose pond you've been pissing in. Look at the top of - the source files, inside the <filename>MAINTAINERS</filename> - file, and last of all in the <filename>CREDITS</filename> file. - You should coordinate with this person to make sure you're not - duplicating effort, or trying something that's already been - rejected. - </para> - - <para> - Make sure you put your name and EMail address at the top of - any files you create or mangle significantly. This is the - first place people will look when they find a bug, or when - <emphasis>they</emphasis> want to make a change. - </para> - </listitem> - - <listitem> - <para> - Usually you want a configuration option for your kernel hack. - Edit <filename>Kconfig</filename> in the appropriate directory. - The Config language is simple to use by cut and paste, and there's - complete documentation in - <filename>Documentation/kbuild/kconfig-language.txt</filename>. - </para> - - <para> - In your description of the option, make sure you address both the - expert user and the user who knows nothing about your feature. Mention - incompatibilities and issues here. <emphasis> Definitely - </emphasis> end your description with <quote> if in doubt, say N - </quote> (or, occasionally, `Y'); this is for people who have no - idea what you are talking about. - </para> - </listitem> - - <listitem> - <para> - Edit the <filename>Makefile</filename>: the CONFIG variables are - exported here so you can usually just add a "obj-$(CONFIG_xxx) += - xxx.o" line. The syntax is documented in - <filename>Documentation/kbuild/makefiles.txt</filename>. - </para> - </listitem> - - <listitem> - <para> - Put yourself in <filename>CREDITS</filename> if you've done - something noteworthy, usually beyond a single file (your name - should be at the top of the source files anyway). - <filename>MAINTAINERS</filename> means you want to be consulted - when changes are made to a subsystem, and hear about bugs; it - implies a more-than-passing commitment to some part of the code. - </para> - </listitem> - - <listitem> - <para> - Finally, don't forget to read <filename>Documentation/SubmittingPatches</filename> - and possibly <filename>Documentation/SubmittingDrivers</filename>. - </para> - </listitem> - </itemizedlist> - </chapter> - - <chapter id="cantrips"> - <title>Kernel Cantrips</title> - - <para> - Some favorites from browsing the source. Feel free to add to this - list. - </para> - - <para> - <filename>arch/x86/include/asm/delay.h:</filename> - </para> - <programlisting> -#define ndelay(n) (__builtin_constant_p(n) ? \ - ((n) > 20000 ? __bad_ndelay() : __const_udelay((n) * 5ul)) : \ - __ndelay(n)) - </programlisting> - - <para> - <filename>include/linux/fs.h</filename>: - </para> - <programlisting> -/* - * Kernel pointers have redundant information, so we can use a - * scheme where we can return either an error code or a dentry - * pointer with the same return value. - * - * This should be a per-architecture thing, to allow different - * error and pointer decisions. - */ - #define ERR_PTR(err) ((void *)((long)(err))) - #define PTR_ERR(ptr) ((long)(ptr)) - #define IS_ERR(ptr) ((unsigned long)(ptr) > (unsigned long)(-1000)) -</programlisting> - - <para> - <filename>arch/x86/include/asm/uaccess_32.h:</filename> - </para> - - <programlisting> -#define copy_to_user(to,from,n) \ - (__builtin_constant_p(n) ? \ - __constant_copy_to_user((to),(from),(n)) : \ - __generic_copy_to_user((to),(from),(n))) - </programlisting> - - <para> - <filename>arch/sparc/kernel/head.S:</filename> - </para> - - <programlisting> -/* - * Sun people can't spell worth damn. "compatability" indeed. - * At least we *know* we can't spell, and use a spell-checker. - */ - -/* Uh, actually Linus it is I who cannot spell. Too much murky - * Sparc assembly will do this to ya. - */ -C_LABEL(cputypvar): - .asciz "compatibility" - -/* Tested on SS-5, SS-10. Probably someone at Sun applied a spell-checker. */ - .align 4 -C_LABEL(cputypvar_sun4m): - .asciz "compatible" - </programlisting> - - <para> - <filename>arch/sparc/lib/checksum.S:</filename> - </para> - - <programlisting> - /* Sun, you just can't beat me, you just can't. Stop trying, - * give up. I'm serious, I am going to kick the living shit - * out of you, game over, lights out. - */ - </programlisting> - </chapter> - - <chapter id="credits"> - <title>Thanks</title> - - <para> - Thanks to Andi Kleen for the idea, answering my questions, fixing - my mistakes, filling content, etc. Philipp Rumpf for more spelling - and clarity fixes, and some excellent non-obvious points. Werner - Almesberger for giving me a great summary of - <function>disable_irq()</function>, and Jes Sorensen and Andrea - Arcangeli added caveats. Michael Elizabeth Chastain for checking - and adding to the Configure section. <!-- Rusty insisted on this - bit; I didn't do it! --> Telsa Gwynne for teaching me DocBook. - </para> - </chapter> -</book> - diff --git a/Documentation/DocBook/kernel-locking.tmpl b/Documentation/DocBook/kernel-locking.tmpl deleted file mode 100644 index 7c9cc4846cb6..000000000000 --- a/Documentation/DocBook/kernel-locking.tmpl +++ /dev/null @@ -1,2151 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="LKLockingGuide"> - <bookinfo> - <title>Unreliable Guide To Locking</title> - - <authorgroup> - <author> - <firstname>Rusty</firstname> - <surname>Russell</surname> - <affiliation> - <address> - <email>rusty@rustcorp.com.au</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2003</year> - <holder>Rusty Russell</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - - <toc></toc> - <chapter id="intro"> - <title>Introduction</title> - <para> - Welcome, to Rusty's Remarkably Unreliable Guide to Kernel - Locking issues. This document describes the locking systems in - the Linux Kernel in 2.6. - </para> - <para> - With the wide availability of HyperThreading, and <firstterm - linkend="gloss-preemption">preemption </firstterm> in the Linux - Kernel, everyone hacking on the kernel needs to know the - fundamentals of concurrency and locking for - <firstterm linkend="gloss-smp"><acronym>SMP</acronym></firstterm>. - </para> - </chapter> - - <chapter id="races"> - <title>The Problem With Concurrency</title> - <para> - (Skip this if you know what a Race Condition is). - </para> - <para> - In a normal program, you can increment a counter like so: - </para> - <programlisting> - very_important_count++; - </programlisting> - - <para> - This is what they would expect to happen: - </para> - - <table> - <title>Expected Results</title> - - <tgroup cols="2" align="left"> - - <thead> - <row> - <entry>Instance 1</entry> - <entry>Instance 2</entry> - </row> - </thead> - - <tbody> - <row> - <entry>read very_important_count (5)</entry> - <entry></entry> - </row> - <row> - <entry>add 1 (6)</entry> - <entry></entry> - </row> - <row> - <entry>write very_important_count (6)</entry> - <entry></entry> - </row> - <row> - <entry></entry> - <entry>read very_important_count (6)</entry> - </row> - <row> - <entry></entry> - <entry>add 1 (7)</entry> - </row> - <row> - <entry></entry> - <entry>write very_important_count (7)</entry> - </row> - </tbody> - - </tgroup> - </table> - - <para> - This is what might happen: - </para> - - <table> - <title>Possible Results</title> - - <tgroup cols="2" align="left"> - <thead> - <row> - <entry>Instance 1</entry> - <entry>Instance 2</entry> - </row> - </thead> - - <tbody> - <row> - <entry>read very_important_count (5)</entry> - <entry></entry> - </row> - <row> - <entry></entry> - <entry>read very_important_count (5)</entry> - </row> - <row> - <entry>add 1 (6)</entry> - <entry></entry> - </row> - <row> - <entry></entry> - <entry>add 1 (6)</entry> - </row> - <row> - <entry>write very_important_count (6)</entry> - <entry></entry> - </row> - <row> - <entry></entry> - <entry>write very_important_count (6)</entry> - </row> - </tbody> - </tgroup> - </table> - - <sect1 id="race-condition"> - <title>Race Conditions and Critical Regions</title> - <para> - This overlap, where the result depends on the - relative timing of multiple tasks, is called a <firstterm>race condition</firstterm>. - The piece of code containing the concurrency issue is called a - <firstterm>critical region</firstterm>. And especially since Linux starting running - on SMP machines, they became one of the major issues in kernel - design and implementation. - </para> - <para> - Preemption can have the same effect, even if there is only one - CPU: by preempting one task during the critical region, we have - exactly the same race condition. In this case the thread which - preempts might run the critical region itself. - </para> - <para> - The solution is to recognize when these simultaneous accesses - occur, and use locks to make sure that only one instance can - enter the critical region at any time. There are many - friendly primitives in the Linux kernel to help you do this. - And then there are the unfriendly primitives, but I'll pretend - they don't exist. - </para> - </sect1> - </chapter> - - <chapter id="locks"> - <title>Locking in the Linux Kernel</title> - - <para> - If I could give you one piece of advice: never sleep with anyone - crazier than yourself. But if I had to give you advice on - locking: <emphasis>keep it simple</emphasis>. - </para> - - <para> - Be reluctant to introduce new locks. - </para> - - <para> - Strangely enough, this last one is the exact reverse of my advice when - you <emphasis>have</emphasis> slept with someone crazier than yourself. - And you should think about getting a big dog. - </para> - - <sect1 id="lock-intro"> - <title>Two Main Types of Kernel Locks: Spinlocks and Mutexes</title> - - <para> - There are two main types of kernel locks. The fundamental type - is the spinlock - (<filename class="headerfile">include/asm/spinlock.h</filename>), - which is a very simple single-holder lock: if you can't get the - spinlock, you keep trying (spinning) until you can. Spinlocks are - very small and fast, and can be used anywhere. - </para> - <para> - The second type is a mutex - (<filename class="headerfile">include/linux/mutex.h</filename>): it - is like a spinlock, but you may block holding a mutex. - If you can't lock a mutex, your task will suspend itself, and be woken - up when the mutex is released. This means the CPU can do something - else while you are waiting. There are many cases when you simply - can't sleep (see <xref linkend="sleeping-things"/>), and so have to - use a spinlock instead. - </para> - <para> - Neither type of lock is recursive: see - <xref linkend="deadlock"/>. - </para> - </sect1> - - <sect1 id="uniprocessor"> - <title>Locks and Uniprocessor Kernels</title> - - <para> - For kernels compiled without <symbol>CONFIG_SMP</symbol>, and - without <symbol>CONFIG_PREEMPT</symbol> spinlocks do not exist at - all. This is an excellent design decision: when no-one else can - run at the same time, there is no reason to have a lock. - </para> - - <para> - If the kernel is compiled without <symbol>CONFIG_SMP</symbol>, - but <symbol>CONFIG_PREEMPT</symbol> is set, then spinlocks - simply disable preemption, which is sufficient to prevent any - races. For most purposes, we can think of preemption as - equivalent to SMP, and not worry about it separately. - </para> - - <para> - You should always test your locking code with <symbol>CONFIG_SMP</symbol> - and <symbol>CONFIG_PREEMPT</symbol> enabled, even if you don't have an SMP test box, because it - will still catch some kinds of locking bugs. - </para> - - <para> - Mutexes still exist, because they are required for - synchronization between <firstterm linkend="gloss-usercontext">user - contexts</firstterm>, as we will see below. - </para> - </sect1> - - <sect1 id="usercontextlocking"> - <title>Locking Only In User Context</title> - - <para> - If you have a data structure which is only ever accessed from - user context, then you can use a simple mutex - (<filename>include/linux/mutex.h</filename>) to protect it. This - is the most trivial case: you initialize the mutex. Then you can - call <function>mutex_lock_interruptible()</function> to grab the mutex, - and <function>mutex_unlock()</function> to release it. There is also a - <function>mutex_lock()</function>, which should be avoided, because it - will not return if a signal is received. - </para> - - <para> - Example: <filename>net/netfilter/nf_sockopt.c</filename> allows - registration of new <function>setsockopt()</function> and - <function>getsockopt()</function> calls, with - <function>nf_register_sockopt()</function>. Registration and - de-registration are only done on module load and unload (and boot - time, where there is no concurrency), and the list of registrations - is only consulted for an unknown <function>setsockopt()</function> - or <function>getsockopt()</function> system call. The - <varname>nf_sockopt_mutex</varname> is perfect to protect this, - especially since the setsockopt and getsockopt calls may well - sleep. - </para> - </sect1> - - <sect1 id="lock-user-bh"> - <title>Locking Between User Context and Softirqs</title> - - <para> - If a <firstterm linkend="gloss-softirq">softirq</firstterm> shares - data with user context, you have two problems. Firstly, the current - user context can be interrupted by a softirq, and secondly, the - critical region could be entered from another CPU. This is where - <function>spin_lock_bh()</function> - (<filename class="headerfile">include/linux/spinlock.h</filename>) is - used. It disables softirqs on that CPU, then grabs the lock. - <function>spin_unlock_bh()</function> does the reverse. (The - '_bh' suffix is a historical reference to "Bottom Halves", the - old name for software interrupts. It should really be - called spin_lock_softirq()' in a perfect world). - </para> - - <para> - Note that you can also use <function>spin_lock_irq()</function> - or <function>spin_lock_irqsave()</function> here, which stop - hardware interrupts as well: see <xref linkend="hardirq-context"/>. - </para> - - <para> - This works perfectly for <firstterm linkend="gloss-up"><acronym>UP - </acronym></firstterm> as well: the spin lock vanishes, and this macro - simply becomes <function>local_bh_disable()</function> - (<filename class="headerfile">include/linux/interrupt.h</filename>), which - protects you from the softirq being run. - </para> - </sect1> - - <sect1 id="lock-user-tasklet"> - <title>Locking Between User Context and Tasklets</title> - - <para> - This is exactly the same as above, because <firstterm - linkend="gloss-tasklet">tasklets</firstterm> are actually run - from a softirq. - </para> - </sect1> - - <sect1 id="lock-user-timers"> - <title>Locking Between User Context and Timers</title> - - <para> - This, too, is exactly the same as above, because <firstterm - linkend="gloss-timers">timers</firstterm> are actually run from - a softirq. From a locking point of view, tasklets and timers - are identical. - </para> - </sect1> - - <sect1 id="lock-tasklets"> - <title>Locking Between Tasklets/Timers</title> - - <para> - Sometimes a tasklet or timer might want to share data with - another tasklet or timer. - </para> - - <sect2 id="lock-tasklets-same"> - <title>The Same Tasklet/Timer</title> - <para> - Since a tasklet is never run on two CPUs at once, you don't - need to worry about your tasklet being reentrant (running - twice at once), even on SMP. - </para> - </sect2> - - <sect2 id="lock-tasklets-different"> - <title>Different Tasklets/Timers</title> - <para> - If another tasklet/timer wants - to share data with your tasklet or timer , you will both need to use - <function>spin_lock()</function> and - <function>spin_unlock()</function> calls. - <function>spin_lock_bh()</function> is - unnecessary here, as you are already in a tasklet, and - none will be run on the same CPU. - </para> - </sect2> - </sect1> - - <sect1 id="lock-softirqs"> - <title>Locking Between Softirqs</title> - - <para> - Often a softirq might - want to share data with itself or a tasklet/timer. - </para> - - <sect2 id="lock-softirqs-same"> - <title>The Same Softirq</title> - - <para> - The same softirq can run on the other CPUs: you can use a - per-CPU array (see <xref linkend="per-cpu"/>) for better - performance. If you're going so far as to use a softirq, - you probably care about scalable performance enough - to justify the extra complexity. - </para> - - <para> - You'll need to use <function>spin_lock()</function> and - <function>spin_unlock()</function> for shared data. - </para> - </sect2> - - <sect2 id="lock-softirqs-different"> - <title>Different Softirqs</title> - - <para> - You'll need to use <function>spin_lock()</function> and - <function>spin_unlock()</function> for shared data, whether it - be a timer, tasklet, different softirq or the same or another - softirq: any of them could be running on a different CPU. - </para> - </sect2> - </sect1> - </chapter> - - <chapter id="hardirq-context"> - <title>Hard IRQ Context</title> - - <para> - Hardware interrupts usually communicate with a - tasklet or softirq. Frequently this involves putting work in a - queue, which the softirq will take out. - </para> - - <sect1 id="hardirq-softirq"> - <title>Locking Between Hard IRQ and Softirqs/Tasklets</title> - - <para> - If a hardware irq handler shares data with a softirq, you have - two concerns. Firstly, the softirq processing can be - interrupted by a hardware interrupt, and secondly, the - critical region could be entered by a hardware interrupt on - another CPU. This is where <function>spin_lock_irq()</function> is - used. It is defined to disable interrupts on that cpu, then grab - the lock. <function>spin_unlock_irq()</function> does the reverse. - </para> - - <para> - The irq handler does not to use - <function>spin_lock_irq()</function>, because the softirq cannot - run while the irq handler is running: it can use - <function>spin_lock()</function>, which is slightly faster. The - only exception would be if a different hardware irq handler uses - the same lock: <function>spin_lock_irq()</function> will stop - that from interrupting us. - </para> - - <para> - This works perfectly for UP as well: the spin lock vanishes, - and this macro simply becomes <function>local_irq_disable()</function> - (<filename class="headerfile">include/asm/smp.h</filename>), which - protects you from the softirq/tasklet/BH being run. - </para> - - <para> - <function>spin_lock_irqsave()</function> - (<filename>include/linux/spinlock.h</filename>) is a variant - which saves whether interrupts were on or off in a flags word, - which is passed to <function>spin_unlock_irqrestore()</function>. This - means that the same code can be used inside an hard irq handler (where - interrupts are already off) and in softirqs (where the irq - disabling is required). - </para> - - <para> - Note that softirqs (and hence tasklets and timers) are run on - return from hardware interrupts, so - <function>spin_lock_irq()</function> also stops these. In that - sense, <function>spin_lock_irqsave()</function> is the most - general and powerful locking function. - </para> - - </sect1> - <sect1 id="hardirq-hardirq"> - <title>Locking Between Two Hard IRQ Handlers</title> - <para> - It is rare to have to share data between two IRQ handlers, but - if you do, <function>spin_lock_irqsave()</function> should be - used: it is architecture-specific whether all interrupts are - disabled inside irq handlers themselves. - </para> - </sect1> - - </chapter> - - <chapter id="cheatsheet"> - <title>Cheat Sheet For Locking</title> - <para> - Pete Zaitcev gives the following summary: - </para> - <itemizedlist> - <listitem> - <para> - If you are in a process context (any syscall) and want to - lock other process out, use a mutex. You can take a mutex - and sleep (<function>copy_from_user*(</function> or - <function>kmalloc(x,GFP_KERNEL)</function>). - </para> - </listitem> - <listitem> - <para> - Otherwise (== data can be touched in an interrupt), use - <function>spin_lock_irqsave()</function> and - <function>spin_unlock_irqrestore()</function>. - </para> - </listitem> - <listitem> - <para> - Avoid holding spinlock for more than 5 lines of code and - across any function call (except accessors like - <function>readb</function>). - </para> - </listitem> - </itemizedlist> - - <sect1 id="minimum-lock-reqirements"> - <title>Table of Minimum Requirements</title> - - <para> The following table lists the <emphasis>minimum</emphasis> - locking requirements between various contexts. In some cases, - the same context can only be running on one CPU at a time, so - no locking is required for that context (eg. a particular - thread can only run on one CPU at a time, but if it needs - shares data with another thread, locking is required). - </para> - <para> - Remember the advice above: you can always use - <function>spin_lock_irqsave()</function>, which is a superset - of all other spinlock primitives. - </para> - - <table> -<title>Table of Locking Requirements</title> -<tgroup cols="11"> -<tbody> - -<row> -<entry></entry> -<entry>IRQ Handler A</entry> -<entry>IRQ Handler B</entry> -<entry>Softirq A</entry> -<entry>Softirq B</entry> -<entry>Tasklet A</entry> -<entry>Tasklet B</entry> -<entry>Timer A</entry> -<entry>Timer B</entry> -<entry>User Context A</entry> -<entry>User Context B</entry> -</row> - -<row> -<entry>IRQ Handler A</entry> -<entry>None</entry> -</row> - -<row> -<entry>IRQ Handler B</entry> -<entry>SLIS</entry> -<entry>None</entry> -</row> - -<row> -<entry>Softirq A</entry> -<entry>SLI</entry> -<entry>SLI</entry> -<entry>SL</entry> -</row> - -<row> -<entry>Softirq B</entry> -<entry>SLI</entry> -<entry>SLI</entry> -<entry>SL</entry> -<entry>SL</entry> -</row> - -<row> -<entry>Tasklet A</entry> -<entry>SLI</entry> -<entry>SLI</entry> -<entry>SL</entry> -<entry>SL</entry> -<entry>None</entry> -</row> - -<row> -<entry>Tasklet B</entry> -<entry>SLI</entry> -<entry>SLI</entry> -<entry>SL</entry> -<entry>SL</entry> -<entry>SL</entry> -<entry>None</entry> -</row> - -<row> -<entry>Timer A</entry> -<entry>SLI</entry> -<entry>SLI</entry> -<entry>SL</entry> -<entry>SL</entry> -<entry>SL</entry> -<entry>SL</entry> -<entry>None</entry> -</row> - -<row> -<entry>Timer B</entry> -<entry>SLI</entry> -<entry>SLI</entry> -<entry>SL</entry> -<entry>SL</entry> -<entry>SL</entry> -<entry>SL</entry> -<entry>SL</entry> -<entry>None</entry> -</row> - -<row> -<entry>User Context A</entry> -<entry>SLI</entry> -<entry>SLI</entry> -<entry>SLBH</entry> -<entry>SLBH</entry> -<entry>SLBH</entry> -<entry>SLBH</entry> -<entry>SLBH</entry> -<entry>SLBH</entry> -<entry>None</entry> -</row> - -<row> -<entry>User Context B</entry> -<entry>SLI</entry> -<entry>SLI</entry> -<entry>SLBH</entry> -<entry>SLBH</entry> -<entry>SLBH</entry> -<entry>SLBH</entry> -<entry>SLBH</entry> -<entry>SLBH</entry> -<entry>MLI</entry> -<entry>None</entry> -</row> - -</tbody> -</tgroup> -</table> - - <table> -<title>Legend for Locking Requirements Table</title> -<tgroup cols="2"> -<tbody> - -<row> -<entry>SLIS</entry> -<entry>spin_lock_irqsave</entry> -</row> -<row> -<entry>SLI</entry> -<entry>spin_lock_irq</entry> -</row> -<row> -<entry>SL</entry> -<entry>spin_lock</entry> -</row> -<row> -<entry>SLBH</entry> -<entry>spin_lock_bh</entry> -</row> -<row> -<entry>MLI</entry> -<entry>mutex_lock_interruptible</entry> -</row> - -</tbody> -</tgroup> -</table> - -</sect1> -</chapter> - -<chapter id="trylock-functions"> - <title>The trylock Functions</title> - <para> - There are functions that try to acquire a lock only once and immediately - return a value telling about success or failure to acquire the lock. - They can be used if you need no access to the data protected with the lock - when some other thread is holding the lock. You should acquire the lock - later if you then need access to the data protected with the lock. - </para> - - <para> - <function>spin_trylock()</function> does not spin but returns non-zero if - it acquires the spinlock on the first try or 0 if not. This function can - be used in all contexts like <function>spin_lock</function>: you must have - disabled the contexts that might interrupt you and acquire the spin lock. - </para> - - <para> - <function>mutex_trylock()</function> does not suspend your task - but returns non-zero if it could lock the mutex on the first try - or 0 if not. This function cannot be safely used in hardware or software - interrupt contexts despite not sleeping. - </para> -</chapter> - - <chapter id="Examples"> - <title>Common Examples</title> - <para> -Let's step through a simple example: a cache of number to name -mappings. The cache keeps a count of how often each of the objects is -used, and when it gets full, throws out the least used one. - - </para> - - <sect1 id="examples-usercontext"> - <title>All In User Context</title> - <para> -For our first example, we assume that all operations are in user -context (ie. from system calls), so we can sleep. This means we can -use a mutex to protect the cache and all the objects within -it. Here's the code: - </para> - - <programlisting> -#include <linux/list.h> -#include <linux/slab.h> -#include <linux/string.h> -#include <linux/mutex.h> -#include <asm/errno.h> - -struct object -{ - struct list_head list; - int id; - char name[32]; - int popularity; -}; - -/* Protects the cache, cache_num, and the objects within it */ -static DEFINE_MUTEX(cache_lock); -static LIST_HEAD(cache); -static unsigned int cache_num = 0; -#define MAX_CACHE_SIZE 10 - -/* Must be holding cache_lock */ -static struct object *__cache_find(int id) -{ - struct object *i; - - list_for_each_entry(i, &cache, list) - if (i->id == id) { - i->popularity++; - return i; - } - return NULL; -} - -/* Must be holding cache_lock */ -static void __cache_delete(struct object *obj) -{ - BUG_ON(!obj); - list_del(&obj->list); - kfree(obj); - cache_num--; -} - -/* Must be holding cache_lock */ -static void __cache_add(struct object *obj) -{ - list_add(&obj->list, &cache); - if (++cache_num > MAX_CACHE_SIZE) { - struct object *i, *outcast = NULL; - list_for_each_entry(i, &cache, list) { - if (!outcast || i->popularity < outcast->popularity) - outcast = i; - } - __cache_delete(outcast); - } -} - -int cache_add(int id, const char *name) -{ - struct object *obj; - - if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL) - return -ENOMEM; - - strlcpy(obj->name, name, sizeof(obj->name)); - obj->id = id; - obj->popularity = 0; - - mutex_lock(&cache_lock); - __cache_add(obj); - mutex_unlock(&cache_lock); - return 0; -} - -void cache_delete(int id) -{ - mutex_lock(&cache_lock); - __cache_delete(__cache_find(id)); - mutex_unlock(&cache_lock); -} - -int cache_find(int id, char *name) -{ - struct object *obj; - int ret = -ENOENT; - - mutex_lock(&cache_lock); - obj = __cache_find(id); - if (obj) { - ret = 0; - strcpy(name, obj->name); - } - mutex_unlock(&cache_lock); - return ret; -} -</programlisting> - - <para> -Note that we always make sure we have the cache_lock when we add, -delete, or look up the cache: both the cache infrastructure itself and -the contents of the objects are protected by the lock. In this case -it's easy, since we copy the data for the user, and never let them -access the objects directly. - </para> - <para> -There is a slight (and common) optimization here: in -<function>cache_add</function> we set up the fields of the object -before grabbing the lock. This is safe, as no-one else can access it -until we put it in cache. - </para> - </sect1> - - <sect1 id="examples-interrupt"> - <title>Accessing From Interrupt Context</title> - <para> -Now consider the case where <function>cache_find</function> can be -called from interrupt context: either a hardware interrupt or a -softirq. An example would be a timer which deletes object from the -cache. - </para> - <para> -The change is shown below, in standard patch format: the -<symbol>-</symbol> are lines which are taken away, and the -<symbol>+</symbol> are lines which are added. - </para> -<programlisting> ---- cache.c.usercontext 2003-12-09 13:58:54.000000000 +1100 -+++ cache.c.interrupt 2003-12-09 14:07:49.000000000 +1100 -@@ -12,7 +12,7 @@ - int popularity; - }; - --static DEFINE_MUTEX(cache_lock); -+static DEFINE_SPINLOCK(cache_lock); - static LIST_HEAD(cache); - static unsigned int cache_num = 0; - #define MAX_CACHE_SIZE 10 -@@ -55,6 +55,7 @@ - int cache_add(int id, const char *name) - { - struct object *obj; -+ unsigned long flags; - - if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL) - return -ENOMEM; -@@ -63,30 +64,33 @@ - obj->id = id; - obj->popularity = 0; - -- mutex_lock(&cache_lock); -+ spin_lock_irqsave(&cache_lock, flags); - __cache_add(obj); -- mutex_unlock(&cache_lock); -+ spin_unlock_irqrestore(&cache_lock, flags); - return 0; - } - - void cache_delete(int id) - { -- mutex_lock(&cache_lock); -+ unsigned long flags; -+ -+ spin_lock_irqsave(&cache_lock, flags); - __cache_delete(__cache_find(id)); -- mutex_unlock(&cache_lock); -+ spin_unlock_irqrestore(&cache_lock, flags); - } - - int cache_find(int id, char *name) - { - struct object *obj; - int ret = -ENOENT; -+ unsigned long flags; - -- mutex_lock(&cache_lock); -+ spin_lock_irqsave(&cache_lock, flags); - obj = __cache_find(id); - if (obj) { - ret = 0; - strcpy(name, obj->name); - } -- mutex_unlock(&cache_lock); -+ spin_unlock_irqrestore(&cache_lock, flags); - return ret; - } -</programlisting> - - <para> -Note that the <function>spin_lock_irqsave</function> will turn off -interrupts if they are on, otherwise does nothing (if we are already -in an interrupt handler), hence these functions are safe to call from -any context. - </para> - <para> -Unfortunately, <function>cache_add</function> calls -<function>kmalloc</function> with the <symbol>GFP_KERNEL</symbol> -flag, which is only legal in user context. I have assumed that -<function>cache_add</function> is still only called in user context, -otherwise this should become a parameter to -<function>cache_add</function>. - </para> - </sect1> - <sect1 id="examples-refcnt"> - <title>Exposing Objects Outside This File</title> - <para> -If our objects contained more information, it might not be sufficient -to copy the information in and out: other parts of the code might want -to keep pointers to these objects, for example, rather than looking up -the id every time. This produces two problems. - </para> - <para> -The first problem is that we use the <symbol>cache_lock</symbol> to -protect objects: we'd need to make this non-static so the rest of the -code can use it. This makes locking trickier, as it is no longer all -in one place. - </para> - <para> -The second problem is the lifetime problem: if another structure keeps -a pointer to an object, it presumably expects that pointer to remain -valid. Unfortunately, this is only guaranteed while you hold the -lock, otherwise someone might call <function>cache_delete</function> -and even worse, add another object, re-using the same address. - </para> - <para> -As there is only one lock, you can't hold it forever: no-one else would -get any work done. - </para> - <para> -The solution to this problem is to use a reference count: everyone who -has a pointer to the object increases it when they first get the -object, and drops the reference count when they're finished with it. -Whoever drops it to zero knows it is unused, and can actually delete it. - </para> - <para> -Here is the code: - </para> - -<programlisting> ---- cache.c.interrupt 2003-12-09 14:25:43.000000000 +1100 -+++ cache.c.refcnt 2003-12-09 14:33:05.000000000 +1100 -@@ -7,6 +7,7 @@ - struct object - { - struct list_head list; -+ unsigned int refcnt; - int id; - char name[32]; - int popularity; -@@ -17,6 +18,35 @@ - static unsigned int cache_num = 0; - #define MAX_CACHE_SIZE 10 - -+static void __object_put(struct object *obj) -+{ -+ if (--obj->refcnt == 0) -+ kfree(obj); -+} -+ -+static void __object_get(struct object *obj) -+{ -+ obj->refcnt++; -+} -+ -+void object_put(struct object *obj) -+{ -+ unsigned long flags; -+ -+ spin_lock_irqsave(&cache_lock, flags); -+ __object_put(obj); -+ spin_unlock_irqrestore(&cache_lock, flags); -+} -+ -+void object_get(struct object *obj) -+{ -+ unsigned long flags; -+ -+ spin_lock_irqsave(&cache_lock, flags); -+ __object_get(obj); -+ spin_unlock_irqrestore(&cache_lock, flags); -+} -+ - /* Must be holding cache_lock */ - static struct object *__cache_find(int id) - { -@@ -35,6 +65,7 @@ - { - BUG_ON(!obj); - list_del(&obj->list); -+ __object_put(obj); - cache_num--; - } - -@@ -63,6 +94,7 @@ - strlcpy(obj->name, name, sizeof(obj->name)); - obj->id = id; - obj->popularity = 0; -+ obj->refcnt = 1; /* The cache holds a reference */ - - spin_lock_irqsave(&cache_lock, flags); - __cache_add(obj); -@@ -79,18 +111,15 @@ - spin_unlock_irqrestore(&cache_lock, flags); - } - --int cache_find(int id, char *name) -+struct object *cache_find(int id) - { - struct object *obj; -- int ret = -ENOENT; - unsigned long flags; - - spin_lock_irqsave(&cache_lock, flags); - obj = __cache_find(id); -- if (obj) { -- ret = 0; -- strcpy(name, obj->name); -- } -+ if (obj) -+ __object_get(obj); - spin_unlock_irqrestore(&cache_lock, flags); -- return ret; -+ return obj; - } -</programlisting> - -<para> -We encapsulate the reference counting in the standard 'get' and 'put' -functions. Now we can return the object itself from -<function>cache_find</function> which has the advantage that the user -can now sleep holding the object (eg. to -<function>copy_to_user</function> to name to userspace). -</para> -<para> -The other point to note is that I said a reference should be held for -every pointer to the object: thus the reference count is 1 when first -inserted into the cache. In some versions the framework does not hold -a reference count, but they are more complicated. -</para> - - <sect2 id="examples-refcnt-atomic"> - <title>Using Atomic Operations For The Reference Count</title> -<para> -In practice, <type>atomic_t</type> would usually be used for -<structfield>refcnt</structfield>. There are a number of atomic -operations defined in - -<filename class="headerfile">include/asm/atomic.h</filename>: these are -guaranteed to be seen atomically from all CPUs in the system, so no -lock is required. In this case, it is simpler than using spinlocks, -although for anything non-trivial using spinlocks is clearer. The -<function>atomic_inc</function> and -<function>atomic_dec_and_test</function> are used instead of the -standard increment and decrement operators, and the lock is no longer -used to protect the reference count itself. -</para> - -<programlisting> ---- cache.c.refcnt 2003-12-09 15:00:35.000000000 +1100 -+++ cache.c.refcnt-atomic 2003-12-11 15:49:42.000000000 +1100 -@@ -7,7 +7,7 @@ - struct object - { - struct list_head list; -- unsigned int refcnt; -+ atomic_t refcnt; - int id; - char name[32]; - int popularity; -@@ -18,33 +18,15 @@ - static unsigned int cache_num = 0; - #define MAX_CACHE_SIZE 10 - --static void __object_put(struct object *obj) --{ -- if (--obj->refcnt == 0) -- kfree(obj); --} -- --static void __object_get(struct object *obj) --{ -- obj->refcnt++; --} -- - void object_put(struct object *obj) - { -- unsigned long flags; -- -- spin_lock_irqsave(&cache_lock, flags); -- __object_put(obj); -- spin_unlock_irqrestore(&cache_lock, flags); -+ if (atomic_dec_and_test(&obj->refcnt)) -+ kfree(obj); - } - - void object_get(struct object *obj) - { -- unsigned long flags; -- -- spin_lock_irqsave(&cache_lock, flags); -- __object_get(obj); -- spin_unlock_irqrestore(&cache_lock, flags); -+ atomic_inc(&obj->refcnt); - } - - /* Must be holding cache_lock */ -@@ -65,7 +47,7 @@ - { - BUG_ON(!obj); - list_del(&obj->list); -- __object_put(obj); -+ object_put(obj); - cache_num--; - } - -@@ -94,7 +76,7 @@ - strlcpy(obj->name, name, sizeof(obj->name)); - obj->id = id; - obj->popularity = 0; -- obj->refcnt = 1; /* The cache holds a reference */ -+ atomic_set(&obj->refcnt, 1); /* The cache holds a reference */ - - spin_lock_irqsave(&cache_lock, flags); - __cache_add(obj); -@@ -119,7 +101,7 @@ - spin_lock_irqsave(&cache_lock, flags); - obj = __cache_find(id); - if (obj) -- __object_get(obj); -+ object_get(obj); - spin_unlock_irqrestore(&cache_lock, flags); - return obj; - } -</programlisting> -</sect2> -</sect1> - - <sect1 id="examples-lock-per-obj"> - <title>Protecting The Objects Themselves</title> - <para> -In these examples, we assumed that the objects (except the reference -counts) never changed once they are created. If we wanted to allow -the name to change, there are three possibilities: - </para> - <itemizedlist> - <listitem> - <para> -You can make <symbol>cache_lock</symbol> non-static, and tell people -to grab that lock before changing the name in any object. - </para> - </listitem> - <listitem> - <para> -You can provide a <function>cache_obj_rename</function> which grabs -this lock and changes the name for the caller, and tell everyone to -use that function. - </para> - </listitem> - <listitem> - <para> -You can make the <symbol>cache_lock</symbol> protect only the cache -itself, and use another lock to protect the name. - </para> - </listitem> - </itemizedlist> - - <para> -Theoretically, you can make the locks as fine-grained as one lock for -every field, for every object. In practice, the most common variants -are: -</para> - <itemizedlist> - <listitem> - <para> -One lock which protects the infrastructure (the <symbol>cache</symbol> -list in this example) and all the objects. This is what we have done -so far. - </para> - </listitem> - <listitem> - <para> -One lock which protects the infrastructure (including the list -pointers inside the objects), and one lock inside the object which -protects the rest of that object. - </para> - </listitem> - <listitem> - <para> -Multiple locks to protect the infrastructure (eg. one lock per hash -chain), possibly with a separate per-object lock. - </para> - </listitem> - </itemizedlist> - -<para> -Here is the "lock-per-object" implementation: -</para> -<programlisting> ---- cache.c.refcnt-atomic 2003-12-11 15:50:54.000000000 +1100 -+++ cache.c.perobjectlock 2003-12-11 17:15:03.000000000 +1100 -@@ -6,11 +6,17 @@ - - struct object - { -+ /* These two protected by cache_lock. */ - struct list_head list; -+ int popularity; -+ - atomic_t refcnt; -+ -+ /* Doesn't change once created. */ - int id; -+ -+ spinlock_t lock; /* Protects the name */ - char name[32]; -- int popularity; - }; - - static DEFINE_SPINLOCK(cache_lock); -@@ -77,6 +84,7 @@ - obj->id = id; - obj->popularity = 0; - atomic_set(&obj->refcnt, 1); /* The cache holds a reference */ -+ spin_lock_init(&obj->lock); - - spin_lock_irqsave(&cache_lock, flags); - __cache_add(obj); -</programlisting> - -<para> -Note that I decide that the <structfield>popularity</structfield> -count should be protected by the <symbol>cache_lock</symbol> rather -than the per-object lock: this is because it (like the -<structname>struct list_head</structname> inside the object) is -logically part of the infrastructure. This way, I don't need to grab -the lock of every object in <function>__cache_add</function> when -seeking the least popular. -</para> - -<para> -I also decided that the <structfield>id</structfield> member is -unchangeable, so I don't need to grab each object lock in -<function>__cache_find()</function> to examine the -<structfield>id</structfield>: the object lock is only used by a -caller who wants to read or write the <structfield>name</structfield> -field. -</para> - -<para> -Note also that I added a comment describing what data was protected by -which locks. This is extremely important, as it describes the runtime -behavior of the code, and can be hard to gain from just reading. And -as Alan Cox says, <quote>Lock data, not code</quote>. -</para> -</sect1> -</chapter> - - <chapter id="common-problems"> - <title>Common Problems</title> - <sect1 id="deadlock"> - <title>Deadlock: Simple and Advanced</title> - - <para> - There is a coding bug where a piece of code tries to grab a - spinlock twice: it will spin forever, waiting for the lock to - be released (spinlocks, rwlocks and mutexes are not - recursive in Linux). This is trivial to diagnose: not a - stay-up-five-nights-talk-to-fluffy-code-bunnies kind of - problem. - </para> - - <para> - For a slightly more complex case, imagine you have a region - shared by a softirq and user context. If you use a - <function>spin_lock()</function> call to protect it, it is - possible that the user context will be interrupted by the softirq - while it holds the lock, and the softirq will then spin - forever trying to get the same lock. - </para> - - <para> - Both of these are called deadlock, and as shown above, it can - occur even with a single CPU (although not on UP compiles, - since spinlocks vanish on kernel compiles with - <symbol>CONFIG_SMP</symbol>=n. You'll still get data corruption - in the second example). - </para> - - <para> - This complete lockup is easy to diagnose: on SMP boxes the - watchdog timer or compiling with <symbol>DEBUG_SPINLOCK</symbol> set - (<filename>include/linux/spinlock.h</filename>) will show this up - immediately when it happens. - </para> - - <para> - A more complex problem is the so-called 'deadly embrace', - involving two or more locks. Say you have a hash table: each - entry in the table is a spinlock, and a chain of hashed - objects. Inside a softirq handler, you sometimes want to - alter an object from one place in the hash to another: you - grab the spinlock of the old hash chain and the spinlock of - the new hash chain, and delete the object from the old one, - and insert it in the new one. - </para> - - <para> - There are two problems here. First, if your code ever - tries to move the object to the same chain, it will deadlock - with itself as it tries to lock it twice. Secondly, if the - same softirq on another CPU is trying to move another object - in the reverse direction, the following could happen: - </para> - - <table> - <title>Consequences</title> - - <tgroup cols="2" align="left"> - - <thead> - <row> - <entry>CPU 1</entry> - <entry>CPU 2</entry> - </row> - </thead> - - <tbody> - <row> - <entry>Grab lock A -> OK</entry> - <entry>Grab lock B -> OK</entry> - </row> - <row> - <entry>Grab lock B -> spin</entry> - <entry>Grab lock A -> spin</entry> - </row> - </tbody> - </tgroup> - </table> - - <para> - The two CPUs will spin forever, waiting for the other to give up - their lock. It will look, smell, and feel like a crash. - </para> - </sect1> - - <sect1 id="techs-deadlock-prevent"> - <title>Preventing Deadlock</title> - - <para> - Textbooks will tell you that if you always lock in the same - order, you will never get this kind of deadlock. Practice - will tell you that this approach doesn't scale: when I - create a new lock, I don't understand enough of the kernel - to figure out where in the 5000 lock hierarchy it will fit. - </para> - - <para> - The best locks are encapsulated: they never get exposed in - headers, and are never held around calls to non-trivial - functions outside the same file. You can read through this - code and see that it will never deadlock, because it never - tries to grab another lock while it has that one. People - using your code don't even need to know you are using a - lock. - </para> - - <para> - A classic problem here is when you provide callbacks or - hooks: if you call these with the lock held, you risk simple - deadlock, or a deadly embrace (who knows what the callback - will do?). Remember, the other programmers are out to get - you, so don't do this. - </para> - - <sect2 id="techs-deadlock-overprevent"> - <title>Overzealous Prevention Of Deadlocks</title> - - <para> - Deadlocks are problematic, but not as bad as data - corruption. Code which grabs a read lock, searches a list, - fails to find what it wants, drops the read lock, grabs a - write lock and inserts the object has a race condition. - </para> - - <para> - If you don't see why, please stay the fuck away from my code. - </para> - </sect2> - </sect1> - - <sect1 id="racing-timers"> - <title>Racing Timers: A Kernel Pastime</title> - - <para> - Timers can produce their own special problems with races. - Consider a collection of objects (list, hash, etc) where each - object has a timer which is due to destroy it. - </para> - - <para> - If you want to destroy the entire collection (say on module - removal), you might do the following: - </para> - - <programlisting> - /* THIS CODE BAD BAD BAD BAD: IF IT WAS ANY WORSE IT WOULD USE - HUNGARIAN NOTATION */ - spin_lock_bh(&list_lock); - - while (list) { - struct foo *next = list->next; - del_timer(&list->timer); - kfree(list); - list = next; - } - - spin_unlock_bh(&list_lock); - </programlisting> - - <para> - Sooner or later, this will crash on SMP, because a timer can - have just gone off before the <function>spin_lock_bh()</function>, - and it will only get the lock after we - <function>spin_unlock_bh()</function>, and then try to free - the element (which has already been freed!). - </para> - - <para> - This can be avoided by checking the result of - <function>del_timer()</function>: if it returns - <returnvalue>1</returnvalue>, the timer has been deleted. - If <returnvalue>0</returnvalue>, it means (in this - case) that it is currently running, so we can do: - </para> - - <programlisting> - retry: - spin_lock_bh(&list_lock); - - while (list) { - struct foo *next = list->next; - if (!del_timer(&list->timer)) { - /* Give timer a chance to delete this */ - spin_unlock_bh(&list_lock); - goto retry; - } - kfree(list); - list = next; - } - - spin_unlock_bh(&list_lock); - </programlisting> - - <para> - Another common problem is deleting timers which restart - themselves (by calling <function>add_timer()</function> at the end - of their timer function). Because this is a fairly common case - which is prone to races, you should use <function>del_timer_sync()</function> - (<filename class="headerfile">include/linux/timer.h</filename>) - to handle this case. It returns the number of times the timer - had to be deleted before we finally stopped it from adding itself back - in. - </para> - </sect1> - - </chapter> - - <chapter id="Efficiency"> - <title>Locking Speed</title> - - <para> -There are three main things to worry about when considering speed of -some code which does locking. First is concurrency: how many things -are going to be waiting while someone else is holding a lock. Second -is the time taken to actually acquire and release an uncontended lock. -Third is using fewer, or smarter locks. I'm assuming that the lock is -used fairly often: otherwise, you wouldn't be concerned about -efficiency. -</para> - <para> -Concurrency depends on how long the lock is usually held: you should -hold the lock for as long as needed, but no longer. In the cache -example, we always create the object without the lock held, and then -grab the lock only when we are ready to insert it in the list. -</para> - <para> -Acquisition times depend on how much damage the lock operations do to -the pipeline (pipeline stalls) and how likely it is that this CPU was -the last one to grab the lock (ie. is the lock cache-hot for this -CPU): on a machine with more CPUs, this likelihood drops fast. -Consider a 700MHz Intel Pentium III: an instruction takes about 0.7ns, -an atomic increment takes about 58ns, a lock which is cache-hot on -this CPU takes 160ns, and a cacheline transfer from another CPU takes -an additional 170 to 360ns. (These figures from Paul McKenney's -<ulink url="http://www.linuxjournal.com/article.php?sid=6993"> Linux -Journal RCU article</ulink>). -</para> - <para> -These two aims conflict: holding a lock for a short time might be done -by splitting locks into parts (such as in our final per-object-lock -example), but this increases the number of lock acquisitions, and the -results are often slower than having a single lock. This is another -reason to advocate locking simplicity. -</para> - <para> -The third concern is addressed below: there are some methods to reduce -the amount of locking which needs to be done. -</para> - - <sect1 id="efficiency-rwlocks"> - <title>Read/Write Lock Variants</title> - - <para> - Both spinlocks and mutexes have read/write variants: - <type>rwlock_t</type> and <structname>struct rw_semaphore</structname>. - These divide users into two classes: the readers and the writers. If - you are only reading the data, you can get a read lock, but to write to - the data you need the write lock. Many people can hold a read lock, - but a writer must be sole holder. - </para> - - <para> - If your code divides neatly along reader/writer lines (as our - cache code does), and the lock is held by readers for - significant lengths of time, using these locks can help. They - are slightly slower than the normal locks though, so in practice - <type>rwlock_t</type> is not usually worthwhile. - </para> - </sect1> - - <sect1 id="efficiency-read-copy-update"> - <title>Avoiding Locks: Read Copy Update</title> - - <para> - There is a special method of read/write locking called Read Copy - Update. Using RCU, the readers can avoid taking a lock - altogether: as we expect our cache to be read more often than - updated (otherwise the cache is a waste of time), it is a - candidate for this optimization. - </para> - - <para> - How do we get rid of read locks? Getting rid of read locks - means that writers may be changing the list underneath the - readers. That is actually quite simple: we can read a linked - list while an element is being added if the writer adds the - element very carefully. For example, adding - <symbol>new</symbol> to a single linked list called - <symbol>list</symbol>: - </para> - - <programlisting> - new->next = list->next; - wmb(); - list->next = new; - </programlisting> - - <para> - The <function>wmb()</function> is a write memory barrier. It - ensures that the first operation (setting the new element's - <symbol>next</symbol> pointer) is complete and will be seen by - all CPUs, before the second operation is (putting the new - element into the list). This is important, since modern - compilers and modern CPUs can both reorder instructions unless - told otherwise: we want a reader to either not see the new - element at all, or see the new element with the - <symbol>next</symbol> pointer correctly pointing at the rest of - the list. - </para> - <para> - Fortunately, there is a function to do this for standard - <structname>struct list_head</structname> lists: - <function>list_add_rcu()</function> - (<filename>include/linux/list.h</filename>). - </para> - <para> - Removing an element from the list is even simpler: we replace - the pointer to the old element with a pointer to its successor, - and readers will either see it, or skip over it. - </para> - <programlisting> - list->next = old->next; - </programlisting> - <para> - There is <function>list_del_rcu()</function> - (<filename>include/linux/list.h</filename>) which does this (the - normal version poisons the old object, which we don't want). - </para> - <para> - The reader must also be careful: some CPUs can look through the - <symbol>next</symbol> pointer to start reading the contents of - the next element early, but don't realize that the pre-fetched - contents is wrong when the <symbol>next</symbol> pointer changes - underneath them. Once again, there is a - <function>list_for_each_entry_rcu()</function> - (<filename>include/linux/list.h</filename>) to help you. Of - course, writers can just use - <function>list_for_each_entry()</function>, since there cannot - be two simultaneous writers. - </para> - <para> - Our final dilemma is this: when can we actually destroy the - removed element? Remember, a reader might be stepping through - this element in the list right now: if we free this element and - the <symbol>next</symbol> pointer changes, the reader will jump - off into garbage and crash. We need to wait until we know that - all the readers who were traversing the list when we deleted the - element are finished. We use <function>call_rcu()</function> to - register a callback which will actually destroy the object once - all pre-existing readers are finished. Alternatively, - <function>synchronize_rcu()</function> may be used to block until - all pre-existing are finished. - </para> - <para> - But how does Read Copy Update know when the readers are - finished? The method is this: firstly, the readers always - traverse the list inside - <function>rcu_read_lock()</function>/<function>rcu_read_unlock()</function> - pairs: these simply disable preemption so the reader won't go to - sleep while reading the list. - </para> - <para> - RCU then waits until every other CPU has slept at least once: - since readers cannot sleep, we know that any readers which were - traversing the list during the deletion are finished, and the - callback is triggered. The real Read Copy Update code is a - little more optimized than this, but this is the fundamental - idea. - </para> - -<programlisting> ---- cache.c.perobjectlock 2003-12-11 17:15:03.000000000 +1100 -+++ cache.c.rcupdate 2003-12-11 17:55:14.000000000 +1100 -@@ -1,15 +1,18 @@ - #include <linux/list.h> - #include <linux/slab.h> - #include <linux/string.h> -+#include <linux/rcupdate.h> - #include <linux/mutex.h> - #include <asm/errno.h> - - struct object - { -- /* These two protected by cache_lock. */ -+ /* This is protected by RCU */ - struct list_head list; - int popularity; - -+ struct rcu_head rcu; -+ - atomic_t refcnt; - - /* Doesn't change once created. */ -@@ -40,7 +43,7 @@ - { - struct object *i; - -- list_for_each_entry(i, &cache, list) { -+ list_for_each_entry_rcu(i, &cache, list) { - if (i->id == id) { - i->popularity++; - return i; -@@ -49,19 +52,25 @@ - return NULL; - } - -+/* Final discard done once we know no readers are looking. */ -+static void cache_delete_rcu(void *arg) -+{ -+ object_put(arg); -+} -+ - /* Must be holding cache_lock */ - static void __cache_delete(struct object *obj) - { - BUG_ON(!obj); -- list_del(&obj->list); -- object_put(obj); -+ list_del_rcu(&obj->list); - cache_num--; -+ call_rcu(&obj->rcu, cache_delete_rcu); - } - - /* Must be holding cache_lock */ - static void __cache_add(struct object *obj) - { -- list_add(&obj->list, &cache); -+ list_add_rcu(&obj->list, &cache); - if (++cache_num > MAX_CACHE_SIZE) { - struct object *i, *outcast = NULL; - list_for_each_entry(i, &cache, list) { -@@ -104,12 +114,11 @@ - struct object *cache_find(int id) - { - struct object *obj; -- unsigned long flags; - -- spin_lock_irqsave(&cache_lock, flags); -+ rcu_read_lock(); - obj = __cache_find(id); - if (obj) - object_get(obj); -- spin_unlock_irqrestore(&cache_lock, flags); -+ rcu_read_unlock(); - return obj; - } -</programlisting> - -<para> -Note that the reader will alter the -<structfield>popularity</structfield> member in -<function>__cache_find()</function>, and now it doesn't hold a lock. -One solution would be to make it an <type>atomic_t</type>, but for -this usage, we don't really care about races: an approximate result is -good enough, so I didn't change it. -</para> - -<para> -The result is that <function>cache_find()</function> requires no -synchronization with any other functions, so is almost as fast on SMP -as it would be on UP. -</para> - -<para> -There is a further optimization possible here: remember our original -cache code, where there were no reference counts and the caller simply -held the lock whenever using the object? This is still possible: if -you hold the lock, no one can delete the object, so you don't need to -get and put the reference count. -</para> - -<para> -Now, because the 'read lock' in RCU is simply disabling preemption, a -caller which always has preemption disabled between calling -<function>cache_find()</function> and -<function>object_put()</function> does not need to actually get and -put the reference count: we could expose -<function>__cache_find()</function> by making it non-static, and -such callers could simply call that. -</para> -<para> -The benefit here is that the reference count is not written to: the -object is not altered in any way, which is much faster on SMP -machines due to caching. -</para> - </sect1> - - <sect1 id="per-cpu"> - <title>Per-CPU Data</title> - - <para> - Another technique for avoiding locking which is used fairly - widely is to duplicate information for each CPU. For example, - if you wanted to keep a count of a common condition, you could - use a spin lock and a single counter. Nice and simple. - </para> - - <para> - If that was too slow (it's usually not, but if you've got a - really big machine to test on and can show that it is), you - could instead use a counter for each CPU, then none of them need - an exclusive lock. See <function>DEFINE_PER_CPU()</function>, - <function>get_cpu_var()</function> and - <function>put_cpu_var()</function> - (<filename class="headerfile">include/linux/percpu.h</filename>). - </para> - - <para> - Of particular use for simple per-cpu counters is the - <type>local_t</type> type, and the - <function>cpu_local_inc()</function> and related functions, - which are more efficient than simple code on some architectures - (<filename class="headerfile">include/asm/local.h</filename>). - </para> - - <para> - Note that there is no simple, reliable way of getting an exact - value of such a counter, without introducing more locks. This - is not a problem for some uses. - </para> - </sect1> - - <sect1 id="mostly-hardirq"> - <title>Data Which Mostly Used By An IRQ Handler</title> - - <para> - If data is always accessed from within the same IRQ handler, you - don't need a lock at all: the kernel already guarantees that the - irq handler will not run simultaneously on multiple CPUs. - </para> - <para> - Manfred Spraul points out that you can still do this, even if - the data is very occasionally accessed in user context or - softirqs/tasklets. The irq handler doesn't use a lock, and - all other accesses are done as so: - </para> - -<programlisting> - spin_lock(&lock); - disable_irq(irq); - ... - enable_irq(irq); - spin_unlock(&lock); -</programlisting> - <para> - The <function>disable_irq()</function> prevents the irq handler - from running (and waits for it to finish if it's currently - running on other CPUs). The spinlock prevents any other - accesses happening at the same time. Naturally, this is slower - than just a <function>spin_lock_irq()</function> call, so it - only makes sense if this type of access happens extremely - rarely. - </para> - </sect1> - </chapter> - - <chapter id="sleeping-things"> - <title>What Functions Are Safe To Call From Interrupts?</title> - - <para> - Many functions in the kernel sleep (ie. call schedule()) - directly or indirectly: you can never call them while holding a - spinlock, or with preemption disabled. This also means you need - to be in user context: calling them from an interrupt is illegal. - </para> - - <sect1 id="sleeping"> - <title>Some Functions Which Sleep</title> - - <para> - The most common ones are listed below, but you usually have to - read the code to find out if other calls are safe. If everyone - else who calls it can sleep, you probably need to be able to - sleep, too. In particular, registration and deregistration - functions usually expect to be called from user context, and can - sleep. - </para> - - <itemizedlist> - <listitem> - <para> - Accesses to - <firstterm linkend="gloss-userspace">userspace</firstterm>: - </para> - <itemizedlist> - <listitem> - <para> - <function>copy_from_user()</function> - </para> - </listitem> - <listitem> - <para> - <function>copy_to_user()</function> - </para> - </listitem> - <listitem> - <para> - <function>get_user()</function> - </para> - </listitem> - <listitem> - <para> - <function>put_user()</function> - </para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para> - <function>kmalloc(GFP_KERNEL)</function> - </para> - </listitem> - - <listitem> - <para> - <function>mutex_lock_interruptible()</function> and - <function>mutex_lock()</function> - </para> - <para> - There is a <function>mutex_trylock()</function> which does not - sleep. Still, it must not be used inside interrupt context since - its implementation is not safe for that. - <function>mutex_unlock()</function> will also never sleep. - It cannot be used in interrupt context either since a mutex - must be released by the same task that acquired it. - </para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="dont-sleep"> - <title>Some Functions Which Don't Sleep</title> - - <para> - Some functions are safe to call from any context, or holding - almost any lock. - </para> - - <itemizedlist> - <listitem> - <para> - <function>printk()</function> - </para> - </listitem> - <listitem> - <para> - <function>kfree()</function> - </para> - </listitem> - <listitem> - <para> - <function>add_timer()</function> and <function>del_timer()</function> - </para> - </listitem> - </itemizedlist> - </sect1> - </chapter> - - <chapter id="apiref-mutex"> - <title>Mutex API reference</title> -!Iinclude/linux/mutex.h -!Ekernel/locking/mutex.c - </chapter> - - <chapter id="apiref-futex"> - <title>Futex API reference</title> -!Ikernel/futex.c - </chapter> - - <chapter id="references"> - <title>Further reading</title> - - <itemizedlist> - <listitem> - <para> - <filename>Documentation/locking/spinlocks.txt</filename>: - Linus Torvalds' spinlocking tutorial in the kernel sources. - </para> - </listitem> - - <listitem> - <para> - Unix Systems for Modern Architectures: Symmetric - Multiprocessing and Caching for Kernel Programmers: - </para> - - <para> - Curt Schimmel's very good introduction to kernel level - locking (not written for Linux, but nearly everything - applies). The book is expensive, but really worth every - penny to understand SMP locking. [ISBN: 0201633388] - </para> - </listitem> - </itemizedlist> - </chapter> - - <chapter id="thanks"> - <title>Thanks</title> - - <para> - Thanks to Telsa Gwynne for DocBooking, neatening and adding - style. - </para> - - <para> - Thanks to Martin Pool, Philipp Rumpf, Stephen Rothwell, Paul - Mackerras, Ruedi Aschwanden, Alan Cox, Manfred Spraul, Tim - Waugh, Pete Zaitcev, James Morris, Robert Love, Paul McKenney, - John Ashby for proofreading, correcting, flaming, commenting. - </para> - - <para> - Thanks to the cabal for having no influence on this document. - </para> - </chapter> - - <glossary id="glossary"> - <title>Glossary</title> - - <glossentry id="gloss-preemption"> - <glossterm>preemption</glossterm> - <glossdef> - <para> - Prior to 2.5, or when <symbol>CONFIG_PREEMPT</symbol> is - unset, processes in user context inside the kernel would not - preempt each other (ie. you had that CPU until you gave it up, - except for interrupts). With the addition of - <symbol>CONFIG_PREEMPT</symbol> in 2.5.4, this changed: when - in user context, higher priority tasks can "cut in": spinlocks - were changed to disable preemption, even on UP. - </para> - </glossdef> - </glossentry> - - <glossentry id="gloss-bh"> - <glossterm>bh</glossterm> - <glossdef> - <para> - Bottom Half: for historical reasons, functions with - '_bh' in them often now refer to any software interrupt, e.g. - <function>spin_lock_bh()</function> blocks any software interrupt - on the current CPU. Bottom halves are deprecated, and will - eventually be replaced by tasklets. Only one bottom half will be - running at any time. - </para> - </glossdef> - </glossentry> - - <glossentry id="gloss-hwinterrupt"> - <glossterm>Hardware Interrupt / Hardware IRQ</glossterm> - <glossdef> - <para> - Hardware interrupt request. <function>in_irq()</function> returns - <returnvalue>true</returnvalue> in a hardware interrupt handler. - </para> - </glossdef> - </glossentry> - - <glossentry id="gloss-interruptcontext"> - <glossterm>Interrupt Context</glossterm> - <glossdef> - <para> - Not user context: processing a hardware irq or software irq. - Indicated by the <function>in_interrupt()</function> macro - returning <returnvalue>true</returnvalue>. - </para> - </glossdef> - </glossentry> - - <glossentry id="gloss-smp"> - <glossterm><acronym>SMP</acronym></glossterm> - <glossdef> - <para> - Symmetric Multi-Processor: kernels compiled for multiple-CPU - machines. (CONFIG_SMP=y). - </para> - </glossdef> - </glossentry> - - <glossentry id="gloss-softirq"> - <glossterm>Software Interrupt / softirq</glossterm> - <glossdef> - <para> - Software interrupt handler. <function>in_irq()</function> returns - <returnvalue>false</returnvalue>; <function>in_softirq()</function> - returns <returnvalue>true</returnvalue>. Tasklets and softirqs - both fall into the category of 'software interrupts'. - </para> - <para> - Strictly speaking a softirq is one of up to 32 enumerated software - interrupts which can run on multiple CPUs at once. - Sometimes used to refer to tasklets as - well (ie. all software interrupts). - </para> - </glossdef> - </glossentry> - - <glossentry id="gloss-tasklet"> - <glossterm>tasklet</glossterm> - <glossdef> - <para> - A dynamically-registrable software interrupt, - which is guaranteed to only run on one CPU at a time. - </para> - </glossdef> - </glossentry> - - <glossentry id="gloss-timers"> - <glossterm>timer</glossterm> - <glossdef> - <para> - A dynamically-registrable software interrupt, which is run at - (or close to) a given time. When running, it is just like a - tasklet (in fact, they are called from the TIMER_SOFTIRQ). - </para> - </glossdef> - </glossentry> - - <glossentry id="gloss-up"> - <glossterm><acronym>UP</acronym></glossterm> - <glossdef> - <para> - Uni-Processor: Non-SMP. (CONFIG_SMP=n). - </para> - </glossdef> - </glossentry> - - <glossentry id="gloss-usercontext"> - <glossterm>User Context</glossterm> - <glossdef> - <para> - The kernel executing on behalf of a particular process (ie. a - system call or trap) or kernel thread. You can tell which - process with the <symbol>current</symbol> macro.) Not to - be confused with userspace. Can be interrupted by software or - hardware interrupts. - </para> - </glossdef> - </glossentry> - - <glossentry id="gloss-userspace"> - <glossterm>Userspace</glossterm> - <glossdef> - <para> - A process executing its own code outside the kernel. - </para> - </glossdef> - </glossentry> - - </glossary> -</book> - diff --git a/Documentation/DocBook/kgdb.tmpl b/Documentation/DocBook/kgdb.tmpl deleted file mode 100644 index f3abca7ec53d..000000000000 --- a/Documentation/DocBook/kgdb.tmpl +++ /dev/null @@ -1,918 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="kgdbOnLinux"> - <bookinfo> - <title>Using kgdb, kdb and the kernel debugger internals</title> - - <authorgroup> - <author> - <firstname>Jason</firstname> - <surname>Wessel</surname> - <affiliation> - <address> - <email>jason.wessel@windriver.com</email> - </address> - </affiliation> - </author> - </authorgroup> - <copyright> - <year>2008,2010</year> - <holder>Wind River Systems, Inc.</holder> - </copyright> - <copyright> - <year>2004-2005</year> - <holder>MontaVista Software, Inc.</holder> - </copyright> - <copyright> - <year>2004</year> - <holder>Amit S. Kale</holder> - </copyright> - - <legalnotice> - <para> - This file is licensed under the terms of the GNU General Public License - version 2. This program is licensed "as is" without any warranty of any - kind, whether express or implied. - </para> - - </legalnotice> - </bookinfo> - -<toc></toc> - <chapter id="Introduction"> - <title>Introduction</title> - <para> - The kernel has two different debugger front ends (kdb and kgdb) - which interface to the debug core. It is possible to use either - of the debugger front ends and dynamically transition between them - if you configure the kernel properly at compile and runtime. - </para> - <para> - Kdb is simplistic shell-style interface which you can use on a - system console with a keyboard or serial console. You can use it - to inspect memory, registers, process lists, dmesg, and even set - breakpoints to stop in a certain location. Kdb is not a source - level debugger, although you can set breakpoints and execute some - basic kernel run control. Kdb is mainly aimed at doing some - analysis to aid in development or diagnosing kernel problems. You - can access some symbols by name in kernel built-ins or in kernel - modules if the code was built - with <symbol>CONFIG_KALLSYMS</symbol>. - </para> - <para> - Kgdb is intended to be used as a source level debugger for the - Linux kernel. It is used along with gdb to debug a Linux kernel. - The expectation is that gdb can be used to "break in" to the - kernel to inspect memory, variables and look through call stack - information similar to the way an application developer would use - gdb to debug an application. It is possible to place breakpoints - in kernel code and perform some limited execution stepping. - </para> - <para> - Two machines are required for using kgdb. One of these machines is - a development machine and the other is the target machine. The - kernel to be debugged runs on the target machine. The development - machine runs an instance of gdb against the vmlinux file which - contains the symbols (not a boot image such as bzImage, zImage, - uImage...). In gdb the developer specifies the connection - parameters and connects to kgdb. The type of connection a - developer makes with gdb depends on the availability of kgdb I/O - modules compiled as built-ins or loadable kernel modules in the test - machine's kernel. - </para> - </chapter> - <chapter id="CompilingAKernel"> - <title>Compiling a kernel</title> - <para> - <itemizedlist> - <listitem><para>In order to enable compilation of kdb, you must first enable kgdb.</para></listitem> - <listitem><para>The kgdb test compile options are described in the kgdb test suite chapter.</para></listitem> - </itemizedlist> - </para> - <sect1 id="CompileKGDB"> - <title>Kernel config options for kgdb</title> - <para> - To enable <symbol>CONFIG_KGDB</symbol> you should look under - "Kernel hacking" / "Kernel debugging" and select "KGDB: kernel debugger". - </para> - <para> - While it is not a hard requirement that you have symbols in your - vmlinux file, gdb tends not to be very useful without the symbolic - data, so you will want to turn - on <symbol>CONFIG_DEBUG_INFO</symbol> which is called "Compile the - kernel with debug info" in the config menu. - </para> - <para> - It is advised, but not required, that you turn on the - <symbol>CONFIG_FRAME_POINTER</symbol> kernel option which is called "Compile the - kernel with frame pointers" in the config menu. This option - inserts code to into the compiled executable which saves the frame - information in registers or on the stack at different points which - allows a debugger such as gdb to more accurately construct - stack back traces while debugging the kernel. - </para> - <para> - If the architecture that you are using supports the kernel option - CONFIG_DEBUG_RODATA, you should consider turning it off. This - option will prevent the use of software breakpoints because it - marks certain regions of the kernel's memory space as read-only. - If kgdb supports it for the architecture you are using, you can - use hardware breakpoints if you desire to run with the - CONFIG_DEBUG_RODATA option turned on, else you need to turn off - this option. - </para> - <para> - Next you should choose one of more I/O drivers to interconnect - debugging host and debugged target. Early boot debugging requires - a KGDB I/O driver that supports early debugging and the driver - must be built into the kernel directly. Kgdb I/O driver - configuration takes place via kernel or module parameters which - you can learn more about in the in the section that describes the - parameter "kgdboc". - </para> - <para>Here is an example set of .config symbols to enable or - disable for kgdb: - <itemizedlist> - <listitem><para># CONFIG_DEBUG_RODATA is not set</para></listitem> - <listitem><para>CONFIG_FRAME_POINTER=y</para></listitem> - <listitem><para>CONFIG_KGDB=y</para></listitem> - <listitem><para>CONFIG_KGDB_SERIAL_CONSOLE=y</para></listitem> - </itemizedlist> - </para> - </sect1> - <sect1 id="CompileKDB"> - <title>Kernel config options for kdb</title> - <para>Kdb is quite a bit more complex than the simple gdbstub - sitting on top of the kernel's debug core. Kdb must implement a - shell, and also adds some helper functions in other parts of the - kernel, responsible for printing out interesting data such as what - you would see if you ran "lsmod", or "ps". In order to build kdb - into the kernel you follow the same steps as you would for kgdb. - </para> - <para>The main config option for kdb - is <symbol>CONFIG_KGDB_KDB</symbol> which is called "KGDB_KDB: - include kdb frontend for kgdb" in the config menu. In theory you - would have already also selected an I/O driver such as the - CONFIG_KGDB_SERIAL_CONSOLE interface if you plan on using kdb on a - serial port, when you were configuring kgdb. - </para> - <para>If you want to use a PS/2-style keyboard with kdb, you would - select CONFIG_KDB_KEYBOARD which is called "KGDB_KDB: keyboard as - input device" in the config menu. The CONFIG_KDB_KEYBOARD option - is not used for anything in the gdb interface to kgdb. The - CONFIG_KDB_KEYBOARD option only works with kdb. - </para> - <para>Here is an example set of .config symbols to enable/disable kdb: - <itemizedlist> - <listitem><para># CONFIG_DEBUG_RODATA is not set</para></listitem> - <listitem><para>CONFIG_FRAME_POINTER=y</para></listitem> - <listitem><para>CONFIG_KGDB=y</para></listitem> - <listitem><para>CONFIG_KGDB_SERIAL_CONSOLE=y</para></listitem> - <listitem><para>CONFIG_KGDB_KDB=y</para></listitem> - <listitem><para>CONFIG_KDB_KEYBOARD=y</para></listitem> - </itemizedlist> - </para> - </sect1> - </chapter> - <chapter id="kgdbKernelArgs"> - <title>Kernel Debugger Boot Arguments</title> - <para>This section describes the various runtime kernel - parameters that affect the configuration of the kernel debugger. - The following chapter covers using kdb and kgdb as well as - providing some examples of the configuration parameters.</para> - <sect1 id="kgdboc"> - <title>Kernel parameter: kgdboc</title> - <para>The kgdboc driver was originally an abbreviation meant to - stand for "kgdb over console". Today it is the primary mechanism - to configure how to communicate from gdb to kgdb as well as the - devices you want to use to interact with the kdb shell. - </para> - <para>For kgdb/gdb, kgdboc is designed to work with a single serial - port. It is intended to cover the circumstance where you want to - use a serial console as your primary console as well as using it to - perform kernel debugging. It is also possible to use kgdb on a - serial port which is not designated as a system console. Kgdboc - may be configured as a kernel built-in or a kernel loadable module. - You can only make use of <constant>kgdbwait</constant> and early - debugging if you build kgdboc into the kernel as a built-in. - </para> - <para>Optionally you can elect to activate kms (Kernel Mode - Setting) integration. When you use kms with kgdboc and you have a - video driver that has atomic mode setting hooks, it is possible to - enter the debugger on the graphics console. When the kernel - execution is resumed, the previous graphics mode will be restored. - This integration can serve as a useful tool to aid in diagnosing - crashes or doing analysis of memory with kdb while allowing the - full graphics console applications to run. - </para> - <sect2 id="kgdbocArgs"> - <title>kgdboc arguments</title> - <para>Usage: <constant>kgdboc=[kms][[,]kbd][[,]serial_device][,baud]</constant></para> - <para>The order listed above must be observed if you use any of the - optional configurations together. - </para> - <para>Abbreviations: - <itemizedlist> - <listitem><para>kms = Kernel Mode Setting</para></listitem> - <listitem><para>kbd = Keyboard</para></listitem> - </itemizedlist> - </para> - <para>You can configure kgdboc to use the keyboard, and/or a serial - device depending on if you are using kdb and/or kgdb, in one of the - following scenarios. The order listed above must be observed if - you use any of the optional configurations together. Using kms + - only gdb is generally not a useful combination.</para> - <sect3 id="kgdbocArgs1"> - <title>Using loadable module or built-in</title> - <para> - <orderedlist> - <listitem><para>As a kernel built-in:</para> - <para>Use the kernel boot argument: <constant>kgdboc=<tty-device>,[baud]</constant></para></listitem> - <listitem> - <para>As a kernel loadable module:</para> - <para>Use the command: <constant>modprobe kgdboc kgdboc=<tty-device>,[baud]</constant></para> - <para>Here are two examples of how you might format the kgdboc - string. The first is for an x86 target using the first serial port. - The second example is for the ARM Versatile AB using the second - serial port. - <orderedlist> - <listitem><para><constant>kgdboc=ttyS0,115200</constant></para></listitem> - <listitem><para><constant>kgdboc=ttyAMA1,115200</constant></para></listitem> - </orderedlist> - </para> - </listitem> - </orderedlist></para> - </sect3> - <sect3 id="kgdbocArgs2"> - <title>Configure kgdboc at runtime with sysfs</title> - <para>At run time you can enable or disable kgdboc by echoing a - parameters into the sysfs. Here are two examples:</para> - <orderedlist> - <listitem><para>Enable kgdboc on ttyS0</para> - <para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> - <listitem><para>Disable kgdboc</para> - <para><constant>echo "" > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> - </orderedlist> - <para>NOTE: You do not need to specify the baud if you are - configuring the console on tty which is already configured or - open.</para> - </sect3> - <sect3 id="kgdbocArgs3"> - <title>More examples</title> - <para>You can configure kgdboc to use the keyboard, and/or a serial device - depending on if you are using kdb and/or kgdb, in one of the - following scenarios. - <orderedlist> - <listitem><para>kdb and kgdb over only a serial port</para> - <para><constant>kgdboc=<serial_device>[,baud]</constant></para> - <para>Example: <constant>kgdboc=ttyS0,115200</constant></para> - </listitem> - <listitem><para>kdb and kgdb with keyboard and a serial port</para> - <para><constant>kgdboc=kbd,<serial_device>[,baud]</constant></para> - <para>Example: <constant>kgdboc=kbd,ttyS0,115200</constant></para> - </listitem> - <listitem><para>kdb with a keyboard</para> - <para><constant>kgdboc=kbd</constant></para> - </listitem> - <listitem><para>kdb with kernel mode setting</para> - <para><constant>kgdboc=kms,kbd</constant></para> - </listitem> - <listitem><para>kdb with kernel mode setting and kgdb over a serial port</para> - <para><constant>kgdboc=kms,kbd,ttyS0,115200</constant></para> - </listitem> - </orderedlist> - </para> - <para>NOTE: Kgdboc does not support interrupting the target via the - gdb remote protocol. You must manually send a sysrq-g unless you - have a proxy that splits console output to a terminal program. - A console proxy has a separate TCP port for the debugger and a separate - TCP port for the "human" console. The proxy can take care of sending - the sysrq-g for you. - </para> - <para>When using kgdboc with no debugger proxy, you can end up - connecting the debugger at one of two entry points. If an - exception occurs after you have loaded kgdboc, a message should - print on the console stating it is waiting for the debugger. In - this case you disconnect your terminal program and then connect the - debugger in its place. If you want to interrupt the target system - and forcibly enter a debug session you have to issue a Sysrq - sequence and then type the letter <constant>g</constant>. Then - you disconnect the terminal session and connect gdb. Your options - if you don't like this are to hack gdb to send the sysrq-g for you - as well as on the initial connect, or to use a debugger proxy that - allows an unmodified gdb to do the debugging. - </para> - </sect3> - </sect2> - </sect1> - <sect1 id="kgdbwait"> - <title>Kernel parameter: kgdbwait</title> - <para> - The Kernel command line option <constant>kgdbwait</constant> makes - kgdb wait for a debugger connection during booting of a kernel. You - can only use this option if you compiled a kgdb I/O driver into the - kernel and you specified the I/O driver configuration as a kernel - command line option. The kgdbwait parameter should always follow the - configuration parameter for the kgdb I/O driver in the kernel - command line else the I/O driver will not be configured prior to - asking the kernel to use it to wait. - </para> - <para> - The kernel will stop and wait as early as the I/O driver and - architecture allows when you use this option. If you build the - kgdb I/O driver as a loadable kernel module kgdbwait will not do - anything. - </para> - </sect1> - <sect1 id="kgdbcon"> - <title>Kernel parameter: kgdbcon</title> - <para> The kgdbcon feature allows you to see printk() messages - inside gdb while gdb is connected to the kernel. Kdb does not make - use of the kgdbcon feature. - </para> - <para>Kgdb supports using the gdb serial protocol to send console - messages to the debugger when the debugger is connected and running. - There are two ways to activate this feature. - <orderedlist> - <listitem><para>Activate with the kernel command line option:</para> - <para><constant>kgdbcon</constant></para> - </listitem> - <listitem><para>Use sysfs before configuring an I/O driver</para> - <para> - <constant>echo 1 > /sys/module/kgdb/parameters/kgdb_use_con</constant> - </para> - <para> - NOTE: If you do this after you configure the kgdb I/O driver, the - setting will not take effect until the next point the I/O is - reconfigured. - </para> - </listitem> - </orderedlist> - </para> - <para>IMPORTANT NOTE: You cannot use kgdboc + kgdbcon on a tty that is an - active system console. An example of incorrect usage is <constant>console=ttyS0,115200 kgdboc=ttyS0 kgdbcon</constant> - </para> - <para>It is possible to use this option with kgdboc on a tty that is not a system console. - </para> - </sect1> - <sect1 id="kgdbreboot"> - <title>Run time parameter: kgdbreboot</title> - <para> The kgdbreboot feature allows you to change how the debugger - deals with the reboot notification. You have 3 choices for the - behavior. The default behavior is always set to 0.</para> - <orderedlist> - <listitem><para>echo -1 > /sys/module/debug_core/parameters/kgdbreboot</para> - <para>Ignore the reboot notification entirely.</para> - </listitem> - <listitem><para>echo 0 > /sys/module/debug_core/parameters/kgdbreboot</para> - <para>Send the detach message to any attached debugger client.</para> - </listitem> - <listitem><para>echo 1 > /sys/module/debug_core/parameters/kgdbreboot</para> - <para>Enter the debugger on reboot notify.</para> - </listitem> - </orderedlist> - </sect1> - </chapter> - <chapter id="usingKDB"> - <title>Using kdb</title> - <para> - </para> - <sect1 id="quickKDBserial"> - <title>Quick start for kdb on a serial port</title> - <para>This is a quick example of how to use kdb.</para> - <para><orderedlist> - <listitem><para>Configure kgdboc at boot using kernel parameters: - <itemizedlist> - <listitem><para><constant>console=ttyS0,115200 kgdboc=ttyS0,115200</constant></para></listitem> - </itemizedlist></para> - <para>OR</para> - <para>Configure kgdboc after the kernel has booted; assuming you are using a serial port console: - <itemizedlist> - <listitem><para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> - </itemizedlist> - </para> - </listitem> - <listitem><para>Enter the kernel debugger manually or by waiting for an oops or fault. There are several ways you can enter the kernel debugger manually; all involve using the sysrq-g, which means you must have enabled CONFIG_MAGIC_SYSRQ=y in your kernel config.</para> - <itemizedlist> - <listitem><para>When logged in as root or with a super user session you can run:</para> - <para><constant>echo g > /proc/sysrq-trigger</constant></para></listitem> - <listitem><para>Example using minicom 2.2</para> - <para>Press: <constant>Control-a</constant></para> - <para>Press: <constant>f</constant></para> - <para>Press: <constant>g</constant></para> - </listitem> - <listitem><para>When you have telneted to a terminal server that supports sending a remote break</para> - <para>Press: <constant>Control-]</constant></para> - <para>Type in:<constant>send break</constant></para> - <para>Press: <constant>Enter</constant></para> - <para>Press: <constant>g</constant></para> - </listitem> - </itemizedlist> - </listitem> - <listitem><para>From the kdb prompt you can run the "help" command to see a complete list of the commands that are available.</para> - <para>Some useful commands in kdb include: - <itemizedlist> - <listitem><para>lsmod -- Shows where kernel modules are loaded</para></listitem> - <listitem><para>ps -- Displays only the active processes</para></listitem> - <listitem><para>ps A -- Shows all the processes</para></listitem> - <listitem><para>summary -- Shows kernel version info and memory usage</para></listitem> - <listitem><para>bt -- Get a backtrace of the current process using dump_stack()</para></listitem> - <listitem><para>dmesg -- View the kernel syslog buffer</para></listitem> - <listitem><para>go -- Continue the system</para></listitem> - </itemizedlist> - </para> - </listitem> - <listitem> - <para>When you are done using kdb you need to consider rebooting the - system or using the "go" command to resuming normal kernel - execution. If you have paused the kernel for a lengthy period of - time, applications that rely on timely networking or anything to do - with real wall clock time could be adversely affected, so you - should take this into consideration when using the kernel - debugger.</para> - </listitem> - </orderedlist></para> - </sect1> - <sect1 id="quickKDBkeyboard"> - <title>Quick start for kdb using a keyboard connected console</title> - <para>This is a quick example of how to use kdb with a keyboard.</para> - <para><orderedlist> - <listitem><para>Configure kgdboc at boot using kernel parameters: - <itemizedlist> - <listitem><para><constant>kgdboc=kbd</constant></para></listitem> - </itemizedlist></para> - <para>OR</para> - <para>Configure kgdboc after the kernel has booted: - <itemizedlist> - <listitem><para><constant>echo kbd > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> - </itemizedlist> - </para> - </listitem> - <listitem><para>Enter the kernel debugger manually or by waiting for an oops or fault. There are several ways you can enter the kernel debugger manually; all involve using the sysrq-g, which means you must have enabled CONFIG_MAGIC_SYSRQ=y in your kernel config.</para> - <itemizedlist> - <listitem><para>When logged in as root or with a super user session you can run:</para> - <para><constant>echo g > /proc/sysrq-trigger</constant></para></listitem> - <listitem><para>Example using a laptop keyboard</para> - <para>Press and hold down: <constant>Alt</constant></para> - <para>Press and hold down: <constant>Fn</constant></para> - <para>Press and release the key with the label: <constant>SysRq</constant></para> - <para>Release: <constant>Fn</constant></para> - <para>Press and release: <constant>g</constant></para> - <para>Release: <constant>Alt</constant></para> - </listitem> - <listitem><para>Example using a PS/2 101-key keyboard</para> - <para>Press and hold down: <constant>Alt</constant></para> - <para>Press and release the key with the label: <constant>SysRq</constant></para> - <para>Press and release: <constant>g</constant></para> - <para>Release: <constant>Alt</constant></para> - </listitem> - </itemizedlist> - </listitem> - <listitem> - <para>Now type in a kdb command such as "help", "dmesg", "bt" or "go" to continue kernel execution.</para> - </listitem> - </orderedlist></para> - </sect1> - </chapter> - <chapter id="EnableKGDB"> - <title>Using kgdb / gdb</title> - <para>In order to use kgdb you must activate it by passing - configuration information to one of the kgdb I/O drivers. If you - do not pass any configuration information kgdb will not do anything - at all. Kgdb will only actively hook up to the kernel trap hooks - if a kgdb I/O driver is loaded and configured. If you unconfigure - a kgdb I/O driver, kgdb will unregister all the kernel hook points. - </para> - <para> All kgdb I/O drivers can be reconfigured at run time, if - <symbol>CONFIG_SYSFS</symbol> and <symbol>CONFIG_MODULES</symbol> - are enabled, by echo'ing a new config string to - <constant>/sys/module/<driver>/parameter/<option></constant>. - The driver can be unconfigured by passing an empty string. You cannot - change the configuration while the debugger is attached. Make sure - to detach the debugger with the <constant>detach</constant> command - prior to trying to unconfigure a kgdb I/O driver. - </para> - <sect1 id="ConnectingGDB"> - <title>Connecting with gdb to a serial port</title> - <orderedlist> - <listitem><para>Configure kgdboc</para> - <para>Configure kgdboc at boot using kernel parameters: - <itemizedlist> - <listitem><para><constant>kgdboc=ttyS0,115200</constant></para></listitem> - </itemizedlist></para> - <para>OR</para> - <para>Configure kgdboc after the kernel has booted: - <itemizedlist> - <listitem><para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> - </itemizedlist></para> - </listitem> - <listitem> - <para>Stop kernel execution (break into the debugger)</para> - <para>In order to connect to gdb via kgdboc, the kernel must - first be stopped. There are several ways to stop the kernel which - include using kgdbwait as a boot argument, via a sysrq-g, or running - the kernel until it takes an exception where it waits for the - debugger to attach. - <itemizedlist> - <listitem><para>When logged in as root or with a super user session you can run:</para> - <para><constant>echo g > /proc/sysrq-trigger</constant></para></listitem> - <listitem><para>Example using minicom 2.2</para> - <para>Press: <constant>Control-a</constant></para> - <para>Press: <constant>f</constant></para> - <para>Press: <constant>g</constant></para> - </listitem> - <listitem><para>When you have telneted to a terminal server that supports sending a remote break</para> - <para>Press: <constant>Control-]</constant></para> - <para>Type in:<constant>send break</constant></para> - <para>Press: <constant>Enter</constant></para> - <para>Press: <constant>g</constant></para> - </listitem> - </itemizedlist> - </para> - </listitem> - <listitem> - <para>Connect from gdb</para> - <para> - Example (using a directly connected port): - </para> - <programlisting> - % gdb ./vmlinux - (gdb) set remotebaud 115200 - (gdb) target remote /dev/ttyS0 - </programlisting> - <para> - Example (kgdb to a terminal server on TCP port 2012): - </para> - <programlisting> - % gdb ./vmlinux - (gdb) target remote 192.168.2.2:2012 - </programlisting> - <para> - Once connected, you can debug a kernel the way you would debug an - application program. - </para> - <para> - If you are having problems connecting or something is going - seriously wrong while debugging, it will most often be the case - that you want to enable gdb to be verbose about its target - communications. You do this prior to issuing the <constant>target - remote</constant> command by typing in: <constant>set debug remote 1</constant> - </para> - </listitem> - </orderedlist> - <para>Remember if you continue in gdb, and need to "break in" again, - you need to issue an other sysrq-g. It is easy to create a simple - entry point by putting a breakpoint at <constant>sys_sync</constant> - and then you can run "sync" from a shell or script to break into the - debugger.</para> - </sect1> - </chapter> - <chapter id="switchKdbKgdb"> - <title>kgdb and kdb interoperability</title> - <para>It is possible to transition between kdb and kgdb dynamically. - The debug core will remember which you used the last time and - automatically start in the same mode.</para> - <sect1> - <title>Switching between kdb and kgdb</title> - <sect2> - <title>Switching from kgdb to kdb</title> - <para> - There are two ways to switch from kgdb to kdb: you can use gdb to - issue a maintenance packet, or you can blindly type the command $3#33. - Whenever the kernel debugger stops in kgdb mode it will print the - message <constant>KGDB or $3#33 for KDB</constant>. It is important - to note that you have to type the sequence correctly in one pass. - You cannot type a backspace or delete because kgdb will interpret - that as part of the debug stream. - <orderedlist> - <listitem><para>Change from kgdb to kdb by blindly typing:</para> - <para><constant>$3#33</constant></para></listitem> - <listitem><para>Change from kgdb to kdb with gdb</para> - <para><constant>maintenance packet 3</constant></para> - <para>NOTE: Now you must kill gdb. Typically you press control-z and - issue the command: kill -9 %</para></listitem> - </orderedlist> - </para> - </sect2> - <sect2> - <title>Change from kdb to kgdb</title> - <para>There are two ways you can change from kdb to kgdb. You can - manually enter kgdb mode by issuing the kgdb command from the kdb - shell prompt, or you can connect gdb while the kdb shell prompt is - active. The kdb shell looks for the typical first commands that gdb - would issue with the gdb remote protocol and if it sees one of those - commands it automatically changes into kgdb mode.</para> - <orderedlist> - <listitem><para>From kdb issue the command:</para> - <para><constant>kgdb</constant></para> - <para>Now disconnect your terminal program and connect gdb in its place</para></listitem> - <listitem><para>At the kdb prompt, disconnect the terminal program and connect gdb in its place.</para></listitem> - </orderedlist> - </sect2> - </sect1> - <sect1> - <title>Running kdb commands from gdb</title> - <para>It is possible to run a limited set of kdb commands from gdb, - using the gdb monitor command. You don't want to execute any of the - run control or breakpoint operations, because it can disrupt the - state of the kernel debugger. You should be using gdb for - breakpoints and run control operations if you have gdb connected. - The more useful commands to run are things like lsmod, dmesg, ps or - possibly some of the memory information commands. To see all the kdb - commands you can run <constant>monitor help</constant>.</para> - <para>Example: - <informalexample><programlisting> -(gdb) monitor ps -1 idle process (state I) and -27 sleeping system daemon (state M) processes suppressed, -use 'ps A' to see all. -Task Addr Pid Parent [*] cpu State Thread Command - -0xc78291d0 1 0 0 0 S 0xc7829404 init -0xc7954150 942 1 0 0 S 0xc7954384 dropbear -0xc78789c0 944 1 0 0 S 0xc7878bf4 sh -(gdb) - </programlisting></informalexample> - </para> - </sect1> - </chapter> - <chapter id="KGDBTestSuite"> - <title>kgdb Test Suite</title> - <para> - When kgdb is enabled in the kernel config you can also elect to - enable the config parameter KGDB_TESTS. Turning this on will - enable a special kgdb I/O module which is designed to test the - kgdb internal functions. - </para> - <para> - The kgdb tests are mainly intended for developers to test the kgdb - internals as well as a tool for developing a new kgdb architecture - specific implementation. These tests are not really for end users - of the Linux kernel. The primary source of documentation would be - to look in the drivers/misc/kgdbts.c file. - </para> - <para> - The kgdb test suite can also be configured at compile time to run - the core set of tests by setting the kernel config parameter - KGDB_TESTS_ON_BOOT. This particular option is aimed at automated - regression testing and does not require modifying the kernel boot - config arguments. If this is turned on, the kgdb test suite can - be disabled by specifying "kgdbts=" as a kernel boot argument. - </para> - </chapter> - <chapter id="CommonBackEndReq"> - <title>Kernel Debugger Internals</title> - <sect1 id="kgdbArchitecture"> - <title>Architecture Specifics</title> - <para> - The kernel debugger is organized into a number of components: - <orderedlist> - <listitem><para>The debug core</para> - <para> - The debug core is found in kernel/debugger/debug_core.c. It contains: - <itemizedlist> - <listitem><para>A generic OS exception handler which includes - sync'ing the processors into a stopped state on an multi-CPU - system.</para></listitem> - <listitem><para>The API to talk to the kgdb I/O drivers</para></listitem> - <listitem><para>The API to make calls to the arch-specific kgdb implementation</para></listitem> - <listitem><para>The logic to perform safe memory reads and writes to memory while using the debugger</para></listitem> - <listitem><para>A full implementation for software breakpoints unless overridden by the arch</para></listitem> - <listitem><para>The API to invoke either the kdb or kgdb frontend to the debug core.</para></listitem> - <listitem><para>The structures and callback API for atomic kernel mode setting.</para> - <para>NOTE: kgdboc is where the kms callbacks are invoked.</para></listitem> - </itemizedlist> - </para> - </listitem> - <listitem><para>kgdb arch-specific implementation</para> - <para> - This implementation is generally found in arch/*/kernel/kgdb.c. - As an example, arch/x86/kernel/kgdb.c contains the specifics to - implement HW breakpoint as well as the initialization to - dynamically register and unregister for the trap handlers on - this architecture. The arch-specific portion implements: - <itemizedlist> - <listitem><para>contains an arch-specific trap catcher which - invokes kgdb_handle_exception() to start kgdb about doing its - work</para></listitem> - <listitem><para>translation to and from gdb specific packet format to pt_regs</para></listitem> - <listitem><para>Registration and unregistration of architecture specific trap hooks</para></listitem> - <listitem><para>Any special exception handling and cleanup</para></listitem> - <listitem><para>NMI exception handling and cleanup</para></listitem> - <listitem><para>(optional) HW breakpoints</para></listitem> - </itemizedlist> - </para> - </listitem> - <listitem><para>gdbstub frontend (aka kgdb)</para> - <para>The gdbstub is located in kernel/debug/gdbstub.c. It contains:</para> - <itemizedlist> - <listitem><para>All the logic to implement the gdb serial protocol</para></listitem> - </itemizedlist> - </listitem> - <listitem><para>kdb frontend</para> - <para>The kdb debugger shell is broken down into a number of - components. The kdb core is located in kernel/debug/kdb. There - are a number of helper functions in some of the other kernel - components to make it possible for kdb to examine and report - information about the kernel without taking locks that could - cause a kernel deadlock. The kdb core contains implements the following functionality.</para> - <itemizedlist> - <listitem><para>A simple shell</para></listitem> - <listitem><para>The kdb core command set</para></listitem> - <listitem><para>A registration API to register additional kdb shell commands.</para> - <itemizedlist> - <listitem><para>A good example of a self-contained kdb module - is the "ftdump" command for dumping the ftrace buffer. See: - kernel/trace/trace_kdb.c</para></listitem> - <listitem><para>For an example of how to dynamically register - a new kdb command you can build the kdb_hello.ko kernel module - from samples/kdb/kdb_hello.c. To build this example you can - set CONFIG_SAMPLES=y and CONFIG_SAMPLE_KDB=m in your kernel - config. Later run "modprobe kdb_hello" and the next time you - enter the kdb shell, you can run the "hello" - command.</para></listitem> - </itemizedlist></listitem> - <listitem><para>The implementation for kdb_printf() which - emits messages directly to I/O drivers, bypassing the kernel - log.</para></listitem> - <listitem><para>SW / HW breakpoint management for the kdb shell</para></listitem> - </itemizedlist> - </listitem> - <listitem><para>kgdb I/O driver</para> - <para> - Each kgdb I/O driver has to provide an implementation for the following: - <itemizedlist> - <listitem><para>configuration via built-in or module</para></listitem> - <listitem><para>dynamic configuration and kgdb hook registration calls</para></listitem> - <listitem><para>read and write character interface</para></listitem> - <listitem><para>A cleanup handler for unconfiguring from the kgdb core</para></listitem> - <listitem><para>(optional) Early debug methodology</para></listitem> - </itemizedlist> - Any given kgdb I/O driver has to operate very closely with the - hardware and must do it in such a way that does not enable - interrupts or change other parts of the system context without - completely restoring them. The kgdb core will repeatedly "poll" - a kgdb I/O driver for characters when it needs input. The I/O - driver is expected to return immediately if there is no data - available. Doing so allows for the future possibility to touch - watchdog hardware in such a way as to have a target system not - reset when these are enabled. - </para> - </listitem> - </orderedlist> - </para> - <para> - If you are intent on adding kgdb architecture specific support - for a new architecture, the architecture should define - <constant>HAVE_ARCH_KGDB</constant> in the architecture specific - Kconfig file. This will enable kgdb for the architecture, and - at that point you must create an architecture specific kgdb - implementation. - </para> - <para> - There are a few flags which must be set on every architecture in - their <asm/kgdb.h> file. These are: - <itemizedlist> - <listitem> - <para> - NUMREGBYTES: The size in bytes of all of the registers, so - that we can ensure they will all fit into a packet. - </para> - </listitem> - <listitem> - <para> - BUFMAX: The size in bytes of the buffer GDB will read into. - This must be larger than NUMREGBYTES. - </para> - </listitem> - <listitem> - <para> - CACHE_FLUSH_IS_SAFE: Set to 1 if it is always safe to call - flush_cache_range or flush_icache_range. On some architectures, - these functions may not be safe to call on SMP since we keep other - CPUs in a holding pattern. - </para> - </listitem> - </itemizedlist> - </para> - <para> - There are also the following functions for the common backend, - found in kernel/kgdb.c, that must be supplied by the - architecture-specific backend unless marked as (optional), in - which case a default function maybe used if the architecture - does not need to provide a specific implementation. - </para> -!Iinclude/linux/kgdb.h - </sect1> - <sect1 id="kgdbocDesign"> - <title>kgdboc internals</title> - <sect2> - <title>kgdboc and uarts</title> - <para> - The kgdboc driver is actually a very thin driver that relies on the - underlying low level to the hardware driver having "polling hooks" - to which the tty driver is attached. In the initial - implementation of kgdboc the serial_core was changed to expose a - low level UART hook for doing polled mode reading and writing of a - single character while in an atomic context. When kgdb makes an I/O - request to the debugger, kgdboc invokes a callback in the serial - core which in turn uses the callback in the UART driver.</para> - <para> - When using kgdboc with a UART, the UART driver must implement two callbacks in the <constant>struct uart_ops</constant>. Example from drivers/8250.c:<programlisting> -#ifdef CONFIG_CONSOLE_POLL - .poll_get_char = serial8250_get_poll_char, - .poll_put_char = serial8250_put_poll_char, -#endif - </programlisting> - Any implementation specifics around creating a polling driver use the - <constant>#ifdef CONFIG_CONSOLE_POLL</constant>, as shown above. - Keep in mind that polling hooks have to be implemented in such a way - that they can be called from an atomic context and have to restore - the state of the UART chip on return such that the system can return - to normal when the debugger detaches. You need to be very careful - with any kind of lock you consider, because failing here is most likely - going to mean pressing the reset button. - </para> - </sect2> - <sect2 id="kgdbocKbd"> - <title>kgdboc and keyboards</title> - <para>The kgdboc driver contains logic to configure communications - with an attached keyboard. The keyboard infrastructure is only - compiled into the kernel when CONFIG_KDB_KEYBOARD=y is set in the - kernel configuration.</para> - <para>The core polled keyboard driver driver for PS/2 type keyboards - is in drivers/char/kdb_keyboard.c. This driver is hooked into the - debug core when kgdboc populates the callback in the array - called <constant>kdb_poll_funcs[]</constant>. The - kdb_get_kbd_char() is the top-level function which polls hardware - for single character input. - </para> - </sect2> - <sect2 id="kgdbocKms"> - <title>kgdboc and kms</title> - <para>The kgdboc driver contains logic to request the graphics - display to switch to a text context when you are using - "kgdboc=kms,kbd", provided that you have a video driver which has a - frame buffer console and atomic kernel mode setting support.</para> - <para> - Every time the kernel - debugger is entered it calls kgdboc_pre_exp_handler() which in turn - calls con_debug_enter() in the virtual console layer. On resuming kernel - execution, the kernel debugger calls kgdboc_post_exp_handler() which - in turn calls con_debug_leave().</para> - <para>Any video driver that wants to be compatible with the kernel - debugger and the atomic kms callbacks must implement the - mode_set_base_atomic, fb_debug_enter and fb_debug_leave operations. - For the fb_debug_enter and fb_debug_leave the option exists to use - the generic drm fb helper functions or implement something custom for - the hardware. The following example shows the initialization of the - .mode_set_base_atomic operation in - drivers/gpu/drm/i915/intel_display.c: - <informalexample> - <programlisting> -static const struct drm_crtc_helper_funcs intel_helper_funcs = { -[...] - .mode_set_base_atomic = intel_pipe_set_base_atomic, -[...] -}; - </programlisting> - </informalexample> - </para> - <para>Here is an example of how the i915 driver initializes the fb_debug_enter and fb_debug_leave functions to use the generic drm helpers in - drivers/gpu/drm/i915/intel_fb.c: - <informalexample> - <programlisting> -static struct fb_ops intelfb_ops = { -[...] - .fb_debug_enter = drm_fb_helper_debug_enter, - .fb_debug_leave = drm_fb_helper_debug_leave, -[...] -}; - </programlisting> - </informalexample> - </para> - </sect2> - </sect1> - </chapter> - <chapter id="credits"> - <title>Credits</title> - <para> - The following people have contributed to this document: - <orderedlist> - <listitem><para>Amit Kale<email>amitkale@linsyssoft.com</email></para></listitem> - <listitem><para>Tom Rini<email>trini@kernel.crashing.org</email></para></listitem> - </orderedlist> - In March 2008 this document was completely rewritten by: - <itemizedlist> - <listitem><para>Jason Wessel<email>jason.wessel@windriver.com</email></para></listitem> - </itemizedlist> - In Jan 2010 this document was updated to include kdb. - <itemizedlist> - <listitem><para>Jason Wessel<email>jason.wessel@windriver.com</email></para></listitem> - </itemizedlist> - </para> - </chapter> -</book> - diff --git a/Documentation/DocBook/libata.tmpl b/Documentation/DocBook/libata.tmpl deleted file mode 100644 index d7fcdc5a4379..000000000000 --- a/Documentation/DocBook/libata.tmpl +++ /dev/null @@ -1,1625 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="libataDevGuide"> - <bookinfo> - <title>libATA Developer's Guide</title> - - <authorgroup> - <author> - <firstname>Jeff</firstname> - <surname>Garzik</surname> - </author> - </authorgroup> - - <copyright> - <year>2003-2006</year> - <holder>Jeff Garzik</holder> - </copyright> - - <legalnotice> - <para> - The contents of this file are subject to the Open - Software License version 1.1 that can be found at - <ulink url="http://fedoraproject.org/wiki/Licensing:OSL1.1">http://fedoraproject.org/wiki/Licensing:OSL1.1</ulink> - and is included herein by reference. - </para> - - <para> - Alternatively, the contents of this file may be used under the terms - of the GNU General Public License version 2 (the "GPL") as distributed - in the kernel source COPYING file, in which case the provisions of - the GPL are applicable instead of the above. If you wish to allow - the use of your version of this file only under the terms of the - GPL and not to allow others to use your version of this file under - the OSL, indicate your decision by deleting the provisions above and - replace them with the notice and other provisions required by the GPL. - If you do not delete the provisions above, a recipient may use your - version of this file under either the OSL or the GPL. - </para> - - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="libataIntroduction"> - <title>Introduction</title> - <para> - libATA is a library used inside the Linux kernel to support ATA host - controllers and devices. libATA provides an ATA driver API, class - transports for ATA and ATAPI devices, and SCSI<->ATA translation - for ATA devices according to the T10 SAT specification. - </para> - <para> - This Guide documents the libATA driver API, library functions, library - internals, and a couple sample ATA low-level drivers. - </para> - </chapter> - - <chapter id="libataDriverApi"> - <title>libata Driver API</title> - <para> - struct ata_port_operations is defined for every low-level libata - hardware driver, and it controls how the low-level driver - interfaces with the ATA and SCSI layers. - </para> - <para> - FIS-based drivers will hook into the system with ->qc_prep() and - ->qc_issue() high-level hooks. Hardware which behaves in a manner - similar to PCI IDE hardware may utilize several generic helpers, - defining at a bare minimum the bus I/O addresses of the ATA shadow - register blocks. - </para> - <sect1> - <title>struct ata_port_operations</title> - - <sect2><title>Disable ATA port</title> - <programlisting> -void (*port_disable) (struct ata_port *); - </programlisting> - - <para> - Called from ata_bus_probe() error path, as well as when - unregistering from the SCSI module (rmmod, hot unplug). - This function should do whatever needs to be done to take the - port out of use. In most cases, ata_port_disable() can be used - as this hook. - </para> - <para> - Called from ata_bus_probe() on a failed probe. - Called from ata_scsi_release(). - </para> - - </sect2> - - <sect2><title>Post-IDENTIFY device configuration</title> - <programlisting> -void (*dev_config) (struct ata_port *, struct ata_device *); - </programlisting> - - <para> - Called after IDENTIFY [PACKET] DEVICE is issued to each device - found. Typically used to apply device-specific fixups prior to - issue of SET FEATURES - XFER MODE, and prior to operation. - </para> - <para> - This entry may be specified as NULL in ata_port_operations. - </para> - - </sect2> - - <sect2><title>Set PIO/DMA mode</title> - <programlisting> -void (*set_piomode) (struct ata_port *, struct ata_device *); -void (*set_dmamode) (struct ata_port *, struct ata_device *); -void (*post_set_mode) (struct ata_port *); -unsigned int (*mode_filter) (struct ata_port *, struct ata_device *, unsigned int); - </programlisting> - - <para> - Hooks called prior to the issue of SET FEATURES - XFER MODE - command. The optional ->mode_filter() hook is called when libata - has built a mask of the possible modes. This is passed to the - ->mode_filter() function which should return a mask of valid modes - after filtering those unsuitable due to hardware limits. It is not - valid to use this interface to add modes. - </para> - <para> - dev->pio_mode and dev->dma_mode are guaranteed to be valid when - ->set_piomode() and when ->set_dmamode() is called. The timings for - any other drive sharing the cable will also be valid at this point. - That is the library records the decisions for the modes of each - drive on a channel before it attempts to set any of them. - </para> - <para> - ->post_set_mode() is - called unconditionally, after the SET FEATURES - XFER MODE - command completes successfully. - </para> - - <para> - ->set_piomode() is always called (if present), but - ->set_dma_mode() is only called if DMA is possible. - </para> - - </sect2> - - <sect2><title>Taskfile read/write</title> - <programlisting> -void (*sff_tf_load) (struct ata_port *ap, struct ata_taskfile *tf); -void (*sff_tf_read) (struct ata_port *ap, struct ata_taskfile *tf); - </programlisting> - - <para> - ->tf_load() is called to load the given taskfile into hardware - registers / DMA buffers. ->tf_read() is called to read the - hardware registers / DMA buffers, to obtain the current set of - taskfile register values. - Most drivers for taskfile-based hardware (PIO or MMIO) use - ata_sff_tf_load() and ata_sff_tf_read() for these hooks. - </para> - - </sect2> - - <sect2><title>PIO data read/write</title> - <programlisting> -void (*sff_data_xfer) (struct ata_device *, unsigned char *, unsigned int, int); - </programlisting> - - <para> -All bmdma-style drivers must implement this hook. This is the low-level -operation that actually copies the data bytes during a PIO data -transfer. -Typically the driver will choose one of ata_sff_data_xfer_noirq(), -ata_sff_data_xfer(), or ata_sff_data_xfer32(). - </para> - - </sect2> - - <sect2><title>ATA command execute</title> - <programlisting> -void (*sff_exec_command)(struct ata_port *ap, struct ata_taskfile *tf); - </programlisting> - - <para> - causes an ATA command, previously loaded with - ->tf_load(), to be initiated in hardware. - Most drivers for taskfile-based hardware use ata_sff_exec_command() - for this hook. - </para> - - </sect2> - - <sect2><title>Per-cmd ATAPI DMA capabilities filter</title> - <programlisting> -int (*check_atapi_dma) (struct ata_queued_cmd *qc); - </programlisting> - - <para> -Allow low-level driver to filter ATA PACKET commands, returning a status -indicating whether or not it is OK to use DMA for the supplied PACKET -command. - </para> - <para> - This hook may be specified as NULL, in which case libata will - assume that atapi dma can be supported. - </para> - - </sect2> - - <sect2><title>Read specific ATA shadow registers</title> - <programlisting> -u8 (*sff_check_status)(struct ata_port *ap); -u8 (*sff_check_altstatus)(struct ata_port *ap); - </programlisting> - - <para> - Reads the Status/AltStatus ATA shadow register from - hardware. On some hardware, reading the Status register has - the side effect of clearing the interrupt condition. - Most drivers for taskfile-based hardware use - ata_sff_check_status() for this hook. - </para> - - </sect2> - - <sect2><title>Write specific ATA shadow register</title> - <programlisting> -void (*sff_set_devctl)(struct ata_port *ap, u8 ctl); - </programlisting> - - <para> - Write the device control ATA shadow register to the hardware. - Most drivers don't need to define this. - </para> - - </sect2> - - <sect2><title>Select ATA device on bus</title> - <programlisting> -void (*sff_dev_select)(struct ata_port *ap, unsigned int device); - </programlisting> - - <para> - Issues the low-level hardware command(s) that causes one of N - hardware devices to be considered 'selected' (active and - available for use) on the ATA bus. This generally has no - meaning on FIS-based devices. - </para> - <para> - Most drivers for taskfile-based hardware use - ata_sff_dev_select() for this hook. - </para> - - </sect2> - - <sect2><title>Private tuning method</title> - <programlisting> -void (*set_mode) (struct ata_port *ap); - </programlisting> - - <para> - By default libata performs drive and controller tuning in - accordance with the ATA timing rules and also applies blacklists - and cable limits. Some controllers need special handling and have - custom tuning rules, typically raid controllers that use ATA - commands but do not actually do drive timing. - </para> - - <warning> - <para> - This hook should not be used to replace the standard controller - tuning logic when a controller has quirks. Replacing the default - tuning logic in that case would bypass handling for drive and - bridge quirks that may be important to data reliability. If a - controller needs to filter the mode selection it should use the - mode_filter hook instead. - </para> - </warning> - - </sect2> - - <sect2><title>Control PCI IDE BMDMA engine</title> - <programlisting> -void (*bmdma_setup) (struct ata_queued_cmd *qc); -void (*bmdma_start) (struct ata_queued_cmd *qc); -void (*bmdma_stop) (struct ata_port *ap); -u8 (*bmdma_status) (struct ata_port *ap); - </programlisting> - - <para> -When setting up an IDE BMDMA transaction, these hooks arm -(->bmdma_setup), fire (->bmdma_start), and halt (->bmdma_stop) -the hardware's DMA engine. ->bmdma_status is used to read the standard -PCI IDE DMA Status register. - </para> - - <para> -These hooks are typically either no-ops, or simply not implemented, in -FIS-based drivers. - </para> - <para> -Most legacy IDE drivers use ata_bmdma_setup() for the bmdma_setup() -hook. ata_bmdma_setup() will write the pointer to the PRD table to -the IDE PRD Table Address register, enable DMA in the DMA Command -register, and call exec_command() to begin the transfer. - </para> - <para> -Most legacy IDE drivers use ata_bmdma_start() for the bmdma_start() -hook. ata_bmdma_start() will write the ATA_DMA_START flag to the DMA -Command register. - </para> - <para> -Many legacy IDE drivers use ata_bmdma_stop() for the bmdma_stop() -hook. ata_bmdma_stop() clears the ATA_DMA_START flag in the DMA -command register. - </para> - <para> -Many legacy IDE drivers use ata_bmdma_status() as the bmdma_status() hook. - </para> - - </sect2> - - <sect2><title>High-level taskfile hooks</title> - <programlisting> -void (*qc_prep) (struct ata_queued_cmd *qc); -int (*qc_issue) (struct ata_queued_cmd *qc); - </programlisting> - - <para> - Higher-level hooks, these two hooks can potentially supercede - several of the above taskfile/DMA engine hooks. ->qc_prep is - called after the buffers have been DMA-mapped, and is typically - used to populate the hardware's DMA scatter-gather table. - Most drivers use the standard ata_qc_prep() helper function, but - more advanced drivers roll their own. - </para> - <para> - ->qc_issue is used to make a command active, once the hardware - and S/G tables have been prepared. IDE BMDMA drivers use the - helper function ata_qc_issue_prot() for taskfile protocol-based - dispatch. More advanced drivers implement their own ->qc_issue. - </para> - <para> - ata_qc_issue_prot() calls ->tf_load(), ->bmdma_setup(), and - ->bmdma_start() as necessary to initiate a transfer. - </para> - - </sect2> - - <sect2><title>Exception and probe handling (EH)</title> - <programlisting> -void (*eng_timeout) (struct ata_port *ap); -void (*phy_reset) (struct ata_port *ap); - </programlisting> - - <para> -Deprecated. Use ->error_handler() instead. - </para> - - <programlisting> -void (*freeze) (struct ata_port *ap); -void (*thaw) (struct ata_port *ap); - </programlisting> - - <para> -ata_port_freeze() is called when HSM violations or some other -condition disrupts normal operation of the port. A frozen port -is not allowed to perform any operation until the port is -thawed, which usually follows a successful reset. - </para> - - <para> -The optional ->freeze() callback can be used for freezing the port -hardware-wise (e.g. mask interrupt and stop DMA engine). If a -port cannot be frozen hardware-wise, the interrupt handler -must ack and clear interrupts unconditionally while the port -is frozen. - </para> - <para> -The optional ->thaw() callback is called to perform the opposite of ->freeze(): -prepare the port for normal operation once again. Unmask interrupts, -start DMA engine, etc. - </para> - - <programlisting> -void (*error_handler) (struct ata_port *ap); - </programlisting> - - <para> -->error_handler() is a driver's hook into probe, hotplug, and recovery -and other exceptional conditions. The primary responsibility of an -implementation is to call ata_do_eh() or ata_bmdma_drive_eh() with a set -of EH hooks as arguments: - </para> - - <para> -'prereset' hook (may be NULL) is called during an EH reset, before any other actions -are taken. - </para> - - <para> -'postreset' hook (may be NULL) is called after the EH reset is performed. Based on -existing conditions, severity of the problem, and hardware capabilities, - </para> - - <para> -Either 'softreset' (may be NULL) or 'hardreset' (may be NULL) will be -called to perform the low-level EH reset. - </para> - - <programlisting> -void (*post_internal_cmd) (struct ata_queued_cmd *qc); - </programlisting> - - <para> -Perform any hardware-specific actions necessary to finish processing -after executing a probe-time or EH-time command via ata_exec_internal(). - </para> - - </sect2> - - <sect2><title>Hardware interrupt handling</title> - <programlisting> -irqreturn_t (*irq_handler)(int, void *, struct pt_regs *); -void (*irq_clear) (struct ata_port *); - </programlisting> - - <para> - ->irq_handler is the interrupt handling routine registered with - the system, by libata. ->irq_clear is called during probe just - before the interrupt handler is registered, to be sure hardware - is quiet. - </para> - <para> - The second argument, dev_instance, should be cast to a pointer - to struct ata_host_set. - </para> - <para> - Most legacy IDE drivers use ata_sff_interrupt() for the - irq_handler hook, which scans all ports in the host_set, - determines which queued command was active (if any), and calls - ata_sff_host_intr(ap,qc). - </para> - <para> - Most legacy IDE drivers use ata_sff_irq_clear() for the - irq_clear() hook, which simply clears the interrupt and error - flags in the DMA status register. - </para> - - </sect2> - - <sect2><title>SATA phy read/write</title> - <programlisting> -int (*scr_read) (struct ata_port *ap, unsigned int sc_reg, - u32 *val); -int (*scr_write) (struct ata_port *ap, unsigned int sc_reg, - u32 val); - </programlisting> - - <para> - Read and write standard SATA phy registers. Currently only used - if ->phy_reset hook called the sata_phy_reset() helper function. - sc_reg is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE. - </para> - - </sect2> - - <sect2><title>Init and shutdown</title> - <programlisting> -int (*port_start) (struct ata_port *ap); -void (*port_stop) (struct ata_port *ap); -void (*host_stop) (struct ata_host_set *host_set); - </programlisting> - - <para> - ->port_start() is called just after the data structures for each - port are initialized. Typically this is used to alloc per-port - DMA buffers / tables / rings, enable DMA engines, and similar - tasks. Some drivers also use this entry point as a chance to - allocate driver-private memory for ap->private_data. - </para> - <para> - Many drivers use ata_port_start() as this hook or call - it from their own port_start() hooks. ata_port_start() - allocates space for a legacy IDE PRD table and returns. - </para> - <para> - ->port_stop() is called after ->host_stop(). Its sole function - is to release DMA/memory resources, now that they are no longer - actively being used. Many drivers also free driver-private - data from port at this time. - </para> - <para> - ->host_stop() is called after all ->port_stop() calls -have completed. The hook must finalize hardware shutdown, release DMA -and other resources, etc. - This hook may be specified as NULL, in which case it is not called. - </para> - - </sect2> - - </sect1> - </chapter> - - <chapter id="libataEH"> - <title>Error handling</title> - - <para> - This chapter describes how errors are handled under libata. - Readers are advised to read SCSI EH - (Documentation/scsi/scsi_eh.txt) and ATA exceptions doc first. - </para> - - <sect1><title>Origins of commands</title> - <para> - In libata, a command is represented with struct ata_queued_cmd - or qc. qc's are preallocated during port initialization and - repetitively used for command executions. Currently only one - qc is allocated per port but yet-to-be-merged NCQ branch - allocates one for each tag and maps each qc to NCQ tag 1-to-1. - </para> - <para> - libata commands can originate from two sources - libata itself - and SCSI midlayer. libata internal commands are used for - initialization and error handling. All normal blk requests - and commands for SCSI emulation are passed as SCSI commands - through queuecommand callback of SCSI host template. - </para> - </sect1> - - <sect1><title>How commands are issued</title> - - <variablelist> - - <varlistentry><term>Internal commands</term> - <listitem> - <para> - First, qc is allocated and initialized using - ata_qc_new_init(). Although ata_qc_new_init() doesn't - implement any wait or retry mechanism when qc is not - available, internal commands are currently issued only during - initialization and error recovery, so no other command is - active and allocation is guaranteed to succeed. - </para> - <para> - Once allocated qc's taskfile is initialized for the command to - be executed. qc currently has two mechanisms to notify - completion. One is via qc->complete_fn() callback and the - other is completion qc->waiting. qc->complete_fn() callback - is the asynchronous path used by normal SCSI translated - commands and qc->waiting is the synchronous (issuer sleeps in - process context) path used by internal commands. - </para> - <para> - Once initialization is complete, host_set lock is acquired - and the qc is issued. - </para> - </listitem> - </varlistentry> - - <varlistentry><term>SCSI commands</term> - <listitem> - <para> - All libata drivers use ata_scsi_queuecmd() as - hostt->queuecommand callback. scmds can either be simulated - or translated. No qc is involved in processing a simulated - scmd. The result is computed right away and the scmd is - completed. - </para> - <para> - For a translated scmd, ata_qc_new_init() is invoked to - allocate a qc and the scmd is translated into the qc. SCSI - midlayer's completion notification function pointer is stored - into qc->scsidone. - </para> - <para> - qc->complete_fn() callback is used for completion - notification. ATA commands use ata_scsi_qc_complete() while - ATAPI commands use atapi_qc_complete(). Both functions end up - calling qc->scsidone to notify upper layer when the qc is - finished. After translation is completed, the qc is issued - with ata_qc_issue(). - </para> - <para> - Note that SCSI midlayer invokes hostt->queuecommand while - holding host_set lock, so all above occur while holding - host_set lock. - </para> - </listitem> - </varlistentry> - - </variablelist> - </sect1> - - <sect1><title>How commands are processed</title> - <para> - Depending on which protocol and which controller are used, - commands are processed differently. For the purpose of - discussion, a controller which uses taskfile interface and all - standard callbacks is assumed. - </para> - <para> - Currently 6 ATA command protocols are used. They can be - sorted into the following four categories according to how - they are processed. - </para> - - <variablelist> - <varlistentry><term>ATA NO DATA or DMA</term> - <listitem> - <para> - ATA_PROT_NODATA and ATA_PROT_DMA fall into this category. - These types of commands don't require any software - intervention once issued. Device will raise interrupt on - completion. - </para> - </listitem> - </varlistentry> - - <varlistentry><term>ATA PIO</term> - <listitem> - <para> - ATA_PROT_PIO is in this category. libata currently - implements PIO with polling. ATA_NIEN bit is set to turn - off interrupt and pio_task on ata_wq performs polling and - IO. - </para> - </listitem> - </varlistentry> - - <varlistentry><term>ATAPI NODATA or DMA</term> - <listitem> - <para> - ATA_PROT_ATAPI_NODATA and ATA_PROT_ATAPI_DMA are in this - category. packet_task is used to poll BSY bit after - issuing PACKET command. Once BSY is turned off by the - device, packet_task transfers CDB and hands off processing - to interrupt handler. - </para> - </listitem> - </varlistentry> - - <varlistentry><term>ATAPI PIO</term> - <listitem> - <para> - ATA_PROT_ATAPI is in this category. ATA_NIEN bit is set - and, as in ATAPI NODATA or DMA, packet_task submits cdb. - However, after submitting cdb, further processing (data - transfer) is handed off to pio_task. - </para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - <sect1><title>How commands are completed</title> - <para> - Once issued, all qc's are either completed with - ata_qc_complete() or time out. For commands which are handled - by interrupts, ata_host_intr() invokes ata_qc_complete(), and, - for PIO tasks, pio_task invokes ata_qc_complete(). In error - cases, packet_task may also complete commands. - </para> - <para> - ata_qc_complete() does the following. - </para> - - <orderedlist> - - <listitem> - <para> - DMA memory is unmapped. - </para> - </listitem> - - <listitem> - <para> - ATA_QCFLAG_ACTIVE is cleared from qc->flags. - </para> - </listitem> - - <listitem> - <para> - qc->complete_fn() callback is invoked. If the return value of - the callback is not zero. Completion is short circuited and - ata_qc_complete() returns. - </para> - </listitem> - - <listitem> - <para> - __ata_qc_complete() is called, which does - <orderedlist> - - <listitem> - <para> - qc->flags is cleared to zero. - </para> - </listitem> - - <listitem> - <para> - ap->active_tag and qc->tag are poisoned. - </para> - </listitem> - - <listitem> - <para> - qc->waiting is cleared & completed (in that order). - </para> - </listitem> - - <listitem> - <para> - qc is deallocated by clearing appropriate bit in ap->qactive. - </para> - </listitem> - - </orderedlist> - </para> - </listitem> - - </orderedlist> - - <para> - So, it basically notifies upper layer and deallocates qc. One - exception is short-circuit path in #3 which is used by - atapi_qc_complete(). - </para> - <para> - For all non-ATAPI commands, whether it fails or not, almost - the same code path is taken and very little error handling - takes place. A qc is completed with success status if it - succeeded, with failed status otherwise. - </para> - <para> - However, failed ATAPI commands require more handling as - REQUEST SENSE is needed to acquire sense data. If an ATAPI - command fails, ata_qc_complete() is invoked with error status, - which in turn invokes atapi_qc_complete() via - qc->complete_fn() callback. - </para> - <para> - This makes atapi_qc_complete() set scmd->result to - SAM_STAT_CHECK_CONDITION, complete the scmd and return 1. As - the sense data is empty but scmd->result is CHECK CONDITION, - SCSI midlayer will invoke EH for the scmd, and returning 1 - makes ata_qc_complete() to return without deallocating the qc. - This leads us to ata_scsi_error() with partially completed qc. - </para> - - </sect1> - - <sect1><title>ata_scsi_error()</title> - <para> - ata_scsi_error() is the current transportt->eh_strategy_handler() - for libata. As discussed above, this will be entered in two - cases - timeout and ATAPI error completion. This function - calls low level libata driver's eng_timeout() callback, the - standard callback for which is ata_eng_timeout(). It checks - if a qc is active and calls ata_qc_timeout() on the qc if so. - Actual error handling occurs in ata_qc_timeout(). - </para> - <para> - If EH is invoked for timeout, ata_qc_timeout() stops BMDMA and - completes the qc. Note that as we're currently in EH, we - cannot call scsi_done. As described in SCSI EH doc, a - recovered scmd should be either retried with - scsi_queue_insert() or finished with scsi_finish_command(). - Here, we override qc->scsidone with scsi_finish_command() and - calls ata_qc_complete(). - </para> - <para> - If EH is invoked due to a failed ATAPI qc, the qc here is - completed but not deallocated. The purpose of this - half-completion is to use the qc as place holder to make EH - code reach this place. This is a bit hackish, but it works. - </para> - <para> - Once control reaches here, the qc is deallocated by invoking - __ata_qc_complete() explicitly. Then, internal qc for REQUEST - SENSE is issued. Once sense data is acquired, scmd is - finished by directly invoking scsi_finish_command() on the - scmd. Note that as we already have completed and deallocated - the qc which was associated with the scmd, we don't need - to/cannot call ata_qc_complete() again. - </para> - - </sect1> - - <sect1><title>Problems with the current EH</title> - - <itemizedlist> - - <listitem> - <para> - Error representation is too crude. Currently any and all - error conditions are represented with ATA STATUS and ERROR - registers. Errors which aren't ATA device errors are treated - as ATA device errors by setting ATA_ERR bit. Better error - descriptor which can properly represent ATA and other - errors/exceptions is needed. - </para> - </listitem> - - <listitem> - <para> - When handling timeouts, no action is taken to make device - forget about the timed out command and ready for new commands. - </para> - </listitem> - - <listitem> - <para> - EH handling via ata_scsi_error() is not properly protected - from usual command processing. On EH entrance, the device is - not in quiescent state. Timed out commands may succeed or - fail any time. pio_task and atapi_task may still be running. - </para> - </listitem> - - <listitem> - <para> - Too weak error recovery. Devices / controllers causing HSM - mismatch errors and other errors quite often require reset to - return to known state. Also, advanced error handling is - necessary to support features like NCQ and hotplug. - </para> - </listitem> - - <listitem> - <para> - ATA errors are directly handled in the interrupt handler and - PIO errors in pio_task. This is problematic for advanced - error handling for the following reasons. - </para> - <para> - First, advanced error handling often requires context and - internal qc execution. - </para> - <para> - Second, even a simple failure (say, CRC error) needs - information gathering and could trigger complex error handling - (say, resetting & reconfiguring). Having multiple code - paths to gather information, enter EH and trigger actions - makes life painful. - </para> - <para> - Third, scattered EH code makes implementing low level drivers - difficult. Low level drivers override libata callbacks. If - EH is scattered over several places, each affected callbacks - should perform its part of error handling. This can be error - prone and painful. - </para> - </listitem> - - </itemizedlist> - </sect1> - </chapter> - - <chapter id="libataExt"> - <title>libata Library</title> -!Edrivers/ata/libata-core.c - </chapter> - - <chapter id="libataInt"> - <title>libata Core Internals</title> -!Idrivers/ata/libata-core.c - </chapter> - - <chapter id="libataScsiInt"> - <title>libata SCSI translation/emulation</title> -!Edrivers/ata/libata-scsi.c -!Idrivers/ata/libata-scsi.c - </chapter> - - <chapter id="ataExceptions"> - <title>ATA errors and exceptions</title> - - <para> - This chapter tries to identify what error/exception conditions exist - for ATA/ATAPI devices and describe how they should be handled in - implementation-neutral way. - </para> - - <para> - The term 'error' is used to describe conditions where either an - explicit error condition is reported from device or a command has - timed out. - </para> - - <para> - The term 'exception' is either used to describe exceptional - conditions which are not errors (say, power or hotplug events), or - to describe both errors and non-error exceptional conditions. Where - explicit distinction between error and exception is necessary, the - term 'non-error exception' is used. - </para> - - <sect1 id="excat"> - <title>Exception categories</title> - <para> - Exceptions are described primarily with respect to legacy - taskfile + bus master IDE interface. If a controller provides - other better mechanism for error reporting, mapping those into - categories described below shouldn't be difficult. - </para> - - <para> - In the following sections, two recovery actions - reset and - reconfiguring transport - are mentioned. These are described - further in <xref linkend="exrec"/>. - </para> - - <sect2 id="excatHSMviolation"> - <title>HSM violation</title> - <para> - This error is indicated when STATUS value doesn't match HSM - requirement during issuing or execution any ATA/ATAPI command. - </para> - - <itemizedlist> - <title>Examples</title> - - <listitem> - <para> - ATA_STATUS doesn't contain !BSY && DRDY && !DRQ while trying - to issue a command. - </para> - </listitem> - - <listitem> - <para> - !BSY && !DRQ during PIO data transfer. - </para> - </listitem> - - <listitem> - <para> - DRQ on command completion. - </para> - </listitem> - - <listitem> - <para> - !BSY && ERR after CDB transfer starts but before the - last byte of CDB is transferred. ATA/ATAPI standard states - that "The device shall not terminate the PACKET command - with an error before the last byte of the command packet has - been written" in the error outputs description of PACKET - command and the state diagram doesn't include such - transitions. - </para> - </listitem> - - </itemizedlist> - - <para> - In these cases, HSM is violated and not much information - regarding the error can be acquired from STATUS or ERROR - register. IOW, this error can be anything - driver bug, - faulty device, controller and/or cable. - </para> - - <para> - As HSM is violated, reset is necessary to restore known state. - Reconfiguring transport for lower speed might be helpful too - as transmission errors sometimes cause this kind of errors. - </para> - </sect2> - - <sect2 id="excatDevErr"> - <title>ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION)</title> - - <para> - These are errors detected and reported by ATA/ATAPI devices - indicating device problems. For this type of errors, STATUS - and ERROR register values are valid and describe error - condition. Note that some of ATA bus errors are detected by - ATA/ATAPI devices and reported using the same mechanism as - device errors. Those cases are described later in this - section. - </para> - - <para> - For ATA commands, this type of errors are indicated by !BSY - && ERR during command execution and on completion. - </para> - - <para>For ATAPI commands,</para> - - <itemizedlist> - - <listitem> - <para> - !BSY && ERR && ABRT right after issuing PACKET - indicates that PACKET command is not supported and falls in - this category. - </para> - </listitem> - - <listitem> - <para> - !BSY && ERR(==CHK) && !ABRT after the last - byte of CDB is transferred indicates CHECK CONDITION and - doesn't fall in this category. - </para> - </listitem> - - <listitem> - <para> - !BSY && ERR(==CHK) && ABRT after the last byte - of CDB is transferred *probably* indicates CHECK CONDITION and - doesn't fall in this category. - </para> - </listitem> - - </itemizedlist> - - <para> - Of errors detected as above, the followings are not ATA/ATAPI - device errors but ATA bus errors and should be handled - according to <xref linkend="excatATAbusErr"/>. - </para> - - <variablelist> - - <varlistentry> - <term>CRC error during data transfer</term> - <listitem> - <para> - This is indicated by ICRC bit in the ERROR register and - means that corruption occurred during data transfer. Up to - ATA/ATAPI-7, the standard specifies that this bit is only - applicable to UDMA transfers but ATA/ATAPI-8 draft revision - 1f says that the bit may be applicable to multiword DMA and - PIO. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>ABRT error during data transfer or on completion</term> - <listitem> - <para> - Up to ATA/ATAPI-7, the standard specifies that ABRT could be - set on ICRC errors and on cases where a device is not able - to complete a command. Combined with the fact that MWDMA - and PIO transfer errors aren't allowed to use ICRC bit up to - ATA/ATAPI-7, it seems to imply that ABRT bit alone could - indicate transfer errors. - </para> - <para> - However, ATA/ATAPI-8 draft revision 1f removes the part - that ICRC errors can turn on ABRT. So, this is kind of - gray area. Some heuristics are needed here. - </para> - </listitem> - </varlistentry> - - </variablelist> - - <para> - ATA/ATAPI device errors can be further categorized as follows. - </para> - - <variablelist> - - <varlistentry> - <term>Media errors</term> - <listitem> - <para> - This is indicated by UNC bit in the ERROR register. ATA - devices reports UNC error only after certain number of - retries cannot recover the data, so there's nothing much - else to do other than notifying upper layer. - </para> - <para> - READ and WRITE commands report CHS or LBA of the first - failed sector but ATA/ATAPI standard specifies that the - amount of transferred data on error completion is - indeterminate, so we cannot assume that sectors preceding - the failed sector have been transferred and thus cannot - complete those sectors successfully as SCSI does. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Media changed / media change requested error</term> - <listitem> - <para> - <<TODO: fill here>> - </para> - </listitem> - </varlistentry> - - <varlistentry><term>Address error</term> - <listitem> - <para> - This is indicated by IDNF bit in the ERROR register. - Report to upper layer. - </para> - </listitem> - </varlistentry> - - <varlistentry><term>Other errors</term> - <listitem> - <para> - This can be invalid command or parameter indicated by ABRT - ERROR bit or some other error condition. Note that ABRT - bit can indicate a lot of things including ICRC and Address - errors. Heuristics needed. - </para> - </listitem> - </varlistentry> - - </variablelist> - - <para> - Depending on commands, not all STATUS/ERROR bits are - applicable. These non-applicable bits are marked with - "na" in the output descriptions but up to ATA/ATAPI-7 - no definition of "na" can be found. However, - ATA/ATAPI-8 draft revision 1f describes "N/A" as - follows. - </para> - - <blockquote> - <variablelist> - <varlistentry><term>3.2.3.3a N/A</term> - <listitem> - <para> - A keyword the indicates a field has no defined value in - this standard and should not be checked by the host or - device. N/A fields should be cleared to zero. - </para> - </listitem> - </varlistentry> - </variablelist> - </blockquote> - - <para> - So, it seems reasonable to assume that "na" bits are - cleared to zero by devices and thus need no explicit masking. - </para> - - </sect2> - - <sect2 id="excatATAPIcc"> - <title>ATAPI device CHECK CONDITION</title> - - <para> - ATAPI device CHECK CONDITION error is indicated by set CHK bit - (ERR bit) in the STATUS register after the last byte of CDB is - transferred for a PACKET command. For this kind of errors, - sense data should be acquired to gather information regarding - the errors. REQUEST SENSE packet command should be used to - acquire sense data. - </para> - - <para> - Once sense data is acquired, this type of errors can be - handled similarly to other SCSI errors. Note that sense data - may indicate ATA bus error (e.g. Sense Key 04h HARDWARE ERROR - && ASC/ASCQ 47h/00h SCSI PARITY ERROR). In such - cases, the error should be considered as an ATA bus error and - handled according to <xref linkend="excatATAbusErr"/>. - </para> - - </sect2> - - <sect2 id="excatNCQerr"> - <title>ATA device error (NCQ)</title> - - <para> - NCQ command error is indicated by cleared BSY and set ERR bit - during NCQ command phase (one or more NCQ commands - outstanding). Although STATUS and ERROR registers will - contain valid values describing the error, READ LOG EXT is - required to clear the error condition, determine which command - has failed and acquire more information. - </para> - - <para> - READ LOG EXT Log Page 10h reports which tag has failed and - taskfile register values describing the error. With this - information the failed command can be handled as a normal ATA - command error as in <xref linkend="excatDevErr"/> and all - other in-flight commands must be retried. Note that this - retry should not be counted - it's likely that commands - retried this way would have completed normally if it were not - for the failed command. - </para> - - <para> - Note that ATA bus errors can be reported as ATA device NCQ - errors. This should be handled as described in <xref - linkend="excatATAbusErr"/>. - </para> - - <para> - If READ LOG EXT Log Page 10h fails or reports NQ, we're - thoroughly screwed. This condition should be treated - according to <xref linkend="excatHSMviolation"/>. - </para> - - </sect2> - - <sect2 id="excatATAbusErr"> - <title>ATA bus error</title> - - <para> - ATA bus error means that data corruption occurred during - transmission over ATA bus (SATA or PATA). This type of errors - can be indicated by - </para> - - <itemizedlist> - - <listitem> - <para> - ICRC or ABRT error as described in <xref linkend="excatDevErr"/>. - </para> - </listitem> - - <listitem> - <para> - Controller-specific error completion with error information - indicating transmission error. - </para> - </listitem> - - <listitem> - <para> - On some controllers, command timeout. In this case, there may - be a mechanism to determine that the timeout is due to - transmission error. - </para> - </listitem> - - <listitem> - <para> - Unknown/random errors, timeouts and all sorts of weirdities. - </para> - </listitem> - - </itemizedlist> - - <para> - As described above, transmission errors can cause wide variety - of symptoms ranging from device ICRC error to random device - lockup, and, for many cases, there is no way to tell if an - error condition is due to transmission error or not; - therefore, it's necessary to employ some kind of heuristic - when dealing with errors and timeouts. For example, - encountering repetitive ABRT errors for known supported - command is likely to indicate ATA bus error. - </para> - - <para> - Once it's determined that ATA bus errors have possibly - occurred, lowering ATA bus transmission speed is one of - actions which may alleviate the problem. See <xref - linkend="exrecReconf"/> for more information. - </para> - - </sect2> - - <sect2 id="excatPCIbusErr"> - <title>PCI bus error</title> - - <para> - Data corruption or other failures during transmission over PCI - (or other system bus). For standard BMDMA, this is indicated - by Error bit in the BMDMA Status register. This type of - errors must be logged as it indicates something is very wrong - with the system. Resetting host controller is recommended. - </para> - - </sect2> - - <sect2 id="excatLateCompletion"> - <title>Late completion</title> - - <para> - This occurs when timeout occurs and the timeout handler finds - out that the timed out command has completed successfully or - with error. This is usually caused by lost interrupts. This - type of errors must be logged. Resetting host controller is - recommended. - </para> - - </sect2> - - <sect2 id="excatUnknown"> - <title>Unknown error (timeout)</title> - - <para> - This is when timeout occurs and the command is still - processing or the host and device are in unknown state. When - this occurs, HSM could be in any valid or invalid state. To - bring the device to known state and make it forget about the - timed out command, resetting is necessary. The timed out - command may be retried. - </para> - - <para> - Timeouts can also be caused by transmission errors. Refer to - <xref linkend="excatATAbusErr"/> for more details. - </para> - - </sect2> - - <sect2 id="excatHoplugPM"> - <title>Hotplug and power management exceptions</title> - - <para> - <<TODO: fill here>> - </para> - - </sect2> - - </sect1> - - <sect1 id="exrec"> - <title>EH recovery actions</title> - - <para> - This section discusses several important recovery actions. - </para> - - <sect2 id="exrecClr"> - <title>Clearing error condition</title> - - <para> - Many controllers require its error registers to be cleared by - error handler. Different controllers may have different - requirements. - </para> - - <para> - For SATA, it's strongly recommended to clear at least SError - register during error handling. - </para> - </sect2> - - <sect2 id="exrecRst"> - <title>Reset</title> - - <para> - During EH, resetting is necessary in the following cases. - </para> - - <itemizedlist> - - <listitem> - <para> - HSM is in unknown or invalid state - </para> - </listitem> - - <listitem> - <para> - HBA is in unknown or invalid state - </para> - </listitem> - - <listitem> - <para> - EH needs to make HBA/device forget about in-flight commands - </para> - </listitem> - - <listitem> - <para> - HBA/device behaves weirdly - </para> - </listitem> - - </itemizedlist> - - <para> - Resetting during EH might be a good idea regardless of error - condition to improve EH robustness. Whether to reset both or - either one of HBA and device depends on situation but the - following scheme is recommended. - </para> - - <itemizedlist> - - <listitem> - <para> - When it's known that HBA is in ready state but ATA/ATAPI - device is in unknown state, reset only device. - </para> - </listitem> - - <listitem> - <para> - If HBA is in unknown state, reset both HBA and device. - </para> - </listitem> - - </itemizedlist> - - <para> - HBA resetting is implementation specific. For a controller - complying to taskfile/BMDMA PCI IDE, stopping active DMA - transaction may be sufficient iff BMDMA state is the only HBA - context. But even mostly taskfile/BMDMA PCI IDE complying - controllers may have implementation specific requirements and - mechanism to reset themselves. This must be addressed by - specific drivers. - </para> - - <para> - OTOH, ATA/ATAPI standard describes in detail ways to reset - ATA/ATAPI devices. - </para> - - <variablelist> - - <varlistentry><term>PATA hardware reset</term> - <listitem> - <para> - This is hardware initiated device reset signalled with - asserted PATA RESET- signal. There is no standard way to - initiate hardware reset from software although some - hardware provides registers that allow driver to directly - tweak the RESET- signal. - </para> - </listitem> - </varlistentry> - - <varlistentry><term>Software reset</term> - <listitem> - <para> - This is achieved by turning CONTROL SRST bit on for at - least 5us. Both PATA and SATA support it but, in case of - SATA, this may require controller-specific support as the - second Register FIS to clear SRST should be transmitted - while BSY bit is still set. Note that on PATA, this resets - both master and slave devices on a channel. - </para> - </listitem> - </varlistentry> - - <varlistentry><term>EXECUTE DEVICE DIAGNOSTIC command</term> - <listitem> - <para> - Although ATA/ATAPI standard doesn't describe exactly, EDD - implies some level of resetting, possibly similar level - with software reset. Host-side EDD protocol can be handled - with normal command processing and most SATA controllers - should be able to handle EDD's just like other commands. - As in software reset, EDD affects both devices on a PATA - bus. - </para> - <para> - Although EDD does reset devices, this doesn't suit error - handling as EDD cannot be issued while BSY is set and it's - unclear how it will act when device is in unknown/weird - state. - </para> - </listitem> - </varlistentry> - - <varlistentry><term>ATAPI DEVICE RESET command</term> - <listitem> - <para> - This is very similar to software reset except that reset - can be restricted to the selected device without affecting - the other device sharing the cable. - </para> - </listitem> - </varlistentry> - - <varlistentry><term>SATA phy reset</term> - <listitem> - <para> - This is the preferred way of resetting a SATA device. In - effect, it's identical to PATA hardware reset. Note that - this can be done with the standard SCR Control register. - As such, it's usually easier to implement than software - reset. - </para> - </listitem> - </varlistentry> - - </variablelist> - - <para> - One more thing to consider when resetting devices is that - resetting clears certain configuration parameters and they - need to be set to their previous or newly adjusted values - after reset. - </para> - - <para> - Parameters affected are. - </para> - - <itemizedlist> - - <listitem> - <para> - CHS set up with INITIALIZE DEVICE PARAMETERS (seldom used) - </para> - </listitem> - - <listitem> - <para> - Parameters set with SET FEATURES including transfer mode setting - </para> - </listitem> - - <listitem> - <para> - Block count set with SET MULTIPLE MODE - </para> - </listitem> - - <listitem> - <para> - Other parameters (SET MAX, MEDIA LOCK...) - </para> - </listitem> - - </itemizedlist> - - <para> - ATA/ATAPI standard specifies that some parameters must be - maintained across hardware or software reset, but doesn't - strictly specify all of them. Always reconfiguring needed - parameters after reset is required for robustness. Note that - this also applies when resuming from deep sleep (power-off). - </para> - - <para> - Also, ATA/ATAPI standard requires that IDENTIFY DEVICE / - IDENTIFY PACKET DEVICE is issued after any configuration - parameter is updated or a hardware reset and the result used - for further operation. OS driver is required to implement - revalidation mechanism to support this. - </para> - - </sect2> - - <sect2 id="exrecReconf"> - <title>Reconfigure transport</title> - - <para> - For both PATA and SATA, a lot of corners are cut for cheap - connectors, cables or controllers and it's quite common to see - high transmission error rate. This can be mitigated by - lowering transmission speed. - </para> - - <para> - The following is a possible scheme Jeff Garzik suggested. - </para> - - <blockquote> - <para> - If more than $N (3?) transmission errors happen in 15 minutes, - </para> - <itemizedlist> - <listitem> - <para> - if SATA, decrease SATA PHY speed. if speed cannot be decreased, - </para> - </listitem> - <listitem> - <para> - decrease UDMA xfer speed. if at UDMA0, switch to PIO4, - </para> - </listitem> - <listitem> - <para> - decrease PIO xfer speed. if at PIO3, complain, but continue - </para> - </listitem> - </itemizedlist> - </blockquote> - - </sect2> - - </sect1> - - </chapter> - - <chapter id="PiixInt"> - <title>ata_piix Internals</title> -!Idrivers/ata/ata_piix.c - </chapter> - - <chapter id="SILInt"> - <title>sata_sil Internals</title> -!Idrivers/ata/sata_sil.c - </chapter> - - <chapter id="libataThanks"> - <title>Thanks</title> - <para> - The bulk of the ATA knowledge comes thanks to long conversations with - Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA - and SCSI specifications. - </para> - <para> - Thanks to Alan Cox for pointing out similarities - between SATA and SCSI, and in general for motivation to hack on - libata. - </para> - <para> - libata's device detection - method, ata_pio_devchk, and in general all the early probing was - based on extensive study of Hale Landis's probe/reset code in his - ATADRVR driver (www.ata-atapi.com). - </para> - </chapter> - -</book> diff --git a/Documentation/DocBook/librs.tmpl b/Documentation/DocBook/librs.tmpl deleted file mode 100644 index 94f21361e0ed..000000000000 --- a/Documentation/DocBook/librs.tmpl +++ /dev/null @@ -1,289 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="Reed-Solomon-Library-Guide"> - <bookinfo> - <title>Reed-Solomon Library Programming Interface</title> - - <authorgroup> - <author> - <firstname>Thomas</firstname> - <surname>Gleixner</surname> - <affiliation> - <address> - <email>tglx@linutronix.de</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2004</year> - <holder>Thomas Gleixner</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License version 2 as published by the Free Software Foundation. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="intro"> - <title>Introduction</title> - <para> - The generic Reed-Solomon Library provides encoding, decoding - and error correction functions. - </para> - <para> - Reed-Solomon codes are used in communication and storage - applications to ensure data integrity. - </para> - <para> - This documentation is provided for developers who want to utilize - the functions provided by the library. - </para> - </chapter> - - <chapter id="bugs"> - <title>Known Bugs And Assumptions</title> - <para> - None. - </para> - </chapter> - - <chapter id="usage"> - <title>Usage</title> - <para> - This chapter provides examples of how to use the library. - </para> - <sect1> - <title>Initializing</title> - <para> - The init function init_rs returns a pointer to an - rs decoder structure, which holds the necessary - information for encoding, decoding and error correction - with the given polynomial. It either uses an existing - matching decoder or creates a new one. On creation all - the lookup tables for fast en/decoding are created. - The function may take a while, so make sure not to - call it in critical code paths. - </para> - <programlisting> -/* the Reed Solomon control structure */ -static struct rs_control *rs_decoder; - -/* Symbolsize is 10 (bits) - * Primitive polynomial is x^10+x^3+1 - * first consecutive root is 0 - * primitive element to generate roots = 1 - * generator polynomial degree (number of roots) = 6 - */ -rs_decoder = init_rs (10, 0x409, 0, 1, 6); - </programlisting> - </sect1> - <sect1> - <title>Encoding</title> - <para> - The encoder calculates the Reed-Solomon code over - the given data length and stores the result in - the parity buffer. Note that the parity buffer must - be initialized before calling the encoder. - </para> - <para> - The expanded data can be inverted on the fly by - providing a non-zero inversion mask. The expanded data is - XOR'ed with the mask. This is used e.g. for FLASH - ECC, where the all 0xFF is inverted to an all 0x00. - The Reed-Solomon code for all 0x00 is all 0x00. The - code is inverted before storing to FLASH so it is 0xFF - too. This prevents that reading from an erased FLASH - results in ECC errors. - </para> - <para> - The databytes are expanded to the given symbol size - on the fly. There is no support for encoding continuous - bitstreams with a symbol size != 8 at the moment. If - it is necessary it should be not a big deal to implement - such functionality. - </para> - <programlisting> -/* Parity buffer. Size = number of roots */ -uint16_t par[6]; -/* Initialize the parity buffer */ -memset(par, 0, sizeof(par)); -/* Encode 512 byte in data8. Store parity in buffer par */ -encode_rs8 (rs_decoder, data8, 512, par, 0); - </programlisting> - </sect1> - <sect1> - <title>Decoding</title> - <para> - The decoder calculates the syndrome over - the given data length and the received parity symbols - and corrects errors in the data. - </para> - <para> - If a syndrome is available from a hardware decoder - then the syndrome calculation is skipped. - </para> - <para> - The correction of the data buffer can be suppressed - by providing a correction pattern buffer and an error - location buffer to the decoder. The decoder stores the - calculated error location and the correction bitmask - in the given buffers. This is useful for hardware - decoders which use a weird bit ordering scheme. - </para> - <para> - The databytes are expanded to the given symbol size - on the fly. There is no support for decoding continuous - bitstreams with a symbolsize != 8 at the moment. If - it is necessary it should be not a big deal to implement - such functionality. - </para> - - <sect2> - <title> - Decoding with syndrome calculation, direct data correction - </title> - <programlisting> -/* Parity buffer. Size = number of roots */ -uint16_t par[6]; -uint8_t data[512]; -int numerr; -/* Receive data */ -..... -/* Receive parity */ -..... -/* Decode 512 byte in data8.*/ -numerr = decode_rs8 (rs_decoder, data8, par, 512, NULL, 0, NULL, 0, NULL); - </programlisting> - </sect2> - - <sect2> - <title> - Decoding with syndrome given by hardware decoder, direct data correction - </title> - <programlisting> -/* Parity buffer. Size = number of roots */ -uint16_t par[6], syn[6]; -uint8_t data[512]; -int numerr; -/* Receive data */ -..... -/* Receive parity */ -..... -/* Get syndrome from hardware decoder */ -..... -/* Decode 512 byte in data8.*/ -numerr = decode_rs8 (rs_decoder, data8, par, 512, syn, 0, NULL, 0, NULL); - </programlisting> - </sect2> - - <sect2> - <title> - Decoding with syndrome given by hardware decoder, no direct data correction. - </title> - <para> - Note: It's not necessary to give data and received parity to the decoder. - </para> - <programlisting> -/* Parity buffer. Size = number of roots */ -uint16_t par[6], syn[6], corr[8]; -uint8_t data[512]; -int numerr, errpos[8]; -/* Receive data */ -..... -/* Receive parity */ -..... -/* Get syndrome from hardware decoder */ -..... -/* Decode 512 byte in data8.*/ -numerr = decode_rs8 (rs_decoder, NULL, NULL, 512, syn, 0, errpos, 0, corr); -for (i = 0; i < numerr; i++) { - do_error_correction_in_your_buffer(errpos[i], corr[i]); -} - </programlisting> - </sect2> - </sect1> - <sect1> - <title>Cleanup</title> - <para> - The function free_rs frees the allocated resources, - if the caller is the last user of the decoder. - </para> - <programlisting> -/* Release resources */ -free_rs(rs_decoder); - </programlisting> - </sect1> - - </chapter> - - <chapter id="structs"> - <title>Structures</title> - <para> - This chapter contains the autogenerated documentation of the structures which are - used in the Reed-Solomon Library and are relevant for a developer. - </para> -!Iinclude/linux/rslib.h - </chapter> - - <chapter id="pubfunctions"> - <title>Public Functions Provided</title> - <para> - This chapter contains the autogenerated documentation of the Reed-Solomon functions - which are exported. - </para> -!Elib/reed_solomon/reed_solomon.c - </chapter> - - <chapter id="credits"> - <title>Credits</title> - <para> - The library code for encoding and decoding was written by Phil Karn. - </para> - <programlisting> - Copyright 2002, Phil Karn, KA9Q - May be used under the terms of the GNU General Public License (GPL) - </programlisting> - <para> - The wrapper functions and interfaces are written by Thomas Gleixner. - </para> - <para> - Many users have provided bugfixes, improvements and helping hands for testing. - Thanks a lot. - </para> - <para> - The following people have contributed to this document: - </para> - <para> - Thomas Gleixner<email>tglx@linutronix.de</email> - </para> - </chapter> -</book> diff --git a/Documentation/DocBook/lsm.tmpl b/Documentation/DocBook/lsm.tmpl deleted file mode 100644 index fe7664ce9667..000000000000 --- a/Documentation/DocBook/lsm.tmpl +++ /dev/null @@ -1,265 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<article class="whitepaper" id="LinuxSecurityModule" lang="en"> - <articleinfo> - <title>Linux Security Modules: General Security Hooks for Linux</title> - <authorgroup> - <author> - <firstname>Stephen</firstname> - <surname>Smalley</surname> - <affiliation> - <orgname>NAI Labs</orgname> - <address><email>ssmalley@nai.com</email></address> - </affiliation> - </author> - <author> - <firstname>Timothy</firstname> - <surname>Fraser</surname> - <affiliation> - <orgname>NAI Labs</orgname> - <address><email>tfraser@nai.com</email></address> - </affiliation> - </author> - <author> - <firstname>Chris</firstname> - <surname>Vance</surname> - <affiliation> - <orgname>NAI Labs</orgname> - <address><email>cvance@nai.com</email></address> - </affiliation> - </author> - </authorgroup> - </articleinfo> - -<sect1 id="Introduction"><title>Introduction</title> - -<para> -In March 2001, the National Security Agency (NSA) gave a presentation -about Security-Enhanced Linux (SELinux) at the 2.5 Linux Kernel -Summit. SELinux is an implementation of flexible and fine-grained -nondiscretionary access controls in the Linux kernel, originally -implemented as its own particular kernel patch. Several other -security projects (e.g. RSBAC, Medusa) have also developed flexible -access control architectures for the Linux kernel, and various -projects have developed particular access control models for Linux -(e.g. LIDS, DTE, SubDomain). Each project has developed and -maintained its own kernel patch to support its security needs. -</para> - -<para> -In response to the NSA presentation, Linus Torvalds made a set of -remarks that described a security framework he would be willing to -consider for inclusion in the mainstream Linux kernel. He described a -general framework that would provide a set of security hooks to -control operations on kernel objects and a set of opaque security -fields in kernel data structures for maintaining security attributes. -This framework could then be used by loadable kernel modules to -implement any desired model of security. Linus also suggested the -possibility of migrating the Linux capabilities code into such a -module. -</para> - -<para> -The Linux Security Modules (LSM) project was started by WireX to -develop such a framework. LSM is a joint development effort by -several security projects, including Immunix, SELinux, SGI and Janus, -and several individuals, including Greg Kroah-Hartman and James -Morris, to develop a Linux kernel patch that implements this -framework. The patch is currently tracking the 2.4 series and is -targeted for integration into the 2.5 development series. This -technical report provides an overview of the framework and the example -capabilities security module provided by the LSM kernel patch. -</para> - -</sect1> - -<sect1 id="framework"><title>LSM Framework</title> - -<para> -The LSM kernel patch provides a general kernel framework to support -security modules. In particular, the LSM framework is primarily -focused on supporting access control modules, although future -development is likely to address other security needs such as -auditing. By itself, the framework does not provide any additional -security; it merely provides the infrastructure to support security -modules. The LSM kernel patch also moves most of the capabilities -logic into an optional security module, with the system defaulting -to the traditional superuser logic. This capabilities module -is discussed further in <xref linkend="cap"/>. -</para> - -<para> -The LSM kernel patch adds security fields to kernel data structures -and inserts calls to hook functions at critical points in the kernel -code to manage the security fields and to perform access control. It -also adds functions for registering and unregistering security -modules, and adds a general <function>security</function> system call -to support new system calls for security-aware applications. -</para> - -<para> -The LSM security fields are simply <type>void*</type> pointers. For -process and program execution security information, security fields -were added to <structname>struct task_struct</structname> and -<structname>struct linux_binprm</structname>. For filesystem security -information, a security field was added to -<structname>struct super_block</structname>. For pipe, file, and socket -security information, security fields were added to -<structname>struct inode</structname> and -<structname>struct file</structname>. For packet and network device security -information, security fields were added to -<structname>struct sk_buff</structname> and -<structname>struct net_device</structname>. For System V IPC security -information, security fields were added to -<structname>struct kern_ipc_perm</structname> and -<structname>struct msg_msg</structname>; additionally, the definitions -for <structname>struct msg_msg</structname>, <structname>struct -msg_queue</structname>, and <structname>struct -shmid_kernel</structname> were moved to header files -(<filename>include/linux/msg.h</filename> and -<filename>include/linux/shm.h</filename> as appropriate) to allow -the security modules to use these definitions. -</para> - -<para> -Each LSM hook is a function pointer in a global table, -security_ops. This table is a -<structname>security_operations</structname> structure as defined by -<filename>include/linux/security.h</filename>. Detailed documentation -for each hook is included in this header file. At present, this -structure consists of a collection of substructures that group related -hooks based on the kernel object (e.g. task, inode, file, sk_buff, -etc) as well as some top-level hook function pointers for system -operations. This structure is likely to be flattened in the future -for performance. The placement of the hook calls in the kernel code -is described by the "called:" lines in the per-hook documentation in -the header file. The hook calls can also be easily found in the -kernel code by looking for the string "security_ops->". - -</para> - -<para> -Linus mentioned per-process security hooks in his original remarks as a -possible alternative to global security hooks. However, if LSM were -to start from the perspective of per-process hooks, then the base -framework would have to deal with how to handle operations that -involve multiple processes (e.g. kill), since each process might have -its own hook for controlling the operation. This would require a -general mechanism for composing hooks in the base framework. -Additionally, LSM would still need global hooks for operations that -have no process context (e.g. network input operations). -Consequently, LSM provides global security hooks, but a security -module is free to implement per-process hooks (where that makes sense) -by storing a security_ops table in each process' security field and -then invoking these per-process hooks from the global hooks. -The problem of composition is thus deferred to the module. -</para> - -<para> -The global security_ops table is initialized to a set of hook -functions provided by a dummy security module that provides -traditional superuser logic. A <function>register_security</function> -function (in <filename>security/security.c</filename>) is provided to -allow a security module to set security_ops to refer to its own hook -functions, and an <function>unregister_security</function> function is -provided to revert security_ops to the dummy module hooks. This -mechanism is used to set the primary security module, which is -responsible for making the final decision for each hook. -</para> - -<para> -LSM also provides a simple mechanism for stacking additional security -modules with the primary security module. It defines -<function>register_security</function> and -<function>unregister_security</function> hooks in the -<structname>security_operations</structname> structure and provides -<function>mod_reg_security</function> and -<function>mod_unreg_security</function> functions that invoke these -hooks after performing some sanity checking. A security module can -call these functions in order to stack with other modules. However, -the actual details of how this stacking is handled are deferred to the -module, which can implement these hooks in any way it wishes -(including always returning an error if it does not wish to support -stacking). In this manner, LSM again defers the problem of -composition to the module. -</para> - -<para> -Although the LSM hooks are organized into substructures based on -kernel object, all of the hooks can be viewed as falling into two -major categories: hooks that are used to manage the security fields -and hooks that are used to perform access control. Examples of the -first category of hooks include the -<function>alloc_security</function> and -<function>free_security</function> hooks defined for each kernel data -structure that has a security field. These hooks are used to allocate -and free security structures for kernel objects. The first category -of hooks also includes hooks that set information in the security -field after allocation, such as the <function>post_lookup</function> -hook in <structname>struct inode_security_ops</structname>. This hook -is used to set security information for inodes after successful lookup -operations. An example of the second category of hooks is the -<function>permission</function> hook in -<structname>struct inode_security_ops</structname>. This hook checks -permission when accessing an inode. -</para> - -</sect1> - -<sect1 id="cap"><title>LSM Capabilities Module</title> - -<para> -The LSM kernel patch moves most of the existing POSIX.1e capabilities -logic into an optional security module stored in the file -<filename>security/capability.c</filename>. This change allows -users who do not want to use capabilities to omit this code entirely -from their kernel, instead using the dummy module for traditional -superuser logic or any other module that they desire. This change -also allows the developers of the capabilities logic to maintain and -enhance their code more freely, without needing to integrate patches -back into the base kernel. -</para> - -<para> -In addition to moving the capabilities logic, the LSM kernel patch -could move the capability-related fields from the kernel data -structures into the new security fields managed by the security -modules. However, at present, the LSM kernel patch leaves the -capability fields in the kernel data structures. In his original -remarks, Linus suggested that this might be preferable so that other -security modules can be easily stacked with the capabilities module -without needing to chain multiple security structures on the security field. -It also avoids imposing extra overhead on the capabilities module -to manage the security fields. However, the LSM framework could -certainly support such a move if it is determined to be desirable, -with only a few additional changes described below. -</para> - -<para> -At present, the capabilities logic for computing process capabilities -on <function>execve</function> and <function>set*uid</function>, -checking capabilities for a particular process, saving and checking -capabilities for netlink messages, and handling the -<function>capget</function> and <function>capset</function> system -calls have been moved into the capabilities module. There are still a -few locations in the base kernel where capability-related fields are -directly examined or modified, but the current version of the LSM -patch does allow a security module to completely replace the -assignment and testing of capabilities. These few locations would -need to be changed if the capability-related fields were moved into -the security field. The following is a list of known locations that -still perform such direct examination or modification of -capability-related fields: -<itemizedlist> -<listitem><para><filename>fs/open.c</filename>:<function>sys_access</function></para></listitem> -<listitem><para><filename>fs/lockd/host.c</filename>:<function>nlm_bind_host</function></para></listitem> -<listitem><para><filename>fs/nfsd/auth.c</filename>:<function>nfsd_setuser</function></para></listitem> -<listitem><para><filename>fs/proc/array.c</filename>:<function>task_cap</function></para></listitem> -</itemizedlist> -</para> - -</sect1> - -</article> diff --git a/Documentation/DocBook/media/.gitignore b/Documentation/DocBook/media/.gitignore deleted file mode 100644 index e461c585fde8..000000000000 --- a/Documentation/DocBook/media/.gitignore +++ /dev/null @@ -1 +0,0 @@ -!*.svg diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile deleted file mode 100644 index 2840ff483d5a..000000000000 --- a/Documentation/DocBook/media/Makefile +++ /dev/null @@ -1,425 +0,0 @@ -### -# Media build rules - Auto-generates media contents/indexes and *.h xml's -# - -SHELL=/bin/bash - -MEDIA_OBJ_DIR=$(objtree)/Documentation/DocBook/ -MEDIA_SRC_DIR=$(srctree)/Documentation/DocBook/media - -MEDIA_TEMP = media-entities.tmpl \ - media-indices.tmpl \ - videodev2.h.xml \ - v4l2.xml \ - audio.h.xml \ - ca.h.xml \ - dmx.h.xml \ - frontend.h.xml \ - net.h.xml \ - video.h.xml \ - -IMGFILES := $(patsubst %.b64,%, $(notdir $(shell ls $(MEDIA_SRC_DIR)/*.b64))) -OBJIMGFILES := $(addprefix $(MEDIA_OBJ_DIR)/, $(IMGFILES)) -GENFILES := $(addprefix $(MEDIA_OBJ_DIR)/, $(MEDIA_TEMP)) - -PHONY += cleanmediadocs - -cleanmediadocs: - -@rm -f `find $(MEDIA_OBJ_DIR) -type l` $(GENFILES) $(OBJIMGFILES) 2>/dev/null - -$(obj)/media_api.xml: $(GENFILES) FORCE - -#$(MEDIA_OBJ_DIR)/media_api.html: $(MEDIA_OBJ_DIR)/media_api.xml -#$(MEDIA_OBJ_DIR)/media_api.pdf: $(MEDIA_OBJ_DIR)/media_api.xml -#$(MEDIA_OBJ_DIR)/media_api.ps: $(MEDIA_OBJ_DIR)/media_api.xml - -V4L_SGMLS = \ - $(shell ls $(MEDIA_SRC_DIR)/v4l/*.xml|perl -ne 'print "$$1 " if (m,.*/(.*)\n,)') \ - capture.c.xml \ - keytable.c.xml \ - v4l2grab.c.xml - -DVB_SGMLS = \ - $(shell ls $(MEDIA_SRC_DIR)/dvb/*.xml|perl -ne 'print "$$1 " if (m,.*/(.*)\n,)') - -MEDIA_SGMLS = $(addprefix ./,$(V4L_SGMLS)) $(addprefix ./,$(DVB_SGMLS)) $(addprefix ./,$(MEDIA_TEMP)) - -FUNCS = \ - close \ - ioctl \ - mmap \ - munmap \ - open \ - poll \ - read \ - select \ - write \ - -IOCTLS = \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/videodev2.h) \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/audio.h) \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/ca.h) \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/dmx.h) \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/frontend.h) \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([A-Z][^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/net.h) \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/video.h) \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/media.h) \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/v4l2-subdev.h) \ - -DEFINES = \ - $(shell perl -ne 'print "$$1 " if /\#define\s+(DTV_[^\s]+)\s+/' $(srctree)/include/uapi/linux/dvb/frontend.h) \ - -TYPES = \ - $(shell perl -ne 'print "$$1 " if /^typedef\s+.*\s+(\S+)\;/' $(srctree)/include/uapi/linux/videodev2.h) \ - $(shell perl -ne 'print "$$1 " if /^typedef\s+.*\s+(\S+)\;/' $(srctree)/include/uapi/linux/dvb/frontend.h) - -ENUMS = \ - $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' \ - $(srctree)/include/uapi/linux/videodev2.h \ - $(srctree)/include/uapi/linux/dvb/audio.h \ - $(srctree)/include/uapi/linux/dvb/ca.h \ - $(srctree)/include/uapi/linux/dvb/dmx.h \ - $(srctree)/include/uapi/linux/dvb/frontend.h \ - $(srctree)/include/uapi/linux/dvb/net.h \ - $(srctree)/include/uapi/linux/dvb/video.h \ - $(srctree)/include/uapi/linux/media.h \ - $(srctree)/include/uapi/linux/v4l2-mediabus.h \ - $(srctree)/include/uapi/linux/v4l2-subdev.h) - -ENUM_DEFS = \ - $(shell perl -e 'open IN,"cat @ARGV| cpp -fpreprocessed |"; while (<IN>) { if ($$enum) {print "$$1\n" if (/\s*([A-Z]\S+)\b/); } $$enum = 0 if ($$enum && /^\}/); $$enum = 1 if(/^\s*enum\s/); }; close IN;' \ - $(srctree)/include/uapi/linux/dvb/dmx.h \ - $(srctree)/include/uapi/linux/dvb/frontend.h) - -STRUCTS = \ - $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/videodev2.h) \ - $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s\{]+)\s*/)' $(srctree)/include/uapi/linux/dvb/audio.h) \ - $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/ca.h) \ - $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/dmx.h) \ - $(shell perl -ne 'print "$$1 " if (!/dtv\_cmds\_h/ && /^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/frontend.h) \ - $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/ && !/_old/)' $(srctree)/include/uapi/linux/dvb/net.h) \ - $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/video.h) \ - $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/media.h) \ - $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-subdev.h) \ - $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-mediabus.h) - -ERRORS = \ - E2BIG \ - EACCES \ - EAGAIN \ - EBADF \ - EBADFD \ - EBADR \ - EBADRQC \ - EBUSY \ - ECHILD \ - ECONNRESET \ - EDEADLK \ - EDOM \ - EEXIST \ - EFAULT \ - EFBIG \ - EILSEQ \ - EINIT \ - EINPROGRESS \ - EINTR \ - EINVAL \ - EIO \ - EMFILE \ - ENFILE \ - ENOBUFS \ - ENODATA \ - ENODEV \ - ENOENT \ - ENOIOCTLCMD \ - ENOMEM \ - ENOSPC \ - ENOSR \ - ENOSYS \ - ENOTSUP \ - ENOTSUPP \ - ENOTTY \ - ENXIO \ - EOPNOTSUPP \ - EOVERFLOW \ - EPERM \ - EPIPE \ - EPROTO \ - ERANGE \ - EREMOTE \ - EREMOTEIO \ - ERESTART \ - ERESTARTSYS \ - ESHUTDOWN \ - ESPIPE \ - ETIME \ - ETIMEDOUT \ - EUSERS \ - EWOULDBLOCK \ - EXDEV \ - -ESCAPE = \ - -e "s/&/\\&/g" \ - -e "s/</\\</g" \ - -e "s/>/\\>/g" - -FILENAME = \ - -e s,"^[^\/]*/",, \ - -e s/"\\.xml"// \ - -e s/"\\.tmpl"// \ - -e s/\\\./-/g \ - -e s/"^func-"// \ - -e s/"^pixfmt-"// \ - -e s/"^vidioc-"// - -# Generate references to these structs in videodev2.h.xml. -DOCUMENTED = \ - -e "s/\(enum *\)v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1<link linkend=\"\2\">v4l2_mpeg_cx2341x_video_\2<\/link>/g" \ - -e "s/\(\(enum\|struct\) *\)\(v4l2_[a-zA-Z0-9_]*\)/\1<link linkend=\"\3\">\3<\/link>/g" \ - -e "s/\(V4L2_PIX_FMT_[A-Z0-9_]\+\)\(\s\+v4l2_fourcc\)/<link linkend=\"\1\">\1<\/link>\2/g" \ - -e ":a;s/\(linkend=\".*\)_\(.*\">\)/\1-\2/;ta" \ - -e "s/v4l2\-mpeg\-vbi\-ITV0/v4l2-mpeg-vbi-itv0-1/g" - -DVB_DOCUMENTED = \ - -e "s,\(struct\s\+\)\([a-z0-9_]\+\)\(\s\+{\),\1\<link linkend=\"\2\">\2\<\/link\>\3,g" \ - -e "s,\(}\s\+\)\([a-z0-9_]\+_t\+\),\1\<link linkend=\"\2\">\2\<\/link\>,g" \ - -e "s,\(define\s\+\)\(DTV_[A-Z0-9_]\+\)\(\s\+[0-9]\+\),\1\<link linkend=\"\2\">\2\<\/link\>\3,g" \ - -e "s,<link\s\+linkend=\".*\">\(DTV_IOCTL_MAX_MSGS\|dtv_cmds_h\|__.*_old\)<\/link>,\1,g" \ - -e ":a;s/\(linkend=\".*\)_\(.*\">\)/\1-\2/;ta" \ - -e "s,\(audio-mixer\|audio-karaoke\|audio-status\|ca-slot-info\|ca-descr-info\|ca-caps\|ca-msg\|ca-descr\|ca-pid\|dmx-filter\|dmx-caps\|video-system\|video-highlight\|video-spu\|video-spu-palette\|video-navi-pack\)-t,\1,g" \ - -e "s,DTV-ISDBT-LAYER[A-C],DTV-ISDBT-LAYER,g" \ - -e "s,\(define\s\+\)\([A-Z0-9_]\+\)\(\s\+_IO\),\1\<link linkend=\"\2\">\2\<\/link\>\3,g" \ - -e "s,\(define\s\+\)\(DTV_[A-Z0-9_]\+\)\(\s\+\),\1\<link linkend=\"\2\">\2\<\/link\>\3,g" \ - -e "s,<link\s\+linkend=\".*\">\(__.*_OLD\)<\/link>,\1,g" \ - -e "s/\(linkend\=\"\)FE_SET_PROPERTY/\1FE_GET_PROPERTY/g" \ - -e "s,<link\s\+linkend=\".*\">\(DTV_ISDBS_TS_ID_LEGACY\|DTV_MAX_COMMAND\|DTV_IOCTL_MAX_MSGS\)<\/link>,\1,g" \ - -# -# Media targets and dependencies -# - -install_media_images = \ - $(Q)if [ "x$(findstring media_api.xml,$(DOCBOOKS))" != "x" ]; then \ - mkdir -p $(MEDIA_OBJ_DIR)/media_api; \ - cp $(OBJIMGFILES) $(MEDIA_SRC_DIR)/*.svg $(MEDIA_SRC_DIR)/v4l/*.svg $(MEDIA_OBJ_DIR)/media_api; \ - fi - -$(MEDIA_OBJ_DIR)/%: $(MEDIA_SRC_DIR)/%.b64 - $(Q)base64 -d $< >$@ - -$(MEDIA_OBJ_DIR)/v4l2.xml: $(OBJIMGFILES) - @$($(quiet)gen_xml) - @(ln -sf `cd $(MEDIA_SRC_DIR) && /bin/pwd`/v4l/*xml $(MEDIA_OBJ_DIR)/) - @(ln -sf `cd $(MEDIA_SRC_DIR) && /bin/pwd`/dvb/*xml $(MEDIA_OBJ_DIR)/) - -$(MEDIA_OBJ_DIR)/videodev2.h.xml: $(srctree)/include/uapi/linux/videodev2.h $(MEDIA_OBJ_DIR)/v4l2.xml - @$($(quiet)gen_xml) - @( \ - echo "<programlisting>") > $@ - @( \ - expand --tabs=8 < $< | \ - sed $(ESCAPE) $(DOCUMENTED) | \ - sed 's/i\.e\./&ie;/') >> $@ - @( \ - echo "</programlisting>") >> $@ - -$(MEDIA_OBJ_DIR)/audio.h.xml: $(srctree)/include/uapi/linux/dvb/audio.h $(MEDIA_OBJ_DIR)/v4l2.xml - @$($(quiet)gen_xml) - @( \ - echo "<programlisting>") > $@ - @( \ - expand --tabs=8 < $< | \ - sed $(ESCAPE) $(DVB_DOCUMENTED) | \ - sed 's/i\.e\./&ie;/') >> $@ - @( \ - echo "</programlisting>") >> $@ - -$(MEDIA_OBJ_DIR)/ca.h.xml: $(srctree)/include/uapi/linux/dvb/ca.h $(MEDIA_OBJ_DIR)/v4l2.xml - @$($(quiet)gen_xml) - @( \ - echo "<programlisting>") > $@ - @( \ - expand --tabs=8 < $< | \ - sed $(ESCAPE) $(DVB_DOCUMENTED) | \ - sed 's/i\.e\./&ie;/') >> $@ - @( \ - echo "</programlisting>") >> $@ - -$(MEDIA_OBJ_DIR)/dmx.h.xml: $(srctree)/include/uapi/linux/dvb/dmx.h $(MEDIA_OBJ_DIR)/v4l2.xml - @$($(quiet)gen_xml) - @( \ - echo "<programlisting>") > $@ - @( \ - for ident in $(ENUM_DEFS) ; do \ - entity=`echo $$ident | tr _ -` ; \ - r="$$r s/([^\w\-])$$ident([^\w\-])/\1\&$$entity\;\2/g;";\ - done; \ - expand --tabs=8 < $< | \ - sed $(ESCAPE) $(DVB_DOCUMENTED) | \ - sed 's/i\.e\./&ie;/' | \ - perl -ne "$$r print $$_;") >> $@ - @( \ - echo "</programlisting>") >> $@ - -$(MEDIA_OBJ_DIR)/frontend.h.xml: $(srctree)/include/uapi/linux/dvb/frontend.h $(MEDIA_OBJ_DIR)/v4l2.xml - @$($(quiet)gen_xml) - @( \ - echo "<programlisting>") > $@ - @( \ - for ident in $(ENUM_DEFS) ; do \ - entity=`echo $$ident | tr _ -` ; \ - r="$$r s/([^\w\-])$$ident([^\w\-])/\1\&$$entity\;\2/g;";\ - done; \ - expand --tabs=8 < $< | \ - sed $(ESCAPE) $(DVB_DOCUMENTED) | \ - sed 's/i\.e\./&ie;/' | \ - perl -ne "$$r print $$_;") >> $@ - @( \ - echo "</programlisting>") >> $@ - -$(MEDIA_OBJ_DIR)/net.h.xml: $(srctree)/include/uapi/linux/dvb/net.h $(MEDIA_OBJ_DIR)/v4l2.xml - @$($(quiet)gen_xml) - @( \ - echo "<programlisting>") > $@ - @( \ - expand --tabs=8 < $< | \ - sed $(ESCAPE) $(DVB_DOCUMENTED) | \ - sed 's/i\.e\./&ie;/') >> $@ - @( \ - echo "</programlisting>") >> $@ - -$(MEDIA_OBJ_DIR)/video.h.xml: $(srctree)/include/uapi/linux/dvb/video.h $(MEDIA_OBJ_DIR)/v4l2.xml - @$($(quiet)gen_xml) - @( \ - echo "<programlisting>") > $@ - @( \ - expand --tabs=8 < $< | \ - sed $(ESCAPE) $(DVB_DOCUMENTED) | \ - sed 's/i\.e\./&ie;/') >> $@ - @( \ - echo "</programlisting>") >> $@ - -$(MEDIA_OBJ_DIR)/media-entities.tmpl: $(MEDIA_OBJ_DIR)/v4l2.xml - @$($(quiet)gen_xml) - @( \ - echo "<!-- Generated file! Do not edit. -->") >$@ - @( \ - echo -e "\n<!-- Functions -->") >>$@ - @( \ - for ident in $(FUNCS) ; do \ - entity=`echo $$ident | tr _ -` ; \ - echo "<!ENTITY func-$$entity \"<link" \ - "linkend='func-$$entity'><function>$$ident()</function></link>\">" \ - >>$@ ; \ - done) - @( \ - echo -e "\n<!-- Ioctls -->") >>$@ - @( \ - for ident in `echo $(IOCTLS) | sed -e "s,VIDIOC_RESERVED,,"`; do\ - entity=`echo $$ident | tr _ -` ; \ - id=`grep -e "<refname>$$ident" -e "<section id=\"$$ident\"" $$(find $(MEDIA_SRC_DIR) -name *.xml -type f)| sed -r s,"^.*/(.*).xml.*","\1",` ; \ - if [ "$$id" != "" ]; then echo "<!ENTITY $$entity \"<link" \ - "linkend='$$id'><constant>$$ident</constant></link>\">" \ - >>$@ ; else \ - echo "Warning: undocumented ioctl: $$ident. Please document it at the media DocBook!" >&2; \ - fi; \ - done) - @( \ - echo -e "\n<!-- Defines -->") >>$@ - @( \ - for ident in $(DEFINES) ; do \ - entity=`echo $$ident | tr _ -` ; \ - echo "<!ENTITY $$entity \"<link" \ - "linkend='$$entity'><constant>$$ident</constant></link>\">" \ - >>$@ ; \ - done) - @( \ - echo -e "\n<!-- Types -->") >>$@ - @( \ - for ident in $(TYPES) ; do \ - entity=`echo $$ident | tr _ -` ; \ - echo "<!ENTITY $$entity \"<link" \ - "linkend='$$entity'>$$ident</link>\">" >>$@ ; \ - done) - @( \ - echo -e "\n<!-- Enums -->") >>$@ - @( \ - for ident in $(ENUMS) ; do \ - entity=`echo $$ident | sed -e "s/v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1/" | tr _ -` ; \ - echo "<!ENTITY $$entity \"enum <link" \ - "linkend='$$entity'>$$ident</link>\">" >>$@ ; \ - done) - @( \ - echo -e "\n<!-- Enum definitions -->") >>$@ - @( \ - for ident in $(ENUM_DEFS) ; do \ - entity=`echo $$ident | tr _ -` ; \ - echo "<!ENTITY $$entity \"<link" \ - "linkend='$$entity'><constant>$$ident</constant></link>\">" \ - >>$@ ; \ - done) - @( \ - echo -e "\n<!-- Structures -->") >>$@ - @( \ - for ident in $(STRUCTS) ; do \ - entity=`echo $$ident | tr _ - | sed s/v4l2-mpeg-vbi-ITV0/v4l2-mpeg-vbi-itv0-1/g` ; \ - echo "<!ENTITY $$entity \"struct <link" \ - "linkend='$$entity'>$$ident</link>\">" >>$@ ; \ - done) - @( \ - echo -e "\n<!-- Error Codes -->") >>$@ - @( \ - for ident in $(ERRORS) ; do \ - echo "<!ENTITY $$ident \"<errorcode>$$ident</errorcode>" \ - "error code\">" >>$@ ; \ - done) - @( \ - echo -e "\n<!-- Subsections -->") >>$@ - @( \ - for file in $(MEDIA_SGMLS) ; do \ - entity=`echo "$$file" | sed $(FILENAME) -e s/"^([^-]*)"/sub\1/` ; \ - if ! echo "$$file" | \ - grep -q -E -e '^(func|vidioc|pixfmt)-' ; then \ - echo "<!ENTITY sub-$$entity SYSTEM \"$$file\">" >>$@ ; \ - fi ; \ - done) - @( \ - echo -e "\n<!-- Function Reference -->") >>$@ - @( \ - for file in $(MEDIA_SGMLS) ; do \ - if echo "$$file" | \ - grep -q -E -e '(func|vidioc|pixfmt)-' ; then \ - entity=`echo "$$file" |sed $(FILENAME)` ; \ - echo "<!ENTITY $$entity SYSTEM \"$$file\">" >>$@ ; \ - fi ; \ - done) - -# Jade can auto-generate a list-of-tables, which includes all structs, -# but we only want data types, all types, and sorted please. -$(MEDIA_OBJ_DIR)/media-indices.tmpl: $(MEDIA_OBJ_DIR)/v4l2.xml - @$($(quiet)gen_xml) - @( \ - echo "<!-- Generated file! Do not edit. -->") >$@ - @( \ - echo -e "\n<index><title>List of Types</title>") >>$@ - @( \ - for ident in $(TYPES) ; do \ - id=`echo $$ident | tr _ -` ; \ - echo "<indexentry><primaryie><link" \ - "linkend='$$id'>$$ident</link></primaryie></indexentry>" >>$@ ; \ - done) - @( \ - for ident in $(ENUMS) ; do \ - id=`echo $$ident | sed -e "s/v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1/" | tr _ -`; \ - echo "<indexentry><primaryie>enum <link" \ - "linkend='$$id'>$$ident</link></primaryie></indexentry>" >>$@ ; \ - done) - @( \ - for ident in $(STRUCTS) ; do \ - id=`echo $$ident | tr _ - | sed s/v4l2-mpeg-vbi-ITV0/v4l2-mpeg-vbi-itv0-1/g` ; \ - echo "<indexentry><primaryie>struct <link" \ - "linkend='$$id'>$$ident</link></primaryie></indexentry>" >>$@ ; \ - done) - @( \ - echo "</index>") >>$@ - diff --git a/Documentation/DocBook/media/bayer.png.b64 b/Documentation/DocBook/media/bayer.png.b64 deleted file mode 100644 index ccdf2bcda95c..000000000000 --- a/Documentation/DocBook/media/bayer.png.b64 +++ /dev/null @@ -1,171 +0,0 @@ -iVBORw0KGgoAAAANSUhEUgAAAlgAAACqCAMAAABGfcHVAAAAAXNSR0IArs4c6QAAAwBQTFRFAAIA -CAICAAQVEQEBAgsAJgECAAogAwsTAQopHQYBNAEAAAxNARQAERIQAhoDABwAABZEHRQKGRYKQw0F -ACMBACUAERwpHR4cVRAFBR5rZhADACR2JiIhBDAGAiWGgQ4AcxQABDYACSeQMSYlJykmESxYlQ4A -PSYZIS05OSsJHS5JOC8kAEMDUC8SADXLNDUzADbEAEsAADX/2RABCFIAAD/qxB0AAD//BFgAK0Vp -WT4r3hwA3RsTRERAAEf/5CIA2iYCCUv+WUgz7iIAOk5g3CgVSU5SiD8uB2sABm8AE1X/U1RQOFyL -4jkfIlz/RV98M1j+G2H/fVk23jtD4T0pXl9ieFtGcV894UIiYWJfAIwA50gOV2p+4kssO2j+dGZx -bG1qVmj/OHH/aHJzfnBX5lQ7B50AZnahdXd0AKUG5V1ARnz/6mErCqgAAKsAent46GBIW4GhAK0A -AK8B42FtALIOin9/ALUAiIOBALkAVIf/6WxWg4eBi4SKJrEAmoVtdY2geoP/rYVXhoyOqYVuJbUh -IrgWX5D/jo6J7nszP7gAsI9S63xnN70zZqO/fZzCOb4+cZr+64dy8otYnJ6b7ImDRcM56IqcWMEo -oJb/N8ZoTMRL7Y9/QchcsaOTo6eohaj/7ZqKXspXj6v9xal+oK+7d7vTUM+Afco5r7CumLTVStKV -bs9ukbb/9qx/9q9l8queoLv/e9R66beG7rDImNRhi9aDwsPAs8bWzcK2cd67jtqP5MWUodyB8b+1 -tMr/z8L/j9+kbOXWnN2ZstD7yc7Rzs7Ly9xb183UwdD/+si/qeOmvuKIx9fj4tPCtuWiqOrL+tS2 -y9v++NPK2dvZt+m0ueq80+Wo3OeSwuy/yezG+d7f/eS/z/DS3uf/6Ono4PC71O39xPb02vPZ/+nR -+Ori6e399+vt+PGz+ur65fL55/Xb4vbh7ffX/PPY8vP9+vLy6Pf36fjr/PfM8vjr//f+/vn48P36 -9vv+/vzf+fv4/fvu//z7+v7//P/7/v/8//QpxAAAAAFiS0dEAIgFHUgAAAAJcEhZcwAAFY8AABWW -AQ2TT8cAAAAHdElNRQfaCRQXGSltwbPRAAAgAElEQVR42u2dDXwU1bXAZwEJtEaNH1nbh68fpoWK -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 diff --git a/Documentation/DocBook/media/constraints.png.b64 b/Documentation/DocBook/media/constraints.png.b64 deleted file mode 100644 index 125b4a94962c..000000000000 --- a/Documentation/DocBook/media/constraints.png.b64 +++ /dev/null @@ -1,59 +0,0 @@ -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 -RU5ErkJggg== diff --git a/Documentation/DocBook/media/crop.gif.b64 b/Documentation/DocBook/media/crop.gif.b64 deleted file mode 100644 index 11d936ae72e8..000000000000 --- a/Documentation/DocBook/media/crop.gif.b64 +++ /dev/null @@ -1,105 +0,0 @@ -R0lGODlhuQJGAeMAAAAAAH9/fwCvAP8AANEA0dEAAK8Ar////wCOAAAA0QAA//////////////// -/////ywAAAAAuQJGAQAE/vDISau9OOvNu/9gKI5kaZ5oqq5s675wLM90bd94ru987//AoHBILBqP -yKRyyWw6n9CodEqtWq/YrHbL7Xq/4LB4TC6bz+i0es1uu9/wuHxOr9vv+Lx+z+/7/4CBgoOEhYaH -iImKi4yNjo+QkZKTlJWWl5iZmpucnZ6foKGio6SlpqeoqaqrrK2ur7CxsrO0tba3uLm6gQC9vr/A -wcLDxMXGx8jJysvMzc7P0NHS09TV1tfYxbth2d3e3+DRAePk5ebn6Onl4ezt7u3q8fLqANtg7/j5 -+s/z/f4B+wIKHAjsn8F09ex5IciwobuDEM1Bi0ixosWLGDNqrJhQIZdk/htDihxJsiTJiSZTqlzJ -MmNHj1q+tRznsKbNmzhzDoz3EiYWmTN7+vQJgOfQmN5mAjzKtCg9pj+TBoU61ClCqlaAthSKVZdV -dFy7NtHKMqxYW1/PmT2bhOzKtWxlpZUYF4pblXDrvpq7Tq+Tu+UGCB5MuLDhw4gTK17MuLHjx5Aj -S55MubLly5gza95MmVxev0EAkxsg8jNoVXNJ0zy9RPQ41RtNsz6V2vPstlLTwdYo+zap2qt9G3Ed -YLdL4bGAL0VOhLhxjL2Zf1IeXboM56Wtt6KuPXRudM8vVu+eiTt5H9hDjj9vyfyIXrTW80gfO4OC -+/jz69/Pv7///wAG/ijggAQWaOCBCCao4IIMNujggRe4J4IwBxBg4YUYZqjhhhx26OGHIIYo4ogk -loihMBbi1k084VlklgLsWQKjBRJqgIwEBJRyY4UqZsNidhjMGOMkQlLgnjERwkdBjuVpk2QFTB5B -H2/2DUlJkRNYhWQKUTKyJQpdFjHlcUFaSaQxo9nGQph/fCkDm0OMCV2VZh7iZpbnwCYfBnDKcecO -fXq3ojotckRnnXr8SQGWEtQIphuKEhEoEHKKdygHCUiQ6QEJdDrEphWA2oGo3UXaAaMHOHrCpFmY -2gSr6H2XJ5AXoHqBp5xyuimpPfCa6we+6uWqCaiqagKsTAxrBbLz/slqTqEUvWgBqLviSqqvnXpq -rbbZTpDtt9ziSsG3unKraabkltutWMq+UOyswa3A7A/tfjGvDpW6eKm3v+a667i38vvvuQLzW7Cm -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 diff --git a/Documentation/DocBook/media/dvb/.gitignore b/Documentation/DocBook/media/dvb/.gitignore deleted file mode 100644 index d7ec32eafac9..000000000000 --- a/Documentation/DocBook/media/dvb/.gitignore +++ /dev/null @@ -1 +0,0 @@ -!*.xml diff --git a/Documentation/DocBook/media/dvb/audio.xml b/Documentation/DocBook/media/dvb/audio.xml deleted file mode 100644 index ea56743ddbe7..000000000000 --- a/Documentation/DocBook/media/dvb/audio.xml +++ /dev/null @@ -1,1314 +0,0 @@ -<title>DVB Audio Device</title> -<para>The DVB audio device controls the MPEG2 audio decoder of the DVB hardware. It -can be accessed through <constant>/dev/dvb/adapter?/audio?</constant>. Data types and and -ioctl definitions can be accessed by including <constant>linux/dvb/audio.h</constant> in your -application. -</para> -<para>Please note that some DVB cards don’t have their own MPEG decoder, which results in -the omission of the audio and video device. -</para> -<para> -These ioctls were also used by V4L2 to control MPEG decoders implemented in V4L2. The use -of these ioctls for that purpose has been made obsolete and proper V4L2 ioctls or controls -have been created to replace that functionality.</para> - -<section id="audio_data_types"> -<title>Audio Data Types</title> -<para>This section describes the structures, data types and defines used when talking to the -audio device. -</para> - -<section id="audio-stream-source-t"> -<title>audio_stream_source_t</title> -<para>The audio stream source is set through the AUDIO_SELECT_SOURCE call and can take -the following values, depending on whether we are replaying from an internal (demux) or -external (user write) source. -</para> -<programlisting> -typedef enum { - AUDIO_SOURCE_DEMUX, - AUDIO_SOURCE_MEMORY -} audio_stream_source_t; -</programlisting> -<para>AUDIO_SOURCE_DEMUX selects the demultiplexer (fed either by the frontend or the -DVR device) as the source of the video stream. If AUDIO_SOURCE_MEMORY -is selected the stream comes from the application through the <constant>write()</constant> system -call. -</para> - -</section> -<section id="audio-play-state-t"> -<title>audio_play_state_t</title> -<para>The following values can be returned by the AUDIO_GET_STATUS call representing the -state of audio playback. -</para> -<programlisting> -typedef enum { - AUDIO_STOPPED, - AUDIO_PLAYING, - AUDIO_PAUSED -} audio_play_state_t; -</programlisting> - -</section> -<section id="audio-channel-select-t"> -<title>audio_channel_select_t</title> -<para>The audio channel selected via AUDIO_CHANNEL_SELECT is determined by the -following values. -</para> -<programlisting> -typedef enum { - AUDIO_STEREO, - AUDIO_MONO_LEFT, - AUDIO_MONO_RIGHT, - AUDIO_MONO, - AUDIO_STEREO_SWAPPED -} audio_channel_select_t; -</programlisting> - -</section> -<section id="audio-status"> -<title>struct audio_status</title> -<para>The AUDIO_GET_STATUS call returns the following structure informing about various -states of the playback operation. -</para> -<programlisting> -typedef struct audio_status { - boolean AV_sync_state; - boolean mute_state; - audio_play_state_t play_state; - audio_stream_source_t stream_source; - audio_channel_select_t channel_select; - boolean bypass_mode; - audio_mixer_t mixer_state; -} audio_status_t; -</programlisting> - -</section> -<section id="audio-mixer"> -<title>struct audio_mixer</title> -<para>The following structure is used by the AUDIO_SET_MIXER call to set the audio -volume. -</para> -<programlisting> -typedef struct audio_mixer { - unsigned int volume_left; - unsigned int volume_right; -} audio_mixer_t; -</programlisting> - -</section> -<section id="audio_encodings"> -<title>audio encodings</title> -<para>A call to AUDIO_GET_CAPABILITIES returns an unsigned integer with the following -bits set according to the hardwares capabilities. -</para> -<programlisting> - #define AUDIO_CAP_DTS 1 - #define AUDIO_CAP_LPCM 2 - #define AUDIO_CAP_MP1 4 - #define AUDIO_CAP_MP2 8 - #define AUDIO_CAP_MP3 16 - #define AUDIO_CAP_AAC 32 - #define AUDIO_CAP_OGG 64 - #define AUDIO_CAP_SDDS 128 - #define AUDIO_CAP_AC3 256 -</programlisting> - -</section> -<section id="audio-karaoke"> -<title>struct audio_karaoke</title> -<para>The ioctl AUDIO_SET_KARAOKE uses the following format: -</para> -<programlisting> -typedef -struct audio_karaoke { - int vocal1; - int vocal2; - int melody; -} audio_karaoke_t; -</programlisting> -<para>If Vocal1 or Vocal2 are non-zero, they get mixed into left and right t at 70% each. If both, -Vocal1 and Vocal2 are non-zero, Vocal1 gets mixed into the left channel and Vocal2 into the -right channel at 100% each. Ff Melody is non-zero, the melody channel gets mixed into left -and right. -</para> - -</section> -<section id="audio-attributes-t"> -<title>audio attributes</title> -<para>The following attributes can be set by a call to AUDIO_SET_ATTRIBUTES: -</para> -<programlisting> - typedef uint16_t audio_attributes_t; - /⋆ bits: descr. ⋆/ - /⋆ 15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, ⋆/ - /⋆ 12 multichannel extension ⋆/ - /⋆ 11-10 audio type (0=not spec, 1=language included) ⋆/ - /⋆ 9- 8 audio application mode (0=not spec, 1=karaoke, 2=surround) ⋆/ - /⋆ 7- 6 Quantization / DRC (mpeg audio: 1=DRC exists)(lpcm: 0=16bit, ⋆/ - /⋆ 5- 4 Sample frequency fs (0=48kHz, 1=96kHz) ⋆/ - /⋆ 2- 0 number of audio channels (n+1 channels) ⋆/ -</programlisting> - </section></section> -<section id="audio_function_calls"> -<title>Audio Function Calls</title> - - -<section id="audio_fopen"> -<title>open()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This system call opens a named audio device (e.g. /dev/dvb/adapter0/audio0) - for subsequent use. When an open() call has succeeded, the device will be ready - for use. The significance of blocking or non-blocking mode is described in the - documentation for functions where there is a difference. It does not affect the - semantics of the open() call itself. A device opened in blocking mode can later - be put into non-blocking mode (and vice versa) using the F_SETFL command - of the fcntl system call. This is a standard system call, documented in the Linux - manual page for fcntl. Only one user can open the Audio Device in O_RDWR - mode. All other attempts to open the device in this mode will fail, and an error - code will be returned. If the Audio Device is opened in O_RDONLY mode, the - only ioctl call that can be used is AUDIO_GET_STATUS. All other call will - return with an error code.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int open(const char ⋆deviceName, int flags);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>const char - *deviceName</para> -</entry><entry - align="char"> -<para>Name of specific audio device.</para> -</entry> - </row><row><entry - align="char"> -<para>int flags</para> -</entry><entry - align="char"> -<para>A bit-wise OR of the following flags:</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_RDONLY read-only access</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_RDWR read/write access</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_NONBLOCK open in non-blocking mode</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>(blocking mode is the default)</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURN VALUE</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>ENODEV</para> -</entry><entry - align="char"> -<para>Device driver not loaded/available.</para> -</entry> - </row><row><entry - align="char"> -<para>EBUSY</para> -</entry><entry - align="char"> -<para>Device or resource busy.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Invalid argument.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section> -<section id="audio_fclose"> -<title>close()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This system call closes a previously opened audio device.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int close(int fd);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURN VALUE</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section> -<section id="audio_fwrite"> -<title>write()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This system call can only be used if AUDIO_SOURCE_MEMORY is selected - in the ioctl call AUDIO_SELECT_SOURCE. The data provided shall be in - PES format. If O_NONBLOCK is not specified the function will block until - buffer space is available. The amount of data to be transferred is implied by - count.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>size_t write(int fd, const void ⋆buf, size_t count);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>void *buf</para> -</entry><entry - align="char"> -<para>Pointer to the buffer containing the PES data.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t count</para> -</entry><entry - align="char"> -<para>Size of buf.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURN VALUE</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EPERM</para> -</entry><entry - align="char"> -<para>Mode AUDIO_SOURCE_MEMORY not selected.</para> -</entry> - </row><row><entry - align="char"> -<para>ENOMEM</para> -</entry><entry - align="char"> -<para>Attempted to write more data than the internal buffer can - hold.</para> -</entry> - </row><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section id="AUDIO_STOP" -role="subsection"><title>AUDIO_STOP</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Audio Device to stop playing the current stream.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = AUDIO_STOP);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_STOP for this command.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="AUDIO_PLAY" -role="subsection"><title>AUDIO_PLAY</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Audio Device to start playing an audio stream from the - selected source.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = AUDIO_PLAY);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_PLAY for this command.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="AUDIO_PAUSE" -role="subsection"><title>AUDIO_PAUSE</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call suspends the audio stream being played. Decoding and playing - are paused. It is then possible to restart again decoding and playing process of - the audio stream using AUDIO_CONTINUE command.</para> -</entry> - </row><row><entry - align="char"> -<para>If AUDIO_SOURCE_MEMORY is selected in the ioctl call - AUDIO_SELECT_SOURCE, the DVB-subsystem will not decode (consume) - any more data until the ioctl call AUDIO_CONTINUE or AUDIO_PLAY is - performed.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = AUDIO_PAUSE);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_PAUSE for this command.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="AUDIO_CONTINUE" -role="subsection"><title>AUDIO_CONTINUE</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl restarts the decoding and playing process previously paused -with AUDIO_PAUSE command.</para> -</entry> - </row><row><entry - align="char"> -<para>It only works if the stream were previously stopped with AUDIO_PAUSE</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = AUDIO_CONTINUE);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_CONTINUE for this command.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="AUDIO_SELECT_SOURCE" -role="subsection"><title>AUDIO_SELECT_SOURCE</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call informs the audio device which source shall be used - for the input data. The possible sources are demux or memory. If - AUDIO_SOURCE_MEMORY is selected, the data is fed to the Audio Device - through the write command.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = AUDIO_SELECT_SOURCE, - audio_stream_source_t source);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_SELECT_SOURCE for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>audio_stream_source_t - source</para> -</entry><entry - align="char"> -<para>Indicates the source that shall be used for the Audio - stream.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="AUDIO_SET_MUTE" -role="subsection"><title>AUDIO_SET_MUTE</title> -<para>DESCRIPTION -</para> -<para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2 -&VIDIOC-DECODER-CMD; with the <constant>V4L2_DEC_CMD_START_MUTE_AUDIO</constant> flag instead.</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the audio device to mute the stream that is currently being - played.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = AUDIO_SET_MUTE, - boolean state);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_SET_MUTE for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>boolean state</para> -</entry><entry - align="char"> -<para>Indicates if audio device shall mute or not.</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>TRUE Audio Mute</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>FALSE Audio Un-mute</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="AUDIO_SET_AV_SYNC" -role="subsection"><title>AUDIO_SET_AV_SYNC</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Audio Device to turn ON or OFF A/V synchronization.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = AUDIO_SET_AV_SYNC, - boolean state);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_AV_SYNC for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>boolean state</para> -</entry><entry - align="char"> -<para>Tells the DVB subsystem if A/V synchronization shall be - ON or OFF.</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>TRUE AV-sync ON</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>FALSE AV-sync OFF</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="AUDIO_SET_BYPASS_MODE" -role="subsection"><title>AUDIO_SET_BYPASS_MODE</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Audio Device to bypass the Audio decoder and forward - the stream without decoding. This mode shall be used if streams that can’t be - handled by the DVB system shall be decoded. Dolby DigitalTM streams are - automatically forwarded by the DVB subsystem if the hardware can handle it.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = - AUDIO_SET_BYPASS_MODE, boolean mode);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_SET_BYPASS_MODE for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>boolean mode</para> -</entry><entry - align="char"> -<para>Enables or disables the decoding of the current Audio - stream in the DVB subsystem.</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>TRUE Bypass is disabled</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>FALSE Bypass is enabled</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="AUDIO_CHANNEL_SELECT" -role="subsection"><title>AUDIO_CHANNEL_SELECT</title> -<para>DESCRIPTION -</para> -<para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2 -<constant>V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK</constant> control instead.</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Audio Device to select the requested channel if possible.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = - AUDIO_CHANNEL_SELECT, audio_channel_select_t);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_CHANNEL_SELECT for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>audio_channel_select_t - ch</para> -</entry><entry - align="char"> -<para>Select the output format of the audio (mono left/right, - stereo).</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="AUDIO_BILINGUAL_CHANNEL_SELECT" -role="subsection"><title>AUDIO_BILINGUAL_CHANNEL_SELECT</title> -<para>DESCRIPTION -</para> -<para>This ioctl is obsolete. Do not use in new drivers. It has been replaced by -the V4L2 <constant>V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK</constant> control -for MPEG decoders controlled through V4L2.</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Audio Device to select the requested channel for bilingual streams if possible.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = - AUDIO_BILINGUAL_CHANNEL_SELECT, audio_channel_select_t);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_BILINGUAL_CHANNEL_SELECT for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>audio_channel_select_t -ch</para> -</entry><entry - align="char"> -<para>Select the output format of the audio (mono left/right, - stereo).</para> -</entry> - </row> -</tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="AUDIO_GET_PTS" -role="subsection"><title>AUDIO_GET_PTS</title> -<para>DESCRIPTION -</para> -<para>This ioctl is obsolete. Do not use in new drivers. If you need this functionality, -then please contact the linux-media mailing list (&v4l-ml;).</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Audio Device to return the current PTS timestamp.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = - AUDIO_GET_PTS, __u64 *pts);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_GET_PTS for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>__u64 *pts -</para> -</entry><entry - align="char"> -<para>Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 / ISO/IEC 13818-1. -</para> -<para> -The PTS should belong to the currently played -frame if possible, but may also be a value close to it -like the PTS of the last decoded frame or the last PTS -extracted by the PES parser.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="AUDIO_GET_STATUS" -role="subsection"><title>AUDIO_GET_STATUS</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Audio Device to return the current state of the Audio - Device.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = AUDIO_GET_STATUS, - struct audio_status ⋆status);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_GET_STATUS for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct audio_status - *status</para> -</entry><entry - align="char"> -<para>Returns the current state of Audio Device.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="AUDIO_GET_CAPABILITIES" -role="subsection"><title>AUDIO_GET_CAPABILITIES</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Audio Device to tell us about the decoding capabilities - of the audio hardware.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = - AUDIO_GET_CAPABILITIES, unsigned int ⋆cap);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_GET_CAPABILITIES for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>unsigned int *cap</para> -</entry><entry - align="char"> -<para>Returns a bit array of supported sound formats.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="AUDIO_CLEAR_BUFFER" -role="subsection"><title>AUDIO_CLEAR_BUFFER</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Audio Device to clear all software and hardware buffers - of the audio decoder device.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = AUDIO_CLEAR_BUFFER);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_CLEAR_BUFFER for this command.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="AUDIO_SET_ID" -role="subsection"><title>AUDIO_SET_ID</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl selects which sub-stream is to be decoded if a program or system - stream is sent to the video device. If no audio stream type is set the id has to be - in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for AC3 and in [0xA0,0xA7] - for LPCM. More specifications may follow for other stream types. If the stream - type is set the id just specifies the substream id of the audio stream and only - the first 5 bits are recognized.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = AUDIO_SET_ID, int - id);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_SET_ID for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>int id</para> -</entry><entry - align="char"> -<para>audio sub-stream id</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="AUDIO_SET_MIXER" -role="subsection"><title>AUDIO_SET_MIXER</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl lets you adjust the mixer settings of the audio decoder.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = AUDIO_SET_MIXER, - audio_mixer_t ⋆mix);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_SET_ID for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>audio_mixer_t *mix</para> -</entry><entry - align="char"> -<para>mixer settings.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="AUDIO_SET_STREAMTYPE" -role="subsection"><title>AUDIO_SET_STREAMTYPE</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl tells the driver which kind of audio stream to expect. This is useful - if the stream offers several audio sub-streams like LPCM and AC3.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = AUDIO_SET_STREAMTYPE, - int type);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_SET_STREAMTYPE for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>int type</para> -</entry><entry - align="char"> -<para>stream type</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>type is not a valid or supported stream type.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section id="AUDIO_SET_EXT_ID" -role="subsection"><title>AUDIO_SET_EXT_ID</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl can be used to set the extension id for MPEG streams in DVD - playback. Only the first 3 bits are recognized.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = AUDIO_SET_EXT_ID, int - id);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_SET_EXT_ID for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>int id</para> -</entry><entry - align="char"> -<para>audio sub_stream_id</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>id is not a valid id.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section id="AUDIO_SET_ATTRIBUTES" -role="subsection"><title>AUDIO_SET_ATTRIBUTES</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl is intended for DVD playback and allows you to set certain - information about the audio stream.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = AUDIO_SET_ATTRIBUTES, - audio_attributes_t attr );</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_SET_ATTRIBUTES for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>audio_attributes_t - attr</para> -</entry><entry - align="char"> -<para>audio attributes according to section ??</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>attr is not a valid or supported attribute setting.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section id="AUDIO_SET_KARAOKE" -role="subsection"><title>AUDIO_SET_KARAOKE</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl allows one to set the mixer settings for a karaoke DVD.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = AUDIO_SET_KARAOKE, - audio_karaoke_t ⋆karaoke);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_SET_KARAOKE for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>audio_karaoke_t - *karaoke</para> -</entry><entry - align="char"> -<para>karaoke settings according to section ??.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>karaoke is not a valid or supported karaoke setting.</para> -</entry> - </row></tbody></tgroup></informaltable> - </section> -</section> diff --git a/Documentation/DocBook/media/dvb/ca.xml b/Documentation/DocBook/media/dvb/ca.xml deleted file mode 100644 index d0b07e763908..000000000000 --- a/Documentation/DocBook/media/dvb/ca.xml +++ /dev/null @@ -1,582 +0,0 @@ -<title>DVB CA Device</title> -<para>The DVB CA device controls the conditional access hardware. It can be accessed through -<constant>/dev/dvb/adapter?/ca?</constant>. Data types and and ioctl definitions can be accessed by -including <constant>linux/dvb/ca.h</constant> in your application. -</para> - -<section id="ca_data_types"> -<title>CA Data Types</title> - - -<section id="ca-slot-info"> -<title>ca_slot_info_t</title> - <programlisting> -typedef struct ca_slot_info { - int num; /⋆ slot number ⋆/ - - int type; /⋆ CA interface this slot supports ⋆/ -#define CA_CI 1 /⋆ CI high level interface ⋆/ -#define CA_CI_LINK 2 /⋆ CI link layer level interface ⋆/ -#define CA_CI_PHYS 4 /⋆ CI physical layer level interface ⋆/ -#define CA_DESCR 8 /⋆ built-in descrambler ⋆/ -#define CA_SC 128 /⋆ simple smart card interface ⋆/ - - unsigned int flags; -#define CA_CI_MODULE_PRESENT 1 /⋆ module (or card) inserted ⋆/ -#define CA_CI_MODULE_READY 2 -} ca_slot_info_t; -</programlisting> - -</section> -<section id="ca-descr-info"> -<title>ca_descr_info_t</title> -<programlisting> -typedef struct ca_descr_info { - unsigned int num; /⋆ number of available descramblers (keys) ⋆/ - unsigned int type; /⋆ type of supported scrambling system ⋆/ -#define CA_ECD 1 -#define CA_NDS 2 -#define CA_DSS 4 -} ca_descr_info_t; -</programlisting> - -</section> -<section id="ca-caps"> -<title>ca_caps_t</title> -<programlisting> -typedef struct ca_caps { - unsigned int slot_num; /⋆ total number of CA card and module slots ⋆/ - unsigned int slot_type; /⋆ OR of all supported types ⋆/ - unsigned int descr_num; /⋆ total number of descrambler slots (keys) ⋆/ - unsigned int descr_type;/⋆ OR of all supported types ⋆/ - } ca_cap_t; -</programlisting> - -</section> -<section id="ca-msg"> -<title>ca_msg_t</title> -<programlisting> -/⋆ a message to/from a CI-CAM ⋆/ -typedef struct ca_msg { - unsigned int index; - unsigned int type; - unsigned int length; - unsigned char msg[256]; -} ca_msg_t; -</programlisting> - -</section> -<section id="ca-descr"> -<title>ca_descr_t</title> -<programlisting> -typedef struct ca_descr { - unsigned int index; - unsigned int parity; - unsigned char cw[8]; -} ca_descr_t; -</programlisting> -</section> - -<section id="ca-pid"> -<title>ca-pid</title> -<programlisting> -typedef struct ca_pid { - unsigned int pid; - int index; /⋆ -1 == disable⋆/ -} ca_pid_t; -</programlisting> -</section></section> - -<section id="ca_function_calls"> -<title>CA Function Calls</title> - - -<section id="ca_fopen"> -<title>open()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This system call opens a named ca device (e.g. /dev/ost/ca) for subsequent use.</para> -<para>When an open() call has succeeded, the device will be ready for use. - The significance of blocking or non-blocking mode is described in the - documentation for functions where there is a difference. It does not affect the - semantics of the open() call itself. A device opened in blocking mode can later - be put into non-blocking mode (and vice versa) using the F_SETFL command - of the fcntl system call. This is a standard system call, documented in the Linux - manual page for fcntl. Only one user can open the CA Device in O_RDWR - mode. All other attempts to open the device in this mode will fail, and an error - code will be returned.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int open(const char ⋆deviceName, int flags);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>const char - *deviceName</para> -</entry><entry - align="char"> -<para>Name of specific video device.</para> -</entry> - </row><row><entry - align="char"> -<para>int flags</para> -</entry><entry - align="char"> -<para>A bit-wise OR of the following flags:</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_RDONLY read-only access</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_RDWR read/write access</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_NONBLOCK open in non-blocking mode</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>(blocking mode is the default)</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURN VALUE</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>ENODEV</para> -</entry><entry - align="char"> -<para>Device driver not loaded/available.</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error.</para> -</entry> - </row><row><entry - align="char"> -<para>EBUSY</para> -</entry><entry - align="char"> -<para>Device or resource busy.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Invalid argument.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section> -<section id="ca_fclose"> -<title>close()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This system call closes a previously opened audio device.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int close(int fd);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURN VALUE</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row></tbody></tgroup></informaltable> - </section> - -<section id="CA_RESET" -role="subsection"><title>CA_RESET</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl is undocumented. Documentation is welcome.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = CA_RESET); -</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals CA_RESET for this command.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -</section> - -<section id="CA_GET_CAP" -role="subsection"><title>CA_GET_CAP</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl is undocumented. Documentation is welcome.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = CA_GET_CAP, - ca_caps_t *);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals CA_GET_CAP for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>ca_caps_t * -</para> -</entry><entry - align="char"> -<para>Undocumented.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -</section> - -<section id="CA_GET_SLOT_INFO" -role="subsection"><title>CA_GET_SLOT_INFO</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl is undocumented. Documentation is welcome.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = CA_GET_SLOT_INFO, - ca_slot_info_t *);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals CA_GET_SLOT_INFO for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>ca_slot_info_t * -</para> -</entry><entry - align="char"> -<para>Undocumented.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -</section> - -<section id="CA_GET_DESCR_INFO" -role="subsection"><title>CA_GET_DESCR_INFO</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl is undocumented. Documentation is welcome.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = CA_GET_DESCR_INFO, - ca_descr_info_t *);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals CA_GET_DESCR_INFO for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>ca_descr_info_t * -</para> -</entry><entry - align="char"> -<para>Undocumented.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -</section> - -<section id="CA_GET_MSG" -role="subsection"><title>CA_GET_MSG</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl is undocumented. Documentation is welcome.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = CA_GET_MSG, - ca_msg_t *);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals CA_GET_MSG for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>ca_msg_t * -</para> -</entry><entry - align="char"> -<para>Undocumented.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -</section> - -<section id="CA_SEND_MSG" -role="subsection"><title>CA_SEND_MSG</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl is undocumented. Documentation is welcome.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = CA_SEND_MSG, - ca_msg_t *);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals CA_SEND_MSG for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>ca_msg_t * -</para> -</entry><entry - align="char"> -<para>Undocumented.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -</section> - -<section id="CA_SET_DESCR" -role="subsection"><title>CA_SET_DESCR</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl is undocumented. Documentation is welcome.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = CA_SET_DESCR, - ca_descr_t *);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals CA_SET_DESCR for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>ca_descr_t * -</para> -</entry><entry - align="char"> -<para>Undocumented.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -</section> - -<section id="CA_SET_PID" -role="subsection"><title>CA_SET_PID</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl is undocumented. Documentation is welcome.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = CA_SET_PID, - ca_pid_t *);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals CA_SET_PID for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>ca_pid_t * -</para> -</entry><entry - align="char"> -<para>Undocumented.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -</section> - -</section> diff --git a/Documentation/DocBook/media/dvb/demux.xml b/Documentation/DocBook/media/dvb/demux.xml deleted file mode 100644 index 34f2fb1cd601..000000000000 --- a/Documentation/DocBook/media/dvb/demux.xml +++ /dev/null @@ -1,1162 +0,0 @@ -<title>DVB Demux Device</title> - -<para>The DVB demux device controls the filters of the DVB hardware/software. It can be -accessed through <constant>/dev/adapter?/demux?</constant>. Data types and and ioctl definitions can be -accessed by including <constant>linux/dvb/dmx.h</constant> in your application. -</para> -<section id="dmx_types"> -<title>Demux Data Types</title> - -<section id="dmx-output-t"> -<title>Output for the demux</title> - -<table pgwide="1" frame="none" id="dmx-output"> - <title>enum dmx_output</title> - <tgroup cols="2"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry align="char" id="DMX-OUT-DECODER">DMX_OUT_DECODER</entry> - <entry>Streaming directly to decoder.</entry> - </row><row> - <entry align="char" id="DMX-OUT-TAP">DMX_OUT_TAP</entry> - <entry>Output going to a memory buffer (to be retrieved via the - read command). Delivers the stream output to the demux - device on which the ioctl is called.</entry> - </row><row> - <entry align="char" id="DMX-OUT-TS-TAP">DMX_OUT_TS_TAP</entry> - <entry>Output multiplexed into a new TS (to be retrieved by - reading from the logical DVR device). Routes output to the - logical DVR device <constant>/dev/dvb/adapter?/dvr?</constant>, - which delivers a TS multiplexed from all filters for which - <constant>DMX_OUT_TS_TAP</constant> was specified.</entry> - </row><row> - <entry align="char" id="DMX-OUT-TSDEMUX-TAP">DMX_OUT_TSDEMUX_TAP</entry> - <entry>Like &DMX-OUT-TS-TAP; but retrieved from the DMX - device.</entry> - </row> - </tbody> - </tgroup> -</table> - -</section> - -<section id="dmx-input-t"> -<title>dmx_input_t</title> -<programlisting> -typedef enum -{ - DMX_IN_FRONTEND, /⋆ Input from a front-end device. ⋆/ - DMX_IN_DVR /⋆ Input from the logical DVR device. ⋆/ -} dmx_input_t; -</programlisting> -</section> - -<section id="dmx-pes-type-t"> -<title>dmx_pes_type_t</title> -<programlisting> -typedef enum -{ - DMX_PES_AUDIO0, - DMX_PES_VIDEO0, - DMX_PES_TELETEXT0, - DMX_PES_SUBTITLE0, - DMX_PES_PCR0, - - DMX_PES_AUDIO1, - DMX_PES_VIDEO1, - DMX_PES_TELETEXT1, - DMX_PES_SUBTITLE1, - DMX_PES_PCR1, - - DMX_PES_AUDIO2, - DMX_PES_VIDEO2, - DMX_PES_TELETEXT2, - DMX_PES_SUBTITLE2, - DMX_PES_PCR2, - - DMX_PES_AUDIO3, - DMX_PES_VIDEO3, - DMX_PES_TELETEXT3, - DMX_PES_SUBTITLE3, - DMX_PES_PCR3, - - DMX_PES_OTHER -} dmx_pes_type_t; -</programlisting> -</section> - -<section id="dmx-filter"> -<title>struct dmx_filter</title> - <programlisting> - typedef struct dmx_filter -{ - __u8 filter[DMX_FILTER_SIZE]; - __u8 mask[DMX_FILTER_SIZE]; - __u8 mode[DMX_FILTER_SIZE]; -} dmx_filter_t; -</programlisting> -</section> - -<section id="dmx-sct-filter-params"> -<title>struct dmx_sct_filter_params</title> -<programlisting> -struct dmx_sct_filter_params -{ - __u16 pid; - dmx_filter_t filter; - __u32 timeout; - __u32 flags; -#define DMX_CHECK_CRC 1 -#define DMX_ONESHOT 2 -#define DMX_IMMEDIATE_START 4 -#define DMX_KERNEL_CLIENT 0x8000 -}; -</programlisting> -</section> - -<section id="dmx-pes-filter-params"> -<title>struct dmx_pes_filter_params</title> -<programlisting> -struct dmx_pes_filter_params -{ - __u16 pid; - dmx_input_t input; - dmx_output_t output; - dmx_pes_type_t pes_type; - __u32 flags; -}; -</programlisting> -</section> - -<section id="dmx-event"> -<title>struct dmx_event</title> - <programlisting> - struct dmx_event - { - dmx_event_t event; - time_t timeStamp; - union - { - dmx_scrambling_status_t scrambling; - } u; - }; -</programlisting> -</section> - -<section id="dmx-stc"> -<title>struct dmx_stc</title> -<programlisting> -struct dmx_stc { - unsigned int num; /⋆ input : which STC? 0..N ⋆/ - unsigned int base; /⋆ output: divisor for stc to get 90 kHz clock ⋆/ - __u64 stc; /⋆ output: stc in 'base'⋆90 kHz units ⋆/ -}; -</programlisting> -</section> - -<section id="dmx-caps"> -<title>struct dmx_caps</title> -<programlisting> - typedef struct dmx_caps { - __u32 caps; - int num_decoders; -} dmx_caps_t; -</programlisting> -</section> - -<section id="dmx-source-t"> -<title>enum dmx_source_t</title> -<programlisting> -typedef enum { - DMX_SOURCE_FRONT0 = 0, - DMX_SOURCE_FRONT1, - DMX_SOURCE_FRONT2, - DMX_SOURCE_FRONT3, - DMX_SOURCE_DVR0 = 16, - DMX_SOURCE_DVR1, - DMX_SOURCE_DVR2, - DMX_SOURCE_DVR3 -} dmx_source_t; -</programlisting> -</section> - -</section> -<section id="dmx_fcalls"> -<title>Demux Function Calls</title> - -<section id="dmx_fopen"> -<title>open()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This system call, used with a device name of /dev/dvb/adapter0/demux0, - allocates a new filter and returns a handle which can be used for subsequent - control of that filter. This call has to be made for each filter to be used, i.e. every - returned file descriptor is a reference to a single filter. /dev/dvb/adapter0/dvr0 - is a logical device to be used for retrieving Transport Streams for digital - video recording. When reading from this device a transport stream containing - the packets from all PES filters set in the corresponding demux device - (/dev/dvb/adapter0/demux0) having the output set to DMX_OUT_TS_TAP. A - recorded Transport Stream is replayed by writing to this device. </para> -<para>The significance of blocking or non-blocking mode is described in the - documentation for functions where there is a difference. It does not affect the - semantics of the open() call itself. A device opened in blocking mode can later - be put into non-blocking mode (and vice versa) using the F_SETFL command - of the fcntl system call.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int open(const char ⋆deviceName, int flags);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>const char - *deviceName</para> -</entry><entry - align="char"> -<para>Name of demux device.</para> -</entry> - </row><row><entry - align="char"> -<para>int flags</para> -</entry><entry - align="char"> -<para>A bit-wise OR of the following flags:</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_RDWR read/write access</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_NONBLOCK open in non-blocking mode</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>(blocking mode is the default)</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURN VALUE</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>ENODEV</para> -</entry><entry - align="char"> -<para>Device driver not loaded/available.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Invalid argument.</para> -</entry> - </row><row><entry - align="char"> -<para>EMFILE</para> -</entry><entry - align="char"> -<para>“Too many open files”, i.e. no more filters available.</para> -</entry> - </row><row><entry - align="char"> -<para>ENOMEM</para> -</entry><entry - align="char"> -<para>The driver failed to allocate enough memory.</para> -</entry> - </row></tbody></tgroup></informaltable> -</section> - -<section id="dmx_fclose"> -<title>close()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This system call deactivates and deallocates a filter that was previously - allocated via the open() call.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int close(int fd);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURN VALUE</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row></tbody></tgroup></informaltable> -</section> - -<section id="dmx_fread"> -<title>read()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This system call returns filtered data, which might be section or PES data. The - filtered data is transferred from the driver’s internal circular buffer to buf. The - maximum amount of data to be transferred is implied by count.</para> -</entry> - </row><row><entry - align="char"> -<para>When returning section data the driver always tries to return a complete single - section (even though buf would provide buffer space for more data). If the size - of the buffer is smaller than the section as much as possible will be returned, - and the remaining data will be provided in subsequent calls.</para> -</entry> - </row><row><entry - align="char"> -<para>The size of the internal buffer is 2 * 4096 bytes (the size of two maximum - sized sections) by default. The size of this buffer may be changed by using the - DMX_SET_BUFFER_SIZE function. If the buffer is not large enough, or if - the read operations are not performed fast enough, this may result in a buffer - overflow error. In this case EOVERFLOW will be returned, and the circular - buffer will be emptied. This call is blocking if there is no data to return, i.e. the - process will be put to sleep waiting for data, unless the O_NONBLOCK flag - is specified.</para> -</entry> - </row><row><entry - align="char"> -<para>Note that in order to be able to read, the filtering process has to be started - by defining either a section or a PES filter by means of the ioctl functions, - and then starting the filtering process via the DMX_START ioctl function - or by setting the DMX_IMMEDIATE_START flag. If the reading is done - from a logical DVR demux device, the data will constitute a Transport Stream - including the packets from all PES filters in the corresponding demux device - /dev/dvb/adapter0/demux0 having the output set to DMX_OUT_TS_TAP.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>size_t read(int fd, void ⋆buf, size_t count);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>void *buf</para> -</entry><entry - align="char"> -<para>Pointer to the buffer to be used for returned filtered data.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t count</para> -</entry><entry - align="char"> -<para>Size of buf.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURN VALUE</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EWOULDBLOCK</para> -</entry><entry - align="char"> -<para>No data to return and O_NONBLOCK was specified.</para> -</entry> - </row><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>ECRC</para> -</entry><entry - align="char"> -<para>Last section had a CRC error - no data returned. The - buffer is flushed.</para> -</entry> - </row><row><entry - align="char"> -<para>EOVERFLOW</para> -</entry><entry - align="char"> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>The filtered data was not read from the buffer in due - time, resulting in non-read data being lost. The buffer is - flushed.</para> -</entry> - </row><row><entry - align="char"> -<para>ETIMEDOUT</para> -</entry><entry - align="char"> -<para>The section was not loaded within the stated timeout - period. See ioctl DMX_SET_FILTER for how to set a - timeout.</para> -</entry> - </row><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>The driver failed to write to the callers buffer due to an - invalid *buf pointer.</para> -</entry> - </row></tbody></tgroup></informaltable> -</section> - -<section id="dmx_fwrite"> -<title>write()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This system call is only provided by the logical device /dev/dvb/adapter0/dvr0, - associated with the physical demux device that provides the actual DVR - functionality. It is used for replay of a digitally recorded Transport Stream. - Matching filters have to be defined in the corresponding physical demux - device, /dev/dvb/adapter0/demux0. The amount of data to be transferred is - implied by count.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>ssize_t write(int fd, const void ⋆buf, size_t - count);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>void *buf</para> -</entry><entry - align="char"> -<para>Pointer to the buffer containing the Transport Stream.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t count</para> -</entry><entry - align="char"> -<para>Size of buf.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURN VALUE</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EWOULDBLOCK</para> -</entry><entry - align="char"> -<para>No data was written. This - might happen if O_NONBLOCK was specified and there - is no more buffer space available (if O_NONBLOCK is - not specified the function will block until buffer space is - available).</para> -</entry> - </row><row><entry - align="char"> -<para>EBUSY</para> -</entry><entry - align="char"> -<para>This error code indicates that there are conflicting - requests. The corresponding demux device is setup to - receive data from the front- end. Make sure that these - filters are stopped and that the filters with input set to - DMX_IN_DVR are started.</para> -</entry> - </row><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row></tbody></tgroup></informaltable> -</section> - -<section id="DMX_START"> -<title>DMX_START</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call is used to start the actual filtering operation defined via the ioctl - calls DMX_SET_FILTER or DMX_SET_PES_FILTER.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl( int fd, int request = DMX_START);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals DMX_START for this command.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Invalid argument, i.e. no filtering parameters provided via - the DMX_SET_FILTER or DMX_SET_PES_FILTER - functions.</para> -</entry> - </row><row><entry - align="char"> -<para>EBUSY</para> -</entry><entry - align="char"> -<para>This error code indicates that there are conflicting - requests. There are active filters filtering data from - another input source. Make sure that these filters are - stopped before starting this filter.</para> -</entry> - </row></tbody></tgroup></informaltable> -</section> - -<section id="DMX_STOP"> -<title>DMX_STOP</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call is used to stop the actual filtering operation defined via the - ioctl calls DMX_SET_FILTER or DMX_SET_PES_FILTER and started via - the DMX_START command.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl( int fd, int request = DMX_STOP);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals DMX_STOP for this command.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -</section> - -<section id="DMX_SET_FILTER"> -<title>DMX_SET_FILTER</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call sets up a filter according to the filter and mask parameters - provided. A timeout may be defined stating number of seconds to wait for a - section to be loaded. A value of 0 means that no timeout should be applied. - Finally there is a flag field where it is possible to state whether a section should - be CRC-checked, whether the filter should be a ”one-shot” filter, i.e. if the - filtering operation should be stopped after the first section is received, and - whether the filtering operation should be started immediately (without waiting - for a DMX_START ioctl call). If a filter was previously set-up, this filter will - be canceled, and the receive buffer will be flushed.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl( int fd, int request = DMX_SET_FILTER, - struct dmx_sct_filter_params ⋆params);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals DMX_SET_FILTER for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct - dmx_sct_filter_params - *params</para> -</entry><entry - align="char"> -<para>Pointer to structure containing filter parameters.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -</section> - -<section id="DMX_SET_PES_FILTER"> -<title>DMX_SET_PES_FILTER</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call sets up a PES filter according to the parameters provided. By a - PES filter is meant a filter that is based just on the packet identifier (PID), i.e. - no PES header or payload filtering capability is supported.</para> -</entry> - </row><row><entry - align="char"> -<para>The transport stream destination for the filtered output may be set. Also the - PES type may be stated in order to be able to e.g. direct a video stream directly - to the video decoder. Finally there is a flag field where it is possible to state - whether the filtering operation should be started immediately (without waiting - for a DMX_START ioctl call). If a filter was previously set-up, this filter will - be cancelled, and the receive buffer will be flushed.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl( int fd, int request = DMX_SET_PES_FILTER, - struct dmx_pes_filter_params ⋆params);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals DMX_SET_PES_FILTER for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct - dmx_pes_filter_params - *params</para> -</entry><entry - align="char"> -<para>Pointer to structure containing filter parameters.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBUSY</para> -</entry><entry - align="char"> -<para>This error code indicates that there are conflicting - requests. There are active filters filtering data from - another input source. Make sure that these filters are - stopped before starting this filter.</para> -</entry> - </row></tbody></tgroup></informaltable> -</section> - -<section id="DMX_SET_BUFFER_SIZE"> -<title>DMX_SET_BUFFER_SIZE</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call is used to set the size of the circular buffer used for filtered data. - The default size is two maximum sized sections, i.e. if this function is not called - a buffer size of 2 * 4096 bytes will be used.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl( int fd, int request = - DMX_SET_BUFFER_SIZE, unsigned long size);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals DMX_SET_BUFFER_SIZE for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>unsigned long size</para> -</entry><entry - align="char"> -<para>Size of circular buffer.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -</section> - -<section id="DMX_GET_EVENT"> -<title>DMX_GET_EVENT</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call returns an event if available. If an event is not available, - the behavior depends on whether the device is in blocking or non-blocking - mode. In the latter case, the call fails immediately with errno set to - EWOULDBLOCK. In the former case, the call blocks until an event becomes - available.</para> -</entry> - </row><row><entry - align="char"> -<para>The standard Linux poll() and/or select() system calls can be used with the - device file descriptor to watch for new events. For select(), the file descriptor - should be included in the exceptfds argument, and for poll(), POLLPRI should - be specified as the wake-up condition. Only the latest event for each filter is - saved.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl( int fd, int request = DMX_GET_EVENT, - struct dmx_event ⋆ev);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals DMX_GET_EVENT for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct dmx_event *ev</para> -</entry><entry - align="char"> -<para>Pointer to the location where the event is to be stored.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EWOULDBLOCK</para> -</entry><entry - align="char"> -<para>There is no event pending, and the device is in - non-blocking mode.</para> -</entry> - </row></tbody></tgroup></informaltable> -</section> - -<section id="DMX_GET_STC"> -<title>DMX_GET_STC</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call returns the current value of the system time counter (which is driven - by a PES filter of type DMX_PES_PCR). Some hardware supports more than one - STC, so you must specify which one by setting the num field of stc before the ioctl - (range 0...n). The result is returned in form of a ratio with a 64 bit numerator - and a 32 bit denominator, so the real 90kHz STC value is stc->stc / - stc->base - .</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl( int fd, int request = DMX_GET_STC, struct - dmx_stc ⋆stc);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals DMX_GET_STC for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct dmx_stc *stc</para> -</entry><entry - align="char"> -<para>Pointer to the location where the stc is to be stored.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Invalid stc number.</para> -</entry> - </row></tbody></tgroup></informaltable> - </section> - -<section id="DMX_GET_PES_PIDS" -role="subsection"><title>DMX_GET_PES_PIDS</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl is undocumented. Documentation is welcome.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = DMX_GET_PES_PIDS, - __u16[5]);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals DMX_GET_PES_PIDS for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>__u16[5] -</para> -</entry><entry - align="char"> -<para>Undocumented.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -</section> - -<section id="DMX_GET_CAPS" -role="subsection"><title>DMX_GET_CAPS</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl is undocumented. Documentation is welcome.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = DMX_GET_CAPS, - dmx_caps_t *);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals DMX_GET_CAPS for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_caps_t * -</para> -</entry><entry - align="char"> -<para>Undocumented.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -</section> - -<section id="DMX_SET_SOURCE" -role="subsection"><title>DMX_SET_SOURCE</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl is undocumented. Documentation is welcome.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = DMX_SET_SOURCE, - dmx_source_t *);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals DMX_SET_SOURCE for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_source_t * -</para> -</entry><entry - align="char"> -<para>Undocumented.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -</section> - -<section id="DMX_ADD_PID" -role="subsection"><title>DMX_ADD_PID</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call allows to add multiple PIDs to a transport stream filter -previously set up with DMX_SET_PES_FILTER and output equal to DMX_OUT_TSDEMUX_TAP. -</para></entry></row><row><entry align="char"><para> -It is used by readers of /dev/dvb/adapterX/demuxY. -</para></entry></row><row><entry align="char"><para> -It may be called at any time, i.e. before or after the first filter on the -shared file descriptor was started. It makes it possible to record multiple -services without the need to de-multiplex or re-multiplex TS packets.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = DMX_ADD_PID, - __u16 *);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals DMX_ADD_PID for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>__u16 * -</para> -</entry><entry - align="char"> -<para>PID number to be filtered.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -</section> - -<section id="DMX_REMOVE_PID" -role="subsection"><title>DMX_REMOVE_PID</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call allows to remove a PID when multiple PIDs are set on a -transport stream filter, e. g. a filter previously set up with output equal to -DMX_OUT_TSDEMUX_TAP, created via either DMX_SET_PES_FILTER or DMX_ADD_PID. -</para></entry></row><row><entry align="char"><para> -It is used by readers of /dev/dvb/adapterX/demuxY. -</para></entry></row><row><entry align="char"><para> -It may be called at any time, i.e. before or after the first filter on the -shared file descriptor was started. It makes it possible to record multiple -services without the need to de-multiplex or re-multiplex TS packets.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = DMX_REMOVE_PID, - __u16 *);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals DMX_REMOVE_PID for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>__u16 * -</para> -</entry><entry - align="char"> -<para>PID of the PES filter to be removed.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -</section> - - -</section> diff --git a/Documentation/DocBook/media/dvb/dvbapi.xml b/Documentation/DocBook/media/dvb/dvbapi.xml deleted file mode 100644 index 8576481e20ae..000000000000 --- a/Documentation/DocBook/media/dvb/dvbapi.xml +++ /dev/null @@ -1,156 +0,0 @@ -<partinfo> -<authorgroup> -<author> -<firstname>Ralph</firstname> -<surname>Metzler</surname> -<othername role="mi">J. K.</othername> -<affiliation><address><email>rjkm@metzlerbros.de</email></address></affiliation> -</author> -<author> -<firstname>Marcus</firstname> -<surname>Metzler</surname> -<othername role="mi">O. C.</othername> -<affiliation><address><email>rjkm@metzlerbros.de</email></address></affiliation> -</author> -</authorgroup> -<authorgroup> -<author> -<firstname>Mauro</firstname> -<othername role="mi">Carvalho</othername> -<surname>Chehab</surname> -<affiliation><address><email>m.chehab@samsung.com</email></address></affiliation> -<contrib>Ported document to Docbook XML.</contrib> -</author> -</authorgroup> -<copyright> - <year>2002</year> - <year>2003</year> - <holder>Convergence GmbH</holder> -</copyright> -<copyright> - <year>2009-2015</year> - <holder>Mauro Carvalho Chehab</holder> -</copyright> - -<revhistory> -<!-- Put document revisions here, newest first. --> -<revision> - <revnumber>2.1.0</revnumber> - <date>2015-05-29</date> - <authorinitials>mcc</authorinitials> - <revremark> - DocBook improvements and cleanups, in order to document the - system calls on a more standard way and provide more description - about the current DVB API. - </revremark> -</revision> -<revision> - <revnumber>2.0.4</revnumber> - <date>2011-05-06</date> - <authorinitials>mcc</authorinitials> - <revremark> - Add more information about DVB APIv5, better describing the frontend GET/SET props ioctl's. - </revremark> -</revision> -<revision> - <revnumber>2.0.3</revnumber> - <date>2010-07-03</date> - <authorinitials>mcc</authorinitials> - <revremark> - Add some frontend capabilities flags, present on kernel, but missing at the specs. - </revremark> -</revision> -<revision> - <revnumber>2.0.2</revnumber> - <date>2009-10-25</date> - <authorinitials>mcc</authorinitials> - <revremark> - documents FE_SET_FRONTEND_TUNE_MODE and FE_DISHETWORK_SEND_LEGACY_CMD ioctls. - </revremark> -</revision> -<revision> -<revnumber>2.0.1</revnumber> -<date>2009-09-16</date> -<authorinitials>mcc</authorinitials> -<revremark> -Added ISDB-T test originally written by Patrick Boettcher -</revremark> -</revision> -<revision> -<revnumber>2.0.0</revnumber> -<date>2009-09-06</date> -<authorinitials>mcc</authorinitials> -<revremark>Conversion from LaTex to DocBook XML. The - contents is the same as the original LaTex version.</revremark> -</revision> -<revision> -<revnumber>1.0.0</revnumber> -<date>2003-07-24</date> -<authorinitials>rjkm</authorinitials> -<revremark>Initial revision on LaTEX.</revremark> -</revision> -</revhistory> -</partinfo> - - -<title>LINUX DVB API</title> -<subtitle>Version 5.10</subtitle> -<!-- ADD THE CHAPTERS HERE --> - <chapter id="dvb_introdution"> - &sub-intro; - </chapter> - <chapter id="dvb_frontend"> - &sub-frontend; - </chapter> - <chapter id="dvb_demux"> - &sub-demux; - </chapter> - <chapter id="dvb_ca"> - &sub-ca; - </chapter> - <chapter id="net"> - &sub-net; - </chapter> - <chapter id="legacy_dvb_apis"> - <title>DVB Deprecated APIs</title> - <para>The APIs described here are kept only for historical reasons. There's - just one driver for a very legacy hardware that uses this API. No - modern drivers should use it. Instead, audio and video should be using - the V4L2 and ALSA APIs, and the pipelines should be set using the - Media Controller API</para> - <section id="dvb_video"> - &sub-video; - </section> - <section id="dvb_audio"> - &sub-audio; - </section> - </chapter> - <chapter id="dvb_examples"> - &sub-examples; - </chapter> -<!-- END OF CHAPTERS --> - <appendix id="audio_h"> - <title>DVB Audio Header File</title> - &sub-audio-h; - </appendix> - <appendix id="ca_h"> - <title>DVB Conditional Access Header File</title> - &sub-ca-h; - </appendix> - <appendix id="dmx_h"> - <title>DVB Demux Header File</title> - &sub-dmx-h; - </appendix> - <appendix id="frontend_h"> - <title>DVB Frontend Header File</title> - &sub-frontend-h; - </appendix> - <appendix id="net_h"> - <title>DVB Network Header File</title> - &sub-net-h; - </appendix> - <appendix id="video_h"> - <title>DVB Video Header File</title> - &sub-video-h; - </appendix> - diff --git a/Documentation/DocBook/media/dvb/dvbproperty.xml b/Documentation/DocBook/media/dvb/dvbproperty.xml deleted file mode 100644 index e579ae5088ae..000000000000 --- a/Documentation/DocBook/media/dvb/dvbproperty.xml +++ /dev/null @@ -1,1680 +0,0 @@ -<section id="frontend-properties"> -<title>DVB Frontend properties</title> -<para>Tuning into a Digital TV physical channel and starting decoding it - requires changing a set of parameters, in order to control the - tuner, the demodulator, the Linear Low-noise Amplifier (LNA) and to set the - antenna subsystem via Satellite Equipment Control (SEC), on satellite - systems. The actual parameters are specific to each particular digital - TV standards, and may change as the digital TV specs evolves.</para> -<para>In the past, the strategy used was to have a union with the parameters - needed to tune for DVB-S, DVB-C, DVB-T and ATSC delivery systems grouped - there. The problem is that, as the second generation standards appeared, - those structs were not big enough to contain the additional parameters. - Also, the union didn't have any space left to be expanded without breaking - userspace. So, the decision was to deprecate the legacy union/struct based - approach, in favor of a properties set approach.</para> - -<para>NOTE: on Linux DVB API version 3, setting a frontend were done via - <link linkend="dvb-frontend-parameters">struct <constant>dvb_frontend_parameters</constant></link>. - This got replaced on version 5 (also called "S2API", as this API were - added originally_enabled to provide support for DVB-S2), because the old - API has a very limited support to new standards and new hardware. This - section describes the new and recommended way to set the frontend, with - suppports all digital TV delivery systems.</para> - -<para>Example: with the properties based approach, in order to set the tuner - to a DVB-C channel at 651 kHz, modulated with 256-QAM, FEC 3/4 and symbol - rate of 5.217 Mbauds, those properties should be sent to - <link linkend="FE_GET_PROPERTY"><constant>FE_SET_PROPERTY</constant></link> ioctl:</para> - <itemizedlist> - <listitem><para>&DTV-DELIVERY-SYSTEM; = SYS_DVBC_ANNEX_A</para></listitem> - <listitem><para>&DTV-FREQUENCY; = 651000000</para></listitem> - <listitem><para>&DTV-MODULATION; = QAM_256</para></listitem> - <listitem><para>&DTV-INVERSION; = INVERSION_AUTO</para></listitem> - <listitem><para>&DTV-SYMBOL-RATE; = 5217000</para></listitem> - <listitem><para>&DTV-INNER-FEC; = FEC_3_4</para></listitem> - <listitem><para>&DTV-TUNE;</para></listitem> - </itemizedlist> - -<para>The code that would do the above is:</para> -<programlisting> -#include <stdio.h> -#include <fcntl.h> -#include <sys/ioctl.h> -#include <linux/dvb/frontend.h> - -static struct dtv_property props[] = { - { .cmd = DTV_DELIVERY_SYSTEM, .u.data = SYS_DVBC_ANNEX_A }, - { .cmd = DTV_FREQUENCY, .u.data = 651000000 }, - { .cmd = DTV_MODULATION, .u.data = QAM_256 }, - { .cmd = DTV_INVERSION, .u.data = INVERSION_AUTO }, - { .cmd = DTV_SYMBOL_RATE, .u.data = 5217000 }, - { .cmd = DTV_INNER_FEC, .u.data = FEC_3_4 }, - { .cmd = DTV_TUNE } -}; - -static struct dtv_properties dtv_prop = { - .num = 6, .props = props -}; - -int main(void) -{ - int fd = open("/dev/dvb/adapter0/frontend0", O_RDWR); - - if (!fd) { - perror ("open"); - return -1; - } - if (ioctl(fd, FE_SET_PROPERTY, &dtv_prop) == -1) { - perror("ioctl"); - return -1; - } - printf("Frontend set\n"); - return 0; -} -</programlisting> - -<para>NOTE: While it is possible to directly call the Kernel code like the - above example, it is strongly recommended to use - <ulink url="https://linuxtv.org/docs/libdvbv5/index.html">libdvbv5</ulink>, - as it provides abstraction to work with the supported digital TV standards - and provides methods for usual operations like program scanning and to - read/write channel descriptor files.</para> - -<section id="dtv-stats"> -<title>struct <structname>dtv_stats</structname></title> -<programlisting> -struct dtv_stats { - __u8 scale; /* enum fecap_scale_params type */ - union { - __u64 uvalue; /* for counters and relative scales */ - __s64 svalue; /* for 1/1000 dB measures */ - }; -} __packed; -</programlisting> -</section> -<section id="dtv-fe-stats"> -<title>struct <structname>dtv_fe_stats</structname></title> -<programlisting> -#define MAX_DTV_STATS 4 - -struct dtv_fe_stats { - __u8 len; - &dtv-stats; stat[MAX_DTV_STATS]; -} __packed; -</programlisting> -</section> - -<section id="dtv-property"> -<title>struct <structname>dtv_property</structname></title> -<programlisting> -/* Reserved fields should be set to 0 */ - -struct dtv_property { - __u32 cmd; - __u32 reserved[3]; - union { - __u32 data; - &dtv-fe-stats; st; - struct { - __u8 data[32]; - __u32 len; - __u32 reserved1[3]; - void *reserved2; - } buffer; - } u; - int result; -} __attribute__ ((packed)); - -/* num of properties cannot exceed DTV_IOCTL_MAX_MSGS per ioctl */ -#define DTV_IOCTL_MAX_MSGS 64 -</programlisting> -</section> -<section id="dtv-properties"> -<title>struct <structname>dtv_properties</structname></title> -<programlisting> -struct dtv_properties { - __u32 num; - &dtv-property; *props; -}; -</programlisting> -</section> - -<section> - <title>Property types</title> -<para> -On <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY and FE_SET_PROPERTY</link>, -the actual action is determined by the dtv_property cmd/data pairs. With one single ioctl, is possible to -get/set up to 64 properties. The actual meaning of each property is described on the next sections. -</para> - -<para>The available frontend property types are shown on the next section.</para> -</section> - -<section id="fe_property_parameters"> - <title>Digital TV property parameters</title> - <section id="DTV-UNDEFINED"> - <title><constant>DTV_UNDEFINED</constant></title> - <para>Used internally. A GET/SET operation for it won't change or return anything.</para> - </section> - <section id="DTV-TUNE"> - <title><constant>DTV_TUNE</constant></title> - <para>Interpret the cache of data, build either a traditional frontend tunerequest so we can pass validation in the <constant>FE_SET_FRONTEND</constant> ioctl.</para> - </section> - <section id="DTV-CLEAR"> - <title><constant>DTV_CLEAR</constant></title> - <para>Reset a cache of data specific to the frontend here. This does not effect hardware.</para> - </section> - <section id="DTV-FREQUENCY"> - <title><constant>DTV_FREQUENCY</constant></title> - - <para>Central frequency of the channel.</para> - - <para>Notes:</para> - <para>1)For satellite delivery systems, it is measured in kHz. - For the other ones, it is measured in Hz.</para> - <para>2)For ISDB-T, the channels are usually transmitted with an offset of 143kHz. - E.g. a valid frequency could be 474143 kHz. The stepping is bound to the bandwidth of - the channel which is 6MHz.</para> - - <para>3)As in ISDB-Tsb the channel consists of only one or three segments the - frequency step is 429kHz, 3*429 respectively. As for ISDB-T the - central frequency of the channel is expected.</para> - </section> - <section id="DTV-MODULATION"> - <title><constant>DTV_MODULATION</constant></title> -<para>Specifies the frontend modulation type for delivery systems that supports - more than one modulation type. The modulation can be one of the types - defined by &fe-modulation;.</para> - - -<section id="fe-modulation-t"> -<title>Modulation property</title> - -<para>Most of the digital TV standards currently offers more than one possible - modulation (sometimes called as "constellation" on some standards). This - enum contains the values used by the Kernel. Please note that not all - modulations are supported by a given standard.</para> - -<table pgwide="1" frame="none" id="fe-modulation"> - <title>enum fe_modulation</title> - <tgroup cols="2"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry id="QPSK"><constant>QPSK</constant></entry> - <entry>QPSK modulation</entry> - </row><row> - <entry id="QAM-16"><constant>QAM_16</constant></entry> - <entry>16-QAM modulation</entry> - </row><row> - <entry id="QAM-32"><constant>QAM_32</constant></entry> - <entry>32-QAM modulation</entry> - </row><row> - <entry id="QAM-64"><constant>QAM_64</constant></entry> - <entry>64-QAM modulation</entry> - </row><row> - <entry id="QAM-128"><constant>QAM_128</constant></entry> - <entry>128-QAM modulation</entry> - </row><row> - <entry id="QAM-256"><constant>QAM_256</constant></entry> - <entry>256-QAM modulation</entry> - </row><row> - <entry id="QAM-AUTO"><constant>QAM_AUTO</constant></entry> - <entry>Autodetect QAM modulation</entry> - </row><row> - <entry id="VSB-8"><constant>VSB_8</constant></entry> - <entry>8-VSB modulation</entry> - </row><row> - <entry id="VSB-16"><constant>VSB_16</constant></entry> - <entry>16-VSB modulation</entry> - </row><row> - <entry id="PSK-8"><constant>PSK_8</constant></entry> - <entry>8-PSK modulation</entry> - </row><row> - <entry id="APSK-16"><constant>APSK_16</constant></entry> - <entry>16-APSK modulation</entry> - </row><row> - <entry id="APSK-32"><constant>APSK_32</constant></entry> - <entry>32-APSK modulation</entry> - </row><row> - <entry id="DQPSK"><constant>DQPSK</constant></entry> - <entry>DQPSK modulation</entry> - </row><row> - <entry id="QAM-4-NR"><constant>QAM_4_NR</constant></entry> - <entry>4-QAM-NR modulation</entry> - </row> - </tbody> - </tgroup> -</table> -</section> - - </section> - <section id="DTV-BANDWIDTH-HZ"> - <title><constant>DTV_BANDWIDTH_HZ</constant></title> - - <para>Bandwidth for the channel, in HZ.</para> - - <para>Possible values: - <constant>1712000</constant>, - <constant>5000000</constant>, - <constant>6000000</constant>, - <constant>7000000</constant>, - <constant>8000000</constant>, - <constant>10000000</constant>. - </para> - - <para>Notes:</para> - - <para>1) For ISDB-T it should be always 6000000Hz (6MHz)</para> - <para>2) For ISDB-Tsb it can vary depending on the number of connected segments</para> - <para>3) Bandwidth doesn't apply for DVB-C transmissions, as the bandwidth - for DVB-C depends on the symbol rate</para> - <para>4) Bandwidth in ISDB-T is fixed (6MHz) or can be easily derived from - other parameters (DTV_ISDBT_SB_SEGMENT_IDX, - DTV_ISDBT_SB_SEGMENT_COUNT).</para> - <para>5) DVB-T supports 6, 7 and 8MHz.</para> - <para>6) In addition, DVB-T2 supports 1.172, 5 and 10MHz.</para> - </section> - <section id="DTV-INVERSION"> - <title><constant>DTV_INVERSION</constant></title> - - <para>Specifies if the frontend should do spectral inversion or not.</para> - -<section id="fe-spectral-inversion-t"> -<title>enum fe_modulation: Frontend spectral inversion</title> - -<para>This parameter indicates if spectral inversion should be presumed or not. - In the automatic setting (<constant>INVERSION_AUTO</constant>) the hardware - will try to figure out the correct setting by itself. If the hardware - doesn't support, the DVB core will try to lock at the carrier first with - inversion off. If it fails, it will try to enable inversion. -</para> - -<table pgwide="1" frame="none" id="fe-spectral-inversion"> - <title>enum fe_modulation</title> - <tgroup cols="2"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry id="INVERSION-OFF"><constant>INVERSION_OFF</constant></entry> - <entry>Don't do spectral band inversion.</entry> - </row><row> - <entry id="INVERSION-ON"><constant>INVERSION_ON</constant></entry> - <entry>Do spectral band inversion.</entry> - </row><row> - <entry id="INVERSION-AUTO"><constant>INVERSION_AUTO</constant></entry> - <entry>Autodetect spectral band inversion.</entry> - </row> - </tbody> - </tgroup> -</table> -</section> - - </section> - <section id="DTV-DISEQC-MASTER"> - <title><constant>DTV_DISEQC_MASTER</constant></title> - <para>Currently not implemented.</para> - </section> - <section id="DTV-SYMBOL-RATE"> - <title><constant>DTV_SYMBOL_RATE</constant></title> - <para>Digital TV symbol rate, in bauds (symbols/second). Used on cable standards.</para> - </section> - <section id="DTV-INNER-FEC"> - <title><constant>DTV_INNER_FEC</constant></title> - <para>Used cable/satellite transmissions. The acceptable values are: - </para> -<section id="fe-code-rate-t"> -<title>enum fe_code_rate: type of the Forward Error Correction.</title> - -<table pgwide="1" frame="none" id="fe-code-rate"> - <title>enum fe_code_rate</title> - <tgroup cols="2"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry id="FEC-NONE"><constant>FEC_NONE</constant></entry> - <entry>No Forward Error Correction Code</entry> - </row><row> - <entry id="FEC-AUTO"><constant>FEC_AUTO</constant></entry> - <entry>Autodetect Error Correction Code</entry> - </row><row> - <entry id="FEC-1-2"><constant>FEC_1_2</constant></entry> - <entry>Forward Error Correction Code 1/2</entry> - </row><row> - <entry id="FEC-2-3"><constant>FEC_2_3</constant></entry> - <entry>Forward Error Correction Code 2/3</entry> - </row><row> - <entry id="FEC-3-4"><constant>FEC_3_4</constant></entry> - <entry>Forward Error Correction Code 3/4</entry> - </row><row> - <entry id="FEC-4-5"><constant>FEC_4_5</constant></entry> - <entry>Forward Error Correction Code 4/5</entry> - </row><row> - <entry id="FEC-5-6"><constant>FEC_5_6</constant></entry> - <entry>Forward Error Correction Code 5/6</entry> - </row><row> - <entry id="FEC-6-7"><constant>FEC_6_7</constant></entry> - <entry>Forward Error Correction Code 6/7</entry> - </row><row> - <entry id="FEC-7-8"><constant>FEC_7_8</constant></entry> - <entry>Forward Error Correction Code 7/8</entry> - </row><row> - <entry id="FEC-8-9"><constant>FEC_8_9</constant></entry> - <entry>Forward Error Correction Code 8/9</entry> - </row><row> - <entry id="FEC-9-10"><constant>FEC_9_10</constant></entry> - <entry>Forward Error Correction Code 9/10</entry> - </row><row> - <entry id="FEC-2-5"><constant>FEC_2_5</constant></entry> - <entry>Forward Error Correction Code 2/5</entry> - </row><row> - <entry id="FEC-3-5"><constant>FEC_3_5</constant></entry> - <entry>Forward Error Correction Code 3/5</entry> - </row> - </tbody> - </tgroup> -</table> -</section> - </section> - <section id="DTV-VOLTAGE"> - <title><constant>DTV_VOLTAGE</constant></title> - <para>The voltage is usually used with non-DiSEqC capable LNBs to switch - the polarzation (horizontal/vertical). When using DiSEqC epuipment this - voltage has to be switched consistently to the DiSEqC commands as - described in the DiSEqC spec.</para> - -<table pgwide="1" frame="none" id="fe-sec-voltage"> - <title id="fe-sec-voltage-t">enum fe_sec_voltage</title> - <tgroup cols="2"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry align="char" id="SEC-VOLTAGE-13"><constant>SEC_VOLTAGE_13</constant></entry> - <entry align="char">Set DC voltage level to 13V</entry> - </row><row> - <entry align="char" id="SEC-VOLTAGE-18"><constant>SEC_VOLTAGE_18</constant></entry> - <entry align="char">Set DC voltage level to 18V</entry> - </row><row> - <entry align="char" id="SEC-VOLTAGE-OFF"><constant>SEC_VOLTAGE_OFF</constant></entry> - <entry align="char">Don't send any voltage to the antenna</entry> - </row> - </tbody> - </tgroup> -</table> - </section> - <section id="DTV-TONE"> - <title><constant>DTV_TONE</constant></title> - <para>Currently not used.</para> - </section> - <section id="DTV-PILOT"> - <title><constant>DTV_PILOT</constant></title> - <para>Sets DVB-S2 pilot</para> - <section id="fe-pilot-t"> - <title>fe_pilot type</title> -<table pgwide="1" frame="none" id="fe-pilot"> - <title>enum fe_pilot</title> - <tgroup cols="2"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry align="char" id="PILOT-ON"><constant>PILOT_ON</constant></entry> - <entry align="char">Pilot tones enabled</entry> - </row><row> - <entry align="char" id="PILOT-OFF"><constant>PILOT_OFF</constant></entry> - <entry align="char">Pilot tones disabled</entry> - </row><row> - <entry align="char" id="PILOT-AUTO"><constant>PILOT_AUTO</constant></entry> - <entry align="char">Autodetect pilot tones</entry> - </row> - </tbody> - </tgroup> -</table> - </section> - </section> - <section id="DTV-ROLLOFF"> - <title><constant>DTV_ROLLOFF</constant></title> - <para>Sets DVB-S2 rolloff</para> - - <section id="fe-rolloff-t"> - <title>fe_rolloff type</title> -<table pgwide="1" frame="none" id="fe-rolloff"> - <title>enum fe_rolloff</title> - <tgroup cols="2"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry align="char" id="ROLLOFF-35"><constant>ROLLOFF_35</constant></entry> - <entry align="char">Roloff factor: α=35%</entry> - </row><row> - <entry align="char" id="ROLLOFF-20"><constant>ROLLOFF_20</constant></entry> - <entry align="char">Roloff factor: α=20%</entry> - </row><row> - <entry align="char" id="ROLLOFF-25"><constant>ROLLOFF_25</constant></entry> - <entry align="char">Roloff factor: α=25%</entry> - </row><row> - <entry align="char" id="ROLLOFF-AUTO"><constant>ROLLOFF_AUTO</constant></entry> - <entry align="char">Auto-detect the roloff factor.</entry> - </row> - </tbody> - </tgroup> -</table> - </section> - </section> - <section id="DTV-DISEQC-SLAVE-REPLY"> - <title><constant>DTV_DISEQC_SLAVE_REPLY</constant></title> - <para>Currently not implemented.</para> - </section> - <section id="DTV-FE-CAPABILITY-COUNT"> - <title><constant>DTV_FE_CAPABILITY_COUNT</constant></title> - <para>Currently not implemented.</para> - </section> - <section id="DTV-FE-CAPABILITY"> - <title><constant>DTV_FE_CAPABILITY</constant></title> - <para>Currently not implemented.</para> - </section> - <section id="DTV-DELIVERY-SYSTEM"> - <title><constant>DTV_DELIVERY_SYSTEM</constant></title> - <para>Specifies the type of Delivery system</para> - <section id="fe-delivery-system-t"> - <title>fe_delivery_system type</title> - <para>Possible values: </para> - -<table pgwide="1" frame="none" id="fe-delivery-system"> - <title>enum fe_delivery_system</title> - <tgroup cols="2"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry id="SYS-UNDEFINED"><constant>SYS_UNDEFINED</constant></entry> - <entry>Undefined standard. Generally, indicates an error</entry> - </row><row> - <entry id="SYS-DVBC-ANNEX-A"><constant>SYS_DVBC_ANNEX_A</constant></entry> - <entry>Cable TV: DVB-C following ITU-T J.83 Annex A spec</entry> - </row><row> - <entry id="SYS-DVBC-ANNEX-B"><constant>SYS_DVBC_ANNEX_B</constant></entry> - <entry>Cable TV: DVB-C following ITU-T J.83 Annex B spec (ClearQAM)</entry> - </row><row> - <entry id="SYS-DVBC-ANNEX-C"><constant>SYS_DVBC_ANNEX_C</constant></entry> - <entry>Cable TV: DVB-C following ITU-T J.83 Annex C spec</entry> - </row><row> - <entry id="SYS-ISDBC"><constant>SYS_ISDBC</constant></entry> - <entry>Cable TV: ISDB-C (no drivers yet)</entry> - </row><row> - <entry id="SYS-DVBT"><constant>SYS_DVBT</constant></entry> - <entry>Terrestral TV: DVB-T</entry> - </row><row> - <entry id="SYS-DVBT2"><constant>SYS_DVBT2</constant></entry> - <entry>Terrestral TV: DVB-T2</entry> - </row><row> - <entry id="SYS-ISDBT"><constant>SYS_ISDBT</constant></entry> - <entry>Terrestral TV: ISDB-T</entry> - </row><row> - <entry id="SYS-ATSC"><constant>SYS_ATSC</constant></entry> - <entry>Terrestral TV: ATSC</entry> - </row><row> - <entry id="SYS-ATSCMH"><constant>SYS_ATSCMH</constant></entry> - <entry>Terrestral TV (mobile): ATSC-M/H</entry> - </row><row> - <entry id="SYS-DTMB"><constant>SYS_DTMB</constant></entry> - <entry>Terrestrial TV: DTMB</entry> - </row><row> - <entry id="SYS-DVBS"><constant>SYS_DVBS</constant></entry> - <entry>Satellite TV: DVB-S</entry> - </row><row> - <entry id="SYS-DVBS2"><constant>SYS_DVBS2</constant></entry> - <entry>Satellite TV: DVB-S2</entry> - </row><row> - <entry id="SYS-TURBO"><constant>SYS_TURBO</constant></entry> - <entry>Satellite TV: DVB-S Turbo</entry> - </row><row> - <entry id="SYS-ISDBS"><constant>SYS_ISDBS</constant></entry> - <entry>Satellite TV: ISDB-S</entry> - </row><row> - <entry id="SYS-DAB"><constant>SYS_DAB</constant></entry> - <entry>Digital audio: DAB (not fully supported)</entry> - </row><row> - <entry id="SYS-DSS"><constant>SYS_DSS</constant></entry> - <entry>Satellite TV:"DSS (not fully supported)</entry> - </row><row> - <entry id="SYS-CMMB"><constant>SYS_CMMB</constant></entry> - <entry>Terrestral TV (mobile):CMMB (not fully supported)</entry> - </row><row> - <entry id="SYS-DVBH"><constant>SYS_DVBH</constant></entry> - <entry>Terrestral TV (mobile): DVB-H (standard deprecated)</entry> - </row> - </tbody> - </tgroup> -</table> - - -</section> - </section> - <section id="DTV-ISDBT-PARTIAL-RECEPTION"> - <title><constant>DTV_ISDBT_PARTIAL_RECEPTION</constant></title> - - <para>If <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '0' this bit-field represents whether - the channel is in partial reception mode or not.</para> - - <para>If '1' <constant>DTV_ISDBT_LAYERA_*</constant> values are assigned to the center segment and - <constant>DTV_ISDBT_LAYERA_SEGMENT_COUNT</constant> has to be '1'.</para> - - <para>If in addition <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1' - <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> represents whether this ISDB-Tsb channel - is consisting of one segment and layer or three segments and two layers.</para> - - <para>Possible values: 0, 1, -1 (AUTO)</para> - </section> - <section id="DTV-ISDBT-SOUND-BROADCASTING"> - <title><constant>DTV_ISDBT_SOUND_BROADCASTING</constant></title> - - <para>This field represents whether the other DTV_ISDBT_*-parameters are - referring to an ISDB-T and an ISDB-Tsb channel. (See also - <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>).</para> - - <para>Possible values: 0, 1, -1 (AUTO)</para> - </section> - <section id="DTV-ISDBT-SB-SUBCHANNEL-ID"> - <title><constant>DTV_ISDBT_SB_SUBCHANNEL_ID</constant></title> - - <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para> - - <para>(Note of the author: This might not be the correct description of the - <constant>SUBCHANNEL-ID</constant> in all details, but it is my understanding of the technical - background needed to program a device)</para> - - <para>An ISDB-Tsb channel (1 or 3 segments) can be broadcasted alone or in a - set of connected ISDB-Tsb channels. In this set of channels every - channel can be received independently. The number of connected - ISDB-Tsb segment can vary, e.g. depending on the frequency spectrum - bandwidth available.</para> - - <para>Example: Assume 8 ISDB-Tsb connected segments are broadcasted. The - broadcaster has several possibilities to put those channels in the - air: Assuming a normal 13-segment ISDB-T spectrum he can align the 8 - segments from position 1-8 to 5-13 or anything in between.</para> - - <para>The underlying layer of segments are subchannels: each segment is - consisting of several subchannels with a predefined IDs. A sub-channel - is used to help the demodulator to synchronize on the channel.</para> - - <para>An ISDB-T channel is always centered over all sub-channels. As for - the example above, in ISDB-Tsb it is no longer as simple as that.</para> - - <para><constant>The DTV_ISDBT_SB_SUBCHANNEL_ID</constant> parameter is used to give the - sub-channel ID of the segment to be demodulated.</para> - - <para>Possible values: 0 .. 41, -1 (AUTO)</para> - </section> - <section id="DTV-ISDBT-SB-SEGMENT-IDX"> - <title><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant></title> - <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para> - <para><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant> gives the index of the segment to be - demodulated for an ISDB-Tsb channel where several of them are - transmitted in the connected manner.</para> - <para>Possible values: 0 .. <constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant> - 1</para> - <para>Note: This value cannot be determined by an automatic channel search.</para> - </section> - <section id="DTV-ISDBT-SB-SEGMENT-COUNT"> - <title><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant></title> - <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para> - <para><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant> gives the total count of connected ISDB-Tsb - channels.</para> - <para>Possible values: 1 .. 13</para> - <para>Note: This value cannot be determined by an automatic channel search.</para> - </section> - <section id="isdb-hierq-layers"> - <title><constant>DTV-ISDBT-LAYER*</constant> parameters</title> - <para>ISDB-T channels can be coded hierarchically. As opposed to DVB-T in - ISDB-T hierarchical layers can be decoded simultaneously. For that - reason a ISDB-T demodulator has 3 Viterbi and 3 Reed-Solomon decoders.</para> - <para>ISDB-T has 3 hierarchical layers which each can use a part of the - available segments. The total number of segments over all layers has - to 13 in ISDB-T.</para> - <para>There are 3 parameter sets, for Layers A, B and C.</para> - <section id="DTV-ISDBT-LAYER-ENABLED"> - <title><constant>DTV_ISDBT_LAYER_ENABLED</constant></title> - <para>Hierarchical reception in ISDB-T is achieved by enabling or disabling - layers in the decoding process. Setting all bits of - <constant>DTV_ISDBT_LAYER_ENABLED</constant> to '1' forces all layers (if applicable) to be - demodulated. This is the default.</para> - <para>If the channel is in the partial reception mode - (<constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> = 1) the central segment can be decoded - independently of the other 12 segments. In that mode layer A has to - have a <constant>SEGMENT_COUNT</constant> of 1.</para> - <para>In ISDB-Tsb only layer A is used, it can be 1 or 3 in ISDB-Tsb - according to <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>. <constant>SEGMENT_COUNT</constant> must be filled - accordingly.</para> - <para>Possible values: 0x1, 0x2, 0x4 (|-able)</para> - <para><constant>DTV_ISDBT_LAYER_ENABLED[0:0]</constant> - layer A</para> - <para><constant>DTV_ISDBT_LAYER_ENABLED[1:1]</constant> - layer B</para> - <para><constant>DTV_ISDBT_LAYER_ENABLED[2:2]</constant> - layer C</para> - <para><constant>DTV_ISDBT_LAYER_ENABLED[31:3]</constant> unused</para> - </section> - <section id="DTV-ISDBT-LAYER-FEC"> - <title><constant>DTV_ISDBT_LAYER*_FEC</constant></title> - <para>Possible values: <constant>FEC_AUTO</constant>, <constant>FEC_1_2</constant>, <constant>FEC_2_3</constant>, <constant>FEC_3_4</constant>, <constant>FEC_5_6</constant>, <constant>FEC_7_8</constant></para> - </section> - <section id="DTV-ISDBT-LAYER-MODULATION"> - <title><constant>DTV_ISDBT_LAYER*_MODULATION</constant></title> - <para>Possible values: <constant>QAM_AUTO</constant>, QP<constant>SK, QAM_16</constant>, <constant>QAM_64</constant>, <constant>DQPSK</constant></para> - <para>Note: If layer C is <constant>DQPSK</constant> layer B has to be <constant>DQPSK</constant>. If layer B is <constant>DQPSK</constant> - and <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>=0 layer has to be <constant>DQPSK</constant>.</para> - </section> - <section id="DTV-ISDBT-LAYER-SEGMENT-COUNT"> - <title><constant>DTV_ISDBT_LAYER*_SEGMENT_COUNT</constant></title> - <para>Possible values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, -1 (AUTO)</para> - <para>Note: Truth table for <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> and - <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> and <constant>LAYER</constant>*_SEGMENT_COUNT</para> - <informaltable id="isdbt-layer_seg-cnt-table"> - <tgroup cols="6"> - <tbody> - <row> - <entry>PR</entry> - <entry>SB</entry> - <entry>Layer A width</entry> - <entry>Layer B width</entry> - <entry>Layer C width</entry> - <entry>total width</entry> - </row> - <row> - <entry>0</entry> - <entry>0</entry> - <entry>1 .. 13</entry> - <entry>1 .. 13</entry> - <entry>1 .. 13</entry> - <entry>13</entry> - </row> - <row> - <entry>1</entry> - <entry>0</entry> - <entry>1</entry> - <entry>1 .. 13</entry> - <entry>1 .. 13</entry> - <entry>13</entry> - </row> - <row> - <entry>0</entry> - <entry>1</entry> - <entry>1</entry> - <entry>0</entry> - <entry>0</entry> - <entry>1</entry> - </row> - <row> - <entry>1</entry> - <entry>1</entry> - <entry>1</entry> - <entry>2</entry> - <entry>0</entry> - <entry>13</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - <section id="DTV-ISDBT-LAYER-TIME-INTERLEAVING"> - <title><constant>DTV_ISDBT_LAYER*_TIME_INTERLEAVING</constant></title> - <para>Valid values: 0, 1, 2, 4, -1 (AUTO)</para> - <para>when DTV_ISDBT_SOUND_BROADCASTING is active, value 8 is also valid.</para> - <para>Note: The real time interleaving length depends on the mode (fft-size). The values - here are referring to what can be found in the TMCC-structure, as shown in the table below.</para> - <informaltable id="isdbt-layer-interleaving-table"> - <tgroup cols="4" align="center"> - <tbody> - <row> - <entry>DTV_ISDBT_LAYER*_TIME_INTERLEAVING</entry> - <entry>Mode 1 (2K FFT)</entry> - <entry>Mode 2 (4K FFT)</entry> - <entry>Mode 3 (8K FFT)</entry> - </row> - <row> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - </row> - <row> - <entry>1</entry> - <entry>4</entry> - <entry>2</entry> - <entry>1</entry> - </row> - <row> - <entry>2</entry> - <entry>8</entry> - <entry>4</entry> - <entry>2</entry> - </row> - <row> - <entry>4</entry> - <entry>16</entry> - <entry>8</entry> - <entry>4</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - <section id="DTV-ATSCMH-FIC-VER"> - <title><constant>DTV_ATSCMH_FIC_VER</constant></title> - <para>Version number of the FIC (Fast Information Channel) signaling data.</para> - <para>FIC is used for relaying information to allow rapid service acquisition by the receiver.</para> - <para>Possible values: 0, 1, 2, 3, ..., 30, 31</para> - </section> - <section id="DTV-ATSCMH-PARADE-ID"> - <title><constant>DTV_ATSCMH_PARADE_ID</constant></title> - <para>Parade identification number</para> - <para>A parade is a collection of up to eight MH groups, conveying one or two ensembles.</para> - <para>Possible values: 0, 1, 2, 3, ..., 126, 127</para> - </section> - <section id="DTV-ATSCMH-NOG"> - <title><constant>DTV_ATSCMH_NOG</constant></title> - <para>Number of MH groups per MH subframe for a designated parade.</para> - <para>Possible values: 1, 2, 3, 4, 5, 6, 7, 8</para> - </section> - <section id="DTV-ATSCMH-TNOG"> - <title><constant>DTV_ATSCMH_TNOG</constant></title> - <para>Total number of MH groups including all MH groups belonging to all MH parades in one MH subframe.</para> - <para>Possible values: 0, 1, 2, 3, ..., 30, 31</para> - </section> - <section id="DTV-ATSCMH-SGN"> - <title><constant>DTV_ATSCMH_SGN</constant></title> - <para>Start group number.</para> - <para>Possible values: 0, 1, 2, 3, ..., 14, 15</para> - </section> - <section id="DTV-ATSCMH-PRC"> - <title><constant>DTV_ATSCMH_PRC</constant></title> - <para>Parade repetition cycle.</para> - <para>Possible values: 1, 2, 3, 4, 5, 6, 7, 8</para> - </section> - <section id="DTV-ATSCMH-RS-FRAME-MODE"> - <title><constant>DTV_ATSCMH_RS_FRAME_MODE</constant></title> - <para>Reed Solomon (RS) frame mode.</para> - <para>Possible values are:</para> -<table pgwide="1" frame="none" id="atscmh-rs-frame-mode"> - <title>enum atscmh_rs_frame_mode</title> - <tgroup cols="2"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry id="ATSCMH-RSFRAME-PRI-ONLY"><constant>ATSCMH_RSFRAME_PRI_ONLY</constant></entry> - <entry>Single Frame: There is only a primary RS Frame for all - Group Regions.</entry> - </row><row> - <entry id="ATSCMH-RSFRAME-PRI-SEC"><constant>ATSCMH_RSFRAME_PRI_SEC</constant></entry> - <entry>Dual Frame: There are two separate RS Frames: Primary RS - Frame for Group Region A and B and Secondary RS Frame for Group - Region C and D.</entry> - </row> - </tbody> - </tgroup> -</table> - </section> - <section id="DTV-ATSCMH-RS-FRAME-ENSEMBLE"> - <title><constant>DTV_ATSCMH_RS_FRAME_ENSEMBLE</constant></title> - <para>Reed Solomon(RS) frame ensemble.</para> - <para>Possible values are:</para> -<table pgwide="1" frame="none" id="atscmh-rs-frame-ensemble"> - <title>enum atscmh_rs_frame_ensemble</title> - <tgroup cols="2"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry id="ATSCMH-RSFRAME-ENS-PRI"><constant>ATSCMH_RSFRAME_ENS_PRI</constant></entry> - <entry>Primary Ensemble.</entry> - </row><row> - <entry id="ATSCMH-RSFRAME-ENS-SEC"><constant>AATSCMH_RSFRAME_PRI_SEC</constant></entry> - <entry>Secondary Ensemble.</entry> - </row><row> - <entry id="ATSCMH-RSFRAME-RES"><constant>AATSCMH_RSFRAME_RES</constant></entry> - <entry>Reserved. Shouldn't be used.</entry> - </row> - </tbody> - </tgroup> -</table> - </section> - <section id="DTV-ATSCMH-RS-CODE-MODE-PRI"> - <title><constant>DTV_ATSCMH_RS_CODE_MODE_PRI</constant></title> - <para>Reed Solomon (RS) code mode (primary).</para> - <para>Possible values are:</para> -<table pgwide="1" frame="none" id="atscmh-rs-code-mode"> - <title>enum atscmh_rs_code_mode</title> - <tgroup cols="2"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry id="ATSCMH-RSCODE-211-187"><constant>ATSCMH_RSCODE_211_187</constant></entry> - <entry>Reed Solomon code (211,187).</entry> - </row><row> - <entry id="ATSCMH-RSCODE-223-187"><constant>ATSCMH_RSCODE_223_187</constant></entry> - <entry>Reed Solomon code (223,187).</entry> - </row><row> - <entry id="ATSCMH-RSCODE-235-187"><constant>ATSCMH_RSCODE_235_187</constant></entry> - <entry>Reed Solomon code (235,187).</entry> - </row><row> - <entry id="ATSCMH-RSCODE-RES"><constant>ATSCMH_RSCODE_RES</constant></entry> - <entry>Reserved. Shouldn't be used.</entry> - </row> - </tbody> - </tgroup> -</table> - </section> - <section id="DTV-ATSCMH-RS-CODE-MODE-SEC"> - <title><constant>DTV_ATSCMH_RS_CODE_MODE_SEC</constant></title> - <para>Reed Solomon (RS) code mode (secondary).</para> - <para>Possible values are the same as documented on - &atscmh-rs-code-mode;:</para> - </section> - <section id="DTV-ATSCMH-SCCC-BLOCK-MODE"> - <title><constant>DTV_ATSCMH_SCCC_BLOCK_MODE</constant></title> - <para>Series Concatenated Convolutional Code Block Mode.</para> - <para>Possible values are:</para> -<table pgwide="1" frame="none" id="atscmh-sccc-block-mode"> - <title>enum atscmh_scc_block_mode</title> - <tgroup cols="2"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry id="ATSCMH-SCCC-BLK-SEP"><constant>ATSCMH_SCCC_BLK_SEP</constant></entry> - <entry>Separate SCCC: the SCCC outer code mode shall be set independently - for each Group Region (A, B, C, D)</entry> - </row><row> - <entry id="ATSCMH-SCCC-BLK-COMB"><constant>ATSCMH_SCCC_BLK_COMB</constant></entry> - <entry>Combined SCCC: all four Regions shall have the same SCCC outer - code mode.</entry> - </row><row> - <entry id="ATSCMH-SCCC-BLK-RES"><constant>ATSCMH_SCCC_BLK_RES</constant></entry> - <entry>Reserved. Shouldn't be used.</entry> - </row> - </tbody> - </tgroup> -</table> - </section> - <section id="DTV-ATSCMH-SCCC-CODE-MODE-A"> - <title><constant>DTV_ATSCMH_SCCC_CODE_MODE_A</constant></title> - <para>Series Concatenated Convolutional Code Rate.</para> - <para>Possible values are:</para> -<table pgwide="1" frame="none" id="atscmh-sccc-code-mode"> - <title>enum atscmh_sccc_code_mode</title> - <tgroup cols="2"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry id="ATSCMH-SCCC-CODE-HLF"><constant>ATSCMH_SCCC_CODE_HLF</constant></entry> - <entry>The outer code rate of a SCCC Block is 1/2 rate.</entry> - </row><row> - <entry id="ATSCMH-SCCC-CODE-QTR"><constant>ATSCMH_SCCC_CODE_QTR</constant></entry> - <entry>The outer code rate of a SCCC Block is 1/4 rate.</entry> - </row><row> - <entry id="ATSCMH-SCCC-CODE-RES"><constant>ATSCMH_SCCC_CODE_RES</constant></entry> - <entry>to be documented.</entry> - </row> - </tbody> - </tgroup> -</table> - </section> - <section id="DTV-ATSCMH-SCCC-CODE-MODE-B"> - <title><constant>DTV_ATSCMH_SCCC_CODE_MODE_B</constant></title> - <para>Series Concatenated Convolutional Code Rate.</para> - <para>Possible values are the same as documented on - &atscmh-sccc-code-mode;.</para> - </section> - <section id="DTV-ATSCMH-SCCC-CODE-MODE-C"> - <title><constant>DTV_ATSCMH_SCCC_CODE_MODE_C</constant></title> - <para>Series Concatenated Convolutional Code Rate.</para> - <para>Possible values are the same as documented on - &atscmh-sccc-code-mode;.</para> - </section> - <section id="DTV-ATSCMH-SCCC-CODE-MODE-D"> - <title><constant>DTV_ATSCMH_SCCC_CODE_MODE_D</constant></title> - <para>Series Concatenated Convolutional Code Rate.</para> - <para>Possible values are the same as documented on - &atscmh-sccc-code-mode;.</para> - </section> - </section> - <section id="DTV-API-VERSION"> - <title><constant>DTV_API_VERSION</constant></title> - <para>Returns the major/minor version of the DVB API</para> - </section> - <section id="DTV-CODE-RATE-HP"> - <title><constant>DTV_CODE_RATE_HP</constant></title> - <para>Used on terrestrial transmissions. The acceptable values are - the ones described at &fe-transmit-mode-t;. - </para> - </section> - <section id="DTV-CODE-RATE-LP"> - <title><constant>DTV_CODE_RATE_LP</constant></title> - <para>Used on terrestrial transmissions. The acceptable values are - the ones described at &fe-transmit-mode-t;. - </para> - - </section> - - <section id="DTV-GUARD-INTERVAL"> - <title><constant>DTV_GUARD_INTERVAL</constant></title> - - <para>Possible values are:</para> - -<section id="fe-guard-interval-t"> -<title>Modulation guard interval</title> - -<table pgwide="1" frame="none" id="fe-guard-interval"> - <title>enum fe_guard_interval</title> - <tgroup cols="2"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry id="GUARD-INTERVAL-AUTO"><constant>GUARD_INTERVAL_AUTO</constant></entry> - <entry>Autodetect the guard interval</entry> - </row><row> - <entry id="GUARD-INTERVAL-1-128"><constant>GUARD_INTERVAL_1_128</constant></entry> - <entry>Guard interval 1/128</entry> - </row><row> - <entry id="GUARD-INTERVAL-1-32"><constant>GUARD_INTERVAL_1_32</constant></entry> - <entry>Guard interval 1/32</entry> - </row><row> - <entry id="GUARD-INTERVAL-1-16"><constant>GUARD_INTERVAL_1_16</constant></entry> - <entry>Guard interval 1/16</entry> - </row><row> - <entry id="GUARD-INTERVAL-1-8"><constant>GUARD_INTERVAL_1_8</constant></entry> - <entry>Guard interval 1/8</entry> - </row><row> - <entry id="GUARD-INTERVAL-1-4"><constant>GUARD_INTERVAL_1_4</constant></entry> - <entry>Guard interval 1/4</entry> - </row><row> - <entry id="GUARD-INTERVAL-19-128"><constant>GUARD_INTERVAL_19_128</constant></entry> - <entry>Guard interval 19/128</entry> - </row><row> - <entry id="GUARD-INTERVAL-19-256"><constant>GUARD_INTERVAL_19_256</constant></entry> - <entry>Guard interval 19/256</entry> - </row><row> - <entry id="GUARD-INTERVAL-PN420"><constant>GUARD_INTERVAL_PN420</constant></entry> - <entry>PN length 420 (1/4)</entry> - </row><row> - <entry id="GUARD-INTERVAL-PN595"><constant>GUARD_INTERVAL_PN595</constant></entry> - <entry>PN length 595 (1/6)</entry> - </row><row> - <entry id="GUARD-INTERVAL-PN945"><constant>GUARD_INTERVAL_PN945</constant></entry> - <entry>PN length 945 (1/9)</entry> - </row> - </tbody> - </tgroup> -</table> - - <para>Notes:</para> - <para>1) If <constant>DTV_GUARD_INTERVAL</constant> is set the <constant>GUARD_INTERVAL_AUTO</constant> the hardware will - try to find the correct guard interval (if capable) and will use TMCC to fill - in the missing parameters.</para> - <para>2) Intervals 1/128, 19/128 and 19/256 are used only for DVB-T2 at present</para> - <para>3) DTMB specifies PN420, PN595 and PN945.</para> -</section> - </section> - <section id="DTV-TRANSMISSION-MODE"> - <title><constant>DTV_TRANSMISSION_MODE</constant></title> - - <para>Specifies the number of carriers used by the standard. - This is used only on OFTM-based standards, e. g. - DVB-T/T2, ISDB-T, DTMB</para> - -<section id="fe-transmit-mode-t"> -<title>enum fe_transmit_mode: Number of carriers per channel</title> - -<table pgwide="1" frame="none" id="fe-transmit-mode"> - <title>enum fe_transmit_mode</title> - <tgroup cols="2"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry id="TRANSMISSION-MODE-AUTO"><constant>TRANSMISSION_MODE_AUTO</constant></entry> - <entry>Autodetect transmission mode. The hardware will try to find - the correct FFT-size (if capable) to fill in the missing - parameters.</entry> - </row><row> - <entry id="TRANSMISSION-MODE-1K"><constant>TRANSMISSION_MODE_1K</constant></entry> - <entry>Transmission mode 1K</entry> - </row><row> - <entry id="TRANSMISSION-MODE-2K"><constant>TRANSMISSION_MODE_2K</constant></entry> - <entry>Transmission mode 2K</entry> - </row><row> - <entry id="TRANSMISSION-MODE-8K"><constant>TRANSMISSION_MODE_8K</constant></entry> - <entry>Transmission mode 8K</entry> - </row><row> - <entry id="TRANSMISSION-MODE-4K"><constant>TRANSMISSION_MODE_4K</constant></entry> - <entry>Transmission mode 4K</entry> - </row><row> - <entry id="TRANSMISSION-MODE-16K"><constant>TRANSMISSION_MODE_16K</constant></entry> - <entry>Transmission mode 16K</entry> - </row><row> - <entry id="TRANSMISSION-MODE-32K"><constant>TRANSMISSION_MODE_32K</constant></entry> - <entry>Transmission mode 32K</entry> - </row><row> - <entry id="TRANSMISSION-MODE-C1"><constant>TRANSMISSION_MODE_C1</constant></entry> - <entry>Single Carrier (C=1) transmission mode (DTMB)</entry> - </row><row> - <entry id="TRANSMISSION-MODE-C3780"><constant>TRANSMISSION_MODE_C3780</constant></entry> - <entry>Multi Carrier (C=3780) transmission mode (DTMB)</entry> - </row> - </tbody> - </tgroup> -</table> - - - <para>Notes:</para> - <para>1) ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called - 'mode' in the standard: Mode 1 is 2K, mode 2 is 4K, mode 3 is 8K</para> - - <para>2) If <constant>DTV_TRANSMISSION_MODE</constant> is set the <constant>TRANSMISSION_MODE_AUTO</constant> the - hardware will try to find the correct FFT-size (if capable) and will - use TMCC to fill in the missing parameters.</para> - <para>3) DVB-T specifies 2K and 8K as valid sizes.</para> - <para>4) DVB-T2 specifies 1K, 2K, 4K, 8K, 16K and 32K.</para> - <para>5) DTMB specifies C1 and C3780.</para> -</section> - </section> - <section id="DTV-HIERARCHY"> - <title><constant>DTV_HIERARCHY</constant></title> - <para>Frontend hierarchy</para> - - -<section id="fe-hierarchy-t"> -<title>Frontend hierarchy</title> - -<table pgwide="1" frame="none" id="fe-hierarchy"> - <title>enum fe_hierarchy</title> - <tgroup cols="2"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry id="HIERARCHY-NONE"><constant>HIERARCHY_NONE</constant></entry> - <entry>No hierarchy</entry> - </row><row> - <entry id="HIERARCHY-AUTO"><constant>HIERARCHY_AUTO</constant></entry> - <entry>Autodetect hierarchy (if supported)</entry> - </row><row> - <entry id="HIERARCHY-1"><constant>HIERARCHY_1</constant></entry> - <entry>Hierarchy 1</entry> - </row><row> - <entry id="HIERARCHY-2"><constant>HIERARCHY_2</constant></entry> - <entry>Hierarchy 2</entry> - </row><row> - <entry id="HIERARCHY-4"><constant>HIERARCHY_4</constant></entry> - <entry>Hierarchy 4</entry> - </row> - </tbody> - </tgroup> -</table> -</section> - - </section> - <section id="DTV-STREAM-ID"> - <title><constant>DTV_STREAM_ID</constant></title> - <para>DVB-S2, DVB-T2 and ISDB-S support the transmission of several - streams on a single transport stream. - This property enables the DVB driver to handle substream filtering, - when supported by the hardware. - By default, substream filtering is disabled. - </para><para> - For DVB-S2 and DVB-T2, the valid substream id range is from 0 to 255. - </para><para> - For ISDB, the valid substream id range is from 1 to 65535. - </para><para> - To disable it, you should use the special macro NO_STREAM_ID_FILTER. - </para><para> - Note: any value outside the id range also disables filtering. - </para> - </section> - <section id="DTV-DVBT2-PLP-ID-LEGACY"> - <title><constant>DTV_DVBT2_PLP_ID_LEGACY</constant></title> - <para>Obsolete, replaced with DTV_STREAM_ID.</para> - </section> - <section id="DTV-ENUM-DELSYS"> - <title><constant>DTV_ENUM_DELSYS</constant></title> - <para>A Multi standard frontend needs to advertise the delivery systems provided. - Applications need to enumerate the provided delivery systems, before using - any other operation with the frontend. Prior to it's introduction, - FE_GET_INFO was used to determine a frontend type. A frontend which - provides more than a single delivery system, FE_GET_INFO doesn't help much. - Applications which intends to use a multistandard frontend must enumerate - the delivery systems associated with it, rather than trying to use - FE_GET_INFO. In the case of a legacy frontend, the result is just the same - as with FE_GET_INFO, but in a more structured format </para> - </section> - <section id="DTV-INTERLEAVING"> - <title><constant>DTV_INTERLEAVING</constant></title> - -<para>Time interleaving to be used. Currently, used only on DTMB.</para> - -<table pgwide="1" frame="none" id="fe-interleaving"> - <title>enum fe_interleaving</title> - <tgroup cols="2"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry id="INTERLEAVING-NONE"><constant>INTERLEAVING_NONE</constant></entry> - <entry>No interleaving.</entry> - </row><row> - <entry id="INTERLEAVING-AUTO"><constant>INTERLEAVING_AUTO</constant></entry> - <entry>Auto-detect interleaving.</entry> - </row><row> - <entry id="INTERLEAVING-240"><constant>INTERLEAVING_240</constant></entry> - <entry>Interleaving of 240 symbols.</entry> - </row><row> - <entry id="INTERLEAVING-720"><constant>INTERLEAVING_720</constant></entry> - <entry>Interleaving of 720 symbols.</entry> - </row> - </tbody> - </tgroup> -</table> - - </section> - <section id="DTV-LNA"> - <title><constant>DTV_LNA</constant></title> - <para>Low-noise amplifier.</para> - <para>Hardware might offer controllable LNA which can be set manually - using that parameter. Usually LNA could be found only from - terrestrial devices if at all.</para> - <para>Possible values: 0, 1, LNA_AUTO</para> - <para>0, LNA off</para> - <para>1, LNA on</para> - <para>use the special macro LNA_AUTO to set LNA auto</para> - </section> -</section> - - <section id="frontend-stat-properties"> - <title>Frontend statistics indicators</title> - <para>The values are returned via <constant>dtv_property.stat</constant>. - If the property is supported, <constant>dtv_property.stat.len</constant> is bigger than zero.</para> - <para>For most delivery systems, <constant>dtv_property.stat.len</constant> - will be 1 if the stats is supported, and the properties will - return a single value for each parameter.</para> - <para>It should be noted, however, that new OFDM delivery systems - like ISDB can use different modulation types for each group of - carriers. On such standards, up to 3 groups of statistics can be - provided, and <constant>dtv_property.stat.len</constant> is updated - to reflect the "global" metrics, plus one metric per each carrier - group (called "layer" on ISDB).</para> - <para>So, in order to be consistent with other delivery systems, the first - value at <link linkend="dtv-stats"><constant>dtv_property.stat.dtv_stats</constant></link> - array refers to the global metric. The other elements of the array - represent each layer, starting from layer A(index 1), - layer B (index 2) and so on.</para> - <para>The number of filled elements are stored at <constant>dtv_property.stat.len</constant>.</para> - <para>Each element of the <constant>dtv_property.stat.dtv_stats</constant> array consists on two elements:</para> - <itemizedlist mark='opencircle'> - <listitem><para><constant>svalue</constant> or <constant>uvalue</constant>, where - <constant>svalue</constant> is for signed values of the measure (dB measures) - and <constant>uvalue</constant> is for unsigned values (counters, relative scale)</para></listitem> - <listitem><para><constant>scale</constant> - Scale for the value. It can be:</para> - <itemizedlist mark='bullet' id="fecap-scale-params"> - <listitem id="FE-SCALE-NOT-AVAILABLE"><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - The parameter is supported by the frontend, but it was not possible to collect it (could be a transitory or permanent condition)</para></listitem> - <listitem id="FE-SCALE-DECIBEL"><para><constant>FE_SCALE_DECIBEL</constant> - parameter is a signed value, measured in 1/1000 dB</para></listitem> - <listitem id="FE-SCALE-RELATIVE"><para><constant>FE_SCALE_RELATIVE</constant> - parameter is a unsigned value, where 0 means 0% and 65535 means 100%.</para></listitem> - <listitem id="FE-SCALE-COUNTER"><para><constant>FE_SCALE_COUNTER</constant> - parameter is a unsigned value that counts the occurrence of an event, like bit error, block error, or lapsed time.</para></listitem> - </itemizedlist> - </listitem> - </itemizedlist> - <section id="DTV-STAT-SIGNAL-STRENGTH"> - <title><constant>DTV_STAT_SIGNAL_STRENGTH</constant></title> - <para>Indicates the signal strength level at the analog part of the tuner or of the demod.</para> - <para>Possible scales for this metric are:</para> - <itemizedlist mark='bullet'> - <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem> - <listitem><para><constant>FE_SCALE_DECIBEL</constant> - signal strength is in 0.001 dBm units, power measured in miliwatts. This value is generally negative.</para></listitem> - <listitem><para><constant>FE_SCALE_RELATIVE</constant> - The frontend provides a 0% to 100% measurement for power (actually, 0 to 65535).</para></listitem> - </itemizedlist> - </section> - <section id="DTV-STAT-CNR"> - <title><constant>DTV_STAT_CNR</constant></title> - <para>Indicates the Signal to Noise ratio for the main carrier.</para> - <para>Possible scales for this metric are:</para> - <itemizedlist mark='bullet'> - <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem> - <listitem><para><constant>FE_SCALE_DECIBEL</constant> - Signal/Noise ratio is in 0.001 dB units.</para></listitem> - <listitem><para><constant>FE_SCALE_RELATIVE</constant> - The frontend provides a 0% to 100% measurement for Signal/Noise (actually, 0 to 65535).</para></listitem> - </itemizedlist> - </section> - <section id="DTV-STAT-PRE-ERROR-BIT-COUNT"> - <title><constant>DTV_STAT_PRE_ERROR_BIT_COUNT</constant></title> - <para>Measures the number of bit errors before the forward error correction (FEC) on the inner coding block (before Viterbi, LDPC or other inner code).</para> - <para>This measure is taken during the same interval as <constant>DTV_STAT_PRE_TOTAL_BIT_COUNT</constant>.</para> - <para>In order to get the BER (Bit Error Rate) measurement, it should be divided by - <link linkend="DTV-STAT-PRE-TOTAL-BIT-COUNT"><constant>DTV_STAT_PRE_TOTAL_BIT_COUNT</constant></link>.</para> - <para>This measurement is monotonically increased, as the frontend gets more bit count measurements. - The frontend may reset it when a channel/transponder is tuned.</para> - <para>Possible scales for this metric are:</para> - <itemizedlist mark='bullet'> - <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem> - <listitem><para><constant>FE_SCALE_COUNTER</constant> - Number of error bits counted before the inner coding.</para></listitem> - </itemizedlist> - </section> - <section id="DTV-STAT-PRE-TOTAL-BIT-COUNT"> - <title><constant>DTV_STAT_PRE_TOTAL_BIT_COUNT</constant></title> - <para>Measures the amount of bits received before the inner code block, during the same period as - <link linkend="DTV-STAT-PRE-ERROR-BIT-COUNT"><constant>DTV_STAT_PRE_ERROR_BIT_COUNT</constant></link> measurement was taken.</para> - <para>It should be noted that this measurement can be smaller than the total amount of bits on the transport stream, - as the frontend may need to manually restart the measurement, losing some data between each measurement interval.</para> - <para>This measurement is monotonically increased, as the frontend gets more bit count measurements. - The frontend may reset it when a channel/transponder is tuned.</para> - <para>Possible scales for this metric are:</para> - <itemizedlist mark='bullet'> - <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem> - <listitem><para><constant>FE_SCALE_COUNTER</constant> - Number of bits counted while measuring - <link linkend="DTV-STAT-PRE-ERROR-BIT-COUNT"><constant>DTV_STAT_PRE_ERROR_BIT_COUNT</constant></link>.</para></listitem> - </itemizedlist> - </section> - <section id="DTV-STAT-POST-ERROR-BIT-COUNT"> - <title><constant>DTV_STAT_POST_ERROR_BIT_COUNT</constant></title> - <para>Measures the number of bit errors after the forward error correction (FEC) done by inner code block (after Viterbi, LDPC or other inner code).</para> - <para>This measure is taken during the same interval as <constant>DTV_STAT_POST_TOTAL_BIT_COUNT</constant>.</para> - <para>In order to get the BER (Bit Error Rate) measurement, it should be divided by - <link linkend="DTV-STAT-POST-TOTAL-BIT-COUNT"><constant>DTV_STAT_POST_TOTAL_BIT_COUNT</constant></link>.</para> - <para>This measurement is monotonically increased, as the frontend gets more bit count measurements. - The frontend may reset it when a channel/transponder is tuned.</para> - <para>Possible scales for this metric are:</para> - <itemizedlist mark='bullet'> - <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem> - <listitem><para><constant>FE_SCALE_COUNTER</constant> - Number of error bits counted after the inner coding.</para></listitem> - </itemizedlist> - </section> - <section id="DTV-STAT-POST-TOTAL-BIT-COUNT"> - <title><constant>DTV_STAT_POST_TOTAL_BIT_COUNT</constant></title> - <para>Measures the amount of bits received after the inner coding, during the same period as - <link linkend="DTV-STAT-POST-ERROR-BIT-COUNT"><constant>DTV_STAT_POST_ERROR_BIT_COUNT</constant></link> measurement was taken.</para> - <para>It should be noted that this measurement can be smaller than the total amount of bits on the transport stream, - as the frontend may need to manually restart the measurement, losing some data between each measurement interval.</para> - <para>This measurement is monotonically increased, as the frontend gets more bit count measurements. - The frontend may reset it when a channel/transponder is tuned.</para> - <para>Possible scales for this metric are:</para> - <itemizedlist mark='bullet'> - <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem> - <listitem><para><constant>FE_SCALE_COUNTER</constant> - Number of bits counted while measuring - <link linkend="DTV-STAT-POST-ERROR-BIT-COUNT"><constant>DTV_STAT_POST_ERROR_BIT_COUNT</constant></link>.</para></listitem> - </itemizedlist> - </section> - <section id="DTV-STAT-ERROR-BLOCK-COUNT"> - <title><constant>DTV_STAT_ERROR_BLOCK_COUNT</constant></title> - <para>Measures the number of block errors after the outer forward error correction coding (after Reed-Solomon or other outer code).</para> - <para>This measurement is monotonically increased, as the frontend gets more bit count measurements. - The frontend may reset it when a channel/transponder is tuned.</para> - <para>Possible scales for this metric are:</para> - <itemizedlist mark='bullet'> - <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem> - <listitem><para><constant>FE_SCALE_COUNTER</constant> - Number of error blocks counted after the outer coding.</para></listitem> - </itemizedlist> - </section> - <section id="DTV-STAT-TOTAL-BLOCK-COUNT"> - <title><constant>DTV-STAT_TOTAL_BLOCK_COUNT</constant></title> - <para>Measures the total number of blocks received during the same period as - <link linkend="DTV-STAT-ERROR-BLOCK-COUNT"><constant>DTV_STAT_ERROR_BLOCK_COUNT</constant></link> measurement was taken.</para> - <para>It can be used to calculate the PER indicator, by dividing - <link linkend="DTV-STAT-ERROR-BLOCK-COUNT"><constant>DTV_STAT_ERROR_BLOCK_COUNT</constant></link> - by <link linkend="DTV-STAT-TOTAL-BLOCK-COUNT"><constant>DTV-STAT-TOTAL-BLOCK-COUNT</constant></link>.</para> - <para>Possible scales for this metric are:</para> - <itemizedlist mark='bullet'> - <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem> - <listitem><para><constant>FE_SCALE_COUNTER</constant> - Number of blocks counted while measuring - <link linkend="DTV-STAT-ERROR-BLOCK-COUNT"><constant>DTV_STAT_ERROR_BLOCK_COUNT</constant></link>.</para></listitem> - </itemizedlist> - </section> - </section> - - <section id="frontend-property-terrestrial-systems"> - <title>Properties used on terrestrial delivery systems</title> - <section id="dvbt-params"> - <title>DVB-T delivery system</title> - <para>The following parameters are valid for DVB-T:</para> - <itemizedlist mark='opencircle'> - <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem> - <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem> - <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem> - <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-BANDWIDTH-HZ"><constant>DTV_BANDWIDTH_HZ</constant></link></para></listitem> - <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-CODE-RATE-HP"><constant>DTV_CODE_RATE_HP</constant></link></para></listitem> - <listitem><para><link linkend="DTV-CODE-RATE-LP"><constant>DTV_CODE_RATE_LP</constant></link></para></listitem> - <listitem><para><link linkend="DTV-GUARD-INTERVAL"><constant>DTV_GUARD_INTERVAL</constant></link></para></listitem> - <listitem><para><link linkend="DTV-TRANSMISSION-MODE"><constant>DTV_TRANSMISSION_MODE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-HIERARCHY"><constant>DTV_HIERARCHY</constant></link></para></listitem> - <listitem><para><link linkend="DTV-LNA"><constant>DTV_LNA</constant></link></para></listitem> - </itemizedlist> - <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para> - </section> - <section id="dvbt2-params"> - <title>DVB-T2 delivery system</title> - <para>DVB-T2 support is currently in the early stages - of development, so expect that this section maygrow and become - more detailed with time.</para> - <para>The following parameters are valid for DVB-T2:</para> - <itemizedlist mark='opencircle'> - <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem> - <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem> - <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem> - <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-BANDWIDTH-HZ"><constant>DTV_BANDWIDTH_HZ</constant></link></para></listitem> - <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-CODE-RATE-HP"><constant>DTV_CODE_RATE_HP</constant></link></para></listitem> - <listitem><para><link linkend="DTV-CODE-RATE-LP"><constant>DTV_CODE_RATE_LP</constant></link></para></listitem> - <listitem><para><link linkend="DTV-GUARD-INTERVAL"><constant>DTV_GUARD_INTERVAL</constant></link></para></listitem> - <listitem><para><link linkend="DTV-TRANSMISSION-MODE"><constant>DTV_TRANSMISSION_MODE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-HIERARCHY"><constant>DTV_HIERARCHY</constant></link></para></listitem> - <listitem><para><link linkend="DTV-STREAM-ID"><constant>DTV_STREAM_ID</constant></link></para></listitem> - <listitem><para><link linkend="DTV-LNA"><constant>DTV_LNA</constant></link></para></listitem> - </itemizedlist> - <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para> - </section> - <section id="isdbt"> - <title>ISDB-T delivery system</title> - <para>This ISDB-T/ISDB-Tsb API extension should reflect all information - needed to tune any ISDB-T/ISDB-Tsb hardware. Of course it is possible - that some very sophisticated devices won't need certain parameters to - tune.</para> - <para>The information given here should help application writers to know how - to handle ISDB-T and ISDB-Tsb hardware using the Linux DVB-API.</para> - <para>The details given here about ISDB-T and ISDB-Tsb are just enough to - basically show the dependencies between the needed parameter values, - but surely some information is left out. For more detailed information - see the following documents:</para> - <para>ARIB STD-B31 - "Transmission System for Digital Terrestrial - Television Broadcasting" and</para> - <para>ARIB TR-B14 - "Operational Guidelines for Digital Terrestrial - Television Broadcasting".</para> - <para>In order to understand the ISDB specific parameters, - one has to have some knowledge the channel structure in - ISDB-T and ISDB-Tsb. I.e. it has to be known to - the reader that an ISDB-T channel consists of 13 segments, - that it can have up to 3 layer sharing those segments, - and things like that.</para> - <para>The following parameters are valid for ISDB-T:</para> - <itemizedlist mark='opencircle'> - <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem> - <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem> - <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem> - <listitem><para><link linkend="DTV-BANDWIDTH-HZ"><constant>DTV_BANDWIDTH_HZ</constant></link></para></listitem> - <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-GUARD-INTERVAL"><constant>DTV_GUARD_INTERVAL</constant></link></para></listitem> - <listitem><para><link linkend="DTV-TRANSMISSION-MODE"><constant>DTV_TRANSMISSION_MODE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ISDBT-LAYER-ENABLED"><constant>DTV_ISDBT_LAYER_ENABLED</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ISDBT-PARTIAL-RECEPTION"><constant>DTV_ISDBT_PARTIAL_RECEPTION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ISDBT-SOUND-BROADCASTING"><constant>DTV_ISDBT_SOUND_BROADCASTING</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ISDBT-SB-SUBCHANNEL-ID"><constant>DTV_ISDBT_SB_SUBCHANNEL_ID</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ISDBT-SB-SEGMENT-IDX"><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ISDBT-SB-SEGMENT-COUNT"><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ISDBT-LAYER-FEC"><constant>DTV_ISDBT_LAYERA_FEC</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ISDBT-LAYER-MODULATION"><constant>DTV_ISDBT_LAYERA_MODULATION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ISDBT-LAYER-SEGMENT-COUNT"><constant>DTV_ISDBT_LAYERA_SEGMENT_COUNT</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ISDBT-LAYER-TIME-INTERLEAVING"><constant>DTV_ISDBT_LAYERA_TIME_INTERLEAVING</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ISDBT-LAYER-FEC"><constant>DTV_ISDBT_LAYERB_FEC</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ISDBT-LAYER-MODULATION"><constant>DTV_ISDBT_LAYERB_MODULATION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ISDBT-LAYER-SEGMENT-COUNT"><constant>DTV_ISDBT_LAYERB_SEGMENT_COUNT</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ISDBT-LAYER-TIME-INTERLEAVING"><constant>DTV_ISDBT_LAYERB_TIME_INTERLEAVING</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ISDBT-LAYER-FEC"><constant>DTV_ISDBT_LAYERC_FEC</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ISDBT-LAYER-MODULATION"><constant>DTV_ISDBT_LAYERC_MODULATION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ISDBT-LAYER-SEGMENT-COUNT"><constant>DTV_ISDBT_LAYERC_SEGMENT_COUNT</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ISDBT-LAYER-TIME-INTERLEAVING"><constant>DTV_ISDBT_LAYERC_TIME_INTERLEAVING</constant></link></para></listitem> - </itemizedlist> - <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para> - </section> - <section id="atsc-params"> - <title>ATSC delivery system</title> - <para>The following parameters are valid for ATSC:</para> - <itemizedlist mark='opencircle'> - <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem> - <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem> - <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem> - <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-BANDWIDTH-HZ"><constant>DTV_BANDWIDTH_HZ</constant></link></para></listitem> - </itemizedlist> - <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para> - </section> - <section id="atscmh-params"> - <title>ATSC-MH delivery system</title> - <para>The following parameters are valid for ATSC-MH:</para> - <itemizedlist mark='opencircle'> - <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem> - <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem> - <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem> - <listitem><para><link linkend="DTV-BANDWIDTH-HZ"><constant>DTV_BANDWIDTH_HZ</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ATSCMH-FIC-VER"><constant>DTV_ATSCMH_FIC_VER</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ATSCMH-PARADE-ID"><constant>DTV_ATSCMH_PARADE_ID</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ATSCMH-NOG"><constant>DTV_ATSCMH_NOG</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ATSCMH-TNOG"><constant>DTV_ATSCMH_TNOG</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ATSCMH-SGN"><constant>DTV_ATSCMH_SGN</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ATSCMH-PRC"><constant>DTV_ATSCMH_PRC</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ATSCMH-RS-FRAME-MODE"><constant>DTV_ATSCMH_RS_FRAME_MODE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ATSCMH-RS-FRAME-ENSEMBLE"><constant>DTV_ATSCMH_RS_FRAME_ENSEMBLE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ATSCMH-RS-CODE-MODE-PRI"><constant>DTV_ATSCMH_RS_CODE_MODE_PRI</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ATSCMH-RS-CODE-MODE-SEC"><constant>DTV_ATSCMH_RS_CODE_MODE_SEC</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ATSCMH-SCCC-BLOCK-MODE"><constant>DTV_ATSCMH_SCCC_BLOCK_MODE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ATSCMH-SCCC-CODE-MODE-A"><constant>DTV_ATSCMH_SCCC_CODE_MODE_A</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ATSCMH-SCCC-CODE-MODE-B"><constant>DTV_ATSCMH_SCCC_CODE_MODE_B</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ATSCMH-SCCC-CODE-MODE-C"><constant>DTV_ATSCMH_SCCC_CODE_MODE_C</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ATSCMH-SCCC-CODE-MODE-D"><constant>DTV_ATSCMH_SCCC_CODE_MODE_D</constant></link></para></listitem> - </itemizedlist> - <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para> - </section> - <section id="dtmb-params"> - <title>DTMB delivery system</title> - <para>The following parameters are valid for DTMB:</para> - <itemizedlist mark='opencircle'> - <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem> - <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem> - <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem> - <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-BANDWIDTH-HZ"><constant>DTV_BANDWIDTH_HZ</constant></link></para></listitem> - <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-INNER-FEC"><constant>DTV_INNER_FEC</constant></link></para></listitem> - <listitem><para><link linkend="DTV-GUARD-INTERVAL"><constant>DTV_GUARD_INTERVAL</constant></link></para></listitem> - <listitem><para><link linkend="DTV-TRANSMISSION-MODE"><constant>DTV_TRANSMISSION_MODE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-INTERLEAVING"><constant>DTV_INTERLEAVING</constant></link></para></listitem> - <listitem><para><link linkend="DTV-LNA"><constant>DTV_LNA</constant></link></para></listitem> - </itemizedlist> - <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para> - </section> - </section> - <section id="frontend-property-cable-systems"> - <title>Properties used on cable delivery systems</title> - <section id="dvbc-params"> - <title>DVB-C delivery system</title> - <para>The DVB-C Annex-A is the widely used cable standard. Transmission uses QAM modulation.</para> - <para>The DVB-C Annex-C is optimized for 6MHz, and is used in Japan. It supports a subset of the Annex A modulation types, and a roll-off of 0.13, instead of 0.15</para> - <para>The following parameters are valid for DVB-C Annex A/C:</para> - <itemizedlist mark='opencircle'> - <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem> - <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem> - <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem> - <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-SYMBOL-RATE"><constant>DTV_SYMBOL_RATE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-INNER-FEC"><constant>DTV_INNER_FEC</constant></link></para></listitem> - <listitem><para><link linkend="DTV-LNA"><constant>DTV_LNA</constant></link></para></listitem> - </itemizedlist> - <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para> - </section> - <section id="dvbc-annex-b-params"> - <title>DVB-C Annex B delivery system</title> - <para>The DVB-C Annex-B is only used on a few Countries like the United States.</para> - <para>The following parameters are valid for DVB-C Annex B:</para> - <itemizedlist mark='opencircle'> - <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem> - <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem> - <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem> - <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-LNA"><constant>DTV_LNA</constant></link></para></listitem> - </itemizedlist> - <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para> - </section> - </section> - <section id="frontend-property-satellite-systems"> - <title>Properties used on satellite delivery systems</title> - <section id="dvbs-params"> - <title>DVB-S delivery system</title> - <para>The following parameters are valid for DVB-S:</para> - <itemizedlist mark='opencircle'> - <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem> - <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem> - <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem> - <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-SYMBOL-RATE"><constant>DTV_SYMBOL_RATE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-INNER-FEC"><constant>DTV_INNER_FEC</constant></link></para></listitem> - <listitem><para><link linkend="DTV-VOLTAGE"><constant>DTV_VOLTAGE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-TONE"><constant>DTV_TONE</constant></link></para></listitem> - </itemizedlist> - <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para> - <para>Future implementations might add those two missing parameters:</para> - <itemizedlist mark='opencircle'> - <listitem><para><link linkend="DTV-DISEQC-MASTER"><constant>DTV_DISEQC_MASTER</constant></link></para></listitem> - <listitem><para><link linkend="DTV-DISEQC-SLAVE-REPLY"><constant>DTV_DISEQC_SLAVE_REPLY</constant></link></para></listitem> - </itemizedlist> - </section> - <section id="dvbs2-params"> - <title>DVB-S2 delivery system</title> - <para>In addition to all parameters valid for DVB-S, DVB-S2 supports the following parameters:</para> - <itemizedlist mark='opencircle'> - <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-PILOT"><constant>DTV_PILOT</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ROLLOFF"><constant>DTV_ROLLOFF</constant></link></para></listitem> - <listitem><para><link linkend="DTV-STREAM-ID"><constant>DTV_STREAM_ID</constant></link></para></listitem> - </itemizedlist> - <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para> - </section> - <section id="turbo-params"> - <title>Turbo code delivery system</title> - <para>In addition to all parameters valid for DVB-S, turbo code supports the following parameters:</para> - <itemizedlist mark='opencircle'> - <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem> - </itemizedlist> - </section> - <section id="isdbs-params"> - <title>ISDB-S delivery system</title> - <para>The following parameters are valid for ISDB-S:</para> - <itemizedlist mark='opencircle'> - <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem> - <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem> - <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem> - <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem> - <listitem><para><link linkend="DTV-SYMBOL-RATE"><constant>DTV_SYMBOL_RATE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-INNER-FEC"><constant>DTV_INNER_FEC</constant></link></para></listitem> - <listitem><para><link linkend="DTV-VOLTAGE"><constant>DTV_VOLTAGE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-STREAM-ID"><constant>DTV_STREAM_ID</constant></link></para></listitem> - </itemizedlist> - </section> - </section> -</section> diff --git a/Documentation/DocBook/media/dvb/dvbstb.pdf b/Documentation/DocBook/media/dvb/dvbstb.pdf Binary files differdeleted file mode 100644 index 0fa75d90c3eb..000000000000 --- a/Documentation/DocBook/media/dvb/dvbstb.pdf +++ /dev/null diff --git a/Documentation/DocBook/media/dvb/examples.xml b/Documentation/DocBook/media/dvb/examples.xml deleted file mode 100644 index 837fb3b64b72..000000000000 --- a/Documentation/DocBook/media/dvb/examples.xml +++ /dev/null @@ -1,367 +0,0 @@ -<title>Examples</title> -<para>In this section we would like to present some examples for using the DVB API. -</para> -<para>NOTE: This section is out of date, and the code below won't even - compile. Please refer to the - <ulink url="https://linuxtv.org/docs/libdvbv5/index.html">libdvbv5</ulink> - for updated/recommended examples. -</para> - -<section id="tuning"> -<title>Tuning</title> -<para>We will start with a generic tuning subroutine that uses the frontend and SEC, as well as -the demux devices. The example is given for QPSK tuners, but can easily be adjusted for -QAM. -</para> -<programlisting> - #include <sys/ioctl.h> - #include <stdio.h> - #include <stdint.h> - #include <sys/types.h> - #include <sys/stat.h> - #include <fcntl.h> - #include <time.h> - #include <unistd.h> - - #include <linux/dvb/dmx.h> - #include <linux/dvb/frontend.h> - #include <linux/dvb/sec.h> - #include <sys/poll.h> - - #define DMX "/dev/dvb/adapter0/demux1" - #define FRONT "/dev/dvb/adapter0/frontend1" - #define SEC "/dev/dvb/adapter0/sec1" - - /⋆ routine for checking if we have a signal and other status information⋆/ - int FEReadStatus(int fd, fe_status_t ⋆stat) - { - int ans; - - if ( (ans = ioctl(fd,FE_READ_STATUS,stat) < 0)){ - perror("FE READ STATUS: "); - return -1; - } - - if (⋆stat & FE_HAS_POWER) - printf("FE HAS POWER\n"); - - if (⋆stat & FE_HAS_SIGNAL) - printf("FE HAS SIGNAL\n"); - - if (⋆stat & FE_SPECTRUM_INV) - printf("SPEKTRUM INV\n"); - - return 0; - } - - - /⋆ tune qpsk ⋆/ - /⋆ freq: frequency of transponder ⋆/ - /⋆ vpid, apid, tpid: PIDs of video, audio and teletext TS packets ⋆/ - /⋆ diseqc: DiSEqC address of the used LNB ⋆/ - /⋆ pol: Polarisation ⋆/ - /⋆ srate: Symbol Rate ⋆/ - /⋆ fec. FEC ⋆/ - /⋆ lnb_lof1: local frequency of lower LNB band ⋆/ - /⋆ lnb_lof2: local frequency of upper LNB band ⋆/ - /⋆ lnb_slof: switch frequency of LNB ⋆/ - - int set_qpsk_channel(int freq, int vpid, int apid, int tpid, - int diseqc, int pol, int srate, int fec, int lnb_lof1, - int lnb_lof2, int lnb_slof) - { - struct secCommand scmd; - struct secCmdSequence scmds; - struct dmx_pes_filter_params pesFilterParams; - FrontendParameters frp; - struct pollfd pfd[1]; - FrontendEvent event; - int demux1, demux2, demux3, front; - - frequency = (uint32_t) freq; - symbolrate = (uint32_t) srate; - - if((front = open(FRONT,O_RDWR)) < 0){ - perror("FRONTEND DEVICE: "); - return -1; - } - - if((sec = open(SEC,O_RDWR)) < 0){ - perror("SEC DEVICE: "); - return -1; - } - - if (demux1 < 0){ - if ((demux1=open(DMX, O_RDWR|O_NONBLOCK)) - < 0){ - perror("DEMUX DEVICE: "); - return -1; - } - } - - if (demux2 < 0){ - if ((demux2=open(DMX, O_RDWR|O_NONBLOCK)) - < 0){ - perror("DEMUX DEVICE: "); - return -1; - } - } - - if (demux3 < 0){ - if ((demux3=open(DMX, O_RDWR|O_NONBLOCK)) - < 0){ - perror("DEMUX DEVICE: "); - return -1; - } - } - - if (freq < lnb_slof) { - frp.Frequency = (freq - lnb_lof1); - scmds.continuousTone = SEC_TONE_OFF; - } else { - frp.Frequency = (freq - lnb_lof2); - scmds.continuousTone = SEC_TONE_ON; - } - frp.Inversion = INVERSION_AUTO; - if (pol) scmds.voltage = SEC_VOLTAGE_18; - else scmds.voltage = SEC_VOLTAGE_13; - - scmd.type=0; - scmd.u.diseqc.addr=0x10; - scmd.u.diseqc.cmd=0x38; - scmd.u.diseqc.numParams=1; - scmd.u.diseqc.params[0] = 0xF0 | ((diseqc ⋆ 4) & 0x0F) | - (scmds.continuousTone == SEC_TONE_ON ? 1 : 0) | - (scmds.voltage==SEC_VOLTAGE_18 ? 2 : 0); - - scmds.miniCommand=SEC_MINI_NONE; - scmds.numCommands=1; - scmds.commands=&scmd; - if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){ - perror("SEC SEND: "); - return -1; - } - - if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){ - perror("SEC SEND: "); - return -1; - } - - frp.u.qpsk.SymbolRate = srate; - frp.u.qpsk.FEC_inner = fec; - - if (ioctl(front, FE_SET_FRONTEND, &frp) < 0){ - perror("QPSK TUNE: "); - return -1; - } - - pfd[0].fd = front; - pfd[0].events = POLLIN; - - if (poll(pfd,1,3000)){ - if (pfd[0].revents & POLLIN){ - printf("Getting QPSK event\n"); - if ( ioctl(front, FE_GET_EVENT, &event) - - == -EOVERFLOW){ - perror("qpsk get event"); - return -1; - } - printf("Received "); - switch(event.type){ - case FE_UNEXPECTED_EV: - printf("unexpected event\n"); - return -1; - case FE_FAILURE_EV: - printf("failure event\n"); - return -1; - - case FE_COMPLETION_EV: - printf("completion event\n"); - } - } - } - - - pesFilterParams.pid = vpid; - pesFilterParams.input = DMX_IN_FRONTEND; - pesFilterParams.output = DMX_OUT_DECODER; - pesFilterParams.pes_type = DMX_PES_VIDEO; - pesFilterParams.flags = DMX_IMMEDIATE_START; - if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ - perror("set_vpid"); - return -1; - } - - pesFilterParams.pid = apid; - pesFilterParams.input = DMX_IN_FRONTEND; - pesFilterParams.output = DMX_OUT_DECODER; - pesFilterParams.pes_type = DMX_PES_AUDIO; - pesFilterParams.flags = DMX_IMMEDIATE_START; - if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ - perror("set_apid"); - return -1; - } - - pesFilterParams.pid = tpid; - pesFilterParams.input = DMX_IN_FRONTEND; - pesFilterParams.output = DMX_OUT_DECODER; - pesFilterParams.pes_type = DMX_PES_TELETEXT; - pesFilterParams.flags = DMX_IMMEDIATE_START; - if (ioctl(demux3, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ - perror("set_tpid"); - return -1; - } - - return has_signal(fds); - } - -</programlisting> -<para>The program assumes that you are using a universal LNB and a standard DiSEqC -switch with up to 4 addresses. Of course, you could build in some more checking if -tuning was successful and maybe try to repeat the tuning process. Depending on the -external hardware, i.e. LNB and DiSEqC switch, and weather conditions this may be -necessary. -</para> -</section> - -<section id="the_dvr_device"> -<title>The DVR device</title> -<para>The following program code shows how to use the DVR device for recording. -</para> -<programlisting> - #include <sys/ioctl.h> - #include <stdio.h> - #include <stdint.h> - #include <sys/types.h> - #include <sys/stat.h> - #include <fcntl.h> - #include <time.h> - #include <unistd.h> - - #include <linux/dvb/dmx.h> - #include <linux/dvb/video.h> - #include <sys/poll.h> - #define DVR "/dev/dvb/adapter0/dvr1" - #define AUDIO "/dev/dvb/adapter0/audio1" - #define VIDEO "/dev/dvb/adapter0/video1" - - #define BUFFY (188⋆20) - #define MAX_LENGTH (1024⋆1024⋆5) /⋆ record 5MB ⋆/ - - - /⋆ switch the demuxes to recording, assuming the transponder is tuned ⋆/ - - /⋆ demux1, demux2: file descriptor of video and audio filters ⋆/ - /⋆ vpid, apid: PIDs of video and audio channels ⋆/ - - int switch_to_record(int demux1, int demux2, uint16_t vpid, uint16_t apid) - { - struct dmx_pes_filter_params pesFilterParams; - - if (demux1 < 0){ - if ((demux1=open(DMX, O_RDWR|O_NONBLOCK)) - < 0){ - perror("DEMUX DEVICE: "); - return -1; - } - } - - if (demux2 < 0){ - if ((demux2=open(DMX, O_RDWR|O_NONBLOCK)) - < 0){ - perror("DEMUX DEVICE: "); - return -1; - } - } - - pesFilterParams.pid = vpid; - pesFilterParams.input = DMX_IN_FRONTEND; - pesFilterParams.output = DMX_OUT_TS_TAP; - pesFilterParams.pes_type = DMX_PES_VIDEO; - pesFilterParams.flags = DMX_IMMEDIATE_START; - if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ - perror("DEMUX DEVICE"); - return -1; - } - pesFilterParams.pid = apid; - pesFilterParams.input = DMX_IN_FRONTEND; - pesFilterParams.output = DMX_OUT_TS_TAP; - pesFilterParams.pes_type = DMX_PES_AUDIO; - pesFilterParams.flags = DMX_IMMEDIATE_START; - if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ - perror("DEMUX DEVICE"); - return -1; - } - return 0; - } - - /⋆ start recording MAX_LENGTH , assuming the transponder is tuned ⋆/ - - /⋆ demux1, demux2: file descriptor of video and audio filters ⋆/ - /⋆ vpid, apid: PIDs of video and audio channels ⋆/ - int record_dvr(int demux1, int demux2, uint16_t vpid, uint16_t apid) - { - int i; - int len; - int written; - uint8_t buf[BUFFY]; - uint64_t length; - struct pollfd pfd[1]; - int dvr, dvr_out; - - /⋆ open dvr device ⋆/ - if ((dvr = open(DVR, O_RDONLY|O_NONBLOCK)) < 0){ - perror("DVR DEVICE"); - return -1; - } - - /⋆ switch video and audio demuxes to dvr ⋆/ - printf ("Switching dvr on\n"); - i = switch_to_record(demux1, demux2, vpid, apid); - printf("finished: "); - - printf("Recording %2.0f MB of test file in TS format\n", - MAX_LENGTH/(1024.0⋆1024.0)); - length = 0; - - /⋆ open output file ⋆/ - if ((dvr_out = open(DVR_FILE,O_WRONLY|O_CREAT - |O_TRUNC, S_IRUSR|S_IWUSR - |S_IRGRP|S_IWGRP|S_IROTH| - S_IWOTH)) < 0){ - perror("Can't open file for dvr test"); - return -1; - } - - pfd[0].fd = dvr; - pfd[0].events = POLLIN; - - /⋆ poll for dvr data and write to file ⋆/ - while (length < MAX_LENGTH ) { - if (poll(pfd,1,1)){ - if (pfd[0].revents & POLLIN){ - len = read(dvr, buf, BUFFY); - if (len < 0){ - perror("recording"); - return -1; - } - if (len > 0){ - written = 0; - while (written < len) - written += - write (dvr_out, - buf, len); - length += len; - printf("written %2.0f MB\r", - length/1024./1024.); - } - } - } - } - return 0; - } - -</programlisting> - -</section> diff --git a/Documentation/DocBook/media/dvb/fe-diseqc-recv-slave-reply.xml b/Documentation/DocBook/media/dvb/fe-diseqc-recv-slave-reply.xml deleted file mode 100644 index 4595dbfff208..000000000000 --- a/Documentation/DocBook/media/dvb/fe-diseqc-recv-slave-reply.xml +++ /dev/null @@ -1,78 +0,0 @@ -<refentry id="FE_DISEQC_RECV_SLAVE_REPLY"> - <refmeta> - <refentrytitle>ioctl FE_DISEQC_RECV_SLAVE_REPLY</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>FE_DISEQC_RECV_SLAVE_REPLY</refname> - <refpurpose>Receives reply from a DiSEqC 2.0 command</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct dvb_diseqc_slave_reply *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fe_fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>FE_DISEQC_RECV_SLAVE_REPLY</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para>pointer to &dvb-diseqc-slave-reply;</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>Receives reply from a DiSEqC 2.0 command.</para> -&return-value-dvb; - -<table pgwide="1" frame="none" id="dvb-diseqc-slave-reply"> - <title>struct <structname>dvb_diseqc_slave_reply</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>uint8_t</entry> - <entry>msg[4]</entry> - <entry>DiSEqC message (framing, data[3])</entry> - </row><row> - <entry>uint8_t</entry> - <entry>msg_len</entry> - <entry>Length of the DiSEqC message. Valid values are 0 to 4, - where 0 means no msg</entry> - </row><row> - <entry>int</entry> - <entry>timeout</entry> - <entry>Return from ioctl after timeout ms with errorcode when no - message was received</entry> - </row> - </tbody> - </tgroup> -</table> - -</refsect1> -</refentry> diff --git a/Documentation/DocBook/media/dvb/fe-diseqc-reset-overload.xml b/Documentation/DocBook/media/dvb/fe-diseqc-reset-overload.xml deleted file mode 100644 index c104df77ecd0..000000000000 --- a/Documentation/DocBook/media/dvb/fe-diseqc-reset-overload.xml +++ /dev/null @@ -1,51 +0,0 @@ -<refentry id="FE_DISEQC_RESET_OVERLOAD"> - <refmeta> - <refentrytitle>ioctl FE_DISEQC_RESET_OVERLOAD</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>FE_DISEQC_RESET_OVERLOAD</refname> - <refpurpose>Restores the power to the antenna subsystem, if it was powered - off due to power overload.</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>NULL</paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fe_fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>FE_DISEQC_RESET_OVERLOAD</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>If the bus has been automatically powered off due to power overload, this ioctl - call restores the power to the bus. The call requires read/write access to the - device. This call has no effect if the device is manually powered off. Not all - DVB adapters support this ioctl.</para> -&return-value-dvb; -</refsect1> -</refentry> diff --git a/Documentation/DocBook/media/dvb/fe-diseqc-send-burst.xml b/Documentation/DocBook/media/dvb/fe-diseqc-send-burst.xml deleted file mode 100644 index 9f6a68f32de3..000000000000 --- a/Documentation/DocBook/media/dvb/fe-diseqc-send-burst.xml +++ /dev/null @@ -1,89 +0,0 @@ -<refentry id="FE_DISEQC_SEND_BURST"> - <refmeta> - <refentrytitle>ioctl FE_DISEQC_SEND_BURST</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>FE_DISEQC_SEND_BURST</refname> - <refpurpose>Sends a 22KHz tone burst for 2x1 mini DiSEqC satellite selection.</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>enum fe_sec_mini_cmd *<parameter>tone</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fe_fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>FE_DISEQC_SEND_BURST</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>tone</parameter></term> - <listitem> - <para>pointer to &fe-sec-mini-cmd;</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - -<para>This ioctl is used to set the generation of a 22kHz tone burst for mini - DiSEqC satellite - selection for 2x1 switches. - This call requires read/write permissions.</para> -<para>It provides support for what's specified at - <ulink url="http://www.eutelsat.com/files/contributed/satellites/pdf/Diseqc/associated%20docs/simple_tone_burst_detec.pdf">Digital Satellite Equipment Control - (DiSEqC) - Simple "ToneBurst" Detection Circuit specification.</ulink> - </para> -&return-value-dvb; -</refsect1> - -<refsect1 id="fe-sec-mini-cmd-t"> -<title>enum fe_sec_mini_cmd</title> - -<table pgwide="1" frame="none" id="fe-sec-mini-cmd"> - <title>enum fe_sec_mini_cmd</title> - <tgroup cols="2"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry align="char" id="SEC-MINI-A"><constant>SEC_MINI_A</constant></entry> - <entry align="char">Sends a mini-DiSEqC 22kHz '0' Tone Burst to - select satellite-A</entry> - </row><row> - <entry align="char" id="SEC-MINI-B"><constant>SEC_MINI_B</constant></entry> - <entry align="char">Sends a mini-DiSEqC 22kHz '1' Data Burst to - select satellite-B</entry> - </row> - </tbody> - </tgroup> -</table> -</refsect1> - -</refentry> diff --git a/Documentation/DocBook/media/dvb/fe-diseqc-send-master-cmd.xml b/Documentation/DocBook/media/dvb/fe-diseqc-send-master-cmd.xml deleted file mode 100644 index 38cf313e121b..000000000000 --- a/Documentation/DocBook/media/dvb/fe-diseqc-send-master-cmd.xml +++ /dev/null @@ -1,72 +0,0 @@ -<refentry id="FE_DISEQC_SEND_MASTER_CMD"> - <refmeta> - <refentrytitle>ioctl FE_DISEQC_SEND_MASTER_CMD</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>FE_DISEQC_SEND_MASTER_CMD</refname> - <refpurpose>Sends a DiSEqC command</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct dvb_diseqc_master_cmd *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fe_fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>FE_DISEQC_SEND_MASTER_CMD</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para>pointer to &dvb-diseqc-master-cmd;</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>Sends a DiSEqC command to the antenna subsystem.</para> -&return-value-dvb; - -<table pgwide="1" frame="none" id="dvb-diseqc-master-cmd"> - <title>struct <structname>dvb_diseqc_master_cmd</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>uint8_t</entry> - <entry>msg[6]</entry> - <entry>DiSEqC message (framing, address, command, data[3])</entry> - </row><row> - <entry>uint8_t</entry> - <entry>msg_len</entry> - <entry>Length of the DiSEqC message. Valid values are 3 to 6</entry> - </row> - </tbody> - </tgroup> -</table> - -</refsect1> -</refentry> diff --git a/Documentation/DocBook/media/dvb/fe-enable-high-lnb-voltage.xml b/Documentation/DocBook/media/dvb/fe-enable-high-lnb-voltage.xml deleted file mode 100644 index c11890b184ad..000000000000 --- a/Documentation/DocBook/media/dvb/fe-enable-high-lnb-voltage.xml +++ /dev/null @@ -1,61 +0,0 @@ -<refentry id="FE_ENABLE_HIGH_LNB_VOLTAGE"> - <refmeta> - <refentrytitle>ioctl FE_ENABLE_HIGH_LNB_VOLTAGE</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>FE_ENABLE_HIGH_LNB_VOLTAGE</refname> - <refpurpose>Select output DC level between normal LNBf voltages or higher - LNBf voltages.</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>unsigned int <parameter>high</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fe_fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>FE_ENABLE_HIGH_LNB_VOLTAGE</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>high</parameter></term> - <listitem> - <para>Valid flags:</para> - <itemizedlist> - <listitem><para>0 - normal 13V and 18V.</para></listitem> - <listitem><para>>0 - enables slightly higher voltages instead of - 13/18V, in order to compensate for long antenna cables.</para></listitem> - </itemizedlist> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>Select output DC level between normal LNBf voltages or higher - LNBf voltages between 0 (normal) or a value grater than 0 for higher - voltages.</para> -&return-value-dvb; -</refsect1> -</refentry> diff --git a/Documentation/DocBook/media/dvb/fe-get-info.xml b/Documentation/DocBook/media/dvb/fe-get-info.xml deleted file mode 100644 index ed0eeb29dd65..000000000000 --- a/Documentation/DocBook/media/dvb/fe-get-info.xml +++ /dev/null @@ -1,266 +0,0 @@ -<refentry id="FE_GET_INFO"> - <refmeta> - <refentrytitle>ioctl FE_GET_INFO</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>FE_GET_INFO</refname> - <refpurpose>Query DVB frontend capabilities and returns information about - the front-end. This call only requires read-only access to the device</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct dvb_frontend_info *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fe_fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>FE_GET_INFO</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para>pointer to struct &dvb-frontend-info;</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>All DVB frontend devices support the -<constant>FE_GET_INFO</constant> ioctl. It is used to identify -kernel devices compatible with this specification and to obtain -information about driver and hardware capabilities. The ioctl takes a -pointer to dvb_frontend_info which is filled by the driver. When the -driver is not compatible with this specification the ioctl returns an error. -</para> -&return-value-dvb; - - <table pgwide="1" frame="none" id="dvb-frontend-info"> - <title>struct <structname>dvb_frontend_info</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>char</entry> - <entry>name[128]</entry> - <entry>Name of the frontend</entry> - </row><row> - <entry>fe_type_t</entry> - <entry>type</entry> - <entry><emphasis role="bold">DEPRECATED</emphasis>. DVBv3 type. Should not be used on modern programs, as a - frontend may have more than one type. So, the DVBv5 API should - be used instead to enumerate and select the frontend type.</entry> - </row><row> - <entry>uint32_t</entry> - <entry>frequency_min</entry> - <entry>Minimal frequency supported by the frontend</entry> - </row><row> - <entry>uint32_t</entry> - <entry>frequency_max</entry> - <entry>Maximal frequency supported by the frontend</entry> - </row><row> - <entry>uint32_t</entry> - <entry>frequency_stepsize</entry> - <entry>Frequency step - all frequencies are multiple of this value</entry> - </row><row> - <entry>uint32_t</entry> - <entry>frequency_tolerance</entry> - <entry>Tolerance of the frequency</entry> - </row><row> - <entry>uint32_t</entry> - <entry>symbol_rate_min</entry> - <entry>Minimal symbol rate (for Cable/Satellite systems), in bauds</entry> - </row><row> - <entry>uint32_t</entry> - <entry>symbol_rate_max</entry> - <entry>Maximal symbol rate (for Cable/Satellite systems), in bauds</entry> - </row><row> - <entry>uint32_t</entry> - <entry>symbol_rate_tolerance</entry> - <entry>Maximal symbol rate tolerance, in ppm</entry> - </row><row> - <entry>uint32_t</entry> - <entry>notifier_delay</entry> - <entry><emphasis role="bold">DEPRECATED</emphasis>. Not used by any driver.</entry> - </row><row> - <entry>&fe-caps;</entry> - <entry>caps</entry> - <entry>Capabilities supported by the frontend</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>NOTE: The frequencies are specified in Hz for Terrestrial and Cable - systems. They're specified in kHz for Satellite systems</para> - </refsect1> - -<refsect1 id="fe-caps-t"> -<title>frontend capabilities</title> - -<para>Capabilities describe what a frontend can do. Some capabilities are - supported only on some specific frontend types.</para> - -<table pgwide="1" frame="none" id="fe-caps"> - <title>enum fe_caps</title> - <tgroup cols="2"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry id="FE-IS-STUPID"><constant>FE_IS_STUPID</constant></entry> - <entry>There's something wrong at the frontend, and it can't - report its capabilities</entry> - </row> - <row> - <entry id="FE-CAN-INVERSION-AUTO"><constant>FE_CAN_INVERSION_AUTO</constant></entry> - <entry>The frontend is capable of auto-detecting inversion</entry> - </row> - <row> - <entry id="FE-CAN-FEC-1-2"><constant>FE_CAN_FEC_1_2</constant></entry> - <entry>The frontend supports FEC 1/2</entry> - </row> - <row> - <entry id="FE-CAN-FEC-2-3"><constant>FE_CAN_FEC_2_3</constant></entry> - <entry>The frontend supports FEC 2/3</entry> - </row> - <row> - <entry id="FE-CAN-FEC-3-4"><constant>FE_CAN_FEC_3_4</constant></entry> - <entry>The frontend supports FEC 3/4</entry> - </row> - <row> - <entry id="FE-CAN-FEC-4-5"><constant>FE_CAN_FEC_4_5</constant></entry> - <entry>The frontend supports FEC 4/5</entry> - </row> - <row> - <entry id="FE-CAN-FEC-5-6"><constant>FE_CAN_FEC_5_6</constant></entry> - <entry>The frontend supports FEC 5/6</entry> - </row> - <row> - <entry id="FE-CAN-FEC-6-7"><constant>FE_CAN_FEC_6_7</constant></entry> - <entry>The frontend supports FEC 6/7</entry> - </row> - <row> - <entry id="FE-CAN-FEC-7-8"><constant>FE_CAN_FEC_7_8</constant></entry> - <entry>The frontend supports FEC 7/8</entry> - </row> - <row> - <entry id="FE-CAN-FEC-8-9"><constant>FE_CAN_FEC_8_9</constant></entry> - <entry>The frontend supports FEC 8/9</entry> - </row> - <row> - <entry id="FE-CAN-FEC-AUTO"><constant>FE_CAN_FEC_AUTO</constant></entry> - <entry>The frontend can autodetect FEC.</entry> - </row> - <row> - <entry id="FE-CAN-QPSK"><constant>FE_CAN_QPSK</constant></entry> - <entry>The frontend supports QPSK modulation</entry> - </row> - <row> - <entry id="FE-CAN-QAM-16"><constant>FE_CAN_QAM_16</constant></entry> - <entry>The frontend supports 16-QAM modulation</entry> - </row> - <row> - <entry id="FE-CAN-QAM-32"><constant>FE_CAN_QAM_32</constant></entry> - <entry>The frontend supports 32-QAM modulation</entry> - </row> - <row> - <entry id="FE-CAN-QAM-64"><constant>FE_CAN_QAM_64</constant></entry> - <entry>The frontend supports 64-QAM modulation</entry> - </row> - <row> - <entry id="FE-CAN-QAM-128"><constant>FE_CAN_QAM_128</constant></entry> - <entry>The frontend supports 128-QAM modulation</entry> - </row> - <row> - <entry id="FE-CAN-QAM-256"><constant>FE_CAN_QAM_256</constant></entry> - <entry>The frontend supports 256-QAM modulation</entry> - </row> - <row> - <entry id="FE-CAN-QAM-AUTO"><constant>FE_CAN_QAM_AUTO</constant></entry> - <entry>The frontend can autodetect modulation</entry> - </row> - <row> - <entry id="FE-CAN-TRANSMISSION-MODE-AUTO"><constant>FE_CAN_TRANSMISSION_MODE_AUTO</constant></entry> - <entry>The frontend can autodetect the transmission mode</entry> - </row> - <row> - <entry id="FE-CAN-BANDWIDTH-AUTO"><constant>FE_CAN_BANDWIDTH_AUTO</constant></entry> - <entry>The frontend can autodetect the bandwidth</entry> - </row> - <row> - <entry id="FE-CAN-GUARD-INTERVAL-AUTO"><constant>FE_CAN_GUARD_INTERVAL_AUTO</constant></entry> - <entry>The frontend can autodetect the guard interval</entry> - </row> - <row> - <entry id="FE-CAN-HIERARCHY-AUTO"><constant>FE_CAN_HIERARCHY_AUTO</constant></entry> - <entry>The frontend can autodetect hierarch</entry> - </row> - <row> - <entry id="FE-CAN-8VSB"><constant>FE_CAN_8VSB</constant></entry> - <entry>The frontend supports 8-VSB modulation</entry> - </row> - <row> - <entry id="FE-CAN-16VSB"><constant>FE_CAN_16VSB</constant></entry> - <entry>The frontend supports 16-VSB modulation</entry> - </row> - <row> - <entry id="FE-HAS-EXTENDED-CAPS"><constant>FE_HAS_EXTENDED_CAPS</constant></entry> - <entry>Currently, unused</entry> - </row> - <row> - <entry id="FE-CAN-MULTISTREAM"><constant>FE_CAN_MULTISTREAM</constant></entry> - <entry>The frontend supports multistream filtering</entry> - </row> - <row> - <entry id="FE-CAN-TURBO-FEC"><constant>FE_CAN_TURBO_FEC</constant></entry> - <entry>The frontend supports turbo FEC modulation</entry> - </row> - <row> - <entry id="FE-CAN-2G-MODULATION"><constant>FE_CAN_2G_MODULATION</constant></entry> - <entry>The frontend supports "2nd generation modulation" (DVB-S2/T2)></entry> - </row> - <row> - <entry id="FE-NEEDS-BENDING"><constant>FE_NEEDS_BENDING</constant></entry> - <entry>Not supported anymore, don't use it</entry> - </row> - <row> - <entry id="FE-CAN-RECOVER"><constant>FE_CAN_RECOVER</constant></entry> - <entry>The frontend can recover from a cable unplug automatically</entry> - </row> - <row> - <entry id="FE-CAN-MUTE-TS"><constant>FE_CAN_MUTE_TS</constant></entry> - <entry>The frontend can stop spurious TS data output</entry> - </row> - </tbody> - </tgroup> -</table> -</refsect1> -</refentry> diff --git a/Documentation/DocBook/media/dvb/fe-get-property.xml b/Documentation/DocBook/media/dvb/fe-get-property.xml deleted file mode 100644 index 53a170ed3bd1..000000000000 --- a/Documentation/DocBook/media/dvb/fe-get-property.xml +++ /dev/null @@ -1,81 +0,0 @@ -<refentry id="FE_GET_PROPERTY"> - <refmeta> - <refentrytitle>ioctl FE_SET_PROPERTY, FE_GET_PROPERTY</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>FE_SET_PROPERTY</refname> - <refname>FE_GET_PROPERTY</refname> - <refpurpose>FE_SET_PROPERTY sets one or more frontend properties. - FE_GET_PROPERTY returns one or more frontend properties.</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct dtv_properties *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fe_fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>FE_SET_PROPERTY, FE_GET_PROPERTY</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para>pointer to &dtv-properties;</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>All DVB frontend devices support the -<constant>FE_SET_PROPERTY</constant> and <constant>FE_GET_PROPERTY</constant> -ioctls. The supported properties and statistics depends on the delivery system -and on the device:</para> -<itemizedlist> -<listitem> - <para><constant>FE_SET_PROPERTY:</constant></para> -<itemizedlist> -<listitem><para>This ioctl is used to set one or more - frontend properties.</para></listitem> -<listitem><para>This is the basic command to request the frontend to tune into some - frequency and to start decoding the digital TV signal.</para></listitem> -<listitem><para>This call requires read/write access to the device.</para></listitem> -<listitem><para>At return, the values are updated to reflect the - actual parameters used.</para></listitem> -</itemizedlist> -</listitem> -<listitem> - <para><constant>FE_GET_PROPERTY:</constant></para> -<itemizedlist> -<listitem><para>This ioctl is used to get properties and -statistics from the frontend.</para></listitem> -<listitem><para>No properties are changed, and statistics aren't reset.</para></listitem> -<listitem><para>This call only requires read-only access to the device.</para></listitem> -</itemizedlist> -</listitem> -</itemizedlist> -&return-value-dvb; -</refsect1> -</refentry> diff --git a/Documentation/DocBook/media/dvb/fe-read-status.xml b/Documentation/DocBook/media/dvb/fe-read-status.xml deleted file mode 100644 index bc0dc2a55f19..000000000000 --- a/Documentation/DocBook/media/dvb/fe-read-status.xml +++ /dev/null @@ -1,107 +0,0 @@ -<refentry id="FE_READ_STATUS"> - <refmeta> - <refentrytitle>ioctl FE_READ_STATUS</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>FE_READ_STATUS</refname> - <refpurpose>Returns status information about the front-end. This call only - requires read-only access to the device</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>unsigned int *<parameter>status</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fe_fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>FE_READ_STATUS</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>status</parameter></term> - <listitem> - <para>pointer to a bitmask integer filled with the values defined by - &fe-status;.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>All DVB frontend devices support the -<constant>FE_READ_STATUS</constant> ioctl. It is used to check about the -locking status of the frontend after being tuned. The ioctl takes a -pointer to an integer where the status will be written. -</para> -<para>NOTE: the size of status is actually sizeof(enum fe_status), with varies - according with the architecture. This needs to be fixed in the future.</para> -&return-value-dvb; -</refsect1> - -<refsect1 id="fe-status-t"> -<title>int fe_status</title> - -<para>The fe_status parameter is used to indicate the current state - and/or state changes of the frontend hardware. It is produced using - the &fe-status; values on a bitmask</para> - -<table pgwide="1" frame="none" id="fe-status"> - <title>enum fe_status</title> - <tgroup cols="2"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry align="char" id="FE-HAS-SIGNAL"><constant>FE_HAS_SIGNAL</constant></entry> - <entry align="char">The frontend has found something above the noise level</entry> - </row><row> - <entry align="char" id="FE-HAS-CARRIER"><constant>FE_HAS_CARRIER</constant></entry> - <entry align="char">The frontend has found a DVB signal</entry> - </row><row> - <entry align="char" id="FE-HAS-VITERBI"><constant>FE_HAS_VITERBI</constant></entry> - <entry align="char">The frontend FEC inner coding (Viterbi, LDPC or other inner code) is stable</entry> - </row><row> - <entry align="char" id="FE-HAS-SYNC"><constant>FE_HAS_SYNC</constant></entry> - <entry align="char">Synchronization bytes was found</entry> - </row><row> - <entry align="char" id="FE-HAS-LOCK"><constant>FE_HAS_LOCK</constant></entry> - <entry align="char">The DVB were locked and everything is working</entry> - </row><row> - <entry align="char" id="FE-TIMEDOUT"><constant>FE_TIMEDOUT</constant></entry> - <entry align="char">no lock within the last about 2 seconds</entry> - </row><row> - <entry align="char" id="FE-REINIT"><constant>FE_REINIT</constant></entry> - <entry align="char">The frontend was reinitialized, application is - recommended to reset DiSEqC, tone and parameters</entry> - </row> - </tbody> - </tgroup> -</table> -</refsect1> -</refentry> diff --git a/Documentation/DocBook/media/dvb/fe-set-frontend-tune-mode.xml b/Documentation/DocBook/media/dvb/fe-set-frontend-tune-mode.xml deleted file mode 100644 index 99fa8a015c7a..000000000000 --- a/Documentation/DocBook/media/dvb/fe-set-frontend-tune-mode.xml +++ /dev/null @@ -1,64 +0,0 @@ -<refentry id="FE_SET_FRONTEND_TUNE_MODE"> - <refmeta> - <refentrytitle>ioctl FE_SET_FRONTEND_TUNE_MODE</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>FE_SET_FRONTEND_TUNE_MODE</refname> - <refpurpose>Allow setting tuner mode flags to the frontend.</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>unsigned int <parameter>flags</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fe_fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>FE_SET_FRONTEND_TUNE_MODE</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>flags</parameter></term> - <listitem> - <para>Valid flags:</para> - <itemizedlist> - <listitem><para>0 - normal tune mode</para></listitem> - <listitem><para>FE_TUNE_MODE_ONESHOT - When set, this flag will - disable any zigzagging or other "normal" tuning behaviour. - Additionally, there will be no automatic monitoring of the - lock status, and hence no frontend events will be - generated. If a frontend device is closed, this flag will - be automatically turned off when the device is reopened - read-write.</para></listitem> - </itemizedlist> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>Allow setting tuner mode flags to the frontend, between 0 (normal) - or FE_TUNE_MODE_ONESHOT mode</para> -&return-value-dvb; -</refsect1> -</refentry> diff --git a/Documentation/DocBook/media/dvb/fe-set-tone.xml b/Documentation/DocBook/media/dvb/fe-set-tone.xml deleted file mode 100644 index 62d44e4ccc39..000000000000 --- a/Documentation/DocBook/media/dvb/fe-set-tone.xml +++ /dev/null @@ -1,91 +0,0 @@ -<refentry id="FE_SET_TONE"> - <refmeta> - <refentrytitle>ioctl FE_SET_TONE</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>FE_SET_TONE</refname> - <refpurpose>Sets/resets the generation of the continuous 22kHz tone.</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>enum fe_sec_tone_mode *<parameter>tone</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fe_fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>FE_SET_TONE</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>tone</parameter></term> - <listitem> - <para>pointer to &fe-sec-tone-mode;</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - -<para>This ioctl is used to set the generation of the continuous 22kHz tone. - This call requires read/write permissions.</para> -<para>Usually, satellite antenna subsystems require that the digital TV - device to send a 22kHz tone in order to select between high/low band on - some dual-band LNBf. It is also used to send signals to DiSEqC equipment, - but this is done using the DiSEqC ioctls.</para> -<para>NOTE: if more than one device is connected to the same antenna, - setting a tone may interfere on other devices, as they may lose - the capability of selecting the band. So, it is recommended that - applications would change to SEC_TONE_OFF when the device is not used.</para> - -&return-value-dvb; -</refsect1> - -<refsect1 id="fe-sec-tone-mode-t"> -<title>enum fe_sec_tone_mode</title> - -<table pgwide="1" frame="none" id="fe-sec-tone-mode"> - <title>enum fe_sec_tone_mode</title> - <tgroup cols="2"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry align="char" id="SEC-TONE-ON"><constant>SEC_TONE_ON</constant></entry> - <entry align="char">Sends a 22kHz tone burst to the antenna</entry> - </row><row> - <entry align="char" id="SEC-TONE-OFF"><constant>SEC_TONE_OFF</constant></entry> - <entry align="char">Don't send a 22kHz tone to the antenna - (except if the FE_DISEQC_* ioctls are called)</entry> - </row> - </tbody> - </tgroup> -</table> -</refsect1> - -</refentry> diff --git a/Documentation/DocBook/media/dvb/fe-set-voltage.xml b/Documentation/DocBook/media/dvb/fe-set-voltage.xml deleted file mode 100644 index c89a6f79b5af..000000000000 --- a/Documentation/DocBook/media/dvb/fe-set-voltage.xml +++ /dev/null @@ -1,69 +0,0 @@ -<refentry id="FE_SET_VOLTAGE"> - <refmeta> - <refentrytitle>ioctl FE_SET_VOLTAGE</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>FE_SET_VOLTAGE</refname> - <refpurpose>Allow setting the DC level sent to the antenna subsystem.</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>enum fe_sec_voltage *<parameter>voltage</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fe_fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>FE_SET_VOLTAGE</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>voltage</parameter></term> - <listitem> - <para>pointer to &fe-sec-voltage;</para> - <para>Valid values are described at &fe-sec-voltage;.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - -<para>This ioctl allows to set the DC voltage level sent through the antenna - cable to 13V, 18V or off.</para> -<para>Usually, a satellite antenna subsystems require that the digital TV - device to send a DC voltage to feed power to the LNBf. Depending on the - LNBf type, the polarization or the intermediate frequency (IF) of the LNBf - can controlled by the voltage level. Other devices (for example, the ones - that implement DISEqC and multipoint LNBf's don't need to control the - voltage level, provided that either 13V or 18V is sent to power up the - LNBf.</para> -<para>NOTE: if more than one device is connected to the same antenna, - setting a voltage level may interfere on other devices, as they may lose - the capability of setting polarization or IF. So, on those - cases, setting the voltage to SEC_VOLTAGE_OFF while the device is not is - used is recommended.</para> - -&return-value-dvb; -</refsect1> - -</refentry> diff --git a/Documentation/DocBook/media/dvb/frontend.xml b/Documentation/DocBook/media/dvb/frontend.xml deleted file mode 100644 index 01210b33c130..000000000000 --- a/Documentation/DocBook/media/dvb/frontend.xml +++ /dev/null @@ -1,269 +0,0 @@ -<title>DVB Frontend API</title> - -<para>The DVB frontend API was designed to support three types of delivery systems:</para> -<itemizedlist> - <listitem><para>Terrestrial systems: DVB-T, DVB-T2, ATSC, ATSC M/H, ISDB-T, DVB-H, DTMB, CMMB</para></listitem> - <listitem><para>Cable systems: DVB-C Annex A/C, ClearQAM (DVB-C Annex B), ISDB-C</para></listitem> - <listitem><para>Satellite systems: DVB-S, DVB-S2, DVB Turbo, ISDB-S, DSS</para></listitem> -</itemizedlist> -<para>The DVB frontend controls several sub-devices including:</para> -<itemizedlist> - <listitem><para>Tuner</para></listitem> - <listitem><para>Digital TV demodulator</para></listitem> - <listitem><para>Low noise amplifier (LNA)</para></listitem> - <listitem><para>Satellite Equipment Control (SEC) hardware (only for Satellite).</para></listitem> -</itemizedlist> -<para>The frontend can be accessed through - <constant>/dev/dvb/adapter?/frontend?</constant>. Data types and - ioctl definitions can be accessed by including - <constant>linux/dvb/frontend.h</constant> in your application. -</para> - -<para>NOTE: Transmission via the internet (DVB-IP) - is not yet handled by this API but a future extension is possible.</para> -<para>On Satellite systems, the API support for the Satellite Equipment Control - (SEC) allows to power control and to send/receive signals to control the - antenna subsystem, selecting the polarization and choosing the Intermediate - Frequency IF) of the Low Noise Block Converter Feed Horn (LNBf). It - supports the DiSEqC and V-SEC protocols. The DiSEqC (digital SEC) -specification is available at -<ulink url="http://www.eutelsat.com/satellites/4_5_5.html">Eutelsat</ulink>.</para> - -<section id="query-dvb-frontend-info"> -<title>Querying frontend information</title> - -<para>Usually, the first thing to do when the frontend is opened is to - check the frontend capabilities. This is done using <link linkend="FE_GET_INFO">FE_GET_INFO</link>. This ioctl will enumerate - the DVB API version and other characteristics about the frontend, and - can be opened either in read only or read/write mode.</para> -</section> - -<section id="dvb-fe-read-status"> -<title>Querying frontend status and statistics</title> - -<para>Once <link linkend="FE_GET_PROPERTY"><constant>FE_SET_PROPERTY</constant></link> - is called, the frontend will run a kernel thread that will periodically - check for the tuner lock status and provide statistics about the quality - of the signal.</para> -<para>The information about the frontend tuner locking status can be queried - using <link linkend="FE_READ_STATUS">FE_READ_STATUS</link>.</para> -<para>Signal statistics are provided via <link linkend="FE_GET_PROPERTY"><constant>FE_GET_PROPERTY</constant></link>. - Please note that several statistics require the demodulator to be fully - locked (e. g. with FE_HAS_LOCK bit set). See - <link linkend="frontend-stat-properties">Frontend statistics indicators</link> - for more details.</para> -</section> - -&sub-dvbproperty; - -<section id="frontend_fcalls"> -<title>Frontend Function Calls</title> - -<refentry id="frontend_f_open"> - <refmeta> - <refentrytitle>DVB frontend open()</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>fe-open</refname> - <refpurpose>Open a frontend device</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <fcntl.h></funcsynopsisinfo> - <funcprototype> - <funcdef>int <function>open</function></funcdef> - <paramdef>const char *<parameter>device_name</parameter></paramdef> - <paramdef>int <parameter>flags</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>device_name</parameter></term> - <listitem> - <para>Device to be opened.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>flags</parameter></term> - <listitem> - <para>Open flags. Access can either be - <constant>O_RDWR</constant> or <constant>O_RDONLY</constant>.</para> - <para>Multiple opens are allowed with <constant>O_RDONLY</constant>. In this mode, only query and read ioctls are allowed.</para> - <para>Only one open is allowed in <constant>O_RDWR</constant>. In this mode, all ioctls are allowed.</para> - <para>When the <constant>O_NONBLOCK</constant> flag is given, the system calls may return &EAGAIN; when no data is available or when the device driver is temporarily busy.</para> - <para>Other flags have no effect.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - <refsect1> - <title>Description</title> - <para>This system call opens a named frontend device (<constant>/dev/dvb/adapter?/frontend?</constant>) - for subsequent use. Usually the first thing to do after a successful open is to - find out the frontend type with <link linkend="FE_GET_INFO">FE_GET_INFO</link>.</para> -<para>The device can be opened in read-only mode, which only allows monitoring of - device status and statistics, or read/write mode, which allows any kind of use - (e.g. performing tuning operations.) -</para> -<para>In a system with multiple front-ends, it is usually the case that multiple devices - cannot be open in read/write mode simultaneously. As long as a front-end - device is opened in read/write mode, other open() calls in read/write mode will - either fail or block, depending on whether non-blocking or blocking mode was - specified. A front-end device opened in blocking mode can later be put into - non-blocking mode (and vice versa) using the F_SETFL command of the fcntl - system call. This is a standard system call, documented in the Linux manual - page for fcntl. When an open() call has succeeded, the device will be ready - for use in the specified mode. This implies that the corresponding hardware is - powered up, and that other front-ends may have been powered down to make - that possible.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success <function>open</function> returns the new file -descriptor. On error -1 is returned, and the <varname>errno</varname> -variable is set appropriately. Possible error codes are:</para> - - <variablelist> - <varlistentry> - <term><errorcode>EACCES</errorcode></term> - <listitem> - <para>The caller has no permission to access the -device.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EBUSY</errorcode></term> - <listitem> - <para>The the device driver is already in use.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>ENXIO</errorcode></term> - <listitem> - <para>No device corresponding to this device special file -exists.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>ENOMEM</errorcode></term> - <listitem> - <para>Not enough kernel memory was available to complete the -request.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EMFILE</errorcode></term> - <listitem> - <para>The process already has the maximum number of -files open.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>ENFILE</errorcode></term> - <listitem> - <para>The limit on the total number of files open on the -system has been reached.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>ENODEV</errorcode></term> - <listitem> - <para>The device got removed.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> - -<refentry id="frontend_f_close"> - <refmeta> - <refentrytitle>DVB frontend close()</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>fe-close</refname> - <refpurpose>Close a frontend device</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <unistd.h></funcsynopsisinfo> - <funcprototype> - <funcdef>int <function>close</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> -<para>This system call closes a previously opened front-end device. After closing - a front-end device, its corresponding hardware might be powered down - automatically.</para> -</refsect1> - <refsect1> - <title>Return Value</title> - - <para>The function returns <returnvalue>0</returnvalue> on -success, <returnvalue>-1</returnvalue> on failure and the -<varname>errno</varname> is set appropriately. Possible error -codes:</para> - - <variablelist> - <varlistentry> - <term><errorcode>EBADF</errorcode></term> - <listitem> - <para><parameter>fd</parameter> is not a valid open file -descriptor.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> - -&sub-fe-get-info; -&sub-fe-read-status; -&sub-fe-get-property; -&sub-fe-diseqc-reset-overload; -&sub-fe-diseqc-send-master-cmd; -&sub-fe-diseqc-recv-slave-reply; -&sub-fe-diseqc-send-burst; -&sub-fe-set-tone; -&sub-fe-set-voltage; -&sub-fe-enable-high-lnb-voltage; -&sub-fe-set-frontend-tune-mode; - -</section> - -<section id="frontend_legacy_dvbv3_api"> -<title>DVB Frontend legacy API (a. k. a. DVBv3)</title> -<para>The usage of this API is deprecated, as it doesn't support all digital - TV standards, doesn't provide good statistics measurements and provides - incomplete information. This is kept only to support legacy applications.</para> - -&sub-frontend_legacy_api; -</section> diff --git a/Documentation/DocBook/media/dvb/frontend_legacy_api.xml b/Documentation/DocBook/media/dvb/frontend_legacy_api.xml deleted file mode 100644 index 8fadf3a4ba44..000000000000 --- a/Documentation/DocBook/media/dvb/frontend_legacy_api.xml +++ /dev/null @@ -1,654 +0,0 @@ -<section id="frontend_legacy_types"> -<title>Frontend Legacy Data Types</title> - -<section id="fe-type-t"> -<title>Frontend type</title> - -<para>For historical reasons, frontend types are named by the type of modulation - used in transmission. The fontend types are given by fe_type_t type, defined as:</para> - -<table pgwide="1" frame="none" id="fe-type"> -<title>Frontend types</title> -<tgroup cols="3"> - &cs-def; - <thead> - <row> - <entry>fe_type</entry> - <entry>Description</entry> - <entry><link linkend="DTV-DELIVERY-SYSTEM">DTV_DELIVERY_SYSTEM</link> equivalent type</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry id="FE-QPSK"><constant>FE_QPSK</constant></entry> - <entry>For DVB-S standard</entry> - <entry><constant>SYS_DVBS</constant></entry> - </row> - <row> - <entry id="FE-QAM"><constant>FE_QAM</constant></entry> - <entry>For DVB-C annex A standard</entry> - <entry><constant>SYS_DVBC_ANNEX_A</constant></entry> - </row> - <row> - <entry id="FE-OFDM"><constant>FE_OFDM</constant></entry> - <entry>For DVB-T standard</entry> - <entry><constant>SYS_DVBT</constant></entry> - </row> - <row> - <entry id="FE-ATSC"><constant>FE_ATSC</constant></entry> - <entry>For ATSC standard (terrestrial) or for DVB-C Annex B (cable) used in US.</entry> - <entry><constant>SYS_ATSC</constant> (terrestrial) or <constant>SYS_DVBC_ANNEX_B</constant> (cable)</entry> - </row> -</tbody></tgroup></table> - -<para>Newer formats like DVB-S2, ISDB-T, ISDB-S and DVB-T2 are not described at the above, as they're -supported via the new <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY/FE_GET_SET_PROPERTY</link> ioctl's, using the <link linkend="DTV-DELIVERY-SYSTEM">DTV_DELIVERY_SYSTEM</link> parameter. -</para> - -<para>In the old days, &dvb-frontend-info; used to contain - <constant>fe_type_t</constant> field to indicate the delivery systems, - filled with either FE_QPSK, FE_QAM, FE_OFDM or FE_ATSC. While this is - still filled to keep backward compatibility, the usage of this - field is deprecated, as it can report just one delivery system, but some - devices support multiple delivery systems. Please use - <link linkend="DTV-ENUM-DELSYS">DTV_ENUM_DELSYS</link> instead. -</para> -<para>On devices that support multiple delivery systems, - &dvb-frontend-info;::<constant>fe_type_t</constant> is filled with the - currently standard, as selected by the last call to - <link linkend="FE_GET_PROPERTY">FE_SET_PROPERTY</link> - using the &DTV-DELIVERY-SYSTEM; property.</para> -</section> - -<section id="fe-bandwidth-t"> -<title>Frontend bandwidth</title> - -<table pgwide="1" frame="none" id="fe-bandwidth"> - <title>enum fe_bandwidth</title> - <tgroup cols="2"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry id="BANDWIDTH-AUTO"><constant>BANDWIDTH_AUTO</constant></entry> - <entry>Autodetect bandwidth (if supported)</entry> - </row><row> - <entry id="BANDWIDTH-1-712-MHZ"><constant>BANDWIDTH_1_712_MHZ</constant></entry> - <entry>1.712 MHz</entry> - </row><row> - <entry id="BANDWIDTH-5-MHZ"><constant>BANDWIDTH_5_MHZ</constant></entry> - <entry>5 MHz</entry> - </row><row> - <entry id="BANDWIDTH-6-MHZ"><constant>BANDWIDTH_6_MHZ</constant></entry> - <entry>6 MHz</entry> - </row><row> - <entry id="BANDWIDTH-7-MHZ"><constant>BANDWIDTH_7_MHZ</constant></entry> - <entry>7 MHz</entry> - </row><row> - <entry id="BANDWIDTH-8-MHZ"><constant>BANDWIDTH_8_MHZ</constant></entry> - <entry>8 MHz</entry> - </row><row> - <entry id="BANDWIDTH-10-MHZ"><constant>BANDWIDTH_10_MHZ</constant></entry> - <entry>10 MHz</entry> - </row> - </tbody> - </tgroup> -</table> - -</section> - -<section id="dvb-frontend-parameters"> -<title>frontend parameters</title> -<para>The kind of parameters passed to the frontend device for tuning depend on -the kind of hardware you are using.</para> -<para>The struct <constant>dvb_frontend_parameters</constant> uses an -union with specific per-system parameters. However, as newer delivery systems -required more data, the structure size weren't enough to fit, and just -extending its size would break the existing applications. So, those parameters -were replaced by the usage of <link linkend="FE_GET_PROPERTY"> -<constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant></link> ioctl's. The -new API is flexible enough to add new parameters to existing delivery systems, -and to add newer delivery systems.</para> -<para>So, newer applications should use <link linkend="FE_GET_PROPERTY"> -<constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant></link> instead, in -order to be able to support the newer System Delivery like DVB-S2, DVB-T2, -DVB-C2, ISDB, etc.</para> -<para>All kinds of parameters are combined as an union in the FrontendParameters structure: -<programlisting> -struct dvb_frontend_parameters { - uint32_t frequency; /⋆ (absolute) frequency in Hz for QAM/OFDM ⋆/ - /⋆ intermediate frequency in kHz for QPSK ⋆/ - &fe-spectral-inversion-t; inversion; - union { - struct dvb_qpsk_parameters qpsk; - struct dvb_qam_parameters qam; - struct dvb_ofdm_parameters ofdm; - struct dvb_vsb_parameters vsb; - } u; -}; -</programlisting></para> -<para>In the case of QPSK frontends the <constant>frequency</constant> field specifies the intermediate -frequency, i.e. the offset which is effectively added to the local oscillator frequency (LOF) of -the LNB. The intermediate frequency has to be specified in units of kHz. For QAM and -OFDM frontends the <constant>frequency</constant> specifies the absolute frequency and is given in Hz. -</para> - -<section id="dvb-qpsk-parameters"> -<title>QPSK parameters</title> -<para>For satellite QPSK frontends you have to use the <constant>dvb_qpsk_parameters</constant> structure:</para> -<programlisting> - struct dvb_qpsk_parameters { - uint32_t symbol_rate; /⋆ symbol rate in Symbols per second ⋆/ - &fe-code-rate-t; fec_inner; /⋆ forward error correction (see above) ⋆/ - }; -</programlisting> -</section> - -<section id="dvb-qam-parameters"> -<title>QAM parameters</title> -<para>for cable QAM frontend you use the <constant>dvb_qam_parameters</constant> structure:</para> -<programlisting> - struct dvb_qam_parameters { - uint32_t symbol_rate; /⋆ symbol rate in Symbols per second ⋆/ - &fe-code-rate-t; fec_inner; /⋆ forward error correction (see above) ⋆/ - &fe-modulation-t; modulation; /⋆ modulation type (see above) ⋆/ - }; -</programlisting> -</section> - -<section id="dvb-vsb-parameters"> -<title>VSB parameters</title> -<para>ATSC frontends are supported by the <constant>dvb_vsb_parameters</constant> structure:</para> -<programlisting> -struct dvb_vsb_parameters { - &fe-modulation-t; modulation; /⋆ modulation type (see above) ⋆/ -}; -</programlisting> -</section> - -<section id="dvb-ofdm-parameters"> -<title>OFDM parameters</title> -<para>DVB-T frontends are supported by the <constant>dvb_ofdm_parameters</constant> structure:</para> -<programlisting> - struct dvb_ofdm_parameters { - &fe-bandwidth-t; bandwidth; - &fe-code-rate-t; code_rate_HP; /⋆ high priority stream code rate ⋆/ - &fe-code-rate-t; code_rate_LP; /⋆ low priority stream code rate ⋆/ - &fe-modulation-t; constellation; /⋆ modulation type (see above) ⋆/ - &fe-transmit-mode-t; transmission_mode; - &fe-guard-interval-t; guard_interval; - &fe-hierarchy-t; hierarchy_information; - }; -</programlisting> -</section> -</section> - -<section id="dvb-frontend-event"> -<title>frontend events</title> - <programlisting> - struct dvb_frontend_event { - fe_status_t status; - struct dvb_frontend_parameters parameters; - }; -</programlisting> - </section> -</section> - -<section id="frontend_legacy_fcalls"> -<title>Frontend Legacy Function Calls</title> - -<para>Those functions are defined at DVB version 3. The support is kept in - the kernel due to compatibility issues only. Their usage is strongly - not recommended</para> - -<section id="FE_READ_BER"> -<title>FE_READ_BER</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call returns the bit error rate for the signal currently - received/demodulated by the front-end. For this command, read-only access to - the device is sufficient.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = <link linkend="FE_READ_BER">FE_READ_BER</link>, - uint32_t ⋆ber);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals <link linkend="FE_READ_BER">FE_READ_BER</link> for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>uint32_t *ber</para> -</entry><entry - align="char"> -<para>The bit error rate is stored into *ber.</para> -</entry> - </row></tbody></tgroup></informaltable> - -&return-value-dvb; -</section> - -<section id="FE_READ_SNR"> -<title>FE_READ_SNR</title> - -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call returns the signal-to-noise ratio for the signal currently received - by the front-end. For this command, read-only access to the device is sufficient.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = <link linkend="FE_READ_SNR">FE_READ_SNR</link>, uint16_t - ⋆snr);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals <link linkend="FE_READ_SNR">FE_READ_SNR</link> for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>uint16_t *snr</para> -</entry><entry - align="char"> -<para>The signal-to-noise ratio is stored into *snr.</para> -</entry> - </row></tbody></tgroup></informaltable> - -&return-value-dvb; -</section> - -<section id="FE_READ_SIGNAL_STRENGTH"> -<title>FE_READ_SIGNAL_STRENGTH</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call returns the signal strength value for the signal currently received - by the front-end. For this command, read-only access to the device is sufficient.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl( int fd, int request = - <link linkend="FE_READ_SIGNAL_STRENGTH">FE_READ_SIGNAL_STRENGTH</link>, uint16_t ⋆strength);</para> -</entry> - </row></tbody></tgroup></informaltable> - -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals <link linkend="FE_READ_SIGNAL_STRENGTH">FE_READ_SIGNAL_STRENGTH</link> for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>uint16_t *strength</para> -</entry><entry - align="char"> -<para>The signal strength value is stored into *strength.</para> -</entry> - </row></tbody></tgroup></informaltable> - -&return-value-dvb; -</section> - -<section id="FE_READ_UNCORRECTED_BLOCKS"> -<title>FE_READ_UNCORRECTED_BLOCKS</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call returns the number of uncorrected blocks detected by the device - driver during its lifetime. For meaningful measurements, the increment in block - count during a specific time interval should be calculated. For this command, - read-only access to the device is sufficient.</para> -</entry> - </row><row><entry - align="char"> -<para>Note that the counter will wrap to zero after its maximum count has been - reached.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl( int fd, int request = - <link linkend="FE_READ_UNCORRECTED_BLOCKS">FE_READ_UNCORRECTED_BLOCKS</link>, uint32_t ⋆ublocks);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals <link linkend="FE_READ_UNCORRECTED_BLOCKS">FE_READ_UNCORRECTED_BLOCKS</link> for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>uint32_t *ublocks</para> -</entry><entry - align="char"> -<para>The total number of uncorrected blocks seen by the driver - so far.</para> -</entry> - </row></tbody></tgroup></informaltable> - -&return-value-dvb; -</section> - -<section id="FE_SET_FRONTEND"> -<title>FE_SET_FRONTEND</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call starts a tuning operation using specified parameters. The result - of this call will be successful if the parameters were valid and the tuning could - be initiated. The result of the tuning operation in itself, however, will arrive - asynchronously as an event (see documentation for <link linkend="FE_GET_EVENT">FE_GET_EVENT</link> and - FrontendEvent.) If a new <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> operation is initiated before - the previous one was completed, the previous operation will be aborted in favor - of the new one. This command requires read/write access to the device.</para> -</entry> - </row></tbody></tgroup></informaltable> - -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link>, - struct dvb_frontend_parameters ⋆p);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct - dvb_frontend_parameters - *p</para> -</entry><entry - align="char"> -<para>Points to parameters for tuning operation.</para> -</entry> - </row></tbody></tgroup></informaltable> - -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Maximum supported symbol rate reached.</para> -</entry> -</row></tbody></tgroup></informaltable> -</section> - -<section id="FE_GET_FRONTEND"> -<title>FE_GET_FRONTEND</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call queries the currently effective frontend parameters. For this - command, read-only access to the device is sufficient.</para> -</entry> - </row></tbody></tgroup></informaltable> - -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = <link linkend="FE_GET_FRONTEND">FE_GET_FRONTEND</link>, - struct dvb_frontend_parameters ⋆p);</para> -</entry> - </row></tbody></tgroup></informaltable> - -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct - dvb_frontend_parameters - *p</para> -</entry><entry - align="char"> -<para>Points to parameters for tuning operation.</para> -</entry> - </row></tbody></tgroup></informaltable> - -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Maximum supported symbol rate reached.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section> - -<section id="FE_GET_EVENT"> -<title>FE_GET_EVENT</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call returns a frontend event if available. If an event is not - available, the behavior depends on whether the device is in blocking or - non-blocking mode. In the latter case, the call fails immediately with errno - set to EWOULDBLOCK. In the former case, the call blocks until an event - becomes available.</para> -</entry> - </row><row><entry - align="char"> -<para>The standard Linux poll() and/or select() system calls can be used with the - device file descriptor to watch for new events. For select(), the file descriptor - should be included in the exceptfds argument, and for poll(), POLLPRI should - be specified as the wake-up condition. Since the event queue allocated is - rather small (room for 8 events), the queue must be serviced regularly to avoid - overflow. If an overflow happens, the oldest event is discarded from the queue, - and an error (EOVERFLOW) occurs the next time the queue is read. After - reporting the error condition in this fashion, subsequent - <link linkend="FE_GET_EVENT">FE_GET_EVENT</link> - calls will return events from the queue as usual.</para> -</entry> - </row><row><entry - align="char"> -<para>For the sake of implementation simplicity, this command requires read/write - access to the device.</para> -</entry> - </row></tbody></tgroup></informaltable> - -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = QPSK_GET_EVENT, - struct dvb_frontend_event ⋆ev);</para> -</entry> - </row></tbody></tgroup></informaltable> - -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals <link linkend="FE_GET_EVENT">FE_GET_EVENT</link> for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct - dvb_frontend_event - *ev</para> -</entry><entry - align="char"> -<para>Points to the location where the event,</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>if any, is to be stored.</para> -</entry> - </row></tbody></tgroup></informaltable> - -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EWOULDBLOCK</para> -</entry><entry - align="char"> -<para>There is no event pending, and the device is in - non-blocking mode.</para> -</entry> - </row><row><entry - align="char"> -<para>EOVERFLOW</para> -</entry><entry - align="char"> -<para>Overflow in event queue - one or more events were lost.</para> -</entry> -</row></tbody></tgroup></informaltable> -</section> - -<section id="FE_DISHNETWORK_SEND_LEGACY_CMD"> - <title>FE_DISHNETWORK_SEND_LEGACY_CMD</title> -<para>DESCRIPTION</para> -<informaltable><tgroup cols="1"><tbody><row> -<entry align="char"> -<para>WARNING: This is a very obscure legacy command, used only at stv0299 driver. Should not be used on newer drivers.</para> -<para>It provides a non-standard method for selecting Diseqc voltage on the frontend, for Dish Network legacy switches.</para> -<para>As support for this ioctl were added in 2004, this means that such dishes were already legacy in 2004.</para> -</entry> -</row></tbody></tgroup></informaltable> - -<para>SYNOPSIS</para> -<informaltable><tgroup cols="1"><tbody><row> -<entry align="char"> -<para>int ioctl(int fd, int request = - <link linkend="FE_DISHNETWORK_SEND_LEGACY_CMD">FE_DISHNETWORK_SEND_LEGACY_CMD</link>, unsigned long cmd);</para> -</entry> -</row></tbody></tgroup></informaltable> - -<para>PARAMETERS</para> -<informaltable><tgroup cols="2"><tbody><row> -<entry align="char"> - <para>unsigned long cmd</para> -</entry> -<entry align="char"> -<para> -sends the specified raw cmd to the dish via DISEqC. -</para> -</entry> - </row></tbody></tgroup></informaltable> - -&return-value-dvb; -</section> - -</section> diff --git a/Documentation/DocBook/media/dvb/intro.xml b/Documentation/DocBook/media/dvb/intro.xml deleted file mode 100644 index b5b701f5d8c2..000000000000 --- a/Documentation/DocBook/media/dvb/intro.xml +++ /dev/null @@ -1,211 +0,0 @@ -<title>Introduction</title> - -<section id="requisites"> -<title>What you need to know</title> - -<para>The reader of this document is required to have some knowledge in -the area of digital video broadcasting (DVB) and should be familiar with -part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), i.e -you should know what a program/transport stream (PS/TS) is and what is -meant by a packetized elementary stream (PES) or an I-frame.</para> - -<para>Various DVB standards documents are available from -<ulink url="http://www.dvb.org" /> and/or -<ulink url="http://www.etsi.org" />.</para> - -<para>It is also necessary to know how to access unix/linux devices and -how to use ioctl calls. This also includes the knowledge of C or C++. -</para> -</section> - -<section id="history"> -<title>History</title> - -<para>The first API for DVB cards we used at Convergence in late 1999 -was an extension of the Video4Linux API which was primarily developed -for frame grabber cards. As such it was not really well suited to be -used for DVB cards and their new features like recording MPEG streams -and filtering several section and PES data streams at the same time. -</para> - -<para>In early 2000, we were approached by Nokia with a proposal for a -new standard Linux DVB API. As a commitment to the development of -terminals based on open standards, Nokia and Convergence made it -available to all Linux developers and published it on -<ulink url="https://linuxtv.org" /> in September 2000. -Convergence is the maintainer of the Linux DVB API. Together with the -LinuxTV community (i.e. you, the reader of this document), the Linux DVB -API will be constantly reviewed and improved. With the Linux driver for -the Siemens/Hauppauge DVB PCI card Convergence provides a first -implementation of the Linux DVB API.</para> -</section> - -<section id="overview"> -<title>Overview</title> - -<figure id="stb_components"> -<title>Components of a DVB card/STB</title> -<mediaobject> -<imageobject> -<imagedata fileref="dvbstb.pdf" format="PS" /> -</imageobject> -<imageobject> -<imagedata fileref="dvbstb.png" format="PNG" /> -</imageobject> -</mediaobject> -</figure> - -<para>A DVB PCI card or DVB set-top-box (STB) usually consists of the -following main hardware components: </para> - -<itemizedlist> - <listitem> - -<para>Frontend consisting of tuner and DVB demodulator</para> - -<para>Here the raw signal reaches the DVB hardware from a satellite dish -or antenna or directly from cable. The frontend down-converts and -demodulates this signal into an MPEG transport stream (TS). In case of a -satellite frontend, this includes a facility for satellite equipment -control (SEC), which allows control of LNB polarization, multi feed -switches or dish rotors.</para> - -</listitem> - <listitem> - -<para>Conditional Access (CA) hardware like CI adapters and smartcard slots -</para> - -<para>The complete TS is passed through the CA hardware. Programs to -which the user has access (controlled by the smart card) are decoded in -real time and re-inserted into the TS.</para> - -</listitem> - <listitem> - <para>Demultiplexer which filters the incoming DVB stream</para> - -<para>The demultiplexer splits the TS into its components like audio and -video streams. Besides usually several of such audio and video streams -it also contains data streams with information about the programs -offered in this or other streams of the same provider.</para> - -</listitem> -<listitem> - -<para>MPEG2 audio and video decoder</para> - -<para>The main targets of the demultiplexer are the MPEG2 audio and -video decoders. After decoding they pass on the uncompressed audio and -video to the computer screen or (through a PAL/NTSC encoder) to a TV -set.</para> - - -</listitem> -</itemizedlist> - -<para><xref linkend="stb_components" /> shows a crude schematic of the control and data flow -between those components.</para> - -<para>On a DVB PCI card not all of these have to be present since some -functionality can be provided by the main CPU of the PC (e.g. MPEG -picture and sound decoding) or is not needed (e.g. for data-only uses -like “internet over satellite”). Also not every card or STB -provides conditional access hardware.</para> - -</section> - -<section id="dvb_devices"> -<title>Linux DVB Devices</title> - -<para>The Linux DVB API lets you control these hardware components -through currently six Unix-style character devices for video, audio, -frontend, demux, CA and IP-over-DVB networking. The video and audio -devices control the MPEG2 decoder hardware, the frontend device the -tuner and the DVB demodulator. The demux device gives you control over -the PES and section filters of the hardware. If the hardware does not -support filtering these filters can be implemented in software. Finally, -the CA device controls all the conditional access capabilities of the -hardware. It can depend on the individual security requirements of the -platform, if and how many of the CA functions are made available to the -application through this device.</para> - -<para>All devices can be found in the <constant>/dev</constant> -tree under <constant>/dev/dvb</constant>. The individual devices -are called:</para> - -<itemizedlist> -<listitem> - -<para><constant>/dev/dvb/adapterN/audioM</constant>,</para> -</listitem> -<listitem> -<para><constant>/dev/dvb/adapterN/videoM</constant>,</para> -</listitem> -<listitem> -<para><constant>/dev/dvb/adapterN/frontendM</constant>,</para> -</listitem> - <listitem> - -<para><constant>/dev/dvb/adapterN/netM</constant>,</para> -</listitem> - <listitem> - -<para><constant>/dev/dvb/adapterN/demuxM</constant>,</para> -</listitem> - <listitem> - -<para><constant>/dev/dvb/adapterN/dvrM</constant>,</para> -</listitem> - <listitem> - -<para><constant>/dev/dvb/adapterN/caM</constant>,</para></listitem></itemizedlist> - -<para>where N enumerates the DVB PCI cards in a system starting -from 0, and M enumerates the devices of each type within each -adapter, starting from 0, too. We will omit the “ -<constant>/dev/dvb/adapterN/</constant>” in the further discussion -of these devices.</para> - -<para>More details about the data structures and function calls of all -the devices are described in the following chapters.</para> - -</section> - -<section id="include_files"> -<title>API include files</title> - -<para>For each of the DVB devices a corresponding include file exists. -The DVB API include files should be included in application sources with -a partial path like:</para> - -<programlisting> - #include <linux/dvb/audio.h> -</programlisting> -<programlisting> - #include <linux/dvb/ca.h> -</programlisting> -<programlisting> - #include <linux/dvb/dmx.h> -</programlisting> -<programlisting> - #include <linux/dvb/frontend.h> -</programlisting> -<programlisting> - #include <linux/dvb/net.h> -</programlisting> -<programlisting> - #include <linux/dvb/osd.h> -</programlisting> -<programlisting> - #include <linux/dvb/video.h> -</programlisting> - -<para>To enable applications to support different API version, an -additional include file -<constant>linux/dvb/version.h</constant> exists, which defines the -constant <constant>DVB_API_VERSION</constant>. This document -describes <constant>DVB_API_VERSION 5.10</constant>. -</para> - -</section> - diff --git a/Documentation/DocBook/media/dvb/net.xml b/Documentation/DocBook/media/dvb/net.xml deleted file mode 100644 index d2e44b7e07df..000000000000 --- a/Documentation/DocBook/media/dvb/net.xml +++ /dev/null @@ -1,238 +0,0 @@ -<title>DVB Network API</title> -<para>The DVB net device controls the mapping of data packages that are - part of a transport stream to be mapped into a virtual network interface, - visible through the standard Linux network protocol stack.</para> -<para>Currently, two encapsulations are supported:</para> -<itemizedlist> - <listitem><para><ulink url="http://en.wikipedia.org/wiki/Multiprotocol_Encapsulation"> - Multi Protocol Encapsulation (MPE)</ulink></para></listitem> - <listitem><para><ulink url="http://en.wikipedia.org/wiki/Unidirectional_Lightweight_Encapsulation"> - Ultra Lightweight Encapsulation (ULE)</ulink></para></listitem> -</itemizedlist> - -<para>In order to create the Linux virtual network interfaces, an application - needs to tell to the Kernel what are the PIDs and the encapsulation types - that are present on the transport stream. This is done through - <constant>/dev/dvb/adapter?/net?</constant> device node. - The data will be available via virtual <constant>dvb?_?</constant> - network interfaces, and will be controled/routed via the standard - ip tools (like ip, route, netstat, ifconfig, etc).</para> -<para> Data types and and ioctl definitions are defined via - <constant>linux/dvb/net.h</constant> header.</para> - -<section id="net_fcalls"> -<title>DVB net Function Calls</title> - - -<refentry id="NET_ADD_IF"> - <refmeta> - <refentrytitle>ioctl NET_ADD_IF</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>NET_ADD_IF</refname> - <refpurpose>Creates a new network interface for a given Packet ID.</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct dvb_net_if *<parameter>net_if</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fe_fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>FE_SET_TONE</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>net_if</parameter></term> - <listitem> - <para>pointer to &dvb-net-if;</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - -<para>The NET_ADD_IF ioctl system call selects the Packet ID (PID) that - contains a TCP/IP traffic, the type of encapsulation to be used (MPE or ULE) - and the interface number for the new interface to be created. When the - system call successfully returns, a new virtual network interface is created.</para> -<para>The &dvb-net-if;::ifnum field will be filled with the number of the - created interface.</para> - -&return-value-dvb; -</refsect1> - -<refsect1 id="dvb-net-if-t"> -<title>struct <structname>dvb_net_if</structname> description</title> - -<table pgwide="1" frame="none" id="dvb-net-if"> - <title>struct <structname>dvb_net_if</structname></title> - <tgroup cols="2"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry align="char">pid</entry> - <entry align="char">Packet ID (PID) of the MPEG-TS that contains - data</entry> - </row><row> - <entry align="char">ifnum</entry> - <entry align="char">number of the DVB interface.</entry> - </row><row> - <entry align="char">feedtype</entry> - <entry align="char">Encapsulation type of the feed. It can be: - <constant>DVB_NET_FEEDTYPE_MPE</constant> for MPE encoding - or - <constant>DVB_NET_FEEDTYPE_ULE</constant> for ULE encoding. - </entry> - </row> - </tbody> - </tgroup> -</table> -</refsect1> -</refentry> - -<refentry id="NET_REMOVE_IF"> - <refmeta> - <refentrytitle>ioctl NET_REMOVE_IF</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>NET_REMOVE_IF</refname> - <refpurpose>Removes a network interface.</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>int <parameter>ifnum</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fe_fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>FE_SET_TONE</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>net_if</parameter></term> - <listitem> - <para>number of the interface to be removed</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - -<para>The NET_REMOVE_IF ioctl deletes an interface previously created - via &NET-ADD-IF;.</para> - -&return-value-dvb; -</refsect1> -</refentry> - - -<refentry id="NET_GET_IF"> - <refmeta> - <refentrytitle>ioctl NET_GET_IF</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>NET_GET_IF</refname> - <refpurpose>Read the configuration data of an interface created via - &NET-ADD-IF;.</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct dvb_net_if *<parameter>net_if</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fe_fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>FE_SET_TONE</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>net_if</parameter></term> - <listitem> - <para>pointer to &dvb-net-if;</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - -<para>The NET_GET_IF ioctl uses the interface number given by the - &dvb-net-if;::ifnum field and fills the content of &dvb-net-if; with - the packet ID and encapsulation type used on such interface. If the - interface was not created yet with &NET-ADD-IF;, it will return -1 and - fill the <constant>errno</constant> with <constant>EINVAL</constant> - error code.</para> - -&return-value-dvb; -</refsect1> -</refentry> -</section> diff --git a/Documentation/DocBook/media/dvb/video.xml b/Documentation/DocBook/media/dvb/video.xml deleted file mode 100644 index 71547fcd7ba0..000000000000 --- a/Documentation/DocBook/media/dvb/video.xml +++ /dev/null @@ -1,1968 +0,0 @@ -<title>DVB Video Device</title> -<para>The DVB video device controls the MPEG2 video decoder of the DVB hardware. It -can be accessed through <emphasis role="bold">/dev/dvb/adapter0/video0</emphasis>. Data types and and -ioctl definitions can be accessed by including <emphasis role="bold">linux/dvb/video.h</emphasis> in your -application. -</para> -<para>Note that the DVB video device only controls decoding of the MPEG video stream, not -its presentation on the TV or computer screen. On PCs this is typically handled by an -associated video4linux device, e.g. <emphasis role="bold">/dev/video</emphasis>, which allows scaling and defining output -windows. -</para> -<para>Some DVB cards don’t have their own MPEG decoder, which results in the omission of -the audio and video device as well as the video4linux device. -</para> -<para>The ioctls that deal with SPUs (sub picture units) and navigation packets are only -supported on some MPEG decoders made for DVD playback. -</para> -<para> -These ioctls were also used by V4L2 to control MPEG decoders implemented in V4L2. The use -of these ioctls for that purpose has been made obsolete and proper V4L2 ioctls or controls -have been created to replace that functionality.</para> -<section id="video_types"> -<title>Video Data Types</title> - -<section id="video-format-t"> -<title>video_format_t</title> -<para>The <constant>video_format_t</constant> data type defined by -</para> -<programlisting> -typedef enum { - VIDEO_FORMAT_4_3, /⋆ Select 4:3 format ⋆/ - VIDEO_FORMAT_16_9, /⋆ Select 16:9 format. ⋆/ - VIDEO_FORMAT_221_1 /⋆ 2.21:1 ⋆/ -} video_format_t; -</programlisting> -<para>is used in the VIDEO_SET_FORMAT function (??) to tell the driver which aspect ratio -the output hardware (e.g. TV) has. It is also used in the data structures video_status -(??) returned by VIDEO_GET_STATUS (??) and video_event (??) returned by -VIDEO_GET_EVENT (??) which report about the display format of the current video -stream. -</para> -</section> - -<section id="video-displayformat-t"> -<title>video_displayformat_t</title> -<para>In case the display format of the video stream and of the display hardware differ the -application has to specify how to handle the cropping of the picture. This can be done using -the VIDEO_SET_DISPLAY_FORMAT call (??) which accepts -</para> -<programlisting> -typedef enum { - VIDEO_PAN_SCAN, /⋆ use pan and scan format ⋆/ - VIDEO_LETTER_BOX, /⋆ use letterbox format ⋆/ - VIDEO_CENTER_CUT_OUT /⋆ use center cut out format ⋆/ -} video_displayformat_t; -</programlisting> -<para>as argument. -</para> -</section> - -<section id="video-stream-source-t"> -<title>video_stream_source_t</title> -<para>The video stream source is set through the VIDEO_SELECT_SOURCE call and can take -the following values, depending on whether we are replaying from an internal (demuxer) or -external (user write) source. -</para> -<programlisting> -typedef enum { - VIDEO_SOURCE_DEMUX, /⋆ Select the demux as the main source ⋆/ - VIDEO_SOURCE_MEMORY /⋆ If this source is selected, the stream - comes from the user through the write - system call ⋆/ -} video_stream_source_t; -</programlisting> -<para>VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the frontend or the -DVR device) as the source of the video stream. If VIDEO_SOURCE_MEMORY -is selected the stream comes from the application through the <emphasis role="bold">write()</emphasis> system -call. -</para> -</section> - -<section id="video-play-state-t"> -<title>video_play_state_t</title> -<para>The following values can be returned by the VIDEO_GET_STATUS call representing the -state of video playback. -</para> -<programlisting> -typedef enum { - VIDEO_STOPPED, /⋆ Video is stopped ⋆/ - VIDEO_PLAYING, /⋆ Video is currently playing ⋆/ - VIDEO_FREEZED /⋆ Video is freezed ⋆/ -} video_play_state_t; -</programlisting> -</section> - -<section id="video-command"> -<title>struct video_command</title> -<para>The structure must be zeroed before use by the application -This ensures it can be extended safely in the future.</para> -<programlisting> -struct video_command { - __u32 cmd; - __u32 flags; - union { - struct { - __u64 pts; - } stop; - - struct { - /⋆ 0 or 1000 specifies normal speed, - 1 specifies forward single stepping, - -1 specifies backward single stepping, - >>1: playback at speed/1000 of the normal speed, - <-1: reverse playback at (-speed/1000) of the normal speed. ⋆/ - __s32 speed; - __u32 format; - } play; - - struct { - __u32 data[16]; - } raw; - }; -}; -</programlisting> -</section> - -<section id="video-size-t"> -<title>video_size_t</title> -<programlisting> -typedef struct { - int w; - int h; - video_format_t aspect_ratio; -} video_size_t; -</programlisting> -</section> - - -<section id="video-event"> -<title>struct video_event</title> -<para>The following is the structure of a video event as it is returned by the VIDEO_GET_EVENT -call. -</para> -<programlisting> -struct video_event { - __s32 type; -#define VIDEO_EVENT_SIZE_CHANGED 1 -#define VIDEO_EVENT_FRAME_RATE_CHANGED 2 -#define VIDEO_EVENT_DECODER_STOPPED 3 -#define VIDEO_EVENT_VSYNC 4 - __kernel_time_t timestamp; - union { - video_size_t size; - unsigned int frame_rate; /⋆ in frames per 1000sec ⋆/ - unsigned char vsync_field; /⋆ unknown/odd/even/progressive ⋆/ - } u; -}; -</programlisting> -</section> - -<section id="video-status"> -<title>struct video_status</title> -<para>The VIDEO_GET_STATUS call returns the following structure informing about various -states of the playback operation. -</para> -<programlisting> -struct video_status { - int video_blank; /⋆ blank video on freeze? ⋆/ - video_play_state_t play_state; /⋆ current state of playback ⋆/ - video_stream_source_t stream_source; /⋆ current source (demux/memory) ⋆/ - video_format_t video_format; /⋆ current aspect ratio of stream ⋆/ - video_displayformat_t display_format;/⋆ selected cropping mode ⋆/ -}; -</programlisting> -<para>If video_blank is set video will be blanked out if the channel is changed or if playback is -stopped. Otherwise, the last picture will be displayed. play_state indicates if the video is -currently frozen, stopped, or being played back. The stream_source corresponds to the seleted -source for the video stream. It can come either from the demultiplexer or from memory. -The video_format indicates the aspect ratio (one of 4:3 or 16:9) of the currently -played video stream. Finally, display_format corresponds to the selected cropping -mode in case the source video format is not the same as the format of the output -device. -</para> -</section> - -<section id="video-still-picture"> -<title>struct video_still_picture</title> -<para>An I-frame displayed via the VIDEO_STILLPICTURE call is passed on within the -following structure. -</para> -<programlisting> -/⋆ pointer to and size of a single iframe in memory ⋆/ -struct video_still_picture { - char ⋆iFrame; /⋆ pointer to a single iframe in memory ⋆/ - int32_t size; -}; -</programlisting> -</section> - -<section id="video_caps"> -<title>video capabilities</title> -<para>A call to VIDEO_GET_CAPABILITIES returns an unsigned integer with the following -bits set according to the hardwares capabilities. -</para> -<programlisting> - /⋆ bit definitions for capabilities: ⋆/ - /⋆ can the hardware decode MPEG1 and/or MPEG2? ⋆/ - #define VIDEO_CAP_MPEG1 1 - #define VIDEO_CAP_MPEG2 2 - /⋆ can you send a system and/or program stream to video device? - (you still have to open the video and the audio device but only - send the stream to the video device) ⋆/ - #define VIDEO_CAP_SYS 4 - #define VIDEO_CAP_PROG 8 - /⋆ can the driver also handle SPU, NAVI and CSS encoded data? - (CSS API is not present yet) ⋆/ - #define VIDEO_CAP_SPU 16 - #define VIDEO_CAP_NAVI 32 - #define VIDEO_CAP_CSS 64 -</programlisting> -</section> - -<section id="video-system"> -<title>video_system_t</title> -<para>A call to VIDEO_SET_SYSTEM sets the desired video system for TV output. The -following system types can be set: -</para> -<programlisting> -typedef enum { - VIDEO_SYSTEM_PAL, - VIDEO_SYSTEM_NTSC, - VIDEO_SYSTEM_PALN, - VIDEO_SYSTEM_PALNc, - VIDEO_SYSTEM_PALM, - VIDEO_SYSTEM_NTSC60, - VIDEO_SYSTEM_PAL60, - VIDEO_SYSTEM_PALM60 -} video_system_t; -</programlisting> -</section> - -<section id="video-highlight"> -<title>struct video_highlight</title> -<para>Calling the ioctl VIDEO_SET_HIGHLIGHTS posts the SPU highlight information. The -call expects the following format for that information: -</para> -<programlisting> - typedef - struct video_highlight { - boolean active; /⋆ 1=show highlight, 0=hide highlight ⋆/ - uint8_t contrast1; /⋆ 7- 4 Pattern pixel contrast ⋆/ - /⋆ 3- 0 Background pixel contrast ⋆/ - uint8_t contrast2; /⋆ 7- 4 Emphasis pixel-2 contrast ⋆/ - /⋆ 3- 0 Emphasis pixel-1 contrast ⋆/ - uint8_t color1; /⋆ 7- 4 Pattern pixel color ⋆/ - /⋆ 3- 0 Background pixel color ⋆/ - uint8_t color2; /⋆ 7- 4 Emphasis pixel-2 color ⋆/ - /⋆ 3- 0 Emphasis pixel-1 color ⋆/ - uint32_t ypos; /⋆ 23-22 auto action mode ⋆/ - /⋆ 21-12 start y ⋆/ - /⋆ 9- 0 end y ⋆/ - uint32_t xpos; /⋆ 23-22 button color number ⋆/ - /⋆ 21-12 start x ⋆/ - /⋆ 9- 0 end x ⋆/ - } video_highlight_t; -</programlisting> - -</section> -<section id="video-spu"> -<title>struct video_spu</title> -<para>Calling VIDEO_SET_SPU deactivates or activates SPU decoding, according to the -following format: -</para> -<programlisting> - typedef - struct video_spu { - boolean active; - int stream_id; - } video_spu_t; -</programlisting> - -</section> -<section id="video-spu-palette"> -<title>struct video_spu_palette</title> -<para>The following structure is used to set the SPU palette by calling VIDEO_SPU_PALETTE: -</para> -<programlisting> - typedef - struct video_spu_palette { - int length; - uint8_t ⋆palette; - } video_spu_palette_t; -</programlisting> - -</section> -<section id="video-navi-pack"> -<title>struct video_navi_pack</title> -<para>In order to get the navigational data the following structure has to be passed to the ioctl -VIDEO_GET_NAVI: -</para> -<programlisting> - typedef - struct video_navi_pack { - int length; /⋆ 0 ... 1024 ⋆/ - uint8_t data[1024]; - } video_navi_pack_t; -</programlisting> -</section> - - -<section id="video-attributes-t"> -<title>video_attributes_t</title> -<para>The following attributes can be set by a call to VIDEO_SET_ATTRIBUTES: -</para> -<programlisting> - typedef uint16_t video_attributes_t; - /⋆ bits: descr. ⋆/ - /⋆ 15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) ⋆/ - /⋆ 13-12 TV system (0=525/60, 1=625/50) ⋆/ - /⋆ 11-10 Aspect ratio (0=4:3, 3=16:9) ⋆/ - /⋆ 9- 8 permitted display mode on 4:3 monitor (0=both, 1=only pan-sca ⋆/ - /⋆ 7 line 21-1 data present in GOP (1=yes, 0=no) ⋆/ - /⋆ 6 line 21-2 data present in GOP (1=yes, 0=no) ⋆/ - /⋆ 5- 3 source resolution (0=720x480/576, 1=704x480/576, 2=352x480/57 ⋆/ - /⋆ 2 source letterboxed (1=yes, 0=no) ⋆/ - /⋆ 0 film/camera mode (0=camera, 1=film (625/50 only)) ⋆/ -</programlisting> -</section></section> - - -<section id="video_function_calls"> -<title>Video Function Calls</title> - - -<section id="video_fopen"> -<title>open()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This system call opens a named video device (e.g. /dev/dvb/adapter0/video0) - for subsequent use.</para> -<para>When an open() call has succeeded, the device will be ready for use. - The significance of blocking or non-blocking mode is described in the - documentation for functions where there is a difference. It does not affect the - semantics of the open() call itself. A device opened in blocking mode can later - be put into non-blocking mode (and vice versa) using the F_SETFL command - of the fcntl system call. This is a standard system call, documented in the Linux - manual page for fcntl. Only one user can open the Video Device in O_RDWR - mode. All other attempts to open the device in this mode will fail, and an - error-code will be returned. If the Video Device is opened in O_RDONLY - mode, the only ioctl call that can be used is VIDEO_GET_STATUS. All other - call will return an error code.</para> -</entry> - </row></tbody></tgroup></informaltable> - -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int open(const char ⋆deviceName, int flags);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>const char - *deviceName</para> -</entry><entry - align="char"> -<para>Name of specific video device.</para> -</entry> - </row><row><entry - align="char"> -<para>int flags</para> -</entry><entry - align="char"> -<para>A bit-wise OR of the following flags:</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_RDONLY read-only access</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_RDWR read/write access</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_NONBLOCK open in non-blocking mode</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>(blocking mode is the default)</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURN VALUE</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>ENODEV</para> -</entry><entry - align="char"> -<para>Device driver not loaded/available.</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error.</para> -</entry> - </row><row><entry - align="char"> -<para>EBUSY</para> -</entry><entry - align="char"> -<para>Device or resource busy.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Invalid argument.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section> -<section id="video_fclose"> -<title>close()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This system call closes a previously opened video device.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int close(int fd);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURN VALUE</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section> -<section id="video_fwrite"> -<title>write()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This system call can only be used if VIDEO_SOURCE_MEMORY is selected - in the ioctl call VIDEO_SELECT_SOURCE. The data provided shall be in - PES format, unless the capability allows other formats. If O_NONBLOCK is - not specified the function will block until buffer space is available. The amount - of data to be transferred is implied by count.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>size_t write(int fd, const void ⋆buf, size_t count);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>void *buf</para> -</entry><entry - align="char"> -<para>Pointer to the buffer containing the PES data.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t count</para> -</entry><entry - align="char"> -<para>Size of buf.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURN VALUE</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EPERM</para> -</entry><entry - align="char"> -<para>Mode VIDEO_SOURCE_MEMORY not selected.</para> -</entry> - </row><row><entry - align="char"> -<para>ENOMEM</para> -</entry><entry - align="char"> -<para>Attempted to write more data than the internal buffer can - hold.</para> -</entry> - </row><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section id="VIDEO_STOP" -role="subsection"><title>VIDEO_STOP</title> -<para>DESCRIPTION -</para> -<para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2 -&VIDIOC-DECODER-CMD; instead.</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Video Device to stop playing the current stream. - Depending on the input parameter, the screen can be blanked out or displaying - the last decoded frame.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = VIDEO_STOP, boolean - mode);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_STOP for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>Boolean mode</para> -</entry><entry - align="char"> -<para>Indicates how the screen shall be handled.</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>TRUE: Blank screen when stop.</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>FALSE: Show last decoded frame.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="VIDEO_PLAY" -role="subsection"><title>VIDEO_PLAY</title> -<para>DESCRIPTION -</para> -<para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2 -&VIDIOC-DECODER-CMD; instead.</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Video Device to start playing a video stream from the - selected source.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = VIDEO_PLAY);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_PLAY for this command.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="VIDEO_FREEZE" -role="subsection"><title>VIDEO_FREEZE</title> -<para>DESCRIPTION -</para> -<para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2 -&VIDIOC-DECODER-CMD; instead.</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call suspends the live video stream being played. Decoding - and playing are frozen. It is then possible to restart the decoding - and playing process of the video stream using the VIDEO_CONTINUE - command. If VIDEO_SOURCE_MEMORY is selected in the ioctl call - VIDEO_SELECT_SOURCE, the DVB subsystem will not decode any more - data until the ioctl call VIDEO_CONTINUE or VIDEO_PLAY is performed.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = VIDEO_FREEZE);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_FREEZE for this command.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="VIDEO_CONTINUE" -role="subsection"><title>VIDEO_CONTINUE</title> -<para>DESCRIPTION -</para> -<para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2 -&VIDIOC-DECODER-CMD; instead.</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call restarts decoding and playing processes of the video stream - which was played before a call to VIDEO_FREEZE was made.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = VIDEO_CONTINUE);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_CONTINUE for this command.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="VIDEO_SELECT_SOURCE" -role="subsection"><title>VIDEO_SELECT_SOURCE</title> -<para>DESCRIPTION -</para> -<para>This ioctl is for DVB devices only. This ioctl was also supported by the -V4L2 ivtv driver, but that has been replaced by the ivtv-specific -<constant>IVTV_IOC_PASSTHROUGH_MODE</constant> ioctl.</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call informs the video device which source shall be used for the input - data. The possible sources are demux or memory. If memory is selected, the - data is fed to the video device through the write command.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = VIDEO_SELECT_SOURCE, - video_stream_source_t source);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_SELECT_SOURCE for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>video_stream_source_t - source</para> -</entry><entry - align="char"> -<para>Indicates which source shall be used for the Video stream.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="VIDEO_SET_BLANK" -role="subsection"><title>VIDEO_SET_BLANK</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Video Device to blank out the picture.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = VIDEO_SET_BLANK, boolean - mode);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_SET_BLANK for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>boolean mode</para> -</entry><entry - align="char"> -<para>TRUE: Blank screen when stop.</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>FALSE: Show last decoded frame.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="VIDEO_GET_STATUS" -role="subsection"><title>VIDEO_GET_STATUS</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Video Device to return the current status of the device.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para> int ioctl(fd, int request = VIDEO_GET_STATUS, struct - video_status ⋆status);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_GET_STATUS for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct video_status - *status</para> -</entry><entry - align="char"> -<para>Returns the current status of the Video Device.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="VIDEO_GET_FRAME_COUNT" -role="subsection"><title>VIDEO_GET_FRAME_COUNT</title> -<para>DESCRIPTION -</para> -<para>This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders this -ioctl has been replaced by the <constant>V4L2_CID_MPEG_VIDEO_DEC_FRAME</constant> control.</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Video Device to return the number of displayed frames -since the decoder was started.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = - VIDEO_GET_FRAME_COUNT, __u64 *pts);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_GET_FRAME_COUNT for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>__u64 *pts -</para> -</entry><entry - align="char"> -<para>Returns the number of frames displayed since the decoder was started. -</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="VIDEO_GET_PTS" -role="subsection"><title>VIDEO_GET_PTS</title> -<para>DESCRIPTION -</para> -<para>This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders this -ioctl has been replaced by the <constant>V4L2_CID_MPEG_VIDEO_DEC_PTS</constant> control.</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Video Device to return the current PTS timestamp.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = - VIDEO_GET_PTS, __u64 *pts);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_GET_PTS for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>__u64 *pts -</para> -</entry><entry - align="char"> -<para>Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 / ISO/IEC 13818-1. -</para> -<para> -The PTS should belong to the currently played -frame if possible, but may also be a value close to it -like the PTS of the last decoded frame or the last PTS -extracted by the PES parser.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="VIDEO_GET_FRAME_RATE" -role="subsection"><title>VIDEO_GET_FRAME_RATE</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Video Device to return the current framerate.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = - VIDEO_GET_FRAME_RATE, unsigned int *rate);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_GET_FRAME_RATE for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>unsigned int *rate -</para> -</entry><entry - align="char"> -<para>Returns the framerate in number of frames per 1000 seconds. -</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="VIDEO_GET_EVENT" -role="subsection"><title>VIDEO_GET_EVENT</title> -<para>DESCRIPTION -</para> -<para>This ioctl is for DVB devices only. To get events from a V4L2 decoder use the V4L2 -&VIDIOC-DQEVENT; ioctl instead.</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call returns an event of type video_event if available. If an event is - not available, the behavior depends on whether the device is in blocking or - non-blocking mode. In the latter case, the call fails immediately with errno - set to EWOULDBLOCK. In the former case, the call blocks until an event - becomes available. The standard Linux poll() and/or select() system calls can - be used with the device file descriptor to watch for new events. For select(), - the file descriptor should be included in the exceptfds argument, and for - poll(), POLLPRI should be specified as the wake-up condition. Read-only - permissions are sufficient for this ioctl call.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para> int ioctl(fd, int request = VIDEO_GET_EVENT, struct - video_event ⋆ev);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_GET_EVENT for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct video_event - *ev</para> -</entry><entry - align="char"> -<para>Points to the location where the event, if any, is to be - stored.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EWOULDBLOCK</para> -</entry><entry - align="char"> -<para>There is no event pending, and the device is in - non-blocking mode.</para> -</entry> - </row><row><entry - align="char"> -<para>EOVERFLOW</para> -</entry><entry - align="char"> -<para>Overflow in event queue - one or more events were lost.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section id="VIDEO_COMMAND" -role="subsection"><title>VIDEO_COMMAND</title> -<para>DESCRIPTION -</para> -<para>This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders this -ioctl has been replaced by the &VIDIOC-DECODER-CMD; ioctl.</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl commands the decoder. The <constant>video_command</constant> struct -is a subset of the <constant>v4l2_decoder_cmd</constant> struct, so refer to the -&VIDIOC-DECODER-CMD; documentation for more information.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = - VIDEO_COMMAND, struct video_command *cmd);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_COMMAND for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct video_command *cmd -</para> -</entry><entry - align="char"> -<para>Commands the decoder. -</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="VIDEO_TRY_COMMAND" -role="subsection"><title>VIDEO_TRY_COMMAND</title> -<para>DESCRIPTION -</para> -<para>This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders this -ioctl has been replaced by the &VIDIOC-TRY-DECODER-CMD; ioctl.</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl tries a decoder command. The <constant>video_command</constant> struct -is a subset of the <constant>v4l2_decoder_cmd</constant> struct, so refer to the -&VIDIOC-TRY-DECODER-CMD; documentation for more information.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = - VIDEO_TRY_COMMAND, struct video_command *cmd);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_TRY_COMMAND for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct video_command *cmd -</para> -</entry><entry - align="char"> -<para>Try a decoder command. -</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="VIDEO_GET_SIZE" -role="subsection"><title>VIDEO_GET_SIZE</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl returns the size and aspect ratio.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = - VIDEO_GET_SIZE, video_size_t *size);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_GET_SIZE for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>video_size_t *size -</para> -</entry><entry - align="char"> -<para>Returns the size and aspect ratio. -</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="VIDEO_SET_DISPLAY_FORMAT" -role="subsection"><title>VIDEO_SET_DISPLAY_FORMAT</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Video Device to select the video format to be applied - by the MPEG chip on the video.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para> int ioctl(fd, int request = - VIDEO_SET_DISPLAY_FORMAT, video_display_format_t - format);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_SET_DISPLAY_FORMAT for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>video_display_format_t - format</para> -</entry><entry - align="char"> -<para>Selects the video format to be used.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="VIDEO_STILLPICTURE" -role="subsection"><title>VIDEO_STILLPICTURE</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Video Device to display a still picture (I-frame). The - input data shall contain an I-frame. If the pointer is NULL, then the current - displayed still picture is blanked.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = VIDEO_STILLPICTURE, - struct video_still_picture ⋆sp);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_STILLPICTURE for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct - video_still_picture - *sp</para> -</entry><entry - align="char"> -<para>Pointer to a location where an I-frame and size is stored.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="VIDEO_FAST_FORWARD" -role="subsection"><title>VIDEO_FAST_FORWARD</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Video Device to skip decoding of N number of I-frames. - This call can only be used if VIDEO_SOURCE_MEMORY is selected.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = VIDEO_FAST_FORWARD, int - nFrames);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_FAST_FORWARD for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>int nFrames</para> -</entry><entry - align="char"> -<para>The number of frames to skip.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EPERM</para> -</entry><entry - align="char"> -<para>Mode VIDEO_SOURCE_MEMORY not selected.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section id="VIDEO_SLOWMOTION" -role="subsection"><title>VIDEO_SLOWMOTION</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the video device to repeat decoding frames N number of - times. This call can only be used if VIDEO_SOURCE_MEMORY is selected.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = VIDEO_SLOWMOTION, int - nFrames);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_SLOWMOTION for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>int nFrames</para> -</entry><entry - align="char"> -<para>The number of times to repeat each frame.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EPERM</para> -</entry><entry - align="char"> -<para>Mode VIDEO_SOURCE_MEMORY not selected.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section id="VIDEO_GET_CAPABILITIES" -role="subsection"><title>VIDEO_GET_CAPABILITIES</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the video device about its decoding capabilities. On success - it returns and integer which has bits set according to the defines in section ??.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = VIDEO_GET_CAPABILITIES, - unsigned int ⋆cap);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_GET_CAPABILITIES for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>unsigned int *cap</para> -</entry><entry - align="char"> -<para>Pointer to a location where to store the capability - information.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="VIDEO_SET_ID" -role="subsection"><title>VIDEO_SET_ID</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl selects which sub-stream is to be decoded if a program or system - stream is sent to the video device.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = VIDEO_SET_ID, int - id);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_SET_ID for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>int id</para> -</entry><entry - align="char"> -<para>video sub-stream id</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Invalid sub-stream id.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section id="VIDEO_CLEAR_BUFFER" -role="subsection"><title>VIDEO_CLEAR_BUFFER</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call clears all video buffers in the driver and in the decoder hardware.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = VIDEO_CLEAR_BUFFER);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_CLEAR_BUFFER for this command.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="VIDEO_SET_STREAMTYPE" -role="subsection"><title>VIDEO_SET_STREAMTYPE</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl tells the driver which kind of stream to expect being written to it. If - this call is not used the default of video PES is used. Some drivers might not - support this call and always expect PES.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = VIDEO_SET_STREAMTYPE, - int type);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_SET_STREAMTYPE for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>int type</para> -</entry><entry - align="char"> -<para>stream type</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="VIDEO_SET_FORMAT" -role="subsection"><title>VIDEO_SET_FORMAT</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl sets the screen format (aspect ratio) of the connected output device - (TV) so that the output of the decoder can be adjusted accordingly.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para> int ioctl(fd, int request = VIDEO_SET_FORMAT, - video_format_t format);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_SET_FORMAT for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>video_format_t - format</para> -</entry><entry - align="char"> -<para>video format of TV as defined in section ??.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>format is not a valid video format.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section id="VIDEO_SET_SYSTEM" -role="subsection"><title>VIDEO_SET_SYSTEM</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl sets the television output format. The format (see section ??) may - vary from the color format of the displayed MPEG stream. If the hardware is - not able to display the requested format the call will return an error.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para> int ioctl(fd, int request = VIDEO_SET_SYSTEM , - video_system_t system);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_SET_FORMAT for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>video_system_t - system</para> -</entry><entry - align="char"> -<para>video system of TV output.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>system is not a valid or supported video system.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section id="VIDEO_SET_HIGHLIGHT" -role="subsection"><title>VIDEO_SET_HIGHLIGHT</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl sets the SPU highlight information for the menu access of a DVD.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para> int ioctl(fd, int request = VIDEO_SET_HIGHLIGHT - ,video_highlight_t ⋆vhilite)</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_SET_HIGHLIGHT for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>video_highlight_t - *vhilite</para> -</entry><entry - align="char"> -<para>SPU Highlight information according to section ??.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; - -</section><section id="VIDEO_SET_SPU" -role="subsection"><title>VIDEO_SET_SPU</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl activates or deactivates SPU decoding in a DVD input stream. It can - only be used, if the driver is able to handle a DVD stream.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para> int ioctl(fd, int request = VIDEO_SET_SPU , - video_spu_t ⋆spu)</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_SET_SPU for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>video_spu_t *spu</para> -</entry><entry - align="char"> -<para>SPU decoding (de)activation and subid setting according - to section ??.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>input is not a valid spu setting or driver cannot handle - SPU.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section id="VIDEO_SET_SPU_PALETTE" -role="subsection"><title>VIDEO_SET_SPU_PALETTE</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl sets the SPU color palette.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para> int ioctl(fd, int request = VIDEO_SET_SPU_PALETTE - ,video_spu_palette_t ⋆palette )</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_SET_SPU_PALETTE for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>video_spu_palette_t - *palette</para> -</entry><entry - align="char"> -<para>SPU palette according to section ??.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>input is not a valid palette or driver doesn’t handle SPU.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section id="VIDEO_GET_NAVI" -role="subsection"><title>VIDEO_GET_NAVI</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl returns navigational information from the DVD stream. This is - especially needed if an encoded stream has to be decoded by the hardware.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para> int ioctl(fd, int request = VIDEO_GET_NAVI , - video_navi_pack_t ⋆navipack)</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_GET_NAVI for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>video_navi_pack_t - *navipack</para> -</entry><entry - align="char"> -<para>PCI or DSI pack (private stream 2) according to section - ??.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>driver is not able to return navigational information</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section id="VIDEO_SET_ATTRIBUTES" -role="subsection"><title>VIDEO_SET_ATTRIBUTES</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl is intended for DVD playback and allows you to set certain - information about the stream. Some hardware may not need this information, - but the call also tells the hardware to prepare for DVD playback.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para> int ioctl(fd, int request = VIDEO_SET_ATTRIBUTE - ,video_attributes_t vattr)</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_SET_ATTRIBUTE for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>video_attributes_t - vattr</para> -</entry><entry - align="char"> -<para>video attributes according to section ??.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>input is not a valid attribute setting.</para> -</entry> - </row></tbody></tgroup></informaltable> - </section></section> diff --git a/Documentation/DocBook/media/dvbstb.png.b64 b/Documentation/DocBook/media/dvbstb.png.b64 deleted file mode 100644 index e8b52fde3d11..000000000000 --- a/Documentation/DocBook/media/dvbstb.png.b64 +++ /dev/null @@ -1,398 +0,0 @@ -iVBORw0KGgoAAAANSUhEUgAAAzMAAAGaCAYAAAA7Jx25AAAABmJLR0QAAAAAAAD5Q7t/AAAACXBI -WXMAAA3XAAANiQFmEOuiAAAgAElEQVR42uzdd1RU18I28GdgKFZUBE0saFA0KoqFFkEhKhbAQmxJ -bIkNNEpMEUwsMZarJMZrw4KxRExQczUqil0jRBA1GAjGQqLYC4TemdnfH76cj3HodYDntxaLmTll -zuw57Zmz9z4yIYQAkYZzcnJCSkoKGjZsyMIgIiIiquPS09PRoEEDyBhmqCaQyWRo06YN3nvvPRYG -ERERUR137Ngx/Pnnn5CzKKgmMDAwwKpVqxhmiIiIiAj29vZ4//33ocWiICIiIiKimohhhoiIiIiI -GGaIiIiIiIgYZoiIiIiIiBhmiIiIiIiIYYaIiIiIiIhhhoiIiIiIiGGGiIiIiIgYZoiIiIiIiBhm -iIiIiIiIGGaIiIiIiIgYZoiIiIiIiGGGiIiIiIiIYYaIiIiIiIhhhoiIiIiIGGaIiIiIiIgYZoiI -iIiIiBhmiIiIiIiIYYaIiIiIiIhhhoiIiIiIqFLIWQRElSMsLAy2trZo1KgR5HJualTxEhIS8P33 -3+PDDz+sM5+5bdu2ePDgAZo2bcoVgCplm3J0dMS5c+fqzGf++uuvsWTJEm5TVClSU1ORk5ODBw8e -oHXr1gwzRDVJbm4uAGDRokUwMDBggVCFmzlzJrKysurUZ3727BksLCzg4eHBFYAq3IIFC5CQkFCn -PnNGRgYAYNWqVVwBqMJFRUVh48aNUCqVlfYeDDNElWzGjBkMM1QpNm7cWOc+c8uWLTFjxgzMmDGD -KwBVuLt37yIkJKTOfW5nZ2duU1SpYaYysc0MERERERHVSAwzRERERETEMENERERERMQwQ0RERERE -xDBDREREREQMM0RERERERAwzREREREREDDNERERERMQwQ0RERERExDBDRERERETEMENERERERMQw -Q0REREREDDNEREREREQMM0RERERERAwzRERERETEMENERERERMQwQ0RERERExDBDREREREQMM0RE -RERERAwzREREREREDDNEREREREQMM0RERERExDBDRERERETEMENERERERMQwQ0REREREDDNERERE -REQMM0RERERERAwzRERERETEMENERERERMQwQ0REREREVGnkLAKimunBgwdISkoq8/SGhoZ47bXX -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 -AADISP8FpxZnWS0U37cAAAAASUVORK5CYII= diff --git a/Documentation/DocBook/media/fieldseq_bt.gif.b64 b/Documentation/DocBook/media/fieldseq_bt.gif.b64 deleted file mode 100644 index b5b557b88158..000000000000 --- a/Documentation/DocBook/media/fieldseq_bt.gif.b64 +++ /dev/null @@ -1,447 +0,0 @@ -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 -l3O5NwEBADs= diff --git a/Documentation/DocBook/media/fieldseq_tb.gif.b64 b/Documentation/DocBook/media/fieldseq_tb.gif.b64 deleted file mode 100644 index 7b4c1766b407..000000000000 --- a/Documentation/DocBook/media/fieldseq_tb.gif.b64 +++ /dev/null @@ -1,445 +0,0 @@ -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 -kh6JXympkivJkm4TEAA7 diff --git a/Documentation/DocBook/media/nv12mt.gif.b64 b/Documentation/DocBook/media/nv12mt.gif.b64 deleted file mode 100644 index 083a7c85d107..000000000000 --- a/Documentation/DocBook/media/nv12mt.gif.b64 +++ /dev/null @@ -1,37 +0,0 @@ -R0lGODlhFgFnAMZnAAAAAAYCAgAASAwFBQAAdEgAACQODkgASCoQEEgAdHQAADATEjUVFHQASDsX -F3QAdE0eHVMhIABISABInEhIAIM0Mok2NI84Nk9PT5o9O5xIAHRInFlZWaxEQbhJRgB0v75LSLhQ -TbRTUcBRTrBXVatcWsJWVKdfXW9vb6VhX0h0v8RcWZhpaJJubpBwb8ZiX8ZiYI5zc4t1dYd4eMhn -Zb90AIN8fH9/f8pracpta8ttasxzcM51dM52dM53dc94dkic39F+fNOEgpmZmdWJh9ePjdiTkt+c -SNuamd2gnt6lo3S//5y/nOCqqeKwr+S1tOa7uv+/dOjBwOrGxuzKye3KyuzMy5zf/7/fnO/S0fHX -1//fnPPd3fTe3vXj4vfo6Pnu7r////v09N////35+f//v///3/////////////////////////// -/////////////////////////////////////////////////////////////////////////yH+ -FE5WMTJNVCBtZW1vcnkgbGF5b3V0ACwAAAAAFgFnAAAH/oBngoOEhYaHiImKi4yNjo+QkZKTlJWW -l5iZmpucnZ6foKGio6SlpqeoqaqrrK2ur7CxsrO0tba3uLm6u7y9vr/AwcLDxMXGmkM3ysvMzc7P -0NHS0CjT1tfY19XZ3N3Y297h4sxDlQDj6OLn6ezZ6+3w0u/x9M0A5r/3vvq9/Lz+kQDqEpiLIC6D -txAyUliLIS2HsyDKkniIIiyLrzC60tiKoyCPq0CqEpmKJCqQJk+lNLWyVEtSKPPJ3Ddz0stRN0Xl -DLUTVEyaQPvVlNTzU1FPRzsl5fRTaNB/QwNGHTi1IL6nu5Zu0qqpKVSsVME+4pqJLCazl9Ba8oqp -jAIA/gTCIOXkVsAVo52OAABgV6kmMxr2Cgbil9LLGh/OIJ6r6QgBLAfuMm48YYzPT1siF7a5qUyD -u1HibtaUWfLoS55NT+a0+DSklqXPxK5EJkuhm7NdV8pMYW9i3YJsT8q99Wqm2MQn/cihZRBuzasv -RenrdgnwM8uFQzpSOfrrTcihW5KyogiYM89VF9cUWq7i3+sRTVlB5Lyj6ngNd/58pn0mMUmY4ER6 -+R2nGWCEMbUIGQE2QUYj3Fnm3VibIPgeJ178kEFz4Imn4F8aEJbcWY18EcQLViziVoITOvLSFgXA -5R4iVvxg44045oijByAU0QMIQAYppJAwPHhIFILx/qUeieDFCIB1igjBg45U4nhBlVSaAEIQYiTi -2IzXLbTKF1mUaeaZaJr5RAc5aKeIFStw0RErVehARZp4mrlAnmlCscILU8yp3y5iILECBI7AKaeg -q3DxQ5cuMgLgCg5uZBwuTpiAhBgQKZqRK45CKqYiftZ30aW1WEFDEF58xIinn4L6aCMIabHDDhye -OqgtYgSRonOLwBqrrKImglAQUjyEalg0xjlRLKEuotayFIoliLC6whKtsVVFai222Wo7KyLT7kpU -VeCGK26xhJTLmblZGZKuuutW1C2tUc1Lb7233TuqU9c6m9At2wJrLb68JEEGP/rG4u4iBaPnr7S8 -/ohhgsRnNOxwLgU/LJVh9YR8Qwsl3HCOCyHIIDI986yMjgwkzKBMyy63g1LN8JzAgskoq4wzOzT/ -3E0MIIiQggM2CG0ztbW88MUZDAgc7y5aFlHBCDsk4ebA8NryxQsZd7DoV7oIQcQKBpyhRRM/jOCE -VV3X8kQRcKYtCBnsNsQLFHSLPQjecL+bi9lxApCFEjuM0ASzuXwNtdSMf5yLlkQEAcIOSmzN9S5O -A6Dxs3HPogUIOSBhRQATy1LEE/d8vq+3t5BhhH0YA6zLFELo47qlocNChhC/unowLRYzDLnevbvy -e/DC265LEqgPsntITCsPvCEef4fV9CVVz8ry/vYOjzwh3KvkvSrgh+985AGPDbrgvl9PbuoRNev+ -6wjHzzz29L8v7/G8g18r0sct8SkrEeXTyfkigaS9sIgRBCwge/bSlzBNAjAV/BACAXgIGAmmOxo8 -lybK8AC5TGdJh4igBAuhOUaUYQOWqQEIMVGb2jVGAh6iRA0N9iYOFmJE8RFhJ/CzIPn9qxDZoYR/ -NLEcBNClAUzIISWWw6FO+XAQQOzKAocjxUKoUBEImY+pIAEY+GhCCh0wT2OAkEVJkMc8EtGYB/cC -pRBKjjVmTKER85fCBhlpEQ2c4SYGEKC3XWILCQhDGyUBIBNE4BG7O0IGtZg8SkRIEV+k2CJM/oSi -R0gShWs5Q4aYY4kaiKiLlvDCBUjZCNcRMYh3zMSXFuEDHGAJS1e65Y20xKVGvPJNurTSjUbQox8N -6ZhAosEf3ZIkADxQXsHU0QWI6SNkIrNIKlJAHSkpwEvIUEKK6AKfxrmncZbJT4BSxBZUIIgTlsic -ZyrnE1bQJkws8gxkgieaIEDPFkaiBlCapR21dxwn7UWQTErEpCqlCMBQEJRrKdQKnkAaVFKiUB2g -aEEPCk5YEpRshygV7VwRAU3lbRaZQsIA+qc+kBLCVriKhaos0CpcqIpVNpxaNwNXCGTJoldWyJ5C -fcVDl35Up0blKVJjyT6lNvUgW/TfUp+6jzkhJhWqBqxfJQ+4Pqd6FXZXrepUv8rHsWK1q2e1qlnF -SlVbsKWt4wurW6O6saxKFa5gZCn+5mrXiijNZn8FWmDTEbTBuqMSHDDsODCgWHEwtrHeeCxkucGB -Y1j2spjNrGY3y9nOevazoA2taEdL2tKa9rSoTa1qV8va1rr2tbCNrWxnS9va2va2uM3tLQIBADs= diff --git a/Documentation/DocBook/media/nv12mt_example.gif.b64 b/Documentation/DocBook/media/nv12mt_example.gif.b64 deleted file mode 100644 index a512078c7f24..000000000000 --- a/Documentation/DocBook/media/nv12mt_example.gif.b64 +++ /dev/null @@ -1,121 +0,0 @@ -R0lGODlhoAHkAOe1AAAAAAAASAAAdEgAAEgASEgAdBgYGHQAABoaGnQASHQAdC0eHigoKEIlJEYm -JS4uLlssKzY2NgBISFIyMQBInEBAQEhBQUhIAFBBQVhCQkhISF5DQ2NDQmdDQ3NEQ05OToNGRHhJ -SJxIAItHRY9HRXRInJdIRlpaWppLSaJJRqpJR7BIRa5KR2NfX7JKR2BgYGxdXWleXmZfX31ZWXJc -XHpaWQB0v29dXLZKSHhbWolXVpVUU5JVU55SUJhUUqdQTrpLSK9OTKRRT6FSULRNS7hMSrVNSr5L -SL9MSr1OS7xQTsBRTrtTUL5WU7lYVsJWVEh0v7deW4pqab5dW8RcWbdgXrZjYcZgXnd3d8ZiX8Zi -YL9lY7RoZshnZb90ALJubLFwb8prabBzccpta79wbsttaqx6ecxzcKt8e4aGhr93dc10cs51dM52 -dImJib97ec53dc94dqiEhKeHhkic39F+fKeKiaWPj9OEgqSSkb6PjtWJh5qamqGamqCcnNePjZ+f -n9iTkr6amtiUktmVk9+cSL6enduamb+jo92gnr+pqd6lo7Ozs7+wsHS//7W1tZy/nOCqqbm5ub+4 -uOKwr+S1tL+/v9+/dOa7uv+/dOjBwOrGxuzKye3KyuzMy5zf/7/fnO/S0d/fnPHX1+Dg4P/fnPPd -3fTe3vXj4vfo6L//v+/v7/nu7r///9//v/v09N//39////35+f//v///3/////////////////// -//////////////////////////////////////////////////////////////////////////// -//////////////////////////////////////////////////////////////////////////// -//////////////////////////////////////////////////////////////////////////// -/////////////////////////////////////////////////////yH+EUNyZWF0ZWQgd2l0aCBH -SU1QACwAAAAAoAHkAAAI/gBrCRxIsKDBgwgTKlzIsKHDhxAjSpxIsaLFixgzatzIsaPHjyBDihxJ -sqTJkyhTqlzJsqXLlzBjypxJs6bNmzhz6tzJs6fPn0CDCh1KtKjRo0iTKl3KtKnTp1CjSp1KtapV -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 -XnvvxTdfffflt19//+03IAA7 diff --git a/Documentation/DocBook/media/pipeline.png.b64 b/Documentation/DocBook/media/pipeline.png.b64 deleted file mode 100644 index 97d9ac007473..000000000000 --- a/Documentation/DocBook/media/pipeline.png.b64 +++ /dev/null @@ -1,213 +0,0 @@ -iVBORw0KGgoAAAANSUhEUgAAAlgAAAEcCAMAAAAsmToJAAAAAXNSR0IArs4c6QAAAwBQTFRFAAEA -EAEBAwUBCgMBCAUKAgkMHQIDCwYXFQYDBgkVDwgFCAsHChASJwkDFA4NEg4TDhANHgwHDg8aExAG -DBEjBBUZERMQCBNRDxU0ExcZFRgVFRcgCRkzHBcUDRdCNRELIxYTAx4mLBUMEBwcEhsiDxwhExsu -Dh8XJRkQByAtDCMUHx4bACk0DSsiGScsFCRcJSUiGSZCDiwqGCg1LyQbIycpVhsPDy0wNyQVECxA -PSIfCS84ADJCEStWRiIULSwpADdHCDkgEy1/BjorEjhADDhXCzZvITNPUysQDzs8MjIvCj04BT1O -PDEoQjEhMDU3LzY9KTdFTTMYNzk2GD6PAEpfEUVjBExFCEpPB1ArK0FjKEVZYTscdDYXG0d5SkA5 -FEiJQUNAOURPAFhCA1RpP0ZJVEMvYUAyBFtRWkYnDlR+QEleAF1jkTojHlV1AGB4PlN5YU87cUws -SVRXAGaBWVJKUlRRRVZlAG1PWFNSBGt5AmqVAG+NAHNpK17BWl9ifFs9KWmnSGZ0YGFfp1IuCnWj -AHuKbWBXoVNAdGBPDniWAHujTWmLk14rAH+ch19XX2aRX2t8AIeLiWgvAIeeAIaqa21rOnehdW1m -AImspWJYj2tLW3C0AIyvWXaNAo6xb3Z5dXZzent4WIKiQojAen+CkX1pcoSWcYDOoH9fp4E+Y4ur -hoWCXIvGb4mut3xpqYNYnYdUO5rDyXxdjY6LYJqk0IRGb5azXZnMjJGUgJWqpJB8l5aUyJN4kKK1 -rZ6IYqzge6Xho6GdnaWpgqy6yZ9zvaR0hqzMk6rN5Jxxw6mF26lbq7C2pLTGwrCbs7Owvb+8zcGc -8rp42L2xsMbY3L+jtMfsz8W2nM/yx8jH0MfA7MWU78h/3crIyNTo4NLD6dK1z9bc1dbT3NXOv9vr -/OKSwur8++Gw4uTh0ef78uPU+OPL3Ojz++bGyfH36evo/+3b6vT88vPw/feu1/v+//bb//nK/PnW -5f/+//ro+fv49/7///37//71//3//v/8sZeTnQAAAAFiS0dEAIgFHUgAAAAJcEhZcwAAFY4AABWO -AUTUBDsAAAAHdElNRQfaCRQPAiJBEFMLAAAgAElEQVR42u2dD3wU5bX300nWws50shA4lyTGikRE -Qy0aUChKvJZqTQGBFNurVo0FWq2VqhAq0hc0t1rAxtLLpu61cUl6gWtNe3vb7Z9IKm+Xqn2tkFih -GmwFA9Xwpw1s/UOyCc97zvPM7L/sbjabXTLZPL/PhzA7O7M7s893zjnPmec5k8WkpNKgLPkTSEmw -pCRYVlSjp5n/3+3xGGsONHt2vx1t04PNTbtP8aUujxAuHvN6XjHe721pbmqLsp/H021+crP5wce8 -Ta8Evi+wKMHKHKkwjf/vA+D/77SrAKDeeTRiO3/vcnzDoTzXgy/+CEKMbVdw5dh9tMGubAfuuMjf -E7HnfgAf/X9yJn6Aupqv206fNfYdXHr/Aloc944EK7PBWg9QurVxlQ3s70Vs+FmAdQ0LAP6By1cA -KCT2AsBqXKme7mEfajBr25MaTIjkSjPA0mHsVnz/G8jgzyBna4MGH/UzdgHYt9ZrMNovwcpksN4E -eJpeHbLB5PDtelT4L/wP4Fr+95NirQa34d85cB1jX3eAsGVhiPRuR644WPjOafxgHXw9uD8axL/k -3+gj3P4vLgJ0SrAyGaxzoFCsfpObJh8aJVMtzUSMA3JZTw/Ab8RKYcD+Rvu2ehsJJIBu9llFwdW3 -0l8N1B0CrDlgpz1K4OfIkRqgT4cOjNkkWBkLFiM4ejT4nXjVrcH/wb9G4BUUwOcZ+xCgtkh74Ci9 -9Iu1Jig/BjhDhmzCGUTzccaKNx9lAqwSUAVY17Kvw7U7S2wLn6fXRXCzn90P2dIVZhxYIlxSiCE0 -W+8F1l+GYDU0hG99P9/gVxiEKxiGvYPMoCMjT2a8fxyRQkQw9HpJg3EBGAmsr4PDz8Eaxz4F+UBf -+DjtMZ0WJ/9ZBu8ZDlZwfX7fjTG0x9ibPTF93D52UEdELgD9LXYw19zteA7onMwLAHuI74SB9QGG -b372DKAvLQF4xN/7FPlR/17gjD3H/BKszHWFYRbr6siEA7sL4Jbga4zG2Yd2sCuqaoC1H63YS3wJ -nSW3RyFgsQ0coQLsNn4KdD/3gtcauG0HOCItVgYH78EYq4fHWOFaDLA6tMNHe3St0m0L3+Ixln+/ -BqP3ib0xGue2LRQstmu+vXjz13mMZYRbubhoFw7yXyRYmdwrHMN7hR/fgVGSdrovVzvEUpuXYPhn -wG9+wJcOaTDZ3GcOpU/fiACLmb3CP5o0ncemCcamQY4EK+PzWD3zYayNYvcwYUj0UiCldTf+9yXQ -2RNlKl+6Aw2YLRCtU/D+uBZgxQDr9iIkrauIeo067OOu8Cfs38Fxgi9+XoKVyWCx+wBKG5t1tDfU -9ME81hlybtki3U59w9XNuOVL/r+IJbu/58yXwOgGdPd0aXAuwXU384eAdT7YtzXqPPO+HuybPRdA -9hnW5YDR2zz41ntnJFiZDBbbbnfQvUI7OBaF5bF+ZdwehALCj+4n2n9qLDkK/8zxMdSNjlA/3UP4 -vRFqsf4+xhG4V8h3G0sB+/4ptJjzB5luyDDV1otUVXd9vbGmpXFr09td96mXha5kT9Yb4psfbKxv -EgMdDjZuE2MTzPfru/9eX/8HsabWeMcY3eBtaHrL+LiDjVt3B75v224/k2CNFL3+D/kbSLCkJFhS -EiwpKQmWlARLSoIlJSXBkpJgSUmwpKQkWFISLCkJlpSUBEtKgiUlwZKSkmBJSbCkJFhSUhIsKQmW -leRP28f50/H5EizLSlHEDC9jCuGxJ6crtoU7TkVjxJxkuGu+XVvNp9t0bS9SFu4Ra1+/PTt/c+R+ -uFLbfMJYtNvMbRk7nq34JFiZrPB5hYdsoKqqA9Sjfbm61ZhkOAdwG1D3IVd2WhJFGp4CB+6Xw8Iq -kD6j0QbZR3D3F/he8CPjHT1s3r0EK8PB6rHBLARmby7kRm538i4QYP2Jag4dmwkOKkU69gjbqcEb -rOddgD1sL8DDofu8D/C4/9gCyPHTrNVZp3oXixpZjCCVYI0gsHy8Tihjf1Rt+Le7pSWw2U4bjBZg -faUEkRJ1QETZte8ShefDT3CxtukV1tXSQm6yBXf+d7Nc0T9o2/d4SUjCyf8iTJZgjTCwng2+FVKG -janqMn9o3UgDLOKmy1g83NrKQ6zzwc493+/YFFFKpoAqIuk03/5dmoCP1g/00xKsjAerpIWLYzMK -oDTw9ACfqgY2w7A8rCDpHEETzZb+kPgCeIpqAz7HOD0PI2yXMfYpUcS2gGosLwf7bq8G1zNuwn7D -JFgZD1ZAFBWdTxVBcjZHezJFKFhPAfyQwLqDu0LOGCysmi8qHS0G+Dg6wR4qJHKCVy4ajWtn0lec -SzvfDzczCVbmg1VQxWVgs2E6oaY/HgcsP3FVKvB6pGUDCLCu53aMB+eE0E9E3y9ntxet4Gh6a/QD -q3Qi62UYyyRYIyzdwPt/O2/Xg+X4+oJF1bNhEV/k1YgWCVdIXvGfIupCS6Xz9/8+xQGQOwddoXh8 -ABqv/8JNf9/a2goQ0jWQYGU2WH7W0cbJ6dL6lLYNsVi3AnzNWHfwyXV7WDCOZyI4p7ptRvW/XdVb -T8/B4P1TZtnRccFCWqoEa6RYrCvUfHPt5JhgfTeQ5uxobz1DVd7HElH0rIq/cb5wAx3yCLTDbf4z -It1gxPElMAE7mCQqFS/BGilgIRiXdeDyTkoWsO7W1ihgvYkheCuJPz7nBDumUTbrV5D3NvOdT2VI -j2O8hRudxz/8YT97EXL9fnSFz/nZq4FnpbA+z7yQYGVyjLXcAXb+MIFFEXmsIFi5gU6kv0tFs6OK -eGsBf1iF9g9yhLnMz0vh+u/npd3VN/j7/EEBpWcCYMngPaOlqCWhSatd84tUteDGHZF5LAKLv+xR -TeGLQ/N1dcZm8faGEjV/4VF0hCoHaaaqnOIrtYXivuP2MlBnBOvEq6oESyq+QobC9ER7vydyq5Eq -CZaUBEtKgiUlwZJKnyqmlXRLsKRSrhJlBI5KlmClX+USLKl0qFKCJZUO1UqwpNKhZkVtl2BJpVzt -qtIswZJKvRSlUoIllQ6wFAmWVOqlKkq3BEsq5apWyzokWFIpV4eiVEiwpNISZHVLsKRSrlpFaZBg -SaVeoCidEiyplKthZGYcJFhpV4FSPgIHZUmw0q8KtFkdEiypVKsbwVIafBIsqVSrhNCq7ZBgSaU8 -gie2ytq6JVhSqVWVSlZLbeiUYEmlVp4ChexWebsESyq16qzgZmtahwRLKg1mSylvlGBJpVotQLGW -T4IllXKrpYyAjKkEaygEmU+WBGtINE3J9AmHEqwhIwskWFKpV4mi1EuwpFIvJbMHAEqwhkrNme0M -+4Dl6+w4++rs7EnT+Q3R6SRysxm7hu3D5HQGC1Z3x7Kc8RNnX2XIds1VadXU8ebS7Ik2W+pHlfja -Z+RMnBg4CVt6z+YqW+CHmzrRNr6x39PpUJQBPQjF10anY37HNek+nYkXm42Dp6N5O5MHy9eQs8Lt -CqpufOirNGjtNaGv3POyWlOJVWeVbW3YCUysS+/pTHWGnc5VOYf7OcKCgSSzOm8cXxN6Au7x6T0b -15IVoSy4LtYOJwlWs80Z/slnGSxaYUuZ1equ7XP0Zxcs1NJ+TqdNUaoSPZ2qyKM/u2DxCz/flwRY -3fkrIz/57IPlqrumKjVcdUReJUMBlqtuam3co0y4sENn39M562DRV3oHDFZ7Tl+IhgAsl6smPxWD -LFuiQXT2wXK5NtrinU5VGbQlcjreiX0/eQjAQhtcNUCwWi+OwtCQgOVy2gbPlWdetK8bCrBc7nh3 -broVpTyB09m6xGURsFxrywcE1oGov/nQgOVyOgadIVrisgxYSFb3IH1h41KXZcBybawcAFi+0VEJ -GiKwXM6iwXHVNs9lIbCQrNiHWpFA9r09+q80RGC5VtYmDlZBdICGCizX2nWDSjPE+sWHCCyXszrm -sbYqiqe/89FclgLLNa8lUbDqV7qsBZZr9mACeJvbYmC55nbEuWFY0s/pFNVYDCy3LUGwfBe7rAaW -syR5rg6sdFkNLFdsZ+io6KesQ3uM5h06sFw1tYmB9aDTcmC5ViQ9Rao7x2U9sNYeiHW40/ob76e7 -LAeW62JfQmDFMlhDCZZzWrJgHV5pQbBim6zGfu7qdC+1IFg1iUwyyvKstCBYrquSBSvfZUWwlsS6 -xtv7id5vrLEgWHUTEwGr3G1FsNY2JTmgYbwlwaqrjToEprMdu4UFFQWxx89oLguC5Zp3IAGwprqs -CFZNeXJgdaywJFiurOiDkwOKZdGWWBKstZ4EwFpiSbBcSSZJm93WBCvaLcP2ELBi5bnWWhIs94PD -F6z85MCqqrMmWBdGM0mOAFexplU0bLQmWAn4k6yl1gRrYnJgLbMoWHN90buEhmL1DGstCtalIw6s -iuEEFus3xFpnUbAulGBZGqwyg6uY4zkkWBKsZMDqNMDySLAkWKkEixcHiTdxVYIlwUoKrGYBVrcE -S4KVUrBE+B77xqgES4KVHFj00ArFK8GSYKUYLF/cEEuCJcFKEiwevndLsCRYqQbLqyhx5r1IsCRY -SYKF4XurBEuClXqwKuONTZZgSbCSBYvFe/yqBEuClTRYtRIsCVY6wGISLAmWBEuCJcGSYEmwMhGs -JRIslFM3phzrOsQ54keHCViz9VFiI11fGe901kiLlW6wwOBJh/zYW10EwwUs0A2wIA5Yn4AVEixL -gAUZBRa+KcE662A5UeZ7xrITN3I6hydYEafD/yewnBKsswqW8xOA0jfRms/RItxM9oo0HMF6lB95 -qVO4c+PM5vKVKyRYaQeLWyYOVo0uIIK7Xa5vGosPDTew6GwEWF8Vp6MjTuKK4WRJsM4SWKYQrEkA -ZKwuIYwESxcu2TS8YqyAVrrcAJNx3RaACUZc9f1S8oEyxjrbYNUA3GEE658nyAqXOodd8B4C1hf0 -vG/Tyq/i/25yiStl8D40MVbIi0K60Emzhm+vcK7xoo5e3CA84b0SrKEBy2m8GId/vxgIroY3WFt4 -wPXo5fxs7pVgnX2wTFdYQ66Qa+MlwxgsdIWbTFco3l5TALl11gJr49xJ+Zfem+nphgIRvF9EXUWA -q3HxWwZYzmEIVmjwjl1BKrl1OYyzFliXGB3Xh1IOVs0NULppoGD54oK1ZlL+TcmBZYby+sO8a8g1 -ziUyWYmCNQlqBgpWd1ywHr08/xpnUnksI91AOQZ3gVii1RTI5z2UIFg3wNI0gvUFgM9sqrkHD6wu -xWBR5kindhwQWNOUKl9MsP7VyB0klXkX6Z6QBOksc22CYH0ZBg4WKNXdMcH6ajBlO/AEKcdpFh3f -lot0I8Ry8UB+ZWJg3aOnE6y6POCPqXlUh9tSDNZFUOz8NBS6BwoWKoytIFiI6t14oNclBlYqFAoW -IZgEWKgwtoJgoXn5TE0BfDIxsFKhULC+gDSmEyxdXLimq9ENr1in67xTXhxYC6V1Bueom/iuOl5y -t8UC69FR8DDyqn87CbDC2AqC9W90OP8Gk4YELPScyYIVxlYQrG9SBP5lXXcOAVho9wrTChZ6F714 -ZRhXSNbdBJzQVdyaBVzHp43VpS6xSaQDDYK1ln6xLaH2ZUBgBdkKgnURXEgxd27dkIB1t2sQYAXZ -CoJ1Azm37+uwaUjA+ow7ra6Qmp74mOcMmq8vQK4bF9H5110CY92uFaDjXl+dh32PFWi9hdm6jbbW -H6qJ6QrX8r1CDeLEhgQU0hIGW0GwdAKrJhTmszuCNBys2fUJnI4adjrEVhCsKwks/BU3DokrdKUZ -LIxkddMerRFm+fuj4A4836uIIKIDadJu4ZcVgja5Tti5c4m90jgxlgnW7CAFSjKq6gMWWAOsS5M6 -neogWJcSWO7MBQvbiiei5xFBhm5Caua6XIaxKuC92eJNLmMtIiiM2uwEwJo1OLCmtVvVYiUFVmXn -yLFYwiNehE5vBeUHuOaGgeW6h/dt9W8PEKw+MVZ3vwqNsYgq68RYfcCa60vgdCCcKtbHFQ5RjJV2 -sJaCkWnCBfeaYA8lHCye7dRhXogrnFwXoCxGr1AfVK/QoCpar7DYZRGwBhS8V3b27RXqQ9Yr7B+s -jsGB9X262y9uDlxWh/ZlFrbUo6VLnSFg1WFHG/faMgrj9jV83GUgeI8Hlisv+TxWkKrwPBbEymPp -ISOv+tOWgn43ASMZmTKwKjti5rH08/rJY9WJzO7Fse8uzU00uz0QsMpaB515N8YifttMUgHkhoIV -SEKQC7oE9JB0Q1ywRJbiNtfAwZrW3h098/7pWJl33XTi/YPljH/bmSs/pWBVdsTIvFOO0ribHBus -uov4uYWl6Psm5VMPVr3SOLgYy8CmeFPwRbEz3BWKtYWbAglS/SZX/2Ald69wWjhVCd4r1EOzpmkD -S9cHDJajsiPuvUK4qr97hV8QRIVb6tSApccDq7Vv+biBBu/OkPkewQkf5n9ha8OWnVHmtwx6dEN3 -UqMbQsCqyZ90zyTRFf3ipPzZnGy0clvmTip9iC+izSO79uiVBcaYjnxw3TPpwltMdC9cEgusCAd0 -dkY3mPcIL9dzuSOnkxK3mddcWZA/9aEgWFvmFly4xEDm0UmznP3dhA7/7gv7lo9THN0jfTxWKFim -uzScfDF/W7y42ozGzFvSfMyMGZ/R3gVmZGAZsG7g8z8CSUdxeDRmRozug3NNsIzzXcvBmgR5mwYJ -VjkFh+0SrFCw9E/y4VaFaylDV8xpKtxIMR+a2Ro+k/DLGDg715iDSOGmGgzfruW4Xc9XWwesOqLl -QmO83Fd1KN1Y8zli7Vu6fq9z4yQaJcPBwrdmbdp4ER9IQxHZeXWDBKuWdzuaRzpYgU4hgkPjBWqM -7u73aaSMDvS83G9yjJwGTNfxZbrhLpb58CyA8wSb1gHLmEEIGh6p8xJ+fM4r521y1XzxXpcxNpnA -cn6Cj17EUP9eAuu8/mOs/sBqNe58jHSwzE5hjRhz5TSGXrnoRxYjsraEgeUU/bxP0p9NZorB2MlS -YGEwdZHRwXZHDrZaczkYYLmN+YRz4bw6BOvewYNlPiGvRLpC0xWGdf4IKmMudBhYhgpNyAywnBYE -ixz4F3XI+3ZY3Qa6HUJpCAOsQCpvVF3MAcoDA8t8Ql7gaQgSrOgWKxwspyFzPoVVLdaauWvNVPZa -d8g0588BxlhiXrRpscwzShFYtYG7Bi0SrABYGGNNDomx+oJ1XUjeMwSsqy0GlrsAxvKFbyFYGGNN -EIHUBMMrfisQY10iDt1IfaYCrNbgXc5aCZYJFvX7Jm+iXmGhKxKsux+l0fPXO7d8EfKvDgPrX83O -oqXSDYUr+QCUUS7R9auhwArByuWnhwwFe4Wue4KT7gcNFgu5f14uwTLBMge7FrrCweKBvlGhxZyo -E7RSYvVtVoqxPgGBCTmBPNb15tLkAozTRR7LeCt3U8rAKguC1T5SwQreJKwxK0TiVT5J55lpfJvW -GbUjt1yuz+aZd9BmG+8Gt3GtmaSXbnLpVgret+B55M9+SBzKlhsgV9xOoCNd6/qEPoGqSNaJt/RL -HxKZ95SAVRvuCeVM6NRpZBe3NYMsn5xiL8FKJVgs1A9KsCRYKQMLg6xpXkWpl2BJsFIKVi09H09R -CiRYEqyUgtVBw2YqFaVj2IJVKcFyWfXJFM2K4hmuYHWoEizLguUz0qPDEawyRYJlWbBoGkL38ASr -Q1HaJFiWBavBvAs97MAqD/ZoJVjWA6tNUaqHJVgdNONLgmXdx8opijoswaJR+yDBsi5YZsJhmIHV -wW8bSLCsC5bHmFMxzMCqCBv+KsGyHljtxpSK4QWWMFhh04wkWNYCywyyhhdYFUbZDAmWdcEygqxh -BVZnn0lGEizLgYVBlne4gWUYLEWVYFkXrHaRyRpOYHUGRlVLsKwLFgZZZRYGa3x0722oNdZJLbMo -WLMzC6wZ/VQtI7CWWBOs/HgGyxyw31cPuq0J1vjkwGq0KFjl8Q66mo9PzppnTbCmxzNYsW/qtFnU -YuUkN26xc601waqPd9Beng/Kml1nRbBqlvWtsuapClTYj3lTp3OpNcGakRxY7BpLgrXCy/qN3rNi -O4+hBGtljKExtXjQVY7Y0Xu3zZpgtSQJlm5JsK7qZPGj9woEy7vUimCNj8GN6BF2x45YKtxWBGui -L0mwqjZaECx3fvyDBsoHZbHxddYDa2NF9ENuDYx8jTkOcK4FwaorYMlqqgXBWtEc/5gr6erPYo0r -rAfW1JhGVunv2tfc1gNrbmfSYE2rsRxYbls/x1xL3cIsxmLxM3RgbVwW02CV9NuRutJyYLnLWfKa -aDmwlnr7OeRmuqmDYLXMsxpYWuwIq/9rv95pNbBs3YMAq3ajxcByl/V3yHj9NxBYrHqltcC6qj2G -7y5XKhJoCsVtLbDmtrPBSK+xFFju/i8Tnm/I4jOqaqwE1opt0Y+3Je6g5JC5bTluK4G1opENTjZL -gTW1td8D7qZ8AweL5TutA9bKZTGvg3gTv0J7hqPd1gFrRfUguWL+8RYC65rdifgMDIUFWKxko1XA -WrouNleJtlFnVG84JGDNa2CDls9mFbDcF7+SyAFTIivLzMQtsQRYdeO9MQNCpXIATbHWEmC5x7ey -FMinbbQEWHVKYuFiuaIEwGItORYAa60tRpqqakBcoZr6HvzZB2tFTgdLjWonuoccLPe8GxPs3lYq -SndW8LJYN945pGDVrc2KYa7aoCDOUJkY7vDGqe4hBcu9IquNpUydkyJGC5xtsNxLshLu3aIZ6MwK -Pfgm29SN7qDG/9ydVm28JuTFivHj26JfEB0l2B1UBu5TOmpzZteEfMPE9J6Ne6or5MXS8eMPs5Sq -Y5ntGudZPJ0lK4LLdUtslw4gaVKtKB1ZEUd/eOvCS01pl6ZZ+ebC3GVN7TFSn94CGidTltxd3I7D -62688mydTsjnL/O2d7LUq+PAA5eetdaZdKG5dOMDLe0DyvHSPZ0sZmV5y8IrpkoNC9VbGqz2anSB -NLSvoE021fBSg6K0WROs1uoCY6xoWUOHbCgJVirUVlUgLBWG7M2SquEoC8ZYLWXGuPYSpT4t8a/U -WVCUXuHQqkpV+FOrobHdJ5tnWIPVaSGwqvjseaVaQjXchS3pswxYbdwH1sugKgNUEXqvcIjlAap7 -JW1VRqjEOmB5MFwvl1hliGiqujXAokExHtkgmQNWpTXA6lQKlGbZHpmijsCYdwsEe9WyPTJGLYrS -aAmwOhKcJSE1PNRIjz2xAlhV5YpXNkfmqIrK21oALF/ch5hIDTuBqN1ghS6hjLAySD5RxmjoD6Q2 -8LhXqUyQl2J3K4BVEO/hOFLDTtV8YvHQg9WtqOWyNTJIojje0IPV2W8xNanhpLYy/pSmoQfLfFyU -VMZ4whargFUrmyPTPKEFwGqjMl1SGdQnrLYGWL7WVpltyByVG7NAs+RPIZVa/yNuo0iwpFKpShG6 -JwCWP4FPC27TM9AD6Ym+m182UUp0tn9HNFhGTftIsDyqkQZXVPEknu3zdVWbsbnvIR+7vUjVFu4j -Jj7MUkm054YiNX/ZUbFnma6WrO6740Gb+IpD+MkzdoiVG0rU/DtPibWAn3B6xCNRFmwIUbniNfy9 -HTOWnYqGz1Pmxo9NdzhmPE1LO8t0rWQ1geXfH/JDB/puqiGyLxum68Ze2BB2beGJnqSP2jRYfcEC -83yA+mpd04FmOQAUHo3Y8KAOqmID/Q90zhqQVNY7Exy4tUYb36/hnhpcH/ndvVOAPyH1VTtk4/tf -o1XT+WcVcupwUaPFkR4Emw3hAA7WBgf+MPjL5L7Ul6tDYGy8gFoL4BvM/4wDf13gv/5+vuj4Qdg+ -KhhCDhabezF2K7afTbRfMmpWppkDVfoBaw7kPO9jPXtzYHLEht+FcSeYbw5chsu7wNbWimIvQu4R -5ltM53PcBt/zs72a43fh++2fAhysro/Aom6210bv/xhmdLL9NvWHjH0JinFRgx9KsMLAegbgEew8 -Hz4f7H3syU4wwPp/GjzP2FOQd5RdADf72c+0vLcYmwn3+tkL2qi3Qvdp5VoOE/zsTQ2ew720vD/j -Vnl7mG8B3JZkBz+kMFB8sF7TdHGBYFP/lEKzqsDQ9NunP0BZC8jhkF0mVl4BtPLvNvt77ECFfhoN -cRasY69WVf2ZsWMPVG1lbL4KYzlYf9X0dxgxtYx15ehv0Lm+3clYNizjX75MghUG1vlGY6O9vxr/ -q68KFs6cDo5csfH2+dl+P+tVoY3RP8b//tNGdCFev2QfPFBFrbihqlLEXm/qo470sGa+F277CrsL -rsPVv9Wy30s21RAYABUfrP+A85iJzE18ZUSS/H9hHP49Bx7Y+WATIyyqxb7/bYTk7+fA91jvR8je -fRZGY3ygaM+3cbBahUNshQlo3EazXdVbT9DrL0EpWjObtFjhYP0JHCeE2/sOjMKlSgiOCFFK9wVf -4m/+Tw3eRouFru9Nsli/EJgsh2sZ+wrkveV/hlsoxmF7OriXDfagg/olo0U0XkmoUVEcLDZYjuoq -VLWDwPo4PBIgaAKdQ8SQvJOj4BbGPrBxb134FvsYt1hdWfC4scHPwP4Gt3dPvyhsXpvfQOqvoNP5 -vgpj0XgVLnAAOOgsj+fAwqrpUCxjLHBU8YYAAus7kG108Dg2vC6xqbfDOUN6sk+xF2z6sgd53PSE -2HUVNWDXGDj3Q53bPGGZToXu9Q4bA1TGvZeM18DVGlYhry9YATWQBdpqrBc+L0IY2tuPoMO0QfHu -XWSW/gPGYn/uZQ0M/l6wwSLGY8J8HS41D4CDhTHYN/hFo7EDALk7WpaDg8h7ir46SoQ68sAKCFur -IkiOg8CKzB6FgLUe4EcijgcYi+A8KN6rogb0v4DRP2QbUdocvqHQUxpZL7sgKimwOsLnhvYFS21t -QbUqkWCN7vNRJ6eA/izFbIep8uwhjNNP5kBh1e06YGBF9vUZJI5fEyfRpuW+EwYWGjO0TWXAwdJ/ -YnrB+0Hb0XKfpv9UgmU0BJbt7hUAAAvPSURBVAfr9gTB6mH3YVfQTxfs2N0tMyHnRBhYgrdfi23f -tI06Yu613gGz/ATW7mTBosA9dJRK/BjrioAr/HEg2gro2BSw/zokjZAFm9mhMQ5wzLoCAys8WrwK -ik+ZfUhhukLAIuwge7M2Dl2h6udeMZcds+m/YRTbTZZghcZYQVf4N97TiwFWD4ZScIuf+of2oxyj -O4KukDfgnzQ0WGKn++BfTK7uEnsZrrCLwq2BclUWMayuv+D9XAqH9jGMnh6J5KoIcvaF5dyA0qgH -WtrYKP13wrpeb/wax5AhnvEKBYsda209cQBmoVfkYB1AsA6I9w6AJsEKBetvGFmh/3qeneERVEyL -tRx0Ho+vMs2UzQze74LPi3hdJKy4J/ylsTty9XjIqn/mDDh471SVaeGPkowP1n4bueHP2m/ZzoPw -sPhqCow10J9TcgsPmvTfdXqf9NNSDv7FaP0b5hUxEwp1yPf7Q8HyNnq4Kfsa682B33CjeC6F9PQ9 -f8SQXoIVmm6YQhmdX6jFe3X4AYsJ1nrIEx2+JwR+y9FMYdeKTNwF8HsRwY4FnduDDwJ9P1z5U9OI -kVn7Hy17gLeC2qgGY/cAwMIj1Vef6L0PIz5+U6eq2hsSIy6sRlVRj1HfwY4tQPd1yIbo49LX0Bzl -QC69X+2hcEr/DfYMbw6zWN+F/CNsly33HT++n7+H4U/2DdaVQ51LXFwowQoD600NFu5hL4MOY6nR -G6qrooCFG43lv3n7u7nwtVNsu07x1AIoPYHNRR7wXR1uRotAeR/yliLqfTPX2KsNwy7HDnZwSqBT -n3DCXVGmRVSC7wcsdp8GqupA+5m/2R+ax3rfZnRZcPNetK+qCqOPUOxNS6V+sj+GqsgRLqLrwnCG -Aiw/kqerDpVHaYtpEQr93EbS92knJFjht3RetuMPw2/E3HkkIr8QeLnA/M3bKIClrSkWOa7TIv+h -MZo/RVc/XeL/CdmnTUcYuLuznpobxp0a0KFWRnvQUVbfJJcBliJuQr/+WJGiPdAyBfLeCM1jeRVT -9GpXmZK/mTqxPTunKzOa6Jo6x3y/qmuMMprWzFFs7xn5DhFi3We33WkEorumK8U7uP099mQRLp4a -6VyxacGGEMmhY9vLsm0Ln7/LQb6wPHzKXIV4+RHzN8de+sFVevaM53lO9dgG3XYnub/1ikJ5nKcU -Bd3ig+ZHBPYib7R3fnb+5u6B3IRudSjRxgAnPGxm552Jf5c/ua3kWJlE9PpMS111vHJslEc8yIF+ -UoNQgwLoBqOVYpRgSSWtRipIDC1R35NgSSWn7lpR5zpG5VgJllQyaq0UPbOYTw+RYEkNWG314sE0 -1XHm7UmwpAYkX3MlUkUpBk/c8ukSLKmE1d5YaT7ur7q/h0hKsKT6V2erp7qiIJATr27t/0m+Eiyp -aGrxNjd7GmurqyrLSxziOX9Clc2JPUdZgiUVTaBECFeU17Yk/nBuCZZUNBWEMFVQUe1paRvgY0kl -WFJRXSEfFt3W3pHsY24lWFJpkQRLSoIlJcGSkmBJSUmwpCRYUhIsKak0g9Vab0zwqq3nQ057vQ1b -m96OuuvL9XySoZ+1NG7b7RcTO7z1TebErdcbt/WtAHAwuPJg49am4LQA39Z62RgRqq8X2UmP0SYH -Guu3RS+q8O5WsQW2RQNuwtuCWiV2U9TWG2o3WlDs5e/11jeeSAdYEfMKt9tpTqFaGuW7juXwSYb+ -Y9NVAIe2B49rfx5ubeNzvHuX22i/8FqiYmXhW+Yi2AKVMReb8+6lAnKAGEgnSs3sn0KzCtXRf4iy -5QLRav69OpWDKj7Rw96fSa0yms95vs/GV4btEVIq0r+3iO91BFvwNWpB5fG0g/WyBouamh+zw8V9 -djw5EzhYvRdA/jbPdBj9Hk1MLW3aYHM820OgFDY9aaPqWSFaD7lbPTMh30+Tox2rmxeICfWMV0KU -YMUF630dxm1tbiwC+9tnIjdcr4lWw20ubmoEGOdH1OybPUU0PxV/dftWXDw3bHaduAuoQd4+KpqF -exXBuNO0iC2oOX6fbrCuAF71+GUtL6KSKNuZBwKs12xU1eGkDb7HvstrxPyWivy9puHJsf+dsSh0 -n+M2eBZJ/Bh87wz7GE2O7rIZ5R0O2SRY/YD1HbATGb1TqDJfmF6badYg/Y5qP2HU8RtFk+vf1ahg -5Bh4iTO3L5qlQ+P0Pzaaa/+uLW8PewJoavEGXmQvrWBlGzVmmprbOOWBQpFesD+icrA6W71i82qE -ZR1dNlRR9Me8tB93f3OU0afRrimj/X8FlVzji8TUOXyDLF40mfk+kvusBCs+WBVGISNvM9XkDJ0J -rUDpjaLV2luahZtrYzq0MlGN9C/aqKN+ciE/YF15Ctqt9/lf0lNU25YdNveiGqQPMdbzF9uod9IM -1q2Qu/lEyBkEAuzdq98KK0iKJucniOE6sdkP0dT98LEi28I96PePU6mAn4H+UmjZUVxRfITt0kQN -m8Xw+AEJVhSwOoNg/QrgzmAEHlq7YeHz4aUcXgC0WAvgslOiEsh/CiKpGhYV9HuWikKKNv1wlB60 -Yi9Q1eSP8zJGH+bk/SENYBlDvHipyIPZ6KJmrDNOyNPcGuamg2D1ziS/fgUPqdArbkbzS1Xewf4c -vy7053gditc0HlL9GHLxstgAdkXTnhMBVilrk2BFActsCsJmOjaFtszoSHubPaFbhoJ1vIjs0MkF -oCowDsF5DLJp9SpeknEBZG/XzKJF60OK6Z2cQnvpyVf0GxhY7OAC6rw5tOei7BoEqxej8F9TKObY -wU4uB/SK2aA/z3z3UUjPus7BjyhGJ9h7Dsw4wfbmIEPYl8TvUeFOvx+tXf5pCVa/YPVu4D05ZXWU -EhchYCFXo45QTw93duAl7g+UiqSm/ruOH2E4wt4xwcJ9yNWofURUiwBrd7rTDeiBPbdnO0B9Lg5Y -vpmgPm3UKcSzKcLTGWUaLyqrvV8Dx0uUJTmETClU8IhgW3SKvf4R3OzkmFw8pXYJVnxXSL+z97E8 -ozRRTLAO6ZCNsfoHOmz2U52xl9BiKUGLRUXW7EdEzvG3WraZDTpWJKp+ptVihYPFj2Hv+dH6CSZY -vinC5VFfcboyY88V8N/oFY2C7xR1vaoB/Jp/0LFVDu2BV7QJ9PiAf/A4fhzaKsgm4wVKhWQpTh5L -6PBiyDsRGyzkitfvNAKr5RhYhcRYIq+jG2DdBXeYNOZBDjdeIsb6IMk674mDdWDVFNE92AW2mGCh -FdVCe7JdOXazV9ibRVVuu8ag+R0d7Ge8CnMpjqezfR00AstQpWQpNliPlf1cOLB4VZOP6/QgGhao -wb0Kctifgr1CwxUaddXGmHYJvee4I0aamnqFf7LZ09wrxL7encYXxrZYiyHXeKbPX8vz3qFIazLF -6WOPUoVu9Q1ebnKHqPf+lRL6Owc7kGixqMb4rTCZdXhI9eBo9kqWYoM1nUprM+pOx7FYRfBR4Sd/ -oelHeMD/eQLo14E8lgjeeWb9bwG7NF2Un2QskMc6L915rPsBCmsbn5wOKsVIEU8F52Cd2asZ4X41 -FRDN3/aY3f4Sz7xrW58cBbPQQFEW9Ble1f5F0Fc3zOePnVhMi7drjh8ZaWQZvPcD1ssOyFm3rWG5 -g9d5jKjoJ8A6Qw9fEBX9eqfg1g0XYBx/hjLv6xpE5v1n1CP8iqhua1RTZmeeMffyknOZsW2VI/2Z -994N2fxeofZ8RB4raLG+ZDoyDKr2Z9P9Px5v9S7HqEmddYr6HsXcNo0+KlbaZ5GB66EbWJD9tPlh -Eqz+YqxdOvUKHaJXGL0G6cxgDdJj/F5hDm+39XRfgyruoyO8mSfvP3oq8CgU8iDB24YH6bah8jRL -PVhtnkax0OjhSavelmZPc1vYKlONnhb+1xC96PV6dpsjFl5vbqL9Xvd46Kazr8lDHY4DYiXpIG4b -NOroECVJkRe5R/QKvUabHPB6ml45FbbKkPHSbApPB/+pPa8YHu5gcxMfvOD1eGj31zweDNNagi1t -iM9GbfE0p2V0g5QUk2BJSbCkJFhSUoPW/wfr5tj8wgE+HwAAAABJRU5ErkJggg== diff --git a/Documentation/DocBook/media/selection.png.b64 b/Documentation/DocBook/media/selection.png.b64 deleted file mode 100644 index 416186558cb2..000000000000 --- a/Documentation/DocBook/media/selection.png.b64 +++ /dev/null @@ -1,206 +0,0 @@ -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 diff --git a/Documentation/DocBook/media/typical_media_device.svg b/Documentation/DocBook/media/typical_media_device.svg deleted file mode 100644 index f0c82f72c4b6..000000000000 --- a/Documentation/DocBook/media/typical_media_device.svg +++ /dev/null @@ -1,28 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<svg stroke-linejoin="round" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns="http://www.w3.org/2000/svg" clip-path="url(#a)" xml:space="preserve" fill-rule="evenodd" height="178.78mm" viewBox="0 0 24285.662 17877.829" width="251.99mm" version="1.2" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" preserveAspectRatio="xMidYMid" stroke-width="28.222"><defs><clipPath id="a" clipPathUnits="userSpaceOnUse"><rect y="0" x="0" width="28000" height="21000"/></clipPath></defs><g transform="matrix(1.004 0 0 1 -2185.6 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#fcf" d="m12231 4800c-516 0-1031 515-1031 1031v4124c0 516 515 1032 1031 1032h8538c516 0 1032-516 1032-1032v-4124c0-516-516-1031-1032-1031h-8538z"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#ffc" d="m3595 15607c-293 0-585 292-585 585v2340c0 293 292 586 585 586h3275c293 0 586-293 586-586v-2340c0-293-293-585-586-585h-3275z"/></g><g transform="translate(-2197.3 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#e6e6e6" d="m2663 2186c-461 0-922 461-922 922v11169c0 461 461 923 922 923h3692c461 0 922-462 922-923v-11169c0-461-461-922-922-922h-3692z"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#ff8080" d="m4461 8602h-2260v-1086h4520v1086h-2260z"/><path fill="none" d="m4461 8602h-2260v-1086h4520v1086h-2260z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="8275" x="2579" class="TextPosition"><tspan fill="#000000">Audio decoder</tspan></tspan></tspan></text> -</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#ff8080" d="m4461 11772h-2260v-1270h4520v1270h-2260z"/><path fill="none" d="m4461 11772h-2260v-1270h4520v1270h-2260z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="11353" x="2617" class="TextPosition"><tspan fill="#000000">Video decoder</tspan></tspan></tspan></text> -</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#ff8080" d="m4453 10217h-2269v-1224h4537v1224h-2268z"/><path fill="none" d="m4453 10217h-2269v-1224h4537v1224h-2268z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="9821" x="2571" class="TextPosition"><tspan fill="#000000">Audio encoder</tspan></tspan></tspan></text> -</g><g transform="translate(-2140.9 -2468.2)" class="com.sun.star.drawing.RectangleShape"><path fill="#cfc" d="m15711 12832h-3810v-1281h7620v1281h-3810z"/><path fill="none" d="m15711 12832h-3810v-1281h7620v1281h-3810z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="12407" x="12377" class="TextPosition"><tspan fill="#000000">Button Key/IR input logic</tspan></tspan></tspan></text> -</g><g transform="translate(-2140.9 -2411.8)" class="com.sun.star.drawing.RectangleShape"><path fill="#cfe7f5" d="m14169 14572h-2268v-1412h4536v1412h-2268z"/><path fill="none" d="m14169 14572h-2268v-1412h4536v1412h-2268z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="14082" x="12882" class="TextPosition"><tspan fill="#000000">EEPROM</tspan></tspan></tspan></text> -</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#fc9" d="m5140 17662h-1563v-1715h3126v1715h-1563z"/><path fill="none" d="m5140 17662h-1563v-1715h3126v1715h-1563z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="17020" x="4276" class="TextPosition"><tspan fill="#000000">Sensor</tspan></tspan></tspan></text> -</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m6719 8030 385-353v176h1167v-176l386 353-386 354v-177h-1167v177l-385-354z"/><path fill="none" d="m6719 8030 385-353v176h1167v-176l386 353-386 354v-177h-1167v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m6719 9612 385-353v176h1167v-176l386 353-386 354v-177h-1167v177l-385-354z"/><path fill="none" d="m6719 9612 385-353v176h1167v-176l386 353-386 354v-177h-1167v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m6721 11100 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z"/><path fill="none" d="m6721 11100 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2411.8)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9962 13854 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z"/><path fill="none" d="m9962 13854 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2468.2)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9962 12163 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z"/><path fill="none" d="m9962 12163 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9962 17158 670-353v176h2028v-176l671 353-671 354v-177h-2028v177l-670-354z"/><path fill="none" d="m9962 17158 670-353v176h2028v-176l671 353-671 354v-177h-2028v177l-670-354z" stroke="#3465af"/></g><g transform="matrix(0 .83339 -1.0005 0 30268 -5276.3)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m23229 12779 1009-978 1009 978h-505v2959h505l-1009 979-1009-979h504v-2959h-504z"/><path fill="none" d="m23229 12779 1009-978 1009 978h-505v2959h505l-1009 979-1009-979h504v-2959h-504z" stroke="#3465af"/></g><g transform="translate(-9973.6 -666.6)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="706px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="15832" x="24341" class="TextPosition" transform="matrix(0,-1,1,0,8509,40173)"><tspan fill="#000000">System Bus</tspan></tspan></tspan></text> -</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#cff" d="m13151 9262h-1250v-875h2499v875h-1249z"/><path fill="none" d="m13151 9262h-1250v-875h2499v875h-1249z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="9040" x="12215" class="TextPosition"><tspan fill="#000000">Demux</tspan></tspan></tspan></text> -</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9996 8765 373-357v178h1130v-178l374 357-374 358v-179h-1130v179l-373-358z"/><path fill="none" d="m9996 8765 373-357v178h1130v-178l374 357-374 358v-179h-1130v179l-373-358z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9996 7378 373-358v179h1130v-179l374 358-374 358v-179h-1130v179l-373-358z"/><path fill="none" d="m9996 7378 373-358v179h1130v-179l374 358-374 358v-179h-1130v179l-373-358z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#cff" d="m16322 7992h-4421v-1270h8841v1270h-4420z"/><path fill="none" d="m16322 7992h-4421v-1270h8841v1270h-4420z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="7573" x="12786" class="TextPosition"><tspan fill="#000000">Conditional Access Module</tspan></tspan></tspan></text> -</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#ff8080" d="m4445 13287h-2269v-1224h4537v1224h-2268z"/><path fill="none" d="m4445 13287h-2269v-1224h4537v1224h-2268z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="12891" x="2601" class="TextPosition"><tspan fill="#000000">Video encoder</tspan></tspan></tspan></text> -</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m6721 12634 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z"/><path fill="none" d="m6721 12634 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m20791 7545 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z"/><path fill="none" d="m20791 7545 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2028 -2186)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="14478" x="1990" class="TextPosition"><tspan fill="#000000">Radio / Analog TV</tspan></tspan></tspan></text> -</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="700" class="TextParagraph"><tspan y="10724" x="14956" class="TextPosition"><tspan fill="#000000">Digital TV</tspan></tspan></tspan></text> -</g><g transform="translate(-8970.5 -1395.8)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="494px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="19167" x="14724" class="TextPosition"><tspan fill="#000000">PS.: picture is not complete: other blocks may be present</tspan></tspan></tspan></text> -</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="18561" x="4199" class="TextPosition"><tspan fill="#000000">Webcam</tspan></tspan></tspan></text> -</g><g transform="translate(-2140.9 -2468.2)" class="com.sun.star.drawing.RectangleShape"><path fill="#f90" d="m14552 16372h-2650v-1412h5299v1412h-2649z"/><path fill="none" d="m14552 16372h-2650v-1412h5299v1412h-2649z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="15882" x="12265" class="TextPosition"><tspan fill="#000000">Processing blocks</tspan></tspan></tspan></text> -</g><g transform="translate(-2140.9 -2468.2)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9962 15654 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z"/><path fill="none" d="m9962 15654 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m6702 16954 397-353v176h1201v-176l398 353-398 354v-177h-1201v177l-397-354z"/><path fill="none" d="m6702 16954 397-353v176h1201v-176l398 353-398 354v-177h-1201v177l-397-354z" stroke="#3465af"/></g><g transform="translate(-2479.5 -2186)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="8792" x="22850" class="TextPosition"><tspan fill="#000000">Smartcard</tspan></tspan></tspan></text> -</g><g transform="matrix(1.0048 0 0 1 -2207.4 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#fcf" d="m2766 2600c-333 0-666 333-666 666v2668c0 333 333 666 666 666h18368c333 0 667-333 667-666v-2668c0-333-334-666-667-666h-18368z"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#ff8080" d="m5121 5155h-1614v-1816h3227v1816h-1613z"/><path fill="none" d="m5121 5155h-1614v-1816h3227v1816h-1613z" stroke="#3465af"/><text font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextShape"><tspan class="TextParagraph"><tspan y="4111" x="4374" class="TextPosition"><tspan fill="#000000">Tuner</tspan></tspan></tspan><tspan class="TextParagraph"><tspan y="4814" x="4151" class="TextPosition"><tspan fill="#000000">FM/TV</tspan></tspan></tspan></text> -</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#ff8080" d="m2902 3702c0 111 40 202 88 202h530c48 0 89-91 89-202 0-110-41-202-89-202h-530c-48 0-88 92-88 202z"/><path fill="none" d="m2902 3702c0 111 40 202 88 202h530c48 0 89-91 89-202 0-110-41-202-89-202h-530c-48 0-88 92-88 202z" stroke="#3465af"/><path fill="#ffb3b3" d="m2902 3702c0 111 40 202 88 202s88-91 88-202c0-110-40-202-88-202s-88 92-88 202z"/><path fill="none" d="m2902 3702c0 111 40 202 88 202s88-91 88-202c0-110-40-202-88-202s-88 92-88 202z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#ff8080" d="m2903 4267c0 110 40 202 88 202h530c48 0 89-92 89-202s-41-203-89-203h-530c-48 0-88 93-88 203z"/><path fill="none" d="m2903 4267c0 110 40 202 88 202h530c48 0 89-92 89-202s-41-203-89-203h-530c-48 0-88 93-88 203z" stroke="#3465af"/><path fill="#ffb3b3" d="m2903 4267c0 110 40 202 88 202s88-92 88-202-40-203-88-203-88 93-88 203z"/><path fill="none" d="m2903 4267c0 110 40 202 88 202s88-92 88-202-40-203-88-203-88 93-88 203z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m6719 4196 385-353v176h1167v-176l386 353-386 354v-177h-1167v177l-385-354z"/><path fill="none" d="m6719 4196 385-353v176h1167v-176l386 353-386 354v-177h-1167v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9979 4150 402-368v184h1217v-184l403 368-403 369v-185h-1217v185l-402-369z"/><path fill="none" d="m9979 4150 402-368v184h1217v-184l403 368-403 369v-185h-1217v185l-402-369z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#cff" d="m16500 6189h-4500v-1389h9e3v1389h-4500z"/><path fill="none" d="m16500 6189h-4500v-1389h9e3v1389h-4500z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="5710" x="12051" class="TextPosition"><tspan fill="#000000">Satellite Equipment Control (SEC)</tspan></tspan></tspan></text> -</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#cff" d="m13400 4600h-1400v-1e3h2800v1e3h-1400z"/><path fill="none" d="m13400 4600h-1400v-1e3h2800v1e3h-1400z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="4316" x="12465" class="TextPosition"><tspan fill="#000000">Demod</tspan></tspan></tspan></text> -</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9979 5451 402-368v184h1217v-184l403 368-403 369v-185h-1217v185l-402-369z"/><path fill="none" d="m9979 5451 402-368v184h1217v-184l403 368-403 369v-185h-1217v185l-402-369z" stroke="#3465af"/></g><path fill="#ff9" d="m7855.1 9099v7302h-1270v-14605h1270v7303z"/><path fill="none" d="m7855.1 9099v7302h-1270v-14605h1270v7303z" stroke="#3465af"/><text y="-6640.4663" x="-20770.572" transform="rotate(-90)" class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="7409.5396" x="-11193.634" class="TextPosition" transform="matrix(0,-1,1,0,-4473,23627)"><tspan fill="#000000">I2C Bus (control bus)</tspan></tspan></tspan></text> -<g transform="translate(-2197.3 -2186)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="3278" x="9391" class="TextPosition"><tspan fill="#000000">Digital TV Frontend</tspan></tspan></tspan></text> -</g><g transform="matrix(1.015 0 0 .99994 -2233.3 -2185.7)" class="com.sun.star.drawing.CustomShape"><g stroke="#3465af" fill="none"><path d="m3e3 2800c-18 0-35 1-53 3"/><path d="m2915 2808c-17 3-35 7-52 12"/><path d="m2832 2830c-16 6-33 12-49 20"/><path d="m2754 2864c-15 8-31 17-46 27"/><path d="m2681 2909c-14 10-28 21-42 32"/><path d="m2614 2962c-13 12-26 24-38 37"/><path d="m2554 3023c-11 13-22 27-33 41"/><path d="m2502 3091c-10 14-19 29-28 45"/><path d="m2459 3164c-8 16-15 32-22 49"/><path d="m2426 3243c-5 17-10 34-14 51"/><path d="m2406 3326c-3 18-5 35-6 53"/><path d="m2400 3411v53"/><path d="m2400 3497v53"/><path d="m2400 3582v53"/><path d="m2400 3668v53"/><path d="m2400 3753v53"/><path d="m2400 3839v53"/><path d="m2400 3924v53"/><path d="m2400 4009v54"/><path d="m2400 4095v53"/><path d="m2400 4180v53"/><path d="m2400 4266v53"/><path d="m2400 4351v53"/><path d="m2400 4437v53"/><path d="m2400 4522v53"/><path d="m2400 4607v54"/><path d="m2400 4693v53"/><path d="m2400 4778v53"/><path d="m2400 4864v53"/><path d="m2400 4949v53"/><path d="m2400 5035v53"/><path d="m2400 5120v53"/><path d="m2400 5205v54"/><path d="m2400 5291v53"/><path d="m2400 5376v53"/><path d="m2400 5462v53"/><path d="m2400 5547v53"/><path d="m2400 5633v53"/><path d="m2400 5718v53"/><path d="m2400 5803c0 18 1 36 3 53"/><path d="m2408 5888c4 18 8 35 13 52"/><path d="m2431 5971c6 16 13 33 20 49"/><path d="m2466 6049c8 15 17 31 27 46"/><path d="m2511 6122c10 14 21 28 32 42"/><path d="m2564 6188c12 13 25 26 38 38"/><path d="m2626 6248c13 11 27 23 41 33"/><path d="m2694 6300c14 10 29 19 45 27"/><path d="m2768 6343c15 7 32 15 48 21"/><path d="m2847 6375c17 5 34 10 51 14"/><path d="m2930 6395c17 2 35 4 53 5"/><path d="m3015 6400h53"/><path d="m3100 6400h53"/><path d="m3186 6400h53"/><path d="m3271 6400h53"/><path d="m3357 6400h53"/><path d="m3442 6400h53"/><path d="m3527 6400h54"/><path d="m3613 6400h53"/><path d="m3698 6400h53"/><path d="m3784 6400h53"/><path d="m3869 6400h53"/><path d="m3955 6400h53"/><path d="m4040 6400h53"/><path d="m4125 6400h54"/><path d="m4211 6400h53"/><path d="m4296 6400h53"/><path d="m4382 6400h53"/><path d="m4467 6400h53"/><path d="m4553 6400h53"/><path d="m4638 6400h53"/><path d="m4723 6400h54"/><path d="m4809 6400h53"/><path d="m4894 6400h53"/><path d="m4980 6400h53"/><path d="m5065 6400h53"/><path d="m5151 6400h53"/><path d="m5236 6400h53"/><path d="m5322 6400h53"/><path d="m5407 6400h53"/><path d="m5492 6400h53"/><path d="m5578 6400h53"/><path d="m5663 6400h53"/><path d="m5749 6400h53"/><path d="m5834 6400h53"/><path d="m5920 6400h53"/><path d="m6005 6400h53"/><path d="m6090 6400h53"/><path d="m6176 6400h53"/><path d="m6261 6400h53"/><path d="m6347 6400h53"/><path d="m6432 6400h53"/><path d="m6518 6400h53"/><path d="m6603 6400h53"/><path d="m6688 6400h54"/><path d="m6774 6400h53"/><path d="m6859 6400h53"/><path d="m6945 6400h53"/><path d="m7030 6400h53"/><path d="m7116 6400h53"/><path d="m7201 6400h53"/><path d="m7286 6400h54"/><path d="m7372 6400h53"/><path d="m7457 6400h53"/><path d="m7543 6400h53"/><path d="m7628 6400h53"/><path d="m7714 6400h53"/><path d="m7799 6400h53"/><path d="m7884 6400h54"/><path d="m7970 6400h53"/><path d="m8055 6400h53"/><path d="m8141 6400h53"/><path d="m8226 6400h53"/><path d="m8312 6400h53"/><path d="m8397 6400h53"/><path d="m8482 6400h54"/><path d="m8568 6400h53"/><path d="m8653 6400h53"/><path d="m8739 6400h53"/><path d="m8824 6400h53"/><path d="m8910 6400h53"/><path d="m8995 6400h53"/><path d="m9081 6400h53"/><path d="m9166 6400h53"/><path d="m9251 6400h53"/><path d="m9337 6400h53"/><path d="m9422 6400h53"/><path d="m9508 6400h53"/><path d="m9593 6400h53"/><path d="m9679 6400h53"/><path d="m9764 6400h53"/><path d="m9849 6400h53"/><path d="m9935 6400h53"/><path d="m10020 6400h53"/><path d="m10106 6400h53"/><path d="m10191 6400h53"/><path d="m10277 6400h53"/><path d="m10362 6400h53"/><path d="m10447 6400h53"/><path d="m10533 6400h53"/><path d="m10618 6400h53"/><path d="m10704 6400h53"/><path d="m10789 6400h53"/><path d="m10875 6400h53"/><path d="m10960 6400h53"/><path d="m11045 6400h54"/><path d="m11131 6400h53"/><path d="m11216 6400h53"/><path d="m11302 6400h53"/><path d="m11387 6400h53"/><path d="m11473 6400h53"/><path d="m11558 6400h53"/><path d="m11643 6400h54"/><path d="m11729 6400h53"/><path d="m11814 6400h53"/><path d="m11900 6400h53"/><path d="m11985 6400h53"/><path d="m12071 6400h53"/><path d="m12156 6400h53"/><path d="m12241 6400h54"/><path d="m12327 6400h53"/><path d="m12412 6400h53"/><path d="m12498 6400h53"/><path d="m12583 6400h53"/><path d="m12669 6400h53"/><path d="m12754 6400h53"/><path d="m12839 6400h54"/><path d="m12925 6400h53"/><path d="m13010 6400h53"/><path d="m13096 6400h53"/><path d="m13181 6400h53"/><path d="m13267 6400h53"/><path d="m13352 6400h53"/><path d="m13438 6400h53"/><path d="m13523 6400h53"/><path d="m13608 6400h53"/><path d="m13694 6400h53"/><path d="m13779 6400h53"/><path d="m13865 6400h53"/><path d="m13950 6400h53"/><path d="m14036 6400h53"/><path d="m14121 6400h53"/><path d="m14206 6400h53"/><path d="m14292 6400h53"/><path d="m14377 6400h53"/><path d="m14463 6400h53"/><path d="m14548 6400h53"/><path d="m14634 6400h53"/><path d="m14719 6400h53"/><path d="m14804 6400h54"/><path d="m14890 6400h53"/><path d="m14975 6400h53"/><path d="m15061 6400h53"/><path d="m15146 6400h53"/><path d="m15232 6400h53"/><path d="m15317 6400h53"/><path d="m15402 6400h54"/><path d="m15488 6400h53"/><path d="m15573 6400h53"/><path d="m15659 6400h53"/><path d="m15744 6400h53"/><path d="m15830 6400h53"/><path d="m15915 6400h53"/><path d="m16000 6400h54"/><path d="m16086 6400h53"/><path d="m16171 6400h53"/><path d="m16257 6400h53"/><path d="m16342 6400h53"/><path d="m16428 6400h53"/><path d="m16513 6400h53"/><path d="m16598 6400h54"/><path d="m16684 6400h53"/><path d="m16769 6400h53"/><path d="m16855 6400h53"/><path d="m16940 6400h53"/><path d="m17026 6400h53"/><path d="m17111 6400h53"/><path d="m17196 6400h54"/><path d="m17282 6400h53"/><path d="m17367 6400h53"/><path d="m17453 6400h53"/><path d="m17538 6400h53"/><path d="m17624 6400h53"/><path d="m17709 6400h53"/><path d="m17795 6400h53"/><path d="m17880 6400h53"/><path d="m17965 6400h53"/><path d="m18051 6400h53"/><path d="m18136 6400h53"/><path d="m18222 6400h53"/><path d="m18307 6400h53"/><path d="m18393 6400h53"/><path d="m18478 6400h53"/><path d="m18563 6400h53"/><path d="m18649 6400h53"/><path d="m18734 6400h53"/><path d="m18820 6400h53"/><path d="m18905 6400h53"/><path d="m18991 6400h53"/><path d="m19076 6400h53"/><path d="m19161 6400h54"/><path d="m19247 6400h53"/><path d="m19332 6400h53"/><path d="m19418 6400h53"/><path d="m19503 6400h53"/><path d="m19589 6400h53"/><path d="m19674 6400h53"/><path d="m19759 6400h54"/><path d="m19845 6400h53"/><path d="m19930 6400h53"/><path d="m20016 6400h53"/><path d="m20101 6400h53"/><path d="m20187 6400h53"/><path d="m20272 6400h53"/><path d="m20357 6400h54"/><path d="m20443 6400h53"/><path d="m20528 6400h53"/><path d="m20614 6400c17-1 35-2 53-5"/><path d="m20699 6390c17-4 34-9 51-14"/><path d="m20781 6365c16-6 32-13 48-21"/><path d="m20858 6329c15-8 31-17 45-27"/><path d="m20930 6283c14-10 28-21 42-32"/><path d="m20996 6229c13-12 25-25 37-38"/><path d="m21055 6167c11-14 22-28 33-42"/><path d="m21106 6098c10-15 19-30 27-45"/><path d="m21148 6024c7-16 14-33 20-49"/><path d="m21179 5944c5-17 9-34 13-51"/><path d="m21197 5861c2-18 4-35 4-53"/><path d="m21201 5776v-54"/><path d="m21201 5690v-53"/><path d="m21201 5605v-53"/><path d="m21201 5519v-53"/><path d="m21201 5434v-53"/><path d="m21201 5348v-53"/><path d="m21201 5263v-53"/><path d="m21201 5178v-54"/><path d="m21201 5092v-53"/><path d="m21201 5007v-53"/><path d="m21201 4921v-53"/><path d="m21201 4836v-53"/><path d="m21201 4750v-53"/><path d="m21201 4665v-53"/><path d="m21201 4579v-53"/><path d="m21201 4494v-53"/><path d="m21201 4409v-53"/><path d="m21201 4323v-53"/><path d="m21201 4238v-53"/><path d="m21201 4152v-53"/><path d="m21201 4067v-53"/><path d="m21201 3981v-53"/><path d="m21201 3896v-53"/><path d="m21201 3811v-53"/><path d="m21201 3725v-53"/><path d="m21201 3640v-53"/><path d="m21201 3554v-53"/><path d="m21201 3469v-53"/><path d="m21201 3383c-1-17-3-35-5-52"/><path d="m21190 3299c-4-17-8-35-14-51"/><path d="m21165 3217c-6-16-13-33-21-49"/><path d="m21129 3140c-9-16-18-31-28-46"/><path d="m21082 3068c-10-14-21-28-33-42"/><path d="m21027 3002c-12-13-24-25-37-37"/><path d="m20965 2944c-14-12-28-22-42-33"/><path d="m20896 2893c-15-9-30-18-46-27"/><path d="m20821 2852c-16-8-32-14-49-20"/><path d="m20741 2821c-17-5-34-9-51-12"/><path d="m20658 2804c-18-3-35-4-53-4"/><path d="m20573 2800h-53"/><path d="m20487 2800h-53"/><path d="m20402 2800h-53"/><path d="m20316 2800h-53"/><path d="m20231 2800h-53"/><path d="m20146 2800h-54"/><path d="m20060 2800h-53"/><path d="m19975 2800h-53"/><path d="m19889 2800h-53"/><path d="m19804 2800h-53"/><path d="m19718 2800h-53"/><path d="m19633 2800h-53"/><path d="m19548 2800h-54"/><path d="m19462 2800h-53"/><path d="m19377 2800h-53"/><path d="m19291 2800h-53"/><path d="m19206 2800h-53"/><path d="m19120 2800h-53"/><path d="m19035 2800h-53"/><path d="m18950 2800h-54"/><path d="m18864 2800h-53"/><path d="m18779 2800h-53"/><path d="m18693 2800h-53"/><path d="m18608 2800h-53"/><path d="m18522 2800h-53"/><path d="m18437 2800h-53"/><path d="m18352 2800h-54"/><path d="m18266 2800h-53"/><path d="m18181 2800h-53"/><path d="m18095 2800h-53"/><path d="m18010 2800h-53"/><path d="m17924 2800h-53"/><path d="m17839 2800h-53"/><path d="m17753 2800h-53"/><path d="m17668 2800h-53"/><path d="m17583 2800h-53"/><path d="m17497 2800h-53"/><path d="m17412 2800h-53"/><path d="m17326 2800h-53"/><path d="m17241 2800h-53"/><path d="m17155 2800h-53"/><path d="m17070 2800h-53"/><path d="m16985 2800h-53"/><path d="m16899 2800h-53"/><path d="m16814 2800h-53"/><path d="m16728 2800h-53"/><path d="m16643 2800h-53"/><path d="m16557 2800h-53"/><path d="m16472 2800h-53"/><path d="m16387 2800h-54"/><path d="m16301 2800h-53"/><path d="m16216 2800h-53"/><path d="m16130 2800h-53"/><path d="m16045 2800h-53"/><path d="m15959 2800h-53"/><path d="m15874 2800h-53"/><path d="m15789 2800h-54"/><path d="m15703 2800h-53"/><path d="m15618 2800h-53"/><path d="m15532 2800h-53"/><path d="m15447 2800h-53"/><path d="m15361 2800h-53"/><path d="m15276 2800h-53"/><path d="m15191 2800h-54"/><path d="m15105 2800h-53"/><path d="m15020 2800h-53"/><path d="m14934 2800h-53"/><path d="m14849 2800h-53"/><path d="m14763 2800h-53"/><path d="m14678 2800h-53"/><path d="m14593 2800h-54"/><path d="m14507 2800h-53"/><path d="m14422 2800h-53"/><path d="m14336 2800h-53"/><path d="m14251 2800h-53"/><path d="m14165 2800h-53"/><path d="m14080 2800h-53"/><path d="m13994 2800h-53"/><path d="m13909 2800h-53"/><path d="m13824 2800h-53"/><path d="m13738 2800h-53"/><path d="m13653 2800h-53"/><path d="m13567 2800h-53"/><path d="m13482 2800h-53"/><path d="m13396 2800h-53"/><path d="m13311 2800h-53"/><path d="m13226 2800h-53"/><path d="m13140 2800h-53"/><path d="m13055 2800h-53"/><path d="m12969 2800h-53"/><path d="m12884 2800h-53"/><path d="m12798 2800h-53"/><path d="m12713 2800h-53"/><path d="m12628 2800h-53"/><path d="m12542 2800h-53"/><path d="m12457 2800h-53"/><path d="m12371 2800h-53"/><path d="m12286 2800h-53"/><path d="m12200 2800h-53"/><path d="m12115 2800h-53"/><path d="m12030 2800h-54"/><path d="m11944 2800h-53"/><path d="m11859 2800h-53"/><path d="m11773 2800h-53"/><path d="m11688 2800h-53"/><path d="m11602 2800h-53"/><path d="m11517 2800h-53"/><path d="m11432 2800h-54"/><path d="m11346 2800h-53"/><path d="m11261 2800h-53"/><path d="m11175 2800h-53"/><path d="m11090 2800h-53"/><path d="m11004 2800h-53"/><path d="m10919 2800h-53"/><path d="m10834 2800h-54"/><path d="m10748 2800h-53"/><path d="m10663 2800h-53"/><path d="m10577 2800h-53"/><path d="m10492 2800h-53"/><path d="m10406 2800h-53"/><path d="m10321 2800h-53"/><path d="m10236 2800h-54"/><path d="m10150 2800h-53"/><path d="m10065 2800h-53"/><path d="m9979 2800h-53"/><path d="m9894 2800h-53"/><path d="m9808 2800h-53"/><path d="m9723 2800h-53"/><path d="m9637 2800h-53"/><path d="m9552 2800h-53"/><path d="m9467 2800h-53"/><path d="m9381 2800h-53"/><path d="m9296 2800h-53"/><path d="m9210 2800h-53"/><path d="m9125 2800h-53"/><path d="m9039 2800h-53"/><path d="m8954 2800h-53"/><path d="m8869 2800h-53"/><path d="m8783 2800h-53"/><path d="m8698 2800h-53"/><path d="m8612 2800h-53"/><path d="m8527 2800h-53"/><path d="m8441 2800h-53"/><path d="m8356 2800h-53"/><path d="m8271 2800h-54"/><path d="m8185 2800h-53"/><path d="m8100 2800h-53"/><path d="m8014 2800h-53"/><path d="m7929 2800h-53"/><path d="m7843 2800h-53"/><path d="m7758 2800h-53"/><path d="m7673 2800h-54"/><path d="m7587 2800h-53"/><path d="m7502 2800h-53"/><path d="m7416 2800h-53"/><path d="m7331 2800h-53"/><path d="m7245 2800h-53"/><path d="m7160 2800h-53"/><path d="m7075 2800h-54"/><path d="m6989 2800h-53"/><path d="m6904 2800h-53"/><path d="m6818 2800h-53"/><path d="m6733 2800h-53"/><path d="m6647 2800h-53"/><path d="m6562 2800h-53"/><path d="m6477 2800h-54"/><path d="m6391 2800h-53"/><path d="m6306 2800h-53"/><path d="m6220 2800h-53"/><path d="m6135 2800h-53"/><path d="m6049 2800h-53"/><path d="m5964 2800h-53"/><path d="m5879 2800h-54"/><path d="m5793 2800h-53"/><path d="m5708 2800h-53"/><path d="m5622 2800h-53"/><path d="m5537 2800h-53"/><path d="m5451 2800h-53"/><path d="m5366 2800h-53"/><path d="m5280 2800h-53"/><path d="m5195 2800h-53"/><path d="m5110 2800h-53"/><path d="m5024 2800h-53"/><path d="m4939 2800h-53"/><path d="m4853 2800h-53"/><path d="m4768 2800h-53"/><path d="m4682 2800h-53"/><path d="m4597 2800h-53"/><path d="m4512 2800h-53"/><path d="m4426 2800h-53"/><path d="m4341 2800h-53"/><path d="m4255 2800h-53"/><path d="m4170 2800h-53"/><path d="m4084 2800h-53"/><path d="m3999 2800h-53"/><path d="m3914 2800h-54"/><path d="m3828 2800h-53"/><path d="m3743 2800h-53"/><path d="m3657 2800h-53"/><path d="m3572 2800h-53"/><path d="m3486 2800h-53"/><path d="m3401 2800h-53"/><path d="m3316 2800h-54"/><path d="m3230 2800h-53"/><path d="m3145 2800h-53"/><path d="m3059 2800h-53"/></g></g><g transform="translate(-2197.3 -2186)"><rect height="1100.7" width="1213.6" y="6917.1" x="23255" fill="#f3e777"/><path fill="#ca4677" d="m22802 7700.4v-405.46l150.7-169.16c82.886-93.039 170.53-186.62 194.77-207.96l44.069-38.798 783.23-0.086 783.23-0.086v613.5 613.5h-978-978v-405.46zm1027.7 136.98v-78.372l-169.91 4.925-169.91 4.9249-5.09 45.854c-8.249 74.303 46.711 101.04 207.69 101.04h137.21v-78.372zm235.86-262.94 4.495-341.31 207.2-8.6408 207.2-8.6408 5.144-46.443c9.596-86.615-41.863-102.05-322.02-96.607l-246.71 4.7956-4.438 419.08-4.439 419.08h74.537 74.538l4.494-341.31zm391.3 313.72c26.41-19.286 36.255-41.399 32.697-73.447l-5.09-45.854h-174.05-174.05l-5.38 48.984c-9.97 90.771 0.993 97.91 150.36 97.91 99.305 0 148.27-7.6982 175.52-27.594zm-627.16-274.84v-77.768h-174.05-174.05v66.246c0 36.436 4.973 71.431 11.051 77.768 6.078 6.3366 84.401 11.521 174.05 11.521h163v-77.768zm659.89-4.9154 5.125-74.042-179.18 4.9155-179.18 4.9155-5.38 48.984c-10.473 95.348-2.259 99.57 183.28 94.197l170.2-4.9284 5.125-74.042zm-659.89-237.63v-78.372l-169.91 4.925-169.91 4.925-5.097 73.447-5.097 73.447h175 175v-78.372zm659.86 4.925-5.097-73.447h-174.05-174.05l-5.38 48.984c-10.289 93.673-2.146 97.91 188.15 97.91h175.52l-5.097-73.447zm-659.86-228.98v-77.768h-137.21c-97.358 0-147.91 7.8138-174.05 26.902-34.952 25.523-49.645 92.242-25.79 117.11 6.078 6.3366 84.401 11.521 174.05 11.521h163v-77.768z"/></g><g transform="matrix(.84874 0 0 .76147 2408.1 3615.3)"><rect height="3076.2" width="2734.3" y="13264" x="19249" fill="#6076b3"/><g stroke-linejoin="round" fill-rule="evenodd" stroke-width="28.222" fill="#e0ee2c"><rect y="13369" width="356.65" x="18937" height="180.95"/><rect y="13708" width="356.65" x="18937" height="180.95"/><rect y="14048" width="356.65" x="18937" height="180.95"/><rect y="14387" width="356.65" x="18937" height="180.95"/><rect y="14726" width="356.65" x="18937" height="180.95"/><rect y="15066" width="356.65" x="18937" height="180.95"/><rect y="15405" width="356.65" x="18937" height="180.95"/><rect y="15744" width="356.65" x="18937" height="180.95"/><rect y="16083" width="356.65" x="18937" height="180.95"/><rect y="13324" width="356.65" x="21939" height="180.95"/><rect y="13663" width="356.65" x="21939" height="180.95"/><rect y="14002" width="356.65" x="21939" height="180.95"/><rect y="14342" width="356.65" x="21939" height="180.95"/><rect y="14681" width="356.65" x="21939" height="180.95"/><rect y="15020" width="356.65" x="21939" height="180.95"/><rect y="15360" width="356.65" x="21939" height="180.95"/><rect y="15699" width="356.65" x="21939" height="180.95"/><rect y="16038" width="356.65" x="21939" height="180.95"/></g><g stroke-linejoin="round" fill-rule="evenodd" transform="matrix(.98702 0 0 .90336 -2675 7020.8)" class="com.sun.star.drawing.TextShape" stroke-width="28.222"><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"/></text> -<text style="word-spacing:0px;letter-spacing:0px" xml:space="preserve" font-size="1128.9px" y="9042.0264" x="22439.668" font-family="Sans" line-height="125%" fill="#000000"><tspan y="9042.0264" x="22439.668">CPU</tspan></text> -</g></g><g stroke-linejoin="round" fill-rule="evenodd" transform="translate(-11752 543.6)" class="com.sun.star.drawing.TextShape" stroke-width="28.222"><text class="TextShape"><tspan font-size="706px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="15832" x="24341" class="TextPosition" transform="matrix(0,-1,1,0,8509,40173)"><tspan fill="#000000">PCI, USB, SPI, I2C, ...</tspan></tspan></tspan></text> -</g><g stroke-linejoin="round" fill-rule="evenodd" transform="translate(-655.31 963.83)" class="com.sun.star.drawing.RectangleShape" stroke-width="28.222"><g transform="matrix(.49166 0 0 1.0059 6045.6 -82.24)"><path fill="#cfe7f5" d="m14169 14572h-2268v-1412h4536v1412h-2268z"/><path fill="none" d="m14169 14572h-2268v-1412h4536v1412h-2268z" stroke="#3465af"/></g><text y="-395.11282" x="-790.22229" class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="13686.9" x="12091.779" class="TextPosition"><tspan fill="#000000">Bridge</tspan></tspan></tspan></text> -<text y="338.66486" x="-846.66675" class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="14420.677" x="12035.335" class="TextPosition"><tspan fill="#000000"> DMA</tspan></tspan></tspan></text> -</g></svg> diff --git a/Documentation/DocBook/media/v4l/.gitignore b/Documentation/DocBook/media/v4l/.gitignore deleted file mode 100644 index d7ec32eafac9..000000000000 --- a/Documentation/DocBook/media/v4l/.gitignore +++ /dev/null @@ -1 +0,0 @@ -!*.xml diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml deleted file mode 100644 index 9beb30f0071b..000000000000 --- a/Documentation/DocBook/media/v4l/biblio.xml +++ /dev/null @@ -1,371 +0,0 @@ - <bibliography> - <title>References</title> - - <biblioentry id="cea608"> - <abbrev>CEA 608-E</abbrev> - <authorgroup> - <corpauthor>Consumer Electronics Association (<ulink -url="http://www.ce.org">http://www.ce.org</ulink>)</corpauthor> - </authorgroup> - <title>CEA-608-E R-2014 "Line 21 Data Services"</title> - </biblioentry> - - <biblioentry id="en300294"> - <abbrev>EN 300 294</abbrev> - <authorgroup> - <corpauthor>European Telecommunication Standards Institute -(<ulink url="http://www.etsi.org">http://www.etsi.org</ulink>)</corpauthor> - </authorgroup> - <title>EN 300 294 "625-line television Wide Screen Signalling -(WSS)"</title> - </biblioentry> - - <biblioentry id="ets300231"> - <abbrev>ETS 300 231</abbrev> - <authorgroup> - <corpauthor>European Telecommunication Standards Institute -(<ulink -url="http://www.etsi.org">http://www.etsi.org</ulink>)</corpauthor> - </authorgroup> - <title>ETS 300 231 "Specification of the domestic video -Programme Delivery Control system (PDC)"</title> - </biblioentry> - - <biblioentry id="ets300706"> - <abbrev>ETS 300 706</abbrev> - <authorgroup> - <corpauthor>European Telecommunication Standards Institute -(<ulink url="http://www.etsi.org">http://www.etsi.org</ulink>)</corpauthor> - </authorgroup> - <title>ETS 300 706 "Enhanced Teletext specification"</title> - </biblioentry> - - <biblioentry id="mpeg2part1"> - <abbrev>ISO 13818-1</abbrev> - <authorgroup> - <corpauthor>International Telecommunication Union (<ulink -url="http://www.itu.ch">http://www.itu.ch</ulink>), International -Organisation for Standardisation (<ulink -url="http://www.iso.ch">http://www.iso.ch</ulink>)</corpauthor> - </authorgroup> - <title>ITU-T Rec. H.222.0 | ISO/IEC 13818-1 "Information -technology — Generic coding of moving pictures and associated -audio information: Systems"</title> - </biblioentry> - - <biblioentry id="mpeg2part2"> - <abbrev>ISO 13818-2</abbrev> - <authorgroup> - <corpauthor>International Telecommunication Union (<ulink -url="http://www.itu.ch">http://www.itu.ch</ulink>), International -Organisation for Standardisation (<ulink -url="http://www.iso.ch">http://www.iso.ch</ulink>)</corpauthor> - </authorgroup> - <title>ITU-T Rec. H.262 | ISO/IEC 13818-2 "Information -technology — Generic coding of moving pictures and associated -audio information: Video"</title> - </biblioentry> - - <biblioentry id="itu470"> - <abbrev>ITU BT.470</abbrev> - <authorgroup> - <corpauthor>International Telecommunication Union (<ulink -url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor> - </authorgroup> - <title>ITU-R Recommendation BT.470-6 "Conventional Television -Systems"</title> - </biblioentry> - - <biblioentry id="itu601"> - <abbrev>ITU BT.601</abbrev> - <authorgroup> - <corpauthor>International Telecommunication Union (<ulink -url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor> - </authorgroup> - <title>ITU-R Recommendation BT.601-5 "Studio Encoding Parameters -of Digital Television for Standard 4:3 and Wide-Screen 16:9 Aspect -Ratios"</title> - </biblioentry> - - <biblioentry id="itu653"> - <abbrev>ITU BT.653</abbrev> - <authorgroup> - <corpauthor>International Telecommunication Union (<ulink -url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor> - </authorgroup> - <title>ITU-R Recommendation BT.653-3 "Teletext systems"</title> - </biblioentry> - - <biblioentry id="itu709"> - <abbrev>ITU BT.709</abbrev> - <authorgroup> - <corpauthor>International Telecommunication Union (<ulink -url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor> - </authorgroup> - <title>ITU-R Recommendation BT.709-5 "Parameter values for the -HDTV standards for production and international programme -exchange"</title> - </biblioentry> - - <biblioentry id="itu1119"> - <abbrev>ITU BT.1119</abbrev> - <authorgroup> - <corpauthor>International Telecommunication Union (<ulink -url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor> - </authorgroup> - <title>ITU-R Recommendation BT.1119 "625-line -television Wide Screen Signalling (WSS)"</title> - </biblioentry> - - <biblioentry id="jfif"> - <abbrev>JFIF</abbrev> - <authorgroup> - <corpauthor>Independent JPEG Group (<ulink -url="http://www.ijg.org">http://www.ijg.org</ulink>)</corpauthor> - </authorgroup> - <title>JPEG File Interchange Format</title> - <subtitle>Version 1.02</subtitle> - </biblioentry> - - <biblioentry id="itu-t81"> - <abbrev>ITU-T.81</abbrev> - <authorgroup> - <corpauthor>International Telecommunication Union -(<ulink url="http://www.itu.int">http://www.itu.int</ulink>)</corpauthor> - </authorgroup> - <title>ITU-T Recommendation T.81 -"Information Technology — Digital Compression and Coding of Continous-Tone -Still Images — Requirements and Guidelines"</title> - </biblioentry> - - <biblioentry id="w3c-jpeg-jfif"> - <abbrev>W3C JPEG JFIF</abbrev> - <authorgroup> - <corpauthor>The World Wide Web Consortium (<ulink -url="http://www.w3.org/Graphics/JPEG">http://www.w3.org</ulink>)</corpauthor> - </authorgroup> - <title>JPEG JFIF</title> - </biblioentry> - - <biblioentry id="smpte12m"> - <abbrev>SMPTE 12M</abbrev> - <authorgroup> - <corpauthor>Society of Motion Picture and Television Engineers -(<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor> - </authorgroup> - <title>SMPTE 12M-1999 "Television, Audio and Film - Time and -Control Code"</title> - </biblioentry> - - <biblioentry id="smpte170m"> - <abbrev>SMPTE 170M</abbrev> - <authorgroup> - <corpauthor>Society of Motion Picture and Television Engineers -(<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor> - </authorgroup> - <title>SMPTE 170M-1999 "Television - Composite Analog Video -Signal - NTSC for Studio Applications"</title> - </biblioentry> - - <biblioentry id="smpte240m"> - <abbrev>SMPTE 240M</abbrev> - <authorgroup> - <corpauthor>Society of Motion Picture and Television Engineers -(<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor> - </authorgroup> - <title>SMPTE 240M-1999 "Television - Signal Parameters - -1125-Line High-Definition Production"</title> - </biblioentry> - - <biblioentry id="smpte431"> - <abbrev>SMPTE RP 431-2</abbrev> - <authorgroup> - <corpauthor>Society of Motion Picture and Television Engineers -(<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor> - </authorgroup> - <title>SMPTE RP 431-2:2011 "D-Cinema Quality - Reference Projector and Environment"</title> - </biblioentry> - - <biblioentry id="smpte2084"> - <abbrev>SMPTE ST 2084</abbrev> - <authorgroup> - <corpauthor>Society of Motion Picture and Television Engineers -(<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor> - </authorgroup> - <title>SMPTE ST 2084:2014 "High Dynamic Range Electro-Optical Transfer Function of Master Reference Displays"</title> - </biblioentry> - - <biblioentry id="srgb"> - <abbrev>sRGB</abbrev> - <authorgroup> - <corpauthor>International Electrotechnical Commission -(<ulink url="http://www.iec.ch">http://www.iec.ch</ulink>)</corpauthor> - </authorgroup> - <title>IEC 61966-2-1 ed1.0 "Multimedia systems and equipment - Colour measurement -and management - Part 2-1: Colour management - Default RGB colour space - sRGB"</title> - </biblioentry> - - <biblioentry id="sycc"> - <abbrev>sYCC</abbrev> - <authorgroup> - <corpauthor>International Electrotechnical Commission -(<ulink url="http://www.iec.ch">http://www.iec.ch</ulink>)</corpauthor> - </authorgroup> - <title>IEC 61966-2-1-am1 ed1.0 "Amendment 1 - Multimedia systems and equipment - Colour measurement -and management - Part 2-1: Colour management - Default RGB colour space - sRGB"</title> - </biblioentry> - - <biblioentry id="xvycc"> - <abbrev>xvYCC</abbrev> - <authorgroup> - <corpauthor>International Electrotechnical Commission -(<ulink url="http://www.iec.ch">http://www.iec.ch</ulink>)</corpauthor> - </authorgroup> - <title>IEC 61966-2-4 ed1.0 "Multimedia systems and equipment - Colour measurement -and management - Part 2-4: Colour management - Extended-gamut YCC colour space for video -applications - xvYCC"</title> - </biblioentry> - - <biblioentry id="adobergb"> - <abbrev>AdobeRGB</abbrev> - <authorgroup> - <corpauthor>Adobe Systems Incorporated (<ulink url="http://www.adobe.com">http://www.adobe.com</ulink>)</corpauthor> - </authorgroup> - <title>Adobe© RGB (1998) Color Image Encoding Version 2005-05</title> - </biblioentry> - - <biblioentry id="oprgb"> - <abbrev>opRGB</abbrev> - <authorgroup> - <corpauthor>International Electrotechnical Commission -(<ulink url="http://www.iec.ch">http://www.iec.ch</ulink>)</corpauthor> - </authorgroup> - <title>IEC 61966-2-5 "Multimedia systems and equipment - Colour measurement -and management - Part 2-5: Colour management - Optional RGB colour space - opRGB"</title> - </biblioentry> - - <biblioentry id="itu2020"> - <abbrev>ITU BT.2020</abbrev> - <authorgroup> - <corpauthor>International Telecommunication Union (<ulink -url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor> - </authorgroup> - <title>ITU-R Recommendation BT.2020 (08/2012) "Parameter values for ultra-high -definition television systems for production and international programme exchange" -</title> - </biblioentry> - - <biblioentry id="tech3213"> - <abbrev>EBU Tech 3213</abbrev> - <authorgroup> - <corpauthor>European Broadcast Union (<ulink -url="http://www.ebu.ch">http://www.ebu.ch</ulink>)</corpauthor> - </authorgroup> - <title>E.B.U. Standard for Chromaticity Tolerances for Studio Monitors"</title> - </biblioentry> - - <biblioentry id="iec62106"> - <abbrev>IEC 62106</abbrev> - <authorgroup> - <corpauthor>International Electrotechnical Commission -(<ulink url="http://www.iec.ch">http://www.iec.ch</ulink>)</corpauthor> - </authorgroup> - <title>Specification of the radio data system (RDS) for VHF/FM sound broadcasting -in the frequency range from 87,5 to 108,0 MHz</title> - </biblioentry> - - <biblioentry id="nrsc4"> - <abbrev>NRSC-4-B</abbrev> - <authorgroup> - <corpauthor>National Radio Systems Committee -(<ulink url="http://www.nrscstandards.org">http://www.nrscstandards.org</ulink>)</corpauthor> - </authorgroup> - <title>NRSC-4-B: United States RBDS Standard</title> - </biblioentry> - - <biblioentry id="iso12232"> - <abbrev>ISO 12232:2006</abbrev> - <authorgroup> - <corpauthor>International Organization for Standardization -(<ulink url="http://www.iso.org">http://www.iso.org</ulink>)</corpauthor> - </authorgroup> - <title>Photography — Digital still cameras — Determination - of exposure index, ISO speed ratings, standard output sensitivity, and - recommended exposure index</title> - </biblioentry> - - <biblioentry id="cea861"> - <abbrev>CEA-861-E</abbrev> - <authorgroup> - <corpauthor>Consumer Electronics Association -(<ulink url="http://www.ce.org">http://www.ce.org</ulink>)</corpauthor> - </authorgroup> - <title>A DTV Profile for Uncompressed High Speed Digital Interfaces</title> - </biblioentry> - - <biblioentry id="vesadmt"> - <abbrev>VESA DMT</abbrev> - <authorgroup> - <corpauthor>Video Electronics Standards Association -(<ulink url="http://www.vesa.org">http://www.vesa.org</ulink>)</corpauthor> - </authorgroup> - <title>VESA and Industry Standards and Guidelines for Computer Display Monitor Timing (DMT)</title> - </biblioentry> - - <biblioentry id="vesaedid"> - <abbrev>EDID</abbrev> - <authorgroup> - <corpauthor>Video Electronics Standards Association -(<ulink url="http://www.vesa.org">http://www.vesa.org</ulink>)</corpauthor> - </authorgroup> - <title>VESA Enhanced Extended Display Identification Data Standard</title> - <subtitle>Release A, Revision 2</subtitle> - </biblioentry> - - <biblioentry id="hdcp"> - <abbrev>HDCP</abbrev> - <authorgroup> - <corpauthor>Digital Content Protection LLC -(<ulink url="http://www.digital-cp.com">http://www.digital-cp.com</ulink>)</corpauthor> - </authorgroup> - <title>High-bandwidth Digital Content Protection System</title> - <subtitle>Revision 1.3</subtitle> - </biblioentry> - - <biblioentry id="hdmi"> - <abbrev>HDMI</abbrev> - <authorgroup> - <corpauthor>HDMI Licensing LLC -(<ulink url="http://www.hdmi.org">http://www.hdmi.org</ulink>)</corpauthor> - </authorgroup> - <title>High-Definition Multimedia Interface</title> - <subtitle>Specification Version 1.4a</subtitle> - </biblioentry> - - <biblioentry id="dp"> - <abbrev>DP</abbrev> - <authorgroup> - <corpauthor>Video Electronics Standards Association -(<ulink url="http://www.vesa.org">http://www.vesa.org</ulink>)</corpauthor> - </authorgroup> - <title>VESA DisplayPort Standard</title> - <subtitle>Version 1, Revision 2</subtitle> - </biblioentry> - - <biblioentry id="poynton"> - <abbrev>poynton</abbrev> - <authorgroup> - <corpauthor>Charles Poynton</corpauthor> - </authorgroup> - <title>Digital Video and HDTV, Algorithms and Interfaces</title> - </biblioentry> - - <biblioentry id="colimg"> - <abbrev>colimg</abbrev> - <authorgroup> - <corpauthor>Erik Reinhard et al.</corpauthor> - </authorgroup> - <title>Color Imaging: Fundamentals and Applications</title> - </biblioentry> - - </bibliography> diff --git a/Documentation/DocBook/media/v4l/capture.c.xml b/Documentation/DocBook/media/v4l/capture.c.xml deleted file mode 100644 index 22126a991b34..000000000000 --- a/Documentation/DocBook/media/v4l/capture.c.xml +++ /dev/null @@ -1,659 +0,0 @@ -<programlisting> -/* - * V4L2 video capture example - * - * This program can be used and distributed without restrictions. - * - * This program is provided with the V4L2 API - * see https://linuxtv.org/docs.php for more information - */ - -#include <stdio.h> -#include <stdlib.h> -#include <string.h> -#include <assert.h> - -#include <getopt.h> /* getopt_long() */ - -#include <fcntl.h> /* low-level i/o */ -#include <unistd.h> -#include <errno.h> -#include <sys/stat.h> -#include <sys/types.h> -#include <sys/time.h> -#include <sys/mman.h> -#include <sys/ioctl.h> - -#include <linux/videodev2.h> - -#define CLEAR(x) memset(&(x), 0, sizeof(x)) - -enum io_method { - IO_METHOD_READ, - IO_METHOD_MMAP, - IO_METHOD_USERPTR, -}; - -struct buffer { - void *start; - size_t length; -}; - -static char *dev_name; -static enum io_method io = IO_METHOD_MMAP; -static int fd = -1; -struct buffer *buffers; -static unsigned int n_buffers; -static int out_buf; -static int force_format; -static int frame_count = 70; - -static void errno_exit(const char *s) -{ - fprintf(stderr, "%s error %d, %s\n", s, errno, strerror(errno)); - exit(EXIT_FAILURE); -} - -static int xioctl(int fh, int request, void *arg) -{ - int r; - - do { - r = ioctl(fh, request, arg); - } while (-1 == r && EINTR == errno); - - return r; -} - -static void process_image(const void *p, int size) -{ - if (out_buf) - fwrite(p, size, 1, stdout); - - fflush(stderr); - fprintf(stderr, "."); - fflush(stdout); -} - -static int read_frame(void) -{ - struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf; - unsigned int i; - - switch (io) { - case IO_METHOD_READ: - if (-1 == read(fd, buffers[0].start, buffers[0].length)) { - switch (errno) { - case EAGAIN: - return 0; - - case EIO: - /* Could ignore EIO, see spec. */ - - /* fall through */ - - default: - errno_exit("read"); - } - } - - process_image(buffers[0].start, buffers[0].length); - break; - - case IO_METHOD_MMAP: - CLEAR(buf); - - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - buf.memory = V4L2_MEMORY_MMAP; - - if (-1 == xioctl(fd, VIDIOC_DQBUF, &buf)) { - switch (errno) { - case EAGAIN: - return 0; - - case EIO: - /* Could ignore EIO, see spec. */ - - /* fall through */ - - default: - errno_exit("VIDIOC_DQBUF"); - } - } - - assert(buf.index < n_buffers); - - process_image(buffers[buf.index].start, buf.bytesused); - - if (-1 == xioctl(fd, VIDIOC_QBUF, &buf)) - errno_exit("VIDIOC_QBUF"); - break; - - case IO_METHOD_USERPTR: - CLEAR(buf); - - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - buf.memory = V4L2_MEMORY_USERPTR; - - if (-1 == xioctl(fd, VIDIOC_DQBUF, &buf)) { - switch (errno) { - case EAGAIN: - return 0; - - case EIO: - /* Could ignore EIO, see spec. */ - - /* fall through */ - - default: - errno_exit("VIDIOC_DQBUF"); - } - } - - for (i = 0; i < n_buffers; ++i) - if (buf.m.userptr == (unsigned long)buffers[i].start - && buf.length == buffers[i].length) - break; - - assert(i < n_buffers); - - process_image((void *)buf.m.userptr, buf.bytesused); - - if (-1 == xioctl(fd, VIDIOC_QBUF, &buf)) - errno_exit("VIDIOC_QBUF"); - break; - } - - return 1; -} - -static void mainloop(void) -{ - unsigned int count; - - count = frame_count; - - while (count-- > 0) { - for (;;) { - fd_set fds; - struct timeval tv; - int r; - - FD_ZERO(&fds); - FD_SET(fd, &fds); - - /* Timeout. */ - tv.tv_sec = 2; - tv.tv_usec = 0; - - r = select(fd + 1, &fds, NULL, NULL, &tv); - - if (-1 == r) { - if (EINTR == errno) - continue; - errno_exit("select"); - } - - if (0 == r) { - fprintf(stderr, "select timeout\n"); - exit(EXIT_FAILURE); - } - - if (read_frame()) - break; - /* EAGAIN - continue select loop. */ - } - } -} - -static void stop_capturing(void) -{ - enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; - - switch (io) { - case IO_METHOD_READ: - /* Nothing to do. */ - break; - - case IO_METHOD_MMAP: - case IO_METHOD_USERPTR: - type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - if (-1 == xioctl(fd, VIDIOC_STREAMOFF, &type)) - errno_exit("VIDIOC_STREAMOFF"); - break; - } -} - -static void start_capturing(void) -{ - unsigned int i; - enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; - - switch (io) { - case IO_METHOD_READ: - /* Nothing to do. */ - break; - - case IO_METHOD_MMAP: - for (i = 0; i < n_buffers; ++i) { - struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf; - - CLEAR(buf); - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - buf.memory = V4L2_MEMORY_MMAP; - buf.index = i; - - if (-1 == xioctl(fd, VIDIOC_QBUF, &buf)) - errno_exit("VIDIOC_QBUF"); - } - type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - if (-1 == xioctl(fd, VIDIOC_STREAMON, &type)) - errno_exit("VIDIOC_STREAMON"); - break; - - case IO_METHOD_USERPTR: - for (i = 0; i < n_buffers; ++i) { - struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf; - - CLEAR(buf); - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - buf.memory = V4L2_MEMORY_USERPTR; - buf.index = i; - buf.m.userptr = (unsigned long)buffers[i].start; - buf.length = buffers[i].length; - - if (-1 == xioctl(fd, VIDIOC_QBUF, &buf)) - errno_exit("VIDIOC_QBUF"); - } - type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - if (-1 == xioctl(fd, VIDIOC_STREAMON, &type)) - errno_exit("VIDIOC_STREAMON"); - break; - } -} - -static void uninit_device(void) -{ - unsigned int i; - - switch (io) { - case IO_METHOD_READ: - free(buffers[0].start); - break; - - case IO_METHOD_MMAP: - for (i = 0; i < n_buffers; ++i) - if (-1 == munmap(buffers[i].start, buffers[i].length)) - errno_exit("munmap"); - break; - - case IO_METHOD_USERPTR: - for (i = 0; i < n_buffers; ++i) - free(buffers[i].start); - break; - } - - free(buffers); -} - -static void init_read(unsigned int buffer_size) -{ - buffers = calloc(1, sizeof(*buffers)); - - if (!buffers) { - fprintf(stderr, "Out of memory\n"); - exit(EXIT_FAILURE); - } - - buffers[0].length = buffer_size; - buffers[0].start = malloc(buffer_size); - - if (!buffers[0].start) { - fprintf(stderr, "Out of memory\n"); - exit(EXIT_FAILURE); - } -} - -static void init_mmap(void) -{ - struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> req; - - CLEAR(req); - - req.count = 4; - req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - req.memory = V4L2_MEMORY_MMAP; - - if (-1 == xioctl(fd, VIDIOC_REQBUFS, &req)) { - if (EINVAL == errno) { - fprintf(stderr, "%s does not support " - "memory mapping\n", dev_name); - exit(EXIT_FAILURE); - } else { - errno_exit("VIDIOC_REQBUFS"); - } - } - - if (req.count < 2) { - fprintf(stderr, "Insufficient buffer memory on %s\n", - dev_name); - exit(EXIT_FAILURE); - } - - buffers = calloc(req.count, sizeof(*buffers)); - - if (!buffers) { - fprintf(stderr, "Out of memory\n"); - exit(EXIT_FAILURE); - } - - for (n_buffers = 0; n_buffers < req.count; ++n_buffers) { - struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf; - - CLEAR(buf); - - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - buf.memory = V4L2_MEMORY_MMAP; - buf.index = n_buffers; - - if (-1 == xioctl(fd, VIDIOC_QUERYBUF, &buf)) - errno_exit("VIDIOC_QUERYBUF"); - - buffers[n_buffers].length = buf.length; - buffers[n_buffers].start = - mmap(NULL /* start anywhere */, - buf.length, - PROT_READ | PROT_WRITE /* required */, - MAP_SHARED /* recommended */, - fd, buf.m.offset); - - if (MAP_FAILED == buffers[n_buffers].start) - errno_exit("mmap"); - } -} - -static void init_userp(unsigned int buffer_size) -{ - struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> req; - - CLEAR(req); - - req.count = 4; - req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - req.memory = V4L2_MEMORY_USERPTR; - - if (-1 == xioctl(fd, VIDIOC_REQBUFS, &req)) { - if (EINVAL == errno) { - fprintf(stderr, "%s does not support " - "user pointer i/o\n", dev_name); - exit(EXIT_FAILURE); - } else { - errno_exit("VIDIOC_REQBUFS"); - } - } - - buffers = calloc(4, sizeof(*buffers)); - - if (!buffers) { - fprintf(stderr, "Out of memory\n"); - exit(EXIT_FAILURE); - } - - for (n_buffers = 0; n_buffers < 4; ++n_buffers) { - buffers[n_buffers].length = buffer_size; - buffers[n_buffers].start = malloc(buffer_size); - - if (!buffers[n_buffers].start) { - fprintf(stderr, "Out of memory\n"); - exit(EXIT_FAILURE); - } - } -} - -static void init_device(void) -{ - struct <link linkend="v4l2-capability">v4l2_capability</link> cap; - struct <link linkend="v4l2-cropcap">v4l2_cropcap</link> cropcap; - struct <link linkend="v4l2-crop">v4l2_crop</link> crop; - struct <link linkend="v4l2-format">v4l2_format</link> fmt; - unsigned int min; - - if (-1 == xioctl(fd, VIDIOC_QUERYCAP, &cap)) { - if (EINVAL == errno) { - fprintf(stderr, "%s is no V4L2 device\n", - dev_name); - exit(EXIT_FAILURE); - } else { - errno_exit("VIDIOC_QUERYCAP"); - } - } - - if (!(cap.capabilities & V4L2_CAP_VIDEO_CAPTURE)) { - fprintf(stderr, "%s is no video capture device\n", - dev_name); - exit(EXIT_FAILURE); - } - - switch (io) { - case IO_METHOD_READ: - if (!(cap.capabilities & V4L2_CAP_READWRITE)) { - fprintf(stderr, "%s does not support read i/o\n", - dev_name); - exit(EXIT_FAILURE); - } - break; - - case IO_METHOD_MMAP: - case IO_METHOD_USERPTR: - if (!(cap.capabilities & V4L2_CAP_STREAMING)) { - fprintf(stderr, "%s does not support streaming i/o\n", - dev_name); - exit(EXIT_FAILURE); - } - break; - } - - - /* Select video input, video standard and tune here. */ - - - CLEAR(cropcap); - - cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - - if (0 == xioctl(fd, VIDIOC_CROPCAP, &cropcap)) { - crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - crop.c = cropcap.defrect; /* reset to default */ - - if (-1 == xioctl(fd, VIDIOC_S_CROP, &crop)) { - switch (errno) { - case EINVAL: - /* Cropping not supported. */ - break; - default: - /* Errors ignored. */ - break; - } - } - } else { - /* Errors ignored. */ - } - - - CLEAR(fmt); - - fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - if (force_format) { - fmt.fmt.pix.width = 640; - fmt.fmt.pix.height = 480; - fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV; - fmt.fmt.pix.field = V4L2_FIELD_INTERLACED; - - if (-1 == xioctl(fd, VIDIOC_S_FMT, &fmt)) - errno_exit("VIDIOC_S_FMT"); - - /* Note VIDIOC_S_FMT may change width and height. */ - } else { - /* Preserve original settings as set by v4l2-ctl for example */ - if (-1 == xioctl(fd, VIDIOC_G_FMT, &fmt)) - errno_exit("VIDIOC_G_FMT"); - } - - /* Buggy driver paranoia. */ - min = fmt.fmt.pix.width * 2; - if (fmt.fmt.pix.bytesperline < min) - fmt.fmt.pix.bytesperline = min; - min = fmt.fmt.pix.bytesperline * fmt.fmt.pix.height; - if (fmt.fmt.pix.sizeimage < min) - fmt.fmt.pix.sizeimage = min; - - switch (io) { - case IO_METHOD_READ: - init_read(fmt.fmt.pix.sizeimage); - break; - - case IO_METHOD_MMAP: - init_mmap(); - break; - - case IO_METHOD_USERPTR: - init_userp(fmt.fmt.pix.sizeimage); - break; - } -} - -static void close_device(void) -{ - if (-1 == close(fd)) - errno_exit("close"); - - fd = -1; -} - -static void open_device(void) -{ - struct stat st; - - if (-1 == stat(dev_name, &st)) { - fprintf(stderr, "Cannot identify '%s': %d, %s\n", - dev_name, errno, strerror(errno)); - exit(EXIT_FAILURE); - } - - if (!S_ISCHR(st.st_mode)) { - fprintf(stderr, "%s is no device\n", dev_name); - exit(EXIT_FAILURE); - } - - fd = open(dev_name, O_RDWR /* required */ | O_NONBLOCK, 0); - - if (-1 == fd) { - fprintf(stderr, "Cannot open '%s': %d, %s\n", - dev_name, errno, strerror(errno)); - exit(EXIT_FAILURE); - } -} - -static void usage(FILE *fp, int argc, char **argv) -{ - fprintf(fp, - "Usage: %s [options]\n\n" - "Version 1.3\n" - "Options:\n" - "-d | --device name Video device name [%s]\n" - "-h | --help Print this message\n" - "-m | --mmap Use memory mapped buffers [default]\n" - "-r | --read Use read() calls\n" - "-u | --userp Use application allocated buffers\n" - "-o | --output Outputs stream to stdout\n" - "-f | --format Force format to 640x480 YUYV\n" - "-c | --count Number of frames to grab [%i]\n" - "", - argv[0], dev_name, frame_count); -} - -static const char short_options[] = "d:hmruofc:"; - -static const struct option -long_options[] = { - { "device", required_argument, NULL, 'd' }, - { "help", no_argument, NULL, 'h' }, - { "mmap", no_argument, NULL, 'm' }, - { "read", no_argument, NULL, 'r' }, - { "userp", no_argument, NULL, 'u' }, - { "output", no_argument, NULL, 'o' }, - { "format", no_argument, NULL, 'f' }, - { "count", required_argument, NULL, 'c' }, - { 0, 0, 0, 0 } -}; - -int main(int argc, char **argv) -{ - dev_name = "/dev/video0"; - - for (;;) { - int idx; - int c; - - c = getopt_long(argc, argv, - short_options, long_options, &idx); - - if (-1 == c) - break; - - switch (c) { - case 0: /* getopt_long() flag */ - break; - - case 'd': - dev_name = optarg; - break; - - case 'h': - usage(stdout, argc, argv); - exit(EXIT_SUCCESS); - - case 'm': - io = IO_METHOD_MMAP; - break; - - case 'r': - io = IO_METHOD_READ; - break; - - case 'u': - io = IO_METHOD_USERPTR; - break; - - case 'o': - out_buf++; - break; - - case 'f': - force_format++; - break; - - case 'c': - errno = 0; - frame_count = strtol(optarg, NULL, 0); - if (errno) - errno_exit(optarg); - break; - - default: - usage(stderr, argc, argv); - exit(EXIT_FAILURE); - } - } - - open_device(); - init_device(); - start_capturing(); - mainloop(); - stop_capturing(); - uninit_device(); - close_device(); - fprintf(stderr, "\n"); - return 0; -} -</programlisting> diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml deleted file mode 100644 index 8b5e014224d6..000000000000 --- a/Documentation/DocBook/media/v4l/common.xml +++ /dev/null @@ -1,1102 +0,0 @@ - <title>Common API Elements</title> - - <para>Programming a V4L2 device consists of these -steps:</para> - - <itemizedlist> - <listitem> - <para>Opening the device</para> - </listitem> - <listitem> - <para>Changing device properties, selecting a video and audio -input, video standard, picture brightness a. o.</para> - </listitem> - <listitem> - <para>Negotiating a data format</para> - </listitem> - <listitem> - <para>Negotiating an input/output method</para> - </listitem> - <listitem> - <para>The actual input/output loop</para> - </listitem> - <listitem> - <para>Closing the device</para> - </listitem> - </itemizedlist> - - <para>In practice most steps are optional and can be executed out of -order. It depends on the V4L2 device type, you can read about the -details in <xref linkend="devices" />. In this chapter we will discuss -the basic concepts applicable to all devices.</para> - - <section id="open"> - <title>Opening and Closing Devices</title> - - <section> - <title>Device Naming</title> - - <para>V4L2 drivers are implemented as kernel modules, loaded -manually by the system administrator or automatically when a device is -first discovered. The driver modules plug into the "videodev" kernel -module. It provides helper functions and a common application -interface specified in this document.</para> - - <para>Each driver thus loaded registers one or more device nodes -with major number 81 and a minor number between 0 and 255. Minor numbers -are allocated dynamically unless the kernel is compiled with the kernel -option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers are -allocated in ranges depending on the device node type (video, radio, etc.).</para> - - <para>Many drivers support "video_nr", "radio_nr" or "vbi_nr" -module options to select specific video/radio/vbi node numbers. This allows -the user to request that the device node is named e.g. /dev/video5 instead -of leaving it to chance. When the driver supports multiple devices of the same -type more than one device node number can be assigned, separated by commas: - <informalexample> - <screen> -> modprobe mydriver video_nr=0,1 radio_nr=0,1</screen> - </informalexample></para> - - <para>In <filename>/etc/modules.conf</filename> this may be -written as: <informalexample> - <screen> -options mydriver video_nr=0,1 radio_nr=0,1 - </screen> - </informalexample> When no device node number is given as module -option the driver supplies a default.</para> - - <para>Normally udev will create the device nodes in /dev automatically -for you. If udev is not installed, then you need to enable the -CONFIG_VIDEO_FIXED_MINOR_RANGES kernel option in order to be able to correctly -relate a minor number to a device node number. I.e., you need to be certain -that minor number 5 maps to device node name video5. With this kernel option -different device types have different minor number ranges. These ranges are -listed in <xref linkend="devices" />. -</para> - - <para>The creation of character special files (with -<application>mknod</application>) is a privileged operation and -devices cannot be opened by major and minor number. That means -applications cannot <emphasis>reliable</emphasis> scan for loaded or -installed drivers. The user must enter a device name, or the -application can try the conventional device names.</para> - </section> - - <section id="related"> - <title>Related Devices</title> - - <para>Devices can support several functions. For example -video capturing, VBI capturing and radio support.</para> - - <para>The V4L2 API creates different nodes for each of these functions.</para> - - <para>The V4L2 API was designed with the idea that one device node could support -all functions. However, in practice this never worked: this 'feature' -was never used by applications and many drivers did not support it and if -they did it was certainly never tested. In addition, switching a device -node between different functions only works when using the streaming I/O -API, not with the read()/write() API.</para> - - <para>Today each device node supports just one function.</para> - - <para>Besides video input or output the hardware may also -support audio sampling or playback. If so, these functions are -implemented as ALSA PCM devices with optional ALSA audio mixer -devices.</para> - - <para>One problem with all these devices is that the V4L2 API -makes no provisions to find these related devices. Some really -complex devices use the Media Controller (see <xref linkend="media_controller" />) -which can be used for this purpose. But most drivers do not use it, -and while some code exists that uses sysfs to discover related devices -(see libmedia_dev in the <ulink url="http://git.linuxtv.org/cgit.cgi/v4l-utils.git/">v4l-utils</ulink> -git repository), there is no library yet that can provide a single API towards -both Media Controller-based devices and devices that do not use the Media Controller. -If you want to work on this please write to the linux-media mailing list: &v4l-ml;.</para> - </section> - - <section> - <title>Multiple Opens</title> - - <para>V4L2 devices can be opened more than once.<footnote><para> -There are still some old and obscure drivers that have not been updated to -allow for multiple opens. This implies that for such drivers &func-open; can -return an &EBUSY; when the device is already in use.</para></footnote> -When this is supported by the driver, users can for example start a -"panel" application to change controls like brightness or audio -volume, while another application captures video and audio. In other words, panel -applications are comparable to an ALSA audio mixer application. -Just opening a V4L2 device should not change the state of the device.<footnote> -<para>Unfortunately, opening a radio device often switches the state of the -device to radio mode in many drivers. This behavior should be fixed eventually -as it violates the V4L2 specification.</para></footnote></para> - - <para>Once an application has allocated the memory buffers needed for -streaming data (by calling the &VIDIOC-REQBUFS; or &VIDIOC-CREATE-BUFS; ioctls, -or implicitly by calling the &func-read; or &func-write; functions) that -application (filehandle) becomes the owner of the device. It is no longer -allowed to make changes that would affect the buffer sizes (e.g. by calling -the &VIDIOC-S-FMT; ioctl) and other applications are no longer allowed to allocate -buffers or start or stop streaming. The &EBUSY; will be returned instead.</para> - - <para>Merely opening a V4L2 device does not grant exclusive -access.<footnote> - <para>Drivers could recognize the -<constant>O_EXCL</constant> open flag. Presently this is not required, -so applications cannot know if it really works.</para> - </footnote> Initiating data exchange however assigns the right -to read or write the requested type of data, and to change related -properties, to this file descriptor. Applications can request -additional access privileges using the priority mechanism described in -<xref linkend="app-pri" />.</para> - </section> - - <section> - <title>Shared Data Streams</title> - - <para>V4L2 drivers should not support multiple applications -reading or writing the same data stream on a device by copying -buffers, time multiplexing or similar means. This is better handled by -a proxy application in user space.</para> - </section> - - <section> - <title>Functions</title> - - <para>To open and close V4L2 devices applications use the -&func-open; and &func-close; function, respectively. Devices are -programmed using the &func-ioctl; function as explained in the -following sections.</para> - </section> - </section> - - <section id="querycap"> - <title>Querying Capabilities</title> - - <para>Because V4L2 covers a wide variety of devices not all -aspects of the API are equally applicable to all types of devices. -Furthermore devices of the same type have different capabilities and -this specification permits the omission of a few complicated and less -important parts of the API.</para> - - <para>The &VIDIOC-QUERYCAP; ioctl is available to check if the kernel -device is compatible with this specification, and to query the <link -linkend="devices">functions</link> and <link linkend="io">I/O -methods</link> supported by the device.</para> - - <para>Starting with kernel version 3.1, VIDIOC-QUERYCAP will return the -V4L2 API version used by the driver, with generally matches the Kernel version. -There's no need of using &VIDIOC-QUERYCAP; to check if a specific ioctl is -supported, the V4L2 core now returns ENOTTY if a driver doesn't provide -support for an ioctl.</para> - - <para>Other features can be queried -by calling the respective ioctl, for example &VIDIOC-ENUMINPUT; -to learn about the number, types and names of video connectors on the -device. Although abstraction is a major objective of this API, the -&VIDIOC-QUERYCAP; ioctl also allows driver specific applications to reliably identify -the driver.</para> - - <para>All V4L2 drivers must support -<constant>VIDIOC_QUERYCAP</constant>. Applications should always call -this ioctl after opening the device.</para> - </section> - - <section id="app-pri"> - <title>Application Priority</title> - - <para>When multiple applications share a device it may be -desirable to assign them different priorities. Contrary to the -traditional "rm -rf /" school of thought a video recording application -could for example block other applications from changing video -controls or switching the current TV channel. Another objective is to -permit low priority applications working in background, which can be -preempted by user controlled applications and automatically regain -control of the device at a later time.</para> - - <para>Since these features cannot be implemented entirely in user -space V4L2 defines the &VIDIOC-G-PRIORITY; and &VIDIOC-S-PRIORITY; -ioctls to request and query the access priority associate with a file -descriptor. Opening a device assigns a medium priority, compatible -with earlier versions of V4L2 and drivers not supporting these ioctls. -Applications requiring a different priority will usually call -<constant>VIDIOC_S_PRIORITY</constant> after verifying the device with -the &VIDIOC-QUERYCAP; ioctl.</para> - - <para>Ioctls changing driver properties, such as &VIDIOC-S-INPUT;, -return an &EBUSY; after another application obtained higher priority.</para> - </section> - - <section id="video"> - <title>Video Inputs and Outputs</title> - - <para>Video inputs and outputs are physical connectors of a -device. These can be for example RF connectors (antenna/cable), CVBS -a.k.a. Composite Video, S-Video or RGB connectors. Video and VBI -capture devices have inputs. Video and VBI output devices have outputs, -at least one each. Radio devices have no video inputs or outputs.</para> - - <para>To learn about the number and attributes of the -available inputs and outputs applications can enumerate them with the -&VIDIOC-ENUMINPUT; and &VIDIOC-ENUMOUTPUT; ioctl, respectively. The -&v4l2-input; returned by the <constant>VIDIOC_ENUMINPUT</constant> -ioctl also contains signal status information applicable when the -current video input is queried.</para> - - <para>The &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; ioctls return the -index of the current video input or output. To select a different -input or output applications call the &VIDIOC-S-INPUT; and -&VIDIOC-S-OUTPUT; ioctls. Drivers must implement all the input ioctls -when the device has one or more inputs, all the output ioctls when the -device has one or more outputs.</para> - - <example> - <title>Information about the current video input</title> - - <programlisting> -&v4l2-input; input; -int index; - -if (-1 == ioctl(fd, &VIDIOC-G-INPUT;, &index)) { - perror("VIDIOC_G_INPUT"); - exit(EXIT_FAILURE); -} - -memset(&input, 0, sizeof(input)); -input.index = index; - -if (-1 == ioctl(fd, &VIDIOC-ENUMINPUT;, &input)) { - perror("VIDIOC_ENUMINPUT"); - exit(EXIT_FAILURE); -} - -printf("Current input: %s\n", input.name); - </programlisting> - </example> - - <example> - <title>Switching to the first video input</title> - - <programlisting> -int index; - -index = 0; - -if (-1 == ioctl(fd, &VIDIOC-S-INPUT;, &index)) { - perror("VIDIOC_S_INPUT"); - exit(EXIT_FAILURE); -} - </programlisting> - </example> - </section> - - <section id="audio"> - <title>Audio Inputs and Outputs</title> - - <para>Audio inputs and outputs are physical connectors of a -device. Video capture devices have inputs, output devices have -outputs, zero or more each. Radio devices have no audio inputs or -outputs. They have exactly one tuner which in fact -<emphasis>is</emphasis> an audio source, but this API associates -tuners with video inputs or outputs only, and radio devices have -none of these.<footnote> - <para>Actually &v4l2-audio; ought to have a -<structfield>tuner</structfield> field like &v4l2-input;, not only -making the API more consistent but also permitting radio devices with -multiple tuners.</para> - </footnote> A connector on a TV card to loop back the received -audio signal to a sound card is not considered an audio output.</para> - - <para>Audio and video inputs and outputs are associated. Selecting -a video source also selects an audio source. This is most evident when -the video and audio source is a tuner. Further audio connectors can -combine with more than one video input or output. Assumed two -composite video inputs and two audio inputs exist, there may be up to -four valid combinations. The relation of video and audio connectors -is defined in the <structfield>audioset</structfield> field of the -respective &v4l2-input; or &v4l2-output;, where each bit represents -the index number, starting at zero, of one audio input or output.</para> - - <para>To learn about the number and attributes of the -available inputs and outputs applications can enumerate them with the -&VIDIOC-ENUMAUDIO; and &VIDIOC-ENUMAUDOUT; ioctl, respectively. The -&v4l2-audio; returned by the <constant>VIDIOC_ENUMAUDIO</constant> ioctl -also contains signal status information applicable when the current -audio input is queried.</para> - - <para>The &VIDIOC-G-AUDIO; and &VIDIOC-G-AUDOUT; ioctls report -the current audio input and output, respectively. Note that, unlike -&VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; these ioctls return a structure -as <constant>VIDIOC_ENUMAUDIO</constant> and -<constant>VIDIOC_ENUMAUDOUT</constant> do, not just an index.</para> - - <para>To select an audio input and change its properties -applications call the &VIDIOC-S-AUDIO; ioctl. To select an audio -output (which presently has no changeable properties) applications -call the &VIDIOC-S-AUDOUT; ioctl.</para> - - <para>Drivers must implement all audio input ioctls when the device -has multiple selectable audio inputs, all audio output ioctls when the -device has multiple selectable audio outputs. When the device has any -audio inputs or outputs the driver must set the <constant>V4L2_CAP_AUDIO</constant> -flag in the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl.</para> - - <example> - <title>Information about the current audio input</title> - - <programlisting> -&v4l2-audio; audio; - -memset(&audio, 0, sizeof(audio)); - -if (-1 == ioctl(fd, &VIDIOC-G-AUDIO;, &audio)) { - perror("VIDIOC_G_AUDIO"); - exit(EXIT_FAILURE); -} - -printf("Current input: %s\n", audio.name); - </programlisting> - </example> - - <example> - <title>Switching to the first audio input</title> - - <programlisting> -&v4l2-audio; audio; - -memset(&audio, 0, sizeof(audio)); /* clear audio.mode, audio.reserved */ - -audio.index = 0; - -if (-1 == ioctl(fd, &VIDIOC-S-AUDIO;, &audio)) { - perror("VIDIOC_S_AUDIO"); - exit(EXIT_FAILURE); -} - </programlisting> - </example> - </section> - - <section id="tuner"> - <title>Tuners and Modulators</title> - - <section> - <title>Tuners</title> - - <para>Video input devices can have one or more tuners -demodulating a RF signal. Each tuner is associated with one or more -video inputs, depending on the number of RF connectors on the tuner. -The <structfield>type</structfield> field of the respective -&v4l2-input; returned by the &VIDIOC-ENUMINPUT; ioctl is set to -<constant>V4L2_INPUT_TYPE_TUNER</constant> and its -<structfield>tuner</structfield> field contains the index number of -the tuner.</para> - - <para>Radio input devices have exactly one tuner with index zero, no -video inputs.</para> - - <para>To query and change tuner properties applications use the -&VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; ioctls, respectively. The -&v4l2-tuner; returned by <constant>VIDIOC_G_TUNER</constant> also -contains signal status information applicable when the tuner of the -current video or radio input is queried. Note that -<constant>VIDIOC_S_TUNER</constant> does not switch the current tuner, -when there is more than one at all. The tuner is solely determined by -the current video input. Drivers must support both ioctls and set the -<constant>V4L2_CAP_TUNER</constant> flag in the &v4l2-capability; -returned by the &VIDIOC-QUERYCAP; ioctl when the device has one or -more tuners.</para> - </section> - - <section> - <title>Modulators</title> - - <para>Video output devices can have one or more modulators, uh, -modulating a video signal for radiation or connection to the antenna -input of a TV set or video recorder. Each modulator is associated with -one or more video outputs, depending on the number of RF connectors on -the modulator. The <structfield>type</structfield> field of the -respective &v4l2-output; returned by the &VIDIOC-ENUMOUTPUT; ioctl is -set to <constant>V4L2_OUTPUT_TYPE_MODULATOR</constant> and its -<structfield>modulator</structfield> field contains the index number -of the modulator.</para> - - <para>Radio output devices have exactly one modulator with index -zero, no video outputs.</para> - - <para>A video or radio device cannot support both a tuner and a -modulator. Two separate device nodes will have to be used for such -hardware, one that supports the tuner functionality and one that supports -the modulator functionality. The reason is a limitation with the -&VIDIOC-S-FREQUENCY; ioctl where you cannot specify whether the frequency -is for a tuner or a modulator.</para> - - <para>To query and change modulator properties applications use -the &VIDIOC-G-MODULATOR; and &VIDIOC-S-MODULATOR; ioctl. Note that -<constant>VIDIOC_S_MODULATOR</constant> does not switch the current -modulator, when there is more than one at all. The modulator is solely -determined by the current video output. Drivers must support both -ioctls and set the <constant>V4L2_CAP_MODULATOR</constant> flag in -the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl when the -device has one or more modulators.</para> - </section> - - <section> - <title>Radio Frequency</title> - - <para>To get and set the tuner or modulator radio frequency -applications use the &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY; -ioctl which both take a pointer to a &v4l2-frequency;. These ioctls -are used for TV and radio devices alike. Drivers must support both -ioctls when the tuner or modulator ioctls are supported, or -when the device is a radio device.</para> - </section> - </section> - - <section id="standard"> - <title>Video Standards</title> - - <para>Video devices typically support one or more different video -standards or variations of standards. Each video input and output may -support another set of standards. This set is reported by the -<structfield>std</structfield> field of &v4l2-input; and -&v4l2-output; returned by the &VIDIOC-ENUMINPUT; and -&VIDIOC-ENUMOUTPUT; ioctls, respectively.</para> - - <para>V4L2 defines one bit for each analog video standard -currently in use worldwide, and sets aside bits for driver defined -standards, ⪚ hybrid standards to watch NTSC video tapes on PAL TVs -and vice versa. Applications can use the predefined bits to select a -particular standard, although presenting the user a menu of supported -standards is preferred. To enumerate and query the attributes of the -supported standards applications use the &VIDIOC-ENUMSTD; ioctl.</para> - - <para>Many of the defined standards are actually just variations -of a few major standards. The hardware may in fact not distinguish -between them, or do so internal and switch automatically. Therefore -enumerated standards also contain sets of one or more standard -bits.</para> - - <para>Assume a hypothetic tuner capable of demodulating B/PAL, -G/PAL and I/PAL signals. The first enumerated standard is a set of B -and G/PAL, switched automatically depending on the selected radio -frequency in UHF or VHF band. Enumeration gives a "PAL-B/G" or "PAL-I" -choice. Similar a Composite input may collapse standards, enumerating -"PAL-B/G/H/I", "NTSC-M" and "SECAM-D/K".<footnote> - <para>Some users are already confused by technical terms PAL, -NTSC and SECAM. There is no point asking them to distinguish between -B, G, D, or K when the software or hardware can do that -automatically.</para> - </footnote></para> - - <para>To query and select the standard used by the current video -input or output applications call the &VIDIOC-G-STD; and -&VIDIOC-S-STD; ioctl, respectively. The <emphasis>received</emphasis> -standard can be sensed with the &VIDIOC-QUERYSTD; ioctl. Note that the -parameter of all these ioctls is a pointer to a &v4l2-std-id; type -(a standard set), <emphasis>not</emphasis> an index into the standard -enumeration. Drivers must implement all video standard ioctls -when the device has one or more video inputs or outputs.</para> - - <para>Special rules apply to devices such as USB cameras where the notion of video -standards makes little sense. More generally for any capture or output device -which is: <itemizedlist> - <listitem> - <para>incapable of capturing fields or frames at the nominal -rate of the video standard, or</para> - </listitem> - <listitem> - <para>that does not support the video standard formats at all.</para> - </listitem> - </itemizedlist> Here the driver shall set the -<structfield>std</structfield> field of &v4l2-input; and &v4l2-output; -to zero and the <constant>VIDIOC_G_STD</constant>, -<constant>VIDIOC_S_STD</constant>, -<constant>VIDIOC_QUERYSTD</constant> and -<constant>VIDIOC_ENUMSTD</constant> ioctls shall return the -&ENOTTY; or the &EINVAL;.</para> - <para>Applications can make use of the <xref linkend="input-capabilities" /> and -<xref linkend="output-capabilities"/> flags to determine whether the video standard ioctls -can be used with the given input or output.</para> - - <example> - <title>Information about the current video standard</title> - - <programlisting> -&v4l2-std-id; std_id; -&v4l2-standard; standard; - -if (-1 == ioctl(fd, &VIDIOC-G-STD;, &std_id)) { - /* Note when VIDIOC_ENUMSTD always returns ENOTTY this - is no video device or it falls under the USB exception, - and VIDIOC_G_STD returning ENOTTY is no error. */ - - perror("VIDIOC_G_STD"); - exit(EXIT_FAILURE); -} - -memset(&standard, 0, sizeof(standard)); -standard.index = 0; - -while (0 == ioctl(fd, &VIDIOC-ENUMSTD;, &standard)) { - if (standard.id & std_id) { - printf("Current video standard: %s\n", standard.name); - exit(EXIT_SUCCESS); - } - - standard.index++; -} - -/* EINVAL indicates the end of the enumeration, which cannot be - empty unless this device falls under the USB exception. */ - -if (errno == EINVAL || standard.index == 0) { - perror("VIDIOC_ENUMSTD"); - exit(EXIT_FAILURE); -} - </programlisting> - </example> - - <example> - <title>Listing the video standards supported by the current -input</title> - - <programlisting> -&v4l2-input; input; -&v4l2-standard; standard; - -memset(&input, 0, sizeof(input)); - -if (-1 == ioctl(fd, &VIDIOC-G-INPUT;, &input.index)) { - perror("VIDIOC_G_INPUT"); - exit(EXIT_FAILURE); -} - -if (-1 == ioctl(fd, &VIDIOC-ENUMINPUT;, &input)) { - perror("VIDIOC_ENUM_INPUT"); - exit(EXIT_FAILURE); -} - -printf("Current input %s supports:\n", input.name); - -memset(&standard, 0, sizeof(standard)); -standard.index = 0; - -while (0 == ioctl(fd, &VIDIOC-ENUMSTD;, &standard)) { - if (standard.id & input.std) - printf("%s\n", standard.name); - - standard.index++; -} - -/* EINVAL indicates the end of the enumeration, which cannot be - empty unless this device falls under the USB exception. */ - -if (errno != EINVAL || standard.index == 0) { - perror("VIDIOC_ENUMSTD"); - exit(EXIT_FAILURE); -} - </programlisting> - </example> - - <example> - <title>Selecting a new video standard</title> - - <programlisting> -&v4l2-input; input; -&v4l2-std-id; std_id; - -memset(&input, 0, sizeof(input)); - -if (-1 == ioctl(fd, &VIDIOC-G-INPUT;, &input.index)) { - perror("VIDIOC_G_INPUT"); - exit(EXIT_FAILURE); -} - -if (-1 == ioctl(fd, &VIDIOC-ENUMINPUT;, &input)) { - perror("VIDIOC_ENUM_INPUT"); - exit(EXIT_FAILURE); -} - -if (0 == (input.std & V4L2_STD_PAL_BG)) { - fprintf(stderr, "Oops. B/G PAL is not supported.\n"); - exit(EXIT_FAILURE); -} - -/* Note this is also supposed to work when only B - <emphasis>or</emphasis> G/PAL is supported. */ - -std_id = V4L2_STD_PAL_BG; - -if (-1 == ioctl(fd, &VIDIOC-S-STD;, &std_id)) { - perror("VIDIOC_S_STD"); - exit(EXIT_FAILURE); -} - </programlisting> - </example> - </section> - <section id="dv-timings"> - <title>Digital Video (DV) Timings</title> - <para> - The video standards discussed so far have been dealing with Analog TV and the -corresponding video timings. Today there are many more different hardware interfaces -such as High Definition TV interfaces (HDMI), VGA, DVI connectors etc., that carry -video signals and there is a need to extend the API to select the video timings -for these interfaces. Since it is not possible to extend the &v4l2-std-id; due to -the limited bits available, a new set of ioctls was added to set/get video timings at -the input and output.</para> - - <para>These ioctls deal with the detailed digital video timings that define -each video format. This includes parameters such as the active video width and height, -signal polarities, frontporches, backporches, sync widths etc. The <filename>linux/v4l2-dv-timings.h</filename> -header can be used to get the timings of the formats in the <xref linkend="cea861" /> and -<xref linkend="vesadmt" /> standards. - </para> - - <para>To enumerate and query the attributes of the DV timings supported by a device - applications use the &VIDIOC-ENUM-DV-TIMINGS; and &VIDIOC-DV-TIMINGS-CAP; ioctls. - To set DV timings for the device applications use the -&VIDIOC-S-DV-TIMINGS; ioctl and to get current DV timings they use the -&VIDIOC-G-DV-TIMINGS; ioctl. To detect the DV timings as seen by the video receiver applications -use the &VIDIOC-QUERY-DV-TIMINGS; ioctl.</para> - <para>Applications can make use of the <xref linkend="input-capabilities" /> and -<xref linkend="output-capabilities"/> flags to determine whether the digital video ioctls -can be used with the given input or output.</para> - </section> - - &sub-controls; - - <section id="format"> - <title>Data Formats</title> - - <section> - <title>Data Format Negotiation</title> - - <para>Different devices exchange different kinds of data with -applications, for example video images, raw or sliced VBI data, RDS -datagrams. Even within one kind many different formats are possible, -in particular an abundance of image formats. Although drivers must -provide a default and the selection persists across closing and -reopening a device, applications should always negotiate a data format -before engaging in data exchange. Negotiation means the application -asks for a particular format and the driver selects and reports the -best the hardware can do to satisfy the request. Of course -applications can also just query the current selection.</para> - - <para>A single mechanism exists to negotiate all data formats -using the aggregate &v4l2-format; and the &VIDIOC-G-FMT; and -&VIDIOC-S-FMT; ioctls. Additionally the &VIDIOC-TRY-FMT; ioctl can be -used to examine what the hardware <emphasis>could</emphasis> do, -without actually selecting a new data format. The data formats -supported by the V4L2 API are covered in the respective device section -in <xref linkend="devices" />. For a closer look at image formats see -<xref linkend="pixfmt" />.</para> - - <para>The <constant>VIDIOC_S_FMT</constant> ioctl is a major -turning-point in the initialization sequence. Prior to this point -multiple panel applications can access the same device concurrently to -select the current input, change controls or modify other properties. -The first <constant>VIDIOC_S_FMT</constant> assigns a logical stream -(video data, VBI data etc.) exclusively to one file descriptor.</para> - - <para>Exclusive means no other application, more precisely no -other file descriptor, can grab this stream or change device -properties inconsistent with the negotiated parameters. A video -standard change for example, when the new standard uses a different -number of scan lines, can invalidate the selected image format. -Therefore only the file descriptor owning the stream can make -invalidating changes. Accordingly multiple file descriptors which -grabbed different logical streams prevent each other from interfering -with their settings. When for example video overlay is about to start -or already in progress, simultaneous video capturing may be restricted -to the same cropping and image size.</para> - - <para>When applications omit the -<constant>VIDIOC_S_FMT</constant> ioctl its locking side effects are -implied by the next step, the selection of an I/O method with the -&VIDIOC-REQBUFS; ioctl or implicit with the first &func-read; or -&func-write; call.</para> - - <para>Generally only one logical stream can be assigned to a -file descriptor, the exception being drivers permitting simultaneous -video capturing and overlay using the same file descriptor for -compatibility with V4L and earlier versions of V4L2. Switching the -logical stream or returning into "panel mode" is possible by closing -and reopening the device. Drivers <emphasis>may</emphasis> support a -switch using <constant>VIDIOC_S_FMT</constant>.</para> - - <para>All drivers exchanging data with -applications must support the <constant>VIDIOC_G_FMT</constant> and -<constant>VIDIOC_S_FMT</constant> ioctl. Implementation of the -<constant>VIDIOC_TRY_FMT</constant> is highly recommended but -optional.</para> - </section> - - <section> - <title>Image Format Enumeration</title> - - <para>Apart of the generic format negotiation functions -a special ioctl to enumerate all image formats supported by video -capture, overlay or output devices is available.<footnote> - <para>Enumerating formats an application has no a-priori -knowledge of (otherwise it could explicitly ask for them and need not -enumerate) seems useless, but there are applications serving as proxy -between drivers and the actual video applications for which this is -useful.</para> - </footnote></para> - - <para>The &VIDIOC-ENUM-FMT; ioctl must be supported -by all drivers exchanging image data with applications.</para> - - <important> - <para>Drivers are not supposed to convert image formats in -kernel space. They must enumerate only formats directly supported by -the hardware. If necessary driver writers should publish an example -conversion routine or library for integration into applications.</para> - </important> - </section> - </section> - - &sub-planar-apis; - - <section id="crop"> - <title>Image Cropping, Insertion and Scaling</title> - - <para>Some video capture devices can sample a subsection of the -picture and shrink or enlarge it to an image of arbitrary size. We -call these abilities cropping and scaling. Some video output devices -can scale an image up or down and insert it at an arbitrary scan line -and horizontal offset into a video signal.</para> - - <para>Applications can use the following API to select an area in -the video signal, query the default area and the hardware limits. -<emphasis>Despite their name, the &VIDIOC-CROPCAP;, &VIDIOC-G-CROP; -and &VIDIOC-S-CROP; ioctls apply to input as well as output -devices.</emphasis></para> - - <para>Scaling requires a source and a target. On a video capture -or overlay device the source is the video signal, and the cropping -ioctls determine the area actually sampled. The target are images -read by the application or overlaid onto the graphics screen. Their -size (and position for an overlay) is negotiated with the -&VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls.</para> - - <para>On a video output device the source are the images passed in -by the application, and their size is again negotiated with the -<constant>VIDIOC_G/S_FMT</constant> ioctls, or may be encoded in a -compressed video stream. The target is the video signal, and the -cropping ioctls determine the area where the images are -inserted.</para> - - <para>Source and target rectangles are defined even if the device -does not support scaling or the <constant>VIDIOC_G/S_CROP</constant> -ioctls. Their size (and position where applicable) will be fixed in -this case. <emphasis>All capture and output device must support the -<constant>VIDIOC_CROPCAP</constant> ioctl such that applications can -determine if scaling takes place.</emphasis></para> - - <section> - <title>Cropping Structures</title> - - <figure id="crop-scale"> - <title>Image Cropping, Insertion and Scaling</title> - <mediaobject> - <imageobject> - <imagedata fileref="crop.pdf" format="PS" /> - </imageobject> - <imageobject> - <imagedata fileref="crop.gif" format="GIF" /> - </imageobject> - <textobject> - <phrase>The cropping, insertion and scaling process</phrase> - </textobject> - </mediaobject> - </figure> - - <para>For capture devices the coordinates of the top left -corner, width and height of the area which can be sampled is given by -the <structfield>bounds</structfield> substructure of the -&v4l2-cropcap; returned by the <constant>VIDIOC_CROPCAP</constant> -ioctl. To support a wide range of hardware this specification does not -define an origin or units. However by convention drivers should -horizontally count unscaled samples relative to 0H (the leading edge -of the horizontal sync pulse, see <xref linkend="vbi-hsync" />). -Vertically ITU-R line -numbers of the first field (<xref linkend="vbi-525" />, <xref -linkend="vbi-625" />), multiplied by two if the driver can capture both -fields.</para> - - <para>The top left corner, width and height of the source -rectangle, that is the area actually sampled, is given by &v4l2-crop; -using the same coordinate system as &v4l2-cropcap;. Applications can -use the <constant>VIDIOC_G_CROP</constant> and -<constant>VIDIOC_S_CROP</constant> ioctls to get and set this -rectangle. It must lie completely within the capture boundaries and -the driver may further adjust the requested size and/or position -according to hardware limitations.</para> - - <para>Each capture device has a default source rectangle, given -by the <structfield>defrect</structfield> substructure of -&v4l2-cropcap;. The center of this rectangle shall align with the -center of the active picture area of the video signal, and cover what -the driver writer considers the complete picture. Drivers shall reset -the source rectangle to the default when the driver is first loaded, -but not later.</para> - - <para>For output devices these structures and ioctls are used -accordingly, defining the <emphasis>target</emphasis> rectangle where -the images will be inserted into the video signal.</para> - - </section> - - <section> - <title>Scaling Adjustments</title> - - <para>Video hardware can have various cropping, insertion and -scaling limitations. It may only scale up or down, support only -discrete scaling factors, or have different scaling abilities in -horizontal and vertical direction. Also it may not support scaling at -all. At the same time the &v4l2-crop; rectangle may have to be -aligned, and both the source and target rectangles may have arbitrary -upper and lower size limits. In particular the maximum -<structfield>width</structfield> and <structfield>height</structfield> -in &v4l2-crop; may be smaller than the -&v4l2-cropcap;.<structfield>bounds</structfield> area. Therefore, as -usual, drivers are expected to adjust the requested parameters and -return the actual values selected.</para> - - <para>Applications can change the source or the target rectangle -first, as they may prefer a particular image size or a certain area in -the video signal. If the driver has to adjust both to satisfy hardware -limitations, the last requested rectangle shall take priority, and the -driver should preferably adjust the opposite one. The &VIDIOC-TRY-FMT; -ioctl however shall not change the driver state and therefore only -adjust the requested rectangle.</para> - - <para>Suppose scaling on a video capture device is restricted to -a factor 1:1 or 2:1 in either direction and the target image size must -be a multiple of 16 × 16 pixels. The source cropping -rectangle is set to defaults, which are also the upper limit in this -example, of 640 × 400 pixels at offset 0, 0. An -application requests an image size of 300 × 225 -pixels, assuming video will be scaled down from the "full picture" -accordingly. The driver sets the image size to the closest possible -values 304 × 224, then chooses the cropping rectangle -closest to the requested size, that is 608 × 224 -(224 × 2:1 would exceed the limit 400). The offset -0, 0 is still valid, thus unmodified. Given the default cropping -rectangle reported by <constant>VIDIOC_CROPCAP</constant> the -application can easily propose another offset to center the cropping -rectangle.</para> - - <para>Now the application may insist on covering an area using a -picture aspect ratio closer to the original request, so it asks for a -cropping rectangle of 608 × 456 pixels. The present -scaling factors limit cropping to 640 × 384, so the -driver returns the cropping size 608 × 384 and adjusts -the image size to closest possible 304 × 192.</para> - - </section> - - <section> - <title>Examples</title> - - <para>Source and target rectangles shall remain unchanged across -closing and reopening a device, such that piping data into or out of a -device will work without special preparations. More advanced -applications should ensure the parameters are suitable before starting -I/O.</para> - - <example> - <title>Resetting the cropping parameters</title> - - <para>(A video capture device is assumed; change -<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> for other -devices.)</para> - - <programlisting> -&v4l2-cropcap; cropcap; -&v4l2-crop; crop; - -memset (&cropcap, 0, sizeof (cropcap)); -cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - -if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &cropcap)) { - perror ("VIDIOC_CROPCAP"); - exit (EXIT_FAILURE); -} - -memset (&crop, 0, sizeof (crop)); -crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; -crop.c = cropcap.defrect; - -/* Ignore if cropping is not supported (EINVAL). */ - -if (-1 == ioctl (fd, &VIDIOC-S-CROP;, &crop) - && errno != EINVAL) { - perror ("VIDIOC_S_CROP"); - exit (EXIT_FAILURE); -} - </programlisting> - </example> - - <example> - <title>Simple downscaling</title> - - <para>(A video capture device is assumed.)</para> - - <programlisting> -&v4l2-cropcap; cropcap; -&v4l2-format; format; - -reset_cropping_parameters (); - -/* Scale down to 1/4 size of full picture. */ - -memset (&format, 0, sizeof (format)); /* defaults */ - -format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - -format.fmt.pix.width = cropcap.defrect.width >> 1; -format.fmt.pix.height = cropcap.defrect.height >> 1; -format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV; - -if (-1 == ioctl (fd, &VIDIOC-S-FMT;, &format)) { - perror ("VIDIOC_S_FORMAT"); - exit (EXIT_FAILURE); -} - -/* We could check the actual image size now, the actual scaling factor - or if the driver can scale at all. */ - </programlisting> - </example> - - <example> - <title>Selecting an output area</title> - - <programlisting> -&v4l2-cropcap; cropcap; -&v4l2-crop; crop; - -memset (&cropcap, 0, sizeof (cropcap)); -cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; - -if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &cropcap)) { - perror ("VIDIOC_CROPCAP"); - exit (EXIT_FAILURE); -} - -memset (&crop, 0, sizeof (crop)); - -crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; -crop.c = cropcap.defrect; - -/* Scale the width and height to 50 % of their original size - and center the output. */ - -crop.c.width /= 2; -crop.c.height /= 2; -crop.c.left += crop.c.width / 2; -crop.c.top += crop.c.height / 2; - -/* Ignore if cropping is not supported (EINVAL). */ - -if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop) - && errno != EINVAL) { - perror ("VIDIOC_S_CROP"); - exit (EXIT_FAILURE); -} -</programlisting> - </example> - - <example> - <title>Current scaling factor and pixel aspect</title> - - <para>(A video capture device is assumed.)</para> - - <programlisting> -&v4l2-cropcap; cropcap; -&v4l2-crop; crop; -&v4l2-format; format; -double hscale, vscale; -double aspect; -int dwidth, dheight; - -memset (&cropcap, 0, sizeof (cropcap)); -cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - -if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &cropcap)) { - perror ("VIDIOC_CROPCAP"); - exit (EXIT_FAILURE); -} - -memset (&crop, 0, sizeof (crop)); -crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - -if (-1 == ioctl (fd, &VIDIOC-G-CROP;, &crop)) { - if (errno != EINVAL) { - perror ("VIDIOC_G_CROP"); - exit (EXIT_FAILURE); - } - - /* Cropping not supported. */ - crop.c = cropcap.defrect; -} - -memset (&format, 0, sizeof (format)); -format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - -if (-1 == ioctl (fd, &VIDIOC-G-FMT;, &format)) { - perror ("VIDIOC_G_FMT"); - exit (EXIT_FAILURE); -} - -/* The scaling applied by the driver. */ - -hscale = format.fmt.pix.width / (double) crop.c.width; -vscale = format.fmt.pix.height / (double) crop.c.height; - -aspect = cropcap.pixelaspect.numerator / - (double) cropcap.pixelaspect.denominator; -aspect = aspect * hscale / vscale; - -/* Devices following ITU-R BT.601 do not capture - square pixels. For playback on a computer monitor - we should scale the images to this size. */ - -dwidth = format.fmt.pix.width / aspect; -dheight = format.fmt.pix.height; - </programlisting> - </example> - </section> - </section> - - &sub-selection-api; - - <section id="streaming-par"> - <title>Streaming Parameters</title> - - <para>Streaming parameters are intended to optimize the video -capture process as well as I/O. Presently applications can request a -high quality capture mode with the &VIDIOC-S-PARM; ioctl.</para> - - <para>The current video standard determines a nominal number of -frames per second. If less than this number of frames is to be -captured or output, applications can request frame skipping or -duplicating on the driver side. This is especially useful when using -the &func-read; or &func-write;, which are not augmented by timestamps -or sequence counters, and to avoid unnecessary data copying.</para> - - <para>Finally these ioctls can be used to determine the number of -buffers used internally by a driver in read/write mode. For -implications see the section discussing the &func-read; -function.</para> - - <para>To get and set the streaming parameters applications call -the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; ioctl, respectively. They take -a pointer to a &v4l2-streamparm;, which contains a union holding -separate parameters for input and output devices.</para> - - <para>These ioctls are optional, drivers need not implement -them. If so, they return the &EINVAL;.</para> - </section> diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml deleted file mode 100644 index 5399e8904715..000000000000 --- a/Documentation/DocBook/media/v4l/compat.xml +++ /dev/null @@ -1,2761 +0,0 @@ - <title>Changes</title> - - <para>The following chapters document the evolution of the V4L2 API, -errata or extensions. They are also intended to help application and -driver writers to port or update their code.</para> - - <section id="diff-v4l"> - <title>Differences between V4L and V4L2</title> - - <para>The Video For Linux API was first introduced in Linux 2.1 to -unify and replace various TV and radio device related interfaces, -developed independently by driver writers in prior years. Starting -with Linux 2.5 the much improved V4L2 API replaces the V4L API. -The support for the old V4L calls were removed from Kernel, but the -library <xref linkend="libv4l" /> supports the conversion of a V4L -API system call into a V4L2 one.</para> - - <section> - <title>Opening and Closing Devices</title> - - <para>For compatibility reasons the character device file names -recommended for V4L2 video capture, overlay, radio and raw -vbi capture devices did not change from those used by V4L. They are -listed in <xref linkend="devices" /> and below in <xref - linkend="v4l-dev" />.</para> - - <para>The teletext devices (minor range 192-223) have been removed in -V4L2 and no longer exist. There is no hardware available anymore for handling -pure teletext. Instead raw or sliced VBI is used.</para> - - <para>The V4L <filename>videodev</filename> module automatically -assigns minor numbers to drivers in load order, depending on the -registered device type. We recommend that V4L2 drivers by default -register devices with the same numbers, but the system administrator -can assign arbitrary minor numbers using driver module options. The -major device number remains 81.</para> - - <table id="v4l-dev"> - <title>V4L Device Types, Names and Numbers</title> - <tgroup cols="3"> - <thead> - <row> - <entry>Device Type</entry> - <entry>File Name</entry> - <entry>Minor Numbers</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry>Video capture and overlay</entry> - <entry><para><filename>/dev/video</filename> and -<filename>/dev/bttv0</filename><footnote> <para>According to -Documentation/devices.txt these should be symbolic links to -<filename>/dev/video0</filename>. Note the original bttv interface is -not compatible with V4L or V4L2.</para> </footnote>, -<filename>/dev/video0</filename> to -<filename>/dev/video63</filename></para></entry> - <entry>0-63</entry> - </row> - <row> - <entry>Radio receiver</entry> - <entry><para><filename>/dev/radio</filename><footnote> - <para>According to -<filename>Documentation/devices.txt</filename> a symbolic link to -<filename>/dev/radio0</filename>.</para> - </footnote>, <filename>/dev/radio0</filename> to -<filename>/dev/radio63</filename></para></entry> - <entry>64-127</entry> - </row> - <row> - <entry>Raw VBI capture</entry> - <entry><para><filename>/dev/vbi</filename>, -<filename>/dev/vbi0</filename> to -<filename>/dev/vbi31</filename></para></entry> - <entry>224-255</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>V4L prohibits (or used to prohibit) multiple opens of a -device file. V4L2 drivers <emphasis>may</emphasis> support multiple -opens, see <xref linkend="open" /> for details and consequences.</para> - - <para>V4L drivers respond to V4L2 ioctls with an &EINVAL;.</para> - </section> - - <section> - <title>Querying Capabilities</title> - - <para>The V4L <constant>VIDIOCGCAP</constant> ioctl is -equivalent to V4L2's &VIDIOC-QUERYCAP;.</para> - - <para>The <structfield>name</structfield> field in struct -<structname>video_capability</structname> became -<structfield>card</structfield> in &v4l2-capability;, -<structfield>type</structfield> was replaced by -<structfield>capabilities</structfield>. Note V4L2 does not -distinguish between device types like this, better think of basic -video input, video output and radio devices supporting a set of -related functions like video capturing, video overlay and VBI -capturing. See <xref linkend="open" /> for an -introduction.<informaltable> - <tgroup cols="3"> - <thead> - <row> - <entry>struct -<structname>video_capability</structname> -<structfield>type</structfield></entry> - <entry>&v4l2-capability; -<structfield>capabilities</structfield> flags</entry> - <entry>Purpose</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry><constant>VID_TYPE_CAPTURE</constant></entry> - <entry><constant>V4L2_CAP_VIDEO_CAPTURE</constant></entry> - <entry>The <link linkend="capture">video -capture</link> interface is supported.</entry> - </row> - <row> - <entry><constant>VID_TYPE_TUNER</constant></entry> - <entry><constant>V4L2_CAP_TUNER</constant></entry> - <entry>The device has a <link linkend="tuner">tuner or -modulator</link>.</entry> - </row> - <row> - <entry><constant>VID_TYPE_TELETEXT</constant></entry> - <entry><constant>V4L2_CAP_VBI_CAPTURE</constant></entry> - <entry>The <link linkend="raw-vbi">raw VBI -capture</link> interface is supported.</entry> - </row> - <row> - <entry><constant>VID_TYPE_OVERLAY</constant></entry> - <entry><constant>V4L2_CAP_VIDEO_OVERLAY</constant></entry> - <entry>The <link linkend="overlay">video -overlay</link> interface is supported.</entry> - </row> - <row> - <entry><constant>VID_TYPE_CHROMAKEY</constant></entry> - <entry><constant>V4L2_FBUF_CAP_CHROMAKEY</constant> in -field <structfield>capability</structfield> of -&v4l2-framebuffer;</entry> - <entry>Whether chromakey overlay is supported. For -more information on overlay see -<xref linkend="overlay" />.</entry> - </row> - <row> - <entry><constant>VID_TYPE_CLIPPING</constant></entry> - <entry><constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant> -and <constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant> in field -<structfield>capability</structfield> of &v4l2-framebuffer;</entry> - <entry>Whether clipping the overlaid image is -supported, see <xref linkend="overlay" />.</entry> - </row> - <row> - <entry><constant>VID_TYPE_FRAMERAM</constant></entry> - <entry><constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant> -<emphasis>not set</emphasis> in field -<structfield>capability</structfield> of &v4l2-framebuffer;</entry> - <entry>Whether overlay overwrites frame buffer memory, -see <xref linkend="overlay" />.</entry> - </row> - <row> - <entry><constant>VID_TYPE_SCALES</constant></entry> - <entry><constant>-</constant></entry> - <entry>This flag indicates if the hardware can scale -images. The V4L2 API implies the scale factor by setting the cropping -dimensions and image size with the &VIDIOC-S-CROP; and &VIDIOC-S-FMT; -ioctl, respectively. The driver returns the closest sizes possible. -For more information on cropping and scaling see <xref - linkend="crop" />.</entry> - </row> - <row> - <entry><constant>VID_TYPE_MONOCHROME</constant></entry> - <entry><constant>-</constant></entry> - <entry>Applications can enumerate the supported image -formats with the &VIDIOC-ENUM-FMT; ioctl to determine if the device -supports grey scale capturing only. For more information on image -formats see <xref linkend="pixfmt" />.</entry> - </row> - <row> - <entry><constant>VID_TYPE_SUBCAPTURE</constant></entry> - <entry><constant>-</constant></entry> - <entry>Applications can call the &VIDIOC-G-CROP; ioctl -to determine if the device supports capturing a subsection of the full -picture ("cropping" in V4L2). If not, the ioctl returns the &EINVAL;. -For more information on cropping and scaling see <xref - linkend="crop" />.</entry> - </row> - <row> - <entry><constant>VID_TYPE_MPEG_DECODER</constant></entry> - <entry><constant>-</constant></entry> - <entry>Applications can enumerate the supported image -formats with the &VIDIOC-ENUM-FMT; ioctl to determine if the device -supports MPEG streams.</entry> - </row> - <row> - <entry><constant>VID_TYPE_MPEG_ENCODER</constant></entry> - <entry><constant>-</constant></entry> - <entry>See above.</entry> - </row> - <row> - <entry><constant>VID_TYPE_MJPEG_DECODER</constant></entry> - <entry><constant>-</constant></entry> - <entry>See above.</entry> - </row> - <row> - <entry><constant>VID_TYPE_MJPEG_ENCODER</constant></entry> - <entry><constant>-</constant></entry> - <entry>See above.</entry> - </row> - </tbody> - </tgroup> - </informaltable></para> - - <para>The <structfield>audios</structfield> field was replaced -by <structfield>capabilities</structfield> flag -<constant>V4L2_CAP_AUDIO</constant>, indicating -<emphasis>if</emphasis> the device has any audio inputs or outputs. To -determine their number applications can enumerate audio inputs with -the &VIDIOC-G-AUDIO; ioctl. The audio ioctls are described in <xref - linkend="audio" />.</para> - - <para>The <structfield>maxwidth</structfield>, -<structfield>maxheight</structfield>, -<structfield>minwidth</structfield> and -<structfield>minheight</structfield> fields were removed. Calling the -&VIDIOC-S-FMT; or &VIDIOC-TRY-FMT; ioctl with the desired dimensions -returns the closest size possible, taking into account the current -video standard, cropping and scaling limitations.</para> - </section> - - <section> - <title>Video Sources</title> - - <para>V4L provides the <constant>VIDIOCGCHAN</constant> and -<constant>VIDIOCSCHAN</constant> ioctl using struct -<structname>video_channel</structname> to enumerate -the video inputs of a V4L device. The equivalent V4L2 ioctls -are &VIDIOC-ENUMINPUT;, &VIDIOC-G-INPUT; and &VIDIOC-S-INPUT; -using &v4l2-input; as discussed in <xref linkend="video" />.</para> - - <para>The <structfield>channel</structfield> field counting -inputs was renamed to <structfield>index</structfield>, the video -input types were renamed as follows: <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>struct <structname>video_channel</structname> -<structfield>type</structfield></entry> - <entry>&v4l2-input; -<structfield>type</structfield></entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry><constant>VIDEO_TYPE_TV</constant></entry> - <entry><constant>V4L2_INPUT_TYPE_TUNER</constant></entry> - </row> - <row> - <entry><constant>VIDEO_TYPE_CAMERA</constant></entry> - <entry><constant>V4L2_INPUT_TYPE_CAMERA</constant></entry> - </row> - </tbody> - </tgroup> - </informaltable></para> - - <para>Unlike the <structfield>tuners</structfield> field -expressing the number of tuners of this input, V4L2 assumes each video -input is connected to at most one tuner. However a tuner can have more -than one input, &ie; RF connectors, and a device can have multiple -tuners. The index number of the tuner associated with the input, if -any, is stored in field <structfield>tuner</structfield> of -&v4l2-input;. Enumeration of tuners is discussed in <xref - linkend="tuner" />.</para> - - <para>The redundant <constant>VIDEO_VC_TUNER</constant> flag was -dropped. Video inputs associated with a tuner are of type -<constant>V4L2_INPUT_TYPE_TUNER</constant>. The -<constant>VIDEO_VC_AUDIO</constant> flag was replaced by the -<structfield>audioset</structfield> field. V4L2 considers devices with -up to 32 audio inputs. Each set bit in the -<structfield>audioset</structfield> field represents one audio input -this video input combines with. For information about audio inputs and -how to switch between them see <xref linkend="audio" />.</para> - - <para>The <structfield>norm</structfield> field describing the -supported video standards was replaced by -<structfield>std</structfield>. The V4L specification mentions a flag -<constant>VIDEO_VC_NORM</constant> indicating whether the standard can -be changed. This flag was a later addition together with the -<structfield>norm</structfield> field and has been removed in the -meantime. V4L2 has a similar, albeit more comprehensive approach -to video standards, see <xref linkend="standard" /> for more -information.</para> - </section> - - <section> - <title>Tuning</title> - - <para>The V4L <constant>VIDIOCGTUNER</constant> and -<constant>VIDIOCSTUNER</constant> ioctl and struct -<structname>video_tuner</structname> can be used to enumerate the -tuners of a V4L TV or radio device. The equivalent V4L2 ioctls are -&VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; using &v4l2-tuner;. Tuners are -covered in <xref linkend="tuner" />.</para> - - <para>The <structfield>tuner</structfield> field counting tuners -was renamed to <structfield>index</structfield>. The fields -<structfield>name</structfield>, <structfield>rangelow</structfield> -and <structfield>rangehigh</structfield> remained unchanged.</para> - - <para>The <constant>VIDEO_TUNER_PAL</constant>, -<constant>VIDEO_TUNER_NTSC</constant> and -<constant>VIDEO_TUNER_SECAM</constant> flags indicating the supported -video standards were dropped. This information is now contained in the -associated &v4l2-input;. No replacement exists for the -<constant>VIDEO_TUNER_NORM</constant> flag indicating whether the -video standard can be switched. The <structfield>mode</structfield> -field to select a different video standard was replaced by a whole new -set of ioctls and structures described in <xref linkend="standard" />. -Due to its ubiquity it should be mentioned the BTTV driver supports -several standards in addition to the regular -<constant>VIDEO_MODE_PAL</constant> (0), -<constant>VIDEO_MODE_NTSC</constant>, -<constant>VIDEO_MODE_SECAM</constant> and -<constant>VIDEO_MODE_AUTO</constant> (3). Namely N/PAL Argentina, -M/PAL, N/PAL, and NTSC Japan with numbers 3-6 (sic).</para> - - <para>The <constant>VIDEO_TUNER_STEREO_ON</constant> flag -indicating stereo reception became -<constant>V4L2_TUNER_SUB_STEREO</constant> in field -<structfield>rxsubchans</structfield>. This field also permits the -detection of monaural and bilingual audio, see the definition of -&v4l2-tuner; for details. Presently no replacement exists for the -<constant>VIDEO_TUNER_RDS_ON</constant> and -<constant>VIDEO_TUNER_MBS_ON</constant> flags.</para> - - <para> The <constant>VIDEO_TUNER_LOW</constant> flag was renamed -to <constant>V4L2_TUNER_CAP_LOW</constant> in the &v4l2-tuner; -<structfield>capability</structfield> field.</para> - - <para>The <constant>VIDIOCGFREQ</constant> and -<constant>VIDIOCSFREQ</constant> ioctl to change the tuner frequency -where renamed to &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY;. They -take a pointer to a &v4l2-frequency; instead of an unsigned long -integer.</para> - </section> - - <section id="v4l-image-properties"> - <title>Image Properties</title> - - <para>V4L2 has no equivalent of the -<constant>VIDIOCGPICT</constant> and <constant>VIDIOCSPICT</constant> -ioctl and struct <structname>video_picture</structname>. The following -fields where replaced by V4L2 controls accessible with the -&VIDIOC-QUERYCTRL;, &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls:<informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>struct <structname>video_picture</structname></entry> - <entry>V4L2 Control ID</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry><structfield>brightness</structfield></entry> - <entry><constant>V4L2_CID_BRIGHTNESS</constant></entry> - </row> - <row> - <entry><structfield>hue</structfield></entry> - <entry><constant>V4L2_CID_HUE</constant></entry> - </row> - <row> - <entry><structfield>colour</structfield></entry> - <entry><constant>V4L2_CID_SATURATION</constant></entry> - </row> - <row> - <entry><structfield>contrast</structfield></entry> - <entry><constant>V4L2_CID_CONTRAST</constant></entry> - </row> - <row> - <entry><structfield>whiteness</structfield></entry> - <entry><constant>V4L2_CID_WHITENESS</constant></entry> - </row> - </tbody> - </tgroup> - </informaltable></para> - - <para>The V4L picture controls are assumed to range from 0 to -65535 with no particular reset value. The V4L2 API permits arbitrary -limits and defaults which can be queried with the &VIDIOC-QUERYCTRL; -ioctl. For general information about controls see <xref -linkend="control" />.</para> - - <para>The <structfield>depth</structfield> (average number of -bits per pixel) of a video image is implied by the selected image -format. V4L2 does not explicitly provide such information assuming -applications recognizing the format are aware of the image depth and -others need not know. The <structfield>palette</structfield> field -moved into the &v4l2-pix-format;:<informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>struct <structname>video_picture</structname> -<structfield>palette</structfield></entry> - <entry>&v4l2-pix-format; -<structfield>pixfmt</structfield></entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry><constant>VIDEO_PALETTE_GREY</constant></entry> - <entry><para><link -linkend="V4L2-PIX-FMT-GREY"><constant>V4L2_PIX_FMT_GREY</constant></link></para></entry> - </row> - <row> - <entry><constant>VIDEO_PALETTE_HI240</constant></entry> - <entry><para><link -linkend="pixfmt-reserved"><constant>V4L2_PIX_FMT_HI240</constant></link><footnote> - <para>This is a custom format used by the BTTV -driver, not one of the V4L2 standard formats.</para> - </footnote></para></entry> - </row> - <row> - <entry><constant>VIDEO_PALETTE_RGB565</constant></entry> - <entry><para><link -linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_RGB565</constant></link></para></entry> - </row> - <row> - <entry><constant>VIDEO_PALETTE_RGB555</constant></entry> - <entry><para><link -linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_RGB555</constant></link></para></entry> - </row> - <row> - <entry><constant>VIDEO_PALETTE_RGB24</constant></entry> - <entry><para><link -linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_BGR24</constant></link></para></entry> - </row> - <row> - <entry><constant>VIDEO_PALETTE_RGB32</constant></entry> - <entry><para><link -linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_BGR32</constant></link><footnote> - <para>Presumably all V4L RGB formats are -little-endian, although some drivers might interpret them according to machine endianness. V4L2 defines little-endian, big-endian and red/blue -swapped variants. For details see <xref linkend="pixfmt-rgb" />.</para> - </footnote></para></entry> - </row> - <row> - <entry><constant>VIDEO_PALETTE_YUV422</constant></entry> - <entry><para><link -linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link></para></entry> - </row> - <row> - <entry><para><constant>VIDEO_PALETTE_YUYV</constant><footnote> - <para><constant>VIDEO_PALETTE_YUV422</constant> -and <constant>VIDEO_PALETTE_YUYV</constant> are the same formats. Some -V4L drivers respond to one, some to the other.</para> - </footnote></para></entry> - <entry><para><link -linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link></para></entry> - </row> - <row> - <entry><constant>VIDEO_PALETTE_UYVY</constant></entry> - <entry><para><link -linkend="V4L2-PIX-FMT-UYVY"><constant>V4L2_PIX_FMT_UYVY</constant></link></para></entry> - </row> - <row> - <entry><constant>VIDEO_PALETTE_YUV420</constant></entry> - <entry>None</entry> - </row> - <row> - <entry><constant>VIDEO_PALETTE_YUV411</constant></entry> - <entry><para><link -linkend="V4L2-PIX-FMT-Y41P"><constant>V4L2_PIX_FMT_Y41P</constant></link><footnote> - <para>Not to be confused with -<constant>V4L2_PIX_FMT_YUV411P</constant>, which is a planar -format.</para> </footnote></para></entry> - </row> - <row> - <entry><constant>VIDEO_PALETTE_RAW</constant></entry> - <entry><para>None<footnote> <para>V4L explains this -as: "RAW capture (BT848)"</para> </footnote></para></entry> - </row> - <row> - <entry><constant>VIDEO_PALETTE_YUV422P</constant></entry> - <entry><para><link -linkend="V4L2-PIX-FMT-YUV422P"><constant>V4L2_PIX_FMT_YUV422P</constant></link></para></entry> - </row> - <row> - <entry><constant>VIDEO_PALETTE_YUV411P</constant></entry> - <entry><para><link -linkend="V4L2-PIX-FMT-YUV411P"><constant>V4L2_PIX_FMT_YUV411P</constant></link><footnote> - <para>Not to be confused with -<constant>V4L2_PIX_FMT_Y41P</constant>, which is a packed -format.</para> </footnote></para></entry> - </row> - <row> - <entry><constant>VIDEO_PALETTE_YUV420P</constant></entry> - <entry><para><link -linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link></para></entry> - </row> - <row> - <entry><constant>VIDEO_PALETTE_YUV410P</constant></entry> - <entry><para><link -linkend="V4L2-PIX-FMT-YVU410"><constant>V4L2_PIX_FMT_YVU410</constant></link></para></entry> - </row> - </tbody> - </tgroup> - </informaltable></para> - - <para>V4L2 image formats are defined in <xref -linkend="pixfmt" />. The image format can be selected with the -&VIDIOC-S-FMT; ioctl.</para> - </section> - - <section> - <title>Audio</title> - - <para>The <constant>VIDIOCGAUDIO</constant> and -<constant>VIDIOCSAUDIO</constant> ioctl and struct -<structname>video_audio</structname> are used to enumerate the -audio inputs of a V4L device. The equivalent V4L2 ioctls are -&VIDIOC-G-AUDIO; and &VIDIOC-S-AUDIO; using &v4l2-audio; as -discussed in <xref linkend="audio" />.</para> - - <para>The <structfield>audio</structfield> "channel number" -field counting audio inputs was renamed to -<structfield>index</structfield>.</para> - - <para>On <constant>VIDIOCSAUDIO</constant> the -<structfield>mode</structfield> field selects <emphasis>one</emphasis> -of the <constant>VIDEO_SOUND_MONO</constant>, -<constant>VIDEO_SOUND_STEREO</constant>, -<constant>VIDEO_SOUND_LANG1</constant> or -<constant>VIDEO_SOUND_LANG2</constant> audio demodulation modes. When -the current audio standard is BTSC -<constant>VIDEO_SOUND_LANG2</constant> refers to SAP and -<constant>VIDEO_SOUND_LANG1</constant> is meaningless. Also -undocumented in the V4L specification, there is no way to query the -selected mode. On <constant>VIDIOCGAUDIO</constant> the driver returns -the <emphasis>actually received</emphasis> audio programmes in this -field. In the V4L2 API this information is stored in the &v4l2-tuner; -<structfield>rxsubchans</structfield> and -<structfield>audmode</structfield> fields, respectively. See <xref -linkend="tuner" /> for more information on tuners. Related to audio -modes &v4l2-audio; also reports if this is a mono or stereo -input, regardless if the source is a tuner.</para> - - <para>The following fields where replaced by V4L2 controls -accessible with the &VIDIOC-QUERYCTRL;, &VIDIOC-G-CTRL; and -&VIDIOC-S-CTRL; ioctls:<informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>struct -<structname>video_audio</structname></entry> - <entry>V4L2 Control ID</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry><structfield>volume</structfield></entry> - <entry><constant>V4L2_CID_AUDIO_VOLUME</constant></entry> - </row> - <row> - <entry><structfield>bass</structfield></entry> - <entry><constant>V4L2_CID_AUDIO_BASS</constant></entry> - </row> - <row> - <entry><structfield>treble</structfield></entry> - <entry><constant>V4L2_CID_AUDIO_TREBLE</constant></entry> - </row> - <row> - <entry><structfield>balance</structfield></entry> - <entry><constant>V4L2_CID_AUDIO_BALANCE</constant></entry> - </row> - </tbody> - </tgroup> - </informaltable></para> - - <para>To determine which of these controls are supported by a -driver V4L provides the <structfield>flags</structfield> -<constant>VIDEO_AUDIO_VOLUME</constant>, -<constant>VIDEO_AUDIO_BASS</constant>, -<constant>VIDEO_AUDIO_TREBLE</constant> and -<constant>VIDEO_AUDIO_BALANCE</constant>. In the V4L2 API the -&VIDIOC-QUERYCTRL; ioctl reports if the respective control is -supported. Accordingly the <constant>VIDEO_AUDIO_MUTABLE</constant> -and <constant>VIDEO_AUDIO_MUTE</constant> flags where replaced by the -boolean <constant>V4L2_CID_AUDIO_MUTE</constant> control.</para> - - <para>All V4L2 controls have a <structfield>step</structfield> -attribute replacing the struct <structname>video_audio</structname> -<structfield>step</structfield> field. The V4L audio controls are -assumed to range from 0 to 65535 with no particular reset value. The -V4L2 API permits arbitrary limits and defaults which can be queried -with the &VIDIOC-QUERYCTRL; ioctl. For general information about -controls see <xref linkend="control" />.</para> - </section> - - <section> - <title>Frame Buffer Overlay</title> - - <para>The V4L2 ioctls equivalent to -<constant>VIDIOCGFBUF</constant> and <constant>VIDIOCSFBUF</constant> -are &VIDIOC-G-FBUF; and &VIDIOC-S-FBUF;. The -<structfield>base</structfield> field of struct -<structname>video_buffer</structname> remained unchanged, except V4L2 -defines a flag to indicate non-destructive overlays instead of a -<constant>NULL</constant> pointer. All other fields moved into the -&v4l2-pix-format; <structfield>fmt</structfield> substructure of -&v4l2-framebuffer;. The <structfield>depth</structfield> field was -replaced by <structfield>pixelformat</structfield>. See <xref - linkend="pixfmt-rgb" /> for a list of RGB formats and their -respective color depths.</para> - - <para>Instead of the special ioctls -<constant>VIDIOCGWIN</constant> and <constant>VIDIOCSWIN</constant> -V4L2 uses the general-purpose data format negotiation ioctls -&VIDIOC-G-FMT; and &VIDIOC-S-FMT;. They take a pointer to a -&v4l2-format; as argument. Here the <structfield>win</structfield> -member of the <structfield>fmt</structfield> union is used, a -&v4l2-window;.</para> - - <para>The <structfield>x</structfield>, -<structfield>y</structfield>, <structfield>width</structfield> and -<structfield>height</structfield> fields of struct -<structname>video_window</structname> moved into &v4l2-rect; -substructure <structfield>w</structfield> of struct -<structname>v4l2_window</structname>. The -<structfield>chromakey</structfield>, -<structfield>clips</structfield>, and -<structfield>clipcount</structfield> fields remained unchanged. Struct -<structname>video_clip</structname> was renamed to &v4l2-clip;, also -containing a struct <structname>v4l2_rect</structname>, but the -semantics are still the same.</para> - - <para>The <constant>VIDEO_WINDOW_INTERLACE</constant> flag was -dropped. Instead applications must set the -<structfield>field</structfield> field to -<constant>V4L2_FIELD_ANY</constant> or -<constant>V4L2_FIELD_INTERLACED</constant>. The -<constant>VIDEO_WINDOW_CHROMAKEY</constant> flag moved into -&v4l2-framebuffer;, under the new name -<constant>V4L2_FBUF_FLAG_CHROMAKEY</constant>.</para> - - <para>In V4L, storing a bitmap pointer in -<structfield>clips</structfield> and setting -<structfield>clipcount</structfield> to -<constant>VIDEO_CLIP_BITMAP</constant> (-1) requests bitmap -clipping, using a fixed size bitmap of 1024 × 625 bits. Struct -<structname>v4l2_window</structname> has a separate -<structfield>bitmap</structfield> pointer field for this purpose and -the bitmap size is determined by <structfield>w.width</structfield> and -<structfield>w.height</structfield>.</para> - - <para>The <constant>VIDIOCCAPTURE</constant> ioctl to enable or -disable overlay was renamed to &VIDIOC-OVERLAY;.</para> - </section> - - <section> - <title>Cropping</title> - - <para>To capture only a subsection of the full picture V4L -defines the <constant>VIDIOCGCAPTURE</constant> and -<constant>VIDIOCSCAPTURE</constant> ioctls using struct -<structname>video_capture</structname>. The equivalent V4L2 ioctls are -&VIDIOC-G-CROP; and &VIDIOC-S-CROP; using &v4l2-crop;, and the related -&VIDIOC-CROPCAP; ioctl. This is a rather complex matter, see -<xref linkend="crop" /> for details.</para> - - <para>The <structfield>x</structfield>, -<structfield>y</structfield>, <structfield>width</structfield> and -<structfield>height</structfield> fields moved into &v4l2-rect; -substructure <structfield>c</structfield> of struct -<structname>v4l2_crop</structname>. The -<structfield>decimation</structfield> field was dropped. In the V4L2 -API the scaling factor is implied by the size of the cropping -rectangle and the size of the captured or overlaid image.</para> - - <para>The <constant>VIDEO_CAPTURE_ODD</constant> -and <constant>VIDEO_CAPTURE_EVEN</constant> flags to capture only the -odd or even field, respectively, were replaced by -<constant>V4L2_FIELD_TOP</constant> and -<constant>V4L2_FIELD_BOTTOM</constant> in the field named -<structfield>field</structfield> of &v4l2-pix-format; and -&v4l2-window;. These structures are used to select a capture or -overlay format with the &VIDIOC-S-FMT; ioctl.</para> - </section> - - <section> - <title>Reading Images, Memory Mapping</title> - - <section> - <title>Capturing using the read method</title> - - <para>There is no essential difference between reading images -from a V4L or V4L2 device using the &func-read; function, however V4L2 -drivers are not required to support this I/O method. Applications can -determine if the function is available with the &VIDIOC-QUERYCAP; -ioctl. All V4L2 devices exchanging data with applications must support -the &func-select; and &func-poll; functions.</para> - - <para>To select an image format and size, V4L provides the -<constant>VIDIOCSPICT</constant> and <constant>VIDIOCSWIN</constant> -ioctls. V4L2 uses the general-purpose data format negotiation ioctls -&VIDIOC-G-FMT; and &VIDIOC-S-FMT;. They take a pointer to a -&v4l2-format; as argument, here the &v4l2-pix-format; named -<structfield>pix</structfield> of its <structfield>fmt</structfield> -union is used.</para> - - <para>For more information about the V4L2 read interface see -<xref linkend="rw" />.</para> - </section> - <section> - <title>Capturing using memory mapping</title> - - <para>Applications can read from V4L devices by mapping -buffers in device memory, or more often just buffers allocated in -DMA-able system memory, into their address space. This avoids the data -copying overhead of the read method. V4L2 supports memory mapping as -well, with a few differences.</para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>V4L</entry> - <entry>V4L2</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry></entry> - <entry>The image format must be selected before -buffers are allocated, with the &VIDIOC-S-FMT; ioctl. When no format -is selected the driver may use the last, possibly by another -application requested format.</entry> - </row> - <row> - <entry><para>Applications cannot change the number of -buffers. The it is built into the driver, unless it has a module -option to change the number when the driver module is -loaded.</para></entry> - <entry><para>The &VIDIOC-REQBUFS; ioctl allocates the -desired number of buffers, this is a required step in the initialization -sequence.</para></entry> - </row> - <row> - <entry><para>Drivers map all buffers as one contiguous -range of memory. The <constant>VIDIOCGMBUF</constant> ioctl is -available to query the number of buffers, the offset of each buffer -from the start of the virtual file, and the overall amount of memory -used, which can be used as arguments for the &func-mmap; -function.</para></entry> - <entry><para>Buffers are individually mapped. The -offset and size of each buffer can be determined with the -&VIDIOC-QUERYBUF; ioctl.</para></entry> - </row> - <row> - <entry><para>The <constant>VIDIOCMCAPTURE</constant> -ioctl prepares a buffer for capturing. It also determines the image -format for this buffer. The ioctl returns immediately, eventually with -an &EAGAIN; if no video signal had been detected. When the driver -supports more than one buffer applications can call the ioctl multiple -times and thus have multiple outstanding capture -requests.</para><para>The <constant>VIDIOCSYNC</constant> ioctl -suspends execution until a particular buffer has been -filled.</para></entry> - <entry><para>Drivers maintain an incoming and outgoing -queue. &VIDIOC-QBUF; enqueues any empty buffer into the incoming -queue. Filled buffers are dequeued from the outgoing queue with the -&VIDIOC-DQBUF; ioctl. To wait until filled buffers become available this -function, &func-select; or &func-poll; can be used. The -&VIDIOC-STREAMON; ioctl must be called once after enqueuing one or -more buffers to start capturing. Its counterpart -&VIDIOC-STREAMOFF; stops capturing and dequeues all buffers from both -queues. Applications can query the signal status, if known, with the -&VIDIOC-ENUMINPUT; ioctl.</para></entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>For a more in-depth discussion of memory mapping and -examples, see <xref linkend="mmap" />.</para> - </section> - </section> - - <section> - <title>Reading Raw VBI Data</title> - - <para>Originally the V4L API did not specify a raw VBI capture -interface, only the device file <filename>/dev/vbi</filename> was -reserved for this purpose. The only driver supporting this interface -was the BTTV driver, de-facto defining the V4L VBI interface. Reading -from the device yields a raw VBI image with the following -parameters:<informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>&v4l2-vbi-format;</entry> - <entry>V4L, BTTV driver</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry>sampling_rate</entry> - <entry>28636363 Hz NTSC (or any other 525-line -standard); 35468950 Hz PAL and SECAM (625-line standards)</entry> - </row> - <row> - <entry>offset</entry> - <entry>?</entry> - </row> - <row> - <entry>samples_per_line</entry> - <entry>2048</entry> - </row> - <row> - <entry>sample_format</entry> - <entry>V4L2_PIX_FMT_GREY. The last four bytes (a -machine endianness integer) contain a frame counter.</entry> - </row> - <row> - <entry>start[]</entry> - <entry>10, 273 NTSC; 22, 335 PAL and SECAM</entry> - </row> - <row> - <entry>count[]</entry> - <entry><para>16, 16<footnote><para>Old driver -versions used different values, eventually the custom -<constant>BTTV_VBISIZE</constant> ioctl was added to query the -correct values.</para></footnote></para></entry> - </row> - <row> - <entry>flags</entry> - <entry>0</entry> - </row> - </tbody> - </tgroup> - </informaltable></para> - - <para>Undocumented in the V4L specification, in Linux 2.3 the -<constant>VIDIOCGVBIFMT</constant> and -<constant>VIDIOCSVBIFMT</constant> ioctls using struct -<structname>vbi_format</structname> were added to determine the VBI -image parameters. These ioctls are only partially compatible with the -V4L2 VBI interface specified in <xref linkend="raw-vbi" />.</para> - - <para>An <structfield>offset</structfield> field does not -exist, <structfield>sample_format</structfield> is supposed to be -<constant>VIDEO_PALETTE_RAW</constant>, equivalent to -<constant>V4L2_PIX_FMT_GREY</constant>. The remaining fields are -probably equivalent to &v4l2-vbi-format;.</para> - - <para>Apparently only the Zoran (ZR 36120) driver implements -these ioctls. The semantics differ from those specified for V4L2 in two -ways. The parameters are reset on &func-open; and -<constant>VIDIOCSVBIFMT</constant> always returns an &EINVAL; if the -parameters are invalid.</para> - </section> - - <section> - <title>Miscellaneous</title> - - <para>V4L2 has no equivalent of the -<constant>VIDIOCGUNIT</constant> ioctl. Applications can find the VBI -device associated with a video capture device (or vice versa) by -reopening the device and requesting VBI data. For details see -<xref linkend="open" />.</para> - - <para>No replacement exists for <constant>VIDIOCKEY</constant>, -and the V4L functions for microcode programming. A new interface for -MPEG compression and playback devices is documented in <xref - linkend="extended-controls" />.</para> - </section> - - </section> - - <section id="hist-v4l2"> - <title>Changes of the V4L2 API</title> - - <para>Soon after the V4L API was added to the kernel it was -criticised as too inflexible. In August 1998 Bill Dirks proposed a -number of improvements and began to work on documentation, example -drivers and applications. With the help of other volunteers this -eventually became the V4L2 API, not just an extension but a -replacement for the V4L API. However it took another four years and -two stable kernel releases until the new API was finally accepted for -inclusion into the kernel in its present form.</para> - - <section> - <title>Early Versions</title> - <para>1998-08-20: First version.</para> - - <para>1998-08-27: The &func-select; function was introduced.</para> - - <para>1998-09-10: New video standard interface.</para> - - <para>1998-09-18: The <constant>VIDIOC_NONCAP</constant> ioctl -was replaced by the otherwise meaningless <constant>O_TRUNC</constant> -&func-open; flag, and the aliases <constant>O_NONCAP</constant> and -<constant>O_NOIO</constant> were defined. Applications can set this -flag if they intend to access controls only, as opposed to capture -applications which need exclusive access. The -<constant>VIDEO_STD_XXX</constant> identifiers are now ordinals -instead of flags, and the <function>video_std_construct()</function> -helper function takes id and transmission arguments.</para> - - <para>1998-09-28: Revamped video standard. Made video controls -individually enumerable.</para> - - <para>1998-10-02: The <structfield>id</structfield> field was -removed from struct <structname>video_standard</structname> and the -color subcarrier fields were renamed. The &VIDIOC-QUERYSTD; ioctl was -renamed to &VIDIOC-ENUMSTD;, &VIDIOC-G-INPUT; to &VIDIOC-ENUMINPUT;. A -first draft of the Codec API was released.</para> - - <para>1998-11-08: Many minor changes. Most symbols have been -renamed. Some material changes to &v4l2-capability;.</para> - - <para>1998-11-12: The read/write directon of some ioctls was misdefined.</para> - - <para>1998-11-14: <constant>V4L2_PIX_FMT_RGB24</constant> -changed to <constant>V4L2_PIX_FMT_BGR24</constant>, and -<constant>V4L2_PIX_FMT_RGB32</constant> changed to -<constant>V4L2_PIX_FMT_BGR32</constant>. Audio controls are now -accessible with the &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls under -names starting with <constant>V4L2_CID_AUDIO</constant>. The -<constant>V4L2_MAJOR</constant> define was removed from -<filename>videodev.h</filename> since it was only used once in the -<filename>videodev</filename> kernel module. The -<constant>YUV422</constant> and <constant>YUV411</constant> planar -image formats were added.</para> - - <para>1998-11-28: A few ioctl symbols changed. Interfaces for codecs and -video output devices were added.</para> - - <para>1999-01-14: A raw VBI capture interface was added.</para> - - <para>1999-01-19: The <constant>VIDIOC_NEXTBUF</constant> ioctl - was removed.</para> - </section> - - <section> - <title>V4L2 Version 0.16 1999-01-31</title> - <para>1999-01-27: There is now one QBUF ioctl, VIDIOC_QWBUF and VIDIOC_QRBUF -are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added -digital zoom (cropping) controls.</para> - </section> - - <!-- Where's 0.17? mhs couldn't find that videodev.h, perhaps Bill - forgot to bump the version number or never released it. --> - - <section> - <title>V4L2 Version 0.18 1999-03-16</title> - <para>Added a v4l to V4L2 ioctl compatibility layer to -videodev.c. Driver writers, this changes how you implement your ioctl -handler. See the Driver Writer's Guide. Added some more control id -codes.</para> - </section> - - <section> - <title>V4L2 Version 0.19 1999-06-05</title> - <para>1999-03-18: Fill in the category and catname fields of -v4l2_queryctrl objects before passing them to the driver. Required a -minor change to the VIDIOC_QUERYCTRL handlers in the sample -drivers.</para> - <para>1999-03-31: Better compatibility for v4l memory capture -ioctls. Requires changes to drivers to fully support new compatibility -features, see Driver Writer's Guide and v4l2cap.c. Added new control -IDs: V4L2_CID_HFLIP, _VFLIP. Changed V4L2_PIX_FMT_YUV422P to _YUV422P, -and _YUV411P to _YUV411P.</para> - <para>1999-04-04: Added a few more control IDs.</para> - <para>1999-04-07: Added the button control type.</para> - <para>1999-05-02: Fixed a typo in videodev.h, and added the -V4L2_CTRL_FLAG_GRAYED (later V4L2_CTRL_FLAG_GRABBED) flag.</para> - <para>1999-05-20: Definition of VIDIOC_G_CTRL was wrong causing -a malfunction of this ioctl.</para> - <para>1999-06-05: Changed the value of -V4L2_CID_WHITENESS.</para> - </section> - - <section> - <title>V4L2 Version 0.20 (1999-09-10)</title> - - <para>Version 0.20 introduced a number of changes which were -<emphasis>not backward compatible</emphasis> with 0.19 and earlier -versions. Purpose of these changes was to simplify the API, while -making it more extensible and following common Linux driver API -conventions.</para> - - <orderedlist> - <listitem> - <para>Some typos in <constant>V4L2_FMT_FLAG</constant> -symbols were fixed. &v4l2-clip; was changed for compatibility with -v4l. (1999-08-30)</para> - </listitem> - - <listitem> - <para><constant>V4L2_TUNER_SUB_LANG1</constant> was added. -(1999-09-05)</para> - </listitem> - - <listitem> - <para>All ioctl() commands that used an integer argument now -take a pointer to an integer. Where it makes sense, ioctls will return -the actual new value in the integer pointed to by the argument, a -common convention in the V4L2 API. The affected ioctls are: -VIDIOC_PREVIEW, VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S_FREQ, -VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_EFFECT. For example -<programlisting> -err = ioctl (fd, VIDIOC_XXX, V4L2_XXX); -</programlisting> becomes <programlisting> -int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &a); -</programlisting> - </para> - </listitem> - - <listitem> - <para>All the different get- and set-format commands were -swept into one &VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctl taking a union -and a type field selecting the union member as parameter. Purpose is to -simplify the API by eliminating several ioctls and to allow new and -driver private data streams without adding new ioctls.</para> - - <para>This change obsoletes the following ioctls: -<constant>VIDIOC_S_INFMT</constant>, -<constant>VIDIOC_G_INFMT</constant>, -<constant>VIDIOC_S_OUTFMT</constant>, -<constant>VIDIOC_G_OUTFMT</constant>, -<constant>VIDIOC_S_VBIFMT</constant> and -<constant>VIDIOC_G_VBIFMT</constant>. The image format structure -<structname>v4l2_format</structname> was renamed to &v4l2-pix-format;, -while &v4l2-format; is now the envelopping structure for all format -negotiations.</para> - </listitem> - - <listitem> - <para>Similar to the changes above, the -<constant>VIDIOC_G_PARM</constant> and -<constant>VIDIOC_S_PARM</constant> ioctls were merged with -<constant>VIDIOC_G_OUTPARM</constant> and -<constant>VIDIOC_S_OUTPARM</constant>. A -<structfield>type</structfield> field in the new &v4l2-streamparm; -selects the respective union member.</para> - - <para>This change obsoletes the -<constant>VIDIOC_G_OUTPARM</constant> and -<constant>VIDIOC_S_OUTPARM</constant> ioctls.</para> - </listitem> - - <listitem> - <para>Control enumeration was simplified, and two new -control flags were introduced and one dropped. The -<structfield>catname</structfield> field was replaced by a -<structfield>group</structfield> field.</para> - - <para>Drivers can now flag unsupported and temporarily -unavailable controls with <constant>V4L2_CTRL_FLAG_DISABLED</constant> -and <constant>V4L2_CTRL_FLAG_GRABBED</constant> respectively. The -<structfield>group</structfield> name indicates a possibly narrower -classification than the <structfield>category</structfield>. In other -words, there may be multiple groups within a category. Controls within -a group would typically be drawn within a group box. Controls in -different categories might have a greater separation, or may even -appear in separate windows.</para> - </listitem> - - <listitem> - <para>The &v4l2-buffer; <structfield>timestamp</structfield> -was changed to a 64 bit integer, containing the sampling or output -time of the frame in nanoseconds. Additionally timestamps will be in -absolute system time, not starting from zero at the beginning of a -stream. The data type name for timestamps is stamp_t, defined as a -signed 64-bit integer. Output devices should not send a buffer out -until the time in the timestamp field has arrived. I would like to -follow SGI's lead, and adopt a multimedia timestamping system like -their UST (Unadjusted System Time). See -http://web.archive.org/web/*/http://reality.sgi.com -/cpirazzi_engr/lg/time/intro.html. -UST uses timestamps that are 64-bit signed integers -(not struct timeval's) and given in nanosecond units. The UST clock -starts at zero when the system is booted and runs continuously and -uniformly. It takes a little over 292 years for UST to overflow. There -is no way to set the UST clock. The regular Linux time-of-day clock -can be changed periodically, which would cause errors if it were being -used for timestamping a multimedia stream. A real UST style clock will -require some support in the kernel that is not there yet. But in -anticipation, I will change the timestamp field to a 64-bit integer, -and I will change the v4l2_masterclock_gettime() function (used only -by drivers) to return a 64-bit integer.</para> - </listitem> - - <listitem> - <para>A <structfield>sequence</structfield> field was added -to &v4l2-buffer;. The <structfield>sequence</structfield> field counts -captured frames, it is ignored by output devices. When a capture -driver drops a frame, the sequence number of that frame is -skipped.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 Version 0.20 incremental changes</title> - <!-- Version number didn't change anymore, reason unknown. --> - - <para>1999-12-23: In &v4l2-vbi-format; the -<structfield>reserved1</structfield> field became -<structfield>offset</structfield>. Previously drivers were required to -clear the <structfield>reserved1</structfield> field.</para> - - <para>2000-01-13: The - <constant>V4L2_FMT_FLAG_NOT_INTERLACED</constant> flag was added.</para> - - <para>2000-07-31: The <filename>linux/poll.h</filename> header -is now included by <filename>videodev.h</filename> for compatibility -with the original <filename>videodev.h</filename> file.</para> - - <para>2000-11-20: <constant>V4L2_TYPE_VBI_OUTPUT</constant> and -<constant>V4L2_PIX_FMT_Y41P</constant> were added.</para> - - <para>2000-11-25: <constant>V4L2_TYPE_VBI_INPUT</constant> was -added.</para> - - <para>2000-12-04: A couple typos in symbol names were fixed.</para> - - <para>2001-01-18: To avoid namespace conflicts the -<constant>fourcc</constant> macro defined in the -<filename>videodev.h</filename> header file was renamed to -<constant>v4l2_fourcc</constant>.</para> - - <para>2001-01-25: A possible driver-level compatibility problem -between the <filename>videodev.h</filename> file in Linux 2.4.0 and -the <filename>videodev.h</filename> file included in the -<filename>videodevX</filename> patch was fixed. Users of an earlier -version of <filename>videodevX</filename> on Linux 2.4.0 should -recompile their V4L and V4L2 drivers.</para> - - <para>2001-01-26: A possible kernel-level incompatibility -between the <filename>videodev.h</filename> file in the -<filename>videodevX</filename> patch and the -<filename>videodev.h</filename> file in Linux 2.2.x with devfs patches -applied was fixed.</para> - - <para>2001-03-02: Certain V4L ioctls which pass data in both -direction although they are defined with read-only parameter, did not -work correctly through the backward compatibility layer. -[Solution?]</para> - - <para>2001-04-13: Big endian 16-bit RGB formats were added.</para> - - <para>2001-09-17: New YUV formats and the &VIDIOC-G-FREQUENCY; and -&VIDIOC-S-FREQUENCY; ioctls were added. (The old -<constant>VIDIOC_G_FREQ</constant> and -<constant>VIDIOC_S_FREQ</constant> ioctls did not take multiple tuners -into account.)</para> - - <para>2000-09-18: <constant>V4L2_BUF_TYPE_VBI</constant> was -added. This may <emphasis>break compatibility</emphasis> as the -&VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls may fail now if the struct -<structname>v4l2_fmt</structname> <structfield>type</structfield> -field does not contain <constant>V4L2_BUF_TYPE_VBI</constant>. In the -documentation of the &v4l2-vbi-format; -<structfield>offset</structfield> field the ambiguous phrase "rising -edge" was changed to "leading edge".</para> - </section> - - <section> - <title>V4L2 Version 0.20 2000-11-23</title> - - <para>A number of changes were made to the raw VBI -interface.</para> - - <orderedlist> - <listitem> - <para>Figures clarifying the line numbering scheme were -added to the V4L2 API specification. The -<structfield>start</structfield>[0] and -<structfield>start</structfield>[1] fields no longer count line -numbers beginning at zero. Rationale: a) The previous definition was -unclear. b) The <structfield>start</structfield>[] values are ordinal -numbers. c) There is no point in inventing a new line numbering -scheme. We now use line number as defined by ITU-R, period. -Compatibility: Add one to the start values. Applications depending on -the previous semantics may not function correctly.</para> - </listitem> - - <listitem> - <para>The restriction "count[0] > 0 and count[1] > 0" -has been relaxed to "(count[0] + count[1]) > 0". Rationale: -Drivers may allocate resources at scan line granularity and some data -services are transmitted only on the first field. The comment that -both <structfield>count</structfield> values will usually be equal is -misleading and pointless and has been removed. This change -<emphasis>breaks compatibility</emphasis> with earlier versions: -Drivers may return EINVAL, applications may not function -correctly.</para> - </listitem> - - <listitem> - <para>Drivers are again permitted to return negative -(unknown) start values as proposed earlier. Why this feature was -dropped is unclear. This change may <emphasis>break -compatibility</emphasis> with applications depending on the start -values being positive. The use of <constant>EBUSY</constant> and -<constant>EINVAL</constant> error codes with the &VIDIOC-S-FMT; ioctl -was clarified. The &EBUSY; was finally documented, and the -<structfield>reserved2</structfield> field which was previously -mentioned only in the <filename>videodev.h</filename> header -file.</para> - </listitem> - - <listitem> - <para>New buffer types -<constant>V4L2_TYPE_VBI_INPUT</constant> and -<constant>V4L2_TYPE_VBI_OUTPUT</constant> were added. The former is an -alias for the old <constant>V4L2_TYPE_VBI</constant>, the latter was -missing in the <filename>videodev.h</filename> file.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 Version 0.20 2002-07-25</title> - <para>Added sliced VBI interface proposal.</para> - </section> - - <section> - <title>V4L2 in Linux 2.5.46, 2002-10</title> - - <para>Around October-November 2002, prior to an announced -feature freeze of Linux 2.5, the API was revised, drawing from -experience with V4L2 0.20. This unnamed version was finally merged -into Linux 2.5.46.</para> - - <orderedlist> - <listitem> - <para>As specified in <xref linkend="related" />, drivers -must make related device functions available under all minor device -numbers.</para> - </listitem> - - <listitem> - <para>The &func-open; function requires access mode -<constant>O_RDWR</constant> regardless of the device type. All V4L2 -drivers exchanging data with applications must support the -<constant>O_NONBLOCK</constant> flag. The <constant>O_NOIO</constant> -flag, a V4L2 symbol which aliased the meaningless -<constant>O_TRUNC</constant> to indicate accesses without data -exchange (panel applications) was dropped. Drivers must stay in "panel -mode" until the application attempts to initiate a data exchange, see -<xref linkend="open" />.</para> - </listitem> - - <listitem> - <para>The &v4l2-capability; changed dramatically. Note that -also the size of the structure changed, which is encoded in the ioctl -request code, thus older V4L2 devices will respond with an &EINVAL; to -the new &VIDIOC-QUERYCAP; ioctl.</para> - - <para>There are new fields to identify the driver, a new RDS -device function <constant>V4L2_CAP_RDS_CAPTURE</constant>, the -<constant>V4L2_CAP_AUDIO</constant> flag indicates if the device has -any audio connectors, another I/O capability -<constant>V4L2_CAP_ASYNCIO</constant> can be flagged. In response to -these changes the <structfield>type</structfield> field became a bit -set and was merged into the <structfield>flags</structfield> field. -<constant>V4L2_FLAG_TUNER</constant> was renamed to -<constant>V4L2_CAP_TUNER</constant>, -<constant>V4L2_CAP_VIDEO_OVERLAY</constant> replaced -<constant>V4L2_FLAG_PREVIEW</constant> and -<constant>V4L2_CAP_VBI_CAPTURE</constant> and -<constant>V4L2_CAP_VBI_OUTPUT</constant> replaced -<constant>V4L2_FLAG_DATA_SERVICE</constant>. -<constant>V4L2_FLAG_READ</constant> and -<constant>V4L2_FLAG_WRITE</constant> were merged into -<constant>V4L2_CAP_READWRITE</constant>.</para> - - <para>The redundant fields -<structfield>inputs</structfield>, <structfield>outputs</structfield> -and <structfield>audios</structfield> were removed. These properties -can be determined as described in <xref linkend="video" /> and <xref -linkend="audio" />.</para> - - <para>The somewhat volatile and therefore barely useful -fields <structfield>maxwidth</structfield>, -<structfield>maxheight</structfield>, -<structfield>minwidth</structfield>, -<structfield>minheight</structfield>, -<structfield>maxframerate</structfield> were removed. This information -is available as described in <xref linkend="format" /> and -<xref linkend="standard" />.</para> - - <para><constant>V4L2_FLAG_SELECT</constant> was removed. We -believe the select() function is important enough to require support -of it in all V4L2 drivers exchanging data with applications. The -redundant <constant>V4L2_FLAG_MONOCHROME</constant> flag was removed, -this information is available as described in <xref - linkend="format" />.</para> - </listitem> - - <listitem> - <para>In &v4l2-input; the -<structfield>assoc_audio</structfield> field and the -<structfield>capability</structfield> field and its only flag -<constant>V4L2_INPUT_CAP_AUDIO</constant> was replaced by the new -<structfield>audioset</structfield> field. Instead of linking one -video input to one audio input this field reports all audio inputs -this video input combines with.</para> - - <para>New fields are <structfield>tuner</structfield> -(reversing the former link from tuners to video inputs), -<structfield>std</structfield> and -<structfield>status</structfield>.</para> - - <para>Accordingly &v4l2-output; lost its -<structfield>capability</structfield> and -<structfield>assoc_audio</structfield> fields. -<structfield>audioset</structfield>, -<structfield>modulator</structfield> and -<structfield>std</structfield> where added instead.</para> - </listitem> - - <listitem> - <para>The &v4l2-audio; field -<structfield>audio</structfield> was renamed to -<structfield>index</structfield>, for consistency with other -structures. A new capability flag -<constant>V4L2_AUDCAP_STEREO</constant> was added to indicated if the -audio input in question supports stereo sound. -<constant>V4L2_AUDCAP_EFFECTS</constant> and the corresponding -<constant>V4L2_AUDMODE</constant> flags where removed. This can be -easily implemented using controls. (However the same applies to AVL -which is still there.)</para> - - <para>Again for consistency the &v4l2-audioout; field -<structfield>audio</structfield> was renamed to -<structfield>index</structfield>.</para> - </listitem> - - <listitem> - <para>The &v4l2-tuner; -<structfield>input</structfield> field was replaced by an -<structfield>index</structfield> field, permitting devices with -multiple tuners. The link between video inputs and tuners is now -reversed, inputs point to their tuner. The -<structfield>std</structfield> substructure became a -simple set (more about this below) and moved into &v4l2-input;. A -<structfield>type</structfield> field was added.</para> - - <para>Accordingly in &v4l2-modulator; the -<structfield>output</structfield> was replaced by an -<structfield>index</structfield> field.</para> - - <para>In &v4l2-frequency; the -<structfield>port</structfield> field was replaced by a -<structfield>tuner</structfield> field containing the respective tuner -or modulator index number. A tuner <structfield>type</structfield> -field was added and the <structfield>reserved</structfield> field -became larger for future extensions (satellite tuners in -particular).</para> - </listitem> - - <listitem> - <para>The idea of completely transparent video standards was -dropped. Experience showed that applications must be able to work with -video standards beyond presenting the user a menu. Instead of -enumerating supported standards with an ioctl applications can now -refer to standards by &v4l2-std-id; and symbols defined in the -<filename>videodev2.h</filename> header file. For details see <xref - linkend="standard" />. The &VIDIOC-G-STD; and -&VIDIOC-S-STD; now take a pointer to this type as argument. -&VIDIOC-QUERYSTD; was added to autodetect the received standard, if -the hardware has this capability. In &v4l2-standard; an -<structfield>index</structfield> field was added for &VIDIOC-ENUMSTD;. -A &v4l2-std-id; field named <structfield>id</structfield> was added as -machine readable identifier, also replacing the -<structfield>transmission</structfield> field. The misleading -<structfield>framerate</structfield> field was renamed -to <structfield>frameperiod</structfield>. The now obsolete -<structfield>colorstandard</structfield> information, originally -needed to distguish between variations of standards, were -removed.</para> - - <para>Struct <structname>v4l2_enumstd</structname> ceased to -be. &VIDIOC-ENUMSTD; now takes a pointer to a &v4l2-standard; -directly. The information which standards are supported by a -particular video input or output moved into &v4l2-input; and -&v4l2-output; fields named <structfield>std</structfield>, -respectively.</para> - </listitem> - - <listitem> - <para>The &v4l2-queryctrl; fields -<structfield>category</structfield> and -<structfield>group</structfield> did not catch on and/or were not -implemented as expected and therefore removed.</para> - </listitem> - - <listitem> - <para>The &VIDIOC-TRY-FMT; ioctl was added to negotiate data -formats as with &VIDIOC-S-FMT;, but without the overhead of -programming the hardware and regardless of I/O in progress.</para> - - <para>In &v4l2-format; the <structfield>fmt</structfield> -union was extended to contain &v4l2-window;. All image format -negotiations are now possible with <constant>VIDIOC_G_FMT</constant>, -<constant>VIDIOC_S_FMT</constant> and -<constant>VIDIOC_TRY_FMT</constant>; ioctl. The -<constant>VIDIOC_G_WIN</constant> and -<constant>VIDIOC_S_WIN</constant> ioctls to prepare for a video -overlay were removed. The <structfield>type</structfield> field -changed to type &v4l2-buf-type; and the buffer type names changed as -follows.<informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Old defines</entry> - <entry>&v4l2-buf-type;</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry><constant>V4L2_BUF_TYPE_CAPTURE</constant></entry> - <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_CODECIN</constant></entry> - <entry>Omitted for now</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_CODECOUT</constant></entry> - <entry>Omitted for now</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_EFFECTSIN</constant></entry> - <entry>Omitted for now</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_EFFECTSIN2</constant></entry> - <entry>Omitted for now</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_EFFECTSOUT</constant></entry> - <entry>Omitted for now</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_VIDEOOUT</constant></entry> - <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry> - </row> - <row> - <entry><constant>-</constant></entry> - <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry> - </row> - <row> - <entry><constant>-</constant></entry> - <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry> - </row> - <row> - <entry><constant>-</constant></entry> - <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry> - </row> - <row> - <entry><constant>-</constant></entry> - <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry> - </row> - <row> - <entry><constant>-</constant></entry> - <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_PRIVATE_BASE</constant></entry> - <entry><constant>V4L2_BUF_TYPE_PRIVATE</constant> (but this is deprecated)</entry> - </row> - </tbody> - </tgroup> - </informaltable></para> - </listitem> - - <listitem> - <para>In &v4l2-fmtdesc; a &v4l2-buf-type; field named -<structfield>type</structfield> was added as in &v4l2-format;. The -<constant>VIDIOC_ENUM_FBUFFMT</constant> ioctl is no longer needed and -was removed. These calls can be replaced by &VIDIOC-ENUM-FMT; with -type <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>.</para> - </listitem> - - <listitem> - <para>In &v4l2-pix-format; the -<structfield>depth</structfield> field was removed, assuming -applications which recognize the format by its four-character-code -already know the color depth, and others do not care about it. The -same rationale lead to the removal of the -<constant>V4L2_FMT_FLAG_COMPRESSED</constant> flag. The -<constant>V4L2_FMT_FLAG_SWCONVECOMPRESSED</constant> flag was removed -because drivers are not supposed to convert images in kernel space. A -user library of conversion functions should be provided instead. The -<constant>V4L2_FMT_FLAG_BYTESPERLINE</constant> flag was redundant. -Applications can set the <structfield>bytesperline</structfield> field -to zero to get a reasonable default. Since the remaining flags were -replaced as well, the <structfield>flags</structfield> field itself -was removed.</para> - <para>The interlace flags were replaced by a &v4l2-field; -value in a newly added <structfield>field</structfield> -field.<informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Old flag</entry> - <entry>&v4l2-field;</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry><constant>V4L2_FMT_FLAG_NOT_INTERLACED</constant></entry> - <entry>?</entry> - </row> - <row> - <entry><constant>V4L2_FMT_FLAG_INTERLACED</constant> -= <constant>V4L2_FMT_FLAG_COMBINED</constant></entry> - <entry><constant>V4L2_FIELD_INTERLACED</constant></entry> - </row> - <row> - <entry><constant>V4L2_FMT_FLAG_TOPFIELD</constant> -= <constant>V4L2_FMT_FLAG_ODDFIELD</constant></entry> - <entry><constant>V4L2_FIELD_TOP</constant></entry> - </row> - <row> - <entry><constant>V4L2_FMT_FLAG_BOTFIELD</constant> -= <constant>V4L2_FMT_FLAG_EVENFIELD</constant></entry> - <entry><constant>V4L2_FIELD_BOTTOM</constant></entry> - </row> - <row> - <entry><constant>-</constant></entry> - <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry> - </row> - <row> - <entry><constant>-</constant></entry> - <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry> - </row> - <row> - <entry><constant>-</constant></entry> - <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry> - </row> - </tbody> - </tgroup> - </informaltable></para> - - <para>The color space flags were replaced by a -&v4l2-colorspace; value in a newly added -<structfield>colorspace</structfield> field, where one of -<constant>V4L2_COLORSPACE_SMPTE170M</constant>, -<constant>V4L2_COLORSPACE_BT878</constant>, -<constant>V4L2_COLORSPACE_470_SYSTEM_M</constant> or -<constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant> replaces -<constant>V4L2_FMT_CS_601YUV</constant>.</para> - </listitem> - - <listitem> - <para>In &v4l2-requestbuffers; the -<structfield>type</structfield> field was properly defined as -&v4l2-buf-type;. Buffer types changed as mentioned above. A new -<structfield>memory</structfield> field of type &v4l2-memory; was -added to distinguish between I/O methods using buffers allocated -by the driver or the application. See <xref linkend="io" /> for -details.</para> - </listitem> - - <listitem> - <para>In &v4l2-buffer; the <structfield>type</structfield> -field was properly defined as &v4l2-buf-type;. Buffer types changed as -mentioned above. A <structfield>field</structfield> field of type -&v4l2-field; was added to indicate if a buffer contains a top or -bottom field. The old field flags were removed. Since no unadjusted -system time clock was added to the kernel as planned, the -<structfield>timestamp</structfield> field changed back from type -stamp_t, an unsigned 64 bit integer expressing the sample time in -nanoseconds, to struct <structname>timeval</structname>. With the -addition of a second memory mapping method the -<structfield>offset</structfield> field moved into union -<structfield>m</structfield>, and a new -<structfield>memory</structfield> field of type &v4l2-memory; was -added to distinguish between I/O methods. See <xref linkend="io" /> -for details.</para> - - <para>The <constant>V4L2_BUF_REQ_CONTIG</constant> -flag was used by the V4L compatibility layer, after changes to this -code it was no longer needed. The -<constant>V4L2_BUF_ATTR_DEVICEMEM</constant> flag would indicate if -the buffer was indeed allocated in device memory rather than DMA-able -system memory. It was barely useful and so was removed.</para> - </listitem> - - <listitem> - <para>In &v4l2-framebuffer; the -<structfield>base[3]</structfield> array anticipating double- and -triple-buffering in off-screen video memory, however without defining -a synchronization mechanism, was replaced by a single pointer. The -<constant>V4L2_FBUF_CAP_SCALEUP</constant> and -<constant>V4L2_FBUF_CAP_SCALEDOWN</constant> flags were removed. -Applications can determine this capability more accurately using the -new cropping and scaling interface. The -<constant>V4L2_FBUF_CAP_CLIPPING</constant> flag was replaced by -<constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant> and -<constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant>.</para> - </listitem> - - <listitem> - <para>In &v4l2-clip; the <structfield>x</structfield>, -<structfield>y</structfield>, <structfield>width</structfield> and -<structfield>height</structfield> field moved into a -<structfield>c</structfield> substructure of type &v4l2-rect;. The -<structfield>x</structfield> and <structfield>y</structfield> fields -were renamed to <structfield>left</structfield> and -<structfield>top</structfield>, &ie; offsets to a context dependent -origin.</para> - </listitem> - - <listitem> - <para>In &v4l2-window; the <structfield>x</structfield>, -<structfield>y</structfield>, <structfield>width</structfield> and -<structfield>height</structfield> field moved into a -<structfield>w</structfield> substructure as above. A -<structfield>field</structfield> field of type %v4l2-field; was added -to distinguish between field and frame (interlaced) overlay.</para> - </listitem> - - <listitem> - <para>The digital zoom interface, including struct -<structname>v4l2_zoomcap</structname>, struct -<structname>v4l2_zoom</structname>, -<constant>V4L2_ZOOM_NONCAP</constant> and -<constant>V4L2_ZOOM_WHILESTREAMING</constant> was replaced by a new -cropping and scaling interface. The previously unused struct -<structname>v4l2_cropcap</structname> and -<structname>v4l2_crop</structname> where redefined for this purpose. -See <xref linkend="crop" /> for details.</para> - </listitem> - - <listitem> - <para>In &v4l2-vbi-format; the -<structfield>SAMPLE_FORMAT</structfield> field now contains a -four-character-code as used to identify video image formats and -<constant>V4L2_PIX_FMT_GREY</constant> replaces the -<constant>V4L2_VBI_SF_UBYTE</constant> define. The -<structfield>reserved</structfield> field was extended.</para> - </listitem> - - <listitem> - <para>In &v4l2-captureparm; the type of the -<structfield>timeperframe</structfield> field changed from unsigned -long to &v4l2-fract;. This allows the accurate expression of multiples -of the NTSC-M frame rate 30000 / 1001. A new field -<structfield>readbuffers</structfield> was added to control the driver -behaviour in read I/O mode.</para> - - <para>Similar changes were made to &v4l2-outputparm;.</para> - </listitem> - - <listitem> - <para>The struct <structname>v4l2_performance</structname> -and <constant>VIDIOC_G_PERF</constant> ioctl were dropped. Except when -using the <link linkend="rw">read/write I/O method</link>, which is -limited anyway, this information is already available to -applications.</para> - </listitem> - - <listitem> - <para>The example transformation from RGB to YCbCr color -space in the old V4L2 documentation was inaccurate, this has been -corrected in <xref linkend="pixfmt" />.<!-- 0.5670G should be -0.587, and 127/112 != 255/224 --></para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 2003-06-19</title> - - <orderedlist> - <listitem> - <para>A new capability flag -<constant>V4L2_CAP_RADIO</constant> was added for radio devices. Prior -to this change radio devices would identify solely by having exactly one -tuner whose type field reads <constant>V4L2_TUNER_RADIO</constant>.</para> - </listitem> - - <listitem> - <para>An optional driver access priority mechanism was -added, see <xref linkend="app-pri" /> for details.</para> - </listitem> - - <listitem> - <para>The audio input and output interface was found to be -incomplete.</para> - <para>Previously the &VIDIOC-G-AUDIO; -ioctl would enumerate the available audio inputs. An ioctl to -determine the current audio input, if more than one combines with the -current video input, did not exist. So -<constant>VIDIOC_G_AUDIO</constant> was renamed to -<constant>VIDIOC_G_AUDIO_OLD</constant>, this ioctl was removed on -Kernel 2.6.39. The &VIDIOC-ENUMAUDIO; ioctl was added to enumerate -audio inputs, while &VIDIOC-G-AUDIO; now reports the current audio -input.</para> - <para>The same changes were made to &VIDIOC-G-AUDOUT; and -&VIDIOC-ENUMAUDOUT;.</para> - <para>Until further the "videodev" module will automatically -translate between the old and new ioctls, but drivers and applications -must be updated to successfully compile again.</para> - </listitem> - - <listitem> - <para>The &VIDIOC-OVERLAY; ioctl was incorrectly defined with -write-read parameter. It was changed to write-only, while the write-read -version was renamed to <constant>VIDIOC_OVERLAY_OLD</constant>. The old -ioctl was removed on Kernel 2.6.39. Until further the "videodev" -kernel module will automatically translate to the new version, so drivers -must be recompiled, but not applications.</para> - </listitem> - - <listitem> - <para><xref linkend="overlay" /> incorrectly stated that -clipping rectangles define regions where the video can be seen. -Correct is that clipping rectangles define regions where -<emphasis>no</emphasis> video shall be displayed and so the graphics -surface can be seen.</para> - </listitem> - - <listitem> - <para>The &VIDIOC-S-PARM; and &VIDIOC-S-CTRL; ioctls were -defined with write-only parameter, inconsistent with other ioctls -modifying their argument. They were changed to write-read, while a -<constant>_OLD</constant> suffix was added to the write-only versions. -The old ioctls were removed on Kernel 2.6.39. Drivers and -applications assuming a constant parameter need an update.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 2003-11-05</title> - <orderedlist> - <listitem> - <para>In <xref linkend="pixfmt-rgb" /> the following pixel -formats were incorrectly transferred from Bill Dirks' V4L2 -specification. Descriptions below refer to bytes in memory, in -ascending address order.<informaltable> - <tgroup cols="3"> - <thead> - <row> - <entry>Symbol</entry> - <entry>In this document prior to revision -0.5</entry> - <entry>Corrected</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry><constant>V4L2_PIX_FMT_RGB24</constant></entry> - <entry>B, G, R</entry> - <entry>R, G, B</entry> - </row> - <row> - <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry> - <entry>R, G, B</entry> - <entry>B, G, R</entry> - </row> - <row> - <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry> - <entry>B, G, R, X</entry> - <entry>R, G, B, X</entry> - </row> - <row> - <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry> - <entry>R, G, B, X</entry> - <entry>B, G, R, X</entry> - </row> - </tbody> - </tgroup> - </informaltable> The -<constant>V4L2_PIX_FMT_BGR24</constant> example was always -correct.</para> - <para>In <xref linkend="v4l-image-properties" /> the mapping -of the V4L <constant>VIDEO_PALETTE_RGB24</constant> and -<constant>VIDEO_PALETTE_RGB32</constant> formats to V4L2 pixel formats -was accordingly corrected.</para> - </listitem> - - <listitem> - <para>Unrelated to the fixes above, drivers may still -interpret some V4L2 RGB pixel formats differently. These issues have -yet to be addressed, for details see <xref - linkend="pixfmt-rgb" />.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 2.6.6, 2004-05-09</title> - <orderedlist> - <listitem> - <para>The &VIDIOC-CROPCAP; ioctl was incorrectly defined -with read-only parameter. It is now defined as write-read ioctl, while -the read-only version was renamed to -<constant>VIDIOC_CROPCAP_OLD</constant>. The old ioctl was removed -on Kernel 2.6.39.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 2.6.8</title> - <orderedlist> - <listitem> - <para>A new field <structfield>input</structfield> (former -<structfield>reserved[0]</structfield>) was added to the &v4l2-buffer; -structure. Purpose of this field is to alternate between video inputs -(⪚ cameras) in step with the video capturing process. This function -must be enabled with the new <constant>V4L2_BUF_FLAG_INPUT</constant> -flag. The <structfield>flags</structfield> field is no longer -read-only.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 spec erratum 2004-08-01</title> - - <orderedlist> - <listitem> - <para>The return value of the -<xref linkend="func-open" /> function was incorrectly documented.</para> - </listitem> - - <listitem> - <para>Audio output ioctls end in -AUDOUT, not -AUDIOOUT.</para> - </listitem> - - <listitem> - <para>In the Current Audio Input example the -<constant>VIDIOC_G_AUDIO</constant> ioctl took the wrong -argument.</para> - </listitem> - - <listitem> - <para>The documentation of the &VIDIOC-QBUF; and -&VIDIOC-DQBUF; ioctls did not mention the &v4l2-buffer; -<structfield>memory</structfield> field. It was also missing from -examples. Also on the <constant>VIDIOC_DQBUF</constant> page the &EIO; -was not documented.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 2.6.14</title> - <orderedlist> - <listitem> - <para>A new sliced VBI interface was added. It is documented -in <xref linkend="sliced" /> and replaces the interface first -proposed in V4L2 specification 0.8.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 2.6.15</title> - <orderedlist> - <listitem> - <para>The &VIDIOC-LOG-STATUS; ioctl was added.</para> - </listitem> - - <listitem> - <para>New video standards -<constant>V4L2_STD_NTSC_443</constant>, -<constant>V4L2_STD_SECAM_LC</constant>, -<constant>V4L2_STD_SECAM_DK</constant> (a set of SECAM D, K and K1), -and <constant>V4L2_STD_ATSC</constant> (a set of -<constant>V4L2_STD_ATSC_8_VSB</constant> and -<constant>V4L2_STD_ATSC_16_VSB</constant>) were defined. Note the -<constant>V4L2_STD_525_60</constant> set now includes -<constant>V4L2_STD_NTSC_443</constant>. See also <xref - linkend="v4l2-std-id" />.</para> - </listitem> - - <listitem> - <para>The <constant>VIDIOC_G_COMP</constant> and -<constant>VIDIOC_S_COMP</constant> ioctl were renamed to -<constant>VIDIOC_G_MPEGCOMP</constant> and -<constant>VIDIOC_S_MPEGCOMP</constant> respectively. Their argument -was replaced by a struct -<structname>v4l2_mpeg_compression</structname> pointer. (The -<constant>VIDIOC_G_MPEGCOMP</constant> and -<constant>VIDIOC_S_MPEGCOMP</constant> ioctls where removed in Linux -2.6.25.)</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 spec erratum 2005-11-27</title> - <para>The capture example in <xref linkend="capture-example" /> -called the &VIDIOC-S-CROP; ioctl without checking if cropping is -supported. In the video standard selection example in -<xref linkend="standard" /> the &VIDIOC-S-STD; call used the wrong -argument type.</para> - </section> - - <section> - <title>V4L2 spec erratum 2006-01-10</title> - <orderedlist> - <listitem> - <para>The <constant>V4L2_IN_ST_COLOR_KILL</constant> flag in -&v4l2-input; not only indicates if the color killer is enabled, but -also if it is active. (The color killer disables color decoding when -it detects no color in the video signal to improve the image -quality.)</para> - </listitem> - - <listitem> - <para>&VIDIOC-S-PARM; is a write-read ioctl, not write-only as -stated on its reference page. The ioctl changed in 2003 as noted above.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 spec erratum 2006-02-03</title> - <orderedlist> - <listitem> - <para>In &v4l2-captureparm; and &v4l2-outputparm; the -<structfield>timeperframe</structfield> field gives the time in -seconds, not microseconds.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 spec erratum 2006-02-04</title> - <orderedlist> - <listitem> - <para>The <structfield>clips</structfield> field in -&v4l2-window; must point to an array of &v4l2-clip;, not a linked -list, because drivers ignore the struct -<structname>v4l2_clip</structname>.<structfield>next</structfield> -pointer.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 2.6.17</title> - <orderedlist> - <listitem> - <para>New video standard macros were added: -<constant>V4L2_STD_NTSC_M_KR</constant> (NTSC M South Korea), and the -sets <constant>V4L2_STD_MN</constant>, -<constant>V4L2_STD_B</constant>, <constant>V4L2_STD_GH</constant> and -<constant>V4L2_STD_DK</constant>. The -<constant>V4L2_STD_NTSC</constant> and -<constant>V4L2_STD_SECAM</constant> sets now include -<constant>V4L2_STD_NTSC_M_KR</constant> and -<constant>V4L2_STD_SECAM_LC</constant> respectively.</para> - </listitem> - - <listitem> - <para>A new <constant>V4L2_TUNER_MODE_LANG1_LANG2</constant> -was defined to record both languages of a bilingual program. The -use of <constant>V4L2_TUNER_MODE_STEREO</constant> for this purpose -is deprecated now. See the &VIDIOC-G-TUNER; section for -details.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 spec erratum 2006-09-23 (Draft 0.15)</title> - <orderedlist> - <listitem> - <para>In various places -<constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> and -<constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant> of the sliced VBI -interface were not mentioned along with other buffer types.</para> - </listitem> - - <listitem> - <para>In <xref linkend="vidioc-g-audio" /> it was clarified -that the &v4l2-audio; <structfield>mode</structfield> field is a flags -field.</para> - </listitem> - - <listitem> - <para><xref linkend="vidioc-querycap" /> did not mention the -sliced VBI and radio capability flags.</para> - </listitem> - - <listitem> - <para>In <xref linkend="vidioc-g-frequency" /> it was -clarified that applications must initialize the tuner -<structfield>type</structfield> field of &v4l2-frequency; before -calling &VIDIOC-S-FREQUENCY;.</para> - </listitem> - - <listitem> - <para>The <structfield>reserved</structfield> array -in &v4l2-requestbuffers; has 2 elements, not 32.</para> - </listitem> - - <listitem> - <para>In <xref linkend="output" /> and <xref - linkend="raw-vbi" /> the device file names -<filename>/dev/vout</filename> which never caught on were replaced -by <filename>/dev/video</filename>.</para> - </listitem> - - <listitem> - <para>With Linux 2.6.15 the possible range for VBI device minor -numbers was extended from 224-239 to 224-255. Accordingly device file names -<filename>/dev/vbi0</filename> to <filename>/dev/vbi31</filename> are -possible now.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 2.6.18</title> - <orderedlist> - <listitem> - <para>New ioctls &VIDIOC-G-EXT-CTRLS;, &VIDIOC-S-EXT-CTRLS; -and &VIDIOC-TRY-EXT-CTRLS; were added, a flag to skip unsupported -controls with &VIDIOC-QUERYCTRL;, new control types -<constant>V4L2_CTRL_TYPE_INTEGER64</constant> and -<constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant> (<xref - linkend="v4l2-ctrl-type" />), and new control flags -<constant>V4L2_CTRL_FLAG_READ_ONLY</constant>, -<constant>V4L2_CTRL_FLAG_UPDATE</constant>, -<constant>V4L2_CTRL_FLAG_INACTIVE</constant> and -<constant>V4L2_CTRL_FLAG_SLIDER</constant> (<xref - linkend="control-flags" />). See <xref - linkend="extended-controls" /> for details.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 2.6.19</title> - <orderedlist> - <listitem> - <para>In &v4l2-sliced-vbi-cap; a buffer type field was added -replacing a reserved field. Note on architectures where the size of -enum types differs from int types the size of the structure changed. -The &VIDIOC-G-SLICED-VBI-CAP; ioctl was redefined from being read-only -to write-read. Applications must initialize the type field and clear -the reserved fields now. These changes may <emphasis>break the -compatibility</emphasis> with older drivers and applications.</para> - </listitem> - - <listitem> - <para>The ioctls &VIDIOC-ENUM-FRAMESIZES; and -&VIDIOC-ENUM-FRAMEINTERVALS; were added.</para> - </listitem> - - <listitem> - <para>A new pixel format <constant>V4L2_PIX_FMT_RGB444</constant> (<xref -linkend="rgb-formats" />) was added.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 spec erratum 2006-10-12 (Draft 0.17)</title> - <orderedlist> - <listitem> - <para><constant>V4L2_PIX_FMT_HM12</constant> (<xref -linkend="reserved-formats" />) is a YUV 4:2:0, not 4:2:2 format.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 2.6.21</title> - <orderedlist> - <listitem> - <para>The <filename>videodev2.h</filename> header file is -now dual licensed under GNU General Public License version two or -later, and under a 3-clause BSD-style license.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 2.6.22</title> - <orderedlist> - <listitem> - <para>Two new field orders - <constant>V4L2_FIELD_INTERLACED_TB</constant> and - <constant>V4L2_FIELD_INTERLACED_BT</constant> were - added. See <xref linkend="v4l2-field" /> for details.</para> - </listitem> - - <listitem> - <para>Three new clipping/blending methods with a global or -straight or inverted local alpha value were added to the video overlay -interface. See the description of the &VIDIOC-G-FBUF; and -&VIDIOC-S-FBUF; ioctls for details.</para> - <para>A new <structfield>global_alpha</structfield> field -was added to <link -linkend="v4l2-window"><structname>v4l2_window</structname></link>, -extending the structure. This may <emphasis>break -compatibility</emphasis> with applications using a struct -<structname>v4l2_window</structname> directly. However the <link -linkend="vidioc-g-fmt">VIDIOC_G/S/TRY_FMT</link> ioctls, which take a -pointer to a <link linkend="v4l2-format">v4l2_format</link> parent -structure with padding bytes at the end, are not affected.</para> - </listitem> - - <listitem> - <para>The format of the <structfield>chromakey</structfield> -field in &v4l2-window; changed from "host order RGB32" to a pixel -value in the same format as the framebuffer. This may <emphasis>break -compatibility</emphasis> with existing applications. Drivers -supporting the "host order RGB32" format are not known.</para> - </listitem> - - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 2.6.24</title> - <orderedlist> - <listitem> - <para>The pixel formats -<constant>V4L2_PIX_FMT_PAL8</constant>, -<constant>V4L2_PIX_FMT_YUV444</constant>, -<constant>V4L2_PIX_FMT_YUV555</constant>, -<constant>V4L2_PIX_FMT_YUV565</constant> and -<constant>V4L2_PIX_FMT_YUV32</constant> were added.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 2.6.25</title> - <orderedlist> - <listitem> - <para>The pixel formats <link linkend="V4L2-PIX-FMT-Y16"> -<constant>V4L2_PIX_FMT_Y16</constant></link> and <link -linkend="V4L2-PIX-FMT-SBGGR16"> -<constant>V4L2_PIX_FMT_SBGGR16</constant></link> were added.</para> - </listitem> - <listitem> - <para>New <link linkend="control">controls</link> -<constant>V4L2_CID_POWER_LINE_FREQUENCY</constant>, -<constant>V4L2_CID_HUE_AUTO</constant>, -<constant>V4L2_CID_WHITE_BALANCE_TEMPERATURE</constant>, -<constant>V4L2_CID_SHARPNESS</constant> and -<constant>V4L2_CID_BACKLIGHT_COMPENSATION</constant> were added. The -controls <constant>V4L2_CID_BLACK_LEVEL</constant>, -<constant>V4L2_CID_WHITENESS</constant>, -<constant>V4L2_CID_HCENTER</constant> and -<constant>V4L2_CID_VCENTER</constant> were deprecated. -</para> - </listitem> - <listitem> - <para>A <link linkend="camera-controls">Camera controls -class</link> was added, with the new controls -<constant>V4L2_CID_EXPOSURE_AUTO</constant>, -<constant>V4L2_CID_EXPOSURE_ABSOLUTE</constant>, -<constant>V4L2_CID_EXPOSURE_AUTO_PRIORITY</constant>, -<constant>V4L2_CID_PAN_RELATIVE</constant>, -<constant>V4L2_CID_TILT_RELATIVE</constant>, -<constant>V4L2_CID_PAN_RESET</constant>, -<constant>V4L2_CID_TILT_RESET</constant>, -<constant>V4L2_CID_PAN_ABSOLUTE</constant>, -<constant>V4L2_CID_TILT_ABSOLUTE</constant>, -<constant>V4L2_CID_FOCUS_ABSOLUTE</constant>, -<constant>V4L2_CID_FOCUS_RELATIVE</constant> and -<constant>V4L2_CID_FOCUS_AUTO</constant>.</para> - </listitem> - <listitem> - <para>The <constant>VIDIOC_G_MPEGCOMP</constant> and -<constant>VIDIOC_S_MPEGCOMP</constant> ioctls, which were superseded -by the <link linkend="extended-controls">extended controls</link> -interface in Linux 2.6.18, where finally removed from the -<filename>videodev2.h</filename> header file.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 2.6.26</title> - <orderedlist> - <listitem> - <para>The pixel formats -<constant>V4L2_PIX_FMT_Y16</constant> and -<constant>V4L2_PIX_FMT_SBGGR16</constant> were added.</para> - </listitem> - <listitem> - <para>Added user controls -<constant>V4L2_CID_CHROMA_AGC</constant> and -<constant>V4L2_CID_COLOR_KILLER</constant>.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 2.6.27</title> - <orderedlist> - <listitem> - <para>The &VIDIOC-S-HW-FREQ-SEEK; ioctl and the -<constant>V4L2_CAP_HW_FREQ_SEEK</constant> capability were added.</para> - </listitem> - <listitem> - <para>The pixel formats -<constant>V4L2_PIX_FMT_YVYU</constant>, -<constant>V4L2_PIX_FMT_PCA501</constant>, -<constant>V4L2_PIX_FMT_PCA505</constant>, -<constant>V4L2_PIX_FMT_PCA508</constant>, -<constant>V4L2_PIX_FMT_PCA561</constant>, -<constant>V4L2_PIX_FMT_SGBRG8</constant>, -<constant>V4L2_PIX_FMT_PAC207</constant> and -<constant>V4L2_PIX_FMT_PJPG</constant> were added.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 2.6.28</title> - <orderedlist> - <listitem> - <para>Added <constant>V4L2_MPEG_AUDIO_ENCODING_AAC</constant> and -<constant>V4L2_MPEG_AUDIO_ENCODING_AC3</constant> MPEG audio encodings.</para> - </listitem> - <listitem> - <para>Added <constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC</constant> MPEG -video encoding.</para> - </listitem> - <listitem> - <para>The pixel formats -<constant>V4L2_PIX_FMT_SGRBG10</constant> and -<constant>V4L2_PIX_FMT_SGRBG10DPCM8</constant> were added.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 2.6.29</title> - <orderedlist> - <listitem> - <para>The <constant>VIDIOC_G_CHIP_IDENT</constant> ioctl was renamed -to <constant>VIDIOC_G_CHIP_IDENT_OLD</constant> and <constant>VIDIOC_DBG_G_CHIP_IDENT</constant> -was introduced in its place. The old struct <structname>v4l2_chip_ident</structname> -was renamed to <structname id="v4l2-chip-ident-old">v4l2_chip_ident_old</structname>.</para> - </listitem> - <listitem> - <para>The pixel formats -<constant>V4L2_PIX_FMT_VYUY</constant>, -<constant>V4L2_PIX_FMT_NV16</constant> and -<constant>V4L2_PIX_FMT_NV61</constant> were added.</para> - </listitem> - <listitem> - <para>Added camera controls -<constant>V4L2_CID_ZOOM_ABSOLUTE</constant>, -<constant>V4L2_CID_ZOOM_RELATIVE</constant>, -<constant>V4L2_CID_ZOOM_CONTINUOUS</constant> and -<constant>V4L2_CID_PRIVACY</constant>.</para> - </listitem> - </orderedlist> - </section> - <section> - <title>V4L2 in Linux 2.6.30</title> - <orderedlist> - <listitem> - <para>New control flag <constant>V4L2_CTRL_FLAG_WRITE_ONLY</constant> was added.</para> - </listitem> - <listitem> - <para>New control <constant>V4L2_CID_COLORFX</constant> was added.</para> - </listitem> - </orderedlist> - </section> - <section> - <title>V4L2 in Linux 2.6.32</title> - <orderedlist> - <listitem> - <para>In order to be easier to compare a V4L2 API and a kernel -version, now V4L2 API is numbered using the Linux Kernel version numeration.</para> - </listitem> - <listitem> - <para>Finalized the RDS capture API. See <xref linkend="rds" /> for -more information.</para> - </listitem> - <listitem> - <para>Added new capabilities for modulators and RDS encoders.</para> - </listitem> - <listitem> - <para>Add description for libv4l API.</para> - </listitem> - <listitem> - <para>Added support for string controls via new type <constant>V4L2_CTRL_TYPE_STRING</constant>.</para> - </listitem> - <listitem> - <para>Added <constant>V4L2_CID_BAND_STOP_FILTER</constant> documentation.</para> - </listitem> - <listitem> - <para>Added FM Modulator (FM TX) Extended Control Class: <constant>V4L2_CTRL_CLASS_FM_TX</constant> and their Control IDs.</para> - </listitem> -<listitem> - <para>Added FM Receiver (FM RX) Extended Control Class: <constant>V4L2_CTRL_CLASS_FM_RX</constant> and their Control IDs.</para> - </listitem> - <listitem> - <para>Added Remote Controller chapter, describing the default Remote Controller mapping for media devices.</para> - </listitem> - </orderedlist> - </section> - <section> - <title>V4L2 in Linux 2.6.33</title> - <orderedlist> - <listitem> - <para>Added support for Digital Video timings in order to support HDTV receivers and transmitters.</para> - </listitem> - </orderedlist> - </section> - <section> - <title>V4L2 in Linux 2.6.34</title> - <orderedlist> - <listitem> - <para>Added -<constant>V4L2_CID_IRIS_ABSOLUTE</constant> and -<constant>V4L2_CID_IRIS_RELATIVE</constant> controls to the - <link linkend="camera-controls">Camera controls class</link>. - </para> - </listitem> - </orderedlist> - </section> - <section> - <title>V4L2 in Linux 2.6.37</title> - <orderedlist> - <listitem> - <para>Remove the vtx (videotext/teletext) API. This API was no longer -used and no hardware exists to verify the API. Nor were any userspace applications found -that used it. It was originally scheduled for removal in 2.6.35. - </para> - </listitem> - </orderedlist> - </section> - <section> - <title>V4L2 in Linux 2.6.39</title> - <orderedlist> - <listitem> - <para>The old VIDIOC_*_OLD symbols and V4L1 support were removed.</para> - </listitem> - <listitem> - <para>Multi-planar API added. Does not affect the compatibility of - current drivers and applications. See - <link linkend="planar-apis">multi-planar API</link> - for details.</para> - </listitem> - </orderedlist> - </section> - <section> - <title>V4L2 in Linux 3.1</title> - <orderedlist> - <listitem> - <para>VIDIOC_QUERYCAP now returns a per-subsystem version instead of a per-driver one.</para> - <para>Standardize an error code for invalid ioctl.</para> - <para>Added V4L2_CTRL_TYPE_BITMASK.</para> - </listitem> - </orderedlist> - </section> - <section> - <title>V4L2 in Linux 3.2</title> - <orderedlist> - <listitem> - <para>V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to userspace.</para> - </listitem> - <listitem> - <para>Add selection API for extended control over cropping - and composing. Does not affect the compatibility of current - drivers and applications. See <link - linkend="selection-api"> selection API </link> for - details.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 3.3</title> - <orderedlist> - <listitem> - <para>Added <constant>V4L2_CID_ALPHA_COMPONENT</constant> control - to the <link linkend="control">User controls class</link>. - </para> - </listitem> - <listitem> - <para>Added the device_caps field to struct v4l2_capabilities and added the new - V4L2_CAP_DEVICE_CAPS capability.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 3.4</title> - <orderedlist> - <listitem> - <para>Added <link linkend="jpeg-controls">JPEG compression control - class</link>.</para> - </listitem> - <listitem> - <para>Extended the DV Timings API: - &VIDIOC-ENUM-DV-TIMINGS;, &VIDIOC-QUERY-DV-TIMINGS; and - &VIDIOC-DV-TIMINGS-CAP;.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 3.5</title> - <orderedlist> - <listitem> - <para>Added integer menus, the new type will be - V4L2_CTRL_TYPE_INTEGER_MENU.</para> - </listitem> - <listitem> - <para>Added selection API for V4L2 subdev interface: - &VIDIOC-SUBDEV-G-SELECTION; and - &VIDIOC-SUBDEV-S-SELECTION;.</para> - </listitem> - <listitem> - <para> Added <constant>V4L2_COLORFX_ANTIQUE</constant>, - <constant>V4L2_COLORFX_ART_FREEZE</constant>, - <constant>V4L2_COLORFX_AQUA</constant>, - <constant>V4L2_COLORFX_SILHOUETTE</constant>, - <constant>V4L2_COLORFX_SOLARIZATION</constant>, - <constant>V4L2_COLORFX_VIVID</constant> and - <constant>V4L2_COLORFX_ARBITRARY_CBCR</constant> menu items - to the <constant>V4L2_CID_COLORFX</constant> control.</para> - </listitem> - <listitem> - <para> Added <constant>V4L2_CID_COLORFX_CBCR</constant> control.</para> - </listitem> - <listitem> - <para> Added camera controls <constant>V4L2_CID_AUTO_EXPOSURE_BIAS</constant>, - <constant>V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE</constant>, - <constant>V4L2_CID_IMAGE_STABILIZATION</constant>, - <constant>V4L2_CID_ISO_SENSITIVITY</constant>, - <constant>V4L2_CID_ISO_SENSITIVITY_AUTO</constant>, - <constant>V4L2_CID_EXPOSURE_METERING</constant>, - <constant>V4L2_CID_SCENE_MODE</constant>, - <constant>V4L2_CID_3A_LOCK</constant>, - <constant>V4L2_CID_AUTO_FOCUS_START</constant>, - <constant>V4L2_CID_AUTO_FOCUS_STOP</constant>, - <constant>V4L2_CID_AUTO_FOCUS_STATUS</constant> and - <constant>V4L2_CID_AUTO_FOCUS_RANGE</constant>. - </para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 3.6</title> - <orderedlist> - <listitem> - <para>Replaced <structfield>input</structfield> in - <structname>v4l2_buffer</structname> by - <structfield>reserved2</structfield> and removed - <constant>V4L2_BUF_FLAG_INPUT</constant>.</para> - </listitem> - <listitem> - <para>Added V4L2_CAP_VIDEO_M2M and V4L2_CAP_VIDEO_M2M_MPLANE capabilities.</para> - </listitem> - <listitem> - <para>Added support for frequency band enumerations: &VIDIOC-ENUM-FREQ-BANDS;.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 3.9</title> - <orderedlist> - <listitem> - <para>Added timestamp types to - <structfield>flags</structfield> field in - <structname>v4l2_buffer</structname>. See <xref - linkend="buffer-flags" />.</para> - </listitem> - <listitem> - <para>Added <constant>V4L2_EVENT_CTRL_CH_RANGE</constant> control event - changes flag. See <xref linkend="ctrl-changes-flags"/>.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 3.10</title> - <orderedlist> - <listitem> - <para>Removed obsolete and unused DV_PRESET ioctls - VIDIOC_G_DV_PRESET, VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and - VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output capability - flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS. - </para> - </listitem> - <listitem> - <para>Added new debugging ioctl &VIDIOC-DBG-G-CHIP-INFO;. - </para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 3.11</title> - <orderedlist> - <listitem> - <para>Remove obsolete <constant>VIDIOC_DBG_G_CHIP_IDENT</constant> ioctl. - </para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 3.14</title> - <orderedlist> - <listitem> - <para> In struct <structname>v4l2_rect</structname>, the type -of <structfield>width</structfield> and <structfield>height</structfield> -fields changed from _s32 to _u32. - </para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 3.15</title> - <orderedlist> - <listitem> - <para>Added Software Defined Radio (SDR) Interface. - </para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 3.16</title> - <orderedlist> - <listitem> - <para>Added event V4L2_EVENT_SOURCE_CHANGE. - </para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 3.17</title> - <orderedlist> - <listitem> - <para>Extended &v4l2-pix-format;. Added format flags. - </para> - </listitem> - <listitem> - <para>Added compound control types and &VIDIOC-QUERY-EXT-CTRL;. - </para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 3.18</title> - <orderedlist> - <listitem> - <para>Added <constant>V4L2_CID_PAN_SPEED</constant> and - <constant>V4L2_CID_TILT_SPEED</constant> camera controls.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 3.19</title> - <orderedlist> - <listitem> - <para>Rewrote Colorspace chapter, added new &v4l2-ycbcr-encoding; -and &v4l2-quantization; fields to &v4l2-pix-format;, &v4l2-pix-format-mplane; -and &v4l2-mbus-framefmt;. - </para> - </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 4.4</title> - <orderedlist> - <listitem> - <para>Renamed <constant>V4L2_TUNER_ADC</constant> to -<constant>V4L2_TUNER_SDR</constant>. The use of -<constant>V4L2_TUNER_ADC</constant> is deprecated now. - </para> - </listitem> - <listitem> - <para>Added <constant>V4L2_CID_RF_TUNER_RF_GAIN</constant> -RF Tuner control.</para> - </listitem> - <listitem> - <para>Added transmitter support for Software Defined Radio (SDR) -Interface.</para> - </listitem> - </orderedlist> - </section> - - <section id="other"> - <title>Relation of V4L2 to other Linux multimedia APIs</title> - - <section id="xvideo"> - <title>X Video Extension</title> - - <para>The X Video Extension (abbreviated XVideo or just Xv) is -an extension of the X Window system, implemented for example by the -XFree86 project. Its scope is similar to V4L2, an API to video capture -and output devices for X clients. Xv allows applications to display -live video in a window, send window contents to a TV output, and -capture or output still images in XPixmaps<footnote> - <para>This is not implemented in XFree86.</para> - </footnote>. With their implementation XFree86 makes the -extension available across many operating systems and -architectures.</para> - - <para>Because the driver is embedded into the X server Xv has a -number of advantages over the V4L2 <link linkend="overlay">video -overlay interface</link>. The driver can easily determine the overlay -target, &ie; visible graphics memory or off-screen buffers for a -destructive overlay. It can program the RAMDAC for a non-destructive -overlay, scaling or color-keying, or the clipping functions of the -video capture hardware, always in sync with drawing operations or -windows moving or changing their stacking order.</para> - - <para>To combine the advantages of Xv and V4L a special Xv -driver exists in XFree86 and XOrg, just programming any overlay capable -Video4Linux device it finds. To enable it -<filename>/etc/X11/XF86Config</filename> must contain these lines:</para> - <para><screen> -Section "Module" - Load "v4l" -EndSection</screen></para> - - <para>As of XFree86 4.2 this driver still supports only V4L -ioctls, however it should work just fine with all V4L2 devices through -the V4L2 backward-compatibility layer. Since V4L2 permits multiple -opens it is possible (if supported by the V4L2 driver) to capture -video while an X client requested video overlay. Restrictions of -simultaneous capturing and overlay are discussed in <xref - linkend="overlay" /> apply.</para> - - <para>Only marginally related to V4L2, XFree86 extended Xv to -support hardware YUV to RGB conversion and scaling for faster video -playback, and added an interface to MPEG-2 decoding hardware. This API -is useful to display images captured with V4L2 devices.</para> - </section> - - <section> - <title>Digital Video</title> - - <para>V4L2 does not support digital terrestrial, cable or -satellite broadcast. A separate project aiming at digital receivers -exists. You can find its homepage at <ulink -url="https://linuxtv.org">https://linuxtv.org</ulink>. The Linux DVB API -has no connection to the V4L2 API except that drivers for hybrid -hardware may support both.</para> - </section> - - <section> - <title>Audio Interfaces</title> - - <para>[to do - OSS/ALSA]</para> - </section> - </section> - - <section id="experimental"> - <title>Experimental API Elements</title> - - <para>The following V4L2 API elements are currently experimental -and may change in the future.</para> - - <itemizedlist> - <listitem> - <para>Video Output Overlay (OSD) Interface, <xref - linkend="osd" />.</para> - </listitem> - <listitem> - <para>&VIDIOC-DBG-G-REGISTER; and &VIDIOC-DBG-S-REGISTER; -ioctls.</para> - </listitem> - <listitem> - <para>&VIDIOC-DBG-G-CHIP-INFO; ioctl.</para> - </listitem> - <listitem> - <para>&VIDIOC-ENUM-DV-TIMINGS;, &VIDIOC-QUERY-DV-TIMINGS; and - &VIDIOC-DV-TIMINGS-CAP; ioctls.</para> - </listitem> - <listitem> - <para>Flash API. <xref linkend="flash-controls" /></para> - </listitem> - <listitem> - <para>&VIDIOC-CREATE-BUFS; and &VIDIOC-PREPARE-BUF; ioctls.</para> - </listitem> - <listitem> - <para>Selection API. <xref linkend="selection-api" /></para> - </listitem> - <listitem> - <para>Sub-device selection API: &VIDIOC-SUBDEV-G-SELECTION; - and &VIDIOC-SUBDEV-S-SELECTION; ioctls.</para> - </listitem> - <listitem> - <para>Support for frequency band enumeration: &VIDIOC-ENUM-FREQ-BANDS; ioctl.</para> - </listitem> - <listitem> - <para>Vendor and device specific media bus pixel formats. - <xref linkend="v4l2-mbus-vendor-spec-fmts" />.</para> - </listitem> - <listitem> - <para>Importing DMABUF file descriptors as a new IO method described - in <xref linkend="dmabuf" />.</para> - </listitem> - <listitem> - <para>Exporting DMABUF files using &VIDIOC-EXPBUF; ioctl.</para> - </listitem> - <listitem> - <para>Software Defined Radio (SDR) Interface, <xref linkend="sdr" />.</para> - </listitem> - </itemizedlist> - </section> - - <section id="obsolete"> - <title>Obsolete API Elements</title> - - <para>The following V4L2 API elements were superseded by new -interfaces and should not be implemented in new drivers.</para> - - <itemizedlist> - <listitem> - <para><constant>VIDIOC_G_MPEGCOMP</constant> and -<constant>VIDIOC_S_MPEGCOMP</constant> ioctls. Use Extended Controls, -<xref linkend="extended-controls" />.</para> - </listitem> - <listitem> - <para>VIDIOC_G_DV_PRESET, VIDIOC_S_DV_PRESET, VIDIOC_ENUM_DV_PRESETS and - VIDIOC_QUERY_DV_PRESET ioctls. Use the DV Timings API (<xref linkend="dv-timings" />).</para> - </listitem> - <listitem> - <para><constant>VIDIOC_SUBDEV_G_CROP</constant> and - <constant>VIDIOC_SUBDEV_S_CROP</constant> ioctls. Use - <constant>VIDIOC_SUBDEV_G_SELECTION</constant> and - <constant>VIDIOC_SUBDEV_S_SELECTION</constant>, <xref - linkend="vidioc-subdev-g-selection" />.</para> - </listitem> - </itemizedlist> - </section> - </section> diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml deleted file mode 100644 index f13a429093f1..000000000000 --- a/Documentation/DocBook/media/v4l/controls.xml +++ /dev/null @@ -1,5478 +0,0 @@ - <section id="control"> - <title>User Controls</title> - - <para>Devices typically have a number of user-settable controls -such as brightness, saturation and so on, which would be presented to -the user on a graphical user interface. But, different devices -will have different controls available, and furthermore, the range of -possible values, and the default value will vary from device to -device. The control ioctls provide the information and a mechanism to -create a nice user interface for these controls that will work -correctly with any device.</para> - - <para>All controls are accessed using an ID value. V4L2 defines -several IDs for specific purposes. Drivers can also implement their -own custom controls using <constant>V4L2_CID_PRIVATE_BASE</constant> -<footnote><para>The use of <constant>V4L2_CID_PRIVATE_BASE</constant> -is problematic because different drivers may use the same -<constant>V4L2_CID_PRIVATE_BASE</constant> ID for different controls. -This makes it hard to programatically set such controls since the meaning -of the control with that ID is driver dependent. In order to resolve this -drivers use unique IDs and the <constant>V4L2_CID_PRIVATE_BASE</constant> -IDs are mapped to those unique IDs by the kernel. Consider these -<constant>V4L2_CID_PRIVATE_BASE</constant> IDs as aliases to the real -IDs.</para> -<para>Many applications today still use the <constant>V4L2_CID_PRIVATE_BASE</constant> -IDs instead of using &VIDIOC-QUERYCTRL; with the <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> -flag to enumerate all IDs, so support for <constant>V4L2_CID_PRIVATE_BASE</constant> -is still around.</para></footnote> -and higher values. The pre-defined control IDs have the prefix -<constant>V4L2_CID_</constant>, and are listed in <xref -linkend="control-id" />. The ID is used when querying the attributes of -a control, and when getting or setting the current value.</para> - - <para>Generally applications should present controls to the user -without assumptions about their purpose. Each control comes with a -name string the user is supposed to understand. When the purpose is -non-intuitive the driver writer should provide a user manual, a user -interface plug-in or a driver specific panel application. Predefined -IDs were introduced to change a few controls programmatically, for -example to mute a device during a channel switch.</para> - - <para>Drivers may enumerate different controls after switching -the current video input or output, tuner or modulator, or audio input -or output. Different in the sense of other bounds, another default and -current value, step size or other menu items. A control with a certain -<emphasis>custom</emphasis> ID can also change name and -type.</para> - - <para>If a control is not applicable to the current configuration -of the device (for example, it doesn't apply to the current video input) -drivers set the <constant>V4L2_CTRL_FLAG_INACTIVE</constant> flag.</para> - - <para>Control values are stored globally, they do not -change when switching except to stay within the reported bounds. They -also do not change ⪚ when the device is opened or closed, when the -tuner radio frequency is changed or generally never without -application request.</para> - - <para>V4L2 specifies an event mechanism to notify applications -when controls change value (see &VIDIOC-SUBSCRIBE-EVENT;, event -<constant>V4L2_EVENT_CTRL</constant>), panel applications might want to make -use of that in order to always reflect the correct control value.</para> - - <para> - All controls use machine endianness. - </para> - - <table pgwide="1" frame="none" id="control-id"> - <title>Control IDs</title> - <tgroup cols="3"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Type</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry><constant>V4L2_CID_BASE</constant></entry> - <entry></entry> - <entry>First predefined ID, equal to -<constant>V4L2_CID_BRIGHTNESS</constant>.</entry> - </row> - <row> - <entry><constant>V4L2_CID_USER_BASE</constant></entry> - <entry></entry> - <entry>Synonym of <constant>V4L2_CID_BASE</constant>.</entry> - </row> - <row> - <entry><constant>V4L2_CID_BRIGHTNESS</constant></entry> - <entry>integer</entry> - <entry>Picture brightness, or more precisely, the black -level.</entry> - </row> - <row> - <entry><constant>V4L2_CID_CONTRAST</constant></entry> - <entry>integer</entry> - <entry>Picture contrast or luma gain.</entry> - </row> - <row> - <entry><constant>V4L2_CID_SATURATION</constant></entry> - <entry>integer</entry> - <entry>Picture color saturation or chroma gain.</entry> - </row> - <row> - <entry><constant>V4L2_CID_HUE</constant></entry> - <entry>integer</entry> - <entry>Hue or color balance.</entry> - </row> - <row> - <entry><constant>V4L2_CID_AUDIO_VOLUME</constant></entry> - <entry>integer</entry> - <entry>Overall audio volume. Note some drivers also -provide an OSS or ALSA mixer interface.</entry> - </row> - <row> - <entry><constant>V4L2_CID_AUDIO_BALANCE</constant></entry> - <entry>integer</entry> - <entry>Audio stereo balance. Minimum corresponds to all -the way left, maximum to right.</entry> - </row> - <row> - <entry><constant>V4L2_CID_AUDIO_BASS</constant></entry> - <entry>integer</entry> - <entry>Audio bass adjustment.</entry> - </row> - <row> - <entry><constant>V4L2_CID_AUDIO_TREBLE</constant></entry> - <entry>integer</entry> - <entry>Audio treble adjustment.</entry> - </row> - <row> - <entry><constant>V4L2_CID_AUDIO_MUTE</constant></entry> - <entry>boolean</entry> - <entry>Mute audio, &ie; set the volume to zero, however -without affecting <constant>V4L2_CID_AUDIO_VOLUME</constant>. Like -ALSA drivers, V4L2 drivers must mute at load time to avoid excessive -noise. Actually the entire device should be reset to a low power -consumption state.</entry> - </row> - <row> - <entry><constant>V4L2_CID_AUDIO_LOUDNESS</constant></entry> - <entry>boolean</entry> - <entry>Loudness mode (bass boost).</entry> - </row> - <row> - <entry><constant>V4L2_CID_BLACK_LEVEL</constant></entry> - <entry>integer</entry> - <entry>Another name for brightness (not a synonym of -<constant>V4L2_CID_BRIGHTNESS</constant>). This control is deprecated -and should not be used in new drivers and applications.</entry> - </row> - <row> - <entry><constant>V4L2_CID_AUTO_WHITE_BALANCE</constant></entry> - <entry>boolean</entry> - <entry>Automatic white balance (cameras).</entry> - </row> - <row> - <entry><constant>V4L2_CID_DO_WHITE_BALANCE</constant></entry> - <entry>button</entry> - <entry>This is an action control. When set (the value is -ignored), the device will do a white balance and then hold the current -setting. Contrast this with the boolean -<constant>V4L2_CID_AUTO_WHITE_BALANCE</constant>, which, when -activated, keeps adjusting the white balance.</entry> - </row> - <row> - <entry><constant>V4L2_CID_RED_BALANCE</constant></entry> - <entry>integer</entry> - <entry>Red chroma balance.</entry> - </row> - <row> - <entry><constant>V4L2_CID_BLUE_BALANCE</constant></entry> - <entry>integer</entry> - <entry>Blue chroma balance.</entry> - </row> - <row> - <entry><constant>V4L2_CID_GAMMA</constant></entry> - <entry>integer</entry> - <entry>Gamma adjust.</entry> - </row> - <row> - <entry><constant>V4L2_CID_WHITENESS</constant></entry> - <entry>integer</entry> - <entry>Whiteness for grey-scale devices. This is a synonym -for <constant>V4L2_CID_GAMMA</constant>. This control is deprecated -and should not be used in new drivers and applications.</entry> - </row> - <row> - <entry><constant>V4L2_CID_EXPOSURE</constant></entry> - <entry>integer</entry> - <entry>Exposure (cameras). [Unit?]</entry> - </row> - <row> - <entry><constant>V4L2_CID_AUTOGAIN</constant></entry> - <entry>boolean</entry> - <entry>Automatic gain/exposure control.</entry> - </row> - <row> - <entry><constant>V4L2_CID_GAIN</constant></entry> - <entry>integer</entry> - <entry>Gain control.</entry> - </row> - <row> - <entry><constant>V4L2_CID_HFLIP</constant></entry> - <entry>boolean</entry> - <entry>Mirror the picture horizontally.</entry> - </row> - <row> - <entry><constant>V4L2_CID_VFLIP</constant></entry> - <entry>boolean</entry> - <entry>Mirror the picture vertically.</entry> - </row> - <row id="v4l2-power-line-frequency"> - <entry><constant>V4L2_CID_POWER_LINE_FREQUENCY</constant></entry> - <entry>enum</entry> - <entry>Enables a power line frequency filter to avoid -flicker. Possible values for <constant>enum v4l2_power_line_frequency</constant> are: -<constant>V4L2_CID_POWER_LINE_FREQUENCY_DISABLED</constant> (0), -<constant>V4L2_CID_POWER_LINE_FREQUENCY_50HZ</constant> (1), -<constant>V4L2_CID_POWER_LINE_FREQUENCY_60HZ</constant> (2) and -<constant>V4L2_CID_POWER_LINE_FREQUENCY_AUTO</constant> (3).</entry> - </row> - <row> - <entry><constant>V4L2_CID_HUE_AUTO</constant></entry> - <entry>boolean</entry> - <entry>Enables automatic hue control by the device. The -effect of setting <constant>V4L2_CID_HUE</constant> while automatic -hue control is enabled is undefined, drivers should ignore such -request.</entry> - </row> - <row> - <entry><constant>V4L2_CID_WHITE_BALANCE_TEMPERATURE</constant></entry> - <entry>integer</entry> - <entry>This control specifies the white balance settings -as a color temperature in Kelvin. A driver should have a minimum of -2800 (incandescent) to 6500 (daylight). For more information about -color temperature see <ulink -url="http://en.wikipedia.org/wiki/Color_temperature">Wikipedia</ulink>.</entry> - </row> - <row> - <entry><constant>V4L2_CID_SHARPNESS</constant></entry> - <entry>integer</entry> - <entry>Adjusts the sharpness filters in a camera. The -minimum value disables the filters, higher values give a sharper -picture.</entry> - </row> - <row> - <entry><constant>V4L2_CID_BACKLIGHT_COMPENSATION</constant></entry> - <entry>integer</entry> - <entry>Adjusts the backlight compensation in a camera. The -minimum value disables backlight compensation.</entry> - </row> - <row> - <entry><constant>V4L2_CID_CHROMA_AGC</constant></entry> - <entry>boolean</entry> - <entry>Chroma automatic gain control.</entry> - </row> - <row> - <entry><constant>V4L2_CID_CHROMA_GAIN</constant></entry> - <entry>integer</entry> - <entry>Adjusts the Chroma gain control (for use when chroma AGC - is disabled).</entry> - </row> - <row> - <entry><constant>V4L2_CID_COLOR_KILLER</constant></entry> - <entry>boolean</entry> - <entry>Enable the color killer (&ie; force a black & white image in case of a weak video signal).</entry> - </row> - <row id="v4l2-colorfx"> - <entry><constant>V4L2_CID_COLORFX</constant></entry> - <entry>enum</entry> - <entry>Selects a color effect. The following values are defined: - </entry> - </row><row> - <entry></entry> - <entry></entry> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_COLORFX_NONE</constant> </entry> - <entry>Color effect is disabled.</entry> - </row> - <row> - <entry><constant>V4L2_COLORFX_ANTIQUE</constant> </entry> - <entry>An aging (old photo) effect.</entry> - </row> - <row> - <entry><constant>V4L2_COLORFX_ART_FREEZE</constant> </entry> - <entry>Frost color effect.</entry> - </row> - <row> - <entry><constant>V4L2_COLORFX_AQUA</constant> </entry> - <entry>Water color, cool tone.</entry> - </row> - <row> - <entry><constant>V4L2_COLORFX_BW</constant> </entry> - <entry>Black and white.</entry> - </row> - <row> - <entry><constant>V4L2_COLORFX_EMBOSS</constant> </entry> - <entry>Emboss, the highlights and shadows replace light/dark boundaries - and low contrast areas are set to a gray background.</entry> - </row> - <row> - <entry><constant>V4L2_COLORFX_GRASS_GREEN</constant> </entry> - <entry>Grass green.</entry> - </row> - <row> - <entry><constant>V4L2_COLORFX_NEGATIVE</constant> </entry> - <entry>Negative.</entry> - </row> - <row> - <entry><constant>V4L2_COLORFX_SEPIA</constant> </entry> - <entry>Sepia tone.</entry> - </row> - <row> - <entry><constant>V4L2_COLORFX_SKETCH</constant> </entry> - <entry>Sketch.</entry> - </row> - <row> - <entry><constant>V4L2_COLORFX_SKIN_WHITEN</constant> </entry> - <entry>Skin whiten.</entry> - </row> - <row> - <entry><constant>V4L2_COLORFX_SKY_BLUE</constant> </entry> - <entry>Sky blue.</entry> - </row> - <row> - <entry><constant>V4L2_COLORFX_SOLARIZATION</constant> </entry> - <entry>Solarization, the image is partially reversed in tone, - only color values above or below a certain threshold are inverted. - </entry> - </row> - <row> - <entry><constant>V4L2_COLORFX_SILHOUETTE</constant> </entry> - <entry>Silhouette (outline).</entry> - </row> - <row> - <entry><constant>V4L2_COLORFX_VIVID</constant> </entry> - <entry>Vivid colors.</entry> - </row> - <row> - <entry><constant>V4L2_COLORFX_SET_CBCR</constant> </entry> - <entry>The Cb and Cr chroma components are replaced by fixed - coefficients determined by <constant>V4L2_CID_COLORFX_CBCR</constant> - control.</entry> - </row> - </tbody> - </entrytbl> - </row> - <row> - <entry><constant>V4L2_CID_COLORFX_CBCR</constant></entry> - <entry>integer</entry> - <entry>Determines the Cb and Cr coefficients for <constant>V4L2_COLORFX_SET_CBCR</constant> - color effect. Bits [7:0] of the supplied 32 bit value are interpreted as - Cr component, bits [15:8] as Cb component and bits [31:16] must be zero. - </entry> - </row> - <row> - <entry><constant>V4L2_CID_AUTOBRIGHTNESS</constant></entry> - <entry>boolean</entry> - <entry>Enable Automatic Brightness.</entry> - </row> - <row> - <entry><constant>V4L2_CID_ROTATE</constant></entry> - <entry>integer</entry> - <entry>Rotates the image by specified angle. Common angles are 90, - 270 and 180. Rotating the image to 90 and 270 will reverse the height - and width of the display window. It is necessary to set the new height and - width of the picture using the &VIDIOC-S-FMT; ioctl according to - the rotation angle selected.</entry> - </row> - <row> - <entry><constant>V4L2_CID_BG_COLOR</constant></entry> - <entry>integer</entry> - <entry>Sets the background color on the current output device. - Background color needs to be specified in the RGB24 format. The - supplied 32 bit value is interpreted as bits 0-7 Red color information, - bits 8-15 Green color information, bits 16-23 Blue color - information and bits 24-31 must be zero.</entry> - </row> - <row> - <entry><constant>V4L2_CID_ILLUMINATORS_1</constant> - <constant>V4L2_CID_ILLUMINATORS_2</constant></entry> - <entry>boolean</entry> - <entry>Switch on or off the illuminator 1 or 2 of the device - (usually a microscope).</entry> - </row> - <row> - <entry><constant>V4L2_CID_MIN_BUFFERS_FOR_CAPTURE</constant></entry> - <entry>integer</entry> - <entry>This is a read-only control that can be read by the application -and used as a hint to determine the number of CAPTURE buffers to pass to REQBUFS. -The value is the minimum number of CAPTURE buffers that is necessary for hardware -to work.</entry> - </row> - <row> - <entry><constant>V4L2_CID_MIN_BUFFERS_FOR_OUTPUT</constant></entry> - <entry>integer</entry> - <entry>This is a read-only control that can be read by the application -and used as a hint to determine the number of OUTPUT buffers to pass to REQBUFS. -The value is the minimum number of OUTPUT buffers that is necessary for hardware -to work.</entry> - </row> - <row id="v4l2-alpha-component"> - <entry><constant>V4L2_CID_ALPHA_COMPONENT</constant></entry> - <entry>integer</entry> - <entry>Sets the alpha color component. When a capture device (or - capture queue of a mem-to-mem device) produces a frame format that - includes an alpha component - (e.g. <link linkend="rgb-formats">packed RGB image formats</link>) - and the alpha value is not defined by the device or the mem-to-mem - input data this control lets you select the alpha component value of - all pixels. When an output device (or output queue of a mem-to-mem - device) consumes a frame format that doesn't include an alpha - component and the device supports alpha channel processing this - control lets you set the alpha component value of all pixels for - further processing in the device. - </entry> - </row> - <row> - <entry><constant>V4L2_CID_LASTP1</constant></entry> - <entry></entry> - <entry>End of the predefined control IDs (currently - <constant>V4L2_CID_ALPHA_COMPONENT</constant> + 1).</entry> - </row> - <row> - <entry><constant>V4L2_CID_PRIVATE_BASE</constant></entry> - <entry></entry> - <entry>ID of the first custom (driver specific) control. -Applications depending on particular custom controls should check the -driver name and version, see <xref linkend="querycap" />.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>Applications can enumerate the available controls with the -&VIDIOC-QUERYCTRL; and &VIDIOC-QUERYMENU; ioctls, get and set a -control value with the &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls. -Drivers must implement <constant>VIDIOC_QUERYCTRL</constant>, -<constant>VIDIOC_G_CTRL</constant> and -<constant>VIDIOC_S_CTRL</constant> when the device has one or more -controls, <constant>VIDIOC_QUERYMENU</constant> when it has one or -more menu type controls.</para> - - <example id="enum_all_controls"> - <title>Enumerating all user controls</title> - - <programlisting> -&v4l2-queryctrl; queryctrl; -&v4l2-querymenu; querymenu; - -static void enumerate_menu(void) -{ - printf(" Menu items:\n"); - - memset(&querymenu, 0, sizeof(querymenu)); - querymenu.id = queryctrl.id; - - for (querymenu.index = queryctrl.minimum; - querymenu.index <= queryctrl.maximum; - querymenu.index++) { - if (0 == ioctl(fd, &VIDIOC-QUERYMENU;, &querymenu)) { - printf(" %s\n", querymenu.name); - } - } -} - -memset(&queryctrl, 0, sizeof(queryctrl)); - -for (queryctrl.id = V4L2_CID_BASE; - queryctrl.id < V4L2_CID_LASTP1; - queryctrl.id++) { - if (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &queryctrl)) { - if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) - continue; - - printf("Control %s\n", queryctrl.name); - - if (queryctrl.type == V4L2_CTRL_TYPE_MENU) - enumerate_menu(); - } else { - if (errno == EINVAL) - continue; - - perror("VIDIOC_QUERYCTRL"); - exit(EXIT_FAILURE); - } -} - -for (queryctrl.id = V4L2_CID_PRIVATE_BASE;; - queryctrl.id++) { - if (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &queryctrl)) { - if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) - continue; - - printf("Control %s\n", queryctrl.name); - - if (queryctrl.type == V4L2_CTRL_TYPE_MENU) - enumerate_menu(); - } else { - if (errno == EINVAL) - break; - - perror("VIDIOC_QUERYCTRL"); - exit(EXIT_FAILURE); - } -} -</programlisting> - </example> - - <example> - <title>Enumerating all user controls (alternative)</title> - <programlisting> -memset(&queryctrl, 0, sizeof(queryctrl)); - -queryctrl.id = V4L2_CTRL_CLASS_USER | V4L2_CTRL_FLAG_NEXT_CTRL; -while (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &queryctrl)) { - if (V4L2_CTRL_ID2CLASS(queryctrl.id) != V4L2_CTRL_CLASS_USER) - break; - if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) - continue; - - printf("Control %s\n", queryctrl.name); - - if (queryctrl.type == V4L2_CTRL_TYPE_MENU) - enumerate_menu(); - - queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; -} -if (errno != EINVAL) { - perror("VIDIOC_QUERYCTRL"); - exit(EXIT_FAILURE); -} -</programlisting> - </example> - - <example> - <title>Changing controls</title> - - <programlisting> -&v4l2-queryctrl; queryctrl; -&v4l2-control; control; - -memset(&queryctrl, 0, sizeof(queryctrl)); -queryctrl.id = V4L2_CID_BRIGHTNESS; - -if (-1 == ioctl(fd, &VIDIOC-QUERYCTRL;, &queryctrl)) { - if (errno != EINVAL) { - perror("VIDIOC_QUERYCTRL"); - exit(EXIT_FAILURE); - } else { - printf("V4L2_CID_BRIGHTNESS is not supported\n"); - } -} else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) { - printf("V4L2_CID_BRIGHTNESS is not supported\n"); -} else { - memset(&control, 0, sizeof (control)); - control.id = V4L2_CID_BRIGHTNESS; - control.value = queryctrl.default_value; - - if (-1 == ioctl(fd, &VIDIOC-S-CTRL;, &control)) { - perror("VIDIOC_S_CTRL"); - exit(EXIT_FAILURE); - } -} - -memset(&control, 0, sizeof(control)); -control.id = V4L2_CID_CONTRAST; - -if (0 == ioctl(fd, &VIDIOC-G-CTRL;, &control)) { - control.value += 1; - - /* The driver may clamp the value or return ERANGE, ignored here */ - - if (-1 == ioctl(fd, &VIDIOC-S-CTRL;, &control) - && errno != ERANGE) { - perror("VIDIOC_S_CTRL"); - exit(EXIT_FAILURE); - } -/* Ignore if V4L2_CID_CONTRAST is unsupported */ -} else if (errno != EINVAL) { - perror("VIDIOC_G_CTRL"); - exit(EXIT_FAILURE); -} - -control.id = V4L2_CID_AUDIO_MUTE; -control.value = 1; /* silence */ - -/* Errors ignored */ -ioctl(fd, VIDIOC_S_CTRL, &control); -</programlisting> - </example> - </section> - - <section id="extended-controls"> - <title>Extended Controls</title> - - <section> - <title>Introduction</title> - - <para>The control mechanism as originally designed was meant -to be used for user settings (brightness, saturation, etc). However, -it turned out to be a very useful model for implementing more -complicated driver APIs where each driver implements only a subset of -a larger API.</para> - - <para>The MPEG encoding API was the driving force behind -designing and implementing this extended control mechanism: the MPEG -standard is quite large and the currently supported hardware MPEG -encoders each only implement a subset of this standard. Further more, -many parameters relating to how the video is encoded into an MPEG -stream are specific to the MPEG encoding chip since the MPEG standard -only defines the format of the resulting MPEG stream, not how the -video is actually encoded into that format.</para> - - <para>Unfortunately, the original control API lacked some -features needed for these new uses and so it was extended into the -(not terribly originally named) extended control API.</para> - - <para>Even though the MPEG encoding API was the first effort -to use the Extended Control API, nowadays there are also other classes -of Extended Controls, such as Camera Controls and FM Transmitter Controls. -The Extended Controls API as well as all Extended Controls classes are -described in the following text.</para> - </section> - - <section> - <title>The Extended Control API</title> - - <para>Three new ioctls are available: &VIDIOC-G-EXT-CTRLS;, -&VIDIOC-S-EXT-CTRLS; and &VIDIOC-TRY-EXT-CTRLS;. These ioctls act on -arrays of controls (as opposed to the &VIDIOC-G-CTRL; and -&VIDIOC-S-CTRL; ioctls that act on a single control). This is needed -since it is often required to atomically change several controls at -once.</para> - - <para>Each of the new ioctls expects a pointer to a -&v4l2-ext-controls;. This structure contains a pointer to the control -array, a count of the number of controls in that array and a control -class. Control classes are used to group similar controls into a -single class. For example, control class -<constant>V4L2_CTRL_CLASS_USER</constant> contains all user controls -(&ie; all controls that can also be set using the old -<constant>VIDIOC_S_CTRL</constant> ioctl). Control class -<constant>V4L2_CTRL_CLASS_MPEG</constant> contains all controls -relating to MPEG encoding, etc.</para> - - <para>All controls in the control array must belong to the -specified control class. An error is returned if this is not the -case.</para> - - <para>It is also possible to use an empty control array (count -== 0) to check whether the specified control class is -supported.</para> - - <para>The control array is a &v4l2-ext-control; array. The -<structname>v4l2_ext_control</structname> structure is very similar to -&v4l2-control;, except for the fact that it also allows for 64-bit -values and pointers to be passed.</para> - - <para>Since the &v4l2-ext-control; supports pointers it is now -also possible to have controls with compound types such as N-dimensional arrays -and/or structures. You need to specify the <constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant> -when enumerating controls to actually be able to see such compound controls. -In other words, these controls with compound types should only be used -programmatically.</para> - - <para>Since such compound controls need to expose more information -about themselves than is possible with &VIDIOC-QUERYCTRL; the -&VIDIOC-QUERY-EXT-CTRL; ioctl was added. In particular, this ioctl gives -the dimensions of the N-dimensional array if this control consists of more than -one element.</para> - - <para>It is important to realize that due to the flexibility of -controls it is necessary to check whether the control you want to set -actually is supported in the driver and what the valid range of values -is. So use the &VIDIOC-QUERYCTRL; (or &VIDIOC-QUERY-EXT-CTRL;) and -&VIDIOC-QUERYMENU; ioctls to check this. Also note that it is possible -that some of the menu indices in a control of type -<constant>V4L2_CTRL_TYPE_MENU</constant> may not be supported -(<constant>VIDIOC_QUERYMENU</constant> will return an error). A good -example is the list of supported MPEG audio bitrates. Some drivers only -support one or two bitrates, others support a wider range.</para> - - <para> - All controls use machine endianness. - </para> - </section> - - <section> - <title>Enumerating Extended Controls</title> - - <para>The recommended way to enumerate over the extended -controls is by using &VIDIOC-QUERYCTRL; in combination with the -<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> flag:</para> - - <informalexample> - <programlisting> -&v4l2-queryctrl; qctrl; - -qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL; -while (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &qctrl)) { - /* ... */ - qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; -} -</programlisting> - </informalexample> - - <para>The initial control ID is set to 0 ORed with the -<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> flag. The -<constant>VIDIOC_QUERYCTRL</constant> ioctl will return the first -control with a higher ID than the specified one. When no such controls -are found an error is returned.</para> - - <para>If you want to get all controls within a specific control -class, then you can set the initial -<structfield>qctrl.id</structfield> value to the control class and add -an extra check to break out of the loop when a control of another -control class is found:</para> - - <informalexample> - <programlisting> -qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL; -while (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &qctrl)) { - if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_MPEG) - break; - /* ... */ - qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; -} -</programlisting> - </informalexample> - - <para>The 32-bit <structfield>qctrl.id</structfield> value is -subdivided into three bit ranges: the top 4 bits are reserved for -flags (⪚ <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>) and are not -actually part of the ID. The remaining 28 bits form the control ID, of -which the most significant 12 bits define the control class and the -least significant 16 bits identify the control within the control -class. It is guaranteed that these last 16 bits are always non-zero -for controls. The range of 0x1000 and up are reserved for -driver-specific controls. The macro -<constant>V4L2_CTRL_ID2CLASS(id)</constant> returns the control class -ID based on a control ID.</para> - - <para>If the driver does not support extended controls, then -<constant>VIDIOC_QUERYCTRL</constant> will fail when used in -combination with <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>. In -that case the old method of enumerating control should be used (see -<xref linkend="enum_all_controls" />). But if it is supported, then it is guaranteed to enumerate over -all controls, including driver-private controls.</para> - </section> - - <section> - <title>Creating Control Panels</title> - - <para>It is possible to create control panels for a graphical -user interface where the user can select the various controls. -Basically you will have to iterate over all controls using the method -described above. Each control class starts with a control of type -<constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant>. -<constant>VIDIOC_QUERYCTRL</constant> will return the name of this -control class which can be used as the title of a tab page within a -control panel.</para> - - <para>The flags field of &v4l2-queryctrl; also contains hints on -the behavior of the control. See the &VIDIOC-QUERYCTRL; documentation -for more details.</para> - </section> - - <section id="mpeg-controls"> - <title>Codec Control Reference</title> - - <para>Below all controls within the Codec control class are -described. First the generic controls, then controls specific for -certain hardware.</para> - - <para>Note: These controls are applicable to all codecs and -not just MPEG. The defines are prefixed with V4L2_CID_MPEG/V4L2_MPEG -as the controls were originally made for MPEG codecs and later -extended to cover all encoding formats.</para> - - <section> - <title>Generic Codec Controls</title> - - <table pgwide="1" frame="none" id="mpeg-control-id"> - <title>Codec Control IDs</title> - <tgroup cols="4"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="6*" /> - <colspec colname="c3" colwidth="2*" /> - <colspec colname="c4" colwidth="6*" /> - <spanspec namest="c1" nameend="c2" spanname="id" /> - <spanspec namest="c2" nameend="c4" spanname="descr" /> - <thead> - <row> - <entry spanname="id" align="left">ID</entry> - <entry align="left">Type</entry> - </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry> - </row> - </thead> - <tbody valign="top"> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_CLASS</constant> </entry> - <entry>class</entry> - </row><row><entry spanname="descr">The Codec class -descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a -description of this control class. This description can be used as the -caption of a Tab page in a GUI, for example.</entry> - </row> - <row><entry></entry></row> - <row id="v4l2-mpeg-stream-type"> - <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_TYPE</constant> </entry> - <entry>enum v4l2_mpeg_stream_type</entry> - </row><row><entry spanname="descr">The MPEG-1, -2 or -4 -output stream type. One cannot assume anything here. Each hardware -MPEG encoder tends to support different subsets of the available MPEG -stream types. This control is specific to multiplexed MPEG streams. -The currently defined stream types are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_PS</constant> </entry> - <entry>MPEG-2 program stream</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_TS</constant> </entry> - <entry>MPEG-2 transport stream</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG1_SS</constant> </entry> - <entry>MPEG-1 system stream</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_DVD</constant> </entry> - <entry>MPEG-2 DVD-compatible stream</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG1_VCD</constant> </entry> - <entry>MPEG-1 VCD-compatible stream</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_SVCD</constant> </entry> - <entry>MPEG-2 SVCD-compatible stream</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_PMT</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">Program Map Table -Packet ID for the MPEG transport stream (default 16)</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_AUDIO</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">Audio Packet ID for -the MPEG transport stream (default 256)</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_VIDEO</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">Video Packet ID for -the MPEG transport stream (default 260)</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_PCR</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">Packet ID for the -MPEG transport stream carrying PCR fields (default 259)</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PES_ID_AUDIO</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">Audio ID for MPEG -PES</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PES_ID_VIDEO</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">Video ID for MPEG -PES</entry> - </row> - <row><entry></entry></row> - <row id="v4l2-mpeg-stream-vbi-fmt"> - <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_VBI_FMT</constant> </entry> - <entry>enum v4l2_mpeg_stream_vbi_fmt</entry> - </row><row><entry spanname="descr">Some cards can embed -VBI data (⪚ Closed Caption, Teletext) into the MPEG stream. This -control selects whether VBI data should be embedded, and if so, what -embedding method should be used. The list of possible VBI formats -depends on the driver. The currently defined VBI format types -are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_STREAM_VBI_FMT_NONE</constant> </entry> - <entry>No VBI in the MPEG stream</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant> </entry> - <entry>VBI in private packets, IVTV format (documented -in the kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.vbi</filename>)</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row id="v4l2-mpeg-audio-sampling-freq"> - <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ</constant> </entry> - <entry>enum v4l2_mpeg_audio_sampling_freq</entry> - </row><row><entry spanname="descr">MPEG Audio sampling -frequency. Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100</constant> </entry> - <entry>44.1 kHz</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000</constant> </entry> - <entry>48 kHz</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000</constant> </entry> - <entry>32 kHz</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row id="v4l2-mpeg-audio-encoding"> - <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_ENCODING</constant> </entry> - <entry>enum v4l2_mpeg_audio_encoding</entry> - </row><row><entry spanname="descr">MPEG Audio encoding. -This control is specific to multiplexed MPEG streams. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_1</constant> </entry> - <entry>MPEG-1/2 Layer I encoding</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_2</constant> </entry> - <entry>MPEG-1/2 Layer II encoding</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_3</constant> </entry> - <entry>MPEG-1/2 Layer III encoding</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_ENCODING_AAC</constant> </entry> - <entry>MPEG-2/4 AAC (Advanced Audio Coding)</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_ENCODING_AC3</constant> </entry> - <entry>AC-3 aka ATSC A/52 encoding</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row id="v4l2-mpeg-audio-l1-bitrate"> - <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L1_BITRATE</constant> </entry> - <entry>enum v4l2_mpeg_audio_l1_bitrate</entry> - </row><row><entry spanname="descr">MPEG-1/2 Layer I bitrate. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_32K</constant> </entry> - <entry>32 kbit/s</entry></row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_64K</constant> </entry> - <entry>64 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_96K</constant> </entry> - <entry>96 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_128K</constant> </entry> - <entry>128 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_160K</constant> </entry> - <entry>160 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_192K</constant> </entry> - <entry>192 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_224K</constant> </entry> - <entry>224 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_256K</constant> </entry> - <entry>256 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_288K</constant> </entry> - <entry>288 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_320K</constant> </entry> - <entry>320 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_352K</constant> </entry> - <entry>352 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_384K</constant> </entry> - <entry>384 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_416K</constant> </entry> - <entry>416 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_448K</constant> </entry> - <entry>448 kbit/s</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row id="v4l2-mpeg-audio-l2-bitrate"> - <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L2_BITRATE</constant> </entry> - <entry>enum v4l2_mpeg_audio_l2_bitrate</entry> - </row><row><entry spanname="descr">MPEG-1/2 Layer II bitrate. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_32K</constant> </entry> - <entry>32 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_48K</constant> </entry> - <entry>48 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_56K</constant> </entry> - <entry>56 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_64K</constant> </entry> - <entry>64 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_80K</constant> </entry> - <entry>80 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_96K</constant> </entry> - <entry>96 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_112K</constant> </entry> - <entry>112 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_128K</constant> </entry> - <entry>128 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_160K</constant> </entry> - <entry>160 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_192K</constant> </entry> - <entry>192 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_224K</constant> </entry> - <entry>224 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_256K</constant> </entry> - <entry>256 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_320K</constant> </entry> - <entry>320 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_384K</constant> </entry> - <entry>384 kbit/s</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row id="v4l2-mpeg-audio-l3-bitrate"> - <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L3_BITRATE</constant> </entry> - <entry>enum v4l2_mpeg_audio_l3_bitrate</entry> - </row><row><entry spanname="descr">MPEG-1/2 Layer III bitrate. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_32K</constant> </entry> - <entry>32 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_40K</constant> </entry> - <entry>40 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_48K</constant> </entry> - <entry>48 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_56K</constant> </entry> - <entry>56 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_64K</constant> </entry> - <entry>64 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_80K</constant> </entry> - <entry>80 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_96K</constant> </entry> - <entry>96 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_112K</constant> </entry> - <entry>112 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_128K</constant> </entry> - <entry>128 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_160K</constant> </entry> - <entry>160 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_192K</constant> </entry> - <entry>192 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_224K</constant> </entry> - <entry>224 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_256K</constant> </entry> - <entry>256 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_320K</constant> </entry> - <entry>320 kbit/s</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_AAC_BITRATE</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">AAC bitrate in bits per second.</entry> - </row> - <row><entry></entry></row> - <row id="v4l2-mpeg-audio-ac3-bitrate"> - <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_AC3_BITRATE</constant> </entry> - <entry>enum v4l2_mpeg_audio_ac3_bitrate</entry> - </row><row><entry spanname="descr">AC-3 bitrate. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_32K</constant> </entry> - <entry>32 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_40K</constant> </entry> - <entry>40 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_48K</constant> </entry> - <entry>48 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_56K</constant> </entry> - <entry>56 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_64K</constant> </entry> - <entry>64 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_80K</constant> </entry> - <entry>80 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_96K</constant> </entry> - <entry>96 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_112K</constant> </entry> - <entry>112 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_128K</constant> </entry> - <entry>128 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_160K</constant> </entry> - <entry>160 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_192K</constant> </entry> - <entry>192 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_224K</constant> </entry> - <entry>224 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_256K</constant> </entry> - <entry>256 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_320K</constant> </entry> - <entry>320 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_384K</constant> </entry> - <entry>384 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_448K</constant> </entry> - <entry>448 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_512K</constant> </entry> - <entry>512 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_576K</constant> </entry> - <entry>576 kbit/s</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_640K</constant> </entry> - <entry>640 kbit/s</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row id="v4l2-mpeg-audio-mode"> - <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MODE</constant> </entry> - <entry>enum v4l2_mpeg_audio_mode</entry> - </row><row><entry spanname="descr">MPEG Audio mode. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_AUDIO_MODE_STEREO</constant> </entry> - <entry>Stereo</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_MODE_JOINT_STEREO</constant> </entry> - <entry>Joint Stereo</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_MODE_DUAL</constant> </entry> - <entry>Bilingual</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_MODE_MONO</constant> </entry> - <entry>Mono</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row id="v4l2-mpeg-audio-mode-extension"> - <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MODE_EXTENSION</constant> </entry> - <entry>enum v4l2_mpeg_audio_mode_extension</entry> - </row><row><entry spanname="descr">Joint Stereo -audio mode extension. In Layer I and II they indicate which subbands -are in intensity stereo. All other subbands are coded in stereo. Layer -III is not (yet) supported. Possible values -are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_4</constant> </entry> - <entry>Subbands 4-31 in intensity stereo</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_8</constant> </entry> - <entry>Subbands 8-31 in intensity stereo</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_12</constant> </entry> - <entry>Subbands 12-31 in intensity stereo</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_16</constant> </entry> - <entry>Subbands 16-31 in intensity stereo</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row id="v4l2-mpeg-audio-emphasis"> - <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_EMPHASIS</constant> </entry> - <entry>enum v4l2_mpeg_audio_emphasis</entry> - </row><row><entry spanname="descr">Audio Emphasis. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_NONE</constant> </entry> - <entry>None</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS</constant> </entry> - <entry>50/15 microsecond emphasis</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17</constant> </entry> - <entry>CCITT J.17</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row id="v4l2-mpeg-audio-crc"> - <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_CRC</constant> </entry> - <entry>enum v4l2_mpeg_audio_crc</entry> - </row><row><entry spanname="descr">CRC method. Possible -values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_AUDIO_CRC_NONE</constant> </entry> - <entry>None</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_CRC_CRC16</constant> </entry> - <entry>16 bit parity check</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MUTE</constant> </entry> - <entry>boolean</entry> - </row><row><entry spanname="descr">Mutes the audio when -capturing. This is not done by muting audio hardware, which can still -produce a slight hiss, but in the encoder itself, guaranteeing a fixed -and reproducible audio bitstream. 0 = unmuted, 1 = muted.</entry> - </row> - <row><entry></entry></row> - <row id="v4l2-mpeg-audio-dec-playback"> - <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK</constant> </entry> - <entry>enum v4l2_mpeg_audio_dec_playback</entry> - </row><row><entry spanname="descr">Determines how monolingual audio should be played back. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_AUTO</constant> </entry> - <entry>Automatically determines the best playback mode.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_STEREO</constant> </entry> - <entry>Stereo playback.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_LEFT</constant> </entry> - <entry>Left channel playback.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_RIGHT</constant> </entry> - <entry>Right channel playback.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_MONO</constant> </entry> - <entry>Mono playback.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_SWAPPED_STEREO</constant> </entry> - <entry>Stereo playback with swapped left and right channels.</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row id="v4l2-mpeg-audio-dec-multilingual-playback"> - <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK</constant> </entry> - <entry>enum v4l2_mpeg_audio_dec_playback</entry> - </row><row><entry spanname="descr">Determines how multilingual audio should be played back.</entry> - </row> - <row><entry></entry></row> - <row id="v4l2-mpeg-video-encoding"> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_ENCODING</constant> </entry> - <entry>enum v4l2_mpeg_video_encoding</entry> - </row><row><entry spanname="descr">MPEG Video encoding -method. This control is specific to multiplexed MPEG streams. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_1</constant> </entry> - <entry>MPEG-1 Video encoding</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_2</constant> </entry> - <entry>MPEG-2 Video encoding</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC</constant> </entry> - <entry>MPEG-4 AVC (H.264) Video encoding</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row id="v4l2-mpeg-video-aspect"> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_ASPECT</constant> </entry> - <entry>enum v4l2_mpeg_video_aspect</entry> - </row><row><entry spanname="descr">Video aspect. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_VIDEO_ASPECT_1x1</constant> </entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_ASPECT_4x3</constant> </entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_ASPECT_16x9</constant> </entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_ASPECT_221x100</constant> </entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_B_FRAMES</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">Number of B-Frames -(default 2)</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_GOP_SIZE</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">GOP size (default -12)</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_GOP_CLOSURE</constant> </entry> - <entry>boolean</entry> - </row><row><entry spanname="descr">GOP closure (default -1)</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_PULLDOWN</constant> </entry> - <entry>boolean</entry> - </row><row><entry spanname="descr">Enable 3:2 pulldown -(default 0)</entry> - </row> - <row><entry></entry></row> - <row id="v4l2-mpeg-video-bitrate-mode"> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE_MODE</constant> </entry> - <entry>enum v4l2_mpeg_video_bitrate_mode</entry> - </row><row><entry spanname="descr">Video bitrate mode. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_VIDEO_BITRATE_MODE_VBR</constant> </entry> - <entry>Variable bitrate</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_BITRATE_MODE_CBR</constant> </entry> - <entry>Constant bitrate</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">Video bitrate in bits -per second.</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE_PEAK</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">Peak video bitrate in -bits per second. Must be larger or equal to the average video bitrate. -It is ignored if the video bitrate mode is set to constant -bitrate.</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">For every captured -frame, skip this many subsequent frames (default 0).</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MUTE</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">"Mutes" the video to a -fixed color when capturing. This is useful for testing, to produce a -fixed video bitstream. 0 = unmuted, 1 = muted.</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MUTE_YUV</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">Sets the "mute" color -of the video. The supplied 32-bit integer is interpreted as follows (bit -0 = least significant bit):</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry>Bit 0:7</entry> - <entry>V chrominance information</entry> - </row> - <row> - <entry>Bit 8:15</entry> - <entry>U chrominance information</entry> - </row> - <row> - <entry>Bit 16:23</entry> - <entry>Y luminance information</entry> - </row> - <row> - <entry>Bit 24:31</entry> - <entry>Must be zero.</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row id="v4l2-mpeg-video-dec-pts"> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_DEC_PTS</constant> </entry> - <entry>integer64</entry> - </row><row><entry spanname="descr">This read-only control returns the -33-bit video Presentation Time Stamp as defined in ITU T-REC-H.222.0 and ISO/IEC 13818-1 of -the currently displayed frame. This is the same PTS as is used in &VIDIOC-DECODER-CMD;.</entry> - </row> - <row><entry></entry></row> - <row id="v4l2-mpeg-video-dec-frame"> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_DEC_FRAME</constant> </entry> - <entry>integer64</entry> - </row><row><entry spanname="descr">This read-only control returns the -frame counter of the frame that is currently displayed (decoded). This value is reset to 0 whenever -the decoder is started.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_DECODER_SLICE_INTERFACE</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">If enabled the decoder expects to receive a single slice per buffer, otherwise -the decoder expects a single frame in per buffer. Applicable to the decoder, all codecs. -</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_ENABLE</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">Enable writing sample aspect ratio in the Video Usability Information. -Applicable to the H264 encoder.</entry> - </row> - - <row><entry></entry></row> - <row id="v4l2-mpeg-video-h264-vui-sar-idc"> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_IDC</constant> </entry> - <entry>enum v4l2_mpeg_video_h264_vui_sar_idc</entry> - </row> - <row><entry spanname="descr">VUI sample aspect ratio indicator for H.264 encoding. The value -is defined in the table E-1 in the standard. Applicable to the H264 encoder.</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_UNSPECIFIED</constant> </entry> - <entry>Unspecified</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_1x1</constant> </entry> - <entry>1x1</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_12x11</constant> </entry> - <entry>12x11</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_10x11</constant> </entry> - <entry>10x11</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_16x11</constant> </entry> - <entry>16x11</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_40x33</constant> </entry> - <entry>40x33</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_24x11</constant> </entry> - <entry>24x11</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_20x11</constant> </entry> - <entry>20x11</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_32x11</constant> </entry> - <entry>32x11</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_80x33</constant> </entry> - <entry>80x33</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_18x11</constant> </entry> - <entry>18x11</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_15x11</constant> </entry> - <entry>15x11</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_64x33</constant> </entry> - <entry>64x33</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_160x99</constant> </entry> - <entry>160x99</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_4x3</constant> </entry> - <entry>4x3</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_3x2</constant> </entry> - <entry>3x2</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_2x1</constant> </entry> - <entry>2x1</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_EXTENDED</constant> </entry> - <entry>Extended SAR</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_WIDTH</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Extended sample aspect ratio width for H.264 VUI encoding. -Applicable to the H264 encoder.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_HEIGHT</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Extended sample aspect ratio height for H.264 VUI encoding. -Applicable to the H264 encoder.</entry> - </row> - - <row><entry></entry></row> - <row id="v4l2-mpeg-video-h264-level"> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_LEVEL</constant> </entry> - <entry>enum v4l2_mpeg_video_h264_level</entry> - </row> - <row><entry spanname="descr">The level information for the H264 video elementary stream. -Applicable to the H264 encoder. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1_0</constant> </entry> - <entry>Level 1.0</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1B</constant> </entry> - <entry>Level 1B</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1_1</constant> </entry> - <entry>Level 1.1</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1_2</constant> </entry> - <entry>Level 1.2</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1_3</constant> </entry> - <entry>Level 1.3</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_2_0</constant> </entry> - <entry>Level 2.0</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_2_1</constant> </entry> - <entry>Level 2.1</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_2_2</constant> </entry> - <entry>Level 2.2</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_3_0</constant> </entry> - <entry>Level 3.0</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_3_1</constant> </entry> - <entry>Level 3.1</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_3_2</constant> </entry> - <entry>Level 3.2</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_4_0</constant> </entry> - <entry>Level 4.0</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_4_1</constant> </entry> - <entry>Level 4.1</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_4_2</constant> </entry> - <entry>Level 4.2</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_5_0</constant> </entry> - <entry>Level 5.0</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_5_1</constant> </entry> - <entry>Level 5.1</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row><entry></entry></row> - <row id="v4l2-mpeg-video-mpeg4-level"> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_LEVEL</constant> </entry> - <entry>enum v4l2_mpeg_video_mpeg4_level</entry> - </row> - <row><entry spanname="descr">The level information for the MPEG4 elementary stream. -Applicable to the MPEG4 encoder. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_VIDEO_LEVEL_0</constant> </entry> - <entry>Level 0</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_LEVEL_0B</constant> </entry> - <entry>Level 0b</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_LEVEL_1</constant> </entry> - <entry>Level 1</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_LEVEL_2</constant> </entry> - <entry>Level 2</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_LEVEL_3</constant> </entry> - <entry>Level 3</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_LEVEL_3B</constant> </entry> - <entry>Level 3b</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_LEVEL_4</constant> </entry> - <entry>Level 4</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_LEVEL_5</constant> </entry> - <entry>Level 5</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row><entry></entry></row> - <row id="v4l2-mpeg-video-h264-profile"> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_PROFILE</constant> </entry> - <entry>enum v4l2_mpeg_video_h264_profile</entry> - </row> - <row><entry spanname="descr">The profile information for H264. -Applicable to the H264 encoder. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_BASELINE</constant> </entry> - <entry>Baseline profile</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_CONSTRAINED_BASELINE</constant> </entry> - <entry>Constrained Baseline profile</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_MAIN</constant> </entry> - <entry>Main profile</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_EXTENDED</constant> </entry> - <entry>Extended profile</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH</constant> </entry> - <entry>High profile</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10</constant> </entry> - <entry>High 10 profile</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422</constant> </entry> - <entry>High 422 profile</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_PREDICTIVE</constant> </entry> - <entry>High 444 Predictive profile</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10_INTRA</constant> </entry> - <entry>High 10 Intra profile</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422_INTRA</constant> </entry> - <entry>High 422 Intra profile</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_INTRA</constant> </entry> - <entry>High 444 Intra profile</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_CAVLC_444_INTRA</constant> </entry> - <entry>CAVLC 444 Intra profile</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_BASELINE</constant> </entry> - <entry>Scalable Baseline profile</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH</constant> </entry> - <entry>Scalable High profile</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH_INTRA</constant> </entry> - <entry>Scalable High Intra profile</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_STEREO_HIGH</constant> </entry> - <entry>Stereo High profile</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_MULTIVIEW_HIGH</constant> </entry> - <entry>Multiview High profile</entry> - </row> - - </tbody> - </entrytbl> - </row> - - <row><entry></entry></row> - <row id="v4l2-mpeg-video-mpeg4-profile"> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_PROFILE</constant> </entry> - <entry>enum v4l2_mpeg_video_mpeg4_profile</entry> - </row> - <row><entry spanname="descr">The profile information for MPEG4. -Applicable to the MPEG4 encoder. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_VIDEO_PROFILE_SIMPLE</constant> </entry> - <entry>Simple profile</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_PROFILE_ADVANCED_SIMPLE</constant> </entry> - <entry>Advanced Simple profile</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_PROFILE_CORE</constant> </entry> - <entry>Core profile</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_PROFILE_SIMPLE_SCALABLE</constant> </entry> - <entry>Simple Scalable profile</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_PROFILE_ADVANCED_CODING_EFFICIENCY</constant> </entry> - <entry></entry> - </row> - </tbody> - </entrytbl> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MAX_REF_PIC</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">The maximum number of reference pictures used for encoding. -Applicable to the encoder. -</entry> - </row> - - <row><entry></entry></row> - <row id="v4l2-mpeg-video-multi-slice-mode"> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE</constant> </entry> - <entry>enum v4l2_mpeg_video_multi_slice_mode</entry> - </row> - <row><entry spanname="descr">Determines how the encoder should handle division of frame into slices. -Applicable to the encoder. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_SINGLE</constant> </entry> - <entry>Single slice per frame.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB</constant> </entry> - <entry>Multiple slices with set maximum number of macroblocks per slice.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES</constant> </entry> - <entry>Multiple slice with set maximum size in bytes per slice.</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_MB</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">The maximum number of macroblocks in a slice. Used when -<constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE</constant> is set to <constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB</constant>. -Applicable to the encoder.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_BYTES</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">The maximum size of a slice in bytes. Used when -<constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE</constant> is set to <constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES</constant>. -Applicable to the encoder.</entry> - </row> - - <row><entry></entry></row> - <row id="v4l2-mpeg-video-h264-loop-filter-mode"> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_MODE</constant> </entry> - <entry>enum v4l2_mpeg_video_h264_loop_filter_mode</entry> - </row> - <row><entry spanname="descr">Loop filter mode for H264 encoder. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_ENABLED</constant> </entry> - <entry>Loop filter is enabled.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED</constant> </entry> - <entry>Loop filter is disabled.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED_AT_SLICE_BOUNDARY</constant> </entry> - <entry>Loop filter is disabled at the slice boundary.</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_ALPHA</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Loop filter alpha coefficient, defined in the H264 standard. -Applicable to the H264 encoder.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_BETA</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Loop filter beta coefficient, defined in the H264 standard. -Applicable to the H264 encoder.</entry> - </row> - - <row><entry></entry></row> - <row id="v4l2-mpeg-video-h264-entropy-mode"> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_ENTROPY_MODE</constant> </entry> - <entry>enum v4l2_mpeg_video_h264_entropy_mode</entry> - </row> - <row><entry spanname="descr">Entropy coding mode for H264 - CABAC/CAVALC. -Applicable to the H264 encoder. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CAVLC</constant> </entry> - <entry>Use CAVLC entropy coding.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CABAC</constant> </entry> - <entry>Use CABAC entropy coding.</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_8X8_TRANSFORM</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">Enable 8X8 transform for H264. Applicable to the H264 encoder.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_CYCLIC_INTRA_REFRESH_MB</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Cyclic intra macroblock refresh. This is the number of continuous macroblocks -refreshed every frame. Each frame a successive set of macroblocks is refreshed until the cycle completes and starts from the -top of the frame. Applicable to H264, H263 and MPEG4 encoder.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">Frame level rate control enable. -If this control is disabled then the quantization parameter for each frame type is constant and set with appropriate controls -(e.g. <constant>V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP</constant>). -If frame rate control is enabled then quantization parameter is adjusted to meet the chosen bitrate. Minimum and maximum value -for the quantization parameter can be set with appropriate controls (e.g. <constant>V4L2_CID_MPEG_VIDEO_H263_MIN_QP</constant>). -Applicable to encoders.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">Macroblock level rate control enable. -Applicable to the MPEG4 and H264 encoders.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_QPEL</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">Quarter pixel motion estimation for MPEG4. Applicable to the MPEG4 encoder.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Quantization parameter for an I frame for H263. Valid range: from 1 to 31.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_MIN_QP</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Minimum quantization parameter for H263. Valid range: from 1 to 31.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_MAX_QP</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Maximum quantization parameter for H263. Valid range: from 1 to 31.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_P_FRAME_QP</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Quantization parameter for an P frame for H263. Valid range: from 1 to 31.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_B_FRAME_QP</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Quantization parameter for an B frame for H263. Valid range: from 1 to 31.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_I_FRAME_QP</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Quantization parameter for an I frame for H264. Valid range: from 0 to 51.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_MIN_QP</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Minimum quantization parameter for H264. Valid range: from 0 to 51.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_MAX_QP</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Maximum quantization parameter for H264. Valid range: from 0 to 51.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_P_FRAME_QP</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Quantization parameter for an P frame for H264. Valid range: from 0 to 51.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_B_FRAME_QP</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Quantization parameter for an B frame for H264. Valid range: from 0 to 51.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_I_FRAME_QP</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Quantization parameter for an I frame for MPEG4. Valid range: from 1 to 31.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_MIN_QP</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Minimum quantization parameter for MPEG4. Valid range: from 1 to 31.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_MAX_QP</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Maximum quantization parameter for MPEG4. Valid range: from 1 to 31.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_P_FRAME_QP</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Quantization parameter for an P frame for MPEG4. Valid range: from 1 to 31.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_B_FRAME_QP</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Quantization parameter for an B frame for MPEG4. Valid range: from 1 to 31.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VBV_SIZE</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">The Video Buffer Verifier size in kilobytes, it is used as a limitation of frame skip. -The VBV is defined in the standard as a mean to verify that the produced stream will be successfully decoded. -The standard describes it as "Part of a hypothetical decoder that is conceptually connected to the -output of the encoder. Its purpose is to provide a constraint on the variability of the data rate that an -encoder or editing process may produce.". -Applicable to the MPEG1, MPEG2, MPEG4 encoders.</entry> - </row> - - <row><entry></entry></row> - <row id="v4l2-mpeg-video-vbv-delay"> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VBV_DELAY</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">Sets the initial delay in milliseconds for -VBV buffer control.</entry> - </row> - - <row><entry></entry></row> - <row id="v4l2-mpeg-video-hor-search-range"> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MV_H_SEARCH_RANGE</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Horizontal search range defines maximum horizontal search area in pixels -to search and match for the present Macroblock (MB) in the reference picture. This V4L2 control macro is used to set -horizontal search range for motion estimation module in video encoder.</entry> - </row> - - <row><entry></entry></row> - <row id="v4l2-mpeg-video-vert-search-range"> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MV_V_SEARCH_RANGE</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Vertical search range defines maximum vertical search area in pixels -to search and match for the present Macroblock (MB) in the reference picture. This V4L2 control macro is used to set -vertical search range for motion estimation module in video encoder.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_CPB_SIZE</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">The Coded Picture Buffer size in kilobytes, it is used as a limitation of frame skip. -The CPB is defined in the H264 standard as a mean to verify that the produced stream will be successfully decoded. -Applicable to the H264 encoder.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_I_PERIOD</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Period between I-frames in the open GOP for H264. In case of an open GOP -this is the period between two I-frames. The period between IDR (Instantaneous Decoding Refresh) frames is taken from the GOP_SIZE control. -An IDR frame, which stands for Instantaneous Decoding Refresh is an I-frame after which no prior frames are -referenced. This means that a stream can be restarted from an IDR frame without the need to store or decode any -previous frames. Applicable to the H264 encoder.</entry> - </row> - - <row><entry></entry></row> - <row id="v4l2-mpeg-video-header-mode"> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_HEADER_MODE</constant> </entry> - <entry>enum v4l2_mpeg_video_header_mode</entry> - </row> - <row><entry spanname="descr">Determines whether the header is returned as the first buffer or is -it returned together with the first frame. Applicable to encoders. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_VIDEO_HEADER_MODE_SEPARATE</constant> </entry> - <entry>The stream header is returned separately in the first buffer.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_HEADER_MODE_JOINED_WITH_1ST_FRAME</constant> </entry> - <entry>The stream header is returned together with the first encoded frame.</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_REPEAT_SEQ_HEADER</constant> </entry> - <entry>boolean</entry> - </row><row><entry spanname="descr">Repeat the video sequence headers. Repeating these -headers makes random access to the video stream easier. Applicable to the MPEG1, 2 and 4 encoder.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_DECODER_MPEG4_DEBLOCK_FILTER</constant> </entry> - <entry>boolean</entry> - </row><row><entry spanname="descr">Enabled the deblocking post processing filter for MPEG4 decoder. -Applicable to the MPEG4 decoder.</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_RES</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">vop_time_increment_resolution value for MPEG4. Applicable to the MPEG4 encoder.</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_INC</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">vop_time_increment value for MPEG4. Applicable to the MPEG4 encoder.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_SEI_FRAME_PACKING</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">Enable generation of frame packing supplemental enhancement information in the encoded bitstream. -The frame packing SEI message contains the arrangement of L and R planes for 3D viewing. Applicable to the H264 encoder.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_SEI_FP_CURRENT_FRAME_0</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">Sets current frame as frame0 in frame packing SEI. -Applicable to the H264 encoder.</entry> - </row> - - <row><entry></entry></row> - <row id="v4l2-mpeg-video-h264-sei-fp-arrangement-type"> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE</constant> </entry> - <entry>enum v4l2_mpeg_video_h264_sei_fp_arrangement_type</entry> - </row> - <row><entry spanname="descr">Frame packing arrangement type for H264 SEI. -Applicable to the H264 encoder. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_CHEKERBOARD</constant> </entry> - <entry>Pixels are alternatively from L and R.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_COLUMN</constant> </entry> - <entry>L and R are interlaced by column.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_ROW</constant> </entry> - <entry>L and R are interlaced by row.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_SIDE_BY_SIDE</constant> </entry> - <entry>L is on the left, R on the right.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TOP_BOTTOM</constant> </entry> - <entry>L is on top, R on bottom.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TEMPORAL</constant> </entry> - <entry>One view per frame.</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_FMO</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">Enables flexible macroblock ordering in the encoded bitstream. It is a technique -used for restructuring the ordering of macroblocks in pictures. Applicable to the H264 encoder.</entry> - </row> - - <row><entry></entry></row> - <row id="v4l2-mpeg-video-h264-fmo-map-type"> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_FMO_MAP_TYPE</constant> </entry> - <entry>enum v4l2_mpeg_video_h264_fmo_map_type</entry> - </row> - <row><entry spanname="descr">When using FMO, the map type divides the image in different scan patterns of macroblocks. -Applicable to the H264 encoder. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_INTERLEAVED_SLICES</constant> </entry> - <entry>Slices are interleaved one after other with macroblocks in run length order.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_SCATTERED_SLICES</constant> </entry> - <entry>Scatters the macroblocks based on a mathematical function known to both encoder and decoder.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_FOREGROUND_WITH_LEFT_OVER</constant> </entry> - <entry>Macroblocks arranged in rectangular areas or regions of interest.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_BOX_OUT</constant> </entry> - <entry>Slice groups grow in a cyclic way from centre to outwards.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_RASTER_SCAN</constant> </entry> - <entry>Slice groups grow in raster scan pattern from left to right.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_WIPE_SCAN</constant> </entry> - <entry>Slice groups grow in wipe scan pattern from top to bottom.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_EXPLICIT</constant> </entry> - <entry>User defined map type.</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_FMO_SLICE_GROUP</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Number of slice groups in FMO. -Applicable to the H264 encoder.</entry> - </row> - - <row><entry></entry></row> - <row id="v4l2-mpeg-video-h264-fmo-change-direction"> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_DIRECTION</constant> </entry> - <entry>enum v4l2_mpeg_video_h264_fmo_change_dir</entry> - </row> - <row><entry spanname="descr">Specifies a direction of the slice group change for raster and wipe maps. -Applicable to the H264 encoder. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_RIGHT</constant> </entry> - <entry>Raster scan or wipe right.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_LEFT</constant> </entry> - <entry>Reverse raster scan or wipe left.</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_RATE</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Specifies the size of the first slice group for raster and wipe map. -Applicable to the H264 encoder.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_FMO_RUN_LENGTH</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Specifies the number of consecutive macroblocks for the interleaved map. -Applicable to the H264 encoder.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_ASO</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">Enables arbitrary slice ordering in encoded bitstream. -Applicable to the H264 encoder.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_ASO_SLICE_ORDER</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">Specifies the slice order in ASO. Applicable to the H264 encoder. -The supplied 32-bit integer is interpreted as follows (bit -0 = least significant bit):</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry>Bit 0:15</entry> - <entry>Slice ID</entry> - </row> - <row> - <entry>Bit 16:32</entry> - <entry>Slice position or order</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">Enables H264 hierarchical coding. -Applicable to the H264 encoder.</entry> - </row> - - <row><entry></entry></row> - <row id="v4l2-mpeg-video-h264-hierarchical-coding-type"> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_TYPE</constant> </entry> - <entry>enum v4l2_mpeg_video_h264_hierarchical_coding_type</entry> - </row> - <row><entry spanname="descr">Specifies the hierarchical coding type. -Applicable to the H264 encoder. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_B</constant> </entry> - <entry>Hierarchical B coding.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_P</constant> </entry> - <entry>Hierarchical P coding.</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Specifies the number of hierarchical coding layers. -Applicable to the H264 encoder.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER_QP</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">Specifies a user defined QP for each layer. Applicable to the H264 encoder. -The supplied 32-bit integer is interpreted as follows (bit -0 = least significant bit):</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry>Bit 0:15</entry> - <entry>QP value</entry> - </row> - <row> - <entry>Bit 16:32</entry> - <entry>Layer number</entry> - </row> - </tbody> - </entrytbl> - </row> - - </tbody> - </tgroup> - </table> - </section> - - <section> - <title>MFC 5.1 MPEG Controls</title> - - <para>The following MPEG class controls deal with MPEG -decoding and encoding settings that are specific to the Multi Format Codec 5.1 device present -in the S5P family of SoCs by Samsung. -</para> - - <table pgwide="1" frame="none" id="mfc51-control-id"> - <title>MFC 5.1 Control IDs</title> - <tgroup cols="4"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="6*" /> - <colspec colname="c3" colwidth="2*" /> - <colspec colname="c4" colwidth="6*" /> - <spanspec namest="c1" nameend="c2" spanname="id" /> - <spanspec namest="c2" nameend="c4" spanname="descr" /> - <thead> - <row> - <entry spanname="id" align="left">ID</entry> - <entry align="left">Type</entry> - </row><row><entry spanname="descr" align="left">Description</entry> - </row> - </thead> - <tbody valign="top"> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY_ENABLE</constant> </entry> - <entry>boolean</entry> - </row><row><entry spanname="descr">If the display delay is enabled then the decoder is forced to return a -CAPTURE buffer (decoded frame) after processing a certain number of OUTPUT buffers. The delay can be set through -<constant>V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY</constant>. This feature can be used for example -for generating thumbnails of videos. Applicable to the H264 decoder. - </entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">Display delay value for H264 decoder. -The decoder is forced to return a decoded frame after the set 'display delay' number of frames. If this number is -low it may result in frames returned out of dispaly order, in addition the hardware may still be using the returned buffer -as a reference picture for subsequent frames. -</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_NUM_REF_PIC_FOR_P</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">The number of reference pictures used for encoding a P picture. -Applicable to the H264 encoder.</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_PADDING</constant> </entry> - <entry>boolean</entry> - </row><row><entry spanname="descr">Padding enable in the encoder - use a color instead of repeating border pixels. -Applicable to encoders.</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_PADDING_YUV</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">Padding color in the encoder. Applicable to encoders. The supplied 32-bit integer is interpreted as follows (bit -0 = least significant bit):</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry>Bit 0:7</entry> - <entry>V chrominance information</entry> - </row> - <row> - <entry>Bit 8:15</entry> - <entry>U chrominance information</entry> - </row> - <row> - <entry>Bit 16:23</entry> - <entry>Y luminance information</entry> - </row> - <row> - <entry>Bit 24:31</entry> - <entry>Must be zero.</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_RC_REACTION_COEFF</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">Reaction coefficient for MFC rate control. Applicable to encoders. -<para>Note 1: Valid only when the frame level RC is enabled.</para> -<para>Note 2: For tight CBR, this field must be small (ex. 2 ~ 10). -For VBR, this field must be large (ex. 100 ~ 1000).</para> -<para>Note 3: It is not recommended to use the greater number than FRAME_RATE * (10^9 / BIT_RATE).</para> -</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_DARK</constant> </entry> - <entry>boolean</entry> - </row><row><entry spanname="descr">Adaptive rate control for dark region. -Valid only when H.264 and macroblock level RC is enabled (<constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant>). -Applicable to the H264 encoder.</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_SMOOTH</constant> </entry> - <entry>boolean</entry> - </row><row><entry spanname="descr">Adaptive rate control for smooth region. -Valid only when H.264 and macroblock level RC is enabled (<constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant>). -Applicable to the H264 encoder.</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_STATIC</constant> </entry> - <entry>boolean</entry> - </row><row><entry spanname="descr">Adaptive rate control for static region. -Valid only when H.264 and macroblock level RC is enabled (<constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant>). -Applicable to the H264 encoder.</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_ACTIVITY</constant> </entry> - <entry>boolean</entry> - </row><row><entry spanname="descr">Adaptive rate control for activity region. -Valid only when H.264 and macroblock level RC is enabled (<constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant>). -Applicable to the H264 encoder.</entry> - </row> - <row><entry></entry></row> - <row id="v4l2-mpeg-mfc51-video-frame-skip-mode"> - <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE</constant> </entry> - <entry>enum v4l2_mpeg_mfc51_video_frame_skip_mode</entry> - </row> - <row><entry spanname="descr"> -Indicates in what conditions the encoder should skip frames. If encoding a frame would cause the encoded stream to be larger then -a chosen data limit then the frame will be skipped. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_MFC51_FRAME_SKIP_MODE_DISABLED</constant> </entry> - <entry>Frame skip mode is disabled.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_MFC51_FRAME_SKIP_MODE_LEVEL_LIMIT</constant> </entry> - <entry>Frame skip mode enabled and buffer limit is set by the chosen level and is defined by the standard.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_MFC51_FRAME_SKIP_MODE_BUF_LIMIT</constant> </entry> - <entry>Frame skip mode enabled and buffer limit is set by the VBV (MPEG1/2/4) or CPB (H264) buffer size control.</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_RC_FIXED_TARGET_BIT</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">Enable rate-control with fixed target bit. -If this setting is enabled, then the rate control logic of the encoder will calculate the average bitrate -for a GOP and keep it below or equal the set bitrate target. Otherwise the rate control logic calculates the -overall average bitrate for the stream and keeps it below or equal to the set bitrate. In the first case -the average bitrate for the whole stream will be smaller then the set bitrate. This is caused because the -average is calculated for smaller number of frames, on the other hand enabling this setting will ensure that -the stream will meet tight bandwidth contraints. Applicable to encoders. -</entry> - </row> - <row><entry></entry></row> - <row id="v4l2-mpeg-mfc51-video-force-frame-type"> - <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_FORCE_FRAME_TYPE</constant> </entry> - <entry>enum v4l2_mpeg_mfc51_video_force_frame_type</entry> - </row> - <row><entry spanname="descr">Force a frame type for the next queued buffer. Applicable to encoders. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_DISABLED</constant> </entry> - <entry>Forcing a specific frame type disabled.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_I_FRAME</constant> </entry> - <entry>Force an I-frame.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_NOT_CODED</constant> </entry> - <entry>Force a non-coded frame.</entry> - </row> - </tbody> - </entrytbl> - </row> - </tbody> - </tgroup> - </table> - </section> - - <section> - <title>CX2341x MPEG Controls</title> - - <para>The following MPEG class controls deal with MPEG -encoding settings that are specific to the Conexant CX23415 and -CX23416 MPEG encoding chips.</para> - - <table pgwide="1" frame="none" id="cx2341x-control-id"> - <title>CX2341x Control IDs</title> - <tgroup cols="4"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="6*" /> - <colspec colname="c3" colwidth="2*" /> - <colspec colname="c4" colwidth="6*" /> - <spanspec namest="c1" nameend="c2" spanname="id" /> - <spanspec namest="c2" nameend="c4" spanname="descr" /> - <thead> - <row> - <entry spanname="id" align="left">ID</entry> - <entry align="left">Type</entry> - </row><row><entry spanname="descr" align="left">Description</entry> - </row> - </thead> - <tbody valign="top"> - <row><entry></entry></row> - <row id="v4l2-mpeg-cx2341x-video-spatial-filter-mode"> - <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE</constant> </entry> - <entry>enum v4l2_mpeg_cx2341x_video_spatial_filter_mode</entry> - </row><row><entry spanname="descr">Sets the Spatial -Filter mode (default <constant>MANUAL</constant>). Possible values -are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_MANUAL</constant> </entry> - <entry>Choose the filter manually</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_AUTO</constant> </entry> - <entry>Choose the filter automatically</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER</constant> </entry> - <entry>integer (0-15)</entry> - </row><row><entry spanname="descr">The setting for the -Spatial Filter. 0 = off, 15 = maximum. (Default is 0.)</entry> - </row> - <row><entry></entry></row> - <row id="luma-spatial-filter-type"> - <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE</constant> </entry> - <entry>enum v4l2_mpeg_cx2341x_video_luma_spatial_filter_type</entry> - </row><row><entry spanname="descr">Select the algorithm -to use for the Luma Spatial Filter (default -<constant>1D_HOR</constant>). Possible values:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_OFF</constant> </entry> - <entry>No filter</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_HOR</constant> </entry> - <entry>One-dimensional horizontal</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_VERT</constant> </entry> - <entry>One-dimensional vertical</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_HV_SEPARABLE</constant> </entry> - <entry>Two-dimensional separable</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_SYM_NON_SEPARABLE</constant> </entry> - <entry>Two-dimensional symmetrical -non-separable</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row id="chroma-spatial-filter-type"> - <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE</constant> </entry> - <entry>enum v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type</entry> - </row><row><entry spanname="descr">Select the algorithm -for the Chroma Spatial Filter (default <constant>1D_HOR</constant>). -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_OFF</constant> </entry> - <entry>No filter</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR</constant> </entry> - <entry>One-dimensional horizontal</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row id="v4l2-mpeg-cx2341x-video-temporal-filter-mode"> - <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE</constant> </entry> - <entry>enum v4l2_mpeg_cx2341x_video_temporal_filter_mode</entry> - </row><row><entry spanname="descr">Sets the Temporal -Filter mode (default <constant>MANUAL</constant>). Possible values -are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_MANUAL</constant> </entry> - <entry>Choose the filter manually</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO</constant> </entry> - <entry>Choose the filter automatically</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER</constant> </entry> - <entry>integer (0-31)</entry> - </row><row><entry spanname="descr">The setting for the -Temporal Filter. 0 = off, 31 = maximum. (Default is 8 for full-scale -capturing and 0 for scaled capturing.)</entry> - </row> - <row><entry></entry></row> - <row id="v4l2-mpeg-cx2341x-video-median-filter-type"> - <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE</constant> </entry> - <entry>enum v4l2_mpeg_cx2341x_video_median_filter_type</entry> - </row><row><entry spanname="descr">Median Filter Type -(default <constant>OFF</constant>). Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_OFF</constant> </entry> - <entry>No filter</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR</constant> </entry> - <entry>Horizontal filter</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT</constant> </entry> - <entry>Vertical filter</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT</constant> </entry> - <entry>Horizontal and vertical filter</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG</constant> </entry> - <entry>Diagonal filter</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM</constant> </entry> - <entry>integer (0-255)</entry> - </row><row><entry spanname="descr">Threshold above which -the luminance median filter is enabled (default 0)</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_TOP</constant> </entry> - <entry>integer (0-255)</entry> - </row><row><entry spanname="descr">Threshold below which -the luminance median filter is enabled (default 255)</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_BOTTOM</constant> </entry> - <entry>integer (0-255)</entry> - </row><row><entry spanname="descr">Threshold above which -the chroma median filter is enabled (default 0)</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_TOP</constant> </entry> - <entry>integer (0-255)</entry> - </row><row><entry spanname="descr">Threshold below which -the chroma median filter is enabled (default 255)</entry> - </row> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_STREAM_INSERT_NAV_PACKETS</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">The CX2341X MPEG encoder -can insert one empty MPEG-2 PES packet into the stream between every -four video frames. The packet size is 2048 bytes, including the -packet_start_code_prefix and stream_id fields. The stream_id is 0xBF -(private stream 2). The payload consists of 0x00 bytes, to be filled -in by the application. 0 = do not insert, 1 = insert packets.</entry> - </row> - </tbody> - </tgroup> - </table> - </section> - - <section> - <title>VPX Control Reference</title> - - <para>The VPX controls include controls for encoding parameters - of VPx video codec.</para> - - <table pgwide="1" frame="none" id="vpx-control-id"> - <title>VPX Control IDs</title> - - <tgroup cols="4"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="6*" /> - <colspec colname="c3" colwidth="2*" /> - <colspec colname="c4" colwidth="6*" /> - <spanspec namest="c1" nameend="c2" spanname="id" /> - <spanspec namest="c2" nameend="c4" spanname="descr" /> - <thead> - <row> - <entry spanname="id" align="left">ID</entry> - <entry align="left">Type</entry> - </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry> - </row> - </thead> - <tbody valign="top"> - <row><entry></entry></row> - - <row><entry></entry></row> - <row id="v4l2-vpx-num-partitions"> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_NUM_PARTITIONS</constant></entry> - <entry>enum v4l2_vp8_num_partitions</entry> - </row> - <row><entry spanname="descr">The number of token partitions to use in VP8 encoder. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_1_PARTITION</constant></entry> - <entry>1 coefficient partition</entry> - </row> - <row> - <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_2_PARTITIONS</constant></entry> - <entry>2 coefficient partitions</entry> - </row> - <row> - <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_4_PARTITIONS</constant></entry> - <entry>4 coefficient partitions</entry> - </row> - <row> - <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_8_PARTITIONS</constant></entry> - <entry>8 coefficient partitions</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_IMD_DISABLE_4X4</constant></entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">Setting this prevents intra 4x4 mode in the intra mode decision.</entry> - </row> - - <row><entry></entry></row> - <row id="v4l2-vpx-num-ref-frames"> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_NUM_REF_FRAMES</constant></entry> - <entry>enum v4l2_vp8_num_ref_frames</entry> - </row> - <row><entry spanname="descr">The number of reference pictures for encoding P frames. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_1_REF_FRAME</constant></entry> - <entry>Last encoded frame will be searched</entry> - </row> - <row> - <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_2_REF_FRAME</constant></entry> - <entry>Two frames will be searched among the last encoded frame, the golden frame -and the alternate reference (altref) frame. The encoder implementation will decide which two are chosen.</entry> - </row> - <row> - <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_3_REF_FRAME</constant></entry> - <entry>The last encoded frame, the golden frame and the altref frame will be searched.</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_FILTER_LEVEL</constant></entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Indicates the loop filter level. The adjustment of the loop -filter level is done via a delta value against a baseline loop filter value.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_FILTER_SHARPNESS</constant></entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">This parameter affects the loop filter. Anything above -zero weakens the deblocking effect on the loop filter.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_REF_PERIOD</constant></entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Sets the refresh period for the golden frame. The period is defined -in number of frames. For a value of 'n', every nth frame starting from the first key frame will be taken as a golden frame. -For eg. for encoding sequence of 0, 1, 2, 3, 4, 5, 6, 7 where the golden frame refresh period is set as 4, the frames -0, 4, 8 etc will be taken as the golden frames as frame 0 is always a key frame.</entry> - </row> - - <row><entry></entry></row> - <row id="v4l2-vpx-golden-frame-sel"> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_SEL</constant></entry> - <entry>enum v4l2_vp8_golden_frame_sel</entry> - </row> - <row><entry spanname="descr">Selects the golden frame for encoding. -Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_PREV</constant></entry> - <entry>Use the (n-2)th frame as a golden frame, current frame index being 'n'.</entry> - </row> - <row> - <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_REF_PERIOD</constant></entry> - <entry>Use the previous specific frame indicated by -V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_REF_PERIOD as a golden frame.</entry> - </row> - </tbody> - </entrytbl> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_MIN_QP</constant></entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Minimum quantization parameter for VP8.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_MAX_QP</constant></entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Maximum quantization parameter for VP8.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_I_FRAME_QP</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Quantization parameter for an I frame for VP8.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_P_FRAME_QP</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Quantization parameter for a P frame for VP8.</entry> - </row> - - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_PROFILE</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Select the desired profile for VPx encoder. -Acceptable values are 0, 1, 2 and 3 corresponding to encoder profiles 0, 1, 2 and 3.</entry> - </row> - - <row><entry></entry></row> - </tbody> - </tgroup> - </table> - - </section> - </section> - - <section id="camera-controls"> - <title>Camera Control Reference</title> - - <para>The Camera class includes controls for mechanical (or -equivalent digital) features of a device such as controllable lenses -or sensors.</para> - - <table pgwide="1" frame="none" id="camera-control-id"> - <title>Camera Control IDs</title> - <tgroup cols="4"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="6*" /> - <colspec colname="c3" colwidth="2*" /> - <colspec colname="c4" colwidth="6*" /> - <spanspec namest="c1" nameend="c2" spanname="id" /> - <spanspec namest="c2" nameend="c4" spanname="descr" /> - <thead> - <row> - <entry spanname="id" align="left">ID</entry> - <entry align="left">Type</entry> - </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry> - </row> - </thead> - <tbody valign="top"> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_CAMERA_CLASS</constant> </entry> - <entry>class</entry> - </row><row><entry spanname="descr">The Camera class -descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a -description of this control class.</entry> - </row> - <row><entry></entry></row> - - <row id="v4l2-exposure-auto-type"> - <entry spanname="id"><constant>V4L2_CID_EXPOSURE_AUTO</constant> </entry> - <entry>enum v4l2_exposure_auto_type</entry> - </row><row><entry spanname="descr">Enables automatic -adjustments of the exposure time and/or iris aperture. The effect of -manual changes of the exposure time or iris aperture while these -features are enabled is undefined, drivers should ignore such -requests. Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_EXPOSURE_AUTO</constant> </entry> - <entry>Automatic exposure time, automatic iris -aperture.</entry> - </row> - <row> - <entry><constant>V4L2_EXPOSURE_MANUAL</constant> </entry> - <entry>Manual exposure time, manual iris.</entry> - </row> - <row> - <entry><constant>V4L2_EXPOSURE_SHUTTER_PRIORITY</constant> </entry> - <entry>Manual exposure time, auto iris.</entry> - </row> - <row> - <entry><constant>V4L2_EXPOSURE_APERTURE_PRIORITY</constant> </entry> - <entry>Auto exposure time, manual iris.</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - - <row> - <entry spanname="id"><constant>V4L2_CID_EXPOSURE_ABSOLUTE</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">Determines the exposure -time of the camera sensor. The exposure time is limited by the frame -interval. Drivers should interpret the values as 100 µs units, -where the value 1 stands for 1/10000th of a second, 10000 for 1 second -and 100000 for 10 seconds.</entry> - </row> - <row><entry></entry></row> - - <row> - <entry spanname="id"><constant>V4L2_CID_EXPOSURE_AUTO_PRIORITY</constant> </entry> - <entry>boolean</entry> - </row><row><entry spanname="descr">When -<constant>V4L2_CID_EXPOSURE_AUTO</constant> is set to -<constant>AUTO</constant> or <constant>APERTURE_PRIORITY</constant>, -this control determines if the device may dynamically vary the frame -rate. By default this feature is disabled (0) and the frame rate must -remain constant.</entry> - </row> - <row><entry></entry></row> - - <row> - <entry spanname="id"><constant>V4L2_CID_EXPOSURE_BIAS</constant> </entry> - <entry>integer menu</entry> - </row><row><entry spanname="descr"> Determines the automatic -exposure compensation, it is effective only when <constant>V4L2_CID_EXPOSURE_AUTO</constant> -control is set to <constant>AUTO</constant>, <constant>SHUTTER_PRIORITY </constant> -or <constant>APERTURE_PRIORITY</constant>. -It is expressed in terms of EV, drivers should interpret the values as 0.001 EV -units, where the value 1000 stands for +1 EV. -<para>Increasing the exposure compensation value is equivalent to decreasing -the exposure value (EV) and will increase the amount of light at the image -sensor. The camera performs the exposure compensation by adjusting absolute -exposure time and/or aperture.</para></entry> - </row> - <row><entry></entry></row> - - <row id="v4l2-exposure-metering"> - <entry spanname="id"><constant>V4L2_CID_EXPOSURE_METERING</constant> </entry> - <entry>enum v4l2_exposure_metering</entry> - </row><row><entry spanname="descr">Determines how the camera measures -the amount of light available for the frame exposure. Possible values are:</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_EXPOSURE_METERING_AVERAGE</constant> </entry> - <entry>Use the light information coming from the entire frame -and average giving no weighting to any particular portion of the metered area. - </entry> - </row> - <row> - <entry><constant>V4L2_EXPOSURE_METERING_CENTER_WEIGHTED</constant> </entry> - <entry>Average the light information coming from the entire frame -giving priority to the center of the metered area.</entry> - </row> - <row> - <entry><constant>V4L2_EXPOSURE_METERING_SPOT</constant> </entry> - <entry>Measure only very small area at the center of the frame.</entry> - </row> - <row> - <entry><constant>V4L2_EXPOSURE_METERING_MATRIX</constant> </entry> - <entry>A multi-zone metering. The light intensity is measured -in several points of the frame and the results are combined. The -algorithm of the zones selection and their significance in calculating the -final value is device dependent.</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - - <row> - <entry spanname="id"><constant>V4L2_CID_PAN_RELATIVE</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">This control turns the -camera horizontally by the specified amount. The unit is undefined. A -positive value moves the camera to the right (clockwise when viewed -from above), a negative value to the left. A value of zero does not -cause motion. This is a write-only control.</entry> - </row> - <row><entry></entry></row> - - <row> - <entry spanname="id"><constant>V4L2_CID_TILT_RELATIVE</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">This control turns the -camera vertically by the specified amount. The unit is undefined. A -positive value moves the camera up, a negative value down. A value of -zero does not cause motion. This is a write-only control.</entry> - </row> - <row><entry></entry></row> - - <row> - <entry spanname="id"><constant>V4L2_CID_PAN_RESET</constant> </entry> - <entry>button</entry> - </row><row><entry spanname="descr">When this control is set, -the camera moves horizontally to the default position.</entry> - </row> - <row><entry></entry></row> - - <row> - <entry spanname="id"><constant>V4L2_CID_TILT_RESET</constant> </entry> - <entry>button</entry> - </row><row><entry spanname="descr">When this control is set, -the camera moves vertically to the default position.</entry> - </row> - <row><entry></entry></row> - - <row> - <entry spanname="id"><constant>V4L2_CID_PAN_ABSOLUTE</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">This control -turns the camera horizontally to the specified position. Positive -values move the camera to the right (clockwise when viewed from above), -negative values to the left. Drivers should interpret the values as arc -seconds, with valid values between -180 * 3600 and +180 * 3600 -inclusive.</entry> - </row> - <row><entry></entry></row> - - <row> - <entry spanname="id"><constant>V4L2_CID_TILT_ABSOLUTE</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">This control -turns the camera vertically to the specified position. Positive values -move the camera up, negative values down. Drivers should interpret the -values as arc seconds, with valid values between -180 * 3600 and +180 -* 3600 inclusive.</entry> - </row> - <row><entry></entry></row> - - <row> - <entry spanname="id"><constant>V4L2_CID_FOCUS_ABSOLUTE</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">This control sets the -focal point of the camera to the specified position. The unit is -undefined. Positive values set the focus closer to the camera, -negative values towards infinity.</entry> - </row> - <row><entry></entry></row> - - <row> - <entry spanname="id"><constant>V4L2_CID_FOCUS_RELATIVE</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">This control moves the -focal point of the camera by the specified amount. The unit is -undefined. Positive values move the focus closer to the camera, -negative values towards infinity. This is a write-only control.</entry> - </row> - <row><entry></entry></row> - - <row> - <entry spanname="id"><constant>V4L2_CID_FOCUS_AUTO</constant> </entry> - <entry>boolean</entry> - </row><row><entry spanname="descr">Enables continuous automatic -focus adjustments. The effect of manual focus adjustments while this feature -is enabled is undefined, drivers should ignore such requests.</entry> - </row> - <row><entry></entry></row> - - <row> - <entry spanname="id"><constant>V4L2_CID_AUTO_FOCUS_START</constant> </entry> - <entry>button</entry> - </row><row><entry spanname="descr">Starts single auto focus process. -The effect of setting this control when <constant>V4L2_CID_FOCUS_AUTO</constant> -is set to <constant>TRUE</constant> (1) is undefined, drivers should ignore -such requests.</entry> - </row> - <row><entry></entry></row> - - <row> - <entry spanname="id"><constant>V4L2_CID_AUTO_FOCUS_STOP</constant> </entry> - <entry>button</entry> - </row><row><entry spanname="descr">Aborts automatic focusing -started with <constant>V4L2_CID_AUTO_FOCUS_START</constant> control. It is -effective only when the continuous autofocus is disabled, that is when -<constant>V4L2_CID_FOCUS_AUTO</constant> control is set to <constant>FALSE -</constant> (0).</entry> - </row> - <row><entry></entry></row> - - <row id="v4l2-auto-focus-status"> - <entry spanname="id"> - <constant>V4L2_CID_AUTO_FOCUS_STATUS</constant> </entry> - <entry>bitmask</entry> - </row> - <row><entry spanname="descr">The automatic focus status. This is a read-only - control.</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_AUTO_FOCUS_STATUS_IDLE</constant> </entry> - <entry>Automatic focus is not active.</entry> - </row> - <row> - <entry><constant>V4L2_AUTO_FOCUS_STATUS_BUSY</constant> </entry> - <entry>Automatic focusing is in progress.</entry> - </row> - <row> - <entry><constant>V4L2_AUTO_FOCUS_STATUS_REACHED</constant> </entry> - <entry>Focus has been reached.</entry> - </row> - <row> - <entry><constant>V4L2_AUTO_FOCUS_STATUS_FAILED</constant> </entry> - <entry>Automatic focus has failed, the driver will not - transition from this state until another action is - performed by an application.</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry spanname="descr"> -Setting <constant>V4L2_LOCK_FOCUS</constant> lock bit of the <constant>V4L2_CID_3A_LOCK -</constant> control may stop updates of the <constant>V4L2_CID_AUTO_FOCUS_STATUS</constant> -control value.</entry> - </row> - <row><entry></entry></row> - - <row id="v4l2-auto-focus-range"> - <entry spanname="id"> - <constant>V4L2_CID_AUTO_FOCUS_RANGE</constant> </entry> - <entry>enum v4l2_auto_focus_range</entry> - </row> - <row><entry spanname="descr">Determines auto focus distance range -for which lens may be adjusted. </entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_AUTO_FOCUS_RANGE_AUTO</constant> </entry> - <entry>The camera automatically selects the focus range.</entry> - </row> - <row> - <entry><constant>V4L2_AUTO_FOCUS_RANGE_NORMAL</constant> </entry> - <entry>Normal distance range, limited for best automatic focus -performance.</entry> - </row> - <row> - <entry><constant>V4L2_AUTO_FOCUS_RANGE_MACRO</constant> </entry> - <entry>Macro (close-up) auto focus. The camera will -use its minimum possible distance for auto focus.</entry> - </row> - <row> - <entry><constant>V4L2_AUTO_FOCUS_RANGE_INFINITY</constant> </entry> - <entry>The lens is set to focus on an object at infinite distance.</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - - <row> - <entry spanname="id"><constant>V4L2_CID_ZOOM_ABSOLUTE</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">Specify the objective lens -focal length as an absolute value. The zoom unit is driver-specific and its -value should be a positive integer.</entry> - </row> - <row><entry></entry></row> - - <row> - <entry spanname="id"><constant>V4L2_CID_ZOOM_RELATIVE</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">Specify the objective lens -focal length relatively to the current value. Positive values move the zoom -lens group towards the telephoto direction, negative values towards the -wide-angle direction. The zoom unit is driver-specific. This is a write-only control.</entry> - </row> - <row><entry></entry></row> - - <row> - <entry spanname="id"><constant>V4L2_CID_ZOOM_CONTINUOUS</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">Move the objective lens group -at the specified speed until it reaches physical device limits or until an -explicit request to stop the movement. A positive value moves the zoom lens -group towards the telephoto direction. A value of zero stops the zoom lens -group movement. A negative value moves the zoom lens group towards the -wide-angle direction. The zoom speed unit is driver-specific.</entry> - </row> - <row><entry></entry></row> - - <row> - <entry spanname="id"><constant>V4L2_CID_IRIS_ABSOLUTE</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">This control sets the -camera's aperture to the specified value. The unit is undefined. -Larger values open the iris wider, smaller values close it.</entry> - </row> - <row><entry></entry></row> - - <row> - <entry spanname="id"><constant>V4L2_CID_IRIS_RELATIVE</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">This control modifies the -camera's aperture by the specified amount. The unit is undefined. -Positive values open the iris one step further, negative values close -it one step further. This is a write-only control.</entry> - </row> - <row><entry></entry></row> - - <row> - <entry spanname="id"><constant>V4L2_CID_PRIVACY</constant> </entry> - <entry>boolean</entry> - </row><row><entry spanname="descr">Prevent video from being acquired -by the camera. When this control is set to <constant>TRUE</constant> (1), no -image can be captured by the camera. Common means to enforce privacy are -mechanical obturation of the sensor and firmware image processing, but the -device is not restricted to these methods. Devices that implement the privacy -control must support read access and may support write access.</entry> - </row> - - <row> - <entry spanname="id"><constant>V4L2_CID_BAND_STOP_FILTER</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">Switch the band-stop filter of a -camera sensor on or off, or specify its strength. Such band-stop filters can -be used, for example, to filter out the fluorescent light component.</entry> - </row> - <row><entry></entry></row> - - <row id="v4l2-auto-n-preset-white-balance"> - <entry spanname="id"><constant>V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE</constant> </entry> - <entry>enum v4l2_auto_n_preset_white_balance</entry> - </row><row><entry spanname="descr">Sets white balance to automatic, -manual or a preset. The presets determine color temperature of the light as -a hint to the camera for white balance adjustments resulting in most accurate -color representation. The following white balance presets are listed in order -of increasing color temperature.</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_WHITE_BALANCE_MANUAL</constant> </entry> - <entry>Manual white balance.</entry> - </row> - <row> - <entry><constant>V4L2_WHITE_BALANCE_AUTO</constant> </entry> - <entry>Automatic white balance adjustments.</entry> - </row> - <row> - <entry><constant>V4L2_WHITE_BALANCE_INCANDESCENT</constant> </entry> - <entry>White balance setting for incandescent (tungsten) lighting. -It generally cools down the colors and corresponds approximately to 2500...3500 K -color temperature range.</entry> - </row> - <row> - <entry><constant>V4L2_WHITE_BALANCE_FLUORESCENT</constant> </entry> - <entry>White balance preset for fluorescent lighting. -It corresponds approximately to 4000...5000 K color temperature.</entry> - </row> - <row> - <entry><constant>V4L2_WHITE_BALANCE_FLUORESCENT_H</constant> </entry> - <entry>With this setting the camera will compensate for -fluorescent H lighting.</entry> - </row> - <row> - <entry><constant>V4L2_WHITE_BALANCE_HORIZON</constant> </entry> - <entry>White balance setting for horizon daylight. -It corresponds approximately to 5000 K color temperature.</entry> - </row> - <row> - <entry><constant>V4L2_WHITE_BALANCE_DAYLIGHT</constant> </entry> - <entry>White balance preset for daylight (with clear sky). -It corresponds approximately to 5000...6500 K color temperature.</entry> - </row> - <row> - <entry><constant>V4L2_WHITE_BALANCE_FLASH</constant> </entry> - <entry>With this setting the camera will compensate for the flash -light. It slightly warms up the colors and corresponds roughly to 5000...5500 K -color temperature.</entry> - </row> - <row> - <entry><constant>V4L2_WHITE_BALANCE_CLOUDY</constant> </entry> - <entry>White balance preset for moderately overcast sky. -This option corresponds approximately to 6500...8000 K color temperature -range.</entry> - </row> - <row> - <entry><constant>V4L2_WHITE_BALANCE_SHADE</constant> </entry> - <entry>White balance preset for shade or heavily overcast -sky. It corresponds approximately to 9000...10000 K color temperature. -</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - - <row id="v4l2-wide-dynamic-range"> - <entry spanname="id"><constant>V4L2_CID_WIDE_DYNAMIC_RANGE</constant></entry> - <entry>boolean</entry> - </row> - <row> - <entry spanname="descr">Enables or disables the camera's wide dynamic -range feature. This feature allows to obtain clear images in situations where -intensity of the illumination varies significantly throughout the scene, i.e. -there are simultaneously very dark and very bright areas. It is most commonly -realized in cameras by combining two subsequent frames with different exposure -times. <footnote id="ctypeconv"><para> This control may be changed to a menu -control in the future, if more options are required.</para></footnote></entry> - </row> - <row><entry></entry></row> - - <row id="v4l2-image-stabilization"> - <entry spanname="id"><constant>V4L2_CID_IMAGE_STABILIZATION</constant></entry> - <entry>boolean</entry> - </row> - <row> - <entry spanname="descr">Enables or disables image stabilization. - <footnoteref linkend="ctypeconv"/></entry> - </row> - <row><entry></entry></row> - - <row> - <entry spanname="id"><constant>V4L2_CID_ISO_SENSITIVITY</constant> </entry> - <entry>integer menu</entry> - </row><row><entry spanname="descr">Determines ISO equivalent of an -image sensor indicating the sensor's sensitivity to light. The numbers are -expressed in arithmetic scale, as per <xref linkend="iso12232" /> standard, -where doubling the sensor sensitivity is represented by doubling the numerical -ISO value. Applications should interpret the values as standard ISO values -multiplied by 1000, e.g. control value 800 stands for ISO 0.8. Drivers will -usually support only a subset of standard ISO values. The effect of setting -this control while the <constant>V4L2_CID_ISO_SENSITIVITY_AUTO</constant> -control is set to a value other than <constant>V4L2_CID_ISO_SENSITIVITY_MANUAL -</constant> is undefined, drivers should ignore such requests.</entry> - </row> - <row><entry></entry></row> - - <row id="v4l2-iso-sensitivity-auto-type"> - <entry spanname="id"><constant>V4L2_CID_ISO_SENSITIVITY_AUTO</constant> </entry> - <entry>enum v4l2_iso_sensitivity_type</entry> - </row><row><entry spanname="descr">Enables or disables automatic ISO -sensitivity adjustments.</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_CID_ISO_SENSITIVITY_MANUAL</constant> </entry> - <entry>Manual ISO sensitivity.</entry> - </row> - <row> - <entry><constant>V4L2_CID_ISO_SENSITIVITY_AUTO</constant> </entry> - <entry>Automatic ISO sensitivity adjustments.</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - - <row id="v4l2-scene-mode"> - <entry spanname="id"><constant>V4L2_CID_SCENE_MODE</constant> </entry> - <entry>enum v4l2_scene_mode</entry> - </row><row><entry spanname="descr">This control allows to select -scene programs as the camera automatic modes optimized for common shooting -scenes. Within these modes the camera determines best exposure, aperture, -focusing, light metering, white balance and equivalent sensitivity. The -controls of those parameters are influenced by the scene mode control. -An exact behavior in each mode is subject to the camera specification. - -<para>When the scene mode feature is not used, this control should be set to -<constant>V4L2_SCENE_MODE_NONE</constant> to make sure the other possibly -related controls are accessible. The following scene programs are defined: -</para> -</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_SCENE_MODE_NONE</constant> </entry> - <entry>The scene mode feature is disabled.</entry> - </row> - <row> - <entry><constant>V4L2_SCENE_MODE_BACKLIGHT</constant> </entry> - <entry>Backlight. Compensates for dark shadows when light is - coming from behind a subject, also by automatically turning - on the flash.</entry> - </row> - <row> - <entry><constant>V4L2_SCENE_MODE_BEACH_SNOW</constant> </entry> - <entry>Beach and snow. This mode compensates for all-white or -bright scenes, which tend to look gray and low contrast, when camera's automatic -exposure is based on an average scene brightness. To compensate, this mode -automatically slightly overexposes the frames. The white balance may also be -adjusted to compensate for the fact that reflected snow looks bluish rather -than white.</entry> - </row> - <row> - <entry><constant>V4L2_SCENE_MODE_CANDLELIGHT</constant> </entry> - <entry>Candle light. The camera generally raises the ISO -sensitivity and lowers the shutter speed. This mode compensates for relatively -close subject in the scene. The flash is disabled in order to preserve the -ambiance of the light.</entry> - </row> - <row> - <entry><constant>V4L2_SCENE_MODE_DAWN_DUSK</constant> </entry> - <entry>Dawn and dusk. Preserves the colors seen in low -natural light before dusk and after down. The camera may turn off the flash, -and automatically focus at infinity. It will usually boost saturation and -lower the shutter speed.</entry> - </row> - <row> - <entry><constant>V4L2_SCENE_MODE_FALL_COLORS</constant> </entry> - <entry>Fall colors. Increases saturation and adjusts white -balance for color enhancement. Pictures of autumn leaves get saturated reds -and yellows.</entry> - </row> - <row> - <entry><constant>V4L2_SCENE_MODE_FIREWORKS</constant> </entry> - <entry>Fireworks. Long exposure times are used to capture -the expanding burst of light from a firework. The camera may invoke image -stabilization.</entry> - </row> - <row> - <entry><constant>V4L2_SCENE_MODE_LANDSCAPE</constant> </entry> - <entry>Landscape. The camera may choose a small aperture to -provide deep depth of field and long exposure duration to help capture detail -in dim light conditions. The focus is fixed at infinity. Suitable for distant -and wide scenery.</entry> - </row> - <row> - <entry><constant>V4L2_SCENE_MODE_NIGHT</constant> </entry> - <entry>Night, also known as Night Landscape. Designed for low -light conditions, it preserves detail in the dark areas without blowing out bright -objects. The camera generally sets itself to a medium-to-high ISO sensitivity, -with a relatively long exposure time, and turns flash off. As such, there will be -increased image noise and the possibility of blurred image.</entry> - </row> - <row> - <entry><constant>V4L2_SCENE_MODE_PARTY_INDOOR</constant> </entry> - <entry>Party and indoor. Designed to capture indoor scenes -that are lit by indoor background lighting as well as the flash. The camera -usually increases ISO sensitivity, and adjusts exposure for the low light -conditions.</entry> - </row> - <row> - <entry><constant>V4L2_SCENE_MODE_PORTRAIT</constant> </entry> - <entry>Portrait. The camera adjusts the aperture so that the -depth of field is reduced, which helps to isolate the subject against a smooth -background. Most cameras recognize the presence of faces in the scene and focus -on them. The color hue is adjusted to enhance skin tones. The intensity of the -flash is often reduced.</entry> - </row> - <row> - <entry><constant>V4L2_SCENE_MODE_SPORTS</constant> </entry> - <entry>Sports. Significantly increases ISO and uses a fast -shutter speed to freeze motion of rapidly-moving subjects. Increased image -noise may be seen in this mode.</entry> - </row> - <row> - <entry><constant>V4L2_SCENE_MODE_SUNSET</constant> </entry> - <entry>Sunset. Preserves deep hues seen in sunsets and -sunrises. It bumps up the saturation.</entry> - </row> - <row> - <entry><constant>V4L2_SCENE_MODE_TEXT</constant> </entry> - <entry>Text. It applies extra contrast and sharpness, it is -typically a black-and-white mode optimized for readability. Automatic focus -may be switched to close-up mode and this setting may also involve some -lens-distortion correction.</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - - <row> - <entry spanname="id"><constant>V4L2_CID_3A_LOCK</constant></entry> - <entry>bitmask</entry> - </row> - <row> - <entry spanname="descr">This control locks or unlocks the automatic -focus, exposure and white balance. The automatic adjustments can be paused -independently by setting the corresponding lock bit to 1. The camera then retains -the settings until the lock bit is cleared. The following lock bits are defined: -</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_LOCK_EXPOSURE</constant></entry> - <entry>Automatic exposure adjustments lock.</entry> - </row> - <row> - <entry><constant>V4L2_LOCK_WHITE_BALANCE</constant></entry> - <entry>Automatic white balance adjustments lock.</entry> - </row> - <row> - <entry><constant>V4L2_LOCK_FOCUS</constant></entry> - <entry>Automatic focus lock.</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry spanname="descr"> -When a given algorithm is not enabled, drivers should ignore requests -to lock it and should return no error. An example might be an application -setting bit <constant>V4L2_LOCK_WHITE_BALANCE</constant> when the -<constant>V4L2_CID_AUTO_WHITE_BALANCE</constant> control is set to -<constant>FALSE</constant>. The value of this control may be changed -by exposure, white balance or focus controls.</entry> - </row> - <row><entry></entry></row> - - <row> - <entry spanname="id"><constant>V4L2_CID_PAN_SPEED</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">This control turns the -camera horizontally at the specific speed. The unit is undefined. A -positive value moves the camera to the right (clockwise when viewed -from above), a negative value to the left. A value of zero stops the motion -if one is in progress and has no effect otherwise.</entry> - </row> - <row><entry></entry></row> - - <row> - <entry spanname="id"><constant>V4L2_CID_TILT_SPEED</constant> </entry> - <entry>integer</entry> - </row><row><entry spanname="descr">This control turns the -camera vertically at the specified speed. The unit is undefined. A -positive value moves the camera up, a negative value down. A value of zero -stops the motion if one is in progress and has no effect otherwise.</entry> - </row> - <row><entry></entry></row> - - </tbody> - </tgroup> - </table> - </section> - - <section id="fm-tx-controls"> - <title>FM Transmitter Control Reference</title> - - <para>The FM Transmitter (FM_TX) class includes controls for common features of -FM transmissions capable devices. Currently this class includes parameters for audio -compression, pilot tone generation, audio deviation limiter, RDS transmission and -tuning power features.</para> - - <table pgwide="1" frame="none" id="fm-tx-control-id"> - <title>FM_TX Control IDs</title> - - <tgroup cols="4"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="6*" /> - <colspec colname="c3" colwidth="2*" /> - <colspec colname="c4" colwidth="6*" /> - <spanspec namest="c1" nameend="c2" spanname="id" /> - <spanspec namest="c2" nameend="c4" spanname="descr" /> - <thead> - <row> - <entry spanname="id" align="left">ID</entry> - <entry align="left">Type</entry> - </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry> - </row> - </thead> - <tbody valign="top"> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_FM_TX_CLASS</constant> </entry> - <entry>class</entry> - </row><row><entry spanname="descr">The FM_TX class -descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a -description of this control class.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RDS_TX_DEVIATION</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Configures RDS signal frequency deviation level in Hz. -The range and step are driver-specific.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RDS_TX_PI</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Sets the RDS Programme Identification field -for transmission.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RDS_TX_PTY</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Sets the RDS Programme Type field for transmission. -This encodes up to 31 pre-defined programme types.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RDS_TX_PS_NAME</constant> </entry> - <entry>string</entry> - </row> - <row><entry spanname="descr">Sets the Programme Service name (PS_NAME) for transmission. -It is intended for static display on a receiver. It is the primary aid to listeners in programme service -identification and selection. In Annex E of <xref linkend="iec62106" />, the RDS specification, -there is a full description of the correct character encoding for Programme Service name strings. -Also from RDS specification, PS is usually a single eight character text. However, it is also possible -to find receivers which can scroll strings sized as 8 x N characters. So, this control must be configured -with steps of 8 characters. The result is it must always contain a string with size multiple of 8.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RDS_TX_RADIO_TEXT</constant> </entry> - <entry>string</entry> - </row> - <row><entry spanname="descr">Sets the Radio Text info for transmission. It is a textual description of -what is being broadcasted. RDS Radio Text can be applied when broadcaster wishes to transmit longer PS names, -programme-related information or any other text. In these cases, RadioText should be used in addition to -<constant>V4L2_CID_RDS_TX_PS_NAME</constant>. The encoding for Radio Text strings is also fully described -in Annex E of <xref linkend="iec62106" />. The length of Radio Text strings depends on which RDS Block is being -used to transmit it, either 32 (2A block) or 64 (2B block). However, it is also possible -to find receivers which can scroll strings sized as 32 x N or 64 x N characters. So, this control must be configured -with steps of 32 or 64 characters. The result is it must always contain a string with size multiple of 32 or 64. </entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RDS_TX_MONO_STEREO</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">Sets the Mono/Stereo bit of the Decoder Identification code. If set, -then the audio was recorded as stereo.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RDS_TX_ARTIFICIAL_HEAD</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">Sets the -<ulink url="http://en.wikipedia.org/wiki/Artificial_head">Artificial Head</ulink> bit of the Decoder -Identification code. If set, then the audio was recorded using an artificial head.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RDS_TX_COMPRESSED</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">Sets the Compressed bit of the Decoder Identification code. If set, -then the audio is compressed.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RDS_TX_DYNAMIC_PTY</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">Sets the Dynamic PTY bit of the Decoder Identification code. If set, -then the PTY code is dynamically switched.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RDS_TX_TRAFFIC_ANNOUNCEMENT</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">If set, then a traffic announcement is in progress.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RDS_TX_TRAFFIC_PROGRAM</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">If set, then the tuned programme carries traffic announcements.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RDS_TX_MUSIC_SPEECH</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">If set, then this channel broadcasts music. If cleared, then it -broadcasts speech. If the transmitter doesn't make this distinction, then it should be set.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RDS_TX_ALT_FREQS_ENABLE</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">If set, then transmit alternate frequencies.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RDS_TX_ALT_FREQS</constant> </entry> - <entry>__u32 array</entry> - </row> - <row><entry spanname="descr">The alternate frequencies in kHz units. The RDS standard allows -for up to 25 frequencies to be defined. Drivers may support fewer frequencies so check -the array size.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_ENABLED</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">Enables or disables the audio deviation limiter feature. -The limiter is useful when trying to maximize the audio volume, minimize receiver-generated -distortion and prevent overmodulation. -</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_RELEASE_TIME</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Sets the audio deviation limiter feature release time. -Unit is in useconds. Step and range are driver-specific.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_DEVIATION</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Configures audio frequency deviation level in Hz. -The range and step are driver-specific.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_ENABLED</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">Enables or disables the audio compression feature. -This feature amplifies signals below the threshold by a fixed gain and compresses audio -signals above the threshold by the ratio of Threshold/(Gain + Threshold).</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_GAIN</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Sets the gain for audio compression feature. It is -a dB value. The range and step are driver-specific.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_THRESHOLD</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Sets the threshold level for audio compression freature. -It is a dB value. The range and step are driver-specific.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Sets the attack time for audio compression feature. -It is a useconds value. The range and step are driver-specific.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Sets the release time for audio compression feature. -It is a useconds value. The range and step are driver-specific.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_ENABLED</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">Enables or disables the pilot tone generation feature.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_DEVIATION</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Configures pilot tone frequency deviation level. Unit is -in Hz. The range and step are driver-specific.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_FREQUENCY</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Configures pilot tone frequency value. Unit is -in Hz. The range and step are driver-specific.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_TUNE_PREEMPHASIS</constant> </entry> - <entry>enum v4l2_preemphasis</entry> - </row> - <row id="v4l2-preemphasis"><entry spanname="descr">Configures the pre-emphasis value for broadcasting. -A pre-emphasis filter is applied to the broadcast to accentuate the high audio frequencies. -Depending on the region, a time constant of either 50 or 75 useconds is used. The enum v4l2_preemphasis -defines possible values for pre-emphasis. Here they are:</entry> - </row><row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_PREEMPHASIS_DISABLED</constant> </entry> - <entry>No pre-emphasis is applied.</entry> - </row> - <row> - <entry><constant>V4L2_PREEMPHASIS_50_uS</constant> </entry> - <entry>A pre-emphasis of 50 uS is used.</entry> - </row> - <row> - <entry><constant>V4L2_PREEMPHASIS_75_uS</constant> </entry> - <entry>A pre-emphasis of 75 uS is used.</entry> - </row> - </tbody> - </entrytbl> - - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_TUNE_POWER_LEVEL</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Sets the output power level for signal transmission. -Unit is in dBuV. Range and step are driver-specific.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_TUNE_ANTENNA_CAPACITOR</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">This selects the value of antenna tuning capacitor -manually or automatically if set to zero. Unit, range and step are driver-specific.</entry> - </row> - <row><entry></entry></row> - </tbody> - </tgroup> - </table> - -<para>For more details about RDS specification, refer to -<xref linkend="iec62106" /> document, from CENELEC.</para> - </section> - - <section id="flash-controls"> - <title>Flash Control Reference</title> - - <note> - <title>Experimental</title> - - <para>This is an <link linkend="experimental">experimental</link> -interface and may change in the future.</para> - </note> - - <para> - The V4L2 flash controls are intended to provide generic access - to flash controller devices. Flash controller devices are - typically used in digital cameras. - </para> - - <para> - The interface can support both LED and xenon flash devices. As - of writing this, there is no xenon flash driver using this - interface. - </para> - - <section id="flash-controls-use-cases"> - <title>Supported use cases</title> - - <section> - <title>Unsynchronised LED flash (software strobe)</title> - - <para> - Unsynchronised LED flash is controlled directly by the - host as the sensor. The flash must be enabled by the host - before the exposure of the image starts and disabled once - it ends. The host is fully responsible for the timing of - the flash. - </para> - - <para>Example of such device: Nokia N900.</para> - </section> - - <section> - <title>Synchronised LED flash (hardware strobe)</title> - - <para> - The synchronised LED flash is pre-programmed by the host - (power and timeout) but controlled by the sensor through a - strobe signal from the sensor to the flash. - </para> - - <para> - The sensor controls the flash duration and timing. This - information typically must be made available to the - sensor. - </para> - - </section> - - <section> - <title>LED flash as torch</title> - - <para> - LED flash may be used as torch in conjunction with another - use case involving camera or individually. - </para> - - - <table pgwide="1" frame="none" id="flash-control-id"> - <title>Flash Control IDs</title> - - <tgroup cols="4"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="6*" /> - <colspec colname="c3" colwidth="2*" /> - <colspec colname="c4" colwidth="6*" /> - <spanspec namest="c1" nameend="c2" spanname="id" /> - <spanspec namest="c2" nameend="c4" spanname="descr" /> - <thead> - <row> - <entry spanname="id" align="left">ID</entry> - <entry align="left">Type</entry> - </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry> - </row> - </thead> - <tbody valign="top"> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_CLASS</constant></entry> - <entry>class</entry> - </row> - <row> - <entry spanname="descr">The FLASH class descriptor.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_LED_MODE</constant></entry> - <entry>menu</entry> - </row> - <row id="v4l2-flash-led-mode"> - <entry spanname="descr">Defines the mode of the flash LED, - the high-power white LED attached to the flash controller. - Setting this control may not be possible in presence of - some faults. See V4L2_CID_FLASH_FAULT.</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_FLASH_LED_MODE_NONE</constant></entry> - <entry>Off.</entry> - </row> - <row> - <entry><constant>V4L2_FLASH_LED_MODE_FLASH</constant></entry> - <entry>Flash mode.</entry> - </row> - <row> - <entry><constant>V4L2_FLASH_LED_MODE_TORCH</constant></entry> - <entry>Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY.</entry> - </row> - </tbody> - </entrytbl> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_SOURCE</constant></entry> - <entry>menu</entry> - </row> - <row id="v4l2-flash-strobe-source"><entry - spanname="descr">Defines the source of the flash LED - strobe.</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_FLASH_STROBE_SOURCE_SOFTWARE</constant></entry> - <entry>The flash strobe is triggered by using - the V4L2_CID_FLASH_STROBE control.</entry> - </row> - <row> - <entry><constant>V4L2_FLASH_STROBE_SOURCE_EXTERNAL</constant></entry> - <entry>The flash strobe is triggered by an - external source. Typically this is a sensor, - which makes it possible to synchronises the - flash strobe start to exposure start.</entry> - </row> - </tbody> - </entrytbl> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE</constant></entry> - <entry>button</entry> - </row> - <row> - <entry spanname="descr">Strobe flash. Valid when - V4L2_CID_FLASH_LED_MODE is set to - V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE - is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this - control may not be possible in presence of some faults. - See V4L2_CID_FLASH_FAULT.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_STOP</constant></entry> - <entry>button</entry> - </row> - <row><entry spanname="descr">Stop flash strobe immediately.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_STATUS</constant></entry> - <entry>boolean</entry> - </row> - <row> - <entry spanname="descr">Strobe status: whether the flash - is strobing at the moment or not. This is a read-only - control.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_TIMEOUT</constant></entry> - <entry>integer</entry> - </row> - <row> - <entry spanname="descr">Hardware timeout for flash. The - flash strobe is stopped after this period of time has - passed from the start of the strobe.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_INTENSITY</constant></entry> - <entry>integer</entry> - </row> - <row> - <entry spanname="descr">Intensity of the flash strobe when - the flash LED is in flash mode - (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps - (mA) if possible.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_TORCH_INTENSITY</constant></entry> - <entry>integer</entry> - </row> - <row> - <entry spanname="descr">Intensity of the flash LED in - torch mode (V4L2_FLASH_LED_MODE_TORCH). The unit should be - milliamps (mA) if possible. Setting this control may not - be possible in presence of some faults. See - V4L2_CID_FLASH_FAULT.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_INDICATOR_INTENSITY</constant></entry> - <entry>integer</entry> - </row> - <row> - <entry spanname="descr">Intensity of the indicator LED. - The indicator LED may be fully independent of the flash - LED. The unit should be microamps (uA) if possible.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_FAULT</constant></entry> - <entry>bitmask</entry> - </row> - <row> - <entry spanname="descr">Faults related to the flash. The - faults tell about specific problems in the flash chip - itself or the LEDs attached to it. Faults may prevent - further use of some of the flash controls. In particular, - V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE - if the fault affects the flash LED. Exactly which faults - have such an effect is chip dependent. Reading the faults - resets the control and returns the chip to a usable state - if possible.</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_FLASH_FAULT_OVER_VOLTAGE</constant></entry> - <entry>Flash controller voltage to the flash LED - has exceeded the limit specific to the flash - controller.</entry> - </row> - <row> - <entry><constant>V4L2_FLASH_FAULT_TIMEOUT</constant></entry> - <entry>The flash strobe was still on when - the timeout set by the user --- - V4L2_CID_FLASH_TIMEOUT control --- has expired. - Not all flash controllers may set this in all - such conditions.</entry> - </row> - <row> - <entry><constant>V4L2_FLASH_FAULT_OVER_TEMPERATURE</constant></entry> - <entry>The flash controller has overheated.</entry> - </row> - <row> - <entry><constant>V4L2_FLASH_FAULT_SHORT_CIRCUIT</constant></entry> - <entry>The short circuit protection of the flash - controller has been triggered.</entry> - </row> - <row> - <entry><constant>V4L2_FLASH_FAULT_OVER_CURRENT</constant></entry> - <entry>Current in the LED power supply has exceeded the limit - specific to the flash controller.</entry> - </row> - <row> - <entry><constant>V4L2_FLASH_FAULT_INDICATOR</constant></entry> - <entry>The flash controller has detected a short or open - circuit condition on the indicator LED.</entry> - </row> - <row> - <entry><constant>V4L2_FLASH_FAULT_UNDER_VOLTAGE</constant></entry> - <entry>Flash controller voltage to the flash LED - has been below the minimum limit specific to the flash - controller.</entry> - </row> - <row> - <entry><constant>V4L2_FLASH_FAULT_INPUT_VOLTAGE</constant></entry> - <entry>The input voltage of the flash controller is below - the limit under which strobing the flash at full current - will not be possible.The condition persists until this flag - is no longer set.</entry> - </row> - <row> - <entry><constant>V4L2_FLASH_FAULT_LED_OVER_TEMPERATURE</constant></entry> - <entry>The temperature of the LED has exceeded its - allowed upper limit.</entry> - </row> - </tbody> - </entrytbl> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_CHARGE</constant></entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">Enable or disable charging of the xenon - flash capacitor.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_READY</constant></entry> - <entry>boolean</entry> - </row> - <row> - <entry spanname="descr">Is the flash ready to strobe? - Xenon flashes require their capacitors charged before - strobing. LED flashes often require a cooldown period - after strobe during which another strobe will not be - possible. This is a read-only control.</entry> - </row> - <row><entry></entry></row> - </tbody> - </tgroup> - </table> - </section> - </section> - </section> - - <section id="jpeg-controls"> - <title>JPEG Control Reference</title> - <para>The JPEG class includes controls for common features of JPEG - encoders and decoders. Currently it includes features for codecs - implementing progressive baseline DCT compression process with - Huffman entrophy coding.</para> - <table pgwide="1" frame="none" id="jpeg-control-id"> - <title>JPEG Control IDs</title> - - <tgroup cols="4"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="6*" /> - <colspec colname="c3" colwidth="2*" /> - <colspec colname="c4" colwidth="6*" /> - <spanspec namest="c1" nameend="c2" spanname="id" /> - <spanspec namest="c2" nameend="c4" spanname="descr" /> - <thead> - <row> - <entry spanname="id" align="left">ID</entry> - <entry align="left">Type</entry> - </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry> - </row> - </thead> - <tbody valign="top"> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_JPEG_CLASS</constant> </entry> - <entry>class</entry> - </row><row><entry spanname="descr">The JPEG class descriptor. Calling - &VIDIOC-QUERYCTRL; for this control will return a description of this - control class. - - </entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_JPEG_CHROMA_SUBSAMPLING</constant></entry> - <entry>menu</entry> - </row> - <row id="v4l2-jpeg-chroma-subsampling"> - <entry spanname="descr">The chroma subsampling factors describe how - each component of an input image is sampled, in respect to maximum - sample rate in each spatial dimension. See <xref linkend="itu-t81"/>, - clause A.1.1. for more details. The <constant> - V4L2_CID_JPEG_CHROMA_SUBSAMPLING</constant> control determines how - Cb and Cr components are downsampled after coverting an input image - from RGB to Y'CbCr color space. - </entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_444</constant> - </entry><entry>No chroma subsampling, each pixel has - Y, Cr and Cb values.</entry> - </row> - <row> - <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_422</constant> - </entry><entry>Horizontally subsample Cr, Cb components - by a factor of 2.</entry> - </row> - <row> - <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_420</constant> - </entry><entry>Subsample Cr, Cb components horizontally - and vertically by 2.</entry> - </row> - <row> - <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_411</constant> - </entry><entry>Horizontally subsample Cr, Cb components - by a factor of 4.</entry> - </row> - <row> - <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_410</constant> - </entry><entry>Subsample Cr, Cb components horizontally - by 4 and vertically by 2.</entry> - </row> - <row> - <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_GRAY</constant> - </entry><entry>Use only luminance component.</entry> - </row> - </tbody> - </entrytbl> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_JPEG_RESTART_INTERVAL</constant> - </entry><entry>integer</entry> - </row> - <row><entry spanname="descr"> - The restart interval determines an interval of inserting RSTm - markers (m = 0..7). The purpose of these markers is to additionally - reinitialize the encoder process, in order to process blocks of - an image independently. - For the lossy compression processes the restart interval unit is - MCU (Minimum Coded Unit) and its value is contained in DRI - (Define Restart Interval) marker. If <constant> - V4L2_CID_JPEG_RESTART_INTERVAL</constant> control is set to 0, - DRI and RSTm markers will not be inserted. - </entry> - </row> - <row id="jpeg-quality-control"> - <entry spanname="id"><constant>V4L2_CID_JPEG_COMPRESSION_QUALITY</constant></entry> - <entry>integer</entry> - </row> - <row> - <entry spanname="descr"> - <constant>V4L2_CID_JPEG_COMPRESSION_QUALITY</constant> control - determines trade-off between image quality and size. - It provides simpler method for applications to control image quality, - without a need for direct reconfiguration of luminance and chrominance - quantization tables. - - In cases where a driver uses quantization tables configured directly - by an application, using interfaces defined elsewhere, <constant> - V4L2_CID_JPEG_COMPRESSION_QUALITY</constant> control should be set - by driver to 0. - - <para>The value range of this control is driver-specific. Only - positive, non-zero values are meaningful. The recommended range - is 1 - 100, where larger values correspond to better image quality. - </para> - </entry> - </row> - <row id="jpeg-active-marker-control"> - <entry spanname="id"><constant>V4L2_CID_JPEG_ACTIVE_MARKER</constant></entry> - <entry>bitmask</entry> - </row> - <row> - <entry spanname="descr">Specify which JPEG markers are included - in compressed stream. This control is valid only for encoders. - </entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_JPEG_ACTIVE_MARKER_APP0</constant></entry> - <entry>Application data segment APP<subscript>0</subscript>.</entry> - </row><row> - <entry><constant>V4L2_JPEG_ACTIVE_MARKER_APP1</constant></entry> - <entry>Application data segment APP<subscript>1</subscript>.</entry> - </row><row> - <entry><constant>V4L2_JPEG_ACTIVE_MARKER_COM</constant></entry> - <entry>Comment segment.</entry> - </row><row> - <entry><constant>V4L2_JPEG_ACTIVE_MARKER_DQT</constant></entry> - <entry>Quantization tables segment.</entry> - </row><row> - <entry><constant>V4L2_JPEG_ACTIVE_MARKER_DHT</constant></entry> - <entry>Huffman tables segment.</entry> - </row> - </tbody> - </entrytbl> - </row> - <row><entry></entry></row> - </tbody> - </tgroup> - </table> - <para>For more details about JPEG specification, refer - to <xref linkend="itu-t81"/>, <xref linkend="jfif"/>, - <xref linkend="w3c-jpeg-jfif"/>.</para> - </section> - - <section id="image-source-controls"> - <title>Image Source Control Reference</title> - - <note> - <title>Experimental</title> - - <para>This is an <link - linkend="experimental">experimental</link> interface and may - change in the future.</para> - </note> - - <para> - The Image Source control class is intended for low-level - control of image source devices such as image sensors. The - devices feature an analogue to digital converter and a bus - transmitter to transmit the image data out of the device. - </para> - - <table pgwide="1" frame="none" id="image-source-control-id"> - <title>Image Source Control IDs</title> - - <tgroup cols="4"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="6*" /> - <colspec colname="c3" colwidth="2*" /> - <colspec colname="c4" colwidth="6*" /> - <spanspec namest="c1" nameend="c2" spanname="id" /> - <spanspec namest="c2" nameend="c4" spanname="descr" /> - <thead> - <row> - <entry spanname="id" align="left">ID</entry> - <entry align="left">Type</entry> - </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry> - </row> - </thead> - <tbody valign="top"> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_IMAGE_SOURCE_CLASS</constant></entry> - <entry>class</entry> - </row> - <row> - <entry spanname="descr">The IMAGE_SOURCE class descriptor.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_VBLANK</constant></entry> - <entry>integer</entry> - </row> - <row> - <entry spanname="descr">Vertical blanking. The idle period - after every frame during which no image data is produced. - The unit of vertical blanking is a line. Every line has - length of the image width plus horizontal blanking at the - pixel rate defined by - <constant>V4L2_CID_PIXEL_RATE</constant> control in the - same sub-device.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_HBLANK</constant></entry> - <entry>integer</entry> - </row> - <row> - <entry spanname="descr">Horizontal blanking. The idle - period after every line of image data during which no - image data is produced. The unit of horizontal blanking is - pixels.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_ANALOGUE_GAIN</constant></entry> - <entry>integer</entry> - </row> - <row> - <entry spanname="descr">Analogue gain is gain affecting - all colour components in the pixel matrix. The gain - operation is performed in the analogue domain before A/D - conversion. - </entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_TEST_PATTERN_RED</constant></entry> - <entry>integer</entry> - </row> - <row> - <entry spanname="descr">Test pattern red colour component. - </entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_TEST_PATTERN_GREENR</constant></entry> - <entry>integer</entry> - </row> - <row> - <entry spanname="descr">Test pattern green (next to red) - colour component. - </entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_TEST_PATTERN_BLUE</constant></entry> - <entry>integer</entry> - </row> - <row> - <entry spanname="descr">Test pattern blue colour component. - </entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_TEST_PATTERN_GREENB</constant></entry> - <entry>integer</entry> - </row> - <row> - <entry spanname="descr">Test pattern green (next to blue) - colour component. - </entry> - </row> - <row><entry></entry></row> - </tbody> - </tgroup> - </table> - - </section> - - <section id="image-process-controls"> - <title>Image Process Control Reference</title> - - <note> - <title>Experimental</title> - - <para>This is an <link - linkend="experimental">experimental</link> interface and may - change in the future.</para> - </note> - - <para> - The Image Process control class is intended for low-level control of - image processing functions. Unlike - <constant>V4L2_CID_IMAGE_SOURCE_CLASS</constant>, the controls in - this class affect processing the image, and do not control capturing - of it. - </para> - - <table pgwide="1" frame="none" id="image-process-control-id"> - <title>Image Process Control IDs</title> - - <tgroup cols="4"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="6*" /> - <colspec colname="c3" colwidth="2*" /> - <colspec colname="c4" colwidth="6*" /> - <spanspec namest="c1" nameend="c2" spanname="id" /> - <spanspec namest="c2" nameend="c4" spanname="descr" /> - <thead> - <row> - <entry spanname="id" align="left">ID</entry> - <entry align="left">Type</entry> - </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry> - </row> - </thead> - <tbody valign="top"> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_IMAGE_PROC_CLASS</constant></entry> - <entry>class</entry> - </row> - <row> - <entry spanname="descr">The IMAGE_PROC class descriptor.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_LINK_FREQ</constant></entry> - <entry>integer menu</entry> - </row> - <row> - <entry spanname="descr">Data bus frequency. Together with the - media bus pixel code, bus type (clock cycles per sample), the - data bus frequency defines the pixel rate - (<constant>V4L2_CID_PIXEL_RATE</constant>) in the - pixel array (or possibly elsewhere, if the device is not an - image sensor). The frame rate can be calculated from the pixel - clock, image width and height and horizontal and vertical - blanking. While the pixel rate control may be defined elsewhere - than in the subdev containing the pixel array, the frame rate - cannot be obtained from that information. This is because only - on the pixel array it can be assumed that the vertical and - horizontal blanking information is exact: no other blanking is - allowed in the pixel array. The selection of frame rate is - performed by selecting the desired horizontal and vertical - blanking. The unit of this control is Hz. </entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_PIXEL_RATE</constant></entry> - <entry>64-bit integer</entry> - </row> - <row> - <entry spanname="descr">Pixel rate in the source pads of - the subdev. This control is read-only and its unit is - pixels / second. - </entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_TEST_PATTERN</constant></entry> - <entry>menu</entry> - </row> - <row id="v4l2-test-pattern"> - <entry spanname="descr"> Some capture/display/sensor devices have - the capability to generate test pattern images. These hardware - specific test patterns can be used to test if a device is working - properly.</entry> - </row> - <row><entry></entry></row> - </tbody> - </tgroup> - </table> - - </section> - - <section id="dv-controls"> - <title>Digital Video Control Reference</title> - - <note> - <title>Experimental</title> - - <para>This is an <link - linkend="experimental">experimental</link> interface and may - change in the future.</para> - </note> - - <para> - The Digital Video control class is intended to control receivers - and transmitters for <ulink url="http://en.wikipedia.org/wiki/Vga">VGA</ulink>, - <ulink url="http://en.wikipedia.org/wiki/Digital_Visual_Interface">DVI</ulink> - (Digital Visual Interface), HDMI (<xref linkend="hdmi" />) and DisplayPort (<xref linkend="dp" />). - These controls are generally expected to be private to the receiver or transmitter - subdevice that implements them, so they are only exposed on the - <filename>/dev/v4l-subdev*</filename> device node. - </para> - - <para>Note that these devices can have multiple input or output pads which are - hooked up to e.g. HDMI connectors. Even though the subdevice will receive or - transmit video from/to only one of those pads, the other pads can still be - active when it comes to EDID (Extended Display Identification Data, - <xref linkend="vesaedid" />) and HDCP (High-bandwidth Digital Content - Protection System, <xref linkend="hdcp" />) processing, allowing the device - to do the fairly slow EDID/HDCP handling in advance. This allows for quick - switching between connectors.</para> - - <para>These pads appear in several of the controls in this section as - bitmasks, one bit for each pad. Bit 0 corresponds to pad 0, bit 1 to pad 1, - etc. The maximum value of the control is the set of valid pads.</para> - - <table pgwide="1" frame="none" id="dv-control-id"> - <title>Digital Video Control IDs</title> - - <tgroup cols="4"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="6*" /> - <colspec colname="c3" colwidth="2*" /> - <colspec colname="c4" colwidth="6*" /> - <spanspec namest="c1" nameend="c2" spanname="id" /> - <spanspec namest="c2" nameend="c4" spanname="descr" /> - <thead> - <row> - <entry spanname="id" align="left">ID</entry> - <entry align="left">Type</entry> - </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry> - </row> - </thead> - <tbody valign="top"> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_DV_CLASS</constant></entry> - <entry>class</entry> - </row> - <row> - <entry spanname="descr">The Digital Video class descriptor.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_DV_TX_HOTPLUG</constant></entry> - <entry>bitmask</entry> - </row> - <row> - <entry spanname="descr">Many connectors have a hotplug pin which is high - if EDID information is available from the source. This control shows the - state of the hotplug pin as seen by the transmitter. - Each bit corresponds to an output pad on the transmitter. If an output pad - does not have an associated hotplug pin, then the bit for that pad will be 0. - This read-only control is applicable to DVI-D, HDMI and DisplayPort connectors. - </entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_DV_TX_RXSENSE</constant></entry> - <entry>bitmask</entry> - </row> - <row> - <entry spanname="descr">Rx Sense is the detection of pull-ups on the TMDS - clock lines. This normally means that the sink has left/entered standby (i.e. - the transmitter can sense that the receiver is ready to receive video). - Each bit corresponds to an output pad on the transmitter. If an output pad - does not have an associated Rx Sense, then the bit for that pad will be 0. - This read-only control is applicable to DVI-D and HDMI devices. - </entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_DV_TX_EDID_PRESENT</constant></entry> - <entry>bitmask</entry> - </row> - <row> - <entry spanname="descr">When the transmitter sees the hotplug signal from the - receiver it will attempt to read the EDID. If set, then the transmitter has read - at least the first block (= 128 bytes). - Each bit corresponds to an output pad on the transmitter. If an output pad - does not support EDIDs, then the bit for that pad will be 0. - This read-only control is applicable to VGA, DVI-A/D, HDMI and DisplayPort connectors. - </entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_DV_TX_MODE</constant></entry> - <entry id="v4l2-dv-tx-mode">enum v4l2_dv_tx_mode</entry> - </row> - <row> - <entry spanname="descr">HDMI transmitters can transmit in DVI-D mode (just video) - or in HDMI mode (video + audio + auxiliary data). This control selects which mode - to use: V4L2_DV_TX_MODE_DVI_D or V4L2_DV_TX_MODE_HDMI. - This control is applicable to HDMI connectors. - </entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_DV_TX_RGB_RANGE</constant></entry> - <entry id="v4l2-dv-rgb-range">enum v4l2_dv_rgb_range</entry> - </row> - <row> - <entry spanname="descr">Select the quantization range for RGB output. V4L2_DV_RANGE_AUTO - follows the RGB quantization range specified in the standard for the video interface - (ie. <xref linkend="cea861" /> for HDMI). V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the standard - to be compatible with sinks that have not implemented the standard correctly - (unfortunately quite common for HDMI and DVI-D). Full range allows all possible values to be - used whereas limited range sets the range to (16 << (N-8)) - (235 << (N-8)) - where N is the number of bits per component. - This control is applicable to VGA, DVI-A/D, HDMI and DisplayPort connectors. - </entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_DV_RX_POWER_PRESENT</constant></entry> - <entry>bitmask</entry> - </row> - <row> - <entry spanname="descr">Detects whether the receiver receives power from the source - (e.g. HDMI carries 5V on one of the pins). This is often used to power an eeprom - which contains EDID information, such that the source can read the EDID even if - the sink is in standby/power off. - Each bit corresponds to an input pad on the transmitter. If an input pad - cannot detect whether power is present, then the bit for that pad will be 0. - This read-only control is applicable to DVI-D, HDMI and DisplayPort connectors. - </entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_DV_RX_RGB_RANGE</constant></entry> - <entry>enum v4l2_dv_rgb_range</entry> - </row> - <row> - <entry spanname="descr">Select the quantization range for RGB input. V4L2_DV_RANGE_AUTO - follows the RGB quantization range specified in the standard for the video interface - (ie. <xref linkend="cea861" /> for HDMI). V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the standard - to be compatible with sources that have not implemented the standard correctly - (unfortunately quite common for HDMI and DVI-D). Full range allows all possible values to be - used whereas limited range sets the range to (16 << (N-8)) - (235 << (N-8)) - where N is the number of bits per component. - This control is applicable to VGA, DVI-A/D, HDMI and DisplayPort connectors. - </entry> - </row> - <row><entry></entry></row> - </tbody> - </tgroup> - </table> - - </section> - - <section id="fm-rx-controls"> - <title>FM Receiver Control Reference</title> - - <para>The FM Receiver (FM_RX) class includes controls for common features of - FM Reception capable devices.</para> - - <table pgwide="1" frame="none" id="fm-rx-control-id"> - <title>FM_RX Control IDs</title> - - <tgroup cols="4"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="6*" /> - <colspec colname="c3" colwidth="2*" /> - <colspec colname="c4" colwidth="6*" /> - <spanspec namest="c1" nameend="c2" spanname="id" /> - <spanspec namest="c2" nameend="c4" spanname="descr" /> - <thead> - <row> - <entry spanname="id" align="left">ID</entry> - <entry align="left">Type</entry> - </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry> - </row> - </thead> - <tbody valign="top"> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_FM_RX_CLASS</constant> </entry> - <entry>class</entry> - </row><row><entry spanname="descr">The FM_RX class -descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a -description of this control class.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RDS_RECEPTION</constant> </entry> - <entry>boolean</entry> - </row><row><entry spanname="descr">Enables/disables RDS - reception by the radio tuner</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RDS_RX_PTY</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Gets RDS Programme Type field. -This encodes up to 31 pre-defined programme types.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RDS_RX_PS_NAME</constant> </entry> - <entry>string</entry> - </row> - <row><entry spanname="descr">Gets the Programme Service name (PS_NAME). -It is intended for static display on a receiver. It is the primary aid to listeners in programme service -identification and selection. In Annex E of <xref linkend="iec62106" />, the RDS specification, -there is a full description of the correct character encoding for Programme Service name strings. -Also from RDS specification, PS is usually a single eight character text. However, it is also possible -to find receivers which can scroll strings sized as 8 x N characters. So, this control must be configured -with steps of 8 characters. The result is it must always contain a string with size multiple of 8.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RDS_RX_RADIO_TEXT</constant> </entry> - <entry>string</entry> - </row> - <row><entry spanname="descr">Gets the Radio Text info. It is a textual description of -what is being broadcasted. RDS Radio Text can be applied when broadcaster wishes to transmit longer PS names, -programme-related information or any other text. In these cases, RadioText can be used in addition to -<constant>V4L2_CID_RDS_RX_PS_NAME</constant>. The encoding for Radio Text strings is also fully described -in Annex E of <xref linkend="iec62106" />. The length of Radio Text strings depends on which RDS Block is being -used to transmit it, either 32 (2A block) or 64 (2B block). However, it is also possible -to find receivers which can scroll strings sized as 32 x N or 64 x N characters. So, this control must be configured -with steps of 32 or 64 characters. The result is it must always contain a string with size multiple of 32 or 64. </entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RDS_RX_TRAFFIC_ANNOUNCEMENT</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">If set, then a traffic announcement is in progress.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RDS_RX_TRAFFIC_PROGRAM</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">If set, then the tuned programme carries traffic announcements.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RDS_RX_MUSIC_SPEECH</constant> </entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">If set, then this channel broadcasts music. If cleared, then it -broadcasts speech. If the transmitter doesn't make this distinction, then it will be set.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_TUNE_DEEMPHASIS</constant> </entry> - <entry>enum v4l2_deemphasis</entry> - </row> - <row id="v4l2-deemphasis"><entry spanname="descr">Configures the de-emphasis value for reception. -A de-emphasis filter is applied to the broadcast to accentuate the high audio frequencies. -Depending on the region, a time constant of either 50 or 75 useconds is used. The enum v4l2_deemphasis -defines possible values for de-emphasis. Here they are:</entry> - </row><row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_DEEMPHASIS_DISABLED</constant> </entry> - <entry>No de-emphasis is applied.</entry> - </row> - <row> - <entry><constant>V4L2_DEEMPHASIS_50_uS</constant> </entry> - <entry>A de-emphasis of 50 uS is used.</entry> - </row> - <row> - <entry><constant>V4L2_DEEMPHASIS_75_uS</constant> </entry> - <entry>A de-emphasis of 75 uS is used.</entry> - </row> - </tbody> - </entrytbl> - - </row> - <row><entry></entry></row> - </tbody> - </tgroup> - </table> - </section> - - <section id="detect-controls"> - <title>Detect Control Reference</title> - - <para>The Detect class includes controls for common features of - various motion or object detection capable devices.</para> - - <table pgwide="1" frame="none" id="detect-control-id"> - <title>Detect Control IDs</title> - - <tgroup cols="4"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="6*" /> - <colspec colname="c3" colwidth="2*" /> - <colspec colname="c4" colwidth="6*" /> - <spanspec namest="c1" nameend="c2" spanname="id" /> - <spanspec namest="c2" nameend="c4" spanname="descr" /> - <thead> - <row> - <entry spanname="id" align="left">ID</entry> - <entry align="left">Type</entry> - </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry> - </row> - </thead> - <tbody valign="top"> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_DETECT_CLASS</constant> </entry> - <entry>class</entry> - </row><row><entry spanname="descr">The Detect class -descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a -description of this control class.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_DETECT_MD_MODE</constant> </entry> - <entry>menu</entry> - </row><row><entry spanname="descr">Sets the motion detection mode.</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_DETECT_MD_MODE_DISABLED</constant> - </entry><entry>Disable motion detection.</entry> - </row> - <row> - <entry><constant>V4L2_DETECT_MD_MODE_GLOBAL</constant> - </entry><entry>Use a single motion detection threshold.</entry> - </row> - <row> - <entry><constant>V4L2_DETECT_MD_MODE_THRESHOLD_GRID</constant> - </entry><entry>The image is divided into a grid, each cell with its own - motion detection threshold. These thresholds are set through the - <constant>V4L2_CID_DETECT_MD_THRESHOLD_GRID</constant> matrix control.</entry> - </row> - <row> - <entry><constant>V4L2_DETECT_MD_MODE_REGION_GRID</constant> - </entry><entry>The image is divided into a grid, each cell with its own - region value that specifies which per-region motion detection thresholds - should be used. Each region has its own thresholds. How these per-region - thresholds are set up is driver-specific. The region values for the grid are set - through the <constant>V4L2_CID_DETECT_MD_REGION_GRID</constant> matrix - control.</entry> - </row> - </tbody> - </entrytbl> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_DETECT_MD_GLOBAL_THRESHOLD</constant> </entry> - <entry>integer</entry> - </row> - <row><entry spanname="descr">Sets the global motion detection threshold to be - used with the <constant>V4L2_DETECT_MD_MODE_GLOBAL</constant> motion detection mode.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_DETECT_MD_THRESHOLD_GRID</constant> </entry> - <entry>__u16 matrix</entry> - </row> - <row><entry spanname="descr">Sets the motion detection thresholds for each cell in the grid. - To be used with the <constant>V4L2_DETECT_MD_MODE_THRESHOLD_GRID</constant> - motion detection mode. Matrix element (0, 0) represents the cell at the top-left of the - grid.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_DETECT_MD_REGION_GRID</constant> </entry> - <entry>__u8 matrix</entry> - </row> - <row><entry spanname="descr">Sets the motion detection region value for each cell in the grid. - To be used with the <constant>V4L2_DETECT_MD_MODE_REGION_GRID</constant> - motion detection mode. Matrix element (0, 0) represents the cell at the top-left of the - grid.</entry> - </row> - </tbody> - </tgroup> - </table> - - </section> - - <section id="rf-tuner-controls"> - <title>RF Tuner Control Reference</title> - - <para> -The RF Tuner (RF_TUNER) class includes controls for common features of devices -having RF tuner. - </para> - <para> -In this context, RF tuner is radio receiver circuit between antenna and -demodulator. It receives radio frequency (RF) from the antenna and converts that -received signal to lower intermediate frequency (IF) or baseband frequency (BB). -Tuners that could do baseband output are often called Zero-IF tuners. Older -tuners were typically simple PLL tuners inside a metal box, whilst newer ones -are highly integrated chips without a metal box "silicon tuners". These controls -are mostly applicable for new feature rich silicon tuners, just because older -tuners does not have much adjustable features. - </para> - <para> -For more information about RF tuners see -<ulink url="http://en.wikipedia.org/wiki/Tuner_%28radio%29">Tuner (radio)</ulink> -and -<ulink url="http://en.wikipedia.org/wiki/RF_front_end">RF front end</ulink> -from Wikipedia. - </para> - - <table pgwide="1" frame="none" id="rf-tuner-control-id"> - <title>RF_TUNER Control IDs</title> - - <tgroup cols="4"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="6*" /> - <colspec colname="c3" colwidth="2*" /> - <colspec colname="c4" colwidth="6*" /> - <spanspec namest="c1" nameend="c2" spanname="id" /> - <spanspec namest="c2" nameend="c4" spanname="descr" /> - <thead> - <row> - <entry spanname="id" align="left">ID</entry> - <entry align="left">Type</entry> - </row> - <row rowsep="1"> - <entry spanname="descr" align="left">Description</entry> - </row> - </thead> - <tbody valign="top"> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_RF_TUNER_CLASS</constant> </entry> - <entry>class</entry> - </row><row><entry spanname="descr">The RF_TUNER class -descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a -description of this control class.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RF_TUNER_BANDWIDTH_AUTO</constant> </entry> - <entry>boolean</entry> - </row> - <row> - <entry spanname="descr">Enables/disables tuner radio channel -bandwidth configuration. In automatic mode bandwidth configuration is performed -by the driver.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RF_TUNER_BANDWIDTH</constant> </entry> - <entry>integer</entry> - </row> - <row> - <entry spanname="descr">Filter(s) on tuner signal path are used to -filter signal according to receiving party needs. Driver configures filters to -fulfill desired bandwidth requirement. Used when V4L2_CID_RF_TUNER_BANDWIDTH_AUTO is not -set. Unit is in Hz. The range and step are driver-specific.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RF_TUNER_LNA_GAIN_AUTO</constant> </entry> - <entry>boolean</entry> - </row> - <row> - <entry spanname="descr">Enables/disables LNA automatic gain control (AGC)</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO</constant> </entry> - <entry>boolean</entry> - </row> - <row> - <entry spanname="descr">Enables/disables mixer automatic gain control (AGC)</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RF_TUNER_IF_GAIN_AUTO</constant> </entry> - <entry>boolean</entry> - </row> - <row> - <entry spanname="descr">Enables/disables IF automatic gain control (AGC)</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RF_TUNER_RF_GAIN</constant> </entry> - <entry>integer</entry> - </row> - <row> - <entry spanname="descr">The RF amplifier is the very first -amplifier on the receiver signal path, just right after the antenna input. -The difference between the LNA gain and the RF gain in this document is that -the LNA gain is integrated in the tuner chip while the RF gain is a separate -chip. There may be both RF and LNA gain controls in the same device. -The range and step are driver-specific.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RF_TUNER_LNA_GAIN</constant> </entry> - <entry>integer</entry> - </row> - <row> - <entry spanname="descr">LNA (low noise amplifier) gain is first -gain stage on the RF tuner signal path. It is located very close to tuner -antenna input. Used when <constant>V4L2_CID_RF_TUNER_LNA_GAIN_AUTO</constant> is not set. -See <constant>V4L2_CID_RF_TUNER_RF_GAIN</constant> to understand how RF gain -and LNA gain differs from the each others. -The range and step are driver-specific.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RF_TUNER_MIXER_GAIN</constant> </entry> - <entry>integer</entry> - </row> - <row> - <entry spanname="descr">Mixer gain is second gain stage on the RF -tuner signal path. It is located inside mixer block, where RF signal is -down-converted by the mixer. Used when <constant>V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO</constant> -is not set. The range and step are driver-specific.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RF_TUNER_IF_GAIN</constant> </entry> - <entry>integer</entry> - </row> - <row> - <entry spanname="descr">IF gain is last gain stage on the RF tuner -signal path. It is located on output of RF tuner. It controls signal level of -intermediate frequency output or baseband output. Used when -<constant>V4L2_CID_RF_TUNER_IF_GAIN_AUTO</constant> is not set. The range and step are -driver-specific.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_RF_TUNER_PLL_LOCK</constant> </entry> - <entry>boolean</entry> - </row> - <row> - <entry spanname="descr">Is synthesizer PLL locked? RF tuner is -receiving given frequency when that control is set. This is a read-only control. -</entry> - </row> - </tbody> - </tgroup> - </table> - </section> -</section> diff --git a/Documentation/DocBook/media/v4l/crop.pdf b/Documentation/DocBook/media/v4l/crop.pdf Binary files differdeleted file mode 100644 index c9fb81cd32f3..000000000000 --- a/Documentation/DocBook/media/v4l/crop.pdf +++ /dev/null diff --git a/Documentation/DocBook/media/v4l/dev-capture.xml b/Documentation/DocBook/media/v4l/dev-capture.xml deleted file mode 100644 index e1c5f9406d6a..000000000000 --- a/Documentation/DocBook/media/v4l/dev-capture.xml +++ /dev/null @@ -1,110 +0,0 @@ - <title>Video Capture Interface</title> - - <para>Video capture devices sample an analog video signal and store -the digitized images in memory. Today nearly all devices can capture -at full 25 or 30 frames/second. With this interface applications can -control the capture process and move images from the driver into user -space.</para> - - <para>Conventionally V4L2 video capture devices are accessed through -character device special files named <filename>/dev/video</filename> -and <filename>/dev/video0</filename> to -<filename>/dev/video63</filename> with major number 81 and minor -numbers 0 to 63. <filename>/dev/video</filename> is typically a -symbolic link to the preferred video device. Note the same device -files are used for video output devices.</para> - - <section> - <title>Querying Capabilities</title> - - <para>Devices supporting the video capture interface set the -<constant>V4L2_CAP_VIDEO_CAPTURE</constant> or -<constant>V4L2_CAP_VIDEO_CAPTURE_MPLANE</constant> flag in the -<structfield>capabilities</structfield> field of &v4l2-capability; -returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions -they may also support the <link linkend="overlay">video overlay</link> -(<constant>V4L2_CAP_VIDEO_OVERLAY</constant>) and the <link -linkend="raw-vbi">raw VBI capture</link> -(<constant>V4L2_CAP_VBI_CAPTURE</constant>) interface. At least one of -the read/write or streaming I/O methods must be supported. Tuners and -audio inputs are optional.</para> - </section> - - <section> - <title>Supplemental Functions</title> - - <para>Video capture devices shall support <link -linkend="audio">audio input</link>, <link -linkend="tuner">tuner</link>, <link linkend="control">controls</link>, -<link linkend="crop">cropping and scaling</link> and <link -linkend="streaming-par">streaming parameter</link> ioctls as needed. -The <link linkend="video">video input</link> and <link -linkend="standard">video standard</link> ioctls must be supported by -all video capture devices.</para> - </section> - - <section> - <title>Image Format Negotiation</title> - - <para>The result of a capture operation is determined by -cropping and image format parameters. The former select an area of the -video picture to capture, the latter how images are stored in memory, -&ie; in RGB or YUV format, the number of bits per pixel or width and -height. Together they also define how images are scaled in the -process.</para> - - <para>As usual these parameters are <emphasis>not</emphasis> reset -at &func-open; time to permit Unix tool chains, programming a device -and then reading from it as if it was a plain file. Well written V4L2 -applications ensure they really get what they want, including cropping -and scaling.</para> - - <para>Cropping initialization at minimum requires to reset the -parameters to defaults. An example is given in <xref -linkend="crop" />.</para> - - <para>To query the current image format applications set the -<structfield>type</structfield> field of a &v4l2-format; to -<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> or -<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant> and call the -&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill -the &v4l2-pix-format; <structfield>pix</structfield> or the -&v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member of the -<structfield>fmt</structfield> union.</para> - - <para>To request different parameters applications set the -<structfield>type</structfield> field of a &v4l2-format; as above and -initialize all fields of the &v4l2-pix-format; -<structfield>vbi</structfield> member of the -<structfield>fmt</structfield> union, or better just modify the -results of <constant>VIDIOC_G_FMT</constant>, and call the -&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may -adjust the parameters and finally return the actual parameters as -<constant>VIDIOC_G_FMT</constant> does.</para> - - <para>Like <constant>VIDIOC_S_FMT</constant> the -&VIDIOC-TRY-FMT; ioctl can be used to learn about hardware limitations -without disabling I/O or possibly time consuming hardware -preparations.</para> - - <para>The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane; -are discussed in <xref linkend="pixfmt" />. See also the specification of the -<constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant> -and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video -capture devices must implement both the -<constant>VIDIOC_G_FMT</constant> and -<constant>VIDIOC_S_FMT</constant> ioctl, even if -<constant>VIDIOC_S_FMT</constant> ignores all requests and always -returns default parameters as <constant>VIDIOC_G_FMT</constant> does. -<constant>VIDIOC_TRY_FMT</constant> is optional.</para> - </section> - - <section> - <title>Reading Images</title> - - <para>A video capture device may support the <link -linkend="rw">read() function</link> and/or streaming (<link -linkend="mmap">memory mapping</link> or <link -linkend="userp">user pointer</link>) I/O. See <xref -linkend="io" /> for details.</para> - </section> diff --git a/Documentation/DocBook/media/v4l/dev-codec.xml b/Documentation/DocBook/media/v4l/dev-codec.xml deleted file mode 100644 index ff44c16fc080..000000000000 --- a/Documentation/DocBook/media/v4l/dev-codec.xml +++ /dev/null @@ -1,27 +0,0 @@ - <title>Codec Interface</title> - - <para>A V4L2 codec can compress, decompress, transform, or otherwise -convert video data from one format into another format, in memory. Typically -such devices are memory-to-memory devices (i.e. devices with the -<constant>V4L2_CAP_VIDEO_M2M</constant> or <constant>V4L2_CAP_VIDEO_M2M_MPLANE</constant> -capability set). -</para> - - <para>A memory-to-memory video node acts just like a normal video node, but it -supports both output (sending frames from memory to the codec hardware) and -capture (receiving the processed frames from the codec hardware into memory) -stream I/O. An application will have to setup the stream -I/O for both sides and finally call &VIDIOC-STREAMON; for both capture and output -to start the codec.</para> - - <para>Video compression codecs use the MPEG controls to setup their codec parameters -(note that the MPEG controls actually support many more codecs than just MPEG). -See <xref linkend="mpeg-controls"></xref>.</para> - - <para>Memory-to-memory devices can often be used as a shared resource: you can -open the video node multiple times, each application setting up their own codec properties -that are local to the file handle, and each can use it independently from the others. -The driver will arbitrate access to the codec and reprogram it whenever another file -handler gets access. This is different from the usual video node behavior where the video properties -are global to the device (i.e. changing something through one file handle is visible -through another file handle).</para> diff --git a/Documentation/DocBook/media/v4l/dev-effect.xml b/Documentation/DocBook/media/v4l/dev-effect.xml deleted file mode 100644 index 2350a67c0710..000000000000 --- a/Documentation/DocBook/media/v4l/dev-effect.xml +++ /dev/null @@ -1,17 +0,0 @@ - <title>Effect Devices Interface</title> - - <note> - <title>Suspended</title> - - <para>This interface has been be suspended from the V4L2 API -implemented in Linux 2.6 until we have more experience with effect -device interfaces.</para> - </note> - - <para>A V4L2 video effect device can do image effects, filtering, or -combine two or more images or image streams. For example video -transitions or wipes. Applications send data to be processed and -receive the result data either with &func-read; and &func-write; -functions, or through the streaming I/O mechanism.</para> - - <para>[to do]</para> diff --git a/Documentation/DocBook/media/v4l/dev-event.xml b/Documentation/DocBook/media/v4l/dev-event.xml deleted file mode 100644 index 19f4becfae34..000000000000 --- a/Documentation/DocBook/media/v4l/dev-event.xml +++ /dev/null @@ -1,43 +0,0 @@ - <title>Event Interface</title> - - <para>The V4L2 event interface provides a means for a user to get - immediately notified on certain conditions taking place on a device. - This might include start of frame or loss of signal events, for - example. Changes in the value or state of a V4L2 control can also be - reported through events. - </para> - - <para>To receive events, the events the user is interested in first must - be subscribed using the &VIDIOC-SUBSCRIBE-EVENT; ioctl. Once an event is - subscribed, the events of subscribed types are dequeueable using the - &VIDIOC-DQEVENT; ioctl. Events may be unsubscribed using - VIDIOC_UNSUBSCRIBE_EVENT ioctl. The special event type V4L2_EVENT_ALL may - be used to unsubscribe all the events the driver supports.</para> - - <para>The event subscriptions and event queues are specific to file - handles. Subscribing an event on one file handle does not affect - other file handles.</para> - - <para>The information on dequeueable events is obtained by using select or - poll system calls on video devices. The V4L2 events use POLLPRI events on - poll system call and exceptions on select system call.</para> - - <para>Starting with kernel 3.1 certain guarantees can be given with - regards to events:<orderedlist> - <listitem> - <para>Each subscribed event has its own internal dedicated event queue. -This means that flooding of one event type will not interfere with other -event types.</para> - </listitem> - <listitem> - <para>If the internal event queue for a particular subscribed event -becomes full, then the oldest event in that queue will be dropped.</para> - </listitem> - <listitem> - <para>Where applicable, certain event types can ensure that the payload -of the oldest event that is about to be dropped will be merged with the payload -of the next oldest event. Thus ensuring that no information is lost, but only an -intermediate step leading up to that information. See the documentation for the -event you want to subscribe to whether this is applicable for that event or not.</para> - </listitem> - </orderedlist></para> diff --git a/Documentation/DocBook/media/v4l/dev-osd.xml b/Documentation/DocBook/media/v4l/dev-osd.xml deleted file mode 100644 index 54853329140b..000000000000 --- a/Documentation/DocBook/media/v4l/dev-osd.xml +++ /dev/null @@ -1,149 +0,0 @@ - <title>Video Output Overlay Interface</title> - <subtitle>Also known as On-Screen Display (OSD)</subtitle> - - <para>Some video output devices can overlay a framebuffer image onto -the outgoing video signal. Applications can set up such an overlay -using this interface, which borrows structures and ioctls of the <link -linkend="overlay">Video Overlay</link> interface.</para> - - <para>The OSD function is accessible through the same character -special file as the <link linkend="capture">Video Output</link> function. -Note the default function of such a <filename>/dev/video</filename> device -is video capturing or output. The OSD function is only available after -calling the &VIDIOC-S-FMT; ioctl.</para> - - <section> - <title>Querying Capabilities</title> - - <para>Devices supporting the <wordasword>Video Output -Overlay</wordasword> interface set the -<constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant> flag in the -<structfield>capabilities</structfield> field of &v4l2-capability; -returned by the &VIDIOC-QUERYCAP; ioctl.</para> - </section> - - <section> - <title>Framebuffer</title> - - <para>Contrary to the <wordasword>Video Overlay</wordasword> -interface the framebuffer is normally implemented on the TV card and -not the graphics card. On Linux it is accessible as a framebuffer -device (<filename>/dev/fbN</filename>). Given a V4L2 device, -applications can find the corresponding framebuffer device by calling -the &VIDIOC-G-FBUF; ioctl. It returns, amongst other information, the -physical address of the framebuffer in the -<structfield>base</structfield> field of &v4l2-framebuffer;. The -framebuffer device ioctl <constant>FBIOGET_FSCREENINFO</constant> -returns the same address in the <structfield>smem_start</structfield> -field of struct <structname>fb_fix_screeninfo</structname>. The -<constant>FBIOGET_FSCREENINFO</constant> ioctl and struct -<structname>fb_fix_screeninfo</structname> are defined in the -<filename>linux/fb.h</filename> header file.</para> - - <para>The width and height of the framebuffer depends on the -current video standard. A V4L2 driver may reject attempts to change -the video standard (or any other ioctl which would imply a framebuffer -size change) with an &EBUSY; until all applications closed the -framebuffer device.</para> - - <example> - <title>Finding a framebuffer device for OSD</title> - - <programlisting> -#include <linux/fb.h> - -&v4l2-framebuffer; fbuf; -unsigned int i; -int fb_fd; - -if (-1 == ioctl(fd, VIDIOC_G_FBUF, &fbuf)) { - perror("VIDIOC_G_FBUF"); - exit(EXIT_FAILURE); -} - -for (i = 0; i < 30; i++) { - char dev_name[16]; - struct fb_fix_screeninfo si; - - snprintf(dev_name, sizeof(dev_name), "/dev/fb%u", i); - - fb_fd = open(dev_name, O_RDWR); - if (-1 == fb_fd) { - switch (errno) { - case ENOENT: /* no such file */ - case ENXIO: /* no driver */ - continue; - - default: - perror("open"); - exit(EXIT_FAILURE); - } - } - - if (0 == ioctl(fb_fd, FBIOGET_FSCREENINFO, &si)) { - if (si.smem_start == (unsigned long)fbuf.base) - break; - } else { - /* Apparently not a framebuffer device. */ - } - - close(fb_fd); - fb_fd = -1; -} - -/* fb_fd is the file descriptor of the framebuffer device - for the video output overlay, or -1 if no device was found. */ -</programlisting> - </example> - </section> - - <section> - <title>Overlay Window and Scaling</title> - - <para>The overlay is controlled by source and target rectangles. -The source rectangle selects a subsection of the framebuffer image to -be overlaid, the target rectangle an area in the outgoing video signal -where the image will appear. Drivers may or may not support scaling, -and arbitrary sizes and positions of these rectangles. Further drivers -may support any (or none) of the clipping/blending methods defined for -the <link linkend="overlay">Video Overlay</link> interface.</para> - - <para>A &v4l2-window; defines the size of the source rectangle, -its position in the framebuffer and the clipping/blending method to be -used for the overlay. To get the current parameters applications set -the <structfield>type</structfield> field of a &v4l2-format; to -<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant> and call the -&VIDIOC-G-FMT; ioctl. The driver fills the -<structname>v4l2_window</structname> substructure named -<structfield>win</structfield>. It is not possible to retrieve a -previously programmed clipping list or bitmap.</para> - - <para>To program the source rectangle applications set the -<structfield>type</structfield> field of a &v4l2-format; to -<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant>, initialize -the <structfield>win</structfield> substructure and call the -&VIDIOC-S-FMT; ioctl. The driver adjusts the parameters against -hardware limits and returns the actual parameters as -<constant>VIDIOC_G_FMT</constant> does. Like -<constant>VIDIOC_S_FMT</constant>, the &VIDIOC-TRY-FMT; ioctl can be -used to learn about driver capabilities without actually changing -driver state. Unlike <constant>VIDIOC_S_FMT</constant> this also works -after the overlay has been enabled.</para> - - <para>A &v4l2-crop; defines the size and position of the target -rectangle. The scaling factor of the overlay is implied by the width -and height given in &v4l2-window; and &v4l2-crop;. The cropping API -applies to <wordasword>Video Output</wordasword> and <wordasword>Video -Output Overlay</wordasword> devices in the same way as to -<wordasword>Video Capture</wordasword> and <wordasword>Video -Overlay</wordasword> devices, merely reversing the direction of the -data flow. For more information see <xref linkend="crop" />.</para> - </section> - - <section> - <title>Enabling Overlay</title> - - <para>There is no V4L2 ioctl to enable or disable the overlay, -however the framebuffer interface of the driver may support the -<constant>FBIOBLANK</constant> ioctl.</para> - </section> diff --git a/Documentation/DocBook/media/v4l/dev-output.xml b/Documentation/DocBook/media/v4l/dev-output.xml deleted file mode 100644 index 9130a3dc7880..000000000000 --- a/Documentation/DocBook/media/v4l/dev-output.xml +++ /dev/null @@ -1,106 +0,0 @@ - <title>Video Output Interface</title> - - <para>Video output devices encode stills or image sequences as -analog video signal. With this interface applications can -control the encoding process and move images from user space to -the driver.</para> - - <para>Conventionally V4L2 video output devices are accessed through -character device special files named <filename>/dev/video</filename> -and <filename>/dev/video0</filename> to -<filename>/dev/video63</filename> with major number 81 and minor -numbers 0 to 63. <filename>/dev/video</filename> is typically a -symbolic link to the preferred video device. Note the same device -files are used for video capture devices.</para> - - <section> - <title>Querying Capabilities</title> - - <para>Devices supporting the video output interface set the -<constant>V4L2_CAP_VIDEO_OUTPUT</constant> or -<constant>V4L2_CAP_VIDEO_OUTPUT_MPLANE</constant> flag in the -<structfield>capabilities</structfield> field of &v4l2-capability; -returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions -they may also support the <link linkend="raw-vbi">raw VBI -output</link> (<constant>V4L2_CAP_VBI_OUTPUT</constant>) interface. At -least one of the read/write or streaming I/O methods must be -supported. Modulators and audio outputs are optional.</para> - </section> - - <section> - <title>Supplemental Functions</title> - - <para>Video output devices shall support <link -linkend="audio">audio output</link>, <link -linkend="tuner">modulator</link>, <link linkend="control">controls</link>, -<link linkend="crop">cropping and scaling</link> and <link -linkend="streaming-par">streaming parameter</link> ioctls as needed. -The <link linkend="video">video output</link> and <link -linkend="standard">video standard</link> ioctls must be supported by -all video output devices.</para> - </section> - - <section> - <title>Image Format Negotiation</title> - - <para>The output is determined by cropping and image format -parameters. The former select an area of the video picture where the -image will appear, the latter how images are stored in memory, &ie; in -RGB or YUV format, the number of bits per pixel or width and height. -Together they also define how images are scaled in the process.</para> - - <para>As usual these parameters are <emphasis>not</emphasis> reset -at &func-open; time to permit Unix tool chains, programming a device -and then writing to it as if it was a plain file. Well written V4L2 -applications ensure they really get what they want, including cropping -and scaling.</para> - - <para>Cropping initialization at minimum requires to reset the -parameters to defaults. An example is given in <xref -linkend="crop" />.</para> - - <para>To query the current image format applications set the -<structfield>type</structfield> field of a &v4l2-format; to -<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> or -<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant> and call the -&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill -the &v4l2-pix-format; <structfield>pix</structfield> or the -&v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member of the -<structfield>fmt</structfield> union.</para> - - <para>To request different parameters applications set the -<structfield>type</structfield> field of a &v4l2-format; as above and -initialize all fields of the &v4l2-pix-format; -<structfield>vbi</structfield> member of the -<structfield>fmt</structfield> union, or better just modify the -results of <constant>VIDIOC_G_FMT</constant>, and call the -&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may -adjust the parameters and finally return the actual parameters as -<constant>VIDIOC_G_FMT</constant> does.</para> - - <para>Like <constant>VIDIOC_S_FMT</constant> the -&VIDIOC-TRY-FMT; ioctl can be used to learn about hardware limitations -without disabling I/O or possibly time consuming hardware -preparations.</para> - - <para>The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane; -are discussed in <xref linkend="pixfmt" />. See also the specification of the -<constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant> -and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video -output devices must implement both the -<constant>VIDIOC_G_FMT</constant> and -<constant>VIDIOC_S_FMT</constant> ioctl, even if -<constant>VIDIOC_S_FMT</constant> ignores all requests and always -returns default parameters as <constant>VIDIOC_G_FMT</constant> does. -<constant>VIDIOC_TRY_FMT</constant> is optional.</para> - </section> - - <section> - <title>Writing Images</title> - - <para>A video output device may support the <link -linkend="rw">write() function</link> and/or streaming (<link -linkend="mmap">memory mapping</link> or <link -linkend="userp">user pointer</link>) I/O. See <xref -linkend="io" /> for details.</para> - </section> diff --git a/Documentation/DocBook/media/v4l/dev-overlay.xml b/Documentation/DocBook/media/v4l/dev-overlay.xml deleted file mode 100644 index cc6e0c5c960c..000000000000 --- a/Documentation/DocBook/media/v4l/dev-overlay.xml +++ /dev/null @@ -1,368 +0,0 @@ - <title>Video Overlay Interface</title> - <subtitle>Also known as Framebuffer Overlay or Previewing</subtitle> - - <para>Video overlay devices have the ability to genlock (TV-)video -into the (VGA-)video signal of a graphics card, or to store captured -images directly in video memory of a graphics card, typically with -clipping. This can be considerable more efficient than capturing -images and displaying them by other means. In the old days when only -nuclear power plants needed cooling towers this used to be the only -way to put live video into a window.</para> - - <para>Video overlay devices are accessed through the same character -special files as <link linkend="capture">video capture</link> devices. -Note the default function of a <filename>/dev/video</filename> device -is video capturing. The overlay function is only available after -calling the &VIDIOC-S-FMT; ioctl.</para> - - <para>The driver may support simultaneous overlay and capturing -using the read/write and streaming I/O methods. If so, operation at -the nominal frame rate of the video standard is not guaranteed. Frames -may be directed away from overlay to capture, or one field may be used -for overlay and the other for capture if the capture parameters permit -this.</para> - - <para>Applications should use different file descriptors for -capturing and overlay. This must be supported by all drivers capable -of simultaneous capturing and overlay. Optionally these drivers may -also permit capturing and overlay with a single file descriptor for -compatibility with V4L and earlier versions of V4L2.<footnote> - <para>A common application of two file descriptors is the -XFree86 <link linkend="xvideo">Xv/V4L</link> interface driver and -a V4L2 application. While the X server controls video overlay, the -application can take advantage of memory mapping and DMA.</para> - <para>In the opinion of the designers of this API, no driver -writer taking the efforts to support simultaneous capturing and -overlay will restrict this ability by requiring a single file -descriptor, as in V4L and earlier versions of V4L2. Making this -optional means applications depending on two file descriptors need -backup routines to be compatible with all drivers, which is -considerable more work than using two fds in applications which do -not. Also two fd's fit the general concept of one file descriptor for -each logical stream. Hence as a complexity trade-off drivers -<emphasis>must</emphasis> support two file descriptors and -<emphasis>may</emphasis> support single fd operation.</para> - </footnote></para> - - <section> - <title>Querying Capabilities</title> - - <para>Devices supporting the video overlay interface set the -<constant>V4L2_CAP_VIDEO_OVERLAY</constant> flag in the -<structfield>capabilities</structfield> field of &v4l2-capability; -returned by the &VIDIOC-QUERYCAP; ioctl. The overlay I/O method specified -below must be supported. Tuners and audio inputs are optional.</para> - </section> - - <section> - <title>Supplemental Functions</title> - - <para>Video overlay devices shall support <link -linkend="audio">audio input</link>, <link -linkend="tuner">tuner</link>, <link linkend="control">controls</link>, -<link linkend="crop">cropping and scaling</link> and <link -linkend="streaming-par">streaming parameter</link> ioctls as needed. -The <link linkend="video">video input</link> and <link -linkend="standard">video standard</link> ioctls must be supported by -all video overlay devices.</para> - </section> - - <section> - <title>Setup</title> - - <para>Before overlay can commence applications must program the -driver with frame buffer parameters, namely the address and size of -the frame buffer and the image format, for example RGB 5:6:5. The -&VIDIOC-G-FBUF; and &VIDIOC-S-FBUF; ioctls are available to get -and set these parameters, respectively. The -<constant>VIDIOC_S_FBUF</constant> ioctl is privileged because it -allows to set up DMA into physical memory, bypassing the memory -protection mechanisms of the kernel. Only the superuser can change the -frame buffer address and size. Users are not supposed to run TV -applications as root or with SUID bit set. A small helper application -with suitable privileges should query the graphics system and program -the V4L2 driver at the appropriate time.</para> - - <para>Some devices add the video overlay to the output signal -of the graphics card. In this case the frame buffer is not modified by -the video device, and the frame buffer address and pixel format are -not needed by the driver. The <constant>VIDIOC_S_FBUF</constant> ioctl -is not privileged. An application can check for this type of device by -calling the <constant>VIDIOC_G_FBUF</constant> ioctl.</para> - - <para>A driver may support any (or none) of five clipping/blending -methods:<orderedlist> - <listitem> - <para>Chroma-keying displays the overlaid image only where -pixels in the primary graphics surface assume a certain color.</para> - </listitem> - <listitem> - <para>A bitmap can be specified where each bit corresponds -to a pixel in the overlaid image. When the bit is set, the -corresponding video pixel is displayed, otherwise a pixel of the -graphics surface.</para> - </listitem> - <listitem> - <para>A list of clipping rectangles can be specified. In -these regions <emphasis>no</emphasis> video is displayed, so the -graphics surface can be seen here.</para> - </listitem> - <listitem> - <para>The framebuffer has an alpha channel that can be used -to clip or blend the framebuffer with the video.</para> - </listitem> - <listitem> - <para>A global alpha value can be specified to blend the -framebuffer contents with video images.</para> - </listitem> - </orderedlist></para> - - <para>When simultaneous capturing and overlay is supported and -the hardware prohibits different image and frame buffer formats, the -format requested first takes precedence. The attempt to capture -(&VIDIOC-S-FMT;) or overlay (&VIDIOC-S-FBUF;) may fail with an -&EBUSY; or return accordingly modified parameters..</para> - </section> - - <section> - <title>Overlay Window</title> - - <para>The overlaid image is determined by cropping and overlay -window parameters. The former select an area of the video picture to -capture, the latter how images are overlaid and clipped. Cropping -initialization at minimum requires to reset the parameters to -defaults. An example is given in <xref linkend="crop" />.</para> - - <para>The overlay window is described by a &v4l2-window;. It -defines the size of the image, its position over the graphics surface -and the clipping to be applied. To get the current parameters -applications set the <structfield>type</structfield> field of a -&v4l2-format; to <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant> and -call the &VIDIOC-G-FMT; ioctl. The driver fills the -<structname>v4l2_window</structname> substructure named -<structfield>win</structfield>. It is not possible to retrieve a -previously programmed clipping list or bitmap.</para> - - <para>To program the overlay window applications set the -<structfield>type</structfield> field of a &v4l2-format; to -<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, initialize the -<structfield>win</structfield> substructure and call the -&VIDIOC-S-FMT; ioctl. The driver adjusts the parameters against -hardware limits and returns the actual parameters as -<constant>VIDIOC_G_FMT</constant> does. Like -<constant>VIDIOC_S_FMT</constant>, the &VIDIOC-TRY-FMT; ioctl can be -used to learn about driver capabilities without actually changing -driver state. Unlike <constant>VIDIOC_S_FMT</constant> this also works -after the overlay has been enabled.</para> - - <para>The scaling factor of the overlaid image is implied by the -width and height given in &v4l2-window; and the size of the cropping -rectangle. For more information see <xref linkend="crop" />.</para> - - <para>When simultaneous capturing and overlay is supported and -the hardware prohibits different image and window sizes, the size -requested first takes precedence. The attempt to capture or overlay as -well (&VIDIOC-S-FMT;) may fail with an &EBUSY; or return accordingly -modified parameters.</para> - - <table pgwide="1" frame="none" id="v4l2-window"> - <title>struct <structname>v4l2_window</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>&v4l2-rect;</entry> - <entry><structfield>w</structfield></entry> - <entry>Size and position of the window relative to the -top, left corner of the frame buffer defined with &VIDIOC-S-FBUF;. The -window can extend the frame buffer width and height, the -<structfield>x</structfield> and <structfield>y</structfield> -coordinates can be negative, and it can lie completely outside the -frame buffer. The driver clips the window accordingly, or if that is -not possible, modifies its size and/or position.</entry> - </row> - <row> - <entry>&v4l2-field;</entry> - <entry><structfield>field</structfield></entry> - <entry>Applications set this field to determine which -video field shall be overlaid, typically one of -<constant>V4L2_FIELD_ANY</constant> (0), -<constant>V4L2_FIELD_TOP</constant>, -<constant>V4L2_FIELD_BOTTOM</constant> or -<constant>V4L2_FIELD_INTERLACED</constant>. Drivers may have to choose -a different field order and return the actual setting here.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>chromakey</structfield></entry> - <entry>When chroma-keying has been negotiated with -&VIDIOC-S-FBUF; applications set this field to the desired pixel value -for the chroma key. The format is the same as the pixel format of the -framebuffer (&v4l2-framebuffer; -<structfield>fmt.pixelformat</structfield> field), with bytes in host -order. E. g. for <link -linkend="V4L2-PIX-FMT-BGR32"><constant>V4L2_PIX_FMT_BGR24</constant></link> -the value should be 0xRRGGBB on a little endian, 0xBBGGRR on a big -endian host.</entry> - </row> - <row> - <entry>&v4l2-clip; *</entry> - <entry><structfield>clips</structfield></entry> - <entry>When chroma-keying has <emphasis>not</emphasis> -been negotiated and &VIDIOC-G-FBUF; indicated this capability, -applications can set this field to point to an array of -clipping rectangles.</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>Like the window coordinates -<structfield>w</structfield>, clipping rectangles are defined relative -to the top, left corner of the frame buffer. However clipping -rectangles must not extend the frame buffer width and height, and they -must not overlap. If possible applications should merge adjacent -rectangles. Whether this must create x-y or y-x bands, or the order of -rectangles, is not defined. When clip lists are not supported the -driver ignores this field. Its contents after calling &VIDIOC-S-FMT; -are undefined.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>clipcount</structfield></entry> - <entry>When the application set the -<structfield>clips</structfield> field, this field must contain the -number of clipping rectangles in the list. When clip lists are not -supported the driver ignores this field, its contents after calling -<constant>VIDIOC_S_FMT</constant> are undefined. When clip lists are -supported but no clipping is desired this field must be set to -zero.</entry> - </row> - <row> - <entry>void *</entry> - <entry><structfield>bitmap</structfield></entry> - <entry>When chroma-keying has -<emphasis>not</emphasis> been negotiated and &VIDIOC-G-FBUF; indicated -this capability, applications can set this field to point to a -clipping bit mask.</entry> - </row> - <row> - <entry spanname="hspan"><para>It must be of the same size -as the window, <structfield>w.width</structfield> and -<structfield>w.height</structfield>. Each bit corresponds to a pixel -in the overlaid image, which is displayed only when the bit is -<emphasis>set</emphasis>. Pixel coordinates translate to bits like: -<programlisting> -((__u8 *) <structfield>bitmap</structfield>)[<structfield>w.width</structfield> * y + x / 8] & (1 << (x & 7))</programlisting></para><para>where <structfield>0</structfield> ≤ x < -<structfield>w.width</structfield> and <structfield>0</structfield> ≤ -y <<structfield>w.height</structfield>.<footnote> - <para>Should we require - <structfield>w.width</structfield> to be a multiple of - eight?</para> - </footnote></para><para>When a clipping -bit mask is not supported the driver ignores this field, its contents -after calling &VIDIOC-S-FMT; are undefined. When a bit mask is supported -but no clipping is desired this field must be set to -<constant>NULL</constant>.</para><para>Applications need not create a -clip list or bit mask. When they pass both, or despite negotiating -chroma-keying, the results are undefined. Regardless of the chosen -method, the clipping abilities of the hardware may be limited in -quantity or quality. The results when these limits are exceeded are -undefined.<footnote> - <para>When the image is written into frame buffer -memory it will be undesirable if the driver clips out less pixels -than expected, because the application and graphics system are not -aware these regions need to be refreshed. The driver should clip out -more pixels or not write the image at all.</para> - </footnote></para></entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>global_alpha</structfield></entry> - <entry>The global alpha value used to blend the -framebuffer with video images, if global alpha blending has been -negotiated (<constant>V4L2_FBUF_FLAG_GLOBAL_ALPHA</constant>, see -&VIDIOC-S-FBUF;, <xref linkend="framebuffer-flags" />).</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>Note this field was added in Linux 2.6.23, extending the structure. However -the <link linkend="vidioc-g-fmt">VIDIOC_G/S/TRY_FMT</link> ioctls, -which take a pointer to a <link -linkend="v4l2-format">v4l2_format</link> parent structure with padding -bytes at the end, are not affected.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="v4l2-clip"> - <title>struct <structname>v4l2_clip</structname><footnote> - <para>The X Window system defines "regions" which are -vectors of struct BoxRec { short x1, y1, x2, y2; } with width = x2 - -x1 and height = y2 - y1, so one cannot pass X11 clip lists -directly.</para> - </footnote></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>&v4l2-rect;</entry> - <entry><structfield>c</structfield></entry> - <entry>Coordinates of the clipping rectangle, relative to -the top, left corner of the frame buffer. Only window pixels -<emphasis>outside</emphasis> all clipping rectangles are -displayed.</entry> - </row> - <row> - <entry>&v4l2-clip; *</entry> - <entry><structfield>next</structfield></entry> - <entry>Pointer to the next clipping rectangle, NULL when -this is the last rectangle. Drivers ignore this field, it cannot be -used to pass a linked list of clipping rectangles.</entry> - </row> - </tbody> - </tgroup> - </table> - - <!-- NB for easier reading this table is duplicated - in the vidioc-cropcap chapter.--> - - <table pgwide="1" frame="none" id="v4l2-rect"> - <title>struct <structname>v4l2_rect</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__s32</entry> - <entry><structfield>left</structfield></entry> - <entry>Horizontal offset of the top, left corner of the -rectangle, in pixels.</entry> - </row> - <row> - <entry>__s32</entry> - <entry><structfield>top</structfield></entry> - <entry>Vertical offset of the top, left corner of the -rectangle, in pixels. Offsets increase to the right and down.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>width</structfield></entry> - <entry>Width of the rectangle, in pixels.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>height</structfield></entry> - <entry>Height of the rectangle, in pixels.</entry> - </row> - </tbody> - </tgroup> - </table> - </section> - - <section> - <title>Enabling Overlay</title> - - <para>To start or stop the frame buffer overlay applications call -the &VIDIOC-OVERLAY; ioctl.</para> - </section> diff --git a/Documentation/DocBook/media/v4l/dev-radio.xml b/Documentation/DocBook/media/v4l/dev-radio.xml deleted file mode 100644 index 3e6ac73b36af..000000000000 --- a/Documentation/DocBook/media/v4l/dev-radio.xml +++ /dev/null @@ -1,49 +0,0 @@ - <title>Radio Interface</title> - - <para>This interface is intended for AM and FM (analog) radio -receivers and transmitters.</para> - - <para>Conventionally V4L2 radio devices are accessed through -character device special files named <filename>/dev/radio</filename> -and <filename>/dev/radio0</filename> to -<filename>/dev/radio63</filename> with major number 81 and minor -numbers 64 to 127.</para> - - <section> - <title>Querying Capabilities</title> - - <para>Devices supporting the radio interface set the -<constant>V4L2_CAP_RADIO</constant> and -<constant>V4L2_CAP_TUNER</constant> or -<constant>V4L2_CAP_MODULATOR</constant> flag in the -<structfield>capabilities</structfield> field of &v4l2-capability; -returned by the &VIDIOC-QUERYCAP; ioctl. Other combinations of -capability flags are reserved for future extensions.</para> - </section> - - <section> - <title>Supplemental Functions</title> - - <para>Radio devices can support <link -linkend="control">controls</link>, and must support the <link -linkend="tuner">tuner or modulator</link> ioctls.</para> - - <para>They do not support the video input or output, audio input -or output, video standard, cropping and scaling, compression and -streaming parameter, or overlay ioctls. All other ioctls and I/O -methods are reserved for future extensions.</para> - </section> - - <section> - <title>Programming</title> - - <para>Radio devices may have a couple audio controls (as discussed -in <xref linkend="control" />) such as a volume control, possibly custom -controls. Further all radio devices have one tuner or modulator (these are -discussed in <xref linkend="tuner" />) with index number zero to select -the radio frequency and to determine if a monaural or FM stereo -program is received/emitted. Drivers switch automatically between AM and FM -depending on the selected frequency. The &VIDIOC-G-TUNER; or -&VIDIOC-G-MODULATOR; ioctl -reports the supported frequency range.</para> - </section> diff --git a/Documentation/DocBook/media/v4l/dev-raw-vbi.xml b/Documentation/DocBook/media/v4l/dev-raw-vbi.xml deleted file mode 100644 index f4b61b6ce3c2..000000000000 --- a/Documentation/DocBook/media/v4l/dev-raw-vbi.xml +++ /dev/null @@ -1,345 +0,0 @@ - <title>Raw VBI Data Interface</title> - - <para>VBI is an abbreviation of Vertical Blanking Interval, a gap -in the sequence of lines of an analog video signal. During VBI -no picture information is transmitted, allowing some time while the -electron beam of a cathode ray tube TV returns to the top of the -screen. Using an oscilloscope you will find here the vertical -synchronization pulses and short data packages ASK -modulated<footnote><para>ASK: Amplitude-Shift Keying. A high signal -level represents a '1' bit, a low level a '0' bit.</para></footnote> -onto the video signal. These are transmissions of services such as -Teletext or Closed Caption.</para> - - <para>Subject of this interface type is raw VBI data, as sampled off -a video signal, or to be added to a signal for output. -The data format is similar to uncompressed video images, a number of -lines times a number of samples per line, we call this a VBI image.</para> - - <para>Conventionally V4L2 VBI devices are accessed through character -device special files named <filename>/dev/vbi</filename> and -<filename>/dev/vbi0</filename> to <filename>/dev/vbi31</filename> with -major number 81 and minor numbers 224 to 255. -<filename>/dev/vbi</filename> is typically a symbolic link to the -preferred VBI device. This convention applies to both input and output -devices.</para> - - <para>To address the problems of finding related video and VBI -devices VBI capturing and output is also available as device function -under <filename>/dev/video</filename>. To capture or output raw VBI -data with these devices applications must call the &VIDIOC-S-FMT; -ioctl. Accessed as <filename>/dev/vbi</filename>, raw VBI capturing -or output is the default device function.</para> - - <section> - <title>Querying Capabilities</title> - - <para>Devices supporting the raw VBI capturing or output API set -the <constant>V4L2_CAP_VBI_CAPTURE</constant> or -<constant>V4L2_CAP_VBI_OUTPUT</constant> flags, respectively, in the -<structfield>capabilities</structfield> field of &v4l2-capability; -returned by the &VIDIOC-QUERYCAP; ioctl. At least one of the -read/write, streaming or asynchronous I/O methods must be -supported. VBI devices may or may not have a tuner or modulator.</para> - </section> - - <section> - <title>Supplemental Functions</title> - - <para>VBI devices shall support <link linkend="video">video -input or output</link>, <link linkend="tuner">tuner or -modulator</link>, and <link linkend="control">controls</link> ioctls -as needed. The <link linkend="standard">video standard</link> ioctls provide -information vital to program a VBI device, therefore must be -supported.</para> - </section> - - <section> - <title>Raw VBI Format Negotiation</title> - - <para>Raw VBI sampling abilities can vary, in particular the -sampling frequency. To properly interpret the data V4L2 specifies an -ioctl to query the sampling parameters. Moreover, to allow for some -flexibility applications can also suggest different parameters.</para> - - <para>As usual these parameters are <emphasis>not</emphasis> -reset at &func-open; time to permit Unix tool chains, programming a -device and then reading from it as if it was a plain file. Well -written V4L2 applications should always ensure they really get what -they want, requesting reasonable parameters and then checking if the -actual parameters are suitable.</para> - - <para>To query the current raw VBI capture parameters -applications set the <structfield>type</structfield> field of a -&v4l2-format; to <constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant> or -<constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>, and call the -&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill -the &v4l2-vbi-format; <structfield>vbi</structfield> member of the -<structfield>fmt</structfield> union.</para> - - <para>To request different parameters applications set the -<structfield>type</structfield> field of a &v4l2-format; as above and -initialize all fields of the &v4l2-vbi-format; -<structfield>vbi</structfield> member of the -<structfield>fmt</structfield> union, or better just modify the -results of <constant>VIDIOC_G_FMT</constant>, and call the -&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers return -an &EINVAL; only when the given parameters are ambiguous, otherwise -they modify the parameters according to the hardware capabilites and -return the actual parameters. When the driver allocates resources at -this point, it may return an &EBUSY; to indicate the returned -parameters are valid but the required resources are currently not -available. That may happen for instance when the video and VBI areas -to capture would overlap, or when the driver supports multiple opens -and another process already requested VBI capturing or output. Anyway, -applications must expect other resource allocation points which may -return <errorcode>EBUSY</errorcode>, at the &VIDIOC-STREAMON; ioctl -and the first read(), write() and select() call.</para> - - <para>VBI devices must implement both the -<constant>VIDIOC_G_FMT</constant> and -<constant>VIDIOC_S_FMT</constant> ioctl, even if -<constant>VIDIOC_S_FMT</constant> ignores all requests and always -returns default parameters as <constant>VIDIOC_G_FMT</constant> does. -<constant>VIDIOC_TRY_FMT</constant> is optional.</para> - - <table pgwide="1" frame="none" id="v4l2-vbi-format"> - <title>struct <structname>v4l2_vbi_format</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>sampling_rate</structfield></entry> - <entry>Samples per second, i. e. unit 1 Hz.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>offset</structfield></entry> - <entry><para>Horizontal offset of the VBI image, -relative to the leading edge of the line synchronization pulse and -counted in samples: The first sample in the VBI image will be located -<structfield>offset</structfield> / -<structfield>sampling_rate</structfield> seconds following the leading -edge. See also <xref linkend="vbi-hsync" />.</para></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>samples_per_line</structfield></entry> - <entry></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>sample_format</structfield></entry> - <entry><para>Defines the sample format as in <xref -linkend="pixfmt" />, a four-character-code.<footnote> - <para>A few devices may be unable to -sample VBI data at all but can extend the video capture window to the -VBI region.</para> - </footnote> Usually this is -<constant>V4L2_PIX_FMT_GREY</constant>, i. e. each sample -consists of 8 bits with lower values oriented towards the black level. -Do not assume any other correlation of values with the signal level. -For example, the MSB does not necessarily indicate if the signal is -'high' or 'low' because 128 may not be the mean value of the -signal. Drivers shall not convert the sample format by software.</para></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>start</structfield>[2]</entry> - <entry>This is the scanning system line number -associated with the first line of the VBI image, of the first and the -second field respectively. See <xref linkend="vbi-525" /> and -<xref linkend="vbi-625" /> for valid values. -The <constant>V4L2_VBI_ITU_525_F1_START</constant>, -<constant>V4L2_VBI_ITU_525_F2_START</constant>, -<constant>V4L2_VBI_ITU_625_F1_START</constant> and -<constant>V4L2_VBI_ITU_625_F2_START</constant> defines give the start line -numbers for each field for each 525 or 625 line format as a convenience. -Don't forget that ITU line numbering starts at 1, not 0. -VBI input drivers can return start values 0 if the hardware cannot -reliable identify scanning lines, VBI acquisition may not require this -information.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>count</structfield>[2]</entry> - <entry>The number of lines in the first and second -field image, respectively.</entry> - </row> - <row> - <entry spanname="hspan"><para>Drivers should be as -flexibility as possible. For example, it may be possible to extend or -move the VBI capture window down to the picture area, implementing a -'full field mode' to capture data service transmissions embedded in -the picture.</para><para>An application can set the first or second -<structfield>count</structfield> value to zero if no data is required -from the respective field; <structfield>count</structfield>[1] if the -scanning system is progressive, &ie; not interlaced. The -corresponding start value shall be ignored by the application and -driver. Anyway, drivers may not support single field capturing and -return both count values non-zero.</para><para>Both -<structfield>count</structfield> values set to zero, or line numbers -outside the bounds depicted in <xref linkend="vbi-525" /> and <xref - linkend="vbi-625" />, or a field image covering -lines of two fields, are invalid and shall not be returned by the -driver.</para><para>To initialize the <structfield>start</structfield> -and <structfield>count</structfield> fields, applications must first -determine the current video standard selection. The &v4l2-std-id; or -the <structfield>framelines</structfield> field of &v4l2-standard; can -be evaluated for this purpose.</para></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry>See <xref linkend="vbifmt-flags" /> below. Currently -only drivers set flags, applications must set this field to -zero.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[2]</entry> - <entry>This array is reserved for future extensions. -Drivers and applications must set it to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="vbifmt-flags"> - <title>Raw VBI Format Flags</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_VBI_UNSYNC</constant></entry> - <entry>0x0001</entry> - <entry><para>This flag indicates hardware which does not -properly distinguish between fields. Normally the VBI image stores the -first field (lower scanning line numbers) first in memory. This may be -a top or bottom field depending on the video standard. When this flag -is set the first or second field may be stored first, however the -fields are still in correct temporal order with the older field first -in memory.<footnote> - <para>Most VBI services transmit on both fields, but -some have different semantics depending on the field number. These -cannot be reliable decoded or encoded when -<constant>V4L2_VBI_UNSYNC</constant> is set.</para> - </footnote></para></entry> - </row> - <row> - <entry><constant>V4L2_VBI_INTERLACED</constant></entry> - <entry>0x0002</entry> - <entry>By default the two field images will be passed -sequentially; all lines of the first field followed by all lines of -the second field (compare <xref linkend="field-order" /> -<constant>V4L2_FIELD_SEQ_TB</constant> and -<constant>V4L2_FIELD_SEQ_BT</constant>, whether the top or bottom -field is first in memory depends on the video standard). When this -flag is set, the two fields are interlaced (cf. -<constant>V4L2_FIELD_INTERLACED</constant>). The first line of the -first field followed by the first line of the second field, then the -two second lines, and so on. Such a layout may be necessary when the -hardware has been programmed to capture or output interlaced video -images and is unable to separate the fields for VBI capturing at -the same time. For simplicity setting this flag implies that both -<structfield>count</structfield> values are equal and non-zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <figure id="vbi-hsync"> - <title>Line synchronization</title> - <mediaobject> - <imageobject> - <imagedata fileref="vbi_hsync.pdf" format="PS" /> - </imageobject> - <imageobject> - <imagedata fileref="vbi_hsync.gif" format="GIF" /> - </imageobject> - <textobject> - <phrase>Line synchronization diagram</phrase> - </textobject> - </mediaobject> - </figure> - - <figure id="vbi-525"> - <title>ITU-R 525 line numbering (M/NTSC and M/PAL)</title> - <mediaobject> - <imageobject> - <imagedata fileref="vbi_525.pdf" format="PS" /> - </imageobject> - <imageobject> - <imagedata fileref="vbi_525.gif" format="GIF" /> - </imageobject> - <textobject> - <phrase>NTSC field synchronization diagram</phrase> - </textobject> - <caption> - <para>(1) For the purpose of this specification field 2 -starts in line 264 and not 263.5 because half line capturing is not -supported.</para> - </caption> - </mediaobject> - </figure> - - <figure id="vbi-625"> - <title>ITU-R 625 line numbering</title> - <mediaobject> - <imageobject> - <imagedata fileref="vbi_625.pdf" format="PS" /> - </imageobject> - <imageobject> - <imagedata fileref="vbi_625.gif" format="GIF" /> - </imageobject> - <textobject> - <phrase>PAL/SECAM field synchronization diagram</phrase> - </textobject> - <caption> - <para>(1) For the purpose of this specification field 2 -starts in line 314 and not 313.5 because half line capturing is not -supported.</para> - </caption> - </mediaobject> - </figure> - - <para>Remember the VBI image format depends on the selected -video standard, therefore the application must choose a new standard or -query the current standard first. Attempts to read or write data ahead -of format negotiation, or after switching the video standard which may -invalidate the negotiated VBI parameters, should be refused by the -driver. A format change during active I/O is not permitted.</para> - </section> - - <section> - <title>Reading and writing VBI images</title> - - <para>To assure synchronization with the field number and easier -implementation, the smallest unit of data passed at a time is one -frame, consisting of two fields of VBI images immediately following in -memory.</para> - - <para>The total size of a frame computes as follows:</para> - - <programlisting> -(<structfield>count</structfield>[0] + <structfield>count</structfield>[1]) * -<structfield>samples_per_line</structfield> * sample size in bytes</programlisting> - - <para>The sample size is most likely always one byte, -applications must check the <structfield>sample_format</structfield> -field though, to function properly with other drivers.</para> - - <para>A VBI device may support <link - linkend="rw">read/write</link> and/or streaming (<link - linkend="mmap">memory mapping</link> or <link - linkend="userp">user pointer</link>) I/O. The latter bears the -possibility of synchronizing video and -VBI data by using buffer timestamps.</para> - - <para>Remember the &VIDIOC-STREAMON; ioctl and the first read(), -write() and select() call can be resource allocation points returning -an &EBUSY; if the required hardware resources are temporarily -unavailable, for example the device is already in use by another -process.</para> - </section> diff --git a/Documentation/DocBook/media/v4l/dev-rds.xml b/Documentation/DocBook/media/v4l/dev-rds.xml deleted file mode 100644 index be2f33737323..000000000000 --- a/Documentation/DocBook/media/v4l/dev-rds.xml +++ /dev/null @@ -1,196 +0,0 @@ - <title>RDS Interface</title> - - <para>The Radio Data System transmits supplementary -information in binary format, for example the station name or travel -information, on an inaudible audio subcarrier of a radio program. This -interface is aimed at devices capable of receiving and/or transmitting RDS -information.</para> - - <para>For more information see the core RDS standard <xref linkend="iec62106" /> -and the RBDS standard <xref linkend="nrsc4" />.</para> - - <para>Note that the RBDS standard as is used in the USA is almost identical -to the RDS standard. Any RDS decoder/encoder can also handle RBDS. Only some of the -fields have slightly different meanings. See the RBDS standard for more -information.</para> - - <para>The RBDS standard also specifies support for MMBS (Modified Mobile Search). -This is a proprietary format which seems to be discontinued. The RDS interface does not -support this format. Should support for MMBS (or the so-called 'E blocks' in general) -be needed, then please contact the linux-media mailing list: &v4l-ml;.</para> - - <section> - <title>Querying Capabilities</title> - - <para>Devices supporting the RDS capturing API set -the <constant>V4L2_CAP_RDS_CAPTURE</constant> flag in -the <structfield>capabilities</structfield> field of &v4l2-capability; -returned by the &VIDIOC-QUERYCAP; ioctl. Any tuner that supports RDS -will set the <constant>V4L2_TUNER_CAP_RDS</constant> flag in -the <structfield>capability</structfield> field of &v4l2-tuner;. If -the driver only passes RDS blocks without interpreting the data -the <constant>V4L2_TUNER_CAP_RDS_BLOCK_IO</constant> flag has to be -set, see <link linkend="reading-rds-data">Reading RDS data</link>. -For future use the -flag <constant>V4L2_TUNER_CAP_RDS_CONTROLS</constant> has also been -defined. However, a driver for a radio tuner with this capability does -not yet exist, so if you are planning to write such a driver you -should discuss this on the linux-media mailing list: &v4l-ml;.</para> - - <para> Whether an RDS signal is present can be detected by looking -at the <structfield>rxsubchans</structfield> field of &v4l2-tuner;: -the <constant>V4L2_TUNER_SUB_RDS</constant> will be set if RDS data -was detected.</para> - - <para>Devices supporting the RDS output API -set the <constant>V4L2_CAP_RDS_OUTPUT</constant> flag in -the <structfield>capabilities</structfield> field of &v4l2-capability; -returned by the &VIDIOC-QUERYCAP; ioctl. -Any modulator that supports RDS will set the -<constant>V4L2_TUNER_CAP_RDS</constant> flag in the <structfield>capability</structfield> -field of &v4l2-modulator;. -In order to enable the RDS transmission one must set the <constant>V4L2_TUNER_SUB_RDS</constant> -bit in the <structfield>txsubchans</structfield> field of &v4l2-modulator;. -If the driver only passes RDS blocks without interpreting the data -the <constant>V4L2_TUNER_CAP_RDS_BLOCK_IO</constant> flag has to be set. If the -tuner is capable of handling RDS entities like program identification codes and radio -text, the flag <constant>V4L2_TUNER_CAP_RDS_CONTROLS</constant> should be set, -see <link linkend="writing-rds-data">Writing RDS data</link> and -<link linkend="fm-tx-controls">FM Transmitter Control Reference</link>.</para> - </section> - - <section id="reading-rds-data"> - <title>Reading RDS data</title> - - <para>RDS data can be read from the radio device -with the &func-read; function. The data is packed in groups of three bytes.</para> - </section> - - <section id="writing-rds-data"> - <title>Writing RDS data</title> - - <para>RDS data can be written to the radio device -with the &func-write; function. The data is packed in groups of three bytes, -as follows:</para> - </section> - - <section> - <title>RDS datastructures</title> - <table frame="none" pgwide="1" id="v4l2-rds-data"> - <title>struct -<structname>v4l2_rds_data</structname></title> - <tgroup cols="3"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="1*" /> - <colspec colname="c3" colwidth="5*" /> - <tbody valign="top"> - <row> - <entry>__u8</entry> - <entry><structfield>lsb</structfield></entry> - <entry>Least Significant Byte of RDS Block</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>msb</structfield></entry> - <entry>Most Significant Byte of RDS Block</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>block</structfield></entry> - <entry>Block description</entry> - </row> - </tbody> - </tgroup> - </table> - <table frame="none" pgwide="1" id="v4l2-rds-block"> - <title>Block description</title> - <tgroup cols="2"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="5*" /> - <tbody valign="top"> - <row> - <entry>Bits 0-2</entry> - <entry>Block (aka offset) of the received data.</entry> - </row> - <row> - <entry>Bits 3-5</entry> - <entry>Deprecated. Currently identical to bits 0-2. Do not use these bits.</entry> - </row> - <row> - <entry>Bit 6</entry> - <entry>Corrected bit. Indicates that an error was corrected for this data block.</entry> - </row> - <row> - <entry>Bit 7</entry> - <entry>Error bit. Indicates that an uncorrectable error occurred during reception of this block.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="v4l2-rds-block-codes"> - <title>Block defines</title> - <tgroup cols="4"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="1*" /> - <colspec colname="c3" colwidth="1*" /> - <colspec colname="c4" colwidth="5*" /> - <tbody valign="top"> - <row> - <entry>V4L2_RDS_BLOCK_MSK</entry> - <entry> </entry> - <entry>7</entry> - <entry>Mask for bits 0-2 to get the block ID.</entry> - </row> - <row> - <entry>V4L2_RDS_BLOCK_A</entry> - <entry> </entry> - <entry>0</entry> - <entry>Block A.</entry> - </row> - <row> - <entry>V4L2_RDS_BLOCK_B</entry> - <entry> </entry> - <entry>1</entry> - <entry>Block B.</entry> - </row> - <row> - <entry>V4L2_RDS_BLOCK_C</entry> - <entry> </entry> - <entry>2</entry> - <entry>Block C.</entry> - </row> - <row> - <entry>V4L2_RDS_BLOCK_D</entry> - <entry> </entry> - <entry>3</entry> - <entry>Block D.</entry> - </row> - <row> - <entry>V4L2_RDS_BLOCK_C_ALT</entry> - <entry> </entry> - <entry>4</entry> - <entry>Block C'.</entry> - </row> - <row> - <entry>V4L2_RDS_BLOCK_INVALID</entry> - <entry>read-only</entry> - <entry>7</entry> - <entry>An invalid block.</entry> - </row> - <row> - <entry>V4L2_RDS_BLOCK_CORRECTED</entry> - <entry>read-only</entry> - <entry>0x40</entry> - <entry>A bit error was detected but corrected.</entry> - </row> - <row> - <entry>V4L2_RDS_BLOCK_ERROR</entry> - <entry>read-only</entry> - <entry>0x80</entry> - <entry>An uncorrectable error occurred.</entry> - </row> - </tbody> - </tgroup> - </table> - </section> diff --git a/Documentation/DocBook/media/v4l/dev-sdr.xml b/Documentation/DocBook/media/v4l/dev-sdr.xml deleted file mode 100644 index a659771f7b7c..000000000000 --- a/Documentation/DocBook/media/v4l/dev-sdr.xml +++ /dev/null @@ -1,132 +0,0 @@ - <title>Software Defined Radio Interface (SDR)</title> - - <note> - <title>Experimental</title> - <para>This is an <link linkend="experimental"> experimental </link> - interface and may change in the future.</para> - </note> - - <para> -SDR is an abbreviation of Software Defined Radio, the radio device -which uses application software for modulation or demodulation. This interface -is intended for controlling and data streaming of such devices. - </para> - - <para> -SDR devices are accessed through character device special files named -<filename>/dev/swradio0</filename> to <filename>/dev/swradio255</filename> -with major number 81 and dynamically allocated minor numbers 0 to 255. - </para> - - <section> - <title>Querying Capabilities</title> - - <para> -Devices supporting the SDR receiver interface set the -<constant>V4L2_CAP_SDR_CAPTURE</constant> and -<constant>V4L2_CAP_TUNER</constant> flag in the -<structfield>capabilities</structfield> field of &v4l2-capability; -returned by the &VIDIOC-QUERYCAP; ioctl. That flag means the device has an -Analog to Digital Converter (ADC), which is a mandatory element for the SDR receiver. - </para> - <para> -Devices supporting the SDR transmitter interface set the -<constant>V4L2_CAP_SDR_OUTPUT</constant> and -<constant>V4L2_CAP_MODULATOR</constant> flag in the -<structfield>capabilities</structfield> field of &v4l2-capability; -returned by the &VIDIOC-QUERYCAP; ioctl. That flag means the device has an -Digital to Analog Converter (DAC), which is a mandatory element for the SDR transmitter. - </para> - <para> -At least one of the read/write, streaming or asynchronous I/O methods must -be supported. - </para> - </section> - - <section> - <title>Supplemental Functions</title> - - <para> -SDR devices can support <link linkend="control">controls</link>, and must -support the <link linkend="tuner">tuner</link> ioctls. Tuner ioctls are used -for setting the ADC/DAC sampling rate (sampling frequency) and the possible -radio frequency (RF). - </para> - - <para> -The <constant>V4L2_TUNER_SDR</constant> tuner type is used for setting SDR -device ADC/DAC frequency, and the <constant>V4L2_TUNER_RF</constant> -tuner type is used for setting radio frequency. -The tuner index of the RF tuner (if any) must always follow the SDR tuner index. -Normally the SDR tuner is #0 and the RF tuner is #1. - </para> - - <para> -The &VIDIOC-S-HW-FREQ-SEEK; ioctl is not supported. - </para> - </section> - - <section> - <title>Data Format Negotiation</title> - - <para> -The SDR device uses the <link linkend="format">format</link> ioctls to -select the capture and output format. Both the sampling resolution and the data -streaming format are bound to that selectable format. In addition to the basic -<link linkend="format">format</link> ioctls, the &VIDIOC-ENUM-FMT; ioctl -must be supported as well. - </para> - - <para> -To use the <link linkend="format">format</link> ioctls applications set the -<structfield>type</structfield> field of a &v4l2-format; to -<constant>V4L2_BUF_TYPE_SDR_CAPTURE</constant> or -<constant>V4L2_BUF_TYPE_SDR_OUTPUT</constant> and use the &v4l2-sdr-format; -<structfield>sdr</structfield> member of the <structfield>fmt</structfield> -union as needed per the desired operation. -Currently there is two fields, <structfield>pixelformat</structfield> and -<structfield>buffersize</structfield>, of struct &v4l2-sdr-format; which are -used. Content of the <structfield>pixelformat</structfield> is V4L2 FourCC -code of the data format. The <structfield>buffersize</structfield> field is -maximum buffer size in bytes required for data transfer, set by the driver in -order to inform application. - </para> - - <table pgwide="1" frame="none" id="v4l2-sdr-format"> - <title>struct <structname>v4l2_sdr_format</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>pixelformat</structfield></entry> - <entry> -The data format or type of compression, set by the application. This is a -little endian <link linkend="v4l2-fourcc">four character code</link>. -V4L2 defines SDR formats in <xref linkend="sdr-formats" />. - </entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>buffersize</structfield></entry> - <entry> -Maximum size in bytes required for data. Value is set by the driver. - </entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>reserved[24]</structfield></entry> - <entry>This array is reserved for future extensions. -Drivers and applications must set it to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para> -An SDR device may support <link linkend="rw">read/write</link> -and/or streaming (<link linkend="mmap">memory mapping</link> -or <link linkend="userp">user pointer</link>) I/O. - </para> - - </section> diff --git a/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml b/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml deleted file mode 100644 index 0aec62ed2bf8..000000000000 --- a/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml +++ /dev/null @@ -1,706 +0,0 @@ - <title>Sliced VBI Data Interface</title> - - <para>VBI stands for Vertical Blanking Interval, a gap in the -sequence of lines of an analog video signal. During VBI no picture -information is transmitted, allowing some time while the electron beam -of a cathode ray tube TV returns to the top of the screen.</para> - - <para>Sliced VBI devices use hardware to demodulate data transmitted -in the VBI. V4L2 drivers shall <emphasis>not</emphasis> do this by -software, see also the <link linkend="raw-vbi">raw VBI -interface</link>. The data is passed as short packets of fixed size, -covering one scan line each. The number of packets per video frame is -variable.</para> - - <para>Sliced VBI capture and output devices are accessed through the -same character special files as raw VBI devices. When a driver -supports both interfaces, the default function of a -<filename>/dev/vbi</filename> device is <emphasis>raw</emphasis> VBI -capturing or output, and the sliced VBI function is only available -after calling the &VIDIOC-S-FMT; ioctl as defined below. Likewise a -<filename>/dev/video</filename> device may support the sliced VBI API, -however the default function here is video capturing or output. -Different file descriptors must be used to pass raw and sliced VBI -data simultaneously, if this is supported by the driver.</para> - - <section> - <title>Querying Capabilities</title> - - <para>Devices supporting the sliced VBI capturing or output API -set the <constant>V4L2_CAP_SLICED_VBI_CAPTURE</constant> or -<constant>V4L2_CAP_SLICED_VBI_OUTPUT</constant> flag respectively, in -the <structfield>capabilities</structfield> field of &v4l2-capability; -returned by the &VIDIOC-QUERYCAP; ioctl. At least one of the -read/write, streaming or asynchronous <link linkend="io">I/O -methods</link> must be supported. Sliced VBI devices may have a tuner -or modulator.</para> - </section> - - <section> - <title>Supplemental Functions</title> - - <para>Sliced VBI devices shall support <link linkend="video">video -input or output</link> and <link linkend="tuner">tuner or -modulator</link> ioctls if they have these capabilities, and they may -support <link linkend="control">control</link> ioctls. The <link -linkend="standard">video standard</link> ioctls provide information -vital to program a sliced VBI device, therefore must be -supported.</para> - </section> - - <section id="sliced-vbi-format-negotitation"> - <title>Sliced VBI Format Negotiation</title> - - <para>To find out which data services are supported by the -hardware applications can call the &VIDIOC-G-SLICED-VBI-CAP; ioctl. -All drivers implementing the sliced VBI interface must support this -ioctl. The results may differ from those of the &VIDIOC-S-FMT; ioctl -when the number of VBI lines the hardware can capture or output per -frame, or the number of services it can identify on a given line are -limited. For example on PAL line 16 the hardware may be able to look -for a VPS or Teletext signal, but not both at the same time.</para> - - <para>To determine the currently selected services applications -set the <structfield>type </structfield> field of &v4l2-format; to -<constant> V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> or <constant> -V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant>, and the &VIDIOC-G-FMT; -ioctl fills the <structfield>fmt.sliced</structfield> member, a -&v4l2-sliced-vbi-format;.</para> - - <para>Applications can request different parameters by -initializing or modifying the <structfield>fmt.sliced</structfield> -member and calling the &VIDIOC-S-FMT; ioctl with a pointer to the -<structname>v4l2_format</structname> structure.</para> - - <para>The sliced VBI API is more complicated than the raw VBI API -because the hardware must be told which VBI service to expect on each -scan line. Not all services may be supported by the hardware on all -lines (this is especially true for VBI output where Teletext is often -unsupported and other services can only be inserted in one specific -line). In many cases, however, it is sufficient to just set the -<structfield>service_set</structfield> field to the required services -and let the driver fill the <structfield>service_lines</structfield> -array according to hardware capabilities. Only if more precise control -is needed should the programmer set the -<structfield>service_lines</structfield> array explicitly.</para> - - <para>The &VIDIOC-S-FMT; ioctl modifies the parameters -according to hardware capabilities. When the driver allocates -resources at this point, it may return an &EBUSY; if the required -resources are temporarily unavailable. Other resource allocation -points which may return <errorcode>EBUSY</errorcode> can be the -&VIDIOC-STREAMON; ioctl and the first &func-read;, &func-write; and -&func-select; call.</para> - - <table frame="none" pgwide="1" id="v4l2-sliced-vbi-format"> - <title>struct -<structname>v4l2_sliced_vbi_format</structname></title> - <tgroup cols="5"> - <colspec colname="c1" colwidth="3*" /> - <colspec colname="c2" colwidth="3*" /> - <colspec colname="c3" colwidth="2*" /> - <colspec colname="c4" colwidth="2*" /> - <colspec colname="c5" colwidth="2*" /> - <spanspec namest="c3" nameend="c5" spanname="hspan" /> - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>service_set</structfield></entry> - <entry spanname="hspan"><para>If -<structfield>service_set</structfield> is non-zero when passed with -&VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;, the -<structfield>service_lines</structfield> array will be filled by the -driver according to the services specified in this field. For example, -if <structfield>service_set</structfield> is initialized with -<constant>V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625</constant>, a -driver for the cx25840 video decoder sets lines 7-22 of both -fields<footnote><para>According to <link -linkend="ets300706">ETS 300 706</link> lines 6-22 of the -first field and lines 5-22 of the second field may carry Teletext -data.</para></footnote> to <constant>V4L2_SLICED_TELETEXT_B</constant> -and line 23 of the first field to -<constant>V4L2_SLICED_WSS_625</constant>. If -<structfield>service_set</structfield> is set to zero, then the values -of <structfield>service_lines</structfield> will be used instead. -</para><para>On return the driver sets this field to the union of all -elements of the returned <structfield>service_lines</structfield> -array. It may contain less services than requested, perhaps just one, -if the hardware cannot handle more services simultaneously. It may be -empty (zero) if none of the requested services are supported by the -hardware.</para></entry> - </row> - <row> - <entry>__u16</entry> - <entry><structfield>service_lines</structfield>[2][24]</entry> - <entry spanname="hspan"><para>Applications initialize this -array with sets of data services the driver shall look for or insert -on the respective scan line. Subject to hardware capabilities drivers -return the requested set, a subset, which may be just a single -service, or an empty set. When the hardware cannot handle multiple -services on the same line the driver shall choose one. No assumptions -can be made on which service the driver chooses.</para><para>Data -services are defined in <xref linkend="vbi-services2" />. Array indices -map to ITU-R line numbers (see also <xref linkend="vbi-525" /> and <xref - linkend="vbi-625" />) as follows: <!-- No nested -tables, sigh. --></para></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>Element</entry> - <entry>525 line systems</entry> - <entry>625 line systems</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry><structfield>service_lines</structfield>[0][1]</entry> - <entry align="center">1</entry> - <entry align="center">1</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry><structfield>service_lines</structfield>[0][23]</entry> - <entry align="center">23</entry> - <entry align="center">23</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry><structfield>service_lines</structfield>[1][1]</entry> - <entry align="center">264</entry> - <entry align="center">314</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry><structfield>service_lines</structfield>[1][23]</entry> - <entry align="center">286</entry> - <entry align="center">336</entry> - </row> - <!-- End of line numbers table. --> - <row> - <entry></entry> - <entry></entry> - <entry spanname="hspan">Drivers must set -<structfield>service_lines</structfield>[0][0] and -<structfield>service_lines</structfield>[1][0] to zero. -The <constant>V4L2_VBI_ITU_525_F1_START</constant>, -<constant>V4L2_VBI_ITU_525_F2_START</constant>, -<constant>V4L2_VBI_ITU_625_F1_START</constant> and -<constant>V4L2_VBI_ITU_625_F2_START</constant> defines give the start -line numbers for each field for each 525 or 625 line format as a -convenience. Don't forget that ITU line numbering starts at 1, not 0. -</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>io_size</structfield></entry> - <entry spanname="hspan">Maximum number of bytes passed by -one &func-read; or &func-write; call, and the buffer size in bytes for -the &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. Drivers set this field to -the size of &v4l2-sliced-vbi-data; times the number of non-zero -elements in the returned <structfield>service_lines</structfield> -array (that is the number of lines potentially carrying data).</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[2]</entry> - <entry spanname="hspan">This array is reserved for future -extensions. Applications and drivers must set it to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <!-- See also vidioc-g-sliced-vbi-cap.sgml --> - <table frame="none" pgwide="1" id="vbi-services2"> - <title>Sliced VBI services</title> - <tgroup cols="5"> - <colspec colname="c1" colwidth="2*" /> - <colspec colname="c2" colwidth="1*" /> - <colspec colname="c3" colwidth="1*" /> - <colspec colname="c4" colwidth="2*" /> - <colspec colname="c5" colwidth="2*" /> - <spanspec namest="c3" nameend="c5" spanname="rlp" /> - <thead> - <row> - <entry>Symbol</entry> - <entry>Value</entry> - <entry>Reference</entry> - <entry>Lines, usually</entry> - <entry>Payload</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry><constant>V4L2_SLICED_TELETEXT_B</constant> -(Teletext System B)</entry> - <entry>0x0001</entry> - <entry><xref linkend="ets300706" />, <xref linkend="itu653" /></entry> - <entry>PAL/SECAM line 7-22, 320-335 (second field 7-22)</entry> - <entry>Last 42 of the 45 byte Teletext packet, that is -without clock run-in and framing code, lsb first transmitted.</entry> - </row> - <row> - <entry><constant>V4L2_SLICED_VPS</constant></entry> - <entry>0x0400</entry> - <entry><xref linkend="ets300231" /></entry> - <entry>PAL line 16</entry> - <entry>Byte number 3 to 15 according to Figure 9 of -ETS 300 231, lsb first transmitted.</entry> - </row> - <row> - <entry><constant>V4L2_SLICED_CAPTION_525</constant></entry> - <entry>0x1000</entry> - <entry><xref linkend="cea608" /></entry> - <entry>NTSC line 21, 284 (second field 21)</entry> - <entry>Two bytes in transmission order, including parity -bit, lsb first transmitted.</entry> - </row> - <row> - <entry><constant>V4L2_SLICED_WSS_625</constant></entry> - <entry>0x4000</entry> - <entry><xref linkend="itu1119" />, <xref linkend="en300294" /></entry> - <entry>PAL/SECAM line 23</entry> - <entry><screen> -Byte 0 1 - msb lsb msb lsb - Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9 -</screen></entry> - </row> - <row> - <entry><constant>V4L2_SLICED_VBI_525</constant></entry> - <entry>0x1000</entry> - <entry spanname="rlp">Set of services applicable to 525 -line systems.</entry> - </row> - <row> - <entry><constant>V4L2_SLICED_VBI_625</constant></entry> - <entry>0x4401</entry> - <entry spanname="rlp">Set of services applicable to 625 -line systems.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>Drivers may return an &EINVAL; when applications attempt to -read or write data without prior format negotiation, after switching -the video standard (which may invalidate the negotiated VBI -parameters) and after switching the video input (which may change the -video standard as a side effect). The &VIDIOC-S-FMT; ioctl may return -an &EBUSY; when applications attempt to change the format while i/o is -in progress (between a &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; call, -and after the first &func-read; or &func-write; call).</para> - </section> - - <section> - <title>Reading and writing sliced VBI data</title> - - <para>A single &func-read; or &func-write; call must pass all data -belonging to one video frame. That is an array of -<structname>v4l2_sliced_vbi_data</structname> structures with one or -more elements and a total size not exceeding -<structfield>io_size</structfield> bytes. Likewise in streaming I/O -mode one buffer of <structfield>io_size</structfield> bytes must -contain data of one video frame. The <structfield>id</structfield> of -unused <structname>v4l2_sliced_vbi_data</structname> elements must be -zero.</para> - - <table frame="none" pgwide="1" id="v4l2-sliced-vbi-data"> - <title>struct -<structname>v4l2_sliced_vbi_data</structname></title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>id</structfield></entry> - <entry>A flag from <xref linkend="vbi-services" /> -identifying the type of data in this packet. Only a single bit must be -set. When the <structfield>id</structfield> of a captured packet is -zero, the packet is empty and the contents of other fields are -undefined. Applications shall ignore empty packets. When the -<structfield>id</structfield> of a packet for output is zero the -contents of the <structfield>data</structfield> field are undefined -and the driver must no longer insert data on the requested -<structfield>field</structfield> and -<structfield>line</structfield>.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>field</structfield></entry> - <entry>The video field number this data has been captured -from, or shall be inserted at. <constant>0</constant> for the first -field, <constant>1</constant> for the second field.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>line</structfield></entry> - <entry>The field (as opposed to frame) line number this -data has been captured from, or shall be inserted at. See <xref - linkend="vbi-525" /> and <xref linkend="vbi-625" /> for valid -values. Sliced VBI capture devices can set the line number of all -packets to <constant>0</constant> if the hardware cannot reliably -identify scan lines. The field number must always be valid.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield></entry> - <entry>This field is reserved for future extensions. -Applications and drivers must set it to zero.</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>data</structfield>[48]</entry> - <entry>The packet payload. See <xref - linkend="vbi-services" /> for the contents and number of -bytes passed for each data type. The contents of padding bytes at the -end of this array are undefined, drivers and applications shall ignore -them.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>Packets are always passed in ascending line number order, -without duplicate line numbers. The &func-write; function and the -&VIDIOC-QBUF; ioctl must return an &EINVAL; when applications violate -this rule. They must also return an &EINVAL; when applications pass an -incorrect field or line number, or a combination of -<structfield>field</structfield>, <structfield>line</structfield> and -<structfield>id</structfield> which has not been negotiated with the -&VIDIOC-G-FMT; or &VIDIOC-S-FMT; ioctl. When the line numbers are -unknown the driver must pass the packets in transmitted order. The -driver can insert empty packets with <structfield>id</structfield> set -to zero anywhere in the packet array.</para> - - <para>To assure synchronization and to distinguish from frame -dropping, when a captured frame does not carry any of the requested -data services drivers must pass one or more empty packets. When an -application fails to pass VBI data in time for output, the driver -must output the last VPS and WSS packet again, and disable the output -of Closed Caption and Teletext data, or output data which is ignored -by Closed Caption and Teletext decoders.</para> - - <para>A sliced VBI device may support <link -linkend="rw">read/write</link> and/or streaming (<link -linkend="mmap">memory mapping</link> and/or <link linkend="userp">user -pointer</link>) I/O. The latter bears the possibility of synchronizing -video and VBI data by using buffer timestamps.</para> - - </section> - - <section> - <title>Sliced VBI Data in MPEG Streams</title> - - <para>If a device can produce an MPEG output stream, it may be -capable of providing <link -linkend="sliced-vbi-format-negotitation">negotiated sliced VBI -services</link> as data embedded in the MPEG stream. Users or -applications control this sliced VBI data insertion with the <link -linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link> -control.</para> - - <para>If the driver does not provide the <link -linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link> -control, or only allows that control to be set to <link -linkend="v4l2-mpeg-stream-vbi-fmt"><constant> -V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link>, then the device -cannot embed sliced VBI data in the MPEG stream.</para> - - <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"> -V4L2_CID_MPEG_STREAM_VBI_FMT</link> control does not implicitly set -the device driver to capture nor cease capturing sliced VBI data. The -control only indicates to embed sliced VBI data in the MPEG stream, if -an application has negotiated sliced VBI service be captured.</para> - - <para>It may also be the case that a device can embed sliced VBI -data in only certain types of MPEG streams: for example in an MPEG-2 -PS but not an MPEG-2 TS. In this situation, if sliced VBI data -insertion is requested, the sliced VBI data will be embedded in MPEG -stream types when supported, and silently omitted from MPEG stream -types where sliced VBI data insertion is not supported by the device. -</para> - - <para>The following subsections specify the format of the -embedded sliced VBI data.</para> - - <section> - <title>MPEG Stream Embedded, Sliced VBI Data Format: NONE</title> - <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant> -V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link> embedded sliced VBI -format shall be interpreted by drivers as a control to cease -embedding sliced VBI data in MPEG streams. Neither the device nor -driver shall insert "empty" embedded sliced VBI data packets in the -MPEG stream when this format is set. No MPEG stream data structures -are specified for this format.</para> - </section> - - <section> - <title>MPEG Stream Embedded, Sliced VBI Data Format: IVTV</title> - <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant> -V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> embedded sliced VBI -format, when supported, indicates to the driver to embed up to 36 -lines of sliced VBI data per frame in an MPEG-2 <emphasis>Private -Stream 1 PES</emphasis> packet encapsulated in an MPEG-2 <emphasis> -Program Pack</emphasis> in the MPEG stream.</para> - - <para><emphasis>Historical context</emphasis>: This format -specification originates from a custom, embedded, sliced VBI data -format used by the <filename>ivtv</filename> driver. This format -has already been informally specified in the kernel sources in the -file <filename>Documentation/video4linux/cx2341x/README.vbi</filename> -. The maximum size of the payload and other aspects of this format -are driven by the CX23415 MPEG decoder's capabilities and limitations -with respect to extracting, decoding, and displaying sliced VBI data -embedded within an MPEG stream.</para> - - <para>This format's use is <emphasis>not</emphasis> exclusive to -the <filename>ivtv</filename> driver <emphasis>nor</emphasis> -exclusive to CX2341x devices, as the sliced VBI data packet insertion -into the MPEG stream is implemented in driver software. At least the -<filename>cx18</filename> driver provides sliced VBI data insertion -into an MPEG-2 PS in this format as well.</para> - - <para>The following definitions specify the payload of the -MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packets that contain -sliced VBI data when <link linkend="v4l2-mpeg-stream-vbi-fmt"> -<constant>V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> is set. -(The MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packet header -and encapsulating MPEG-2 <emphasis>Program Pack</emphasis> header are -not detailed here. Please refer to the MPEG-2 specifications for -details on those packet headers.)</para> - - <para>The payload of the MPEG-2 <emphasis>Private Stream 1 PES -</emphasis> packets that contain sliced VBI data is specified by -&v4l2-mpeg-vbi-fmt-ivtv;. The payload is variable -length, depending on the actual number of lines of sliced VBI data -present in a video frame. The payload may be padded at the end with -unspecified fill bytes to align the end of the payload to a 4-byte -boundary. The payload shall never exceed 1552 bytes (2 fields with -18 lines/field with 43 bytes of data/line and a 4 byte magic number). -</para> - - <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv"> - <title>struct <structname>v4l2_mpeg_vbi_fmt_ivtv</structname> - </title> - <tgroup cols="4"> - &cs-ustr; - <tbody valign="top"> - <row> - <entry>__u8</entry> - <entry><structfield>magic</structfield>[4]</entry> - <entry></entry> - <entry>A "magic" constant from <xref - linkend="v4l2-mpeg-vbi-fmt-ivtv-magic" /> that indicates -this is a valid sliced VBI data payload and also indicates which -member of the anonymous union, <structfield>itv0</structfield> or -<structfield>ITV0</structfield>, to use for the payload data.</entry> - </row> - <row> - <entry>union</entry> - <entry>(anonymous)</entry> - </row> - <row> - <entry></entry> - <entry>struct <link linkend="v4l2-mpeg-vbi-itv0"> - <structname>v4l2_mpeg_vbi_itv0</structname></link> - </entry> - <entry><structfield>itv0</structfield></entry> - <entry>The primary form of the sliced VBI data payload -that contains anywhere from 1 to 35 lines of sliced VBI data. -Line masks are provided in this form of the payload indicating -which VBI lines are provided.</entry> - </row> - <row> - <entry></entry> - <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-1"> - <structname>v4l2_mpeg_vbi_ITV0</structname></link> - </entry> - <entry><structfield>ITV0</structfield></entry> - <entry>An alternate form of the sliced VBI data payload -used when 36 lines of sliced VBI data are present. No line masks are -provided in this form of the payload; all valid line mask bits are -implcitly set.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv-magic"> - <title>Magic Constants for &v4l2-mpeg-vbi-fmt-ivtv; - <structfield>magic</structfield> field</title> - <tgroup cols="3"> - &cs-def; - <thead> - <row> - <entry align="left">Defined Symbol</entry> - <entry align="left">Value</entry> - <entry align="left">Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC0</constant> - </entry> - <entry>"itv0"</entry> - <entry>Indicates the <structfield>itv0</structfield> -member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC1</constant> - </entry> - <entry>"ITV0"</entry> - <entry>Indicates the <structfield>ITV0</structfield> -member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid and -that 36 lines of sliced VBI data are present.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0"> - <title>struct <structname>v4l2_mpeg_vbi_itv0</structname> - </title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__le32</entry> - <entry><structfield>linemask</structfield>[2]</entry> - <entry><para>Bitmasks indicating the VBI service lines -present. These <structfield>linemask</structfield> values are stored -in little endian byte order in the MPEG stream. Some reference -<structfield>linemask</structfield> bit positions with their -corresponding VBI line number and video field are given below. -b<subscript>0</subscript> indicates the least significant bit of a -<structfield>linemask</structfield> value:<screen> -<structfield>linemask</structfield>[0] b<subscript>0</subscript>: line 6 first field -<structfield>linemask</structfield>[0] b<subscript>17</subscript>: line 23 first field -<structfield>linemask</structfield>[0] b<subscript>18</subscript>: line 6 second field -<structfield>linemask</structfield>[0] b<subscript>31</subscript>: line 19 second field -<structfield>linemask</structfield>[1] b<subscript>0</subscript>: line 20 second field -<structfield>linemask</structfield>[1] b<subscript>3</subscript>: line 23 second field -<structfield>linemask</structfield>[1] b<subscript>4</subscript>-b<subscript>31</subscript>: unused and set to 0</screen></para></entry> - </row> - <row> - <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line"> - <structname>v4l2_mpeg_vbi_itv0_line</structname></link> - </entry> - <entry><structfield>line</structfield>[35]</entry> - <entry>This is a variable length array that holds from 1 -to 35 lines of sliced VBI data. The sliced VBI data lines present -correspond to the bits set in the <structfield>linemask</structfield> -array, starting from b<subscript>0</subscript> of <structfield> -linemask</structfield>[0] up through b<subscript>31</subscript> of -<structfield>linemask</structfield>[0], and from b<subscript>0 -</subscript> of <structfield>linemask</structfield>[1] up through b -<subscript>3</subscript> of <structfield>linemask</structfield>[1]. -<structfield>line</structfield>[0] corresponds to the first bit -found set in the <structfield>linemask</structfield> array, -<structfield>line</structfield>[1] corresponds to the second bit -found set in the <structfield>linemask</structfield> array, etc. -If no <structfield>linemask</structfield> array bits are set, then -<structfield>line</structfield>[0] may contain one line of -unspecified data that should be ignored by applications.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-1"> - <title>struct <structname>v4l2_mpeg_vbi_ITV0</structname> - </title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line"> - <structname>v4l2_mpeg_vbi_itv0_line</structname></link> - </entry> - <entry><structfield>line</structfield>[36]</entry> - <entry>A fixed length array of 36 lines of sliced VBI -data. <structfield>line</structfield>[0] through <structfield>line -</structfield>[17] correspond to lines 6 through 23 of the -first field. <structfield>line</structfield>[18] through -<structfield>line</structfield>[35] corresponds to lines 6 -through 23 of the second field.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-line"> - <title>struct <structname>v4l2_mpeg_vbi_itv0_line</structname> - </title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u8</entry> - <entry><structfield>id</structfield></entry> - <entry>A line identifier value from -<xref linkend="ITV0-Line-Identifier-Constants" /> that indicates -the type of sliced VBI data stored on this line.</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>data</structfield>[42]</entry> - <entry>The sliced VBI data for the line.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="ITV0-Line-Identifier-Constants"> - <title>Line Identifiers for struct <link - linkend="v4l2-mpeg-vbi-itv0-line"><structname> -v4l2_mpeg_vbi_itv0_line</structname></link> <structfield>id -</structfield> field</title> - <tgroup cols="3"> - &cs-def; - <thead> - <row> - <entry align="left">Defined Symbol</entry> - <entry align="left">Value</entry> - <entry align="left">Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry><constant>V4L2_MPEG_VBI_IVTV_TELETEXT_B</constant> - </entry> - <entry>1</entry> - <entry>Refer to <link linkend="vbi-services2"> -Sliced VBI services</link> for a description of the line payload.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VBI_IVTV_CAPTION_525</constant> - </entry> - <entry>4</entry> - <entry>Refer to <link linkend="vbi-services2"> -Sliced VBI services</link> for a description of the line payload.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VBI_IVTV_WSS_625</constant> - </entry> - <entry>5</entry> - <entry>Refer to <link linkend="vbi-services2"> -Sliced VBI services</link> for a description of the line payload.</entry> - </row> - <row> - <entry><constant>V4L2_MPEG_VBI_IVTV_VPS</constant> - </entry> - <entry>7</entry> - <entry>Refer to <link linkend="vbi-services2"> -Sliced VBI services</link> for a description of the line payload.</entry> - </row> - </tbody> - </tgroup> - </table> - - </section> - </section> diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml deleted file mode 100644 index 4f0ba58c9bd9..000000000000 --- a/Documentation/DocBook/media/v4l/dev-subdev.xml +++ /dev/null @@ -1,484 +0,0 @@ - <title>Sub-device Interface</title> - - <note> - <title>Experimental</title> - <para>This is an <link linkend="experimental">experimental</link> - interface and may change in the future.</para> - </note> - - <para>The complex nature of V4L2 devices, where hardware is often made of - several integrated circuits that need to interact with each other in a - controlled way, leads to complex V4L2 drivers. The drivers usually reflect - the hardware model in software, and model the different hardware components - as software blocks called sub-devices.</para> - - <para>V4L2 sub-devices are usually kernel-only objects. If the V4L2 driver - implements the media device API, they will automatically inherit from media - entities. Applications will be able to enumerate the sub-devices and discover - the hardware topology using the media entities, pads and links enumeration - API.</para> - - <para>In addition to make sub-devices discoverable, drivers can also choose - to make them directly configurable by applications. When both the sub-device - driver and the V4L2 device driver support this, sub-devices will feature a - character device node on which ioctls can be called to - <itemizedlist> - <listitem><para>query, read and write sub-devices controls</para></listitem> - <listitem><para>subscribe and unsubscribe to events and retrieve them</para></listitem> - <listitem><para>negotiate image formats on individual pads</para></listitem> - </itemizedlist> - </para> - - <para>Sub-device character device nodes, conventionally named - <filename>/dev/v4l-subdev*</filename>, use major number 81.</para> - - <section> - <title>Controls</title> - <para>Most V4L2 controls are implemented by sub-device hardware. Drivers - usually merge all controls and expose them through video device nodes. - Applications can control all sub-devices through a single interface.</para> - - <para>Complex devices sometimes implement the same control in different - pieces of hardware. This situation is common in embedded platforms, where - both sensors and image processing hardware implement identical functions, - such as contrast adjustment, white balance or faulty pixels correction. As - the V4L2 controls API doesn't support several identical controls in a single - device, all but one of the identical controls are hidden.</para> - - <para>Applications can access those hidden controls through the sub-device - node with the V4L2 control API described in <xref linkend="control" />. The - ioctls behave identically as when issued on V4L2 device nodes, with the - exception that they deal only with controls implemented in the sub-device. - </para> - - <para>Depending on the driver, those controls might also be exposed through - one (or several) V4L2 device nodes.</para> - </section> - - <section> - <title>Events</title> - <para>V4L2 sub-devices can notify applications of events as described in - <xref linkend="event" />. The API behaves identically as when used on V4L2 - device nodes, with the exception that it only deals with events generated by - the sub-device. Depending on the driver, those events might also be reported - on one (or several) V4L2 device nodes.</para> - </section> - - <section id="pad-level-formats"> - <title>Pad-level Formats</title> - - <warning><para>Pad-level formats are only applicable to very complex device that - need to expose low-level format configuration to user space. Generic V4L2 - applications do <emphasis>not</emphasis> need to use the API described in - this section.</para></warning> - - <note><para>For the purpose of this section, the term - <wordasword>format</wordasword> means the combination of media bus data - format, frame width and frame height.</para></note> - - <para>Image formats are typically negotiated on video capture and - output devices using the format and <link - linkend="vidioc-subdev-g-selection">selection</link> ioctls. The - driver is responsible for configuring every block in the video - pipeline according to the requested format at the pipeline input - and/or output.</para> - - <para>For complex devices, such as often found in embedded systems, - identical image sizes at the output of a pipeline can be achieved using - different hardware configurations. One such example is shown on - <xref linkend="pipeline-scaling" />, where - image scaling can be performed on both the video sensor and the host image - processing hardware.</para> - - <figure id="pipeline-scaling"> - <title>Image Format Negotiation on Pipelines</title> - <mediaobject> - <imageobject> - <imagedata fileref="pipeline.pdf" format="PS" /> - </imageobject> - <imageobject> - <imagedata fileref="pipeline.png" format="PNG" /> - </imageobject> - <textobject> - <phrase>High quality and high speed pipeline configuration</phrase> - </textobject> - </mediaobject> - </figure> - - <para>The sensor scaler is usually of less quality than the host scaler, but - scaling on the sensor is required to achieve higher frame rates. Depending - on the use case (quality vs. speed), the pipeline must be configured - differently. Applications need to configure the formats at every point in - the pipeline explicitly.</para> - - <para>Drivers that implement the <link linkend="media-controller-intro">media - API</link> can expose pad-level image format configuration to applications. - When they do, applications can use the &VIDIOC-SUBDEV-G-FMT; and - &VIDIOC-SUBDEV-S-FMT; ioctls. to negotiate formats on a per-pad basis.</para> - - <para>Applications are responsible for configuring coherent parameters on - the whole pipeline and making sure that connected pads have compatible - formats. The pipeline is checked for formats mismatch at &VIDIOC-STREAMON; - time, and an &EPIPE; is then returned if the configuration is - invalid.</para> - - <para>Pad-level image format configuration support can be tested by calling - the &VIDIOC-SUBDEV-G-FMT; ioctl on pad 0. If the driver returns an &EINVAL; - pad-level format configuration is not supported by the sub-device.</para> - - <section> - <title>Format Negotiation</title> - - <para>Acceptable formats on pads can (and usually do) depend on a number - of external parameters, such as formats on other pads, active links, or - even controls. Finding a combination of formats on all pads in a video - pipeline, acceptable to both application and driver, can't rely on formats - enumeration only. A format negotiation mechanism is required.</para> - - <para>Central to the format negotiation mechanism are the get/set format - operations. When called with the <structfield>which</structfield> argument - set to <constant>V4L2_SUBDEV_FORMAT_TRY</constant>, the - &VIDIOC-SUBDEV-G-FMT; and &VIDIOC-SUBDEV-S-FMT; ioctls operate on a set of - formats parameters that are not connected to the hardware configuration. - Modifying those 'try' formats leaves the device state untouched (this - applies to both the software state stored in the driver and the hardware - state stored in the device itself).</para> - - <para>While not kept as part of the device state, try formats are stored - in the sub-device file handles. A &VIDIOC-SUBDEV-G-FMT; call will return - the last try format set <emphasis>on the same sub-device file - handle</emphasis>. Several applications querying the same sub-device at - the same time will thus not interact with each other.</para> - - <para>To find out whether a particular format is supported by the device, - applications use the &VIDIOC-SUBDEV-S-FMT; ioctl. Drivers verify and, if - needed, change the requested <structfield>format</structfield> based on - device requirements and return the possibly modified value. Applications - can then choose to try a different format or accept the returned value and - continue.</para> - - <para>Formats returned by the driver during a negotiation iteration are - guaranteed to be supported by the device. In particular, drivers guarantee - that a returned format will not be further changed if passed to an - &VIDIOC-SUBDEV-S-FMT; call as-is (as long as external parameters, such as - formats on other pads or links' configuration are not changed).</para> - - <para>Drivers automatically propagate formats inside sub-devices. When a - try or active format is set on a pad, corresponding formats on other pads - of the same sub-device can be modified by the driver. Drivers are free to - modify formats as required by the device. However, they should comply with - the following rules when possible: - <itemizedlist> - <listitem><para>Formats should be propagated from sink pads to source pads. - Modifying a format on a source pad should not modify the format on any - sink pad.</para></listitem> - <listitem><para>Sub-devices that scale frames using variable scaling factors - should reset the scale factors to default values when sink pads formats - are modified. If the 1:1 scaling ratio is supported, this means that - source pads formats should be reset to the sink pads formats.</para></listitem> - </itemizedlist> - </para> - - <para>Formats are not propagated across links, as that would involve - propagating them from one sub-device file handle to another. Applications - must then take care to configure both ends of every link explicitly with - compatible formats. Identical formats on the two ends of a link are - guaranteed to be compatible. Drivers are free to accept different formats - matching device requirements as being compatible.</para> - - <para><xref linkend="sample-pipeline-config" /> - shows a sample configuration sequence for the pipeline described in - <xref linkend="pipeline-scaling" /> (table - columns list entity names and pad numbers).</para> - - <table pgwide="0" frame="none" id="sample-pipeline-config"> - <title>Sample Pipeline Configuration</title> - <tgroup cols="3"> - <colspec colname="what"/> - <colspec colname="sensor-0 format" /> - <colspec colname="frontend-0 format" /> - <colspec colname="frontend-1 format" /> - <colspec colname="scaler-0 format" /> - <colspec colname="scaler-0 compose" /> - <colspec colname="scaler-1 format" /> - <thead> - <row> - <entry></entry> - <entry>Sensor/0 format</entry> - <entry>Frontend/0 format</entry> - <entry>Frontend/1 format</entry> - <entry>Scaler/0 format</entry> - <entry>Scaler/0 compose selection rectangle</entry> - <entry>Scaler/1 format</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry>Initial state</entry> - <entry>2048x1536/SGRBG8_1X8</entry> - <entry>(default)</entry> - <entry>(default)</entry> - <entry>(default)</entry> - <entry>(default)</entry> - <entry>(default)</entry> - </row> - <row> - <entry>Configure frontend sink format</entry> - <entry>2048x1536/SGRBG8_1X8</entry> - <entry><emphasis>2048x1536/SGRBG8_1X8</emphasis></entry> - <entry><emphasis>2046x1534/SGRBG8_1X8</emphasis></entry> - <entry>(default)</entry> - <entry>(default)</entry> - <entry>(default)</entry> - </row> - <row> - <entry>Configure scaler sink format</entry> - <entry>2048x1536/SGRBG8_1X8</entry> - <entry>2048x1536/SGRBG8_1X8</entry> - <entry>2046x1534/SGRBG8_1X8</entry> - <entry><emphasis>2046x1534/SGRBG8_1X8</emphasis></entry> - <entry><emphasis>0,0/2046x1534</emphasis></entry> - <entry><emphasis>2046x1534/SGRBG8_1X8</emphasis></entry> - </row> - <row> - <entry>Configure scaler sink compose selection</entry> - <entry>2048x1536/SGRBG8_1X8</entry> - <entry>2048x1536/SGRBG8_1X8</entry> - <entry>2046x1534/SGRBG8_1X8</entry> - <entry>2046x1534/SGRBG8_1X8</entry> - <entry><emphasis>0,0/1280x960</emphasis></entry> - <entry><emphasis>1280x960/SGRBG8_1X8</emphasis></entry> - </row> - </tbody> - </tgroup> - </table> - - <para> - <orderedlist> - <listitem><para>Initial state. The sensor source pad format is - set to its native 3MP size and V4L2_MBUS_FMT_SGRBG8_1X8 - media bus code. Formats on the host frontend and scaler sink - and source pads have the default values, as well as the - compose rectangle on the scaler's sink pad.</para></listitem> - - <listitem><para>The application configures the frontend sink - pad format's size to 2048x1536 and its media bus code to - V4L2_MBUS_FMT_SGRBG_1X8. The driver propagates the format to - the frontend source pad.</para></listitem> - - <listitem><para>The application configures the scaler sink pad - format's size to 2046x1534 and the media bus code to - V4L2_MBUS_FMT_SGRBG_1X8 to match the frontend source size and - media bus code. The media bus code on the sink pad is set to - V4L2_MBUS_FMT_SGRBG_1X8. The driver propagates the size to the - compose selection rectangle on the scaler's sink pad, and the - format to the scaler source pad.</para></listitem> - - <listitem><para>The application configures the size of the compose - selection rectangle of the scaler's sink pad 1280x960. The driver - propagates the size to the scaler's source pad - format.</para></listitem> - - </orderedlist> - </para> - - <para>When satisfied with the try results, applications can set the active - formats by setting the <structfield>which</structfield> argument to - <constant>V4L2_SUBDEV_FORMAT_ACTIVE</constant>. Active formats are changed - exactly as try formats by drivers. To avoid modifying the hardware state - during format negotiation, applications should negotiate try formats first - and then modify the active settings using the try formats returned during - the last negotiation iteration. This guarantees that the active format - will be applied as-is by the driver without being modified. - </para> - </section> - - <section id="v4l2-subdev-selections"> - <title>Selections: cropping, scaling and composition</title> - - <para>Many sub-devices support cropping frames on their input or output - pads (or possible even on both). Cropping is used to select the area of - interest in an image, typically on an image sensor or a video decoder. It can - also be used as part of digital zoom implementations to select the area of - the image that will be scaled up.</para> - - <para>Crop settings are defined by a crop rectangle and represented in a - &v4l2-rect; by the coordinates of the top left corner and the rectangle - size. Both the coordinates and sizes are expressed in pixels.</para> - - <para>As for pad formats, drivers store try and active - rectangles for the selection targets <xref - linkend="v4l2-selections-common" />.</para> - - <para>On sink pads, cropping is applied relative to the - current pad format. The pad format represents the image size as - received by the sub-device from the previous block in the - pipeline, and the crop rectangle represents the sub-image that - will be transmitted further inside the sub-device for - processing.</para> - - <para>The scaling operation changes the size of the image by - scaling it to new dimensions. The scaling ratio isn't specified - explicitly, but is implied from the original and scaled image - sizes. Both sizes are represented by &v4l2-rect;.</para> - - <para>Scaling support is optional. When supported by a subdev, - the crop rectangle on the subdev's sink pad is scaled to the - size configured using the &VIDIOC-SUBDEV-S-SELECTION; IOCTL - using <constant>V4L2_SEL_TGT_COMPOSE</constant> - selection target on the same pad. If the subdev supports scaling - but not composing, the top and left values are not used and must - always be set to zero.</para> - - <para>On source pads, cropping is similar to sink pads, with the - exception that the source size from which the cropping is - performed, is the COMPOSE rectangle on the sink pad. In both - sink and source pads, the crop rectangle must be entirely - contained inside the source image size for the crop - operation.</para> - - <para>The drivers should always use the closest possible - rectangle the user requests on all selection targets, unless - specifically told otherwise. - <constant>V4L2_SEL_FLAG_GE</constant> and - <constant>V4L2_SEL_FLAG_LE</constant> flags may be - used to round the image size either up or down. <xref - linkend="v4l2-selection-flags" /></para> - </section> - - <section> - <title>Types of selection targets</title> - - <section> - <title>Actual targets</title> - - <para>Actual targets (without a postfix) reflect the actual - hardware configuration at any point of time. There is a BOUNDS - target corresponding to every actual target.</para> - </section> - - <section> - <title>BOUNDS targets</title> - - <para>BOUNDS targets is the smallest rectangle that contains all - valid actual rectangles. It may not be possible to set the actual - rectangle as large as the BOUNDS rectangle, however. This may be - because e.g. a sensor's pixel array is not rectangular but - cross-shaped or round. The maximum size may also be smaller than the - BOUNDS rectangle.</para> - </section> - - </section> - - <section> - <title>Order of configuration and format propagation</title> - - <para>Inside subdevs, the order of image processing steps will - always be from the sink pad towards the source pad. This is also - reflected in the order in which the configuration must be - performed by the user: the changes made will be propagated to - any subsequent stages. If this behaviour is not desired, the - user must set - <constant>V4L2_SEL_FLAG_KEEP_CONFIG</constant> flag. This - flag causes no propagation of the changes are allowed in any - circumstances. This may also cause the accessed rectangle to be - adjusted by the driver, depending on the properties of the - underlying hardware.</para> - - <para>The coordinates to a step always refer to the actual size - of the previous step. The exception to this rule is the source - compose rectangle, which refers to the sink compose bounds - rectangle --- if it is supported by the hardware.</para> - - <orderedlist> - <listitem><para>Sink pad format. The user configures the sink pad - format. This format defines the parameters of the image the - entity receives through the pad for further processing.</para></listitem> - - <listitem><para>Sink pad actual crop selection. The sink pad crop - defines the crop performed to the sink pad format.</para></listitem> - - <listitem><para>Sink pad actual compose selection. The size of the - sink pad compose rectangle defines the scaling ratio compared - to the size of the sink pad crop rectangle. The location of - the compose rectangle specifies the location of the actual - sink compose rectangle in the sink compose bounds - rectangle.</para></listitem> - - <listitem><para>Source pad actual crop selection. Crop on the source - pad defines crop performed to the image in the sink compose - bounds rectangle.</para></listitem> - - <listitem><para>Source pad format. The source pad format defines the - output pixel format of the subdev, as well as the other - parameters with the exception of the image width and height. - Width and height are defined by the size of the source pad - actual crop selection.</para></listitem> - </orderedlist> - - <para>Accessing any of the above rectangles not supported by the - subdev will return <constant>EINVAL</constant>. Any rectangle - referring to a previous unsupported rectangle coordinates will - instead refer to the previous supported rectangle. For example, - if sink crop is not supported, the compose selection will refer - to the sink pad format dimensions instead.</para> - - <figure id="subdev-image-processing-crop"> - <title>Image processing in subdevs: simple crop example</title> - <mediaobject> - <imageobject> - <imagedata fileref="subdev-image-processing-crop.svg" - format="SVG" scale="200" /> - </imageobject> - </mediaobject> - </figure> - - <para>In the above example, the subdev supports cropping on its - sink pad. To configure it, the user sets the media bus format on - the subdev's sink pad. Now the actual crop rectangle can be set - on the sink pad --- the location and size of this rectangle - reflect the location and size of a rectangle to be cropped from - the sink format. The size of the sink crop rectangle will also - be the size of the format of the subdev's source pad.</para> - - <figure id="subdev-image-processing-scaling-multi-source"> - <title>Image processing in subdevs: scaling with multiple sources</title> - <mediaobject> - <imageobject> - <imagedata fileref="subdev-image-processing-scaling-multi-source.svg" - format="SVG" scale="200" /> - </imageobject> - </mediaobject> - </figure> - - <para>In this example, the subdev is capable of first cropping, - then scaling and finally cropping for two source pads - individually from the resulting scaled image. The location of - the scaled image in the cropped image is ignored in sink compose - target. Both of the locations of the source crop rectangles - refer to the sink scaling rectangle, independently cropping an - area at location specified by the source crop rectangle from - it.</para> - - <figure id="subdev-image-processing-full"> - <title>Image processing in subdevs: scaling and composition - with multiple sinks and sources</title> - <mediaobject> - <imageobject> - <imagedata fileref="subdev-image-processing-full.svg" - format="SVG" scale="200" /> - </imageobject> - </mediaobject> - </figure> - - <para>The subdev driver supports two sink pads and two source - pads. The images from both of the sink pads are individually - cropped, then scaled and further composed on the composition - bounds rectangle. From that, two independent streams are cropped - and sent out of the subdev from the source pads.</para> - - </section> - - </section> - - &sub-subdev-formats; diff --git a/Documentation/DocBook/media/v4l/dev-teletext.xml b/Documentation/DocBook/media/v4l/dev-teletext.xml deleted file mode 100644 index bd21c64d70f3..000000000000 --- a/Documentation/DocBook/media/v4l/dev-teletext.xml +++ /dev/null @@ -1,29 +0,0 @@ - <title>Teletext Interface</title> - - <para>This interface was aimed at devices receiving and demodulating -Teletext data [<xref linkend="ets300706" />, <xref linkend="itu653" />], evaluating the -Teletext packages and storing formatted pages in cache memory. Such -devices are usually implemented as microcontrollers with serial -interface (I<superscript>2</superscript>C) and could be found on old -TV cards, dedicated Teletext decoding cards and home-brew devices -connected to the PC parallel port.</para> - - <para>The Teletext API was designed by Martin Buck. It was defined in -the kernel header file <filename>linux/videotext.h</filename>, the -specification is available from <ulink url="ftp://ftp.gwdg.de/pub/linux/misc/videotext/"> -ftp://ftp.gwdg.de/pub/linux/misc/videotext/</ulink>. (Videotext is the name of -the German public television Teletext service.)</para> - - <para>Eventually the Teletext API was integrated into the V4L API -with character device file names <filename>/dev/vtx0</filename> to -<filename>/dev/vtx31</filename>, device major number 81, minor numbers -192 to 223.</para> - - <para>However, teletext decoders were quickly replaced by more -generic VBI demodulators and those dedicated teletext decoders no longer exist. -For many years the vtx devices were still around, even though nobody used -them. So the decision was made to finally remove support for the Teletext API in -kernel 2.6.37.</para> - - <para>Modern devices all use the <link linkend="raw-vbi">raw</link> or -<link linkend="sliced">sliced</link> VBI API.</para> diff --git a/Documentation/DocBook/media/v4l/driver.xml b/Documentation/DocBook/media/v4l/driver.xml deleted file mode 100644 index 7c6638bacedb..000000000000 --- a/Documentation/DocBook/media/v4l/driver.xml +++ /dev/null @@ -1,200 +0,0 @@ - <title>V4L2 Driver Programming</title> - - <!-- This part defines the interface between the "videodev" - module and individual drivers. --> - - <para>to do</para> -<!-- - <para>V4L2 is a two-layer driver system. The top layer is the "videodev" -kernel module. When videodev initializes it registers as character device -with major number 81, and it registers a set of file operations. All V4L2 -drivers are really clients of videodev, which calls V4L2 drivers through -driver method functions. V4L2 drivers are also written as kernel modules. -After probing the hardware they register one or more devices with -videodev.</para> - - <section id="driver-modules"> - <title>Driver Modules</title> - - <para>V4L2 driver modules must have an initialization function which is -called after the module was loaded into kernel, an exit function whis is -called before the module is removed. When the driver is compiled into the -kernel these functions called at system boot and shutdown time.</para> - - <informalexample> - <programlisting> -#include <linux/module.h> - -/* Export information about this module. For details and other useful - macros see <filename>linux/module.h</filename>. */ -MODULE_DESCRIPTION("my - driver for my hardware"); -MODULE_AUTHOR("Your name here"); -MODULE_LICENSE("GPL"); - -static void -my_module_exit (void) -{ - /* Free all resources allocated by my_module_init(). */ -} - -static int -my_module_init (void) -{ - /* Bind the driver to the supported hardware, see - <link linkend="driver-pci"> and - <link linkend="driver-usb"> for examples. */ - - return 0; /* a negative value on error, 0 on success. */ -} - -/* Export module functions. */ -module_init (my_module_init); -module_exit (my_module_exit); -</programlisting> - </informalexample> - - <para>Users can add parameters when kernel modules are inserted:</para> - - <informalexample> - <programlisting> -include <linux/moduleparam.h> - -static int my_option = 123; -static int my_option_array[47]; - -/* Export the symbol, an int, with access permissions 0664. - See <filename>linux/moduleparam.h</filename> for other types. */ -module_param (my_option, int, 0644); -module_param_array (my_option_array, int, NULL, 0644); - -MODULE_PARM_DESC (my_option, "Does magic things, default 123"); -</programlisting> - </informalexample> - - <para>One parameter should be supported by all V4L2 drivers, the minor -number of the device it will register. Purpose is to predictably link V4L2 -drivers to device nodes if more than one video device is installed. Use the -name of the device node followed by a "_nr" suffix, for example "video_nr" -for <filename>/dev/video</filename>.</para> - - <informalexample> - <programlisting> -/* Minor number of the device, -1 to allocate the first unused. */ -static int video_nr = -1; - -module_param (video_nr, int, 0444); -</programlisting> - </informalexample> - </section> - - <section id="driver-pci"> - <title>PCI Devices</title> - - <para>PCI devices are initialized like this:</para> - - <informalexample> - <programlisting> -typedef struct { - /* State of one physical device. */ -} my_device; - -static int -my_resume (struct pci_dev * pci_dev) -{ - /* Restore the suspended device to working state. */ -} - -static int -my_suspend (struct pci_dev * pci_dev, - pm_message_t state) -{ - /* This function is called before the system goes to sleep. - Stop all DMAs and disable interrupts, then put the device - into a low power state. For details see the kernel - sources under <filename>Documentation/power</filename>. */ - - return 0; /* a negative value on error, 0 on success. */ -} - -static void -my_remove (struct pci_dev * pci_dev) -{ - my_device *my = pci_get_drvdata (pci_dev); - - /* Describe me. */ -} - -static int -my_probe (struct pci_dev * pci_dev, - const struct pci_device_id * pci_id) -{ - my_device *my; - - /* Describe me. */ - - /* You can allocate per-device data here and store a pointer - to it in the pci_dev structure. */ - my = ...; - pci_set_drvdata (pci_dev, my); - - return 0; /* a negative value on error, 0 on success. */ -} - -/* A list of supported PCI devices. */ -static struct pci_device_id -my_pci_device_ids [] = { - { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR, - PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0 }, - { 0 } /* end of list */ -}; - -/* Load our module if supported PCI devices are installed. */ -MODULE_DEVICE_TABLE (pci, my_pci_device_ids); - -static struct pci_driver -my_pci_driver = { - .name = "my", - .id_table = my_pci_device_ids, - - .probe = my_probe, - .remove = my_remove, - - /* Power management functions. */ - .suspend = my_suspend, - .resume = my_resume, -}; - -static void -my_module_exit (void) -{ - pci_unregister_driver (&my_pci_driver); -} - -static int -my_module_init (void) -{ - return pci_register_driver (&my_pci_driver); -} -</programlisting> - </informalexample> - </section> - - <section id="driver-usb"> - <title>USB Devices</title> - <para>to do</para> - </section> - <section id="driver-registering"> - <title>Registering V4L2 Drivers</title> - - <para>After a V4L2 driver probed the hardware it registers one or more -devices with the videodev module.</para> - </section> - <section id="driver-file-ops"> - <title>File Operations</title> - <para>to do</para> - </section> - <section id="driver-internal-api"> - <title>Internal API</title> - <para>to do</para> - </section> ---> diff --git a/Documentation/DocBook/media/v4l/fdl-appendix.xml b/Documentation/DocBook/media/v4l/fdl-appendix.xml deleted file mode 100644 index ae22394ba997..000000000000 --- a/Documentation/DocBook/media/v4l/fdl-appendix.xml +++ /dev/null @@ -1,671 +0,0 @@ -<!-- - The GNU Free Documentation License 1.1 in DocBook - Markup by Eric Baudais <baudais@okstate.edu> - Maintained by the GNOME Documentation Project - http://live.gnome.org/DocumentationProject - Version: 1.0.1 - Last Modified: Nov 16, 2000 ---> - -<appendix id="fdl"> - <appendixinfo> - <releaseinfo> - Version 1.1, March 2000 - </releaseinfo> - <copyright> - <year>2000</year><holder>Free Software Foundation, Inc.</holder> - </copyright> - <legalnotice id="fdl-legalnotice"> - <para> - <address>Free Software Foundation, Inc. <street>59 Temple Place, - Suite 330</street>, <city>Boston</city>, <state>MA</state> - <postcode>02111-1307</postcode> <country>USA</country></address> - Everyone is permitted to copy and distribute verbatim copies of this - license document, but changing it is not allowed. - </para> - </legalnotice> - </appendixinfo> - <title>GNU Free Documentation License</title> - - <sect1 id="fdl-preamble"> - <title>0. PREAMBLE</title> - <para> - The purpose of this License is to make a manual, textbook, or - other written document <quote>free</quote> in the sense of - freedom: to assure everyone the effective freedom to copy and - redistribute it, with or without modifying it, either - commercially or noncommercially. Secondarily, this License - preserves for the author and publisher a way to get credit for - their work, while not being considered responsible for - modifications made by others. - </para> - - <para> - This License is a kind of <quote>copyleft</quote>, which means - that derivative works of the document must themselves be free in - the same sense. It complements the GNU General Public License, - which is a copyleft license designed for free software. - </para> - - <para> - We have designed this License in order to use it for manuals for - free software, because free software needs free documentation: a - free program should come with manuals providing the same - freedoms that the software does. But this License is not limited - to software manuals; it can be used for any textual work, - regardless of subject matter or whether it is published as a - printed book. We recommend this License principally for works - whose purpose is instruction or reference. - </para> - </sect1> - <sect1 id="fdl-section1"> - <title>1. APPLICABILITY AND DEFINITIONS</title> - <para id="fdl-document"> - This License applies to any manual or other work that contains a - notice placed by the copyright holder saying it can be - distributed under the terms of this License. The - <quote>Document</quote>, below, refers to any such manual or - work. Any member of the public is a licensee, and is addressed - as <quote>you</quote>. - </para> - - <para id="fdl-modified"> - A <quote>Modified Version</quote> of the Document means any work - containing the Document or a portion of it, either copied - verbatim, or with modifications and/or translated into another - language. - </para> - - <para id="fdl-secondary"> - A <quote>Secondary Section</quote> is a named appendix or a - front-matter section of the <link - linkend="fdl-document">Document</link> that deals exclusively - with the relationship of the publishers or authors of the - Document to the Document's overall subject (or to related - matters) and contains nothing that could fall directly within - that overall subject. (For example, if the Document is in part a - textbook of mathematics, a Secondary Section may not explain any - mathematics.) The relationship could be a matter of historical - connection with the subject or with related matters, or of - legal, commercial, philosophical, ethical or political position - regarding them. - </para> - - <para id="fdl-invariant"> - The <quote>Invariant Sections</quote> are certain <link - linkend="fdl-secondary"> Secondary Sections</link> whose titles - are designated, as being those of Invariant Sections, in the - notice that says that the <link - linkend="fdl-document">Document</link> is released under this - License. - </para> - - <para id="fdl-cover-texts"> - The <quote>Cover Texts</quote> are certain short passages of - text that are listed, as Front-Cover Texts or Back-Cover Texts, - in the notice that says that the <link - linkend="fdl-document">Document</link> is released under this - License. - </para> - - <para id="fdl-transparent"> - A <quote>Transparent</quote> copy of the <link - linkend="fdl-document"> Document</link> means a machine-readable - copy, represented in a format whose specification is available - to the general public, whose contents can be viewed and edited - directly and straightforwardly with generic text editors or (for - images composed of pixels) generic paint programs or (for - drawings) some widely available drawing editor, and that is - suitable for input to text formatters or for automatic - translation to a variety of formats suitable for input to text - formatters. A copy made in an otherwise Transparent file format - whose markup has been designed to thwart or discourage - subsequent modification by readers is not Transparent. A copy - that is not <quote>Transparent</quote> is called - <quote>Opaque</quote>. - </para> - - <para> - Examples of suitable formats for Transparent copies include - plain ASCII without markup, Texinfo input format, LaTeX input - format, SGML or XML using a publicly available DTD, and - standard-conforming simple HTML designed for human - modification. Opaque formats include PostScript, PDF, - proprietary formats that can be read and edited only by - proprietary word processors, SGML or XML for which the DTD - and/or processing tools are not generally available, and the - machine-generated HTML produced by some word processors for - output purposes only. - </para> - - <para id="fdl-title-page"> - The <quote>Title Page</quote> means, for a printed book, the - title page itself, plus such following pages as are needed to - hold, legibly, the material this License requires to appear in - the title page. For works in formats which do not have any title - page as such, <quote>Title Page</quote> means the text near the - most prominent appearance of the work's title, preceding the - beginning of the body of the text. - </para> - </sect1> - - <sect1 id="fdl-section2"> - <title>2. VERBATIM COPYING</title> - <para> - You may copy and distribute the <link - linkend="fdl-document">Document</link> in any medium, either - commercially or noncommercially, provided that this License, the - copyright notices, and the license notice saying this License - applies to the Document are reproduced in all copies, and that - you add no other conditions whatsoever to those of this - License. You may not use technical measures to obstruct or - control the reading or further copying of the copies you make or - distribute. However, you may accept compensation in exchange for - copies. If you distribute a large enough number of copies you - must also follow the conditions in <link - linkend="fdl-section3">section 3</link>. - </para> - - <para> - You may also lend copies, under the same conditions stated - above, and you may publicly display copies. - </para> - </sect1> - - <sect1 id="fdl-section3"> - <title>3. COPYING IN QUANTITY</title> - <para> - If you publish printed copies of the <link - linkend="fdl-document">Document</link> numbering more than 100, - and the Document's license notice requires <link - linkend="fdl-cover-texts">Cover Texts</link>, you must enclose - the copies in covers that carry, clearly and legibly, all these - Cover Texts: Front-Cover Texts on the front cover, and - Back-Cover Texts on the back cover. Both covers must also - clearly and legibly identify you as the publisher of these - copies. The front cover must present the full title with all - words of the title equally prominent and visible. You may add - other material on the covers in addition. Copying with changes - limited to the covers, as long as they preserve the title of the - <link linkend="fdl-document">Document</link> and satisfy these - conditions, can be treated as verbatim copying in other - respects. - </para> - - <para> - If the required texts for either cover are too voluminous to fit - legibly, you should put the first ones listed (as many as fit - reasonably) on the actual cover, and continue the rest onto - adjacent pages. - </para> - - <para> - If you publish or distribute <link - linkend="fdl-transparent">Opaque</link> copies of the <link - linkend="fdl-document">Document</link> numbering more than 100, - you must either include a machine-readable <link - linkend="fdl-transparent">Transparent</link> copy along with - each Opaque copy, or state in or with each Opaque copy a - publicly-accessible computer-network location containing a - complete Transparent copy of the Document, free of added - material, which the general network-using public has access to - download anonymously at no charge using public-standard network - protocols. If you use the latter option, you must take - reasonably prudent steps, when you begin distribution of Opaque - copies in quantity, to ensure that this Transparent copy will - remain thus accessible at the stated location until at least one - year after the last time you distribute an Opaque copy (directly - or through your agents or retailers) of that edition to the - public. - </para> - - <para> - It is requested, but not required, that you contact the authors - of the <link linkend="fdl-document">Document</link> well before - redistributing any large number of copies, to give them a chance - to provide you with an updated version of the Document. - </para> - </sect1> - - <sect1 id="fdl-section4"> - <title>4. MODIFICATIONS</title> - <para> - You may copy and distribute a <link - linkend="fdl-modified">Modified Version</link> of the <link - linkend="fdl-document">Document</link> under the conditions of - sections <link linkend="fdl-section2">2</link> and <link - linkend="fdl-section3">3</link> above, provided that you release - the Modified Version under precisely this License, with the - Modified Version filling the role of the Document, thus - licensing distribution and modification of the Modified Version - to whoever possesses a copy of it. In addition, you must do - these things in the Modified Version: - </para> - - <itemizedlist mark="opencircle"> - <listitem> - <formalpara> - <title>A</title> - <para> - Use in the <link linkend="fdl-title-page">Title - Page</link> (and on the covers, if any) a title distinct - from that of the <link - linkend="fdl-document">Document</link>, and from those of - previous versions (which should, if there were any, be - listed in the History section of the Document). You may - use the same title as a previous version if the original - publisher of that version gives permission. - </para> - </formalpara> - </listitem> - - <listitem> - <formalpara> - <title>B</title> - <para> - List on the <link linkend="fdl-title-page">Title - Page</link>, as authors, one or more persons or entities - responsible for authorship of the modifications in the - <link linkend="fdl-modified">Modified Version</link>, - together with at least five of the principal authors of - the <link linkend="fdl-document">Document</link> (all of - its principal authors, if it has less than five). - </para> - </formalpara> - </listitem> - - <listitem> - <formalpara> - <title>C</title> - <para> - State on the <link linkend="fdl-title-page">Title - Page</link> the name of the publisher of the <link - linkend="fdl-modified">Modified Version</link>, as the - publisher. - </para> - </formalpara> - </listitem> - - <listitem> - <formalpara> - <title>D</title> - <para> - Preserve all the copyright notices of the <link - linkend="fdl-document">Document</link>. - </para> - </formalpara> - </listitem> - - <listitem> - <formalpara> - <title>E</title> - <para> - Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - </para> - </formalpara> - </listitem> - - <listitem> - <formalpara> - <title>F</title> - <para> - Include, immediately after the copyright notices, a - license notice giving the public permission to use the - <link linkend="fdl-modified">Modified Version</link> under - the terms of this License, in the form shown in the - Addendum below. - </para> - </formalpara> - </listitem> - - <listitem> - <formalpara> - <title>G</title> - <para> - Preserve in that license notice the full lists of <link - linkend="fdl-invariant"> Invariant Sections</link> and - required <link linkend="fdl-cover-texts">Cover - Texts</link> given in the <link - linkend="fdl-document">Document's</link> license notice. - </para> - </formalpara> - </listitem> - - <listitem> - <formalpara> - <title>H</title> - <para> - Include an unaltered copy of this License. - </para> - </formalpara> - </listitem> - - <listitem> - <formalpara> - <title>I</title> - <para> - Preserve the section entitled <quote>History</quote>, and - its title, and add to it an item stating at least the - title, year, new authors, and publisher of the <link - linkend="fdl-modified">Modified Version </link>as given on - the <link linkend="fdl-title-page">Title Page</link>. If - there is no section entitled <quote>History</quote> in the - <link linkend="fdl-document">Document</link>, create one - stating the title, year, authors, and publisher of the - Document as given on its Title Page, then add an item - describing the Modified Version as stated in the previous - sentence. - </para> - </formalpara> - </listitem> - - <listitem> - <formalpara> - <title>J</title> - <para> - Preserve the network location, if any, given in the <link - linkend="fdl-document">Document</link> for public access - to a <link linkend="fdl-transparent">Transparent</link> - copy of the Document, and likewise the network locations - given in the Document for previous versions it was based - on. These may be placed in the <quote>History</quote> - section. You may omit a network location for a work that - was published at least four years before the Document - itself, or if the original publisher of the version it - refers to gives permission. - </para> - </formalpara> - </listitem> - - <listitem> - <formalpara> - <title>K</title> - <para> - In any section entitled <quote>Acknowledgements</quote> or - <quote>Dedications</quote>, preserve the section's title, - and preserve in the section all the substance and tone of - each of the contributor acknowledgements and/or - dedications given therein. - </para> - </formalpara> - </listitem> - - <listitem> - <formalpara> - <title>L</title> - <para> - Preserve all the <link linkend="fdl-invariant">Invariant - Sections</link> of the <link - linkend="fdl-document">Document</link>, unaltered in their - text and in their titles. Section numbers or the - equivalent are not considered part of the section titles. - </para> - </formalpara> - </listitem> - - <listitem> - <formalpara> - <title>M</title> - <para> - Delete any section entitled - <quote>Endorsements</quote>. Such a section may not be - included in the <link linkend="fdl-modified">Modified - Version</link>. - </para> - </formalpara> - </listitem> - - <listitem> - <formalpara> - <title>N</title> - <para> - Do not retitle any existing section as - <quote>Endorsements</quote> or to conflict in title with - any <link linkend="fdl-invariant">Invariant - Section</link>. - </para> - </formalpara> - </listitem> - </itemizedlist> - - <para> - If the <link linkend="fdl-modified">Modified Version</link> - includes new front-matter sections or appendices that qualify as - <link linkend="fdl-secondary">Secondary Sections</link> and - contain no material copied from the Document, you may at your - option designate some or all of these sections as invariant. To - do this, add their titles to the list of <link - linkend="fdl-invariant">Invariant Sections</link> in the - Modified Version's license notice. These titles must be - distinct from any other section titles. - </para> - - <para> - You may add a section entitled <quote>Endorsements</quote>, - provided it contains nothing but endorsements of your <link - linkend="fdl-modified">Modified Version</link> by various - parties--for example, statements of peer review or that the text - has been approved by an organization as the authoritative - definition of a standard. - </para> - - <para> - You may add a passage of up to five words as a <link - linkend="fdl-cover-texts">Front-Cover Text</link>, and a passage - of up to 25 words as a <link - linkend="fdl-cover-texts">Back-Cover Text</link>, to the end of - the list of <link linkend="fdl-cover-texts">Cover Texts</link> - in the <link linkend="fdl-modified">Modified Version</link>. - Only one passage of Front-Cover Text and one of Back-Cover Text - may be added by (or through arrangements made by) any one - entity. If the <link linkend="fdl-document">Document</link> - already includes a cover text for the same cover, previously - added by you or by arrangement made by the same entity you are - acting on behalf of, you may not add another; but you may - replace the old one, on explicit permission from the previous - publisher that added the old one. - </para> - - <para> - The author(s) and publisher(s) of the <link - linkend="fdl-document">Document</link> do not by this License - give permission to use their names for publicity for or to - assert or imply endorsement of any <link - linkend="fdl-modified">Modified Version </link>. - </para> - </sect1> - - <sect1 id="fdl-section5"> - <title>5. COMBINING DOCUMENTS</title> - <para> - You may combine the <link linkend="fdl-document">Document</link> - with other documents released under this License, under the - terms defined in <link linkend="fdl-section4">section 4</link> - above for modified versions, provided that you include in the - combination all of the <link linkend="fdl-invariant">Invariant - Sections</link> of all of the original documents, unmodified, - and list them all as Invariant Sections of your combined work in - its license notice. - </para> - - <para> - The combined work need only contain one copy of this License, - and multiple identical <link linkend="fdl-invariant">Invariant - Sections</link> may be replaced with a single copy. If there are - multiple Invariant Sections with the same name but different - contents, make the title of each such section unique by adding - at the end of it, in parentheses, the name of the original - author or publisher of that section if known, or else a unique - number. Make the same adjustment to the section titles in the - list of Invariant Sections in the license notice of the combined - work. - </para> - - <para> - In the combination, you must combine any sections entitled - <quote>History</quote> in the various original documents, - forming one section entitled <quote>History</quote>; likewise - combine any sections entitled <quote>Acknowledgements</quote>, - and any sections entitled <quote>Dedications</quote>. You must - delete all sections entitled <quote>Endorsements.</quote> - </para> - </sect1> - - <sect1 id="fdl-section6"> - <title>6. COLLECTIONS OF DOCUMENTS</title> - <para> - You may make a collection consisting of the <link - linkend="fdl-document">Document</link> and other documents - released under this License, and replace the individual copies - of this License in the various documents with a single copy that - is included in the collection, provided that you follow the - rules of this License for verbatim copying of each of the - documents in all other respects. - </para> - - <para> - You may extract a single document from such a collection, and - dispbibute it individually under this License, provided you - insert a copy of this License into the extracted document, and - follow this License in all other respects regarding verbatim - copying of that document. - </para> - </sect1> - - <sect1 id="fdl-section7"> - <title>7. AGGREGATION WITH INDEPENDENT WORKS</title> - <para> - A compilation of the <link - linkend="fdl-document">Document</link> or its derivatives with - other separate and independent documents or works, in or on a - volume of a storage or distribution medium, does not as a whole - count as a <link linkend="fdl-modified">Modified Version</link> - of the Document, provided no compilation copyright is claimed - for the compilation. Such a compilation is called an - <quote>aggregate</quote>, and this License does not apply to the - other self-contained works thus compiled with the Document , on - account of their being thus compiled, if they are not themselves - derivative works of the Document. If the <link - linkend="fdl-cover-texts">Cover Text</link> requirement of <link - linkend="fdl-section3">section 3</link> is applicable to these - copies of the Document, then if the Document is less than one - quarter of the entire aggregate, the Document's Cover Texts may - be placed on covers that surround only the Document within the - aggregate. Otherwise they must appear on covers around the whole - aggregate. - </para> - </sect1> - - <sect1 id="fdl-section8"> - <title>8. TRANSLATION</title> - <para> - Translation is considered a kind of modification, so you may - distribute translations of the <link - linkend="fdl-document">Document</link> under the terms of <link - linkend="fdl-section4">section 4</link>. Replacing <link - linkend="fdl-invariant"> Invariant Sections</link> with - translations requires special permission from their copyright - holders, but you may include translations of some or all - Invariant Sections in addition to the original versions of these - Invariant Sections. You may include a translation of this - License provided that you also include the original English - version of this License. In case of a disagreement between the - translation and the original English version of this License, - the original English version will prevail. - </para> - </sect1> - - <sect1 id="fdl-section9"> - <title>9. TERMINATION</title> - <para> - You may not copy, modify, sublicense, or distribute the <link - linkend="fdl-document">Document</link> except as expressly - provided for under this License. Any other attempt to copy, - modify, sublicense or distribute the Document is void, and will - automatically terminate your rights under this License. However, - parties who have received copies, or rights, from you under this - License will not have their licenses terminated so long as such - parties remain in full compliance. - </para> - </sect1> - - <sect1 id="fdl-section10"> - <title>10. FUTURE REVISIONS OF THIS LICENSE</title> - <para> - The <ulink type="http" - url="http://www.gnu.org/fsf/fsf.html">Free Software - Foundation</ulink> may publish new, revised versions of the GNU - Free Documentation License from time to time. Such new versions - will be similar in spirit to the present version, but may differ - in detail to address new problems or concerns. See <ulink - type="http" - url="http://www.gnu.org/copyleft">http://www.gnu.org/copyleft/</ulink>. - </para> - - <para> - Each version of the License is given a distinguishing version - number. If the <link linkend="fdl-document">Document</link> - specifies that a particular numbered version of this License - <quote>or any later version</quote> applies to it, you have the - option of following the terms and conditions either of that - specified version or of any later version that has been - published (not as a draft) by the Free Software Foundation. If - the Document does not specify a version number of this License, - you may choose any version ever published (not as a draft) by - the Free Software Foundation. - </para> - </sect1> - - <sect1 id="fdl-using"> - <title>Addendum</title> - <para> - To use this License in a document you have written, include a copy of - the License in the document and put the following copyright and - license notices just after the title page: - </para> - - <blockquote> - <para> - Copyright © YEAR YOUR NAME. - </para> - <para> - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation - License, Version 1.1 or any later version published by the - Free Software Foundation; with the <link - linkend="fdl-invariant">Invariant Sections</link> being LIST - THEIR TITLES, with the <link - linkend="fdl-cover-texts">Front-Cover Texts</link> being LIST, - and with the <link linkend="fdl-cover-texts">Back-Cover - Texts</link> being LIST. A copy of the license is included in - the section entitled <quote>GNU Free Documentation - License</quote>. - </para> - </blockquote> - - <para> - If you have no <link linkend="fdl-invariant">Invariant - Sections</link>, write <quote>with no Invariant Sections</quote> - instead of saying which ones are invariant. If you have no - <link linkend="fdl-cover-texts">Front-Cover Texts</link>, write - <quote>no Front-Cover Texts</quote> instead of - <quote>Front-Cover Texts being LIST</quote>; likewise for <link - linkend="fdl-cover-texts">Back-Cover Texts</link>. - </para> - - <para> - If your document contains nontrivial examples of program code, - we recommend releasing these examples in parallel under your - choice of free software license, such as the <ulink type="http" - url="http://www.gnu.org/copyleft/gpl.html"> GNU General Public - License</ulink>, to permit their use in free software. - </para> - </sect1> -</appendix> - - - - - - diff --git a/Documentation/DocBook/media/v4l/fieldseq_bt.pdf b/Documentation/DocBook/media/v4l/fieldseq_bt.pdf Binary files differdeleted file mode 100644 index 26598b23f80d..000000000000 --- a/Documentation/DocBook/media/v4l/fieldseq_bt.pdf +++ /dev/null diff --git a/Documentation/DocBook/media/v4l/fieldseq_tb.pdf b/Documentation/DocBook/media/v4l/fieldseq_tb.pdf Binary files differdeleted file mode 100644 index 4965b22ddb3a..000000000000 --- a/Documentation/DocBook/media/v4l/fieldseq_tb.pdf +++ /dev/null diff --git a/Documentation/DocBook/media/v4l/func-close.xml b/Documentation/DocBook/media/v4l/func-close.xml deleted file mode 100644 index 232920d2f3c6..000000000000 --- a/Documentation/DocBook/media/v4l/func-close.xml +++ /dev/null @@ -1,62 +0,0 @@ -<refentry id="func-close"> - <refmeta> - <refentrytitle>V4L2 close()</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>v4l2-close</refname> - <refpurpose>Close a V4L2 device</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <unistd.h></funcsynopsisinfo> - <funcprototype> - <funcdef>int <function>close</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>Closes the device. Any I/O in progress is terminated and -resources associated with the file descriptor are freed. However data -format parameters, current input or output, control values or other -properties remain unchanged.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>The function returns <returnvalue>0</returnvalue> on -success, <returnvalue>-1</returnvalue> on failure and the -<varname>errno</varname> is set appropriately. Possible error -codes:</para> - - <variablelist> - <varlistentry> - <term><errorcode>EBADF</errorcode></term> - <listitem> - <para><parameter>fd</parameter> is not a valid open file -descriptor.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/func-ioctl.xml b/Documentation/DocBook/media/v4l/func-ioctl.xml deleted file mode 100644 index 4394184a1a6d..000000000000 --- a/Documentation/DocBook/media/v4l/func-ioctl.xml +++ /dev/null @@ -1,71 +0,0 @@ -<refentry id="func-ioctl"> - <refmeta> - <refentrytitle>V4L2 ioctl()</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>v4l2-ioctl</refname> - <refpurpose>Program a V4L2 device</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <sys/ioctl.h></funcsynopsisinfo> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>void *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>V4L2 ioctl request code as defined in the <filename>videodev2.h</filename> header file, for example -VIDIOC_QUERYCAP.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para>Pointer to a function parameter, usually a structure.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>The <function>ioctl()</function> function is used to program -V4L2 devices. The argument <parameter>fd</parameter> must be an open -file descriptor. An ioctl <parameter>request</parameter> has encoded -in it whether the argument is an input, output or read/write -parameter, and the size of the argument <parameter>argp</parameter> in -bytes. Macros and defines specifying V4L2 ioctl requests are located -in the <filename>videodev2.h</filename> header file. -Applications should use their own copy, not include the version in the -kernel sources on the system they compile on. All V4L2 ioctl requests, -their respective function and parameters are specified in <xref - linkend="user-func" />.</para> - </refsect1> - - <refsect1> - &return-value; - <para>When an ioctl that takes an output or read/write parameter fails, - the parameter remains unmodified.</para> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/func-mmap.xml b/Documentation/DocBook/media/v4l/func-mmap.xml deleted file mode 100644 index f31ad71bf301..000000000000 --- a/Documentation/DocBook/media/v4l/func-mmap.xml +++ /dev/null @@ -1,183 +0,0 @@ -<refentry id="func-mmap"> - <refmeta> - <refentrytitle>V4L2 mmap()</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>v4l2-mmap</refname> - <refpurpose>Map device memory into application address space</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo> -#include <unistd.h> -#include <sys/mman.h></funcsynopsisinfo> - <funcprototype> - <funcdef>void *<function>mmap</function></funcdef> - <paramdef>void *<parameter>start</parameter></paramdef> - <paramdef>size_t <parameter>length</parameter></paramdef> - <paramdef>int <parameter>prot</parameter></paramdef> - <paramdef>int <parameter>flags</parameter></paramdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>off_t <parameter>offset</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - <variablelist> - <varlistentry> - <term><parameter>start</parameter></term> - <listitem> - <para>Map the buffer to this address in the -application's address space. When the <constant>MAP_FIXED</constant> -flag is specified, <parameter>start</parameter> must be a multiple of the -pagesize and mmap will fail when the specified address -cannot be used. Use of this option is discouraged; applications should -just specify a <constant>NULL</constant> pointer here.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>length</parameter></term> - <listitem> - <para>Length of the memory area to map. This must be the -same value as returned by the driver in the &v4l2-buffer; -<structfield>length</structfield> field for the -single-planar API, and the same value as returned by the driver -in the &v4l2-plane; <structfield>length</structfield> field for the -multi-planar API.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>prot</parameter></term> - <listitem> - <para>The <parameter>prot</parameter> argument describes the -desired memory protection. Regardless of the device type and the -direction of data exchange it should be set to -<constant>PROT_READ</constant> | <constant>PROT_WRITE</constant>, -permitting read and write access to image buffers. Drivers should -support at least this combination of flags. Note the Linux -<filename>video-buf</filename> kernel module, which is used by the -bttv, saa7134, saa7146, cx88 and vivi driver supports only -<constant>PROT_READ</constant> | <constant>PROT_WRITE</constant>. When -the driver does not support the desired protection the -<function>mmap()</function> function fails.</para> - <para>Note device memory accesses (⪚ the memory on a -graphics card with video capturing hardware) may incur a performance -penalty compared to main memory accesses, or reads may be -significantly slower than writes or vice versa. Other I/O methods may -be more efficient in this case.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>flags</parameter></term> - <listitem> - <para>The <parameter>flags</parameter> parameter -specifies the type of the mapped object, mapping options and whether -modifications made to the mapped copy of the page are private to the -process or are to be shared with other references.</para> - <para><constant>MAP_FIXED</constant> requests that the -driver selects no other address than the one specified. If the -specified address cannot be used, <function>mmap()</function> will fail. If -<constant>MAP_FIXED</constant> is specified, -<parameter>start</parameter> must be a multiple of the pagesize. Use -of this option is discouraged.</para> - <para>One of the <constant>MAP_SHARED</constant> or -<constant>MAP_PRIVATE</constant> flags must be set. -<constant>MAP_SHARED</constant> allows applications to share the -mapped memory with other (⪚ child-) processes. Note the Linux -<filename>video-buf</filename> module which is used by the bttv, -saa7134, saa7146, cx88 and vivi driver supports only -<constant>MAP_SHARED</constant>. <constant>MAP_PRIVATE</constant> -requests copy-on-write semantics. V4L2 applications should not set the -<constant>MAP_PRIVATE</constant>, <constant>MAP_DENYWRITE</constant>, -<constant>MAP_EXECUTABLE</constant> or <constant>MAP_ANON</constant> -flag.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>offset</parameter></term> - <listitem> - <para>Offset of the buffer in device memory. This must be the -same value as returned by the driver in the &v4l2-buffer; -<structfield>m</structfield> union <structfield>offset</structfield> field for -the single-planar API, and the same value as returned by the driver -in the &v4l2-plane; <structfield>m</structfield> union -<structfield>mem_offset</structfield> field for the multi-planar API.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>The <function>mmap()</function> function asks to map -<parameter>length</parameter> bytes starting at -<parameter>offset</parameter> in the memory of the device specified by -<parameter>fd</parameter> into the application address space, -preferably at address <parameter>start</parameter>. This latter -address is a hint only, and is usually specified as 0.</para> - - <para>Suitable length and offset parameters are queried with the -&VIDIOC-QUERYBUF; ioctl. Buffers must be allocated with the -&VIDIOC-REQBUFS; ioctl before they can be queried.</para> - - <para>To unmap buffers the &func-munmap; function is used.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success <function>mmap()</function> returns a pointer to -the mapped buffer. On error <constant>MAP_FAILED</constant> (-1) is -returned, and the <varname>errno</varname> variable is set -appropriately. Possible error codes are:</para> - - <variablelist> - <varlistentry> - <term><errorcode>EBADF</errorcode></term> - <listitem> - <para><parameter>fd</parameter> is not a valid file -descriptor.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EACCES</errorcode></term> - <listitem> - <para><parameter>fd</parameter> is -not open for reading and writing.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The <parameter>start</parameter> or -<parameter>length</parameter> or <parameter>offset</parameter> are not -suitable. (E. g. they are too large, or not aligned on a -<constant>PAGESIZE</constant> boundary.)</para> - <para>The <parameter>flags</parameter> or -<parameter>prot</parameter> value is not supported.</para> - <para>No buffers have been allocated with the -&VIDIOC-REQBUFS; ioctl.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>ENOMEM</errorcode></term> - <listitem> - <para>Not enough physical or virtual memory was available to -complete the request.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/func-munmap.xml b/Documentation/DocBook/media/v4l/func-munmap.xml deleted file mode 100644 index 860d49ca54a5..000000000000 --- a/Documentation/DocBook/media/v4l/func-munmap.xml +++ /dev/null @@ -1,76 +0,0 @@ -<refentry id="func-munmap"> - <refmeta> - <refentrytitle>V4L2 munmap()</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>v4l2-munmap</refname> - <refpurpose>Unmap device memory</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo> -#include <unistd.h> -#include <sys/mman.h></funcsynopsisinfo> - <funcprototype> - <funcdef>int <function>munmap</function></funcdef> - <paramdef>void *<parameter>start</parameter></paramdef> - <paramdef>size_t <parameter>length</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - <refsect1> - <title>Arguments</title> - <variablelist> - <varlistentry> - <term><parameter>start</parameter></term> - <listitem> - <para>Address of the mapped buffer as returned by the -&func-mmap; function.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>length</parameter></term> - <listitem> - <para>Length of the mapped buffer. This must be the same -value as given to <function>mmap()</function> and returned by the -driver in the &v4l2-buffer; <structfield>length</structfield> -field for the single-planar API and in the &v4l2-plane; -<structfield>length</structfield> field for the multi-planar API.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>Unmaps a previously with the &func-mmap; function mapped -buffer and frees it, if possible. <!-- ? This function (not freeing) -has no impact on I/O in progress, specifically it does not imply -&VIDIOC-STREAMOFF; to terminate I/O. Unmapped buffers can still be -enqueued, dequeued or queried, they are just not accessible by the -application.--></para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success <function>munmap()</function> returns 0, on -failure -1 and the <varname>errno</varname> variable is set -appropriately:</para> - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The <parameter>start</parameter> or -<parameter>length</parameter> is incorrect, or no buffers have been -mapped yet.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/func-open.xml b/Documentation/DocBook/media/v4l/func-open.xml deleted file mode 100644 index cf64e207c3ee..000000000000 --- a/Documentation/DocBook/media/v4l/func-open.xml +++ /dev/null @@ -1,113 +0,0 @@ -<refentry id="func-open"> - <refmeta> - <refentrytitle>V4L2 open()</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>v4l2-open</refname> - <refpurpose>Open a V4L2 device</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <fcntl.h></funcsynopsisinfo> - <funcprototype> - <funcdef>int <function>open</function></funcdef> - <paramdef>const char *<parameter>device_name</parameter></paramdef> - <paramdef>int <parameter>flags</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>device_name</parameter></term> - <listitem> - <para>Device to be opened.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>flags</parameter></term> - <listitem> - <para>Open flags. Access mode must be -<constant>O_RDWR</constant>. This is just a technicality, input devices -still support only reading and output devices only writing.</para> - <para>When the <constant>O_NONBLOCK</constant> flag is -given, the read() function and the &VIDIOC-DQBUF; ioctl will return -the &EAGAIN; when no data is available or no buffer is in the driver -outgoing queue, otherwise these functions block until data becomes -available. All V4L2 drivers exchanging data with applications must -support the <constant>O_NONBLOCK</constant> flag.</para> - <para>Other flags have no effect.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - <refsect1> - <title>Description</title> - - <para>To open a V4L2 device applications call -<function>open()</function> with the desired device name. This -function has no side effects; all data format parameters, current -input or output, control values or other properties remain unchanged. -At the first <function>open()</function> call after loading the driver -they will be reset to default values, drivers are never in an -undefined state.</para> - </refsect1> - <refsect1> - <title>Return Value</title> - - <para>On success <function>open</function> returns the new file -descriptor. On error -1 is returned, and the <varname>errno</varname> -variable is set appropriately. Possible error codes are:</para> - - <variablelist> - <varlistentry> - <term><errorcode>EACCES</errorcode></term> - <listitem> - <para>The caller has no permission to access the -device.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EBUSY</errorcode></term> - <listitem> - <para>The driver does not support multiple opens and the -device is already in use.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>ENXIO</errorcode></term> - <listitem> - <para>No device corresponding to this device special file -exists.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>ENOMEM</errorcode></term> - <listitem> - <para>Not enough kernel memory was available to complete the -request.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EMFILE</errorcode></term> - <listitem> - <para>The process already has the maximum number of -files open.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>ENFILE</errorcode></term> - <listitem> - <para>The limit on the total number of files open on the -system has been reached.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/func-poll.xml b/Documentation/DocBook/media/v4l/func-poll.xml deleted file mode 100644 index 4c73f115219b..000000000000 --- a/Documentation/DocBook/media/v4l/func-poll.xml +++ /dev/null @@ -1,142 +0,0 @@ -<refentry id="func-poll"> - <refmeta> - <refentrytitle>V4L2 poll()</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>v4l2-poll</refname> - <refpurpose>Wait for some event on a file descriptor</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <sys/poll.h></funcsynopsisinfo> - <funcprototype> - <funcdef>int <function>poll</function></funcdef> - <paramdef>struct pollfd *<parameter>ufds</parameter></paramdef> - <paramdef>unsigned int <parameter>nfds</parameter></paramdef> - <paramdef>int <parameter>timeout</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>With the <function>poll()</function> function applications -can suspend execution until the driver has captured data or is ready -to accept data for output.</para> - - <para>When streaming I/O has been negotiated this function waits -until a buffer has been filled by the capture device and can be dequeued -with the &VIDIOC-DQBUF; ioctl. For output devices this function waits -until the device is ready to accept a new buffer to be queued up with -the &VIDIOC-QBUF; ioctl for display. When buffers are already in the outgoing -queue of the driver (capture) or the incoming queue isn't full (display) -the function returns immediately.</para> - - <para>On success <function>poll()</function> returns the number of -file descriptors that have been selected (that is, file descriptors -for which the <structfield>revents</structfield> field of the -respective <structname>pollfd</structname> structure is non-zero). -Capture devices set the <constant>POLLIN</constant> and -<constant>POLLRDNORM</constant> flags in the -<structfield>revents</structfield> field, output devices the -<constant>POLLOUT</constant> and <constant>POLLWRNORM</constant> -flags. When the function timed out it returns a value of zero, on -failure it returns <returnvalue>-1</returnvalue> and the -<varname>errno</varname> variable is set appropriately. When the -application did not call &VIDIOC-STREAMON; the -<function>poll()</function> function succeeds, but sets the -<constant>POLLERR</constant> flag in the -<structfield>revents</structfield> field. When the -application has called &VIDIOC-STREAMON; for a capture device but hasn't -yet called &VIDIOC-QBUF;, the <function>poll()</function> function -succeeds and sets the <constant>POLLERR</constant> flag in the -<structfield>revents</structfield> field. For output devices this -same situation will cause <function>poll()</function> to succeed -as well, but it sets the <constant>POLLOUT</constant> and -<constant>POLLWRNORM</constant> flags in the <structfield>revents</structfield> -field.</para> - - <para>If an event occurred (see &VIDIOC-DQEVENT;) then -<constant>POLLPRI</constant> will be set in the <structfield>revents</structfield> -field and <function>poll()</function> will return.</para> - - <para>When use of the <function>read()</function> function has -been negotiated and the driver does not capture yet, the -<function>poll</function> function starts capturing. When that fails -it returns a <constant>POLLERR</constant> as above. Otherwise it waits -until data has been captured and can be read. When the driver captures -continuously (as opposed to, for example, still images) the function -may return immediately.</para> - - <para>When use of the <function>write()</function> function has -been negotiated and the driver does not stream yet, the -<function>poll</function> function starts streaming. When that fails -it returns a <constant>POLLERR</constant> as above. Otherwise it waits -until the driver is ready for a non-blocking -<function>write()</function> call.</para> - - <para>If the caller is only interested in events (just -<constant>POLLPRI</constant> is set in the <structfield>events</structfield> -field), then <function>poll()</function> will <emphasis>not</emphasis> -start streaming if the driver does not stream yet. This makes it -possible to just poll for events and not for buffers.</para> - - <para>All drivers implementing the <function>read()</function> or -<function>write()</function> function or streaming I/O must also -support the <function>poll()</function> function.</para> - - <para>For more details see the -<function>poll()</function> manual page.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, <function>poll()</function> returns the number -structures which have non-zero <structfield>revents</structfield> -fields, or zero if the call timed out. On error -<returnvalue>-1</returnvalue> is returned, and the -<varname>errno</varname> variable is set appropriately:</para> - - <variablelist> - <varlistentry> - <term><errorcode>EBADF</errorcode></term> - <listitem> - <para>One or more of the <parameter>ufds</parameter> members -specify an invalid file descriptor.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EBUSY</errorcode></term> - <listitem> - <para>The driver does not support multiple read or write -streams and the device is already in use.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EFAULT</errorcode></term> - <listitem> - <para><parameter>ufds</parameter> references an inaccessible -memory area.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EINTR</errorcode></term> - <listitem> - <para>The call was interrupted by a signal.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The <parameter>nfds</parameter> argument is greater -than <constant>OPEN_MAX</constant>.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/func-read.xml b/Documentation/DocBook/media/v4l/func-read.xml deleted file mode 100644 index e218bbfbd362..000000000000 --- a/Documentation/DocBook/media/v4l/func-read.xml +++ /dev/null @@ -1,181 +0,0 @@ -<refentry id="func-read"> - <refmeta> - <refentrytitle>V4L2 read()</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>v4l2-read</refname> - <refpurpose>Read from a V4L2 device</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <unistd.h></funcsynopsisinfo> - <funcprototype> - <funcdef>ssize_t <function>read</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>void *<parameter>buf</parameter></paramdef> - <paramdef>size_t <parameter>count</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>buf</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>count</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para><function>read()</function> attempts to read up to -<parameter>count</parameter> bytes from file descriptor -<parameter>fd</parameter> into the buffer starting at -<parameter>buf</parameter>. The layout of the data in the buffer is -discussed in the respective device interface section, see ##. If <parameter>count</parameter> is zero, -<function>read()</function> returns zero and has no other results. If -<parameter>count</parameter> is greater than -<constant>SSIZE_MAX</constant>, the result is unspecified. Regardless -of the <parameter>count</parameter> value each -<function>read()</function> call will provide at most one frame (two -fields) worth of data.</para> - - <para>By default <function>read()</function> blocks until data -becomes available. When the <constant>O_NONBLOCK</constant> flag was -given to the &func-open; function it -returns immediately with an &EAGAIN; when no data is available. The -&func-select; or &func-poll; functions -can always be used to suspend execution until data becomes available. All -drivers supporting the <function>read()</function> function must also -support <function>select()</function> and -<function>poll()</function>.</para> - - <para>Drivers can implement read functionality in different -ways, using a single or multiple buffers and discarding the oldest or -newest frames once the internal buffers are filled.</para> - - <para><function>read()</function> never returns a "snapshot" of a -buffer being filled. Using a single buffer the driver will stop -capturing when the application starts reading the buffer until the -read is finished. Thus only the period of the vertical blanking -interval is available for reading, or the capture rate must fall below -the nominal frame rate of the video standard.</para> - -<para>The behavior of -<function>read()</function> when called during the active picture -period or the vertical blanking separating the top and bottom field -depends on the discarding policy. A driver discarding the oldest -frames keeps capturing into an internal buffer, continuously -overwriting the previously, not read frame, and returns the frame -being received at the time of the <function>read()</function> call as -soon as it is complete.</para> - - <para>A driver discarding the newest frames stops capturing until -the next <function>read()</function> call. The frame being received at -<function>read()</function> time is discarded, returning the following -frame instead. Again this implies a reduction of the capture rate to -one half or less of the nominal frame rate. An example of this model -is the video read mode of the bttv driver, initiating a DMA to user -memory when <function>read()</function> is called and returning when -the DMA finished.</para> - - <para>In the multiple buffer model drivers maintain a ring of -internal buffers, automatically advancing to the next free buffer. -This allows continuous capturing when the application can empty the -buffers fast enough. Again, the behavior when the driver runs out of -free buffers depends on the discarding policy.</para> - - <para>Applications can get and set the number of buffers used -internally by the driver with the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; -ioctls. They are optional, however. The discarding policy is not -reported and cannot be changed. For minimum requirements see <xref - linkend="devices" />.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, the number of bytes read is returned. It is not -an error if this number is smaller than the number of bytes requested, -or the amount of data required for one frame. This may happen for -example because <function>read()</function> was interrupted by a -signal. On error, -1 is returned, and the <varname>errno</varname> -variable is set appropriately. In this case the next read will start -at the beginning of a new frame. Possible error codes are:</para> - - <variablelist> - <varlistentry> - <term><errorcode>EAGAIN</errorcode></term> - <listitem> - <para>Non-blocking I/O has been selected using -O_NONBLOCK and no data was immediately available for reading.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EBADF</errorcode></term> - <listitem> - <para><parameter>fd</parameter> is not a valid file -descriptor or is not open for reading, or the process already has the -maximum number of files open.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EBUSY</errorcode></term> - <listitem> - <para>The driver does not support multiple read streams and the -device is already in use.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EFAULT</errorcode></term> - <listitem> - <para><parameter>buf</parameter> references an inaccessible -memory area.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EINTR</errorcode></term> - <listitem> - <para>The call was interrupted by a signal before any -data was read.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EIO</errorcode></term> - <listitem> - <para>I/O error. This indicates some hardware problem or a -failure to communicate with a remote device (USB camera etc.).</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The <function>read()</function> function is not -supported by this driver, not on this device, or generally not on this -type of device.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/func-select.xml b/Documentation/DocBook/media/v4l/func-select.xml deleted file mode 100644 index e12a60d9bd85..000000000000 --- a/Documentation/DocBook/media/v4l/func-select.xml +++ /dev/null @@ -1,130 +0,0 @@ -<refentry id="func-select"> - <refmeta> - <refentrytitle>V4L2 select()</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>v4l2-select</refname> - <refpurpose>Synchronous I/O multiplexing</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo> -#include <sys/time.h> -#include <sys/types.h> -#include <unistd.h></funcsynopsisinfo> - <funcprototype> - <funcdef>int <function>select</function></funcdef> - <paramdef>int <parameter>nfds</parameter></paramdef> - <paramdef>fd_set *<parameter>readfds</parameter></paramdef> - <paramdef>fd_set *<parameter>writefds</parameter></paramdef> - <paramdef>fd_set *<parameter>exceptfds</parameter></paramdef> - <paramdef>struct timeval *<parameter>timeout</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>With the <function>select()</function> function applications -can suspend execution until the driver has captured data or is ready -to accept data for output.</para> - - <para>When streaming I/O has been negotiated this function waits -until a buffer has been filled or displayed and can be dequeued with -the &VIDIOC-DQBUF; ioctl. When buffers are already in the outgoing -queue of the driver the function returns immediately.</para> - - <para>On success <function>select()</function> returns the total -number of bits set in the <structname>fd_set</structname>s. When the -function timed out it returns a value of zero. On failure it returns -<returnvalue>-1</returnvalue> and the <varname>errno</varname> -variable is set appropriately. When the application did not call -&VIDIOC-QBUF; or &VIDIOC-STREAMON; yet the -<function>select()</function> function succeeds, setting the bit of -the file descriptor in <parameter>readfds</parameter> or -<parameter>writefds</parameter>, but subsequent &VIDIOC-DQBUF; calls -will fail.<footnote><para>The Linux kernel implements -<function>select()</function> like the &func-poll; function, but -<function>select()</function> cannot return a -<constant>POLLERR</constant>.</para> - </footnote></para> - - <para>When use of the <function>read()</function> function has -been negotiated and the driver does not capture yet, the -<function>select()</function> function starts capturing. When that -fails, <function>select()</function> returns successful and a -subsequent <function>read()</function> call, which also attempts to -start capturing, will return an appropriate error code. When the -driver captures continuously (as opposed to, for example, still -images) and data is already available the -<function>select()</function> function returns immediately.</para> - - <para>When use of the <function>write()</function> function has -been negotiated the <function>select()</function> function just waits -until the driver is ready for a non-blocking -<function>write()</function> call.</para> - - <para>All drivers implementing the <function>read()</function> or -<function>write()</function> function or streaming I/O must also -support the <function>select()</function> function.</para> - - <para>For more details see the <function>select()</function> -manual page.</para> - - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, <function>select()</function> returns the number -of descriptors contained in the three returned descriptor sets, which -will be zero if the timeout expired. On error -<returnvalue>-1</returnvalue> is returned, and the -<varname>errno</varname> variable is set appropriately; the sets and -<parameter>timeout</parameter> are undefined. Possible error codes -are:</para> - - <variablelist> - <varlistentry> - <term><errorcode>EBADF</errorcode></term> - <listitem> - <para>One or more of the file descriptor sets specified a -file descriptor that is not open.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EBUSY</errorcode></term> - <listitem> - <para>The driver does not support multiple read or write -streams and the device is already in use.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EFAULT</errorcode></term> - <listitem> - <para>The <parameter>readfds</parameter>, -<parameter>writefds</parameter>, <parameter>exceptfds</parameter> or -<parameter>timeout</parameter> pointer references an inaccessible memory -area.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EINTR</errorcode></term> - <listitem> - <para>The call was interrupted by a signal.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The <parameter>nfds</parameter> argument is less than -zero or greater than <constant>FD_SETSIZE</constant>.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/func-write.xml b/Documentation/DocBook/media/v4l/func-write.xml deleted file mode 100644 index 575207885726..000000000000 --- a/Documentation/DocBook/media/v4l/func-write.xml +++ /dev/null @@ -1,128 +0,0 @@ -<refentry id="func-write"> - <refmeta> - <refentrytitle>V4L2 write()</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>v4l2-write</refname> - <refpurpose>Write to a V4L2 device</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <unistd.h></funcsynopsisinfo> - <funcprototype> - <funcdef>ssize_t <function>write</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>void *<parameter>buf</parameter></paramdef> - <paramdef>size_t <parameter>count</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>buf</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>count</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para><function>write()</function> writes up to -<parameter>count</parameter> bytes to the device referenced by the -file descriptor <parameter>fd</parameter> from the buffer starting at -<parameter>buf</parameter>. When the hardware outputs are not active -yet, this function enables them. When <parameter>count</parameter> is -zero, <function>write()</function> returns -<returnvalue>0</returnvalue> without any other effect.</para> - - <para>When the application does not provide more data in time, the -previous video frame, raw VBI image, sliced VPS or WSS data is -displayed again. Sliced Teletext or Closed Caption data is not -repeated, the driver inserts a blank line instead.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, the number of bytes written are returned. Zero -indicates nothing was written. On error, <returnvalue>-1</returnvalue> -is returned, and the <varname>errno</varname> variable is set -appropriately. In this case the next write will start at the beginning -of a new frame. Possible error codes are:</para> - - <variablelist> - <varlistentry> - <term><errorcode>EAGAIN</errorcode></term> - <listitem> - <para>Non-blocking I/O has been selected using the <link -linkend="func-open"><constant>O_NONBLOCK</constant></link> flag and no -buffer space was available to write the data immediately.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EBADF</errorcode></term> - <listitem> - <para><parameter>fd</parameter> is not a valid file -descriptor or is not open for writing.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EBUSY</errorcode></term> - <listitem> - <para>The driver does not support multiple write streams and the -device is already in use.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EFAULT</errorcode></term> - <listitem> - <para><parameter>buf</parameter> references an inaccessible -memory area.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EINTR</errorcode></term> - <listitem> - <para>The call was interrupted by a signal before any -data was written.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EIO</errorcode></term> - <listitem> - <para>I/O error. This indicates some hardware problem.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The <function>write()</function> function is not -supported by this driver, not on this device, or generally not on this -type of device.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/gen-errors.xml b/Documentation/DocBook/media/v4l/gen-errors.xml deleted file mode 100644 index 7e29a4e1f696..000000000000 --- a/Documentation/DocBook/media/v4l/gen-errors.xml +++ /dev/null @@ -1,77 +0,0 @@ -<title>Generic Error Codes</title> - -<table frame="none" pgwide="1" id="gen-errors"> - <title>Generic error codes</title> - <tgroup cols="2"> - &cs-str; - <tbody valign="top"> - <!-- Keep it ordered alphabetically --> - <row> - <entry>EAGAIN (aka EWOULDBLOCK)</entry> - <entry>The ioctl can't be handled because the device is in state where - it can't perform it. This could happen for example in case where - device is sleeping and ioctl is performed to query statistics. - It is also returned when the ioctl would need to wait - for an event, but the device was opened in non-blocking mode. - </entry> - </row> - <row> - <entry>EBADF</entry> - <entry>The file descriptor is not a valid.</entry> - </row> - <row> - <entry>EBUSY</entry> - <entry>The ioctl can't be handled because the device is busy. This is - typically return while device is streaming, and an ioctl tried to - change something that would affect the stream, or would require the - usage of a hardware resource that was already allocated. The ioctl - must not be retried without performing another action to fix the - problem first (typically: stop the stream before retrying).</entry> - </row> - <row> - <entry>EFAULT</entry> - <entry>There was a failure while copying data from/to userspace, - probably caused by an invalid pointer reference.</entry> - </row> - <row> - <entry>EINVAL</entry> - <entry>One or more of the ioctl parameters are invalid or out of the - allowed range. This is a widely used error code. See the individual - ioctl requests for specific causes.</entry> - </row> - <row> - <entry>ENODEV</entry> - <entry>Device not found or was removed.</entry> - </row> - <row> - <entry>ENOMEM</entry> - <entry>There's not enough memory to handle the desired operation.</entry> - </row> - <row> - <entry>ENOTTY</entry> - <entry>The ioctl is not supported by the driver, actually meaning that - the required functionality is not available, or the file - descriptor is not for a media device.</entry> - </row> - <row> - <entry>ENOSPC</entry> - <entry>On USB devices, the stream ioctl's can return this error, meaning - that this request would overcommit the usb bandwidth reserved - for periodic transfers (up to 80% of the USB bandwidth).</entry> - </row> - <row> - <entry>EPERM</entry> - <entry>Permission denied. Can be returned if the device needs write - permission, or some special capabilities is needed - (e. g. root)</entry> - </row> - </tbody> - </tgroup> -</table> - -<para>Note 1: ioctls may return other error codes. Since errors may have side -effects such as a driver reset, applications should abort on unexpected errors. -</para> - -<para>Note 2: Request-specific error codes are listed in the individual -requests descriptions.</para> diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml deleted file mode 100644 index 144158b3a5ac..000000000000 --- a/Documentation/DocBook/media/v4l/io.xml +++ /dev/null @@ -1,1551 +0,0 @@ - <title>Input/Output</title> - - <para>The V4L2 API defines several different methods to read from or -write to a device. All drivers exchanging data with applications must -support at least one of them.</para> - - <para>The classic I/O method using the <function>read()</function> -and <function>write()</function> function is automatically selected -after opening a V4L2 device. When the driver does not support this -method attempts to read or write will fail at any time.</para> - - <para>Other methods must be negotiated. To select the streaming I/O -method with memory mapped or user buffers applications call the -&VIDIOC-REQBUFS; ioctl. The asynchronous I/O method is not defined -yet.</para> - - <para>Video overlay can be considered another I/O method, although -the application does not directly receive the image data. It is -selected by initiating video overlay with the &VIDIOC-S-FMT; ioctl. -For more information see <xref linkend="overlay" />.</para> - - <para>Generally exactly one I/O method, including overlay, is -associated with each file descriptor. The only exceptions are -applications not exchanging data with a driver ("panel applications", -see <xref linkend="open" />) and drivers permitting simultaneous video capturing -and overlay using the same file descriptor, for compatibility with V4L -and earlier versions of V4L2.</para> - - <para><constant>VIDIOC_S_FMT</constant> and -<constant>VIDIOC_REQBUFS</constant> would permit this to some degree, -but for simplicity drivers need not support switching the I/O method -(after first switching away from read/write) other than by closing -and reopening the device.</para> - - <para>The following sections describe the various I/O methods in -more detail.</para> - - <section id="rw"> - <title>Read/Write</title> - - <para>Input and output devices support the -<function>read()</function> and <function>write()</function> function, -respectively, when the <constant>V4L2_CAP_READWRITE</constant> flag in -the <structfield>capabilities</structfield> field of &v4l2-capability; -returned by the &VIDIOC-QUERYCAP; ioctl is set.</para> - - <para>Drivers may need the CPU to copy the data, but they may also -support DMA to or from user memory, so this I/O method is not -necessarily less efficient than other methods merely exchanging buffer -pointers. It is considered inferior though because no meta-information -like frame counters or timestamps are passed. This information is -necessary to recognize frame dropping and to synchronize with other -data streams. However this is also the simplest I/O method, requiring -little or no setup to exchange data. It permits command line stunts -like this (the <application>vidctrl</application> tool is -fictitious):</para> - - <informalexample> - <screen> -> vidctrl /dev/video --input=0 --format=YUYV --size=352x288 -> dd if=/dev/video of=myimage.422 bs=202752 count=1 -</screen> - </informalexample> - - <para>To read from the device applications use the -&func-read; function, to write the &func-write; function. -Drivers must implement one I/O method if they -exchange data with applications, but it need not be this.<footnote> - <para>It would be desirable if applications could depend on -drivers supporting all I/O interfaces, but as much as the complex -memory mapping I/O can be inadequate for some devices we have no -reason to require this interface, which is most useful for simple -applications capturing still images.</para> - </footnote> When reading or writing is supported, the driver -must also support the &func-select; and &func-poll; -function.<footnote> - <para>At the driver level <function>select()</function> and -<function>poll()</function> are the same, and -<function>select()</function> is too important to be optional.</para> - </footnote></para> - </section> - - <section id="mmap"> - <title>Streaming I/O (Memory Mapping)</title> - - <para>Input and output devices support this I/O method when the -<constant>V4L2_CAP_STREAMING</constant> flag in the -<structfield>capabilities</structfield> field of &v4l2-capability; -returned by the &VIDIOC-QUERYCAP; ioctl is set. There are two -streaming methods, to determine if the memory mapping flavor is -supported applications must call the &VIDIOC-REQBUFS; ioctl.</para> - - <para>Streaming is an I/O method where only pointers to buffers -are exchanged between application and driver, the data itself is not -copied. Memory mapping is primarily intended to map buffers in device -memory into the application's address space. Device memory can be for -example the video memory on a graphics card with a video capture -add-on. However, being the most efficient I/O method available for a -long time, many other drivers support streaming as well, allocating -buffers in DMA-able main memory.</para> - - <para>A driver can support many sets of buffers. Each set is -identified by a unique buffer type value. The sets are independent and -each set can hold a different type of data. To access different sets -at the same time different file descriptors must be used.<footnote> - <para>One could use one file descriptor and set the buffer -type field accordingly when calling &VIDIOC-QBUF; etc., but it makes -the <function>select()</function> function ambiguous. We also like the -clean approach of one file descriptor per logical stream. Video -overlay for example is also a logical stream, although the CPU is not -needed for continuous operation.</para> - </footnote></para> - - <para>To allocate device buffers applications call the -&VIDIOC-REQBUFS; ioctl with the desired number of buffers and buffer -type, for example <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>. -This ioctl can also be used to change the number of buffers or to free -the allocated memory, provided none of the buffers are still -mapped.</para> - - <para>Before applications can access the buffers they must map -them into their address space with the &func-mmap; function. The -location of the buffers in device memory can be determined with the -&VIDIOC-QUERYBUF; ioctl. In the single-planar API case, the -<structfield>m.offset</structfield> and <structfield>length</structfield> -returned in a &v4l2-buffer; are passed as sixth and second parameter to the -<function>mmap()</function> function. When using the multi-planar API, -&v4l2-buffer; contains an array of &v4l2-plane; structures, each -containing its own <structfield>m.offset</structfield> and -<structfield>length</structfield>. When using the multi-planar API, every -plane of every buffer has to be mapped separately, so the number of -calls to &func-mmap; should be equal to number of buffers times number of -planes in each buffer. The offset and length values must not be modified. -Remember, the buffers are allocated in physical memory, as opposed to virtual -memory, which can be swapped out to disk. Applications should free the buffers -as soon as possible with the &func-munmap; function.</para> - - <example> - <title>Mapping buffers in the single-planar API</title> - <programlisting> -&v4l2-requestbuffers; reqbuf; -struct { - void *start; - size_t length; -} *buffers; -unsigned int i; - -memset(&reqbuf, 0, sizeof(reqbuf)); -reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; -reqbuf.memory = V4L2_MEMORY_MMAP; -reqbuf.count = 20; - -if (-1 == ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf)) { - if (errno == EINVAL) - printf("Video capturing or mmap-streaming is not supported\n"); - else - perror("VIDIOC_REQBUFS"); - - exit(EXIT_FAILURE); -} - -/* We want at least five buffers. */ - -if (reqbuf.count < 5) { - /* You may need to free the buffers here. */ - printf("Not enough buffer memory\n"); - exit(EXIT_FAILURE); -} - -buffers = calloc(reqbuf.count, sizeof(*buffers)); -assert(buffers != NULL); - -for (i = 0; i < reqbuf.count; i++) { - &v4l2-buffer; buffer; - - memset(&buffer, 0, sizeof(buffer)); - buffer.type = reqbuf.type; - buffer.memory = V4L2_MEMORY_MMAP; - buffer.index = i; - - if (-1 == ioctl (fd, &VIDIOC-QUERYBUF;, &buffer)) { - perror("VIDIOC_QUERYBUF"); - exit(EXIT_FAILURE); - } - - buffers[i].length = buffer.length; /* remember for munmap() */ - - buffers[i].start = mmap(NULL, buffer.length, - PROT_READ | PROT_WRITE, /* recommended */ - MAP_SHARED, /* recommended */ - fd, buffer.m.offset); - - if (MAP_FAILED == buffers[i].start) { - /* If you do not exit here you should unmap() and free() - the buffers mapped so far. */ - perror("mmap"); - exit(EXIT_FAILURE); - } -} - -/* Cleanup. */ - -for (i = 0; i < reqbuf.count; i++) - munmap(buffers[i].start, buffers[i].length); - </programlisting> - </example> - - <example> - <title>Mapping buffers in the multi-planar API</title> - <programlisting> -&v4l2-requestbuffers; reqbuf; -/* Our current format uses 3 planes per buffer */ -#define FMT_NUM_PLANES = 3 - -struct { - void *start[FMT_NUM_PLANES]; - size_t length[FMT_NUM_PLANES]; -} *buffers; -unsigned int i, j; - -memset(&reqbuf, 0, sizeof(reqbuf)); -reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE; -reqbuf.memory = V4L2_MEMORY_MMAP; -reqbuf.count = 20; - -if (ioctl(fd, &VIDIOC-REQBUFS;, &reqbuf) < 0) { - if (errno == EINVAL) - printf("Video capturing or mmap-streaming is not supported\n"); - else - perror("VIDIOC_REQBUFS"); - - exit(EXIT_FAILURE); -} - -/* We want at least five buffers. */ - -if (reqbuf.count < 5) { - /* You may need to free the buffers here. */ - printf("Not enough buffer memory\n"); - exit(EXIT_FAILURE); -} - -buffers = calloc(reqbuf.count, sizeof(*buffers)); -assert(buffers != NULL); - -for (i = 0; i < reqbuf.count; i++) { - &v4l2-buffer; buffer; - &v4l2-plane; planes[FMT_NUM_PLANES]; - - memset(&buffer, 0, sizeof(buffer)); - buffer.type = reqbuf.type; - buffer.memory = V4L2_MEMORY_MMAP; - buffer.index = i; - /* length in struct v4l2_buffer in multi-planar API stores the size - * of planes array. */ - buffer.length = FMT_NUM_PLANES; - buffer.m.planes = planes; - - if (ioctl(fd, &VIDIOC-QUERYBUF;, &buffer) < 0) { - perror("VIDIOC_QUERYBUF"); - exit(EXIT_FAILURE); - } - - /* Every plane has to be mapped separately */ - for (j = 0; j < FMT_NUM_PLANES; j++) { - buffers[i].length[j] = buffer.m.planes[j].length; /* remember for munmap() */ - - buffers[i].start[j] = mmap(NULL, buffer.m.planes[j].length, - PROT_READ | PROT_WRITE, /* recommended */ - MAP_SHARED, /* recommended */ - fd, buffer.m.planes[j].m.offset); - - if (MAP_FAILED == buffers[i].start[j]) { - /* If you do not exit here you should unmap() and free() - the buffers and planes mapped so far. */ - perror("mmap"); - exit(EXIT_FAILURE); - } - } -} - -/* Cleanup. */ - -for (i = 0; i < reqbuf.count; i++) - for (j = 0; j < FMT_NUM_PLANES; j++) - munmap(buffers[i].start[j], buffers[i].length[j]); - </programlisting> - </example> - - <para>Conceptually streaming drivers maintain two buffer queues, an incoming -and an outgoing queue. They separate the synchronous capture or output -operation locked to a video clock from the application which is -subject to random disk or network delays and preemption by -other processes, thereby reducing the probability of data loss. -The queues are organized as FIFOs, buffers will be -output in the order enqueued in the incoming FIFO, and were -captured in the order dequeued from the outgoing FIFO.</para> - - <para>The driver may require a minimum number of buffers enqueued -at all times to function, apart of this no limit exists on the number -of buffers applications can enqueue in advance, or dequeue and -process. They can also enqueue in a different order than buffers have -been dequeued, and the driver can <emphasis>fill</emphasis> enqueued -<emphasis>empty</emphasis> buffers in any order. <footnote> - <para>Random enqueue order permits applications processing -images out of order (such as video codecs) to return buffers earlier, -reducing the probability of data loss. Random fill order allows -drivers to reuse buffers on a LIFO-basis, taking advantage of caches -holding scatter-gather lists and the like.</para> - </footnote> The index number of a buffer (&v4l2-buffer; -<structfield>index</structfield>) plays no role here, it only -identifies the buffer.</para> - - <para>Initially all mapped buffers are in dequeued state, -inaccessible by the driver. For capturing applications it is customary -to first enqueue all mapped buffers, then to start capturing and enter -the read loop. Here the application waits until a filled buffer can be -dequeued, and re-enqueues the buffer when the data is no longer -needed. Output applications fill and enqueue buffers, when enough -buffers are stacked up the output is started with -<constant>VIDIOC_STREAMON</constant>. In the write loop, when -the application runs out of free buffers, it must wait until an empty -buffer can be dequeued and reused.</para> - - <para>To enqueue and dequeue a buffer applications use the -&VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. The status of a buffer being -mapped, enqueued, full or empty can be determined at any time using the -&VIDIOC-QUERYBUF; ioctl. Two methods exist to suspend execution of the -application until one or more buffers can be dequeued. By default -<constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the -outgoing queue. When the <constant>O_NONBLOCK</constant> flag was -given to the &func-open; function, <constant>VIDIOC_DQBUF</constant> -returns immediately with an &EAGAIN; when no buffer is available. The -&func-select; or &func-poll; functions are always available.</para> - - <para>To start and stop capturing or output applications call the -&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note -<constant>VIDIOC_STREAMOFF</constant> removes all buffers from both -queues as a side effect. Since there is no notion of doing anything -"now" on a multitasking system, if an application needs to synchronize -with another event it should examine the &v4l2-buffer; -<structfield>timestamp</structfield> of captured or outputted buffers. -</para> - - <para>Drivers implementing memory mapping I/O must -support the <constant>VIDIOC_REQBUFS</constant>, -<constant>VIDIOC_QUERYBUF</constant>, -<constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>, -<constant>VIDIOC_STREAMON</constant> and -<constant>VIDIOC_STREAMOFF</constant> ioctl, the -<function>mmap()</function>, <function>munmap()</function>, -<function>select()</function> and <function>poll()</function> -function.<footnote> - <para>At the driver level <function>select()</function> and -<function>poll()</function> are the same, and -<function>select()</function> is too important to be optional. The -rest should be evident.</para> - </footnote></para> - - <para>[capture example]</para> - - </section> - - <section id="userp"> - <title>Streaming I/O (User Pointers)</title> - - <para>Input and output devices support this I/O method when the -<constant>V4L2_CAP_STREAMING</constant> flag in the -<structfield>capabilities</structfield> field of &v4l2-capability; -returned by the &VIDIOC-QUERYCAP; ioctl is set. If the particular user -pointer method (not only memory mapping) is supported must be -determined by calling the &VIDIOC-REQBUFS; ioctl.</para> - - <para>This I/O method combines advantages of the read/write and -memory mapping methods. Buffers (planes) are allocated by the application -itself, and can reside for example in virtual or shared memory. Only -pointers to data are exchanged, these pointers and meta-information -are passed in &v4l2-buffer; (or in &v4l2-plane; in the multi-planar API case). -The driver must be switched into user pointer I/O mode by calling the -&VIDIOC-REQBUFS; with the desired buffer type. No buffers (planes) are allocated -beforehand, consequently they are not indexed and cannot be queried like mapped -buffers with the <constant>VIDIOC_QUERYBUF</constant> ioctl.</para> - - <example> - <title>Initiating streaming I/O with user pointers</title> - - <programlisting> -&v4l2-requestbuffers; reqbuf; - -memset (&reqbuf, 0, sizeof (reqbuf)); -reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; -reqbuf.memory = V4L2_MEMORY_USERPTR; - -if (ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) { - if (errno == EINVAL) - printf ("Video capturing or user pointer streaming is not supported\n"); - else - perror ("VIDIOC_REQBUFS"); - - exit (EXIT_FAILURE); -} - </programlisting> - </example> - - <para>Buffer (plane) addresses and sizes are passed on the fly with the -&VIDIOC-QBUF; ioctl. Although buffers are commonly cycled, -applications can pass different addresses and sizes at each -<constant>VIDIOC_QBUF</constant> call. If required by the hardware the -driver swaps memory pages within physical memory to create a -continuous area of memory. This happens transparently to the -application in the virtual memory subsystem of the kernel. When buffer -pages have been swapped out to disk they are brought back and finally -locked in physical memory for DMA.<footnote> - <para>We expect that frequently used buffers are typically not -swapped out. Anyway, the process of swapping, locking or generating -scatter-gather lists may be time consuming. The delay can be masked by -the depth of the incoming buffer queue, and perhaps by maintaining -caches assuming a buffer will be soon enqueued again. On the other -hand, to optimize memory usage drivers can limit the number of buffers -locked in advance and recycle the most recently used buffers first. Of -course, the pages of empty buffers in the incoming queue need not be -saved to disk. Output buffers must be saved on the incoming and -outgoing queue because an application may share them with other -processes.</para> - </footnote></para> - - <para>Filled or displayed buffers are dequeued with the -&VIDIOC-DQBUF; ioctl. The driver can unlock the memory pages at any -time between the completion of the DMA and this ioctl. The memory is -also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or -when the device is closed. Applications must take care not to free -buffers without dequeuing. For once, the buffers remain locked until -further, wasting physical memory. Second the driver will not be -notified when the memory is returned to the application's free list -and subsequently reused for other purposes, possibly completing the -requested DMA and overwriting valuable data.</para> - - <para>For capturing applications it is customary to enqueue a -number of empty buffers, to start capturing and enter the read loop. -Here the application waits until a filled buffer can be dequeued, and -re-enqueues the buffer when the data is no longer needed. Output -applications fill and enqueue buffers, when enough buffers are stacked -up output is started. In the write loop, when the application -runs out of free buffers it must wait until an empty buffer can be -dequeued and reused. Two methods exist to suspend execution of the -application until one or more buffers can be dequeued. By default -<constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the -outgoing queue. When the <constant>O_NONBLOCK</constant> flag was -given to the &func-open; function, <constant>VIDIOC_DQBUF</constant> -returns immediately with an &EAGAIN; when no buffer is available. The -&func-select; or &func-poll; function are always available.</para> - - <para>To start and stop capturing or output applications call the -&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note -<constant>VIDIOC_STREAMOFF</constant> removes all buffers from both -queues and unlocks all buffers as a side effect. Since there is no -notion of doing anything "now" on a multitasking system, if an -application needs to synchronize with another event it should examine -the &v4l2-buffer; <structfield>timestamp</structfield> of captured -or outputted buffers.</para> - - <para>Drivers implementing user pointer I/O must -support the <constant>VIDIOC_REQBUFS</constant>, -<constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>, -<constant>VIDIOC_STREAMON</constant> and -<constant>VIDIOC_STREAMOFF</constant> ioctl, the -<function>select()</function> and <function>poll()</function> function.<footnote> - <para>At the driver level <function>select()</function> and -<function>poll()</function> are the same, and -<function>select()</function> is too important to be optional. The -rest should be evident.</para> - </footnote></para> - </section> - - <section id="dmabuf"> - <title>Streaming I/O (DMA buffer importing)</title> - - <note> - <title>Experimental</title> - <para>This is an <link linkend="experimental">experimental</link> - interface and may change in the future.</para> - </note> - -<para>The DMABUF framework provides a generic method for sharing buffers -between multiple devices. Device drivers that support DMABUF can export a DMA -buffer to userspace as a file descriptor (known as the exporter role), import a -DMA buffer from userspace using a file descriptor previously exported for a -different or the same device (known as the importer role), or both. This -section describes the DMABUF importer role API in V4L2.</para> - - <para>Refer to <link linkend="vidioc-expbuf">DMABUF exporting</link> for -details about exporting V4L2 buffers as DMABUF file descriptors.</para> - -<para>Input and output devices support the streaming I/O method when the -<constant>V4L2_CAP_STREAMING</constant> flag in the -<structfield>capabilities</structfield> field of &v4l2-capability; returned by -the &VIDIOC-QUERYCAP; ioctl is set. Whether importing DMA buffers through -DMABUF file descriptors is supported is determined by calling the -&VIDIOC-REQBUFS; ioctl with the memory type set to -<constant>V4L2_MEMORY_DMABUF</constant>.</para> - - <para>This I/O method is dedicated to sharing DMA buffers between different -devices, which may be V4L devices or other video-related devices (e.g. DRM). -Buffers (planes) are allocated by a driver on behalf of an application. Next, -these buffers are exported to the application as file descriptors using an API -which is specific for an allocator driver. Only such file descriptor are -exchanged. The descriptors and meta-information are passed in &v4l2-buffer; (or -in &v4l2-plane; in the multi-planar API case). The driver must be switched -into DMABUF I/O mode by calling the &VIDIOC-REQBUFS; with the desired buffer -type.</para> - - <example> - <title>Initiating streaming I/O with DMABUF file descriptors</title> - - <programlisting> -&v4l2-requestbuffers; reqbuf; - -memset(&reqbuf, 0, sizeof (reqbuf)); -reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; -reqbuf.memory = V4L2_MEMORY_DMABUF; -reqbuf.count = 1; - -if (ioctl(fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) { - if (errno == EINVAL) - printf("Video capturing or DMABUF streaming is not supported\n"); - else - perror("VIDIOC_REQBUFS"); - - exit(EXIT_FAILURE); -} - </programlisting> - </example> - - <para>The buffer (plane) file descriptor is passed on the fly with the -&VIDIOC-QBUF; ioctl. In case of multiplanar buffers, every plane can be -associated with a different DMABUF descriptor. Although buffers are commonly -cycled, applications can pass a different DMABUF descriptor at each -<constant>VIDIOC_QBUF</constant> call.</para> - - <example> - <title>Queueing DMABUF using single plane API</title> - - <programlisting> -int buffer_queue(int v4lfd, int index, int dmafd) -{ - &v4l2-buffer; buf; - - memset(&buf, 0, sizeof buf); - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - buf.memory = V4L2_MEMORY_DMABUF; - buf.index = index; - buf.m.fd = dmafd; - - if (ioctl(v4lfd, &VIDIOC-QBUF;, &buf) == -1) { - perror("VIDIOC_QBUF"); - return -1; - } - - return 0; -} - </programlisting> - </example> - - <example> - <title>Queueing DMABUF using multi plane API</title> - - <programlisting> -int buffer_queue_mp(int v4lfd, int index, int dmafd[], int n_planes) -{ - &v4l2-buffer; buf; - &v4l2-plane; planes[VIDEO_MAX_PLANES]; - int i; - - memset(&buf, 0, sizeof buf); - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE; - buf.memory = V4L2_MEMORY_DMABUF; - buf.index = index; - buf.m.planes = planes; - buf.length = n_planes; - - memset(&planes, 0, sizeof planes); - - for (i = 0; i < n_planes; ++i) - buf.m.planes[i].m.fd = dmafd[i]; - - if (ioctl(v4lfd, &VIDIOC-QBUF;, &buf) == -1) { - perror("VIDIOC_QBUF"); - return -1; - } - - return 0; -} - </programlisting> - </example> - - <para>Captured or displayed buffers are dequeued with the -&VIDIOC-DQBUF; ioctl. The driver can unlock the buffer at any -time between the completion of the DMA and this ioctl. The memory is -also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or -when the device is closed.</para> - - <para>For capturing applications it is customary to enqueue a -number of empty buffers, to start capturing and enter the read loop. -Here the application waits until a filled buffer can be dequeued, and -re-enqueues the buffer when the data is no longer needed. Output -applications fill and enqueue buffers, when enough buffers are stacked -up output is started. In the write loop, when the application -runs out of free buffers it must wait until an empty buffer can be -dequeued and reused. Two methods exist to suspend execution of the -application until one or more buffers can be dequeued. By default -<constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the -outgoing queue. When the <constant>O_NONBLOCK</constant> flag was -given to the &func-open; function, <constant>VIDIOC_DQBUF</constant> -returns immediately with an &EAGAIN; when no buffer is available. The -&func-select; and &func-poll; functions are always available.</para> - - <para>To start and stop capturing or displaying applications call the -&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctls. Note that -<constant>VIDIOC_STREAMOFF</constant> removes all buffers from both queues and -unlocks all buffers as a side effect. Since there is no notion of doing -anything "now" on a multitasking system, if an application needs to synchronize -with another event it should examine the &v4l2-buffer; -<structfield>timestamp</structfield> of captured or outputted buffers.</para> - - <para>Drivers implementing DMABUF importing I/O must support the -<constant>VIDIOC_REQBUFS</constant>, <constant>VIDIOC_QBUF</constant>, -<constant>VIDIOC_DQBUF</constant>, <constant>VIDIOC_STREAMON</constant> and -<constant>VIDIOC_STREAMOFF</constant> ioctls, and the -<function>select()</function> and <function>poll()</function> functions.</para> - - </section> - - <section id="async"> - <title>Asynchronous I/O</title> - - <para>This method is not defined yet.</para> - </section> - - <section id="buffer"> - <title>Buffers</title> - - <para>A buffer contains data exchanged by application and -driver using one of the Streaming I/O methods. In the multi-planar API, the -data is held in planes, while the buffer structure acts as a container -for the planes. Only pointers to buffers (planes) are exchanged, the data -itself is not copied. These pointers, together with meta-information like -timestamps or field parity, are stored in a struct -<structname>v4l2_buffer</structname>, argument to -the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. -In the multi-planar API, some plane-specific members of struct -<structname>v4l2_buffer</structname>, such as pointers and sizes for each -plane, are stored in struct <structname>v4l2_plane</structname> instead. -In that case, struct <structname>v4l2_buffer</structname> contains an array of -plane structures.</para> - - <para>Dequeued video buffers come with timestamps. The driver - decides at which part of the frame and with which clock the - timestamp is taken. Please see flags in the masks - <constant>V4L2_BUF_FLAG_TIMESTAMP_MASK</constant> and - <constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant> in <xref - linkend="buffer-flags" />. These flags are always valid and constant - across all buffers during the whole video stream. Changes in these - flags may take place as a side effect of &VIDIOC-S-INPUT; or - &VIDIOC-S-OUTPUT; however. The - <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> timestamp type - which is used by e.g. on mem-to-mem devices is an exception to the - rule: the timestamp source flags are copied from the OUTPUT video - buffer to the CAPTURE video buffer.</para> - - <table frame="none" pgwide="1" id="v4l2-buffer"> - <title>struct <structname>v4l2_buffer</structname></title> - <tgroup cols="4"> - &cs-ustr; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>index</structfield></entry> - <entry></entry> - <entry>Number of the buffer, set by the application except -when calling &VIDIOC-DQBUF;, then it is set by the driver. -This field can range from zero to the number of buffers allocated -with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>), -plus any buffers allocated with &VIDIOC-CREATE-BUFS; minus one.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry></entry> - <entry>Type of the buffer, same as &v4l2-format; -<structfield>type</structfield> or &v4l2-requestbuffers; -<structfield>type</structfield>, set by the application. See <xref -linkend="v4l2-buf-type" /></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>bytesused</structfield></entry> - <entry></entry> - <entry>The number of bytes occupied by the data in the -buffer. It depends on the negotiated data format and may change with -each buffer for compressed variable size data like JPEG images. -Drivers must set this field when <structfield>type</structfield> -refers to a capture stream, applications when it refers to an output stream. -If the application sets this to 0 for an output stream, then -<structfield>bytesused</structfield> will be set to the size of the -buffer (see the <structfield>length</structfield> field of this struct) by -the driver. For multiplanar formats this field is ignored and the -<structfield>planes</structfield> pointer is used instead.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry></entry> - <entry>Flags set by the application or driver, see <xref -linkend="buffer-flags" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>field</structfield></entry> - <entry></entry> - <entry>Indicates the field order of the image in the -buffer, see <xref linkend="v4l2-field" />. This field is not used when -the buffer contains VBI data. Drivers must set it when -<structfield>type</structfield> refers to a capture stream, -applications when it refers to an output stream.</entry> - </row> - <row> - <entry>struct timeval</entry> - <entry><structfield>timestamp</structfield></entry> - <entry></entry> - <entry><para>For capture streams this is time when the first data - byte was captured, as returned by the - <function>clock_gettime()</function> function for the relevant - clock id; see <constant>V4L2_BUF_FLAG_TIMESTAMP_*</constant> in - <xref linkend="buffer-flags" />. For output streams the driver - stores the time at which the last data byte was actually sent out - in the <structfield>timestamp</structfield> field. This permits - applications to monitor the drift between the video and system - clock. For output streams that use <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> - the application has to fill in the timestamp which will be copied - by the driver to the capture stream.</para></entry> - </row> - <row> - <entry>&v4l2-timecode;</entry> - <entry><structfield>timecode</structfield></entry> - <entry></entry> - <entry>When <structfield>type</structfield> is -<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and the -<constant>V4L2_BUF_FLAG_TIMECODE</constant> flag is set in -<structfield>flags</structfield>, this structure contains a frame -timecode. In <link linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> -mode the top and bottom field contain the same timecode. -Timecodes are intended to help video editing and are typically recorded on -video tapes, but also embedded in compressed formats like MPEG. This -field is independent of the <structfield>timestamp</structfield> and -<structfield>sequence</structfield> fields.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>sequence</structfield></entry> - <entry></entry> - <entry>Set by the driver, counting the frames (not fields!) in -sequence. This field is set for both input and output devices.</entry> - </row> - <row> - <entry spanname="hspan"><para>In <link -linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> mode the top and -bottom field have the same sequence number. The count starts at zero -and includes dropped or repeated frames. A dropped frame was received -by an input device but could not be stored due to lack of free buffer -space. A repeated frame was displayed again by an output device -because the application did not pass new data in -time.</para><para>Note this may count the frames received -e.g. over USB, without taking into account the frames dropped by the -remote hardware due to limited compression throughput or bus -bandwidth. These devices identify by not enumerating any video -standards, see <xref linkend="standard" />.</para></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>memory</structfield></entry> - <entry></entry> - <entry>This field must be set by applications and/or drivers -in accordance with the selected I/O method. See <xref linkend="v4l2-memory" - /></entry> - </row> - <row> - <entry>union</entry> - <entry><structfield>m</structfield></entry> - </row> - <row> - <entry></entry> - <entry>__u32</entry> - <entry><structfield>offset</structfield></entry> - <entry>For the single-planar API and when -<structfield>memory</structfield> is <constant>V4L2_MEMORY_MMAP</constant> this -is the offset of the buffer from the start of the device memory. The value is -returned by the driver and apart of serving as parameter to the &func-mmap; -function not useful for applications. See <xref linkend="mmap" /> for details - </entry> - </row> - <row> - <entry></entry> - <entry>unsigned long</entry> - <entry><structfield>userptr</structfield></entry> - <entry>For the single-planar API and when -<structfield>memory</structfield> is <constant>V4L2_MEMORY_USERPTR</constant> -this is a pointer to the buffer (casted to unsigned long type) in virtual -memory, set by the application. See <xref linkend="userp" /> for details. - </entry> - </row> - <row> - <entry></entry> - <entry>struct v4l2_plane</entry> - <entry><structfield>*planes</structfield></entry> - <entry>When using the multi-planar API, contains a userspace pointer - to an array of &v4l2-plane;. The size of the array should be put - in the <structfield>length</structfield> field of this - <structname>v4l2_buffer</structname> structure.</entry> - </row> - <row> - <entry></entry> - <entry>int</entry> - <entry><structfield>fd</structfield></entry> - <entry>For the single-plane API and when -<structfield>memory</structfield> is <constant>V4L2_MEMORY_DMABUF</constant> this -is the file descriptor associated with a DMABUF buffer.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>length</structfield></entry> - <entry></entry> - <entry>Size of the buffer (not the payload) in bytes for the - single-planar API. This is set by the driver based on the calls to - &VIDIOC-REQBUFS; and/or &VIDIOC-CREATE-BUFS;. For the multi-planar API the application sets - this to the number of elements in the <structfield>planes</structfield> - array. The driver will fill in the actual number of valid elements in - that array. - </entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved2</structfield></entry> - <entry></entry> - <entry>A place holder for future extensions. Drivers and applications -must set this to 0.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield></entry> - <entry></entry> - <entry>A place holder for future extensions. Drivers and applications -must set this to 0.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="v4l2-plane"> - <title>struct <structname>v4l2_plane</structname></title> - <tgroup cols="4"> - &cs-ustr; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>bytesused</structfield></entry> - <entry></entry> - <entry>The number of bytes occupied by data in the plane - (its payload). Drivers must set this field when <structfield>type</structfield> - refers to a capture stream, applications when it refers to an output stream. - If the application sets this to 0 for an output stream, then - <structfield>bytesused</structfield> will be set to the size of the - plane (see the <structfield>length</structfield> field of this struct) - by the driver. Note that the actual image data starts at - <structfield>data_offset</structfield> which may not be 0.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>length</structfield></entry> - <entry></entry> - <entry>Size in bytes of the plane (not its payload). This is set by the driver - based on the calls to &VIDIOC-REQBUFS; and/or &VIDIOC-CREATE-BUFS;.</entry> - </row> - <row> - <entry>union</entry> - <entry><structfield>m</structfield></entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry></entry> - <entry>__u32</entry> - <entry><structfield>mem_offset</structfield></entry> - <entry>When the memory type in the containing &v4l2-buffer; is - <constant>V4L2_MEMORY_MMAP</constant>, this is the value that - should be passed to &func-mmap;, similar to the - <structfield>offset</structfield> field in &v4l2-buffer;.</entry> - </row> - <row> - <entry></entry> - <entry>unsigned long</entry> - <entry><structfield>userptr</structfield></entry> - <entry>When the memory type in the containing &v4l2-buffer; is - <constant>V4L2_MEMORY_USERPTR</constant>, this is a userspace - pointer to the memory allocated for this plane by an application. - </entry> - </row> - <row> - <entry></entry> - <entry>int</entry> - <entry><structfield>fd</structfield></entry> - <entry>When the memory type in the containing &v4l2-buffer; is - <constant>V4L2_MEMORY_DMABUF</constant>, this is a file - descriptor associated with a DMABUF buffer, similar to the - <structfield>fd</structfield> field in &v4l2-buffer;.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>data_offset</structfield></entry> - <entry></entry> - <entry>Offset in bytes to video data in the plane. - Drivers must set this field when <structfield>type</structfield> - refers to a capture stream, applications when it refers to an output stream. - Note that data_offset is included in <structfield>bytesused</structfield>. - So the size of the image in the plane is - <structfield>bytesused</structfield>-<structfield>data_offset</structfield> at - offset <structfield>data_offset</structfield> from the start of the plane. - </entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved[11]</structfield></entry> - <entry></entry> - <entry>Reserved for future use. Should be zeroed by drivers and - applications.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="v4l2-buf-type"> - <title>enum v4l2_buf_type</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry> - <entry>1</entry> - <entry>Buffer of a single-planar video capture stream, see <xref - linkend="capture" />.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant> - </entry> - <entry>9</entry> - <entry>Buffer of a multi-planar video capture stream, see <xref - linkend="capture" />.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry> - <entry>2</entry> - <entry>Buffer of a single-planar video output stream, see <xref - linkend="output" />.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant> - </entry> - <entry>10</entry> - <entry>Buffer of a multi-planar video output stream, see <xref - linkend="output" />.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry> - <entry>3</entry> - <entry>Buffer for video overlay, see <xref linkend="overlay" />.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry> - <entry>4</entry> - <entry>Buffer of a raw VBI capture stream, see <xref - linkend="raw-vbi" />.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry> - <entry>5</entry> - <entry>Buffer of a raw VBI output stream, see <xref - linkend="raw-vbi" />.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry> - <entry>6</entry> - <entry>Buffer of a sliced VBI capture stream, see <xref - linkend="sliced" />.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry> - <entry>7</entry> - <entry>Buffer of a sliced VBI output stream, see <xref - linkend="sliced" />.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant></entry> - <entry>8</entry> - <entry>Buffer for video output overlay (OSD), see <xref - linkend="osd" />.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_SDR_CAPTURE</constant></entry> - <entry>11</entry> - <entry>Buffer for Software Defined Radio (SDR) capture stream, see - <xref linkend="sdr" />.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_SDR_OUTPUT</constant></entry> - <entry>12</entry> - <entry>Buffer for Software Defined Radio (SDR) output stream, see - <xref linkend="sdr" />.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="buffer-flags"> - <title>Buffer Flags</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_BUF_FLAG_MAPPED</constant></entry> - <entry>0x00000001</entry> - <entry>The buffer resides in device memory and has been mapped -into the application's address space, see <xref linkend="mmap" /> for details. -Drivers set or clear this flag when the -<link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link - linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link - linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Set by the driver.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_QUEUED</constant></entry> - <entry>0x00000002</entry> - <entry>Internally drivers maintain two buffer queues, an -incoming and outgoing queue. When this flag is set, the buffer is -currently on the incoming queue. It automatically moves to the -outgoing queue after the buffer has been filled (capture devices) or -displayed (output devices). Drivers set or clear this flag when the -<constant>VIDIOC_QUERYBUF</constant> ioctl is called. After -(successful) calling the <constant>VIDIOC_QBUF </constant>ioctl it is -always set and after <constant>VIDIOC_DQBUF</constant> always -cleared.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_DONE</constant></entry> - <entry>0x00000004</entry> - <entry>When this flag is set, the buffer is currently on -the outgoing queue, ready to be dequeued from the driver. Drivers set -or clear this flag when the <constant>VIDIOC_QUERYBUF</constant> ioctl -is called. After calling the <constant>VIDIOC_QBUF</constant> or -<constant>VIDIOC_DQBUF</constant> it is always cleared. Of course a -buffer cannot be on both queues at the same time, the -<constant>V4L2_BUF_FLAG_QUEUED</constant> and -<constant>V4L2_BUF_FLAG_DONE</constant> flag are mutually exclusive. -They can be both cleared however, then the buffer is in "dequeued" -state, in the application domain so to say.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_ERROR</constant></entry> - <entry>0x00000040</entry> - <entry>When this flag is set, the buffer has been dequeued - successfully, although the data might have been corrupted. - This is recoverable, streaming may continue as normal and - the buffer may be reused normally. - Drivers set this flag when the <constant>VIDIOC_DQBUF</constant> - ioctl is called.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_KEYFRAME</constant></entry> - <entry>0x00000008</entry> - <entry>Drivers set or clear this flag when calling the -<constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video -capture devices when the buffer contains a compressed image which is a -key frame (or field), &ie; can be decompressed on its own. Also known as -an I-frame. Applications can set this bit when <structfield>type</structfield> -refers to an output stream.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_PFRAME</constant></entry> - <entry>0x00000010</entry> - <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant> -this flags predicted frames or fields which contain only differences to a -previous key frame. Applications can set this bit when <structfield>type</structfield> -refers to an output stream.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_BFRAME</constant></entry> - <entry>0x00000020</entry> - <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant> -this flags a bi-directional predicted frame or field which contains only -the differences between the current frame and both the preceding and following -key frames to specify its content. Applications can set this bit when -<structfield>type</structfield> refers to an output stream.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_TIMECODE</constant></entry> - <entry>0x00000100</entry> - <entry>The <structfield>timecode</structfield> field is valid. -Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant> -ioctl is called. Applications can set this bit and the corresponding -<structfield>timecode</structfield> structure when <structfield>type</structfield> -refers to an output stream.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_PREPARED</constant></entry> - <entry>0x00000400</entry> - <entry>The buffer has been prepared for I/O and can be queued by the -application. Drivers set or clear this flag when the -<link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link - linkend="vidioc-qbuf">VIDIOC_PREPARE_BUF</link>, <link - linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link - linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant></entry> - <entry>0x00000800</entry> - <entry>Caches do not have to be invalidated for this buffer. -Typically applications shall use this flag if the data captured in the buffer -is not going to be touched by the CPU, instead the buffer will, probably, be -passed on to a DMA-capable hardware unit for further processing or output. -</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant></entry> - <entry>0x00001000</entry> - <entry>Caches do not have to be cleaned for this buffer. -Typically applications shall use this flag for output buffers if the data -in this buffer has not been created by the CPU but by some DMA-capable unit, -in which case caches have not been used.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_LAST</constant></entry> - <entry>0x00100000</entry> - <entry>Last buffer produced by the hardware. mem2mem codec drivers -set this flag on the capture queue for the last buffer when the -<link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link> or -<link linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Due to hardware -limitations, the last buffer may be empty. In this case the driver will set the -<structfield>bytesused</structfield> field to 0, regardless of the format. Any -Any subsequent call to the <link linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl -will not block anymore, but return an &EPIPE;.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MASK</constant></entry> - <entry>0x0000e000</entry> - <entry>Mask for timestamp types below. To test the - timestamp type, mask out bits not belonging to timestamp - type by performing a logical and operation with buffer - flags and timestamp mask.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN</constant></entry> - <entry>0x00000000</entry> - <entry>Unknown timestamp type. This type is used by - drivers before Linux 3.9 and may be either monotonic (see - below) or realtime (wall clock). Monotonic clock has been - favoured in embedded systems whereas most of the drivers - use the realtime clock. Either kinds of timestamps are - available in user space via - <function>clock_gettime(2)</function> using clock IDs - <constant>CLOCK_MONOTONIC</constant> and - <constant>CLOCK_REALTIME</constant>, respectively.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC</constant></entry> - <entry>0x00002000</entry> - <entry>The buffer timestamp has been taken from the - <constant>CLOCK_MONOTONIC</constant> clock. To access the - same clock outside V4L2, use - <function>clock_gettime(2)</function>.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant></entry> - <entry>0x00004000</entry> - <entry>The CAPTURE buffer timestamp has been taken from the - corresponding OUTPUT buffer. This flag applies only to mem2mem devices.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant></entry> - <entry>0x00070000</entry> - <entry>Mask for timestamp sources below. The timestamp source - defines the point of time the timestamp is taken in relation to - the frame. Logical 'and' operation between the - <structfield>flags</structfield> field and - <constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant> produces the - value of the timestamp source. Applications must set the timestamp - source when <structfield>type</structfield> refers to an output stream - and <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> is set.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_EOF</constant></entry> - <entry>0x00000000</entry> - <entry>End Of Frame. The buffer timestamp has been taken - when the last pixel of the frame has been received or the - last pixel of the frame has been transmitted. In practice, - software generated timestamps will typically be read from - the clock a small amount of time after the last pixel has - been received or transmitten, depending on the system and - other activity in it.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_SOE</constant></entry> - <entry>0x00010000</entry> - <entry>Start Of Exposure. The buffer timestamp has been - taken when the exposure of the frame has begun. This is - only valid for the - <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> buffer - type.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="v4l2-memory"> - <title>enum v4l2_memory</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_MEMORY_MMAP</constant></entry> - <entry>1</entry> - <entry>The buffer is used for <link linkend="mmap">memory -mapping</link> I/O.</entry> - </row> - <row> - <entry><constant>V4L2_MEMORY_USERPTR</constant></entry> - <entry>2</entry> - <entry>The buffer is used for <link linkend="userp">user -pointer</link> I/O.</entry> - </row> - <row> - <entry><constant>V4L2_MEMORY_OVERLAY</constant></entry> - <entry>3</entry> - <entry>[to do]</entry> - </row> - <row> - <entry><constant>V4L2_MEMORY_DMABUF</constant></entry> - <entry>4</entry> - <entry>The buffer is used for <link linkend="dmabuf">DMA shared -buffer</link> I/O.</entry> - </row> - </tbody> - </tgroup> - </table> - - <section> - <title>Timecodes</title> - - <para>The <structname>v4l2_timecode</structname> structure is -designed to hold a <xref linkend="smpte12m" /> or similar timecode. -(struct <structname>timeval</structname> timestamps are stored in -&v4l2-buffer; field <structfield>timestamp</structfield>.)</para> - - <table frame="none" pgwide="1" id="v4l2-timecode"> - <title>struct <structname>v4l2_timecode</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry>Frame rate the timecodes are based on, see <xref - linkend="timecode-type" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry>Timecode flags, see <xref linkend="timecode-flags" />.</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>frames</structfield></entry> - <entry>Frame count, 0 ... 23/24/29/49/59, depending on the - type of timecode.</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>seconds</structfield></entry> - <entry>Seconds count, 0 ... 59. This is a binary, not BCD number.</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>minutes</structfield></entry> - <entry>Minutes count, 0 ... 59. This is a binary, not BCD number.</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>hours</structfield></entry> - <entry>Hours count, 0 ... 29. This is a binary, not BCD number.</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>userbits</structfield>[4]</entry> - <entry>The "user group" bits from the timecode.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="timecode-type"> - <title>Timecode Types</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_TC_TYPE_24FPS</constant></entry> - <entry>1</entry> - <entry>24 frames per second, i. e. film.</entry> - </row> - <row> - <entry><constant>V4L2_TC_TYPE_25FPS</constant></entry> - <entry>2</entry> - <entry>25 frames per second, &ie; PAL or SECAM video.</entry> - </row> - <row> - <entry><constant>V4L2_TC_TYPE_30FPS</constant></entry> - <entry>3</entry> - <entry>30 frames per second, &ie; NTSC video.</entry> - </row> - <row> - <entry><constant>V4L2_TC_TYPE_50FPS</constant></entry> - <entry>4</entry> - <entry></entry> - </row> - <row> - <entry><constant>V4L2_TC_TYPE_60FPS</constant></entry> - <entry>5</entry> - <entry></entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="timecode-flags"> - <title>Timecode Flags</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_TC_FLAG_DROPFRAME</constant></entry> - <entry>0x0001</entry> - <entry>Indicates "drop frame" semantics for counting frames -in 29.97 fps material. When set, frame numbers 0 and 1 at the start of -each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the -count.</entry> - </row> - <row> - <entry><constant>V4L2_TC_FLAG_COLORFRAME</constant></entry> - <entry>0x0002</entry> - <entry>The "color frame" flag.</entry> - </row> - <row> - <entry><constant>V4L2_TC_USERBITS_field</constant></entry> - <entry>0x000C</entry> - <entry>Field mask for the "binary group flags".</entry> - </row> - <row> - <entry><constant>V4L2_TC_USERBITS_USERDEFINED</constant></entry> - <entry>0x0000</entry> - <entry>Unspecified format.</entry> - </row> - <row> - <entry><constant>V4L2_TC_USERBITS_8BITCHARS</constant></entry> - <entry>0x0008</entry> - <entry>8-bit ISO characters.</entry> - </row> - </tbody> - </tgroup> - </table> - </section> - </section> - - <section id="field-order"> - <title>Field Order</title> - - <para>We have to distinguish between progressive and interlaced -video. Progressive video transmits all lines of a video image -sequentially. Interlaced video divides an image into two fields, -containing only the odd and even lines of the image, respectively. -Alternating the so called odd and even field are transmitted, and due -to a small delay between fields a cathode ray TV displays the lines -interleaved, yielding the original frame. This curious technique was -invented because at refresh rates similar to film the image would -fade out too quickly. Transmitting fields reduces the flicker without -the necessity of doubling the frame rate and with it the bandwidth -required for each channel.</para> - - <para>It is important to understand a video camera does not expose -one frame at a time, merely transmitting the frames separated into -fields. The fields are in fact captured at two different instances in -time. An object on screen may well move between one field and the -next. For applications analysing motion it is of paramount importance -to recognize which field of a frame is older, the <emphasis>temporal -order</emphasis>.</para> - - <para>When the driver provides or accepts images field by field -rather than interleaved, it is also important applications understand -how the fields combine to frames. We distinguish between top (aka odd) and -bottom (aka even) fields, the <emphasis>spatial order</emphasis>: The first line -of the top field is the first line of an interlaced frame, the first -line of the bottom field is the second line of that frame.</para> - - <para>However because fields were captured one after the other, -arguing whether a frame commences with the top or bottom field is -pointless. Any two successive top and bottom, or bottom and top fields -yield a valid frame. Only when the source was progressive to begin -with, ⪚ when transferring film to video, two fields may come from -the same frame, creating a natural order.</para> - - <para>Counter to intuition the top field is not necessarily the -older field. Whether the older field contains the top or bottom lines -is a convention determined by the video standard. Hence the -distinction between temporal and spatial order of fields. The diagrams -below should make this clearer.</para> - - <para>All video capture and output devices must report the current -field order. Some drivers may permit the selection of a different -order, to this end applications initialize the -<structfield>field</structfield> field of &v4l2-pix-format; before -calling the &VIDIOC-S-FMT; ioctl. If this is not desired it should -have the value <constant>V4L2_FIELD_ANY</constant> (0).</para> - - <table frame="none" pgwide="1" id="v4l2-field"> - <title>enum v4l2_field</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_FIELD_ANY</constant></entry> - <entry>0</entry> - <entry>Applications request this field order when any -one of the <constant>V4L2_FIELD_NONE</constant>, -<constant>V4L2_FIELD_TOP</constant>, -<constant>V4L2_FIELD_BOTTOM</constant>, or -<constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable. -Drivers choose depending on hardware capabilities or e. g. the -requested image size, and return the actual field order. Drivers must -never return <constant>V4L2_FIELD_ANY</constant>. If multiple -field orders are possible the driver must choose one of the possible -field orders during &VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;. &v4l2-buffer; -<structfield>field</structfield> can never be -<constant>V4L2_FIELD_ANY</constant>.</entry> - </row> - <row> - <entry><constant>V4L2_FIELD_NONE</constant></entry> - <entry>1</entry> - <entry>Images are in progressive format, not interlaced. -The driver may also indicate this order when it cannot distinguish -between <constant>V4L2_FIELD_TOP</constant> and -<constant>V4L2_FIELD_BOTTOM</constant>.</entry> - </row> - <row> - <entry><constant>V4L2_FIELD_TOP</constant></entry> - <entry>2</entry> - <entry>Images consist of the top (aka odd) field only.</entry> - </row> - <row> - <entry><constant>V4L2_FIELD_BOTTOM</constant></entry> - <entry>3</entry> - <entry>Images consist of the bottom (aka even) field only. -Applications may wish to prevent a device from capturing interlaced -images because they will have "comb" or "feathering" artefacts around -moving objects.</entry> - </row> - <row> - <entry><constant>V4L2_FIELD_INTERLACED</constant></entry> - <entry>4</entry> - <entry>Images contain both fields, interleaved line by -line. The temporal order of the fields (whether the top or bottom -field is first transmitted) depends on the current video standard. -M/NTSC transmits the bottom field first, all other standards the top -field first.</entry> - </row> - <row> - <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry> - <entry>5</entry> - <entry>Images contain both fields, the top field lines -are stored first in memory, immediately followed by the bottom field -lines. Fields are always stored in temporal order, the older one first -in memory. Image sizes refer to the frame, not fields.</entry> - </row> - <row> - <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry> - <entry>6</entry> - <entry>Images contain both fields, the bottom field -lines are stored first in memory, immediately followed by the top -field lines. Fields are always stored in temporal order, the older one -first in memory. Image sizes refer to the frame, not fields.</entry> - </row> - <row> - <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry> - <entry>7</entry> - <entry>The two fields of a frame are passed in separate -buffers, in temporal order, &ie; the older one first. To indicate the field -parity (whether the current field is a top or bottom field) the driver -or application, depending on data direction, must set &v4l2-buffer; -<structfield>field</structfield> to -<constant>V4L2_FIELD_TOP</constant> or -<constant>V4L2_FIELD_BOTTOM</constant>. Any two successive fields pair -to build a frame. If fields are successive, without any dropped fields -between them (fields can drop individually), can be determined from -the &v4l2-buffer; <structfield>sequence</structfield> field. This format -cannot be selected when using the read/write I/O method since there -is no way to communicate if a field was a top or bottom field.</entry> - </row> - <row> - <entry><constant>V4L2_FIELD_INTERLACED_TB</constant></entry> - <entry>8</entry> - <entry>Images contain both fields, interleaved line by -line, top field first. The top field is transmitted first.</entry> - </row> - <row> - <entry><constant>V4L2_FIELD_INTERLACED_BT</constant></entry> - <entry>9</entry> - <entry>Images contain both fields, interleaved line by -line, top field first. The bottom field is transmitted first.</entry> - </row> - </tbody> - </tgroup> - </table> - - <figure id="fieldseq-tb"> - <title>Field Order, Top Field First Transmitted</title> - <mediaobject> - <imageobject> - <imagedata fileref="fieldseq_tb.pdf" format="PS" /> - </imageobject> - <imageobject> - <imagedata fileref="fieldseq_tb.gif" format="GIF" /> - </imageobject> - </mediaobject> - </figure> - - <figure id="fieldseq-bt"> - <title>Field Order, Bottom Field First Transmitted</title> - <mediaobject> - <imageobject> - <imagedata fileref="fieldseq_bt.pdf" format="PS" /> - </imageobject> - <imageobject> - <imagedata fileref="fieldseq_bt.gif" format="GIF" /> - </imageobject> - </mediaobject> - </figure> - </section> diff --git a/Documentation/DocBook/media/v4l/keytable.c.xml b/Documentation/DocBook/media/v4l/keytable.c.xml deleted file mode 100644 index d53254a3be15..000000000000 --- a/Documentation/DocBook/media/v4l/keytable.c.xml +++ /dev/null @@ -1,172 +0,0 @@ -<programlisting> -/* keytable.c - This program allows checking/replacing keys at IR - - Copyright (C) 2006-2009 Mauro Carvalho Chehab <mchehab@infradead.org> - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation, version 2 of the License. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - */ - -#include <ctype.h> -#include <errno.h> -#include <fcntl.h> -#include <stdio.h> -#include <stdlib.h> -#include <string.h> -#include <linux/input.h> -#include <sys/ioctl.h> - -#include "parse.h" - -void prtcode (int *codes) -{ - struct parse_key *p; - - for (p=keynames;p->name!=NULL;p++) { - if (p->value == (unsigned)codes[1]) { - printf("scancode 0x%04x = %s (0x%02x)\n", codes[0], p->name, codes[1]); - return; - } - } - - if (isprint (codes[1])) - printf("scancode %d = '%c' (0x%02x)\n", codes[0], codes[1], codes[1]); - else - printf("scancode %d = 0x%02x\n", codes[0], codes[1]); -} - -int parse_code(char *string) -{ - struct parse_key *p; - - for (p=keynames;p->name!=NULL;p++) { - if (!strcasecmp(p->name, string)) { - return p->value; - } - } - return -1; -} - -int main (int argc, char *argv[]) -{ - int fd; - unsigned int i, j; - int codes[2]; - - if (argc<2 || argc>4) { - printf ("usage: %s <device> to get table; or\n" - " %s <device> <scancode> <keycode>\n" - " %s <device> <keycode_file>\n",*argv,*argv,*argv); - return -1; - } - - if ((fd = open(argv[1], O_RDONLY)) < 0) { - perror("Couldn't open input device"); - return(-1); - } - - if (argc==4) { - int value; - - value=parse_code(argv[3]); - - if (value==-1) { - value = strtol(argv[3], NULL, 0); - if (errno) - perror("value"); - } - - codes [0] = (unsigned) strtol(argv[2], NULL, 0); - codes [1] = (unsigned) value; - - if(ioctl(fd, EVIOCSKEYCODE, codes)) - perror ("EVIOCSKEYCODE"); - - if(ioctl(fd, EVIOCGKEYCODE, codes)==0) - prtcode(codes); - return 0; - } - - if (argc==3) { - FILE *fin; - int value; - char *scancode, *keycode, s[2048]; - - fin=fopen(argv[2],"r"); - if (fin==NULL) { - perror ("opening keycode file"); - return -1; - } - - /* Clears old table */ - for (j = 0; j < 256; j++) { - for (i = 0; i < 256; i++) { - codes[0] = (j << 8) | i; - codes[1] = KEY_RESERVED; - ioctl(fd, EVIOCSKEYCODE, codes); - } - } - - while (fgets(s,sizeof(s),fin)) { - scancode=strtok(s,"\n\t =:"); - if (!scancode) { - perror ("parsing input file scancode"); - return -1; - } - if (!strcasecmp(scancode, "scancode")) { - scancode = strtok(NULL,"\n\t =:"); - if (!scancode) { - perror ("parsing input file scancode"); - return -1; - } - } - - keycode=strtok(NULL,"\n\t =:("); - if (!keycode) { - perror ("parsing input file keycode"); - return -1; - } - - // printf ("parsing %s=%s:", scancode, keycode); - value=parse_code(keycode); - // printf ("\tvalue=%d\n",value); - - if (value==-1) { - value = strtol(keycode, NULL, 0); - if (errno) - perror("value"); - } - - codes [0] = (unsigned) strtol(scancode, NULL, 0); - codes [1] = (unsigned) value; - - // printf("\t%04x=%04x\n",codes[0], codes[1]); - if(ioctl(fd, EVIOCSKEYCODE, codes)) { - fprintf(stderr, "Setting scancode 0x%04x with 0x%04x via ",codes[0], codes[1]); - perror ("EVIOCSKEYCODE"); - } - - if(ioctl(fd, EVIOCGKEYCODE, codes)==0) - prtcode(codes); - } - return 0; - } - - /* Get scancode table */ - for (j = 0; j < 256; j++) { - for (i = 0; i < 256; i++) { - codes[0] = (j << 8) | i; - if (!ioctl(fd, EVIOCGKEYCODE, codes) && codes[1] != KEY_RESERVED) - prtcode(codes); - } - } - return 0; -} - -</programlisting> diff --git a/Documentation/DocBook/media/v4l/libv4l.xml b/Documentation/DocBook/media/v4l/libv4l.xml deleted file mode 100644 index d3b71e20003c..000000000000 --- a/Documentation/DocBook/media/v4l/libv4l.xml +++ /dev/null @@ -1,160 +0,0 @@ -<title>Libv4l Userspace Library</title> -<section id="libv4l-introduction"> - <title>Introduction</title> - - <para>libv4l is a collection of libraries which adds a thin abstraction -layer on top of video4linux2 devices. The purpose of this (thin) layer -is to make it easy for application writers to support a wide variety of -devices without having to write separate code for different devices in the -same class.</para> -<para>An example of using libv4l is provided by -<link linkend='v4l2grab-example'>v4l2grab</link>. -</para> - - <para>libv4l consists of 3 different libraries:</para> - <section> - <title>libv4lconvert</title> - - <para>libv4lconvert is a library that converts several -different pixelformats found in V4L2 drivers into a few common RGB and -YUY formats.</para> - <para>It currently accepts the following V4L2 driver formats: -<link linkend="V4L2-PIX-FMT-BGR24"><constant>V4L2_PIX_FMT_BGR24</constant></link>, -<link linkend="V4L2-PIX-FMT-HM12"><constant>V4L2_PIX_FMT_HM12</constant></link>, -<link linkend="V4L2-PIX-FMT-JPEG"><constant>V4L2_PIX_FMT_JPEG</constant></link>, -<link linkend="V4L2-PIX-FMT-MJPEG"><constant>V4L2_PIX_FMT_MJPEG</constant></link>, -<link linkend="V4L2-PIX-FMT-MR97310A"><constant>V4L2_PIX_FMT_MR97310A</constant></link>, -<link linkend="V4L2-PIX-FMT-OV511"><constant>V4L2_PIX_FMT_OV511</constant></link>, -<link linkend="V4L2-PIX-FMT-OV518"><constant>V4L2_PIX_FMT_OV518</constant></link>, -<link linkend="V4L2-PIX-FMT-PAC207"><constant>V4L2_PIX_FMT_PAC207</constant></link>, -<link linkend="V4L2-PIX-FMT-PJPG"><constant>V4L2_PIX_FMT_PJPG</constant></link>, -<link linkend="V4L2-PIX-FMT-RGB24"><constant>V4L2_PIX_FMT_RGB24</constant></link>, -<link linkend="V4L2-PIX-FMT-SBGGR8"><constant>V4L2_PIX_FMT_SBGGR8</constant></link>, -<link linkend="V4L2-PIX-FMT-SGBRG8"><constant>V4L2_PIX_FMT_SGBRG8</constant></link>, -<link linkend="V4L2-PIX-FMT-SGRBG8"><constant>V4L2_PIX_FMT_SGRBG8</constant></link>, -<link linkend="V4L2-PIX-FMT-SN9C10X"><constant>V4L2_PIX_FMT_SN9C10X</constant></link>, -<link linkend="V4L2-PIX-FMT-SN9C20X-I420"><constant>V4L2_PIX_FMT_SN9C20X_I420</constant></link>, -<link linkend="V4L2-PIX-FMT-SPCA501"><constant>V4L2_PIX_FMT_SPCA501</constant></link>, -<link linkend="V4L2-PIX-FMT-SPCA505"><constant>V4L2_PIX_FMT_SPCA505</constant></link>, -<link linkend="V4L2-PIX-FMT-SPCA508"><constant>V4L2_PIX_FMT_SPCA508</constant></link>, -<link linkend="V4L2-PIX-FMT-SPCA561"><constant>V4L2_PIX_FMT_SPCA561</constant></link>, -<link linkend="V4L2-PIX-FMT-SQ905C"><constant>V4L2_PIX_FMT_SQ905C</constant></link>, -<constant>V4L2_PIX_FMT_SRGGB8</constant>, -<link linkend="V4L2-PIX-FMT-UYVY"><constant>V4L2_PIX_FMT_UYVY</constant></link>, -<link linkend="V4L2-PIX-FMT-YUV420"><constant>V4L2_PIX_FMT_YUV420</constant></link>, -<link linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link>, -<link linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link>, -and <link linkend="V4L2-PIX-FMT-YVYU"><constant>V4L2_PIX_FMT_YVYU</constant></link>. -</para> - <para>Later on libv4lconvert was expanded to also be able to do -various video processing functions to improve webcam video quality. -The video processing is split in to 2 parts: libv4lconvert/control and -libv4lconvert/processing.</para> - - <para>The control part is used to offer video controls which can -be used to control the video processing functions made available by - libv4lconvert/processing. These controls are stored application wide -(until reboot) by using a persistent shared memory object.</para> - - <para>libv4lconvert/processing offers the actual video -processing functionality.</para> - </section> - <section> - <title>libv4l1</title> - <para>This library offers functions that can be used to quickly -make v4l1 applications work with v4l2 devices. These functions work exactly -like the normal open/close/etc, except that libv4l1 does full emulation of -the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it -will just pass calls through.</para> - <para>Since those functions are emulations of the old V4L1 API, -it shouldn't be used for new applications.</para> - </section> - <section> - <title>libv4l2</title> - <para>This library should be used for all modern V4L2 -applications.</para> - <para>It provides handles to call V4L2 open/ioctl/close/poll -methods. Instead of just providing the raw output of the device, it enhances -the calls in the sense that it will use libv4lconvert to provide more video -formats and to enhance the image quality.</para> - <para>In most cases, libv4l2 just passes the calls directly -through to the v4l2 driver, intercepting the calls to -<link linkend='vidioc-g-fmt'><constant>VIDIOC_TRY_FMT</constant></link>, -<link linkend='vidioc-g-fmt'><constant>VIDIOC_G_FMT</constant></link> -<link linkend='vidioc-g-fmt'><constant>VIDIOC_S_FMT</constant></link> -<link linkend='vidioc-enum-framesizes'><constant>VIDIOC_ENUM_FRAMESIZES</constant></link> -and <link linkend='vidioc-enum-frameintervals'><constant>VIDIOC_ENUM_FRAMEINTERVALS</constant></link> -in order to emulate the formats -<link linkend="V4L2-PIX-FMT-BGR24"><constant>V4L2_PIX_FMT_BGR24</constant></link>, -<link linkend="V4L2-PIX-FMT-RGB24"><constant>V4L2_PIX_FMT_RGB24</constant></link>, -<link linkend="V4L2-PIX-FMT-YUV420"><constant>V4L2_PIX_FMT_YUV420</constant></link>, -and <link linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link>, -if they aren't available in the driver. -<link linkend='vidioc-enum-fmt'><constant>VIDIOC_ENUM_FMT</constant></link> -keeps enumerating the hardware supported formats, plus the emulated formats -offered by libv4l at the end. -</para> - <section id="libv4l-ops"> - <title>Libv4l device control functions</title> - <para>The common file operation methods are provided by -libv4l.</para> - <para>Those functions operate just like glibc -open/close/dup/ioctl/read/mmap/munmap:</para> -<itemizedlist><listitem> - <para>int v4l2_open(const char *file, int oflag, -...) - -operates like the standard <link linkend='func-open'>open()</link> function. -</para></listitem><listitem> - <para>int v4l2_close(int fd) - -operates like the standard <link linkend='func-close'>close()</link> function. -</para></listitem><listitem> - <para>int v4l2_dup(int fd) - -operates like the standard dup() function, duplicating a file handler. -</para></listitem><listitem> - <para>int v4l2_ioctl (int fd, unsigned long int request, ...) - -operates like the standard <link linkend='func-ioctl'>ioctl()</link> function. -</para></listitem><listitem> - <para>int v4l2_read (int fd, void* buffer, size_t n) - -operates like the standard <link linkend='func-read'>read()</link> function. -</para></listitem><listitem> - <para>void v4l2_mmap(void *start, size_t length, int prot, int flags, int fd, int64_t offset); - -operates like the standard <link linkend='func-mmap'>mmap()</link> function. -</para></listitem><listitem> - <para>int v4l2_munmap(void *_start, size_t length); - -operates like the standard <link linkend='func-munmap'>munmap()</link> function. -</para></listitem> -</itemizedlist> - <para>Those functions provide additional control:</para> -<itemizedlist><listitem> - <para>int v4l2_fd_open(int fd, int v4l2_flags) - -opens an already opened fd for further use through v4l2lib and possibly -modify libv4l2's default behavior through the v4l2_flags argument. -Currently, v4l2_flags can be <constant>V4L2_DISABLE_CONVERSION</constant>, -to disable format conversion. -</para></listitem><listitem> - <para>int v4l2_set_control(int fd, int cid, int value) - -This function takes a value of 0 - 65535, and then scales that range to -the actual range of the given v4l control id, and then if the cid exists -and is not locked sets the cid to the scaled value. -</para></listitem><listitem> - <para>int v4l2_get_control(int fd, int cid) - -This function returns a value of 0 - 65535, scaled to from the actual range -of the given v4l control id. when the cid does not exist, could not be -accessed for some reason, or some error occurred 0 is returned. -</para></listitem> -</itemizedlist> - </section> - </section> - <section> - - <title>v4l1compat.so wrapper library</title> - - <para>This library intercepts calls to -open/close/ioctl/mmap/mmunmap operations and redirects them to the libv4l -counterparts, by using LD_PRELOAD=/usr/lib/v4l1compat.so. It also -emulates V4L1 calls via V4L2 API.</para> - <para>It allows usage of binary legacy applications that -still don't use libv4l.</para> - </section> - -</section> diff --git a/Documentation/DocBook/media/v4l/lirc_device_interface.xml b/Documentation/DocBook/media/v4l/lirc_device_interface.xml deleted file mode 100644 index 34cada2ca710..000000000000 --- a/Documentation/DocBook/media/v4l/lirc_device_interface.xml +++ /dev/null @@ -1,255 +0,0 @@ -<section id="lirc_dev"> -<title>LIRC Device Interface</title> - - -<section id="lirc_dev_intro"> -<title>Introduction</title> - -<para>The LIRC device interface is a bi-directional interface for -transporting raw IR data between userspace and kernelspace. Fundamentally, -it is just a chardev (/dev/lircX, for X = 0, 1, 2, ...), with a number -of standard struct file_operations defined on it. With respect to -transporting raw IR data to and fro, the essential fops are read, write -and ioctl.</para> - -<para>Example dmesg output upon a driver registering w/LIRC:</para> - <blockquote> - <para>$ dmesg |grep lirc_dev</para> - <para>lirc_dev: IR Remote Control driver registered, major 248</para> - <para>rc rc0: lirc_dev: driver ir-lirc-codec (mceusb) registered at minor = 0</para> - </blockquote> - -<para>What you should see for a chardev:</para> - <blockquote> - <para>$ ls -l /dev/lirc*</para> - <para>crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0</para> - </blockquote> -</section> - -<section id="lirc_read"> -<title>LIRC read fop</title> - -<para>The lircd userspace daemon reads raw IR data from the LIRC chardev. The -exact format of the data depends on what modes a driver supports, and what -mode has been selected. lircd obtains supported modes and sets the active mode -via the ioctl interface, detailed at <xref linkend="lirc_ioctl"/>. The generally -preferred mode is LIRC_MODE_MODE2, in which packets containing an int value -describing an IR signal are read from the chardev.</para> - -<para>See also <ulink url="http://www.lirc.org/html/technical.html">http://www.lirc.org/html/technical.html</ulink> for more info.</para> -</section> - -<section id="lirc_write"> -<title>LIRC write fop</title> - -<para>The data written to the chardev is a pulse/space sequence of integer -values. Pulses and spaces are only marked implicitly by their position. The -data must start and end with a pulse, therefore, the data must always include -an uneven number of samples. The write function must block until the data has -been transmitted by the hardware. If more data is provided than the hardware -can send, the driver returns EINVAL.</para> - -</section> - -<section id="lirc_ioctl"> -<title>LIRC ioctl fop</title> - -<para>The LIRC device's ioctl definition is bound by the ioctl function -definition of struct file_operations, leaving us with an unsigned int -for the ioctl command and an unsigned long for the arg. For the purposes -of ioctl portability across 32-bit and 64-bit, these values are capped -to their 32-bit sizes.</para> - -<para>The following ioctls can be used to change specific hardware settings. -In general each driver should have a default set of settings. The driver -implementation is expected to re-apply the default settings when the device -is closed by user-space, so that every application opening the device can rely -on working with the default settings initially.</para> - -<variablelist> - <varlistentry> - <term>LIRC_GET_FEATURES</term> - <listitem> - <para>Obviously, get the underlying hardware device's features. If a driver - does not announce support of certain features, calling of the corresponding - ioctls is undefined.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>LIRC_GET_SEND_MODE</term> - <listitem> - <para>Get supported transmit mode. Only LIRC_MODE_PULSE is supported by lircd.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>LIRC_GET_REC_MODE</term> - <listitem> - <para>Get supported receive modes. Only LIRC_MODE_MODE2 and LIRC_MODE_LIRCCODE - are supported by lircd.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>LIRC_GET_SEND_CARRIER</term> - <listitem> - <para>Get carrier frequency (in Hz) currently used for transmit.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>LIRC_GET_REC_CARRIER</term> - <listitem> - <para>Get carrier frequency (in Hz) currently used for IR reception.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>LIRC_{G,S}ET_{SEND,REC}_DUTY_CYCLE</term> - <listitem> - <para>Get/set the duty cycle (from 0 to 100) of the carrier signal. Currently, - no special meaning is defined for 0 or 100, but this could be used to switch - off carrier generation in the future, so these values should be reserved.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>LIRC_GET_REC_RESOLUTION</term> - <listitem> - <para>Some receiver have maximum resolution which is defined by internal - sample rate or data format limitations. E.g. it's common that signals can - only be reported in 50 microsecond steps. This integer value is used by - lircd to automatically adjust the aeps tolerance value in the lircd - config file.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>LIRC_GET_M{IN,AX}_TIMEOUT</term> - <listitem> - <para>Some devices have internal timers that can be used to detect when - there's no IR activity for a long time. This can help lircd in detecting - that a IR signal is finished and can speed up the decoding process. - Returns an integer value with the minimum/maximum timeout that can be - set. Some devices have a fixed timeout, in that case both ioctls will - return the same value even though the timeout cannot be changed.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>LIRC_GET_M{IN,AX}_FILTER_{PULSE,SPACE}</term> - <listitem> - <para>Some devices are able to filter out spikes in the incoming signal - using given filter rules. These ioctls return the hardware capabilities - that describe the bounds of the possible filters. Filter settings depend - on the IR protocols that are expected. lircd derives the settings from - all protocols definitions found in its config file.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>LIRC_GET_LENGTH</term> - <listitem> - <para>Retrieves the code length in bits (only for LIRC_MODE_LIRCCODE). - Reads on the device must be done in blocks matching the bit count. - The bit could should be rounded up so that it matches full bytes.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>LIRC_SET_{SEND,REC}_MODE</term> - <listitem> - <para>Set send/receive mode. Largely obsolete for send, as only - LIRC_MODE_PULSE is supported.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>LIRC_SET_{SEND,REC}_CARRIER</term> - <listitem> - <para>Set send/receive carrier (in Hz).</para> - </listitem> - </varlistentry> - <varlistentry> - <term>LIRC_SET_TRANSMITTER_MASK</term> - <listitem> - <para>This enables the given set of transmitters. The first transmitter - is encoded by the least significant bit, etc. When an invalid bit mask - is given, i.e. a bit is set, even though the device does not have so many - transitters, then this ioctl returns the number of available transitters - and does nothing otherwise.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>LIRC_SET_REC_TIMEOUT</term> - <listitem> - <para>Sets the integer value for IR inactivity timeout (cf. - LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT). A value of 0 (if - supported by the hardware) disables all hardware timeouts and data should - be reported as soon as possible. If the exact value cannot be set, then - the next possible value _greater_ than the given value should be set.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>LIRC_SET_REC_TIMEOUT_REPORTS</term> - <listitem> - <para>Enable (1) or disable (0) timeout reports in LIRC_MODE_MODE2. By - default, timeout reports should be turned off.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>LIRC_SET_REC_FILTER_{,PULSE,SPACE}</term> - <listitem> - <para>Pulses/spaces shorter than this are filtered out by hardware. If - filters cannot be set independently for pulse/space, the corresponding - ioctls must return an error and LIRC_SET_REC_FILTER shall be used instead.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>LIRC_SET_MEASURE_CARRIER_MODE</term> - <listitem> - <para>Enable (1)/disable (0) measure mode. If enabled, from the next key - press on, the driver will send LIRC_MODE2_FREQUENCY packets. By default - this should be turned off.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>LIRC_SET_REC_{DUTY_CYCLE,CARRIER}_RANGE</term> - <listitem> - <para>To set a range use LIRC_SET_REC_DUTY_CYCLE_RANGE/LIRC_SET_REC_CARRIER_RANGE - with the lower bound first and later LIRC_SET_REC_DUTY_CYCLE/LIRC_SET_REC_CARRIER - with the upper bound.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>LIRC_NOTIFY_DECODE</term> - <listitem> - <para>This ioctl is called by lircd whenever a successful decoding of an - incoming IR signal could be done. This can be used by supporting hardware - to give visual feedback to the user e.g. by flashing a LED.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>LIRC_SETUP_{START,END}</term> - <listitem> - <para>Setting of several driver parameters can be optimized by encapsulating - the according ioctl calls with LIRC_SETUP_START/LIRC_SETUP_END. When a - driver receives a LIRC_SETUP_START ioctl it can choose to not commit - further setting changes to the hardware until a LIRC_SETUP_END is received. - But this is open to the driver implementation and every driver must also - handle parameter changes which are not encapsulated by LIRC_SETUP_START - and LIRC_SETUP_END. Drivers can also choose to ignore these ioctls.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>LIRC_SET_WIDEBAND_RECEIVER</term> - <listitem> - <para>Some receivers are equipped with special wide band receiver which is intended - to be used to learn output of existing remote. - Calling that ioctl with (1) will enable it, and with (0) disable it. - This might be useful of receivers that have otherwise narrow band receiver - that prevents them to be used with some remotes. - Wide band receiver might also be more precise - On the other hand its disadvantage it usually reduced range of reception. - Note: wide band receiver might be implictly enabled if you enable - carrier reports. In that case it will be disabled as soon as you disable - carrier reports. Trying to disable wide band receiver while carrier - reports are active will do nothing.</para> - </listitem> - </varlistentry> -</variablelist> -<section id="lirc_dev_errors"> - &return-value; -</section> -</section> -</section> diff --git a/Documentation/DocBook/media/v4l/media-controller.xml b/Documentation/DocBook/media/v4l/media-controller.xml deleted file mode 100644 index 5f2fc07a93d7..000000000000 --- a/Documentation/DocBook/media/v4l/media-controller.xml +++ /dev/null @@ -1,105 +0,0 @@ -<partinfo> - <authorgroup> - <author> - <firstname>Laurent</firstname> - <surname>Pinchart</surname> - <affiliation><address><email>laurent.pinchart@ideasonboard.com</email></address></affiliation> - <contrib>Initial version.</contrib> - </author> - </authorgroup> - <copyright> - <year>2010</year> - <holder>Laurent Pinchart</holder> - </copyright> - - <revhistory> - <!-- Put document revisions here, newest first. --> - <revision> - <revnumber>1.0.0</revnumber> - <date>2010-11-10</date> - <authorinitials>lp</authorinitials> - <revremark>Initial revision</revremark> - </revision> - </revhistory> -</partinfo> - -<title>Media Controller API</title> - -<chapter id="media_controller"> - <title>Media Controller</title> - - <section id="media-controller-intro"> - <title>Introduction</title> - <para>Media devices increasingly handle multiple related functions. Many USB - cameras include microphones, video capture hardware can also output video, - or SoC camera interfaces also perform memory-to-memory operations similar to - video codecs.</para> - <para>Independent functions, even when implemented in the same hardware, can - be modelled as separate devices. A USB camera with a microphone will be - presented to userspace applications as V4L2 and ALSA capture devices. The - devices' relationships (when using a webcam, end-users shouldn't have to - manually select the associated USB microphone), while not made available - directly to applications by the drivers, can usually be retrieved from - sysfs.</para> - <para>With more and more advanced SoC devices being introduced, the current - approach will not scale. Device topologies are getting increasingly complex - and can't always be represented by a tree structure. Hardware blocks are - shared between different functions, creating dependencies between seemingly - unrelated devices.</para> - <para>Kernel abstraction APIs such as V4L2 and ALSA provide means for - applications to access hardware parameters. As newer hardware expose an - increasingly high number of those parameters, drivers need to guess what - applications really require based on limited information, thereby - implementing policies that belong to userspace.</para> - <para>The media controller API aims at solving those problems.</para> - </section> - - <section id="media-controller-model"> - <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 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> - - <!-- All non-ioctl specific data types go here. --> - &sub-media-types; -</chapter> - -<appendix id="media-user-func"> - <title>Function Reference</title> - <!-- Keep this alphabetically sorted. --> - &sub-media-func-open; - &sub-media-func-close; - &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; -</appendix> diff --git a/Documentation/DocBook/media/v4l/media-func-close.xml b/Documentation/DocBook/media/v4l/media-func-close.xml deleted file mode 100644 index be149c802aeb..000000000000 --- a/Documentation/DocBook/media/v4l/media-func-close.xml +++ /dev/null @@ -1,59 +0,0 @@ -<refentry id="media-func-close"> - <refmeta> - <refentrytitle>media close()</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>media-close</refname> - <refpurpose>Close a media device</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <unistd.h></funcsynopsisinfo> - <funcprototype> - <funcdef>int <function>close</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>Closes the media device. Resources associated with the file descriptor - are freed. The device configuration remain unchanged.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para><function>close</function> returns 0 on success. On error, -1 is - returned, and <varname>errno</varname> is set appropriately. Possible error - codes are:</para> - - <variablelist> - <varlistentry> - <term><errorcode>EBADF</errorcode></term> - <listitem> - <para><parameter>fd</parameter> is not a valid open file descriptor. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/media-func-ioctl.xml b/Documentation/DocBook/media/v4l/media-func-ioctl.xml deleted file mode 100644 index 39478d0fbcaa..000000000000 --- a/Documentation/DocBook/media/v4l/media-func-ioctl.xml +++ /dev/null @@ -1,73 +0,0 @@ -<refentry id="media-func-ioctl"> - <refmeta> - <refentrytitle>media ioctl()</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>media-ioctl</refname> - <refpurpose>Control a media device</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <sys/ioctl.h></funcsynopsisinfo> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>void *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>Media ioctl request code as defined in the media.h header file, - for example MEDIA_IOC_SETUP_LINK.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para>Pointer to a request-specific structure.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - <para>The <function>ioctl()</function> function manipulates media device - parameters. The argument <parameter>fd</parameter> must be an open file - descriptor.</para> - <para>The ioctl <parameter>request</parameter> code specifies the media - function to be called. It has encoded in it whether the argument is an - input, output or read/write parameter, and the size of the argument - <parameter>argp</parameter> in bytes.</para> - <para>Macros and structures definitions specifying media ioctl requests and - their parameters are located in the media.h header file. All media ioctl - requests, their respective function and parameters are specified in - <xref linkend="media-user-func" />.</para> - </refsect1> - - <refsect1> - &return-value; - - <para>Request-specific error codes are listed in the - individual requests descriptions.</para> - <para>When an ioctl that takes an output or read/write parameter fails, - the parameter remains unmodified.</para> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/media-func-open.xml b/Documentation/DocBook/media/v4l/media-func-open.xml deleted file mode 100644 index 122374a3e894..000000000000 --- a/Documentation/DocBook/media/v4l/media-func-open.xml +++ /dev/null @@ -1,94 +0,0 @@ -<refentry id="media-func-open"> - <refmeta> - <refentrytitle>media open()</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>media-open</refname> - <refpurpose>Open a media device</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <fcntl.h></funcsynopsisinfo> - <funcprototype> - <funcdef>int <function>open</function></funcdef> - <paramdef>const char *<parameter>device_name</parameter></paramdef> - <paramdef>int <parameter>flags</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>device_name</parameter></term> - <listitem> - <para>Device to be opened.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>flags</parameter></term> - <listitem> - <para>Open flags. Access mode must be either <constant>O_RDONLY</constant> - or <constant>O_RDWR</constant>. Other flags have no effect.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - <refsect1> - <title>Description</title> - <para>To open a media device applications call <function>open()</function> - with the desired device name. The function has no side effects; the device - configuration remain unchanged.</para> - <para>When the device is opened in read-only mode, attempts to modify its - configuration will result in an error, and <varname>errno</varname> will be - set to <errorcode>EBADF</errorcode>.</para> - </refsect1> - <refsect1> - <title>Return Value</title> - - <para><function>open</function> returns the new file descriptor on success. - On error, -1 is returned, and <varname>errno</varname> is set appropriately. - Possible error codes are:</para> - - <variablelist> - <varlistentry> - <term><errorcode>EACCES</errorcode></term> - <listitem> - <para>The requested access to the file is not allowed.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EMFILE</errorcode></term> - <listitem> - <para>The process already has the maximum number of files open. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>ENFILE</errorcode></term> - <listitem> - <para>The system limit on the total number of open files has been - reached.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>ENOMEM</errorcode></term> - <listitem> - <para>Insufficient kernel memory was available.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>ENXIO</errorcode></term> - <listitem> - <para>No device corresponding to this device special file exists. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/media-ioc-device-info.xml b/Documentation/DocBook/media/v4l/media-ioc-device-info.xml deleted file mode 100644 index b0a21ac300b8..000000000000 --- a/Documentation/DocBook/media/v4l/media-ioc-device-info.xml +++ /dev/null @@ -1,132 +0,0 @@ -<refentry id="media-ioc-device-info"> - <refmeta> - <refentrytitle>ioctl MEDIA_IOC_DEVICE_INFO</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>MEDIA_IOC_DEVICE_INFO</refname> - <refpurpose>Query device information</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct media_device_info *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>File descriptor returned by - <link linkend='media-func-open'><function>open()</function></link>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>MEDIA_IOC_DEVICE_INFO</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>All media devices must support the <constant>MEDIA_IOC_DEVICE_INFO</constant> - ioctl. To query device information, applications call the ioctl with a - pointer to a &media-device-info;. The driver fills the structure and returns - the information to the application. - The ioctl never fails.</para> - - <table pgwide="1" frame="none" id="media-device-info"> - <title>struct <structname>media_device_info</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>char</entry> - <entry><structfield>driver</structfield>[16]</entry> - <entry><para>Name of the driver implementing the media API as a - NUL-terminated ASCII string. The driver version is stored in the - <structfield>driver_version</structfield> field.</para> - <para>Driver specific applications can use this information to - verify the driver identity. It is also useful to work around - known bugs, or to identify drivers in error reports.</para></entry> - </row> - <row> - <entry>char</entry> - <entry><structfield>model</structfield>[32]</entry> - <entry>Device model name as a NUL-terminated UTF-8 string. The - device version is stored in the <structfield>device_version</structfield> - field and is not be appended to the model name.</entry> - </row> - <row> - <entry>char</entry> - <entry><structfield>serial</structfield>[40]</entry> - <entry>Serial number as a NUL-terminated ASCII string.</entry> - </row> - <row> - <entry>char</entry> - <entry><structfield>bus_info</structfield>[32]</entry> - <entry>Location of the device in the system as a NUL-terminated - ASCII string. This includes the bus type name (PCI, USB, ...) and a - bus-specific identifier.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>media_version</structfield></entry> - <entry>Media API version, formatted with the - <constant>KERNEL_VERSION()</constant> macro.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>hw_revision</structfield></entry> - <entry>Hardware device revision in a driver-specific format.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>driver_version</structfield></entry> - <entry>Media device driver version, formatted with the - <constant>KERNEL_VERSION()</constant> macro. Together with the - <structfield>driver</structfield> field this identifies a particular - driver.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[31]</entry> - <entry>Reserved for future extensions. Drivers and applications must - set this array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - <para>The <structfield>serial</structfield> and <structfield>bus_info</structfield> - fields can be used to distinguish between multiple instances of otherwise - identical hardware. The serial number takes precedence when provided and can - be assumed to be unique. If the serial number is an empty string, the - <structfield>bus_info</structfield> field can be used instead. The - <structfield>bus_info</structfield> field is guaranteed to be unique, but - can vary across reboots or device unplug/replug.</para> - </refsect1> - - <refsect1> - &return-value; - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml b/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml deleted file mode 100644 index 0c4f96bfc2de..000000000000 --- a/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml +++ /dev/null @@ -1,180 +0,0 @@ -<refentry id="media-ioc-enum-entities"> - <refmeta> - <refentrytitle>ioctl MEDIA_IOC_ENUM_ENTITIES</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>MEDIA_IOC_ENUM_ENTITIES</refname> - <refpurpose>Enumerate entities and their properties</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct media_entity_desc *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>File descriptor returned by - <link linkend='media-func-open'><function>open()</function></link>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>MEDIA_IOC_ENUM_ENTITIES</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - <para>To query the attributes of an entity, applications set the id field - of a &media-entity-desc; structure and call the MEDIA_IOC_ENUM_ENTITIES - ioctl with a pointer to this structure. The driver fills the rest of the - structure or returns an &EINVAL; when the id is invalid.</para> - <para>Entities can be enumerated by or'ing the id with the - <constant>MEDIA_ENT_ID_FLAG_NEXT</constant> flag. The driver will return - information about the entity with the smallest id strictly larger than the - requested one ('next entity'), or the &EINVAL; if there is none.</para> - <para>Entity IDs can be non-contiguous. Applications must - <emphasis>not</emphasis> try to enumerate entities by calling - MEDIA_IOC_ENUM_ENTITIES with increasing id's until they get an error.</para> - - <table pgwide="1" frame="none" id="media-entity-desc"> - <title>struct <structname>media_entity_desc</structname></title> - <tgroup cols="5"> - <colspec colname="c1" /> - <colspec colname="c2" /> - <colspec colname="c3" /> - <colspec colname="c4" /> - <colspec colname="c5" /> - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>id</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Entity id, set by the application. When the id is or'ed with - <constant>MEDIA_ENT_ID_FLAG_NEXT</constant>, the driver clears the - flag and returns the first entity with a larger id.</entry> - </row> - <row> - <entry>char</entry> - <entry><structfield>name</structfield>[32]</entry> - <entry></entry> - <entry></entry> - <entry>Entity name as an UTF-8 NULL-terminated string.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Entity type, see <xref linkend="media-entity-type" /> for details.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>revision</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Entity revision. Always zero (obsolete)</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Entity flags, see <xref linkend="media-entity-flag" /> for details.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>group_id</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Entity group ID. Always zero (obsolete)</entry> - </row> - <row> - <entry>__u16</entry> - <entry><structfield>pads</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Number of pads</entry> - </row> - <row> - <entry>__u16</entry> - <entry><structfield>links</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Total number of outbound links. Inbound links are not counted - in this field.</entry> - </row> - <row> - <entry>union</entry> - </row> - <row> - <entry></entry> - <entry>struct</entry> - <entry><structfield>dev</structfield></entry> - <entry></entry> - <entry>Valid for (sub-)devices that create a single device node.</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>__u32</entry> - <entry><structfield>major</structfield></entry> - <entry>Device node major number.</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>__u32</entry> - <entry><structfield>minor</structfield></entry> - <entry>Device node minor number.</entry> - </row> - <row> - <entry></entry> - <entry>__u8</entry> - <entry><structfield>raw</structfield>[184]</entry> - <entry></entry> - <entry></entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The &media-entity-desc; <structfield>id</structfield> references - a non-existing entity.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml b/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml deleted file mode 100644 index 2bbeea9f3e18..000000000000 --- a/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml +++ /dev/null @@ -1,160 +0,0 @@ -<refentry id="media-ioc-enum-links"> - <refmeta> - <refentrytitle>ioctl MEDIA_IOC_ENUM_LINKS</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>MEDIA_IOC_ENUM_LINKS</refname> - <refpurpose>Enumerate all pads and links for a given entity</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct media_links_enum *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>File descriptor returned by - <link linkend='media-func-open'><function>open()</function></link>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>MEDIA_IOC_ENUM_LINKS</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>To enumerate pads and/or links for a given entity, applications set - the entity field of a &media-links-enum; structure and initialize the - &media-pad-desc; and &media-link-desc; structure arrays pointed by the - <structfield>pads</structfield> and <structfield>links</structfield> fields. - They then call the MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this - structure.</para> - <para>If the <structfield>pads</structfield> field is not NULL, the driver - fills the <structfield>pads</structfield> array with information about the - entity's pads. The array must have enough room to store all the entity's - pads. The number of pads can be retrieved with the &MEDIA-IOC-ENUM-ENTITIES; - ioctl.</para> - <para>If the <structfield>links</structfield> field is not NULL, the driver - fills the <structfield>links</structfield> array with information about the - entity's outbound links. The array must have enough room to store all the - entity's outbound links. The number of outbound links can be retrieved with - the &MEDIA-IOC-ENUM-ENTITIES; ioctl.</para> - <para>Only forward links that originate at one of the entity's source pads - are returned during the enumeration process.</para> - - <table pgwide="1" frame="none" id="media-links-enum"> - <title>struct <structname>media_links_enum</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>entity</structfield></entry> - <entry>Entity id, set by the application.</entry> - </row> - <row> - <entry>&media-pad-desc;</entry> - <entry>*<structfield>pads</structfield></entry> - <entry>Pointer to a pads array allocated by the application. Ignored - if NULL.</entry> - </row> - <row> - <entry>&media-link-desc;</entry> - <entry>*<structfield>links</structfield></entry> - <entry>Pointer to a links array allocated by the application. Ignored - if NULL.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="media-pad-desc"> - <title>struct <structname>media_pad_desc</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>entity</structfield></entry> - <entry>ID of the entity this pad belongs to.</entry> - </row> - <row> - <entry>__u16</entry> - <entry><structfield>index</structfield></entry> - <entry>0-based pad index.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry>Pad flags, see <xref linkend="media-pad-flag" /> for more details.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="media-link-desc"> - <title>struct <structname>media_link_desc</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>&media-pad-desc;</entry> - <entry><structfield>source</structfield></entry> - <entry>Pad at the origin of this link.</entry> - </row> - <row> - <entry>&media-pad-desc;</entry> - <entry><structfield>sink</structfield></entry> - <entry>Pad at the target of this link.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry>Link flags, see <xref linkend="media-link-flag" /> for more details.</entry> - </row> - </tbody> - </tgroup> - </table> - - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The &media-links-enum; <structfield>id</structfield> references - a non-existing entity.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/media-ioc-g-topology.xml b/Documentation/DocBook/media/v4l/media-ioc-g-topology.xml deleted file mode 100644 index 63152ab9efba..000000000000 --- a/Documentation/DocBook/media/v4l/media-ioc-g-topology.xml +++ /dev/null @@ -1,394 +0,0 @@ -<refentry id="media-g-topology"> - <refmeta> - <refentrytitle>ioctl MEDIA_IOC_G_TOPOLOGY</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>MEDIA_IOC_G_TOPOLOGY</refname> - <refpurpose>Enumerate the graph topology and graph element properties</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct media_v2_topology *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>File descriptor returned by - <link linkend='media-func-open'><function>open()</function></link>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>MEDIA_IOC_G_TOPOLOGY</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para><emphasis role="bold">NOTE:</emphasis> This new ioctl is programmed to be added on Kernel 4.6. Its definition/arguments may change until its final version.</para> - - <para>The typical usage of this ioctl is to call it twice. - On the first call, the structure defined at &media-v2-topology; should - be zeroed. At return, if no errors happen, this ioctl will return the - <constant>topology_version</constant> and the total number of entities, - interfaces, pads and links.</para> - <para>Before the second call, the userspace should allocate arrays to - store the graph elements that are desired, putting the pointers to them - at the ptr_entities, ptr_interfaces, ptr_links and/or ptr_pads, keeping - the other values untouched.</para> - <para>If the <constant>topology_version</constant> remains the same, the - ioctl should fill the desired arrays with the media graph elements.</para> - - <table pgwide="1" frame="none" id="media-v2-topology"> - <title>struct <structname>media_v2_topology</structname></title> - <tgroup cols="5"> - <colspec colname="c1" /> - <colspec colname="c2" /> - <colspec colname="c3" /> - <colspec colname="c4" /> - <colspec colname="c5" /> - <tbody valign="top"> - <row> - <entry>__u64</entry> - <entry><structfield>topology_version</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Version of the media graph topology. When the graph is - created, this field starts with zero. Every time a graph - element is added or removed, this field is - incremented.</entry> - </row> - <row> - <entry>__u64</entry> - <entry><structfield>num_entities</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Number of entities in the graph</entry> - </row> - <row> - <entry>__u64</entry> - <entry><structfield>ptr_entities</structfield></entry> - <entry></entry> - <entry></entry> - <entry>A pointer to a memory area where the entities array - will be stored, converted to a 64-bits integer. - It can be zero. if zero, the ioctl won't store the - entities. It will just update - <constant>num_entities</constant></entry> - </row> - <row> - <entry>__u64</entry> - <entry><structfield>num_interfaces</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Number of interfaces in the graph</entry> - </row> - <row> - <entry>__u64</entry> - <entry><structfield>ptr_interfaces</structfield></entry> - <entry></entry> - <entry></entry> - <entry>A pointer to a memory area where the interfaces array - will be stored, converted to a 64-bits integer. - It can be zero. if zero, the ioctl won't store the - interfaces. It will just update - <constant>num_interfaces</constant></entry> - </row> - <row> - <entry>__u64</entry> - <entry><structfield>num_pads</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Total number of pads in the graph</entry> - </row> - <row> - <entry>__u64</entry> - <entry><structfield>ptr_pads</structfield></entry> - <entry></entry> - <entry></entry> - <entry>A pointer to a memory area where the pads array - will be stored, converted to a 64-bits integer. - It can be zero. if zero, the ioctl won't store the - pads. It will just update - <constant>num_pads</constant></entry> - </row> - <row> - <entry>__u64</entry> - <entry><structfield>num_links</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Total number of data and interface links in the graph</entry> - </row> - <row> - <entry>__u64</entry> - <entry><structfield>ptr_links</structfield></entry> - <entry></entry> - <entry></entry> - <entry>A pointer to a memory area where the links array - will be stored, converted to a 64-bits integer. - It can be zero. if zero, the ioctl won't store the - links. It will just update - <constant>num_links</constant></entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="media-v2-entity"> - <title>struct <structname>media_v2_entity</structname></title> - <tgroup cols="5"> - <colspec colname="c1" /> - <colspec colname="c2" /> - <colspec colname="c3" /> - <colspec colname="c4" /> - <colspec colname="c5" /> - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>id</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Unique ID for the entity.</entry> - </row> - <row> - <entry>char</entry> - <entry><structfield>name</structfield>[64]</entry> - <entry></entry> - <entry></entry> - <entry>Entity name as an UTF-8 NULL-terminated string.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>function</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Entity main function, see <xref linkend="media-entity-type" /> for details.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[12]</entry> - <entry>Reserved for future extensions. Drivers and applications must - set this array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="media-v2-interface"> - <title>struct <structname>media_v2_interface</structname></title> - <tgroup cols="5"> - <colspec colname="c1" /> - <colspec colname="c2" /> - <colspec colname="c3" /> - <colspec colname="c4" /> - <colspec colname="c5" /> - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>id</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Unique ID for the interface.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>intf_type</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Interface type, see <xref linkend="media-intf-type" /> for details.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Interface flags. Currently unused.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[9]</entry> - <entry></entry> - <entry></entry> - <entry>Reserved for future extensions. Drivers and applications must - set this array to zero.</entry> - </row> - <row> - <entry>struct media_v2_intf_devnode</entry> - <entry><structfield>devnode</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Used only for device node interfaces. See <xref linkend="media-v2-intf-devnode" /> for details..</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="media-v2-intf-devnode"> - <title>struct <structname>media_v2_interface</structname></title> - <tgroup cols="5"> - <colspec colname="c1" /> - <colspec colname="c2" /> - <colspec colname="c3" /> - <colspec colname="c4" /> - <colspec colname="c5" /> - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>major</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Device node major number.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>minor</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Device node minor number.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="media-v2-pad"> - <title>struct <structname>media_v2_pad</structname></title> - <tgroup cols="5"> - <colspec colname="c1" /> - <colspec colname="c2" /> - <colspec colname="c3" /> - <colspec colname="c4" /> - <colspec colname="c5" /> - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>id</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Unique ID for the pad.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>entity_id</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Unique ID for the entity where this pad belongs.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Pad flags, see <xref linkend="media-pad-flag" /> for more details.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[9]</entry> - <entry></entry> - <entry></entry> - <entry>Reserved for future extensions. Drivers and applications must - set this array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="media-v2-link"> - <title>struct <structname>media_v2_pad</structname></title> - <tgroup cols="5"> - <colspec colname="c1" /> - <colspec colname="c2" /> - <colspec colname="c3" /> - <colspec colname="c4" /> - <colspec colname="c5" /> - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>id</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Unique ID for the pad.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>source_id</structfield></entry> - <entry></entry> - <entry></entry> - <entry> - <para>On pad to pad links: unique ID for the source pad.</para> - <para>On interface to entity links: unique ID for the interface.</para> - </entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>sink_id</structfield></entry> - <entry></entry> - <entry></entry> - <entry> - <para>On pad to pad links: unique ID for the sink pad.</para> - <para>On interface to entity links: unique ID for the entity.</para> - </entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Link flags, see <xref linkend="media-link-flag" /> for more details.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[5]</entry> - <entry></entry> - <entry></entry> - <entry>Reserved for future extensions. Drivers and applications must - set this array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>ENOSPC</errorcode></term> - <listitem> - <para>This is returned when either one or more of the num_entities, - num_interfaces, num_links or num_pads are non-zero and are smaller - than the actual number of elements inside the graph. This may happen - if the <constant>topology_version</constant> changed when compared - to the last time this ioctl was called. Userspace should usually - free the area for the pointers, zero the struct elements and call - this ioctl again.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/media-ioc-setup-link.xml b/Documentation/DocBook/media/v4l/media-ioc-setup-link.xml deleted file mode 100644 index fc2e522ee65a..000000000000 --- a/Documentation/DocBook/media/v4l/media-ioc-setup-link.xml +++ /dev/null @@ -1,84 +0,0 @@ -<refentry id="media-ioc-setup-link"> - <refmeta> - <refentrytitle>ioctl MEDIA_IOC_SETUP_LINK</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>MEDIA_IOC_SETUP_LINK</refname> - <refpurpose>Modify the properties of a link</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct media_link_desc *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>File descriptor returned by - <link linkend='media-func-open'><function>open()</function></link>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>MEDIA_IOC_SETUP_LINK</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>To change link properties applications fill a &media-link-desc; with - link identification information (source and sink pad) and the new requested - link flags. They then call the MEDIA_IOC_SETUP_LINK ioctl with a pointer to - that structure.</para> - <para>The only configurable property is the <constant>ENABLED</constant> - link flag to enable/disable a link. Links marked with the - <constant>IMMUTABLE</constant> link flag can not be enabled or disabled. - </para> - <para>Link configuration has no side effect on other links. If an enabled - link at the sink pad prevents the link from being enabled, the driver - returns with an &EBUSY;.</para> - <para>Only links marked with the <constant>DYNAMIC</constant> link flag can - be enabled/disabled while streaming media data. Attempting to enable or - disable a streaming non-dynamic link will return an &EBUSY;.</para> - <para>If the specified link can't be found the driver returns with an - &EINVAL;.</para> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The &media-link-desc; references a non-existing link, or the - link is immutable and an attempt to modify its configuration was made. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/media-types.xml b/Documentation/DocBook/media/v4l/media-types.xml deleted file mode 100644 index 0ee0f3386cdf..000000000000 --- a/Documentation/DocBook/media/v4l/media-types.xml +++ /dev/null @@ -1,236 +0,0 @@ -<section id="media-controller-types"> -<title>Types and flags used to represent the media graph elements</title> - - <table frame="none" pgwide="1" id="media-entity-type"> - <title>Media entity types</title> - <tgroup cols="2"> - <colspec colname="c1"/> - <colspec colname="c2"/> - <tbody valign="top"> - <row> - <entry><constant>MEDIA_ENT_F_UNKNOWN</constant> and <constant>MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN</constant></entry> - <entry>Unknown entity. That generally indicates that - a driver didn't initialize properly the entity, with is a Kernel bug</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_F_IO_V4L</constant></entry> - <entry>Data streaming input and/or output entity.</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_F_IO_VBI</constant></entry> - <entry>V4L VBI streaming input or output entity</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_F_IO_SWRADIO</constant></entry> - <entry>V4L Software Digital Radio (SDR) streaming input or output entity</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_F_IO_DTV</constant></entry> - <entry>DVB Digital TV streaming input or output entity</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_F_DTV_DEMOD</constant></entry> - <entry>Digital TV demodulator entity.</entry> - </row> - <row> - <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> - <entry><constant>MEDIA_ENT_F_DTV_CA</constant></entry> - <entry>Digital TV Conditional Access module (CAM) entity</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_F_DTV_NET_DECAP</constant></entry> - <entry>Digital TV network ULE/MLE desencapsulation entity. Could be implemented on hardware or in Kernelspace</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_F_CONN_RF</constant></entry> - <entry>Connector for a Radio Frequency (RF) signal.</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_F_CONN_SVIDEO</constant></entry> - <entry>Connector for a S-Video signal.</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_F_CONN_COMPOSITE</constant></entry> - <entry>Connector for a RGB composite signal.</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_F_CAM_SENSOR</constant></entry> - <entry>Camera video sensor entity.</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_F_FLASH</constant></entry> - <entry>Flash controller entity.</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_F_LENS</constant></entry> - <entry>Lens controller entity.</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_F_ATV_DECODER</constant></entry> - <entry>Analog video decoder, the basic function of the video decoder - is to accept analogue video from a wide variety of sources such as - broadcast, DVD players, cameras and video cassette recorders, in - either NTSC, PAL, SECAM or HD format, separating the stream - into its component parts, luminance and chrominance, and output - it in some digital video standard, with appropriate timing - signals.</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_F_TUNER</constant></entry> - <entry>Digital TV, analog TV, radio and/or software radio tuner.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="media-entity-flag"> - <title>Media entity flags</title> - <tgroup cols="2"> - <colspec colname="c1"/> - <colspec colname="c2"/> - <tbody valign="top"> - <row> - <entry><constant>MEDIA_ENT_FL_DEFAULT</constant></entry> - <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> - - <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"> - <colspec colname="c1"/> - <colspec colname="c2"/> - <tbody valign="top"> - <row> - <entry><constant>MEDIA_PAD_FL_SINK</constant></entry> - <entry>Input pad, relative to the entity. Input pads sink data and - are targets of links.</entry> - </row> - <row> - <entry><constant>MEDIA_PAD_FL_SOURCE</constant></entry> - <entry>Output pad, relative to the entity. Output pads source data - and are origins of links.</entry> - </row> - <row> - <entry><constant>MEDIA_PAD_FL_MUST_CONNECT</constant></entry> - <entry>If this flag is set and the pad is linked to any other - pad, then at least one of those links must be enabled for the - entity to be able to stream. There could be temporary reasons - (e.g. device configuration dependent) for the pad to need - enabled links even when this flag isn't set; the absence of the - flag doesn't imply there is none.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>One and only one of <constant>MEDIA_PAD_FL_SINK</constant> and - <constant>MEDIA_PAD_FL_SOURCE</constant> must be set for every pad.</para> - - <table frame="none" pgwide="1" id="media-link-flag"> - <title>Media link flags</title> - <tgroup cols="2"> - <colspec colname="c1"/> - <colspec colname="c2"/> - <tbody valign="top"> - <row> - <entry><constant>MEDIA_LNK_FL_ENABLED</constant></entry> - <entry>The link is enabled and can be used to transfer media data. - When two or more links target a sink pad, only one of them can be - enabled at a time.</entry> - </row> - <row> - <entry><constant>MEDIA_LNK_FL_IMMUTABLE</constant></entry> - <entry>The link enabled state can't be modified at runtime. An - immutable link is always enabled.</entry> - </row> - <row> - <entry><constant>MEDIA_LNK_FL_DYNAMIC</constant></entry> - <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> - -</section> diff --git a/Documentation/DocBook/media/v4l/pipeline.pdf b/Documentation/DocBook/media/v4l/pipeline.pdf Binary files differdeleted file mode 100644 index ee3e37f04b6a..000000000000 --- a/Documentation/DocBook/media/v4l/pipeline.pdf +++ /dev/null diff --git a/Documentation/DocBook/media/v4l/pixfmt-grey.xml b/Documentation/DocBook/media/v4l/pixfmt-grey.xml deleted file mode 100644 index bee970d3f76d..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-grey.xml +++ /dev/null @@ -1,62 +0,0 @@ - <refentry id="V4L2-PIX-FMT-GREY"> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_GREY ('GREY')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname><constant>V4L2_PIX_FMT_GREY</constant></refname> - <refpurpose>Grey-scale image</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>This is a grey-scale image. It is really a degenerate -Y'CbCr format which simply contains no Cb or Cr data.</para> - - <example> - <title><constant>V4L2_PIX_FMT_GREY</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>Y'<subscript>00</subscript></entry> - <entry>Y'<subscript>01</subscript></entry> - <entry>Y'<subscript>02</subscript></entry> - <entry>Y'<subscript>03</subscript></entry> - </row> - <row> - <entry>start + 4:</entry> - <entry>Y'<subscript>10</subscript></entry> - <entry>Y'<subscript>11</subscript></entry> - <entry>Y'<subscript>12</subscript></entry> - <entry>Y'<subscript>13</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>Y'<subscript>20</subscript></entry> - <entry>Y'<subscript>21</subscript></entry> - <entry>Y'<subscript>22</subscript></entry> - <entry>Y'<subscript>23</subscript></entry> - </row> - <row> - <entry>start + 12:</entry> - <entry>Y'<subscript>30</subscript></entry> - <entry>Y'<subscript>31</subscript></entry> - <entry>Y'<subscript>32</subscript></entry> - <entry>Y'<subscript>33</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-m420.xml b/Documentation/DocBook/media/v4l/pixfmt-m420.xml deleted file mode 100644 index aadae92c5d04..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-m420.xml +++ /dev/null @@ -1,139 +0,0 @@ - <refentry id="V4L2-PIX-FMT-M420"> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_M420 ('M420')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname><constant>V4L2_PIX_FMT_M420</constant></refname> - <refpurpose>Format with ½ horizontal and vertical chroma - resolution, also known as YUV 4:2:0. Hybrid plane line-interleaved - layout.</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>M420 is a YUV format with ½ horizontal and vertical chroma - subsampling (YUV 4:2:0). Pixels are organized as interleaved luma and - chroma planes. Two lines of luma data are followed by one line of chroma - data.</para> - <para>The luma plane has one byte per pixel. The chroma plane contains - interleaved CbCr pixels subsampled by ½ in the horizontal and - vertical directions. Each CbCr pair belongs to four pixels. For example, -Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to -Y'<subscript>00</subscript>, Y'<subscript>01</subscript>, -Y'<subscript>10</subscript>, Y'<subscript>11</subscript>.</para> - - <para>All line lengths are identical: if the Y lines include pad bytes - so do the CbCr lines.</para> - - <example> - <title><constant>V4L2_PIX_FMT_M420</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>Y'<subscript>00</subscript></entry> - <entry>Y'<subscript>01</subscript></entry> - <entry>Y'<subscript>02</subscript></entry> - <entry>Y'<subscript>03</subscript></entry> - </row> - <row> - <entry>start + 4:</entry> - <entry>Y'<subscript>10</subscript></entry> - <entry>Y'<subscript>11</subscript></entry> - <entry>Y'<subscript>12</subscript></entry> - <entry>Y'<subscript>13</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>Cb<subscript>00</subscript></entry> - <entry>Cr<subscript>00</subscript></entry> - <entry>Cb<subscript>01</subscript></entry> - <entry>Cr<subscript>01</subscript></entry> - </row> - <row> - <entry>start + 16:</entry> - <entry>Y'<subscript>20</subscript></entry> - <entry>Y'<subscript>21</subscript></entry> - <entry>Y'<subscript>22</subscript></entry> - <entry>Y'<subscript>23</subscript></entry> - </row> - <row> - <entry>start + 20:</entry> - <entry>Y'<subscript>30</subscript></entry> - <entry>Y'<subscript>31</subscript></entry> - <entry>Y'<subscript>32</subscript></entry> - <entry>Y'<subscript>33</subscript></entry> - </row> - <row> - <entry>start + 24:</entry> - <entry>Cb<subscript>10</subscript></entry> - <entry>Cr<subscript>10</subscript></entry> - <entry>Cb<subscript>11</subscript></entry> - <entry>Cr<subscript>11</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - - <formalpara> - <title>Color Sample Location.</title> - <para> - <informaltable frame="none"> - <tgroup cols="7" align="center"> - <tbody valign="top"> - <row> - <entry></entry> - <entry>0</entry><entry></entry><entry>1</entry><entry></entry> - <entry>2</entry><entry></entry><entry>3</entry> - </row> - <row> - <entry>0</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - <entry></entry><entry>C</entry><entry></entry><entry></entry> - <entry></entry><entry>C</entry><entry></entry> - </row> - <row> - <entry>1</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - </row> - <row> - <entry>2</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - <entry></entry><entry>C</entry><entry></entry><entry></entry> - <entry></entry><entry>C</entry><entry></entry> - </row> - <row> - <entry>3</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv12.xml b/Documentation/DocBook/media/v4l/pixfmt-nv12.xml deleted file mode 100644 index 84dd4fd7cb80..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-nv12.xml +++ /dev/null @@ -1,143 +0,0 @@ - <refentry> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_NV12 ('NV12'), V4L2_PIX_FMT_NV21 ('NV21')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname id="V4L2-PIX-FMT-NV12"><constant>V4L2_PIX_FMT_NV12</constant></refname> - <refname id="V4L2-PIX-FMT-NV21"><constant>V4L2_PIX_FMT_NV21</constant></refname> - <refpurpose>Formats with ½ horizontal and vertical -chroma resolution, also known as YUV 4:2:0. One luminance and one -chrominance plane with alternating chroma samples as opposed to -<constant>V4L2_PIX_FMT_YVU420</constant></refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>These are two-plane versions of the YUV 4:2:0 format. -The three components are separated into two sub-images or planes. The -Y plane is first. The Y plane has one byte per pixel. For -<constant>V4L2_PIX_FMT_NV12</constant>, a combined CbCr plane -immediately follows the Y plane in memory. The CbCr plane is the same -width, in bytes, as the Y plane (and of the image), but is half as -tall in pixels. Each CbCr pair belongs to four pixels. For example, -Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to -Y'<subscript>00</subscript>, Y'<subscript>01</subscript>, -Y'<subscript>10</subscript>, Y'<subscript>11</subscript>. -<constant>V4L2_PIX_FMT_NV21</constant> is the same except the Cb and -Cr bytes are swapped, the CrCb plane starts with a Cr byte.</para> - - <para>If the Y plane has pad bytes after each row, then the -CbCr plane has as many pad bytes after its rows.</para> - - <example> - <title><constant>V4L2_PIX_FMT_NV12</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>Y'<subscript>00</subscript></entry> - <entry>Y'<subscript>01</subscript></entry> - <entry>Y'<subscript>02</subscript></entry> - <entry>Y'<subscript>03</subscript></entry> - </row> - <row> - <entry>start + 4:</entry> - <entry>Y'<subscript>10</subscript></entry> - <entry>Y'<subscript>11</subscript></entry> - <entry>Y'<subscript>12</subscript></entry> - <entry>Y'<subscript>13</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>Y'<subscript>20</subscript></entry> - <entry>Y'<subscript>21</subscript></entry> - <entry>Y'<subscript>22</subscript></entry> - <entry>Y'<subscript>23</subscript></entry> - </row> - <row> - <entry>start + 12:</entry> - <entry>Y'<subscript>30</subscript></entry> - <entry>Y'<subscript>31</subscript></entry> - <entry>Y'<subscript>32</subscript></entry> - <entry>Y'<subscript>33</subscript></entry> - </row> - <row> - <entry>start + 16:</entry> - <entry>Cb<subscript>00</subscript></entry> - <entry>Cr<subscript>00</subscript></entry> - <entry>Cb<subscript>01</subscript></entry> - <entry>Cr<subscript>01</subscript></entry> - </row> - <row> - <entry>start + 20:</entry> - <entry>Cb<subscript>10</subscript></entry> - <entry>Cr<subscript>10</subscript></entry> - <entry>Cb<subscript>11</subscript></entry> - <entry>Cr<subscript>11</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - - <formalpara> - <title>Color Sample Location.</title> - <para> - <informaltable frame="none"> - <tgroup cols="7" align="center"> - <tbody valign="top"> - <row> - <entry></entry> - <entry>0</entry><entry></entry><entry>1</entry><entry></entry> - <entry>2</entry><entry></entry><entry>3</entry> - </row> - <row> - <entry>0</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - <entry></entry><entry>C</entry><entry></entry><entry></entry> - <entry></entry><entry>C</entry><entry></entry> - </row> - <row> - <entry>1</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - </row> - <row> - <entry>2</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - <entry></entry><entry>C</entry><entry></entry><entry></entry> - <entry></entry><entry>C</entry><entry></entry> - </row> - <row> - <entry>3</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv12m.xml b/Documentation/DocBook/media/v4l/pixfmt-nv12m.xml deleted file mode 100644 index f3a3d459fcdf..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-nv12m.xml +++ /dev/null @@ -1,153 +0,0 @@ - <refentry> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_NV12M ('NM12'), V4L2_PIX_FMT_NV21M ('NM21'), V4L2_PIX_FMT_NV12MT_16X16</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname id="V4L2-PIX-FMT-NV12M"><constant>V4L2_PIX_FMT_NV12M</constant></refname> - <refname id="V4L2-PIX-FMT-NV21M"><constant>V4L2_PIX_FMT_NV21M</constant></refname> - <refname id="V4L2-PIX-FMT-NV12MT-16X16"><constant>V4L2_PIX_FMT_NV12MT_16X16</constant></refname> - <refpurpose>Variation of <constant>V4L2_PIX_FMT_NV12</constant> and <constant>V4L2_PIX_FMT_NV21</constant> with planes - non contiguous in memory. </refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>This is a multi-planar, two-plane version of the YUV 4:2:0 format. -The three components are separated into two sub-images or planes. -<constant>V4L2_PIX_FMT_NV12M</constant> differs from <constant>V4L2_PIX_FMT_NV12 -</constant> in that the two planes are non-contiguous in memory, i.e. the chroma -plane do not necessarily immediately follows the luma plane. -The luminance data occupies the first plane. The Y plane has one byte per pixel. -In the second plane there is a chrominance data with alternating chroma samples. -The CbCr plane is the same width, in bytes, as the Y plane (and of the image), -but is half as tall in pixels. Each CbCr pair belongs to four pixels. For example, -Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to -Y'<subscript>00</subscript>, Y'<subscript>01</subscript>, -Y'<subscript>10</subscript>, Y'<subscript>11</subscript>. -<constant>V4L2_PIX_FMT_NV12MT_16X16</constant> is the tiled version of -<constant>V4L2_PIX_FMT_NV12M</constant> with 16x16 macroblock tiles. Here pixels -are arranged in 16x16 2D tiles and tiles are arranged in linear order in memory. -<constant>V4L2_PIX_FMT_NV21M</constant> is the same as <constant>V4L2_PIX_FMT_NV12M</constant> -except the Cb and Cr bytes are swapped, the CrCb plane starts with a Cr byte.</para> - - <para><constant>V4L2_PIX_FMT_NV12M</constant> is intended to be -used only in drivers and applications that support the multi-planar API, -described in <xref linkend="planar-apis"/>. </para> - - <para>If the Y plane has pad bytes after each row, then the -CbCr plane has as many pad bytes after its rows.</para> - - <example> - <title><constant>V4L2_PIX_FMT_NV12M</constant> 4 × 4 pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start0 + 0:</entry> - <entry>Y'<subscript>00</subscript></entry> - <entry>Y'<subscript>01</subscript></entry> - <entry>Y'<subscript>02</subscript></entry> - <entry>Y'<subscript>03</subscript></entry> - </row> - <row> - <entry>start0 + 4:</entry> - <entry>Y'<subscript>10</subscript></entry> - <entry>Y'<subscript>11</subscript></entry> - <entry>Y'<subscript>12</subscript></entry> - <entry>Y'<subscript>13</subscript></entry> - </row> - <row> - <entry>start0 + 8:</entry> - <entry>Y'<subscript>20</subscript></entry> - <entry>Y'<subscript>21</subscript></entry> - <entry>Y'<subscript>22</subscript></entry> - <entry>Y'<subscript>23</subscript></entry> - </row> - <row> - <entry>start0 + 12:</entry> - <entry>Y'<subscript>30</subscript></entry> - <entry>Y'<subscript>31</subscript></entry> - <entry>Y'<subscript>32</subscript></entry> - <entry>Y'<subscript>33</subscript></entry> - </row> - <row> - <entry></entry> - </row> - <row> - <entry>start1 + 0:</entry> - <entry>Cb<subscript>00</subscript></entry> - <entry>Cr<subscript>00</subscript></entry> - <entry>Cb<subscript>01</subscript></entry> - <entry>Cr<subscript>01</subscript></entry> - </row> - <row> - <entry>start1 + 4:</entry> - <entry>Cb<subscript>10</subscript></entry> - <entry>Cr<subscript>10</subscript></entry> - <entry>Cb<subscript>11</subscript></entry> - <entry>Cr<subscript>11</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - - <formalpara> - <title>Color Sample Location.</title> - <para> - <informaltable frame="none"> - <tgroup cols="7" align="center"> - <tbody valign="top"> - <row> - <entry></entry> - <entry>0</entry><entry></entry><entry>1</entry><entry></entry> - <entry>2</entry><entry></entry><entry>3</entry> - </row> - <row> - <entry>0</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - <entry></entry><entry>C</entry><entry></entry><entry></entry> - <entry></entry><entry>C</entry><entry></entry> - </row> - <row> - <entry>1</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - </row> - <row> - <entry>2</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - <entry></entry><entry>C</entry><entry></entry><entry></entry> - <entry></entry><entry>C</entry><entry></entry> - </row> - <row> - <entry>3</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv12mt.xml b/Documentation/DocBook/media/v4l/pixfmt-nv12mt.xml deleted file mode 100644 index 8a70a1707b7a..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-nv12mt.xml +++ /dev/null @@ -1,66 +0,0 @@ - <refentry> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_NV12MT ('TM12')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname id="V4L2-PIX-FMT-NV12MT"><constant>V4L2_PIX_FMT_NV12MT -</constant></refname> - <refpurpose>Formats with ½ horizontal and vertical -chroma resolution. This format has two planes - one for luminance and one for -chrominance. Chroma samples are interleaved. The difference to -<constant>V4L2_PIX_FMT_NV12</constant> is the memory layout. Pixels are -grouped in macroblocks of 64x32 size. The order of macroblocks in memory is -also not standard. - </refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>This is the two-plane versions of the YUV 4:2:0 format where data -is grouped into 64x32 macroblocks. The three components are separated into two -sub-images or planes. The Y plane has one byte per pixel and pixels are grouped -into 64x32 macroblocks. The CbCr plane has the same width, in bytes, as the Y -plane (and the image), but is half as tall in pixels. The chroma plane is also -grouped into 64x32 macroblocks.</para> - <para>Width of the buffer has to be aligned to the multiple of 128, and -height alignment is 32. Every four adjacent buffers - two horizontally and two -vertically are grouped together and are located in memory in Z or flipped Z -order. </para> - <para>Layout of macroblocks in memory is presented in the following -figure.</para> - <para><figure id="nv12mt"> - <title><constant>V4L2_PIX_FMT_NV12MT</constant> macroblock Z shape -memory layout</title> - <mediaobject> - <imageobject> - <imagedata fileref="nv12mt.gif" format="GIF" /> - </imageobject> - </mediaobject> - </figure> - The requirement that width is multiple of 128 is implemented because, -the Z shape cannot be cut in half horizontally. In case the vertical resolution -of macroblocks is odd then the last row of macroblocks is arranged in a linear -order. </para> - <para>In case of chroma the layout is identical. Cb and Cr samples are -interleaved. Height of the buffer is aligned to 32. - </para> - <example> - <title>Memory layout of macroblocks in <constant>V4L2_PIX_FMT_NV12 -</constant> format pixel image - extreme case</title> - <para> - <figure id="nv12mt_ex"> - <title>Example <constant>V4L2_PIX_FMT_NV12MT</constant> memory -layout of macroblocks</title> - <mediaobject> - <imageobject> - <imagedata fileref="nv12mt_example.gif" format="GIF" /> - </imageobject> - </mediaobject> - </figure> - Memory layout of macroblocks of <constant>V4L2_PIX_FMT_NV12MT -</constant> format in most extreme case. - </para> - </example> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv16.xml b/Documentation/DocBook/media/v4l/pixfmt-nv16.xml deleted file mode 100644 index 8ae1f8a810d0..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-nv16.xml +++ /dev/null @@ -1,166 +0,0 @@ - <refentry> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_NV16 ('NV16'), V4L2_PIX_FMT_NV61 ('NV61')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname id="V4L2-PIX-FMT-NV16"><constant>V4L2_PIX_FMT_NV16</constant></refname> - <refname id="V4L2-PIX-FMT-NV61"><constant>V4L2_PIX_FMT_NV61</constant></refname> - <refpurpose>Formats with ½ horizontal -chroma resolution, also known as YUV 4:2:2. One luminance and one -chrominance plane with alternating chroma samples as opposed to -<constant>V4L2_PIX_FMT_YVU420</constant></refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>These are two-plane versions of the YUV 4:2:2 format. -The three components are separated into two sub-images or planes. The -Y plane is first. The Y plane has one byte per pixel. For -<constant>V4L2_PIX_FMT_NV16</constant>, a combined CbCr plane -immediately follows the Y plane in memory. The CbCr plane is the same -width and height, in bytes, as the Y plane (and of the image). -Each CbCr pair belongs to two pixels. For example, -Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to -Y'<subscript>00</subscript>, Y'<subscript>01</subscript>. -<constant>V4L2_PIX_FMT_NV61</constant> is the same except the Cb and -Cr bytes are swapped, the CrCb plane starts with a Cr byte.</para> - - <para>If the Y plane has pad bytes after each row, then the -CbCr plane has as many pad bytes after its rows.</para> - - <example> - <title><constant>V4L2_PIX_FMT_NV16</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>Y'<subscript>00</subscript></entry> - <entry>Y'<subscript>01</subscript></entry> - <entry>Y'<subscript>02</subscript></entry> - <entry>Y'<subscript>03</subscript></entry> - </row> - <row> - <entry>start + 4:</entry> - <entry>Y'<subscript>10</subscript></entry> - <entry>Y'<subscript>11</subscript></entry> - <entry>Y'<subscript>12</subscript></entry> - <entry>Y'<subscript>13</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>Y'<subscript>20</subscript></entry> - <entry>Y'<subscript>21</subscript></entry> - <entry>Y'<subscript>22</subscript></entry> - <entry>Y'<subscript>23</subscript></entry> - </row> - <row> - <entry>start + 12:</entry> - <entry>Y'<subscript>30</subscript></entry> - <entry>Y'<subscript>31</subscript></entry> - <entry>Y'<subscript>32</subscript></entry> - <entry>Y'<subscript>33</subscript></entry> - </row> - <row> - <entry>start + 16:</entry> - <entry>Cb<subscript>00</subscript></entry> - <entry>Cr<subscript>00</subscript></entry> - <entry>Cb<subscript>01</subscript></entry> - <entry>Cr<subscript>01</subscript></entry> - </row> - <row> - <entry>start + 20:</entry> - <entry>Cb<subscript>10</subscript></entry> - <entry>Cr<subscript>10</subscript></entry> - <entry>Cb<subscript>11</subscript></entry> - <entry>Cr<subscript>11</subscript></entry> - </row> - <row> - <entry>start + 24:</entry> - <entry>Cb<subscript>20</subscript></entry> - <entry>Cr<subscript>20</subscript></entry> - <entry>Cb<subscript>21</subscript></entry> - <entry>Cr<subscript>21</subscript></entry> - </row> - <row> - <entry>start + 28:</entry> - <entry>Cb<subscript>30</subscript></entry> - <entry>Cr<subscript>30</subscript></entry> - <entry>Cb<subscript>31</subscript></entry> - <entry>Cr<subscript>31</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - - <formalpara> - <title>Color Sample Location.</title> - <para> - <informaltable frame="none"> - <tgroup cols="7" align="center"> - <tbody valign="top"> - <row> - <entry></entry> - <entry>0</entry><entry></entry><entry>1</entry><entry></entry> - <entry>2</entry><entry></entry><entry>3</entry> - </row> - <row> - <entry>0</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - <entry></entry><entry>C</entry><entry></entry><entry></entry> - <entry></entry><entry>C</entry><entry></entry> - </row> - <row> - <entry>1</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - <entry></entry><entry>C</entry><entry></entry><entry></entry> - <entry></entry><entry>C</entry><entry></entry> - </row> - <row> - <entry></entry> - </row> - <row> - <entry>2</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - <entry></entry><entry>C</entry><entry></entry><entry></entry> - <entry></entry><entry>C</entry><entry></entry> - </row> - <row> - <entry>3</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - <entry></entry><entry>C</entry><entry></entry><entry></entry> - <entry></entry><entry>C</entry><entry></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv16m.xml b/Documentation/DocBook/media/v4l/pixfmt-nv16m.xml deleted file mode 100644 index fb2b5e35d665..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-nv16m.xml +++ /dev/null @@ -1,170 +0,0 @@ - <refentry> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_NV16M ('NM16'), V4L2_PIX_FMT_NV61M ('NM61')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname id="V4L2-PIX-FMT-NV16M"><constant>V4L2_PIX_FMT_NV16M</constant></refname> - <refname id="V4L2-PIX-FMT-NV61M"><constant>V4L2_PIX_FMT_NV61M</constant></refname> - <refpurpose>Variation of <constant>V4L2_PIX_FMT_NV16</constant> and <constant>V4L2_PIX_FMT_NV61</constant> with planes - non contiguous in memory. </refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>This is a multi-planar, two-plane version of the YUV 4:2:2 format. -The three components are separated into two sub-images or planes. -<constant>V4L2_PIX_FMT_NV16M</constant> differs from <constant>V4L2_PIX_FMT_NV16 -</constant> in that the two planes are non-contiguous in memory, i.e. the chroma -plane does not necessarily immediately follow the luma plane. -The luminance data occupies the first plane. The Y plane has one byte per pixel. -In the second plane there is chrominance data with alternating chroma samples. -The CbCr plane is the same width and height, in bytes, as the Y plane. -Each CbCr pair belongs to two pixels. For example, -Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to -Y'<subscript>00</subscript>, Y'<subscript>01</subscript>. -<constant>V4L2_PIX_FMT_NV61M</constant> is the same as <constant>V4L2_PIX_FMT_NV16M</constant> -except the Cb and Cr bytes are swapped, the CrCb plane starts with a Cr byte.</para> - - <para><constant>V4L2_PIX_FMT_NV16M</constant> and -<constant>V4L2_PIX_FMT_NV61M</constant> are intended to be used only in drivers -and applications that support the multi-planar API, described in -<xref linkend="planar-apis"/>. </para> - - <example> - <title><constant>V4L2_PIX_FMT_NV16M</constant> 4 × 4 pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start0 + 0:</entry> - <entry>Y'<subscript>00</subscript></entry> - <entry>Y'<subscript>01</subscript></entry> - <entry>Y'<subscript>02</subscript></entry> - <entry>Y'<subscript>03</subscript></entry> - </row> - <row> - <entry>start0 + 4:</entry> - <entry>Y'<subscript>10</subscript></entry> - <entry>Y'<subscript>11</subscript></entry> - <entry>Y'<subscript>12</subscript></entry> - <entry>Y'<subscript>13</subscript></entry> - </row> - <row> - <entry>start0 + 8:</entry> - <entry>Y'<subscript>20</subscript></entry> - <entry>Y'<subscript>21</subscript></entry> - <entry>Y'<subscript>22</subscript></entry> - <entry>Y'<subscript>23</subscript></entry> - </row> - <row> - <entry>start0 + 12:</entry> - <entry>Y'<subscript>30</subscript></entry> - <entry>Y'<subscript>31</subscript></entry> - <entry>Y'<subscript>32</subscript></entry> - <entry>Y'<subscript>33</subscript></entry> - </row> - <row> - <entry></entry> - </row> - <row> - <entry>start1 + 0:</entry> - <entry>Cb<subscript>00</subscript></entry> - <entry>Cr<subscript>00</subscript></entry> - <entry>Cb<subscript>02</subscript></entry> - <entry>Cr<subscript>02</subscript></entry> - </row> - <row> - <entry>start1 + 4:</entry> - <entry>Cb<subscript>10</subscript></entry> - <entry>Cr<subscript>10</subscript></entry> - <entry>Cb<subscript>12</subscript></entry> - <entry>Cr<subscript>12</subscript></entry> - </row> - <row> - <entry>start1 + 8:</entry> - <entry>Cb<subscript>20</subscript></entry> - <entry>Cr<subscript>20</subscript></entry> - <entry>Cb<subscript>22</subscript></entry> - <entry>Cr<subscript>22</subscript></entry> - </row> - <row> - <entry>start1 + 12:</entry> - <entry>Cb<subscript>30</subscript></entry> - <entry>Cr<subscript>30</subscript></entry> - <entry>Cb<subscript>32</subscript></entry> - <entry>Cr<subscript>32</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - - <formalpara> - <title>Color Sample Location.</title> - <para> - <informaltable frame="none"> - <tgroup cols="7" align="center"> - <tbody valign="top"> - <row> - <entry></entry> - <entry>0</entry><entry></entry><entry>1</entry><entry></entry> - <entry>2</entry><entry></entry><entry>3</entry> - </row> - <row> - <entry>0</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - <entry></entry><entry>C</entry><entry></entry><entry></entry> - <entry></entry><entry>C</entry><entry></entry> - </row> - <row> - <entry>1</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - <entry></entry><entry>C</entry><entry></entry><entry></entry> - <entry></entry><entry>C</entry><entry></entry> - </row> - <row> - <entry></entry> - </row> - <row> - <entry>2</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - <entry></entry><entry>C</entry><entry></entry><entry></entry> - <entry></entry><entry>C</entry><entry></entry> - </row> - <row> - <entry>3</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - <entry></entry><entry>C</entry><entry></entry><entry></entry> - <entry></entry><entry>C</entry><entry></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv24.xml b/Documentation/DocBook/media/v4l/pixfmt-nv24.xml deleted file mode 100644 index fb255f2ca9dd..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-nv24.xml +++ /dev/null @@ -1,121 +0,0 @@ - <refentry> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_NV24 ('NV24'), V4L2_PIX_FMT_NV42 ('NV42')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname id="V4L2-PIX-FMT-NV24"><constant>V4L2_PIX_FMT_NV24</constant></refname> - <refname id="V4L2-PIX-FMT-NV42"><constant>V4L2_PIX_FMT_NV42</constant></refname> - <refpurpose>Formats with full horizontal and vertical -chroma resolutions, also known as YUV 4:4:4. One luminance and one -chrominance plane with alternating chroma samples as opposed to -<constant>V4L2_PIX_FMT_YVU420</constant></refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>These are two-plane versions of the YUV 4:4:4 format. The three - components are separated into two sub-images or planes. The Y plane is - first, with each Y sample stored in one byte per pixel. For - <constant>V4L2_PIX_FMT_NV24</constant>, a combined CbCr plane - immediately follows the Y plane in memory. The CbCr plane has the same - width and height, in pixels, as the Y plane (and the image). Each line - contains one CbCr pair per pixel, with each Cb and Cr sample stored in - one byte. <constant>V4L2_PIX_FMT_NV42</constant> is the same except that - the Cb and Cr samples are swapped, the CrCb plane starts with a Cr - sample.</para> - - <para>If the Y plane has pad bytes after each row, then the CbCr plane - has twice as many pad bytes after its rows.</para> - - <example> - <title><constant>V4L2_PIX_FMT_NV24</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="9" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>Y'<subscript>00</subscript></entry> - <entry>Y'<subscript>01</subscript></entry> - <entry>Y'<subscript>02</subscript></entry> - <entry>Y'<subscript>03</subscript></entry> - </row> - <row> - <entry>start + 4:</entry> - <entry>Y'<subscript>10</subscript></entry> - <entry>Y'<subscript>11</subscript></entry> - <entry>Y'<subscript>12</subscript></entry> - <entry>Y'<subscript>13</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>Y'<subscript>20</subscript></entry> - <entry>Y'<subscript>21</subscript></entry> - <entry>Y'<subscript>22</subscript></entry> - <entry>Y'<subscript>23</subscript></entry> - </row> - <row> - <entry>start + 12:</entry> - <entry>Y'<subscript>30</subscript></entry> - <entry>Y'<subscript>31</subscript></entry> - <entry>Y'<subscript>32</subscript></entry> - <entry>Y'<subscript>33</subscript></entry> - </row> - <row> - <entry>start + 16:</entry> - <entry>Cb<subscript>00</subscript></entry> - <entry>Cr<subscript>00</subscript></entry> - <entry>Cb<subscript>01</subscript></entry> - <entry>Cr<subscript>01</subscript></entry> - <entry>Cb<subscript>02</subscript></entry> - <entry>Cr<subscript>02</subscript></entry> - <entry>Cb<subscript>03</subscript></entry> - <entry>Cr<subscript>03</subscript></entry> - </row> - <row> - <entry>start + 24:</entry> - <entry>Cb<subscript>10</subscript></entry> - <entry>Cr<subscript>10</subscript></entry> - <entry>Cb<subscript>11</subscript></entry> - <entry>Cr<subscript>11</subscript></entry> - <entry>Cb<subscript>12</subscript></entry> - <entry>Cr<subscript>12</subscript></entry> - <entry>Cb<subscript>13</subscript></entry> - <entry>Cr<subscript>13</subscript></entry> - </row> - <row> - <entry>start + 32:</entry> - <entry>Cb<subscript>20</subscript></entry> - <entry>Cr<subscript>20</subscript></entry> - <entry>Cb<subscript>21</subscript></entry> - <entry>Cr<subscript>21</subscript></entry> - <entry>Cb<subscript>22</subscript></entry> - <entry>Cr<subscript>22</subscript></entry> - <entry>Cb<subscript>23</subscript></entry> - <entry>Cr<subscript>23</subscript></entry> - </row> - <row> - <entry>start + 40:</entry> - <entry>Cb<subscript>30</subscript></entry> - <entry>Cr<subscript>30</subscript></entry> - <entry>Cb<subscript>31</subscript></entry> - <entry>Cr<subscript>31</subscript></entry> - <entry>Cb<subscript>32</subscript></entry> - <entry>Cr<subscript>32</subscript></entry> - <entry>Cb<subscript>33</subscript></entry> - <entry>Cr<subscript>33</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml b/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml deleted file mode 100644 index b60fb935b91b..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml +++ /dev/null @@ -1,937 +0,0 @@ -<refentry id="packed-rgb"> - <refmeta> - <refentrytitle>Packed RGB formats</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname>Packed RGB formats</refname> - <refpurpose>Packed RGB formats</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>These formats are designed to match the pixel formats of -typical PC graphics frame buffers. They occupy 8, 16, 24 or 32 bits -per pixel. These are all packed-pixel formats, meaning all the data -for a pixel lie next to each other in memory.</para> - - <table pgwide="1" frame="none" id="rgb-formats"> - <title>Packed RGB Image Formats</title> - <tgroup cols="37" align="center"> - <colspec colname="id" align="left" /> - <colspec colname="fourcc" /> - <colspec colname="bit" /> - - <colspec colnum="4" colname="b07" align="center" /> - <colspec colnum="5" colname="b06" align="center" /> - <colspec colnum="6" colname="b05" align="center" /> - <colspec colnum="7" colname="b04" align="center" /> - <colspec colnum="8" colname="b03" align="center" /> - <colspec colnum="9" colname="b02" align="center" /> - <colspec colnum="10" colname="b01" align="center" /> - <colspec colnum="11" colname="b00" align="center" /> - - <colspec colnum="13" colname="b17" align="center" /> - <colspec colnum="14" colname="b16" align="center" /> - <colspec colnum="15" colname="b15" align="center" /> - <colspec colnum="16" colname="b14" align="center" /> - <colspec colnum="17" colname="b13" align="center" /> - <colspec colnum="18" colname="b12" align="center" /> - <colspec colnum="19" colname="b11" align="center" /> - <colspec colnum="20" colname="b10" align="center" /> - - <colspec colnum="22" colname="b27" align="center" /> - <colspec colnum="23" colname="b26" align="center" /> - <colspec colnum="24" colname="b25" align="center" /> - <colspec colnum="25" colname="b24" align="center" /> - <colspec colnum="26" colname="b23" align="center" /> - <colspec colnum="27" colname="b22" align="center" /> - <colspec colnum="28" colname="b21" align="center" /> - <colspec colnum="29" colname="b20" align="center" /> - - <colspec colnum="31" colname="b37" align="center" /> - <colspec colnum="32" colname="b36" align="center" /> - <colspec colnum="33" colname="b35" align="center" /> - <colspec colnum="34" colname="b34" align="center" /> - <colspec colnum="35" colname="b33" align="center" /> - <colspec colnum="36" colname="b32" align="center" /> - <colspec colnum="37" colname="b31" align="center" /> - <colspec colnum="38" colname="b30" align="center" /> - - <spanspec namest="b07" nameend="b00" spanname="b0" /> - <spanspec namest="b17" nameend="b10" spanname="b1" /> - <spanspec namest="b27" nameend="b20" spanname="b2" /> - <spanspec namest="b37" nameend="b30" spanname="b3" /> - <thead> - <row> - <entry>Identifier</entry> - <entry>Code</entry> - <entry> </entry> - <entry spanname="b0">Byte 0 in memory</entry> - <entry spanname="b1">Byte 1</entry> - <entry spanname="b2">Byte 2</entry> - <entry spanname="b3">Byte 3</entry> - </row> - <row> - <entry> </entry> - <entry> </entry> - <entry>Bit</entry> - <entry>7</entry> - <entry>6</entry> - <entry>5</entry> - <entry>4</entry> - <entry>3</entry> - <entry>2</entry> - <entry>1</entry> - <entry>0</entry> - <entry> </entry> - <entry>7</entry> - <entry>6</entry> - <entry>5</entry> - <entry>4</entry> - <entry>3</entry> - <entry>2</entry> - <entry>1</entry> - <entry>0</entry> - <entry> </entry> - <entry>7</entry> - <entry>6</entry> - <entry>5</entry> - <entry>4</entry> - <entry>3</entry> - <entry>2</entry> - <entry>1</entry> - <entry>0</entry> - <entry> </entry> - <entry>7</entry> - <entry>6</entry> - <entry>5</entry> - <entry>4</entry> - <entry>3</entry> - <entry>2</entry> - <entry>1</entry> - <entry>0</entry> - </row> - </thead> - <tbody valign="top"> - <row id="V4L2-PIX-FMT-RGB332"> - <entry><constant>V4L2_PIX_FMT_RGB332</constant></entry> - <entry>'RGB1'</entry> - <entry></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row id="V4L2-PIX-FMT-ARGB444"> - <entry><constant>V4L2_PIX_FMT_ARGB444</constant></entry> - <entry>'AR12'</entry> - <entry></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry></entry> - <entry>a<subscript>3</subscript></entry> - <entry>a<subscript>2</subscript></entry> - <entry>a<subscript>1</subscript></entry> - <entry>a<subscript>0</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - </row> - <row id="V4L2-PIX-FMT-XRGB444"> - <entry><constant>V4L2_PIX_FMT_XRGB444</constant></entry> - <entry>'XR12'</entry> - <entry></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - </row> - <row id="V4L2-PIX-FMT-ARGB555"> - <entry><constant>V4L2_PIX_FMT_ARGB555</constant></entry> - <entry>'AR15'</entry> - <entry></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry></entry> - <entry>a</entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - </row> - <row id="V4L2-PIX-FMT-XRGB555"> - <entry><constant>V4L2_PIX_FMT_XRGB555</constant></entry> - <entry>'XR15'</entry> - <entry></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry></entry> - <entry>-</entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - </row> - <row id="V4L2-PIX-FMT-RGB565"> - <entry><constant>V4L2_PIX_FMT_RGB565</constant></entry> - <entry>'RGBP'</entry> - <entry></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - </row> - <row id="V4L2-PIX-FMT-ARGB555X"> - <entry><constant>V4L2_PIX_FMT_ARGB555X</constant></entry> - <entry>'AR15' | (1 << 31)</entry> - <entry></entry> - <entry>a</entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row id="V4L2-PIX-FMT-XRGB555X"> - <entry><constant>V4L2_PIX_FMT_XRGB555X</constant></entry> - <entry>'XR15' | (1 << 31)</entry> - <entry></entry> - <entry>-</entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row id="V4L2-PIX-FMT-RGB565X"> - <entry><constant>V4L2_PIX_FMT_RGB565X</constant></entry> - <entry>'RGBR'</entry> - <entry></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row id="V4L2-PIX-FMT-BGR24"> - <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry> - <entry>'BGR3'</entry> - <entry></entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry></entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry></entry> - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - </row> - <row id="V4L2-PIX-FMT-RGB24"> - <entry><constant>V4L2_PIX_FMT_RGB24</constant></entry> - <entry>'RGB3'</entry> - <entry></entry> - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry></entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry></entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row id="V4L2-PIX-FMT-BGR666"> - <entry><constant>V4L2_PIX_FMT_BGR666</constant></entry> - <entry>'BGRH'</entry> - <entry></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - </row> - <row id="V4L2-PIX-FMT-ABGR32"> - <entry><constant>V4L2_PIX_FMT_ABGR32</constant></entry> - <entry>'AR24'</entry> - <entry></entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry></entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry></entry> - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry></entry> - <entry>a<subscript>7</subscript></entry> - <entry>a<subscript>6</subscript></entry> - <entry>a<subscript>5</subscript></entry> - <entry>a<subscript>4</subscript></entry> - <entry>a<subscript>3</subscript></entry> - <entry>a<subscript>2</subscript></entry> - <entry>a<subscript>1</subscript></entry> - <entry>a<subscript>0</subscript></entry> - </row> - <row id="V4L2-PIX-FMT-XBGR32"> - <entry><constant>V4L2_PIX_FMT_XBGR32</constant></entry> - <entry>'XR24'</entry> - <entry></entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry></entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry></entry> - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - </row> - <row id="V4L2-PIX-FMT-ARGB32"> - <entry><constant>V4L2_PIX_FMT_ARGB32</constant></entry> - <entry>'BA24'</entry> - <entry></entry> - <entry>a<subscript>7</subscript></entry> - <entry>a<subscript>6</subscript></entry> - <entry>a<subscript>5</subscript></entry> - <entry>a<subscript>4</subscript></entry> - <entry>a<subscript>3</subscript></entry> - <entry>a<subscript>2</subscript></entry> - <entry>a<subscript>1</subscript></entry> - <entry>a<subscript>0</subscript></entry> - <entry></entry> - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry></entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry></entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row id="V4L2-PIX-FMT-XRGB32"> - <entry><constant>V4L2_PIX_FMT_XRGB32</constant></entry> - <entry>'BX24'</entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry></entry> - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry></entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry></entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - </tbody> - </tgroup> - </table> - - <para>Bit 7 is the most significant bit.</para> - - <para>The usage and value of the alpha bits (a) in the ARGB and ABGR formats - (collectively referred to as alpha formats) depend on the device type and - hardware operation. <link linkend="capture">Capture</link> devices - (including capture queues of mem-to-mem devices) fill the alpha component in - memory. When the device outputs an alpha channel the alpha component will - have a meaningful value. Otherwise, when the device doesn't output an alpha - channel but can set the alpha bit to a user-configurable value, the <link - linkend="v4l2-alpha-component"><constant>V4L2_CID_ALPHA_COMPONENT</constant> - </link> control is used to specify that alpha value, and the alpha component - of all pixels will be set to the value specified by that control. Otherwise - a corresponding format without an alpha component (XRGB or XBGR) must be - used instead of an alpha format.</para> - - <para><link linkend="output">Output</link> devices (including output queues - of mem-to-mem devices and <link linkend="osd">video output overlay</link> - devices) read the alpha component from memory. When the device processes the - alpha channel the alpha component must be filled with meaningful values by - applications. Otherwise a corresponding format without an alpha component - (XRGB or XBGR) must be used instead of an alpha format.</para> - - <para>The XRGB and XBGR formats contain undefined bits (-). Applications, - devices and drivers must ignore those bits, for both <link - linkend="capture">capture</link> and <link linkend="output">output</link> - devices.</para> - - <example> - <title><constant>V4L2_PIX_FMT_BGR24</constant> 4 × 4 pixel -image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="13" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>B<subscript>00</subscript></entry> - <entry>G<subscript>00</subscript></entry> - <entry>R<subscript>00</subscript></entry> - <entry>B<subscript>01</subscript></entry> - <entry>G<subscript>01</subscript></entry> - <entry>R<subscript>01</subscript></entry> - <entry>B<subscript>02</subscript></entry> - <entry>G<subscript>02</subscript></entry> - <entry>R<subscript>02</subscript></entry> - <entry>B<subscript>03</subscript></entry> - <entry>G<subscript>03</subscript></entry> - <entry>R<subscript>03</subscript></entry> - </row> - <row> - <entry>start + 12:</entry> - <entry>B<subscript>10</subscript></entry> - <entry>G<subscript>10</subscript></entry> - <entry>R<subscript>10</subscript></entry> - <entry>B<subscript>11</subscript></entry> - <entry>G<subscript>11</subscript></entry> - <entry>R<subscript>11</subscript></entry> - <entry>B<subscript>12</subscript></entry> - <entry>G<subscript>12</subscript></entry> - <entry>R<subscript>12</subscript></entry> - <entry>B<subscript>13</subscript></entry> - <entry>G<subscript>13</subscript></entry> - <entry>R<subscript>13</subscript></entry> - </row> - <row> - <entry>start + 24:</entry> - <entry>B<subscript>20</subscript></entry> - <entry>G<subscript>20</subscript></entry> - <entry>R<subscript>20</subscript></entry> - <entry>B<subscript>21</subscript></entry> - <entry>G<subscript>21</subscript></entry> - <entry>R<subscript>21</subscript></entry> - <entry>B<subscript>22</subscript></entry> - <entry>G<subscript>22</subscript></entry> - <entry>R<subscript>22</subscript></entry> - <entry>B<subscript>23</subscript></entry> - <entry>G<subscript>23</subscript></entry> - <entry>R<subscript>23</subscript></entry> - </row> - <row> - <entry>start + 36:</entry> - <entry>B<subscript>30</subscript></entry> - <entry>G<subscript>30</subscript></entry> - <entry>R<subscript>30</subscript></entry> - <entry>B<subscript>31</subscript></entry> - <entry>G<subscript>31</subscript></entry> - <entry>R<subscript>31</subscript></entry> - <entry>B<subscript>32</subscript></entry> - <entry>G<subscript>32</subscript></entry> - <entry>R<subscript>32</subscript></entry> - <entry>B<subscript>33</subscript></entry> - <entry>G<subscript>33</subscript></entry> - <entry>R<subscript>33</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - - <para>Formats defined in <xref linkend="rgb-formats-deprecated"/> are - deprecated and must not be used by new drivers. They are documented here for - reference. The meaning of their alpha bits (a) is ill-defined and - interpreted as in either the corresponding ARGB or XRGB format, depending on - the driver.</para> - - <table pgwide="1" frame="none" id="rgb-formats-deprecated"> - <title>Deprecated Packed RGB Image Formats</title> - <tgroup cols="37" align="center"> - <colspec colname="id" align="left" /> - <colspec colname="fourcc" /> - <colspec colname="bit" /> - - <colspec colnum="4" colname="b07" align="center" /> - <colspec colnum="5" colname="b06" align="center" /> - <colspec colnum="6" colname="b05" align="center" /> - <colspec colnum="7" colname="b04" align="center" /> - <colspec colnum="8" colname="b03" align="center" /> - <colspec colnum="9" colname="b02" align="center" /> - <colspec colnum="10" colname="b01" align="center" /> - <colspec colnum="11" colname="b00" align="center" /> - - <colspec colnum="13" colname="b17" align="center" /> - <colspec colnum="14" colname="b16" align="center" /> - <colspec colnum="15" colname="b15" align="center" /> - <colspec colnum="16" colname="b14" align="center" /> - <colspec colnum="17" colname="b13" align="center" /> - <colspec colnum="18" colname="b12" align="center" /> - <colspec colnum="19" colname="b11" align="center" /> - <colspec colnum="20" colname="b10" align="center" /> - - <colspec colnum="22" colname="b27" align="center" /> - <colspec colnum="23" colname="b26" align="center" /> - <colspec colnum="24" colname="b25" align="center" /> - <colspec colnum="25" colname="b24" align="center" /> - <colspec colnum="26" colname="b23" align="center" /> - <colspec colnum="27" colname="b22" align="center" /> - <colspec colnum="28" colname="b21" align="center" /> - <colspec colnum="29" colname="b20" align="center" /> - - <colspec colnum="31" colname="b37" align="center" /> - <colspec colnum="32" colname="b36" align="center" /> - <colspec colnum="33" colname="b35" align="center" /> - <colspec colnum="34" colname="b34" align="center" /> - <colspec colnum="35" colname="b33" align="center" /> - <colspec colnum="36" colname="b32" align="center" /> - <colspec colnum="37" colname="b31" align="center" /> - <colspec colnum="38" colname="b30" align="center" /> - - <spanspec namest="b07" nameend="b00" spanname="b0" /> - <spanspec namest="b17" nameend="b10" spanname="b1" /> - <spanspec namest="b27" nameend="b20" spanname="b2" /> - <spanspec namest="b37" nameend="b30" spanname="b3" /> - <thead> - <row> - <entry>Identifier</entry> - <entry>Code</entry> - <entry> </entry> - <entry spanname="b0">Byte 0 in memory</entry> - <entry spanname="b1">Byte 1</entry> - <entry spanname="b2">Byte 2</entry> - <entry spanname="b3">Byte 3</entry> - </row> - <row> - <entry> </entry> - <entry> </entry> - <entry>Bit</entry> - <entry>7</entry> - <entry>6</entry> - <entry>5</entry> - <entry>4</entry> - <entry>3</entry> - <entry>2</entry> - <entry>1</entry> - <entry>0</entry> - <entry> </entry> - <entry>7</entry> - <entry>6</entry> - <entry>5</entry> - <entry>4</entry> - <entry>3</entry> - <entry>2</entry> - <entry>1</entry> - <entry>0</entry> - <entry> </entry> - <entry>7</entry> - <entry>6</entry> - <entry>5</entry> - <entry>4</entry> - <entry>3</entry> - <entry>2</entry> - <entry>1</entry> - <entry>0</entry> - <entry> </entry> - <entry>7</entry> - <entry>6</entry> - <entry>5</entry> - <entry>4</entry> - <entry>3</entry> - <entry>2</entry> - <entry>1</entry> - <entry>0</entry> - </row> - </thead> - <tbody> - <row id="V4L2-PIX-FMT-RGB444"> - <entry><constant>V4L2_PIX_FMT_RGB444</constant></entry> - <entry>'R444'</entry> - <entry></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry></entry> - <entry>a<subscript>3</subscript></entry> - <entry>a<subscript>2</subscript></entry> - <entry>a<subscript>1</subscript></entry> - <entry>a<subscript>0</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - </row> - <row id="V4L2-PIX-FMT-RGB555"> - <entry><constant>V4L2_PIX_FMT_RGB555</constant></entry> - <entry>'RGBO'</entry> - <entry></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry></entry> - <entry>a</entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - </row> - <row id="V4L2-PIX-FMT-RGB555X"> - <entry><constant>V4L2_PIX_FMT_RGB555X</constant></entry> - <entry>'RGBQ'</entry> - <entry></entry> - <entry>a</entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row id="V4L2-PIX-FMT-BGR32"> - <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry> - <entry>'BGR4'</entry> - <entry></entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry></entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry></entry> - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry></entry> - <entry>a<subscript>7</subscript></entry> - <entry>a<subscript>6</subscript></entry> - <entry>a<subscript>5</subscript></entry> - <entry>a<subscript>4</subscript></entry> - <entry>a<subscript>3</subscript></entry> - <entry>a<subscript>2</subscript></entry> - <entry>a<subscript>1</subscript></entry> - <entry>a<subscript>0</subscript></entry> - </row> - <row id="V4L2-PIX-FMT-RGB32"> - <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry> - <entry>'RGB4'</entry> - <entry></entry> - <entry>a<subscript>7</subscript></entry> - <entry>a<subscript>6</subscript></entry> - <entry>a<subscript>5</subscript></entry> - <entry>a<subscript>4</subscript></entry> - <entry>a<subscript>3</subscript></entry> - <entry>a<subscript>2</subscript></entry> - <entry>a<subscript>1</subscript></entry> - <entry>a<subscript>0</subscript></entry> - <entry></entry> - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry></entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry></entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - </tbody> - </tgroup> - </table> - - <para>A test utility to determine which RGB formats a driver -actually supports is available from the LinuxTV v4l-dvb repository. -See &v4l-dvb; for access instructions.</para> - - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-packed-yuv.xml b/Documentation/DocBook/media/v4l/pixfmt-packed-yuv.xml deleted file mode 100644 index 33fa5a47a865..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-packed-yuv.xml +++ /dev/null @@ -1,236 +0,0 @@ -<refentry id="packed-yuv"> - <refmeta> - <refentrytitle>Packed YUV formats</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname>Packed YUV formats</refname> - <refpurpose>Packed YUV formats</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>Similar to the packed RGB formats these formats store -the Y, Cb and Cr component of each pixel in one 16 or 32 bit -word.</para> - - <table pgwide="1" frame="none"> - <title>Packed YUV Image Formats</title> - <tgroup cols="37" align="center"> - <colspec colname="id" align="left" /> - <colspec colname="fourcc" /> - <colspec colname="bit" /> - - <colspec colnum="4" colname="b07" align="center" /> - <colspec colnum="5" colname="b06" align="center" /> - <colspec colnum="6" colname="b05" align="center" /> - <colspec colnum="7" colname="b04" align="center" /> - <colspec colnum="8" colname="b03" align="center" /> - <colspec colnum="9" colname="b02" align="center" /> - <colspec colnum="10" colname="b01" align="center" /> - <colspec colnum="11" colname="b00" align="center" /> - - <colspec colnum="13" colname="b17" align="center" /> - <colspec colnum="14" colname="b16" align="center" /> - <colspec colnum="15" colname="b15" align="center" /> - <colspec colnum="16" colname="b14" align="center" /> - <colspec colnum="17" colname="b13" align="center" /> - <colspec colnum="18" colname="b12" align="center" /> - <colspec colnum="19" colname="b11" align="center" /> - <colspec colnum="20" colname="b10" align="center" /> - - <colspec colnum="22" colname="b27" align="center" /> - <colspec colnum="23" colname="b26" align="center" /> - <colspec colnum="24" colname="b25" align="center" /> - <colspec colnum="25" colname="b24" align="center" /> - <colspec colnum="26" colname="b23" align="center" /> - <colspec colnum="27" colname="b22" align="center" /> - <colspec colnum="28" colname="b21" align="center" /> - <colspec colnum="29" colname="b20" align="center" /> - - <colspec colnum="31" colname="b37" align="center" /> - <colspec colnum="32" colname="b36" align="center" /> - <colspec colnum="33" colname="b35" align="center" /> - <colspec colnum="34" colname="b34" align="center" /> - <colspec colnum="35" colname="b33" align="center" /> - <colspec colnum="36" colname="b32" align="center" /> - <colspec colnum="37" colname="b31" align="center" /> - <colspec colnum="38" colname="b30" align="center" /> - - <spanspec namest="b07" nameend="b00" spanname="b0" /> - <spanspec namest="b17" nameend="b10" spanname="b1" /> - <spanspec namest="b27" nameend="b20" spanname="b2" /> - <spanspec namest="b37" nameend="b30" spanname="b3" /> - <thead> - <row> - <entry>Identifier</entry> - <entry>Code</entry> - <entry> </entry> - <entry spanname="b0">Byte 0 in memory</entry> - <entry spanname="b1">Byte 1</entry> - <entry spanname="b2">Byte 2</entry> - <entry spanname="b3">Byte 3</entry> - </row> - <row> - <entry> </entry> - <entry> </entry> - <entry>Bit</entry> - <entry>7</entry> - <entry>6</entry> - <entry>5</entry> - <entry>4</entry> - <entry>3</entry> - <entry>2</entry> - <entry>1</entry> - <entry>0</entry> - <entry> </entry> - <entry>7</entry> - <entry>6</entry> - <entry>5</entry> - <entry>4</entry> - <entry>3</entry> - <entry>2</entry> - <entry>1</entry> - <entry>0</entry> - <entry> </entry> - <entry>7</entry> - <entry>6</entry> - <entry>5</entry> - <entry>4</entry> - <entry>3</entry> - <entry>2</entry> - <entry>1</entry> - <entry>0</entry> - <entry> </entry> - <entry>7</entry> - <entry>6</entry> - <entry>5</entry> - <entry>4</entry> - <entry>3</entry> - <entry>2</entry> - <entry>1</entry> - <entry>0</entry> - </row> - </thead> - <tbody valign="top"> - <row id="V4L2-PIX-FMT-YUV444"> - <entry><constant>V4L2_PIX_FMT_YUV444</constant></entry> - <entry>'Y444'</entry> - <entry></entry> - <entry>Cb<subscript>3</subscript></entry> - <entry>Cb<subscript>2</subscript></entry> - <entry>Cb<subscript>1</subscript></entry> - <entry>Cb<subscript>0</subscript></entry> - <entry>Cr<subscript>3</subscript></entry> - <entry>Cr<subscript>2</subscript></entry> - <entry>Cr<subscript>1</subscript></entry> - <entry>Cr<subscript>0</subscript></entry> - <entry></entry> - <entry>a<subscript>3</subscript></entry> - <entry>a<subscript>2</subscript></entry> - <entry>a<subscript>1</subscript></entry> - <entry>a<subscript>0</subscript></entry> - <entry>Y'<subscript>3</subscript></entry> - <entry>Y'<subscript>2</subscript></entry> - <entry>Y'<subscript>1</subscript></entry> - <entry>Y'<subscript>0</subscript></entry> - </row> - - <row id="V4L2-PIX-FMT-YUV555"> - <entry><constant>V4L2_PIX_FMT_YUV555</constant></entry> - <entry>'YUVO'</entry> - <entry></entry> - <entry>Cb<subscript>2</subscript></entry> - <entry>Cb<subscript>1</subscript></entry> - <entry>Cb<subscript>0</subscript></entry> - <entry>Cr<subscript>4</subscript></entry> - <entry>Cr<subscript>3</subscript></entry> - <entry>Cr<subscript>2</subscript></entry> - <entry>Cr<subscript>1</subscript></entry> - <entry>Cr<subscript>0</subscript></entry> - <entry></entry> - <entry>a</entry> - <entry>Y'<subscript>4</subscript></entry> - <entry>Y'<subscript>3</subscript></entry> - <entry>Y'<subscript>2</subscript></entry> - <entry>Y'<subscript>1</subscript></entry> - <entry>Y'<subscript>0</subscript></entry> - <entry>Cb<subscript>4</subscript></entry> - <entry>Cb<subscript>3</subscript></entry> - </row> - - <row id="V4L2-PIX-FMT-YUV565"> - <entry><constant>V4L2_PIX_FMT_YUV565</constant></entry> - <entry>'YUVP'</entry> - <entry></entry> - <entry>Cb<subscript>2</subscript></entry> - <entry>Cb<subscript>1</subscript></entry> - <entry>Cb<subscript>0</subscript></entry> - <entry>Cr<subscript>4</subscript></entry> - <entry>Cr<subscript>3</subscript></entry> - <entry>Cr<subscript>2</subscript></entry> - <entry>Cr<subscript>1</subscript></entry> - <entry>Cr<subscript>0</subscript></entry> - <entry></entry> - <entry>Y'<subscript>4</subscript></entry> - <entry>Y'<subscript>3</subscript></entry> - <entry>Y'<subscript>2</subscript></entry> - <entry>Y'<subscript>1</subscript></entry> - <entry>Y'<subscript>0</subscript></entry> - <entry>Cb<subscript>5</subscript></entry> - <entry>Cb<subscript>4</subscript></entry> - <entry>Cb<subscript>3</subscript></entry> - </row> - - <row id="V4L2-PIX-FMT-YUV32"> - <entry><constant>V4L2_PIX_FMT_YUV32</constant></entry> - <entry>'YUV4'</entry> - <entry></entry> - <entry>a<subscript>7</subscript></entry> - <entry>a<subscript>6</subscript></entry> - <entry>a<subscript>5</subscript></entry> - <entry>a<subscript>4</subscript></entry> - <entry>a<subscript>3</subscript></entry> - <entry>a<subscript>2</subscript></entry> - <entry>a<subscript>1</subscript></entry> - <entry>a<subscript>0</subscript></entry> - <entry></entry> - <entry>Y'<subscript>7</subscript></entry> - <entry>Y'<subscript>6</subscript></entry> - <entry>Y'<subscript>5</subscript></entry> - <entry>Y'<subscript>4</subscript></entry> - <entry>Y'<subscript>3</subscript></entry> - <entry>Y'<subscript>2</subscript></entry> - <entry>Y'<subscript>1</subscript></entry> - <entry>Y'<subscript>0</subscript></entry> - <entry></entry> - <entry>Cb<subscript>7</subscript></entry> - <entry>Cb<subscript>6</subscript></entry> - <entry>Cb<subscript>5</subscript></entry> - <entry>Cb<subscript>4</subscript></entry> - <entry>Cb<subscript>3</subscript></entry> - <entry>Cb<subscript>2</subscript></entry> - <entry>Cb<subscript>1</subscript></entry> - <entry>Cb<subscript>0</subscript></entry> - <entry></entry> - <entry>Cr<subscript>7</subscript></entry> - <entry>Cr<subscript>6</subscript></entry> - <entry>Cr<subscript>5</subscript></entry> - <entry>Cr<subscript>4</subscript></entry> - <entry>Cr<subscript>3</subscript></entry> - <entry>Cr<subscript>2</subscript></entry> - <entry>Cr<subscript>1</subscript></entry> - <entry>Cr<subscript>0</subscript></entry> - </row> - </tbody> - </tgroup> - </table> - - <para>Bit 7 is the most significant bit. The value of a = alpha -bits is undefined when reading from the driver, ignored when writing -to the driver, except when alpha blending has been negotiated for a -<link linkend="overlay">Video Overlay</link> or <link -linkend="osd">Video Output Overlay</link>.</para> - - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-sbggr16.xml b/Documentation/DocBook/media/v4l/pixfmt-sbggr16.xml deleted file mode 100644 index 6494b05d84a1..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-sbggr16.xml +++ /dev/null @@ -1,83 +0,0 @@ -<refentry id="V4L2-PIX-FMT-SBGGR16"> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_SBGGR16 ('BYR2')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname><constant>V4L2_PIX_FMT_SBGGR16</constant></refname> - <refpurpose>Bayer RGB format</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>This format is similar to <link -linkend="V4L2-PIX-FMT-SBGGR8"> -<constant>V4L2_PIX_FMT_SBGGR8</constant></link>, except each pixel has -a depth of 16 bits. The least significant byte is stored at lower -memory addresses (little-endian). Note the actual sampling precision -may be lower than 16 bits, for example 10 bits per pixel with values -in range 0 to 1023.</para> - - <example> - <title><constant>V4L2_PIX_FMT_SBGGR16</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>B<subscript>00low</subscript></entry> - <entry>B<subscript>00high</subscript></entry> - <entry>G<subscript>01low</subscript></entry> - <entry>G<subscript>01high</subscript></entry> - <entry>B<subscript>02low</subscript></entry> - <entry>B<subscript>02high</subscript></entry> - <entry>G<subscript>03low</subscript></entry> - <entry>G<subscript>03high</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>G<subscript>10low</subscript></entry> - <entry>G<subscript>10high</subscript></entry> - <entry>R<subscript>11low</subscript></entry> - <entry>R<subscript>11high</subscript></entry> - <entry>G<subscript>12low</subscript></entry> - <entry>G<subscript>12high</subscript></entry> - <entry>R<subscript>13low</subscript></entry> - <entry>R<subscript>13high</subscript></entry> - </row> - <row> - <entry>start + 16:</entry> - <entry>B<subscript>20low</subscript></entry> - <entry>B<subscript>20high</subscript></entry> - <entry>G<subscript>21low</subscript></entry> - <entry>G<subscript>21high</subscript></entry> - <entry>B<subscript>22low</subscript></entry> - <entry>B<subscript>22high</subscript></entry> - <entry>G<subscript>23low</subscript></entry> - <entry>G<subscript>23high</subscript></entry> - </row> - <row> - <entry>start + 24:</entry> - <entry>G<subscript>30low</subscript></entry> - <entry>G<subscript>30high</subscript></entry> - <entry>R<subscript>31low</subscript></entry> - <entry>R<subscript>31high</subscript></entry> - <entry>G<subscript>32low</subscript></entry> - <entry>G<subscript>32high</subscript></entry> - <entry>R<subscript>33low</subscript></entry> - <entry>R<subscript>33high</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-sbggr8.xml b/Documentation/DocBook/media/v4l/pixfmt-sbggr8.xml deleted file mode 100644 index 5eaf2b42d3f7..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-sbggr8.xml +++ /dev/null @@ -1,67 +0,0 @@ - <refentry id="V4L2-PIX-FMT-SBGGR8"> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_SBGGR8 ('BA81')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname><constant>V4L2_PIX_FMT_SBGGR8</constant></refname> - <refpurpose>Bayer RGB format</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>This is commonly the native format of digital cameras, -reflecting the arrangement of sensors on the CCD device. Only one red, -green or blue value is given for each pixel. Missing components must -be interpolated from neighbouring pixels. From left to right the first -row consists of a blue and green value, the second row of a green and -red value. This scheme repeats to the right and down for every two -columns and rows.</para> - - <example> - <title><constant>V4L2_PIX_FMT_SBGGR8</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>B<subscript>00</subscript></entry> - <entry>G<subscript>01</subscript></entry> - <entry>B<subscript>02</subscript></entry> - <entry>G<subscript>03</subscript></entry> - </row> - <row> - <entry>start + 4:</entry> - <entry>G<subscript>10</subscript></entry> - <entry>R<subscript>11</subscript></entry> - <entry>G<subscript>12</subscript></entry> - <entry>R<subscript>13</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>B<subscript>20</subscript></entry> - <entry>G<subscript>21</subscript></entry> - <entry>B<subscript>22</subscript></entry> - <entry>G<subscript>23</subscript></entry> - </row> - <row> - <entry>start + 12:</entry> - <entry>G<subscript>30</subscript></entry> - <entry>R<subscript>31</subscript></entry> - <entry>G<subscript>32</subscript></entry> - <entry>R<subscript>33</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-sdr-cs08.xml b/Documentation/DocBook/media/v4l/pixfmt-sdr-cs08.xml deleted file mode 100644 index 6118d8f7a20c..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-sdr-cs08.xml +++ /dev/null @@ -1,44 +0,0 @@ -<refentry id="V4L2-SDR-FMT-CS08"> - <refmeta> - <refentrytitle>V4L2_SDR_FMT_CS8 ('CS08')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname> - <constant>V4L2_SDR_FMT_CS8</constant> - </refname> - <refpurpose>Complex signed 8-bit IQ sample</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <para> -This format contains sequence of complex number samples. Each complex number -consist two parts, called In-phase and Quadrature (IQ). Both I and Q are -represented as a 8 bit signed number. I value comes first and Q value after -that. - </para> - <example> - <title><constant>V4L2_SDR_FMT_CS8</constant> 1 sample</title> - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="2" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>I'<subscript>0</subscript></entry> - </row> - <row> - <entry>start + 1:</entry> - <entry>Q'<subscript>0</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-sdr-cs14le.xml b/Documentation/DocBook/media/v4l/pixfmt-sdr-cs14le.xml deleted file mode 100644 index e4b494ce1369..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-sdr-cs14le.xml +++ /dev/null @@ -1,47 +0,0 @@ -<refentry id="V4L2-SDR-FMT-CS14LE"> - <refmeta> - <refentrytitle>V4L2_SDR_FMT_CS14LE ('CS14')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname> - <constant>V4L2_SDR_FMT_CS14LE</constant> - </refname> - <refpurpose>Complex signed 14-bit little endian IQ sample</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <para> -This format contains sequence of complex number samples. Each complex number -consist two parts, called In-phase and Quadrature (IQ). Both I and Q are -represented as a 14 bit signed little endian number. I value comes first -and Q value after that. 14 bit value is stored in 16 bit space with unused -high bits padded with 0. - </para> - <example> - <title><constant>V4L2_SDR_FMT_CS14LE</constant> 1 sample</title> - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="3" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>I'<subscript>0[7:0]</subscript></entry> - <entry>I'<subscript>0[13:8]</subscript></entry> - </row> - <row> - <entry>start + 2:</entry> - <entry>Q'<subscript>0[7:0]</subscript></entry> - <entry>Q'<subscript>0[13:8]</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-sdr-cu08.xml b/Documentation/DocBook/media/v4l/pixfmt-sdr-cu08.xml deleted file mode 100644 index 2d80104c178b..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-sdr-cu08.xml +++ /dev/null @@ -1,44 +0,0 @@ -<refentry id="V4L2-SDR-FMT-CU08"> - <refmeta> - <refentrytitle>V4L2_SDR_FMT_CU8 ('CU08')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname> - <constant>V4L2_SDR_FMT_CU8</constant> - </refname> - <refpurpose>Complex unsigned 8-bit IQ sample</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <para> -This format contains sequence of complex number samples. Each complex number -consist two parts, called In-phase and Quadrature (IQ). Both I and Q are -represented as a 8 bit unsigned number. I value comes first and Q value after -that. - </para> - <example> - <title><constant>V4L2_SDR_FMT_CU8</constant> 1 sample</title> - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="2" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>I'<subscript>0</subscript></entry> - </row> - <row> - <entry>start + 1:</entry> - <entry>Q'<subscript>0</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-sdr-cu16le.xml b/Documentation/DocBook/media/v4l/pixfmt-sdr-cu16le.xml deleted file mode 100644 index 26288ffa9071..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-sdr-cu16le.xml +++ /dev/null @@ -1,46 +0,0 @@ -<refentry id="V4L2-SDR-FMT-CU16LE"> - <refmeta> - <refentrytitle>V4L2_SDR_FMT_CU16LE ('CU16')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname> - <constant>V4L2_SDR_FMT_CU16LE</constant> - </refname> - <refpurpose>Complex unsigned 16-bit little endian IQ sample</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <para> -This format contains sequence of complex number samples. Each complex number -consist two parts, called In-phase and Quadrature (IQ). Both I and Q are -represented as a 16 bit unsigned little endian number. I value comes first -and Q value after that. - </para> - <example> - <title><constant>V4L2_SDR_FMT_CU16LE</constant> 1 sample</title> - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="3" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>I'<subscript>0[7:0]</subscript></entry> - <entry>I'<subscript>0[15:8]</subscript></entry> - </row> - <row> - <entry>start + 2:</entry> - <entry>Q'<subscript>0[7:0]</subscript></entry> - <entry>Q'<subscript>0[15:8]</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-sdr-ru12le.xml b/Documentation/DocBook/media/v4l/pixfmt-sdr-ru12le.xml deleted file mode 100644 index 3df076b99f94..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-sdr-ru12le.xml +++ /dev/null @@ -1,40 +0,0 @@ -<refentry id="V4L2-SDR-FMT-RU12LE"> - <refmeta> - <refentrytitle>V4L2_SDR_FMT_RU12LE ('RU12')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname> - <constant>V4L2_SDR_FMT_RU12LE</constant> - </refname> - <refpurpose>Real unsigned 12-bit little endian sample</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <para> -This format contains sequence of real number samples. Each sample is -represented as a 12 bit unsigned little endian number. Sample is stored -in 16 bit space with unused high bits padded with 0. - </para> - <example> - <title><constant>V4L2_SDR_FMT_RU12LE</constant> 1 sample</title> - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="3" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>I'<subscript>0[7:0]</subscript></entry> - <entry>I'<subscript>0[11:8]</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-sgbrg8.xml b/Documentation/DocBook/media/v4l/pixfmt-sgbrg8.xml deleted file mode 100644 index fee65dca79c5..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-sgbrg8.xml +++ /dev/null @@ -1,67 +0,0 @@ - <refentry id="V4L2-PIX-FMT-SGBRG8"> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_SGBRG8 ('GBRG')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname><constant>V4L2_PIX_FMT_SGBRG8</constant></refname> - <refpurpose>Bayer RGB format</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>This is commonly the native format of digital cameras, -reflecting the arrangement of sensors on the CCD device. Only one red, -green or blue value is given for each pixel. Missing components must -be interpolated from neighbouring pixels. From left to right the first -row consists of a green and blue value, the second row of a red and -green value. This scheme repeats to the right and down for every two -columns and rows.</para> - - <example> - <title><constant>V4L2_PIX_FMT_SGBRG8</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>G<subscript>00</subscript></entry> - <entry>B<subscript>01</subscript></entry> - <entry>G<subscript>02</subscript></entry> - <entry>B<subscript>03</subscript></entry> - </row> - <row> - <entry>start + 4:</entry> - <entry>R<subscript>10</subscript></entry> - <entry>G<subscript>11</subscript></entry> - <entry>R<subscript>12</subscript></entry> - <entry>G<subscript>13</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>G<subscript>20</subscript></entry> - <entry>B<subscript>21</subscript></entry> - <entry>G<subscript>22</subscript></entry> - <entry>B<subscript>23</subscript></entry> - </row> - <row> - <entry>start + 12:</entry> - <entry>R<subscript>30</subscript></entry> - <entry>G<subscript>31</subscript></entry> - <entry>R<subscript>32</subscript></entry> - <entry>G<subscript>33</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-sgrbg8.xml b/Documentation/DocBook/media/v4l/pixfmt-sgrbg8.xml deleted file mode 100644 index 7803b8c41b45..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-sgrbg8.xml +++ /dev/null @@ -1,67 +0,0 @@ - <refentry id="V4L2-PIX-FMT-SGRBG8"> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_SGRBG8 ('GRBG')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname><constant>V4L2_PIX_FMT_SGRBG8</constant></refname> - <refpurpose>Bayer RGB format</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>This is commonly the native format of digital cameras, -reflecting the arrangement of sensors on the CCD device. Only one red, -green or blue value is given for each pixel. Missing components must -be interpolated from neighbouring pixels. From left to right the first -row consists of a green and blue value, the second row of a red and -green value. This scheme repeats to the right and down for every two -columns and rows.</para> - - <example> - <title><constant>V4L2_PIX_FMT_SGRBG8</constant> 4 × -4 pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>G<subscript>00</subscript></entry> - <entry>R<subscript>01</subscript></entry> - <entry>G<subscript>02</subscript></entry> - <entry>R<subscript>03</subscript></entry> - </row> - <row> - <entry>start + 4:</entry> - <entry>B<subscript>10</subscript></entry> - <entry>G<subscript>11</subscript></entry> - <entry>B<subscript>12</subscript></entry> - <entry>G<subscript>13</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>G<subscript>20</subscript></entry> - <entry>R<subscript>21</subscript></entry> - <entry>G<subscript>22</subscript></entry> - <entry>R<subscript>23</subscript></entry> - </row> - <row> - <entry>start + 12:</entry> - <entry>B<subscript>30</subscript></entry> - <entry>G<subscript>31</subscript></entry> - <entry>B<subscript>32</subscript></entry> - <entry>G<subscript>33</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-srggb10.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb10.xml deleted file mode 100644 index f34d03ebda3a..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-srggb10.xml +++ /dev/null @@ -1,90 +0,0 @@ - <refentry id="pixfmt-srggb10"> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_SRGGB10 ('RG10'), - V4L2_PIX_FMT_SGRBG10 ('BA10'), - V4L2_PIX_FMT_SGBRG10 ('GB10'), - V4L2_PIX_FMT_SBGGR10 ('BG10'), - </refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname id="V4L2-PIX-FMT-SRGGB10"><constant>V4L2_PIX_FMT_SRGGB10</constant></refname> - <refname id="V4L2-PIX-FMT-SGRBG10"><constant>V4L2_PIX_FMT_SGRBG10</constant></refname> - <refname id="V4L2-PIX-FMT-SGBRG10"><constant>V4L2_PIX_FMT_SGBRG10</constant></refname> - <refname id="V4L2-PIX-FMT-SBGGR10"><constant>V4L2_PIX_FMT_SBGGR10</constant></refname> - <refpurpose>10-bit Bayer formats expanded to 16 bits</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>These four pixel formats are raw sRGB / Bayer formats with -10 bits per colour. Each colour component is stored in a 16-bit word, with 6 -unused high bits filled with zeros. Each n-pixel row contains n/2 green samples -and n/2 blue or red samples, with alternating red and blue rows. Bytes are -stored in memory in little endian order. They are conventionally described -as GRGR... BGBG..., RGRG... GBGB..., etc. Below is an example of one of these -formats</para> - - <example> - <title><constant>V4L2_PIX_FMT_SBGGR10</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte, high 6 bits in high bytes are 0. - <informaltable frame="none"> - <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>B<subscript>00low</subscript></entry> - <entry>B<subscript>00high</subscript></entry> - <entry>G<subscript>01low</subscript></entry> - <entry>G<subscript>01high</subscript></entry> - <entry>B<subscript>02low</subscript></entry> - <entry>B<subscript>02high</subscript></entry> - <entry>G<subscript>03low</subscript></entry> - <entry>G<subscript>03high</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>G<subscript>10low</subscript></entry> - <entry>G<subscript>10high</subscript></entry> - <entry>R<subscript>11low</subscript></entry> - <entry>R<subscript>11high</subscript></entry> - <entry>G<subscript>12low</subscript></entry> - <entry>G<subscript>12high</subscript></entry> - <entry>R<subscript>13low</subscript></entry> - <entry>R<subscript>13high</subscript></entry> - </row> - <row> - <entry>start + 16:</entry> - <entry>B<subscript>20low</subscript></entry> - <entry>B<subscript>20high</subscript></entry> - <entry>G<subscript>21low</subscript></entry> - <entry>G<subscript>21high</subscript></entry> - <entry>B<subscript>22low</subscript></entry> - <entry>B<subscript>22high</subscript></entry> - <entry>G<subscript>23low</subscript></entry> - <entry>G<subscript>23high</subscript></entry> - </row> - <row> - <entry>start + 24:</entry> - <entry>G<subscript>30low</subscript></entry> - <entry>G<subscript>30high</subscript></entry> - <entry>R<subscript>31low</subscript></entry> - <entry>R<subscript>31high</subscript></entry> - <entry>G<subscript>32low</subscript></entry> - <entry>G<subscript>32high</subscript></entry> - <entry>R<subscript>33low</subscript></entry> - <entry>R<subscript>33high</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-srggb10alaw8.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb10alaw8.xml deleted file mode 100644 index d2e5845e57fb..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-srggb10alaw8.xml +++ /dev/null @@ -1,34 +0,0 @@ - <refentry> - <refmeta> - <refentrytitle> - V4L2_PIX_FMT_SBGGR10ALAW8 ('aBA8'), - V4L2_PIX_FMT_SGBRG10ALAW8 ('aGA8'), - V4L2_PIX_FMT_SGRBG10ALAW8 ('agA8'), - V4L2_PIX_FMT_SRGGB10ALAW8 ('aRA8'), - </refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname id="V4L2-PIX-FMT-SBGGR10ALAW8"> - <constant>V4L2_PIX_FMT_SBGGR10ALAW8</constant> - </refname> - <refname id="V4L2-PIX-FMT-SGBRG10ALAW8"> - <constant>V4L2_PIX_FMT_SGBRG10ALAW8</constant> - </refname> - <refname id="V4L2-PIX-FMT-SGRBG10ALAW8"> - <constant>V4L2_PIX_FMT_SGRBG10ALAW8</constant> - </refname> - <refname id="V4L2-PIX-FMT-SRGGB10ALAW8"> - <constant>V4L2_PIX_FMT_SRGGB10ALAW8</constant> - </refname> - <refpurpose>10-bit Bayer formats compressed to 8 bits</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <para>These four pixel formats are raw sRGB / Bayer - formats with 10 bits per color compressed to 8 bits each, - using the A-LAW algorithm. Each color component consumes 8 - bits of memory. In other respects this format is similar to - <xref linkend="V4L2-PIX-FMT-SRGGB8"></xref>.</para> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-srggb10dpcm8.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb10dpcm8.xml deleted file mode 100644 index bde89878c5c5..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-srggb10dpcm8.xml +++ /dev/null @@ -1,28 +0,0 @@ - <refentry id="pixfmt-srggb10dpcm8"> - <refmeta> - <refentrytitle> - V4L2_PIX_FMT_SBGGR10DPCM8 ('bBA8'), - V4L2_PIX_FMT_SGBRG10DPCM8 ('bGA8'), - V4L2_PIX_FMT_SGRBG10DPCM8 ('BD10'), - V4L2_PIX_FMT_SRGGB10DPCM8 ('bRA8'), - </refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname id="V4L2-PIX-FMT-SBGGR10DPCM8"><constant>V4L2_PIX_FMT_SBGGR10DPCM8</constant></refname> - <refname id="V4L2-PIX-FMT-SGBRG10DPCM8"><constant>V4L2_PIX_FMT_SGBRG10DPCM8</constant></refname> - <refname id="V4L2-PIX-FMT-SGRBG10DPCM8"><constant>V4L2_PIX_FMT_SGRBG10DPCM8</constant></refname> - <refname id="V4L2-PIX-FMT-SRGGB10DPCM8"><constant>V4L2_PIX_FMT_SRGGB10DPCM8</constant></refname> - <refpurpose>10-bit Bayer formats compressed to 8 bits</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>These four pixel formats are raw sRGB / Bayer formats - with 10 bits per colour compressed to 8 bits each, using DPCM - compression. DPCM, differential pulse-code modulation, is lossy. - Each colour component consumes 8 bits of memory. In other respects - this format is similar to <xref linkend="pixfmt-srggb10" />.</para> - - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-srggb10p.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb10p.xml deleted file mode 100644 index a8cc102cde4f..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-srggb10p.xml +++ /dev/null @@ -1,99 +0,0 @@ - <refentry id="pixfmt-srggb10p"> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_SRGGB10P ('pRAA'), - V4L2_PIX_FMT_SGRBG10P ('pgAA'), - V4L2_PIX_FMT_SGBRG10P ('pGAA'), - V4L2_PIX_FMT_SBGGR10P ('pBAA'), - </refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname id="V4L2-PIX-FMT-SRGGB10P"><constant>V4L2_PIX_FMT_SRGGB10P</constant></refname> - <refname id="V4L2-PIX-FMT-SGRBG10P"><constant>V4L2_PIX_FMT_SGRBG10P</constant></refname> - <refname id="V4L2-PIX-FMT-SGBRG10P"><constant>V4L2_PIX_FMT_SGBRG10P</constant></refname> - <refname id="V4L2-PIX-FMT-SBGGR10P"><constant>V4L2_PIX_FMT_SBGGR10P</constant></refname> - <refpurpose>10-bit packed Bayer formats</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>These four pixel formats are packed raw sRGB / - Bayer formats with 10 bits per colour. Every four consecutive - colour components are packed into 5 bytes. Each of the first 4 - bytes contain the 8 high order bits of the pixels, and the - fifth byte contains the two least significants bits of each - pixel, in the same order.</para> - - <para>Each n-pixel row contains n/2 green samples and n/2 blue - or red samples, with alternating green-red and green-blue - rows. They are conventionally described as GRGR... BGBG..., - RGRG... GBGB..., etc. Below is an example of one of these - formats:</para> - - <example> - <title><constant>V4L2_PIX_FMT_SBGGR10P</constant> 4 × 4 - pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="topbot" colsep="1" rowsep="1"> - <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>B<subscript>00high</subscript></entry> - <entry>G<subscript>01high</subscript></entry> - <entry>B<subscript>02high</subscript></entry> - <entry>G<subscript>03high</subscript></entry> - <entry>B<subscript>00low</subscript>(bits 7--6) - G<subscript>01low</subscript>(bits 5--4) - B<subscript>02low</subscript>(bits 3--2) - G<subscript>03low</subscript>(bits 1--0) - </entry> - </row> - <row> - <entry>start + 5:</entry> - <entry>G<subscript>10high</subscript></entry> - <entry>R<subscript>11high</subscript></entry> - <entry>G<subscript>12high</subscript></entry> - <entry>R<subscript>13high</subscript></entry> - <entry>G<subscript>10low</subscript>(bits 7--6) - R<subscript>11low</subscript>(bits 5--4) - G<subscript>12low</subscript>(bits 3--2) - R<subscript>13low</subscript>(bits 1--0) - </entry> - </row> - <row> - <entry>start + 10:</entry> - <entry>B<subscript>20high</subscript></entry> - <entry>G<subscript>21high</subscript></entry> - <entry>B<subscript>22high</subscript></entry> - <entry>G<subscript>23high</subscript></entry> - <entry>B<subscript>20low</subscript>(bits 7--6) - G<subscript>21low</subscript>(bits 5--4) - B<subscript>22low</subscript>(bits 3--2) - G<subscript>23low</subscript>(bits 1--0) - </entry> - </row> - <row> - <entry>start + 15:</entry> - <entry>G<subscript>30high</subscript></entry> - <entry>R<subscript>31high</subscript></entry> - <entry>G<subscript>32high</subscript></entry> - <entry>R<subscript>33high</subscript></entry> - <entry>G<subscript>30low</subscript>(bits 7--6) - R<subscript>31low</subscript>(bits 5--4) - G<subscript>32low</subscript>(bits 3--2) - R<subscript>33low</subscript>(bits 1--0) - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-srggb12.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb12.xml deleted file mode 100644 index 0c8e4adf417f..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-srggb12.xml +++ /dev/null @@ -1,90 +0,0 @@ - <refentry> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_SRGGB12 ('RG12'), - V4L2_PIX_FMT_SGRBG12 ('BA12'), - V4L2_PIX_FMT_SGBRG12 ('GB12'), - V4L2_PIX_FMT_SBGGR12 ('BG12'), - </refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname id="V4L2-PIX-FMT-SRGGB12"><constant>V4L2_PIX_FMT_SRGGB12</constant></refname> - <refname id="V4L2-PIX-FMT-SGRBG12"><constant>V4L2_PIX_FMT_SGRBG12</constant></refname> - <refname id="V4L2-PIX-FMT-SGBRG12"><constant>V4L2_PIX_FMT_SGBRG12</constant></refname> - <refname id="V4L2-PIX-FMT-SBGGR12"><constant>V4L2_PIX_FMT_SBGGR12</constant></refname> - <refpurpose>12-bit Bayer formats expanded to 16 bits</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>These four pixel formats are raw sRGB / Bayer formats with -12 bits per colour. Each colour component is stored in a 16-bit word, with 4 -unused high bits filled with zeros. Each n-pixel row contains n/2 green samples -and n/2 blue or red samples, with alternating red and blue rows. Bytes are -stored in memory in little endian order. They are conventionally described -as GRGR... BGBG..., RGRG... GBGB..., etc. Below is an example of one of these -formats</para> - - <example> - <title><constant>V4L2_PIX_FMT_SBGGR12</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte, high 6 bits in high bytes are 0. - <informaltable frame="none"> - <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>B<subscript>00low</subscript></entry> - <entry>B<subscript>00high</subscript></entry> - <entry>G<subscript>01low</subscript></entry> - <entry>G<subscript>01high</subscript></entry> - <entry>B<subscript>02low</subscript></entry> - <entry>B<subscript>02high</subscript></entry> - <entry>G<subscript>03low</subscript></entry> - <entry>G<subscript>03high</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>G<subscript>10low</subscript></entry> - <entry>G<subscript>10high</subscript></entry> - <entry>R<subscript>11low</subscript></entry> - <entry>R<subscript>11high</subscript></entry> - <entry>G<subscript>12low</subscript></entry> - <entry>G<subscript>12high</subscript></entry> - <entry>R<subscript>13low</subscript></entry> - <entry>R<subscript>13high</subscript></entry> - </row> - <row> - <entry>start + 16:</entry> - <entry>B<subscript>20low</subscript></entry> - <entry>B<subscript>20high</subscript></entry> - <entry>G<subscript>21low</subscript></entry> - <entry>G<subscript>21high</subscript></entry> - <entry>B<subscript>22low</subscript></entry> - <entry>B<subscript>22high</subscript></entry> - <entry>G<subscript>23low</subscript></entry> - <entry>G<subscript>23high</subscript></entry> - </row> - <row> - <entry>start + 24:</entry> - <entry>G<subscript>30low</subscript></entry> - <entry>G<subscript>30high</subscript></entry> - <entry>R<subscript>31low</subscript></entry> - <entry>R<subscript>31high</subscript></entry> - <entry>G<subscript>32low</subscript></entry> - <entry>G<subscript>32high</subscript></entry> - <entry>R<subscript>33low</subscript></entry> - <entry>R<subscript>33high</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-srggb8.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb8.xml deleted file mode 100644 index 2570e3be3cf1..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-srggb8.xml +++ /dev/null @@ -1,67 +0,0 @@ - <refentry id="V4L2-PIX-FMT-SRGGB8"> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_SRGGB8 ('RGGB')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname><constant>V4L2_PIX_FMT_SRGGB8</constant></refname> - <refpurpose>Bayer RGB format</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>This is commonly the native format of digital cameras, -reflecting the arrangement of sensors on the CCD device. Only one red, -green or blue value is given for each pixel. Missing components must -be interpolated from neighbouring pixels. From left to right the first -row consists of a red and green value, the second row of a green and -blue value. This scheme repeats to the right and down for every two -columns and rows.</para> - - <example> - <title><constant>V4L2_PIX_FMT_SRGGB8</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>R<subscript>00</subscript></entry> - <entry>G<subscript>01</subscript></entry> - <entry>R<subscript>02</subscript></entry> - <entry>G<subscript>03</subscript></entry> - </row> - <row> - <entry>start + 4:</entry> - <entry>G<subscript>10</subscript></entry> - <entry>B<subscript>11</subscript></entry> - <entry>G<subscript>12</subscript></entry> - <entry>B<subscript>13</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>R<subscript>20</subscript></entry> - <entry>G<subscript>21</subscript></entry> - <entry>R<subscript>22</subscript></entry> - <entry>G<subscript>23</subscript></entry> - </row> - <row> - <entry>start + 12:</entry> - <entry>G<subscript>30</subscript></entry> - <entry>B<subscript>31</subscript></entry> - <entry>G<subscript>32</subscript></entry> - <entry>B<subscript>33</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-uv8.xml b/Documentation/DocBook/media/v4l/pixfmt-uv8.xml deleted file mode 100644 index c507c1f73cd0..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-uv8.xml +++ /dev/null @@ -1,62 +0,0 @@ - <refentry id="V4L2-PIX-FMT-UV8"> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_UV8 ('UV8')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname><constant>V4L2_PIX_FMT_UV8</constant></refname> - <refpurpose>UV plane interleaved</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <para>In this format there is no Y plane, Only CbCr plane. ie - (UV interleaved)</para> - <example> - <title> - <constant>V4L2_PIX_FMT_UV8</constant> - pixel image - </title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>Cb<subscript>00</subscript></entry> - <entry>Cr<subscript>00</subscript></entry> - <entry>Cb<subscript>01</subscript></entry> - <entry>Cr<subscript>01</subscript></entry> - </row> - <row> - <entry>start + 4:</entry> - <entry>Cb<subscript>10</subscript></entry> - <entry>Cr<subscript>10</subscript></entry> - <entry>Cb<subscript>11</subscript></entry> - <entry>Cr<subscript>11</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>Cb<subscript>20</subscript></entry> - <entry>Cr<subscript>20</subscript></entry> - <entry>Cb<subscript>21</subscript></entry> - <entry>Cr<subscript>21</subscript></entry> - </row> - <row> - <entry>start + 12:</entry> - <entry>Cb<subscript>30</subscript></entry> - <entry>Cr<subscript>30</subscript></entry> - <entry>Cb<subscript>31</subscript></entry> - <entry>Cr<subscript>31</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-uyvy.xml b/Documentation/DocBook/media/v4l/pixfmt-uyvy.xml deleted file mode 100644 index b1f6801a17ff..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-uyvy.xml +++ /dev/null @@ -1,120 +0,0 @@ - <refentry id="V4L2-PIX-FMT-UYVY"> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_UYVY ('UYVY')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname><constant>V4L2_PIX_FMT_UYVY</constant></refname> - <refpurpose>Variation of -<constant>V4L2_PIX_FMT_YUYV</constant> with different order of samples -in memory</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>In this format each four bytes is two pixels. Each four -bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and -the Cb and Cr belong to both pixels. As you can see, the Cr and Cb -components have half the horizontal resolution of the Y -component.</para> - - <example> - <title><constant>V4L2_PIX_FMT_UYVY</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="9" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>Cb<subscript>00</subscript></entry> - <entry>Y'<subscript>00</subscript></entry> - <entry>Cr<subscript>00</subscript></entry> - <entry>Y'<subscript>01</subscript></entry> - <entry>Cb<subscript>01</subscript></entry> - <entry>Y'<subscript>02</subscript></entry> - <entry>Cr<subscript>01</subscript></entry> - <entry>Y'<subscript>03</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>Cb<subscript>10</subscript></entry> - <entry>Y'<subscript>10</subscript></entry> - <entry>Cr<subscript>10</subscript></entry> - <entry>Y'<subscript>11</subscript></entry> - <entry>Cb<subscript>11</subscript></entry> - <entry>Y'<subscript>12</subscript></entry> - <entry>Cr<subscript>11</subscript></entry> - <entry>Y'<subscript>13</subscript></entry> - </row> - <row> - <entry>start + 16:</entry> - <entry>Cb<subscript>20</subscript></entry> - <entry>Y'<subscript>20</subscript></entry> - <entry>Cr<subscript>20</subscript></entry> - <entry>Y'<subscript>21</subscript></entry> - <entry>Cb<subscript>21</subscript></entry> - <entry>Y'<subscript>22</subscript></entry> - <entry>Cr<subscript>21</subscript></entry> - <entry>Y'<subscript>23</subscript></entry> - </row> - <row> - <entry>start + 24:</entry> - <entry>Cb<subscript>30</subscript></entry> - <entry>Y'<subscript>30</subscript></entry> - <entry>Cr<subscript>30</subscript></entry> - <entry>Y'<subscript>31</subscript></entry> - <entry>Cb<subscript>31</subscript></entry> - <entry>Y'<subscript>32</subscript></entry> - <entry>Cr<subscript>31</subscript></entry> - <entry>Y'<subscript>33</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - - <formalpara> - <title>Color Sample Location.</title> - <para> - <informaltable frame="none"> - <tgroup cols="7" align="center"> - <tbody valign="top"> - <row> - <entry></entry> - <entry>0</entry><entry></entry><entry>1</entry><entry></entry> - <entry>2</entry><entry></entry><entry>3</entry> - </row> - <row> - <entry>0</entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry> - </row> - <row> - <entry>1</entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry> - </row> - <row> - <entry>2</entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry> - </row> - <row> - <entry>3</entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-vyuy.xml b/Documentation/DocBook/media/v4l/pixfmt-vyuy.xml deleted file mode 100644 index 82803408b389..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-vyuy.xml +++ /dev/null @@ -1,120 +0,0 @@ - <refentry id="V4L2-PIX-FMT-VYUY"> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_VYUY ('VYUY')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname><constant>V4L2_PIX_FMT_VYUY</constant></refname> - <refpurpose>Variation of -<constant>V4L2_PIX_FMT_YUYV</constant> with different order of samples -in memory</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>In this format each four bytes is two pixels. Each four -bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and -the Cb and Cr belong to both pixels. As you can see, the Cr and Cb -components have half the horizontal resolution of the Y -component.</para> - - <example> - <title><constant>V4L2_PIX_FMT_VYUY</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="9" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>Cr<subscript>00</subscript></entry> - <entry>Y'<subscript>00</subscript></entry> - <entry>Cb<subscript>00</subscript></entry> - <entry>Y'<subscript>01</subscript></entry> - <entry>Cr<subscript>01</subscript></entry> - <entry>Y'<subscript>02</subscript></entry> - <entry>Cb<subscript>01</subscript></entry> - <entry>Y'<subscript>03</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>Cr<subscript>10</subscript></entry> - <entry>Y'<subscript>10</subscript></entry> - <entry>Cb<subscript>10</subscript></entry> - <entry>Y'<subscript>11</subscript></entry> - <entry>Cr<subscript>11</subscript></entry> - <entry>Y'<subscript>12</subscript></entry> - <entry>Cb<subscript>11</subscript></entry> - <entry>Y'<subscript>13</subscript></entry> - </row> - <row> - <entry>start + 16:</entry> - <entry>Cr<subscript>20</subscript></entry> - <entry>Y'<subscript>20</subscript></entry> - <entry>Cb<subscript>20</subscript></entry> - <entry>Y'<subscript>21</subscript></entry> - <entry>Cr<subscript>21</subscript></entry> - <entry>Y'<subscript>22</subscript></entry> - <entry>Cb<subscript>21</subscript></entry> - <entry>Y'<subscript>23</subscript></entry> - </row> - <row> - <entry>start + 24:</entry> - <entry>Cr<subscript>30</subscript></entry> - <entry>Y'<subscript>30</subscript></entry> - <entry>Cb<subscript>30</subscript></entry> - <entry>Y'<subscript>31</subscript></entry> - <entry>Cr<subscript>31</subscript></entry> - <entry>Y'<subscript>32</subscript></entry> - <entry>Cb<subscript>31</subscript></entry> - <entry>Y'<subscript>33</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - - <formalpara> - <title>Color Sample Location.</title> - <para> - <informaltable frame="none"> - <tgroup cols="7" align="center"> - <tbody valign="top"> - <row> - <entry></entry> - <entry>0</entry><entry></entry><entry>1</entry><entry></entry> - <entry>2</entry><entry></entry><entry>3</entry> - </row> - <row> - <entry>0</entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry> - </row> - <row> - <entry>1</entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry> - </row> - <row> - <entry>2</entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry> - </row> - <row> - <entry>3</entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-y10.xml b/Documentation/DocBook/media/v4l/pixfmt-y10.xml deleted file mode 100644 index d065043db8d8..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-y10.xml +++ /dev/null @@ -1,79 +0,0 @@ -<refentry id="V4L2-PIX-FMT-Y10"> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_Y10 ('Y10 ')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname><constant>V4L2_PIX_FMT_Y10</constant></refname> - <refpurpose>Grey-scale image</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>This is a grey-scale image with a depth of 10 bits per pixel. Pixels -are stored in 16-bit words with unused high bits padded with 0. The least -significant byte is stored at lower memory addresses (little-endian).</para> - - <example> - <title><constant>V4L2_PIX_FMT_Y10</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="9" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>Y'<subscript>00low</subscript></entry> - <entry>Y'<subscript>00high</subscript></entry> - <entry>Y'<subscript>01low</subscript></entry> - <entry>Y'<subscript>01high</subscript></entry> - <entry>Y'<subscript>02low</subscript></entry> - <entry>Y'<subscript>02high</subscript></entry> - <entry>Y'<subscript>03low</subscript></entry> - <entry>Y'<subscript>03high</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>Y'<subscript>10low</subscript></entry> - <entry>Y'<subscript>10high</subscript></entry> - <entry>Y'<subscript>11low</subscript></entry> - <entry>Y'<subscript>11high</subscript></entry> - <entry>Y'<subscript>12low</subscript></entry> - <entry>Y'<subscript>12high</subscript></entry> - <entry>Y'<subscript>13low</subscript></entry> - <entry>Y'<subscript>13high</subscript></entry> - </row> - <row> - <entry>start + 16:</entry> - <entry>Y'<subscript>20low</subscript></entry> - <entry>Y'<subscript>20high</subscript></entry> - <entry>Y'<subscript>21low</subscript></entry> - <entry>Y'<subscript>21high</subscript></entry> - <entry>Y'<subscript>22low</subscript></entry> - <entry>Y'<subscript>22high</subscript></entry> - <entry>Y'<subscript>23low</subscript></entry> - <entry>Y'<subscript>23high</subscript></entry> - </row> - <row> - <entry>start + 24:</entry> - <entry>Y'<subscript>30low</subscript></entry> - <entry>Y'<subscript>30high</subscript></entry> - <entry>Y'<subscript>31low</subscript></entry> - <entry>Y'<subscript>31high</subscript></entry> - <entry>Y'<subscript>32low</subscript></entry> - <entry>Y'<subscript>32high</subscript></entry> - <entry>Y'<subscript>33low</subscript></entry> - <entry>Y'<subscript>33high</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-y10b.xml b/Documentation/DocBook/media/v4l/pixfmt-y10b.xml deleted file mode 100644 index adb0ad808c93..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-y10b.xml +++ /dev/null @@ -1,43 +0,0 @@ -<refentry id="V4L2-PIX-FMT-Y10BPACK"> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_Y10BPACK ('Y10B')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname><constant>V4L2_PIX_FMT_Y10BPACK</constant></refname> - <refpurpose>Grey-scale image as a bit-packed array</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>This is a packed grey-scale image format with a depth of 10 bits per - pixel. Pixels are stored in a bit-packed array of 10bit bits per pixel, - with no padding between them and with the most significant bits coming - first from the left.</para> - - <example> - <title><constant>V4L2_PIX_FMT_Y10BPACK</constant> 4 pixel data stream taking 5 bytes</title> - - <formalpara> - <title>Bit-packed representation</title> - <para>pixels cross the byte boundary and have a ratio of 5 bytes for each 4 - pixels. - <informaltable frame="all"> - <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>Y'<subscript>00[9:2]</subscript></entry> - <entry>Y'<subscript>00[1:0]</subscript>Y'<subscript>01[9:4]</subscript></entry> - <entry>Y'<subscript>01[3:0]</subscript>Y'<subscript>02[9:6]</subscript></entry> - <entry>Y'<subscript>02[5:0]</subscript>Y'<subscript>03[9:8]</subscript></entry> - <entry>Y'<subscript>03[7:0]</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-y12.xml b/Documentation/DocBook/media/v4l/pixfmt-y12.xml deleted file mode 100644 index ff417b858cc9..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-y12.xml +++ /dev/null @@ -1,79 +0,0 @@ -<refentry id="V4L2-PIX-FMT-Y12"> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_Y12 ('Y12 ')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname><constant>V4L2_PIX_FMT_Y12</constant></refname> - <refpurpose>Grey-scale image</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>This is a grey-scale image with a depth of 12 bits per pixel. Pixels -are stored in 16-bit words with unused high bits padded with 0. The least -significant byte is stored at lower memory addresses (little-endian).</para> - - <example> - <title><constant>V4L2_PIX_FMT_Y12</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="9" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>Y'<subscript>00low</subscript></entry> - <entry>Y'<subscript>00high</subscript></entry> - <entry>Y'<subscript>01low</subscript></entry> - <entry>Y'<subscript>01high</subscript></entry> - <entry>Y'<subscript>02low</subscript></entry> - <entry>Y'<subscript>02high</subscript></entry> - <entry>Y'<subscript>03low</subscript></entry> - <entry>Y'<subscript>03high</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>Y'<subscript>10low</subscript></entry> - <entry>Y'<subscript>10high</subscript></entry> - <entry>Y'<subscript>11low</subscript></entry> - <entry>Y'<subscript>11high</subscript></entry> - <entry>Y'<subscript>12low</subscript></entry> - <entry>Y'<subscript>12high</subscript></entry> - <entry>Y'<subscript>13low</subscript></entry> - <entry>Y'<subscript>13high</subscript></entry> - </row> - <row> - <entry>start + 16:</entry> - <entry>Y'<subscript>20low</subscript></entry> - <entry>Y'<subscript>20high</subscript></entry> - <entry>Y'<subscript>21low</subscript></entry> - <entry>Y'<subscript>21high</subscript></entry> - <entry>Y'<subscript>22low</subscript></entry> - <entry>Y'<subscript>22high</subscript></entry> - <entry>Y'<subscript>23low</subscript></entry> - <entry>Y'<subscript>23high</subscript></entry> - </row> - <row> - <entry>start + 24:</entry> - <entry>Y'<subscript>30low</subscript></entry> - <entry>Y'<subscript>30high</subscript></entry> - <entry>Y'<subscript>31low</subscript></entry> - <entry>Y'<subscript>31high</subscript></entry> - <entry>Y'<subscript>32low</subscript></entry> - <entry>Y'<subscript>32high</subscript></entry> - <entry>Y'<subscript>33low</subscript></entry> - <entry>Y'<subscript>33high</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-y16-be.xml b/Documentation/DocBook/media/v4l/pixfmt-y16-be.xml deleted file mode 100644 index cea53e1eaa43..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-y16-be.xml +++ /dev/null @@ -1,81 +0,0 @@ -<refentry id="V4L2-PIX-FMT-Y16-BE"> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_Y16_BE ('Y16 ' | (1 << 31))</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname><constant>V4L2_PIX_FMT_Y16_BE</constant></refname> - <refpurpose>Grey-scale image</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>This is a grey-scale image with a depth of 16 bits per -pixel. The most significant byte is stored at lower memory addresses -(big-endian). Note the actual sampling precision may be lower than -16 bits, for example 10 bits per pixel with values in range 0 to -1023.</para> - - <example> - <title><constant>V4L2_PIX_FMT_Y16_BE</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="9" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>Y'<subscript>00high</subscript></entry> - <entry>Y'<subscript>00low</subscript></entry> - <entry>Y'<subscript>01high</subscript></entry> - <entry>Y'<subscript>01low</subscript></entry> - <entry>Y'<subscript>02high</subscript></entry> - <entry>Y'<subscript>02low</subscript></entry> - <entry>Y'<subscript>03high</subscript></entry> - <entry>Y'<subscript>03low</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>Y'<subscript>10high</subscript></entry> - <entry>Y'<subscript>10low</subscript></entry> - <entry>Y'<subscript>11high</subscript></entry> - <entry>Y'<subscript>11low</subscript></entry> - <entry>Y'<subscript>12high</subscript></entry> - <entry>Y'<subscript>12low</subscript></entry> - <entry>Y'<subscript>13high</subscript></entry> - <entry>Y'<subscript>13low</subscript></entry> - </row> - <row> - <entry>start + 16:</entry> - <entry>Y'<subscript>20high</subscript></entry> - <entry>Y'<subscript>20low</subscript></entry> - <entry>Y'<subscript>21high</subscript></entry> - <entry>Y'<subscript>21low</subscript></entry> - <entry>Y'<subscript>22high</subscript></entry> - <entry>Y'<subscript>22low</subscript></entry> - <entry>Y'<subscript>23high</subscript></entry> - <entry>Y'<subscript>23low</subscript></entry> - </row> - <row> - <entry>start + 24:</entry> - <entry>Y'<subscript>30high</subscript></entry> - <entry>Y'<subscript>30low</subscript></entry> - <entry>Y'<subscript>31high</subscript></entry> - <entry>Y'<subscript>31low</subscript></entry> - <entry>Y'<subscript>32high</subscript></entry> - <entry>Y'<subscript>32low</subscript></entry> - <entry>Y'<subscript>33high</subscript></entry> - <entry>Y'<subscript>33low</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-y16.xml b/Documentation/DocBook/media/v4l/pixfmt-y16.xml deleted file mode 100644 index ff4f727d5624..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-y16.xml +++ /dev/null @@ -1,81 +0,0 @@ -<refentry id="V4L2-PIX-FMT-Y16"> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_Y16 ('Y16 ')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname><constant>V4L2_PIX_FMT_Y16</constant></refname> - <refpurpose>Grey-scale image</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>This is a grey-scale image with a depth of 16 bits per -pixel. The least significant byte is stored at lower memory addresses -(little-endian). Note the actual sampling precision may be lower than -16 bits, for example 10 bits per pixel with values in range 0 to -1023.</para> - - <example> - <title><constant>V4L2_PIX_FMT_Y16</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="9" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>Y'<subscript>00low</subscript></entry> - <entry>Y'<subscript>00high</subscript></entry> - <entry>Y'<subscript>01low</subscript></entry> - <entry>Y'<subscript>01high</subscript></entry> - <entry>Y'<subscript>02low</subscript></entry> - <entry>Y'<subscript>02high</subscript></entry> - <entry>Y'<subscript>03low</subscript></entry> - <entry>Y'<subscript>03high</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>Y'<subscript>10low</subscript></entry> - <entry>Y'<subscript>10high</subscript></entry> - <entry>Y'<subscript>11low</subscript></entry> - <entry>Y'<subscript>11high</subscript></entry> - <entry>Y'<subscript>12low</subscript></entry> - <entry>Y'<subscript>12high</subscript></entry> - <entry>Y'<subscript>13low</subscript></entry> - <entry>Y'<subscript>13high</subscript></entry> - </row> - <row> - <entry>start + 16:</entry> - <entry>Y'<subscript>20low</subscript></entry> - <entry>Y'<subscript>20high</subscript></entry> - <entry>Y'<subscript>21low</subscript></entry> - <entry>Y'<subscript>21high</subscript></entry> - <entry>Y'<subscript>22low</subscript></entry> - <entry>Y'<subscript>22high</subscript></entry> - <entry>Y'<subscript>23low</subscript></entry> - <entry>Y'<subscript>23high</subscript></entry> - </row> - <row> - <entry>start + 24:</entry> - <entry>Y'<subscript>30low</subscript></entry> - <entry>Y'<subscript>30high</subscript></entry> - <entry>Y'<subscript>31low</subscript></entry> - <entry>Y'<subscript>31high</subscript></entry> - <entry>Y'<subscript>32low</subscript></entry> - <entry>Y'<subscript>32high</subscript></entry> - <entry>Y'<subscript>33low</subscript></entry> - <entry>Y'<subscript>33high</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-y41p.xml b/Documentation/DocBook/media/v4l/pixfmt-y41p.xml deleted file mode 100644 index 98dcb91d2917..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-y41p.xml +++ /dev/null @@ -1,149 +0,0 @@ - <refentry id="V4L2-PIX-FMT-Y41P"> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_Y41P ('Y41P')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname><constant>V4L2_PIX_FMT_Y41P</constant></refname> - <refpurpose>Format with ¼ horizontal chroma -resolution, also known as YUV 4:1:1</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>In this format each 12 bytes is eight pixels. In the -twelve bytes are two CbCr pairs and eight Y's. The first CbCr pair -goes with the first four Y's, and the second CbCr pair goes with the -other four Y's. The Cb and Cr components have one fourth the -horizontal resolution of the Y component.</para> - - <para>Do not confuse this format with <link -linkend="V4L2-PIX-FMT-YUV411P"><constant>V4L2_PIX_FMT_YUV411P</constant></link>. -Y41P is derived from "YUV 4:1:1 <emphasis>packed</emphasis>", while -YUV411P stands for "YUV 4:1:1 <emphasis>planar</emphasis>".</para> - - <example> - <title><constant>V4L2_PIX_FMT_Y41P</constant> 8 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="13" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>Cb<subscript>00</subscript></entry> - <entry>Y'<subscript>00</subscript></entry> - <entry>Cr<subscript>00</subscript></entry> - <entry>Y'<subscript>01</subscript></entry> - <entry>Cb<subscript>01</subscript></entry> - <entry>Y'<subscript>02</subscript></entry> - <entry>Cr<subscript>01</subscript></entry> - <entry>Y'<subscript>03</subscript></entry> - <entry>Y'<subscript>04</subscript></entry> - <entry>Y'<subscript>05</subscript></entry> - <entry>Y'<subscript>06</subscript></entry> - <entry>Y'<subscript>07</subscript></entry> - </row> - <row> - <entry>start + 12:</entry> - <entry>Cb<subscript>10</subscript></entry> - <entry>Y'<subscript>10</subscript></entry> - <entry>Cr<subscript>10</subscript></entry> - <entry>Y'<subscript>11</subscript></entry> - <entry>Cb<subscript>11</subscript></entry> - <entry>Y'<subscript>12</subscript></entry> - <entry>Cr<subscript>11</subscript></entry> - <entry>Y'<subscript>13</subscript></entry> - <entry>Y'<subscript>14</subscript></entry> - <entry>Y'<subscript>15</subscript></entry> - <entry>Y'<subscript>16</subscript></entry> - <entry>Y'<subscript>17</subscript></entry> - </row> - <row> - <entry>start + 24:</entry> - <entry>Cb<subscript>20</subscript></entry> - <entry>Y'<subscript>20</subscript></entry> - <entry>Cr<subscript>20</subscript></entry> - <entry>Y'<subscript>21</subscript></entry> - <entry>Cb<subscript>21</subscript></entry> - <entry>Y'<subscript>22</subscript></entry> - <entry>Cr<subscript>21</subscript></entry> - <entry>Y'<subscript>23</subscript></entry> - <entry>Y'<subscript>24</subscript></entry> - <entry>Y'<subscript>25</subscript></entry> - <entry>Y'<subscript>26</subscript></entry> - <entry>Y'<subscript>27</subscript></entry> - </row> - <row> - <entry>start + 36:</entry> - <entry>Cb<subscript>30</subscript></entry> - <entry>Y'<subscript>30</subscript></entry> - <entry>Cr<subscript>30</subscript></entry> - <entry>Y'<subscript>31</subscript></entry> - <entry>Cb<subscript>31</subscript></entry> - <entry>Y'<subscript>32</subscript></entry> - <entry>Cr<subscript>31</subscript></entry> - <entry>Y'<subscript>33</subscript></entry> - <entry>Y'<subscript>34</subscript></entry> - <entry>Y'<subscript>35</subscript></entry> - <entry>Y'<subscript>36</subscript></entry> - <entry>Y'<subscript>37</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable></para> - </formalpara> - - <formalpara> - <title>Color Sample Location.</title> - <para> - <informaltable frame="none"> - <tgroup cols="15" align="center"> - <tbody valign="top"> - <row> - <entry></entry> - <entry>0</entry><entry></entry><entry>1</entry><entry></entry> - <entry>2</entry><entry></entry><entry>3</entry><entry></entry> - <entry>4</entry><entry></entry><entry>5</entry><entry></entry> - <entry>6</entry><entry></entry><entry>7</entry> - </row> - <row> - <entry>0</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry>1</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry>2</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry>3</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuv410.xml b/Documentation/DocBook/media/v4l/pixfmt-yuv410.xml deleted file mode 100644 index 0869dce5f92c..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-yuv410.xml +++ /dev/null @@ -1,133 +0,0 @@ - <refentry> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_YVU410 ('YVU9'), V4L2_PIX_FMT_YUV410 ('YUV9')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname id="V4L2-PIX-FMT-YVU410"><constant>V4L2_PIX_FMT_YVU410</constant></refname> - <refname id="V4L2-PIX-FMT-YUV410"><constant>V4L2_PIX_FMT_YUV410</constant></refname> - <refpurpose>Planar formats with ¼ horizontal and -vertical chroma resolution, also known as YUV 4:1:0</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>These are planar formats, as opposed to a packed format. -The three components are separated into three sub-images or planes. -The Y plane is first. The Y plane has one byte per pixel. For -<constant>V4L2_PIX_FMT_YVU410</constant>, the Cr plane immediately -follows the Y plane in memory. The Cr plane is ¼ the width and -¼ the height of the Y plane (and of the image). Each Cr belongs -to 16 pixels, a four-by-four square of the image. Following the Cr -plane is the Cb plane, just like the Cr plane. -<constant>V4L2_PIX_FMT_YUV410</constant> is the same, except the Cb -plane comes first, then the Cr plane.</para> - - <para>If the Y plane has pad bytes after each row, then the Cr -and Cb planes have ¼ as many pad bytes after their rows. In -other words, four Cx rows (including padding) are exactly as long as -one Y row (including padding).</para> - - <example> - <title><constant>V4L2_PIX_FMT_YVU410</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>Y'<subscript>00</subscript></entry> - <entry>Y'<subscript>01</subscript></entry> - <entry>Y'<subscript>02</subscript></entry> - <entry>Y'<subscript>03</subscript></entry> - </row> - <row> - <entry>start + 4:</entry> - <entry>Y'<subscript>10</subscript></entry> - <entry>Y'<subscript>11</subscript></entry> - <entry>Y'<subscript>12</subscript></entry> - <entry>Y'<subscript>13</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>Y'<subscript>20</subscript></entry> - <entry>Y'<subscript>21</subscript></entry> - <entry>Y'<subscript>22</subscript></entry> - <entry>Y'<subscript>23</subscript></entry> - </row> - <row> - <entry>start + 12:</entry> - <entry>Y'<subscript>30</subscript></entry> - <entry>Y'<subscript>31</subscript></entry> - <entry>Y'<subscript>32</subscript></entry> - <entry>Y'<subscript>33</subscript></entry> - </row> - <row> - <entry>start + 16:</entry> - <entry>Cr<subscript>00</subscript></entry> - </row> - <row> - <entry>start + 17:</entry> - <entry>Cb<subscript>00</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - - <formalpara> - <title>Color Sample Location.</title> - <para> - <informaltable frame="none"> - <tgroup cols="7" align="center"> - <tbody valign="top"> - <row> - <entry></entry> - <entry>0</entry><entry></entry><entry>1</entry><entry></entry> - <entry>2</entry><entry></entry><entry>3</entry> - </row> - <row> - <entry>0</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - </row> - <row> - <entry>1</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - <entry></entry><entry></entry><entry></entry><entry>C</entry> - <entry></entry><entry></entry><entry></entry> - </row> - <row> - <entry>2</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - </row> - <row> - <entry>3</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuv411p.xml b/Documentation/DocBook/media/v4l/pixfmt-yuv411p.xml deleted file mode 100644 index 086dc731bf02..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-yuv411p.xml +++ /dev/null @@ -1,147 +0,0 @@ - <refentry id="V4L2-PIX-FMT-YUV411P"> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_YUV411P ('411P')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname><constant>V4L2_PIX_FMT_YUV411P</constant></refname> - <refpurpose>Format with ¼ horizontal chroma resolution, -also known as YUV 4:1:1. Planar layout as opposed to -<constant>V4L2_PIX_FMT_Y41P</constant></refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>This format is not commonly used. This is a planar -format similar to the 4:2:2 planar format except with half as many -chroma. The three components are separated into three sub-images or -planes. The Y plane is first. The Y plane has one byte per pixel. The -Cb plane immediately follows the Y plane in memory. The Cb plane is -¼ the width of the Y plane (and of the image). Each Cb belongs -to 4 pixels all on the same row. For example, -Cb<subscript>0</subscript> belongs to Y'<subscript>00</subscript>, -Y'<subscript>01</subscript>, Y'<subscript>02</subscript> and -Y'<subscript>03</subscript>. Following the Cb plane is the Cr plane, -just like the Cb plane.</para> - - <para>If the Y plane has pad bytes after each row, then the Cr -and Cb planes have ¼ as many pad bytes after their rows. In -other words, four C x rows (including padding) is exactly as long as -one Y row (including padding).</para> - - <example> - <title><constant>V4L2_PIX_FMT_YUV411P</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>Y'<subscript>00</subscript></entry> - <entry>Y'<subscript>01</subscript></entry> - <entry>Y'<subscript>02</subscript></entry> - <entry>Y'<subscript>03</subscript></entry> - </row> - <row> - <entry>start + 4:</entry> - <entry>Y'<subscript>10</subscript></entry> - <entry>Y'<subscript>11</subscript></entry> - <entry>Y'<subscript>12</subscript></entry> - <entry>Y'<subscript>13</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>Y'<subscript>20</subscript></entry> - <entry>Y'<subscript>21</subscript></entry> - <entry>Y'<subscript>22</subscript></entry> - <entry>Y'<subscript>23</subscript></entry> - </row> - <row> - <entry>start + 12:</entry> - <entry>Y'<subscript>30</subscript></entry> - <entry>Y'<subscript>31</subscript></entry> - <entry>Y'<subscript>32</subscript></entry> - <entry>Y'<subscript>33</subscript></entry> - </row> - <row> - <entry>start + 16:</entry> - <entry>Cb<subscript>00</subscript></entry> - </row> - <row> - <entry>start + 17:</entry> - <entry>Cb<subscript>10</subscript></entry> - </row> - <row> - <entry>start + 18:</entry> - <entry>Cb<subscript>20</subscript></entry> - </row> - <row> - <entry>start + 19:</entry> - <entry>Cb<subscript>30</subscript></entry> - </row> - <row> - <entry>start + 20:</entry> - <entry>Cr<subscript>00</subscript></entry> - </row> - <row> - <entry>start + 21:</entry> - <entry>Cr<subscript>10</subscript></entry> - </row> - <row> - <entry>start + 22:</entry> - <entry>Cr<subscript>20</subscript></entry> - </row> - <row> - <entry>start + 23:</entry> - <entry>Cr<subscript>30</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - - <formalpara> - <title>Color Sample Location.</title> - <para> - <informaltable frame="none"> - <tgroup cols="7" align="center"> - <tbody valign="top"> - <row> - <entry></entry> - <entry>0</entry><entry></entry><entry>1</entry><entry></entry> - <entry>2</entry><entry></entry><entry>3</entry> - </row> - <row> - <entry>0</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry>1</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry>2</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry>3</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuv420.xml b/Documentation/DocBook/media/v4l/pixfmt-yuv420.xml deleted file mode 100644 index 48649fac1596..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-yuv420.xml +++ /dev/null @@ -1,149 +0,0 @@ - <refentry> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_YVU420 ('YV12'), V4L2_PIX_FMT_YUV420 ('YU12')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname id="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></refname> - <refname id="V4L2-PIX-FMT-YUV420"><constant>V4L2_PIX_FMT_YUV420</constant></refname> - <refpurpose>Planar formats with ½ horizontal and -vertical chroma resolution, also known as YUV 4:2:0</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>These are planar formats, as opposed to a packed format. -The three components are separated into three sub- images or planes. -The Y plane is first. The Y plane has one byte per pixel. For -<constant>V4L2_PIX_FMT_YVU420</constant>, the Cr plane immediately -follows the Y plane in memory. The Cr plane is half the width and half -the height of the Y plane (and of the image). Each Cr belongs to four -pixels, a two-by-two square of the image. For example, -Cr<subscript>0</subscript> belongs to Y'<subscript>00</subscript>, -Y'<subscript>01</subscript>, Y'<subscript>10</subscript>, and -Y'<subscript>11</subscript>. Following the Cr plane is the Cb plane, -just like the Cr plane. <constant>V4L2_PIX_FMT_YUV420</constant> is -the same except the Cb plane comes first, then the Cr plane.</para> - - <para>If the Y plane has pad bytes after each row, then the Cr -and Cb planes have half as many pad bytes after their rows. In other -words, two Cx rows (including padding) is exactly as long as one Y row -(including padding).</para> - - <example> - <title><constant>V4L2_PIX_FMT_YVU420</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>Y'<subscript>00</subscript></entry> - <entry>Y'<subscript>01</subscript></entry> - <entry>Y'<subscript>02</subscript></entry> - <entry>Y'<subscript>03</subscript></entry> - </row> - <row> - <entry>start + 4:</entry> - <entry>Y'<subscript>10</subscript></entry> - <entry>Y'<subscript>11</subscript></entry> - <entry>Y'<subscript>12</subscript></entry> - <entry>Y'<subscript>13</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>Y'<subscript>20</subscript></entry> - <entry>Y'<subscript>21</subscript></entry> - <entry>Y'<subscript>22</subscript></entry> - <entry>Y'<subscript>23</subscript></entry> - </row> - <row> - <entry>start + 12:</entry> - <entry>Y'<subscript>30</subscript></entry> - <entry>Y'<subscript>31</subscript></entry> - <entry>Y'<subscript>32</subscript></entry> - <entry>Y'<subscript>33</subscript></entry> - </row> - <row> - <entry>start + 16:</entry> - <entry>Cr<subscript>00</subscript></entry> - <entry>Cr<subscript>01</subscript></entry> - </row> - <row> - <entry>start + 18:</entry> - <entry>Cr<subscript>10</subscript></entry> - <entry>Cr<subscript>11</subscript></entry> - </row> - <row> - <entry>start + 20:</entry> - <entry>Cb<subscript>00</subscript></entry> - <entry>Cb<subscript>01</subscript></entry> - </row> - <row> - <entry>start + 22:</entry> - <entry>Cb<subscript>10</subscript></entry> - <entry>Cb<subscript>11</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - - <formalpara> - <title>Color Sample Location.</title> - <para> - <informaltable frame="none"> - <tgroup cols="7" align="center"> - <tbody valign="top"> - <row> - <entry></entry> - <entry>0</entry><entry></entry><entry>1</entry><entry></entry> - <entry>2</entry><entry></entry><entry>3</entry> - </row> - <row> - <entry>0</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - <entry></entry><entry>C</entry><entry></entry><entry></entry> - <entry></entry><entry>C</entry><entry></entry> - </row> - <row> - <entry>1</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - </row> - <row> - <entry>2</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - <entry></entry><entry>C</entry><entry></entry><entry></entry> - <entry></entry><entry>C</entry><entry></entry> - </row> - <row> - <entry>3</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuv420m.xml b/Documentation/DocBook/media/v4l/pixfmt-yuv420m.xml deleted file mode 100644 index e781cc61786c..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-yuv420m.xml +++ /dev/null @@ -1,154 +0,0 @@ - <refentry id="V4L2-PIX-FMT-YUV420M"> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_YUV420M ('YM12')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname> <constant>V4L2_PIX_FMT_YUV420M</constant></refname> - <refpurpose>Variation of <constant>V4L2_PIX_FMT_YUV420</constant> - with planes non contiguous in memory. </refpurpose> - </refnamediv> - - <refsect1> - <title>Description</title> - - <para>This is a multi-planar format, as opposed to a packed format. -The three components are separated into three sub- images or planes. - -The Y plane is first. The Y plane has one byte per pixel. The Cb data -constitutes the second plane which is half the width and half -the height of the Y plane (and of the image). Each Cb belongs to four -pixels, a two-by-two square of the image. For example, -Cb<subscript>0</subscript> belongs to Y'<subscript>00</subscript>, -Y'<subscript>01</subscript>, Y'<subscript>10</subscript>, and -Y'<subscript>11</subscript>. The Cr data, just like the Cb plane, is -in the third plane. </para> - - <para>If the Y plane has pad bytes after each row, then the Cb -and Cr planes have half as many pad bytes after their rows. In other -words, two Cx rows (including padding) is exactly as long as one Y row -(including padding).</para> - - <para><constant>V4L2_PIX_FMT_YUV420M</constant> is intended to be -used only in drivers and applications that support the multi-planar API, -described in <xref linkend="planar-apis"/>. </para> - - <example> - <title><constant>V4L2_PIX_FMT_YUV420M</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start0 + 0:</entry> - <entry>Y'<subscript>00</subscript></entry> - <entry>Y'<subscript>01</subscript></entry> - <entry>Y'<subscript>02</subscript></entry> - <entry>Y'<subscript>03</subscript></entry> - </row> - <row> - <entry>start0 + 4:</entry> - <entry>Y'<subscript>10</subscript></entry> - <entry>Y'<subscript>11</subscript></entry> - <entry>Y'<subscript>12</subscript></entry> - <entry>Y'<subscript>13</subscript></entry> - </row> - <row> - <entry>start0 + 8:</entry> - <entry>Y'<subscript>20</subscript></entry> - <entry>Y'<subscript>21</subscript></entry> - <entry>Y'<subscript>22</subscript></entry> - <entry>Y'<subscript>23</subscript></entry> - </row> - <row> - <entry>start0 + 12:</entry> - <entry>Y'<subscript>30</subscript></entry> - <entry>Y'<subscript>31</subscript></entry> - <entry>Y'<subscript>32</subscript></entry> - <entry>Y'<subscript>33</subscript></entry> - </row> - <row><entry></entry></row> - <row> - <entry>start1 + 0:</entry> - <entry>Cb<subscript>00</subscript></entry> - <entry>Cb<subscript>01</subscript></entry> - </row> - <row> - <entry>start1 + 2:</entry> - <entry>Cb<subscript>10</subscript></entry> - <entry>Cb<subscript>11</subscript></entry> - </row> - <row><entry></entry></row> - <row> - <entry>start2 + 0:</entry> - <entry>Cr<subscript>00</subscript></entry> - <entry>Cr<subscript>01</subscript></entry> - </row> - <row> - <entry>start2 + 2:</entry> - <entry>Cr<subscript>10</subscript></entry> - <entry>Cr<subscript>11</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - - <formalpara> - <title>Color Sample Location.</title> - <para> - <informaltable frame="none"> - <tgroup cols="7" align="center"> - <tbody valign="top"> - <row> - <entry></entry> - <entry>0</entry><entry></entry><entry>1</entry><entry></entry> - <entry>2</entry><entry></entry><entry>3</entry> - </row> - <row> - <entry>0</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - <entry></entry><entry>C</entry><entry></entry><entry></entry> - <entry></entry><entry>C</entry><entry></entry> - </row> - <row> - <entry>1</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - </row> - <row> - <entry>2</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - <entry></entry><entry>C</entry><entry></entry><entry></entry> - <entry></entry><entry>C</entry><entry></entry> - </row> - <row> - <entry>3</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuv422p.xml b/Documentation/DocBook/media/v4l/pixfmt-yuv422p.xml deleted file mode 100644 index 4ce6463fe0a5..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-yuv422p.xml +++ /dev/null @@ -1,153 +0,0 @@ - <refentry id="V4L2-PIX-FMT-YUV422P"> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_YUV422P ('422P')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname><constant>V4L2_PIX_FMT_YUV422P</constant></refname> - <refpurpose>Format with ½ horizontal chroma resolution, -also known as YUV 4:2:2. Planar layout as opposed to -<constant>V4L2_PIX_FMT_YUYV</constant></refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>This format is not commonly used. This is a planar -version of the YUYV format. The three components are separated into -three sub-images or planes. The Y plane is first. The Y plane has one -byte per pixel. The Cb plane immediately follows the Y plane in -memory. The Cb plane is half the width of the Y plane (and of the -image). Each Cb belongs to two pixels. For example, -Cb<subscript>0</subscript> belongs to Y'<subscript>00</subscript>, -Y'<subscript>01</subscript>. Following the Cb plane is the Cr plane, -just like the Cb plane.</para> - - <para>If the Y plane has pad bytes after each row, then the Cr -and Cb planes have half as many pad bytes after their rows. In other -words, two Cx rows (including padding) is exactly as long as one Y row -(including padding).</para> - - <example> - <title><constant>V4L2_PIX_FMT_YUV422P</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>Y'<subscript>00</subscript></entry> - <entry>Y'<subscript>01</subscript></entry> - <entry>Y'<subscript>02</subscript></entry> - <entry>Y'<subscript>03</subscript></entry> - </row> - <row> - <entry>start + 4:</entry> - <entry>Y'<subscript>10</subscript></entry> - <entry>Y'<subscript>11</subscript></entry> - <entry>Y'<subscript>12</subscript></entry> - <entry>Y'<subscript>13</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>Y'<subscript>20</subscript></entry> - <entry>Y'<subscript>21</subscript></entry> - <entry>Y'<subscript>22</subscript></entry> - <entry>Y'<subscript>23</subscript></entry> - </row> - <row> - <entry>start + 12:</entry> - <entry>Y'<subscript>30</subscript></entry> - <entry>Y'<subscript>31</subscript></entry> - <entry>Y'<subscript>32</subscript></entry> - <entry>Y'<subscript>33</subscript></entry> - </row> - <row> - <entry>start + 16:</entry> - <entry>Cb<subscript>00</subscript></entry> - <entry>Cb<subscript>01</subscript></entry> - </row> - <row> - <entry>start + 18:</entry> - <entry>Cb<subscript>10</subscript></entry> - <entry>Cb<subscript>11</subscript></entry> - </row> - <row> - <entry>start + 20:</entry> - <entry>Cb<subscript>20</subscript></entry> - <entry>Cb<subscript>21</subscript></entry> - </row> - <row> - <entry>start + 22:</entry> - <entry>Cb<subscript>30</subscript></entry> - <entry>Cb<subscript>31</subscript></entry> - </row> - <row> - <entry>start + 24:</entry> - <entry>Cr<subscript>00</subscript></entry> - <entry>Cr<subscript>01</subscript></entry> - </row> - <row> - <entry>start + 26:</entry> - <entry>Cr<subscript>10</subscript></entry> - <entry>Cr<subscript>11</subscript></entry> - </row> - <row> - <entry>start + 28:</entry> - <entry>Cr<subscript>20</subscript></entry> - <entry>Cr<subscript>21</subscript></entry> - </row> - <row> - <entry>start + 30:</entry> - <entry>Cr<subscript>30</subscript></entry> - <entry>Cr<subscript>31</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - - <formalpara> - <title>Color Sample Location.</title> - <para> - <informaltable frame="none"> - <tgroup cols="7" align="center"> - <tbody valign="top"> - <row> - <entry></entry> - <entry>0</entry><entry></entry><entry>1</entry><entry></entry> - <entry>2</entry><entry></entry><entry>3</entry> - </row> - <row> - <entry>0</entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry> - </row> - <row> - <entry>1</entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry> - </row> - <row> - <entry>2</entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry> - </row> - <row> - <entry>3</entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuyv.xml b/Documentation/DocBook/media/v4l/pixfmt-yuyv.xml deleted file mode 100644 index 58384092251a..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-yuyv.xml +++ /dev/null @@ -1,120 +0,0 @@ - <refentry id="V4L2-PIX-FMT-YUYV"> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_YUYV ('YUYV')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname><constant>V4L2_PIX_FMT_YUYV</constant></refname> - <refpurpose>Packed format with ½ horizontal chroma -resolution, also known as YUV 4:2:2</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>In this format each four bytes is two pixels. Each four -bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and -the Cb and Cr belong to both pixels. As you can see, the Cr and Cb -components have half the horizontal resolution of the Y component. -<constant>V4L2_PIX_FMT_YUYV </constant> is known in the Windows -environment as YUY2.</para> - - <example> - <title><constant>V4L2_PIX_FMT_YUYV</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="9" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>Y'<subscript>00</subscript></entry> - <entry>Cb<subscript>00</subscript></entry> - <entry>Y'<subscript>01</subscript></entry> - <entry>Cr<subscript>00</subscript></entry> - <entry>Y'<subscript>02</subscript></entry> - <entry>Cb<subscript>01</subscript></entry> - <entry>Y'<subscript>03</subscript></entry> - <entry>Cr<subscript>01</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>Y'<subscript>10</subscript></entry> - <entry>Cb<subscript>10</subscript></entry> - <entry>Y'<subscript>11</subscript></entry> - <entry>Cr<subscript>10</subscript></entry> - <entry>Y'<subscript>12</subscript></entry> - <entry>Cb<subscript>11</subscript></entry> - <entry>Y'<subscript>13</subscript></entry> - <entry>Cr<subscript>11</subscript></entry> - </row> - <row> - <entry>start + 16:</entry> - <entry>Y'<subscript>20</subscript></entry> - <entry>Cb<subscript>20</subscript></entry> - <entry>Y'<subscript>21</subscript></entry> - <entry>Cr<subscript>20</subscript></entry> - <entry>Y'<subscript>22</subscript></entry> - <entry>Cb<subscript>21</subscript></entry> - <entry>Y'<subscript>23</subscript></entry> - <entry>Cr<subscript>21</subscript></entry> - </row> - <row> - <entry>start + 24:</entry> - <entry>Y'<subscript>30</subscript></entry> - <entry>Cb<subscript>30</subscript></entry> - <entry>Y'<subscript>31</subscript></entry> - <entry>Cr<subscript>30</subscript></entry> - <entry>Y'<subscript>32</subscript></entry> - <entry>Cb<subscript>31</subscript></entry> - <entry>Y'<subscript>33</subscript></entry> - <entry>Cr<subscript>31</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - - <formalpara> - <title>Color Sample Location.</title> - <para> - <informaltable frame="none"> - <tgroup cols="7" align="center"> - <tbody valign="top"> - <row> - <entry></entry> - <entry>0</entry><entry></entry><entry>1</entry><entry></entry> - <entry>2</entry><entry></entry><entry>3</entry> - </row> - <row> - <entry>0</entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry> - </row> - <row> - <entry>1</entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry> - </row> - <row> - <entry>2</entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry> - </row> - <row> - <entry>3</entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-yvu420m.xml b/Documentation/DocBook/media/v4l/pixfmt-yvu420m.xml deleted file mode 100644 index 2330667907c7..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-yvu420m.xml +++ /dev/null @@ -1,154 +0,0 @@ - <refentry id="V4L2-PIX-FMT-YVU420M"> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_YVU420M ('YM21')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname> <constant>V4L2_PIX_FMT_YVU420M</constant></refname> - <refpurpose>Variation of <constant>V4L2_PIX_FMT_YVU420</constant> - with planes non contiguous in memory. </refpurpose> - </refnamediv> - - <refsect1> - <title>Description</title> - - <para>This is a multi-planar format, as opposed to a packed format. -The three components are separated into three sub-images or planes. - -The Y plane is first. The Y plane has one byte per pixel. The Cr data -constitutes the second plane which is half the width and half -the height of the Y plane (and of the image). Each Cr belongs to four -pixels, a two-by-two square of the image. For example, -Cr<subscript>0</subscript> belongs to Y'<subscript>00</subscript>, -Y'<subscript>01</subscript>, Y'<subscript>10</subscript>, and -Y'<subscript>11</subscript>. The Cb data, just like the Cr plane, constitutes -the third plane. </para> - - <para>If the Y plane has pad bytes after each row, then the Cr -and Cb planes have half as many pad bytes after their rows. In other -words, two Cx rows (including padding) is exactly as long as one Y row -(including padding).</para> - - <para><constant>V4L2_PIX_FMT_YVU420M</constant> is intended to be -used only in drivers and applications that support the multi-planar API, -described in <xref linkend="planar-apis"/>. </para> - - <example> - <title><constant>V4L2_PIX_FMT_YVU420M</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start0 + 0:</entry> - <entry>Y'<subscript>00</subscript></entry> - <entry>Y'<subscript>01</subscript></entry> - <entry>Y'<subscript>02</subscript></entry> - <entry>Y'<subscript>03</subscript></entry> - </row> - <row> - <entry>start0 + 4:</entry> - <entry>Y'<subscript>10</subscript></entry> - <entry>Y'<subscript>11</subscript></entry> - <entry>Y'<subscript>12</subscript></entry> - <entry>Y'<subscript>13</subscript></entry> - </row> - <row> - <entry>start0 + 8:</entry> - <entry>Y'<subscript>20</subscript></entry> - <entry>Y'<subscript>21</subscript></entry> - <entry>Y'<subscript>22</subscript></entry> - <entry>Y'<subscript>23</subscript></entry> - </row> - <row> - <entry>start0 + 12:</entry> - <entry>Y'<subscript>30</subscript></entry> - <entry>Y'<subscript>31</subscript></entry> - <entry>Y'<subscript>32</subscript></entry> - <entry>Y'<subscript>33</subscript></entry> - </row> - <row><entry></entry></row> - <row> - <entry>start1 + 0:</entry> - <entry>Cr<subscript>00</subscript></entry> - <entry>Cr<subscript>01</subscript></entry> - </row> - <row> - <entry>start1 + 2:</entry> - <entry>Cr<subscript>10</subscript></entry> - <entry>Cr<subscript>11</subscript></entry> - </row> - <row><entry></entry></row> - <row> - <entry>start2 + 0:</entry> - <entry>Cb<subscript>00</subscript></entry> - <entry>Cb<subscript>01</subscript></entry> - </row> - <row> - <entry>start2 + 2:</entry> - <entry>Cb<subscript>10</subscript></entry> - <entry>Cb<subscript>11</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - - <formalpara> - <title>Color Sample Location.</title> - <para> - <informaltable frame="none"> - <tgroup cols="7" align="center"> - <tbody valign="top"> - <row> - <entry></entry> - <entry>0</entry><entry></entry><entry>1</entry><entry></entry> - <entry>2</entry><entry></entry><entry>3</entry> - </row> - <row> - <entry>0</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - <entry></entry><entry>C</entry><entry></entry><entry></entry> - <entry></entry><entry>C</entry><entry></entry> - </row> - <row> - <entry>1</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - </row> - <row> - <entry>2</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - <entry></entry><entry>C</entry><entry></entry><entry></entry> - <entry></entry><entry>C</entry><entry></entry> - </row> - <row> - <entry>3</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-yvyu.xml b/Documentation/DocBook/media/v4l/pixfmt-yvyu.xml deleted file mode 100644 index bfffdc76d3da..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt-yvyu.xml +++ /dev/null @@ -1,120 +0,0 @@ - <refentry id="V4L2-PIX-FMT-YVYU"> - <refmeta> - <refentrytitle>V4L2_PIX_FMT_YVYU ('YVYU')</refentrytitle> - &manvol; - </refmeta> - <refnamediv> - <refname><constant>V4L2_PIX_FMT_YVYU</constant></refname> - <refpurpose>Variation of -<constant>V4L2_PIX_FMT_YUYV</constant> with different order of samples -in memory</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - - <para>In this format each four bytes is two pixels. Each four -bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and -the Cb and Cr belong to both pixels. As you can see, the Cr and Cb -components have half the horizontal resolution of the Y -component.</para> - - <example> - <title><constant>V4L2_PIX_FMT_YVYU</constant> 4 × 4 -pixel image</title> - - <formalpara> - <title>Byte Order.</title> - <para>Each cell is one byte. - <informaltable frame="none"> - <tgroup cols="9" align="center"> - <colspec align="left" colwidth="2*" /> - <tbody valign="top"> - <row> - <entry>start + 0:</entry> - <entry>Y'<subscript>00</subscript></entry> - <entry>Cr<subscript>00</subscript></entry> - <entry>Y'<subscript>01</subscript></entry> - <entry>Cb<subscript>00</subscript></entry> - <entry>Y'<subscript>02</subscript></entry> - <entry>Cr<subscript>01</subscript></entry> - <entry>Y'<subscript>03</subscript></entry> - <entry>Cb<subscript>01</subscript></entry> - </row> - <row> - <entry>start + 8:</entry> - <entry>Y'<subscript>10</subscript></entry> - <entry>Cr<subscript>10</subscript></entry> - <entry>Y'<subscript>11</subscript></entry> - <entry>Cb<subscript>10</subscript></entry> - <entry>Y'<subscript>12</subscript></entry> - <entry>Cr<subscript>11</subscript></entry> - <entry>Y'<subscript>13</subscript></entry> - <entry>Cb<subscript>11</subscript></entry> - </row> - <row> - <entry>start + 16:</entry> - <entry>Y'<subscript>20</subscript></entry> - <entry>Cr<subscript>20</subscript></entry> - <entry>Y'<subscript>21</subscript></entry> - <entry>Cb<subscript>20</subscript></entry> - <entry>Y'<subscript>22</subscript></entry> - <entry>Cr<subscript>21</subscript></entry> - <entry>Y'<subscript>23</subscript></entry> - <entry>Cb<subscript>21</subscript></entry> - </row> - <row> - <entry>start + 24:</entry> - <entry>Y'<subscript>30</subscript></entry> - <entry>Cr<subscript>30</subscript></entry> - <entry>Y'<subscript>31</subscript></entry> - <entry>Cb<subscript>30</subscript></entry> - <entry>Y'<subscript>32</subscript></entry> - <entry>Cr<subscript>31</subscript></entry> - <entry>Y'<subscript>33</subscript></entry> - <entry>Cb<subscript>31</subscript></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - - <formalpara> - <title>Color Sample Location.</title> - <para> - <informaltable frame="none"> - <tgroup cols="7" align="center"> - <tbody valign="top"> - <row> - <entry></entry> - <entry>0</entry><entry></entry><entry>1</entry><entry></entry> - <entry>2</entry><entry></entry><entry>3</entry> - </row> - <row> - <entry>0</entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry> - </row> - <row> - <entry>1</entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry> - </row> - <row> - <entry>2</entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry> - </row> - <row> - <entry>3</entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry>C</entry><entry>Y</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </formalpara> - </example> - </refsect1> - </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt.xml b/Documentation/DocBook/media/v4l/pixfmt.xml deleted file mode 100644 index d871245d2973..000000000000 --- a/Documentation/DocBook/media/v4l/pixfmt.xml +++ /dev/null @@ -1,1992 +0,0 @@ - <title>Image Formats</title> - - <para>The V4L2 API was primarily designed for devices exchanging -image data with applications. The -<structname>v4l2_pix_format</structname> and <structname>v4l2_pix_format_mplane -</structname> structures define the format and layout of an image in memory. -The former is used with the single-planar API, while the latter is used with the -multi-planar version (see <xref linkend="planar-apis"/>). Image formats are -negotiated with the &VIDIOC-S-FMT; ioctl. (The explanations here focus on video -capturing and output, for overlay frame buffer formats see also -&VIDIOC-G-FBUF;.)</para> - -<section> - <title>Single-planar format structure</title> - <table pgwide="1" frame="none" id="v4l2-pix-format"> - <title>struct <structname>v4l2_pix_format</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>width</structfield></entry> - <entry>Image width in pixels.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>height</structfield></entry> - <entry>Image height in pixels. If <structfield>field</structfield> is - one of <constant>V4L2_FIELD_TOP</constant>, <constant>V4L2_FIELD_BOTTOM</constant> - or <constant>V4L2_FIELD_ALTERNATE</constant> then height refers to the - number of lines in the field, otherwise it refers to the number of - lines in the frame (which is twice the field height for interlaced - formats).</entry> - </row> - <row> - <entry spanname="hspan">Applications set these fields to -request an image size, drivers return the closest possible values. In -case of planar formats the <structfield>width</structfield> and -<structfield>height</structfield> applies to the largest plane. To -avoid ambiguities drivers must return values rounded up to a multiple -of the scale factor of any smaller planes. For example when the image -format is YUV 4:2:0, <structfield>width</structfield> and -<structfield>height</structfield> must be multiples of two.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>pixelformat</structfield></entry> - <entry>The pixel format or type of compression, set by the -application. This is a little endian <link -linkend="v4l2-fourcc">four character code</link>. V4L2 defines -standard RGB formats in <xref linkend="rgb-formats" />, YUV formats in <xref -linkend="yuv-formats" />, and reserved codes in <xref -linkend="reserved-formats" /></entry> - </row> - <row> - <entry>&v4l2-field;</entry> - <entry><structfield>field</structfield></entry> - <entry>Video images are typically interlaced. Applications -can request to capture or output only the top or bottom field, or both -fields interlaced or sequentially stored in one buffer or alternating -in separate buffers. Drivers return the actual field order selected. -For more details on fields see <xref linkend="field-order" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>bytesperline</structfield></entry> - <entry>Distance in bytes between the leftmost pixels in two -adjacent lines.</entry> - </row> - <row> - <entry spanname="hspan"><para>Both applications and drivers -can set this field to request padding bytes at the end of each line. -Drivers however may ignore the value requested by the application, -returning <structfield>width</structfield> times bytes per pixel or a -larger value required by the hardware. That implies applications can -just set this field to zero to get a reasonable -default.</para><para>Video hardware may access padding bytes, -therefore they must reside in accessible memory. Consider cases where -padding bytes after the last line of an image cross a system page -boundary. Input devices may write padding bytes, the value is -undefined. Output devices ignore the contents of padding -bytes.</para><para>When the image format is planar the -<structfield>bytesperline</structfield> value applies to the first -plane and is divided by the same factor as the -<structfield>width</structfield> field for the other planes. For -example the Cb and Cr planes of a YUV 4:2:0 image have half as many -padding bytes following each line as the Y plane. To avoid ambiguities -drivers must return a <structfield>bytesperline</structfield> value -rounded up to a multiple of the scale factor.</para> -<para>For compressed formats the <structfield>bytesperline</structfield> -value makes no sense. Applications and drivers must set this to 0 in -that case.</para></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>sizeimage</structfield></entry> - <entry>Size in bytes of the buffer to hold a complete image, -set by the driver. Usually this is -<structfield>bytesperline</structfield> times -<structfield>height</structfield>. When the image consists of variable -length compressed data this is the maximum number of bytes required to -hold an image.</entry> - </row> - <row> - <entry>&v4l2-colorspace;</entry> - <entry><structfield>colorspace</structfield></entry> - <entry>This information supplements the -<structfield>pixelformat</structfield> and must be set by the driver for -capture streams and by the application for output streams, -see <xref linkend="colorspaces" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>priv</structfield></entry> - <entry><para>This field indicates whether the remaining fields of the -<structname>v4l2_pix_format</structname> structure, also called the extended -fields, are valid. When set to <constant>V4L2_PIX_FMT_PRIV_MAGIC</constant>, it -indicates that the extended fields have been correctly initialized. When set to -any other value it indicates that the extended fields contain undefined values. -</para> -<para>Applications that wish to use the pixel format extended fields must first -ensure that the feature is supported by querying the device for the -<link linkend="querycap"><constant>V4L2_CAP_EXT_PIX_FORMAT</constant></link> -capability. If the capability isn't set the pixel format extended fields are not -supported and using the extended fields will lead to undefined results.</para> -<para>To use the extended fields, applications must set the -<structfield>priv</structfield> field to -<constant>V4L2_PIX_FMT_PRIV_MAGIC</constant>, initialize all the extended fields -and zero the unused bytes of the <structname>v4l2_format</structname> -<structfield>raw_data</structfield> field.</para> -<para>When the <structfield>priv</structfield> field isn't set to -<constant>V4L2_PIX_FMT_PRIV_MAGIC</constant> drivers must act as if all the -extended fields were set to zero. On return drivers must set the -<structfield>priv</structfield> field to -<constant>V4L2_PIX_FMT_PRIV_MAGIC</constant> and all the extended fields to -applicable values.</para></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry>Flags set by the application or driver, see <xref -linkend="format-flags" />.</entry> - </row> - <row> - <entry>&v4l2-ycbcr-encoding;</entry> - <entry><structfield>ycbcr_enc</structfield></entry> - <entry>This information supplements the -<structfield>colorspace</structfield> and must be set by the driver for -capture streams and by the application for output streams, -see <xref linkend="colorspaces" />.</entry> - </row> - <row> - <entry>&v4l2-quantization;</entry> - <entry><structfield>quantization</structfield></entry> - <entry>This information supplements the -<structfield>colorspace</structfield> and must be set by the driver for -capture streams and by the application for output streams, -see <xref linkend="colorspaces" />.</entry> - </row> - <row> - <entry>&v4l2-xfer-func;</entry> - <entry><structfield>xfer_func</structfield></entry> - <entry>This information supplements the -<structfield>colorspace</structfield> and must be set by the driver for -capture streams and by the application for output streams, -see <xref linkend="colorspaces" />.</entry> - </row> - </tbody> - </tgroup> - </table> -</section> - -<section> - <title>Multi-planar format structures</title> - <para>The <structname>v4l2_plane_pix_format</structname> structures define - size and layout for each of the planes in a multi-planar format. - The <structname>v4l2_pix_format_mplane</structname> structure contains - information common to all planes (such as image width and height) and - an array of <structname>v4l2_plane_pix_format</structname> structures, - describing all planes of that format.</para> - <table pgwide="1" frame="none" id="v4l2-plane-pix-format"> - <title>struct <structname>v4l2_plane_pix_format</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>sizeimage</structfield></entry> - <entry>Maximum size in bytes required for image data in this plane. - </entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>bytesperline</structfield></entry> - <entry>Distance in bytes between the leftmost pixels in two adjacent - lines. See &v4l2-pix-format;.</entry> - </row> - <row> - <entry>__u16</entry> - <entry><structfield>reserved[6]</structfield></entry> - <entry>Reserved for future extensions. Should be zeroed by drivers and - applications.</entry> - </row> - </tbody> - </tgroup> - </table> - <table pgwide="1" frame="none" id="v4l2-pix-format-mplane"> - <title>struct <structname>v4l2_pix_format_mplane</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>width</structfield></entry> - <entry>Image width in pixels. See &v4l2-pix-format;.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>height</structfield></entry> - <entry>Image height in pixels. See &v4l2-pix-format;.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>pixelformat</structfield></entry> - <entry>The pixel format. Both single- and multi-planar four character -codes can be used.</entry> - </row> - <row> - <entry>&v4l2-field;</entry> - <entry><structfield>field</structfield></entry> - <entry>See &v4l2-pix-format;.</entry> - </row> - <row> - <entry>&v4l2-colorspace;</entry> - <entry><structfield>colorspace</structfield></entry> - <entry>See &v4l2-pix-format;.</entry> - </row> - <row> - <entry>&v4l2-plane-pix-format;</entry> - <entry><structfield>plane_fmt[VIDEO_MAX_PLANES]</structfield></entry> - <entry>An array of structures describing format of each plane this - pixel format consists of. The number of valid entries in this array - has to be put in the <structfield>num_planes</structfield> - field.</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>num_planes</structfield></entry> - <entry>Number of planes (i.e. separate memory buffers) for this format - and the number of valid entries in the - <structfield>plane_fmt</structfield> array.</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>flags</structfield></entry> - <entry>Flags set by the application or driver, see <xref -linkend="format-flags" />.</entry> - </row> - <row> - <entry>&v4l2-ycbcr-encoding;</entry> - <entry><structfield>ycbcr_enc</structfield></entry> - <entry>This information supplements the -<structfield>colorspace</structfield> and must be set by the driver for -capture streams and by the application for output streams, -see <xref linkend="colorspaces" />.</entry> - </row> - <row> - <entry>&v4l2-quantization;</entry> - <entry><structfield>quantization</structfield></entry> - <entry>This information supplements the -<structfield>colorspace</structfield> and must be set by the driver for -capture streams and by the application for output streams, -see <xref linkend="colorspaces" />.</entry> - </row> - <row> - <entry>&v4l2-xfer-func;</entry> - <entry><structfield>xfer_func</structfield></entry> - <entry>This information supplements the -<structfield>colorspace</structfield> and must be set by the driver for -capture streams and by the application for output streams, -see <xref linkend="colorspaces" />.</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>reserved[7]</structfield></entry> - <entry>Reserved for future extensions. Should be zeroed by drivers - and applications.</entry> - </row> - </tbody> - </tgroup> - </table> -</section> - - <section> - <title>Standard Image Formats</title> - - <para>In order to exchange images between drivers and -applications, it is necessary to have standard image data formats -which both sides will interpret the same way. V4L2 includes several -such formats, and this section is intended to be an unambiguous -specification of the standard image data formats in V4L2.</para> - - <para>V4L2 drivers are not limited to these formats, however. -Driver-specific formats are possible. In that case the application may -depend on a codec to convert images to one of the standard formats -when needed. But the data can still be stored and retrieved in the -proprietary format. For example, a device may support a proprietary -compressed format. Applications can still capture and save the data in -the compressed format, saving much disk space, and later use a codec -to convert the images to the X Windows screen format when the video is -to be displayed.</para> - - <para>Even so, ultimately, some standard formats are needed, so -the V4L2 specification would not be complete without well-defined -standard formats.</para> - - <para>The V4L2 standard formats are mainly uncompressed formats. The -pixels are always arranged in memory from left to right, and from top -to bottom. The first byte of data in the image buffer is always for -the leftmost pixel of the topmost row. Following that is the pixel -immediately to its right, and so on until the end of the top row of -pixels. Following the rightmost pixel of the row there may be zero or -more bytes of padding to guarantee that each row of pixel data has a -certain alignment. Following the pad bytes, if any, is data for the -leftmost pixel of the second row from the top, and so on. The last row -has just as many pad bytes after it as the other rows.</para> - - <para>In V4L2 each format has an identifier which looks like -<constant>PIX_FMT_XXX</constant>, defined in the <link -linkend="videodev">videodev2.h</link> header file. These identifiers -represent <link linkend="v4l2-fourcc">four character (FourCC) codes</link> -which are also listed below, however they are not the same as those -used in the Windows world.</para> - - <para>For some formats, data is stored in separate, discontiguous -memory buffers. Those formats are identified by a separate set of FourCC codes -and are referred to as "multi-planar formats". For example, a YUV422 frame is -normally stored in one memory buffer, but it can also be placed in two or three -separate buffers, with Y component in one buffer and CbCr components in another -in the 2-planar version or with each component in its own buffer in the -3-planar case. Those sub-buffers are referred to as "planes".</para> - </section> - - <section id="colorspaces"> - <title>Colorspaces</title> - - <para>'Color' is a very complex concept and depends on physics, chemistry and -biology. Just because you have three numbers that describe the 'red', 'green' -and 'blue' components of the color of a pixel does not mean that you can accurately -display that color. A colorspace defines what it actually <emphasis>means</emphasis> -to have an RGB value of e.g. (255, 0, 0). That is, which color should be -reproduced on the screen in a perfectly calibrated environment.</para> - - <para>In order to do that we first need to have a good definition of -color, i.e. some way to uniquely and unambiguously define a color so that someone -else can reproduce it. Human color vision is trichromatic since the human eye has -color receptors that are sensitive to three different wavelengths of light. Hence -the need to use three numbers to describe color. Be glad you are not a mantis shrimp -as those are sensitive to 12 different wavelengths, so instead of RGB we would be -using the ABCDEFGHIJKL colorspace...</para> - - <para>Color exists only in the eye and brain and is the result of how strongly -color receptors are stimulated. This is based on the Spectral -Power Distribution (SPD) which is a graph showing the intensity (radiant power) -of the light at wavelengths covering the visible spectrum as it enters the eye. -The science of colorimetry is about the relationship between the SPD and color as -perceived by the human brain.</para> - - <para>Since the human eye has only three color receptors it is perfectly -possible that different SPDs will result in the same stimulation of those receptors -and are perceived as the same color, even though the SPD of the light is -different.</para> - - <para>In the 1920s experiments were devised to determine the relationship -between SPDs and the perceived color and that resulted in the CIE 1931 standard -that defines spectral weighting functions that model the perception of color. -Specifically that standard defines functions that can take an SPD and calculate -the stimulus for each color receptor. After some further mathematical transforms -these stimuli are known as the <emphasis>CIE XYZ tristimulus</emphasis> values -and these X, Y and Z values describe a color as perceived by a human unambiguously. -These X, Y and Z values are all in the range [0…1].</para> - - <para>The Y value in the CIE XYZ colorspace corresponds to luminance. Often -the CIE XYZ colorspace is transformed to the normalized CIE xyY colorspace:</para> - - <para>x = X / (X + Y + Z)</para> - <para>y = Y / (X + Y + Z)</para> - - <para>The x and y values are the chromaticity coordinates and can be used to -define a color without the luminance component Y. It is very confusing to -have such similar names for these colorspaces. Just be aware that if colors -are specified with lower case 'x' and 'y', then the CIE xyY colorspace is -used. Upper case 'X' and 'Y' refer to the CIE XYZ colorspace. Also, y has nothing -to do with luminance. Together x and y specify a color, and Y the luminance. -That is really all you need to remember from a practical point of view. At -the end of this section you will find reading resources that go into much more -detail if you are interested. -</para> - - <para>A monitor or TV will reproduce colors by emitting light at three -different wavelengths, the combination of which will stimulate the color receptors -in the eye and thus cause the perception of color. Historically these wavelengths -were defined by the red, green and blue phosphors used in the displays. These -<emphasis>color primaries</emphasis> are part of what defines a colorspace.</para> - - <para>Different display devices will have different primaries and some -primaries are more suitable for some display technologies than others. This has -resulted in a variety of colorspaces that are used for different display -technologies or uses. To define a colorspace you need to define the three -color primaries (these are typically defined as x, y chromaticity coordinates -from the CIE xyY colorspace) but also the white reference: that is the color obtained -when all three primaries are at maximum power. This determines the relative power -or energy of the primaries. This is usually chosen to be close to daylight which has -been defined as the CIE D65 Illuminant.</para> - - <para>To recapitulate: the CIE XYZ colorspace uniquely identifies colors. -Other colorspaces are defined by three chromaticity coordinates defined in the -CIE xyY colorspace. Based on those a 3x3 matrix can be constructed that -transforms CIE XYZ colors to colors in the new colorspace. -</para> - - <para>Both the CIE XYZ and the RGB colorspace that are derived from the -specific chromaticity primaries are linear colorspaces. But neither the eye, -nor display technology is linear. Doubling the values of all components in -the linear colorspace will not be perceived as twice the intensity of the color. -So each colorspace also defines a transfer function that takes a linear color -component value and transforms it to the non-linear component value, which is a -closer match to the non-linear performance of both the eye and displays. Linear -component values are denoted RGB, non-linear are denoted as R'G'B'. In general -colors used in graphics are all R'G'B', except in openGL which uses linear RGB. -Special care should be taken when dealing with openGL to provide linear RGB colors -or to use the built-in openGL support to apply the inverse transfer function.</para> - - <para>The final piece that defines a colorspace is a function that -transforms non-linear R'G'B' to non-linear Y'CbCr. This function is determined -by the so-called luma coefficients. There may be multiple possible Y'CbCr -encodings allowed for the same colorspace. Many encodings of color -prefer to use luma (Y') and chroma (CbCr) instead of R'G'B'. Since the human -eye is more sensitive to differences in luminance than in color this encoding -allows one to reduce the amount of color information compared to the luma -data. Note that the luma (Y') is unrelated to the Y in the CIE XYZ colorspace. -Also note that Y'CbCr is often called YCbCr or YUV even though these are -strictly speaking wrong.</para> - - <para>Sometimes people confuse Y'CbCr as being a colorspace. This is not -correct, it is just an encoding of an R'G'B' color into luma and chroma -values. The underlying colorspace that is associated with the R'G'B' color -is also associated with the Y'CbCr color.</para> - - <para>The final step is how the RGB, R'G'B' or Y'CbCr values are -quantized. The CIE XYZ colorspace where X, Y and Z are in the range -[0…1] describes all colors that humans can perceive, but the transform to -another colorspace will produce colors that are outside the [0…1] range. -Once clamped to the [0…1] range those colors can no longer be reproduced -in that colorspace. This clamping is what reduces the extent or gamut of the -colorspace. How the range of [0…1] is translated to integer values in the -range of [0…255] (or higher, depending on the color depth) is called the -quantization. This is <emphasis>not</emphasis> part of the colorspace -definition. In practice RGB or R'G'B' values are full range, i.e. they -use the full [0…255] range. Y'CbCr values on the other hand are limited -range with Y' using [16…235] and Cb and Cr using [16…240].</para> - - <para>Unfortunately, in some cases limited range RGB is also used -where the components use the range [16…235]. And full range Y'CbCr also exists -using the [0…255] range.</para> - - <para>In order to correctly interpret a color you need to know the -quantization range, whether it is R'G'B' or Y'CbCr, the used Y'CbCr encoding -and the colorspace. -From that information you can calculate the corresponding CIE XYZ color -and map that again to whatever colorspace your display device uses.</para> - - <para>The colorspace definition itself consists of the three -chromaticity primaries, the white reference chromaticity, a transfer -function and the luma coefficients needed to transform R'G'B' to Y'CbCr. While -some colorspace standards correctly define all four, quite often the colorspace -standard only defines some, and you have to rely on other standards for -the missing pieces. The fact that colorspaces are often a mix of different -standards also led to very confusing naming conventions where the name of -a standard was used to name a colorspace when in fact that standard was -part of various other colorspaces as well.</para> - - <para>If you want to read more about colors and colorspaces, then the -following resources are useful: <xref linkend="poynton" /> is a good practical -book for video engineers, <xref linkend="colimg" /> has a much broader scope and -describes many more aspects of color (physics, chemistry, biology, etc.). -The <ulink url="http://www.brucelindbloom.com">http://www.brucelindbloom.com</ulink> -website is an excellent resource, especially with respect to the mathematics behind -colorspace conversions. The wikipedia <ulink url="http://en.wikipedia.org/wiki/CIE_1931_color_space#CIE_xy_chromaticity_diagram_and_the_CIE_xyY_color_space">CIE 1931 colorspace</ulink> article -is also very useful.</para> - </section> - - <section> - <title>Defining Colorspaces in V4L2</title> - <para>In V4L2 colorspaces are defined by four values. The first is the colorspace -identifier (&v4l2-colorspace;) which defines the chromaticities, the default transfer -function, the default Y'CbCr encoding and the default quantization method. The second -is the transfer function identifier (&v4l2-xfer-func;) to specify non-standard -transfer functions. The third is the Y'CbCr encoding identifier (&v4l2-ycbcr-encoding;) -to specify non-standard Y'CbCr encodings and the fourth is the quantization identifier -(&v4l2-quantization;) to specify non-standard quantization methods. Most of the time -only the colorspace field of &v4l2-pix-format; or &v4l2-pix-format-mplane; needs to -be filled in. Note that the default R'G'B' quantization is full range for all -colorspaces except for BT.2020 which uses limited range R'G'B' quantization.</para> - - <table pgwide="1" frame="none" id="v4l2-colorspace"> - <title>V4L2 Colorspaces</title> - <tgroup cols="2" align="left"> - &cs-def; - <thead> - <row> - <entry>Identifier</entry> - <entry>Details</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry><constant>V4L2_COLORSPACE_DEFAULT</constant></entry> - <entry>The default colorspace. This can be used by applications to let the - driver fill in the colorspace.</entry> - </row> - <row> - <entry><constant>V4L2_COLORSPACE_SMPTE170M</constant></entry> - <entry>See <xref linkend="col-smpte-170m" />.</entry> - </row> - <row> - <entry><constant>V4L2_COLORSPACE_REC709</constant></entry> - <entry>See <xref linkend="col-rec709" />.</entry> - </row> - <row> - <entry><constant>V4L2_COLORSPACE_SRGB</constant></entry> - <entry>See <xref linkend="col-srgb" />.</entry> - </row> - <row> - <entry><constant>V4L2_COLORSPACE_ADOBERGB</constant></entry> - <entry>See <xref linkend="col-adobergb" />.</entry> - </row> - <row> - <entry><constant>V4L2_COLORSPACE_BT2020</constant></entry> - <entry>See <xref linkend="col-bt2020" />.</entry> - </row> - <row> - <entry><constant>V4L2_COLORSPACE_DCI_P3</constant></entry> - <entry>See <xref linkend="col-dcip3" />.</entry> - </row> - <row> - <entry><constant>V4L2_COLORSPACE_SMPTE240M</constant></entry> - <entry>See <xref linkend="col-smpte-240m" />.</entry> - </row> - <row> - <entry><constant>V4L2_COLORSPACE_470_SYSTEM_M</constant></entry> - <entry>See <xref linkend="col-sysm" />.</entry> - </row> - <row> - <entry><constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant></entry> - <entry>See <xref linkend="col-sysbg" />.</entry> - </row> - <row> - <entry><constant>V4L2_COLORSPACE_JPEG</constant></entry> - <entry>See <xref linkend="col-jpeg" />.</entry> - </row> - <row> - <entry><constant>V4L2_COLORSPACE_RAW</constant></entry> - <entry>The raw colorspace. This is used for raw image capture where - the image is minimally processed and is using the internal colorspace - of the device. The software that processes an image using this - 'colorspace' will have to know the internals of the capture device.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="v4l2-xfer-func"> - <title>V4L2 Transfer Function</title> - <tgroup cols="2" align="left"> - &cs-def; - <thead> - <row> - <entry>Identifier</entry> - <entry>Details</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry><constant>V4L2_XFER_FUNC_DEFAULT</constant></entry> - <entry>Use the default transfer function as defined by the colorspace.</entry> - </row> - <row> - <entry><constant>V4L2_XFER_FUNC_709</constant></entry> - <entry>Use the Rec. 709 transfer function.</entry> - </row> - <row> - <entry><constant>V4L2_XFER_FUNC_SRGB</constant></entry> - <entry>Use the sRGB transfer function.</entry> - </row> - <row> - <entry><constant>V4L2_XFER_FUNC_ADOBERGB</constant></entry> - <entry>Use the AdobeRGB transfer function.</entry> - </row> - <row> - <entry><constant>V4L2_XFER_FUNC_SMPTE240M</constant></entry> - <entry>Use the SMPTE 240M transfer function.</entry> - </row> - <row> - <entry><constant>V4L2_XFER_FUNC_NONE</constant></entry> - <entry>Do not use a transfer function (i.e. use linear RGB values).</entry> - </row> - <row> - <entry><constant>V4L2_XFER_FUNC_DCI_P3</constant></entry> - <entry>Use the DCI-P3 transfer function.</entry> - </row> - <row> - <entry><constant>V4L2_XFER_FUNC_SMPTE2084</constant></entry> - <entry>Use the SMPTE 2084 transfer function.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="v4l2-ycbcr-encoding"> - <title>V4L2 Y'CbCr Encodings</title> - <tgroup cols="2" align="left"> - &cs-def; - <thead> - <row> - <entry>Identifier</entry> - <entry>Details</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry><constant>V4L2_YCBCR_ENC_DEFAULT</constant></entry> - <entry>Use the default Y'CbCr encoding as defined by the colorspace.</entry> - </row> - <row> - <entry><constant>V4L2_YCBCR_ENC_601</constant></entry> - <entry>Use the BT.601 Y'CbCr encoding.</entry> - </row> - <row> - <entry><constant>V4L2_YCBCR_ENC_709</constant></entry> - <entry>Use the Rec. 709 Y'CbCr encoding.</entry> - </row> - <row> - <entry><constant>V4L2_YCBCR_ENC_XV601</constant></entry> - <entry>Use the extended gamut xvYCC BT.601 encoding.</entry> - </row> - <row> - <entry><constant>V4L2_YCBCR_ENC_XV709</constant></entry> - <entry>Use the extended gamut xvYCC Rec. 709 encoding.</entry> - </row> - <row> - <entry><constant>V4L2_YCBCR_ENC_SYCC</constant></entry> - <entry>Use the extended gamut sYCC encoding.</entry> - </row> - <row> - <entry><constant>V4L2_YCBCR_ENC_BT2020</constant></entry> - <entry>Use the default non-constant luminance BT.2020 Y'CbCr encoding.</entry> - </row> - <row> - <entry><constant>V4L2_YCBCR_ENC_BT2020_CONST_LUM</constant></entry> - <entry>Use the constant luminance BT.2020 Yc'CbcCrc encoding.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="v4l2-quantization"> - <title>V4L2 Quantization Methods</title> - <tgroup cols="2" align="left"> - &cs-def; - <thead> - <row> - <entry>Identifier</entry> - <entry>Details</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry><constant>V4L2_QUANTIZATION_DEFAULT</constant></entry> - <entry>Use the default quantization encoding as defined by the colorspace. -This is always full range for R'G'B' (except for the BT.2020 colorspace) and usually -limited range for Y'CbCr.</entry> - </row> - <row> - <entry><constant>V4L2_QUANTIZATION_FULL_RANGE</constant></entry> - <entry>Use the full range quantization encoding. I.e. the range [0…1] -is mapped to [0…255] (with possible clipping to [1…254] to avoid the -0x00 and 0xff values). Cb and Cr are mapped from [-0.5…0.5] to [0…255] -(with possible clipping to [1…254] to avoid the 0x00 and 0xff values).</entry> - </row> - <row> - <entry><constant>V4L2_QUANTIZATION_LIM_RANGE</constant></entry> - <entry>Use the limited range quantization encoding. I.e. the range [0…1] -is mapped to [16…235]. Cb and Cr are mapped from [-0.5…0.5] to [16…240]. -</entry> - </row> - </tbody> - </tgroup> - </table> - </section> - - <section> - <title>Detailed Colorspace Descriptions</title> - <section id="col-smpte-170m"> - <title>Colorspace SMPTE 170M (<constant>V4L2_COLORSPACE_SMPTE170M</constant>)</title> - <para>The <xref linkend="smpte170m" /> standard defines the colorspace used by NTSC and PAL and by SDTV -in general. The default transfer function is <constant>V4L2_XFER_FUNC_709</constant>. -The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>. -The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and -the white reference are:</para> - <table frame="none"> - <title>SMPTE 170M Chromaticities</title> - <tgroup cols="3" align="left"> - &cs-str; - <thead> - <row> - <entry>Color</entry> - <entry>x</entry> - <entry>y</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry>Red</entry> - <entry>0.630</entry> - <entry>0.340</entry> - </row> - <row> - <entry>Green</entry> - <entry>0.310</entry> - <entry>0.595</entry> - </row> - <row> - <entry>Blue</entry> - <entry>0.155</entry> - <entry>0.070</entry> - </row> - <row> - <entry>White Reference (D65)</entry> - <entry>0.3127</entry> - <entry>0.3290</entry> - </row> - </tbody> - </tgroup> - </table> - <para>The red, green and blue chromaticities are also often referred to -as the SMPTE C set, so this colorspace is sometimes called SMPTE C as well.</para> - <variablelist> - <varlistentry> - <term>The transfer function defined for SMPTE 170M is the same as the -one defined in Rec. 709.</term> - <listitem> - <para>L' = -1.099(-L)<superscript>0.45</superscript> + 0.099 for L ≤ -0.018</para> - <para>L' = 4.5L for -0.018 < L < 0.018</para> - <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for L ≥ 0.018</para> - </listitem> - </varlistentry> - </variablelist> - <variablelist> - <varlistentry> - <term>Inverse Transfer function:</term> - <listitem> - <para>L = -((L' - 0.099) / -1.099)<superscript>1/0.45</superscript> for L' ≤ -0.081</para> - <para>L = L' / 4.5 for -0.081 < L' < 0.081</para> - <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> - </listitem> - </varlistentry> - </variablelist> - <variablelist> - <varlistentry> - <term>The luminance (Y') and color difference (Cb and Cr) are obtained with -the following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term> - <listitem> - <para>Y' = 0.299R' + 0.587G' + 0.114B'</para> - <para>Cb = -0.169R' - 0.331G' + 0.5B'</para> - <para>Cr = 0.5R' - 0.419G' - 0.081B'</para> - </listitem> - </varlistentry> - </variablelist> - <para>Y' is clamped to the range [0…1] and Cb and Cr are -clamped to the range [-0.5…0.5]. This conversion to Y'CbCr is identical to the one -defined in the <xref linkend="itu601" /> standard and this colorspace is sometimes called BT.601 as well, even -though BT.601 does not mention any color primaries.</para> - <para>The default quantization is limited range, but full range is possible although -rarely seen.</para> - </section> - - <section id="col-rec709"> - <title>Colorspace Rec. 709 (<constant>V4L2_COLORSPACE_REC709</constant>)</title> - <para>The <xref linkend="itu709" /> standard defines the colorspace used by HDTV in general. -The default transfer function is <constant>V4L2_XFER_FUNC_709</constant>. The default -Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_709</constant>. The default Y'CbCr quantization is -limited range. The chromaticities of the primary colors and the white reference are:</para> - <table frame="none"> - <title>Rec. 709 Chromaticities</title> - <tgroup cols="3" align="left"> - &cs-str; - <thead> - <row> - <entry>Color</entry> - <entry>x</entry> - <entry>y</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry>Red</entry> - <entry>0.640</entry> - <entry>0.330</entry> - </row> - <row> - <entry>Green</entry> - <entry>0.300</entry> - <entry>0.600</entry> - </row> - <row> - <entry>Blue</entry> - <entry>0.150</entry> - <entry>0.060</entry> - </row> - <row> - <entry>White Reference (D65)</entry> - <entry>0.3127</entry> - <entry>0.3290</entry> - </row> - </tbody> - </tgroup> - </table> - <para>The full name of this standard is Rec. ITU-R BT.709-5.</para> - <variablelist> - <varlistentry> - <term>Transfer function. Normally L is in the range [0…1], but for the extended -gamut xvYCC encoding values outside that range are allowed.</term> - <listitem> - <para>L' = -1.099(-L)<superscript>0.45</superscript> + 0.099 for L ≤ -0.018</para> - <para>L' = 4.5L for -0.018 < L < 0.018</para> - <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for L ≥ 0.018</para> - </listitem> - </varlistentry> - </variablelist> - <variablelist> - <varlistentry> - <term>Inverse Transfer function:</term> - <listitem> - <para>L = -((L' - 0.099) / -1.099)<superscript>1/0.45</superscript> for L' ≤ -0.081</para> - <para>L = L' / 4.5 for -0.081 < L' < 0.081</para> - <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> - </listitem> - </varlistentry> - </variablelist> - <variablelist> - <varlistentry> - <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the following -<constant>V4L2_YCBCR_ENC_709</constant> encoding:</term> - <listitem> - <para>Y' = 0.2126R' + 0.7152G' + 0.0722B'</para> - <para>Cb = -0.1146R' - 0.3854G' + 0.5B'</para> - <para>Cr = 0.5R' - 0.4542G' - 0.0458B'</para> - </listitem> - </varlistentry> - </variablelist> - <para>Y' is clamped to the range [0…1] and Cb and Cr are -clamped to the range [-0.5…0.5].</para> - <para>The default quantization is limited range, but full range is possible although -rarely seen.</para> - <para>The <constant>V4L2_YCBCR_ENC_709</constant> encoding described above is the default -for this colorspace, but it can be overridden with <constant>V4L2_YCBCR_ENC_601</constant>, in which -case the BT.601 Y'CbCr encoding is used.</para> - <para>Two additional extended gamut Y'CbCr encodings are also possible with this colorspace:</para> - <variablelist> - <varlistentry> - <term>The xvYCC 709 encoding (<constant>V4L2_YCBCR_ENC_XV709</constant>, <xref linkend="xvycc" />) -is similar to the Rec. 709 encoding, but it allows for R', G' and B' values that are outside the range -[0…1]. The resulting Y', Cb and Cr values are scaled and offset:</term> - <listitem> - <para>Y' = (219 / 256) * (0.2126R' + 0.7152G' + 0.0722B') + (16 / 256)</para> - <para>Cb = (224 / 256) * (-0.1146R' - 0.3854G' + 0.5B')</para> - <para>Cr = (224 / 256) * (0.5R' - 0.4542G' - 0.0458B')</para> - </listitem> - </varlistentry> - </variablelist> - <variablelist> - <varlistentry> - <term>The xvYCC 601 encoding (<constant>V4L2_YCBCR_ENC_XV601</constant>, <xref linkend="xvycc" />) is similar -to the BT.601 encoding, but it allows for R', G' and B' values that are outside the range -[0…1]. The resulting Y', Cb and Cr values are scaled and offset:</term> - <listitem> - <para>Y' = (219 / 256) * (0.299R' + 0.587G' + 0.114B') + (16 / 256)</para> - <para>Cb = (224 / 256) * (-0.169R' - 0.331G' + 0.5B')</para> - <para>Cr = (224 / 256) * (0.5R' - 0.419G' - 0.081B')</para> - </listitem> - </varlistentry> - </variablelist> - <para>Y' is clamped to the range [0…1] and Cb and Cr are clamped -to the range [-0.5…0.5]. The non-standard xvYCC 709 or xvYCC 601 encodings can be used by -selecting <constant>V4L2_YCBCR_ENC_XV709</constant> or <constant>V4L2_YCBCR_ENC_XV601</constant>. -The xvYCC encodings always use full range quantization.</para> - </section> - - <section id="col-srgb"> - <title>Colorspace sRGB (<constant>V4L2_COLORSPACE_SRGB</constant>)</title> - <para>The <xref linkend="srgb" /> standard defines the colorspace used by most webcams -and computer graphics. The default transfer function is <constant>V4L2_XFER_FUNC_SRGB</constant>. -The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_SYCC</constant>. The default Y'CbCr -quantization is full range. The chromaticities of the primary colors and the white -reference are:</para> - <table frame="none"> - <title>sRGB Chromaticities</title> - <tgroup cols="3" align="left"> - &cs-str; - <thead> - <row> - <entry>Color</entry> - <entry>x</entry> - <entry>y</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry>Red</entry> - <entry>0.640</entry> - <entry>0.330</entry> - </row> - <row> - <entry>Green</entry> - <entry>0.300</entry> - <entry>0.600</entry> - </row> - <row> - <entry>Blue</entry> - <entry>0.150</entry> - <entry>0.060</entry> - </row> - <row> - <entry>White Reference (D65)</entry> - <entry>0.3127</entry> - <entry>0.3290</entry> - </row> - </tbody> - </tgroup> - </table> - <para>These chromaticities are identical to the Rec. 709 colorspace.</para> - <variablelist> - <varlistentry> - <term>Transfer function. Note that negative values for L are only used by the Y'CbCr conversion.</term> - <listitem> - <para>L' = -1.055(-L)<superscript>1/2.4</superscript> + 0.055 for L < -0.0031308</para> - <para>L' = 12.92L for -0.0031308 ≤ L ≤ 0.0031308</para> - <para>L' = 1.055L<superscript>1/2.4</superscript> - 0.055 for 0.0031308 < L ≤ 1</para> - </listitem> - </varlistentry> - <varlistentry> - <term>Inverse Transfer function:</term> - <listitem> - <para>L = -((-L' + 0.055) / 1.055)<superscript>2.4</superscript> for L' < -0.04045</para> - <para>L = L' / 12.92 for -0.04045 ≤ L' ≤ 0.04045</para> - <para>L = ((L' + 0.055) / 1.055)<superscript>2.4</superscript> for L' > 0.04045</para> - </listitem> - </varlistentry> - </variablelist> - <variablelist> - <varlistentry> - <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the following -<constant>V4L2_YCBCR_ENC_SYCC</constant> encoding as defined by <xref linkend="sycc" />:</term> - <listitem> - <para>Y' = 0.2990R' + 0.5870G' + 0.1140B'</para> - <para>Cb = -0.1687R' - 0.3313G' + 0.5B'</para> - <para>Cr = 0.5R' - 0.4187G' - 0.0813B'</para> - </listitem> - </varlistentry> - </variablelist> - <para>Y' is clamped to the range [0…1] and Cb and Cr are clamped -to the range [-0.5…0.5]. The <constant>V4L2_YCBCR_ENC_SYCC</constant> quantization is always -full range. Although this Y'CbCr encoding looks very similar to the <constant>V4L2_YCBCR_ENC_XV601</constant> -encoding, it is not. The <constant>V4L2_YCBCR_ENC_XV601</constant> scales and offsets the Y'CbCr -values before quantization, but this encoding does not do that.</para> - </section> - - <section id="col-adobergb"> - <title>Colorspace Adobe RGB (<constant>V4L2_COLORSPACE_ADOBERGB</constant>)</title> - <para>The <xref linkend="adobergb" /> standard defines the colorspace used by computer graphics -that use the AdobeRGB colorspace. This is also known as the <xref linkend="oprgb" /> standard. -The default transfer function is <constant>V4L2_XFER_FUNC_ADOBERGB</constant>. -The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr -quantization is limited range. The chromaticities of the primary colors and the white reference -are:</para> - <table frame="none"> - <title>Adobe RGB Chromaticities</title> - <tgroup cols="3" align="left"> - &cs-str; - <thead> - <row> - <entry>Color</entry> - <entry>x</entry> - <entry>y</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry>Red</entry> - <entry>0.6400</entry> - <entry>0.3300</entry> - </row> - <row> - <entry>Green</entry> - <entry>0.2100</entry> - <entry>0.7100</entry> - </row> - <row> - <entry>Blue</entry> - <entry>0.1500</entry> - <entry>0.0600</entry> - </row> - <row> - <entry>White Reference (D65)</entry> - <entry>0.3127</entry> - <entry>0.3290</entry> - </row> - </tbody> - </tgroup> - </table> - <variablelist> - <varlistentry> - <term>Transfer function:</term> - <listitem> - <para>L' = L<superscript>1/2.19921875</superscript></para> - </listitem> - </varlistentry> - <varlistentry> - <term>Inverse Transfer function:</term> - <listitem> - <para>L = L'<superscript>2.19921875</superscript></para> - </listitem> - </varlistentry> - </variablelist> - <variablelist> - <varlistentry> - <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the -following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term> - <listitem> - <para>Y' = 0.299R' + 0.587G' + 0.114B'</para> - <para>Cb = -0.169R' - 0.331G' + 0.5B'</para> - <para>Cr = 0.5R' - 0.419G' - 0.081B'</para> - </listitem> - </varlistentry> - </variablelist> - <para>Y' is clamped to the range [0…1] and Cb and Cr are -clamped to the range [-0.5…0.5]. This transform is identical to one defined in -SMPTE 170M/BT.601. The Y'CbCr quantization is limited range.</para> - </section> - - <section id="col-bt2020"> - <title>Colorspace BT.2020 (<constant>V4L2_COLORSPACE_BT2020</constant>)</title> - <para>The <xref linkend="itu2020" /> standard defines the colorspace used by Ultra-high definition -television (UHDTV). The default transfer function is <constant>V4L2_XFER_FUNC_709</constant>. -The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_BT2020</constant>. -The default R'G'B' quantization is limited range (!), and so is the default Y'CbCr quantization. -The chromaticities of the primary colors and the white reference are:</para> - <table frame="none"> - <title>BT.2020 Chromaticities</title> - <tgroup cols="3" align="left"> - &cs-str; - <thead> - <row> - <entry>Color</entry> - <entry>x</entry> - <entry>y</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry>Red</entry> - <entry>0.708</entry> - <entry>0.292</entry> - </row> - <row> - <entry>Green</entry> - <entry>0.170</entry> - <entry>0.797</entry> - </row> - <row> - <entry>Blue</entry> - <entry>0.131</entry> - <entry>0.046</entry> - </row> - <row> - <entry>White Reference (D65)</entry> - <entry>0.3127</entry> - <entry>0.3290</entry> - </row> - </tbody> - </tgroup> - </table> - <variablelist> - <varlistentry> - <term>Transfer function (same as Rec. 709):</term> - <listitem> - <para>L' = 4.5L for 0 ≤ L < 0.018</para> - <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for 0.018 ≤ L ≤ 1</para> - </listitem> - </varlistentry> - <varlistentry> - <term>Inverse Transfer function:</term> - <listitem> - <para>L = L' / 4.5 for L' < 0.081</para> - <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> - </listitem> - </varlistentry> - </variablelist> - <variablelist> - <varlistentry> - <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the -following <constant>V4L2_YCBCR_ENC_BT2020</constant> encoding:</term> - <listitem> - <para>Y' = 0.2627R' + 0.6780G' + 0.0593B'</para> - <para>Cb = -0.1396R' - 0.3604G' + 0.5B'</para> - <para>Cr = 0.5R' - 0.4598G' - 0.0402B'</para> - </listitem> - </varlistentry> - </variablelist> - <para>Y' is clamped to the range [0…1] and Cb and Cr are -clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range.</para> - <para>There is also an alternate constant luminance R'G'B' to Yc'CbcCrc -(<constant>V4L2_YCBCR_ENC_BT2020_CONST_LUM</constant>) encoding:</para> - <variablelist> - <varlistentry> - <term>Luma:</term> - <listitem> - <para>Yc' = (0.2627R + 0.6780G + 0.0593B)'</para> - </listitem> - </varlistentry> - </variablelist> - <variablelist> - <varlistentry> - <term>B' - Yc' ≤ 0:</term> - <listitem> - <para>Cbc = (B' - Yc') / 1.9404</para> - </listitem> - </varlistentry> - </variablelist> - <variablelist> - <varlistentry> - <term>B' - Yc' > 0:</term> - <listitem> - <para>Cbc = (B' - Yc') / 1.5816</para> - </listitem> - </varlistentry> - </variablelist> - <variablelist> - <varlistentry> - <term>R' - Yc' ≤ 0:</term> - <listitem> - <para>Crc = (R' - Y') / 1.7184</para> - </listitem> - </varlistentry> - </variablelist> - <variablelist> - <varlistentry> - <term>R' - Yc' > 0:</term> - <listitem> - <para>Crc = (R' - Y') / 0.9936</para> - </listitem> - </varlistentry> - </variablelist> - <para>Yc' is clamped to the range [0…1] and Cbc and Crc are -clamped to the range [-0.5…0.5]. The Yc'CbcCrc quantization is limited range.</para> - </section> - - <section id="col-dcip3"> - <title>Colorspace DCI-P3 (<constant>V4L2_COLORSPACE_DCI_P3</constant>)</title> - <para>The <xref linkend="smpte431" /> standard defines the colorspace used by cinema -projectors that use the DCI-P3 colorspace. -The default transfer function is <constant>V4L2_XFER_FUNC_DCI_P3</constant>. -The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_709</constant>. Note that this -colorspace does not specify a Y'CbCr encoding since it is not meant to be encoded -to Y'CbCr. So this default Y'CbCr encoding was picked because it is the HDTV -encoding. The default Y'CbCr quantization is limited range. The chromaticities of -the primary colors and the white reference are:</para> - <table frame="none"> - <title>DCI-P3 Chromaticities</title> - <tgroup cols="3" align="left"> - &cs-str; - <thead> - <row> - <entry>Color</entry> - <entry>x</entry> - <entry>y</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry>Red</entry> - <entry>0.6800</entry> - <entry>0.3200</entry> - </row> - <row> - <entry>Green</entry> - <entry>0.2650</entry> - <entry>0.6900</entry> - </row> - <row> - <entry>Blue</entry> - <entry>0.1500</entry> - <entry>0.0600</entry> - </row> - <row> - <entry>White Reference</entry> - <entry>0.3140</entry> - <entry>0.3510</entry> - </row> - </tbody> - </tgroup> - </table> - <variablelist> - <varlistentry> - <term>Transfer function:</term> - <listitem> - <para>L' = L<superscript>1/2.6</superscript></para> - </listitem> - </varlistentry> - <varlistentry> - <term>Inverse Transfer function:</term> - <listitem> - <para>L = L'<superscript>2.6</superscript></para> - </listitem> - </varlistentry> - </variablelist> - <para>Y'CbCr encoding is not specified. V4L2 defaults to Rec. 709.</para> - </section> - - <section id="col-smpte-240m"> - <title>Colorspace SMPTE 240M (<constant>V4L2_COLORSPACE_SMPTE240M</constant>)</title> - <para>The <xref linkend="smpte240m" /> standard was an interim standard used during -the early days of HDTV (1988-1998). It has been superseded by Rec. 709. -The default transfer function is <constant>V4L2_XFER_FUNC_SMPTE240M</constant>. -The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_SMPTE240M</constant>. -The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and the -white reference are:</para> - <table frame="none"> - <title>SMPTE 240M Chromaticities</title> - <tgroup cols="3" align="left"> - &cs-str; - <thead> - <row> - <entry>Color</entry> - <entry>x</entry> - <entry>y</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry>Red</entry> - <entry>0.630</entry> - <entry>0.340</entry> - </row> - <row> - <entry>Green</entry> - <entry>0.310</entry> - <entry>0.595</entry> - </row> - <row> - <entry>Blue</entry> - <entry>0.155</entry> - <entry>0.070</entry> - </row> - <row> - <entry>White Reference (D65)</entry> - <entry>0.3127</entry> - <entry>0.3290</entry> - </row> - </tbody> - </tgroup> - </table> - <para>These chromaticities are identical to the SMPTE 170M colorspace.</para> - <variablelist> - <varlistentry> - <term>Transfer function:</term> - <listitem> - <para>L' = 4L for 0 ≤ L < 0.0228</para> - <para>L' = 1.1115L<superscript>0.45</superscript> - 0.1115 for 0.0228 ≤ L ≤ 1</para> - </listitem> - </varlistentry> - <varlistentry> - <term>Inverse Transfer function:</term> - <listitem> - <para>L = L' / 4 for 0 ≤ L' < 0.0913</para> - <para>L = ((L' + 0.1115) / 1.1115)<superscript>1/0.45</superscript> for L' ≥ 0.0913</para> - </listitem> - </varlistentry> - </variablelist> - <variablelist> - <varlistentry> - <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the -following <constant>V4L2_YCBCR_ENC_SMPTE240M</constant> encoding:</term> - <listitem> - <para>Y' = 0.2122R' + 0.7013G' + 0.0865B'</para> - <para>Cb = -0.1161R' - 0.3839G' + 0.5B'</para> - <para>Cr = 0.5R' - 0.4451G' - 0.0549B'</para> - </listitem> - </varlistentry> - </variablelist> - <para>Yc' is clamped to the range [0…1] and Cbc and Crc are -clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range.</para> - </section> - - <section id="col-sysm"> - <title>Colorspace NTSC 1953 (<constant>V4L2_COLORSPACE_470_SYSTEM_M</constant>)</title> - <para>This standard defines the colorspace used by NTSC in 1953. In practice this -colorspace is obsolete and SMPTE 170M should be used instead. -The default transfer function is <constant>V4L2_XFER_FUNC_709</constant>. -The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>. -The default Y'CbCr quantization is limited range. -The chromaticities of the primary colors and the white reference are:</para> - <table frame="none"> - <title>NTSC 1953 Chromaticities</title> - <tgroup cols="3" align="left"> - &cs-str; - <thead> - <row> - <entry>Color</entry> - <entry>x</entry> - <entry>y</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry>Red</entry> - <entry>0.67</entry> - <entry>0.33</entry> - </row> - <row> - <entry>Green</entry> - <entry>0.21</entry> - <entry>0.71</entry> - </row> - <row> - <entry>Blue</entry> - <entry>0.14</entry> - <entry>0.08</entry> - </row> - <row> - <entry>White Reference (C)</entry> - <entry>0.310</entry> - <entry>0.316</entry> - </row> - </tbody> - </tgroup> - </table> - <para>Note that this colorspace uses Illuminant C instead of D65 as the -white reference. To correctly convert an image in this colorspace to another -that uses D65 you need to apply a chromatic adaptation algorithm such as the -Bradford method.</para> - <variablelist> - <varlistentry> - <term>The transfer function was never properly defined for NTSC 1953. The -Rec. 709 transfer function is recommended in the literature:</term> - <listitem> - <para>L' = 4.5L for 0 ≤ L < 0.018</para> - <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for 0.018 ≤ L ≤ 1</para> - </listitem> - </varlistentry> - <varlistentry> - <term>Inverse Transfer function:</term> - <listitem> - <para>L = L' / 4.5 for L' < 0.081</para> - <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> - </listitem> - </varlistentry> - </variablelist> - <variablelist> - <varlistentry> - <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the -following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term> - <listitem> - <para>Y' = 0.299R' + 0.587G' + 0.114B'</para> - <para>Cb = -0.169R' - 0.331G' + 0.5B'</para> - <para>Cr = 0.5R' - 0.419G' - 0.081B'</para> - </listitem> - </varlistentry> - </variablelist> - <para>Y' is clamped to the range [0…1] and Cb and Cr are -clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range. -This transform is identical to one defined in SMPTE 170M/BT.601.</para> - </section> - - <section id="col-sysbg"> - <title>Colorspace EBU Tech. 3213 (<constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant>)</title> - <para>The <xref linkend="tech3213" /> standard defines the colorspace used by PAL/SECAM in 1975. In practice this -colorspace is obsolete and SMPTE 170M should be used instead. -The default transfer function is <constant>V4L2_XFER_FUNC_709</constant>. -The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>. -The default Y'CbCr quantization is limited range. -The chromaticities of the primary colors and the white reference are:</para> - <table frame="none"> - <title>EBU Tech. 3213 Chromaticities</title> - <tgroup cols="3" align="left"> - &cs-str; - <thead> - <row> - <entry>Color</entry> - <entry>x</entry> - <entry>y</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry>Red</entry> - <entry>0.64</entry> - <entry>0.33</entry> - </row> - <row> - <entry>Green</entry> - <entry>0.29</entry> - <entry>0.60</entry> - </row> - <row> - <entry>Blue</entry> - <entry>0.15</entry> - <entry>0.06</entry> - </row> - <row> - <entry>White Reference (D65)</entry> - <entry>0.3127</entry> - <entry>0.3290</entry> - </row> - </tbody> - </tgroup> - </table> - <variablelist> - <varlistentry> - <term>The transfer function was never properly defined for this colorspace. -The Rec. 709 transfer function is recommended in the literature:</term> - <listitem> - <para>L' = 4.5L for 0 ≤ L < 0.018</para> - <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for 0.018 ≤ L ≤ 1</para> - </listitem> - </varlistentry> - <varlistentry> - <term>Inverse Transfer function:</term> - <listitem> - <para>L = L' / 4.5 for L' < 0.081</para> - <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> - </listitem> - </varlistentry> - </variablelist> - <variablelist> - <varlistentry> - <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the -following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term> - <listitem> - <para>Y' = 0.299R' + 0.587G' + 0.114B'</para> - <para>Cb = -0.169R' - 0.331G' + 0.5B'</para> - <para>Cr = 0.5R' - 0.419G' - 0.081B'</para> - </listitem> - </varlistentry> - </variablelist> - <para>Y' is clamped to the range [0…1] and Cb and Cr are -clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range. -This transform is identical to one defined in SMPTE 170M/BT.601.</para> - </section> - - <section id="col-jpeg"> - <title>Colorspace JPEG (<constant>V4L2_COLORSPACE_JPEG</constant>)</title> - <para>This colorspace defines the colorspace used by most (Motion-)JPEG formats. The chromaticities -of the primary colors and the white reference are identical to sRGB. The transfer -function use is <constant>V4L2_XFER_FUNC_SRGB</constant>. The Y'CbCr encoding is -<constant>V4L2_YCBCR_ENC_601</constant> with full range quantization where -Y' is scaled to [0…255] and Cb/Cr are scaled to [-128…128] and -then clipped to [-128…127].</para> - <para>Note that the JPEG standard does not actually store colorspace information. -So if something other than sRGB is used, then the driver will have to set that information -explicitly. Effectively <constant>V4L2_COLORSPACE_JPEG</constant> can be considered to be -an abbreviation for <constant>V4L2_COLORSPACE_SRGB</constant>, <constant>V4L2_YCBCR_ENC_601</constant> -and <constant>V4L2_QUANTIZATION_FULL_RANGE</constant>.</para> - </section> - - </section> - - <section> - <title>Detailed Transfer Function Descriptions</title> - <section id="xf-smpte-2084"> - <title>Transfer Function SMPTE 2084 (<constant>V4L2_XFER_FUNC_SMPTE2084</constant>)</title> - <para>The <xref linkend="smpte2084" /> standard defines the transfer function used by -High Dynamic Range content.</para> - <variablelist> - <varlistentry> - <term>Constants:</term> - <listitem> - <para>m1 = (2610 / 4096) / 4</para> - <para>m2 = (2523 / 4096) * 128</para> - <para>c1 = 3424 / 4096</para> - <para>c2 = (2413 / 4096) * 32</para> - <para>c3 = (2392 / 4096) * 32</para> - </listitem> - </varlistentry> - <varlistentry> - <term>Transfer function:</term> - <listitem> - <para>L' = ((c1 + c2 * L<superscript>m1</superscript>) / (1 + c3 * L<superscript>m1</superscript>))<superscript>m2</superscript></para> - </listitem> - </varlistentry> - </variablelist> - <variablelist> - <varlistentry> - <term>Inverse Transfer function:</term> - <listitem> - <para>L = (max(L'<superscript>1/m2</superscript> - c1, 0) / (c2 - c3 * L'<superscript>1/m2</superscript>))<superscript>1/m1</superscript></para> - </listitem> - </varlistentry> - </variablelist> - </section> - </section> - - <section id="pixfmt-indexed"> - <title>Indexed Format</title> - - <para>In this format each pixel is represented by an 8 bit index -into a 256 entry ARGB palette. It is intended for <link -linkend="osd">Video Output Overlays</link> only. There are no ioctls to -access the palette, this must be done with ioctls of the Linux framebuffer API.</para> - - <table pgwide="0" frame="none"> - <title>Indexed Image Format</title> - <tgroup cols="37" align="center"> - <colspec colname="id" align="left" /> - <colspec colname="fourcc" /> - <colspec colname="bit" /> - - <colspec colnum="4" colname="b07" align="center" /> - <colspec colnum="5" colname="b06" align="center" /> - <colspec colnum="6" colname="b05" align="center" /> - <colspec colnum="7" colname="b04" align="center" /> - <colspec colnum="8" colname="b03" align="center" /> - <colspec colnum="9" colname="b02" align="center" /> - <colspec colnum="10" colname="b01" align="center" /> - <colspec colnum="11" colname="b00" align="center" /> - - <spanspec namest="b07" nameend="b00" spanname="b0" /> - <spanspec namest="b17" nameend="b10" spanname="b1" /> - <spanspec namest="b27" nameend="b20" spanname="b2" /> - <spanspec namest="b37" nameend="b30" spanname="b3" /> - <thead> - <row> - <entry>Identifier</entry> - <entry>Code</entry> - <entry> </entry> - <entry spanname="b0">Byte 0</entry> - </row> - <row> - <entry> </entry> - <entry> </entry> - <entry>Bit</entry> - <entry>7</entry> - <entry>6</entry> - <entry>5</entry> - <entry>4</entry> - <entry>3</entry> - <entry>2</entry> - <entry>1</entry> - <entry>0</entry> - </row> - </thead> - <tbody valign="top"> - <row id="V4L2-PIX-FMT-PAL8"> - <entry><constant>V4L2_PIX_FMT_PAL8</constant></entry> - <entry>'PAL8'</entry> - <entry></entry> - <entry>i<subscript>7</subscript></entry> - <entry>i<subscript>6</subscript></entry> - <entry>i<subscript>5</subscript></entry> - <entry>i<subscript>4</subscript></entry> - <entry>i<subscript>3</subscript></entry> - <entry>i<subscript>2</subscript></entry> - <entry>i<subscript>1</subscript></entry> - <entry>i<subscript>0</subscript></entry> - </row> - </tbody> - </tgroup> - </table> - </section> - - <section id="pixfmt-rgb"> - <title>RGB Formats</title> - - &sub-packed-rgb; - &sub-sbggr8; - &sub-sgbrg8; - &sub-sgrbg8; - &sub-srggb8; - &sub-sbggr16; - &sub-srggb10; - &sub-srggb10p; - &sub-srggb10alaw8; - &sub-srggb10dpcm8; - &sub-srggb12; - </section> - - <section id="yuv-formats"> - <title>YUV Formats</title> - - <para>YUV is the format native to TV broadcast and composite video -signals. It separates the brightness information (Y) from the color -information (U and V or Cb and Cr). The color information consists of -red and blue <emphasis>color difference</emphasis> signals, this way -the green component can be reconstructed by subtracting from the -brightness component. See <xref linkend="colorspaces" /> for conversion -examples. YUV was chosen because early television would only transmit -brightness information. To add color in a way compatible with existing -receivers a new signal carrier was added to transmit the color -difference signals. Secondary in the YUV format the U and V components -usually have lower resolution than the Y component. This is an analog -video compression technique taking advantage of a property of the -human visual system, being more sensitive to brightness -information.</para> - - &sub-packed-yuv; - &sub-grey; - &sub-y10; - &sub-y12; - &sub-y10b; - &sub-y16; - &sub-y16-be; - &sub-uv8; - &sub-yuyv; - &sub-uyvy; - &sub-yvyu; - &sub-vyuy; - &sub-y41p; - &sub-yuv420; - &sub-yuv420m; - &sub-yvu420m; - &sub-yuv410; - &sub-yuv422p; - &sub-yuv411p; - &sub-nv12; - &sub-nv12m; - &sub-nv12mt; - &sub-nv16; - &sub-nv16m; - &sub-nv24; - &sub-m420; - </section> - - <section> - <title>Compressed Formats</title> - - <table pgwide="1" frame="none" id="compressed-formats"> - <title>Compressed Image Formats</title> - <tgroup cols="3" align="left"> - &cs-def; - <thead> - <row> - <entry>Identifier</entry> - <entry>Code</entry> - <entry>Details</entry> - </row> - </thead> - <tbody valign="top"> - <row id="V4L2-PIX-FMT-JPEG"> - <entry><constant>V4L2_PIX_FMT_JPEG</constant></entry> - <entry>'JPEG'</entry> - <entry>TBD. See also &VIDIOC-G-JPEGCOMP;, - &VIDIOC-S-JPEGCOMP;.</entry> - </row> - <row id="V4L2-PIX-FMT-MPEG"> - <entry><constant>V4L2_PIX_FMT_MPEG</constant></entry> - <entry>'MPEG'</entry> - <entry>MPEG multiplexed stream. The actual format is determined by -extended control <constant>V4L2_CID_MPEG_STREAM_TYPE</constant>, see -<xref linkend="mpeg-control-id" />.</entry> - </row> - <row id="V4L2-PIX-FMT-H264"> - <entry><constant>V4L2_PIX_FMT_H264</constant></entry> - <entry>'H264'</entry> - <entry>H264 video elementary stream with start codes.</entry> - </row> - <row id="V4L2-PIX-FMT-H264-NO-SC"> - <entry><constant>V4L2_PIX_FMT_H264_NO_SC</constant></entry> - <entry>'AVC1'</entry> - <entry>H264 video elementary stream without start codes.</entry> - </row> - <row id="V4L2-PIX-FMT-H264-MVC"> - <entry><constant>V4L2_PIX_FMT_H264_MVC</constant></entry> - <entry>'M264'</entry> - <entry>H264 MVC video elementary stream.</entry> - </row> - <row id="V4L2-PIX-FMT-H263"> - <entry><constant>V4L2_PIX_FMT_H263</constant></entry> - <entry>'H263'</entry> - <entry>H263 video elementary stream.</entry> - </row> - <row id="V4L2-PIX-FMT-MPEG1"> - <entry><constant>V4L2_PIX_FMT_MPEG1</constant></entry> - <entry>'MPG1'</entry> - <entry>MPEG1 video elementary stream.</entry> - </row> - <row id="V4L2-PIX-FMT-MPEG2"> - <entry><constant>V4L2_PIX_FMT_MPEG2</constant></entry> - <entry>'MPG2'</entry> - <entry>MPEG2 video elementary stream.</entry> - </row> - <row id="V4L2-PIX-FMT-MPEG4"> - <entry><constant>V4L2_PIX_FMT_MPEG4</constant></entry> - <entry>'MPG4'</entry> - <entry>MPEG4 video elementary stream.</entry> - </row> - <row id="V4L2-PIX-FMT-XVID"> - <entry><constant>V4L2_PIX_FMT_XVID</constant></entry> - <entry>'XVID'</entry> - <entry>Xvid video elementary stream.</entry> - </row> - <row id="V4L2-PIX-FMT-VC1-ANNEX-G"> - <entry><constant>V4L2_PIX_FMT_VC1_ANNEX_G</constant></entry> - <entry>'VC1G'</entry> - <entry>VC1, SMPTE 421M Annex G compliant stream.</entry> - </row> - <row id="V4L2-PIX-FMT-VC1-ANNEX-L"> - <entry><constant>V4L2_PIX_FMT_VC1_ANNEX_L</constant></entry> - <entry>'VC1L'</entry> - <entry>VC1, SMPTE 421M Annex L compliant stream.</entry> - </row> - <row id="V4L2-PIX-FMT-VP8"> - <entry><constant>V4L2_PIX_FMT_VP8</constant></entry> - <entry>'VP80'</entry> - <entry>VP8 video elementary stream.</entry> - </row> - </tbody> - </tgroup> - </table> - </section> - - <section id="sdr-formats"> - <title>SDR Formats</title> - - <para>These formats are used for <link linkend="sdr">SDR</link> -interface only.</para> - - &sub-sdr-cu08; - &sub-sdr-cu16le; - &sub-sdr-cs08; - &sub-sdr-cs14le; - &sub-sdr-ru12le; - - </section> - - <section id="pixfmt-reserved"> - <title>Reserved Format Identifiers</title> - - <para>These formats are not defined by this specification, they -are just listed for reference and to avoid naming conflicts. If you -want to register your own format, send an e-mail to the linux-media mailing -list &v4l-ml; for inclusion in the <filename>videodev2.h</filename> -file. If you want to share your format with other developers add a -link to your documentation and send a copy to the linux-media mailing list -for inclusion in this section. If you think your format should be listed -in a standard format section please make a proposal on the linux-media mailing -list.</para> - - <table pgwide="1" frame="none" id="reserved-formats"> - <title>Reserved Image Formats</title> - <tgroup cols="3" align="left"> - &cs-def; - <thead> - <row> - <entry>Identifier</entry> - <entry>Code</entry> - <entry>Details</entry> - </row> - </thead> - <tbody valign="top"> - <row id="V4L2-PIX-FMT-DV"> - <entry><constant>V4L2_PIX_FMT_DV</constant></entry> - <entry>'dvsd'</entry> - <entry>unknown</entry> - </row> - <row id="V4L2-PIX-FMT-ET61X251"> - <entry><constant>V4L2_PIX_FMT_ET61X251</constant></entry> - <entry>'E625'</entry> - <entry>Compressed format of the ET61X251 driver.</entry> - </row> - <row id="V4L2-PIX-FMT-HI240"> - <entry><constant>V4L2_PIX_FMT_HI240</constant></entry> - <entry>'HI24'</entry> - <entry><para>8 bit RGB format used by the BTTV driver.</para></entry> - </row> - <row id="V4L2-PIX-FMT-HM12"> - <entry><constant>V4L2_PIX_FMT_HM12</constant></entry> - <entry>'HM12'</entry> - <entry><para>YUV 4:2:0 format used by the -IVTV driver, <ulink url="http://www.ivtvdriver.org/"> -http://www.ivtvdriver.org/</ulink></para><para>The format is documented in the -kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.hm12</filename> -</para></entry> - </row> - <row id="V4L2-PIX-FMT-CPIA1"> - <entry><constant>V4L2_PIX_FMT_CPIA1</constant></entry> - <entry>'CPIA'</entry> - <entry>YUV format used by the gspca cpia1 driver.</entry> - </row> - <row id="V4L2-PIX-FMT-JPGL"> - <entry><constant>V4L2_PIX_FMT_JPGL</constant></entry> - <entry>'JPGL'</entry> - <entry>JPEG-Light format (Pegasus Lossless JPEG) - used in Divio webcams NW 80x.</entry> - </row> - <row id="V4L2-PIX-FMT-SPCA501"> - <entry><constant>V4L2_PIX_FMT_SPCA501</constant></entry> - <entry>'S501'</entry> - <entry>YUYV per line used by the gspca driver.</entry> - </row> - <row id="V4L2-PIX-FMT-SPCA505"> - <entry><constant>V4L2_PIX_FMT_SPCA505</constant></entry> - <entry>'S505'</entry> - <entry>YYUV per line used by the gspca driver.</entry> - </row> - <row id="V4L2-PIX-FMT-SPCA508"> - <entry><constant>V4L2_PIX_FMT_SPCA508</constant></entry> - <entry>'S508'</entry> - <entry>YUVY per line used by the gspca driver.</entry> - </row> - <row id="V4L2-PIX-FMT-SPCA561"> - <entry><constant>V4L2_PIX_FMT_SPCA561</constant></entry> - <entry>'S561'</entry> - <entry>Compressed GBRG Bayer format used by the gspca driver.</entry> - </row> - <row id="V4L2-PIX-FMT-PAC207"> - <entry><constant>V4L2_PIX_FMT_PAC207</constant></entry> - <entry>'P207'</entry> - <entry>Compressed BGGR Bayer format used by the gspca driver.</entry> - </row> - <row id="V4L2-PIX-FMT-MR97310A"> - <entry><constant>V4L2_PIX_FMT_MR97310A</constant></entry> - <entry>'M310'</entry> - <entry>Compressed BGGR Bayer format used by the gspca driver.</entry> - </row> - <row id="V4L2-PIX-FMT-JL2005BCD"> - <entry><constant>V4L2_PIX_FMT_JL2005BCD</constant></entry> - <entry>'JL20'</entry> - <entry>JPEG compressed RGGB Bayer format used by the gspca driver.</entry> - </row> - <row id="V4L2-PIX-FMT-OV511"> - <entry><constant>V4L2_PIX_FMT_OV511</constant></entry> - <entry>'O511'</entry> - <entry>OV511 JPEG format used by the gspca driver.</entry> - </row> - <row id="V4L2-PIX-FMT-OV518"> - <entry><constant>V4L2_PIX_FMT_OV518</constant></entry> - <entry>'O518'</entry> - <entry>OV518 JPEG format used by the gspca driver.</entry> - </row> - <row id="V4L2-PIX-FMT-PJPG"> - <entry><constant>V4L2_PIX_FMT_PJPG</constant></entry> - <entry>'PJPG'</entry> - <entry>Pixart 73xx JPEG format used by the gspca driver.</entry> - </row> - <row id="V4L2-PIX-FMT-SE401"> - <entry><constant>V4L2_PIX_FMT_SE401</constant></entry> - <entry>'S401'</entry> - <entry>Compressed RGB format used by the gspca se401 driver</entry> - </row> - <row id="V4L2-PIX-FMT-SQ905C"> - <entry><constant>V4L2_PIX_FMT_SQ905C</constant></entry> - <entry>'905C'</entry> - <entry>Compressed RGGB bayer format used by the gspca driver.</entry> - </row> - <row id="V4L2-PIX-FMT-MJPEG"> - <entry><constant>V4L2_PIX_FMT_MJPEG</constant></entry> - <entry>'MJPG'</entry> - <entry>Compressed format used by the Zoran driver</entry> - </row> - <row id="V4L2-PIX-FMT-PWC1"> - <entry><constant>V4L2_PIX_FMT_PWC1</constant></entry> - <entry>'PWC1'</entry> - <entry>Compressed format of the PWC driver.</entry> - </row> - <row id="V4L2-PIX-FMT-PWC2"> - <entry><constant>V4L2_PIX_FMT_PWC2</constant></entry> - <entry>'PWC2'</entry> - <entry>Compressed format of the PWC driver.</entry> - </row> - <row id="V4L2-PIX-FMT-SN9C10X"> - <entry><constant>V4L2_PIX_FMT_SN9C10X</constant></entry> - <entry>'S910'</entry> - <entry>Compressed format of the SN9C102 driver.</entry> - </row> - <row id="V4L2-PIX-FMT-SN9C20X-I420"> - <entry><constant>V4L2_PIX_FMT_SN9C20X_I420</constant></entry> - <entry>'S920'</entry> - <entry>YUV 4:2:0 format of the gspca sn9c20x driver.</entry> - </row> - <row id="V4L2-PIX-FMT-SN9C2028"> - <entry><constant>V4L2_PIX_FMT_SN9C2028</constant></entry> - <entry>'SONX'</entry> - <entry>Compressed GBRG bayer format of the gspca sn9c2028 driver.</entry> - </row> - <row id="V4L2-PIX-FMT-STV0680"> - <entry><constant>V4L2_PIX_FMT_STV0680</constant></entry> - <entry>'S680'</entry> - <entry>Bayer format of the gspca stv0680 driver.</entry> - </row> - <row id="V4L2-PIX-FMT-WNVA"> - <entry><constant>V4L2_PIX_FMT_WNVA</constant></entry> - <entry>'WNVA'</entry> - <entry><para>Used by the Winnov Videum driver, <ulink -url="http://www.thedirks.org/winnov/"> -http://www.thedirks.org/winnov/</ulink></para></entry> - </row> - <row id="V4L2-PIX-FMT-TM6000"> - <entry><constant>V4L2_PIX_FMT_TM6000</constant></entry> - <entry>'TM60'</entry> - <entry><para>Used by Trident tm6000</para></entry> - </row> - <row id="V4L2-PIX-FMT-CIT-YYVYUY"> - <entry><constant>V4L2_PIX_FMT_CIT_YYVYUY</constant></entry> - <entry>'CITV'</entry> - <entry><para>Used by xirlink CIT, found at IBM webcams.</para> - <para>Uses one line of Y then 1 line of VYUY</para> - </entry> - </row> - <row id="V4L2-PIX-FMT-KONICA420"> - <entry><constant>V4L2_PIX_FMT_KONICA420</constant></entry> - <entry>'KONI'</entry> - <entry><para>Used by Konica webcams.</para> - <para>YUV420 planar in blocks of 256 pixels.</para> - </entry> - </row> - <row id="V4L2-PIX-FMT-YYUV"> - <entry><constant>V4L2_PIX_FMT_YYUV</constant></entry> - <entry>'YYUV'</entry> - <entry>unknown</entry> - </row> - <row id="V4L2-PIX-FMT-Y4"> - <entry><constant>V4L2_PIX_FMT_Y4</constant></entry> - <entry>'Y04 '</entry> - <entry>Old 4-bit greyscale format. Only the most significant 4 bits of each byte are used, -the other bits are set to 0.</entry> - </row> - <row id="V4L2-PIX-FMT-Y6"> - <entry><constant>V4L2_PIX_FMT_Y6</constant></entry> - <entry>'Y06 '</entry> - <entry>Old 6-bit greyscale format. Only the most significant 6 bits of each byte are used, -the other bits are set to 0.</entry> - </row> - <row id="V4L2-PIX-FMT-S5C-UYVY-JPG"> - <entry><constant>V4L2_PIX_FMT_S5C_UYVY_JPG</constant></entry> - <entry>'S5CI'</entry> - <entry>Two-planar format used by Samsung S5C73MX cameras. The -first plane contains interleaved JPEG and UYVY image data, followed by meta data -in form of an array of offsets to the UYVY data blocks. The actual pointer array -follows immediately the interleaved JPEG/UYVY data, the number of entries in -this array equals the height of the UYVY image. Each entry is a 4-byte unsigned -integer in big endian order and it's an offset to a single pixel line of the -UYVY image. The first plane can start either with JPEG or UYVY data chunk. The -size of a single UYVY block equals the UYVY image's width multiplied by 2. The -size of a JPEG chunk depends on the image and can vary with each line. -<para>The second plane, at an offset of 4084 bytes, contains a 4-byte offset to -the pointer array in the first plane. This offset is followed by a 4-byte value -indicating size of the pointer array. All numbers in the second plane are also -in big endian order. Remaining data in the second plane is undefined. The -information in the second plane allows to easily find location of the pointer -array, which can be different for each frame. The size of the pointer array is -constant for given UYVY image height.</para> -<para>In order to extract UYVY and JPEG frames an application can initially set -a data pointer to the start of first plane and then add an offset from the first -entry of the pointers table. Such a pointer indicates start of an UYVY image -pixel line. Whole UYVY line can be copied to a separate buffer. These steps -should be repeated for each line, i.e. the number of entries in the pointer -array. Anything what's in between the UYVY lines is JPEG data and should be -concatenated to form the JPEG stream. </para> -</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="format-flags"> - <title>Format Flags</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_PIX_FMT_FLAG_PREMUL_ALPHA</constant></entry> - <entry>0x00000001</entry> - <entry>The color values are premultiplied by the alpha channel -value. For example, if a light blue pixel with 50% transparency was described by -RGBA values (128, 192, 255, 128), the same pixel described with premultiplied -colors would be described by RGBA values (64, 96, 128, 128) </entry> - </row> - </tbody> - </tgroup> - </table> - </section> diff --git a/Documentation/DocBook/media/v4l/planar-apis.xml b/Documentation/DocBook/media/v4l/planar-apis.xml deleted file mode 100644 index 878ce2040488..000000000000 --- a/Documentation/DocBook/media/v4l/planar-apis.xml +++ /dev/null @@ -1,62 +0,0 @@ -<section id="planar-apis"> - <title>Single- and multi-planar APIs</title> - - <para>Some devices require data for each input or output video frame - to be placed in discontiguous memory buffers. In such cases, one - video frame has to be addressed using more than one memory address, i.e. one - pointer per "plane". A plane is a sub-buffer of the current frame. For - examples of such formats see <xref linkend="pixfmt" />.</para> - - <para>Initially, V4L2 API did not support multi-planar buffers and a set of - extensions has been introduced to handle them. Those extensions constitute - what is being referred to as the "multi-planar API".</para> - - <para>Some of the V4L2 API calls and structures are interpreted differently, - depending on whether single- or multi-planar API is being used. An application - can choose whether to use one or the other by passing a corresponding buffer - type to its ioctl calls. Multi-planar versions of buffer types are suffixed - with an `_MPLANE' string. For a list of available multi-planar buffer types - see &v4l2-buf-type;. - </para> - - <section> - <title>Multi-planar formats</title> - <para>Multi-planar API introduces new multi-planar formats. Those formats - use a separate set of FourCC codes. It is important to distinguish between - the multi-planar API and a multi-planar format. Multi-planar API calls can - handle all single-planar formats as well (as long as they are passed in - multi-planar API structures), while the single-planar API cannot - handle multi-planar formats.</para> - </section> - - <section> - <title>Calls that distinguish between single and multi-planar APIs</title> - <variablelist> - <varlistentry> - <term>&VIDIOC-QUERYCAP;</term> - <listitem><para>Two additional multi-planar capabilities are added. They can - be set together with non-multi-planar ones for devices that handle - both single- and multi-planar formats.</para></listitem> - </varlistentry> - <varlistentry> - <term>&VIDIOC-G-FMT;, &VIDIOC-S-FMT;, &VIDIOC-TRY-FMT;</term> - <listitem><para>New structures for describing multi-planar formats are added: - &v4l2-pix-format-mplane; and &v4l2-plane-pix-format;. Drivers may - define new multi-planar formats, which have distinct FourCC codes from - the existing single-planar ones.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>&VIDIOC-QBUF;, &VIDIOC-DQBUF;, &VIDIOC-QUERYBUF;</term> - <listitem><para>A new &v4l2-plane; structure for describing planes is added. - Arrays of this structure are passed in the new - <structfield>m.planes</structfield> field of &v4l2-buffer;.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>&VIDIOC-REQBUFS;</term> - <listitem><para>Will allocate multi-planar buffers as requested.</para></listitem> - </varlistentry> - </variablelist> - </section> -</section> diff --git a/Documentation/DocBook/media/v4l/remote_controllers.xml b/Documentation/DocBook/media/v4l/remote_controllers.xml deleted file mode 100644 index b86844e80257..000000000000 --- a/Documentation/DocBook/media/v4l/remote_controllers.xml +++ /dev/null @@ -1,320 +0,0 @@ -<partinfo> -<authorgroup> -<author> -<firstname>Mauro</firstname> -<surname>Chehab</surname> -<othername role="mi">Carvalho</othername> -<affiliation><address><email>m.chehab@samsung.com</email></address></affiliation> -<contrib>Initial version.</contrib> -</author> -</authorgroup> -<copyright> - <year>2009-2014</year> - <holder>Mauro Carvalho Chehab</holder> -</copyright> - -<revhistory> -<!-- Put document revisions here, newest first. --> -<revision> -<revnumber>3.15</revnumber> -<date>2014-02-06</date> -<authorinitials>mcc</authorinitials> -<revremark>Added the interface description and the RC sysfs class description.</revremark> -</revision> -<revision> -<revnumber>1.0</revnumber> -<date>2009-09-06</date> -<authorinitials>mcc</authorinitials> -<revremark>Initial revision</revremark> -</revision> -</revhistory> -</partinfo> - - <title>Remote Controller API</title> - <chapter id="remote_controllers"> - -<title>Remote Controllers</title> - -<section id="Remote_controllers_Intro"> -<title>Introduction</title> - -<para>Currently, most analog and digital devices have a Infrared input for remote controllers. Each -manufacturer has their own type of control. It is not rare for the same manufacturer to ship different -types of controls, depending on the device.</para> -<para>A Remote Controller interface is mapped as a normal evdev/input interface, just like a keyboard or a mouse. -So, it uses all ioctls already defined for any other input devices.</para> -<para>However, remove controllers are more flexible than a normal input device, as the IR -receiver (and/or transmitter) can be used in conjunction with a wide variety of different IR remotes.</para> -<para>In order to allow flexibility, the Remote Controller subsystem allows controlling the -RC-specific attributes via <link linkend="remote_controllers_sysfs_nodes">the sysfs class nodes</link>.</para> -</section> - -<section id="remote_controllers_sysfs_nodes"> -<title>Remote Controller's sysfs nodes</title> -<para>As defined at <constant>Documentation/ABI/testing/sysfs-class-rc</constant>, those are the sysfs nodes that control the Remote Controllers:</para> - -<section id="sys_class_rc"> -<title>/sys/class/rc/</title> -<para>The <constant>/sys/class/rc/</constant> class sub-directory belongs to the Remote Controller -core and provides a sysfs interface for configuring infrared remote controller receivers. -</para> - -</section> -<section id="sys_class_rc_rcN"> -<title>/sys/class/rc/rcN/</title> -<para>A <constant>/sys/class/rc/rcN</constant> directory is created for each remote - control receiver device where N is the number of the receiver.</para> - -</section> -<section id="sys_class_rc_rcN_protocols"> -<title>/sys/class/rc/rcN/protocols</title> -<para>Reading this file returns a list of available protocols, something like:</para> -<para><constant>rc5 [rc6] nec jvc [sony]</constant></para> -<para>Enabled protocols are shown in [] brackets.</para> -<para>Writing "+proto" will add a protocol to the list of enabled protocols.</para> -<para>Writing "-proto" will remove a protocol from the list of enabled protocols.</para> -<para>Writing "proto" will enable only "proto".</para> -<para>Writing "none" will disable all protocols.</para> -<para>Write fails with EINVAL if an invalid protocol combination or unknown protocol name is used.</para> - -</section> -<section id="sys_class_rc_rcN_filter"> -<title>/sys/class/rc/rcN/filter</title> -<para>Sets the scancode filter expected value.</para> -<para>Use in combination with <constant>/sys/class/rc/rcN/filter_mask</constant> to set the -expected value of the bits set in the filter mask. -If the hardware supports it then scancodes which do not match -the filter will be ignored. Otherwise the write will fail with -an error.</para> -<para>This value may be reset to 0 if the current protocol is altered.</para> - -</section> -<section id="sys_class_rc_rcN_filter_mask"> -<title>/sys/class/rc/rcN/filter_mask</title> -<para>Sets the scancode filter mask of bits to compare. -Use in combination with <constant>/sys/class/rc/rcN/filter</constant> to set the bits -of the scancode which should be compared against the expected -value. A value of 0 disables the filter to allow all valid -scancodes to be processed.</para> -<para>If the hardware supports it then scancodes which do not match -the filter will be ignored. Otherwise the write will fail with -an error.</para> -<para>This value may be reset to 0 if the current protocol is altered.</para> - -</section> -<section id="sys_class_rc_rcN_wakeup_protocols"> -<title>/sys/class/rc/rcN/wakeup_protocols</title> -<para>Reading this file returns a list of available protocols to use for the -wakeup filter, something like:</para> -<para><constant>rc5 rc6 nec jvc [sony]</constant></para> -<para>The enabled wakeup protocol is shown in [] brackets.</para> -<para>Writing "+proto" will add a protocol to the list of enabled wakeup -protocols.</para> -<para>Writing "-proto" will remove a protocol from the list of enabled wakeup -protocols.</para> -<para>Writing "proto" will use "proto" for wakeup events.</para> -<para>Writing "none" will disable wakeup.</para> -<para>Write fails with EINVAL if an invalid protocol combination or unknown -protocol name is used, or if wakeup is not supported by the hardware.</para> - -</section> -<section id="sys_class_rc_rcN_wakeup_filter"> -<title>/sys/class/rc/rcN/wakeup_filter</title> -<para>Sets the scancode wakeup filter expected value. -Use in combination with <constant>/sys/class/rc/rcN/wakeup_filter_mask</constant> to -set the expected value of the bits set in the wakeup filter mask -to trigger a system wake event.</para> -<para>If the hardware supports it and wakeup_filter_mask is not 0 then -scancodes which match the filter will wake the system from e.g. -suspend to RAM or power off. -Otherwise the write will fail with an error.</para> -<para>This value may be reset to 0 if the wakeup protocol is altered.</para> - -</section> -<section id="sys_class_rc_rcN_wakeup_filter_mask"> -<title>/sys/class/rc/rcN/wakeup_filter_mask</title> -<para>Sets the scancode wakeup filter mask of bits to compare. -Use in combination with <constant>/sys/class/rc/rcN/wakeup_filter</constant> to set -the bits of the scancode which should be compared against the -expected value to trigger a system wake event.</para> -<para>If the hardware supports it and wakeup_filter_mask is not 0 then -scancodes which match the filter will wake the system from e.g. -suspend to RAM or power off. -Otherwise the write will fail with an error.</para> -<para>This value may be reset to 0 if the wakeup protocol is altered.</para> -</section> -</section> - -<section id="Remote_controllers_tables"> -<title>Remote controller tables</title> -<para>Unfortunately, for several years, there was no effort to create uniform IR keycodes for -different devices. This caused the same IR keyname to be mapped completely differently on -different IR devices. This resulted that the same IR keyname to be mapped completely different on -different IR's. Due to that, V4L2 API now specifies a standard for mapping Media keys on IR.</para> -<para>This standard should be used by both V4L/DVB drivers and userspace applications</para> -<para>The modules register the remote as keyboard within the linux input layer. This means that the IR key strokes will look like normal keyboard key strokes (if CONFIG_INPUT_KEYBOARD is enabled). Using the event devices (CONFIG_INPUT_EVDEV) it is possible for applications to access the remote via /dev/input/event devices.</para> - -<table pgwide="1" frame="none" id="rc_standard_keymap"> -<title>IR default keymapping</title> -<tgroup cols="3"> -&cs-str; -<tbody valign="top"> -<row> -<entry>Key code</entry> -<entry>Meaning</entry> -<entry>Key examples on IR</entry> -</row> - -<row><entry><emphasis role="bold">Numeric keys</emphasis></entry></row> - -<row><entry><constant>KEY_0</constant></entry><entry>Keyboard digit 0</entry><entry>0</entry></row> -<row><entry><constant>KEY_1</constant></entry><entry>Keyboard digit 1</entry><entry>1</entry></row> -<row><entry><constant>KEY_2</constant></entry><entry>Keyboard digit 2</entry><entry>2</entry></row> -<row><entry><constant>KEY_3</constant></entry><entry>Keyboard digit 3</entry><entry>3</entry></row> -<row><entry><constant>KEY_4</constant></entry><entry>Keyboard digit 4</entry><entry>4</entry></row> -<row><entry><constant>KEY_5</constant></entry><entry>Keyboard digit 5</entry><entry>5</entry></row> -<row><entry><constant>KEY_6</constant></entry><entry>Keyboard digit 6</entry><entry>6</entry></row> -<row><entry><constant>KEY_7</constant></entry><entry>Keyboard digit 7</entry><entry>7</entry></row> -<row><entry><constant>KEY_8</constant></entry><entry>Keyboard digit 8</entry><entry>8</entry></row> -<row><entry><constant>KEY_9</constant></entry><entry>Keyboard digit 9</entry><entry>9</entry></row> - -<row><entry><emphasis role="bold">Movie play control</emphasis></entry></row> - -<row><entry><constant>KEY_FORWARD</constant></entry><entry>Instantly advance in time</entry><entry>>> / FORWARD</entry></row> -<row><entry><constant>KEY_BACK</constant></entry><entry>Instantly go back in time</entry><entry><<< / BACK</entry></row> -<row><entry><constant>KEY_FASTFORWARD</constant></entry><entry>Play movie faster</entry><entry>>>> / FORWARD</entry></row> -<row><entry><constant>KEY_REWIND</constant></entry><entry>Play movie back</entry><entry>REWIND / BACKWARD</entry></row> -<row><entry><constant>KEY_NEXT</constant></entry><entry>Select next chapter / sub-chapter / interval</entry><entry>NEXT / SKIP</entry></row> -<row><entry><constant>KEY_PREVIOUS</constant></entry><entry>Select previous chapter / sub-chapter / interval</entry><entry><< / PREV / PREVIOUS</entry></row> -<row><entry><constant>KEY_AGAIN</constant></entry><entry>Repeat the video or a video interval</entry><entry>REPEAT / LOOP / RECALL</entry></row> -<row><entry><constant>KEY_PAUSE</constant></entry><entry>Pause sroweam</entry><entry>PAUSE / FREEZE</entry></row> -<row><entry><constant>KEY_PLAY</constant></entry><entry>Play movie at the normal timeshift</entry><entry>NORMAL TIMESHIFT / LIVE / ></entry></row> -<row><entry><constant>KEY_PLAYPAUSE</constant></entry><entry>Alternate between play and pause</entry><entry>PLAY / PAUSE</entry></row> -<row><entry><constant>KEY_STOP</constant></entry><entry>Stop sroweam</entry><entry>STOP</entry></row> -<row><entry><constant>KEY_RECORD</constant></entry><entry>Start/stop recording sroweam</entry><entry>CAPTURE / REC / RECORD/PAUSE</entry></row> -<row><entry><constant>KEY_CAMERA</constant></entry><entry>Take a picture of the image</entry><entry>CAMERA ICON / CAPTURE / SNAPSHOT</entry></row> -<row><entry><constant>KEY_SHUFFLE</constant></entry><entry>Enable shuffle mode</entry><entry>SHUFFLE</entry></row> -<row><entry><constant>KEY_TIME</constant></entry><entry>Activate time shift mode</entry><entry>TIME SHIFT</entry></row> -<row><entry><constant>KEY_TITLE</constant></entry><entry>Allow changing the chapter</entry><entry>CHAPTER</entry></row> -<row><entry><constant>KEY_SUBTITLE</constant></entry><entry>Allow changing the subtitle</entry><entry>SUBTITLE</entry></row> - -<row><entry><emphasis role="bold">Image control</emphasis></entry></row> - -<row><entry><constant>KEY_BRIGHTNESSDOWN</constant></entry><entry>Decrease Brightness</entry><entry>BRIGHTNESS DECREASE</entry></row> -<row><entry><constant>KEY_BRIGHTNESSUP</constant></entry><entry>Increase Brightness</entry><entry>BRIGHTNESS INCREASE</entry></row> - -<row><entry><constant>KEY_ANGLE</constant></entry><entry>Switch video camera angle (on videos with more than one angle stored)</entry><entry>ANGLE / SWAP</entry></row> -<row><entry><constant>KEY_EPG</constant></entry><entry>Open the Elecrowonic Play Guide (EPG)</entry><entry>EPG / GUIDE</entry></row> -<row><entry><constant>KEY_TEXT</constant></entry><entry>Activate/change closed caption mode</entry><entry>CLOSED CAPTION/TELETEXT / DVD TEXT / TELETEXT / TTX</entry></row> - -<row><entry><emphasis role="bold">Audio control</emphasis></entry></row> - -<row><entry><constant>KEY_AUDIO</constant></entry><entry>Change audio source</entry><entry>AUDIO SOURCE / AUDIO / MUSIC</entry></row> -<row><entry><constant>KEY_MUTE</constant></entry><entry>Mute/unmute audio</entry><entry>MUTE / DEMUTE / UNMUTE</entry></row> -<row><entry><constant>KEY_VOLUMEDOWN</constant></entry><entry>Decrease volume</entry><entry>VOLUME- / VOLUME DOWN</entry></row> -<row><entry><constant>KEY_VOLUMEUP</constant></entry><entry>Increase volume</entry><entry>VOLUME+ / VOLUME UP</entry></row> -<row><entry><constant>KEY_MODE</constant></entry><entry>Change sound mode</entry><entry>MONO/STEREO</entry></row> -<row><entry><constant>KEY_LANGUAGE</constant></entry><entry>Select Language</entry><entry>1ST / 2ND LANGUAGE / DVD LANG / MTS/SAP / MTS SEL</entry></row> - -<row><entry><emphasis role="bold">Channel control</emphasis></entry></row> - -<row><entry><constant>KEY_CHANNEL</constant></entry><entry>Go to the next favorite channel</entry><entry>ALT / CHANNEL / CH SURFING / SURF / FAV</entry></row> -<row><entry><constant>KEY_CHANNELDOWN</constant></entry><entry>Decrease channel sequencially</entry><entry>CHANNEL - / CHANNEL DOWN / DOWN</entry></row> -<row><entry><constant>KEY_CHANNELUP</constant></entry><entry>Increase channel sequencially</entry><entry>CHANNEL + / CHANNEL UP / UP</entry></row> -<row><entry><constant>KEY_DIGITS</constant></entry><entry>Use more than one digit for channel</entry><entry>PLUS / 100/ 1xx / xxx / -/-- / Single Double Triple Digit</entry></row> -<row><entry><constant>KEY_SEARCH</constant></entry><entry>Start channel autoscan</entry><entry>SCAN / AUTOSCAN</entry></row> - -<row><entry><emphasis role="bold">Colored keys</emphasis></entry></row> - -<row><entry><constant>KEY_BLUE</constant></entry><entry>IR Blue key</entry><entry>BLUE</entry></row> -<row><entry><constant>KEY_GREEN</constant></entry><entry>IR Green Key</entry><entry>GREEN</entry></row> -<row><entry><constant>KEY_RED</constant></entry><entry>IR Red key</entry><entry>RED</entry></row> -<row><entry><constant>KEY_YELLOW</constant></entry><entry>IR Yellow key</entry><entry> YELLOW</entry></row> - -<row><entry><emphasis role="bold">Media selection</emphasis></entry></row> - -<row><entry><constant>KEY_CD</constant></entry><entry>Change input source to Compact Disc</entry><entry>CD</entry></row> -<row><entry><constant>KEY_DVD</constant></entry><entry>Change input to DVD</entry><entry>DVD / DVD MENU</entry></row> -<row><entry><constant>KEY_EJECTCLOSECD</constant></entry><entry>Open/close the CD/DVD player</entry><entry>-> ) / CLOSE / OPEN</entry></row> - -<row><entry><constant>KEY_MEDIA</constant></entry><entry>Turn on/off Media application</entry><entry>PC/TV / TURN ON/OFF APP</entry></row> -<row><entry><constant>KEY_PC</constant></entry><entry>Selects from TV to PC</entry><entry>PC</entry></row> -<row><entry><constant>KEY_RADIO</constant></entry><entry>Put into AM/FM radio mode</entry><entry>RADIO / TV/FM / TV/RADIO / FM / FM/RADIO</entry></row> -<row><entry><constant>KEY_TV</constant></entry><entry>Select tv mode</entry><entry>TV / LIVE TV</entry></row> -<row><entry><constant>KEY_TV2</constant></entry><entry>Select Cable mode</entry><entry>AIR/CBL</entry></row> -<row><entry><constant>KEY_VCR</constant></entry><entry>Select VCR mode</entry><entry>VCR MODE / DTR</entry></row> -<row><entry><constant>KEY_VIDEO</constant></entry><entry>Alternate between input modes</entry><entry>SOURCE / SELECT / DISPLAY / SWITCH INPUTS / VIDEO</entry></row> - -<row><entry><emphasis role="bold">Power control</emphasis></entry></row> - -<row><entry><constant>KEY_POWER</constant></entry><entry>Turn on/off computer</entry><entry>SYSTEM POWER / COMPUTER POWER</entry></row> -<row><entry><constant>KEY_POWER2</constant></entry><entry>Turn on/off application</entry><entry>TV ON/OFF / POWER</entry></row> -<row><entry><constant>KEY_SLEEP</constant></entry><entry>Activate sleep timer</entry><entry>SLEEP / SLEEP TIMER</entry></row> -<row><entry><constant>KEY_SUSPEND</constant></entry><entry>Put computer into suspend mode</entry><entry>STANDBY / SUSPEND</entry></row> - -<row><entry><emphasis role="bold">Window control</emphasis></entry></row> - -<row><entry><constant>KEY_CLEAR</constant></entry><entry>Stop sroweam and return to default input video/audio</entry><entry>CLEAR / RESET / BOSS KEY</entry></row> -<row><entry><constant>KEY_CYCLEWINDOWS</constant></entry><entry>Minimize windows and move to the next one</entry><entry>ALT-TAB / MINIMIZE / DESKTOP</entry></row> -<row><entry><constant>KEY_FAVORITES</constant></entry><entry>Open the favorites sroweam window</entry><entry>TV WALL / Favorites</entry></row> -<row><entry><constant>KEY_MENU</constant></entry><entry>Call application menu</entry><entry>2ND CONTROLS (USA: MENU) / DVD/MENU / SHOW/HIDE CTRL</entry></row> -<row><entry><constant>KEY_NEW</constant></entry><entry>Open/Close Picture in Picture</entry><entry>PIP</entry></row> -<row><entry><constant>KEY_OK</constant></entry><entry>Send a confirmation code to application</entry><entry>OK / ENTER / RETURN</entry></row> -<row><entry><constant>KEY_SCREEN</constant></entry><entry>Select screen aspect ratio</entry><entry>4:3 16:9 SELECT</entry></row> -<row><entry><constant>KEY_ZOOM</constant></entry><entry>Put device into zoom/full screen mode</entry><entry>ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH</entry></row> - -<row><entry><emphasis role="bold">Navigation keys</emphasis></entry></row> - -<row><entry><constant>KEY_ESC</constant></entry><entry>Cancel current operation</entry><entry>CANCEL / BACK</entry></row> -<row><entry><constant>KEY_HELP</constant></entry><entry>Open a Help window</entry><entry>HELP</entry></row> -<row><entry><constant>KEY_HOMEPAGE</constant></entry><entry>Navigate to Homepage</entry><entry>HOME</entry></row> -<row><entry><constant>KEY_INFO</constant></entry><entry>Open On Screen Display</entry><entry>DISPLAY INFORMATION / OSD</entry></row> -<row><entry><constant>KEY_WWW</constant></entry><entry>Open the default browser</entry><entry>WEB</entry></row> -<row><entry><constant>KEY_UP</constant></entry><entry>Up key</entry><entry>UP</entry></row> -<row><entry><constant>KEY_DOWN</constant></entry><entry>Down key</entry><entry>DOWN</entry></row> -<row><entry><constant>KEY_LEFT</constant></entry><entry>Left key</entry><entry>LEFT</entry></row> -<row><entry><constant>KEY_RIGHT</constant></entry><entry>Right key</entry><entry>RIGHT</entry></row> - -<row><entry><emphasis role="bold">Miscellaneous keys</emphasis></entry></row> - -<row><entry><constant>KEY_DOT</constant></entry><entry>Return a dot</entry><entry>.</entry></row> -<row><entry><constant>KEY_FN</constant></entry><entry>Select a function</entry><entry>FUNCTION</entry></row> - -</tbody> -</tgroup> -</table> - -<para>It should be noted that, sometimes, there some fundamental missing keys at some cheaper IR's. Due to that, it is recommended to:</para> - -<table pgwide="1" frame="none" id="rc_keymap_notes"> -<title>Notes</title> -<tgroup cols="1"> -&cs-str; -<tbody valign="top"> -<row> -<entry>On simpler IR's, without separate channel keys, you need to map UP as <constant>KEY_CHANNELUP</constant></entry> -</row><row> -<entry>On simpler IR's, without separate channel keys, you need to map DOWN as <constant>KEY_CHANNELDOWN</constant></entry> -</row><row> -<entry>On simpler IR's, without separate volume keys, you need to map LEFT as <constant>KEY_VOLUMEDOWN</constant></entry> -</row><row> -<entry>On simpler IR's, without separate volume keys, you need to map RIGHT as <constant>KEY_VOLUMEUP</constant></entry> -</row> -</tbody> -</tgroup> -</table> - -</section> - -<section id="Remote_controllers_table_change"> -<title>Changing default Remote Controller mappings</title> -<para>The event interface provides two ioctls to be used against -the /dev/input/event device, to allow changing the default -keymapping.</para> - -<para>This program demonstrates how to replace the keymap tables.</para> -&sub-keytable-c; -</section> - -&sub-lirc_device_interface; -</chapter> diff --git a/Documentation/DocBook/media/v4l/selection-api.xml b/Documentation/DocBook/media/v4l/selection-api.xml deleted file mode 100644 index 28cbded766c9..000000000000 --- a/Documentation/DocBook/media/v4l/selection-api.xml +++ /dev/null @@ -1,324 +0,0 @@ -<section id="selection-api"> - - <title>Experimental API for cropping, composing and scaling</title> - - <note> - <title>Experimental</title> - - <para>This is an <link linkend="experimental">experimental</link> -interface and may change in the future.</para> - </note> - - <section> - <title>Introduction</title> - -<para>Some video capture devices can sample a subsection of a picture and -shrink or enlarge it to an image of arbitrary size. Next, the devices can -insert the image into larger one. Some video output devices can crop part of an -input image, scale it up or down and insert it at an arbitrary scan line and -horizontal offset into a video signal. We call these abilities cropping, -scaling and composing.</para> - -<para>On a video <emphasis>capture</emphasis> device the source is a video -signal, and the cropping target determine the area actually sampled. The sink -is an image stored in a memory buffer. The composing area specifies which part -of the buffer is actually written to by the hardware. </para> - -<para>On a video <emphasis>output</emphasis> device the source is an image in a -memory buffer, and the cropping target is a part of an image to be shown on a -display. The sink is the display or the graphics screen. The application may -select the part of display where the image should be displayed. The size and -position of such a window is controlled by the compose target.</para> - -<para>Rectangles for all cropping and composing targets are defined even if the -device does supports neither cropping nor composing. Their size and position -will be fixed in such a case. If the device does not support scaling then the -cropping and composing rectangles have the same size.</para> - - </section> - - <section> - <title>Selection targets</title> - - <para> - <figure id="sel-targets-capture"> - <title>Cropping and composing targets</title> - <mediaobject> - <imageobject> - <imagedata fileref="selection.png" format="PNG" /> - </imageobject> - <textobject> - <phrase>Targets used by a cropping, composing and scaling - process</phrase> - </textobject> - </mediaobject> - </figure> - </para> - - <para>See <xref linkend="v4l2-selection-targets" /> for more - information.</para> - </section> - - <section> - - <title>Configuration</title> - -<para>Applications can use the <link linkend="vidioc-g-selection">selection -API</link> to select an area in a video signal or a buffer, and to query for -default settings and hardware limits.</para> - -<para>Video hardware can have various cropping, composing and scaling -limitations. It may only scale up or down, support only discrete scaling -factors, or have different scaling abilities in the horizontal and vertical -directions. Also it may not support scaling at all. At the same time the -cropping/composing rectangles may have to be aligned, and both the source and -the sink may have arbitrary upper and lower size limits. Therefore, as usual, -drivers are expected to adjust the requested parameters and return the actual -values selected. An application can control the rounding behaviour using <link -linkend="v4l2-selection-flags"> constraint flags </link>.</para> - - <section> - - <title>Configuration of video capture</title> - -<para>See figure <xref linkend="sel-targets-capture" /> for examples of the -selection targets available for a video capture device. It is recommended to -configure the cropping targets before to the composing targets.</para> - -<para>The range of coordinates of the top left corner, width and height of -areas that can be sampled is given by the <constant>V4L2_SEL_TGT_CROP_BOUNDS</constant> -target. It is recommended for the driver developers to put the -top/left corner at position <constant>(0,0)</constant>. The rectangle's -coordinates are expressed in pixels.</para> - -<para>The top left corner, width and height of the source rectangle, that is -the area actually sampled, is given by the <constant>V4L2_SEL_TGT_CROP</constant> -target. It uses the same coordinate system as <constant>V4L2_SEL_TGT_CROP_BOUNDS</constant>. -The active cropping area must lie completely inside the capture boundaries. The -driver may further adjust the requested size and/or position according to hardware -limitations.</para> - -<para>Each capture device has a default source rectangle, given by the -<constant>V4L2_SEL_TGT_CROP_DEFAULT</constant> target. This rectangle shall -over what the driver writer considers the complete picture. Drivers shall set -the active crop rectangle to the default when the driver is first loaded, but -not later.</para> - -<para>The composing targets refer to a memory buffer. The limits of composing -coordinates are obtained using <constant>V4L2_SEL_TGT_COMPOSE_BOUNDS</constant>. -All coordinates are expressed in pixels. The rectangle's top/left -corner must be located at position <constant>(0,0)</constant>. The width and -height are equal to the image size set by <constant>VIDIOC_S_FMT</constant>. -</para> - -<para>The part of a buffer into which the image is inserted by the hardware is -controlled by the <constant>V4L2_SEL_TGT_COMPOSE</constant> target. -The rectangle's coordinates are also expressed in the same coordinate system as -the bounds rectangle. The composing rectangle must lie completely inside bounds -rectangle. The driver must adjust the composing rectangle to fit to the -bounding limits. Moreover, the driver can perform other adjustments according -to hardware limitations. The application can control rounding behaviour using -<link linkend="v4l2-selection-flags"> constraint flags</link>.</para> - -<para>For capture devices the default composing rectangle is queried using -<constant>V4L2_SEL_TGT_COMPOSE_DEFAULT</constant>. It is usually equal to the -bounding rectangle.</para> - -<para>The part of a buffer that is modified by the hardware is given by -<constant>V4L2_SEL_TGT_COMPOSE_PADDED</constant>. It contains all pixels -defined using <constant>V4L2_SEL_TGT_COMPOSE</constant> plus all -padding data modified by hardware during insertion process. All pixels outside -this rectangle <emphasis>must not</emphasis> be changed by the hardware. The -content of pixels that lie inside the padded area but outside active area is -undefined. The application can use the padded and active rectangles to detect -where the rubbish pixels are located and remove them if needed.</para> - - </section> - - <section> - - <title>Configuration of video output</title> - -<para>For output devices targets and ioctls are used similarly to the video -capture case. The <emphasis>composing</emphasis> rectangle refers to the -insertion of an image into a video signal. The cropping rectangles refer to a -memory buffer. It is recommended to configure the composing targets before to -the cropping targets.</para> - -<para>The cropping targets refer to the memory buffer that contains an image to -be inserted into a video signal or graphical screen. The limits of cropping -coordinates are obtained using <constant>V4L2_SEL_TGT_CROP_BOUNDS</constant>. -All coordinates are expressed in pixels. The top/left corner is always point -<constant>(0,0)</constant>. The width and height is equal to the image size -specified using <constant>VIDIOC_S_FMT</constant> ioctl.</para> - -<para>The top left corner, width and height of the source rectangle, that is -the area from which image date are processed by the hardware, is given by the -<constant>V4L2_SEL_TGT_CROP</constant>. Its coordinates are expressed -in in the same coordinate system as the bounds rectangle. The active cropping -area must lie completely inside the crop boundaries and the driver may further -adjust the requested size and/or position according to hardware -limitations.</para> - -<para>For output devices the default cropping rectangle is queried using -<constant>V4L2_SEL_TGT_CROP_DEFAULT</constant>. It is usually equal to the -bounding rectangle.</para> - -<para>The part of a video signal or graphics display where the image is -inserted by the hardware is controlled by <constant>V4L2_SEL_TGT_COMPOSE</constant> -target. The rectangle's coordinates are expressed in pixels. The composing -rectangle must lie completely inside the bounds rectangle. The driver must -adjust the area to fit to the bounding limits. Moreover, the driver can -perform other adjustments according to hardware limitations.</para> - -<para>The device has a default composing rectangle, given by the -<constant>V4L2_SEL_TGT_COMPOSE_DEFAULT</constant> target. This rectangle shall cover what -the driver writer considers the complete picture. It is recommended for the -driver developers to put the top/left corner at position <constant>(0,0)</constant>. -Drivers shall set the active composing rectangle to the default -one when the driver is first loaded.</para> - -<para>The devices may introduce additional content to video signal other than -an image from memory buffers. It includes borders around an image. However, -such a padded area is driver-dependent feature not covered by this document. -Driver developers are encouraged to keep padded rectangle equal to active one. -The padded target is accessed by the <constant>V4L2_SEL_TGT_COMPOSE_PADDED</constant> -identifier. It must contain all pixels from the <constant>V4L2_SEL_TGT_COMPOSE</constant> -target.</para> - - </section> - - <section> - - <title>Scaling control</title> - -<para>An application can detect if scaling is performed by comparing the width -and the height of rectangles obtained using <constant>V4L2_SEL_TGT_CROP</constant> -and <constant>V4L2_SEL_TGT_COMPOSE</constant> targets. If -these are not equal then the scaling is applied. The application can compute -the scaling ratios using these values.</para> - - </section> - - </section> - - <section> - - <title>Comparison with old cropping API</title> - -<para>The selection API was introduced to cope with deficiencies of previous -<link linkend="crop"> API</link>, that was designed to control simple capture -devices. Later the cropping API was adopted by video output drivers. The ioctls -are used to select a part of the display were the video signal is inserted. It -should be considered as an API abuse because the described operation is -actually the composing. The selection API makes a clear distinction between -composing and cropping operations by setting the appropriate targets. The V4L2 -API lacks any support for composing to and cropping from an image inside a -memory buffer. The application could configure a capture device to fill only a -part of an image by abusing V4L2 API. Cropping a smaller image from a larger -one is achieved by setting the field -&v4l2-pix-format;<structfield>::bytesperline</structfield>. Introducing an image offsets -could be done by modifying field &v4l2-buffer;<structfield>::m_userptr</structfield> -before calling <constant>VIDIOC_QBUF</constant>. Those -operations should be avoided because they are not portable (endianness), and do -not work for macroblock and Bayer formats and mmap buffers. The selection API -deals with configuration of buffer cropping/composing in a clear, intuitive and -portable way. Next, with the selection API the concepts of the padded target -and constraints flags are introduced. Finally, &v4l2-crop; and &v4l2-cropcap; -have no reserved fields. Therefore there is no way to extend their functionality. -The new &v4l2-selection; provides a lot of place for future -extensions. Driver developers are encouraged to implement only selection API. -The former cropping API would be simulated using the new one.</para> - - </section> - - <section> - <title>Examples</title> - <example> - <title>Resetting the cropping parameters</title> - - <para>(A video capture device is assumed; change -<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> for other devices; change target to -<constant>V4L2_SEL_TGT_COMPOSE_*</constant> family to configure composing -area)</para> - - <programlisting> - - &v4l2-selection; sel = { - .type = V4L2_BUF_TYPE_VIDEO_CAPTURE, - .target = V4L2_SEL_TGT_CROP_DEFAULT, - }; - ret = ioctl(fd, &VIDIOC-G-SELECTION;, &sel); - if (ret) - exit(-1); - sel.target = V4L2_SEL_TGT_CROP; - ret = ioctl(fd, &VIDIOC-S-SELECTION;, &sel); - if (ret) - exit(-1); - - </programlisting> - </example> - - <example> - <title>Simple downscaling</title> - <para>Setting a composing area on output of size of <emphasis> at most -</emphasis> half of limit placed at a center of a display.</para> - <programlisting> - - &v4l2-selection; sel = { - .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, - .target = V4L2_SEL_TGT_COMPOSE_BOUNDS, - }; - struct v4l2_rect r; - - ret = ioctl(fd, &VIDIOC-G-SELECTION;, &sel); - if (ret) - exit(-1); - /* setting smaller compose rectangle */ - r.width = sel.r.width / 2; - r.height = sel.r.height / 2; - r.left = sel.r.width / 4; - r.top = sel.r.height / 4; - sel.r = r; - sel.target = V4L2_SEL_TGT_COMPOSE; - sel.flags = V4L2_SEL_FLAG_LE; - ret = ioctl(fd, &VIDIOC-S-SELECTION;, &sel); - if (ret) - exit(-1); - - </programlisting> - </example> - - <example> - <title>Querying for scaling factors</title> - <para>A video output device is assumed; change -<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> for other devices</para> - <programlisting> - - &v4l2-selection; compose = { - .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, - .target = V4L2_SEL_TGT_COMPOSE, - }; - &v4l2-selection; crop = { - .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, - .target = V4L2_SEL_TGT_CROP, - }; - double hscale, vscale; - - ret = ioctl(fd, &VIDIOC-G-SELECTION;, &compose); - if (ret) - exit(-1); - ret = ioctl(fd, &VIDIOC-G-SELECTION;, &crop); - if (ret) - exit(-1); - - /* computing scaling factors */ - hscale = (double)compose.r.width / crop.r.width; - vscale = (double)compose.r.height / crop.r.height; - - </programlisting> - </example> - - </section> - -</section> diff --git a/Documentation/DocBook/media/v4l/selections-common.xml b/Documentation/DocBook/media/v4l/selections-common.xml deleted file mode 100644 index d6d56fb6f9c0..000000000000 --- a/Documentation/DocBook/media/v4l/selections-common.xml +++ /dev/null @@ -1,180 +0,0 @@ -<section id="v4l2-selections-common"> - - <title>Common selection definitions</title> - - <para>While the <link linkend="selection-api">V4L2 selection - API</link> and <link linkend="v4l2-subdev-selections">V4L2 subdev - selection APIs</link> are very similar, there's one fundamental - difference between the two. On sub-device API, the selection - rectangle refers to the media bus format, and is bound to a - sub-device's pad. On the V4L2 interface the selection rectangles - refer to the in-memory pixel format.</para> - - <para>This section defines the common definitions of the - selection interfaces on the two APIs.</para> - - <section id="v4l2-selection-targets"> - - <title>Selection targets</title> - - <para>The precise meaning of the selection targets may be - dependent on which of the two interfaces they are used.</para> - - <table pgwide="1" frame="none" id="v4l2-selection-targets-table"> - <title>Selection target definitions</title> - <tgroup cols="5"> - <colspec colname="c1" /> - <colspec colname="c2" /> - <colspec colname="c3" /> - <colspec colname="c4" /> - <colspec colname="c5" /> - &cs-def; - <thead> - <row rowsep="1"> - <entry align="left">Target name</entry> - <entry align="left">id</entry> - <entry align="left">Definition</entry> - <entry align="left">Valid for V4L2</entry> - <entry align="left">Valid for V4L2 subdev</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry><constant>V4L2_SEL_TGT_CROP</constant></entry> - <entry>0x0000</entry> - <entry>Crop rectangle. Defines the cropped area.</entry> - <entry>Yes</entry> - <entry>Yes</entry> - </row> - <row> - <entry><constant>V4L2_SEL_TGT_CROP_DEFAULT</constant></entry> - <entry>0x0001</entry> - <entry>Suggested cropping rectangle that covers the "whole picture".</entry> - <entry>Yes</entry> - <entry>No</entry> - </row> - <row> - <entry><constant>V4L2_SEL_TGT_CROP_BOUNDS</constant></entry> - <entry>0x0002</entry> - <entry>Bounds of the crop rectangle. All valid crop - rectangles fit inside the crop bounds rectangle. - </entry> - <entry>Yes</entry> - <entry>Yes</entry> - </row> - <row> - <entry><constant>V4L2_SEL_TGT_NATIVE_SIZE</constant></entry> - <entry>0x0003</entry> - <entry>The native size of the device, e.g. a sensor's - pixel array. <structfield>left</structfield> and - <structfield>top</structfield> fields are zero for this - target. Setting the native size will generally only make - sense for memory to memory devices where the software can - create a canvas of a given size in which for example a - video frame can be composed. In that case - V4L2_SEL_TGT_NATIVE_SIZE can be used to configure the size - of that canvas. - </entry> - <entry>Yes</entry> - <entry>Yes</entry> - </row> - <row> - <entry><constant>V4L2_SEL_TGT_COMPOSE</constant></entry> - <entry>0x0100</entry> - <entry>Compose rectangle. Used to configure scaling - and composition.</entry> - <entry>Yes</entry> - <entry>Yes</entry> - </row> - <row> - <entry><constant>V4L2_SEL_TGT_COMPOSE_DEFAULT</constant></entry> - <entry>0x0101</entry> - <entry>Suggested composition rectangle that covers the "whole picture".</entry> - <entry>Yes</entry> - <entry>No</entry> - </row> - <row> - <entry><constant>V4L2_SEL_TGT_COMPOSE_BOUNDS</constant></entry> - <entry>0x0102</entry> - <entry>Bounds of the compose rectangle. All valid compose - rectangles fit inside the compose bounds rectangle.</entry> - <entry>Yes</entry> - <entry>Yes</entry> - </row> - <row> - <entry><constant>V4L2_SEL_TGT_COMPOSE_PADDED</constant></entry> - <entry>0x0103</entry> - <entry>The active area and all padding pixels that are inserted or - modified by hardware.</entry> - <entry>Yes</entry> - <entry>No</entry> - </row> - </tbody> - </tgroup> - </table> - - </section> - - <section id="v4l2-selection-flags"> - - <title>Selection flags</title> - - <table pgwide="1" frame="none" id="v4l2-selection-flags-table"> - <title>Selection flag definitions</title> - <tgroup cols="5"> - <colspec colname="c1" /> - <colspec colname="c2" /> - <colspec colname="c3" /> - <colspec colname="c4" /> - <colspec colname="c5" /> - &cs-def; - <thead> - <row rowsep="1"> - <entry align="left">Flag name</entry> - <entry align="left">id</entry> - <entry align="left">Definition</entry> - <entry align="left">Valid for V4L2</entry> - <entry align="left">Valid for V4L2 subdev</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry><constant>V4L2_SEL_FLAG_GE</constant></entry> - <entry>(1 << 0)</entry> - <entry>Suggest the driver it should choose greater or - equal rectangle (in size) than was requested. Albeit the - driver may choose a lesser size, it will only do so due to - hardware limitations. Without this flag (and - <constant>V4L2_SEL_FLAG_LE</constant>) the - behaviour is to choose the closest possible - rectangle.</entry> - <entry>Yes</entry> - <entry>Yes</entry> - </row> - <row> - <entry><constant>V4L2_SEL_FLAG_LE</constant></entry> - <entry>(1 << 1)</entry> - <entry>Suggest the driver it - should choose lesser or equal rectangle (in size) than was - requested. Albeit the driver may choose a greater size, it - will only do so due to hardware limitations.</entry> - <entry>Yes</entry> - <entry>Yes</entry> - </row> - <row> - <entry><constant>V4L2_SEL_FLAG_KEEP_CONFIG</constant></entry> - <entry>(1 << 2)</entry> - <entry>The configuration must not be propagated to any - further processing steps. If this flag is not given, the - configuration is propagated inside the subdevice to all - further processing steps.</entry> - <entry>No</entry> - <entry>Yes</entry> - </row> - </tbody> - </tgroup> - </table> - - </section> - -</section> diff --git a/Documentation/DocBook/media/v4l/subdev-formats.xml b/Documentation/DocBook/media/v4l/subdev-formats.xml deleted file mode 100644 index 4e73345e3eab..000000000000 --- a/Documentation/DocBook/media/v4l/subdev-formats.xml +++ /dev/null @@ -1,4046 +0,0 @@ -<section id="v4l2-mbus-format"> - <title>Media Bus Formats</title> - - <table pgwide="1" frame="none" id="v4l2-mbus-framefmt"> - <title>struct <structname>v4l2_mbus_framefmt</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>width</structfield></entry> - <entry>Image width, in pixels.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>height</structfield></entry> - <entry>Image height, in pixels.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>code</structfield></entry> - <entry>Format code, from &v4l2-mbus-pixelcode;.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>field</structfield></entry> - <entry>Field order, from &v4l2-field;. See - <xref linkend="field-order" /> for details.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>colorspace</structfield></entry> - <entry>Image colorspace, from &v4l2-colorspace;. See - <xref linkend="colorspaces" /> for details.</entry> - </row> - <row> - <entry>&v4l2-ycbcr-encoding;</entry> - <entry><structfield>ycbcr_enc</structfield></entry> - <entry>This information supplements the -<structfield>colorspace</structfield> and must be set by the driver for -capture streams and by the application for output streams, -see <xref linkend="colorspaces" />.</entry> - </row> - <row> - <entry>&v4l2-quantization;</entry> - <entry><structfield>quantization</structfield></entry> - <entry>This information supplements the -<structfield>colorspace</structfield> and must be set by the driver for -capture streams and by the application for output streams, -see <xref linkend="colorspaces" />.</entry> - </row> - <row> - <entry>&v4l2-xfer-func;</entry> - <entry><structfield>xfer_func</structfield></entry> - <entry>This information supplements the -<structfield>colorspace</structfield> and must be set by the driver for -capture streams and by the application for output streams, -see <xref linkend="colorspaces" />.</entry> - </row> - <row> - <entry>__u16</entry> - <entry><structfield>reserved</structfield>[11]</entry> - <entry>Reserved for future extensions. Applications and drivers must - set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <section id="v4l2-mbus-pixelcode"> - <title>Media Bus Pixel Codes</title> - - <para>The media bus pixel codes describe image formats as flowing over - physical busses (both between separate physical components and inside SoC - devices). This should not be confused with the V4L2 pixel formats that - describe, using four character codes, image formats as stored in memory. - </para> - - <para>While there is a relationship between image formats on busses and - image formats in memory (a raw Bayer image won't be magically converted to - JPEG just by storing it to memory), there is no one-to-one correspondance - between them.</para> - - <section> - <title>Packed RGB Formats</title> - - <para>Those formats transfer pixel data as red, green and blue components. - The format code is made of the following information. - <itemizedlist> - <listitem><para>The red, green and blue components order code, as encoded in a - pixel sample. Possible values are RGB and BGR.</para></listitem> - <listitem><para>The number of bits per component, for each component. The values - can be different for all components. Common values are 555 and 565.</para> - </listitem> - <listitem><para>The number of bus samples per pixel. Pixels that are wider than - the bus width must be transferred in multiple samples. Common values are - 1 and 2.</para></listitem> - <listitem><para>The bus width.</para></listitem> - <listitem><para>For formats where the total number of bits per pixel is smaller - than the number of bus samples per pixel times the bus width, a padding - value stating if the bytes are padded in their most high order bits - (PADHI) or low order bits (PADLO). A "C" prefix is used for component-wise - padding in the most high order bits (CPADHI) or low order bits (CPADLO) - of each separate component.</para></listitem> - <listitem><para>For formats where the number of bus samples per pixel is larger - than 1, an endianness value stating if the pixel is transferred MSB first - (BE) or LSB first (LE).</para></listitem> - </itemizedlist> - </para> - - <para>For instance, a format where pixels are encoded as 5-bits red, 5-bits - green and 5-bit blue values padded on the high bit, transferred as 2 8-bit - samples per pixel with the most significant bits (padding, red and half of - the green value) transferred first will be named - <constant>MEDIA_BUS_FMT_RGB555_2X8_PADHI_BE</constant>. - </para> - - <para>The following tables list existing packed RGB formats.</para> - - <table pgwide="0" frame="none" id="v4l2-mbus-pixelcode-rgb"> - <title>RGB formats</title> - <tgroup cols="27"> - <colspec colname="id" align="left" /> - <colspec colname="code" align="center"/> - <colspec colname="bit" /> - <colspec colnum="4" colname="b31" align="center" /> - <colspec colnum="5" colname="b20" align="center" /> - <colspec colnum="6" colname="b29" align="center" /> - <colspec colnum="7" colname="b28" align="center" /> - <colspec colnum="8" colname="b27" align="center" /> - <colspec colnum="9" colname="b26" align="center" /> - <colspec colnum="10" colname="b25" align="center" /> - <colspec colnum="11" colname="b24" align="center" /> - <colspec colnum="12" colname="b23" align="center" /> - <colspec colnum="13" colname="b22" align="center" /> - <colspec colnum="14" colname="b21" align="center" /> - <colspec colnum="15" colname="b20" align="center" /> - <colspec colnum="16" colname="b19" align="center" /> - <colspec colnum="17" colname="b18" align="center" /> - <colspec colnum="18" colname="b17" align="center" /> - <colspec colnum="19" colname="b16" align="center" /> - <colspec colnum="20" colname="b15" align="center" /> - <colspec colnum="21" colname="b14" align="center" /> - <colspec colnum="22" colname="b13" align="center" /> - <colspec colnum="23" colname="b12" align="center" /> - <colspec colnum="24" colname="b11" align="center" /> - <colspec colnum="25" colname="b10" align="center" /> - <colspec colnum="26" colname="b09" align="center" /> - <colspec colnum="27" colname="b08" align="center" /> - <colspec colnum="28" colname="b07" align="center" /> - <colspec colnum="29" colname="b06" align="center" /> - <colspec colnum="30" colname="b05" align="center" /> - <colspec colnum="31" colname="b04" align="center" /> - <colspec colnum="32" colname="b03" align="center" /> - <colspec colnum="33" colname="b02" align="center" /> - <colspec colnum="34" colname="b01" align="center" /> - <colspec colnum="35" colname="b00" align="center" /> - <spanspec namest="b31" nameend="b00" spanname="b0" /> - <thead> - <row> - <entry>Identifier</entry> - <entry>Code</entry> - <entry></entry> - <entry spanname="b0">Data organization</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>Bit</entry> - <entry>31</entry> - <entry>30</entry> - <entry>29</entry> - <entry>28</entry> - <entry>27</entry> - <entry>26</entry> - <entry>25</entry> - <entry>24</entry> - <entry>23</entry> - <entry>22</entry> - <entry>21</entry> - <entry>20</entry> - <entry>19</entry> - <entry>18</entry> - <entry>17</entry> - <entry>16</entry> - <entry>15</entry> - <entry>14</entry> - <entry>13</entry> - <entry>12</entry> - <entry>11</entry> - <entry>10</entry> - <entry>9</entry> - <entry>8</entry> - <entry>7</entry> - <entry>6</entry> - <entry>5</entry> - <entry>4</entry> - <entry>3</entry> - <entry>2</entry> - <entry>1</entry> - <entry>0</entry> - </row> - </thead> - <tbody valign="top"> - <row id="MEDIA-BUS-FMT-RGB444-1X12"> - <entry>MEDIA_BUS_FMT_RGB444_1X12</entry> - <entry>0x1016</entry> - <entry></entry> - &dash-ent-20; - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-RGB444-2X8-PADHI-BE"> - <entry>MEDIA_BUS_FMT_RGB444_2X8_PADHI_BE</entry> - <entry>0x1001</entry> - <entry></entry> - &dash-ent-24; - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-RGB444-2X8-PADHI-LE"> - <entry>MEDIA_BUS_FMT_RGB444_2X8_PADHI_LE</entry> - <entry>0x1002</entry> - <entry></entry> - &dash-ent-24; - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-RGB555-2X8-PADHI-BE"> - <entry>MEDIA_BUS_FMT_RGB555_2X8_PADHI_BE</entry> - <entry>0x1003</entry> - <entry></entry> - &dash-ent-24; - <entry>0</entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-RGB555-2X8-PADHI-LE"> - <entry>MEDIA_BUS_FMT_RGB555_2X8_PADHI_LE</entry> - <entry>0x1004</entry> - <entry></entry> - &dash-ent-24; - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>0</entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-RGB565-1X16"> - <entry>MEDIA_BUS_FMT_RGB565_1X16</entry> - <entry>0x1017</entry> - <entry></entry> - &dash-ent-16; - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-BGR565-2X8-BE"> - <entry>MEDIA_BUS_FMT_BGR565_2X8_BE</entry> - <entry>0x1005</entry> - <entry></entry> - &dash-ent-24; - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-BGR565-2X8-LE"> - <entry>MEDIA_BUS_FMT_BGR565_2X8_LE</entry> - <entry>0x1006</entry> - <entry></entry> - &dash-ent-24; - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-RGB565-2X8-BE"> - <entry>MEDIA_BUS_FMT_RGB565_2X8_BE</entry> - <entry>0x1007</entry> - <entry></entry> - &dash-ent-24; - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-RGB565-2X8-LE"> - <entry>MEDIA_BUS_FMT_RGB565_2X8_LE</entry> - <entry>0x1008</entry> - <entry></entry> - &dash-ent-24; - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-RGB666-1X18"> - <entry>MEDIA_BUS_FMT_RGB666_1X18</entry> - <entry>0x1009</entry> - <entry></entry> - &dash-ent-14; - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-RBG888-1X24"> - <entry>MEDIA_BUS_FMT_RBG888_1X24</entry> - <entry>0x100e</entry> - <entry></entry> - &dash-ent-8; - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-RGB666-1X24_CPADHI"> - <entry>MEDIA_BUS_FMT_RGB666_1X24_CPADHI</entry> - <entry>0x1015</entry> - <entry></entry> - &dash-ent-8; - <entry>0</entry> - <entry>0</entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>0</entry> - <entry>0</entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>0</entry> - <entry>0</entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-BGR888-1X24"> - <entry>MEDIA_BUS_FMT_BGR888_1X24</entry> - <entry>0x1013</entry> - <entry></entry> - &dash-ent-8; - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-GBR888-1X24"> - <entry>MEDIA_BUS_FMT_GBR888_1X24</entry> - <entry>0x1014</entry> - <entry></entry> - &dash-ent-8; - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-RGB888-1X24"> - <entry>MEDIA_BUS_FMT_RGB888_1X24</entry> - <entry>0x100a</entry> - <entry></entry> - &dash-ent-8; - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-RGB888-2X12-BE"> - <entry>MEDIA_BUS_FMT_RGB888_2X12_BE</entry> - <entry>0x100b</entry> - <entry></entry> - &dash-ent-20; - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-20; - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-RGB888-2X12-LE"> - <entry>MEDIA_BUS_FMT_RGB888_2X12_LE</entry> - <entry>0x100c</entry> - <entry></entry> - &dash-ent-20; - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-20; - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-ARGB888-1X32"> - <entry>MEDIA_BUS_FMT_ARGB888_1X32</entry> - <entry>0x100d</entry> - <entry></entry> - <entry>a<subscript>7</subscript></entry> - <entry>a<subscript>6</subscript></entry> - <entry>a<subscript>5</subscript></entry> - <entry>a<subscript>4</subscript></entry> - <entry>a<subscript>3</subscript></entry> - <entry>a<subscript>2</subscript></entry> - <entry>a<subscript>1</subscript></entry> - <entry>a<subscript>0</subscript></entry> - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-RGB888-1X32-PADHI"> - <entry>MEDIA_BUS_FMT_RGB888_1X32_PADHI</entry> - <entry>0x100f</entry> - <entry></entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - </tbody> - </tgroup> - </table> - - <para>On LVDS buses, usually each sample is transferred serialized in - seven time slots per pixel clock, on three (18-bit) or four (24-bit) - differential data pairs at the same time. The remaining bits are used for - control signals as defined by SPWG/PSWG/VESA or JEIDA standards. - The 24-bit RGB format serialized in seven time slots on four lanes using - JEIDA defined bit mapping will be named - <constant>MEDIA_BUS_FMT_RGB888_1X7X4_JEIDA</constant>, for example. - </para> - - <table pgwide="0" frame="none" id="v4l2-mbus-pixelcode-rgb-lvds"> - <title>LVDS RGB formats</title> - <tgroup cols="8"> - <colspec colname="id" align="left" /> - <colspec colname="code" align="center" /> - <colspec colname="slot" align="center" /> - <colspec colname="lane" /> - <colspec colnum="5" colname="l03" align="center" /> - <colspec colnum="6" colname="l02" align="center" /> - <colspec colnum="7" colname="l01" align="center" /> - <colspec colnum="8" colname="l00" align="center" /> - <spanspec namest="l03" nameend="l00" spanname="l0" /> - <thead> - <row> - <entry>Identifier</entry> - <entry>Code</entry> - <entry></entry> - <entry></entry> - <entry spanname="l0">Data organization</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>Timeslot</entry> - <entry>Lane</entry> - <entry>3</entry> - <entry>2</entry> - <entry>1</entry> - <entry>0</entry> - </row> - </thead> - <tbody valign="top"> - <row id="MEDIA-BUS-FMT-RGB666-1X7X3-SPWG"> - <entry>MEDIA_BUS_FMT_RGB666_1X7X3_SPWG</entry> - <entry>0x1010</entry> - <entry>0</entry> - <entry></entry> - <entry>-</entry> - <entry>d</entry> - <entry>b<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>1</entry> - <entry></entry> - <entry>-</entry> - <entry>d</entry> - <entry>b<subscript>0</subscript></entry> - <entry>r<subscript>5</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>2</entry> - <entry></entry> - <entry>-</entry> - <entry>d</entry> - <entry>g<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>3</entry> - <entry></entry> - <entry>-</entry> - <entry>b<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>4</entry> - <entry></entry> - <entry>-</entry> - <entry>b<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>5</entry> - <entry></entry> - <entry>-</entry> - <entry>b<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>6</entry> - <entry></entry> - <entry>-</entry> - <entry>b<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-RGB888-1X7X4-SPWG"> - <entry>MEDIA_BUS_FMT_RGB888_1X7X4_SPWG</entry> - <entry>0x1011</entry> - <entry>0</entry> - <entry></entry> - <entry>d</entry> - <entry>d</entry> - <entry>b<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>1</entry> - <entry></entry> - <entry>b<subscript>7</subscript></entry> - <entry>d</entry> - <entry>b<subscript>0</subscript></entry> - <entry>r<subscript>5</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>2</entry> - <entry></entry> - <entry>b<subscript>6</subscript></entry> - <entry>d</entry> - <entry>g<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>3</entry> - <entry></entry> - <entry>g<subscript>7</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>4</entry> - <entry></entry> - <entry>g<subscript>6</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>5</entry> - <entry></entry> - <entry>r<subscript>7</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>6</entry> - <entry></entry> - <entry>r<subscript>6</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-RGB888-1X7X4-JEIDA"> - <entry>MEDIA_BUS_FMT_RGB888_1X7X4_JEIDA</entry> - <entry>0x1012</entry> - <entry>0</entry> - <entry></entry> - <entry>d</entry> - <entry>d</entry> - <entry>b<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>1</entry> - <entry></entry> - <entry>b<subscript>1</subscript></entry> - <entry>d</entry> - <entry>b<subscript>2</subscript></entry> - <entry>r<subscript>7</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>2</entry> - <entry></entry> - <entry>b<subscript>0</subscript></entry> - <entry>d</entry> - <entry>g<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>3</entry> - <entry></entry> - <entry>g<subscript>1</subscript></entry> - <entry>b<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>4</entry> - <entry></entry> - <entry>g<subscript>0</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>5</entry> - <entry></entry> - <entry>r<subscript>1</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>6</entry> - <entry></entry> - <entry>r<subscript>0</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - </row> - </tbody> - </tgroup> - </table> - </section> - - <section> - <title>Bayer Formats</title> - - <para>Those formats transfer pixel data as red, green and blue components. - The format code is made of the following information. - <itemizedlist> - <listitem><para>The red, green and blue components order code, as encoded in a - pixel sample. The possible values are shown in <xref - linkend="bayer-patterns" />.</para></listitem> - <listitem><para>The number of bits per pixel component. All components are - transferred on the same number of bits. Common values are 8, 10 and 12.</para> - </listitem> - <listitem><para>The compression (optional). If the pixel components are - ALAW- or DPCM-compressed, a mention of the compression scheme and the - number of bits per compressed pixel component.</para></listitem> - <listitem><para>The number of bus samples per pixel. Pixels that are wider than - the bus width must be transferred in multiple samples. Common values are - 1 and 2.</para></listitem> - <listitem><para>The bus width.</para></listitem> - <listitem><para>For formats where the total number of bits per pixel is smaller - than the number of bus samples per pixel times the bus width, a padding - value stating if the bytes are padded in their most high order bits - (PADHI) or low order bits (PADLO).</para></listitem> - <listitem><para>For formats where the number of bus samples per pixel is larger - than 1, an endianness value stating if the pixel is transferred MSB first - (BE) or LSB first (LE).</para></listitem> - </itemizedlist> - </para> - - <para>For instance, a format with uncompressed 10-bit Bayer components - arranged in a red, green, green, blue pattern transferred as 2 8-bit - samples per pixel with the least significant bits transferred first will - be named <constant>MEDIA_BUS_FMT_SRGGB10_2X8_PADHI_LE</constant>. - </para> - - <figure id="bayer-patterns"> - <title>Bayer Patterns</title> - <mediaobject> - <imageobject> - <imagedata fileref="bayer.png" format="PNG" /> - </imageobject> - <textobject> - <phrase>Bayer filter color patterns</phrase> - </textobject> - </mediaobject> - </figure> - - <para>The following table lists existing packed Bayer formats. The data - organization is given as an example for the first pixel only.</para> - - <table pgwide="0" frame="none" id="v4l2-mbus-pixelcode-bayer"> - <title>Bayer Formats</title> - <tgroup cols="15"> - <colspec colname="id" align="left" /> - <colspec colname="code" align="center"/> - <colspec colname="bit" /> - <colspec colnum="4" colname="b11" align="center" /> - <colspec colnum="5" colname="b10" align="center" /> - <colspec colnum="6" colname="b09" align="center" /> - <colspec colnum="7" colname="b08" align="center" /> - <colspec colnum="8" colname="b07" align="center" /> - <colspec colnum="9" colname="b06" align="center" /> - <colspec colnum="10" colname="b05" align="center" /> - <colspec colnum="11" colname="b04" align="center" /> - <colspec colnum="12" colname="b03" align="center" /> - <colspec colnum="13" colname="b02" align="center" /> - <colspec colnum="14" colname="b01" align="center" /> - <colspec colnum="15" colname="b00" align="center" /> - <spanspec namest="b11" nameend="b00" spanname="b0" /> - <thead> - <row> - <entry>Identifier</entry> - <entry>Code</entry> - <entry></entry> - <entry spanname="b0">Data organization</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>Bit</entry> - <entry>11</entry> - <entry>10</entry> - <entry>9</entry> - <entry>8</entry> - <entry>7</entry> - <entry>6</entry> - <entry>5</entry> - <entry>4</entry> - <entry>3</entry> - <entry>2</entry> - <entry>1</entry> - <entry>0</entry> - </row> - </thead> - <tbody valign="top"> - <row id="MEDIA-BUS-FMT-SBGGR8-1X8"> - <entry>MEDIA_BUS_FMT_SBGGR8_1X8</entry> - <entry>0x3001</entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-SGBRG8-1X8"> - <entry>MEDIA_BUS_FMT_SGBRG8_1X8</entry> - <entry>0x3013</entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-SGRBG8-1X8"> - <entry>MEDIA_BUS_FMT_SGRBG8_1X8</entry> - <entry>0x3002</entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-SRGGB8-1X8"> - <entry>MEDIA_BUS_FMT_SRGGB8_1X8</entry> - <entry>0x3014</entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-SBGGR10-ALAW8-1X8"> - <entry>MEDIA_BUS_FMT_SBGGR10_ALAW8_1X8</entry> - <entry>0x3015</entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-SGBRG10-ALAW8-1X8"> - <entry>MEDIA_BUS_FMT_SGBRG10_ALAW8_1X8</entry> - <entry>0x3016</entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-SGRBG10-ALAW8-1X8"> - <entry>MEDIA_BUS_FMT_SGRBG10_ALAW8_1X8</entry> - <entry>0x3017</entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-SRGGB10-ALAW8-1X8"> - <entry>MEDIA_BUS_FMT_SRGGB10_ALAW8_1X8</entry> - <entry>0x3018</entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-SBGGR10-DPCM8-1X8"> - <entry>MEDIA_BUS_FMT_SBGGR10_DPCM8_1X8</entry> - <entry>0x300b</entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-SGBRG10-DPCM8-1X8"> - <entry>MEDIA_BUS_FMT_SGBRG10_DPCM8_1X8</entry> - <entry>0x300c</entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-SGRBG10-DPCM8-1X8"> - <entry>MEDIA_BUS_FMT_SGRBG10_DPCM8_1X8</entry> - <entry>0x3009</entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-SRGGB10-DPCM8-1X8"> - <entry>MEDIA_BUS_FMT_SRGGB10_DPCM8_1X8</entry> - <entry>0x300d</entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-SBGGR10-2X8-PADHI-BE"> - <entry>MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_BE</entry> - <entry>0x3003</entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>b<subscript>9</subscript></entry> - <entry>b<subscript>8</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-SBGGR10-2X8-PADHI-LE"> - <entry>MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_LE</entry> - <entry>0x3004</entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>b<subscript>9</subscript></entry> - <entry>b<subscript>8</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-SBGGR10-2X8-PADLO-BE"> - <entry>MEDIA_BUS_FMT_SBGGR10_2X8_PADLO_BE</entry> - <entry>0x3005</entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>b<subscript>9</subscript></entry> - <entry>b<subscript>8</subscript></entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - </row> - <row id="MEDIA-BUS-FMT-SBGGR10-2X8-PADLO-LE"> - <entry>MEDIA_BUS_FMT_SBGGR10_2X8_PADLO_LE</entry> - <entry>0x3006</entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>b<subscript>9</subscript></entry> - <entry>b<subscript>8</subscript></entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-SBGGR10-1X10"> - <entry>MEDIA_BUS_FMT_SBGGR10_1X10</entry> - <entry>0x3007</entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>b<subscript>9</subscript></entry> - <entry>b<subscript>8</subscript></entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-SGBRG10-1X10"> - <entry>MEDIA_BUS_FMT_SGBRG10_1X10</entry> - <entry>0x300e</entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>g<subscript>9</subscript></entry> - <entry>g<subscript>8</subscript></entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-SGRBG10-1X10"> - <entry>MEDIA_BUS_FMT_SGRBG10_1X10</entry> - <entry>0x300a</entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>g<subscript>9</subscript></entry> - <entry>g<subscript>8</subscript></entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-SRGGB10-1X10"> - <entry>MEDIA_BUS_FMT_SRGGB10_1X10</entry> - <entry>0x300f</entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>r<subscript>9</subscript></entry> - <entry>r<subscript>8</subscript></entry> - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-SBGGR12-1X12"> - <entry>MEDIA_BUS_FMT_SBGGR12_1X12</entry> - <entry>0x3008</entry> - <entry></entry> - <entry>b<subscript>11</subscript></entry> - <entry>b<subscript>10</subscript></entry> - <entry>b<subscript>9</subscript></entry> - <entry>b<subscript>8</subscript></entry> - <entry>b<subscript>7</subscript></entry> - <entry>b<subscript>6</subscript></entry> - <entry>b<subscript>5</subscript></entry> - <entry>b<subscript>4</subscript></entry> - <entry>b<subscript>3</subscript></entry> - <entry>b<subscript>2</subscript></entry> - <entry>b<subscript>1</subscript></entry> - <entry>b<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-SGBRG12-1X12"> - <entry>MEDIA_BUS_FMT_SGBRG12_1X12</entry> - <entry>0x3010</entry> - <entry></entry> - <entry>g<subscript>11</subscript></entry> - <entry>g<subscript>10</subscript></entry> - <entry>g<subscript>9</subscript></entry> - <entry>g<subscript>8</subscript></entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-SGRBG12-1X12"> - <entry>MEDIA_BUS_FMT_SGRBG12_1X12</entry> - <entry>0x3011</entry> - <entry></entry> - <entry>g<subscript>11</subscript></entry> - <entry>g<subscript>10</subscript></entry> - <entry>g<subscript>9</subscript></entry> - <entry>g<subscript>8</subscript></entry> - <entry>g<subscript>7</subscript></entry> - <entry>g<subscript>6</subscript></entry> - <entry>g<subscript>5</subscript></entry> - <entry>g<subscript>4</subscript></entry> - <entry>g<subscript>3</subscript></entry> - <entry>g<subscript>2</subscript></entry> - <entry>g<subscript>1</subscript></entry> - <entry>g<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-SRGGB12-1X12"> - <entry>MEDIA_BUS_FMT_SRGGB12_1X12</entry> - <entry>0x3012</entry> - <entry></entry> - <entry>r<subscript>11</subscript></entry> - <entry>r<subscript>10</subscript></entry> - <entry>r<subscript>9</subscript></entry> - <entry>r<subscript>8</subscript></entry> - <entry>r<subscript>7</subscript></entry> - <entry>r<subscript>6</subscript></entry> - <entry>r<subscript>5</subscript></entry> - <entry>r<subscript>4</subscript></entry> - <entry>r<subscript>3</subscript></entry> - <entry>r<subscript>2</subscript></entry> - <entry>r<subscript>1</subscript></entry> - <entry>r<subscript>0</subscript></entry> - </row> - </tbody> - </tgroup> - </table> - </section> - - <section> - <title>Packed YUV Formats</title> - - <para>Those data formats transfer pixel data as (possibly downsampled) Y, U - and V components. Some formats include dummy bits in some of their samples - and are collectively referred to as "YDYC" (Y-Dummy-Y-Chroma) formats. - One cannot rely on the values of these dummy bits as those are undefined. - </para> - <para>The format code is made of the following information. - <itemizedlist> - <listitem><para>The Y, U and V components order code, as transferred on the - bus. Possible values are YUYV, UYVY, YVYU and VYUY for formats with no - dummy bit, and YDYUYDYV, YDYVYDYU, YUYDYVYD and YVYDYUYD for YDYC formats. - </para></listitem> - <listitem><para>The number of bits per pixel component. All components are - transferred on the same number of bits. Common values are 8, 10 and 12.</para> - </listitem> - <listitem><para>The number of bus samples per pixel. Pixels that are wider than - the bus width must be transferred in multiple samples. Common values are - 1, 1.5 (encoded as 1_5) and 2.</para></listitem> - <listitem><para>The bus width. When the bus width is larger than the number of - bits per pixel component, several components are packed in a single bus - sample. The components are ordered as specified by the order code, with - components on the left of the code transferred in the high order bits. - Common values are 8 and 16.</para> - </listitem> - </itemizedlist> - </para> - - <para>For instance, a format where pixels are encoded as 8-bit YUV values - downsampled to 4:2:2 and transferred as 2 8-bit bus samples per pixel in the - U, Y, V, Y order will be named <constant>MEDIA_BUS_FMT_UYVY8_2X8</constant>. - </para> - - <para><xref linkend="v4l2-mbus-pixelcode-yuv8"/> lists existing packed YUV - formats and describes the organization of each pixel data in each sample. - When a format pattern is split across multiple samples each of the samples - in the pattern is described.</para> - - <para>The role of each bit transferred over the bus is identified by one - of the following codes.</para> - - <itemizedlist> - <listitem><para>y<subscript>x</subscript> for luma component bit number x</para></listitem> - <listitem><para>u<subscript>x</subscript> for blue chroma component bit number x</para></listitem> - <listitem><para>v<subscript>x</subscript> for red chroma component bit number x</para></listitem> - <listitem><para>a<subscript>x</subscript> for alpha component bit number x</para></listitem> - <listitem><para>- for non-available bits (for positions higher than the bus width)</para></listitem> - <listitem><para>d for dummy bits</para></listitem> - </itemizedlist> - - <table pgwide="0" frame="none" id="v4l2-mbus-pixelcode-yuv8"> - <title>YUV Formats</title> - <tgroup cols="23"> - <colspec colname="id" align="left" /> - <colspec colname="code" align="center"/> - <colspec colname="bit" /> - <colspec colnum="4" colname="b31" align="center" /> - <colspec colnum="5" colname="b20" align="center" /> - <colspec colnum="6" colname="b29" align="center" /> - <colspec colnum="7" colname="b28" align="center" /> - <colspec colnum="8" colname="b27" align="center" /> - <colspec colnum="9" colname="b26" align="center" /> - <colspec colnum="10" colname="b25" align="center" /> - <colspec colnum="11" colname="b24" align="center" /> - <colspec colnum="12" colname="b23" align="center" /> - <colspec colnum="13" colname="b22" align="center" /> - <colspec colnum="14" colname="b21" align="center" /> - <colspec colnum="15" colname="b20" align="center" /> - <colspec colnum="16" colname="b19" align="center" /> - <colspec colnum="17" colname="b18" align="center" /> - <colspec colnum="18" colname="b17" align="center" /> - <colspec colnum="19" colname="b16" align="center" /> - <colspec colnum="20" colname="b15" align="center" /> - <colspec colnum="21" colname="b14" align="center" /> - <colspec colnum="22" colname="b13" align="center" /> - <colspec colnum="23" colname="b12" align="center" /> - <colspec colnum="24" colname="b11" align="center" /> - <colspec colnum="25" colname="b10" align="center" /> - <colspec colnum="26" colname="b09" align="center" /> - <colspec colnum="27" colname="b08" align="center" /> - <colspec colnum="28" colname="b07" align="center" /> - <colspec colnum="29" colname="b06" align="center" /> - <colspec colnum="30" colname="b05" align="center" /> - <colspec colnum="31" colname="b04" align="center" /> - <colspec colnum="32" colname="b03" align="center" /> - <colspec colnum="33" colname="b02" align="center" /> - <colspec colnum="34" colname="b01" align="center" /> - <colspec colnum="35" colname="b00" align="center" /> - <spanspec namest="b31" nameend="b00" spanname="b0" /> - <thead> - <row> - <entry>Identifier</entry> - <entry>Code</entry> - <entry></entry> - <entry spanname="b0">Data organization</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>Bit</entry> - <entry>31</entry> - <entry>30</entry> - <entry>29</entry> - <entry>28</entry> - <entry>27</entry> - <entry>26</entry> - <entry>25</entry> - <entry>24</entry> - <entry>23</entry> - <entry>22</entry> - <entry>21</entry> - <entry>10</entry> - <entry>19</entry> - <entry>18</entry> - <entry>17</entry> - <entry>16</entry> - <entry>15</entry> - <entry>14</entry> - <entry>13</entry> - <entry>12</entry> - <entry>11</entry> - <entry>10</entry> - <entry>9</entry> - <entry>8</entry> - <entry>7</entry> - <entry>6</entry> - <entry>5</entry> - <entry>4</entry> - <entry>3</entry> - <entry>2</entry> - <entry>1</entry> - <entry>0</entry> - </row> - </thead> - <tbody valign="top"> - <row id="MEDIA-BUS-FMT-Y8-1X8"> - <entry>MEDIA_BUS_FMT_Y8_1X8</entry> - <entry>0x2001</entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-UV8-1X8"> - <entry>MEDIA_BUS_FMT_UV8_1X8</entry> - <entry>0x2015</entry> - <entry></entry> - &dash-ent-24; - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-UYVY8-1_5X8"> - <entry>MEDIA_BUS_FMT_UYVY8_1_5X8</entry> - <entry>0x2002</entry> - <entry></entry> - &dash-ent-24; - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-VYUY8-1_5X8"> - <entry>MEDIA_BUS_FMT_VYUY8_1_5X8</entry> - <entry>0x2003</entry> - <entry></entry> - &dash-ent-24; - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-YUYV8-1_5X8"> - <entry>MEDIA_BUS_FMT_YUYV8_1_5X8</entry> - <entry>0x2004</entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-YVYU8-1_5X8"> - <entry>MEDIA_BUS_FMT_YVYU8_1_5X8</entry> - <entry>0x2005</entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-UYVY8-2X8"> - <entry>MEDIA_BUS_FMT_UYVY8_2X8</entry> - <entry>0x2006</entry> - <entry></entry> - &dash-ent-24; - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-VYUY8-2X8"> - <entry>MEDIA_BUS_FMT_VYUY8_2X8</entry> - <entry>0x2007</entry> - <entry></entry> - &dash-ent-24; - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-YUYV8-2X8"> - <entry>MEDIA_BUS_FMT_YUYV8_2X8</entry> - <entry>0x2008</entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-YVYU8-2X8"> - <entry>MEDIA_BUS_FMT_YVYU8_2X8</entry> - <entry>0x2009</entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-24; - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-Y10-1X10"> - <entry>MEDIA_BUS_FMT_Y10_1X10</entry> - <entry>0x200a</entry> - <entry></entry> - &dash-ent-22; - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-UYVY10-2X10"> - <entry>MEDIA_BUS_FMT_UYVY10_2X10</entry> - <entry>0x2018</entry> - <entry></entry> - &dash-ent-22; - <entry>u<subscript>9</subscript></entry> - <entry>u<subscript>8</subscript></entry> - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-22; - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-22; - <entry>v<subscript>9</subscript></entry> - <entry>v<subscript>8</subscript></entry> - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-22; - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-VYUY10-2X10"> - <entry>MEDIA_BUS_FMT_VYUY10_2X10</entry> - <entry>0x2019</entry> - <entry></entry> - &dash-ent-22; - <entry>v<subscript>9</subscript></entry> - <entry>v<subscript>8</subscript></entry> - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-22; - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-22; - <entry>u<subscript>9</subscript></entry> - <entry>u<subscript>8</subscript></entry> - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-22; - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-YUYV10-2X10"> - <entry>MEDIA_BUS_FMT_YUYV10_2X10</entry> - <entry>0x200b</entry> - <entry></entry> - &dash-ent-22; - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-22; - <entry>u<subscript>9</subscript></entry> - <entry>u<subscript>8</subscript></entry> - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-22; - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-22; - <entry>v<subscript>9</subscript></entry> - <entry>v<subscript>8</subscript></entry> - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-YVYU10-2X10"> - <entry>MEDIA_BUS_FMT_YVYU10_2X10</entry> - <entry>0x200c</entry> - <entry></entry> - &dash-ent-22; - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-22; - <entry>v<subscript>9</subscript></entry> - <entry>v<subscript>8</subscript></entry> - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-22; - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-22; - <entry>u<subscript>9</subscript></entry> - <entry>u<subscript>8</subscript></entry> - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-Y12-1X12"> - <entry>MEDIA_BUS_FMT_Y12_1X12</entry> - <entry>0x2013</entry> - <entry></entry> - &dash-ent-20; - <entry>y<subscript>11</subscript></entry> - <entry>y<subscript>10</subscript></entry> - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-UYVY12-2X12"> - <entry>MEDIA_BUS_FMT_UYVY12_2X12</entry> - <entry>0x201c</entry> - <entry></entry> - &dash-ent-20; - <entry>u<subscript>11</subscript></entry> - <entry>u<subscript>10</subscript></entry> - <entry>u<subscript>9</subscript></entry> - <entry>u<subscript>8</subscript></entry> - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-20; - <entry>y<subscript>11</subscript></entry> - <entry>y<subscript>10</subscript></entry> - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-20; - <entry>v<subscript>11</subscript></entry> - <entry>v<subscript>10</subscript></entry> - <entry>v<subscript>9</subscript></entry> - <entry>v<subscript>8</subscript></entry> - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-20; - <entry>y<subscript>11</subscript></entry> - <entry>y<subscript>10</subscript></entry> - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-VYUY12-2X12"> - <entry>MEDIA_BUS_FMT_VYUY12_2X12</entry> - <entry>0x201d</entry> - <entry></entry> - &dash-ent-20; - <entry>v<subscript>11</subscript></entry> - <entry>v<subscript>10</subscript></entry> - <entry>v<subscript>9</subscript></entry> - <entry>v<subscript>8</subscript></entry> - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-20; - <entry>y<subscript>11</subscript></entry> - <entry>y<subscript>10</subscript></entry> - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-20; - <entry>u<subscript>11</subscript></entry> - <entry>u<subscript>10</subscript></entry> - <entry>u<subscript>9</subscript></entry> - <entry>u<subscript>8</subscript></entry> - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-20; - <entry>y<subscript>11</subscript></entry> - <entry>y<subscript>10</subscript></entry> - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-YUYV12-2X12"> - <entry>MEDIA_BUS_FMT_YUYV12_2X12</entry> - <entry>0x201e</entry> - <entry></entry> - &dash-ent-20; - <entry>y<subscript>11</subscript></entry> - <entry>y<subscript>10</subscript></entry> - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-20; - <entry>u<subscript>11</subscript></entry> - <entry>u<subscript>10</subscript></entry> - <entry>u<subscript>9</subscript></entry> - <entry>u<subscript>8</subscript></entry> - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-20; - <entry>y<subscript>11</subscript></entry> - <entry>y<subscript>10</subscript></entry> - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-20; - <entry>v<subscript>11</subscript></entry> - <entry>v<subscript>10</subscript></entry> - <entry>v<subscript>9</subscript></entry> - <entry>v<subscript>8</subscript></entry> - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-YVYU12-2X12"> - <entry>MEDIA_BUS_FMT_YVYU12_2X12</entry> - <entry>0x201f</entry> - <entry></entry> - &dash-ent-20; - <entry>y<subscript>11</subscript></entry> - <entry>y<subscript>10</subscript></entry> - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-20; - <entry>v<subscript>11</subscript></entry> - <entry>v<subscript>10</subscript></entry> - <entry>v<subscript>9</subscript></entry> - <entry>v<subscript>8</subscript></entry> - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-20; - <entry>y<subscript>11</subscript></entry> - <entry>y<subscript>10</subscript></entry> - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-20; - <entry>u<subscript>11</subscript></entry> - <entry>u<subscript>10</subscript></entry> - <entry>u<subscript>9</subscript></entry> - <entry>u<subscript>8</subscript></entry> - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-UYVY8-1X16"> - <entry>MEDIA_BUS_FMT_UYVY8_1X16</entry> - <entry>0x200f</entry> - <entry></entry> - &dash-ent-16; - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-16; - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-VYUY8-1X16"> - <entry>MEDIA_BUS_FMT_VYUY8_1X16</entry> - <entry>0x2010</entry> - <entry></entry> - &dash-ent-16; - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-16; - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-YUYV8-1X16"> - <entry>MEDIA_BUS_FMT_YUYV8_1X16</entry> - <entry>0x2011</entry> - <entry></entry> - &dash-ent-16; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-16; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-YVYU8-1X16"> - <entry>MEDIA_BUS_FMT_YVYU8_1X16</entry> - <entry>0x2012</entry> - <entry></entry> - &dash-ent-16; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-16; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-YDYUYDYV8-1X16"> - <entry>MEDIA_BUS_FMT_YDYUYDYV8_1X16</entry> - <entry>0x2014</entry> - <entry></entry> - &dash-ent-16; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - <entry>d</entry> - <entry>d</entry> - <entry>d</entry> - <entry>d</entry> - <entry>d</entry> - <entry>d</entry> - <entry>d</entry> - <entry>d</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-16; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-16; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - <entry>d</entry> - <entry>d</entry> - <entry>d</entry> - <entry>d</entry> - <entry>d</entry> - <entry>d</entry> - <entry>d</entry> - <entry>d</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-16; - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-UYVY10-1X20"> - <entry>MEDIA_BUS_FMT_UYVY10_1X20</entry> - <entry>0x201a</entry> - <entry></entry> - &dash-ent-12; - <entry>u<subscript>9</subscript></entry> - <entry>u<subscript>8</subscript></entry> - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-12; - <entry>v<subscript>9</subscript></entry> - <entry>v<subscript>8</subscript></entry> - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-VYUY10-1X20"> - <entry>MEDIA_BUS_FMT_VYUY10_1X20</entry> - <entry>0x201b</entry> - <entry></entry> - &dash-ent-12; - <entry>v<subscript>9</subscript></entry> - <entry>v<subscript>8</subscript></entry> - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-12; - <entry>u<subscript>9</subscript></entry> - <entry>u<subscript>8</subscript></entry> - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-YUYV10-1X20"> - <entry>MEDIA_BUS_FMT_YUYV10_1X20</entry> - <entry>0x200d</entry> - <entry></entry> - &dash-ent-12; - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - <entry>u<subscript>9</subscript></entry> - <entry>u<subscript>8</subscript></entry> - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-12; - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - <entry>v<subscript>9</subscript></entry> - <entry>v<subscript>8</subscript></entry> - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-YVYU10-1X20"> - <entry>MEDIA_BUS_FMT_YVYU10_1X20</entry> - <entry>0x200e</entry> - <entry></entry> - &dash-ent-12; - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - <entry>v<subscript>9</subscript></entry> - <entry>v<subscript>8</subscript></entry> - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-12; - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - <entry>u<subscript>9</subscript></entry> - <entry>u<subscript>8</subscript></entry> - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-VUY8-1X24"> - <entry>MEDIA_BUS_FMT_VUY8_1X24</entry> - <entry>0x201a</entry> - <entry></entry> - &dash-ent-8; - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-YUV8-1X24"> - <entry>MEDIA_BUS_FMT_YUV8_1X24</entry> - <entry>0x2025</entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-UYVY12-1X24"> - <entry>MEDIA_BUS_FMT_UYVY12_1X24</entry> - <entry>0x2020</entry> - <entry></entry> - &dash-ent-8; - <entry>u<subscript>11</subscript></entry> - <entry>u<subscript>10</subscript></entry> - <entry>u<subscript>9</subscript></entry> - <entry>u<subscript>8</subscript></entry> - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - <entry>y<subscript>11</subscript></entry> - <entry>y<subscript>10</subscript></entry> - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-8; - <entry>v<subscript>11</subscript></entry> - <entry>v<subscript>10</subscript></entry> - <entry>v<subscript>9</subscript></entry> - <entry>v<subscript>8</subscript></entry> - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - <entry>y<subscript>11</subscript></entry> - <entry>y<subscript>10</subscript></entry> - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-VYUY12-1X24"> - <entry>MEDIA_BUS_FMT_VYUY12_1X24</entry> - <entry>0x2021</entry> - <entry></entry> - &dash-ent-8; - <entry>v<subscript>11</subscript></entry> - <entry>v<subscript>10</subscript></entry> - <entry>v<subscript>9</subscript></entry> - <entry>v<subscript>8</subscript></entry> - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - <entry>y<subscript>11</subscript></entry> - <entry>y<subscript>10</subscript></entry> - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-8; - <entry>u<subscript>11</subscript></entry> - <entry>u<subscript>10</subscript></entry> - <entry>u<subscript>9</subscript></entry> - <entry>u<subscript>8</subscript></entry> - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - <entry>y<subscript>11</subscript></entry> - <entry>y<subscript>10</subscript></entry> - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-YUYV12-1X24"> - <entry>MEDIA_BUS_FMT_YUYV12_1X24</entry> - <entry>0x2022</entry> - <entry></entry> - &dash-ent-8; - <entry>y<subscript>11</subscript></entry> - <entry>y<subscript>10</subscript></entry> - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - <entry>u<subscript>11</subscript></entry> - <entry>u<subscript>10</subscript></entry> - <entry>u<subscript>9</subscript></entry> - <entry>u<subscript>8</subscript></entry> - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-8; - <entry>y<subscript>11</subscript></entry> - <entry>y<subscript>10</subscript></entry> - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - <entry>v<subscript>11</subscript></entry> - <entry>v<subscript>10</subscript></entry> - <entry>v<subscript>9</subscript></entry> - <entry>v<subscript>8</subscript></entry> - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-YVYU12-1X24"> - <entry>MEDIA_BUS_FMT_YVYU12_1X24</entry> - <entry>0x2023</entry> - <entry></entry> - &dash-ent-8; - <entry>y<subscript>11</subscript></entry> - <entry>y<subscript>10</subscript></entry> - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - <entry>v<subscript>11</subscript></entry> - <entry>v<subscript>10</subscript></entry> - <entry>v<subscript>9</subscript></entry> - <entry>v<subscript>8</subscript></entry> - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - &dash-ent-8; - <entry>y<subscript>11</subscript></entry> - <entry>y<subscript>10</subscript></entry> - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - <entry>u<subscript>11</subscript></entry> - <entry>u<subscript>10</subscript></entry> - <entry>u<subscript>9</subscript></entry> - <entry>u<subscript>8</subscript></entry> - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-YUV10-1X30"> - <entry>MEDIA_BUS_FMT_YUV10_1X30</entry> - <entry>0x2016</entry> - <entry></entry> - <entry>-</entry> - <entry>-</entry> - <entry>y<subscript>9</subscript></entry> - <entry>y<subscript>8</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - <entry>u<subscript>9</subscript></entry> - <entry>u<subscript>8</subscript></entry> - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - <entry>v<subscript>9</subscript></entry> - <entry>v<subscript>8</subscript></entry> - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - <row id="MEDIA-BUS-FMT-AYUV8-1X32"> - <entry>MEDIA_BUS_FMT_AYUV8_1X32</entry> - <entry>0x2017</entry> - <entry></entry> - <entry>a<subscript>7</subscript></entry> - <entry>a<subscript>6</subscript></entry> - <entry>a<subscript>5</subscript></entry> - <entry>a<subscript>4</subscript></entry> - <entry>a<subscript>3</subscript></entry> - <entry>a<subscript>2</subscript></entry> - <entry>a<subscript>1</subscript></entry> - <entry>a<subscript>0</subscript></entry> - <entry>y<subscript>7</subscript></entry> - <entry>y<subscript>6</subscript></entry> - <entry>y<subscript>5</subscript></entry> - <entry>y<subscript>4</subscript></entry> - <entry>y<subscript>3</subscript></entry> - <entry>y<subscript>2</subscript></entry> - <entry>y<subscript>1</subscript></entry> - <entry>y<subscript>0</subscript></entry> - <entry>u<subscript>7</subscript></entry> - <entry>u<subscript>6</subscript></entry> - <entry>u<subscript>5</subscript></entry> - <entry>u<subscript>4</subscript></entry> - <entry>u<subscript>3</subscript></entry> - <entry>u<subscript>2</subscript></entry> - <entry>u<subscript>1</subscript></entry> - <entry>u<subscript>0</subscript></entry> - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - </tbody> - </tgroup> - </table> - </section> - - <section> - <title>HSV/HSL Formats</title> - - <para>Those formats transfer pixel data as RGB values in a cylindrical-coordinate - system using Hue-Saturation-Value or Hue-Saturation-Lightness components. The - format code is made of the following information. - <itemizedlist> - <listitem><para>The hue, saturation, value or lightness and optional alpha - components order code, as encoded in a pixel sample. The only currently - supported value is AHSV. - </para></listitem> - <listitem><para>The number of bits per component, for each component. The values - can be different for all components. The only currently supported value is 8888. - </para></listitem> - <listitem><para>The number of bus samples per pixel. Pixels that are wider than - the bus width must be transferred in multiple samples. The only currently - supported value is 1.</para></listitem> - <listitem><para>The bus width.</para></listitem> - <listitem><para>For formats where the total number of bits per pixel is smaller - than the number of bus samples per pixel times the bus width, a padding - value stating if the bytes are padded in their most high order bits - (PADHI) or low order bits (PADLO).</para></listitem> - <listitem><para>For formats where the number of bus samples per pixel is larger - than 1, an endianness value stating if the pixel is transferred MSB first - (BE) or LSB first (LE).</para></listitem> - </itemizedlist> - </para> - - <para>The following table lists existing HSV/HSL formats.</para> - - <table pgwide="0" frame="none" id="v4l2-mbus-pixelcode-hsv"> - <title>HSV/HSL formats</title> - <tgroup cols="27"> - <colspec colname="id" align="left" /> - <colspec colname="code" align="center"/> - <colspec colname="bit" /> - <colspec colnum="4" colname="b31" align="center" /> - <colspec colnum="5" colname="b20" align="center" /> - <colspec colnum="6" colname="b29" align="center" /> - <colspec colnum="7" colname="b28" align="center" /> - <colspec colnum="8" colname="b27" align="center" /> - <colspec colnum="9" colname="b26" align="center" /> - <colspec colnum="10" colname="b25" align="center" /> - <colspec colnum="11" colname="b24" align="center" /> - <colspec colnum="12" colname="b23" align="center" /> - <colspec colnum="13" colname="b22" align="center" /> - <colspec colnum="14" colname="b21" align="center" /> - <colspec colnum="15" colname="b20" align="center" /> - <colspec colnum="16" colname="b19" align="center" /> - <colspec colnum="17" colname="b18" align="center" /> - <colspec colnum="18" colname="b17" align="center" /> - <colspec colnum="19" colname="b16" align="center" /> - <colspec colnum="20" colname="b15" align="center" /> - <colspec colnum="21" colname="b14" align="center" /> - <colspec colnum="22" colname="b13" align="center" /> - <colspec colnum="23" colname="b12" align="center" /> - <colspec colnum="24" colname="b11" align="center" /> - <colspec colnum="25" colname="b10" align="center" /> - <colspec colnum="26" colname="b09" align="center" /> - <colspec colnum="27" colname="b08" align="center" /> - <colspec colnum="28" colname="b07" align="center" /> - <colspec colnum="29" colname="b06" align="center" /> - <colspec colnum="30" colname="b05" align="center" /> - <colspec colnum="31" colname="b04" align="center" /> - <colspec colnum="32" colname="b03" align="center" /> - <colspec colnum="33" colname="b02" align="center" /> - <colspec colnum="34" colname="b01" align="center" /> - <colspec colnum="35" colname="b00" align="center" /> - <spanspec namest="b31" nameend="b00" spanname="b0" /> - <thead> - <row> - <entry>Identifier</entry> - <entry>Code</entry> - <entry></entry> - <entry spanname="b0">Data organization</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>Bit</entry> - <entry>31</entry> - <entry>30</entry> - <entry>29</entry> - <entry>28</entry> - <entry>27</entry> - <entry>26</entry> - <entry>25</entry> - <entry>24</entry> - <entry>23</entry> - <entry>22</entry> - <entry>21</entry> - <entry>20</entry> - <entry>19</entry> - <entry>18</entry> - <entry>17</entry> - <entry>16</entry> - <entry>15</entry> - <entry>14</entry> - <entry>13</entry> - <entry>12</entry> - <entry>11</entry> - <entry>10</entry> - <entry>9</entry> - <entry>8</entry> - <entry>7</entry> - <entry>6</entry> - <entry>5</entry> - <entry>4</entry> - <entry>3</entry> - <entry>2</entry> - <entry>1</entry> - <entry>0</entry> - </row> - </thead> - <tbody valign="top"> - <row id="MEDIA-BUS-FMT-AHSV8888-1X32"> - <entry>MEDIA_BUS_FMT_AHSV8888_1X32</entry> - <entry>0x6001</entry> - <entry></entry> - <entry>a<subscript>7</subscript></entry> - <entry>a<subscript>6</subscript></entry> - <entry>a<subscript>5</subscript></entry> - <entry>a<subscript>4</subscript></entry> - <entry>a<subscript>3</subscript></entry> - <entry>a<subscript>2</subscript></entry> - <entry>a<subscript>1</subscript></entry> - <entry>a<subscript>0</subscript></entry> - <entry>h<subscript>7</subscript></entry> - <entry>h<subscript>6</subscript></entry> - <entry>h<subscript>5</subscript></entry> - <entry>h<subscript>4</subscript></entry> - <entry>h<subscript>3</subscript></entry> - <entry>h<subscript>2</subscript></entry> - <entry>h<subscript>1</subscript></entry> - <entry>h<subscript>0</subscript></entry> - <entry>s<subscript>7</subscript></entry> - <entry>s<subscript>6</subscript></entry> - <entry>s<subscript>5</subscript></entry> - <entry>s<subscript>4</subscript></entry> - <entry>s<subscript>3</subscript></entry> - <entry>s<subscript>2</subscript></entry> - <entry>s<subscript>1</subscript></entry> - <entry>s<subscript>0</subscript></entry> - <entry>v<subscript>7</subscript></entry> - <entry>v<subscript>6</subscript></entry> - <entry>v<subscript>5</subscript></entry> - <entry>v<subscript>4</subscript></entry> - <entry>v<subscript>3</subscript></entry> - <entry>v<subscript>2</subscript></entry> - <entry>v<subscript>1</subscript></entry> - <entry>v<subscript>0</subscript></entry> - </row> - </tbody> - </tgroup> - </table> - </section> - - <section> - <title>JPEG Compressed Formats</title> - - <para>Those data formats consist of an ordered sequence of 8-bit bytes - obtained from JPEG compression process. Additionally to the - <constant>_JPEG</constant> postfix the format code is made of - the following information. - <itemizedlist> - <listitem><para>The number of bus samples per entropy encoded byte.</para></listitem> - <listitem><para>The bus width.</para></listitem> - </itemizedlist> - </para> - - <para>For instance, for a JPEG baseline process and an 8-bit bus width - the format will be named <constant>MEDIA_BUS_FMT_JPEG_1X8</constant>. - </para> - - <para>The following table lists existing JPEG compressed formats.</para> - - <table pgwide="0" frame="none" id="v4l2-mbus-pixelcode-jpeg"> - <title>JPEG Formats</title> - <tgroup cols="3"> - <colspec colname="id" align="left" /> - <colspec colname="code" align="left"/> - <colspec colname="remarks" align="left"/> - <thead> - <row> - <entry>Identifier</entry> - <entry>Code</entry> - <entry>Remarks</entry> - </row> - </thead> - <tbody valign="top"> - <row id="MEDIA-BUS-FMT-JPEG-1X8"> - <entry>MEDIA_BUS_FMT_JPEG_1X8</entry> - <entry>0x4001</entry> - <entry>Besides of its usage for the parallel bus this format is - recommended for transmission of JPEG data over MIPI CSI bus - using the User Defined 8-bit Data types. - </entry> - </row> - </tbody> - </tgroup> - </table> - </section> - - <section id="v4l2-mbus-vendor-spec-fmts"> - <title>Vendor and Device Specific Formats</title> - - <note> - <title>Experimental</title> - <para>This is an <link linkend="experimental">experimental</link> -interface and may change in the future.</para> - </note> - - <para>This section lists complex data formats that are either vendor or - device specific. - </para> - - <para>The following table lists the existing vendor and device specific - formats.</para> - - <table pgwide="0" frame="none" id="v4l2-mbus-pixelcode-vendor-specific"> - <title>Vendor and device specific formats</title> - <tgroup cols="3"> - <colspec colname="id" align="left" /> - <colspec colname="code" align="left"/> - <colspec colname="remarks" align="left"/> - <thead> - <row> - <entry>Identifier</entry> - <entry>Code</entry> - <entry>Comments</entry> - </row> - </thead> - <tbody valign="top"> - <row id="MEDIA-BUS-FMT-S5C-UYVY-JPEG-1X8"> - <entry>MEDIA_BUS_FMT_S5C_UYVY_JPEG_1X8</entry> - <entry>0x5001</entry> - <entry> - Interleaved raw UYVY and JPEG image format with embedded - meta-data used by Samsung S3C73MX camera sensors. - </entry> - </row> - </tbody> - </tgroup> - </table> - </section> - - </section> -</section> diff --git a/Documentation/DocBook/media/v4l/subdev-image-processing-crop.dia b/Documentation/DocBook/media/v4l/subdev-image-processing-crop.dia deleted file mode 100644 index e32ba5362e1d..000000000000 --- a/Documentation/DocBook/media/v4l/subdev-image-processing-crop.dia +++ /dev/null @@ -1,614 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<dia:diagram xmlns:dia="http://www.lysator.liu.se/~alla/dia/"> - <dia:diagramdata> - <dia:attribute name="background"> - <dia:color val="#ffffff"/> - </dia:attribute> - <dia:attribute name="pagebreak"> - <dia:color val="#000099"/> - </dia:attribute> - <dia:attribute name="paper"> - <dia:composite type="paper"> - <dia:attribute name="name"> - <dia:string>#A4#</dia:string> - </dia:attribute> - <dia:attribute name="tmargin"> - <dia:real val="2.8222000598907471"/> - </dia:attribute> - <dia:attribute name="bmargin"> - <dia:real val="2.8222000598907471"/> - </dia:attribute> - <dia:attribute name="lmargin"> - <dia:real val="2.8222000598907471"/> - </dia:attribute> - <dia:attribute name="rmargin"> - <dia:real val="2.8222000598907471"/> - </dia:attribute> - <dia:attribute name="is_portrait"> - <dia:boolean val="false"/> - </dia:attribute> - <dia:attribute name="scaling"> - <dia:real val="0.49000000953674316"/> - </dia:attribute> - <dia:attribute name="fitto"> - <dia:boolean val="false"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="grid"> - <dia:composite type="grid"> - <dia:attribute name="width_x"> - <dia:real val="1"/> - </dia:attribute> - <dia:attribute name="width_y"> - <dia:real val="1"/> - </dia:attribute> - <dia:attribute name="visible_x"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="visible_y"> - <dia:int val="1"/> - </dia:attribute> - <dia:composite type="color"/> - </dia:composite> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#d8e5e5"/> - </dia:attribute> - <dia:attribute name="guides"> - <dia:composite type="guides"> - <dia:attribute name="hguides"/> - <dia:attribute name="vguides"/> - </dia:composite> - </dia:attribute> - </dia:diagramdata> - <dia:layer name="Background" visible="true" active="true"> - <dia:object type="Standard - Box" version="0" id="O0"> - <dia:attribute name="obj_pos"> - <dia:point val="-0.4,6.5"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="-0.45,6.45;23.1387,16.2"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="-0.4,6.5"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="23.48871579904775"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="9.6500000000000004"/> - </dia:attribute> - <dia:attribute name="border_width"> - <dia:real val="0.10000000149011612"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="false"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Box" version="0" id="O1"> - <dia:attribute name="obj_pos"> - <dia:point val="0.225,9.45"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="0.175,9.4;8.225,14.7"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="0.225,9.45"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="7.9499999999999975"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="5.1999999999999975"/> - </dia:attribute> - <dia:attribute name="border_width"> - <dia:real val="0.10000000149011612"/> - </dia:attribute> - <dia:attribute name="border_color"> - <dia:color val="#a52a2a"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Box" version="0" id="O2"> - <dia:attribute name="obj_pos"> - <dia:point val="3.175,10.55"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="3.125,10.5;7.925,14.45"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="3.175,10.55"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="4.6999999999999975"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="3.8499999999999979"/> - </dia:attribute> - <dia:attribute name="border_width"> - <dia:real val="0.10000000149011612"/> - </dia:attribute> - <dia:attribute name="border_color"> - <dia:color val="#0000ff"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O3"> - <dia:attribute name="obj_pos"> - <dia:point val="3.725,11.3875"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="3.725,10.7925;6.6025,13.14"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>#sink -crop -selection#</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="3.725,11.3875"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#0000ff"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O4"> - <dia:attribute name="obj_pos"> - <dia:point val="1.475,7.9"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="1.475,7.305;1.475,8.0525"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>##</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="1.475,7.9"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#000000"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O5"> - <dia:attribute name="obj_pos"> - <dia:point val="0.426918,7.89569"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="0.426918,7.30069;3.90942,8.84819"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>#sink media -bus format#</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="0.426918,7.89569"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#a52a2a"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O6"> - <dia:attribute name="obj_pos"> - <dia:point val="17.4887,7.75"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="17.4887,7.155;21.8112,8.7025"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>#source media -bus format#</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="17.4887,7.75"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#8b6914"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Box" version="0" id="O7"> - <dia:attribute name="obj_pos"> - <dia:point val="17.5244,9.5417"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="17.4744,9.4917;22.2387,13.35"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="17.5244,9.5417"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="4.6643157990477508"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="3.758300000000002"/> - </dia:attribute> - <dia:attribute name="border_width"> - <dia:real val="0.10000000149011612"/> - </dia:attribute> - <dia:attribute name="border_color"> - <dia:color val="#8b6914"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O8"> - <dia:attribute name="obj_pos"> - <dia:point val="17.5244,13.3"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="3.12132,13.2463;17.5781,14.4537"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="17.5244,13.3"/> - <dia:point val="3.175,14.4"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O7" connection="5"/> - <dia:connection handle="1" to="O2" connection="5"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O9"> - <dia:attribute name="obj_pos"> - <dia:point val="17.5244,9.5417"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="3.12162,9.48832;17.5778,10.6034"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="17.5244,9.5417"/> - <dia:point val="3.175,10.55"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O7" connection="0"/> - <dia:connection handle="1" to="O2" connection="0"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O10"> - <dia:attribute name="obj_pos"> - <dia:point val="22.1887,13.3"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="7.82132,13.2463;22.2424,14.4537"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="22.1887,13.3"/> - <dia:point val="7.875,14.4"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O7" connection="7"/> - <dia:connection handle="1" to="O2" connection="7"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O11"> - <dia:attribute name="obj_pos"> - <dia:point val="22.1887,9.5417"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="7.82161,9.48831;22.2421,10.6034"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="22.1887,9.5417"/> - <dia:point val="7.875,10.55"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O7" connection="2"/> - <dia:connection handle="1" to="O2" connection="2"/> - </dia:connections> - </dia:object> - <dia:object type="Geometric - Perfect Circle" version="1" id="O12"> - <dia:attribute name="obj_pos"> - <dia:point val="23.23,10.5742"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="23.18,10.5242;24.13,11.4742"/> - </dia:attribute> - <dia:attribute name="meta"> - <dia:composite type="dict"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="23.23,10.5742"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="0.84999999999999787"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="0.84999999999999787"/> - </dia:attribute> - <dia:attribute name="line_width"> - <dia:real val="0.10000000000000001"/> - </dia:attribute> - <dia:attribute name="line_colour"> - <dia:color val="#000000"/> - </dia:attribute> - <dia:attribute name="fill_colour"> - <dia:color val="#ffffff"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="0"/> - <dia:real val="1"/> - </dia:attribute> - <dia:attribute name="flip_horizontal"> - <dia:boolean val="false"/> - </dia:attribute> - <dia:attribute name="flip_vertical"> - <dia:boolean val="false"/> - </dia:attribute> - <dia:attribute name="subscale"> - <dia:real val="1"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O13"> - <dia:attribute name="obj_pos"> - <dia:point val="24.08,10.9992"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="24.03,10.6388;32.4953,11.3624"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="24.08,10.9992"/> - <dia:point val="32.3835,11.0007"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="end_arrow"> - <dia:enum val="22"/> - </dia:attribute> - <dia:attribute name="end_arrow_length"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:attribute name="end_arrow_width"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O12" connection="3"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O14"> - <dia:attribute name="obj_pos"> - <dia:point val="25.3454,10.49"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="25.3454,9.895;29.9904,10.6425"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>#pad 1 (source)#</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="25.3454,10.49"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#000000"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Geometric - Perfect Circle" version="1" id="O15"> - <dia:attribute name="obj_pos"> - <dia:point val="-1.44491,11.6506"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="-1.49491,11.6006;-0.54491,12.5506"/> - </dia:attribute> - <dia:attribute name="meta"> - <dia:composite type="dict"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="-1.44491,11.6506"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="0.84999999999999787"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="0.84999999999999787"/> - </dia:attribute> - <dia:attribute name="line_width"> - <dia:real val="0.10000000000000001"/> - </dia:attribute> - <dia:attribute name="line_colour"> - <dia:color val="#000000"/> - </dia:attribute> - <dia:attribute name="fill_colour"> - <dia:color val="#ffffff"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="0"/> - <dia:real val="1"/> - </dia:attribute> - <dia:attribute name="flip_horizontal"> - <dia:boolean val="false"/> - </dia:attribute> - <dia:attribute name="flip_vertical"> - <dia:boolean val="false"/> - </dia:attribute> - <dia:attribute name="subscale"> - <dia:real val="1"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O16"> - <dia:attribute name="obj_pos"> - <dia:point val="-9.61991,12.09"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="-9.67,11.7149;-1.33311,12.4385"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="-9.61991,12.09"/> - <dia:point val="-1.44491,12.0756"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="end_arrow"> - <dia:enum val="22"/> - </dia:attribute> - <dia:attribute name="end_arrow_length"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:attribute name="end_arrow_width"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="1" to="O15" connection="2"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O17"> - <dia:attribute name="obj_pos"> - <dia:point val="-7.39291,11.49"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="-7.39291,10.895;-3.58791,11.6425"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>#pad 0 (sink)#</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="-7.39291,11.49"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#000000"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - </dia:layer> -</dia:diagram> diff --git a/Documentation/DocBook/media/v4l/subdev-image-processing-crop.svg b/Documentation/DocBook/media/v4l/subdev-image-processing-crop.svg deleted file mode 100644 index 18b0f5de9ed2..000000000000 --- a/Documentation/DocBook/media/v4l/subdev-image-processing-crop.svg +++ /dev/null @@ -1,63 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd"> -<svg width="43cm" height="10cm" viewBox="-194 128 844 196" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> - <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="-8" y="130" width="469.774" height="193"/> - <g> - <rect style="fill: #ffffff" x="4.5" y="189" width="159" height="104"/> - <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="4.5" y="189" width="159" height="104"/> - </g> - <g> - <rect style="fill: #ffffff" x="63.5" y="211" width="94" height="77"/> - <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="63.5" y="211" width="94" height="77"/> - </g> - <text style="fill: #0000ff;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="74.5" y="227.75"> - <tspan x="74.5" y="227.75">sink</tspan> - <tspan x="74.5" y="243.75">crop</tspan> - <tspan x="74.5" y="259.75">selection</tspan> - </text> - <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="29.5" y="158"> - <tspan x="29.5" y="158"></tspan> - </text> - <text style="fill: #a52a2a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="8.53836" y="157.914"> - <tspan x="8.53836" y="157.914">sink media</tspan> - <tspan x="8.53836" y="173.914">bus format</tspan> - </text> - <text style="fill: #8b6914;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="349.774" y="155"> - <tspan x="349.774" y="155">source media</tspan> - <tspan x="349.774" y="171">bus format</tspan> - </text> - <g> - <rect style="fill: #ffffff" x="350.488" y="190.834" width="93.2863" height="75.166"/> - <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="350.488" y="190.834" width="93.2863" height="75.166"/> - </g> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="350.488" y1="266" x2="63.5" y2="288"/> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="350.488" y1="190.834" x2="63.5" y2="211"/> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="443.774" y1="266" x2="157.5" y2="288"/> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="443.774" y1="190.834" x2="157.5" y2="211"/> - <g> - <ellipse style="fill: #ffffff" cx="473.1" cy="219.984" rx="8.5" ry="8.5"/> - <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="473.1" cy="219.984" rx="8.5" ry="8.5"/> - <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="473.1" cy="219.984" rx="8.5" ry="8.5"/> - </g> - <g> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="481.6" y1="219.984" x2="637.934" y2="220.012"/> - <polygon style="fill: #000000" points="645.434,220.014 635.433,225.012 637.934,220.012 635.435,215.012 "/> - <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="645.434,220.014 635.433,225.012 637.934,220.012 635.435,215.012 "/> - </g> - <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="506.908" y="209.8"> - <tspan x="506.908" y="209.8">pad 1 (source)</tspan> - </text> - <g> - <ellipse style="fill: #ffffff" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/> - <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/> - <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/> - </g> - <g> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-192.398" y1="241.8" x2="-38.6343" y2="241.529"/> - <polygon style="fill: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/> - <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/> - </g> - <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-147.858" y="229.8"> - <tspan x="-147.858" y="229.8">pad 0 (sink)</tspan> - </text> -</svg> diff --git a/Documentation/DocBook/media/v4l/subdev-image-processing-full.dia b/Documentation/DocBook/media/v4l/subdev-image-processing-full.dia deleted file mode 100644 index a0d782927840..000000000000 --- a/Documentation/DocBook/media/v4l/subdev-image-processing-full.dia +++ /dev/null @@ -1,1588 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<dia:diagram xmlns:dia="http://www.lysator.liu.se/~alla/dia/"> - <dia:diagramdata> - <dia:attribute name="background"> - <dia:color val="#ffffff"/> - </dia:attribute> - <dia:attribute name="pagebreak"> - <dia:color val="#000099"/> - </dia:attribute> - <dia:attribute name="paper"> - <dia:composite type="paper"> - <dia:attribute name="name"> - <dia:string>#A4#</dia:string> - </dia:attribute> - <dia:attribute name="tmargin"> - <dia:real val="2.8222000598907471"/> - </dia:attribute> - <dia:attribute name="bmargin"> - <dia:real val="2.8222000598907471"/> - </dia:attribute> - <dia:attribute name="lmargin"> - <dia:real val="2.8222000598907471"/> - </dia:attribute> - <dia:attribute name="rmargin"> - <dia:real val="2.8222000598907471"/> - </dia:attribute> - <dia:attribute name="is_portrait"> - <dia:boolean val="false"/> - </dia:attribute> - <dia:attribute name="scaling"> - <dia:real val="0.49000000953674316"/> - </dia:attribute> - <dia:attribute name="fitto"> - <dia:boolean val="false"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="grid"> - <dia:composite type="grid"> - <dia:attribute name="width_x"> - <dia:real val="1"/> - </dia:attribute> - <dia:attribute name="width_y"> - <dia:real val="1"/> - </dia:attribute> - <dia:attribute name="visible_x"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="visible_y"> - <dia:int val="1"/> - </dia:attribute> - <dia:composite type="color"/> - </dia:composite> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#d8e5e5"/> - </dia:attribute> - <dia:attribute name="guides"> - <dia:composite type="guides"> - <dia:attribute name="hguides"/> - <dia:attribute name="vguides"/> - </dia:composite> - </dia:attribute> - </dia:diagramdata> - <dia:layer name="Background" visible="true" active="true"> - <dia:object type="Standard - Box" version="0" id="O0"> - <dia:attribute name="obj_pos"> - <dia:point val="15.945,6.45"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="15.895,6.4;26.4,18.95"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="15.945,6.45"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="10.404999999254942"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="12.449999999999992"/> - </dia:attribute> - <dia:attribute name="border_width"> - <dia:real val="0.10000000149011612"/> - </dia:attribute> - <dia:attribute name="border_color"> - <dia:color val="#ff765a"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Box" version="0" id="O1"> - <dia:attribute name="obj_pos"> - <dia:point val="-0.1,3.65"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="-0.15,3.6;40.25,20.85"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="-0.1,3.65"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="40.300000000000004"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="17.149999999999999"/> - </dia:attribute> - <dia:attribute name="border_width"> - <dia:real val="0.10000000149011612"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="false"/> - </dia:attribute> - </dia:object> - <dia:object type="Geometric - Perfect Circle" version="1" id="O2"> - <dia:attribute name="obj_pos"> - <dia:point val="-1.05,7.9106"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="-1.1,7.8606;-0.15,8.8106"/> - </dia:attribute> - <dia:attribute name="meta"> - <dia:composite type="dict"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="-1.05,7.9106"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="0.84999999999999787"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="0.84999999999999787"/> - </dia:attribute> - <dia:attribute name="line_width"> - <dia:real val="0.10000000000000001"/> - </dia:attribute> - <dia:attribute name="line_colour"> - <dia:color val="#000000"/> - </dia:attribute> - <dia:attribute name="fill_colour"> - <dia:color val="#ffffff"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="0"/> - <dia:real val="1"/> - </dia:attribute> - <dia:attribute name="flip_horizontal"> - <dia:boolean val="false"/> - </dia:attribute> - <dia:attribute name="flip_vertical"> - <dia:boolean val="false"/> - </dia:attribute> - <dia:attribute name="subscale"> - <dia:real val="1"/> - </dia:attribute> - </dia:object> - <dia:object type="Geometric - Perfect Circle" version="1" id="O3"> - <dia:attribute name="obj_pos"> - <dia:point val="40.3366,9.8342"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="40.2866,9.7842;41.2366,10.7342"/> - </dia:attribute> - <dia:attribute name="meta"> - <dia:composite type="dict"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="40.3366,9.8342"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="0.84999999999999787"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="0.84999999999999787"/> - </dia:attribute> - <dia:attribute name="line_width"> - <dia:real val="0.10000000000000001"/> - </dia:attribute> - <dia:attribute name="line_colour"> - <dia:color val="#000000"/> - </dia:attribute> - <dia:attribute name="fill_colour"> - <dia:color val="#ffffff"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="0"/> - <dia:real val="1"/> - </dia:attribute> - <dia:attribute name="flip_horizontal"> - <dia:boolean val="false"/> - </dia:attribute> - <dia:attribute name="flip_vertical"> - <dia:boolean val="false"/> - </dia:attribute> - <dia:attribute name="subscale"> - <dia:real val="1"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O4"> - <dia:attribute name="obj_pos"> - <dia:point val="-9.225,8.35"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="-9.27509,7.97487;-0.938197,8.69848"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="-9.225,8.35"/> - <dia:point val="-1.05,8.3356"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="end_arrow"> - <dia:enum val="22"/> - </dia:attribute> - <dia:attribute name="end_arrow_length"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:attribute name="end_arrow_width"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="1" to="O2" connection="2"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O5"> - <dia:attribute name="obj_pos"> - <dia:point val="41.1866,10.2592"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="41.1366,9.89879;49.6019,10.6224"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="41.1866,10.2592"/> - <dia:point val="49.4901,10.2607"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="end_arrow"> - <dia:enum val="22"/> - </dia:attribute> - <dia:attribute name="end_arrow_length"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:attribute name="end_arrow_width"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O3" connection="3"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O6"> - <dia:attribute name="obj_pos"> - <dia:point val="-6.998,7.75"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="-6.998,7.155;-3.193,7.9025"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>#pad 0 (sink)#</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="-6.998,7.75"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#000000"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O7"> - <dia:attribute name="obj_pos"> - <dia:point val="42.452,9.75"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="42.452,9.155;47.097,9.9025"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>#pad 2 (source)#</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="42.452,9.75"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#000000"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Box" version="0" id="O8"> - <dia:attribute name="obj_pos"> - <dia:point val="0.275,6"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="0.225,5.95;8.275,11.25"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="0.275,6"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="7.9499999999999975"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="5.1999999999999975"/> - </dia:attribute> - <dia:attribute name="border_width"> - <dia:real val="0.10000000149011612"/> - </dia:attribute> - <dia:attribute name="border_color"> - <dia:color val="#a52a2a"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Box" version="0" id="O9"> - <dia:attribute name="obj_pos"> - <dia:point val="3.125,6.8"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="3.075,6.75;7.875,10.7"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="3.125,6.8"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="4.6999999999999975"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="3.8499999999999979"/> - </dia:attribute> - <dia:attribute name="border_width"> - <dia:real val="0.10000000149011612"/> - </dia:attribute> - <dia:attribute name="border_color"> - <dia:color val="#0000ff"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O10"> - <dia:attribute name="obj_pos"> - <dia:point val="1.525,4.45"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="1.525,3.855;1.525,4.6025"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>##</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="1.525,4.45"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#000000"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O11"> - <dia:attribute name="obj_pos"> - <dia:point val="0.476918,4.44569"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="0.476918,3.85069;3.95942,5.39819"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>#sink media -bus format#</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="0.476918,4.44569"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#a52a2a"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Box" version="0" id="O12"> - <dia:attribute name="obj_pos"> - <dia:point val="16.6822,9.28251"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="16.6322,9.23251;24.9922,17.9564"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="16.6822,9.28251"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="8.2600228398861297"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="8.6238900617957164"/> - </dia:attribute> - <dia:attribute name="border_width"> - <dia:real val="0.10000000149011612"/> - </dia:attribute> - <dia:attribute name="border_color"> - <dia:color val="#00ff00"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O13"> - <dia:attribute name="obj_pos"> - <dia:point val="16.6822,17.9064"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="3.05732,10.5823;16.7499,17.9741"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="16.6822,17.9064"/> - <dia:point val="3.125,10.65"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O12" connection="5"/> - <dia:connection handle="1" to="O9" connection="5"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O14"> - <dia:attribute name="obj_pos"> - <dia:point val="16.6822,9.28251"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="3.06681,6.74181;16.7404,9.3407"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="16.6822,9.28251"/> - <dia:point val="3.125,6.8"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O12" connection="0"/> - <dia:connection handle="1" to="O9" connection="0"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O15"> - <dia:attribute name="obj_pos"> - <dia:point val="24.9422,17.9064"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="7.75945,10.5845;25.0077,17.9719"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="24.9422,17.9064"/> - <dia:point val="7.825,10.65"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O12" connection="7"/> - <dia:connection handle="1" to="O9" connection="7"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O16"> - <dia:attribute name="obj_pos"> - <dia:point val="24.9422,9.28251"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="7.76834,6.74334;24.9989,9.33917"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="24.9422,9.28251"/> - <dia:point val="7.825,6.8"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O12" connection="2"/> - <dia:connection handle="1" to="O9" connection="2"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O17"> - <dia:attribute name="obj_pos"> - <dia:point val="16.7352,7.47209"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="16.7352,6.87709;22.5602,8.42459"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>#sink compose -selection (scaling)#</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="16.7352,7.47209"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#00ff00"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Box" version="0" id="O18"> - <dia:attribute name="obj_pos"> - <dia:point val="20.4661,9.72825"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="20.4161,9.67825;25.5254,13.3509"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="20.4661,9.72825"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="5.009308462554376"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="3.5726155970598077"/> - </dia:attribute> - <dia:attribute name="border_width"> - <dia:real val="0.10000000149011612"/> - </dia:attribute> - <dia:attribute name="border_color"> - <dia:color val="#a020f0"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O19"> - <dia:attribute name="obj_pos"> - <dia:point val="34.475,5.2564"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="34.475,4.6614;38.7975,6.2089"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>#source media -bus format#</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="34.475,5.2564"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#8b6914"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Box" version="0" id="O20"> - <dia:attribute name="obj_pos"> - <dia:point val="34.4244,8.6917"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="34.3744,8.6417;39.4837,12.3143"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="34.4244,8.6917"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="5.009308462554376"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="3.5726155970598077"/> - </dia:attribute> - <dia:attribute name="border_width"> - <dia:real val="0.10000000149011612"/> - </dia:attribute> - <dia:attribute name="border_color"> - <dia:color val="#8b6914"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O21"> - <dia:attribute name="obj_pos"> - <dia:point val="34.4244,12.2643"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="20.4125,12.2107;34.478,13.3545"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="34.4244,12.2643"/> - <dia:point val="20.4661,13.3009"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O20" connection="5"/> - <dia:connection handle="1" to="O18" connection="5"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O22"> - <dia:attribute name="obj_pos"> - <dia:point val="34.4244,8.6917"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="20.4125,8.63813;34.478,9.78182"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="34.4244,8.6917"/> - <dia:point val="20.4661,9.72825"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O20" connection="0"/> - <dia:connection handle="1" to="O18" connection="0"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O23"> - <dia:attribute name="obj_pos"> - <dia:point val="39.4337,12.2643"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="25.4218,12.2107;39.4873,13.3545"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="39.4337,12.2643"/> - <dia:point val="25.4754,13.3009"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O20" connection="7"/> - <dia:connection handle="1" to="O18" connection="7"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O24"> - <dia:attribute name="obj_pos"> - <dia:point val="39.4337,8.6917"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="25.4218,8.63813;39.4873,9.78182"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="39.4337,8.6917"/> - <dia:point val="25.4754,9.72825"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O20" connection="2"/> - <dia:connection handle="1" to="O18" connection="2"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O25"> - <dia:attribute name="obj_pos"> - <dia:point val="16.25,5.15"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="16.25,4.555;21.68,6.1025"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>#sink compose -bounds selection#</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="16.25,5.15"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#ff765a"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Geometric - Perfect Circle" version="1" id="O26"> - <dia:attribute name="obj_pos"> - <dia:point val="-1.02991,16.6506"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="-1.07991,16.6006;-0.12991,17.5506"/> - </dia:attribute> - <dia:attribute name="meta"> - <dia:composite type="dict"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="-1.02991,16.6506"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="0.84999999999999787"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="0.84999999999999787"/> - </dia:attribute> - <dia:attribute name="line_width"> - <dia:real val="0.10000000000000001"/> - </dia:attribute> - <dia:attribute name="line_colour"> - <dia:color val="#000000"/> - </dia:attribute> - <dia:attribute name="fill_colour"> - <dia:color val="#ffffff"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="0"/> - <dia:real val="1"/> - </dia:attribute> - <dia:attribute name="flip_horizontal"> - <dia:boolean val="false"/> - </dia:attribute> - <dia:attribute name="flip_vertical"> - <dia:boolean val="false"/> - </dia:attribute> - <dia:attribute name="subscale"> - <dia:real val="1"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O27"> - <dia:attribute name="obj_pos"> - <dia:point val="-9.20491,17.09"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="-9.255,16.7149;-0.918107,17.4385"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="-9.20491,17.09"/> - <dia:point val="-1.02991,17.0756"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="end_arrow"> - <dia:enum val="22"/> - </dia:attribute> - <dia:attribute name="end_arrow_length"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:attribute name="end_arrow_width"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="1" to="O26" connection="2"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O28"> - <dia:attribute name="obj_pos"> - <dia:point val="-6.95,16.45"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="-6.95,15.855;-3.145,16.6025"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>#pad 1 (sink)#</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="-6.95,16.45"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#000000"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Box" version="0" id="O29"> - <dia:attribute name="obj_pos"> - <dia:point val="0.390412,14.64"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="0.340412,14.59;6.045,18.8"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="0.390412,14.64"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="5.604587512785236"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="4.1099999999999994"/> - </dia:attribute> - <dia:attribute name="border_width"> - <dia:real val="0.10000000149011612"/> - </dia:attribute> - <dia:attribute name="border_color"> - <dia:color val="#a52a2a"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Box" version="0" id="O30"> - <dia:attribute name="obj_pos"> - <dia:point val="2.645,15.74"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="2.595,15.69;5.6,18.3"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="2.645,15.74"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="2.904999999254942"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="2.5100000000000016"/> - </dia:attribute> - <dia:attribute name="border_width"> - <dia:real val="0.10000000149011612"/> - </dia:attribute> - <dia:attribute name="border_color"> - <dia:color val="#0000ff"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O31"> - <dia:attribute name="obj_pos"> - <dia:point val="1.595,12.99"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="1.595,12.395;1.595,13.1425"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>##</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="1.595,12.99"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#000000"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O32"> - <dia:attribute name="obj_pos"> - <dia:point val="17.945,12.595"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="2.58596,12.536;18.004,15.799"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="17.945,12.595"/> - <dia:point val="2.645,15.74"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O36" connection="0"/> - <dia:connection handle="1" to="O30" connection="0"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O33"> - <dia:attribute name="obj_pos"> - <dia:point val="17.945,15.8"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="2.58772,15.7427;18.0023,18.3073"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="17.945,15.8"/> - <dia:point val="2.645,18.25"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O36" connection="5"/> - <dia:connection handle="1" to="O30" connection="5"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O34"> - <dia:attribute name="obj_pos"> - <dia:point val="21.7,15.8"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="5.49307,15.7431;21.7569,18.3069"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="21.7,15.8"/> - <dia:point val="5.55,18.25"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O36" connection="7"/> - <dia:connection handle="1" to="O30" connection="7"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O35"> - <dia:attribute name="obj_pos"> - <dia:point val="21.7,12.595"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="5.49136,12.5364;21.7586,15.7986"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="21.7,12.595"/> - <dia:point val="5.55,15.74"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O36" connection="2"/> - <dia:connection handle="1" to="O30" connection="2"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Box" version="0" id="O36"> - <dia:attribute name="obj_pos"> - <dia:point val="17.945,12.595"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="17.895,12.545;21.75,15.85"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="17.945,12.595"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="3.7549999992549452"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="3.2049999992549427"/> - </dia:attribute> - <dia:attribute name="border_width"> - <dia:real val="0.10000000149011612"/> - </dia:attribute> - <dia:attribute name="border_color"> - <dia:color val="#00ff00"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="false"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Box" version="0" id="O37"> - <dia:attribute name="obj_pos"> - <dia:point val="22.1631,14.2233"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="22.1131,14.1733;25.45,16.7"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="22.1631,14.2233"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="3.2369000000000021"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="2.4267000000000003"/> - </dia:attribute> - <dia:attribute name="border_width"> - <dia:real val="0.10000000149011612"/> - </dia:attribute> - <dia:attribute name="border_color"> - <dia:color val="#a020f0"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="false"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Box" version="0" id="O38"> - <dia:attribute name="obj_pos"> - <dia:point val="34.6714,16.2367"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="34.6214,16.1867;37.9,18.75"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="34.6714,16.2367"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="3.178600000000003"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="2.4632999999999967"/> - </dia:attribute> - <dia:attribute name="border_width"> - <dia:real val="0.10000000149011612"/> - </dia:attribute> - <dia:attribute name="border_color"> - <dia:color val="#8b6914"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O39"> - <dia:attribute name="obj_pos"> - <dia:point val="34.6714,18.7"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="22.1057,16.5926;34.7288,18.7574"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="34.6714,18.7"/> - <dia:point val="22.1631,16.65"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O38" connection="5"/> - <dia:connection handle="1" to="O37" connection="5"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O40"> - <dia:attribute name="obj_pos"> - <dia:point val="34.6714,16.2367"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="22.1058,14.166;34.7287,16.294"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="34.6714,16.2367"/> - <dia:point val="22.1631,14.2233"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O38" connection="0"/> - <dia:connection handle="1" to="O37" connection="0"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O41"> - <dia:attribute name="obj_pos"> - <dia:point val="37.85,18.7"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="25.3425,16.5925;37.9075,18.7575"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="37.85,18.7"/> - <dia:point val="25.4,16.65"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O38" connection="7"/> - <dia:connection handle="1" to="O37" connection="7"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O42"> - <dia:attribute name="obj_pos"> - <dia:point val="37.85,16.2367"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="25.3427,14.166;37.9073,16.294"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="37.85,16.2367"/> - <dia:point val="25.4,14.2233"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O38" connection="2"/> - <dia:connection handle="1" to="O37" connection="2"/> - </dia:connections> - </dia:object> - <dia:object type="Geometric - Perfect Circle" version="1" id="O43"> - <dia:attribute name="obj_pos"> - <dia:point val="40.347,16.7742"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="40.297,16.7242;41.247,17.6742"/> - </dia:attribute> - <dia:attribute name="meta"> - <dia:composite type="dict"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="40.347,16.7742"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="0.84999999999999787"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="0.84999999999999787"/> - </dia:attribute> - <dia:attribute name="line_width"> - <dia:real val="0.10000000000000001"/> - </dia:attribute> - <dia:attribute name="line_colour"> - <dia:color val="#000000"/> - </dia:attribute> - <dia:attribute name="fill_colour"> - <dia:color val="#ffffff"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="0"/> - <dia:real val="1"/> - </dia:attribute> - <dia:attribute name="flip_horizontal"> - <dia:boolean val="false"/> - </dia:attribute> - <dia:attribute name="flip_vertical"> - <dia:boolean val="false"/> - </dia:attribute> - <dia:attribute name="subscale"> - <dia:real val="1"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O44"> - <dia:attribute name="obj_pos"> - <dia:point val="41.197,17.1992"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="41.147,16.8388;49.6123,17.5624"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="41.197,17.1992"/> - <dia:point val="49.5005,17.2007"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="end_arrow"> - <dia:enum val="22"/> - </dia:attribute> - <dia:attribute name="end_arrow_length"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:attribute name="end_arrow_width"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O43" connection="3"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O45"> - <dia:attribute name="obj_pos"> - <dia:point val="42.4624,16.69"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="42.4624,16.095;47.1074,16.8425"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>#pad 3 (source)#</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="42.4624,16.69"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#000000"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O46"> - <dia:attribute name="obj_pos"> - <dia:point val="9.85,4.55"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="9.85,3.955;12.7275,6.3025"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>#sink -crop -selection#</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="9.85,4.55"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#0000ff"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O47"> - <dia:attribute name="obj_pos"> - <dia:point val="27.65,4.75"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="27.65,4.155;30.5275,6.5025"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>#source -crop -selection#</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="27.65,4.75"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#a020f0"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O48"> - <dia:attribute name="obj_pos"> - <dia:point val="10.55,6.6"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="7.7135,6.39438;10.6035,7.11605"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="10.55,6.6"/> - <dia:point val="7.825,6.8"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#0000ff"/> - </dia:attribute> - <dia:attribute name="end_arrow"> - <dia:enum val="22"/> - </dia:attribute> - <dia:attribute name="end_arrow_length"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:attribute name="end_arrow_width"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="1" to="O9" connection="2"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O49"> - <dia:attribute name="obj_pos"> - <dia:point val="10.45,6.55"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="5.48029,6.48236;10.5176,15.8387"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="10.45,6.55"/> - <dia:point val="5.55,15.74"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#0000ff"/> - </dia:attribute> - <dia:attribute name="end_arrow"> - <dia:enum val="22"/> - </dia:attribute> - <dia:attribute name="end_arrow_length"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:attribute name="end_arrow_width"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="1" to="O30" connection="2"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O50"> - <dia:attribute name="obj_pos"> - <dia:point val="27.5246,6.66071"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="25.406,6.59136;27.594,9.82122"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="27.5246,6.66071"/> - <dia:point val="25.4754,9.72825"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#a020f0"/> - </dia:attribute> - <dia:attribute name="end_arrow"> - <dia:enum val="22"/> - </dia:attribute> - <dia:attribute name="end_arrow_length"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:attribute name="end_arrow_width"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="1" to="O18" connection="2"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O51"> - <dia:attribute name="obj_pos"> - <dia:point val="27.5036,6.68935"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="25.2161,6.62775;27.5652,14.331"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="27.5036,6.68935"/> - <dia:point val="25.4,14.2233"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#a020f0"/> - </dia:attribute> - <dia:attribute name="end_arrow"> - <dia:enum val="22"/> - </dia:attribute> - <dia:attribute name="end_arrow_length"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:attribute name="end_arrow_width"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="1" to="O37" connection="2"/> - </dia:connections> - </dia:object> - </dia:layer> -</dia:diagram> diff --git a/Documentation/DocBook/media/v4l/subdev-image-processing-full.svg b/Documentation/DocBook/media/v4l/subdev-image-processing-full.svg deleted file mode 100644 index 3322cf4c0093..000000000000 --- a/Documentation/DocBook/media/v4l/subdev-image-processing-full.svg +++ /dev/null @@ -1,163 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd"> -<svg width="59cm" height="18cm" viewBox="-186 71 1178 346" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> - <g> - <rect style="fill: #ffffff" x="318.9" y="129" width="208.1" height="249"/> - <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ff765a" x="318.9" y="129" width="208.1" height="249"/> - </g> - <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="-2" y="73" width="806" height="343"/> - <g> - <ellipse style="fill: #ffffff" cx="-12.5" cy="166.712" rx="8.5" ry="8.5"/> - <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.5" cy="166.712" rx="8.5" ry="8.5"/> - <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.5" cy="166.712" rx="8.5" ry="8.5"/> - </g> - <g> - <ellipse style="fill: #ffffff" cx="815.232" cy="205.184" rx="8.5" ry="8.5"/> - <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.232" cy="205.184" rx="8.5" ry="8.5"/> - <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.232" cy="205.184" rx="8.5" ry="8.5"/> - </g> - <g> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-184.5" y1="167" x2="-30.7361" y2="166.729"/> - <polygon style="fill: #000000" points="-23.2361,166.716 -33.2272,171.734 -30.7361,166.729 -33.2449,161.734 "/> - <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-23.2361,166.716 -33.2272,171.734 -30.7361,166.729 -33.2449,161.734 "/> - </g> - <g> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="823.732" y1="205.184" x2="980.066" y2="205.212"/> - <polygon style="fill: #000000" points="987.566,205.214 977.565,210.212 980.066,205.212 977.567,200.212 "/> - <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="987.566,205.214 977.565,210.212 980.066,205.212 977.567,200.212 "/> - </g> - <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-139.96" y="155"> - <tspan x="-139.96" y="155">pad 0 (sink)</tspan> - </text> - <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="849.04" y="195"> - <tspan x="849.04" y="195">pad 2 (source)</tspan> - </text> - <g> - <rect style="fill: #ffffff" x="5.5" y="120" width="159" height="104"/> - <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="5.5" y="120" width="159" height="104"/> - </g> - <g> - <rect style="fill: #ffffff" x="62.5" y="136" width="94" height="77"/> - <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="62.5" y="136" width="94" height="77"/> - </g> - <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="30.5" y="89"> - <tspan x="30.5" y="89"></tspan> - </text> - <text style="fill: #a52a2a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="9.53836" y="88.9138"> - <tspan x="9.53836" y="88.9138">sink media</tspan> - <tspan x="9.53836" y="104.914">bus format</tspan> - </text> - <g> - <rect style="fill: #ffffff" x="333.644" y="185.65" width="165.2" height="172.478"/> - <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #00ff00" x="333.644" y="185.65" width="165.2" height="172.478"/> - </g> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="358.128" x2="62.5" y2="213"/> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="185.65" x2="62.5" y2="136"/> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="358.128" x2="156.5" y2="213"/> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="185.65" x2="156.5" y2="136"/> - <text style="fill: #00ff00;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="334.704" y="149.442"> - <tspan x="334.704" y="149.442">sink compose</tspan> - <tspan x="334.704" y="165.442">selection (scaling)</tspan> - </text> - <g> - <rect style="fill: #ffffff" x="409.322" y="194.565" width="100.186" height="71.4523"/> - <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="409.322" y="194.565" width="100.186" height="71.4523"/> - </g> - <text style="fill: #8b6914;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="689.5" y="105.128"> - <tspan x="689.5" y="105.128">source media</tspan> - <tspan x="689.5" y="121.128">bus format</tspan> - </text> - <g> - <rect style="fill: #ffffff" x="688.488" y="173.834" width="100.186" height="71.4523"/> - <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="688.488" y="173.834" width="100.186" height="71.4523"/> - </g> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="688.488" y1="245.286" x2="409.322" y2="266.018"/> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="688.488" y1="173.834" x2="409.322" y2="194.565"/> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="788.674" y1="245.286" x2="509.508" y2="266.018"/> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="788.674" y1="173.834" x2="509.508" y2="194.565"/> - <text style="fill: #ff765a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="325" y="103"> - <tspan x="325" y="103">sink compose</tspan> - <tspan x="325" y="119">bounds selection</tspan> - </text> - <g> - <ellipse style="fill: #ffffff" cx="-12.0982" cy="341.512" rx="8.5" ry="8.5"/> - <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.0982" cy="341.512" rx="8.5" ry="8.5"/> - <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.0982" cy="341.512" rx="8.5" ry="8.5"/> - </g> - <g> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-184.098" y1="341.8" x2="-30.3343" y2="341.529"/> - <polygon style="fill: #000000" points="-22.8343,341.516 -32.8254,346.534 -30.3343,341.529 -32.8431,336.534 "/> - <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-22.8343,341.516 -32.8254,346.534 -30.3343,341.529 -32.8431,336.534 "/> - </g> - <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-139" y="329"> - <tspan x="-139" y="329">pad 1 (sink)</tspan> - </text> - <g> - <rect style="fill: #ffffff" x="7.80824" y="292.8" width="112.092" height="82.2"/> - <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="7.80824" y="292.8" width="112.092" height="82.2"/> - </g> - <g> - <rect style="fill: #ffffff" x="52.9" y="314.8" width="58.1" height="50.2"/> - <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="52.9" y="314.8" width="58.1" height="50.2"/> - </g> - <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="31.9" y="259.8"> - <tspan x="31.9" y="259.8"></tspan> - </text> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="358.9" y1="251.9" x2="52.9" y2="314.8"/> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="358.9" y1="316" x2="52.9" y2="365"/> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="434" y1="316" x2="111" y2="365"/> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="434" y1="251.9" x2="111" y2="314.8"/> - <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #00ff00" x="358.9" y="251.9" width="75.1" height="64.1"/> - <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="443.262" y="284.466" width="64.738" height="48.534"/> - <g> - <rect style="fill: #ffffff" x="693.428" y="324.734" width="63.572" height="49.266"/> - <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="693.428" y="324.734" width="63.572" height="49.266"/> - </g> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="693.428" y1="374" x2="443.262" y2="333"/> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="693.428" y1="324.734" x2="443.262" y2="284.466"/> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="757" y1="374" x2="508" y2="333"/> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="757" y1="324.734" x2="508" y2="284.466"/> - <g> - <ellipse style="fill: #ffffff" cx="815.44" cy="343.984" rx="8.5" ry="8.5"/> - <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.44" cy="343.984" rx="8.5" ry="8.5"/> - <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.44" cy="343.984" rx="8.5" ry="8.5"/> - </g> - <g> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="823.94" y1="343.984" x2="980.274" y2="344.012"/> - <polygon style="fill: #000000" points="987.774,344.014 977.773,349.012 980.274,344.012 977.775,339.012 "/> - <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="987.774,344.014 977.773,349.012 980.274,344.012 977.775,339.012 "/> - </g> - <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="849.248" y="333.8"> - <tspan x="849.248" y="333.8">pad 3 (source)</tspan> - </text> - <text style="fill: #0000ff;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="197" y="91"> - <tspan x="197" y="91">sink</tspan> - <tspan x="197" y="107">crop</tspan> - <tspan x="197" y="123">selection</tspan> - </text> - <text style="fill: #a020f0;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="553" y="95"> - <tspan x="553" y="95">source</tspan> - <tspan x="553" y="111">crop</tspan> - <tspan x="553" y="127">selection</tspan> - </text> - <g> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x1="211" y1="132" x2="166.21" y2="135.287"/> - <polygon style="fill: #0000ff" points="158.73,135.836 168.337,130.118 166.21,135.287 169.069,140.091 "/> - <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" points="158.73,135.836 168.337,130.118 166.21,135.287 169.069,140.091 "/> - </g> - <g> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x1="209" y1="131" x2="115.581" y2="306.209"/> - <polygon style="fill: #0000ff" points="112.052,312.827 112.345,301.65 115.581,306.209 121.169,306.355 "/> - <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" points="112.052,312.827 112.345,301.65 115.581,306.209 121.169,306.355 "/> - </g> - <g> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="550.492" y1="133.214" x2="514.916" y2="186.469"/> - <polygon style="fill: #a020f0" points="510.75,192.706 512.147,181.613 514.916,186.469 520.463,187.168 "/> - <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="510.75,192.706 512.147,181.613 514.916,186.469 520.463,187.168 "/> - </g> - <g> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="550.072" y1="133.787" x2="510.618" y2="275.089"/> - <polygon style="fill: #a020f0" points="508.601,282.312 506.475,271.336 510.618,275.089 516.106,274.025 "/> - <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="508.601,282.312 506.475,271.336 510.618,275.089 516.106,274.025 "/> - </g> -</svg> diff --git a/Documentation/DocBook/media/v4l/subdev-image-processing-scaling-multi-source.dia b/Documentation/DocBook/media/v4l/subdev-image-processing-scaling-multi-source.dia deleted file mode 100644 index 0cd50a7bda80..000000000000 --- a/Documentation/DocBook/media/v4l/subdev-image-processing-scaling-multi-source.dia +++ /dev/null @@ -1,1152 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<dia:diagram xmlns:dia="http://www.lysator.liu.se/~alla/dia/"> - <dia:diagramdata> - <dia:attribute name="background"> - <dia:color val="#ffffff"/> - </dia:attribute> - <dia:attribute name="pagebreak"> - <dia:color val="#000099"/> - </dia:attribute> - <dia:attribute name="paper"> - <dia:composite type="paper"> - <dia:attribute name="name"> - <dia:string>#A4#</dia:string> - </dia:attribute> - <dia:attribute name="tmargin"> - <dia:real val="2.8222000598907471"/> - </dia:attribute> - <dia:attribute name="bmargin"> - <dia:real val="2.8222000598907471"/> - </dia:attribute> - <dia:attribute name="lmargin"> - <dia:real val="2.8222000598907471"/> - </dia:attribute> - <dia:attribute name="rmargin"> - <dia:real val="2.8222000598907471"/> - </dia:attribute> - <dia:attribute name="is_portrait"> - <dia:boolean val="false"/> - </dia:attribute> - <dia:attribute name="scaling"> - <dia:real val="0.49000000953674316"/> - </dia:attribute> - <dia:attribute name="fitto"> - <dia:boolean val="false"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="grid"> - <dia:composite type="grid"> - <dia:attribute name="width_x"> - <dia:real val="1"/> - </dia:attribute> - <dia:attribute name="width_y"> - <dia:real val="1"/> - </dia:attribute> - <dia:attribute name="visible_x"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="visible_y"> - <dia:int val="1"/> - </dia:attribute> - <dia:composite type="color"/> - </dia:composite> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#d8e5e5"/> - </dia:attribute> - <dia:attribute name="guides"> - <dia:composite type="guides"> - <dia:attribute name="hguides"/> - <dia:attribute name="vguides"/> - </dia:composite> - </dia:attribute> - </dia:diagramdata> - <dia:layer name="Background" visible="true" active="true"> - <dia:object type="Standard - Box" version="0" id="O0"> - <dia:attribute name="obj_pos"> - <dia:point val="-0.4,6.5"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="-0.45,6.45;39.95,22.9"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="-0.4,6.5"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="40.299999999999997"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="16.349999999999998"/> - </dia:attribute> - <dia:attribute name="border_width"> - <dia:real val="0.10000000149011612"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="false"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Box" version="0" id="O1"> - <dia:attribute name="obj_pos"> - <dia:point val="0.225,9.45"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="0.175,9.4;8.225,14.7"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="0.225,9.45"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="7.9499999999999975"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="5.1999999999999975"/> - </dia:attribute> - <dia:attribute name="border_width"> - <dia:real val="0.10000000149011612"/> - </dia:attribute> - <dia:attribute name="border_color"> - <dia:color val="#a52a2a"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Box" version="0" id="O2"> - <dia:attribute name="obj_pos"> - <dia:point val="2.475,10.2"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="2.425,10.15;7.225,14.1"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="2.475,10.2"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="4.6999999999999975"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="3.8499999999999979"/> - </dia:attribute> - <dia:attribute name="border_width"> - <dia:real val="0.10000000149011612"/> - </dia:attribute> - <dia:attribute name="border_color"> - <dia:color val="#0000ff"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O3"> - <dia:attribute name="obj_pos"> - <dia:point val="3,11.2"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="3,10.605;5.8775,12.9525"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>#sink -crop -selection#</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="3,11.2"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#0000ff"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O4"> - <dia:attribute name="obj_pos"> - <dia:point val="1.475,7.9"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="1.475,7.305;1.475,8.0525"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>##</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="1.475,7.9"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#000000"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O5"> - <dia:attribute name="obj_pos"> - <dia:point val="0.426918,7.89569"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="0.426918,7.30069;3.90942,8.84819"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>#sink media -bus format#</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="0.426918,7.89569"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#a52a2a"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Box" version="0" id="O6"> - <dia:attribute name="obj_pos"> - <dia:point val="16.6822,9.28251"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="16.6322,9.23251;24.9922,17.9564"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="16.6822,9.28251"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="8.2600228398861297"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="8.6238900617957164"/> - </dia:attribute> - <dia:attribute name="border_width"> - <dia:real val="0.10000000149011612"/> - </dia:attribute> - <dia:attribute name="border_color"> - <dia:color val="#00ff00"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O7"> - <dia:attribute name="obj_pos"> - <dia:point val="16.6822,17.9064"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="2.41365,13.9886;16.7436,17.9678"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="16.6822,17.9064"/> - <dia:point val="2.475,14.05"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O6" connection="5"/> - <dia:connection handle="1" to="O2" connection="5"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O8"> - <dia:attribute name="obj_pos"> - <dia:point val="16.6822,9.28251"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="2.42188,9.22939;16.7353,10.2531"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="16.6822,9.28251"/> - <dia:point val="2.475,10.2"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O6" connection="0"/> - <dia:connection handle="1" to="O2" connection="0"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O9"> - <dia:attribute name="obj_pos"> - <dia:point val="24.9422,17.9064"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="7.11553,13.9905;25.0017,17.9659"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="24.9422,17.9064"/> - <dia:point val="7.175,14.05"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O6" connection="7"/> - <dia:connection handle="1" to="O2" connection="7"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O10"> - <dia:attribute name="obj_pos"> - <dia:point val="24.9422,9.28251"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="7.12249,9.23;24.9947,10.2525"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="24.9422,9.28251"/> - <dia:point val="7.175,10.2"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O6" connection="2"/> - <dia:connection handle="1" to="O2" connection="2"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O11"> - <dia:attribute name="obj_pos"> - <dia:point val="16.7352,7.47209"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="16.7352,6.87709;22.5602,8.42459"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>#sink compose -selection (scaling)#</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="16.7352,7.47209"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#00ff00"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Box" version="0" id="O12"> - <dia:attribute name="obj_pos"> - <dia:point val="19.1161,9.97825"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="19.0661,9.92825;24.1754,13.6009"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="19.1161,9.97825"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="5.009308462554376"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="3.5726155970598077"/> - </dia:attribute> - <dia:attribute name="border_width"> - <dia:real val="0.10000000149011612"/> - </dia:attribute> - <dia:attribute name="border_color"> - <dia:color val="#a020f0"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O13"> - <dia:attribute name="obj_pos"> - <dia:point val="27.1661,7.47209"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="27.1661,6.87709;30.0436,9.22459"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>#source -crop -selection#</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="27.1661,7.47209"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#a020f0"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O14"> - <dia:attribute name="obj_pos"> - <dia:point val="34.575,7.8564"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="34.575,7.2614;38.8975,8.8089"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>#source media -bus format#</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="34.575,7.8564"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#8b6914"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Box" version="0" id="O15"> - <dia:attribute name="obj_pos"> - <dia:point val="34.5244,11.2917"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="34.4744,11.2417;39.5837,14.9143"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="34.5244,11.2917"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="5.009308462554376"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="3.5726155970598077"/> - </dia:attribute> - <dia:attribute name="border_width"> - <dia:real val="0.10000000149011612"/> - </dia:attribute> - <dia:attribute name="border_color"> - <dia:color val="#8b6914"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O16"> - <dia:attribute name="obj_pos"> - <dia:point val="34.5244,14.8643"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="19.062,13.4968;34.5785,14.9184"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="34.5244,14.8643"/> - <dia:point val="19.1161,13.5509"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O15" connection="5"/> - <dia:connection handle="1" to="O12" connection="5"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O17"> - <dia:attribute name="obj_pos"> - <dia:point val="34.5244,11.2917"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="19.062,9.92418;34.5785,11.3458"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="34.5244,11.2917"/> - <dia:point val="19.1161,9.97825"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O15" connection="0"/> - <dia:connection handle="1" to="O12" connection="0"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O18"> - <dia:attribute name="obj_pos"> - <dia:point val="39.5337,14.8643"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="24.0713,13.4968;39.5878,14.9184"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="39.5337,14.8643"/> - <dia:point val="24.1254,13.5509"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O15" connection="7"/> - <dia:connection handle="1" to="O12" connection="7"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O19"> - <dia:attribute name="obj_pos"> - <dia:point val="39.5337,11.2917"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="24.0713,9.92418;39.5878,11.3458"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="39.5337,11.2917"/> - <dia:point val="24.1254,9.97825"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O15" connection="2"/> - <dia:connection handle="1" to="O12" connection="2"/> - </dia:connections> - </dia:object> - <dia:object type="Geometric - Perfect Circle" version="1" id="O20"> - <dia:attribute name="obj_pos"> - <dia:point val="39.98,12.0742"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="39.93,12.0242;40.88,12.9742"/> - </dia:attribute> - <dia:attribute name="meta"> - <dia:composite type="dict"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="39.98,12.0742"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="0.84999999999999787"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="0.84999999999999787"/> - </dia:attribute> - <dia:attribute name="line_width"> - <dia:real val="0.10000000000000001"/> - </dia:attribute> - <dia:attribute name="line_colour"> - <dia:color val="#000000"/> - </dia:attribute> - <dia:attribute name="fill_colour"> - <dia:color val="#ffffff"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="0"/> - <dia:real val="1"/> - </dia:attribute> - <dia:attribute name="flip_horizontal"> - <dia:boolean val="false"/> - </dia:attribute> - <dia:attribute name="flip_vertical"> - <dia:boolean val="false"/> - </dia:attribute> - <dia:attribute name="subscale"> - <dia:real val="1"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O21"> - <dia:attribute name="obj_pos"> - <dia:point val="40.83,12.4992"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="40.78,12.1388;49.2453,12.8624"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="40.83,12.4992"/> - <dia:point val="49.1335,12.5007"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="end_arrow"> - <dia:enum val="22"/> - </dia:attribute> - <dia:attribute name="end_arrow_length"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:attribute name="end_arrow_width"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O20" connection="3"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O22"> - <dia:attribute name="obj_pos"> - <dia:point val="42.0954,11.99"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="42.0954,11.395;46.7404,12.1425"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>#pad 1 (source)#</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="42.0954,11.99"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#000000"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Geometric - Perfect Circle" version="1" id="O23"> - <dia:attribute name="obj_pos"> - <dia:point val="-1.44491,11.6506"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="-1.49491,11.6006;-0.54491,12.5506"/> - </dia:attribute> - <dia:attribute name="meta"> - <dia:composite type="dict"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="-1.44491,11.6506"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="0.84999999999999787"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="0.84999999999999787"/> - </dia:attribute> - <dia:attribute name="line_width"> - <dia:real val="0.10000000000000001"/> - </dia:attribute> - <dia:attribute name="line_colour"> - <dia:color val="#000000"/> - </dia:attribute> - <dia:attribute name="fill_colour"> - <dia:color val="#ffffff"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="0"/> - <dia:real val="1"/> - </dia:attribute> - <dia:attribute name="flip_horizontal"> - <dia:boolean val="false"/> - </dia:attribute> - <dia:attribute name="flip_vertical"> - <dia:boolean val="false"/> - </dia:attribute> - <dia:attribute name="subscale"> - <dia:real val="1"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O24"> - <dia:attribute name="obj_pos"> - <dia:point val="-9.61991,12.09"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="-9.67,11.7149;-1.33311,12.4385"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="-9.61991,12.09"/> - <dia:point val="-1.44491,12.0756"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="end_arrow"> - <dia:enum val="22"/> - </dia:attribute> - <dia:attribute name="end_arrow_length"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:attribute name="end_arrow_width"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="1" to="O23" connection="2"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O25"> - <dia:attribute name="obj_pos"> - <dia:point val="-7.39291,11.49"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="-7.39291,10.895;-3.58791,11.6425"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>#pad 0 (sink)#</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="-7.39291,11.49"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#000000"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Box" version="0" id="O26"> - <dia:attribute name="obj_pos"> - <dia:point val="19.4911,13.8333"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="19.4411,13.7833;24.5504,17.4559"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="19.4911,13.8333"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="5.009308462554376"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="3.5726155970598077"/> - </dia:attribute> - <dia:attribute name="border_width"> - <dia:real val="0.10000000149011612"/> - </dia:attribute> - <dia:attribute name="border_color"> - <dia:color val="#a020f0"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="false"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Box" version="0" id="O27"> - <dia:attribute name="obj_pos"> - <dia:point val="34.4994,17.2967"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="34.4494,17.2467;39.5587,20.9193"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="34.4994,17.2967"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="5.009308462554376"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="3.5726155970598077"/> - </dia:attribute> - <dia:attribute name="border_width"> - <dia:real val="0.10000000149011612"/> - </dia:attribute> - <dia:attribute name="border_color"> - <dia:color val="#8b6914"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O28"> - <dia:attribute name="obj_pos"> - <dia:point val="34.4994,20.8693"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="19.4311,17.3459;34.5594,20.9293"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="34.4994,20.8693"/> - <dia:point val="19.4911,17.4059"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O27" connection="5"/> - <dia:connection handle="1" to="O26" connection="5"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O29"> - <dia:attribute name="obj_pos"> - <dia:point val="34.4994,17.2967"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="19.4311,13.7733;34.5594,17.3567"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="34.4994,17.2967"/> - <dia:point val="19.4911,13.8333"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O27" connection="0"/> - <dia:connection handle="1" to="O26" connection="0"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O30"> - <dia:attribute name="obj_pos"> - <dia:point val="39.5087,20.8693"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="24.4404,17.3459;39.5687,20.9293"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="39.5087,20.8693"/> - <dia:point val="24.5004,17.4059"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O27" connection="7"/> - <dia:connection handle="1" to="O26" connection="7"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O31"> - <dia:attribute name="obj_pos"> - <dia:point val="39.5087,17.2967"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="24.4404,13.7733;39.5687,17.3567"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="39.5087,17.2967"/> - <dia:point val="24.5004,13.8333"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#e60505"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="4"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O27" connection="2"/> - <dia:connection handle="1" to="O26" connection="2"/> - </dia:connections> - </dia:object> - <dia:object type="Geometric - Perfect Circle" version="1" id="O32"> - <dia:attribute name="obj_pos"> - <dia:point val="39.855,18.7792"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="39.805,18.7292;40.755,19.6792"/> - </dia:attribute> - <dia:attribute name="meta"> - <dia:composite type="dict"/> - </dia:attribute> - <dia:attribute name="elem_corner"> - <dia:point val="39.855,18.7792"/> - </dia:attribute> - <dia:attribute name="elem_width"> - <dia:real val="0.84999999999999787"/> - </dia:attribute> - <dia:attribute name="elem_height"> - <dia:real val="0.84999999999999787"/> - </dia:attribute> - <dia:attribute name="line_width"> - <dia:real val="0.10000000000000001"/> - </dia:attribute> - <dia:attribute name="line_colour"> - <dia:color val="#000000"/> - </dia:attribute> - <dia:attribute name="fill_colour"> - <dia:color val="#ffffff"/> - </dia:attribute> - <dia:attribute name="show_background"> - <dia:boolean val="true"/> - </dia:attribute> - <dia:attribute name="line_style"> - <dia:enum val="0"/> - <dia:real val="1"/> - </dia:attribute> - <dia:attribute name="flip_horizontal"> - <dia:boolean val="false"/> - </dia:attribute> - <dia:attribute name="flip_vertical"> - <dia:boolean val="false"/> - </dia:attribute> - <dia:attribute name="subscale"> - <dia:real val="1"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O33"> - <dia:attribute name="obj_pos"> - <dia:point val="40.705,19.2042"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="40.655,18.8438;49.1203,19.5674"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="40.705,19.2042"/> - <dia:point val="49.0085,19.2057"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="end_arrow"> - <dia:enum val="22"/> - </dia:attribute> - <dia:attribute name="end_arrow_length"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:attribute name="end_arrow_width"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="0" to="O32" connection="3"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Text" version="1" id="O34"> - <dia:attribute name="obj_pos"> - <dia:point val="41.9704,18.695"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="41.9704,18.1;46.6154,18.8475"/> - </dia:attribute> - <dia:attribute name="text"> - <dia:composite type="text"> - <dia:attribute name="string"> - <dia:string>#pad 2 (source)#</dia:string> - </dia:attribute> - <dia:attribute name="font"> - <dia:font family="sans" style="0" name="Helvetica"/> - </dia:attribute> - <dia:attribute name="height"> - <dia:real val="0.80000000000000004"/> - </dia:attribute> - <dia:attribute name="pos"> - <dia:point val="41.9704,18.695"/> - </dia:attribute> - <dia:attribute name="color"> - <dia:color val="#000000"/> - </dia:attribute> - <dia:attribute name="alignment"> - <dia:enum val="0"/> - </dia:attribute> - </dia:composite> - </dia:attribute> - <dia:attribute name="valign"> - <dia:enum val="3"/> - </dia:attribute> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O35"> - <dia:attribute name="obj_pos"> - <dia:point val="27.3,9.55"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="24.0146,9.49376;27.3562,10.255"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="27.3,9.55"/> - <dia:point val="24.1254,9.97825"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#a020f0"/> - </dia:attribute> - <dia:attribute name="end_arrow"> - <dia:enum val="22"/> - </dia:attribute> - <dia:attribute name="end_arrow_length"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:attribute name="end_arrow_width"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="1" to="O12" connection="2"/> - </dia:connections> - </dia:object> - <dia:object type="Standard - Line" version="0" id="O36"> - <dia:attribute name="obj_pos"> - <dia:point val="27.3454,9.53624"/> - </dia:attribute> - <dia:attribute name="obj_bb"> - <dia:rectangle val="24.4311,9.46695;27.4147,13.9265"/> - </dia:attribute> - <dia:attribute name="conn_endpoints"> - <dia:point val="27.3454,9.53624"/> - <dia:point val="24.5004,13.8333"/> - </dia:attribute> - <dia:attribute name="numcp"> - <dia:int val="1"/> - </dia:attribute> - <dia:attribute name="line_color"> - <dia:color val="#a020f0"/> - </dia:attribute> - <dia:attribute name="end_arrow"> - <dia:enum val="22"/> - </dia:attribute> - <dia:attribute name="end_arrow_length"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:attribute name="end_arrow_width"> - <dia:real val="0.5"/> - </dia:attribute> - <dia:connections> - <dia:connection handle="1" to="O26" connection="2"/> - </dia:connections> - </dia:object> - </dia:layer> -</dia:diagram> diff --git a/Documentation/DocBook/media/v4l/subdev-image-processing-scaling-multi-source.svg b/Documentation/DocBook/media/v4l/subdev-image-processing-scaling-multi-source.svg deleted file mode 100644 index 2340c0f8bc92..000000000000 --- a/Documentation/DocBook/media/v4l/subdev-image-processing-scaling-multi-source.svg +++ /dev/null @@ -1,116 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd"> -<svg width="59cm" height="17cm" viewBox="-194 128 1179 330" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> - <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="-8" y="130" width="806" height="327"/> - <g> - <rect style="fill: #ffffff" x="4.5" y="189" width="159" height="104"/> - <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="4.5" y="189" width="159" height="104"/> - </g> - <g> - <rect style="fill: #ffffff" x="49.5" y="204" width="94" height="77"/> - <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="49.5" y="204" width="94" height="77"/> - </g> - <text style="fill: #0000ff;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="60" y="224"> - <tspan x="60" y="224">sink</tspan> - <tspan x="60" y="240">crop</tspan> - <tspan x="60" y="256">selection</tspan> - </text> - <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="29.5" y="158"> - <tspan x="29.5" y="158"></tspan> - </text> - <text style="fill: #a52a2a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="8.53836" y="157.914"> - <tspan x="8.53836" y="157.914">sink media</tspan> - <tspan x="8.53836" y="173.914">bus format</tspan> - </text> - <g> - <rect style="fill: #ffffff" x="333.644" y="185.65" width="165.2" height="172.478"/> - <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #00ff00" x="333.644" y="185.65" width="165.2" height="172.478"/> - </g> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="358.128" x2="49.5" y2="281"/> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="185.65" x2="49.5" y2="204"/> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="358.128" x2="143.5" y2="281"/> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="185.65" x2="143.5" y2="204"/> - <text style="fill: #00ff00;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="334.704" y="149.442"> - <tspan x="334.704" y="149.442">sink compose</tspan> - <tspan x="334.704" y="165.442">selection (scaling)</tspan> - </text> - <g> - <rect style="fill: #ffffff" x="382.322" y="199.565" width="100.186" height="71.4523"/> - <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="382.322" y="199.565" width="100.186" height="71.4523"/> - </g> - <text style="fill: #a020f0;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="543.322" y="149.442"> - <tspan x="543.322" y="149.442">source</tspan> - <tspan x="543.322" y="165.442">crop</tspan> - <tspan x="543.322" y="181.442">selection</tspan> - </text> - <text style="fill: #8b6914;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="691.5" y="157.128"> - <tspan x="691.5" y="157.128">source media</tspan> - <tspan x="691.5" y="173.128">bus format</tspan> - </text> - <g> - <rect style="fill: #ffffff" x="690.488" y="225.834" width="100.186" height="71.4523"/> - <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="690.488" y="225.834" width="100.186" height="71.4523"/> - </g> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="690.488" y1="297.286" x2="382.322" y2="271.018"/> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="690.488" y1="225.834" x2="382.322" y2="199.565"/> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.674" y1="297.286" x2="482.508" y2="271.018"/> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.674" y1="225.834" x2="482.508" y2="199.565"/> - <g> - <ellipse style="fill: #ffffff" cx="808.1" cy="249.984" rx="8.5" ry="8.5"/> - <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="808.1" cy="249.984" rx="8.5" ry="8.5"/> - <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="808.1" cy="249.984" rx="8.5" ry="8.5"/> - </g> - <g> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="816.6" y1="249.984" x2="972.934" y2="250.012"/> - <polygon style="fill: #000000" points="980.434,250.014 970.433,255.012 972.934,250.012 970.435,245.012 "/> - <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="980.434,250.014 970.433,255.012 972.934,250.012 970.435,245.012 "/> - </g> - <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="841.908" y="239.8"> - <tspan x="841.908" y="239.8">pad 1 (source)</tspan> - </text> - <g> - <ellipse style="fill: #ffffff" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/> - <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/> - <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/> - </g> - <g> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-192.398" y1="241.8" x2="-38.6343" y2="241.529"/> - <polygon style="fill: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/> - <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/> - </g> - <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-147.858" y="229.8"> - <tspan x="-147.858" y="229.8">pad 0 (sink)</tspan> - </text> - <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="389.822" y="276.666" width="100.186" height="71.4523"/> - <g> - <rect style="fill: #ffffff" x="689.988" y="345.934" width="100.186" height="71.4523"/> - <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="689.988" y="345.934" width="100.186" height="71.4523"/> - </g> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="689.988" y1="417.386" x2="389.822" y2="348.118"/> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="689.988" y1="345.934" x2="389.822" y2="276.666"/> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.174" y1="417.386" x2="490.008" y2="348.118"/> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.174" y1="345.934" x2="490.008" y2="276.666"/> - <g> - <ellipse style="fill: #ffffff" cx="805.6" cy="384.084" rx="8.5" ry="8.5"/> - <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="805.6" cy="384.084" rx="8.5" ry="8.5"/> - <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="805.6" cy="384.084" rx="8.5" ry="8.5"/> - </g> - <g> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="814.1" y1="384.084" x2="970.434" y2="384.112"/> - <polygon style="fill: #000000" points="977.934,384.114 967.933,389.112 970.434,384.112 967.935,379.112 "/> - <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="977.934,384.114 967.933,389.112 970.434,384.112 967.935,379.112 "/> - </g> - <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="839.408" y="373.9"> - <tspan x="839.408" y="373.9">pad 2 (source)</tspan> - </text> - <g> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="546" y1="191" x2="492.157" y2="198.263"/> - <polygon style="fill: #a020f0" points="484.724,199.266 493.966,192.974 492.157,198.263 495.303,202.884 "/> - <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="484.724,199.266 493.966,192.974 492.157,198.263 495.303,202.884 "/> - </g> - <g> - <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="546.908" y1="190.725" x2="495.383" y2="268.548"/> - <polygon style="fill: #a020f0" points="491.242,274.802 492.594,263.703 495.383,268.548 500.932,269.224 "/> - <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="491.242,274.802 492.594,263.703 495.383,268.548 500.932,269.224 "/> - </g> -</svg> diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml deleted file mode 100644 index 42e626d6c936..000000000000 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ /dev/null @@ -1,728 +0,0 @@ - <partinfo> - <authorgroup> - <author> - <firstname>Michael</firstname> - <surname>Schimek</surname> - <othername role="mi">H</othername> - <affiliation> - <address> - <email>mschimek@gmx.at</email> - </address> - </affiliation> - </author> - - <author> - <firstname>Bill</firstname> - <surname>Dirks</surname> - <!-- Commented until Bill opts in to be spammed. - <affiliation> - <address> - <email>bill@thedirks.org</email> - </address> - </affiliation> --> - <contrib>Original author of the V4L2 API and -documentation.</contrib> - </author> - - <author> - <firstname>Hans</firstname> - <surname>Verkuil</surname> - <contrib>Designed and documented the VIDIOC_LOG_STATUS ioctl, -the extended control ioctls, major parts of the sliced VBI API, the -MPEG encoder and decoder APIs and the DV Timings API.</contrib> - <affiliation> - <address> - <email>hverkuil@xs4all.nl</email> - </address> - </affiliation> - </author> - - <author> - <firstname>Martin</firstname> - <surname>Rubli</surname> - <!-- - <affiliation> - <address> - <email>martin_rubli@logitech.com</email> - </address> - </affiliation> --> - <contrib>Designed and documented the VIDIOC_ENUM_FRAMESIZES -and VIDIOC_ENUM_FRAMEINTERVALS ioctls.</contrib> - </author> - - <author> - <firstname>Andy</firstname> - <surname>Walls</surname> - <contrib>Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV -MPEG stream embedded, sliced VBI data format in this specification. -</contrib> - <affiliation> - <address> - <email>awalls@md.metrocast.net</email> - </address> - </affiliation> - </author> - - <author> - <firstname>Mauro</firstname> - <surname>Carvalho Chehab</surname> - <contrib>Documented libv4l, designed and added v4l2grab example, -Remote Controller chapter.</contrib> - <affiliation> - <address> - <email>m.chehab@samsung.com</email> - </address> - </affiliation> - </author> - - <author> - <firstname>Muralidharan</firstname> - <surname>Karicheri</surname> - <contrib>Documented the Digital Video timings API.</contrib> - <affiliation> - <address> - <email>m-karicheri2@ti.com</email> - </address> - </affiliation> - </author> - - <author> - <firstname>Pawel</firstname> - <surname>Osciak</surname> - <contrib>Designed and documented the multi-planar API.</contrib> - <affiliation> - <address> - <email>pawel AT osciak.com</email> - </address> - </affiliation> - </author> - - <author> - <firstname>Sakari</firstname> - <surname>Ailus</surname> - <contrib>Subdev selections API.</contrib> - <affiliation> - <address> - <email>sakari.ailus@iki.fi</email> - </address> - </affiliation> - </author> - <author> - <firstname>Antti</firstname> - <surname>Palosaari</surname> - <contrib>SDR API.</contrib> - <affiliation> - <address> - <email>crope@iki.fi</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>1999</year> - <year>2000</year> - <year>2001</year> - <year>2002</year> - <year>2003</year> - <year>2004</year> - <year>2005</year> - <year>2006</year> - <year>2007</year> - <year>2008</year> - <year>2009</year> - <year>2010</year> - <year>2011</year> - <year>2012</year> - <year>2013</year> - <year>2014</year> - <year>2015</year> - <holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin -Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, - Pawel Osciak</holder> - </copyright> - <legalnotice> - <para>Except when explicitly stated as GPL, programming examples within - this part can be used and distributed without restrictions.</para> - </legalnotice> - <revhistory> - <!-- Put document revisions here, newest first. --> - <!-- API revisions (changes and additions of defines, enums, -structs, ioctls) must be noted in more detail in the history chapter -(compat.xml), along with the possible impact on existing drivers and -applications. --> - <revision> - <revnumber>4.5</revnumber> - <date>2015-10-29</date> - <authorinitials>rr</authorinitials> - <revremark>Extend vidioc-g-ext-ctrls;. Replace ctrl_class with a new -union with ctrl_class and which. Which is used to select the current value of -the control or the default value. - </revremark> - </revision> - - <revision> - <revnumber>4.4</revnumber> - <date>2015-05-26</date> - <authorinitials>ap</authorinitials> - <revremark>Renamed V4L2_TUNER_ADC to V4L2_TUNER_SDR. -Added V4L2_CID_RF_TUNER_RF_GAIN control. -Added transmitter support for Software Defined Radio (SDR) Interface. - </revremark> - </revision> - - <revision> - <revnumber>4.1</revnumber> - <date>2015-02-13</date> - <authorinitials>mcc</authorinitials> - <revremark>Fix documentation for media controller device nodes and add support for DVB device nodes. -Add support for Tuner sub-device. - </revremark> - </revision> - <revision> - <revnumber>3.19</revnumber> - <date>2014-12-05</date> - <authorinitials>hv</authorinitials> - <revremark>Rewrote Colorspace chapter, added new &v4l2-ycbcr-encoding; and &v4l2-quantization; fields -to &v4l2-pix-format;, &v4l2-pix-format-mplane; and &v4l2-mbus-framefmt;. - </revremark> - </revision> - - <revision> - <revnumber>3.17</revnumber> - <date>2014-08-04</date> - <authorinitials>lp, hv</authorinitials> - <revremark>Extended &v4l2-pix-format;. Added format flags. Added compound control types -and VIDIOC_QUERY_EXT_CTRL. - </revremark> - </revision> - - <revision> - <revnumber>3.15</revnumber> - <date>2014-02-03</date> - <authorinitials>hv, ap</authorinitials> - <revremark>Update several sections of "Common API Elements": "Opening and Closing Devices" -"Querying Capabilities", "Application Priority", "Video Inputs and Outputs", "Audio Inputs and Outputs" -"Tuners and Modulators", "Video Standards" and "Digital Video (DV) Timings". Added SDR API. - </revremark> - </revision> - - <revision> - <revnumber>3.14</revnumber> - <date>2013-11-25</date> - <authorinitials>rr</authorinitials> - <revremark>Set width and height as unsigned on v4l2_rect. - </revremark> - </revision> - - <revision> - <revnumber>3.11</revnumber> - <date>2013-05-26</date> - <authorinitials>hv</authorinitials> - <revremark>Remove obsolete VIDIOC_DBG_G_CHIP_IDENT ioctl. - </revremark> - </revision> - - <revision> - <revnumber>3.10</revnumber> - <date>2013-03-25</date> - <authorinitials>hv</authorinitials> - <revremark>Remove obsolete and unused DV_PRESET ioctls: - VIDIOC_G_DV_PRESET, VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and - VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output capability - flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS. Added VIDIOC_DBG_G_CHIP_INFO. - </revremark> - </revision> - - <revision> - <revnumber>3.9</revnumber> - <date>2012-12-03</date> - <authorinitials>sa, sn</authorinitials> - <revremark>Added timestamp types to v4l2_buffer. - Added V4L2_EVENT_CTRL_CH_RANGE control event changes flag. - </revremark> - </revision> - - <revision> - <revnumber>3.6</revnumber> - <date>2012-07-02</date> - <authorinitials>hv</authorinitials> - <revremark>Added VIDIOC_ENUM_FREQ_BANDS. - </revremark> - </revision> - - <revision> - <revnumber>3.5</revnumber> - <date>2012-05-07</date> - <authorinitials>sa, sn, hv</authorinitials> - <revremark>Added V4L2_CTRL_TYPE_INTEGER_MENU and V4L2 subdev - selections API. Improved the description of V4L2_CID_COLORFX - control, added V4L2_CID_COLORFX_CBCR control. - Added camera controls V4L2_CID_AUTO_EXPOSURE_BIAS, - V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE, V4L2_CID_IMAGE_STABILIZATION, - V4L2_CID_ISO_SENSITIVITY, V4L2_CID_ISO_SENSITIVITY_AUTO, - V4L2_CID_EXPOSURE_METERING, V4L2_CID_SCENE_MODE, - V4L2_CID_3A_LOCK, V4L2_CID_AUTO_FOCUS_START, - V4L2_CID_AUTO_FOCUS_STOP, V4L2_CID_AUTO_FOCUS_STATUS - and V4L2_CID_AUTO_FOCUS_RANGE. - Added VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and - VIDIOC_DV_TIMINGS_CAP. - </revremark> - </revision> - - <revision> - <revnumber>3.4</revnumber> - <date>2012-01-25</date> - <authorinitials>sn</authorinitials> - <revremark>Added <link linkend="jpeg-controls">JPEG compression - control class.</link> - </revremark> - </revision> - - <revision> - <revnumber>3.3</revnumber> - <date>2012-01-11</date> - <authorinitials>hv</authorinitials> - <revremark>Added device_caps field to struct v4l2_capabilities.</revremark> - </revision> - - <revision> - <revnumber>3.2</revnumber> - <date>2011-08-26</date> - <authorinitials>hv</authorinitials> - <revremark>Added V4L2_CTRL_FLAG_VOLATILE.</revremark> - </revision> - - <revision> - <revnumber>3.1</revnumber> - <date>2011-06-27</date> - <authorinitials>mcc, po, hv</authorinitials> - <revremark>Documented that VIDIOC_QUERYCAP now returns a per-subsystem version instead of a per-driver one. - Standardize an error code for invalid ioctl. - Added V4L2_CTRL_TYPE_BITMASK.</revremark> - </revision> - - <revision> - <revnumber>2.6.39</revnumber> - <date>2011-03-01</date> - <authorinitials>mcc, po</authorinitials> - <revremark>Removed VIDIOC_*_OLD from videodev2.h header and update it to reflect latest changes. Added the <link linkend="planar-apis">multi-planar API</link>.</revremark> - </revision> - - <revision> - <revnumber>2.6.37</revnumber> - <date>2010-08-06</date> - <authorinitials>hv</authorinitials> - <revremark>Removed obsolete vtx (videotext) API.</revremark> - </revision> - - <revision> - <revnumber>2.6.33</revnumber> - <date>2009-12-03</date> - <authorinitials>mk</authorinitials> - <revremark>Added documentation for the Digital Video timings API.</revremark> - </revision> - - <revision> - <revnumber>2.6.32</revnumber> - <date>2009-08-31</date> - <authorinitials>mcc</authorinitials> - <revremark>Now, revisions will match the kernel version where -the V4L2 API changes will be used by the Linux Kernel. -Also added Remote Controller chapter.</revremark> - </revision> - - <revision> - <revnumber>0.29</revnumber> - <date>2009-08-26</date> - <authorinitials>ev</authorinitials> - <revremark>Added documentation for string controls and for FM Transmitter controls.</revremark> - </revision> - - <revision> - <revnumber>0.28</revnumber> - <date>2009-08-26</date> - <authorinitials>gl</authorinitials> - <revremark>Added V4L2_CID_BAND_STOP_FILTER documentation.</revremark> - </revision> - - <revision> - <revnumber>0.27</revnumber> - <date>2009-08-15</date> - <authorinitials>mcc</authorinitials> - <revremark>Added libv4l and Remote Controller documentation; -added v4l2grab and keytable application examples.</revremark> - </revision> - - <revision> - <revnumber>0.26</revnumber> - <date>2009-07-23</date> - <authorinitials>hv</authorinitials> - <revremark>Finalized the RDS capture API. Added modulator and RDS encoder -capabilities. Added support for string controls.</revremark> - </revision> - - <revision> - <revnumber>0.25</revnumber> - <date>2009-01-18</date> - <authorinitials>hv</authorinitials> - <revremark>Added pixel formats VYUY, NV16 and NV61, and changed -the debug ioctls VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT. -Added camera controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE, -V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY.</revremark> - </revision> - - <revision> - <revnumber>0.24</revnumber> - <date>2008-03-04</date> - <authorinitials>mhs</authorinitials> - <revremark>Added pixel formats Y16 and SBGGR16, new controls -and a camera controls class. Removed VIDIOC_G/S_MPEGCOMP.</revremark> - </revision> - - <revision> - <revnumber>0.23</revnumber> - <date>2007-08-30</date> - <authorinitials>mhs</authorinitials> - <revremark>Fixed a typo in VIDIOC_DBG_G/S_REGISTER. -Clarified the byte order of packed pixel formats.</revremark> - </revision> - - <revision> - <revnumber>0.22</revnumber> - <date>2007-08-29</date> - <authorinitials>mhs</authorinitials> - <revremark>Added the Video Output Overlay interface, new MPEG -controls, V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT, -VIDIOC_DBG_G/S_REGISTER, VIDIOC_(TRY_)ENCODER_CMD, -VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats. -Clarifications in the cropping chapter, about RGB pixel formats, the -mmap(), poll(), select(), read() and write() functions. Typographical -fixes.</revremark> - </revision> - - <revision> - <revnumber>0.21</revnumber> - <date>2006-12-19</date> - <authorinitials>mhs</authorinitials> - <revremark>Fixed a link in the VIDIOC_G_EXT_CTRLS section.</revremark> - </revision> - - <revision> - <revnumber>0.20</revnumber> - <date>2006-11-24</date> - <authorinitials>mhs</authorinitials> - <revremark>Clarified the purpose of the audioset field in -struct v4l2_input and v4l2_output.</revremark> - </revision> - - <revision> - <revnumber>0.19</revnumber> - <date>2006-10-19</date> - <authorinitials>mhs</authorinitials> - <revremark>Documented V4L2_PIX_FMT_RGB444.</revremark> - </revision> - - <revision> - <revnumber>0.18</revnumber> - <date>2006-10-18</date> - <authorinitials>mhs</authorinitials> - <revremark>Added the description of extended controls by Hans -Verkuil. Linked V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE.</revremark> - </revision> - - <revision> - <revnumber>0.17</revnumber> - <date>2006-10-12</date> - <authorinitials>mhs</authorinitials> - <revremark>Corrected V4L2_PIX_FMT_HM12 description.</revremark> - </revision> - - <revision> - <revnumber>0.16</revnumber> - <date>2006-10-08</date> - <authorinitials>mhs</authorinitials> - <revremark>VIDIOC_ENUM_FRAMESIZES and -VIDIOC_ENUM_FRAMEINTERVALS are now part of the API.</revremark> - </revision> - - <revision> - <revnumber>0.15</revnumber> - <date>2006-09-23</date> - <authorinitials>mhs</authorinitials> - <revremark>Cleaned up the bibliography, added BT.653 and -BT.1119. capture.c/start_capturing() for user pointer I/O did not -initialize the buffer index. Documented the V4L MPEG and MJPEG -VID_TYPEs and V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel -formats. See the history chapter for API changes.</revremark> - </revision> - - <revision> - <revnumber>0.14</revnumber> - <date>2006-09-14</date> - <authorinitials>mr</authorinitials> - <revremark>Added VIDIOC_ENUM_FRAMESIZES and -VIDIOC_ENUM_FRAMEINTERVALS proposal for frame format enumeration of -digital devices.</revremark> - </revision> - - <revision> - <revnumber>0.13</revnumber> - <date>2006-04-07</date> - <authorinitials>mhs</authorinitials> - <revremark>Corrected the description of struct v4l2_window -clips. New V4L2_STD_ and V4L2_TUNER_MODE_LANG1_LANG2 -defines.</revremark> - </revision> - - <revision> - <revnumber>0.12</revnumber> - <date>2006-02-03</date> - <authorinitials>mhs</authorinitials> - <revremark>Corrected the description of struct -v4l2_captureparm and v4l2_outputparm.</revremark> - </revision> - - <revision> - <revnumber>0.11</revnumber> - <date>2006-01-27</date> - <authorinitials>mhs</authorinitials> - <revremark>Improved the description of struct -v4l2_tuner.</revremark> - </revision> - - <revision> - <revnumber>0.10</revnumber> - <date>2006-01-10</date> - <authorinitials>mhs</authorinitials> - <revremark>VIDIOC_G_INPUT and VIDIOC_S_PARM -clarifications.</revremark> - </revision> - - <revision> - <revnumber>0.9</revnumber> - <date>2005-11-27</date> - <authorinitials>mhs</authorinitials> - <revremark>Improved the 525 line numbering diagram. Hans -Verkuil and I rewrote the sliced VBI section. He also contributed a -VIDIOC_LOG_STATUS page. Fixed VIDIOC_S_STD call in the video standard -selection example. Various updates.</revremark> - </revision> - - <revision> - <revnumber>0.8</revnumber> - <date>2004-10-04</date> - <authorinitials>mhs</authorinitials> - <revremark>Somehow a piece of junk slipped into the capture -example, removed.</revremark> - </revision> - - <revision> - <revnumber>0.7</revnumber> - <date>2004-09-19</date> - <authorinitials>mhs</authorinitials> - <revremark>Fixed video standard selection, control -enumeration, downscaling and aspect example. Added read and user -pointer i/o to video capture example.</revremark> - </revision> - - <revision> - <revnumber>0.6</revnumber> - <date>2004-08-01</date> - <authorinitials>mhs</authorinitials> - <revremark>v4l2_buffer changes, added video capture example, -various corrections.</revremark> - </revision> - - <revision> - <revnumber>0.5</revnumber> - <date>2003-11-05</date> - <authorinitials>mhs</authorinitials> - <revremark>Pixel format erratum.</revremark> - </revision> - - <revision> - <revnumber>0.4</revnumber> - <date>2003-09-17</date> - <authorinitials>mhs</authorinitials> - <revremark>Corrected source and Makefile to generate a PDF. -SGML fixes. Added latest API changes. Closed gaps in the history -chapter.</revremark> - </revision> - - <revision> - <revnumber>0.3</revnumber> - <date>2003-02-05</date> - <authorinitials>mhs</authorinitials> - <revremark>Another draft, more corrections.</revremark> - </revision> - - <revision> - <revnumber>0.2</revnumber> - <date>2003-01-15</date> - <authorinitials>mhs</authorinitials> - <revremark>Second draft, with corrections pointed out by Gerd -Knorr.</revremark> - </revision> - - <revision> - <revnumber>0.1</revnumber> - <date>2002-12-01</date> - <authorinitials>mhs</authorinitials> - <revremark>First draft, based on documentation by Bill Dirks -and discussions on the V4L mailing list.</revremark> - </revision> - </revhistory> -</partinfo> - -<title>Video for Linux Two API Specification</title> - <subtitle>Revision 4.4</subtitle> - - <chapter id="common"> - &sub-common; - </chapter> - - <chapter id="pixfmt"> - &sub-pixfmt; - </chapter> - - <chapter id="io"> - &sub-io; - </chapter> - - <chapter id="devices"> - <title>Interfaces</title> - - <section id="capture"> &sub-dev-capture; </section> - <section id="overlay"> &sub-dev-overlay; </section> - <section id="output"> &sub-dev-output; </section> - <section id="osd"> &sub-dev-osd; </section> - <section id="codec"> &sub-dev-codec; </section> - <section id="effect"> &sub-dev-effect; </section> - <section id="raw-vbi"> &sub-dev-raw-vbi; </section> - <section id="sliced"> &sub-dev-sliced-vbi; </section> - <section id="ttx"> &sub-dev-teletext; </section> - <section id="radio"> &sub-dev-radio; </section> - <section id="rds"> &sub-dev-rds; </section> - <section id="sdr"> &sub-dev-sdr; </section> - <section id="event"> &sub-dev-event; </section> - <section id="subdev"> &sub-dev-subdev; </section> - </chapter> - - <chapter id="driver"> - &sub-driver; - </chapter> - - <chapter id="libv4l"> - &sub-libv4l; - </chapter> - - <chapter id="compat"> - &sub-compat; - </chapter> - - <appendix id="user-func"> - <title>Function Reference</title> - - <!-- Keep this alphabetically sorted. --> - - &sub-close; - &sub-ioctl; - <!-- All ioctls go here. --> - &sub-create-bufs; - &sub-cropcap; - &sub-dbg-g-chip-info; - &sub-dbg-g-register; - &sub-decoder-cmd; - &sub-dqevent; - &sub-dv-timings-cap; - &sub-encoder-cmd; - &sub-enumaudio; - &sub-enumaudioout; - &sub-enum-dv-timings; - &sub-enum-fmt; - &sub-enum-framesizes; - &sub-enum-frameintervals; - &sub-enum-freq-bands; - &sub-enuminput; - &sub-enumoutput; - &sub-enumstd; - &sub-expbuf; - &sub-g-audio; - &sub-g-audioout; - &sub-g-crop; - &sub-g-ctrl; - &sub-g-dv-timings; - &sub-g-edid; - &sub-g-enc-index; - &sub-g-ext-ctrls; - &sub-g-fbuf; - &sub-g-fmt; - &sub-g-frequency; - &sub-g-input; - &sub-g-jpegcomp; - &sub-g-modulator; - &sub-g-output; - &sub-g-parm; - &sub-g-priority; - &sub-g-selection; - &sub-g-sliced-vbi-cap; - &sub-g-std; - &sub-g-tuner; - &sub-log-status; - &sub-overlay; - &sub-prepare-buf; - &sub-qbuf; - &sub-querybuf; - &sub-querycap; - &sub-queryctrl; - &sub-query-dv-timings; - &sub-querystd; - &sub-reqbufs; - &sub-s-hw-freq-seek; - &sub-streamon; - &sub-subdev-enum-frame-interval; - &sub-subdev-enum-frame-size; - &sub-subdev-enum-mbus-code; - &sub-subdev-g-crop; - &sub-subdev-g-fmt; - &sub-subdev-g-frame-interval; - &sub-subdev-g-selection; - &sub-subscribe-event; - <!-- End of ioctls. --> - &sub-mmap; - &sub-munmap; - &sub-open; - &sub-poll; - &sub-read; - &sub-select; - &sub-write; - </appendix> - - <appendix> - <title>Common definitions for V4L2 and V4L2 subdev interfaces</title> - &sub-selections-common; - </appendix> - - <appendix id="videodev"> - <title>Video For Linux Two Header File</title> - &sub-videodev2-h; - </appendix> - - <appendix id="capture-example"> - <title>Video Capture Example</title> - &sub-capture-c; - </appendix> - - <appendix id="v4l2grab-example"> - <title>Video Grabber example using libv4l</title> - <para>This program demonstrates how to grab V4L2 images in ppm format by -using libv4l handlers. The advantage is that this grabber can potentially work -with any V4L2 driver.</para> - &sub-v4l2grab-c; - </appendix> - - &sub-media-indices; - - &sub-biblio; - diff --git a/Documentation/DocBook/media/v4l/v4l2grab.c.xml b/Documentation/DocBook/media/v4l/v4l2grab.c.xml deleted file mode 100644 index bed12e40be27..000000000000 --- a/Documentation/DocBook/media/v4l/v4l2grab.c.xml +++ /dev/null @@ -1,164 +0,0 @@ -<programlisting> -/* V4L2 video picture grabber - Copyright (C) 2009 Mauro Carvalho Chehab <mchehab@infradead.org> - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation version 2 of the License. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - */ - -#include <stdio.h> -#include <stdlib.h> -#include <string.h> -#include <fcntl.h> -#include <errno.h> -#include <sys/ioctl.h> -#include <sys/types.h> -#include <sys/time.h> -#include <sys/mman.h> -#include <linux/videodev2.h> -#include "../libv4l/include/libv4l2.h" - -#define CLEAR(x) memset(&(x), 0, sizeof(x)) - -struct buffer { - void *start; - size_t length; -}; - -static void xioctl(int fh, int request, void *arg) -{ - int r; - - do { - r = v4l2_ioctl(fh, request, arg); - } while (r == -1 && ((errno == EINTR) || (errno == EAGAIN))); - - if (r == -1) { - fprintf(stderr, "error %d, %s\n", errno, strerror(errno)); - exit(EXIT_FAILURE); - } -} - -int main(int argc, char **argv) -{ - struct <link linkend="v4l2-format">v4l2_format</link> fmt; - struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf; - struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> req; - enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; - fd_set fds; - struct timeval tv; - int r, fd = -1; - unsigned int i, n_buffers; - char *dev_name = "/dev/video0"; - char out_name[256]; - FILE *fout; - struct buffer *buffers; - - fd = v4l2_open(dev_name, O_RDWR | O_NONBLOCK, 0); - if (fd < 0) { - perror("Cannot open device"); - exit(EXIT_FAILURE); - } - - CLEAR(fmt); - fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - fmt.fmt.pix.width = 640; - fmt.fmt.pix.height = 480; - fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_RGB24; - fmt.fmt.pix.field = V4L2_FIELD_INTERLACED; - xioctl(fd, VIDIOC_S_FMT, &fmt); - if (fmt.fmt.pix.pixelformat != V4L2_PIX_FMT_RGB24) { - printf("Libv4l didn't accept RGB24 format. Can't proceed.\n"); - exit(EXIT_FAILURE); - } - if ((fmt.fmt.pix.width != 640) || (fmt.fmt.pix.height != 480)) - printf("Warning: driver is sending image at %dx%d\n", - fmt.fmt.pix.width, fmt.fmt.pix.height); - - CLEAR(req); - req.count = 2; - req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - req.memory = V4L2_MEMORY_MMAP; - xioctl(fd, VIDIOC_REQBUFS, &req); - - buffers = calloc(req.count, sizeof(*buffers)); - for (n_buffers = 0; n_buffers < req.count; ++n_buffers) { - CLEAR(buf); - - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - buf.memory = V4L2_MEMORY_MMAP; - buf.index = n_buffers; - - xioctl(fd, VIDIOC_QUERYBUF, &buf); - - buffers[n_buffers].length = buf.length; - buffers[n_buffers].start = v4l2_mmap(NULL, buf.length, - PROT_READ | PROT_WRITE, MAP_SHARED, - fd, buf.m.offset); - - if (MAP_FAILED == buffers[n_buffers].start) { - perror("mmap"); - exit(EXIT_FAILURE); - } - } - - for (i = 0; i < n_buffers; ++i) { - CLEAR(buf); - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - buf.memory = V4L2_MEMORY_MMAP; - buf.index = i; - xioctl(fd, VIDIOC_QBUF, &buf); - } - type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - - xioctl(fd, VIDIOC_STREAMON, &type); - for (i = 0; i < 20; i++) { - do { - FD_ZERO(&fds); - FD_SET(fd, &fds); - - /* Timeout. */ - tv.tv_sec = 2; - tv.tv_usec = 0; - - r = select(fd + 1, &fds, NULL, NULL, &tv); - } while ((r == -1 && (errno = EINTR))); - if (r == -1) { - perror("select"); - return errno; - } - - CLEAR(buf); - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - buf.memory = V4L2_MEMORY_MMAP; - xioctl(fd, VIDIOC_DQBUF, &buf); - - sprintf(out_name, "out%03d.ppm", i); - fout = fopen(out_name, "w"); - if (!fout) { - perror("Cannot open image"); - exit(EXIT_FAILURE); - } - fprintf(fout, "P6\n%d %d 255\n", - fmt.fmt.pix.width, fmt.fmt.pix.height); - fwrite(buffers[buf.index].start, buf.bytesused, 1, fout); - fclose(fout); - - xioctl(fd, VIDIOC_QBUF, &buf); - } - - type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - xioctl(fd, VIDIOC_STREAMOFF, &type); - for (i = 0; i < n_buffers; ++i) - v4l2_munmap(buffers[i].start, buffers[i].length); - v4l2_close(fd); - - return 0; -} -</programlisting> diff --git a/Documentation/DocBook/media/v4l/vbi_525.pdf b/Documentation/DocBook/media/v4l/vbi_525.pdf Binary files differdeleted file mode 100644 index 9e72c25b208d..000000000000 --- a/Documentation/DocBook/media/v4l/vbi_525.pdf +++ /dev/null diff --git a/Documentation/DocBook/media/v4l/vbi_625.pdf b/Documentation/DocBook/media/v4l/vbi_625.pdf Binary files differdeleted file mode 100644 index 765235e33a4d..000000000000 --- a/Documentation/DocBook/media/v4l/vbi_625.pdf +++ /dev/null diff --git a/Documentation/DocBook/media/v4l/vbi_hsync.pdf b/Documentation/DocBook/media/v4l/vbi_hsync.pdf Binary files differdeleted file mode 100644 index 200b668189bf..000000000000 --- a/Documentation/DocBook/media/v4l/vbi_hsync.pdf +++ /dev/null diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml deleted file mode 100644 index d81fa0d4016b..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml +++ /dev/null @@ -1,164 +0,0 @@ -<refentry id="vidioc-create-bufs"> - <refmeta> - <refentrytitle>ioctl VIDIOC_CREATE_BUFS</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_CREATE_BUFS</refname> - <refpurpose>Create buffers for Memory Mapped or User Pointer or DMA Buffer - I/O</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_create_buffers *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_CREATE_BUFS</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <note> - <title>Experimental</title> - <para>This is an <link linkend="experimental"> experimental </link> - interface and may change in the future.</para> - </note> - - <para>This ioctl is used to create buffers for <link linkend="mmap">memory -mapped</link> or <link linkend="userp">user pointer</link> or <link -linkend="dmabuf">DMA buffer</link> I/O. It can be used as an alternative or in -addition to the &VIDIOC-REQBUFS; ioctl, when a tighter -control over buffers is required. This ioctl can be called multiple times to -create buffers of different sizes.</para> - - <para>To allocate the device buffers applications must initialize the -relevant fields of the <structname>v4l2_create_buffers</structname> structure. -The <structfield>count</structfield> field must be set to the number of -requested buffers, the <structfield>memory</structfield> field specifies the -requested I/O method and the <structfield>reserved</structfield> array must be -zeroed.</para> - - <para>The <structfield>format</structfield> field specifies the image format -that the buffers must be able to handle. The application has to fill in this -&v4l2-format;. Usually this will be done using the &VIDIOC-TRY-FMT; or &VIDIOC-G-FMT; ioctls -to ensure that the requested format is supported by the driver. -Based on the format's <structfield>type</structfield> field the requested buffer -size (for single-planar) or plane sizes (for multi-planar formats) will be -used for the allocated buffers. The driver may return an error if the size(s) -are not supported by the hardware (usually because they are too small).</para> - - <para>The buffers created by this ioctl will have as minimum size the size -defined by the <structfield>format.pix.sizeimage</structfield> field (or the -corresponding fields for other format types). Usually if the -<structfield>format.pix.sizeimage</structfield> field is less than the minimum -required for the given format, then an error will be returned since drivers will -typically not allow this. If it is larger, then the value will be used as-is. -In other words, the driver may reject the requested size, but if it is accepted -the driver will use it unchanged.</para> - - <para>When the ioctl is called with a pointer to this structure the driver -will attempt to allocate up to the requested number of buffers and store the -actual number allocated and the starting index in the -<structfield>count</structfield> and the <structfield>index</structfield> fields -respectively. On return <structfield>count</structfield> can be smaller than -the number requested.</para> - - <table pgwide="1" frame="none" id="v4l2-create-buffers"> - <title>struct <structname>v4l2_create_buffers</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>index</structfield></entry> - <entry>The starting buffer index, returned by the driver.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>count</structfield></entry> - <entry>The number of buffers requested or granted. If count == 0, then - <constant>VIDIOC_CREATE_BUFS</constant> will set <structfield>index</structfield> - to the current number of created buffers, and it will check the validity of - <structfield>memory</structfield> and <structfield>format.type</structfield>. - If those are invalid -1 is returned and errno is set to &EINVAL;, - otherwise <constant>VIDIOC_CREATE_BUFS</constant> returns 0. It will - never set errno to &EBUSY; in this particular case.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>memory</structfield></entry> - <entry>Applications set this field to -<constant>V4L2_MEMORY_MMAP</constant>, -<constant>V4L2_MEMORY_DMABUF</constant> or -<constant>V4L2_MEMORY_USERPTR</constant>. See <xref linkend="v4l2-memory" -/></entry> - </row> - <row> - <entry>&v4l2-format;</entry> - <entry><structfield>format</structfield></entry> - <entry>Filled in by the application, preserved by the driver.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[8]</entry> - <entry>A place holder for future extensions. Drivers and applications -must set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>ENOMEM</errorcode></term> - <listitem> - <para>No memory to allocate buffers for <link linkend="mmap">memory -mapped</link> I/O.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The buffer type (<structfield>format.type</structfield> field), -requested I/O method (<structfield>memory</structfield>) or format -(<structfield>format</structfield> field) is not valid.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-cropcap.xml b/Documentation/DocBook/media/v4l/vidioc-cropcap.xml deleted file mode 100644 index 50cb940cbe5c..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-cropcap.xml +++ /dev/null @@ -1,166 +0,0 @@ -<refentry id="vidioc-cropcap"> - <refmeta> - <refentrytitle>ioctl VIDIOC_CROPCAP</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_CROPCAP</refname> - <refpurpose>Information about the video cropping and scaling abilities</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_cropcap -*<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_CROPCAP</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>Applications use this function to query the cropping -limits, the pixel aspect of images and to calculate scale factors. -They set the <structfield>type</structfield> field of a v4l2_cropcap -structure to the respective buffer (stream) type and call the -<constant>VIDIOC_CROPCAP</constant> ioctl with a pointer to this -structure. Drivers fill the rest of the structure. The results are -constant except when switching the video standard. Remember this -switch can occur implicit when switching the video input or -output.</para> - -<para>Do not use the multiplanar buffer types. Use <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> -instead of <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant> -and use <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> instead of -<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>.</para> - - <para>This ioctl must be implemented for video capture or output devices that -support cropping and/or scaling and/or have non-square pixels, and for overlay devices.</para> - - <table pgwide="1" frame="none" id="v4l2-cropcap"> - <title>struct <structname>v4l2_cropcap</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry>Type of the data stream, set by the application. -Only these types are valid here: -<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>, -<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> and -<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>. See <xref linkend="v4l2-buf-type" />.</entry> - </row> - <row> - <entry>struct <link linkend="v4l2-rect-crop">v4l2_rect</link></entry> - <entry><structfield>bounds</structfield></entry> - <entry>Defines the window within capturing or output is -possible, this may exclude for example the horizontal and vertical -blanking areas. The cropping rectangle cannot exceed these limits. -Width and height are defined in pixels, the driver writer is free to -choose origin and units of the coordinate system in the analog -domain.</entry> - </row> - <row> - <entry>struct <link linkend="v4l2-rect-crop">v4l2_rect</link></entry> - <entry><structfield>defrect</structfield></entry> - <entry>Default cropping rectangle, it shall cover the -"whole picture". Assuming pixel aspect 1/1 this could be for example a -640 × 480 rectangle for NTSC, a -768 × 576 rectangle for PAL and SECAM centered over -the active picture area. The same co-ordinate system as for - <structfield>bounds</structfield> is used.</entry> - </row> - <row> - <entry>&v4l2-fract;</entry> - <entry><structfield>pixelaspect</structfield></entry> - <entry><para>This is the pixel aspect (y / x) when no -scaling is applied, the ratio of the actual sampling -frequency and the frequency required to get square -pixels.</para><para>When cropping coordinates refer to square pixels, -the driver sets <structfield>pixelaspect</structfield> to 1/1. Other -common values are 54/59 for PAL and SECAM, 11/10 for NTSC sampled -according to [<xref linkend="itu601" />].</para></entry> - </row> - </tbody> - </tgroup> - </table> - - <!-- NB this table is duplicated in the overlay chapter. --> - - <table pgwide="1" frame="none" id="v4l2-rect-crop"> - <title>struct <structname>v4l2_rect</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__s32</entry> - <entry><structfield>left</structfield></entry> - <entry>Horizontal offset of the top, left corner of the -rectangle, in pixels.</entry> - </row> - <row> - <entry>__s32</entry> - <entry><structfield>top</structfield></entry> - <entry>Vertical offset of the top, left corner of the -rectangle, in pixels.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>width</structfield></entry> - <entry>Width of the rectangle, in pixels.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>height</structfield></entry> - <entry>Height of the rectangle, in pixels.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The &v4l2-cropcap; <structfield>type</structfield> is -invalid.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml b/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml deleted file mode 100644 index f14a3bb1afaa..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml +++ /dev/null @@ -1,207 +0,0 @@ -<refentry id="vidioc-dbg-g-chip-info"> - <refmeta> - <refentrytitle>ioctl VIDIOC_DBG_G_CHIP_INFO</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_DBG_G_CHIP_INFO</refname> - <refpurpose>Identify the chips on a TV card</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_dbg_chip_info -*<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_DBG_G_CHIP_INFO</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <note> - <title>Experimental</title> - - <para>This is an <link -linkend="experimental">experimental</link> interface and may change in -the future.</para> - </note> - - <para>For driver debugging purposes this ioctl allows test -applications to query the driver about the chips present on the TV -card. Regular applications must not use it. When you found a chip -specific bug, please contact the linux-media mailing list (&v4l-ml;) -so it can be fixed.</para> - - <para>Additionally the Linux kernel must be compiled with the -<constant>CONFIG_VIDEO_ADV_DEBUG</constant> option to enable this ioctl.</para> - - <para>To query the driver applications must initialize the -<structfield>match.type</structfield> and -<structfield>match.addr</structfield> or <structfield>match.name</structfield> -fields of a &v4l2-dbg-chip-info; -and call <constant>VIDIOC_DBG_G_CHIP_INFO</constant> with a pointer to -this structure. On success the driver stores information about the -selected chip in the <structfield>name</structfield> and -<structfield>flags</structfield> fields.</para> - - <para>When <structfield>match.type</structfield> is -<constant>V4L2_CHIP_MATCH_BRIDGE</constant>, -<structfield>match.addr</structfield> selects the nth bridge 'chip' -on the TV card. You can enumerate all chips by starting at zero and -incrementing <structfield>match.addr</structfield> by one until -<constant>VIDIOC_DBG_G_CHIP_INFO</constant> fails with an &EINVAL;. -The number zero always selects the bridge chip itself, ⪚ the chip -connected to the PCI or USB bus. Non-zero numbers identify specific -parts of the bridge chip such as an AC97 register block.</para> - - <para>When <structfield>match.type</structfield> is -<constant>V4L2_CHIP_MATCH_SUBDEV</constant>, -<structfield>match.addr</structfield> selects the nth sub-device. This -allows you to enumerate over all sub-devices.</para> - - <para>On success, the <structfield>name</structfield> field will -contain a chip name and the <structfield>flags</structfield> field will -contain <constant>V4L2_CHIP_FL_READABLE</constant> if the driver supports -reading registers from the device or <constant>V4L2_CHIP_FL_WRITABLE</constant> -if the driver supports writing registers to the device.</para> - - <para>We recommended the <application>v4l2-dbg</application> -utility over calling this ioctl directly. It is available from the -LinuxTV v4l-dvb repository; see <ulink -url="https://linuxtv.org/repo/">https://linuxtv.org/repo/</ulink> for -access instructions.</para> - - <!-- Note for convenience vidioc-dbg-g-register.sgml - contains a duplicate of this table. --> - <table pgwide="1" frame="none" id="name-v4l2-dbg-match"> - <title>struct <structname>v4l2_dbg_match</structname></title> - <tgroup cols="4"> - &cs-ustr; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry>See <xref linkend="name-chip-match-types" /> for a list of -possible types.</entry> - </row> - <row> - <entry>union</entry> - <entry>(anonymous)</entry> - </row> - <row> - <entry></entry> - <entry>__u32</entry> - <entry><structfield>addr</structfield></entry> - <entry>Match a chip by this number, interpreted according -to the <structfield>type</structfield> field.</entry> - </row> - <row> - <entry></entry> - <entry>char</entry> - <entry><structfield>name[32]</structfield></entry> - <entry>Match a chip by this name, interpreted according -to the <structfield>type</structfield> field. Currently unused.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="v4l2-dbg-chip-info"> - <title>struct <structname>v4l2_dbg_chip_info</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>struct v4l2_dbg_match</entry> - <entry><structfield>match</structfield></entry> - <entry>How to match the chip, see <xref linkend="name-v4l2-dbg-match" />.</entry> - </row> - <row> - <entry>char</entry> - <entry><structfield>name[32]</structfield></entry> - <entry>The name of the chip.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry>Set by the driver. If <constant>V4L2_CHIP_FL_READABLE</constant> -is set, then the driver supports reading registers from the device. If -<constant>V4L2_CHIP_FL_WRITABLE</constant> is set, then it supports writing registers.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved[8]</structfield></entry> - <entry>Reserved fields, both application and driver must set these to 0.</entry> - </row> - </tbody> - </tgroup> - </table> - - <!-- Note for convenience vidioc-dbg-g-register.sgml - contains a duplicate of this table. --> - <table pgwide="1" frame="none" id="name-chip-match-types"> - <title>Chip Match Types</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_CHIP_MATCH_BRIDGE</constant></entry> - <entry>0</entry> - <entry>Match the nth chip on the card, zero for the - bridge chip. Does not match sub-devices.</entry> - </row> - <row> - <entry><constant>V4L2_CHIP_MATCH_SUBDEV</constant></entry> - <entry>4</entry> - <entry>Match the nth sub-device.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The <structfield>match_type</structfield> is invalid or -no device could be matched.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml b/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml deleted file mode 100644 index 5877f68a5820..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml +++ /dev/null @@ -1,227 +0,0 @@ -<refentry id="vidioc-dbg-g-register"> - <refmeta> - <refentrytitle>ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_DBG_G_REGISTER</refname> - <refname>VIDIOC_DBG_S_REGISTER</refname> - <refpurpose>Read or write hardware registers</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_dbg_register *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>const struct v4l2_dbg_register -*<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <note> - <title>Experimental</title> - - <para>This is an <link linkend="experimental">experimental</link> -interface and may change in the future.</para> - </note> - - <para>For driver debugging purposes these ioctls allow test -applications to access hardware registers directly. Regular -applications must not use them.</para> - - <para>Since writing or even reading registers can jeopardize the -system security, its stability and damage the hardware, both ioctls -require superuser privileges. Additionally the Linux kernel must be -compiled with the <constant>CONFIG_VIDEO_ADV_DEBUG</constant> option -to enable these ioctls.</para> - - <para>To write a register applications must initialize all fields -of a &v4l2-dbg-register; except for <structfield>size</structfield> and call -<constant>VIDIOC_DBG_S_REGISTER</constant> with a pointer to this -structure. The <structfield>match.type</structfield> and -<structfield>match.addr</structfield> or <structfield>match.name</structfield> -fields select a chip on the TV -card, the <structfield>reg</structfield> field specifies a register -number and the <structfield>val</structfield> field the value to be -written into the register.</para> - - <para>To read a register applications must initialize the -<structfield>match.type</structfield>, -<structfield>match.addr</structfield> or <structfield>match.name</structfield> and -<structfield>reg</structfield> fields, and call -<constant>VIDIOC_DBG_G_REGISTER</constant> with a pointer to this -structure. On success the driver stores the register value in the -<structfield>val</structfield> field and the size (in bytes) of the -value in <structfield>size</structfield>.</para> - - <para>When <structfield>match.type</structfield> is -<constant>V4L2_CHIP_MATCH_BRIDGE</constant>, -<structfield>match.addr</structfield> selects the nth non-sub-device chip -on the TV card. The number zero always selects the host chip, ⪚ the -chip connected to the PCI or USB bus. You can find out which chips are -present with the &VIDIOC-DBG-G-CHIP-INFO; ioctl.</para> - - <para>When <structfield>match.type</structfield> is -<constant>V4L2_CHIP_MATCH_SUBDEV</constant>, -<structfield>match.addr</structfield> selects the nth sub-device.</para> - - <para>These ioctls are optional, not all drivers may support them. -However when a driver supports these ioctls it must also support -&VIDIOC-DBG-G-CHIP-INFO;. Conversely it may support -<constant>VIDIOC_DBG_G_CHIP_INFO</constant> but not these ioctls.</para> - - <para><constant>VIDIOC_DBG_G_REGISTER</constant> and -<constant>VIDIOC_DBG_S_REGISTER</constant> were introduced in Linux -2.6.21, but their API was changed to the one described here in kernel 2.6.29.</para> - - <para>We recommended the <application>v4l2-dbg</application> -utility over calling these ioctls directly. It is available from the -LinuxTV v4l-dvb repository; see <ulink -url="https://linuxtv.org/repo/">https://linuxtv.org/repo/</ulink> for -access instructions.</para> - - <!-- Note for convenience vidioc-dbg-g-chip-info.sgml - contains a duplicate of this table. --> - <table pgwide="1" frame="none" id="v4l2-dbg-match"> - <title>struct <structname>v4l2_dbg_match</structname></title> - <tgroup cols="4"> - &cs-ustr; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry>See <xref linkend="chip-match-types" /> for a list of -possible types.</entry> - </row> - <row> - <entry>union</entry> - <entry>(anonymous)</entry> - </row> - <row> - <entry></entry> - <entry>__u32</entry> - <entry><structfield>addr</structfield></entry> - <entry>Match a chip by this number, interpreted according -to the <structfield>type</structfield> field.</entry> - </row> - <row> - <entry></entry> - <entry>char</entry> - <entry><structfield>name[32]</structfield></entry> - <entry>Match a chip by this name, interpreted according -to the <structfield>type</structfield> field. Currently unused.</entry> - </row> - </tbody> - </tgroup> - </table> - - - <table pgwide="1" frame="none" id="v4l2-dbg-register"> - <title>struct <structname>v4l2_dbg_register</structname></title> - <tgroup cols="4"> - <colspec colname="c1" /> - <colspec colname="c2" /> - <colspec colname="c4" /> - <tbody valign="top"> - <row> - <entry>struct v4l2_dbg_match</entry> - <entry><structfield>match</structfield></entry> - <entry>How to match the chip, see <xref linkend="v4l2-dbg-match" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>size</structfield></entry> - <entry>The register size in bytes.</entry> - </row> - <row> - <entry>__u64</entry> - <entry><structfield>reg</structfield></entry> - <entry>A register number.</entry> - </row> - <row> - <entry>__u64</entry> - <entry><structfield>val</structfield></entry> - <entry>The value read from, or to be written into the -register.</entry> - </row> - </tbody> - </tgroup> - </table> - - <!-- Note for convenience vidioc-dbg-g-chip-info.sgml - contains a duplicate of this table. --> - <table pgwide="1" frame="none" id="chip-match-types"> - <title>Chip Match Types</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_CHIP_MATCH_BRIDGE</constant></entry> - <entry>0</entry> - <entry>Match the nth chip on the card, zero for the - bridge chip. Does not match sub-devices.</entry> - </row> - <row> - <entry><constant>V4L2_CHIP_MATCH_SUBDEV</constant></entry> - <entry>4</entry> - <entry>Match the nth sub-device.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EPERM</errorcode></term> - <listitem> - <para>Insufficient permissions. Root privileges are required -to execute these ioctls.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml b/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml deleted file mode 100644 index 73eb5cfe698a..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml +++ /dev/null @@ -1,259 +0,0 @@ -<refentry id="vidioc-decoder-cmd"> - <refmeta> - <refentrytitle>ioctl VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_DECODER_CMD</refname> - <refname>VIDIOC_TRY_DECODER_CMD</refname> - <refpurpose>Execute an decoder command</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_decoder_cmd *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>These ioctls control an audio/video (usually MPEG-) decoder. -<constant>VIDIOC_DECODER_CMD</constant> sends a command to the -decoder, <constant>VIDIOC_TRY_DECODER_CMD</constant> can be used to -try a command without actually executing it. To send a command applications -must initialize all fields of a &v4l2-decoder-cmd; and call -<constant>VIDIOC_DECODER_CMD</constant> or <constant>VIDIOC_TRY_DECODER_CMD</constant> -with a pointer to this structure.</para> - - <para>The <structfield>cmd</structfield> field must contain the -command code. Some commands use the <structfield>flags</structfield> field for -additional information. -</para> - - <para>A <function>write</function>() or &VIDIOC-STREAMON; call sends an implicit -START command to the decoder if it has not been started yet. -</para> - - <para>A <function>close</function>() or &VIDIOC-STREAMOFF; call of a streaming -file descriptor sends an implicit immediate STOP command to the decoder, and all -buffered data is discarded.</para> - - <para>These ioctls are optional, not all drivers may support -them. They were introduced in Linux 3.3.</para> - - <table pgwide="1" frame="none" id="v4l2-decoder-cmd"> - <title>struct <structname>v4l2_decoder_cmd</structname></title> - <tgroup cols="5"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>cmd</structfield></entry> - <entry></entry> - <entry></entry> - <entry>The decoder command, see <xref linkend="decoder-cmds" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry></entry> - <entry></entry> - <entry>Flags to go with the command. If no flags are defined for -this command, drivers and applications must set this field to zero.</entry> - </row> - <row> - <entry>union</entry> - <entry>(anonymous)</entry> - <entry></entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry></entry> - <entry>struct</entry> - <entry><structfield>start</structfield></entry> - <entry></entry> - <entry>Structure containing additional data for the -<constant>V4L2_DEC_CMD_START</constant> command.</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>__s32</entry> - <entry><structfield>speed</structfield></entry> - <entry>Playback speed and direction. The playback speed is defined as -<structfield>speed</structfield>/1000 of the normal speed. So 1000 is normal playback. -Negative numbers denote reverse playback, so -1000 does reverse playback at normal -speed. Speeds -1, 0 and 1 have special meanings: speed 0 is shorthand for 1000 -(normal playback). A speed of 1 steps just one frame forward, a speed of -1 steps -just one frame back. - </entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>__u32</entry> - <entry><structfield>format</structfield></entry> - <entry>Format restrictions. This field is set by the driver, not the -application. Possible values are <constant>V4L2_DEC_START_FMT_NONE</constant> if -there are no format restrictions or <constant>V4L2_DEC_START_FMT_GOP</constant> -if the decoder operates on full GOPs (<wordasword>Group Of Pictures</wordasword>). -This is usually the case for reverse playback: the decoder needs full GOPs, which -it can then play in reverse order. So to implement reverse playback the application -must feed the decoder the last GOP in the video file, then the GOP before that, etc. etc. - </entry> - </row> - <row> - <entry></entry> - <entry>struct</entry> - <entry><structfield>stop</structfield></entry> - <entry></entry> - <entry>Structure containing additional data for the -<constant>V4L2_DEC_CMD_STOP</constant> command.</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>__u64</entry> - <entry><structfield>pts</structfield></entry> - <entry>Stop playback at this <structfield>pts</structfield> or immediately -if the playback is already past that timestamp. Leave to 0 if you want to stop after the -last frame was decoded. - </entry> - </row> - <row> - <entry></entry> - <entry>struct</entry> - <entry><structfield>raw</structfield></entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>__u32</entry> - <entry><structfield>data</structfield>[16]</entry> - <entry>Reserved for future extensions. Drivers and -applications must set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="decoder-cmds"> - <title>Decoder Commands</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_DEC_CMD_START</constant></entry> - <entry>0</entry> - <entry>Start the decoder. When the decoder is already -running or paused, this command will just change the playback speed. -That means that calling <constant>V4L2_DEC_CMD_START</constant> when -the decoder was paused will <emphasis>not</emphasis> resume the decoder. -You have to explicitly call <constant>V4L2_DEC_CMD_RESUME</constant> for that. -This command has one flag: -<constant>V4L2_DEC_CMD_START_MUTE_AUDIO</constant>. If set, then audio will -be muted when playing back at a non-standard speed. - </entry> - </row> - <row> - <entry><constant>V4L2_DEC_CMD_STOP</constant></entry> - <entry>1</entry> - <entry>Stop the decoder. When the decoder is already stopped, -this command does nothing. This command has two flags: -if <constant>V4L2_DEC_CMD_STOP_TO_BLACK</constant> is set, then the decoder will -set the picture to black after it stopped decoding. Otherwise the last image will -repeat. mem2mem decoders will stop producing new frames altogether. They will send -a <constant>V4L2_EVENT_EOS</constant> event when the last frame has been decoded -and all frames are ready to be dequeued and will set the -<constant>V4L2_BUF_FLAG_LAST</constant> buffer flag on the last buffer of the -capture queue to indicate there will be no new buffers produced to dequeue. This -buffer may be empty, indicated by the driver setting the -<structfield>bytesused</structfield> field to 0. Once the -<constant>V4L2_BUF_FLAG_LAST</constant> flag was set, the -<link linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl will not block anymore, -but return an &EPIPE;. -If <constant>V4L2_DEC_CMD_STOP_IMMEDIATELY</constant> is set, then the decoder -stops immediately (ignoring the <structfield>pts</structfield> value), otherwise it -will keep decoding until timestamp >= pts or until the last of the pending data from -its internal buffers was decoded. -</entry> - </row> - <row> - <entry><constant>V4L2_DEC_CMD_PAUSE</constant></entry> - <entry>2</entry> - <entry>Pause the decoder. When the decoder has not been -started yet, the driver will return an &EPERM;. When the decoder is -already paused, this command does nothing. This command has one flag: -if <constant>V4L2_DEC_CMD_PAUSE_TO_BLACK</constant> is set, then set the -decoder output to black when paused. -</entry> - </row> - <row> - <entry><constant>V4L2_DEC_CMD_RESUME</constant></entry> - <entry>3</entry> - <entry>Resume decoding after a PAUSE command. When the -decoder has not been started yet, the driver will return an &EPERM;. -When the decoder is already running, this command does nothing. No -flags are defined for this command.</entry> - </row> - </tbody> - </tgroup> - </table> - - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The <structfield>cmd</structfield> field is invalid.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EPERM</errorcode></term> - <listitem> - <para>The application sent a PAUSE or RESUME command when -the decoder was not running.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml deleted file mode 100644 index c9c3c7713832..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml +++ /dev/null @@ -1,471 +0,0 @@ -<refentry id="vidioc-dqevent"> - <refmeta> - <refentrytitle>ioctl VIDIOC_DQEVENT</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_DQEVENT</refname> - <refpurpose>Dequeue event</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_event -*<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_DQEVENT</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>Dequeue an event from a video device. No input is required - for this ioctl. All the fields of the &v4l2-event; structure are - filled by the driver. The file handle will also receive exceptions - which the application may get by e.g. using the select system - call.</para> - - <table frame="none" pgwide="1" id="v4l2-event"> - <title>struct <structname>v4l2_event</structname></title> - <tgroup cols="4"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry></entry> - <entry>Type of the event, see <xref linkend="event-type" />.</entry> - </row> - <row> - <entry>union</entry> - <entry><structfield>u</structfield></entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry></entry> - <entry>&v4l2-event-vsync;</entry> - <entry><structfield>vsync</structfield></entry> - <entry>Event data for event <constant>V4L2_EVENT_VSYNC</constant>. - </entry> - </row> - <row> - <entry></entry> - <entry>&v4l2-event-ctrl;</entry> - <entry><structfield>ctrl</structfield></entry> - <entry>Event data for event <constant>V4L2_EVENT_CTRL</constant>. - </entry> - </row> - <row> - <entry></entry> - <entry>&v4l2-event-frame-sync;</entry> - <entry><structfield>frame_sync</structfield></entry> - <entry>Event data for event - <constant>V4L2_EVENT_FRAME_SYNC</constant>.</entry> - </row> - <row> - <entry></entry> - <entry>&v4l2-event-motion-det;</entry> - <entry><structfield>motion_det</structfield></entry> - <entry>Event data for event V4L2_EVENT_MOTION_DET.</entry> - </row> - <row> - <entry></entry> - <entry>&v4l2-event-src-change;</entry> - <entry><structfield>src_change</structfield></entry> - <entry>Event data for event V4L2_EVENT_SOURCE_CHANGE.</entry> - </row> - <row> - <entry></entry> - <entry>__u8</entry> - <entry><structfield>data</structfield>[64]</entry> - <entry>Event data. Defined by the event type. The union - should be used to define easily accessible type for - events.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>pending</structfield></entry> - <entry></entry> - <entry>Number of pending events excluding this one.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>sequence</structfield></entry> - <entry></entry> - <entry>Event sequence number. The sequence number is - incremented for every subscribed event that takes place. - If sequence numbers are not contiguous it means that - events have been lost. - </entry> - </row> - <row> - <entry>struct timespec</entry> - <entry><structfield>timestamp</structfield></entry> - <entry></entry> - <entry>Event timestamp. The timestamp has been taken from the - <constant>CLOCK_MONOTONIC</constant> clock. To access the - same clock outside V4L2, use <function>clock_gettime(2)</function>. - </entry> - </row> - <row> - <entry>u32</entry> - <entry><structfield>id</structfield></entry> - <entry></entry> - <entry>The ID associated with the event source. If the event does not - have an associated ID (this depends on the event type), then this - is 0.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[8]</entry> - <entry></entry> - <entry>Reserved for future extensions. Drivers must set - the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="event-type"> - <title>Event Types</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_EVENT_ALL</constant></entry> - <entry>0</entry> - <entry>All events. V4L2_EVENT_ALL is valid only for - VIDIOC_UNSUBSCRIBE_EVENT for unsubscribing all events at once. - </entry> - </row> - <row> - <entry><constant>V4L2_EVENT_VSYNC</constant></entry> - <entry>1</entry> - <entry>This event is triggered on the vertical sync. - This event has a &v4l2-event-vsync; associated with it. - </entry> - </row> - <row> - <entry><constant>V4L2_EVENT_EOS</constant></entry> - <entry>2</entry> - <entry>This event is triggered when the end of a stream is reached. - This is typically used with MPEG decoders to report to the application - when the last of the MPEG stream has been decoded. - </entry> - </row> - <row> - <entry><constant>V4L2_EVENT_CTRL</constant></entry> - <entry>3</entry> - <entry><para>This event requires that the <structfield>id</structfield> - matches the control ID from which you want to receive events. - This event is triggered if the control's value changes, if a - button control is pressed or if the control's flags change. - This event has a &v4l2-event-ctrl; associated with it. This struct - contains much of the same information as &v4l2-queryctrl; and - &v4l2-control;.</para> - - <para>If the event is generated due to a call to &VIDIOC-S-CTRL; or - &VIDIOC-S-EXT-CTRLS;, then the event will <emphasis>not</emphasis> be sent to - the file handle that called the ioctl function. This prevents - nasty feedback loops. If you <emphasis>do</emphasis> want to get the - event, then set the <constant>V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK</constant> - flag. - </para> - - <para>This event type will ensure that no information is lost when - more events are raised than there is room internally. In that - case the &v4l2-event-ctrl; of the second-oldest event is kept, - but the <structfield>changes</structfield> field of the - second-oldest event is ORed with the <structfield>changes</structfield> - field of the oldest event.</para> - </entry> - </row> - <row> - <entry><constant>V4L2_EVENT_FRAME_SYNC</constant></entry> - <entry>4</entry> - <entry> - <para>Triggered immediately when the reception of a - frame has begun. This event has a - &v4l2-event-frame-sync; associated with it.</para> - - <para>If the hardware needs to be stopped in the case of a - buffer underrun it might not be able to generate this event. - In such cases the <structfield>frame_sequence</structfield> - field in &v4l2-event-frame-sync; will not be incremented. This - causes two consecutive frame sequence numbers to have n times - frame interval in between them.</para> - </entry> - </row> - <row> - <entry><constant>V4L2_EVENT_SOURCE_CHANGE</constant></entry> - <entry>5</entry> - <entry> - <para>This event is triggered when a source parameter change is - detected during runtime by the video device. It can be a - runtime resolution change triggered by a video decoder or the - format change happening on an input connector. - This event requires that the <structfield>id</structfield> - matches the input index (when used with a video device node) - or the pad index (when used with a subdevice node) from which - you want to receive events.</para> - - <para>This event has a &v4l2-event-src-change; associated - with it. The <structfield>changes</structfield> bitfield denotes - what has changed for the subscribed pad. If multiple events - occurred before application could dequeue them, then the changes - will have the ORed value of all the events generated.</para> - </entry> - </row> - <row> - <entry><constant>V4L2_EVENT_MOTION_DET</constant></entry> - <entry>6</entry> - <entry> - <para>Triggered whenever the motion detection state for one or more of the regions - changes. This event has a &v4l2-event-motion-det; associated with it.</para> - </entry> - </row> - <row> - <entry><constant>V4L2_EVENT_PRIVATE_START</constant></entry> - <entry>0x08000000</entry> - <entry>Base event number for driver-private events.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="v4l2-event-vsync"> - <title>struct <structname>v4l2_event_vsync</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u8</entry> - <entry><structfield>field</structfield></entry> - <entry>The upcoming field. See &v4l2-field;.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="v4l2-event-ctrl"> - <title>struct <structname>v4l2_event_ctrl</structname></title> - <tgroup cols="4"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>changes</structfield></entry> - <entry></entry> - <entry>A bitmask that tells what has changed. See <xref linkend="ctrl-changes-flags" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry></entry> - <entry>The type of the control. See &v4l2-ctrl-type;.</entry> - </row> - <row> - <entry>union (anonymous)</entry> - <entry></entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry></entry> - <entry>__s32</entry> - <entry><structfield>value</structfield></entry> - <entry>The 32-bit value of the control for 32-bit control types. - This is 0 for string controls since the value of a string - cannot be passed using &VIDIOC-DQEVENT;.</entry> - </row> - <row> - <entry></entry> - <entry>__s64</entry> - <entry><structfield>value64</structfield></entry> - <entry>The 64-bit value of the control for 64-bit control types.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry></entry> - <entry>The control flags. See <xref linkend="control-flags" />.</entry> - </row> - <row> - <entry>__s32</entry> - <entry><structfield>minimum</structfield></entry> - <entry></entry> - <entry>The minimum value of the control. See &v4l2-queryctrl;.</entry> - </row> - <row> - <entry>__s32</entry> - <entry><structfield>maximum</structfield></entry> - <entry></entry> - <entry>The maximum value of the control. See &v4l2-queryctrl;.</entry> - </row> - <row> - <entry>__s32</entry> - <entry><structfield>step</structfield></entry> - <entry></entry> - <entry>The step value of the control. See &v4l2-queryctrl;.</entry> - </row> - <row> - <entry>__s32</entry> - <entry><structfield>default_value</structfield></entry> - <entry></entry> - <entry>The default value value of the control. See &v4l2-queryctrl;.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="v4l2-event-frame-sync"> - <title>struct <structname>v4l2_event_frame_sync</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>frame_sequence</structfield></entry> - <entry> - The sequence number of the frame being received. - </entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="v4l2-event-src-change"> - <title>struct <structname>v4l2_event_src_change</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>changes</structfield></entry> - <entry> - A bitmask that tells what has changed. See <xref linkend="src-changes-flags" />. - </entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="v4l2-event-motion-det"> - <title>struct <structname>v4l2_event_motion_det</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry> - Currently only one flag is available: if <constant>V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ</constant> - is set, then the <structfield>frame_sequence</structfield> field is valid, - otherwise that field should be ignored. - </entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>frame_sequence</structfield></entry> - <entry> - The sequence number of the frame being received. Only valid if the - <constant>V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ</constant> flag was set. - </entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>region_mask</structfield></entry> - <entry> - The bitmask of the regions that reported motion. There is at least one - region. If this field is 0, then no motion was detected at all. - If there is no <constant>V4L2_CID_DETECT_MD_REGION_GRID</constant> control - (see <xref linkend="detect-controls" />) to assign a different region - to each cell in the motion detection grid, then that all cells - are automatically assigned to the default region 0. - </entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="ctrl-changes-flags"> - <title>Control Changes</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_EVENT_CTRL_CH_VALUE</constant></entry> - <entry>0x0001</entry> - <entry>This control event was triggered because the value of the control - changed. Special cases: Volatile controls do no generate this event; - If a control has the <constant>V4L2_CTRL_FLAG_EXECUTE_ON_WRITE</constant> - flag set, then this event is sent as well, regardless its value.</entry> - </row> - <row> - <entry><constant>V4L2_EVENT_CTRL_CH_FLAGS</constant></entry> - <entry>0x0002</entry> - <entry>This control event was triggered because the control flags - changed.</entry> - </row> - <row> - <entry><constant>V4L2_EVENT_CTRL_CH_RANGE</constant></entry> - <entry>0x0004</entry> - <entry>This control event was triggered because the minimum, - maximum, step or the default value of the control changed.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="src-changes-flags"> - <title>Source Changes</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_EVENT_SRC_CH_RESOLUTION</constant></entry> - <entry>0x0001</entry> - <entry>This event gets triggered when a resolution change is - detected at an input. This can come from an input connector or - from a video decoder. - </entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - <refsect1> - &return-value; - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml b/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml deleted file mode 100644 index a2017bfcaed2..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml +++ /dev/null @@ -1,214 +0,0 @@ -<refentry id="vidioc-dv-timings-cap"> - <refmeta> - <refentrytitle>ioctl VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_DV_TIMINGS_CAP</refname> - <refname>VIDIOC_SUBDEV_DV_TIMINGS_CAP</refname> - <refpurpose>The capabilities of the Digital Video receiver/transmitter</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_dv_timings_cap *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <note> - <title>Experimental</title> - <para>This is an <link linkend="experimental"> experimental </link> - interface and may change in the future.</para> - </note> - - <para>To query the capabilities of the DV receiver/transmitter applications -can call the <constant>VIDIOC_DV_TIMINGS_CAP</constant> ioctl on a video node -and the driver will fill in the structure. Note that drivers may return -different values after switching the video input or output.</para> - - <para>When implemented by the driver DV capabilities of subdevices can be -queried by calling the <constant>VIDIOC_SUBDEV_DV_TIMINGS_CAP</constant> ioctl -directly on a subdevice node. The capabilities are specific to inputs (for DV -receivers) or outputs (for DV transmitters), applications must specify the -desired pad number in the &v4l2-dv-timings-cap; <structfield>pad</structfield> -field. Attempts to query capabilities on a pad that doesn't support them will -return an &EINVAL;.</para> - - <table pgwide="1" frame="none" id="v4l2-bt-timings-cap"> - <title>struct <structname>v4l2_bt_timings_cap</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>min_width</structfield></entry> - <entry>Minimum width of the active video in pixels.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>max_width</structfield></entry> - <entry>Maximum width of the active video in pixels.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>min_height</structfield></entry> - <entry>Minimum height of the active video in lines.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>max_height</structfield></entry> - <entry>Maximum height of the active video in lines.</entry> - </row> - <row> - <entry>__u64</entry> - <entry><structfield>min_pixelclock</structfield></entry> - <entry>Minimum pixelclock frequency in Hz.</entry> - </row> - <row> - <entry>__u64</entry> - <entry><structfield>max_pixelclock</structfield></entry> - <entry>Maximum pixelclock frequency in Hz.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>standards</structfield></entry> - <entry>The video standard(s) supported by the hardware. - See <xref linkend="dv-bt-standards"/> for a list of standards.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>capabilities</structfield></entry> - <entry>Several flags giving more information about the capabilities. - See <xref linkend="dv-bt-cap-capabilities"/> for a description of the flags. - </entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[16]</entry> - <entry>Reserved for future extensions. Drivers must set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="v4l2-dv-timings-cap"> - <title>struct <structname>v4l2_dv_timings_cap</structname></title> - <tgroup cols="4"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry>Type of DV timings as listed in <xref linkend="dv-timing-types"/>.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>pad</structfield></entry> - <entry>Pad number as reported by the media controller API. This field - is only used when operating on a subdevice node. When operating on a - video node applications must set this field to zero.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[2]</entry> - <entry>Reserved for future extensions. Drivers must set the array to zero.</entry> - </row> - <row> - <entry>union</entry> - <entry><structfield></structfield></entry> - <entry></entry> - </row> - <row> - <entry></entry> - <entry>&v4l2-bt-timings-cap;</entry> - <entry><structfield>bt</structfield></entry> - <entry>BT.656/1120 timings capabilities of the hardware.</entry> - </row> - <row> - <entry></entry> - <entry>__u32</entry> - <entry><structfield>raw_data</structfield>[32]</entry> - <entry></entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="dv-bt-cap-capabilities"> - <title>DV BT Timing capabilities</title> - <tgroup cols="2"> - &cs-str; - <tbody valign="top"> - <row> - <entry>Flag</entry> - <entry>Description</entry> - </row> - <row> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>V4L2_DV_BT_CAP_INTERLACED</entry> - <entry>Interlaced formats are supported. - </entry> - </row> - <row> - <entry>V4L2_DV_BT_CAP_PROGRESSIVE</entry> - <entry>Progressive formats are supported. - </entry> - </row> - <row> - <entry>V4L2_DV_BT_CAP_REDUCED_BLANKING</entry> - <entry>CVT/GTF specific: the timings can make use of reduced blanking (CVT) -or the 'Secondary GTF' curve (GTF). - </entry> - </row> - <row> - <entry>V4L2_DV_BT_CAP_CUSTOM</entry> - <entry>Can support non-standard timings, i.e. timings not belonging to the -standards set in the <structfield>standards</structfield> field. - </entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml b/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml deleted file mode 100644 index 70a4a08e9404..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml +++ /dev/null @@ -1,197 +0,0 @@ -<refentry id="vidioc-encoder-cmd"> - <refmeta> - <refentrytitle>ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_ENCODER_CMD</refname> - <refname>VIDIOC_TRY_ENCODER_CMD</refname> - <refpurpose>Execute an encoder command</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_encoder_cmd *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>These ioctls control an audio/video (usually MPEG-) encoder. -<constant>VIDIOC_ENCODER_CMD</constant> sends a command to the -encoder, <constant>VIDIOC_TRY_ENCODER_CMD</constant> can be used to -try a command without actually executing it.</para> - - <para>To send a command applications must initialize all fields of a - &v4l2-encoder-cmd; and call - <constant>VIDIOC_ENCODER_CMD</constant> or - <constant>VIDIOC_TRY_ENCODER_CMD</constant> with a pointer to this - structure.</para> - - <para>The <structfield>cmd</structfield> field must contain the -command code. The <structfield>flags</structfield> field is currently -only used by the STOP command and contains one bit: If the -<constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant> flag is set, -encoding will continue until the end of the current <wordasword>Group -Of Pictures</wordasword>, otherwise it will stop immediately.</para> - - <para>A <function>read</function>() or &VIDIOC-STREAMON; call sends an implicit -START command to the encoder if it has not been started yet. After a STOP command, -<function>read</function>() calls will read the remaining data -buffered by the driver. When the buffer is empty, -<function>read</function>() will return zero and the next -<function>read</function>() call will restart the encoder.</para> - - <para>A <function>close</function>() or &VIDIOC-STREAMOFF; call of a streaming -file descriptor sends an implicit immediate STOP to the encoder, and all buffered -data is discarded.</para> - - <para>These ioctls are optional, not all drivers may support -them. They were introduced in Linux 2.6.21.</para> - - <table pgwide="1" frame="none" id="v4l2-encoder-cmd"> - <title>struct <structname>v4l2_encoder_cmd</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>cmd</structfield></entry> - <entry>The encoder command, see <xref linkend="encoder-cmds" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry>Flags to go with the command, see <xref - linkend="encoder-flags" />. If no flags are defined for -this command, drivers and applications must set this field to -zero.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>data</structfield>[8]</entry> - <entry>Reserved for future extensions. Drivers and -applications must set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="encoder-cmds"> - <title>Encoder Commands</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_ENC_CMD_START</constant></entry> - <entry>0</entry> - <entry>Start the encoder. When the encoder is already -running or paused, this command does nothing. No flags are defined for -this command.</entry> - </row> - <row> - <entry><constant>V4L2_ENC_CMD_STOP</constant></entry> - <entry>1</entry> - <entry>Stop the encoder. When the -<constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant> flag is set, -encoding will continue until the end of the current <wordasword>Group -Of Pictures</wordasword>, otherwise encoding will stop immediately. -When the encoder is already stopped, this command does -nothing. mem2mem encoders will send a <constant>V4L2_EVENT_EOS</constant> event -when the last frame has been encoded and all frames are ready to be dequeued and -will set the <constant>V4L2_BUF_FLAG_LAST</constant> buffer flag on the last -buffer of the capture queue to indicate there will be no new buffers produced to -dequeue. This buffer may be empty, indicated by the driver setting the -<structfield>bytesused</structfield> field to 0. Once the -<constant>V4L2_BUF_FLAG_LAST</constant> flag was set, the -<link linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl will not block anymore, -but return an &EPIPE;.</entry> - </row> - <row> - <entry><constant>V4L2_ENC_CMD_PAUSE</constant></entry> - <entry>2</entry> - <entry>Pause the encoder. When the encoder has not been -started yet, the driver will return an &EPERM;. When the encoder is -already paused, this command does nothing. No flags are defined for -this command.</entry> - </row> - <row> - <entry><constant>V4L2_ENC_CMD_RESUME</constant></entry> - <entry>3</entry> - <entry>Resume encoding after a PAUSE command. When the -encoder has not been started yet, the driver will return an &EPERM;. -When the encoder is already running, this command does nothing. No -flags are defined for this command.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="encoder-flags"> - <title>Encoder Command Flags</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant></entry> - <entry>0x0001</entry> - <entry>Stop encoding at the end of the current <wordasword>Group Of -Pictures</wordasword>, rather than immediately.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The <structfield>cmd</structfield> field is invalid.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EPERM</errorcode></term> - <listitem> - <para>The application sent a PAUSE or RESUME command when -the encoder was not running.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml deleted file mode 100644 index 6e3cadd4e1f9..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml +++ /dev/null @@ -1,133 +0,0 @@ -<refentry id="vidioc-enum-dv-timings"> - <refmeta> - <refentrytitle>ioctl VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_ENUM_DV_TIMINGS</refname> - <refname>VIDIOC_SUBDEV_ENUM_DV_TIMINGS</refname> - <refpurpose>Enumerate supported Digital Video timings</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_enum_dv_timings *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <note> - <title>Experimental</title> - <para>This is an <link linkend="experimental"> experimental </link> - interface and may change in the future.</para> - </note> - - <para>While some DV receivers or transmitters support a wide range of timings, others -support only a limited number of timings. With this ioctl applications can enumerate a list -of known supported timings. Call &VIDIOC-DV-TIMINGS-CAP; to check if it also supports other -standards or even custom timings that are not in this list.</para> - - <para>To query the available timings, applications initialize the -<structfield>index</structfield> field and zero the reserved array of &v4l2-enum-dv-timings; -and call the <constant>VIDIOC_ENUM_DV_TIMINGS</constant> ioctl on a video node with a -pointer to this structure. Drivers fill the rest of the structure or return an -&EINVAL; when the index is out of bounds. To enumerate all supported DV timings, -applications shall begin at index zero, incrementing by one until the -driver returns <errorcode>EINVAL</errorcode>. Note that drivers may enumerate a -different set of DV timings after switching the video input or -output.</para> - - <para>When implemented by the driver DV timings of subdevices can be queried -by calling the <constant>VIDIOC_SUBDEV_ENUM_DV_TIMINGS</constant> ioctl directly -on a subdevice node. The DV timings are specific to inputs (for DV receivers) or -outputs (for DV transmitters), applications must specify the desired pad number -in the &v4l2-enum-dv-timings; <structfield>pad</structfield> field. Attempts to -enumerate timings on a pad that doesn't support them will return an &EINVAL;.</para> - - <table pgwide="1" frame="none" id="v4l2-enum-dv-timings"> - <title>struct <structname>v4l2_enum_dv_timings</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>index</structfield></entry> - <entry>Number of the DV timings, set by the -application.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>pad</structfield></entry> - <entry>Pad number as reported by the media controller API. This field - is only used when operating on a subdevice node. When operating on a - video node applications must set this field to zero.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[2]</entry> - <entry>Reserved for future extensions. Drivers and applications must - set the array to zero.</entry> - </row> - <row> - <entry>&v4l2-dv-timings;</entry> - <entry><structfield>timings</structfield></entry> - <entry>The timings.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The &v4l2-enum-dv-timings; <structfield>index</structfield> -is out of bounds or the <structfield>pad</structfield> number is invalid.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>ENODATA</errorcode></term> - <listitem> - <para>Digital video presets are not supported for this input or output.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml b/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml deleted file mode 100644 index f8dfeed34fca..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml +++ /dev/null @@ -1,159 +0,0 @@ -<refentry id="vidioc-enum-fmt"> - <refmeta> - <refentrytitle>ioctl VIDIOC_ENUM_FMT</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_ENUM_FMT</refname> - <refpurpose>Enumerate image formats</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_fmtdesc -*<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_ENUM_FMT</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>To enumerate image formats applications initialize the -<structfield>type</structfield> and <structfield>index</structfield> -field of &v4l2-fmtdesc; and call the -<constant>VIDIOC_ENUM_FMT</constant> ioctl with a pointer to this -structure. Drivers fill the rest of the structure or return an -&EINVAL;. All formats are enumerable by beginning at index zero and -incrementing by one until <errorcode>EINVAL</errorcode> is -returned.</para> - - <para>Note that after switching input or output the list of enumerated image -formats may be different.</para> - - <table pgwide="1" frame="none" id="v4l2-fmtdesc"> - <title>struct <structname>v4l2_fmtdesc</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>index</structfield></entry> - <entry>Number of the format in the enumeration, set by -the application. This is in no way related to the <structfield> -pixelformat</structfield> field.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry>Type of the data stream, set by the application. -Only these types are valid here: -<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>, -<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>, -<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>, -<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant> and -<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>. See <xref linkend="v4l2-buf-type" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry>See <xref linkend="fmtdesc-flags" /></entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>description</structfield>[32]</entry> - <entry>Description of the format, a NUL-terminated ASCII -string. This information is intended for the user, for example: "YUV -4:2:2".</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>pixelformat</structfield></entry> - <entry>The image format identifier. This is a -four character code as computed by the v4l2_fourcc() -macro:</entry> - </row> - <row> - <entry spanname="hspan"><para><programlisting id="v4l2-fourcc"> -#define v4l2_fourcc(a,b,c,d) (((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24)) -</programlisting></para><para>Several image formats are already -defined by this specification in <xref linkend="pixfmt" />. Note these -codes are not the same as those used in the Windows world.</para></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[4]</entry> - <entry>Reserved for future extensions. Drivers must set -the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="fmtdesc-flags"> - <title>Image Format Description Flags</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_FMT_FLAG_COMPRESSED</constant></entry> - <entry>0x0001</entry> - <entry>This is a compressed format.</entry> - </row> - <row> - <entry><constant>V4L2_FMT_FLAG_EMULATED</constant></entry> - <entry>0x0002</entry> - <entry>This format is not native to the device but emulated -through software (usually libv4l2), where possible try to use a native format -instead for better performance.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The &v4l2-fmtdesc; <structfield>type</structfield> -is not supported or the <structfield>index</structfield> is out of -bounds.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-frameintervals.xml b/Documentation/DocBook/media/v4l/vidioc-enum-frameintervals.xml deleted file mode 100644 index 7c839ab0afbb..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-enum-frameintervals.xml +++ /dev/null @@ -1,260 +0,0 @@ -<refentry id="vidioc-enum-frameintervals"> - - <refmeta> - <refentrytitle>ioctl VIDIOC_ENUM_FRAMEINTERVALS</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_ENUM_FRAMEINTERVALS</refname> - <refpurpose>Enumerate frame intervals</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_frmivalenum *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_ENUM_FRAMEINTERVALS</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para>Pointer to a &v4l2-frmivalenum; structure that -contains a pixel format and size and receives a frame interval.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>This ioctl allows applications to enumerate all frame -intervals that the device supports for the given pixel format and -frame size.</para> - <para>The supported pixel formats and frame sizes can be obtained -by using the &VIDIOC-ENUM-FMT; and &VIDIOC-ENUM-FRAMESIZES; -functions.</para> - <para>The return value and the content of the -<structfield>v4l2_frmivalenum.type</structfield> field depend on the -type of frame intervals the device supports. Here are the semantics of -the function for the different cases:</para> - <itemizedlist> - <listitem> - <para><emphasis role="bold">Discrete:</emphasis> The function -returns success if the given index value (zero-based) is valid. The -application should increase the index by one for each call until -<constant>EINVAL</constant> is returned. The `v4l2_frmivalenum.type` -field is set to `V4L2_FRMIVAL_TYPE_DISCRETE` by the driver. Of the -union only the `discrete` member is valid.</para> - </listitem> - <listitem> - <para><emphasis role="bold">Step-wise:</emphasis> The function -returns success if the given index value is zero and -<constant>EINVAL</constant> for any other index value. The -<structfield>v4l2_frmivalenum.type</structfield> field is set to -<constant>V4L2_FRMIVAL_TYPE_STEPWISE</constant> by the driver. Of the -union only the <structfield>stepwise</structfield> member is -valid.</para> - </listitem> - <listitem> - <para><emphasis role="bold">Continuous:</emphasis> This is a -special case of the step-wise type above. The function returns success -if the given index value is zero and <constant>EINVAL</constant> for -any other index value. The -<structfield>v4l2_frmivalenum.type</structfield> field is set to -<constant>V4L2_FRMIVAL_TYPE_CONTINUOUS</constant> by the driver. Of -the union only the <structfield>stepwise</structfield> member is valid -and the <structfield>step</structfield> value is set to 1.</para> - </listitem> - </itemizedlist> - - <para>When the application calls the function with index zero, it -must check the <structfield>type</structfield> field to determine the -type of frame interval enumeration the device supports. Only for the -<constant>V4L2_FRMIVAL_TYPE_DISCRETE</constant> type does it make -sense to increase the index value to receive more frame -intervals.</para> - <para>Note that the order in which the frame intervals are -returned has no special meaning. In particular does it not say -anything about potential default frame intervals.</para> - <para>Applications can assume that the enumeration data does not -change without any interaction from the application itself. This means -that the enumeration data is consistent if the application does not -perform any other ioctl calls while it runs the frame interval -enumeration.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <itemizedlist> - <listitem> - <para><emphasis role="bold">Frame intervals and frame -rates:</emphasis> The V4L2 API uses frame intervals instead of frame -rates. Given the frame interval the frame rate can be computed as -follows:<screen>frame_rate = 1 / frame_interval</screen></para> - </listitem> - </itemizedlist> - - </refsect1> - - <refsect1> - <title>Structs</title> - - <para>In the structs below, <emphasis>IN</emphasis> denotes a -value that has to be filled in by the application, -<emphasis>OUT</emphasis> denotes values that the driver fills in. The -application should zero out all members except for the -<emphasis>IN</emphasis> fields.</para> - - <table pgwide="1" frame="none" id="v4l2-frmival-stepwise"> - <title>struct <structname>v4l2_frmival_stepwise</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>&v4l2-fract;</entry> - <entry><structfield>min</structfield></entry> - <entry>Minimum frame interval [s].</entry> - </row> - <row> - <entry>&v4l2-fract;</entry> - <entry><structfield>max</structfield></entry> - <entry>Maximum frame interval [s].</entry> - </row> - <row> - <entry>&v4l2-fract;</entry> - <entry><structfield>step</structfield></entry> - <entry>Frame interval step size [s].</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="v4l2-frmivalenum"> - <title>struct <structname>v4l2_frmivalenum</structname></title> - <tgroup cols="4"> - <colspec colname="c1" /> - <colspec colname="c2" /> - <colspec colname="c3" /> - <colspec colname="c4" /> - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>index</structfield></entry> - <entry></entry> - <entry>IN: Index of the given frame interval in the -enumeration.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>pixel_format</structfield></entry> - <entry></entry> - <entry>IN: Pixel format for which the frame intervals are -enumerated.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>width</structfield></entry> - <entry></entry> - <entry>IN: Frame width for which the frame intervals are -enumerated.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>height</structfield></entry> - <entry></entry> - <entry>IN: Frame height for which the frame intervals are -enumerated.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry></entry> - <entry>OUT: Frame interval type the device supports.</entry> - </row> - <row> - <entry>union</entry> - <entry></entry> - <entry></entry> - <entry>OUT: Frame interval with the given index.</entry> - </row> - <row> - <entry></entry> - <entry>&v4l2-fract;</entry> - <entry><structfield>discrete</structfield></entry> - <entry>Frame interval [s].</entry> - </row> - <row> - <entry></entry> - <entry>&v4l2-frmival-stepwise;</entry> - <entry><structfield>stepwise</structfield></entry> - <entry></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved[2]</structfield></entry> - <entry></entry> - <entry>Reserved space for future use. Must be zeroed by drivers and - applications.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - <title>Enums</title> - - <table pgwide="1" frame="none" id="v4l2-frmivaltypes"> - <title>enum <structname>v4l2_frmivaltypes</structname></title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_FRMIVAL_TYPE_DISCRETE</constant></entry> - <entry>1</entry> - <entry>Discrete frame interval.</entry> - </row> - <row> - <entry><constant>V4L2_FRMIVAL_TYPE_CONTINUOUS</constant></entry> - <entry>2</entry> - <entry>Continuous frame interval.</entry> - </row> - <row> - <entry><constant>V4L2_FRMIVAL_TYPE_STEPWISE</constant></entry> - <entry>3</entry> - <entry>Step-wise defined frame interval.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - </refsect1> - -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml b/Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml deleted file mode 100644 index 9ed68ac8f474..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml +++ /dev/null @@ -1,265 +0,0 @@ -<refentry id="vidioc-enum-framesizes"> - - <refmeta> - <refentrytitle>ioctl VIDIOC_ENUM_FRAMESIZES</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_ENUM_FRAMESIZES</refname> - <refpurpose>Enumerate frame sizes</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_frmsizeenum *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_ENUM_FRAMESIZES</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para>Pointer to a &v4l2-frmsizeenum; that contains an index -and pixel format and receives a frame width and height.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>This ioctl allows applications to enumerate all frame sizes -(&ie; width and height in pixels) that the device supports for the -given pixel format.</para> - <para>The supported pixel formats can be obtained by using the -&VIDIOC-ENUM-FMT; function.</para> - <para>The return value and the content of the -<structfield>v4l2_frmsizeenum.type</structfield> field depend on the -type of frame sizes the device supports. Here are the semantics of the -function for the different cases:</para> - - <itemizedlist> - <listitem> - <para><emphasis role="bold">Discrete:</emphasis> The function -returns success if the given index value (zero-based) is valid. The -application should increase the index by one for each call until -<constant>EINVAL</constant> is returned. The -<structfield>v4l2_frmsizeenum.type</structfield> field is set to -<constant>V4L2_FRMSIZE_TYPE_DISCRETE</constant> by the driver. Of the -union only the <structfield>discrete</structfield> member is -valid.</para> - </listitem> - <listitem> - <para><emphasis role="bold">Step-wise:</emphasis> The function -returns success if the given index value is zero and -<constant>EINVAL</constant> for any other index value. The -<structfield>v4l2_frmsizeenum.type</structfield> field is set to -<constant>V4L2_FRMSIZE_TYPE_STEPWISE</constant> by the driver. Of the -union only the <structfield>stepwise</structfield> member is -valid.</para> - </listitem> - <listitem> - <para><emphasis role="bold">Continuous:</emphasis> This is a -special case of the step-wise type above. The function returns success -if the given index value is zero and <constant>EINVAL</constant> for -any other index value. The -<structfield>v4l2_frmsizeenum.type</structfield> field is set to -<constant>V4L2_FRMSIZE_TYPE_CONTINUOUS</constant> by the driver. Of -the union only the <structfield>stepwise</structfield> member is valid -and the <structfield>step_width</structfield> and -<structfield>step_height</structfield> values are set to 1.</para> - </listitem> - </itemizedlist> - - <para>When the application calls the function with index zero, it -must check the <structfield>type</structfield> field to determine the -type of frame size enumeration the device supports. Only for the -<constant>V4L2_FRMSIZE_TYPE_DISCRETE</constant> type does it make -sense to increase the index value to receive more frame sizes.</para> - <para>Note that the order in which the frame sizes are returned -has no special meaning. In particular does it not say anything about -potential default format sizes.</para> - <para>Applications can assume that the enumeration data does not -change without any interaction from the application itself. This means -that the enumeration data is consistent if the application does not -perform any other ioctl calls while it runs the frame size -enumeration.</para> - </refsect1> - - <refsect1> - <title>Structs</title> - - <para>In the structs below, <emphasis>IN</emphasis> denotes a -value that has to be filled in by the application, -<emphasis>OUT</emphasis> denotes values that the driver fills in. The -application should zero out all members except for the -<emphasis>IN</emphasis> fields.</para> - - <table pgwide="1" frame="none" id="v4l2-frmsize-discrete"> - <title>struct <structname>v4l2_frmsize_discrete</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>width</structfield></entry> - <entry>Width of the frame [pixel].</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>height</structfield></entry> - <entry>Height of the frame [pixel].</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="v4l2-frmsize-stepwise"> - <title>struct <structname>v4l2_frmsize_stepwise</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>min_width</structfield></entry> - <entry>Minimum frame width [pixel].</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>max_width</structfield></entry> - <entry>Maximum frame width [pixel].</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>step_width</structfield></entry> - <entry>Frame width step size [pixel].</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>min_height</structfield></entry> - <entry>Minimum frame height [pixel].</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>max_height</structfield></entry> - <entry>Maximum frame height [pixel].</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>step_height</structfield></entry> - <entry>Frame height step size [pixel].</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="v4l2-frmsizeenum"> - <title>struct <structname>v4l2_frmsizeenum</structname></title> - <tgroup cols="4"> - <colspec colname="c1" /> - <colspec colname="c2" /> - <colspec colname="c3" /> - <colspec colname="c4" /> - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>index</structfield></entry> - <entry></entry> - <entry>IN: Index of the given frame size in the enumeration.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>pixel_format</structfield></entry> - <entry></entry> - <entry>IN: Pixel format for which the frame sizes are enumerated.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry></entry> - <entry>OUT: Frame size type the device supports.</entry> - </row> - <row> - <entry>union</entry> - <entry></entry> - <entry></entry> - <entry>OUT: Frame size with the given index.</entry> - </row> - <row> - <entry></entry> - <entry>&v4l2-frmsize-discrete;</entry> - <entry><structfield>discrete</structfield></entry> - <entry></entry> - </row> - <row> - <entry></entry> - <entry>&v4l2-frmsize-stepwise;</entry> - <entry><structfield>stepwise</structfield></entry> - <entry></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved[2]</structfield></entry> - <entry></entry> - <entry>Reserved space for future use. Must be zeroed by drivers and - applications.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - <title>Enums</title> - - <table pgwide="1" frame="none" id="v4l2-frmsizetypes"> - <title>enum <structname>v4l2_frmsizetypes</structname></title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_FRMSIZE_TYPE_DISCRETE</constant></entry> - <entry>1</entry> - <entry>Discrete frame size.</entry> - </row> - <row> - <entry><constant>V4L2_FRMSIZE_TYPE_CONTINUOUS</constant></entry> - <entry>2</entry> - <entry>Continuous frame size.</entry> - </row> - <row> - <entry><constant>V4L2_FRMSIZE_TYPE_STEPWISE</constant></entry> - <entry>3</entry> - <entry>Step-wise defined frame size.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-freq-bands.xml b/Documentation/DocBook/media/v4l/vidioc-enum-freq-bands.xml deleted file mode 100644 index 4e8ea65f7282..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-enum-freq-bands.xml +++ /dev/null @@ -1,181 +0,0 @@ -<refentry id="vidioc-enum-freq-bands"> - <refmeta> - <refentrytitle>ioctl VIDIOC_ENUM_FREQ_BANDS</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_ENUM_FREQ_BANDS</refname> - <refpurpose>Enumerate supported frequency bands</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_frequency_band -*<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_ENUM_FREQ_BANDS</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <note> - <title>Experimental</title> - <para>This is an <link linkend="experimental"> experimental </link> - interface and may change in the future.</para> - </note> - - <para>Enumerates the frequency bands that a tuner or modulator supports. -To do this applications initialize the <structfield>tuner</structfield>, -<structfield>type</structfield> and <structfield>index</structfield> fields, -and zero out the <structfield>reserved</structfield> array of a &v4l2-frequency-band; and -call the <constant>VIDIOC_ENUM_FREQ_BANDS</constant> ioctl with a pointer -to this structure.</para> - - <para>This ioctl is supported if the <constant>V4L2_TUNER_CAP_FREQ_BANDS</constant> capability - of the corresponding tuner/modulator is set.</para> - - <table pgwide="1" frame="none" id="v4l2-frequency-band"> - <title>struct <structname>v4l2_frequency_band</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>tuner</structfield></entry> - <entry>The tuner or modulator index number. This is the -same value as in the &v4l2-input; <structfield>tuner</structfield> -field and the &v4l2-tuner; <structfield>index</structfield> field, or -the &v4l2-output; <structfield>modulator</structfield> field and the -&v4l2-modulator; <structfield>index</structfield> field.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry>The tuner type. This is the same value as in the -&v4l2-tuner; <structfield>type</structfield> field. The type must be set -to <constant>V4L2_TUNER_RADIO</constant> for <filename>/dev/radioX</filename> -device nodes, and to <constant>V4L2_TUNER_ANALOG_TV</constant> -for all others. Set this field to <constant>V4L2_TUNER_RADIO</constant> for -modulators (currently only radio modulators are supported). -See <xref linkend="v4l2-tuner-type" /></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>index</structfield></entry> - <entry>Identifies the frequency band, set by the application.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>capability</structfield></entry> - <entry spanname="hspan">The tuner/modulator capability flags for -this frequency band, see <xref linkend="tuner-capability" />. The <constant>V4L2_TUNER_CAP_LOW</constant> -or <constant>V4L2_TUNER_CAP_1HZ</constant> capability must be the same for all frequency bands of the selected tuner/modulator. -So either all bands have that capability set, or none of them have that capability.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>rangelow</structfield></entry> - <entry spanname="hspan">The lowest tunable frequency in -units of 62.5 kHz, or if the <structfield>capability</structfield> -flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 -Hz, for this frequency band. A 1 Hz unit is used when the <structfield>capability</structfield> flag -<constant>V4L2_TUNER_CAP_1HZ</constant> is set.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>rangehigh</structfield></entry> - <entry spanname="hspan">The highest tunable frequency in -units of 62.5 kHz, or if the <structfield>capability</structfield> -flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 -Hz, for this frequency band. A 1 Hz unit is used when the <structfield>capability</structfield> flag -<constant>V4L2_TUNER_CAP_1HZ</constant> is set.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>modulation</structfield></entry> - <entry spanname="hspan">The supported modulation systems of this frequency band. - See <xref linkend="band-modulation" />. Note that currently only one - modulation system per frequency band is supported. More work will need to - be done if multiple modulation systems are possible. Contact the - linux-media mailing list (&v4l-ml;) if you need that functionality.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[9]</entry> - <entry>Reserved for future extensions. Applications and drivers - must set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="band-modulation"> - <title>Band Modulation Systems</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_BAND_MODULATION_VSB</constant></entry> - <entry>0x02</entry> - <entry>Vestigial Sideband modulation, used for analog TV.</entry> - </row> - <row> - <entry><constant>V4L2_BAND_MODULATION_FM</constant></entry> - <entry>0x04</entry> - <entry>Frequency Modulation, commonly used for analog radio.</entry> - </row> - <row> - <entry><constant>V4L2_BAND_MODULATION_AM</constant></entry> - <entry>0x08</entry> - <entry>Amplitude Modulation, commonly used for analog radio.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The <structfield>tuner</structfield> or <structfield>index</structfield> -is out of bounds or the <structfield>type</structfield> field is wrong.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-enumaudio.xml b/Documentation/DocBook/media/v4l/vidioc-enumaudio.xml deleted file mode 100644 index ea816ab2e49e..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-enumaudio.xml +++ /dev/null @@ -1,76 +0,0 @@ -<refentry id="vidioc-enumaudio"> - <refmeta> - <refentrytitle>ioctl VIDIOC_ENUMAUDIO</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_ENUMAUDIO</refname> - <refpurpose>Enumerate audio inputs</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_audio *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_ENUMAUDIO</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>To query the attributes of an audio input applications -initialize the <structfield>index</structfield> field and zero out the -<structfield>reserved</structfield> array of a &v4l2-audio; -and call the <constant>VIDIOC_ENUMAUDIO</constant> ioctl with a pointer -to this structure. Drivers fill the rest of the structure or return an -&EINVAL; when the index is out of bounds. To enumerate all audio -inputs applications shall begin at index zero, incrementing by one -until the driver returns <errorcode>EINVAL</errorcode>.</para> - - <para>See <xref linkend="vidioc-g-audio" /> for a description of -&v4l2-audio;.</para> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The number of the audio input is out of bounds.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-enumaudioout.xml b/Documentation/DocBook/media/v4l/vidioc-enumaudioout.xml deleted file mode 100644 index 2e87cedb0d32..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-enumaudioout.xml +++ /dev/null @@ -1,79 +0,0 @@ -<refentry id="vidioc-enumaudioout"> - <refmeta> - <refentrytitle>ioctl VIDIOC_ENUMAUDOUT</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_ENUMAUDOUT</refname> - <refpurpose>Enumerate audio outputs</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_audioout *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_ENUMAUDOUT</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>To query the attributes of an audio output applications -initialize the <structfield>index</structfield> field and zero out the -<structfield>reserved</structfield> array of a &v4l2-audioout; and -call the <constant>VIDIOC_G_AUDOUT</constant> ioctl with a pointer -to this structure. Drivers fill the rest of the structure or return an -&EINVAL; when the index is out of bounds. To enumerate all audio -outputs applications shall begin at index zero, incrementing by one -until the driver returns <errorcode>EINVAL</errorcode>.</para> - - <para>Note connectors on a TV card to loop back the received audio -signal to a sound card are not audio outputs in this sense.</para> - - <para>See <xref linkend="vidioc-g-audioout" /> for a description of -&v4l2-audioout;.</para> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The number of the audio output is out of bounds.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-enuminput.xml b/Documentation/DocBook/media/v4l/vidioc-enuminput.xml deleted file mode 100644 index 603fecef9083..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-enuminput.xml +++ /dev/null @@ -1,316 +0,0 @@ -<refentry id="vidioc-enuminput"> - <refmeta> - <refentrytitle>ioctl VIDIOC_ENUMINPUT</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_ENUMINPUT</refname> - <refpurpose>Enumerate video inputs</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_input -*<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_ENUMINPUT</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>To query the attributes of a video input applications -initialize the <structfield>index</structfield> field of &v4l2-input; -and call the <constant>VIDIOC_ENUMINPUT</constant> ioctl with a -pointer to this structure. Drivers fill the rest of the structure or -return an &EINVAL; when the index is out of bounds. To enumerate all -inputs applications shall begin at index zero, incrementing by one -until the driver returns <errorcode>EINVAL</errorcode>.</para> - - <table frame="none" pgwide="1" id="v4l2-input"> - <title>struct <structname>v4l2_input</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>index</structfield></entry> - <entry>Identifies the input, set by the -application.</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>name</structfield>[32]</entry> - <entry>Name of the video input, a NUL-terminated ASCII -string, for example: "Vin (Composite 2)". This information is intended -for the user, preferably the connector label on the device itself.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry>Type of the input, see <xref - linkend="input-type" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>audioset</structfield></entry> - <entry><para>Drivers can enumerate up to 32 video and -audio inputs. This field shows which audio inputs were selectable as -audio source if this was the currently selected video input. It is a -bit mask. The LSB corresponds to audio input 0, the MSB to input 31. -Any number of bits can be set, or none.</para><para>When the driver -does not enumerate audio inputs no bits must be set. Applications -shall not interpret this as lack of audio support. Some drivers -automatically select audio sources and do not enumerate them since -there is no choice anyway.</para><para>For details on audio inputs and -how to select the current input see <xref - linkend="audio" />.</para></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>tuner</structfield></entry> - <entry>Capture devices can have zero or more tuners (RF -demodulators). When the <structfield>type</structfield> is set to -<constant>V4L2_INPUT_TYPE_TUNER</constant> this is an RF connector and -this field identifies the tuner. It corresponds to -&v4l2-tuner; field <structfield>index</structfield>. For details on -tuners see <xref linkend="tuner" />.</entry> - </row> - <row> - <entry>&v4l2-std-id;</entry> - <entry><structfield>std</structfield></entry> - <entry>Every video input supports one or more different -video standards. This field is a set of all supported standards. For -details on video standards and how to switch see <xref -linkend="standard" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>status</structfield></entry> - <entry>This field provides status information about the -input. See <xref linkend="input-status" /> for flags. -With the exception of the sensor orientation bits <structfield>status</structfield> is only valid when this is the -current input.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>capabilities</structfield></entry> - <entry>This field provides capabilities for the -input. See <xref linkend="input-capabilities" /> for flags.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[3]</entry> - <entry>Reserved for future extensions. Drivers must set -the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="input-type"> - <title>Input Types</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_INPUT_TYPE_TUNER</constant></entry> - <entry>1</entry> - <entry>This input uses a tuner (RF demodulator).</entry> - </row> - <row> - <entry><constant>V4L2_INPUT_TYPE_CAMERA</constant></entry> - <entry>2</entry> - <entry>Analog baseband input, for example CVBS / -Composite Video, S-Video, RGB.</entry> - </row> - </tbody> - </tgroup> - </table> - - <!-- Status flags based on proposal by Mark McClelland, -video4linux-list@redhat.com on 18 Oct 2002, subject "Re: [V4L] Re: -v4l2 api". "Why are some of them inverted? So that the driver doesn't -have to lie about the status in cases where it can't tell one way or -the other. Plus, a status of zero would generally mean that everything -is OK." --> - - <table frame="none" pgwide="1" id="input-status"> - <title>Input Status Flags</title> - <tgroup cols="3"> - <colspec colname="c1" /> - <colspec colname="c2" align="center" /> - <colspec colname="c3" /> - <spanspec namest="c1" nameend="c3" spanname="hspan" - align="left" /> - <tbody valign="top"> - <row> - <entry spanname="hspan">General</entry> - </row> - <row> - <entry><constant>V4L2_IN_ST_NO_POWER</constant></entry> - <entry>0x00000001</entry> - <entry>Attached device is off.</entry> - </row> - <row> - <entry><constant>V4L2_IN_ST_NO_SIGNAL</constant></entry> - <entry>0x00000002</entry> - <entry></entry> - </row> - <row> - <entry><constant>V4L2_IN_ST_NO_COLOR</constant></entry> - <entry>0x00000004</entry> - <entry>The hardware supports color decoding, but does not -detect color modulation in the signal.</entry> - </row> - <row> - <entry spanname="hspan">Sensor Orientation</entry> - </row> - <row> - <entry><constant>V4L2_IN_ST_HFLIP</constant></entry> - <entry>0x00000010</entry> - <entry>The input is connected to a device that produces a signal -that is flipped horizontally and does not correct this before passing the -signal to userspace.</entry> - </row> - <row> - <entry><constant>V4L2_IN_ST_VFLIP</constant></entry> - <entry>0x00000020</entry> - <entry>The input is connected to a device that produces a signal -that is flipped vertically and does not correct this before passing the -signal to userspace. Note that a 180 degree rotation is the same as HFLIP | VFLIP</entry> - </row> - <row> - <entry spanname="hspan">Analog Video</entry> - </row> - <row> - <entry><constant>V4L2_IN_ST_NO_H_LOCK</constant></entry> - <entry>0x00000100</entry> - <entry>No horizontal sync lock.</entry> - </row> - <row> - <entry><constant>V4L2_IN_ST_COLOR_KILL</constant></entry> - <entry>0x00000200</entry> - <entry>A color killer circuit automatically disables color -decoding when it detects no color modulation. When this flag is set -the color killer is enabled <emphasis>and</emphasis> has shut off -color decoding.</entry> - </row> - <row> - <entry spanname="hspan">Digital Video</entry> - </row> - <row> - <entry><constant>V4L2_IN_ST_NO_SYNC</constant></entry> - <entry>0x00010000</entry> - <entry>No synchronization lock.</entry> - </row> - <row> - <entry><constant>V4L2_IN_ST_NO_EQU</constant></entry> - <entry>0x00020000</entry> - <entry>No equalizer lock.</entry> - </row> - <row> - <entry><constant>V4L2_IN_ST_NO_CARRIER</constant></entry> - <entry>0x00040000</entry> - <entry>Carrier recovery failed.</entry> - </row> - <row> - <entry spanname="hspan">VCR and Set-Top Box</entry> - </row> - <row> - <entry><constant>V4L2_IN_ST_MACROVISION</constant></entry> - <entry>0x01000000</entry> - <entry>Macrovision is an analog copy prevention system -mangling the video signal to confuse video recorders. When this -flag is set Macrovision has been detected.</entry> - </row> - <row> - <entry><constant>V4L2_IN_ST_NO_ACCESS</constant></entry> - <entry>0x02000000</entry> - <entry>Conditional access denied.</entry> - </row> - <row> - <entry><constant>V4L2_IN_ST_VTR</constant></entry> - <entry>0x04000000</entry> - <entry>VTR time constant. [?]</entry> - </row> - </tbody> - </tgroup> - </table> - - <!-- Capability flags based on video timings RFC by Muralidharan -Karicheri, titled RFC (v1.2): V4L - Support for video timings at the -input/output interface to linux-media@vger.kernel.org on 19 Oct 2009. - --> - <table frame="none" pgwide="1" id="input-capabilities"> - <title>Input capabilities</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_IN_CAP_DV_TIMINGS</constant></entry> - <entry>0x00000002</entry> - <entry>This input supports setting video timings by using VIDIOC_S_DV_TIMINGS.</entry> - </row> - <row> - <entry><constant>V4L2_IN_CAP_STD</constant></entry> - <entry>0x00000004</entry> - <entry>This input supports setting the TV standard by using VIDIOC_S_STD.</entry> - </row> - <row> - <entry><constant>V4L2_IN_CAP_NATIVE_SIZE</constant></entry> - <entry>0x00000008</entry> - <entry>This input supports setting the native size using - the <constant>V4L2_SEL_TGT_NATIVE_SIZE</constant> - selection target, see <xref - linkend="v4l2-selections-common"/>.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The &v4l2-input; <structfield>index</structfield> is -out of bounds.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml b/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml deleted file mode 100644 index 773fb1258c24..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml +++ /dev/null @@ -1,201 +0,0 @@ -<refentry id="vidioc-enumoutput"> - <refmeta> - <refentrytitle>ioctl VIDIOC_ENUMOUTPUT</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_ENUMOUTPUT</refname> - <refpurpose>Enumerate video outputs</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_output *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_ENUMOUTPUT</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>To query the attributes of a video outputs applications -initialize the <structfield>index</structfield> field of &v4l2-output; -and call the <constant>VIDIOC_ENUMOUTPUT</constant> ioctl with a -pointer to this structure. Drivers fill the rest of the structure or -return an &EINVAL; when the index is out of bounds. To enumerate all -outputs applications shall begin at index zero, incrementing by one -until the driver returns <errorcode>EINVAL</errorcode>.</para> - - <table frame="none" pgwide="1" id="v4l2-output"> - <title>struct <structname>v4l2_output</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>index</structfield></entry> - <entry>Identifies the output, set by the -application.</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>name</structfield>[32]</entry> - <entry>Name of the video output, a NUL-terminated ASCII -string, for example: "Vout". This information is intended for the -user, preferably the connector label on the device itself.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry>Type of the output, see <xref - linkend="output-type" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>audioset</structfield></entry> - <entry><para>Drivers can enumerate up to 32 video and -audio outputs. This field shows which audio outputs were -selectable as the current output if this was the currently selected -video output. It is a bit mask. The LSB corresponds to audio output 0, -the MSB to output 31. Any number of bits can be set, or -none.</para><para>When the driver does not enumerate audio outputs no -bits must be set. Applications shall not interpret this as lack of -audio support. Drivers may automatically select audio outputs without -enumerating them.</para><para>For details on audio outputs and how to -select the current output see <xref linkend="audio" />.</para></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>modulator</structfield></entry> - <entry>Output devices can have zero or more RF modulators. -When the <structfield>type</structfield> is -<constant>V4L2_OUTPUT_TYPE_MODULATOR</constant> this is an RF -connector and this field identifies the modulator. It corresponds to -&v4l2-modulator; field <structfield>index</structfield>. For details -on modulators see <xref linkend="tuner" />.</entry> - </row> - <row> - <entry>&v4l2-std-id;</entry> - <entry><structfield>std</structfield></entry> - <entry>Every video output supports one or more different -video standards. This field is a set of all supported standards. For -details on video standards and how to switch see <xref - linkend="standard" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>capabilities</structfield></entry> - <entry>This field provides capabilities for the -output. See <xref linkend="output-capabilities" /> for flags.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[3]</entry> - <entry>Reserved for future extensions. Drivers must set -the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="output-type"> - <title>Output Type</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_OUTPUT_TYPE_MODULATOR</constant></entry> - <entry>1</entry> - <entry>This output is an analog TV modulator.</entry> - </row> - <row> - <entry><constant>V4L2_OUTPUT_TYPE_ANALOG</constant></entry> - <entry>2</entry> - <entry>Analog baseband output, for example Composite / -CVBS, S-Video, RGB.</entry> - </row> - <row> - <entry><constant>V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY</constant></entry> - <entry>3</entry> - <entry>[?]</entry> - </row> - </tbody> - </tgroup> - </table> - - <!-- Capabilities flags based on video timings RFC by Muralidharan -Karicheri, titled RFC (v1.2): V4L - Support for video timings at the -input/output interface to linux-media@vger.kernel.org on 19 Oct 2009. - --> - <table frame="none" pgwide="1" id="output-capabilities"> - <title>Output capabilities</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_OUT_CAP_DV_TIMINGS</constant></entry> - <entry>0x00000002</entry> - <entry>This output supports setting video timings by using VIDIOC_S_DV_TIMINGS.</entry> - </row> - <row> - <entry><constant>V4L2_OUT_CAP_STD</constant></entry> - <entry>0x00000004</entry> - <entry>This output supports setting the TV standard by using VIDIOC_S_STD.</entry> - </row> - <row> - <entry><constant>V4L2_OUT_CAP_NATIVE_SIZE</constant></entry> - <entry>0x00000008</entry> - <entry>This output supports setting the native size using - the <constant>V4L2_SEL_TGT_NATIVE_SIZE</constant> - selection target, see <xref - linkend="v4l2-selections-common"/>.</entry> - </row> - </tbody> - </tgroup> - </table> - - </refsect1> - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The &v4l2-output; <structfield>index</structfield> -is out of bounds.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-enumstd.xml b/Documentation/DocBook/media/v4l/vidioc-enumstd.xml deleted file mode 100644 index f18454e91752..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-enumstd.xml +++ /dev/null @@ -1,389 +0,0 @@ -<refentry id="vidioc-enumstd"> - <refmeta> - <refentrytitle>ioctl VIDIOC_ENUMSTD</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_ENUMSTD</refname> - <refpurpose>Enumerate supported video standards</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_standard *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_ENUMSTD</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>To query the attributes of a video standard, -especially a custom (driver defined) one, applications initialize the -<structfield>index</structfield> field of &v4l2-standard; and call the -<constant>VIDIOC_ENUMSTD</constant> ioctl with a pointer to this -structure. Drivers fill the rest of the structure or return an -&EINVAL; when the index is out of bounds. To enumerate all standards -applications shall begin at index zero, incrementing by one until the -driver returns <errorcode>EINVAL</errorcode>. Drivers may enumerate a -different set of standards after switching the video input or -output.<footnote> - <para>The supported standards may overlap and we need an -unambiguous set to find the current standard returned by -<constant>VIDIOC_G_STD</constant>.</para> - </footnote></para> - - <table pgwide="1" frame="none" id="v4l2-standard"> - <title>struct <structname>v4l2_standard</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>index</structfield></entry> - <entry>Number of the video standard, set by the -application.</entry> - </row> - <row> - <entry>&v4l2-std-id;</entry> - <entry><structfield>id</structfield></entry> - <entry>The bits in this field identify the standard as -one of the common standards listed in <xref linkend="v4l2-std-id" />, -or if bits 32 to 63 are set as custom standards. Multiple bits can be -set if the hardware does not distinguish between these standards, -however separate indices do not indicate the opposite. The -<structfield>id</structfield> must be unique. No other enumerated -<structname>v4l2_standard</structname> structure, for this input or -output anyway, can contain the same set of bits.</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>name</structfield>[24]</entry> - <entry>Name of the standard, a NUL-terminated ASCII -string, for example: "PAL-B/G", "NTSC Japan". This information is -intended for the user.</entry> - </row> - <row> - <entry>&v4l2-fract;</entry> - <entry><structfield>frameperiod</structfield></entry> - <entry>The frame period (not field period) is numerator -/ denominator. For example M/NTSC has a frame period of 1001 / -30000 seconds.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>framelines</structfield></entry> - <entry>Total lines per frame including blanking, -e. g. 625 for B/PAL.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[4]</entry> - <entry>Reserved for future extensions. Drivers must set -the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="v4l2-fract"> - <title>struct <structname>v4l2_fract</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>numerator</structfield></entry> - <entry></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>denominator</structfield></entry> - <entry></entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="v4l2-std-id"> - <title>typedef <structname>v4l2_std_id</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u64</entry> - <entry><structfield>v4l2_std_id</structfield></entry> - <entry>This type is a set, each bit representing another -video standard as listed below and in <xref -linkend="video-standards" />. The 32 most significant bits are reserved -for custom (driver defined) video standards.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para><programlisting> -#define V4L2_STD_PAL_B ((v4l2_std_id)0x00000001) -#define V4L2_STD_PAL_B1 ((v4l2_std_id)0x00000002) -#define V4L2_STD_PAL_G ((v4l2_std_id)0x00000004) -#define V4L2_STD_PAL_H ((v4l2_std_id)0x00000008) -#define V4L2_STD_PAL_I ((v4l2_std_id)0x00000010) -#define V4L2_STD_PAL_D ((v4l2_std_id)0x00000020) -#define V4L2_STD_PAL_D1 ((v4l2_std_id)0x00000040) -#define V4L2_STD_PAL_K ((v4l2_std_id)0x00000080) - -#define V4L2_STD_PAL_M ((v4l2_std_id)0x00000100) -#define V4L2_STD_PAL_N ((v4l2_std_id)0x00000200) -#define V4L2_STD_PAL_Nc ((v4l2_std_id)0x00000400) -#define V4L2_STD_PAL_60 ((v4l2_std_id)0x00000800) -</programlisting></para><para><constant>V4L2_STD_PAL_60</constant> is -a hybrid standard with 525 lines, 60 Hz refresh rate, and PAL color -modulation with a 4.43 MHz color subcarrier. Some PAL video recorders -can play back NTSC tapes in this mode for display on a 50/60 Hz agnostic -PAL TV.</para><para><programlisting> -#define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000) -#define V4L2_STD_NTSC_M_JP ((v4l2_std_id)0x00002000) -#define V4L2_STD_NTSC_443 ((v4l2_std_id)0x00004000) -</programlisting></para><para><constant>V4L2_STD_NTSC_443</constant> -is a hybrid standard with 525 lines, 60 Hz refresh rate, and NTSC -color modulation with a 4.43 MHz color -subcarrier.</para><para><programlisting> -#define V4L2_STD_NTSC_M_KR ((v4l2_std_id)0x00008000) - -#define V4L2_STD_SECAM_B ((v4l2_std_id)0x00010000) -#define V4L2_STD_SECAM_D ((v4l2_std_id)0x00020000) -#define V4L2_STD_SECAM_G ((v4l2_std_id)0x00040000) -#define V4L2_STD_SECAM_H ((v4l2_std_id)0x00080000) -#define V4L2_STD_SECAM_K ((v4l2_std_id)0x00100000) -#define V4L2_STD_SECAM_K1 ((v4l2_std_id)0x00200000) -#define V4L2_STD_SECAM_L ((v4l2_std_id)0x00400000) -#define V4L2_STD_SECAM_LC ((v4l2_std_id)0x00800000) - -/* ATSC/HDTV */ -#define V4L2_STD_ATSC_8_VSB ((v4l2_std_id)0x01000000) -#define V4L2_STD_ATSC_16_VSB ((v4l2_std_id)0x02000000) -</programlisting></para><para><!-- ATSC proposal by Mark McClelland, -video4linux-list@redhat.com on 17 Oct 2002 ---><constant>V4L2_STD_ATSC_8_VSB</constant> and -<constant>V4L2_STD_ATSC_16_VSB</constant> are U.S. terrestrial digital -TV standards. Presently the V4L2 API does not support digital TV. See -also the Linux DVB API at <ulink -url="https://linuxtv.org">https://linuxtv.org</ulink>.</para> -<para><programlisting> -#define V4L2_STD_PAL_BG (V4L2_STD_PAL_B |\ - V4L2_STD_PAL_B1 |\ - V4L2_STD_PAL_G) -#define V4L2_STD_B (V4L2_STD_PAL_B |\ - V4L2_STD_PAL_B1 |\ - V4L2_STD_SECAM_B) -#define V4L2_STD_GH (V4L2_STD_PAL_G |\ - V4L2_STD_PAL_H |\ - V4L2_STD_SECAM_G |\ - V4L2_STD_SECAM_H) -#define V4L2_STD_PAL_DK (V4L2_STD_PAL_D |\ - V4L2_STD_PAL_D1 |\ - V4L2_STD_PAL_K) -#define V4L2_STD_PAL (V4L2_STD_PAL_BG |\ - V4L2_STD_PAL_DK |\ - V4L2_STD_PAL_H |\ - V4L2_STD_PAL_I) -#define V4L2_STD_NTSC (V4L2_STD_NTSC_M |\ - V4L2_STD_NTSC_M_JP |\ - V4L2_STD_NTSC_M_KR) -#define V4L2_STD_MN (V4L2_STD_PAL_M |\ - V4L2_STD_PAL_N |\ - V4L2_STD_PAL_Nc |\ - V4L2_STD_NTSC) -#define V4L2_STD_SECAM_DK (V4L2_STD_SECAM_D |\ - V4L2_STD_SECAM_K |\ - V4L2_STD_SECAM_K1) -#define V4L2_STD_DK (V4L2_STD_PAL_DK |\ - V4L2_STD_SECAM_DK) - -#define V4L2_STD_SECAM (V4L2_STD_SECAM_B |\ - V4L2_STD_SECAM_G |\ - V4L2_STD_SECAM_H |\ - V4L2_STD_SECAM_DK |\ - V4L2_STD_SECAM_L |\ - V4L2_STD_SECAM_LC) - -#define V4L2_STD_525_60 (V4L2_STD_PAL_M |\ - V4L2_STD_PAL_60 |\ - V4L2_STD_NTSC |\ - V4L2_STD_NTSC_443) -#define V4L2_STD_625_50 (V4L2_STD_PAL |\ - V4L2_STD_PAL_N |\ - V4L2_STD_PAL_Nc |\ - V4L2_STD_SECAM) - -#define V4L2_STD_UNKNOWN 0 -#define V4L2_STD_ALL (V4L2_STD_525_60 |\ - V4L2_STD_625_50) -</programlisting></para> - - <table pgwide="1" id="video-standards" orient="land"> - <title>Video Standards (based on [<xref linkend="itu470" />])</title> - <tgroup cols="12" colsep="1" rowsep="1" align="center"> - <colspec colname="c1" align="left" /> - <colspec colname="c2" /> - <colspec colname="c3" /> - <colspec colname="c4" /> - <colspec colname="c5" /> - <colspec colnum="7" colname="c7" /> - <colspec colnum="9" colname="c9" /> - <colspec colnum="12" colname="c12" /> - <spanspec namest="c2" nameend="c3" spanname="m" align="center" /> - <spanspec namest="c4" nameend="c12" spanname="x" align="center" /> - <spanspec namest="c5" nameend="c7" spanname="b" align="center" /> - <spanspec namest="c9" nameend="c12" spanname="s" align="center" /> - <thead> - <row> - <entry>Characteristics</entry> - <entry><para>M/NTSC<footnote><para>Japan uses a standard -similar to M/NTSC -(V4L2_STD_NTSC_M_JP).</para></footnote></para></entry> - <entry>M/PAL</entry> - <entry><para>N/PAL<footnote><para> The values in -brackets apply to the combination N/PAL a.k.a. -N<subscript>C</subscript> used in Argentina -(V4L2_STD_PAL_Nc).</para></footnote></para></entry> - <entry align="center">B, B1, G/PAL</entry> - <entry align="center">D, D1, K/PAL</entry> - <entry align="center">H/PAL</entry> - <entry align="center">I/PAL</entry> - <entry align="center">B, G/SECAM</entry> - <entry align="center">D, K/SECAM</entry> - <entry align="center">K1/SECAM</entry> - <entry align="center">L/SECAM</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry>Frame lines</entry> - <entry spanname="m">525</entry> - <entry spanname="x">625</entry> - </row> - <row> - <entry>Frame period (s)</entry> - <entry spanname="m">1001/30000</entry> - <entry spanname="x">1/25</entry> - </row> - <row> - <entry>Chrominance sub-carrier frequency (Hz)</entry> - <entry>3579545 ± 10</entry> - <entry>3579611.49 ± 10</entry> - <entry>4433618.75 ± 5 (3582056.25 -± 5)</entry> - <entry spanname="b">4433618.75 ± 5</entry> - <entry>4433618.75 ± 1</entry> - <entry spanname="s">f<subscript>OR</subscript> = -4406250 ± 2000, f<subscript>OB</subscript> = 4250000 -± 2000</entry> - </row> - <row> - <entry>Nominal radio-frequency channel bandwidth -(MHz)</entry> - <entry>6</entry> - <entry>6</entry> - <entry>6</entry> - <entry>B: 7; B1, G: 8</entry> - <entry>8</entry> - <entry>8</entry> - <entry>8</entry> - <entry>8</entry> - <entry>8</entry> - <entry>8</entry> - <entry>8</entry> - </row> - <row> - <entry>Sound carrier relative to vision carrier -(MHz)</entry> - <entry>+ 4.5</entry> - <entry>+ 4.5</entry> - <entry>+ 4.5</entry> - <entry><para>+ 5.5 ± 0.001 -<footnote><para>In the Federal Republic of Germany, Austria, Italy, -the Netherlands, Slovakia and Switzerland a system of two sound -carriers is used, the frequency of the second carrier being -242.1875 kHz above the frequency of the first sound carrier. For -stereophonic sound transmissions a similar system is used in -Australia.</para></footnote> <footnote><para>New Zealand uses a sound -carrier displaced 5.4996 ± 0.0005 MHz from the vision -carrier.</para></footnote> <footnote><para>In Denmark, Finland, New -Zealand, Sweden and Spain a system of two sound carriers is used. In -Iceland, Norway and Poland the same system is being introduced. The -second carrier is 5.85 MHz above the vision carrier and is DQPSK -modulated with 728 kbit/s sound and data multiplex. (NICAM -system)</para></footnote> <footnote><para>In the United Kingdom, a -system of two sound carriers is used. The second sound carrier is -6.552 MHz above the vision carrier and is DQPSK modulated with a -728 kbit/s sound and data multiplex able to carry two sound -channels. (NICAM system)</para></footnote></para></entry> - <entry>+ 6.5 ± 0.001</entry> - <entry>+ 5.5</entry> - <entry>+ 5.9996 ± 0.0005</entry> - <entry>+ 5.5 ± 0.001</entry> - <entry>+ 6.5 ± 0.001</entry> - <entry>+ 6.5</entry> - <entry><para>+ 6.5 <footnote><para>In France, a -digital carrier 5.85 MHz away from the vision carrier may be used in -addition to the main sound carrier. It is modulated in differentially -encoded QPSK with a 728 kbit/s sound and data multiplexer capable of -carrying two sound channels. (NICAM -system)</para></footnote></para></entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The &v4l2-standard; <structfield>index</structfield> -is out of bounds.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>ENODATA</errorcode></term> - <listitem> - <para>Standard video timings are not supported for this input or output.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-expbuf.xml b/Documentation/DocBook/media/v4l/vidioc-expbuf.xml deleted file mode 100644 index 0ae0b6a915d0..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-expbuf.xml +++ /dev/null @@ -1,211 +0,0 @@ -<refentry id="vidioc-expbuf"> - - <refmeta> - <refentrytitle>ioctl VIDIOC_EXPBUF</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_EXPBUF</refname> - <refpurpose>Export a buffer as a DMABUF file descriptor.</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_exportbuffer *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_EXPBUF</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <note> - <title>Experimental</title> - <para>This is an <link linkend="experimental"> experimental </link> - interface and may change in the future.</para> - </note> - -<para>This ioctl is an extension to the <link linkend="mmap">memory -mapping</link> I/O method, therefore it is available only for -<constant>V4L2_MEMORY_MMAP</constant> buffers. It can be used to export a -buffer as a DMABUF file at any time after buffers have been allocated with the -&VIDIOC-REQBUFS; ioctl.</para> - -<para> To export a buffer, applications fill &v4l2-exportbuffer;. The -<structfield>type</structfield> field is set to the same buffer type as was -previously used with &v4l2-requestbuffers; <structfield>type</structfield>. -Applications must also set the <structfield>index</structfield> field. Valid -index numbers range from zero to the number of buffers allocated with -&VIDIOC-REQBUFS; (&v4l2-requestbuffers; <structfield>count</structfield>) -minus one. For the multi-planar API, applications set the <structfield>plane</structfield> -field to the index of the plane to be exported. Valid planes -range from zero to the maximal number of valid planes for the currently active -format. For the single-planar API, applications must set <structfield>plane</structfield> -to zero. Additional flags may be posted in the <structfield>flags</structfield> -field. Refer to a manual for open() for details. -Currently only O_CLOEXEC, O_RDONLY, O_WRONLY, and O_RDWR are supported. All -other fields must be set to zero. -In the case of multi-planar API, every plane is exported separately using -multiple <constant>VIDIOC_EXPBUF</constant> calls.</para> - -<para>After calling <constant>VIDIOC_EXPBUF</constant> the <structfield>fd</structfield> -field will be set by a driver. This is a DMABUF file -descriptor. The application may pass it to other DMABUF-aware devices. Refer to -<link linkend="dmabuf">DMABUF importing</link> for details about importing -DMABUF files into V4L2 nodes. It is recommended to close a DMABUF file when it -is no longer used to allow the associated memory to be reclaimed.</para> - </refsect1> - - <refsect1> - <title>Examples</title> - - <example> - <title>Exporting a buffer.</title> - <programlisting> -int buffer_export(int v4lfd, &v4l2-buf-type; bt, int index, int *dmafd) -{ - &v4l2-exportbuffer; expbuf; - - memset(&expbuf, 0, sizeof(expbuf)); - expbuf.type = bt; - expbuf.index = index; - if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &expbuf) == -1) { - perror("VIDIOC_EXPBUF"); - return -1; - } - - *dmafd = expbuf.fd; - - return 0; -} - </programlisting> - </example> - - <example> - <title>Exporting a buffer using the multi-planar API.</title> - <programlisting> -int buffer_export_mp(int v4lfd, &v4l2-buf-type; bt, int index, - int dmafd[], int n_planes) -{ - int i; - - for (i = 0; i < n_planes; ++i) { - &v4l2-exportbuffer; expbuf; - - memset(&expbuf, 0, sizeof(expbuf)); - expbuf.type = bt; - expbuf.index = index; - expbuf.plane = i; - if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &expbuf) == -1) { - perror("VIDIOC_EXPBUF"); - while (i) - close(dmafd[--i]); - return -1; - } - dmafd[i] = expbuf.fd; - } - - return 0; -} - </programlisting> - </example> - - <table pgwide="1" frame="none" id="v4l2-exportbuffer"> - <title>struct <structname>v4l2_exportbuffer</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry>Type of the buffer, same as &v4l2-format; -<structfield>type</structfield> or &v4l2-requestbuffers; -<structfield>type</structfield>, set by the application. See <xref -linkend="v4l2-buf-type" /></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>index</structfield></entry> - <entry>Number of the buffer, set by the application. This field is -only used for <link linkend="mmap">memory mapping</link> I/O and can range from -zero to the number of buffers allocated with the &VIDIOC-REQBUFS; and/or -&VIDIOC-CREATE-BUFS; ioctls. </entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>plane</structfield></entry> - <entry>Index of the plane to be exported when using the -multi-planar API. Otherwise this value must be set to zero. </entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry>Flags for the newly created file, currently only -<constant>O_CLOEXEC</constant>, <constant>O_RDONLY</constant>, <constant>O_WRONLY</constant>, -and <constant>O_RDWR</constant> are supported, refer to the manual -of open() for more details.</entry> - </row> - <row> - <entry>__s32</entry> - <entry><structfield>fd</structfield></entry> - <entry>The DMABUF file descriptor associated with a buffer. Set by - the driver.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved[11]</structfield></entry> - <entry>Reserved field for future use. Drivers and applications must -set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - </refsect1> - - <refsect1> - &return-value; - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>A queue is not in MMAP mode or DMABUF exporting is not -supported or <structfield>flags</structfield> or <structfield>type</structfield> -or <structfield>index</structfield> or <structfield>plane</structfield> fields -are invalid.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-audio.xml b/Documentation/DocBook/media/v4l/vidioc-g-audio.xml deleted file mode 100644 index d7bb9b3738f6..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-g-audio.xml +++ /dev/null @@ -1,172 +0,0 @@ -<refentry id="vidioc-g-audio"> - <refmeta> - <refentrytitle>ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_G_AUDIO</refname> - <refname>VIDIOC_S_AUDIO</refname> - <refpurpose>Query or select the current audio input and its -attributes</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_audio *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>const struct v4l2_audio *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_G_AUDIO, VIDIOC_S_AUDIO</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>To query the current audio input applications zero out the -<structfield>reserved</structfield> array of a &v4l2-audio; -and call the <constant>VIDIOC_G_AUDIO</constant> ioctl with a pointer -to this structure. Drivers fill the rest of the structure or return an -&EINVAL; when the device has no audio inputs, or none which combine -with the current video input.</para> - - <para>Audio inputs have one writable property, the audio mode. To -select the current audio input <emphasis>and</emphasis> change the -audio mode, applications initialize the -<structfield>index</structfield> and <structfield>mode</structfield> -fields, and the -<structfield>reserved</structfield> array of a -<structname>v4l2_audio</structname> structure and call the -<constant>VIDIOC_S_AUDIO</constant> ioctl. Drivers may switch to a -different audio mode if the request cannot be satisfied. However, this -is a write-only ioctl, it does not return the actual new audio -mode.</para> - - <table pgwide="1" frame="none" id="v4l2-audio"> - <title>struct <structname>v4l2_audio</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>index</structfield></entry> - <entry>Identifies the audio input, set by the -driver or application.</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>name</structfield>[32]</entry> - <entry>Name of the audio input, a NUL-terminated ASCII -string, for example: "Line In". This information is intended for the -user, preferably the connector label on the device itself.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>capability</structfield></entry> - <entry>Audio capability flags, see <xref - linkend="audio-capability" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>mode</structfield></entry> - <entry>Audio mode flags set by drivers and applications (on - <constant>VIDIOC_S_AUDIO</constant> ioctl), see <xref linkend="audio-mode" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[2]</entry> - <entry>Reserved for future extensions. Drivers and -applications must set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="audio-capability"> - <title>Audio Capability Flags</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_AUDCAP_STEREO</constant></entry> - <entry>0x00001</entry> - <entry>This is a stereo input. The flag is intended to -automatically disable stereo recording etc. when the signal is always -monaural. The API provides no means to detect if stereo is -<emphasis>received</emphasis>, unless the audio input belongs to a -tuner.</entry> - </row> - <row> - <entry><constant>V4L2_AUDCAP_AVL</constant></entry> - <entry>0x00002</entry> - <entry>Automatic Volume Level mode is supported.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="audio-mode"> - <title>Audio Mode Flags</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_AUDMODE_AVL</constant></entry> - <entry>0x00001</entry> - <entry>AVL mode is on.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>No audio inputs combine with the current video input, -or the number of the selected audio input is out of bounds or it does -not combine.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-audioout.xml b/Documentation/DocBook/media/v4l/vidioc-g-audioout.xml deleted file mode 100644 index 200a2704a970..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-g-audioout.xml +++ /dev/null @@ -1,138 +0,0 @@ -<refentry id="vidioc-g-audioout"> - <refmeta> - <refentrytitle>ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_G_AUDOUT</refname> - <refname>VIDIOC_S_AUDOUT</refname> - <refpurpose>Query or select the current audio output</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_audioout *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>const struct v4l2_audioout *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>To query the current audio output applications zero out the -<structfield>reserved</structfield> array of a &v4l2-audioout; and -call the <constant>VIDIOC_G_AUDOUT</constant> ioctl with a pointer -to this structure. Drivers fill the rest of the structure or return an -&EINVAL; when the device has no audio inputs, or none which combine -with the current video output.</para> - - <para>Audio outputs have no writable properties. Nevertheless, to -select the current audio output applications can initialize the -<structfield>index</structfield> field and -<structfield>reserved</structfield> array (which in the future may -contain writable properties) of a -<structname>v4l2_audioout</structname> structure and call the -<constant>VIDIOC_S_AUDOUT</constant> ioctl. Drivers switch to the -requested output or return the &EINVAL; when the index is out of -bounds. This is a write-only ioctl, it does not return the current -audio output attributes as <constant>VIDIOC_G_AUDOUT</constant> -does.</para> - - <para>Note connectors on a TV card to loop back the received audio -signal to a sound card are not audio outputs in this sense.</para> - - <table pgwide="1" frame="none" id="v4l2-audioout"> - <title>struct <structname>v4l2_audioout</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>index</structfield></entry> - <entry>Identifies the audio output, set by the -driver or application.</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>name</structfield>[32]</entry> - <entry>Name of the audio output, a NUL-terminated ASCII -string, for example: "Line Out". This information is intended for the -user, preferably the connector label on the device itself.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>capability</structfield></entry> - <entry>Audio capability flags, none defined yet. Drivers -must set this field to zero.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>mode</structfield></entry> - <entry>Audio mode, none defined yet. Drivers and -applications (on <constant>VIDIOC_S_AUDOUT</constant>) must set this -field to zero.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[2]</entry> - <entry>Reserved for future extensions. Drivers and -applications must set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>No audio outputs combine with the current video -output, or the number of the selected audio output is out of bounds or -it does not combine.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-crop.xml b/Documentation/DocBook/media/v4l/vidioc-g-crop.xml deleted file mode 100644 index e6c4efb9e8b4..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-g-crop.xml +++ /dev/null @@ -1,129 +0,0 @@ -<refentry id="vidioc-g-crop"> - <refmeta> - <refentrytitle>ioctl VIDIOC_G_CROP, VIDIOC_S_CROP</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_G_CROP</refname> - <refname>VIDIOC_S_CROP</refname> - <refpurpose>Get or set the current cropping rectangle</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_crop *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>const struct v4l2_crop *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_G_CROP, VIDIOC_S_CROP</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>To query the cropping rectangle size and position -applications set the <structfield>type</structfield> field of a -<structname>v4l2_crop</structname> structure to the respective buffer -(stream) type and call the <constant>VIDIOC_G_CROP</constant> ioctl -with a pointer to this structure. The driver fills the rest of the -structure or returns the &EINVAL; if cropping is not supported.</para> - - <para>To change the cropping rectangle applications initialize the -<structfield>type</structfield> and &v4l2-rect; substructure named -<structfield>c</structfield> of a v4l2_crop structure and call the -<constant>VIDIOC_S_CROP</constant> ioctl with a pointer to this -structure.</para> - -<para>Do not use the multiplanar buffer types. Use <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> -instead of <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant> -and use <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> instead of -<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>.</para> - - <para>The driver first adjusts the requested dimensions against -hardware limits, &ie; the bounds given by the capture/output window, -and it rounds to the closest possible values of horizontal and -vertical offset, width and height. In particular the driver must round -the vertical offset of the cropping rectangle to frame lines modulo -two, such that the field order cannot be confused.</para> - - <para>Second the driver adjusts the image size (the opposite -rectangle of the scaling process, source or target depending on the -data direction) to the closest size possible while maintaining the -current horizontal and vertical scaling factor.</para> - - <para>Finally the driver programs the hardware with the actual -cropping and image parameters. <constant>VIDIOC_S_CROP</constant> is a -write-only ioctl, it does not return the actual parameters. To query -them applications must call <constant>VIDIOC_G_CROP</constant> and -&VIDIOC-G-FMT;. When the parameters are unsuitable the application may -modify the cropping or image parameters and repeat the cycle until -satisfactory parameters have been negotiated.</para> - - <para>When cropping is not supported then no parameters are -changed and <constant>VIDIOC_S_CROP</constant> returns the -&EINVAL;.</para> - - <table pgwide="1" frame="none" id="v4l2-crop"> - <title>struct <structname>v4l2_crop</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry>Type of the data stream, set by the application. -Only these types are valid here: <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>, -<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> and -<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>. See <xref linkend="v4l2-buf-type" />.</entry> - </row> - <row> - <entry>&v4l2-rect;</entry> - <entry><structfield>c</structfield></entry> - <entry>Cropping rectangle. The same co-ordinate system as -for &v4l2-cropcap; <structfield>bounds</structfield> is used.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-ctrl.xml b/Documentation/DocBook/media/v4l/vidioc-g-ctrl.xml deleted file mode 100644 index ee2820d6ca66..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-g-ctrl.xml +++ /dev/null @@ -1,133 +0,0 @@ -<refentry id="vidioc-g-ctrl"> - <refmeta> - <refentrytitle>ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_G_CTRL</refname> - <refname>VIDIOC_S_CTRL</refname> - <refpurpose>Get or set the value of a control</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_control -*<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_G_CTRL, VIDIOC_S_CTRL</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>To get the current value of a control applications -initialize the <structfield>id</structfield> field of a struct -<structname>v4l2_control</structname> and call the -<constant>VIDIOC_G_CTRL</constant> ioctl with a pointer to this -structure. To change the value of a control applications initialize -the <structfield>id</structfield> and <structfield>value</structfield> -fields of a struct <structname>v4l2_control</structname> and call the -<constant>VIDIOC_S_CTRL</constant> ioctl.</para> - - <para>When the <structfield>id</structfield> is invalid drivers -return an &EINVAL;. When the <structfield>value</structfield> is out -of bounds drivers can choose to take the closest valid value or return -an &ERANGE;, whatever seems more appropriate. However, -<constant>VIDIOC_S_CTRL</constant> is a write-only ioctl, it does not -return the actual new value. If the <structfield>value</structfield> -is inappropriate for the control (e.g. if it refers to an unsupported -menu index of a menu control), then &EINVAL; is returned as well.</para> - - <para>These ioctls work only with user controls. For other -control classes the &VIDIOC-G-EXT-CTRLS;, &VIDIOC-S-EXT-CTRLS; or -&VIDIOC-TRY-EXT-CTRLS; must be used.</para> - - <table pgwide="1" frame="none" id="v4l2-control"> - <title>struct <structname>v4l2_control</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>id</structfield></entry> - <entry>Identifies the control, set by the -application.</entry> - </row> - <row> - <entry>__s32</entry> - <entry><structfield>value</structfield></entry> - <entry>New value or current value.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The &v4l2-control; <structfield>id</structfield> is -invalid or the <structfield>value</structfield> is inappropriate for -the given control (i.e. if a menu item is selected that is not supported -by the driver according to &VIDIOC-QUERYMENU;).</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>ERANGE</errorcode></term> - <listitem> - <para>The &v4l2-control; <structfield>value</structfield> -is out of bounds.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EBUSY</errorcode></term> - <listitem> - <para>The control is temporarily not changeable, possibly -because another applications took over control of the device function -this control belongs to.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EACCES</errorcode></term> - <listitem> - <para>Attempt to set a read-only control or to get a - write-only control.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml deleted file mode 100644 index 06952d7cc770..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml +++ /dev/null @@ -1,343 +0,0 @@ -<refentry id="vidioc-g-dv-timings"> - <refmeta> - <refentrytitle>ioctl VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_G_DV_TIMINGS</refname> - <refname>VIDIOC_S_DV_TIMINGS</refname> - <refname>VIDIOC_SUBDEV_G_DV_TIMINGS</refname> - <refname>VIDIOC_SUBDEV_S_DV_TIMINGS</refname> - <refpurpose>Get or set DV timings for input or output</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_dv_timings *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS, VIDIOC_SUBDEV_G_DV_TIMINGS, VIDIOC_SUBDEV_S_DV_TIMINGS</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - <para>To set DV timings for the input or output, applications use the -<constant>VIDIOC_S_DV_TIMINGS</constant> ioctl and to get the current timings, -applications use the <constant>VIDIOC_G_DV_TIMINGS</constant> ioctl. The detailed timing -information is filled in using the structure &v4l2-dv-timings;. These ioctls take -a pointer to the &v4l2-dv-timings; structure as argument. If the ioctl is not supported -or the timing values are not correct, the driver returns &EINVAL;.</para> -<para>The <filename>linux/v4l2-dv-timings.h</filename> header can be used to get the -timings of the formats in the <xref linkend="cea861" /> and <xref linkend="vesadmt" /> -standards. If the current input or output does not support DV timings (e.g. if -&VIDIOC-ENUMINPUT; does not set the <constant>V4L2_IN_CAP_DV_TIMINGS</constant> flag), then -&ENODATA; is returned.</para> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>This ioctl is not supported, or the -<constant>VIDIOC_S_DV_TIMINGS</constant> parameter was unsuitable.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>ENODATA</errorcode></term> - <listitem> - <para>Digital video timings are not supported for this input or output.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EBUSY</errorcode></term> - <listitem> - <para>The device is busy and therefore can not change the timings.</para> - </listitem> - </varlistentry> - </variablelist> - - <table pgwide="1" frame="none" id="v4l2-bt-timings"> - <title>struct <structname>v4l2_bt_timings</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>width</structfield></entry> - <entry>Width of the active video in pixels.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>height</structfield></entry> - <entry>Height of the active video frame in lines. So for interlaced formats the - height of the active video in each field is <structfield>height</structfield>/2.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>interlaced</structfield></entry> - <entry>Progressive (0) or interlaced (1)</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>polarities</structfield></entry> - <entry>This is a bit mask that defines polarities of sync signals. -bit 0 (V4L2_DV_VSYNC_POS_POL) is for vertical sync polarity and bit 1 (V4L2_DV_HSYNC_POS_POL) is for horizontal sync polarity. If the bit is set -(1) it is positive polarity and if is cleared (0), it is negative polarity.</entry> - </row> - <row> - <entry>__u64</entry> - <entry><structfield>pixelclock</structfield></entry> - <entry>Pixel clock in Hz. Ex. 74.25MHz->74250000</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>hfrontporch</structfield></entry> - <entry>Horizontal front porch in pixels</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>hsync</structfield></entry> - <entry>Horizontal sync length in pixels</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>hbackporch</structfield></entry> - <entry>Horizontal back porch in pixels</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>vfrontporch</structfield></entry> - <entry>Vertical front porch in lines. For interlaced formats this refers to the - odd field (aka field 1).</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>vsync</structfield></entry> - <entry>Vertical sync length in lines. For interlaced formats this refers to the - odd field (aka field 1).</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>vbackporch</structfield></entry> - <entry>Vertical back porch in lines. For interlaced formats this refers to the - odd field (aka field 1).</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>il_vfrontporch</structfield></entry> - <entry>Vertical front porch in lines for the even field (aka field 2) of - interlaced field formats. Must be 0 for progressive formats.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>il_vsync</structfield></entry> - <entry>Vertical sync length in lines for the even field (aka field 2) of - interlaced field formats. Must be 0 for progressive formats.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>il_vbackporch</structfield></entry> - <entry>Vertical back porch in lines for the even field (aka field 2) of - interlaced field formats. Must be 0 for progressive formats.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>standards</structfield></entry> - <entry>The video standard(s) this format belongs to. This will be filled in by - the driver. Applications must set this to 0. See <xref linkend="dv-bt-standards"/> - for a list of standards.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry>Several flags giving more information about the format. - See <xref linkend="dv-bt-flags"/> for a description of the flags. - </entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="v4l2-dv-timings"> - <title>struct <structname>v4l2_dv_timings</structname></title> - <tgroup cols="4"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry></entry> - <entry>Type of DV timings as listed in <xref linkend="dv-timing-types"/>.</entry> - </row> - <row> - <entry>union</entry> - <entry><structfield></structfield></entry> - <entry></entry> - </row> - <row> - <entry></entry> - <entry>&v4l2-bt-timings;</entry> - <entry><structfield>bt</structfield></entry> - <entry>Timings defined by BT.656/1120 specifications</entry> - </row> - <row> - <entry></entry> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[32]</entry> - <entry></entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="dv-timing-types"> - <title>DV Timing types</title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>Timing type</entry> - <entry>value</entry> - <entry>Description</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>V4L2_DV_BT_656_1120</entry> - <entry>0</entry> - <entry>BT.656/1120 timings</entry> - </row> - </tbody> - </tgroup> - </table> - <table pgwide="1" frame="none" id="dv-bt-standards"> - <title>DV BT Timing standards</title> - <tgroup cols="2"> - &cs-str; - <tbody valign="top"> - <row> - <entry>Timing standard</entry> - <entry>Description</entry> - </row> - <row> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>V4L2_DV_BT_STD_CEA861</entry> - <entry>The timings follow the CEA-861 Digital TV Profile standard</entry> - </row> - <row> - <entry>V4L2_DV_BT_STD_DMT</entry> - <entry>The timings follow the VESA Discrete Monitor Timings standard</entry> - </row> - <row> - <entry>V4L2_DV_BT_STD_CVT</entry> - <entry>The timings follow the VESA Coordinated Video Timings standard</entry> - </row> - <row> - <entry>V4L2_DV_BT_STD_GTF</entry> - <entry>The timings follow the VESA Generalized Timings Formula standard</entry> - </row> - </tbody> - </tgroup> - </table> - <table pgwide="1" frame="none" id="dv-bt-flags"> - <title>DV BT Timing flags</title> - <tgroup cols="2"> - &cs-str; - <tbody valign="top"> - <row> - <entry>Flag</entry> - <entry>Description</entry> - </row> - <row> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>V4L2_DV_FL_REDUCED_BLANKING</entry> - <entry>CVT/GTF specific: the timings use reduced blanking (CVT) or the 'Secondary -GTF' curve (GTF). In both cases the horizontal and/or vertical blanking -intervals are reduced, allowing a higher resolution over the same -bandwidth. This is a read-only flag, applications must not set this. - </entry> - </row> - <row> - <entry>V4L2_DV_FL_CAN_REDUCE_FPS</entry> - <entry>CEA-861 specific: set for CEA-861 formats with a framerate that is a multiple -of six. These formats can be optionally played at 1 / 1.001 speed to -be compatible with 60 Hz based standards such as NTSC and PAL-M that use a framerate of -29.97 frames per second. If the transmitter can't generate such frequencies, then the -flag will also be cleared. This is a read-only flag, applications must not set this. - </entry> - </row> - <row> - <entry>V4L2_DV_FL_REDUCED_FPS</entry> - <entry>CEA-861 specific: only valid for video transmitters, the flag is cleared -by receivers. It is also only valid for formats with the V4L2_DV_FL_CAN_REDUCE_FPS flag -set, for other formats the flag will be cleared by the driver. - -If the application sets this flag, then the pixelclock used to set up the transmitter is -divided by 1.001 to make it compatible with NTSC framerates. If the transmitter -can't generate such frequencies, then the flag will also be cleared. - </entry> - </row> - <row> - <entry>V4L2_DV_FL_HALF_LINE</entry> - <entry>Specific to interlaced formats: if set, then the vertical frontporch -of field 1 (aka the odd field) is really one half-line longer and the vertical backporch -of field 2 (aka the even field) is really one half-line shorter, so each field has exactly -the same number of half-lines. Whether half-lines can be detected or used depends on -the hardware. - </entry> - </row> - <row> - <entry>V4L2_DV_FL_IS_CE_VIDEO</entry> - <entry>If set, then this is a Consumer Electronics (CE) video format. -Such formats differ from other formats (commonly called IT formats) in that if -R'G'B' encoding is used then by default the R'G'B' values use limited range -(i.e. 16-235) as opposed to full range (i.e. 0-255). All formats defined in CEA-861 -except for the 640x480p59.94 format are CE formats. - </entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-edid.xml b/Documentation/DocBook/media/v4l/vidioc-g-edid.xml deleted file mode 100644 index 2702536bbc7c..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-g-edid.xml +++ /dev/null @@ -1,171 +0,0 @@ -<refentry id="vidioc-g-edid"> - <refmeta> - <refentrytitle>ioctl VIDIOC_G_EDID, VIDIOC_S_EDID</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_G_EDID</refname> - <refname>VIDIOC_S_EDID</refname> - <refname>VIDIOC_SUBDEV_G_EDID</refname> - <refname>VIDIOC_SUBDEV_S_EDID</refname> - <refpurpose>Get or set the EDID of a video receiver/transmitter</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_edid *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_edid *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_G_EDID, VIDIOC_S_EDID, VIDIOC_SUBDEV_G_EDID, VIDIOC_SUBDEV_S_EDID</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - <para>These ioctls can be used to get or set an EDID associated with an input - from a receiver or an output of a transmitter device. They can be - used with subdevice nodes (/dev/v4l-subdevX) or with video nodes (/dev/videoX).</para> - - <para>When used with video nodes the <structfield>pad</structfield> field represents the - input (for video capture devices) or output (for video output devices) index as - is returned by &VIDIOC-ENUMINPUT; and &VIDIOC-ENUMOUTPUT; respectively. When used - with subdevice nodes the <structfield>pad</structfield> field represents the - input or output pad of the subdevice. If there is no EDID support for the given - <structfield>pad</structfield> value, then the &EINVAL; will be returned.</para> - - <para>To get the EDID data the application has to fill in the <structfield>pad</structfield>, - <structfield>start_block</structfield>, <structfield>blocks</structfield> and <structfield>edid</structfield> - fields and call <constant>VIDIOC_G_EDID</constant>. The current EDID from block - <structfield>start_block</structfield> and of size <structfield>blocks</structfield> - will be placed in the memory <structfield>edid</structfield> points to. The <structfield>edid</structfield> - pointer must point to memory at least <structfield>blocks</structfield> * 128 bytes - large (the size of one block is 128 bytes).</para> - - <para>If there are fewer blocks than specified, then the driver will set <structfield>blocks</structfield> - to the actual number of blocks. If there are no EDID blocks available at all, then the error code - ENODATA is set.</para> - - <para>If blocks have to be retrieved from the sink, then this call will block until they - have been read.</para> - - <para>If <structfield>start_block</structfield> and <structfield>blocks</structfield> are - both set to 0 when <constant>VIDIOC_G_EDID</constant> is called, then the driver will - set <structfield>blocks</structfield> to the total number of available EDID blocks - and it will return 0 without copying any data. This is an easy way to discover how many - EDID blocks there are. Note that if there are no EDID blocks available at all, then - the driver will set <structfield>blocks</structfield> to 0 and it returns 0.</para> - - <para>To set the EDID blocks of a receiver the application has to fill in the <structfield>pad</structfield>, - <structfield>blocks</structfield> and <structfield>edid</structfield> fields and set - <structfield>start_block</structfield> to 0. It is not possible to set part of an EDID, - it is always all or nothing. Setting the EDID data is only valid for receivers as it makes - no sense for a transmitter.</para> - - <para>The driver assumes that the full EDID is passed in. If there are more EDID blocks than - the hardware can handle then the EDID is not written, but instead the error code E2BIG is set - and <structfield>blocks</structfield> is set to the maximum that the hardware supports. - If <structfield>start_block</structfield> is any - value other than 0 then the error code EINVAL is set.</para> - - <para>To disable an EDID you set <structfield>blocks</structfield> to 0. Depending on the - hardware this will drive the hotplug pin low and/or block the source from reading the EDID - data in some way. In any case, the end result is the same: the EDID is no longer available. - </para> - - <table pgwide="1" frame="none" id="v4l2-edid"> - <title>struct <structname>v4l2_edid</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>pad</structfield></entry> - <entry>Pad for which to get/set the EDID blocks. When used with a video device - node the pad represents the input or output index as returned by - &VIDIOC-ENUMINPUT; and &VIDIOC-ENUMOUTPUT; respectively.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>start_block</structfield></entry> - <entry>Read the EDID from starting with this block. Must be 0 when setting - the EDID.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>blocks</structfield></entry> - <entry>The number of blocks to get or set. Must be less or equal to 256 (the - maximum number of blocks as defined by the standard). When you set the EDID and - <structfield>blocks</structfield> is 0, then the EDID is disabled or erased.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[5]</entry> - <entry>Reserved for future extensions. Applications and drivers must - set the array to zero.</entry> - </row> - <row> - <entry>__u8 *</entry> - <entry><structfield>edid</structfield></entry> - <entry>Pointer to memory that contains the EDID. The minimum size is - <structfield>blocks</structfield> * 128.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>ENODATA</errorcode></term> - <listitem> - <para>The EDID data is not available.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>E2BIG</errorcode></term> - <listitem> - <para>The EDID data you provided is more than the hardware can handle.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-enc-index.xml b/Documentation/DocBook/media/v4l/vidioc-g-enc-index.xml deleted file mode 100644 index be25029a16f1..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-g-enc-index.xml +++ /dev/null @@ -1,189 +0,0 @@ -<refentry id="vidioc-g-enc-index"> - <refmeta> - <refentrytitle>ioctl VIDIOC_G_ENC_INDEX</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_G_ENC_INDEX</refname> - <refpurpose>Get meta data about a compressed video stream</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_enc_idx *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_G_ENC_INDEX</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>The <constant>VIDIOC_G_ENC_INDEX</constant> ioctl provides -meta data about a compressed video stream the same or another -application currently reads from the driver, which is useful for -random access into the stream without decoding it.</para> - - <para>To read the data applications must call -<constant>VIDIOC_G_ENC_INDEX</constant> with a pointer to a -&v4l2-enc-idx;. On success the driver fills the -<structfield>entry</structfield> array, stores the number of elements -written in the <structfield>entries</structfield> field, and -initializes the <structfield>entries_cap</structfield> field.</para> - - <para>Each element of the <structfield>entry</structfield> array -contains meta data about one picture. A -<constant>VIDIOC_G_ENC_INDEX</constant> call reads up to -<constant>V4L2_ENC_IDX_ENTRIES</constant> entries from a driver -buffer, which can hold up to <structfield>entries_cap</structfield> -entries. This number can be lower or higher than -<constant>V4L2_ENC_IDX_ENTRIES</constant>, but not zero. When the -application fails to read the meta data in time the oldest entries -will be lost. When the buffer is empty or no capturing/encoding is in -progress, <structfield>entries</structfield> will be zero.</para> - - <para>Currently this ioctl is only defined for MPEG-2 program -streams and video elementary streams.</para> - - <table pgwide="1" frame="none" id="v4l2-enc-idx"> - <title>struct <structname>v4l2_enc_idx</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>entries</structfield></entry> - <entry>The number of entries the driver stored in the -<structfield>entry</structfield> array.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>entries_cap</structfield></entry> - <entry>The number of entries the driver can -buffer. Must be greater than zero.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[4]</entry> - <entry spanname="hspan">Reserved for future extensions. -Drivers must set the array to zero.</entry> - </row> - <row> - <entry>&v4l2-enc-idx-entry;</entry> - <entry><structfield>entry</structfield>[<constant>V4L2_ENC_IDX_ENTRIES</constant>]</entry> - <entry>Meta data about a compressed video stream. Each -element of the array corresponds to one picture, sorted in ascending -order by their <structfield>offset</structfield>.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="v4l2-enc-idx-entry"> - <title>struct <structname>v4l2_enc_idx_entry</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u64</entry> - <entry><structfield>offset</structfield></entry> - <entry>The offset in bytes from the beginning of the -compressed video stream to the beginning of this picture, that is a -<wordasword>PES packet header</wordasword> as defined in <xref - linkend="mpeg2part1" /> or a <wordasword>picture -header</wordasword> as defined in <xref linkend="mpeg2part2" />. When -the encoder is stopped, the driver resets the offset to zero.</entry> - </row> - <row> - <entry>__u64</entry> - <entry><structfield>pts</structfield></entry> - <entry>The 33 bit <wordasword>Presentation Time -Stamp</wordasword> of this picture as defined in <xref - linkend="mpeg2part1" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>length</structfield></entry> - <entry>The length of this picture in bytes.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry>Flags containing the coding type of this picture, see <xref - linkend="enc-idx-flags" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[2]</entry> - <entry>Reserved for future extensions. -Drivers must set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="enc-idx-flags"> - <title>Index Entry Flags</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_ENC_IDX_FRAME_I</constant></entry> - <entry>0x00</entry> - <entry>This is an Intra-coded picture.</entry> - </row> - <row> - <entry><constant>V4L2_ENC_IDX_FRAME_P</constant></entry> - <entry>0x01</entry> - <entry>This is a Predictive-coded picture.</entry> - </row> - <row> - <entry><constant>V4L2_ENC_IDX_FRAME_B</constant></entry> - <entry>0x02</entry> - <entry>This is a Bidirectionally predictive-coded -picture.</entry> - </row> - <row> - <entry><constant>V4L2_ENC_IDX_FRAME_MASK</constant></entry> - <entry>0x0F</entry> - <entry><wordasword>AND</wordasword> the flags field with -this mask to obtain the picture coding type.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml deleted file mode 100644 index eb82f7e7d06b..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml +++ /dev/null @@ -1,456 +0,0 @@ -<refentry id="vidioc-g-ext-ctrls"> - <refmeta> - <refentrytitle>ioctl VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, -VIDIOC_TRY_EXT_CTRLS</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_G_EXT_CTRLS</refname> - <refname>VIDIOC_S_EXT_CTRLS</refname> - <refname>VIDIOC_TRY_EXT_CTRLS</refname> - <refpurpose>Get or set the value of several controls, try control -values</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_ext_controls -*<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, -VIDIOC_TRY_EXT_CTRLS</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>These ioctls allow the caller to get or set multiple -controls atomically. Control IDs are grouped into control classes (see -<xref linkend="ctrl-class" />) and all controls in the control array -must belong to the same control class.</para> - - <para>Applications must always fill in the -<structfield>count</structfield>, -<structfield>which</structfield>, -<structfield>controls</structfield> and -<structfield>reserved</structfield> fields of &v4l2-ext-controls;, and -initialize the &v4l2-ext-control; array pointed to by the -<structfield>controls</structfield> fields.</para> - - <para>To get the current value of a set of controls applications -initialize the <structfield>id</structfield>, -<structfield>size</structfield> and <structfield>reserved2</structfield> fields -of each &v4l2-ext-control; and call the -<constant>VIDIOC_G_EXT_CTRLS</constant> ioctl. String controls controls -must also set the <structfield>string</structfield> field. Controls -of compound types (<constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is set) -must set the <structfield>ptr</structfield> field.</para> - - <para>If the <structfield>size</structfield> is too small to -receive the control result (only relevant for pointer-type controls -like strings), then the driver will set <structfield>size</structfield> -to a valid value and return an &ENOSPC;. You should re-allocate the -memory to this new size and try again. For the string type it is possible that -the same issue occurs again if the string has grown in the meantime. It is -recommended to call &VIDIOC-QUERYCTRL; first and use -<structfield>maximum</structfield>+1 as the new <structfield>size</structfield> -value. It is guaranteed that that is sufficient memory. -</para> - - <para>N-dimensional arrays are set and retrieved row-by-row. You cannot set a partial -array, all elements have to be set or retrieved. The total size is calculated -as <structfield>elems</structfield> * <structfield>elem_size</structfield>. -These values can be obtained by calling &VIDIOC-QUERY-EXT-CTRL;.</para> - - <para>To change the value of a set of controls applications -initialize the <structfield>id</structfield>, <structfield>size</structfield>, -<structfield>reserved2</structfield> and -<structfield>value/value64/string/ptr</structfield> fields of each &v4l2-ext-control; and -call the <constant>VIDIOC_S_EXT_CTRLS</constant> ioctl. The controls -will only be set if <emphasis>all</emphasis> control values are -valid.</para> - - <para>To check if a set of controls have correct values applications -initialize the <structfield>id</structfield>, <structfield>size</structfield>, -<structfield>reserved2</structfield> and -<structfield>value/value64/string/ptr</structfield> fields of each &v4l2-ext-control; and -call the <constant>VIDIOC_TRY_EXT_CTRLS</constant> ioctl. It is up to -the driver whether wrong values are automatically adjusted to a valid -value or if an error is returned.</para> - - <para>When the <structfield>id</structfield> or -<structfield>which</structfield> is invalid drivers return an -&EINVAL;. When the value is out of bounds drivers can choose to take -the closest valid value or return an &ERANGE;, whatever seems more -appropriate. In the first case the new value is set in -&v4l2-ext-control;. If the new control value is inappropriate (e.g. the -given menu index is not supported by the menu control), then this will -also result in an &EINVAL; error.</para> - - <para>The driver will only set/get these controls if all control -values are correct. This prevents the situation where only some of the -controls were set/get. Only low-level errors (⪚ a failed i2c -command) can still cause this situation.</para> - - <table pgwide="1" frame="none" id="v4l2-ext-control"> - <title>struct <structname>v4l2_ext_control</structname></title> - <tgroup cols="4"> - &cs-ustr; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>id</structfield></entry> - <entry></entry> - <entry>Identifies the control, set by the -application.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>size</structfield></entry> - <entry></entry> - <entry>The total size in bytes of the payload of this -control. This is normally 0, but for pointer controls this should be -set to the size of the memory containing the payload, or that will -receive the payload. If <constant>VIDIOC_G_EXT_CTRLS</constant> finds -that this value is less than is required to store -the payload result, then it is set to a value large enough to store the -payload result and ENOSPC is returned. Note that for string controls -this <structfield>size</structfield> field should not be confused with the length of the string. -This field refers to the size of the memory that contains the string. -The actual <emphasis>length</emphasis> of the string may well be much smaller. -</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved2</structfield>[1]</entry> - <entry></entry> - <entry>Reserved for future extensions. Drivers and -applications must set the array to zero.</entry> - </row> - <row> - <entry>union</entry> - <entry>(anonymous)</entry> - </row> - <row> - <entry></entry> - <entry>__s32</entry> - <entry><structfield>value</structfield></entry> - <entry>New value or current value. Valid if this control is not of -type <constant>V4L2_CTRL_TYPE_INTEGER64</constant> and -<constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is not set.</entry> - </row> - <row> - <entry></entry> - <entry>__s64</entry> - <entry><structfield>value64</structfield></entry> - <entry>New value or current value. Valid if this control is of -type <constant>V4L2_CTRL_TYPE_INTEGER64</constant> and -<constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is not set.</entry> - </row> - <row> - <entry></entry> - <entry>char *</entry> - <entry><structfield>string</structfield></entry> - <entry>A pointer to a string. Valid if this control is of -type <constant>V4L2_CTRL_TYPE_STRING</constant>.</entry> - </row> - <row> - <entry></entry> - <entry>__u8 *</entry> - <entry><structfield>p_u8</structfield></entry> - <entry>A pointer to a matrix control of unsigned 8-bit values. -Valid if this control is of type <constant>V4L2_CTRL_TYPE_U8</constant>.</entry> - </row> - <row> - <entry></entry> - <entry>__u16 *</entry> - <entry><structfield>p_u16</structfield></entry> - <entry>A pointer to a matrix control of unsigned 16-bit values. -Valid if this control is of type <constant>V4L2_CTRL_TYPE_U16</constant>.</entry> - </row> - <row> - <entry></entry> - <entry>__u32 *</entry> - <entry><structfield>p_u32</structfield></entry> - <entry>A pointer to a matrix control of unsigned 32-bit values. -Valid if this control is of type <constant>V4L2_CTRL_TYPE_U32</constant>.</entry> - </row> - <row> - <entry></entry> - <entry>void *</entry> - <entry><structfield>ptr</structfield></entry> - <entry>A pointer to a compound type which can be an N-dimensional array and/or a -compound type (the control's type is >= <constant>V4L2_CTRL_COMPOUND_TYPES</constant>). -Valid if <constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is set for this control. -</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="v4l2-ext-controls"> - <title>struct <structname>v4l2_ext_controls</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>union</entry> - <entry>(anonymous)</entry> - </row> - <row> - <entry></entry> - <entry>__u32</entry> - <entry><structfield>ctrl_class</structfield></entry> - <entry>The control class to which all controls belong, see -<xref linkend="ctrl-class" />. Drivers that use a kernel framework for handling -controls will also accept a value of 0 here, meaning that the controls can -belong to any control class. Whether drivers support this can be tested by setting -<structfield>ctrl_class</structfield> to 0 and calling <constant>VIDIOC_TRY_EXT_CTRLS</constant> -with a <structfield>count</structfield> of 0. If that succeeds, then the driver -supports this feature.</entry> - </row> - <row> - <entry></entry> - <entry>__u32</entry> - <entry><structfield>which</structfield></entry> - <entry><para>Which value of the control to get/set/try. <constant>V4L2_CTRL_WHICH_CUR_VAL</constant> -will return the current value of the control and <constant>V4L2_CTRL_WHICH_DEF_VAL</constant> will -return the default value of the control. Please note that you can only get the default value of the -control, you cannot set or try it.</para> -<para>For backwards compatibility you can also use a control class here (see -<xref linkend="ctrl-class" />). In that case all controls have to belong to that -control class. This usage is deprecated, instead just use <constant>V4L2_CTRL_WHICH_CUR_VAL</constant>. -There are some very old drivers that do not yet support <constant>V4L2_CTRL_WHICH_CUR_VAL</constant> -and that require a control class here. You can test for such drivers by setting ctrl_class to -<constant>V4L2_CTRL_WHICH_CUR_VAL</constant> and calling VIDIOC_TRY_EXT_CTRLS with a count of 0. -If that fails, then the driver does not support <constant>V4L2_CTRL_WHICH_CUR_VAL</constant>.</para> -</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>count</structfield></entry> - <entry>The number of controls in the controls array. May -also be zero.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>error_idx</structfield></entry> - <entry><para>Set by the driver in case of an error. If the error is -associated with a particular control, then <structfield>error_idx</structfield> -is set to the index of that control. If the error is not related to a specific -control, or the validation step failed (see below), then -<structfield>error_idx</structfield> is set to <structfield>count</structfield>. -The value is undefined if the ioctl returned 0 (success).</para> - -<para>Before controls are read from/written to hardware a validation step -takes place: this checks if all controls in the list are valid controls, -if no attempt is made to write to a read-only control or read from a write-only -control, and any other up-front checks that can be done without accessing the -hardware. The exact validations done during this step are driver dependent -since some checks might require hardware access for some devices, thus making -it impossible to do those checks up-front. However, drivers should make a -best-effort to do as many up-front checks as possible.</para> - -<para>This check is done to avoid leaving the hardware in an inconsistent state due -to easy-to-avoid problems. But it leads to another problem: the application needs to -know whether an error came from the validation step (meaning that the hardware -was not touched) or from an error during the actual reading from/writing to hardware.</para> - -<para>The, in hindsight quite poor, solution for that is to set <structfield>error_idx</structfield> -to <structfield>count</structfield> if the validation failed. This has the -unfortunate side-effect that it is not possible to see which control failed the -validation. If the validation was successful and the error happened while -accessing the hardware, then <structfield>error_idx</structfield> is less than -<structfield>count</structfield> and only the controls up to -<structfield>error_idx-1</structfield> were read or written correctly, and the -state of the remaining controls is undefined.</para> - -<para>Since <constant>VIDIOC_TRY_EXT_CTRLS</constant> does not access hardware -there is also no need to handle the validation step in this special way, -so <structfield>error_idx</structfield> will just be set to the control that -failed the validation step instead of to <structfield>count</structfield>. -This means that if <constant>VIDIOC_S_EXT_CTRLS</constant> fails with -<structfield>error_idx</structfield> set to <structfield>count</structfield>, -then you can call <constant>VIDIOC_TRY_EXT_CTRLS</constant> to try to discover -the actual control that failed the validation step. Unfortunately, there -is no <constant>TRY</constant> equivalent for <constant>VIDIOC_G_EXT_CTRLS</constant>. -</para></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[2]</entry> - <entry>Reserved for future extensions. Drivers and -applications must set the array to zero.</entry> - </row> - <row> - <entry>&v4l2-ext-control; *</entry> - <entry><structfield>controls</structfield></entry> - <entry>Pointer to an array of -<structfield>count</structfield> v4l2_ext_control structures. Ignored -if <structfield>count</structfield> equals zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="ctrl-class"> - <title>Control classes</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_CTRL_CLASS_USER</constant></entry> - <entry>0x980000</entry> - <entry>The class containing user controls. These controls -are described in <xref linkend="control" />. All controls that can be set -using the &VIDIOC-S-CTRL; and &VIDIOC-G-CTRL; ioctl belong to this -class.</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_CLASS_MPEG</constant></entry> - <entry>0x990000</entry> - <entry>The class containing MPEG compression controls. -These controls are described in <xref - linkend="mpeg-controls" />.</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_CLASS_CAMERA</constant></entry> - <entry>0x9a0000</entry> - <entry>The class containing camera controls. -These controls are described in <xref - linkend="camera-controls" />.</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_CLASS_FM_TX</constant></entry> - <entry>0x9b0000</entry> - <entry>The class containing FM Transmitter (FM TX) controls. -These controls are described in <xref - linkend="fm-tx-controls" />.</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_CLASS_FLASH</constant></entry> - <entry>0x9c0000</entry> - <entry>The class containing flash device controls. -These controls are described in <xref - linkend="flash-controls" />.</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_CLASS_JPEG</constant></entry> - <entry>0x9d0000</entry> - <entry>The class containing JPEG compression controls. -These controls are described in <xref - linkend="jpeg-controls" />.</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_CLASS_IMAGE_SOURCE</constant></entry> - <entry>0x9e0000</entry> <entry>The class containing image - source controls. These controls are described in <xref - linkend="image-source-controls" />.</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_CLASS_IMAGE_PROC</constant></entry> - <entry>0x9f0000</entry> <entry>The class containing image - processing controls. These controls are described in <xref - linkend="image-process-controls" />.</entry> - </row> - - <row> - <entry><constant>V4L2_CTRL_CLASS_FM_RX</constant></entry> - <entry>0xa10000</entry> - <entry>The class containing FM Receiver (FM RX) controls. -These controls are described in <xref - linkend="fm-rx-controls" />.</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_CLASS_RF_TUNER</constant></entry> - <entry>0xa20000</entry> - <entry>The class containing RF tuner controls. -These controls are described in <xref linkend="rf-tuner-controls" />.</entry> - </row> - </tbody> - </tgroup> - </table> - - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The &v4l2-ext-control; <structfield>id</structfield> -is invalid, the &v4l2-ext-controls; -<structfield>which</structfield> is invalid, or the &v4l2-ext-control; -<structfield>value</structfield> was inappropriate (e.g. the given menu -index is not supported by the driver). This error code is -also returned by the <constant>VIDIOC_S_EXT_CTRLS</constant> and -<constant>VIDIOC_TRY_EXT_CTRLS</constant> ioctls if two or more -control values are in conflict.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>ERANGE</errorcode></term> - <listitem> - <para>The &v4l2-ext-control; <structfield>value</structfield> -is out of bounds.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EBUSY</errorcode></term> - <listitem> - <para>The control is temporarily not changeable, possibly -because another applications took over control of the device function -this control belongs to.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>ENOSPC</errorcode></term> - <listitem> - <para>The space reserved for the control's payload is insufficient. -The field <structfield>size</structfield> is set to a value that is enough -to store the payload and this error code is returned.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EACCES</errorcode></term> - <listitem> - <para>Attempt to try or set a read-only control or to get a - write-only control.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> - diff --git a/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml b/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml deleted file mode 100644 index 77607cc19688..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml +++ /dev/null @@ -1,459 +0,0 @@ -<refentry id="vidioc-g-fbuf"> - <refmeta> - <refentrytitle>ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_G_FBUF</refname> - <refname>VIDIOC_S_FBUF</refname> - <refpurpose>Get or set frame buffer overlay parameters</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_framebuffer *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>const struct v4l2_framebuffer *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_G_FBUF, VIDIOC_S_FBUF</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>Applications can use the <constant>VIDIOC_G_FBUF</constant> and -<constant>VIDIOC_S_FBUF</constant> ioctl to get and set the -framebuffer parameters for a <link linkend="overlay">Video -Overlay</link> or <link linkend="osd">Video Output Overlay</link> -(OSD). The type of overlay is implied by the device type (capture or -output device) and can be determined with the &VIDIOC-QUERYCAP; ioctl. -One <filename>/dev/videoN</filename> device must not support both -kinds of overlay.</para> - - <para>The V4L2 API distinguishes destructive and non-destructive -overlays. A destructive overlay copies captured video images into the -video memory of a graphics card. A non-destructive overlay blends -video images into a VGA signal or graphics into a video signal. -<wordasword>Video Output Overlays</wordasword> are always -non-destructive.</para> - - <para>To get the current parameters applications call the -<constant>VIDIOC_G_FBUF</constant> ioctl with a pointer to a -<structname>v4l2_framebuffer</structname> structure. The driver fills -all fields of the structure or returns an &EINVAL; when overlays are -not supported.</para> - - <para>To set the parameters for a <wordasword>Video Output -Overlay</wordasword>, applications must initialize the -<structfield>flags</structfield> field of a struct -<structname>v4l2_framebuffer</structname>. Since the framebuffer is -implemented on the TV card all other parameters are determined by the -driver. When an application calls <constant>VIDIOC_S_FBUF</constant> -with a pointer to this structure, the driver prepares for the overlay -and returns the framebuffer parameters as -<constant>VIDIOC_G_FBUF</constant> does, or it returns an error -code.</para> - - <para>To set the parameters for a <wordasword>non-destructive -Video Overlay</wordasword>, applications must initialize the -<structfield>flags</structfield> field, the -<structfield>fmt</structfield> substructure, and call -<constant>VIDIOC_S_FBUF</constant>. Again the driver prepares for the -overlay and returns the framebuffer parameters as -<constant>VIDIOC_G_FBUF</constant> does, or it returns an error -code.</para> - - <para>For a <wordasword>destructive Video Overlay</wordasword> -applications must additionally provide a -<structfield>base</structfield> address. Setting up a DMA to a -random memory location can jeopardize the system security, its -stability or even damage the hardware, therefore only the superuser -can set the parameters for a destructive video overlay.</para> - - <!-- NB v4l2_pix_format is also specified in pixfmt.sgml.--> - - <table pgwide="1" frame="none" id="v4l2-framebuffer"> - <title>struct <structname>v4l2_framebuffer</structname></title> - <tgroup cols="4"> - &cs-ustr; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>capability</structfield></entry> - <entry></entry> - <entry>Overlay capability flags set by the driver, see -<xref linkend="framebuffer-cap" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry></entry> - <entry>Overlay control flags set by application and -driver, see <xref linkend="framebuffer-flags" /></entry> - </row> - <row> - <entry>void *</entry> - <entry><structfield>base</structfield></entry> - <entry></entry> - <entry>Physical base address of the framebuffer, -that is the address of the pixel in the top left corner of the -framebuffer.<footnote><para>A physical base address may not suit all -platforms. GK notes in theory we should pass something like PCI device -+ memory region + offset instead. If you encounter problems please -discuss on the linux-media mailing list: &v4l-ml;.</para></footnote></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - <entry>This field is irrelevant to -<wordasword>non-destructive Video Overlays</wordasword>. For -<wordasword>destructive Video Overlays</wordasword> applications must -provide a base address. The driver may accept only base addresses -which are a multiple of two, four or eight bytes. For -<wordasword>Video Output Overlays</wordasword> the driver must return -a valid base address, so applications can find the corresponding Linux -framebuffer device (see <xref linkend="osd" />).</entry> - </row> - <row> - <entry>struct</entry> - <entry><structfield>fmt</structfield></entry> - <entry></entry> - <entry>Layout of the frame buffer.</entry> - </row> - <row> - <entry></entry> - <entry>__u32</entry> - <entry><structfield>width</structfield></entry> - <entry>Width of the frame buffer in pixels.</entry> - </row> - <row> - <entry></entry> - <entry>__u32</entry> - <entry><structfield>height</structfield></entry> - <entry>Height of the frame buffer in pixels.</entry> - </row> - <row> - <entry></entry> - <entry>__u32</entry> - <entry><structfield>pixelformat</structfield></entry> - <entry>The pixel format of the -framebuffer.</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - <entry>For <wordasword>non-destructive Video -Overlays</wordasword> this field only defines a format for the -&v4l2-window; <structfield>chromakey</structfield> field.</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - <entry>For <wordasword>destructive Video -Overlays</wordasword> applications must initialize this field. For -<wordasword>Video Output Overlays</wordasword> the driver must return -a valid format.</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - <entry>Usually this is an RGB format (for example -<link linkend="V4L2-PIX-FMT-RGB565"><constant>V4L2_PIX_FMT_RGB565</constant></link>) -but YUV formats (only packed YUV formats when chroma keying is used, -not including <constant>V4L2_PIX_FMT_YUYV</constant> and -<constant>V4L2_PIX_FMT_UYVY</constant>) and the -<constant>V4L2_PIX_FMT_PAL8</constant> format are also permitted. The -behavior of the driver when an application requests a compressed -format is undefined. See <xref linkend="pixfmt" /> for information on -pixel formats.</entry> - </row> - <row> - <entry></entry> - <entry>&v4l2-field;</entry> - <entry><structfield>field</structfield></entry> - <entry>Drivers and applications shall ignore this field. -If applicable, the field order is selected with the &VIDIOC-S-FMT; -ioctl, using the <structfield>field</structfield> field of -&v4l2-window;.</entry> - </row> - <row> - <entry></entry> - <entry>__u32</entry> - <entry><structfield>bytesperline</structfield></entry> - <entry>Distance in bytes between the leftmost pixels in -two adjacent lines.</entry> - </row> - <row> - <entry spanname="hspan"><para>This field is irrelevant to -<wordasword>non-destructive Video -Overlays</wordasword>.</para><para>For <wordasword>destructive Video -Overlays</wordasword> both applications and drivers can set this field -to request padding bytes at the end of each line. Drivers however may -ignore the requested value, returning <structfield>width</structfield> -times bytes-per-pixel or a larger value required by the hardware. That -implies applications can just set this field to zero to get a -reasonable default.</para><para>For <wordasword>Video Output -Overlays</wordasword> the driver must return a valid -value.</para><para>Video hardware may access padding bytes, therefore -they must reside in accessible memory. Consider for example the case -where padding bytes after the last line of an image cross a system -page boundary. Capture devices may write padding bytes, the value is -undefined. Output devices ignore the contents of padding -bytes.</para><para>When the image format is planar the -<structfield>bytesperline</structfield> value applies to the first -plane and is divided by the same factor as the -<structfield>width</structfield> field for the other planes. For -example the Cb and Cr planes of a YUV 4:2:0 image have half as many -padding bytes following each line as the Y plane. To avoid ambiguities -drivers must return a <structfield>bytesperline</structfield> value -rounded up to a multiple of the scale factor.</para></entry> - </row> - <row> - <entry></entry> - <entry>__u32</entry> - <entry><structfield>sizeimage</structfield></entry> - <entry><para>This field is irrelevant to -<wordasword>non-destructive Video Overlays</wordasword>. For -<wordasword>destructive Video Overlays</wordasword> applications must -initialize this field. For <wordasword>Video Output -Overlays</wordasword> the driver must return a valid -format.</para><para>Together with <structfield>base</structfield> it -defines the framebuffer memory accessible by the -driver.</para></entry> - </row> - <row> - <entry></entry> - <entry>&v4l2-colorspace;</entry> - <entry><structfield>colorspace</structfield></entry> - <entry>This information supplements the -<structfield>pixelformat</structfield> and must be set by the driver, -see <xref linkend="colorspaces" />.</entry> - </row> - <row> - <entry></entry> - <entry>__u32</entry> - <entry><structfield>priv</structfield></entry> - <entry>Reserved. Drivers and applications must set this field to -zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="framebuffer-cap"> - <title>Frame Buffer Capability Flags</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant></entry> - <entry>0x0001</entry> - <entry>The device is capable of non-destructive overlays. -When the driver clears this flag, only destructive overlays are -supported. There are no drivers yet which support both destructive and -non-destructive overlays. Video Output Overlays are in practice always -non-destructive.</entry> - </row> - <row> - <entry><constant>V4L2_FBUF_CAP_CHROMAKEY</constant></entry> - <entry>0x0002</entry> - <entry>The device supports clipping by chroma-keying the -images. That is, image pixels replace pixels in the VGA or video -signal only where the latter assume a certain color. Chroma-keying -makes no sense for destructive overlays.</entry> - </row> - <row> - <entry><constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant></entry> - <entry>0x0004</entry> - <entry>The device supports clipping using a list of clip -rectangles.</entry> - </row> - <row> - <entry><constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant></entry> - <entry>0x0008</entry> - <entry>The device supports clipping using a bit mask.</entry> - </row> - <row> - <entry><constant>V4L2_FBUF_CAP_LOCAL_ALPHA</constant></entry> - <entry>0x0010</entry> - <entry>The device supports clipping/blending using the -alpha channel of the framebuffer or VGA signal. Alpha blending makes -no sense for destructive overlays.</entry> - </row> - <row> - <entry><constant>V4L2_FBUF_CAP_GLOBAL_ALPHA</constant></entry> - <entry>0x0020</entry> - <entry>The device supports alpha blending using a global -alpha value. Alpha blending makes no sense for destructive overlays.</entry> - </row> - <row> - <entry><constant>V4L2_FBUF_CAP_LOCAL_INV_ALPHA</constant></entry> - <entry>0x0040</entry> - <entry>The device supports clipping/blending using the -inverted alpha channel of the framebuffer or VGA signal. Alpha -blending makes no sense for destructive overlays.</entry> - </row> - <row> - <entry><constant>V4L2_FBUF_CAP_SRC_CHROMAKEY</constant></entry> - <entry>0x0080</entry> - <entry>The device supports Source Chroma-keying. Video pixels -with the chroma-key colors are replaced by framebuffer pixels, which is exactly opposite of -<constant>V4L2_FBUF_CAP_CHROMAKEY</constant></entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="framebuffer-flags"> - <title>Frame Buffer Flags</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_FBUF_FLAG_PRIMARY</constant></entry> - <entry>0x0001</entry> - <entry>The framebuffer is the primary graphics surface. -In other words, the overlay is destructive. This flag is typically set by any -driver that doesn't have the <constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant> -capability and it is cleared otherwise.</entry> - </row> - <row> - <entry><constant>V4L2_FBUF_FLAG_OVERLAY</constant></entry> - <entry>0x0002</entry> - <entry>If this flag is set for a video capture device, then the -driver will set the initial overlay size to cover the full framebuffer size, -otherwise the existing overlay size (as set by &VIDIOC-S-FMT;) will be used. - -Only one video capture driver (bttv) supports this flag. The use of this flag -for capture devices is deprecated. There is no way to detect which drivers -support this flag, so the only reliable method of setting the overlay size is -through &VIDIOC-S-FMT;. - -If this flag is set for a video output device, then the video output overlay -window is relative to the top-left corner of the framebuffer and restricted -to the size of the framebuffer. If it is cleared, then the video output -overlay window is relative to the video output display. - </entry> - </row> - <row> - <entry><constant>V4L2_FBUF_FLAG_CHROMAKEY</constant></entry> - <entry>0x0004</entry> - <entry>Use chroma-keying. The chroma-key color is -determined by the <structfield>chromakey</structfield> field of -&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref - linkend="overlay" /> -and - <xref linkend="osd" />.</entry> - </row> - <row> - <entry spanname="hspan">There are no flags to enable -clipping using a list of clip rectangles or a bitmap. These methods -are negotiated with the &VIDIOC-S-FMT; ioctl, see <xref - linkend="overlay" /> and <xref linkend="osd" />.</entry> - </row> - <row> - <entry><constant>V4L2_FBUF_FLAG_LOCAL_ALPHA</constant></entry> - <entry>0x0008</entry> - <entry>Use the alpha channel of the framebuffer to clip or -blend framebuffer pixels with video images. The blend -function is: output = framebuffer pixel * alpha + video pixel * (1 - -alpha). The actual alpha depth depends on the framebuffer pixel -format.</entry> - </row> - <row> - <entry><constant>V4L2_FBUF_FLAG_GLOBAL_ALPHA</constant></entry> - <entry>0x0010</entry> - <entry>Use a global alpha value to blend the framebuffer -with video images. The blend function is: output = (framebuffer pixel -* alpha + video pixel * (255 - alpha)) / 255. The alpha value is -determined by the <structfield>global_alpha</structfield> field of -&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref - linkend="overlay" /> -and <xref linkend="osd" />.</entry> - </row> - <row> - <entry><constant>V4L2_FBUF_FLAG_LOCAL_INV_ALPHA</constant></entry> - <entry>0x0020</entry> - <entry>Like -<constant>V4L2_FBUF_FLAG_LOCAL_ALPHA</constant>, use the alpha channel -of the framebuffer to clip or blend framebuffer pixels with video -images, but with an inverted alpha value. The blend function is: -output = framebuffer pixel * (1 - alpha) + video pixel * alpha. The -actual alpha depth depends on the framebuffer pixel format.</entry> - </row> - <row> - <entry><constant>V4L2_FBUF_FLAG_SRC_CHROMAKEY</constant></entry> - <entry>0x0040</entry> - <entry>Use source chroma-keying. The source chroma-key color is -determined by the <structfield>chromakey</structfield> field of -&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref -linkend="overlay" /> and <xref linkend="osd" />. -Both chroma-keying are mutual exclusive to each other, so same -<structfield>chromakey</structfield> field of &v4l2-window; is being used.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EPERM</errorcode></term> - <listitem> - <para><constant>VIDIOC_S_FBUF</constant> can only be called -by a privileged user to negotiate the parameters for a destructive -overlay.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The <constant>VIDIOC_S_FBUF</constant> parameters are unsuitable.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml b/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml deleted file mode 100644 index ffcb448251f0..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml +++ /dev/null @@ -1,204 +0,0 @@ -<refentry id="vidioc-g-fmt"> - <refmeta> - <refentrytitle>ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, -VIDIOC_TRY_FMT</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_G_FMT</refname> - <refname>VIDIOC_S_FMT</refname> - <refname>VIDIOC_TRY_FMT</refname> - <refpurpose>Get or set the data format, try a format</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_format -*<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>These ioctls are used to negotiate the format of data -(typically image format) exchanged between driver and -application.</para> - - <para>To query the current parameters applications set the -<structfield>type</structfield> field of a struct -<structname>v4l2_format</structname> to the respective buffer (stream) -type. For example video capture devices use -<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> or -<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>. When the application -calls the <constant>VIDIOC_G_FMT</constant> ioctl with a pointer to -this structure the driver fills the respective member of the -<structfield>fmt</structfield> union. In case of video capture devices -that is either the &v4l2-pix-format; <structfield>pix</structfield> or -the &v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member. -When the requested buffer type is not supported drivers return an -&EINVAL;.</para> - - <para>To change the current format parameters applications -initialize the <structfield>type</structfield> field and all -fields of the respective <structfield>fmt</structfield> -union member. For details see the documentation of the various devices -types in <xref linkend="devices" />. Good practice is to query the -current parameters first, and to -modify only those parameters not suitable for the application. When -the application calls the <constant>VIDIOC_S_FMT</constant> ioctl -with a pointer to a <structname>v4l2_format</structname> structure -the driver checks -and adjusts the parameters against hardware abilities. Drivers -should not return an error code unless the <structfield>type</structfield> field is invalid, this is -a mechanism to fathom device capabilities and to approach parameters -acceptable for both the application and driver. On success the driver -may program the hardware, allocate resources and generally prepare for -data exchange. -Finally the <constant>VIDIOC_S_FMT</constant> ioctl returns the -current format parameters as <constant>VIDIOC_G_FMT</constant> does. -Very simple, inflexible devices may even ignore all input and always -return the default parameters. However all V4L2 devices exchanging -data with the application must implement the -<constant>VIDIOC_G_FMT</constant> and -<constant>VIDIOC_S_FMT</constant> ioctl. When the requested buffer -type is not supported drivers return an &EINVAL; on a -<constant>VIDIOC_S_FMT</constant> attempt. When I/O is already in -progress or the resource is not available for other reasons drivers -return the &EBUSY;.</para> - - <para>The <constant>VIDIOC_TRY_FMT</constant> ioctl is equivalent -to <constant>VIDIOC_S_FMT</constant> with one exception: it does not -change driver state. It can also be called at any time, never -returning <errorcode>EBUSY</errorcode>. This function is provided to -negotiate parameters, to learn about hardware limitations, without -disabling I/O or possibly time consuming hardware preparations. -Although strongly recommended drivers are not required to implement -this ioctl.</para> - - <para>The format as returned by <constant>VIDIOC_TRY_FMT</constant> -must be identical to what <constant>VIDIOC_S_FMT</constant> returns for -the same input or output.</para> - - <table pgwide="1" frame="none" id="v4l2-format"> - <title>struct <structname>v4l2_format</structname></title> - <tgroup cols="4"> - <colspec colname="c1" /> - <colspec colname="c2" /> - <colspec colname="c3" /> - <colspec colname="c4" /> - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry></entry> - <entry>Type of the data stream, see <xref - linkend="v4l2-buf-type" />.</entry> - </row> - <row> - <entry>union</entry> - <entry><structfield>fmt</structfield></entry> - </row> - <row> - <entry></entry> - <entry>&v4l2-pix-format;</entry> - <entry><structfield>pix</structfield></entry> - <entry>Definition of an image format, see <xref - linkend="pixfmt" />, used by video capture and output -devices.</entry> - </row> - <row> - <entry></entry> - <entry>&v4l2-pix-format-mplane;</entry> - <entry><structfield>pix_mp</structfield></entry> - <entry>Definition of an image format, see <xref - linkend="pixfmt" />, used by video capture and output -devices that support the <link linkend="planar-apis">multi-planar -version of the API</link>.</entry> - </row> - <row> - <entry></entry> - <entry>&v4l2-window;</entry> - <entry><structfield>win</structfield></entry> - <entry>Definition of an overlaid image, see <xref - linkend="overlay" />, used by video overlay devices.</entry> - </row> - <row> - <entry></entry> - <entry>&v4l2-vbi-format;</entry> - <entry><structfield>vbi</structfield></entry> - <entry>Raw VBI capture or output parameters. This is -discussed in more detail in <xref linkend="raw-vbi" />. Used by raw VBI -capture and output devices.</entry> - </row> - <row> - <entry></entry> - <entry>&v4l2-sliced-vbi-format;</entry> - <entry><structfield>sliced</structfield></entry> - <entry>Sliced VBI capture or output parameters. See -<xref linkend="sliced" /> for details. Used by sliced VBI -capture and output devices.</entry> - </row> - <row> - <entry></entry> - <entry>&v4l2-sdr-format;</entry> - <entry><structfield>sdr</structfield></entry> - <entry>Definition of a data format, see -<xref linkend="pixfmt" />, used by SDR capture and output devices.</entry> - </row> - <row> - <entry></entry> - <entry>__u8</entry> - <entry><structfield>raw_data</structfield>[200]</entry> - <entry>Place holder for future extensions.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The &v4l2-format; <structfield>type</structfield> -field is invalid or the requested buffer type not supported.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml b/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml deleted file mode 100644 index d1034fb61d15..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml +++ /dev/null @@ -1,148 +0,0 @@ -<refentry id="vidioc-g-frequency"> - <refmeta> - <refentrytitle>ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_G_FREQUENCY</refname> - <refname>VIDIOC_S_FREQUENCY</refname> - <refpurpose>Get or set tuner or modulator radio -frequency</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_frequency -*<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>const struct v4l2_frequency -*<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>To get the current tuner or modulator radio frequency -applications set the <structfield>tuner</structfield> field of a -&v4l2-frequency; to the respective tuner or modulator number (only -input devices have tuners, only output devices have modulators), zero -out the <structfield>reserved</structfield> array and -call the <constant>VIDIOC_G_FREQUENCY</constant> ioctl with a pointer -to this structure. The driver stores the current frequency in the -<structfield>frequency</structfield> field.</para> - - <para>To change the current tuner or modulator radio frequency -applications initialize the <structfield>tuner</structfield>, -<structfield>type</structfield> and -<structfield>frequency</structfield> fields, and the -<structfield>reserved</structfield> array of a &v4l2-frequency; and -call the <constant>VIDIOC_S_FREQUENCY</constant> ioctl with a pointer -to this structure. When the requested frequency is not possible the -driver assumes the closest possible value. However -<constant>VIDIOC_S_FREQUENCY</constant> is a write-only ioctl, it does -not return the actual new frequency.</para> - - <table pgwide="1" frame="none" id="v4l2-frequency"> - <title>struct <structname>v4l2_frequency</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>tuner</structfield></entry> - <entry>The tuner or modulator index number. This is the -same value as in the &v4l2-input; <structfield>tuner</structfield> -field and the &v4l2-tuner; <structfield>index</structfield> field, or -the &v4l2-output; <structfield>modulator</structfield> field and the -&v4l2-modulator; <structfield>index</structfield> field.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry>The tuner type. This is the same value as in the -&v4l2-tuner; <structfield>type</structfield> field. The type must be set -to <constant>V4L2_TUNER_RADIO</constant> for <filename>/dev/radioX</filename> -device nodes, and to <constant>V4L2_TUNER_ANALOG_TV</constant> -for all others. Set this field to <constant>V4L2_TUNER_RADIO</constant> for -modulators (currently only radio modulators are supported). -See <xref linkend="v4l2-tuner-type" /></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>frequency</structfield></entry> - <entry>Tuning frequency in units of 62.5 kHz, or if the -&v4l2-tuner; or &v4l2-modulator; <structfield>capability</structfield> flag -<constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 -Hz. A 1 Hz unit is used when the <structfield>capability</structfield> flag -<constant>V4L2_TUNER_CAP_1HZ</constant> is set.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[8]</entry> - <entry>Reserved for future extensions. Drivers and - applications must set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The <structfield>tuner</structfield> index is out of -bounds or the value in the <structfield>type</structfield> field is -wrong.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EBUSY</errorcode></term> - <listitem> - <para>A hardware seek is in progress.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-input.xml b/Documentation/DocBook/media/v4l/vidioc-g-input.xml deleted file mode 100644 index 1d43065090dd..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-g-input.xml +++ /dev/null @@ -1,83 +0,0 @@ -<refentry id="vidioc-g-input"> - <refmeta> - <refentrytitle>ioctl VIDIOC_G_INPUT, VIDIOC_S_INPUT</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_G_INPUT</refname> - <refname>VIDIOC_S_INPUT</refname> - <refpurpose>Query or select the current video input</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>int *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_G_INPUT, VIDIOC_S_INPUT</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>To query the current video input applications call the -<constant>VIDIOC_G_INPUT</constant> ioctl with a pointer to an integer -where the driver stores the number of the input, as in the -&v4l2-input; <structfield>index</structfield> field. This ioctl will -fail only when there are no video inputs, returning -<errorcode>EINVAL</errorcode>.</para> - - <para>To select a video input applications store the number of the -desired input in an integer and call the -<constant>VIDIOC_S_INPUT</constant> ioctl with a pointer to this -integer. Side effects are possible. For example inputs may support -different video standards, so the driver may implicitly switch the -current standard. Because of these possible side effects applications -must select an input before querying or negotiating any other parameters.</para> - - <para>Information about video inputs is available using the -&VIDIOC-ENUMINPUT; ioctl.</para> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The number of the video input is out of bounds.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-jpegcomp.xml b/Documentation/DocBook/media/v4l/vidioc-g-jpegcomp.xml deleted file mode 100644 index 098ff483802e..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-g-jpegcomp.xml +++ /dev/null @@ -1,175 +0,0 @@ -<refentry id="vidioc-g-jpegcomp"> - <refmeta> - <refentrytitle>ioctl VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_G_JPEGCOMP</refname> - <refname>VIDIOC_S_JPEGCOMP</refname> - <refpurpose></refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>v4l2_jpegcompression *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>const v4l2_jpegcompression *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>These ioctls are <emphasis role="bold">deprecated</emphasis>. - New drivers and applications should use <link linkend="jpeg-controls"> - JPEG class controls</link> for image quality and JPEG markers control. - </para> - - <para>[to do]</para> - - <para>Ronald Bultje elaborates:</para> - - <!-- See video4linux-list@redhat.com on 16 Oct 2002, subject -"Re: [V4L] Re: v4l2 api / Zoran v4l2_jpegcompression" --> - - <para>APP is some application-specific information. The -application can set it itself, and it'll be stored in the JPEG-encoded -fields (eg; interlacing information for in an AVI or so). COM is the -same, but it's comments, like 'encoded by me' or so.</para> - - <para>jpeg_markers describes whether the huffman tables, -quantization tables and the restart interval information (all -JPEG-specific stuff) should be stored in the JPEG-encoded fields. -These define how the JPEG field is encoded. If you omit them, -applications assume you've used standard encoding. You usually do want -to add them.</para> - - <!-- NB VIDIOC_S_JPEGCOMP is w/o. --> - - <table pgwide="1" frame="none" id="v4l2-jpegcompression"> - <title>struct <structname>v4l2_jpegcompression</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>int</entry> - <entry><structfield>quality</structfield></entry> - <entry>Deprecated. If <link linkend="jpeg-quality-control"><constant> - V4L2_CID_JPEG_COMPRESSION_QUALITY</constant></link> control is exposed - by a driver applications should use it instead and ignore this field. - </entry> - </row> - <row> - <entry>int</entry> - <entry><structfield>APPn</structfield></entry> - <entry></entry> - </row> - <row> - <entry>int</entry> - <entry><structfield>APP_len</structfield></entry> - <entry></entry> - </row> - <row> - <entry>char</entry> - <entry><structfield>APP_data</structfield>[60]</entry> - <entry></entry> - </row> - <row> - <entry>int</entry> - <entry><structfield>COM_len</structfield></entry> - <entry></entry> - </row> - <row> - <entry>char</entry> - <entry><structfield>COM_data</structfield>[60]</entry> - <entry></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>jpeg_markers</structfield></entry> - <entry>See <xref linkend="jpeg-markers"/>. Deprecated. - If <link linkend="jpeg-active-marker-control"><constant> - V4L2_CID_JPEG_ACTIVE_MARKER</constant></link> control - is exposed by a driver applications should use it instead - and ignore this field.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="jpeg-markers"> - <title>JPEG Markers Flags</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_JPEG_MARKER_DHT</constant></entry> - <entry>(1<<3)</entry> - <entry>Define Huffman Tables</entry> - </row> - <row> - <entry><constant>V4L2_JPEG_MARKER_DQT</constant></entry> - <entry>(1<<4)</entry> - <entry>Define Quantization Tables</entry> - </row> - <row> - <entry><constant>V4L2_JPEG_MARKER_DRI</constant></entry> - <entry>(1<<5)</entry> - <entry>Define Restart Interval</entry> - </row> - <row> - <entry><constant>V4L2_JPEG_MARKER_COM</constant></entry> - <entry>(1<<6)</entry> - <entry>Comment segment</entry> - </row> - <row> - <entry><constant>V4L2_JPEG_MARKER_APP</constant></entry> - <entry>(1<<7)</entry> - <entry>App segment, driver will always use APP0</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml b/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml deleted file mode 100644 index 96e17b344c5d..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml +++ /dev/null @@ -1,252 +0,0 @@ -<refentry id="vidioc-g-modulator"> - <refmeta> - <refentrytitle>ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_G_MODULATOR</refname> - <refname>VIDIOC_S_MODULATOR</refname> - <refpurpose>Get or set modulator attributes</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_modulator -*<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>const struct v4l2_modulator -*<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>To query the attributes of a modulator applications initialize -the <structfield>index</structfield> field and zero out the -<structfield>reserved</structfield> array of a &v4l2-modulator; and -call the <constant>VIDIOC_G_MODULATOR</constant> ioctl with a pointer -to this structure. Drivers fill the rest of the structure or return an -&EINVAL; when the index is out of bounds. To enumerate all modulators -applications shall begin at index zero, incrementing by one until the -driver returns <errorcode>EINVAL</errorcode>.</para> - - <para>Modulators have two writable properties, an audio -modulation set and the radio frequency. To change the modulated audio -subprograms, applications initialize the <structfield>index -</structfield> and <structfield>txsubchans</structfield> fields and the -<structfield>reserved</structfield> array and call the -<constant>VIDIOC_S_MODULATOR</constant> ioctl. Drivers may choose a -different audio modulation if the request cannot be satisfied. However -this is a write-only ioctl, it does not return the actual audio -modulation selected.</para> - - <para><link linkend="sdr">SDR</link> specific modulator types are -<constant>V4L2_TUNER_SDR</constant> and <constant>V4L2_TUNER_RF</constant>. -For SDR devices <structfield>txsubchans</structfield> field must be -initialized to zero. -The term 'modulator' means SDR transmitter in this context.</para> - - <para>To change the radio frequency the &VIDIOC-S-FREQUENCY; ioctl -is available.</para> - - <table pgwide="1" frame="none" id="v4l2-modulator"> - <title>struct <structname>v4l2_modulator</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>index</structfield></entry> - <entry>Identifies the modulator, set by the -application.</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>name</structfield>[32]</entry> - <entry>Name of the modulator, a NUL-terminated ASCII -string. This information is intended for the user.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>capability</structfield></entry> - <entry>Modulator capability flags. No flags are defined -for this field, the tuner flags in &v4l2-tuner; -are used accordingly. The audio flags indicate the ability -to encode audio subprograms. They will <emphasis>not</emphasis> -change for example with the current video standard.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>rangelow</structfield></entry> - <entry>The lowest tunable frequency in units of 62.5 -KHz, or if the <structfield>capability</structfield> flag -<constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 -Hz, or if the <structfield>capability</structfield> flag -<constant>V4L2_TUNER_CAP_1HZ</constant> is set, in units of 1 Hz.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>rangehigh</structfield></entry> - <entry>The highest tunable frequency in units of 62.5 -KHz, or if the <structfield>capability</structfield> flag -<constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 -Hz, or if the <structfield>capability</structfield> flag -<constant>V4L2_TUNER_CAP_1HZ</constant> is set, in units of 1 Hz.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>txsubchans</structfield></entry> - <entry>With this field applications can determine how -audio sub-carriers shall be modulated. It contains a set of flags as -defined in <xref linkend="modulator-txsubchans" />. Note the tuner -<structfield>rxsubchans</structfield> flags are reused, but the -semantics are different. Video output devices are assumed to have an -analog or PCM audio input with 1-3 channels. The -<structfield>txsubchans</structfield> flags select one or more -channels for modulation, together with some audio subprogram -indicator, for example a stereo pilot tone.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry spanname="hspan">Type of the modulator, see <xref - linkend="v4l2-tuner-type" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[3]</entry> - <entry>Reserved for future extensions. Drivers and -applications must set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="modulator-txsubchans"> - <title>Modulator Audio Transmission Flags</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry> - <entry>0x0001</entry> - <entry>Modulate channel 1 as mono audio, when the input -has more channels, a down-mix of channel 1 and 2. This flag does not -combine with <constant>V4L2_TUNER_SUB_STEREO</constant> or -<constant>V4L2_TUNER_SUB_LANG1</constant>.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_SUB_STEREO</constant></entry> - <entry>0x0002</entry> - <entry>Modulate channel 1 and 2 as left and right -channel of a stereo audio signal. When the input has only one channel -or two channels and <constant>V4L2_TUNER_SUB_SAP</constant> is also -set, channel 1 is encoded as left and right channel. This flag does -not combine with <constant>V4L2_TUNER_SUB_MONO</constant> or -<constant>V4L2_TUNER_SUB_LANG1</constant>. When the driver does not -support stereo audio it shall fall back to mono.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_SUB_LANG1</constant></entry> - <entry>0x0008</entry> - <entry>Modulate channel 1 and 2 as primary and secondary -language of a bilingual audio signal. When the input has only one -channel it is used for both languages. It is not possible to encode -the primary or secondary language only. This flag does not combine -with <constant>V4L2_TUNER_SUB_MONO</constant>, -<constant>V4L2_TUNER_SUB_STEREO</constant> or -<constant>V4L2_TUNER_SUB_SAP</constant>. If the hardware does not -support the respective audio matrix, or the current video standard -does not permit bilingual audio the -<constant>VIDIOC_S_MODULATOR</constant> ioctl shall return an &EINVAL; -and the driver shall fall back to mono or stereo mode.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_SUB_LANG2</constant></entry> - <entry>0x0004</entry> - <entry>Same effect as -<constant>V4L2_TUNER_SUB_SAP</constant>.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_SUB_SAP</constant></entry> - <entry>0x0004</entry> - <entry>When combined with <constant>V4L2_TUNER_SUB_MONO -</constant> the first channel is encoded as mono audio, the last -channel as Second Audio Program. When the input has only one channel -it is used for both audio tracks. When the input has three channels -the mono track is a down-mix of channel 1 and 2. When combined with -<constant>V4L2_TUNER_SUB_STEREO</constant> channel 1 and 2 are -encoded as left and right stereo audio, channel 3 as Second Audio -Program. When the input has only two channels, the first is encoded as -left and right channel and the second as SAP. When the input has only -one channel it is used for all audio tracks. It is not possible to -encode a Second Audio Program only. This flag must combine with -<constant>V4L2_TUNER_SUB_MONO</constant> or -<constant>V4L2_TUNER_SUB_STEREO</constant>. If the hardware does not -support the respective audio matrix, or the current video standard -does not permit SAP the <constant>VIDIOC_S_MODULATOR</constant> ioctl -shall return an &EINVAL; and driver shall fall back to mono or stereo -mode.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_SUB_RDS</constant></entry> - <entry>0x0010</entry> - <entry>Enable the RDS encoder for a radio FM transmitter.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The &v4l2-modulator; -<structfield>index</structfield> is out of bounds.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-output.xml b/Documentation/DocBook/media/v4l/vidioc-g-output.xml deleted file mode 100644 index 4533068ecb8a..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-g-output.xml +++ /dev/null @@ -1,85 +0,0 @@ -<refentry id="vidioc-g-output"> - <refmeta> - <refentrytitle>ioctl VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_G_OUTPUT</refname> - <refname>VIDIOC_S_OUTPUT</refname> - <refpurpose>Query or select the current video output</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>int *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>To query the current video output applications call the -<constant>VIDIOC_G_OUTPUT</constant> ioctl with a pointer to an integer -where the driver stores the number of the output, as in the -&v4l2-output; <structfield>index</structfield> field. This ioctl -will fail only when there are no video outputs, returning the -&EINVAL;.</para> - - <para>To select a video output applications store the number of the -desired output in an integer and call the -<constant>VIDIOC_S_OUTPUT</constant> ioctl with a pointer to this integer. -Side effects are possible. For example outputs may support different -video standards, so the driver may implicitly switch the current -standard. -standard. Because of these possible side effects applications -must select an output before querying or negotiating any other parameters.</para> - - <para>Information about video outputs is available using the -&VIDIOC-ENUMOUTPUT; ioctl.</para> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The number of the video output is out of bounds, or -there are no video outputs at all.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-parm.xml b/Documentation/DocBook/media/v4l/vidioc-g-parm.xml deleted file mode 100644 index 721728745407..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-g-parm.xml +++ /dev/null @@ -1,314 +0,0 @@ -<refentry id="vidioc-g-parm"> - <refmeta> - <refentrytitle>ioctl VIDIOC_G_PARM, VIDIOC_S_PARM</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_G_PARM</refname> - <refname>VIDIOC_S_PARM</refname> - <refpurpose>Get or set streaming parameters</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>v4l2_streamparm *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_G_PARM, VIDIOC_S_PARM</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>The current video standard determines a nominal number of -frames per second. If less than this number of frames is to be -captured or output, applications can request frame skipping or -duplicating on the driver side. This is especially useful when using -the <function>read()</function> or <function>write()</function>, which -are not augmented by timestamps or sequence counters, and to avoid -unnecessary data copying.</para> - - <para>Further these ioctls can be used to determine the number of -buffers used internally by a driver in read/write mode. For -implications see the section discussing the &func-read; -function.</para> - - <para>To get and set the streaming parameters applications call -the <constant>VIDIOC_G_PARM</constant> and -<constant>VIDIOC_S_PARM</constant> ioctl, respectively. They take a -pointer to a struct <structname>v4l2_streamparm</structname> which -contains a union holding separate parameters for input and output -devices.</para> - - <table pgwide="1" frame="none" id="v4l2-streamparm"> - <title>struct <structname>v4l2_streamparm</structname></title> - <tgroup cols="4"> - &cs-ustr; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry></entry> - <entry>The buffer (stream) type, same as &v4l2-format; -<structfield>type</structfield>, set by the application. See <xref - linkend="v4l2-buf-type" /></entry> - </row> - <row> - <entry>union</entry> - <entry><structfield>parm</structfield></entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry></entry> - <entry>&v4l2-captureparm;</entry> - <entry><structfield>capture</structfield></entry> - <entry>Parameters for capture devices, used when -<structfield>type</structfield> is -<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>.</entry> - </row> - <row> - <entry></entry> - <entry>&v4l2-outputparm;</entry> - <entry><structfield>output</structfield></entry> - <entry>Parameters for output devices, used when -<structfield>type</structfield> is -<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>.</entry> - </row> - <row> - <entry></entry> - <entry>__u8</entry> - <entry><structfield>raw_data</structfield>[200]</entry> - <entry>A place holder for future extensions.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="v4l2-captureparm"> - <title>struct <structname>v4l2_captureparm</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>capability</structfield></entry> - <entry>See <xref linkend="parm-caps" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>capturemode</structfield></entry> - <entry>Set by drivers and applications, see <xref linkend="parm-flags" />.</entry> - </row> - <row> - <entry>&v4l2-fract;</entry> - <entry><structfield>timeperframe</structfield></entry> - <entry><para>This is the desired period between -successive frames captured by the driver, in seconds. The -field is intended to skip frames on the driver side, saving I/O -bandwidth.</para><para>Applications store here the desired frame -period, drivers return the actual frame period, which must be greater -or equal to the nominal frame period determined by the current video -standard (&v4l2-standard; <structfield>frameperiod</structfield> -field). Changing the video standard (also implicitly by switching the -video input) may reset this parameter to the nominal frame period. To -reset manually applications can just set this field to -zero.</para><para>Drivers support this function only when they set the -<constant>V4L2_CAP_TIMEPERFRAME</constant> flag in the -<structfield>capability</structfield> field.</para></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>extendedmode</structfield></entry> - <entry>Custom (driver specific) streaming parameters. When -unused, applications and drivers must set this field to zero. -Applications using this field should check the driver name and -version, see <xref linkend="querycap" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>readbuffers</structfield></entry> - <entry>Applications set this field to the desired number -of buffers used internally by the driver in &func-read; mode. Drivers -return the actual number of buffers. When an application requests zero -buffers, drivers should just return the current setting rather than -the minimum or an error code. For details see <xref - linkend="rw" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[4]</entry> - <entry>Reserved for future extensions. Drivers and -applications must set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="v4l2-outputparm"> - <title>struct <structname>v4l2_outputparm</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>capability</structfield></entry> - <entry>See <xref linkend="parm-caps" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>outputmode</structfield></entry> - <entry>Set by drivers and applications, see <xref - linkend="parm-flags" />.</entry> - </row> - <row> - <entry>&v4l2-fract;</entry> - <entry><structfield>timeperframe</structfield></entry> - <entry>This is the desired period between -successive frames output by the driver, in seconds.</entry> - </row> - <row> - <entry spanname="hspan"><para>The field is intended to -repeat frames on the driver side in &func-write; mode (in streaming -mode timestamps can be used to throttle the output), saving I/O -bandwidth.</para><para>Applications store here the desired frame -period, drivers return the actual frame period, which must be greater -or equal to the nominal frame period determined by the current video -standard (&v4l2-standard; <structfield>frameperiod</structfield> -field). Changing the video standard (also implicitly by switching the -video output) may reset this parameter to the nominal frame period. To -reset manually applications can just set this field to -zero.</para><para>Drivers support this function only when they set the -<constant>V4L2_CAP_TIMEPERFRAME</constant> flag in the -<structfield>capability</structfield> field.</para></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>extendedmode</structfield></entry> - <entry>Custom (driver specific) streaming parameters. When -unused, applications and drivers must set this field to zero. -Applications using this field should check the driver name and -version, see <xref linkend="querycap" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>writebuffers</structfield></entry> - <entry>Applications set this field to the desired number -of buffers used internally by the driver in -<function>write()</function> mode. Drivers return the actual number of -buffers. When an application requests zero buffers, drivers should -just return the current setting rather than the minimum or an error -code. For details see <xref linkend="rw" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[4]</entry> - <entry>Reserved for future extensions. Drivers and -applications must set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="parm-caps"> - <title>Streaming Parameters Capabilites</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_CAP_TIMEPERFRAME</constant></entry> - <entry>0x1000</entry> - <entry>The frame skipping/repeating controlled by the -<structfield>timeperframe</structfield> field is supported.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="parm-flags"> - <title>Capture Parameters Flags</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_MODE_HIGHQUALITY</constant></entry> - <entry>0x0001</entry> - <entry><para>High quality imaging mode. High quality mode -is intended for still imaging applications. The idea is to get the -best possible image quality that the hardware can deliver. It is not -defined how the driver writer may achieve that; it will depend on the -hardware and the ingenuity of the driver writer. High quality mode is -a different mode from the regular motion video capture modes. In -high quality mode:<itemizedlist> - <listitem> - <para>The driver may be able to capture higher -resolutions than for motion capture.</para> - </listitem> - <listitem> - <para>The driver may support fewer pixel formats -than motion capture (eg; true color).</para> - </listitem> - <listitem> - <para>The driver may capture and arithmetically -combine multiple successive fields or frames to remove color edge -artifacts and reduce the noise in the video data. -</para> - </listitem> - <listitem> - <para>The driver may capture images in slices like -a scanner in order to handle larger format images than would otherwise -be possible. </para> - </listitem> - <listitem> - <para>An image capture operation may be -significantly slower than motion capture. </para> - </listitem> - <listitem> - <para>Moving objects in the image might have -excessive motion blur. </para> - </listitem> - <listitem> - <para>Capture might only work through the -<function>read()</function> call.</para> - </listitem> - </itemizedlist></para></entry> - </row> - </tbody> - </tgroup> - </table> - - </refsect1> - - <refsect1> - &return-value; - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-priority.xml b/Documentation/DocBook/media/v4l/vidioc-g-priority.xml deleted file mode 100644 index 6a81b4fe9538..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-g-priority.xml +++ /dev/null @@ -1,135 +0,0 @@ -<refentry id="vidioc-g-priority"> - <refmeta> - <refentrytitle>ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_G_PRIORITY</refname> - <refname>VIDIOC_S_PRIORITY</refname> - <refpurpose>Query or request the access priority associated with a -file descriptor</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>enum v4l2_priority *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>const enum v4l2_priority *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para>Pointer to an enum v4l2_priority type.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>To query the current access priority -applications call the <constant>VIDIOC_G_PRIORITY</constant> ioctl -with a pointer to an enum v4l2_priority variable where the driver stores -the current priority.</para> - - <para>To request an access priority applications store the -desired priority in an enum v4l2_priority variable and call -<constant>VIDIOC_S_PRIORITY</constant> ioctl with a pointer to this -variable.</para> - - <table frame="none" pgwide="1" id="v4l2-priority"> - <title>enum v4l2_priority</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_PRIORITY_UNSET</constant></entry> - <entry>0</entry> - <entry></entry> - </row> - <row> - <entry><constant>V4L2_PRIORITY_BACKGROUND</constant></entry> - <entry>1</entry> - <entry>Lowest priority, usually applications running in -background, for example monitoring VBI transmissions. A proxy -application running in user space will be necessary if multiple -applications want to read from a device at this priority.</entry> - </row> - <row> - <entry><constant>V4L2_PRIORITY_INTERACTIVE</constant></entry> - <entry>2</entry> - <entry></entry> - </row> - <row> - <entry><constant>V4L2_PRIORITY_DEFAULT</constant></entry> - <entry>2</entry> - <entry>Medium priority, usually applications started and -interactively controlled by the user. For example TV viewers, Teletext -browsers, or just "panel" applications to change the channel or video -controls. This is the default priority unless an application requests -another.</entry> - </row> - <row> - <entry><constant>V4L2_PRIORITY_RECORD</constant></entry> - <entry>3</entry> - <entry>Highest priority. Only one file descriptor can have -this priority, it blocks any other fd from changing device properties. -Usually applications which must not be interrupted, like video -recording.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The requested priority value is invalid.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EBUSY</errorcode></term> - <listitem> - <para>Another application already requested higher -priority.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml deleted file mode 100644 index 7865351688da..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml +++ /dev/null @@ -1,239 +0,0 @@ -<refentry id="vidioc-g-selection"> - - <refmeta> - <refentrytitle>ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_G_SELECTION</refname> - <refname>VIDIOC_S_SELECTION</refname> - <refpurpose>Get or set one of the selection rectangles</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_selection *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_G_SELECTION, VIDIOC_S_SELECTION</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <note> - <title>Experimental</title> - <para>This is an <link linkend="experimental"> experimental </link> - interface and may change in the future.</para> - </note> - - <para>The ioctls are used to query and configure selection rectangles.</para> - -<para>To query the cropping (composing) rectangle set &v4l2-selection; -<structfield> type </structfield> field to the respective buffer type. -Do not use the multiplanar buffer types. Use <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> -instead of <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant> and use -<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> instead of -<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>. The next step is -setting the value of &v4l2-selection; <structfield>target</structfield> field -to <constant>V4L2_SEL_TGT_CROP</constant> (<constant>V4L2_SEL_TGT_COMPOSE</constant>). -Please refer to table <xref linkend="v4l2-selections-common" /> or <xref linkend="selection-api" /> -for additional targets. The <structfield>flags</structfield> and <structfield>reserved -</structfield> fields of &v4l2-selection; are ignored and they must be filled -with zeros. The driver fills the rest of the structure or -returns &EINVAL; if incorrect buffer type or target was used. If cropping -(composing) is not supported then the active rectangle is not mutable and it is -always equal to the bounds rectangle. Finally, the &v4l2-rect; -<structfield>r</structfield> rectangle is filled with the current cropping -(composing) coordinates. The coordinates are expressed in driver-dependent -units. The only exception are rectangles for images in raw formats, whose -coordinates are always expressed in pixels.</para> - -<para>To change the cropping (composing) rectangle set the &v4l2-selection; -<structfield>type</structfield> field to the respective buffer type. Do not -use multiplanar buffers. Use <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> -instead of <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>. Use -<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> instead of -<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>. The next step is -setting the value of &v4l2-selection; <structfield>target</structfield> to -<constant>V4L2_SEL_TGT_CROP</constant> (<constant>V4L2_SEL_TGT_COMPOSE</constant>). -Please refer to table <xref linkend="v4l2-selections-common" /> or <xref linkend="selection-api" /> -for additional targets. The &v4l2-rect; <structfield>r</structfield> rectangle need to be -set to the desired active area. Field &v4l2-selection; <structfield> reserved -</structfield> is ignored and must be filled with zeros. The driver may adjust -coordinates of the requested rectangle. An application may -introduce constraints to control rounding behaviour. The &v4l2-selection; -<structfield>flags</structfield> field must be set to one of the following: - -<itemizedlist> - <listitem> -<para><constant>0</constant> - The driver can adjust the rectangle size freely -and shall choose a crop/compose rectangle as close as possible to the requested -one.</para> - </listitem> - <listitem> -<para><constant>V4L2_SEL_FLAG_GE</constant> - The driver is not allowed to -shrink the rectangle. The original rectangle must lay inside the adjusted -one.</para> - </listitem> - <listitem> -<para><constant>V4L2_SEL_FLAG_LE</constant> - The driver is not allowed to -enlarge the rectangle. The adjusted rectangle must lay inside the original -one.</para> - </listitem> - <listitem> -<para><constant>V4L2_SEL_FLAG_GE | V4L2_SEL_FLAG_LE</constant> - The driver -must choose the size exactly the same as in the requested rectangle.</para> - </listitem> -</itemizedlist> - -Please refer to <xref linkend="sel-const-adjust" />. - -</para> - -<para> The driver may have to adjusts the requested dimensions against hardware -limits and other parts as the pipeline, i.e. the bounds given by the -capture/output window or TV display. The closest possible values of horizontal -and vertical offset and sizes are chosen according to following priority: - -<orderedlist> - <listitem> - <para>Satisfy constraints from &v4l2-selection; <structfield>flags</structfield>.</para> - </listitem> - <listitem> - <para>Adjust width, height, left, and top to hardware limits and alignments.</para> - </listitem> - <listitem> - <para>Keep center of adjusted rectangle as close as possible to the original one.</para> - </listitem> - <listitem> - <para>Keep width and height as close as possible to original ones.</para> - </listitem> - <listitem> - <para>Keep horizontal and vertical offset as close as possible to original ones.</para> - </listitem> -</orderedlist> - -On success the &v4l2-rect; <structfield>r</structfield> field contains -the adjusted rectangle. When the parameters are unsuitable the application may -modify the cropping (composing) or image parameters and repeat the cycle until -satisfactory parameters have been negotiated. If constraints flags have to be -violated at then ERANGE is returned. The error indicates that <emphasis>there -exist no rectangle</emphasis> that satisfies the constraints.</para> - - <para>Selection targets and flags are documented in <xref - linkend="v4l2-selections-common"/>.</para> - - <para> - <figure id="sel-const-adjust"> - <title>Size adjustments with constraint flags.</title> - <mediaobject> - <imageobject> - <imagedata fileref="constraints.png" format="PNG" /> - </imageobject> - <textobject> - <phrase>Behaviour of rectangle adjustment for different constraint - flags.</phrase> - </textobject> - </mediaobject> - </figure> - </para> - - <para> - <table pgwide="1" frame="none" id="v4l2-selection"> - <title>struct <structname>v4l2_selection</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry>Type of the buffer (from &v4l2-buf-type;).</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>target</structfield></entry> - <entry>Used to select between <link linkend="v4l2-selections-common"> cropping - and composing rectangles</link>.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry>Flags controlling the selection rectangle adjustments, refer to - <link linkend="v4l2-selection-flags">selection flags</link>.</entry> - </row> - <row> - <entry>&v4l2-rect;</entry> - <entry><structfield>r</structfield></entry> - <entry>The selection rectangle.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved[9]</structfield></entry> - <entry>Reserved fields for future use. Drivers and applications must zero this array.</entry> - </row> - </tbody> - </tgroup> - </table> - </para> - </refsect1> - - <refsect1> - &return-value; - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>Given buffer type <structfield>type</structfield> or -the selection target <structfield>target</structfield> is not supported, -or the <structfield>flags</structfield> argument is not valid.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>ERANGE</errorcode></term> - <listitem> - <para>It is not possible to adjust &v4l2-rect; <structfield> -r</structfield> rectangle to satisfy all contraints given in the -<structfield>flags</structfield> argument.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EBUSY</errorcode></term> - <listitem> - <para>It is not possible to apply change of the selection rectangle -at the moment. Usually because streaming is in progress.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-sliced-vbi-cap.xml b/Documentation/DocBook/media/v4l/vidioc-g-sliced-vbi-cap.xml deleted file mode 100644 index d05623c55403..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-g-sliced-vbi-cap.xml +++ /dev/null @@ -1,255 +0,0 @@ -<refentry id="vidioc-g-sliced-vbi-cap"> - <refmeta> - <refentrytitle>ioctl VIDIOC_G_SLICED_VBI_CAP</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_G_SLICED_VBI_CAP</refname> - <refpurpose>Query sliced VBI capabilities</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_sliced_vbi_cap *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_G_SLICED_VBI_CAP</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>To find out which data services are supported by a sliced -VBI capture or output device, applications initialize the -<structfield>type</structfield> field of a &v4l2-sliced-vbi-cap;, -clear the <structfield>reserved</structfield> array and -call the <constant>VIDIOC_G_SLICED_VBI_CAP</constant> ioctl. The -driver fills in the remaining fields or returns an &EINVAL; if the -sliced VBI API is unsupported or <structfield>type</structfield> -is invalid.</para> - - <para>Note the <structfield>type</structfield> field was added, -and the ioctl changed from read-only to write-read, in Linux 2.6.19.</para> - - <table pgwide="1" frame="none" id="v4l2-sliced-vbi-cap"> - <title>struct <structname>v4l2_sliced_vbi_cap</structname></title> - <tgroup cols="5"> - <colspec colname="c1" colwidth="3*" /> - <colspec colname="c2" colwidth="3*" /> - <colspec colname="c3" colwidth="2*" /> - <colspec colname="c4" colwidth="2*" /> - <colspec colname="c5" colwidth="2*" /> - <spanspec spanname="hspan" namest="c3" nameend="c5" /> - <tbody valign="top"> - <row> - <entry>__u16</entry> - <entry><structfield>service_set</structfield></entry> - <entry spanname="hspan">A set of all data services -supported by the driver. Equal to the union of all elements of the -<structfield>service_lines </structfield> array.</entry> - </row> - <row> - <entry>__u16</entry> - <entry><structfield>service_lines</structfield>[2][24]</entry> - <entry spanname="hspan">Each element of this array -contains a set of data services the hardware can look for or insert -into a particular scan line. Data services are defined in <xref - linkend="vbi-services" />. Array indices map to ITU-R -line numbers (see also <xref - linkend="vbi-525" /> and <xref -linkend="vbi-625" />) as follows:</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry>Element</entry> - <entry>525 line systems</entry> - <entry>625 line systems</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry><structfield>service_lines</structfield>[0][1]</entry> - <entry align="center">1</entry> - <entry align="center">1</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry><structfield>service_lines</structfield>[0][23]</entry> - <entry align="center">23</entry> - <entry align="center">23</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry><structfield>service_lines</structfield>[1][1]</entry> - <entry align="center">264</entry> - <entry align="center">314</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry><structfield>service_lines</structfield>[1][23]</entry> - <entry align="center">286</entry> - <entry align="center">336</entry> - </row> - <row> - <entry></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry spanname="hspan">The number of VBI lines the -hardware can capture or output per frame, or the number of services it -can identify on a given line may be limited. For example on PAL line -16 the hardware may be able to look for a VPS or Teletext signal, but -not both at the same time. Applications can learn about these limits -using the &VIDIOC-S-FMT; ioctl as described in <xref - linkend="sliced" />.</entry> - </row> - <row> - <entry></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry spanname="hspan">Drivers must set -<structfield>service_lines</structfield>[0][0] and -<structfield>service_lines</structfield>[1][0] to zero.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry>Type of the data stream, see <xref - linkend="v4l2-buf-type" />. Should be -<constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> or -<constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant>.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[3]</entry> - <entry spanname="hspan">This array is reserved for future -extensions. Applications and drivers must set it to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <!-- See also dev-sliced-vbi.sgml --> - <table pgwide="1" frame="none" id="vbi-services"> - <title>Sliced VBI services</title> - <tgroup cols="5"> - <colspec colname="c1" colwidth="2*" /> - <colspec colname="c2" colwidth="1*" /> - <colspec colname="c3" colwidth="1*" /> - <colspec colname="c4" colwidth="2*" /> - <colspec colname="c5" colwidth="2*" /> - <spanspec spanname='rlp' namest='c3' nameend='c5' /> - <thead> - <row> - <entry>Symbol</entry> - <entry>Value</entry> - <entry>Reference</entry> - <entry>Lines, usually</entry> - <entry>Payload</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry><constant>V4L2_SLICED_TELETEXT_B</constant> (Teletext -System B)</entry> - <entry>0x0001</entry> - <entry><xref linkend="ets300706" />, <xref linkend="itu653" /></entry> - <entry>PAL/SECAM line 7-22, 320-335 (second field 7-22)</entry> - <entry>Last 42 of the 45 byte Teletext packet, that is -without clock run-in and framing code, lsb first transmitted.</entry> - </row> - <row> - <entry><constant>V4L2_SLICED_VPS</constant></entry> - <entry>0x0400</entry> - <entry><xref linkend="ets300231" /></entry> - <entry>PAL line 16</entry> - <entry>Byte number 3 to 15 according to Figure 9 of -ETS 300 231, lsb first transmitted.</entry> - </row> - <row> - <entry><constant>V4L2_SLICED_CAPTION_525</constant></entry> - <entry>0x1000</entry> - <entry><xref linkend="cea608" /></entry> - <entry>NTSC line 21, 284 (second field 21)</entry> - <entry>Two bytes in transmission order, including parity -bit, lsb first transmitted.</entry> - </row> - <row> - <entry><constant>V4L2_SLICED_WSS_625</constant></entry> - <entry>0x4000</entry> - <entry><xref linkend="en300294" />, <xref linkend="itu1119" /></entry> - <entry>PAL/SECAM line 23</entry> - <entry><screen> -Byte 0 1 - msb lsb msb lsb -Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9 -</screen></entry> - </row> - <row> - <entry><constant>V4L2_SLICED_VBI_525</constant></entry> - <entry>0x1000</entry> - <entry spanname="rlp">Set of services applicable to 525 -line systems.</entry> - </row> - <row> - <entry><constant>V4L2_SLICED_VBI_625</constant></entry> - <entry>0x4401</entry> - <entry spanname="rlp">Set of services applicable to 625 -line systems.</entry> - </row> - </tbody> - </tgroup> - </table> - - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The value in the <structfield>type</structfield> field is -wrong.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-std.xml b/Documentation/DocBook/media/v4l/vidioc-g-std.xml deleted file mode 100644 index 4a898417de28..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-g-std.xml +++ /dev/null @@ -1,98 +0,0 @@ -<refentry id="vidioc-g-std"> - <refmeta> - <refentrytitle>ioctl VIDIOC_G_STD, VIDIOC_S_STD</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_G_STD</refname> - <refname>VIDIOC_S_STD</refname> - <refpurpose>Query or select the video standard of the current input</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>v4l2_std_id -*<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>const v4l2_std_id -*<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_G_STD, VIDIOC_S_STD</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>To query and select the current video standard applications -use the <constant>VIDIOC_G_STD</constant> and <constant>VIDIOC_S_STD</constant> ioctls which take a pointer to a -&v4l2-std-id; type as argument. <constant>VIDIOC_G_STD</constant> can -return a single flag or a set of flags as in &v4l2-standard; field -<structfield>id</structfield>. The flags must be unambiguous such -that they appear in only one enumerated <structname>v4l2_standard</structname> structure.</para> - - <para><constant>VIDIOC_S_STD</constant> accepts one or more -flags, being a write-only ioctl it does not return the actual new standard as -<constant>VIDIOC_G_STD</constant> does. When no flags are given or -the current input does not support the requested standard the driver -returns an &EINVAL;. When the standard set is ambiguous drivers may -return <errorcode>EINVAL</errorcode> or choose any of the requested -standards. If the current input or output does not support standard video timings (e.g. if -&VIDIOC-ENUMINPUT; does not set the <constant>V4L2_IN_CAP_STD</constant> flag), then -&ENODATA; is returned.</para> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The <constant>VIDIOC_S_STD</constant> parameter was unsuitable.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>ENODATA</errorcode></term> - <listitem> - <para>Standard video timings are not supported for this input or output.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml deleted file mode 100644 index 459b7e561f3c..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml +++ /dev/null @@ -1,594 +0,0 @@ -<refentry id="vidioc-g-tuner"> - <refmeta> - <refentrytitle>ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_G_TUNER</refname> - <refname>VIDIOC_S_TUNER</refname> - <refpurpose>Get or set tuner attributes</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_tuner -*<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>const struct v4l2_tuner -*<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_G_TUNER, VIDIOC_S_TUNER</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>To query the attributes of a tuner applications initialize the -<structfield>index</structfield> field and zero out the -<structfield>reserved</structfield> array of a &v4l2-tuner; and call the -<constant>VIDIOC_G_TUNER</constant> ioctl with a pointer to this -structure. Drivers fill the rest of the structure or return an -&EINVAL; when the index is out of bounds. To enumerate all tuners -applications shall begin at index zero, incrementing by one until the -driver returns <errorcode>EINVAL</errorcode>.</para> - - <para>Tuners have two writable properties, the audio mode and -the radio frequency. To change the audio mode, applications initialize -the <structfield>index</structfield>, -<structfield>audmode</structfield> and -<structfield>reserved</structfield> fields and call the -<constant>VIDIOC_S_TUNER</constant> ioctl. This will -<emphasis>not</emphasis> change the current tuner, which is determined -by the current video input. Drivers may choose a different audio mode -if the requested mode is invalid or unsupported. Since this is a -<!-- FIXME -->write-only ioctl, it does not return the actually -selected audio mode.</para> - - <para><link linkend="sdr">SDR</link> specific tuner types are -<constant>V4L2_TUNER_SDR</constant> and <constant>V4L2_TUNER_RF</constant>. -For SDR devices <structfield>audmode</structfield> field must be -initialized to zero. -The term 'tuner' means SDR receiver in this context.</para> - - <para>To change the radio frequency the &VIDIOC-S-FREQUENCY; ioctl -is available.</para> - - <table pgwide="1" frame="none" id="v4l2-tuner"> - <title>struct <structname>v4l2_tuner</structname></title> - <tgroup cols="3"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="1*" /> - <colspec colname="c3" colwidth="1*" /> - <colspec colname="c4" colwidth="1*" /> - <spanspec spanname="hspan" namest="c3" nameend="c4" /> - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>index</structfield></entry> - <entry spanname="hspan">Identifies the tuner, set by the -application.</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>name</structfield>[32]</entry> - <entry spanname="hspan"><para>Name of the tuner, a -NUL-terminated ASCII string. This information is intended for the -user.<!-- FIXME Video inputs already have a name, the purpose of this -field is not quite clear.--></para></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry spanname="hspan">Type of the tuner, see <xref - linkend="v4l2-tuner-type" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>capability</structfield></entry> - <entry spanname="hspan"><para>Tuner capability flags, see -<xref linkend="tuner-capability" />. Audio flags indicate the ability -to decode audio subprograms. They will <emphasis>not</emphasis> -change, for example with the current video standard.</para><para>When -the structure refers to a radio tuner the -<constant>V4L2_TUNER_CAP_LANG1</constant>, -<constant>V4L2_TUNER_CAP_LANG2</constant> and -<constant>V4L2_TUNER_CAP_NORM</constant> flags can't be used.</para> -<para>If multiple frequency bands are supported, then -<structfield>capability</structfield> is the union of all -<structfield>capability</structfield> fields of each &v4l2-frequency-band;. -</para></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>rangelow</structfield></entry> - <entry spanname="hspan">The lowest tunable frequency in -units of 62.5 kHz, or if the <structfield>capability</structfield> -flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 -Hz, or if the <structfield>capability</structfield> flag -<constant>V4L2_TUNER_CAP_1HZ</constant> is set, in units of 1 Hz. -If multiple frequency bands are supported, then -<structfield>rangelow</structfield> is the lowest frequency -of all the frequency bands.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>rangehigh</structfield></entry> - <entry spanname="hspan">The highest tunable frequency in -units of 62.5 kHz, or if the <structfield>capability</structfield> -flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 -Hz, or if the <structfield>capability</structfield> flag -<constant>V4L2_TUNER_CAP_1HZ</constant> is set, in units of 1 Hz. -If multiple frequency bands are supported, then -<structfield>rangehigh</structfield> is the highest frequency -of all the frequency bands.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>rxsubchans</structfield></entry> - <entry spanname="hspan"><para>Some tuners or audio -decoders can determine the received audio subprograms by analyzing -audio carriers, pilot tones or other indicators. To pass this -information drivers set flags defined in <xref - linkend="tuner-rxsubchans" /> in this field. For -example:</para></entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry> - <entry>receiving mono audio</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry><constant>STEREO | SAP</constant></entry> - <entry>receiving stereo audio and a secondary audio -program</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry><constant>MONO | STEREO</constant></entry> - <entry>receiving mono or stereo audio, the hardware cannot -distinguish</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry><constant>LANG1 | LANG2</constant></entry> - <entry>receiving bilingual audio</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry><constant>MONO | STEREO | LANG1 | LANG2</constant></entry> - <entry>receiving mono, stereo or bilingual -audio</entry> - </row> - <row> - <entry></entry> - <entry></entry> - <entry spanname="hspan"><para>When the -<constant>V4L2_TUNER_CAP_STEREO</constant>, -<constant>_LANG1</constant>, <constant>_LANG2</constant> or -<constant>_SAP</constant> flag is cleared in the -<structfield>capability</structfield> field, the corresponding -<constant>V4L2_TUNER_SUB_</constant> flag must not be set -here.</para><para>This field is valid only if this is the tuner of the -current video input, or when the structure refers to a radio -tuner.</para></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>audmode</structfield></entry> - <entry spanname="hspan"><para>The selected audio mode, see -<xref linkend="tuner-audmode" /> for valid values. The audio mode does -not affect audio subprogram detection, and like a <link -linkend="control">control</link> it does not automatically change -unless the requested mode is invalid or unsupported. See <xref - linkend="tuner-matrix" /> for possible results when -the selected and received audio programs do not -match.</para><para>Currently this is the only field of struct -<structname>v4l2_tuner</structname> applications can -change.</para></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>signal</structfield></entry> - <entry spanname="hspan">The signal strength if known, ranging -from 0 to 65535. Higher values indicate a better signal.</entry> - </row> - <row> - <entry>__s32</entry> - <entry><structfield>afc</structfield></entry> - <entry spanname="hspan">Automatic frequency control: When the -<structfield>afc</structfield> value is negative, the frequency is too -low, when positive too high.<!-- FIXME need example what to do when it never -settles at zero, &ie; range is what? --></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[4]</entry> - <entry spanname="hspan">Reserved for future extensions. Drivers and -applications must set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="v4l2-tuner-type"> - <title>enum v4l2_tuner_type</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_TUNER_RADIO</constant></entry> - <entry>1</entry> - <entry></entry> - </row> - <row> - <entry><constant>V4L2_TUNER_ANALOG_TV</constant></entry> - <entry>2</entry> - <entry></entry> - </row> - <row> - <entry><constant>V4L2_TUNER_SDR</constant></entry> - <entry>4</entry> - <entry></entry> - </row> - <row> - <entry><constant>V4L2_TUNER_RF</constant></entry> - <entry>5</entry> - <entry></entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="tuner-capability"> - <title>Tuner and Modulator Capability Flags</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_TUNER_CAP_LOW</constant></entry> - <entry>0x0001</entry> - <entry>When set, tuning frequencies are expressed in units of -62.5 Hz instead of 62.5 kHz.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_CAP_NORM</constant></entry> - <entry>0x0002</entry> - <entry>This is a multi-standard tuner; the video standard -can or must be switched. (B/G PAL tuners for example are typically not - considered multi-standard because the video standard is automatically - determined from the frequency band.) The set of supported video - standards is available from the &v4l2-input; pointing to this tuner, - see the description of ioctl &VIDIOC-ENUMINPUT; for details. Only - <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_CAP_HWSEEK_BOUNDED</constant></entry> - <entry>0x0004</entry> - <entry>If set, then this tuner supports the hardware seek functionality - where the seek stops when it reaches the end of the frequency range.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_CAP_HWSEEK_WRAP</constant></entry> - <entry>0x0008</entry> - <entry>If set, then this tuner supports the hardware seek functionality - where the seek wraps around when it reaches the end of the frequency range.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_CAP_STEREO</constant></entry> - <entry>0x0010</entry> - <entry>Stereo audio reception is supported.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_CAP_LANG1</constant></entry> - <entry>0x0040</entry> - <entry>Reception of the primary language of a bilingual -audio program is supported. Bilingual audio is a feature of -two-channel systems, transmitting the primary language monaural on the -main audio carrier and a secondary language monaural on a second -carrier. Only - <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_CAP_LANG2</constant></entry> - <entry>0x0020</entry> - <entry>Reception of the secondary language of a bilingual -audio program is supported. Only - <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_CAP_SAP</constant></entry> - <entry>0x0020</entry> - <entry><para>Reception of a secondary audio program is -supported. This is a feature of the BTSC system which accompanies the -NTSC video standard. Two audio carriers are available for mono or -stereo transmissions of a primary language, and an independent third -carrier for a monaural secondary language. Only - <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</para><para>Note the -<constant>V4L2_TUNER_CAP_LANG2</constant> and -<constant>V4L2_TUNER_CAP_SAP</constant> flags are synonyms. -<constant>V4L2_TUNER_CAP_SAP</constant> applies when the tuner -supports the <constant>V4L2_STD_NTSC_M</constant> video -standard.</para><!-- FIXME what if PAL+NTSC and Bi but not SAP? --></entry> - </row> - <row> - <entry><constant>V4L2_TUNER_CAP_RDS</constant></entry> - <entry>0x0080</entry> - <entry>RDS capture is supported. This capability is only valid for -radio tuners.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_CAP_RDS_BLOCK_IO</constant></entry> - <entry>0x0100</entry> - <entry>The RDS data is passed as unparsed RDS blocks.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_CAP_RDS_CONTROLS</constant></entry> - <entry>0x0200</entry> - <entry>The RDS data is parsed by the hardware and set via controls.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_CAP_FREQ_BANDS</constant></entry> - <entry>0x0400</entry> - <entry>The &VIDIOC-ENUM-FREQ-BANDS; ioctl can be used to enumerate - the available frequency bands.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_CAP_HWSEEK_PROG_LIM</constant></entry> - <entry>0x0800</entry> - <entry>The range to search when using the hardware seek functionality - is programmable, see &VIDIOC-S-HW-FREQ-SEEK; for details.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_CAP_1HZ</constant></entry> - <entry>0x1000</entry> - <entry>When set, tuning frequencies are expressed in units of 1 Hz instead of 62.5 kHz.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="tuner-rxsubchans"> - <title>Tuner Audio Reception Flags</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry> - <entry>0x0001</entry> - <entry>The tuner receives a mono audio signal.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_SUB_STEREO</constant></entry> - <entry>0x0002</entry> - <entry>The tuner receives a stereo audio signal.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_SUB_LANG1</constant></entry> - <entry>0x0008</entry> - <entry>The tuner receives the primary language of a -bilingual audio signal. Drivers must clear this flag when the current -video standard is <constant>V4L2_STD_NTSC_M</constant>.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_SUB_LANG2</constant></entry> - <entry>0x0004</entry> - <entry>The tuner receives the secondary language of a -bilingual audio signal (or a second audio program).</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_SUB_SAP</constant></entry> - <entry>0x0004</entry> - <entry>The tuner receives a Second Audio Program. Note the -<constant>V4L2_TUNER_SUB_LANG2</constant> and -<constant>V4L2_TUNER_SUB_SAP</constant> flags are synonyms. The -<constant>V4L2_TUNER_SUB_SAP</constant> flag applies when the -current video standard is <constant>V4L2_STD_NTSC_M</constant>.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_SUB_RDS</constant></entry> - <entry>0x0010</entry> - <entry>The tuner receives an RDS channel.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="tuner-audmode"> - <title>Tuner Audio Modes</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_TUNER_MODE_MONO</constant></entry> - <entry>0</entry> - <entry>Play mono audio. When the tuner receives a stereo -signal this a down-mix of the left and right channel. When the tuner -receives a bilingual or SAP signal this mode selects the primary -language.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_MODE_STEREO</constant></entry> - <entry>1</entry> - <entry><para>Play stereo audio. When the tuner receives -bilingual audio it may play different languages on the left and right -channel or the primary language is played on both channels.</para><para>Playing -different languages in this mode is -deprecated. New drivers should do this only in -<constant>MODE_LANG1_LANG2</constant>.</para><para>When the tuner -receives no stereo signal or does not support stereo reception the -driver shall fall back to <constant>MODE_MONO</constant>.</para></entry> - </row> - <row> - <entry><constant>V4L2_TUNER_MODE_LANG1</constant></entry> - <entry>3</entry> - <entry>Play the primary language, mono or stereo. Only -<constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this -mode.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_MODE_LANG2</constant></entry> - <entry>2</entry> - <entry>Play the secondary language, mono. When the tuner -receives no bilingual audio or SAP, or their reception is not -supported the driver shall fall back to mono or stereo mode. Only -<constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this -mode.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_MODE_SAP</constant></entry> - <entry>2</entry> - <entry>Play the Second Audio Program. When the tuner -receives no bilingual audio or SAP, or their reception is not -supported the driver shall fall back to mono or stereo mode. Only -<constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this mode. -Note the <constant>V4L2_TUNER_MODE_LANG2</constant> and -<constant>V4L2_TUNER_MODE_SAP</constant> are synonyms.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_MODE_LANG1_LANG2</constant></entry> - <entry>4</entry> - <entry>Play the primary language on the left channel, the -secondary language on the right channel. When the tuner receives no -bilingual audio or SAP, it shall fall back to -<constant>MODE_LANG1</constant> or <constant>MODE_MONO</constant>. -Only <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this -mode.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="all" id="tuner-matrix"> - <title>Tuner Audio Matrix</title> - <tgroup cols="6" align="center"> - <colspec align="left" /> - <colspec colname="c2" colwidth="1*" /> - <colspec colwidth="1*" /> - <colspec colwidth="1*" /> - <colspec colnum="6" colname="c6" colwidth="1*" /> - <spanspec namest="c2" nameend="c6" spanname="hspan" align="center" /> - <thead> - <row> - <entry></entry> - <entry spanname="hspan">Selected -<constant>V4L2_TUNER_MODE_</constant></entry> - </row> - <row> - <entry>Received <constant>V4L2_TUNER_SUB_</constant></entry> - <entry><constant>MONO</constant></entry> - <entry><constant>STEREO</constant></entry> - <entry><constant>LANG1</constant></entry> - <entry><constant>LANG2 = SAP</constant></entry> - <entry><constant>LANG1_LANG2</constant><footnote><para>This -mode has been added in Linux 2.6.17 and may not be supported by older -drivers.</para></footnote></entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry><constant>MONO</constant></entry> - <entry>Mono</entry> - <entry>Mono/Mono</entry> - <entry>Mono</entry> - <entry>Mono</entry> - <entry>Mono/Mono</entry> - </row> - <row> - <entry><constant>MONO | SAP</constant></entry> - <entry>Mono</entry> - <entry>Mono/Mono</entry> - <entry>Mono</entry> - <entry>SAP</entry> - <entry>Mono/SAP (preferred) or Mono/Mono</entry> - </row> - <row> - <entry><constant>STEREO</constant></entry> - <entry>L+R</entry> - <entry>L/R</entry> - <entry>Stereo L/R (preferred) or Mono L+R</entry> - <entry>Stereo L/R (preferred) or Mono L+R</entry> - <entry>L/R (preferred) or L+R/L+R</entry> - </row> - <row> - <entry><constant>STEREO | SAP</constant></entry> - <entry>L+R</entry> - <entry>L/R</entry> - <entry>Stereo L/R (preferred) or Mono L+R</entry> - <entry>SAP</entry> - <entry>L+R/SAP (preferred) or L/R or L+R/L+R</entry> - </row> - <row> - <entry><constant>LANG1 | LANG2</constant></entry> - <entry>Language 1</entry> - <entry>Lang1/Lang2 (deprecated<footnote><para>Playback of -both languages in <constant>MODE_STEREO</constant> is deprecated. In -the future drivers should produce only the primary language in this -mode. Applications should request -<constant>MODE_LANG1_LANG2</constant> to record both languages or a -stereo signal.</para></footnote>) or -Lang1/Lang1</entry> - <entry>Language 1</entry> - <entry>Language 2</entry> - <entry>Lang1/Lang2 (preferred) or Lang1/Lang1</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The &v4l2-tuner; <structfield>index</structfield> is -out of bounds.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-log-status.xml b/Documentation/DocBook/media/v4l/vidioc-log-status.xml deleted file mode 100644 index 5ded7d35e27b..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-log-status.xml +++ /dev/null @@ -1,41 +0,0 @@ -<refentry id="vidioc-log-status"> - <refmeta> - <refentrytitle>ioctl VIDIOC_LOG_STATUS</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_LOG_STATUS</refname> - <refpurpose>Log driver status information</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>As the video/audio devices become more complicated it -becomes harder to debug problems. When this ioctl is called the driver -will output the current device status to the kernel log. This is -particular useful when dealing with problems like no sound, no video -and incorrectly tuned channels. Also many modern devices autodetect -video and audio standards and this ioctl will report what the device -thinks what the standard is. Mismatches may give an indication where -the problem is.</para> - - <para>This ioctl is optional and not all drivers support it. It -was introduced in Linux 2.6.15.</para> - </refsect1> - - <refsect1> - &return-value; - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-overlay.xml b/Documentation/DocBook/media/v4l/vidioc-overlay.xml deleted file mode 100644 index 250a7de1877f..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-overlay.xml +++ /dev/null @@ -1,74 +0,0 @@ -<refentry id="vidioc-overlay"> - <refmeta> - <refentrytitle>ioctl VIDIOC_OVERLAY</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_OVERLAY</refname> - <refpurpose>Start or stop video overlay</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>const int *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_OVERLAY</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>This ioctl is part of the <link linkend="overlay">video - overlay</link> I/O method. Applications call - <constant>VIDIOC_OVERLAY</constant> to start or stop the - overlay. It takes a pointer to an integer which must be set to - zero by the application to stop overlay, to one to start.</para> - - <para>Drivers do not support &VIDIOC-STREAMON; or -&VIDIOC-STREAMOFF; with <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>.</para> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The overlay parameters have not been set up. See <xref -linkend="overlay" /> for the necessary steps.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml b/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml deleted file mode 100644 index fa7ad7e33228..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml +++ /dev/null @@ -1,94 +0,0 @@ -<refentry id="vidioc-prepare-buf"> - <refmeta> - <refentrytitle>ioctl VIDIOC_PREPARE_BUF</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_PREPARE_BUF</refname> - <refpurpose>Prepare a buffer for I/O</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_buffer *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_PREPARE_BUF</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <note> - <title>Experimental</title> - <para>This is an <link linkend="experimental"> experimental </link> - interface and may change in the future.</para> - </note> - - <para>Applications can optionally call the -<constant>VIDIOC_PREPARE_BUF</constant> ioctl to pass ownership of the buffer -to the driver before actually enqueuing it, using the -<constant>VIDIOC_QBUF</constant> ioctl, and to prepare it for future I/O. -Such preparations may include cache invalidation or cleaning. Performing them -in advance saves time during the actual I/O. In case such cache operations are -not required, the application can use one of -<constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant> and -<constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant> flags to skip the respective -step.</para> - - <para>The <structname>v4l2_buffer</structname> structure is -specified in <xref linkend="buffer" />.</para> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EBUSY</errorcode></term> - <listitem> - <para>File I/O is in progress.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The buffer <structfield>type</structfield> is not -supported, or the <structfield>index</structfield> is out of bounds, -or no buffers have been allocated yet, or the -<structfield>userptr</structfield> or -<structfield>length</structfield> are invalid.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml deleted file mode 100644 index 8b98a0e421fc..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml +++ /dev/null @@ -1,202 +0,0 @@ -<refentry id="vidioc-qbuf"> - <refmeta> - <refentrytitle>ioctl VIDIOC_QBUF, VIDIOC_DQBUF</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_QBUF</refname> - <refname>VIDIOC_DQBUF</refname> - <refpurpose>Exchange a buffer with the driver</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_buffer *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_QBUF, VIDIOC_DQBUF</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>Applications call the <constant>VIDIOC_QBUF</constant> ioctl -to enqueue an empty (capturing) or filled (output) buffer in the -driver's incoming queue. The semantics depend on the selected I/O -method.</para> - - <para>To enqueue a buffer applications set the <structfield>type</structfield> -field of a &v4l2-buffer; to the same buffer type as was previously used -with &v4l2-format; <structfield>type</structfield> and &v4l2-requestbuffers; -<structfield>type</structfield>. Applications must also set the -<structfield>index</structfield> field. Valid index numbers range from -zero to the number of buffers allocated with &VIDIOC-REQBUFS; -(&v4l2-requestbuffers; <structfield>count</structfield>) minus one. The -contents of the struct <structname>v4l2_buffer</structname> returned -by a &VIDIOC-QUERYBUF; ioctl will do as well. When the buffer is -intended for output (<structfield>type</structfield> is -<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>, -<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>, or -<constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>) applications must also -initialize the <structfield>bytesused</structfield>, -<structfield>field</structfield> and -<structfield>timestamp</structfield> fields, see <xref -linkend="buffer" /> for details. -Applications must also set <structfield>flags</structfield> to 0. -The <structfield>reserved2</structfield> and -<structfield>reserved</structfield> fields must be set to 0. When using -the <link linkend="planar-apis">multi-planar API</link>, the -<structfield>m.planes</structfield> field must contain a userspace pointer -to a filled-in array of &v4l2-plane; and the <structfield>length</structfield> -field must be set to the number of elements in that array. -</para> - - <para>To enqueue a <link linkend="mmap">memory mapped</link> -buffer applications set the <structfield>memory</structfield> -field to <constant>V4L2_MEMORY_MMAP</constant>. When -<constant>VIDIOC_QBUF</constant> is called with a pointer to this -structure the driver sets the -<constant>V4L2_BUF_FLAG_MAPPED</constant> and -<constant>V4L2_BUF_FLAG_QUEUED</constant> flags and clears the -<constant>V4L2_BUF_FLAG_DONE</constant> flag in the -<structfield>flags</structfield> field, or it returns an -&EINVAL;.</para> - - <para>To enqueue a <link linkend="userp">user pointer</link> -buffer applications set the <structfield>memory</structfield> -field to <constant>V4L2_MEMORY_USERPTR</constant>, the -<structfield>m.userptr</structfield> field to the address of the -buffer and <structfield>length</structfield> to its size. When the multi-planar -API is used, <structfield>m.userptr</structfield> and -<structfield>length</structfield> members of the passed array of &v4l2-plane; -have to be used instead. When <constant>VIDIOC_QBUF</constant> is called with -a pointer to this structure the driver sets the -<constant>V4L2_BUF_FLAG_QUEUED</constant> flag and clears the -<constant>V4L2_BUF_FLAG_MAPPED</constant> and -<constant>V4L2_BUF_FLAG_DONE</constant> flags in the -<structfield>flags</structfield> field, or it returns an error code. -This ioctl locks the memory pages of the buffer in physical memory, -they cannot be swapped out to disk. Buffers remain locked until -dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is -called, or until the device is closed.</para> - - <para>To enqueue a <link linkend="dmabuf">DMABUF</link> buffer applications -set the <structfield>memory</structfield> field to -<constant>V4L2_MEMORY_DMABUF</constant> and the <structfield>m.fd</structfield> -field to a file descriptor associated with a DMABUF buffer. When the -multi-planar API is used the <structfield>m.fd</structfield> fields of the -passed array of &v4l2-plane; have to be used instead. When -<constant>VIDIOC_QBUF</constant> is called with a pointer to this structure the -driver sets the <constant>V4L2_BUF_FLAG_QUEUED</constant> flag and clears the -<constant>V4L2_BUF_FLAG_MAPPED</constant> and -<constant>V4L2_BUF_FLAG_DONE</constant> flags in the -<structfield>flags</structfield> field, or it returns an error code. This -ioctl locks the buffer. Locking a buffer means passing it to a driver for a -hardware access (usually DMA). If an application accesses (reads/writes) a -locked buffer then the result is undefined. Buffers remain locked until -dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is called, or -until the device is closed.</para> - - <para>Applications call the <constant>VIDIOC_DQBUF</constant> -ioctl to dequeue a filled (capturing) or displayed (output) buffer -from the driver's outgoing queue. They just set the -<structfield>type</structfield>, <structfield>memory</structfield> -and <structfield>reserved</structfield> -fields of a &v4l2-buffer; as above, when <constant>VIDIOC_DQBUF</constant> -is called with a pointer to this structure the driver fills the -remaining fields or returns an error code. The driver may also set -<constant>V4L2_BUF_FLAG_ERROR</constant> in the <structfield>flags</structfield> -field. It indicates a non-critical (recoverable) streaming error. In such case -the application may continue as normal, but should be aware that data in the -dequeued buffer might be corrupted. When using the multi-planar API, the -planes array must be passed in as well.</para> - - <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no -buffer is in the outgoing queue. When the -<constant>O_NONBLOCK</constant> flag was given to the &func-open; -function, <constant>VIDIOC_DQBUF</constant> returns immediately -with an &EAGAIN; when no buffer is available.</para> - - <para>The <structname>v4l2_buffer</structname> structure is -specified in <xref linkend="buffer" />.</para> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EAGAIN</errorcode></term> - <listitem> - <para>Non-blocking I/O has been selected using -<constant>O_NONBLOCK</constant> and no buffer was in the outgoing -queue.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The buffer <structfield>type</structfield> is not -supported, or the <structfield>index</structfield> is out of bounds, -or no buffers have been allocated yet, or the -<structfield>userptr</structfield> or -<structfield>length</structfield> are invalid.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EIO</errorcode></term> - <listitem> - <para><constant>VIDIOC_DQBUF</constant> failed due to an -internal error. Can also indicate temporary problems like signal -loss. Note the driver might dequeue an (empty) buffer despite -returning an error, or even stop capturing. Reusing such buffer may be unsafe -though and its details (e.g. <structfield>index</structfield>) may not be -returned either. It is recommended that drivers indicate recoverable errors -by setting the <constant>V4L2_BUF_FLAG_ERROR</constant> and returning 0 instead. -In that case the application should be able to safely reuse the buffer and -continue streaming. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EPIPE</errorcode></term> - <listitem> - <para><constant>VIDIOC_DQBUF</constant> returns this on an empty -capture queue for mem2mem codecs if a buffer with the -<constant>V4L2_BUF_FLAG_LAST</constant> was already dequeued and no new buffers -are expected to become available. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml deleted file mode 100644 index e9c70a8f3476..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml +++ /dev/null @@ -1,111 +0,0 @@ -<refentry id="vidioc-query-dv-timings"> - <refmeta> - <refentrytitle>ioctl VIDIOC_QUERY_DV_TIMINGS</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_QUERY_DV_TIMINGS</refname> - <refname>VIDIOC_SUBDEV_QUERY_DV_TIMINGS</refname> - <refpurpose>Sense the DV preset received by the current -input</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_dv_timings *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_QUERY_DV_TIMINGS, VIDIOC_SUBDEV_QUERY_DV_TIMINGS</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <note> - <title>Experimental</title> - <para>This is an <link linkend="experimental"> experimental </link> - interface and may change in the future.</para> - </note> - - <para>The hardware may be able to detect the current DV timings -automatically, similar to sensing the video standard. To do so, applications -call <constant>VIDIOC_QUERY_DV_TIMINGS</constant> with a pointer to a -&v4l2-dv-timings;. Once the hardware detects the timings, it will fill in the -timings structure. - -If the timings could not be detected because there was no signal, then -<errorcode>ENOLINK</errorcode> is returned. If a signal was detected, but -it was unstable and the receiver could not lock to the signal, then -<errorcode>ENOLCK</errorcode> is returned. If the receiver could lock to the signal, -but the format is unsupported (e.g. because the pixelclock is out of range -of the hardware capabilities), then the driver fills in whatever timings it -could find and returns <errorcode>ERANGE</errorcode>. In that case the application -can call &VIDIOC-DV-TIMINGS-CAP; to compare the found timings with the hardware's -capabilities in order to give more precise feedback to the user. -</para> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>ENODATA</errorcode></term> - <listitem> - <para>Digital video timings are not supported for this input or output.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>ENOLINK</errorcode></term> - <listitem> - <para>No timings could be detected because no signal was found. -</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>ENOLCK</errorcode></term> - <listitem> - <para>The signal was unstable and the hardware could not lock on to it. -</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>ERANGE</errorcode></term> - <listitem> - <para>Timings were found, but they are out of range of the hardware -capabilities. -</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-querybuf.xml b/Documentation/DocBook/media/v4l/vidioc-querybuf.xml deleted file mode 100644 index 50bfcb5e8508..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-querybuf.xml +++ /dev/null @@ -1,106 +0,0 @@ -<refentry id="vidioc-querybuf"> - <refmeta> - <refentrytitle>ioctl VIDIOC_QUERYBUF</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_QUERYBUF</refname> - <refpurpose>Query the status of a buffer</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_buffer *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_QUERYBUF</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>This ioctl is part of the <link linkend="mmap">streaming -</link> I/O method. It can be used to query the status of a -buffer at any time after buffers have been allocated with the -&VIDIOC-REQBUFS; ioctl.</para> - - <para>Applications set the <structfield>type</structfield> field - of a &v4l2-buffer; to the same buffer type as was previously used with -&v4l2-format; <structfield>type</structfield> and &v4l2-requestbuffers; -<structfield>type</structfield>, and the <structfield>index</structfield> - field. Valid index numbers range from zero -to the number of buffers allocated with &VIDIOC-REQBUFS; - (&v4l2-requestbuffers; <structfield>count</structfield>) minus one. -The <structfield>reserved</structfield> and <structfield>reserved2 </structfield> -fields must be set to 0. -When using the <link linkend="planar-apis">multi-planar API</link>, the -<structfield>m.planes</structfield> field must contain a userspace pointer to an -array of &v4l2-plane; and the <structfield>length</structfield> field has -to be set to the number of elements in that array. -After calling <constant>VIDIOC_QUERYBUF</constant> with a pointer to - this structure drivers return an error code or fill the rest of -the structure.</para> - - <para>In the <structfield>flags</structfield> field the -<constant>V4L2_BUF_FLAG_MAPPED</constant>, -<constant>V4L2_BUF_FLAG_PREPARED</constant>, -<constant>V4L2_BUF_FLAG_QUEUED</constant> and -<constant>V4L2_BUF_FLAG_DONE</constant> flags will be valid. The -<structfield>memory</structfield> field will be set to the current -I/O method. For the single-planar API, the <structfield>m.offset</structfield> -contains the offset of the buffer from the start of the device memory, -the <structfield>length</structfield> field its size. For the multi-planar API, -fields <structfield>m.mem_offset</structfield> and -<structfield>length</structfield> in the <structfield>m.planes</structfield> -array elements will be used instead and the <structfield>length</structfield> -field of &v4l2-buffer; is set to the number of filled-in array elements. -The driver may or may not set the remaining fields and flags, they are -meaningless in this context.</para> - - <para>The <structname>v4l2_buffer</structname> structure is - specified in <xref linkend="buffer" />.</para> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The buffer <structfield>type</structfield> is not -supported, or the <structfield>index</structfield> is out of bounds.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-querycap.xml b/Documentation/DocBook/media/v4l/vidioc-querycap.xml deleted file mode 100644 index cd82148dedd7..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-querycap.xml +++ /dev/null @@ -1,350 +0,0 @@ -<refentry id="vidioc-querycap"> - <refmeta> - <refentrytitle>ioctl VIDIOC_QUERYCAP</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_QUERYCAP</refname> - <refpurpose>Query device capabilities</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_capability *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_QUERYCAP</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>All V4L2 devices support the -<constant>VIDIOC_QUERYCAP</constant> ioctl. It is used to identify -kernel devices compatible with this specification and to obtain -information about driver and hardware capabilities. The ioctl takes a -pointer to a &v4l2-capability; which is filled by the driver. When the -driver is not compatible with this specification the ioctl returns an -&EINVAL;.</para> - - <table pgwide="1" frame="none" id="v4l2-capability"> - <title>struct <structname>v4l2_capability</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u8</entry> - <entry><structfield>driver</structfield>[16]</entry> - <entry><para>Name of the driver, a unique NUL-terminated -ASCII string. For example: "bttv". Driver specific applications can -use this information to verify the driver identity. It is also useful -to work around known bugs, or to identify drivers in error reports.</para> -<para>Storing strings in fixed sized arrays is bad -practice but unavoidable here. Drivers and applications should take -precautions to never read or write beyond the end of the array and to -make sure the strings are properly NUL-terminated.</para></entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>card</structfield>[32]</entry> - <entry>Name of the device, a NUL-terminated UTF-8 string. -For example: "Yoyodyne TV/FM". One driver may support different brands -or models of video hardware. This information is intended for users, -for example in a menu of available devices. Since multiple TV cards of -the same brand may be installed which are supported by the same -driver, this name should be combined with the character device file -name (⪚ <filename>/dev/video2</filename>) or the -<structfield>bus_info</structfield> string to avoid -ambiguities.</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>bus_info</structfield>[32]</entry> - <entry>Location of the device in the system, a -NUL-terminated ASCII string. For example: "PCI:0000:05:06.0". This -information is intended for users, to distinguish multiple -identical devices. If no such information is available the field must -simply count the devices controlled by the driver ("platform:vivi-000"). -The bus_info must start with "PCI:" for PCI boards, "PCIe:" for PCI Express boards, -"usb-" for USB devices, "I2C:" for i2c devices, "ISA:" for ISA devices, -"parport" for parallel port devices and "platform:" for platform devices.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>version</structfield></entry> - <entry><para>Version number of the driver.</para> -<para>Starting with kernel 3.1, the version reported is provided by the -V4L2 subsystem following the kernel numbering scheme. However, it -may not always return the same version as the kernel if, for example, -a stable or distribution-modified kernel uses the V4L2 stack from a -newer kernel.</para> -<para>The version number is formatted using the -<constant>KERNEL_VERSION()</constant> macro:</para></entry> - </row> - <row> - <entry spanname="hspan"><para> -<programlisting> -#define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c)) - -__u32 version = KERNEL_VERSION(0, 8, 1); - -printf ("Version: %u.%u.%u\n", - (version >> 16) & 0xFF, - (version >> 8) & 0xFF, - version & 0xFF); -</programlisting></para></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>capabilities</structfield></entry> - <entry>Available capabilities of the physical device as a whole, see <xref - linkend="device-capabilities" />. The same physical device can export - multiple devices in /dev (e.g. /dev/videoX, /dev/vbiY and /dev/radioZ). - The <structfield>capabilities</structfield> field should contain a union - of all capabilities available around the several V4L2 devices exported - to userspace. - For all those devices the <structfield>capabilities</structfield> field - returns the same set of capabilities. This allows applications to open - just one of the devices (typically the video device) and discover whether - video, vbi and/or radio are also supported. - </entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>device_caps</structfield></entry> - <entry>Device capabilities of the opened device, see <xref - linkend="device-capabilities" />. Should contain the available capabilities - of that specific device node. So, for example, <structfield>device_caps</structfield> - of a radio device will only contain radio related capabilities and - no video or vbi capabilities. This field is only set if the <structfield>capabilities</structfield> - field contains the <constant>V4L2_CAP_DEVICE_CAPS</constant> capability. - Only the <structfield>capabilities</structfield> field can have the - <constant>V4L2_CAP_DEVICE_CAPS</constant> capability, <structfield>device_caps</structfield> - will never set <constant>V4L2_CAP_DEVICE_CAPS</constant>. - </entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[3]</entry> - <entry>Reserved for future extensions. Drivers must set -this array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="device-capabilities"> - <title>Device Capabilities Flags</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_CAP_VIDEO_CAPTURE</constant></entry> - <entry>0x00000001</entry> - <entry>The device supports the single-planar API through the <link -linkend="capture">Video Capture</link> interface.</entry> - </row> - <row> - <entry><constant>V4L2_CAP_VIDEO_CAPTURE_MPLANE</constant></entry> - <entry>0x00001000</entry> - <entry>The device supports the - <link linkend="planar-apis">multi-planar API</link> through the - <link linkend="capture">Video Capture</link> interface.</entry> - </row> - <row> - <entry><constant>V4L2_CAP_VIDEO_OUTPUT</constant></entry> - <entry>0x00000002</entry> - <entry>The device supports the single-planar API through the <link -linkend="output">Video Output</link> interface.</entry> - </row> - <row> - <entry><constant>V4L2_CAP_VIDEO_OUTPUT_MPLANE</constant></entry> - <entry>0x00002000</entry> - <entry>The device supports the - <link linkend="planar-apis">multi-planar API</link> through the - <link linkend="output">Video Output</link> interface.</entry> - </row> - <row> - <entry><constant>V4L2_CAP_VIDEO_M2M</constant></entry> - <entry>0x00004000</entry> - <entry>The device supports the single-planar API through the - Video Memory-To-Memory interface.</entry> - </row> - <row> - <entry><constant>V4L2_CAP_VIDEO_M2M_MPLANE</constant></entry> - <entry>0x00008000</entry> - <entry>The device supports the - <link linkend="planar-apis">multi-planar API</link> through the - Video Memory-To-Memory interface.</entry> - </row> - <row> - <entry><constant>V4L2_CAP_VIDEO_OVERLAY</constant></entry> - <entry>0x00000004</entry> - <entry>The device supports the <link -linkend="overlay">Video Overlay</link> interface. A video overlay device -typically stores captured images directly in the video memory of a -graphics card, with hardware clipping and scaling.</entry> - </row> - <row> - <entry><constant>V4L2_CAP_VBI_CAPTURE</constant></entry> - <entry>0x00000010</entry> - <entry>The device supports the <link linkend="raw-vbi">Raw -VBI Capture</link> interface, providing Teletext and Closed Caption -data.</entry> - </row> - <row> - <entry><constant>V4L2_CAP_VBI_OUTPUT</constant></entry> - <entry>0x00000020</entry> - <entry>The device supports the <link linkend="raw-vbi">Raw VBI Output</link> interface.</entry> - </row> - <row> - <entry><constant>V4L2_CAP_SLICED_VBI_CAPTURE</constant></entry> - <entry>0x00000040</entry> - <entry>The device supports the <link linkend="sliced">Sliced VBI Capture</link> interface.</entry> - </row> - <row> - <entry><constant>V4L2_CAP_SLICED_VBI_OUTPUT</constant></entry> - <entry>0x00000080</entry> - <entry>The device supports the <link linkend="sliced">Sliced VBI Output</link> interface.</entry> - </row> - <row> - <entry><constant>V4L2_CAP_RDS_CAPTURE</constant></entry> - <entry>0x00000100</entry> - <entry>The device supports the <link linkend="rds">RDS</link> capture interface.</entry> - </row> - <row> - <entry><constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant></entry> - <entry>0x00000200</entry> - <entry>The device supports the <link linkend="osd">Video -Output Overlay</link> (OSD) interface. Unlike the <wordasword>Video -Overlay</wordasword> interface, this is a secondary function of video -output devices and overlays an image onto an outgoing video signal. -When the driver sets this flag, it must clear the -<constant>V4L2_CAP_VIDEO_OVERLAY</constant> flag and vice -versa.<footnote><para>The &v4l2-framebuffer; lacks an -&v4l2-buf-type; field, therefore the type of overlay is implied by the -driver capabilities.</para></footnote></entry> - </row> - <row> - <entry><constant>V4L2_CAP_HW_FREQ_SEEK</constant></entry> - <entry>0x00000400</entry> - <entry>The device supports the &VIDIOC-S-HW-FREQ-SEEK; ioctl for -hardware frequency seeking.</entry> - </row> - <row> - <entry><constant>V4L2_CAP_RDS_OUTPUT</constant></entry> - <entry>0x00000800</entry> - <entry>The device supports the <link linkend="rds">RDS</link> output interface.</entry> - </row> - <row> - <entry><constant>V4L2_CAP_TUNER</constant></entry> - <entry>0x00010000</entry> - <entry>The device has some sort of tuner to -receive RF-modulated video signals. For more information about -tuner programming see -<xref linkend="tuner" />.</entry> - </row> - <row> - <entry><constant>V4L2_CAP_AUDIO</constant></entry> - <entry>0x00020000</entry> - <entry>The device has audio inputs or outputs. It may or -may not support audio recording or playback, in PCM or compressed -formats. PCM audio support must be implemented as ALSA or OSS -interface. For more information on audio inputs and outputs see <xref - linkend="audio" />.</entry> - </row> - <row> - <entry><constant>V4L2_CAP_RADIO</constant></entry> - <entry>0x00040000</entry> - <entry>This is a radio receiver.</entry> - </row> - <row> - <entry><constant>V4L2_CAP_MODULATOR</constant></entry> - <entry>0x00080000</entry> - <entry>The device has some sort of modulator to -emit RF-modulated video/audio signals. For more information about -modulator programming see -<xref linkend="tuner" />.</entry> - </row> - <row> - <entry><constant>V4L2_CAP_SDR_CAPTURE</constant></entry> - <entry>0x00100000</entry> - <entry>The device supports the -<link linkend="sdr">SDR Capture</link> interface.</entry> - </row> - <row> - <entry><constant>V4L2_CAP_EXT_PIX_FORMAT</constant></entry> - <entry>0x00200000</entry> - <entry>The device supports the &v4l2-pix-format; extended -fields.</entry> - </row> - <row> - <entry><constant>V4L2_CAP_SDR_OUTPUT</constant></entry> - <entry>0x00400000</entry> - <entry>The device supports the -<link linkend="sdr">SDR Output</link> interface.</entry> - </row> - <row> - <entry><constant>V4L2_CAP_READWRITE</constant></entry> - <entry>0x01000000</entry> - <entry>The device supports the <link -linkend="rw">read()</link> and/or <link linkend="rw">write()</link> -I/O methods.</entry> - </row> - <row> - <entry><constant>V4L2_CAP_ASYNCIO</constant></entry> - <entry>0x02000000</entry> - <entry>The device supports the <link -linkend="async">asynchronous</link> I/O methods.</entry> - </row> - <row> - <entry><constant>V4L2_CAP_STREAMING</constant></entry> - <entry>0x04000000</entry> - <entry>The device supports the <link -linkend="mmap">streaming</link> I/O method.</entry> - </row> - <row> - <entry><constant>V4L2_CAP_DEVICE_CAPS</constant></entry> - <entry>0x80000000</entry> - <entry>The driver fills the <structfield>device_caps</structfield> - field. This capability can only appear in the <structfield>capabilities</structfield> - field and never in the <structfield>device_caps</structfield> field.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml deleted file mode 100644 index 55b7582cf314..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml +++ /dev/null @@ -1,661 +0,0 @@ -<refentry id="vidioc-queryctrl"> - <refmeta> - <refentrytitle>ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_QUERYCTRL</refname> - <refname>VIDIOC_QUERY_EXT_CTRL</refname> - <refname>VIDIOC_QUERYMENU</refname> - <refpurpose>Enumerate controls and menu control items</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_queryctrl *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_query_ext_ctrl *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_querymenu *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>To query the attributes of a control applications set the -<structfield>id</structfield> field of a &v4l2-queryctrl; and call the -<constant>VIDIOC_QUERYCTRL</constant> ioctl with a pointer to this -structure. The driver fills the rest of the structure or returns an -&EINVAL; when the <structfield>id</structfield> is invalid.</para> - - <para>It is possible to enumerate controls by calling -<constant>VIDIOC_QUERYCTRL</constant> with successive -<structfield>id</structfield> values starting from -<constant>V4L2_CID_BASE</constant> up to and exclusive -<constant>V4L2_CID_LASTP1</constant>. Drivers may return -<errorcode>EINVAL</errorcode> if a control in this range is not -supported. Further applications can enumerate private controls, which -are not defined in this specification, by starting at -<constant>V4L2_CID_PRIVATE_BASE</constant> and incrementing -<structfield>id</structfield> until the driver returns -<errorcode>EINVAL</errorcode>.</para> - - <para>In both cases, when the driver sets the -<constant>V4L2_CTRL_FLAG_DISABLED</constant> flag in the -<structfield>flags</structfield> field this control is permanently -disabled and should be ignored by the application.<footnote> - <para><constant>V4L2_CTRL_FLAG_DISABLED</constant> was -intended for two purposes: Drivers can skip predefined controls not -supported by the hardware (although returning EINVAL would do as -well), or disable predefined and private controls after hardware -detection without the trouble of reordering control arrays and indices -(EINVAL cannot be used to skip private controls because it would -prematurely end the enumeration).</para></footnote></para> - - <para>When the application ORs <structfield>id</structfield> with -<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> the driver returns the -next supported non-compound control, or <errorcode>EINVAL</errorcode> -if there is none. In addition, the <constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant> -flag can be specified to enumerate all compound controls (i.e. controls -with type ≥ <constant>V4L2_CTRL_COMPOUND_TYPES</constant> and/or array -control, in other words controls that contain more than one value). -Specify both <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> and -<constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant> in order to enumerate -all controls, compound or not. Drivers which do not support these flags yet -always return <errorcode>EINVAL</errorcode>.</para> - - <para>The <constant>VIDIOC_QUERY_EXT_CTRL</constant> ioctl was -introduced in order to better support controls that can use compound -types, and to expose additional control information that cannot be -returned in &v4l2-queryctrl; since that structure is full.</para> - - <para><constant>VIDIOC_QUERY_EXT_CTRL</constant> is used in the -same way as <constant>VIDIOC_QUERYCTRL</constant>, except that the -<structfield>reserved</structfield> array must be zeroed as well.</para> - - <para>Additional information is required for menu controls: the -names of the menu items. To query them applications set the -<structfield>id</structfield> and <structfield>index</structfield> -fields of &v4l2-querymenu; and call the -<constant>VIDIOC_QUERYMENU</constant> ioctl with a pointer to this -structure. The driver fills the rest of the structure or returns an -&EINVAL; when the <structfield>id</structfield> or -<structfield>index</structfield> is invalid. Menu items are enumerated -by calling <constant>VIDIOC_QUERYMENU</constant> with successive -<structfield>index</structfield> values from &v4l2-queryctrl; -<structfield>minimum</structfield> to -<structfield>maximum</structfield>, inclusive. Note that it is possible -for <constant>VIDIOC_QUERYMENU</constant> to return an &EINVAL; for some -indices between <structfield>minimum</structfield> and <structfield>maximum</structfield>. -In that case that particular menu item is not supported by this driver. Also note that -the <structfield>minimum</structfield> value is not necessarily 0.</para> - - <para>See also the examples in <xref linkend="control" />.</para> - - <table pgwide="1" frame="none" id="v4l2-queryctrl"> - <title>struct <structname>v4l2_queryctrl</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>id</structfield></entry> - <entry>Identifies the control, set by the application. See -<xref linkend="control-id" /> for predefined IDs. When the ID is ORed -with V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and returns -the first control with a higher ID. Drivers which do not support this -flag yet always return an &EINVAL;.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry>Type of control, see <xref - linkend="v4l2-ctrl-type" />.</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>name</structfield>[32]</entry> - <entry>Name of the control, a NUL-terminated ASCII -string. This information is intended for the user.</entry> - </row> - <row> - <entry>__s32</entry> - <entry><structfield>minimum</structfield></entry> - <entry>Minimum value, inclusive. This field gives a lower -bound for the control. See &v4l2-ctrl-type; how the minimum value is to -be used for each possible control type. Note that this a signed 32-bit value.</entry> - </row> - <row> - <entry>__s32</entry> - <entry><structfield>maximum</structfield></entry> - <entry>Maximum value, inclusive. This field gives an upper -bound for the control. See &v4l2-ctrl-type; how the maximum value is to -be used for each possible control type. Note that this a signed 32-bit value.</entry> - </row> - <row> - <entry>__s32</entry> - <entry><structfield>step</structfield></entry> - <entry><para>This field gives a step size for the control. -See &v4l2-ctrl-type; how the step value is to be used for each possible -control type. Note that this an unsigned 32-bit value. -</para><para>Generally drivers should not scale hardware -control values. It may be necessary for example when the -<structfield>name</structfield> or <structfield>id</structfield> imply -a particular unit and the hardware actually accepts only multiples of -said unit. If so, drivers must take care values are properly rounded -when scaling, such that errors will not accumulate on repeated -read-write cycles.</para><para>This field gives the smallest change of -an integer control actually affecting hardware. Often the information -is needed when the user can change controls by keyboard or GUI -buttons, rather than a slider. When for example a hardware register -accepts values 0-511 and the driver reports 0-65535, step should be -128.</para><para>Note that although signed, the step value is supposed to -be always positive.</para></entry> - </row> - <row> - <entry>__s32</entry> - <entry><structfield>default_value</structfield></entry> - <entry>The default value of a -<constant>V4L2_CTRL_TYPE_INTEGER</constant>, -<constant>_BOOLEAN</constant>, <constant>_BITMASK</constant>, -<constant>_MENU</constant> or <constant>_INTEGER_MENU</constant> control. -Not valid for other types of controls. -Note that drivers reset controls to their default value only when the -driver is first loaded, never afterwards.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry>Control flags, see <xref - linkend="control-flags" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[2]</entry> - <entry>Reserved for future extensions. Drivers must set -the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="v4l2-query-ext-ctrl"> - <title>struct <structname>v4l2_query_ext_ctrl</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>id</structfield></entry> - <entry>Identifies the control, set by the application. See -<xref linkend="control-id" /> for predefined IDs. When the ID is ORed -with <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> the driver clears the -flag and returns the first non-compound control with a higher ID. When the -ID is ORed with <constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant> the driver -clears the flag and returns the first compound control with a higher ID. -Set both to get the first control (compound or not) with a higher ID.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry>Type of control, see <xref - linkend="v4l2-ctrl-type" />.</entry> - </row> - <row> - <entry>char</entry> - <entry><structfield>name</structfield>[32]</entry> - <entry>Name of the control, a NUL-terminated ASCII -string. This information is intended for the user.</entry> - </row> - <row> - <entry>__s64</entry> - <entry><structfield>minimum</structfield></entry> - <entry>Minimum value, inclusive. This field gives a lower -bound for the control. See &v4l2-ctrl-type; how the minimum value is to -be used for each possible control type. Note that this a signed 64-bit value.</entry> - </row> - <row> - <entry>__s64</entry> - <entry><structfield>maximum</structfield></entry> - <entry>Maximum value, inclusive. This field gives an upper -bound for the control. See &v4l2-ctrl-type; how the maximum value is to -be used for each possible control type. Note that this a signed 64-bit value.</entry> - </row> - <row> - <entry>__u64</entry> - <entry><structfield>step</structfield></entry> - <entry><para>This field gives a step size for the control. -See &v4l2-ctrl-type; how the step value is to be used for each possible -control type. Note that this an unsigned 64-bit value. -</para><para>Generally drivers should not scale hardware -control values. It may be necessary for example when the -<structfield>name</structfield> or <structfield>id</structfield> imply -a particular unit and the hardware actually accepts only multiples of -said unit. If so, drivers must take care values are properly rounded -when scaling, such that errors will not accumulate on repeated -read-write cycles.</para><para>This field gives the smallest change of -an integer control actually affecting hardware. Often the information -is needed when the user can change controls by keyboard or GUI -buttons, rather than a slider. When for example a hardware register -accepts values 0-511 and the driver reports 0-65535, step should be -128.</para></entry> - </row> - <row> - <entry>__s64</entry> - <entry><structfield>default_value</structfield></entry> - <entry>The default value of a -<constant>V4L2_CTRL_TYPE_INTEGER</constant>, <constant>_INTEGER64</constant>, -<constant>_BOOLEAN</constant>, <constant>_BITMASK</constant>, -<constant>_MENU</constant>, <constant>_INTEGER_MENU</constant>, -<constant>_U8</constant> or <constant>_U16</constant> control. -Not valid for other types of controls. -Note that drivers reset controls to their default value only when the -driver is first loaded, never afterwards. -</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry>Control flags, see <xref - linkend="control-flags" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>elem_size</structfield></entry> - <entry>The size in bytes of a single element of the array. -Given a char pointer <constant>p</constant> to a 3-dimensional array you can find the -position of cell <constant>(z, y, x)</constant> as follows: -<constant>p + ((z * dims[1] + y) * dims[0] + x) * elem_size</constant>. <structfield>elem_size</structfield> -is always valid, also when the control isn't an array. For string controls -<structfield>elem_size</structfield> is equal to <structfield>maximum + 1</structfield>. -</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>elems</structfield></entry> - <entry>The number of elements in the N-dimensional array. If this control -is not an array, then <structfield>elems</structfield> is 1. The <structfield>elems</structfield> -field can never be 0.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>nr_of_dims</structfield></entry> - <entry>The number of dimension in the N-dimensional array. If this control -is not an array, then this field is 0.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>dims[V4L2_CTRL_MAX_DIMS]</structfield></entry> - <entry>The size of each dimension. The first <structfield>nr_of_dims</structfield> -elements of this array must be non-zero, all remaining elements must be zero.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[32]</entry> - <entry>Reserved for future extensions. Applications and drivers -must set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="v4l2-querymenu"> - <title>struct <structname>v4l2_querymenu</structname></title> - <tgroup cols="4"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry></entry> - <entry><structfield>id</structfield></entry> - <entry>Identifies the control, set by the application -from the respective &v4l2-queryctrl; -<structfield>id</structfield>.</entry> - </row> - <row> - <entry>__u32</entry> - <entry></entry> - <entry><structfield>index</structfield></entry> - <entry>Index of the menu item, starting at zero, set by - the application.</entry> - </row> - <row> - <entry>union</entry> - <entry></entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry></entry> - <entry>__u8</entry> - <entry><structfield>name</structfield>[32]</entry> - <entry>Name of the menu item, a NUL-terminated ASCII -string. This information is intended for the user. This field is valid -for <constant>V4L2_CTRL_FLAG_MENU</constant> type controls.</entry> - </row> - <row> - <entry></entry> - <entry>__s64</entry> - <entry><structfield>value</structfield></entry> - <entry> - Value of the integer menu item. This field is valid for - <constant>V4L2_CTRL_FLAG_INTEGER_MENU</constant> type - controls. - </entry> - </row> - <row> - <entry>__u32</entry> - <entry></entry> - <entry><structfield>reserved</structfield></entry> - <entry>Reserved for future extensions. Drivers must set -the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="v4l2-ctrl-type"> - <title>enum v4l2_ctrl_type</title> - <tgroup cols="5" align="left"> - <colspec colwidth="30*" /> - <colspec colwidth="5*" align="center" /> - <colspec colwidth="5*" align="center" /> - <colspec colwidth="5*" align="center" /> - <colspec colwidth="55*" /> - <thead> - <row> - <entry>Type</entry> - <entry><structfield>minimum</structfield></entry> - <entry><structfield>step</structfield></entry> - <entry><structfield>maximum</structfield></entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry><constant>V4L2_CTRL_TYPE_INTEGER</constant></entry> - <entry>any</entry> - <entry>any</entry> - <entry>any</entry> - <entry>An integer-valued control ranging from minimum to -maximum inclusive. The step value indicates the increment between -values.</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_TYPE_BOOLEAN</constant></entry> - <entry>0</entry> - <entry>1</entry> - <entry>1</entry> - <entry>A boolean-valued control. Zero corresponds to -"disabled", and one means "enabled".</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_TYPE_MENU</constant></entry> - <entry>≥ 0</entry> - <entry>1</entry> - <entry>N-1</entry> - <entry>The control has a menu of N choices. The names of -the menu items can be enumerated with the -<constant>VIDIOC_QUERYMENU</constant> ioctl.</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_TYPE_INTEGER_MENU</constant></entry> - <entry>≥ 0</entry> - <entry>1</entry> - <entry>N-1</entry> - <entry> - The control has a menu of N choices. The values of the - menu items can be enumerated with the - <constant>VIDIOC_QUERYMENU</constant> ioctl. This is - similar to <constant>V4L2_CTRL_TYPE_MENU</constant> - except that instead of strings, the menu items are - signed 64-bit integers. - </entry> - </row> - <row> - <entry><constant>V4L2_CTRL_TYPE_BITMASK</constant></entry> - <entry>0</entry> - <entry>n/a</entry> - <entry>any</entry> - <entry>A bitmask field. The maximum value is the set of bits that can -be used, all other bits are to be 0. The maximum value is interpreted as a __u32, -allowing the use of bit 31 in the bitmask.</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_TYPE_BUTTON</constant></entry> - <entry>0</entry> - <entry>0</entry> - <entry>0</entry> - <entry>A control which performs an action when set. -Drivers must ignore the value passed with -<constant>VIDIOC_S_CTRL</constant> and return an &EINVAL; on a -<constant>VIDIOC_G_CTRL</constant> attempt.</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_TYPE_INTEGER64</constant></entry> - <entry>any</entry> - <entry>any</entry> - <entry>any</entry> - <entry>A 64-bit integer valued control. Minimum, maximum -and step size cannot be queried using <constant>VIDIOC_QUERYCTRL</constant>. -Only <constant>VIDIOC_QUERY_EXT_CTRL</constant> can retrieve the 64-bit -min/max/step values, they should be interpreted as n/a when using -<constant>VIDIOC_QUERYCTRL</constant>.</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_TYPE_STRING</constant></entry> - <entry>≥ 0</entry> - <entry>≥ 1</entry> - <entry>≥ 0</entry> - <entry>The minimum and maximum string lengths. The step size -means that the string must be (minimum + N * step) characters long for -N ≥ 0. These lengths do not include the terminating zero, so in order to -pass a string of length 8 to &VIDIOC-S-EXT-CTRLS; you need to set the -<structfield>size</structfield> field of &v4l2-ext-control; to 9. For &VIDIOC-G-EXT-CTRLS; you can -set the <structfield>size</structfield> field to <structfield>maximum</structfield> + 1. -Which character encoding is used will depend on the string control itself and -should be part of the control documentation.</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant></entry> - <entry>n/a</entry> - <entry>n/a</entry> - <entry>n/a</entry> - <entry>This is not a control. When -<constant>VIDIOC_QUERYCTRL</constant> is called with a control ID -equal to a control class code (see <xref linkend="ctrl-class" />) + 1, the -ioctl returns the name of the control class and this control type. -Older drivers which do not support this feature return an -&EINVAL;.</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_TYPE_U8</constant></entry> - <entry>any</entry> - <entry>any</entry> - <entry>any</entry> - <entry>An unsigned 8-bit valued control ranging from minimum to -maximum inclusive. The step value indicates the increment between -values. -</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_TYPE_U16</constant></entry> - <entry>any</entry> - <entry>any</entry> - <entry>any</entry> - <entry>An unsigned 16-bit valued control ranging from minimum to -maximum inclusive. The step value indicates the increment between -values. -</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_TYPE_U32</constant></entry> - <entry>any</entry> - <entry>any</entry> - <entry>any</entry> - <entry>An unsigned 32-bit valued control ranging from minimum to -maximum inclusive. The step value indicates the increment between -values. -</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="control-flags"> - <title>Control Flags</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_CTRL_FLAG_DISABLED</constant></entry> - <entry>0x0001</entry> - <entry>This control is permanently disabled and should be -ignored by the application. Any attempt to change the control will -result in an &EINVAL;.</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_FLAG_GRABBED</constant></entry> - <entry>0x0002</entry> - <entry>This control is temporarily unchangeable, for -example because another application took over control of the -respective resource. Such controls may be displayed specially in a -user interface. Attempts to change the control may result in an -&EBUSY;.</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_FLAG_READ_ONLY</constant></entry> - <entry>0x0004</entry> - <entry>This control is permanently readable only. Any -attempt to change the control will result in an &EINVAL;.</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_FLAG_UPDATE</constant></entry> - <entry>0x0008</entry> - <entry>A hint that changing this control may affect the -value of other controls within the same control class. Applications -should update their user interface accordingly.</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_FLAG_INACTIVE</constant></entry> - <entry>0x0010</entry> - <entry>This control is not applicable to the current -configuration and should be displayed accordingly in a user interface. -For example the flag may be set on a MPEG audio level 2 bitrate -control when MPEG audio encoding level 1 was selected with another -control.</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_FLAG_SLIDER</constant></entry> - <entry>0x0020</entry> - <entry>A hint that this control is best represented as a -slider-like element in a user interface.</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_FLAG_WRITE_ONLY</constant></entry> - <entry>0x0040</entry> - <entry>This control is permanently writable only. Any -attempt to read the control will result in an &EACCES; error code. This -flag is typically present for relative controls or action controls where -writing a value will cause the device to carry out a given action -(⪚ motor control) but no meaningful value can be returned.</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_FLAG_VOLATILE</constant></entry> - <entry>0x0080</entry> - <entry>This control is volatile, which means that the value of the control -changes continuously. A typical example would be the current gain value if the device -is in auto-gain mode. In such a case the hardware calculates the gain value based on -the lighting conditions which can change over time. Note that setting a new value for -a volatile control will have no effect and no <constant>V4L2_EVENT_CTRL_CH_VALUE</constant> -will be sent, unless the <constant>V4L2_CTRL_FLAG_EXECUTE_ON_WRITE</constant> flag -(see below) is also set. Otherwise the new value will just be ignored.</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant></entry> - <entry>0x0100</entry> - <entry>This control has a pointer type, so its value has to be accessed -using one of the pointer fields of &v4l2-ext-control;. This flag is set for controls -that are an array, string, or have a compound type. In all cases you have to set a -pointer to memory containing the payload of the control.</entry> - </row> - <row> - <entry><constant>V4L2_CTRL_FLAG_EXECUTE_ON_WRITE</constant></entry> - <entry>0x0200</entry> - <entry>The value provided to the control will be propagated to the driver -even if it remains constant. This is required when the control represents an action -on the hardware. For example: clearing an error flag or triggering the flash. All the -controls of the type <constant>V4L2_CTRL_TYPE_BUTTON</constant> have this flag set.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The &v4l2-queryctrl; <structfield>id</structfield> -is invalid. The &v4l2-querymenu; <structfield>id</structfield> is -invalid or <structfield>index</structfield> is out of range (less than -<structfield>minimum</structfield> or greater than <structfield>maximum</structfield>) -or this particular menu item is not supported by the driver.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EACCES</errorcode></term> - <listitem> - <para>An attempt was made to read a write-only control.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-querystd.xml b/Documentation/DocBook/media/v4l/vidioc-querystd.xml deleted file mode 100644 index 222348542182..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-querystd.xml +++ /dev/null @@ -1,75 +0,0 @@ -<refentry id="vidioc-querystd"> - <refmeta> - <refentrytitle>ioctl VIDIOC_QUERYSTD</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_QUERYSTD</refname> - <refpurpose>Sense the video standard received by the current -input</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>v4l2_std_id *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_QUERYSTD</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>The hardware may be able to detect the current video -standard automatically. To do so, applications call <constant> -VIDIOC_QUERYSTD</constant> with a pointer to a &v4l2-std-id; type. The -driver stores here a set of candidates, this can be a single flag or a -set of supported standards if for example the hardware can only -distinguish between 50 and 60 Hz systems. If no signal was detected, -then the driver will return V4L2_STD_UNKNOWN. When detection is not -possible or fails, the set must contain all standards supported by the -current video input or output.</para> - - </refsect1> - - <refsect1> - &return-value; - <variablelist> - <varlistentry> - <term><errorcode>ENODATA</errorcode></term> - <listitem> - <para>Standard video timings are not supported for this input or output.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml b/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml deleted file mode 100644 index 0f193fda0470..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml +++ /dev/null @@ -1,137 +0,0 @@ -<refentry id="vidioc-reqbufs"> - <refmeta> - <refentrytitle>ioctl VIDIOC_REQBUFS</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_REQBUFS</refname> - <refpurpose>Initiate Memory Mapping or User Pointer I/O</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_requestbuffers *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_REQBUFS</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - -<para>This ioctl is used to initiate <link linkend="mmap">memory mapped</link>, -<link linkend="userp">user pointer</link> or <link -linkend="dmabuf">DMABUF</link> based I/O. Memory mapped buffers are located in -device memory and must be allocated with this ioctl before they can be mapped -into the application's address space. User buffers are allocated by -applications themselves, and this ioctl is merely used to switch the driver -into user pointer I/O mode and to setup some internal structures. -Similarly, DMABUF buffers are allocated by applications through a device -driver, and this ioctl only configures the driver into DMABUF I/O mode without -performing any direct allocation.</para> - - <para>To allocate device buffers applications initialize all fields of the -<structname>v4l2_requestbuffers</structname> structure. They set the -<structfield>type</structfield> field to the respective stream or buffer type, -the <structfield>count</structfield> field to the desired number of buffers, -<structfield>memory</structfield> must be set to the requested I/O method and -the <structfield>reserved</structfield> array must be zeroed. When the ioctl is -called with a pointer to this structure the driver will attempt to allocate the -requested number of buffers and it stores the actual number allocated in the -<structfield>count</structfield> field. It can be smaller than the number -requested, even zero, when the driver runs out of free memory. A larger number -is also possible when the driver requires more buffers to function correctly. -For example video output requires at least two buffers, one displayed and one -filled by the application.</para> - <para>When the I/O method is not supported the ioctl -returns an &EINVAL;.</para> - - <para>Applications can call <constant>VIDIOC_REQBUFS</constant> -again to change the number of buffers, however this cannot succeed -when any buffers are still mapped. A <structfield>count</structfield> -value of zero frees all buffers, after aborting or finishing any DMA -in progress, an implicit &VIDIOC-STREAMOFF;. <!-- mhs: I see no -reason why munmap()ping one or even all buffers must imply -streamoff.--></para> - - <table pgwide="1" frame="none" id="v4l2-requestbuffers"> - <title>struct <structname>v4l2_requestbuffers</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>count</structfield></entry> - <entry>The number of buffers requested or granted.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry>Type of the stream or buffers, this is the same -as the &v4l2-format; <structfield>type</structfield> field. See <xref - linkend="v4l2-buf-type" /> for valid values.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>memory</structfield></entry> - <entry>Applications set this field to -<constant>V4L2_MEMORY_MMAP</constant>, -<constant>V4L2_MEMORY_DMABUF</constant> or -<constant>V4L2_MEMORY_USERPTR</constant>. See <xref linkend="v4l2-memory" -/>.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[2]</entry> - <entry>A place holder for future extensions. Drivers and applications -must set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The buffer type (<structfield>type</structfield> field) or the -requested I/O method (<structfield>memory</structfield>) is not -supported.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml b/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml deleted file mode 100644 index a5fc4c4880f3..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml +++ /dev/null @@ -1,188 +0,0 @@ -<refentry id="vidioc-s-hw-freq-seek"> - <refmeta> - <refentrytitle>ioctl VIDIOC_S_HW_FREQ_SEEK</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_S_HW_FREQ_SEEK</refname> - <refpurpose>Perform a hardware frequency seek</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_hw_freq_seek -*<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_S_HW_FREQ_SEEK</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>Start a hardware frequency seek from the current frequency. -To do this applications initialize the <structfield>tuner</structfield>, -<structfield>type</structfield>, <structfield>seek_upward</structfield>, -<structfield>wrap_around</structfield>, <structfield>spacing</structfield>, -<structfield>rangelow</structfield> and <structfield>rangehigh</structfield> -fields, and zero out the <structfield>reserved</structfield> array of a -&v4l2-hw-freq-seek; and call the <constant>VIDIOC_S_HW_FREQ_SEEK</constant> -ioctl with a pointer to this structure.</para> - - <para>The <structfield>rangelow</structfield> and -<structfield>rangehigh</structfield> fields can be set to a non-zero value to -tell the driver to search a specific band. If the &v4l2-tuner; -<structfield>capability</structfield> field has the -<constant>V4L2_TUNER_CAP_HWSEEK_PROG_LIM</constant> flag set, these values -must fall within one of the bands returned by &VIDIOC-ENUM-FREQ-BANDS;. If -the <constant>V4L2_TUNER_CAP_HWSEEK_PROG_LIM</constant> flag is not set, -then these values must exactly match those of one of the bands returned by -&VIDIOC-ENUM-FREQ-BANDS;. If the current frequency of the tuner does not fall -within the selected band it will be clamped to fit in the band before the -seek is started.</para> - - <para>If an error is returned, then the original frequency will - be restored.</para> - - <para>This ioctl is supported if the <constant>V4L2_CAP_HW_FREQ_SEEK</constant> capability is set.</para> - - <para>If this ioctl is called from a non-blocking filehandle, then &EAGAIN; is - returned and no seek takes place.</para> - - <table pgwide="1" frame="none" id="v4l2-hw-freq-seek"> - <title>struct <structname>v4l2_hw_freq_seek</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>tuner</structfield></entry> - <entry>The tuner index number. This is the -same value as in the &v4l2-input; <structfield>tuner</structfield> -field and the &v4l2-tuner; <structfield>index</structfield> field.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry>The tuner type. This is the same value as in the -&v4l2-tuner; <structfield>type</structfield> field. See <xref - linkend="v4l2-tuner-type" /></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>seek_upward</structfield></entry> - <entry>If non-zero, seek upward from the current frequency, else seek downward.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>wrap_around</structfield></entry> - <entry>If non-zero, wrap around when at the end of the frequency range, else stop seeking. - The &v4l2-tuner; <structfield>capability</structfield> field will tell you what the - hardware supports. - </entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>spacing</structfield></entry> - <entry>If non-zero, defines the hardware seek resolution in Hz. The driver selects the nearest value that is supported by the device. If spacing is zero a reasonable default value is used.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>rangelow</structfield></entry> - <entry>If non-zero, the lowest tunable frequency of the band to -search in units of 62.5 kHz, or if the &v4l2-tuner; -<structfield>capability</structfield> field has the -<constant>V4L2_TUNER_CAP_LOW</constant> flag set, in units of 62.5 Hz or if the &v4l2-tuner; -<structfield>capability</structfield> field has the -<constant>V4L2_TUNER_CAP_1HZ</constant> flag set, in units of 1 Hz. -If <structfield>rangelow</structfield> is zero a reasonable default value -is used.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>rangehigh</structfield></entry> - <entry>If non-zero, the highest tunable frequency of the band to -search in units of 62.5 kHz, or if the &v4l2-tuner; -<structfield>capability</structfield> field has the -<constant>V4L2_TUNER_CAP_LOW</constant> flag set, in units of 62.5 Hz or if the &v4l2-tuner; -<structfield>capability</structfield> field has the -<constant>V4L2_TUNER_CAP_1HZ</constant> flag set, in units of 1 Hz. -If <structfield>rangehigh</structfield> is zero a reasonable default value -is used.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[5]</entry> - <entry>Reserved for future extensions. Applications - must set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The <structfield>tuner</structfield> index is out of -bounds, the <structfield>wrap_around</structfield> value is not supported or -one of the values in the <structfield>type</structfield>, -<structfield>rangelow</structfield> or <structfield>rangehigh</structfield> -fields is wrong.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EAGAIN</errorcode></term> - <listitem> - <para>Attempted to call <constant>VIDIOC_S_HW_FREQ_SEEK</constant> - with the filehandle in non-blocking mode.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>ENODATA</errorcode></term> - <listitem> - <para>The hardware seek found no channels.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EBUSY</errorcode></term> - <listitem> - <para>Another hardware seek is already in progress.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-streamon.xml b/Documentation/DocBook/media/v4l/vidioc-streamon.xml deleted file mode 100644 index df2c63d07bac..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-streamon.xml +++ /dev/null @@ -1,128 +0,0 @@ -<refentry id="vidioc-streamon"> - <refmeta> - <refentrytitle>ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_STREAMON</refname> - <refname>VIDIOC_STREAMOFF</refname> - <refpurpose>Start or stop streaming I/O</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>const int *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_STREAMON, VIDIOC_STREAMOFF</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>The <constant>VIDIOC_STREAMON</constant> and -<constant>VIDIOC_STREAMOFF</constant> ioctl start and stop the capture -or output process during streaming (<link linkend="mmap">memory -mapping</link>, <link linkend="userp">user pointer</link> or -<link linkend="dmabuf">DMABUF</link>) I/O.</para> - - <para>Capture hardware is disabled and no input -buffers are filled (if there are any empty buffers in the incoming -queue) until <constant>VIDIOC_STREAMON</constant> has been called. -Output hardware is disabled and no video signal is -produced until <constant>VIDIOC_STREAMON</constant> has been called. -The ioctl will succeed when at least one output buffer is in the -incoming queue.</para> - - <para>Memory-to-memory devices will not start until -<constant>VIDIOC_STREAMON</constant> has been called for both the capture -and output stream types.</para> - - <para>If <constant>VIDIOC_STREAMON</constant> fails then any already -queued buffers will remain queued.</para> - - <para>The <constant>VIDIOC_STREAMOFF</constant> ioctl, apart of -aborting or finishing any DMA in progress, unlocks any user pointer -buffers locked in physical memory, and it removes all buffers from the -incoming and outgoing queues. That means all images captured but not -dequeued yet will be lost, likewise all images enqueued for output but -not transmitted yet. I/O returns to the same state as after calling -&VIDIOC-REQBUFS; and can be restarted accordingly.</para> - - <para>If buffers have been queued with &VIDIOC-QBUF; and -<constant>VIDIOC_STREAMOFF</constant> is called without ever having -called <constant>VIDIOC_STREAMON</constant>, then those queued buffers -will also be removed from the incoming queue and all are returned to the -same state as after calling &VIDIOC-REQBUFS; and can be restarted -accordingly.</para> - - <para>Both ioctls take a pointer to an integer, the desired buffer or -stream type. This is the same as &v4l2-requestbuffers; -<structfield>type</structfield>.</para> - - <para>If <constant>VIDIOC_STREAMON</constant> is called when streaming -is already in progress, or if <constant>VIDIOC_STREAMOFF</constant> is called -when streaming is already stopped, then 0 is returned. Nothing happens in the -case of <constant>VIDIOC_STREAMON</constant>, but <constant>VIDIOC_STREAMOFF</constant> -will return queued buffers to their starting state as mentioned above.</para> - - <para>Note that applications can be preempted for unknown periods right -before or after the <constant>VIDIOC_STREAMON</constant> or -<constant>VIDIOC_STREAMOFF</constant> calls, there is no notion of -starting or stopping "now". Buffer timestamps can be used to -synchronize with other events.</para> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The buffer <structfield>type</structfield> is not supported, - or no buffers have been allocated (memory mapping) or enqueued - (output) yet.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EPIPE</errorcode></term> - <listitem> - <para>The driver implements <link - linkend="pad-level-formats">pad-level format configuration</link> and - the pipeline configuration is invalid. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-enum-frame-interval.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-enum-frame-interval.xml deleted file mode 100644 index cff59f5cbf04..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-subdev-enum-frame-interval.xml +++ /dev/null @@ -1,157 +0,0 @@ -<refentry id="vidioc-subdev-enum-frame-interval"> - <refmeta> - <refentrytitle>ioctl VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</refname> - <refpurpose>Enumerate frame intervals</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_subdev_frame_interval_enum * - <parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <note> - <title>Experimental</title> - <para>This is an <link linkend="experimental">experimental</link> - interface and may change in the future.</para> - </note> - - <para>This ioctl lets applications enumerate available frame intervals on a - given sub-device pad. Frame intervals only makes sense for sub-devices that - can control the frame period on their own. This includes, for instance, - image sensors and TV tuners.</para> - - <para>For the common use case of image sensors, the frame intervals - available on the sub-device output pad depend on the frame format and size - on the same pad. Applications must thus specify the desired format and size - when enumerating frame intervals.</para> - - <para>To enumerate frame intervals applications initialize the - <structfield>index</structfield>, <structfield>pad</structfield>, - <structfield>which</structfield>, <structfield>code</structfield>, - <structfield>width</structfield> and <structfield>height</structfield> - fields of &v4l2-subdev-frame-interval-enum; and call the - <constant>VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</constant> ioctl with a pointer - to this structure. Drivers fill the rest of the structure or return - an &EINVAL; if one of the input fields is invalid. All frame intervals are - enumerable by beginning at index zero and incrementing by one until - <errorcode>EINVAL</errorcode> is returned.</para> - - <para>Available frame intervals may depend on the current 'try' formats - at other pads of the sub-device, as well as on the current active links. See - &VIDIOC-SUBDEV-G-FMT; for more information about the try formats.</para> - - <para>Sub-devices that support the frame interval enumeration ioctl should - implemented it on a single pad only. Its behaviour when supported on - multiple pads of the same sub-device is not defined.</para> - - <table pgwide="1" frame="none" id="v4l2-subdev-frame-interval-enum"> - <title>struct <structname>v4l2_subdev_frame_interval_enum</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>index</structfield></entry> - <entry>Number of the format in the enumeration, set by the - application.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>pad</structfield></entry> - <entry>Pad number as reported by the media controller API.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>code</structfield></entry> - <entry>The media bus format code, as defined in - <xref linkend="v4l2-mbus-format" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>width</structfield></entry> - <entry>Frame width, in pixels.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>height</structfield></entry> - <entry>Frame height, in pixels.</entry> - </row> - <row> - <entry>&v4l2-fract;</entry> - <entry><structfield>interval</structfield></entry> - <entry>Period, in seconds, between consecutive video frames.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>which</structfield></entry> - <entry>Frame intervals to be enumerated, from &v4l2-subdev-format-whence;.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[8]</entry> - <entry>Reserved for future extensions. Applications and drivers must - set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The &v4l2-subdev-frame-interval-enum; - <structfield>pad</structfield> references a non-existing pad, one of - the <structfield>code</structfield>, <structfield>width</structfield> - or <structfield>height</structfield> fields are invalid for the given - pad or the <structfield>index</structfield> field is out of bounds. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-enum-frame-size.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-enum-frame-size.xml deleted file mode 100644 index abd545ede67a..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-subdev-enum-frame-size.xml +++ /dev/null @@ -1,159 +0,0 @@ -<refentry id="vidioc-subdev-enum-frame-size"> - <refmeta> - <refentrytitle>ioctl VIDIOC_SUBDEV_ENUM_FRAME_SIZE</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_SUBDEV_ENUM_FRAME_SIZE</refname> - <refpurpose>Enumerate media bus frame sizes</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_subdev_frame_size_enum * - <parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_SUBDEV_ENUM_FRAME_SIZE</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <note> - <title>Experimental</title> - <para>This is an <link linkend="experimental">experimental</link> - interface and may change in the future.</para> - </note> - - <para>This ioctl allows applications to enumerate all frame sizes - supported by a sub-device on the given pad for the given media bus format. - Supported formats can be retrieved with the &VIDIOC-SUBDEV-ENUM-MBUS-CODE; - ioctl.</para> - - <para>To enumerate frame sizes applications initialize the - <structfield>pad</structfield>, <structfield>which</structfield> , - <structfield>code</structfield> and <structfield>index</structfield> - fields of the &v4l2-subdev-mbus-code-enum; and call the - <constant>VIDIOC_SUBDEV_ENUM_FRAME_SIZE</constant> ioctl with a pointer to - the structure. Drivers fill the minimum and maximum frame sizes or return - an &EINVAL; if one of the input parameters is invalid.</para> - - <para>Sub-devices that only support discrete frame sizes (such as most - sensors) will return one or more frame sizes with identical minimum and - maximum values.</para> - - <para>Not all possible sizes in given [minimum, maximum] ranges need to be - supported. For instance, a scaler that uses a fixed-point scaling ratio - might not be able to produce every frame size between the minimum and - maximum values. Applications must use the &VIDIOC-SUBDEV-S-FMT; ioctl to - try the sub-device for an exact supported frame size.</para> - - <para>Available frame sizes may depend on the current 'try' formats at other - pads of the sub-device, as well as on the current active links and the - current values of V4L2 controls. See &VIDIOC-SUBDEV-G-FMT; for more - information about try formats.</para> - - <table pgwide="1" frame="none" id="v4l2-subdev-frame-size-enum"> - <title>struct <structname>v4l2_subdev_frame_size_enum</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>index</structfield></entry> - <entry>Number of the format in the enumeration, set by the - application.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>pad</structfield></entry> - <entry>Pad number as reported by the media controller API.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>code</structfield></entry> - <entry>The media bus format code, as defined in - <xref linkend="v4l2-mbus-format" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>min_width</structfield></entry> - <entry>Minimum frame width, in pixels.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>max_width</structfield></entry> - <entry>Maximum frame width, in pixels.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>min_height</structfield></entry> - <entry>Minimum frame height, in pixels.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>max_height</structfield></entry> - <entry>Maximum frame height, in pixels.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>which</structfield></entry> - <entry>Frame sizes to be enumerated, from &v4l2-subdev-format-whence;.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[8]</entry> - <entry>Reserved for future extensions. Applications and drivers must - set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The &v4l2-subdev-frame-size-enum; <structfield>pad</structfield> - references a non-existing pad, the <structfield>code</structfield> is - invalid for the given pad or the <structfield>index</structfield> - field is out of bounds.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-enum-mbus-code.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-enum-mbus-code.xml deleted file mode 100644 index 0bcb278fd062..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-subdev-enum-mbus-code.xml +++ /dev/null @@ -1,124 +0,0 @@ -<refentry id="vidioc-subdev-enum-mbus-code"> - <refmeta> - <refentrytitle>ioctl VIDIOC_SUBDEV_ENUM_MBUS_CODE</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_SUBDEV_ENUM_MBUS_CODE</refname> - <refpurpose>Enumerate media bus formats</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_subdev_mbus_code_enum * - <parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_SUBDEV_ENUM_MBUS_CODE</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <note> - <title>Experimental</title> - <para>This is an <link linkend="experimental">experimental</link> - interface and may change in the future.</para> - </note> - - <para>To enumerate media bus formats available at a given sub-device pad - applications initialize the <structfield>pad</structfield>, <structfield>which</structfield> - and <structfield>index</structfield> fields of &v4l2-subdev-mbus-code-enum; and - call the <constant>VIDIOC_SUBDEV_ENUM_MBUS_CODE</constant> ioctl with a - pointer to this structure. Drivers fill the rest of the structure or return - an &EINVAL; if either the <structfield>pad</structfield> or - <structfield>index</structfield> are invalid. All media bus formats are - enumerable by beginning at index zero and incrementing by one until - <errorcode>EINVAL</errorcode> is returned.</para> - - <para>Available media bus formats may depend on the current 'try' formats - at other pads of the sub-device, as well as on the current active links. See - &VIDIOC-SUBDEV-G-FMT; for more information about the try formats.</para> - - <table pgwide="1" frame="none" id="v4l2-subdev-mbus-code-enum"> - <title>struct <structname>v4l2_subdev_mbus_code_enum</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>pad</structfield></entry> - <entry>Pad number as reported by the media controller API.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>index</structfield></entry> - <entry>Number of the format in the enumeration, set by the - application.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>code</structfield></entry> - <entry>The media bus format code, as defined in - <xref linkend="v4l2-mbus-format" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>which</structfield></entry> - <entry>Media bus format codes to be enumerated, from &v4l2-subdev-format-whence;.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[8]</entry> - <entry>Reserved for future extensions. Applications and drivers must - set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The &v4l2-subdev-mbus-code-enum; <structfield>pad</structfield> - references a non-existing pad, or the <structfield>index</structfield> - field is out of bounds.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-crop.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-crop.xml deleted file mode 100644 index 4cddd788c589..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-subdev-g-crop.xml +++ /dev/null @@ -1,158 +0,0 @@ -<refentry id="vidioc-subdev-g-crop"> - <refmeta> - <refentrytitle>ioctl VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_SUBDEV_G_CROP</refname> - <refname>VIDIOC_SUBDEV_S_CROP</refname> - <refpurpose>Get or set the crop rectangle on a subdev pad</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_subdev_crop *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>const struct v4l2_subdev_crop *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <note> - <title>Obsolete</title> - - <para>This is an <link linkend="obsolete">obsolete</link> - interface and may be removed in the future. It is superseded by - <link linkend="vidioc-subdev-g-selection">the selection - API</link>.</para> - </note> - - <para>To retrieve the current crop rectangle applications set the - <structfield>pad</structfield> field of a &v4l2-subdev-crop; to the - desired pad number as reported by the media API and the - <structfield>which</structfield> field to - <constant>V4L2_SUBDEV_FORMAT_ACTIVE</constant>. They then call the - <constant>VIDIOC_SUBDEV_G_CROP</constant> ioctl with a pointer to this - structure. The driver fills the members of the <structfield>rect</structfield> - field or returns &EINVAL; if the input arguments are invalid, or if cropping - is not supported on the given pad.</para> - - <para>To change the current crop rectangle applications set both the - <structfield>pad</structfield> and <structfield>which</structfield> fields - and all members of the <structfield>rect</structfield> field. They then call - the <constant>VIDIOC_SUBDEV_S_CROP</constant> ioctl with a pointer to this - structure. The driver verifies the requested crop rectangle, adjusts it - based on the hardware capabilities and configures the device. Upon return - the &v4l2-subdev-crop; contains the current format as would be returned - by a <constant>VIDIOC_SUBDEV_G_CROP</constant> call.</para> - - <para>Applications can query the device capabilities by setting the - <structfield>which</structfield> to - <constant>V4L2_SUBDEV_FORMAT_TRY</constant>. When set, 'try' crop - rectangles are not applied to the device by the driver, but are mangled - exactly as active crop rectangles and stored in the sub-device file handle. - Two applications querying the same sub-device would thus not interact with - each other.</para> - - <para>Drivers must not return an error solely because the requested crop - rectangle doesn't match the device capabilities. They must instead modify - the rectangle to match what the hardware can provide. The modified format - should be as close as possible to the original request.</para> - - <table pgwide="1" frame="none" id="v4l2-subdev-crop"> - <title>struct <structname>v4l2_subdev_crop</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>pad</structfield></entry> - <entry>Pad number as reported by the media framework.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>which</structfield></entry> - <entry>Crop rectangle to get or set, from - &v4l2-subdev-format-whence;.</entry> - </row> - <row> - <entry>&v4l2-rect;</entry> - <entry><structfield>rect</structfield></entry> - <entry>Crop rectangle boundaries, in pixels.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[8]</entry> - <entry>Reserved for future extensions. Applications and drivers must - set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EBUSY</errorcode></term> - <listitem> - <para>The crop rectangle can't be changed because the pad is currently - busy. This can be caused, for instance, by an active video stream on - the pad. The ioctl must not be retried without performing another - action to fix the problem first. Only returned by - <constant>VIDIOC_SUBDEV_S_CROP</constant></para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The &v4l2-subdev-crop; <structfield>pad</structfield> - references a non-existing pad, the <structfield>which</structfield> - field references a non-existing format, or cropping is not supported - on the given subdev pad.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-fmt.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-fmt.xml deleted file mode 100644 index a67cde6f8c54..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-subdev-g-fmt.xml +++ /dev/null @@ -1,183 +0,0 @@ -<refentry id="vidioc-subdev-g-fmt"> - <refmeta> - <refentrytitle>ioctl VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_SUBDEV_G_FMT</refname> - <refname>VIDIOC_SUBDEV_S_FMT</refname> - <refpurpose>Get or set the data format on a subdev pad</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_subdev_format *<parameter>argp</parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <note> - <title>Experimental</title> - <para>This is an <link linkend="experimental">experimental</link> - interface and may change in the future.</para> - </note> - - <para>These ioctls are used to negotiate the frame format at specific - subdev pads in the image pipeline.</para> - - <para>To retrieve the current format applications set the - <structfield>pad</structfield> field of a &v4l2-subdev-format; to the - desired pad number as reported by the media API and the - <structfield>which</structfield> field to - <constant>V4L2_SUBDEV_FORMAT_ACTIVE</constant>. When they call the - <constant>VIDIOC_SUBDEV_G_FMT</constant> ioctl with a pointer to this - structure the driver fills the members of the <structfield>format</structfield> - field.</para> - - <para>To change the current format applications set both the - <structfield>pad</structfield> and <structfield>which</structfield> fields - and all members of the <structfield>format</structfield> field. When they - call the <constant>VIDIOC_SUBDEV_S_FMT</constant> ioctl with a pointer to this - structure the driver verifies the requested format, adjusts it based on the - hardware capabilities and configures the device. Upon return the - &v4l2-subdev-format; contains the current format as would be returned by a - <constant>VIDIOC_SUBDEV_G_FMT</constant> call.</para> - - <para>Applications can query the device capabilities by setting the - <structfield>which</structfield> to - <constant>V4L2_SUBDEV_FORMAT_TRY</constant>. When set, 'try' formats are not - applied to the device by the driver, but are changed exactly as active - formats and stored in the sub-device file handle. Two applications querying - the same sub-device would thus not interact with each other.</para> - - <para>For instance, to try a format at the output pad of a sub-device, - applications would first set the try format at the sub-device input with the - <constant>VIDIOC_SUBDEV_S_FMT</constant> ioctl. They would then either - retrieve the default format at the output pad with the - <constant>VIDIOC_SUBDEV_G_FMT</constant> ioctl, or set the desired output - pad format with the <constant>VIDIOC_SUBDEV_S_FMT</constant> ioctl and check - the returned value.</para> - - <para>Try formats do not depend on active formats, but can depend on the - current links configuration or sub-device controls value. For instance, a - low-pass noise filter might crop pixels at the frame boundaries, modifying - its output frame size.</para> - - <para>Drivers must not return an error solely because the requested format - doesn't match the device capabilities. They must instead modify the format - to match what the hardware can provide. The modified format should be as - close as possible to the original request.</para> - - <table pgwide="1" frame="none" id="v4l2-subdev-format"> - <title>struct <structname>v4l2_subdev_format</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>pad</structfield></entry> - <entry>Pad number as reported by the media controller API.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>which</structfield></entry> - <entry>Format to modified, from &v4l2-subdev-format-whence;.</entry> - </row> - <row> - <entry>&v4l2-mbus-framefmt;</entry> - <entry><structfield>format</structfield></entry> - <entry>Definition of an image format, see <xref - linkend="v4l2-mbus-framefmt" /> for details.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[8]</entry> - <entry>Reserved for future extensions. Applications and drivers must - set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="v4l2-subdev-format-whence"> - <title>enum <structname>v4l2_subdev_format_whence</structname></title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry>V4L2_SUBDEV_FORMAT_TRY</entry> - <entry>0</entry> - <entry>Try formats, used for querying device capabilities.</entry> - </row> - <row> - <entry>V4L2_SUBDEV_FORMAT_ACTIVE</entry> - <entry>1</entry> - <entry>Active formats, applied to the hardware.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EBUSY</errorcode></term> - <listitem> - <para>The format can't be changed because the pad is currently busy. - This can be caused, for instance, by an active video stream on the - pad. The ioctl must not be retried without performing another action - to fix the problem first. Only returned by - <constant>VIDIOC_SUBDEV_S_FMT</constant></para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The &v4l2-subdev-format; <structfield>pad</structfield> - references a non-existing pad, or the <structfield>which</structfield> - field references a non-existing format.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - <refsect1> - &return-value; - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-frame-interval.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-frame-interval.xml deleted file mode 100644 index 0bc3ea22d31f..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-subdev-g-frame-interval.xml +++ /dev/null @@ -1,141 +0,0 @@ -<refentry id="vidioc-subdev-g-frame-interval"> - <refmeta> - <refentrytitle>ioctl VIDIOC_SUBDEV_G_FRAME_INTERVAL, VIDIOC_SUBDEV_S_FRAME_INTERVAL</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_SUBDEV_G_FRAME_INTERVAL</refname> - <refname>VIDIOC_SUBDEV_S_FRAME_INTERVAL</refname> - <refpurpose>Get or set the frame interval on a subdev pad</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_subdev_frame_interval *<parameter>argp</parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_SUBDEV_G_FRAME_INTERVAL, VIDIOC_SUBDEV_S_FRAME_INTERVAL</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <note> - <title>Experimental</title> - <para>This is an <link linkend="experimental">experimental</link> - interface and may change in the future.</para> - </note> - - <para>These ioctls are used to get and set the frame interval at specific - subdev pads in the image pipeline. The frame interval only makes sense for - sub-devices that can control the frame period on their own. This includes, - for instance, image sensors and TV tuners. Sub-devices that don't support - frame intervals must not implement these ioctls.</para> - - <para>To retrieve the current frame interval applications set the - <structfield>pad</structfield> field of a &v4l2-subdev-frame-interval; to - the desired pad number as reported by the media controller API. When they - call the <constant>VIDIOC_SUBDEV_G_FRAME_INTERVAL</constant> ioctl with a - pointer to this structure the driver fills the members of the - <structfield>interval</structfield> field.</para> - - <para>To change the current frame interval applications set both the - <structfield>pad</structfield> field and all members of the - <structfield>interval</structfield> field. When they call the - <constant>VIDIOC_SUBDEV_S_FRAME_INTERVAL</constant> ioctl with a pointer to - this structure the driver verifies the requested interval, adjusts it based - on the hardware capabilities and configures the device. Upon return the - &v4l2-subdev-frame-interval; contains the current frame interval as would be - returned by a <constant>VIDIOC_SUBDEV_G_FRAME_INTERVAL</constant> call. - </para> - - <para>Drivers must not return an error solely because the requested interval - doesn't match the device capabilities. They must instead modify the interval - to match what the hardware can provide. The modified interval should be as - close as possible to the original request.</para> - - <para>Sub-devices that support the frame interval ioctls should implement - them on a single pad only. Their behaviour when supported on multiple pads - of the same sub-device is not defined.</para> - - <table pgwide="1" frame="none" id="v4l2-subdev-frame-interval"> - <title>struct <structname>v4l2_subdev_frame_interval</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>pad</structfield></entry> - <entry>Pad number as reported by the media controller API.</entry> - </row> - <row> - <entry>&v4l2-fract;</entry> - <entry><structfield>interval</structfield></entry> - <entry>Period, in seconds, between consecutive video frames.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[9]</entry> - <entry>Reserved for future extensions. Applications and drivers must - set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EBUSY</errorcode></term> - <listitem> - <para>The frame interval can't be changed because the pad is currently - busy. This can be caused, for instance, by an active video stream on - the pad. The ioctl must not be retried without performing another - action to fix the problem first. Only returned by - <constant>VIDIOC_SUBDEV_S_FRAME_INTERVAL</constant></para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The &v4l2-subdev-frame-interval; <structfield>pad</structfield> - references a non-existing pad, or the pad doesn't support frame - intervals.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml deleted file mode 100644 index c62a7360719b..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml +++ /dev/null @@ -1,165 +0,0 @@ -<refentry id="vidioc-subdev-g-selection"> - <refmeta> - <refentrytitle>ioctl VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_SUBDEV_G_SELECTION</refname> - <refname>VIDIOC_SUBDEV_S_SELECTION</refname> - <refpurpose>Get or set selection rectangles on a subdev pad</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_subdev_selection *<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <note> - <title>Experimental</title> - <para>This is an <link linkend="experimental">experimental</link> - interface and may change in the future.</para> - </note> - - <para>The selections are used to configure various image - processing functionality performed by the subdevs which affect the - image size. This currently includes cropping, scaling and - composition.</para> - - <para>The selection API replaces <link - linkend="vidioc-subdev-g-crop">the old subdev crop API</link>. All - the function of the crop API, and more, are supported by the - selections API.</para> - - <para>See <xref linkend="subdev"></xref> for - more information on how each selection target affects the image - processing pipeline inside the subdevice.</para> - - <refsect2> - <title>Types of selection targets</title> - - <para>There are two types of selection targets: actual and bounds. The - actual targets are the targets which configure the hardware. The BOUNDS - target will return a rectangle that contain all possible actual - rectangles.</para> - </refsect2> - - <refsect2> - <title>Discovering supported features</title> - - <para>To discover which targets are supported, the user can - perform <constant>VIDIOC_SUBDEV_G_SELECTION</constant> on them. - Any unsupported target will return - <constant>EINVAL</constant>.</para> - - <para>Selection targets and flags are documented in <xref - linkend="v4l2-selections-common"/>.</para> - - <table pgwide="1" frame="none" id="v4l2-subdev-selection"> - <title>struct <structname>v4l2_subdev_selection</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>which</structfield></entry> - <entry>Active or try selection, from - &v4l2-subdev-format-whence;.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>pad</structfield></entry> - <entry>Pad number as reported by the media framework.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>target</structfield></entry> - <entry>Target selection rectangle. See - <xref linkend="v4l2-selections-common" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry>Flags. See - <xref linkend="v4l2-selection-flags" />.</entry> - </row> - <row> - <entry>&v4l2-rect;</entry> - <entry><structfield>r</structfield></entry> - <entry>Selection rectangle, in pixels.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[8]</entry> - <entry>Reserved for future extensions. Applications and drivers must - set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect2> - - </refsect1> - - <refsect1> - &return-value; - - <variablelist> - <varlistentry> - <term><errorcode>EBUSY</errorcode></term> - <listitem> - <para>The selection rectangle can't be changed because the - pad is currently busy. This can be caused, for instance, by - an active video stream on the pad. The ioctl must not be - retried without performing another action to fix the problem - first. Only returned by - <constant>VIDIOC_SUBDEV_S_SELECTION</constant></para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The &v4l2-subdev-selection; - <structfield>pad</structfield> references a non-existing - pad, the <structfield>which</structfield> field references a - non-existing format, or the selection target is not - supported on the given subdev pad.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml deleted file mode 100644 index 5fd0ee78f880..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml +++ /dev/null @@ -1,130 +0,0 @@ -<refentry id="vidioc-subscribe-event"> - <refmeta> - <refentrytitle>ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>VIDIOC_SUBSCRIBE_EVENT</refname> - <refname>VIDIOC_UNSUBSCRIBE_EVENT</refname> - <refpurpose>Subscribe or unsubscribe event</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>ioctl</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>request</parameter></paramdef> - <paramdef>struct v4l2_event_subscription -*<parameter>argp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>request</parameter></term> - <listitem> - <para>VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>argp</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para>Subscribe or unsubscribe V4L2 event. Subscribed events are - dequeued by using the &VIDIOC-DQEVENT; ioctl.</para> - - <table frame="none" pgwide="1" id="v4l2-event-subscription"> - <title>struct <structname>v4l2_event_subscription</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry>Type of the event, see <xref linkend="event-type" />. Note that -<constant>V4L2_EVENT_ALL</constant> can be used with VIDIOC_UNSUBSCRIBE_EVENT -for unsubscribing all events at once.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>id</structfield></entry> - <entry>ID of the event source. If there is no ID associated with - the event source, then set this to 0. Whether or not an event - needs an ID depends on the event type.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry>Event flags, see <xref linkend="event-flags" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield>[5]</entry> - <entry>Reserved for future extensions. Drivers and applications - must set the array to zero.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="event-flags"> - <title>Event Flags</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_EVENT_SUB_FL_SEND_INITIAL</constant></entry> - <entry>0x0001</entry> - <entry>When this event is subscribed an initial event will be sent - containing the current status. This only makes sense for events - that are triggered by a status change such as <constant>V4L2_EVENT_CTRL</constant>. - Other events will ignore this flag.</entry> - </row> - <row> - <entry><constant>V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK</constant></entry> - <entry>0x0002</entry> - <entry><para>If set, then events directly caused by an ioctl will also be sent to - the filehandle that called that ioctl. For example, changing a control using - &VIDIOC-S-CTRL; will cause a V4L2_EVENT_CTRL to be sent back to that same - filehandle. Normally such events are suppressed to prevent feedback loops - where an application changes a control to a one value and then another, and - then receives an event telling it that that control has changed to the first - value.</para> - - <para>Since it can't tell whether that event was caused by another application - or by the &VIDIOC-S-CTRL; call it is hard to decide whether to set the - control to the value in the event, or ignore it.</para> - - <para>Think carefully when you set this flag so you won't get into situations - like that.</para> - </entry> - </row> - </tbody> - </tgroup> - </table> - - </refsect1> - <refsect1> - &return-value; - </refsect1> -</refentry> diff --git a/Documentation/DocBook/media/vbi_525.gif.b64 b/Documentation/DocBook/media/vbi_525.gif.b64 deleted file mode 100644 index d5dcf06f2aef..000000000000 --- a/Documentation/DocBook/media/vbi_525.gif.b64 +++ /dev/null @@ -1,84 +0,0 @@ -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 -E9gqF8bNWgAAOw== diff --git a/Documentation/DocBook/media/vbi_625.gif.b64 b/Documentation/DocBook/media/vbi_625.gif.b64 deleted file mode 100644 index 831f49a02821..000000000000 --- a/Documentation/DocBook/media/vbi_625.gif.b64 +++ /dev/null @@ -1,90 +0,0 @@ -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 -0Adtyay8rcRcXsY8yW56buKsptPTzwkX0C6Xzx03zy1MzcccngxdcfDcbNE8yyatziSdbSFdzgX9 -yxqdaRxdZIpm0b/+iaY+PcgeJs2UEW3KjKeQGMmPDM2cHNHJbMv1DNKAbMpYLNKJ2kH1I9W5TNWk -nNWwTHJ9M9SKnNDL7Mgq7YpevdTa/NJuUNRPjXNvbWQKt3NwPdc8nSNhjRdtTc9wqtQOjdZ+PclN -jc4TrdBy/dV0bdcjp62SZNYEdtdr3RF6jdKH2s6VLYqN/cuCDdOETdYX2G6f7dmGfdg3F9c7gtex -FdOXvNCWrV6sDZF3KNGqbNT6FNqKDWyiXdqkXdeL/diazdYnDdXsfNmuXWVq7duRDdznPNqJrdvM -vdu8XdG4DWan3bypTdFlTdzmNm4ufdzTbN2FbdvFLN3OvdzkHd7RF93bJf3b393ZKZ3dSY3Z2AzZ -3s3ZAhzd551mNv3Ozw3U5lHGpfPfl3NGA351Rmfgj6XHd7xYUKdZCR51rGE2vVJ1E04eAU45Fl7F -1htMGv5LHN7hXZ3EIS7iI07iJW7iJ47iKa7iK87iLe7iLw7jMS7jM07jNW7jN47jOa7jO87jPe7j -Pw7kQV68E+EQhqrAQs6aZmirzYzkQC4aAmmIygHlTS7kP0G3gRJ8VB7kAGCRbQB8uqflTu6Ci4jl -ehjmPs7laf58XB7Fau6DR56aBQAAOw== diff --git a/Documentation/DocBook/media/vbi_hsync.gif.b64 b/Documentation/DocBook/media/vbi_hsync.gif.b64 deleted file mode 100644 index cdafabed5c11..000000000000 --- a/Documentation/DocBook/media/vbi_hsync.gif.b64 +++ /dev/null @@ -1,43 +0,0 @@ -R0lGODlhBwHJAOcAAAAAAAEBAQICAgMDAwQEBAUFBQYGBgcHBwgICAkJCQoKCgsLCwwMDA0NDQ4O -Dg8PDxAQEBERERISEhMTExQUFBUVFRYWFhcXFxgYGBkZGRoaGhsbGxwcHB0dHR4eHh8fHyAgICEh -ISIiIiMjIyQkJCUlJSYmJicnJygoKCkpKSoqKisrKywsLC0tLS4uLi8vLzAwMDExMTIyMjMzMzQ0 -NDU1NTY2Njc3Nzg4ODk5OTo6Ojs7Ozw8PD09PT4+Pj8/P0BAQEFBQUJCQkNDQ0REREVFRUZGRkdH -R0hISElJSUpKSktLS0xMTE1NTU5OTk9PT1BQUFFRUVJSUlNTU1RUVFVVVVZWVldXV1hYWFlZWVpa -WltbW1xcXF1dXV5eXl9fX2BgYGFhYWJiYmNjY2RkZGVlZWZmZmdnZ2hoaGlpaWpqamtra2xsbG1t -bW5ubm9vb3BwcHFxcXJycnNzc3R0dHV1dXZ2dnd3d3h4eHl5eXp6ent7e3x8fH19fX5+fn9/f4CA -gIGBgYKCgoODg4SEhIWFhYaGhoeHh4iIiImJiYqKiouLi4yMjI2NjY6Ojo+Pj5CQkJGRkZKSkpOT -k5SUlJWVlZaWlpeXl5iYmJmZmZqampubm5ycnJ2dnZ6enp+fn6CgoKGhoaKioqOjo6SkpKWlpaam -pqenp6ioqKmpqaqqqqurq6ysrK2tra6urq+vr7CwsLGxsbKysrOzs7S0tLW1tba2tre3t7i4uLm5 -ubq6uru7u7y8vL29vb6+vr+/v8DAwMHBwcLCwsPDw8TExMXFxcbGxsfHx8jIyMnJycrKysvLy8zM -zM3Nzc7Ozs/Pz9DQ0NHR0dLS0tPT09TU1NXV1dbW1tfX19jY2NnZ2dra2tvb29zc3N3d3d7e3t/f -3+Dg4OHh4eLi4uPj4+Tk5OXl5ebm5ufn5+jo6Onp6erq6uvr6+zs7O3t7e7u7u/v7/Dw8PHx8fLy -8vPz8/T09PX19fb29vf39/j4+Pn5+fr6+vv7+/z8/P39/f7+/v///ywAAAAABwHJAAAI/gD/CRxI -sKDBgwgTKlzIsKHDhxAjSpxIsaLFixgzatzIsaPHjyBDihxJsqTJkyhTqlzJsqXLlzBjypxJs6bN -mzhz6tzJs6fPn0CDCh1KtKjRo0iTKl3KtKnTp1CjSp1KtarVqyQBYN1aVSvXr1C9gh2rVOxCsV4B -mE2b0GxDt2TjtnWo9l9du2rrar2bl+BavQL3ApZLeC5du3j77g2MF/FAtIv1AoZb+Gfey5gza97M -ua/ByJ4XI8b8+PHl0ZkrE6XsuCDr1xD5ip7d2m9pv6IZqxYK+zPC3g/T0mabGLdk4YEH7wYK3PZB -yqyXSw/++3l139OzS4R+Hbtr7eCp/nv/bp18+PMKuZcfj7792fXm47ufz/52fd308zu/X3u/fv3N -+Sfgf/MFaJ98BLpnIH4IJojegv0d6GB7EEI4oXYVdnfhgxoOyOCG4WXIH4jTidggiSV2KOGHKGa3 -oIUtqvaiijEuNyN8NUp344g5EqYef9H1KNePJwYpJFlEehjhkT7iuCKLTMZl4olRgjWlklV+deWT -WWpJ45JgdrnVllCKOeaXMJrZFZpfqmkVmWG6SRWcRsoZFZl12hkWmzxemCdXeAr555lOgjnof4de -tSOVG0KWaFl3GVponH52ZumlmGaq6aaY0pjmhJppmRqQbTaKm6gewgnio2uSOumq/jpO+qmDrE5F -p6AtSZZeSrf2WOtEoZEmm2C/Astnn6CapKtjbClWZki95lhsbLcRtxmlHkVb47TBWcuYcGvxeiyj -fp7kGbOJEZscStrGyK1T7bb4blPxojgvU4Hiulu+vto4Lpck3rvUoljCuq+npZp6cKGz0uovwwmX -u3CRESc7sZINJyhwWbJW7PDFXGZM4MZI1WsvyCF7rDHKZYqMKMuSvmqwS5yOypHJAcP0K8k4z5xr -RTz/C7DPLO2crdDPEr2S0R31rDDNQB/dMbISQ01R0FOT+/TPV0vtqtZVc21s0wjLLONFJG8XNdkQ -y5z2UNy+TW3XbN8Ho9xBxa3z/to3lz0i3nljBPhbfG+UZMoqG5db2+KJ9O7gDDHd99dUstpscsgR -x6CzqC0O0uN70z05xVlHdNpwgvUHGWrFef5RppGHPjawNddue3nB5nYufsKmu/vrhL/3kuRqq1Tr -6pd/G+6HymGLdvC7Dl+46cYD7aywoSleXGOtj5RnnZALP3vx7Bb2J/iyk6++subTZanz2ZJ2te2R -st8+9NaFHx/x1Jff5GFz0Z9/+Dc3c9EnSK4ryfLG1z89GaY6AjwQARvnQLfBr24XpFrizGSk+tlv -aOJbXwULxj3/gTB6DBwhCD2oQLBtkIR66mAEVTe9AqqQhCzMigvNhsIbrnCG/m6ZIAB9+MPqwfCB -IryhDI14QiQ2kIiUyqH3dqhBHtoJfSZs4gu16CYsGpCKYDyinLz4QS5W8YwcjF0WkxbCJxKRjC0M -oxnlmCU46tA19BPiCO04xZjM8IBq/GL63hjIMloNitiS4uv+aMUxRk5/ihQXIhMJSUaiUUzgq6RM -LEmhR5qLk2LsoieVBco5YnKUCiwlG2OIyqyoMoNpPIsm/TjJRMKya698JYZiB7kELq2W6OvlLT8H -TF62MJfM+R3+lnnIAB5zk8zBHOZks7/BqEuXwXwmLS1DzestDnmNud5MsqlDZPKGWMkzT+9CBc33 -5PGd8IynPOfJwkilLp37/gniN8dZyDgOcienCadudnc6anavnT30p/SKokvH9fOO/+RmqxIK0YUi -EosBNVz2tnnRR9KzUxyFYjAzqpHehZSQbdxYEBEqUhcVM0WTbGhNZBor+7xNj8SMaT7TJc1Tgcug -Bf2LNZnlKODp1KYCbR64ujcZ0OBxe5FR3jAfqsSdNiujucMnPnl3uaxiraNI3ep3hro8161uNLbB -G00fNk3abG+aAiXqcKqlGG8Oy6hgLang+HnUjERyiBFV4VpZitKa5rWEgKJjldgpKs5d9KOQjeym -XkrSMdnzpYatpWY3y1l6NXGB3RlsZ9eDzp7ydKmnW1dAlTnaQ94zruEkS2tUnfra1iIUdRvlHueu -iS7N2daic1VncEEz3N/6MbVyNU1TV0tUdL3VuF6aKnQhJdrpWve62M2udrfL3e5697vgDa94x0ve -8lIkIAA7 diff --git a/Documentation/DocBook/media_api.tmpl b/Documentation/DocBook/media_api.tmpl deleted file mode 100644 index 7b77e0f7b87d..000000000000 --- a/Documentation/DocBook/media_api.tmpl +++ /dev/null @@ -1,117 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % media-entities SYSTEM "./media-entities.tmpl"> %media-entities; -<!ENTITY media-indices SYSTEM "./media-indices.tmpl"> - -<!ENTITY eg "e. g."> -<!ENTITY ie "i. e."> -<!ENTITY fd "File descriptor returned by <link linkend='func-open'><function>open()</function></link>."> -<!ENTITY fe_fd "File descriptor returned by <link linkend='frontend_f_open'><function>open()</function></link>."> -<!ENTITY i2c "I<superscript>2</superscript>C"> -<!ENTITY return-value "<title>Return Value</title><para>On success <returnvalue>0</returnvalue> is returned, on error <returnvalue>-1</returnvalue> and the <varname>errno</varname> variable is set appropriately. The generic error codes are described at the <link linkend='gen-errors'>Generic Error Codes</link> chapter.</para>"> -<!ENTITY return-value-dvb "<para>RETURN VALUE</para><para>On success <returnvalue>0</returnvalue> is returned, on error <returnvalue>-1</returnvalue> and the <varname>errno</varname> variable is set appropriately. The generic error codes are described at the <link linkend='gen-errors'>Generic Error Codes</link> chapter.</para>"> -<!ENTITY manvol "<manvolnum>2</manvolnum>"> - -<!-- Table templates: structs, structs w/union, defines. --> -<!ENTITY cs-str "<colspec colname='c1' colwidth='1*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='2*' /><spanspec spanname='hspan' namest='c1' nameend='c3' />"> -<!ENTITY cs-ustr "<colspec colname='c1' colwidth='1*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='1*' /><colspec colname='c4' colwidth='2*' /><spanspec spanname='hspan' namest='c1' nameend='c4' />"> -<!ENTITY cs-def "<colspec colname='c1' colwidth='3*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='4*' /><spanspec spanname='hspan' namest='c1' nameend='c3' />"> - -<!-- Video for Linux mailing list address. --> -<!ENTITY v4l-ml "<ulink url='https://linuxtv.org/lists.php'>https://linuxtv.org/lists.php</ulink>"> - -<!-- LinuxTV v4l-dvb repository. --> -<!ENTITY v4l-dvb "<ulink url='https://linuxtv.org/repo/'>https://linuxtv.org/repo/</ulink>"> -<!ENTITY dash-ent-8 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>"> -<!ENTITY dash-ent-10 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>"> -<!ENTITY dash-ent-12 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>"> -<!ENTITY dash-ent-14 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>"> -<!ENTITY dash-ent-16 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>"> -<!ENTITY dash-ent-20 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>"> -<!ENTITY dash-ent-22 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>"> -<!ENTITY dash-ent-24 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>"> -]> - -<book id="media_api" lang="en"> -<bookinfo> - <title>LINUX MEDIA INFRASTRUCTURE API</title> - - <copyright> - <year>2009-2015</year> - <holder>LinuxTV Developers</holder> - </copyright> - - <legalnotice> - <para>Permission is granted to copy, distribute and/or modify - this document under the terms of the GNU Free Documentation License, - Version 1.1 or any later version published by the Free Software - Foundation. A copy of the license is included in the chapter entitled - "GNU Free Documentation License"</para> - </legalnotice> -</bookinfo> - -<toc></toc> <!-- autogenerated --> - -<preface> - <title>Introduction</title> - - <para>This document covers the Linux Kernel to Userspace API's used by - video and radio streaming devices, including video cameras, - analog and digital TV receiver cards, AM/FM receiver cards, - streaming capture and output devices, codec devices and remote - controllers.</para> - <para>A typical media device hardware is shown at - <xref linkend="typical_media_device" />.</para> - <figure id="typical_media_device"> - <title>Typical Media Device</title> - <mediaobject> - <imageobject> - <imagedata fileref="typical_media_device.svg" format="SVG" /> - </imageobject> - <textobject> - <phrase>Typical Media Device Block Diagram</phrase> - </textobject> - </mediaobject> - </figure> - <para>The media infrastructure API was designed to control such - devices. It is divided into four parts.</para> - <para>The first part covers radio, video capture and output, - cameras, analog TV devices and codecs.</para> - <para>The second part covers the - API used for digital TV and Internet reception via one of the - several digital tv standards. While it is called as DVB API, - in fact it covers several different video standards including - DVB-T/T2, DVB-S/S2, DVB-C, ATSC, ISDB-T, ISDB-S,etc. The complete - list of supported standards can be found at - <xref linkend="fe-delivery-system-t" />.</para> - <para>The third part covers the Remote Controller API.</para> - <para>The fourth part covers the Media Controller API.</para> - <para>It should also be noted that a media device may also have audio - components, like mixers, PCM capture, PCM playback, etc, which - are controlled via ALSA API.</para> - <para>For additional information and for the latest development code, - see: <ulink url="https://linuxtv.org">https://linuxtv.org</ulink>.</para> - <para>For discussing improvements, reporting troubles, sending new drivers, etc, please mail to: <ulink url="http://vger.kernel.org/vger-lists.html#linux-media">Linux Media Mailing List (LMML).</ulink>.</para> -</preface> - -<part id="v4l2spec"> -&sub-v4l2; -</part> -<part id="dvbapi"> -&sub-dvbapi; -</part> -<part id="remotes"> -&sub-remote_controllers; -</part> -<part id="media_common"> -&sub-media-controller; -</part> - -<chapter id="gen_errors"> -&sub-gen-errors; -</chapter> - -&sub-fdl-appendix; - -</book> diff --git a/Documentation/DocBook/mtdnand.tmpl b/Documentation/DocBook/mtdnand.tmpl deleted file mode 100644 index b442921bca54..000000000000 --- a/Documentation/DocBook/mtdnand.tmpl +++ /dev/null @@ -1,1291 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="MTD-NAND-Guide"> - <bookinfo> - <title>MTD NAND Driver Programming Interface</title> - - <authorgroup> - <author> - <firstname>Thomas</firstname> - <surname>Gleixner</surname> - <affiliation> - <address> - <email>tglx@linutronix.de</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2004</year> - <holder>Thomas Gleixner</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License version 2 as published by the Free Software Foundation. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="intro"> - <title>Introduction</title> - <para> - The generic NAND driver supports almost all NAND and AG-AND based - chips and connects them to the Memory Technology Devices (MTD) - subsystem of the Linux Kernel. - </para> - <para> - This documentation is provided for developers who want to implement - board drivers or filesystem drivers suitable for NAND devices. - </para> - </chapter> - - <chapter id="bugs"> - <title>Known Bugs And Assumptions</title> - <para> - None. - </para> - </chapter> - - <chapter id="dochints"> - <title>Documentation hints</title> - <para> - The function and structure docs are autogenerated. Each function and - struct member has a short description which is marked with an [XXX] identifier. - The following chapters explain the meaning of those identifiers. - </para> - <sect1 id="Function_identifiers_XXX"> - <title>Function identifiers [XXX]</title> - <para> - The functions are marked with [XXX] identifiers in the short - comment. The identifiers explain the usage and scope of the - functions. Following identifiers are used: - </para> - <itemizedlist> - <listitem><para> - [MTD Interface]</para><para> - These functions provide the interface to the MTD kernel API. - They are not replaceable and provide functionality - which is complete hardware independent. - </para></listitem> - <listitem><para> - [NAND Interface]</para><para> - These functions are exported and provide the interface to the NAND kernel API. - </para></listitem> - <listitem><para> - [GENERIC]</para><para> - Generic functions are not replaceable and provide functionality - which is complete hardware independent. - </para></listitem> - <listitem><para> - [DEFAULT]</para><para> - Default functions provide hardware related functionality which is suitable - for most of the implementations. These functions can be replaced by the - board driver if necessary. Those functions are called via pointers in the - NAND chip description structure. The board driver can set the functions which - should be replaced by board dependent functions before calling nand_scan(). - If the function pointer is NULL on entry to nand_scan() then the pointer - is set to the default function which is suitable for the detected chip type. - </para></listitem> - </itemizedlist> - </sect1> - <sect1 id="Struct_member_identifiers_XXX"> - <title>Struct member identifiers [XXX]</title> - <para> - The struct members are marked with [XXX] identifiers in the - comment. The identifiers explain the usage and scope of the - members. Following identifiers are used: - </para> - <itemizedlist> - <listitem><para> - [INTERN]</para><para> - These members are for NAND driver internal use only and must not be - modified. Most of these values are calculated from the chip geometry - information which is evaluated during nand_scan(). - </para></listitem> - <listitem><para> - [REPLACEABLE]</para><para> - Replaceable members hold hardware related functions which can be - provided by the board driver. The board driver can set the functions which - should be replaced by board dependent functions before calling nand_scan(). - If the function pointer is NULL on entry to nand_scan() then the pointer - is set to the default function which is suitable for the detected chip type. - </para></listitem> - <listitem><para> - [BOARDSPECIFIC]</para><para> - Board specific members hold hardware related information which must - be provided by the board driver. The board driver must set the function - pointers and datafields before calling nand_scan(). - </para></listitem> - <listitem><para> - [OPTIONAL]</para><para> - Optional members can hold information relevant for the board driver. The - generic NAND driver code does not use this information. - </para></listitem> - </itemizedlist> - </sect1> - </chapter> - - <chapter id="basicboarddriver"> - <title>Basic board driver</title> - <para> - For most boards it will be sufficient to provide just the - basic functions and fill out some really board dependent - members in the nand chip description structure. - </para> - <sect1 id="Basic_defines"> - <title>Basic defines</title> - <para> - At least you have to provide a nand_chip structure - and a storage for the ioremap'ed chip address. - You can allocate the nand_chip structure using - kmalloc or you can allocate it statically. - The NAND chip structure embeds an mtd structure - which will be registered to the MTD subsystem. - You can extract a pointer to the mtd structure - from a nand_chip pointer using the nand_to_mtd() - helper. - </para> - <para> - Kmalloc based example - </para> - <programlisting> -static struct mtd_info *board_mtd; -static void __iomem *baseaddr; - </programlisting> - <para> - Static example - </para> - <programlisting> -static struct nand_chip board_chip; -static void __iomem *baseaddr; - </programlisting> - </sect1> - <sect1 id="Partition_defines"> - <title>Partition defines</title> - <para> - If you want to divide your device into partitions, then - define a partitioning scheme suitable to your board. - </para> - <programlisting> -#define NUM_PARTITIONS 2 -static struct mtd_partition partition_info[] = { - { .name = "Flash partition 1", - .offset = 0, - .size = 8 * 1024 * 1024 }, - { .name = "Flash partition 2", - .offset = MTDPART_OFS_NEXT, - .size = MTDPART_SIZ_FULL }, -}; - </programlisting> - </sect1> - <sect1 id="Hardware_control_functions"> - <title>Hardware control function</title> - <para> - The hardware control function provides access to the - control pins of the NAND chip(s). - The access can be done by GPIO pins or by address lines. - If you use address lines, make sure that the timing - requirements are met. - </para> - <para> - <emphasis>GPIO based example</emphasis> - </para> - <programlisting> -static void board_hwcontrol(struct mtd_info *mtd, int cmd) -{ - switch(cmd){ - case NAND_CTL_SETCLE: /* Set CLE pin high */ break; - case NAND_CTL_CLRCLE: /* Set CLE pin low */ break; - case NAND_CTL_SETALE: /* Set ALE pin high */ break; - case NAND_CTL_CLRALE: /* Set ALE pin low */ break; - case NAND_CTL_SETNCE: /* Set nCE pin low */ break; - case NAND_CTL_CLRNCE: /* Set nCE pin high */ break; - } -} - </programlisting> - <para> - <emphasis>Address lines based example.</emphasis> It's assumed that the - nCE pin is driven by a chip select decoder. - </para> - <programlisting> -static void board_hwcontrol(struct mtd_info *mtd, int cmd) -{ - struct nand_chip *this = mtd_to_nand(mtd); - switch(cmd){ - case NAND_CTL_SETCLE: this->IO_ADDR_W |= CLE_ADRR_BIT; break; - case NAND_CTL_CLRCLE: this->IO_ADDR_W &= ~CLE_ADRR_BIT; break; - case NAND_CTL_SETALE: this->IO_ADDR_W |= ALE_ADRR_BIT; break; - case NAND_CTL_CLRALE: this->IO_ADDR_W &= ~ALE_ADRR_BIT; break; - } -} - </programlisting> - </sect1> - <sect1 id="Device_ready_function"> - <title>Device ready function</title> - <para> - If the hardware interface has the ready busy pin of the NAND chip connected to a - GPIO or other accessible I/O pin, this function is used to read back the state of the - pin. The function has no arguments and should return 0, if the device is busy (R/B pin - is low) and 1, if the device is ready (R/B pin is high). - If the hardware interface does not give access to the ready busy pin, then - the function must not be defined and the function pointer this->dev_ready is set to NULL. - </para> - </sect1> - <sect1 id="Init_function"> - <title>Init function</title> - <para> - The init function allocates memory and sets up all the board - specific parameters and function pointers. When everything - is set up nand_scan() is called. This function tries to - detect and identify then chip. If a chip is found all the - internal data fields are initialized accordingly. - The structure(s) have to be zeroed out first and then filled with the necessary - information about the device. - </para> - <programlisting> -static int __init board_init (void) -{ - struct nand_chip *this; - int err = 0; - - /* Allocate memory for MTD device structure and private data */ - this = kzalloc(sizeof(struct nand_chip), GFP_KERNEL); - if (!this) { - printk ("Unable to allocate NAND MTD device structure.\n"); - err = -ENOMEM; - goto out; - } - - board_mtd = nand_to_mtd(this); - - /* map physical address */ - baseaddr = ioremap(CHIP_PHYSICAL_ADDRESS, 1024); - if (!baseaddr) { - printk("Ioremap to access NAND chip failed\n"); - err = -EIO; - goto out_mtd; - } - - /* Set address of NAND IO lines */ - this->IO_ADDR_R = baseaddr; - this->IO_ADDR_W = baseaddr; - /* Reference hardware control function */ - this->hwcontrol = board_hwcontrol; - /* Set command delay time, see datasheet for correct value */ - this->chip_delay = CHIP_DEPENDEND_COMMAND_DELAY; - /* Assign the device ready function, if available */ - this->dev_ready = board_dev_ready; - this->eccmode = NAND_ECC_SOFT; - - /* Scan to find existence of the device */ - if (nand_scan (board_mtd, 1)) { - err = -ENXIO; - goto out_ior; - } - - add_mtd_partitions(board_mtd, partition_info, NUM_PARTITIONS); - goto out; - -out_ior: - iounmap(baseaddr); -out_mtd: - kfree (this); -out: - return err; -} -module_init(board_init); - </programlisting> - </sect1> - <sect1 id="Exit_function"> - <title>Exit function</title> - <para> - The exit function is only necessary if the driver is - compiled as a module. It releases all resources which - are held by the chip driver and unregisters the partitions - in the MTD layer. - </para> - <programlisting> -#ifdef MODULE -static void __exit board_cleanup (void) -{ - /* Release resources, unregister device */ - nand_release (board_mtd); - - /* unmap physical address */ - iounmap(baseaddr); - - /* Free the MTD device structure */ - kfree (mtd_to_nand(board_mtd)); -} -module_exit(board_cleanup); -#endif - </programlisting> - </sect1> - </chapter> - - <chapter id="boarddriversadvanced"> - <title>Advanced board driver functions</title> - <para> - This chapter describes the advanced functionality of the NAND - driver. For a list of functions which can be overridden by the board - driver see the documentation of the nand_chip structure. - </para> - <sect1 id="Multiple_chip_control"> - <title>Multiple chip control</title> - <para> - The nand driver can control chip arrays. Therefore the - board driver must provide an own select_chip function. This - function must (de)select the requested chip. - The function pointer in the nand_chip structure must - be set before calling nand_scan(). The maxchip parameter - of nand_scan() defines the maximum number of chips to - scan for. Make sure that the select_chip function can - handle the requested number of chips. - </para> - <para> - The nand driver concatenates the chips to one virtual - chip and provides this virtual chip to the MTD layer. - </para> - <para> - <emphasis>Note: The driver can only handle linear chip arrays - of equally sized chips. There is no support for - parallel arrays which extend the buswidth.</emphasis> - </para> - <para> - <emphasis>GPIO based example</emphasis> - </para> - <programlisting> -static void board_select_chip (struct mtd_info *mtd, int chip) -{ - /* Deselect all chips, set all nCE pins high */ - GPIO(BOARD_NAND_NCE) |= 0xff; - if (chip >= 0) - GPIO(BOARD_NAND_NCE) &= ~ (1 << chip); -} - </programlisting> - <para> - <emphasis>Address lines based example.</emphasis> - Its assumed that the nCE pins are connected to an - address decoder. - </para> - <programlisting> -static void board_select_chip (struct mtd_info *mtd, int chip) -{ - struct nand_chip *this = mtd_to_nand(mtd); - - /* Deselect all chips */ - this->IO_ADDR_R &= ~BOARD_NAND_ADDR_MASK; - this->IO_ADDR_W &= ~BOARD_NAND_ADDR_MASK; - switch (chip) { - case 0: - this->IO_ADDR_R |= BOARD_NAND_ADDR_CHIP0; - this->IO_ADDR_W |= BOARD_NAND_ADDR_CHIP0; - break; - .... - case n: - this->IO_ADDR_R |= BOARD_NAND_ADDR_CHIPn; - this->IO_ADDR_W |= BOARD_NAND_ADDR_CHIPn; - break; - } -} - </programlisting> - </sect1> - <sect1 id="Hardware_ECC_support"> - <title>Hardware ECC support</title> - <sect2 id="Functions_and_constants"> - <title>Functions and constants</title> - <para> - The nand driver supports three different types of - hardware ECC. - <itemizedlist> - <listitem><para>NAND_ECC_HW3_256</para><para> - Hardware ECC generator providing 3 bytes ECC per - 256 byte. - </para> </listitem> - <listitem><para>NAND_ECC_HW3_512</para><para> - Hardware ECC generator providing 3 bytes ECC per - 512 byte. - </para> </listitem> - <listitem><para>NAND_ECC_HW6_512</para><para> - Hardware ECC generator providing 6 bytes ECC per - 512 byte. - </para> </listitem> - <listitem><para>NAND_ECC_HW8_512</para><para> - Hardware ECC generator providing 6 bytes ECC per - 512 byte. - </para> </listitem> - </itemizedlist> - If your hardware generator has a different functionality - add it at the appropriate place in nand_base.c - </para> - <para> - The board driver must provide following functions: - <itemizedlist> - <listitem><para>enable_hwecc</para><para> - This function is called before reading / writing to - the chip. Reset or initialize the hardware generator - in this function. The function is called with an - argument which let you distinguish between read - and write operations. - </para> </listitem> - <listitem><para>calculate_ecc</para><para> - This function is called after read / write from / to - the chip. Transfer the ECC from the hardware to - the buffer. If the option NAND_HWECC_SYNDROME is set - then the function is only called on write. See below. - </para> </listitem> - <listitem><para>correct_data</para><para> - In case of an ECC error this function is called for - error detection and correction. Return 1 respectively 2 - in case the error can be corrected. If the error is - not correctable return -1. If your hardware generator - matches the default algorithm of the nand_ecc software - generator then use the correction function provided - by nand_ecc instead of implementing duplicated code. - </para> </listitem> - </itemizedlist> - </para> - </sect2> - <sect2 id="Hardware_ECC_with_syndrome_calculation"> - <title>Hardware ECC with syndrome calculation</title> - <para> - Many hardware ECC implementations provide Reed-Solomon - codes and calculate an error syndrome on read. The syndrome - must be converted to a standard Reed-Solomon syndrome - before calling the error correction code in the generic - Reed-Solomon library. - </para> - <para> - The ECC bytes must be placed immediately after the data - bytes in order to make the syndrome generator work. This - is contrary to the usual layout used by software ECC. The - separation of data and out of band area is not longer - possible. The nand driver code handles this layout and - the remaining free bytes in the oob area are managed by - the autoplacement code. Provide a matching oob-layout - in this case. See rts_from4.c and diskonchip.c for - implementation reference. In those cases we must also - use bad block tables on FLASH, because the ECC layout is - interfering with the bad block marker positions. - See bad block table support for details. - </para> - </sect2> - </sect1> - <sect1 id="Bad_Block_table_support"> - <title>Bad block table support</title> - <para> - Most NAND chips mark the bad blocks at a defined - position in the spare area. Those blocks must - not be erased under any circumstances as the bad - block information would be lost. - It is possible to check the bad block mark each - time when the blocks are accessed by reading the - spare area of the first page in the block. This - is time consuming so a bad block table is used. - </para> - <para> - The nand driver supports various types of bad block - tables. - <itemizedlist> - <listitem><para>Per device</para><para> - The bad block table contains all bad block information - of the device which can consist of multiple chips. - </para> </listitem> - <listitem><para>Per chip</para><para> - A bad block table is used per chip and contains the - bad block information for this particular chip. - </para> </listitem> - <listitem><para>Fixed offset</para><para> - The bad block table is located at a fixed offset - in the chip (device). This applies to various - DiskOnChip devices. - </para> </listitem> - <listitem><para>Automatic placed</para><para> - The bad block table is automatically placed and - detected either at the end or at the beginning - of a chip (device) - </para> </listitem> - <listitem><para>Mirrored tables</para><para> - The bad block table is mirrored on the chip (device) to - allow updates of the bad block table without data loss. - </para> </listitem> - </itemizedlist> - </para> - <para> - nand_scan() calls the function nand_default_bbt(). - nand_default_bbt() selects appropriate default - bad block table descriptors depending on the chip information - which was retrieved by nand_scan(). - </para> - <para> - The standard policy is scanning the device for bad - blocks and build a ram based bad block table which - allows faster access than always checking the - bad block information on the flash chip itself. - </para> - <sect2 id="Flash_based_tables"> - <title>Flash based tables</title> - <para> - It may be desired or necessary to keep a bad block table in FLASH. - For AG-AND chips this is mandatory, as they have no factory marked - bad blocks. They have factory marked good blocks. The marker pattern - is erased when the block is erased to be reused. So in case of - powerloss before writing the pattern back to the chip this block - would be lost and added to the bad blocks. Therefore we scan the - chip(s) when we detect them the first time for good blocks and - store this information in a bad block table before erasing any - of the blocks. - </para> - <para> - The blocks in which the tables are stored are protected against - accidental access by marking them bad in the memory bad block - table. The bad block table management functions are allowed - to circumvent this protection. - </para> - <para> - The simplest way to activate the FLASH based bad block table support - is to set the option NAND_BBT_USE_FLASH in the bbt_option field of - the nand chip structure before calling nand_scan(). For AG-AND - chips is this done by default. - This activates the default FLASH based bad block table functionality - of the NAND driver. The default bad block table options are - <itemizedlist> - <listitem><para>Store bad block table per chip</para></listitem> - <listitem><para>Use 2 bits per block</para></listitem> - <listitem><para>Automatic placement at the end of the chip</para></listitem> - <listitem><para>Use mirrored tables with version numbers</para></listitem> - <listitem><para>Reserve 4 blocks at the end of the chip</para></listitem> - </itemizedlist> - </para> - </sect2> - <sect2 id="User_defined_tables"> - <title>User defined tables</title> - <para> - User defined tables are created by filling out a - nand_bbt_descr structure and storing the pointer in the - nand_chip structure member bbt_td before calling nand_scan(). - If a mirror table is necessary a second structure must be - created and a pointer to this structure must be stored - in bbt_md inside the nand_chip structure. If the bbt_md - member is set to NULL then only the main table is used - and no scan for the mirrored table is performed. - </para> - <para> - The most important field in the nand_bbt_descr structure - is the options field. The options define most of the - table properties. Use the predefined constants from - nand.h to define the options. - <itemizedlist> - <listitem><para>Number of bits per block</para> - <para>The supported number of bits is 1, 2, 4, 8.</para></listitem> - <listitem><para>Table per chip</para> - <para>Setting the constant NAND_BBT_PERCHIP selects that - a bad block table is managed for each chip in a chip array. - If this option is not set then a per device bad block table - is used.</para></listitem> - <listitem><para>Table location is absolute</para> - <para>Use the option constant NAND_BBT_ABSPAGE and - define the absolute page number where the bad block - table starts in the field pages. If you have selected bad block - tables per chip and you have a multi chip array then the start page - must be given for each chip in the chip array. Note: there is no scan - for a table ident pattern performed, so the fields - pattern, veroffs, offs, len can be left uninitialized</para></listitem> - <listitem><para>Table location is automatically detected</para> - <para>The table can either be located in the first or the last good - blocks of the chip (device). Set NAND_BBT_LASTBLOCK to place - the bad block table at the end of the chip (device). The - bad block tables are marked and identified by a pattern which - is stored in the spare area of the first page in the block which - holds the bad block table. Store a pointer to the pattern - in the pattern field. Further the length of the pattern has to be - stored in len and the offset in the spare area must be given - in the offs member of the nand_bbt_descr structure. For mirrored - bad block tables different patterns are mandatory.</para></listitem> - <listitem><para>Table creation</para> - <para>Set the option NAND_BBT_CREATE to enable the table creation - if no table can be found during the scan. Usually this is done only - once if a new chip is found. </para></listitem> - <listitem><para>Table write support</para> - <para>Set the option NAND_BBT_WRITE to enable the table write support. - This allows the update of the bad block table(s) in case a block has - to be marked bad due to wear. The MTD interface function block_markbad - is calling the update function of the bad block table. If the write - support is enabled then the table is updated on FLASH.</para> - <para> - Note: Write support should only be enabled for mirrored tables with - version control. - </para></listitem> - <listitem><para>Table version control</para> - <para>Set the option NAND_BBT_VERSION to enable the table version control. - It's highly recommended to enable this for mirrored tables with write - support. It makes sure that the risk of losing the bad block - table information is reduced to the loss of the information about the - one worn out block which should be marked bad. The version is stored in - 4 consecutive bytes in the spare area of the device. The position of - the version number is defined by the member veroffs in the bad block table - descriptor.</para></listitem> - <listitem><para>Save block contents on write</para> - <para> - In case that the block which holds the bad block table does contain - other useful information, set the option NAND_BBT_SAVECONTENT. When - the bad block table is written then the whole block is read the bad - block table is updated and the block is erased and everything is - written back. If this option is not set only the bad block table - is written and everything else in the block is ignored and erased. - </para></listitem> - <listitem><para>Number of reserved blocks</para> - <para> - For automatic placement some blocks must be reserved for - bad block table storage. The number of reserved blocks is defined - in the maxblocks member of the bad block table description structure. - Reserving 4 blocks for mirrored tables should be a reasonable number. - This also limits the number of blocks which are scanned for the bad - block table ident pattern. - </para></listitem> - </itemizedlist> - </para> - </sect2> - </sect1> - <sect1 id="Spare_area_placement"> - <title>Spare area (auto)placement</title> - <para> - The nand driver implements different possibilities for - placement of filesystem data in the spare area, - <itemizedlist> - <listitem><para>Placement defined by fs driver</para></listitem> - <listitem><para>Automatic placement</para></listitem> - </itemizedlist> - The default placement function is automatic placement. The - nand driver has built in default placement schemes for the - various chiptypes. If due to hardware ECC functionality the - default placement does not fit then the board driver can - provide a own placement scheme. - </para> - <para> - File system drivers can provide a own placement scheme which - is used instead of the default placement scheme. - </para> - <para> - Placement schemes are defined by a nand_oobinfo structure - <programlisting> -struct nand_oobinfo { - int useecc; - int eccbytes; - int eccpos[24]; - int oobfree[8][2]; -}; - </programlisting> - <itemizedlist> - <listitem><para>useecc</para><para> - The useecc member controls the ecc and placement function. The header - file include/mtd/mtd-abi.h contains constants to select ecc and - placement. MTD_NANDECC_OFF switches off the ecc complete. This is - not recommended and available for testing and diagnosis only. - MTD_NANDECC_PLACE selects caller defined placement, MTD_NANDECC_AUTOPLACE - selects automatic placement. - </para></listitem> - <listitem><para>eccbytes</para><para> - The eccbytes member defines the number of ecc bytes per page. - </para></listitem> - <listitem><para>eccpos</para><para> - The eccpos array holds the byte offsets in the spare area where - the ecc codes are placed. - </para></listitem> - <listitem><para>oobfree</para><para> - The oobfree array defines the areas in the spare area which can be - used for automatic placement. The information is given in the format - {offset, size}. offset defines the start of the usable area, size the - length in bytes. More than one area can be defined. The list is terminated - by an {0, 0} entry. - </para></listitem> - </itemizedlist> - </para> - <sect2 id="Placement_defined_by_fs_driver"> - <title>Placement defined by fs driver</title> - <para> - The calling function provides a pointer to a nand_oobinfo - structure which defines the ecc placement. For writes the - caller must provide a spare area buffer along with the - data buffer. The spare area buffer size is (number of pages) * - (size of spare area). For reads the buffer size is - (number of pages) * ((size of spare area) + (number of ecc - steps per page) * sizeof (int)). The driver stores the - result of the ecc check for each tuple in the spare buffer. - The storage sequence is - </para> - <para> - <spare data page 0><ecc result 0>...<ecc result n> - </para> - <para> - ... - </para> - <para> - <spare data page n><ecc result 0>...<ecc result n> - </para> - <para> - This is a legacy mode used by YAFFS1. - </para> - <para> - If the spare area buffer is NULL then only the ECC placement is - done according to the given scheme in the nand_oobinfo structure. - </para> - </sect2> - <sect2 id="Automatic_placement"> - <title>Automatic placement</title> - <para> - Automatic placement uses the built in defaults to place the - ecc bytes in the spare area. If filesystem data have to be stored / - read into the spare area then the calling function must provide a - buffer. The buffer size per page is determined by the oobfree array in - the nand_oobinfo structure. - </para> - <para> - If the spare area buffer is NULL then only the ECC placement is - done according to the default builtin scheme. - </para> - </sect2> - </sect1> - <sect1 id="Spare_area_autoplacement_default"> - <title>Spare area autoplacement default schemes</title> - <sect2 id="pagesize_256"> - <title>256 byte pagesize</title> -<informaltable><tgroup cols="3"><tbody> -<row> -<entry>Offset</entry> -<entry>Content</entry> -<entry>Comment</entry> -</row> -<row> -<entry>0x00</entry> -<entry>ECC byte 0</entry> -<entry>Error correction code byte 0</entry> -</row> -<row> -<entry>0x01</entry> -<entry>ECC byte 1</entry> -<entry>Error correction code byte 1</entry> -</row> -<row> -<entry>0x02</entry> -<entry>ECC byte 2</entry> -<entry>Error correction code byte 2</entry> -</row> -<row> -<entry>0x03</entry> -<entry>Autoplace 0</entry> -<entry></entry> -</row> -<row> -<entry>0x04</entry> -<entry>Autoplace 1</entry> -<entry></entry> -</row> -<row> -<entry>0x05</entry> -<entry>Bad block marker</entry> -<entry>If any bit in this byte is zero, then this block is bad. -This applies only to the first page in a block. In the remaining -pages this byte is reserved</entry> -</row> -<row> -<entry>0x06</entry> -<entry>Autoplace 2</entry> -<entry></entry> -</row> -<row> -<entry>0x07</entry> -<entry>Autoplace 3</entry> -<entry></entry> -</row> -</tbody></tgroup></informaltable> - </sect2> - <sect2 id="pagesize_512"> - <title>512 byte pagesize</title> -<informaltable><tgroup cols="3"><tbody> -<row> -<entry>Offset</entry> -<entry>Content</entry> -<entry>Comment</entry> -</row> -<row> -<entry>0x00</entry> -<entry>ECC byte 0</entry> -<entry>Error correction code byte 0 of the lower 256 Byte data in -this page</entry> -</row> -<row> -<entry>0x01</entry> -<entry>ECC byte 1</entry> -<entry>Error correction code byte 1 of the lower 256 Bytes of data -in this page</entry> -</row> -<row> -<entry>0x02</entry> -<entry>ECC byte 2</entry> -<entry>Error correction code byte 2 of the lower 256 Bytes of data -in this page</entry> -</row> -<row> -<entry>0x03</entry> -<entry>ECC byte 3</entry> -<entry>Error correction code byte 0 of the upper 256 Bytes of data -in this page</entry> -</row> -<row> -<entry>0x04</entry> -<entry>reserved</entry> -<entry>reserved</entry> -</row> -<row> -<entry>0x05</entry> -<entry>Bad block marker</entry> -<entry>If any bit in this byte is zero, then this block is bad. -This applies only to the first page in a block. In the remaining -pages this byte is reserved</entry> -</row> -<row> -<entry>0x06</entry> -<entry>ECC byte 4</entry> -<entry>Error correction code byte 1 of the upper 256 Bytes of data -in this page</entry> -</row> -<row> -<entry>0x07</entry> -<entry>ECC byte 5</entry> -<entry>Error correction code byte 2 of the upper 256 Bytes of data -in this page</entry> -</row> -<row> -<entry>0x08 - 0x0F</entry> -<entry>Autoplace 0 - 7</entry> -<entry></entry> -</row> -</tbody></tgroup></informaltable> - </sect2> - <sect2 id="pagesize_2048"> - <title>2048 byte pagesize</title> -<informaltable><tgroup cols="3"><tbody> -<row> -<entry>Offset</entry> -<entry>Content</entry> -<entry>Comment</entry> -</row> -<row> -<entry>0x00</entry> -<entry>Bad block marker</entry> -<entry>If any bit in this byte is zero, then this block is bad. -This applies only to the first page in a block. In the remaining -pages this byte is reserved</entry> -</row> -<row> -<entry>0x01</entry> -<entry>Reserved</entry> -<entry>Reserved</entry> -</row> -<row> -<entry>0x02-0x27</entry> -<entry>Autoplace 0 - 37</entry> -<entry></entry> -</row> -<row> -<entry>0x28</entry> -<entry>ECC byte 0</entry> -<entry>Error correction code byte 0 of the first 256 Byte data in -this page</entry> -</row> -<row> -<entry>0x29</entry> -<entry>ECC byte 1</entry> -<entry>Error correction code byte 1 of the first 256 Bytes of data -in this page</entry> -</row> -<row> -<entry>0x2A</entry> -<entry>ECC byte 2</entry> -<entry>Error correction code byte 2 of the first 256 Bytes data in -this page</entry> -</row> -<row> -<entry>0x2B</entry> -<entry>ECC byte 3</entry> -<entry>Error correction code byte 0 of the second 256 Bytes of data -in this page</entry> -</row> -<row> -<entry>0x2C</entry> -<entry>ECC byte 4</entry> -<entry>Error correction code byte 1 of the second 256 Bytes of data -in this page</entry> -</row> -<row> -<entry>0x2D</entry> -<entry>ECC byte 5</entry> -<entry>Error correction code byte 2 of the second 256 Bytes of data -in this page</entry> -</row> -<row> -<entry>0x2E</entry> -<entry>ECC byte 6</entry> -<entry>Error correction code byte 0 of the third 256 Bytes of data -in this page</entry> -</row> -<row> -<entry>0x2F</entry> -<entry>ECC byte 7</entry> -<entry>Error correction code byte 1 of the third 256 Bytes of data -in this page</entry> -</row> -<row> -<entry>0x30</entry> -<entry>ECC byte 8</entry> -<entry>Error correction code byte 2 of the third 256 Bytes of data -in this page</entry> -</row> -<row> -<entry>0x31</entry> -<entry>ECC byte 9</entry> -<entry>Error correction code byte 0 of the fourth 256 Bytes of data -in this page</entry> -</row> -<row> -<entry>0x32</entry> -<entry>ECC byte 10</entry> -<entry>Error correction code byte 1 of the fourth 256 Bytes of data -in this page</entry> -</row> -<row> -<entry>0x33</entry> -<entry>ECC byte 11</entry> -<entry>Error correction code byte 2 of the fourth 256 Bytes of data -in this page</entry> -</row> -<row> -<entry>0x34</entry> -<entry>ECC byte 12</entry> -<entry>Error correction code byte 0 of the fifth 256 Bytes of data -in this page</entry> -</row> -<row> -<entry>0x35</entry> -<entry>ECC byte 13</entry> -<entry>Error correction code byte 1 of the fifth 256 Bytes of data -in this page</entry> -</row> -<row> -<entry>0x36</entry> -<entry>ECC byte 14</entry> -<entry>Error correction code byte 2 of the fifth 256 Bytes of data -in this page</entry> -</row> -<row> -<entry>0x37</entry> -<entry>ECC byte 15</entry> -<entry>Error correction code byte 0 of the sixt 256 Bytes of data -in this page</entry> -</row> -<row> -<entry>0x38</entry> -<entry>ECC byte 16</entry> -<entry>Error correction code byte 1 of the sixt 256 Bytes of data -in this page</entry> -</row> -<row> -<entry>0x39</entry> -<entry>ECC byte 17</entry> -<entry>Error correction code byte 2 of the sixt 256 Bytes of data -in this page</entry> -</row> -<row> -<entry>0x3A</entry> -<entry>ECC byte 18</entry> -<entry>Error correction code byte 0 of the seventh 256 Bytes of -data in this page</entry> -</row> -<row> -<entry>0x3B</entry> -<entry>ECC byte 19</entry> -<entry>Error correction code byte 1 of the seventh 256 Bytes of -data in this page</entry> -</row> -<row> -<entry>0x3C</entry> -<entry>ECC byte 20</entry> -<entry>Error correction code byte 2 of the seventh 256 Bytes of -data in this page</entry> -</row> -<row> -<entry>0x3D</entry> -<entry>ECC byte 21</entry> -<entry>Error correction code byte 0 of the eighth 256 Bytes of data -in this page</entry> -</row> -<row> -<entry>0x3E</entry> -<entry>ECC byte 22</entry> -<entry>Error correction code byte 1 of the eighth 256 Bytes of data -in this page</entry> -</row> -<row> -<entry>0x3F</entry> -<entry>ECC byte 23</entry> -<entry>Error correction code byte 2 of the eighth 256 Bytes of data -in this page</entry> -</row> -</tbody></tgroup></informaltable> - </sect2> - </sect1> - </chapter> - - <chapter id="filesystems"> - <title>Filesystem support</title> - <para> - The NAND driver provides all necessary functions for a - filesystem via the MTD interface. - </para> - <para> - Filesystems must be aware of the NAND peculiarities and - restrictions. One major restrictions of NAND Flash is, that you cannot - write as often as you want to a page. The consecutive writes to a page, - before erasing it again, are restricted to 1-3 writes, depending on the - manufacturers specifications. This applies similar to the spare area. - </para> - <para> - Therefore NAND aware filesystems must either write in page size chunks - or hold a writebuffer to collect smaller writes until they sum up to - pagesize. Available NAND aware filesystems: JFFS2, YAFFS. - </para> - <para> - The spare area usage to store filesystem data is controlled by - the spare area placement functionality which is described in one - of the earlier chapters. - </para> - </chapter> - <chapter id="tools"> - <title>Tools</title> - <para> - The MTD project provides a couple of helpful tools to handle NAND Flash. - <itemizedlist> - <listitem><para>flasherase, flasheraseall: Erase and format FLASH partitions</para></listitem> - <listitem><para>nandwrite: write filesystem images to NAND FLASH</para></listitem> - <listitem><para>nanddump: dump the contents of a NAND FLASH partitions</para></listitem> - </itemizedlist> - </para> - <para> - These tools are aware of the NAND restrictions. Please use those tools - instead of complaining about errors which are caused by non NAND aware - access methods. - </para> - </chapter> - - <chapter id="defines"> - <title>Constants</title> - <para> - This chapter describes the constants which might be relevant for a driver developer. - </para> - <sect1 id="Chip_option_constants"> - <title>Chip option constants</title> - <sect2 id="Constants_for_chip_id_table"> - <title>Constants for chip id table</title> - <para> - These constants are defined in nand.h. They are ored together to describe - the chip functionality. - <programlisting> -/* Buswitdh is 16 bit */ -#define NAND_BUSWIDTH_16 0x00000002 -/* Device supports partial programming without padding */ -#define NAND_NO_PADDING 0x00000004 -/* Chip has cache program function */ -#define NAND_CACHEPRG 0x00000008 -/* Chip has copy back function */ -#define NAND_COPYBACK 0x00000010 -/* AND Chip which has 4 banks and a confusing page / block - * assignment. See Renesas datasheet for further information */ -#define NAND_IS_AND 0x00000020 -/* Chip has a array of 4 pages which can be read without - * additional ready /busy waits */ -#define NAND_4PAGE_ARRAY 0x00000040 - </programlisting> - </para> - </sect2> - <sect2 id="Constants_for_runtime_options"> - <title>Constants for runtime options</title> - <para> - These constants are defined in nand.h. They are ored together to describe - the functionality. - <programlisting> -/* The hw ecc generator provides a syndrome instead a ecc value on read - * This can only work if we have the ecc bytes directly behind the - * data bytes. Applies for DOC and AG-AND Renesas HW Reed Solomon generators */ -#define NAND_HWECC_SYNDROME 0x00020000 - </programlisting> - </para> - </sect2> - </sect1> - - <sect1 id="EEC_selection_constants"> - <title>ECC selection constants</title> - <para> - Use these constants to select the ECC algorithm. - <programlisting> -/* No ECC. Usage is not recommended ! */ -#define NAND_ECC_NONE 0 -/* Software ECC 3 byte ECC per 256 Byte data */ -#define NAND_ECC_SOFT 1 -/* Hardware ECC 3 byte ECC per 256 Byte data */ -#define NAND_ECC_HW3_256 2 -/* Hardware ECC 3 byte ECC per 512 Byte data */ -#define NAND_ECC_HW3_512 3 -/* Hardware ECC 6 byte ECC per 512 Byte data */ -#define NAND_ECC_HW6_512 4 -/* Hardware ECC 6 byte ECC per 512 Byte data */ -#define NAND_ECC_HW8_512 6 - </programlisting> - </para> - </sect1> - - <sect1 id="Hardware_control_related_constants"> - <title>Hardware control related constants</title> - <para> - These constants describe the requested hardware access function when - the boardspecific hardware control function is called - <programlisting> -/* Select the chip by setting nCE to low */ -#define NAND_CTL_SETNCE 1 -/* Deselect the chip by setting nCE to high */ -#define NAND_CTL_CLRNCE 2 -/* Select the command latch by setting CLE to high */ -#define NAND_CTL_SETCLE 3 -/* Deselect the command latch by setting CLE to low */ -#define NAND_CTL_CLRCLE 4 -/* Select the address latch by setting ALE to high */ -#define NAND_CTL_SETALE 5 -/* Deselect the address latch by setting ALE to low */ -#define NAND_CTL_CLRALE 6 -/* Set write protection by setting WP to high. Not used! */ -#define NAND_CTL_SETWP 7 -/* Clear write protection by setting WP to low. Not used! */ -#define NAND_CTL_CLRWP 8 - </programlisting> - </para> - </sect1> - - <sect1 id="Bad_block_table_constants"> - <title>Bad block table related constants</title> - <para> - These constants describe the options used for bad block - table descriptors. - <programlisting> -/* Options for the bad block table descriptors */ - -/* The number of bits used per block in the bbt on the device */ -#define NAND_BBT_NRBITS_MSK 0x0000000F -#define NAND_BBT_1BIT 0x00000001 -#define NAND_BBT_2BIT 0x00000002 -#define NAND_BBT_4BIT 0x00000004 -#define NAND_BBT_8BIT 0x00000008 -/* The bad block table is in the last good block of the device */ -#define NAND_BBT_LASTBLOCK 0x00000010 -/* The bbt is at the given page, else we must scan for the bbt */ -#define NAND_BBT_ABSPAGE 0x00000020 -/* bbt is stored per chip on multichip devices */ -#define NAND_BBT_PERCHIP 0x00000080 -/* bbt has a version counter at offset veroffs */ -#define NAND_BBT_VERSION 0x00000100 -/* Create a bbt if none axists */ -#define NAND_BBT_CREATE 0x00000200 -/* Write bbt if necessary */ -#define NAND_BBT_WRITE 0x00001000 -/* Read and write back block contents when writing bbt */ -#define NAND_BBT_SAVECONTENT 0x00002000 - </programlisting> - </para> - </sect1> - - </chapter> - - <chapter id="structs"> - <title>Structures</title> - <para> - This chapter contains the autogenerated documentation of the structures which are - used in the NAND driver and might be relevant for a driver developer. Each - struct member has a short description which is marked with an [XXX] identifier. - See the chapter "Documentation hints" for an explanation. - </para> -!Iinclude/linux/mtd/nand.h - </chapter> - - <chapter id="pubfunctions"> - <title>Public Functions Provided</title> - <para> - This chapter contains the autogenerated documentation of the NAND kernel API functions - which are exported. Each function has a short description which is marked with an [XXX] identifier. - See the chapter "Documentation hints" for an explanation. - </para> -!Edrivers/mtd/nand/nand_base.c -!Edrivers/mtd/nand/nand_bbt.c -!Edrivers/mtd/nand/nand_ecc.c - </chapter> - - <chapter id="intfunctions"> - <title>Internal Functions Provided</title> - <para> - This chapter contains the autogenerated documentation of the NAND driver internal functions. - Each function has a short description which is marked with an [XXX] identifier. - See the chapter "Documentation hints" for an explanation. - The functions marked with [DEFAULT] might be relevant for a board driver developer. - </para> -!Idrivers/mtd/nand/nand_base.c -!Idrivers/mtd/nand/nand_bbt.c -<!-- No internal functions for kernel-doc: -X!Idrivers/mtd/nand/nand_ecc.c ---> - </chapter> - - <chapter id="credits"> - <title>Credits</title> - <para> - The following people have contributed to the NAND driver: - <orderedlist> - <listitem><para>Steven J. Hill<email>sjhill@realitydiluted.com</email></para></listitem> - <listitem><para>David Woodhouse<email>dwmw2@infradead.org</email></para></listitem> - <listitem><para>Thomas Gleixner<email>tglx@linutronix.de</email></para></listitem> - </orderedlist> - A lot of users have provided bugfixes, improvements and helping hands for testing. - Thanks a lot. - </para> - <para> - The following people have contributed to this document: - <orderedlist> - <listitem><para>Thomas Gleixner<email>tglx@linutronix.de</email></para></listitem> - </orderedlist> - </para> - </chapter> -</book> diff --git a/Documentation/DocBook/networking.tmpl b/Documentation/DocBook/networking.tmpl deleted file mode 100644 index 29df25016c7c..000000000000 --- a/Documentation/DocBook/networking.tmpl +++ /dev/null @@ -1,111 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="LinuxNetworking"> - <bookinfo> - <title>Linux Networking and Network Devices APIs</title> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="netcore"> - <title>Linux Networking</title> - <sect1><title>Networking Base Types</title> -!Iinclude/linux/net.h - </sect1> - <sect1><title>Socket Buffer Functions</title> -!Iinclude/linux/skbuff.h -!Iinclude/net/sock.h -!Enet/socket.c -!Enet/core/skbuff.c -!Enet/core/sock.c -!Enet/core/datagram.c -!Enet/core/stream.c - </sect1> - <sect1><title>Socket Filter</title> -!Enet/core/filter.c - </sect1> - <sect1><title>Generic Network Statistics</title> -!Iinclude/uapi/linux/gen_stats.h -!Enet/core/gen_stats.c -!Enet/core/gen_estimator.c - </sect1> - <sect1><title>SUN RPC subsystem</title> -<!-- The !D functionality is not perfect, garbage has to be protected by comments -!Dnet/sunrpc/sunrpc_syms.c ---> -!Enet/sunrpc/xdr.c -!Enet/sunrpc/svc_xprt.c -!Enet/sunrpc/xprt.c -!Enet/sunrpc/sched.c -!Enet/sunrpc/socklib.c -!Enet/sunrpc/stats.c -!Enet/sunrpc/rpc_pipe.c -!Enet/sunrpc/rpcb_clnt.c -!Enet/sunrpc/clnt.c - </sect1> - <sect1><title>WiMAX</title> -!Enet/wimax/op-msg.c -!Enet/wimax/op-reset.c -!Enet/wimax/op-rfkill.c -!Enet/wimax/stack.c -!Iinclude/net/wimax.h -!Iinclude/uapi/linux/wimax.h - </sect1> - </chapter> - - <chapter id="netdev"> - <title>Network device support</title> - <sect1><title>Driver Support</title> -!Enet/core/dev.c -!Enet/ethernet/eth.c -!Enet/sched/sch_generic.c -!Iinclude/linux/etherdevice.h -!Iinclude/linux/netdevice.h - </sect1> - <sect1><title>PHY Support</title> -!Edrivers/net/phy/phy.c -!Idrivers/net/phy/phy.c -!Edrivers/net/phy/phy_device.c -!Idrivers/net/phy/phy_device.c -!Edrivers/net/phy/mdio_bus.c -!Idrivers/net/phy/mdio_bus.c - </sect1> -<!-- FIXME: Removed for now since no structured comments in source - <sect1><title>Wireless</title> -X!Enet/core/wireless.c - </sect1> ---> - </chapter> - -</book> diff --git a/Documentation/DocBook/rapidio.tmpl b/Documentation/DocBook/rapidio.tmpl deleted file mode 100644 index 50479360d845..000000000000 --- a/Documentation/DocBook/rapidio.tmpl +++ /dev/null @@ -1,158 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ - <!ENTITY rapidio SYSTEM "rapidio.xml"> - ]> - -<book id="RapidIO-Guide"> - <bookinfo> - <title>RapidIO Subsystem Guide</title> - - <authorgroup> - <author> - <firstname>Matt</firstname> - <surname>Porter</surname> - <affiliation> - <address> - <email>mporter@kernel.crashing.org</email> - <email>mporter@mvista.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2005</year> - <holder>MontaVista Software, Inc.</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License version 2 as published by the Free Software Foundation. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="intro"> - <title>Introduction</title> - <para> - RapidIO is a high speed switched fabric interconnect with - features aimed at the embedded market. RapidIO provides - support for memory-mapped I/O as well as message-based - transactions over the switched fabric network. RapidIO has - a standardized discovery mechanism not unlike the PCI bus - standard that allows simple detection of devices in a - network. - </para> - <para> - This documentation is provided for developers intending - to support RapidIO on new architectures, write new drivers, - or to understand the subsystem internals. - </para> - </chapter> - - <chapter id="bugs"> - <title>Known Bugs and Limitations</title> - - <sect1 id="known_bugs"> - <title>Bugs</title> - <para>None. ;)</para> - </sect1> - <sect1 id="Limitations"> - <title>Limitations</title> - <para> - <orderedlist> - <listitem><para>Access/management of RapidIO memory regions is not supported</para></listitem> - <listitem><para>Multiple host enumeration is not supported</para></listitem> - </orderedlist> - </para> - </sect1> - </chapter> - - <chapter id="drivers"> - <title>RapidIO driver interface</title> - <para> - Drivers are provided a set of calls in order - to interface with the subsystem to gather info - on devices, request/map memory region resources, - and manage mailboxes/doorbells. - </para> - <sect1 id="Functions"> - <title>Functions</title> -!Iinclude/linux/rio_drv.h -!Edrivers/rapidio/rio-driver.c -!Edrivers/rapidio/rio.c - </sect1> - </chapter> - - <chapter id="internals"> - <title>Internals</title> - - <para> - This chapter contains the autogenerated documentation of the RapidIO - subsystem. - </para> - - <sect1 id="Structures"><title>Structures</title> -!Iinclude/linux/rio.h - </sect1> - <sect1 id="Enumeration_and_Discovery"><title>Enumeration and Discovery</title> -!Idrivers/rapidio/rio-scan.c - </sect1> - <sect1 id="Driver_functionality"><title>Driver functionality</title> -!Idrivers/rapidio/rio.c -!Idrivers/rapidio/rio-access.c - </sect1> - <sect1 id="Device_model_support"><title>Device model support</title> -!Idrivers/rapidio/rio-driver.c - </sect1> - <sect1 id="Sysfs_support"><title>Sysfs support</title> -!Idrivers/rapidio/rio-sysfs.c - </sect1> - <sect1 id="PPC32_support"><title>PPC32 support</title> -!Iarch/powerpc/sysdev/fsl_rio.c - </sect1> - </chapter> - - <chapter id="credits"> - <title>Credits</title> - <para> - The following people have contributed to the RapidIO - subsystem directly or indirectly: - <orderedlist> - <listitem><para>Matt Porter<email>mporter@kernel.crashing.org</email></para></listitem> - <listitem><para>Randy Vinson<email>rvinson@mvista.com</email></para></listitem> - <listitem><para>Dan Malek<email>dan@embeddedalley.com</email></para></listitem> - </orderedlist> - </para> - <para> - The following people have contributed to this document: - <orderedlist> - <listitem><para>Matt Porter<email>mporter@kernel.crashing.org</email></para></listitem> - </orderedlist> - </para> - </chapter> -</book> diff --git a/Documentation/DocBook/regulator.tmpl b/Documentation/DocBook/regulator.tmpl deleted file mode 100644 index 3b08a085d2c7..000000000000 --- a/Documentation/DocBook/regulator.tmpl +++ /dev/null @@ -1,304 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="regulator-api"> - <bookinfo> - <title>Voltage and current regulator API</title> - - <authorgroup> - <author> - <firstname>Liam</firstname> - <surname>Girdwood</surname> - <affiliation> - <address> - <email>lrg@slimlogic.co.uk</email> - </address> - </affiliation> - </author> - <author> - <firstname>Mark</firstname> - <surname>Brown</surname> - <affiliation> - <orgname>Wolfson Microelectronics</orgname> - <address> - <email>broonie@opensource.wolfsonmicro.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2007-2008</year> - <holder>Wolfson Microelectronics</holder> - </copyright> - <copyright> - <year>2008</year> - <holder>Liam Girdwood</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License version 2 as published by the Free Software Foundation. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="intro"> - <title>Introduction</title> - <para> - This framework is designed to provide a standard kernel - interface to control voltage and current regulators. - </para> - <para> - The intention is to allow systems to dynamically control - regulator power output in order to save power and prolong - battery life. This applies to both voltage regulators (where - voltage output is controllable) and current sinks (where current - limit is controllable). - </para> - <para> - Note that additional (and currently more complete) documentation - is available in the Linux kernel source under - <filename>Documentation/power/regulator</filename>. - </para> - - <sect1 id="glossary"> - <title>Glossary</title> - <para> - The regulator API uses a number of terms which may not be - familiar: - </para> - <glossary> - - <glossentry> - <glossterm>Regulator</glossterm> - <glossdef> - <para> - Electronic device that supplies power to other devices. Most - regulators can enable and disable their output and some can also - control their output voltage or current. - </para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>Consumer</glossterm> - <glossdef> - <para> - Electronic device which consumes power provided by a regulator. - These may either be static, requiring only a fixed supply, or - dynamic, requiring active management of the regulator at - runtime. - </para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>Power Domain</glossterm> - <glossdef> - <para> - The electronic circuit supplied by a given regulator, including - the regulator and all consumer devices. The configuration of - the regulator is shared between all the components in the - circuit. - </para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>Power Management Integrated Circuit</glossterm> - <acronym>PMIC</acronym> - <glossdef> - <para> - An IC which contains numerous regulators and often also other - subsystems. In an embedded system the primary PMIC is often - equivalent to a combination of the PSU and southbridge in a - desktop system. - </para> - </glossdef> - </glossentry> - </glossary> - </sect1> - </chapter> - - <chapter id="consumer"> - <title>Consumer driver interface</title> - <para> - This offers a similar API to the kernel clock framework. - Consumer drivers use <link - linkend='API-regulator-get'>get</link> and <link - linkend='API-regulator-put'>put</link> operations to acquire and - release regulators. Functions are - provided to <link linkend='API-regulator-enable'>enable</link> - and <link linkend='API-regulator-disable'>disable</link> the - regulator and to get and set the runtime parameters of the - regulator. - </para> - <para> - When requesting regulators consumers use symbolic names for their - supplies, such as "Vcc", which are mapped into actual regulator - devices by the machine interface. - </para> - <para> - A stub version of this API is provided when the regulator - framework is not in use in order to minimise the need to use - ifdefs. - </para> - - <sect1 id="consumer-enable"> - <title>Enabling and disabling</title> - <para> - The regulator API provides reference counted enabling and - disabling of regulators. Consumer devices use the <function><link - linkend='API-regulator-enable'>regulator_enable</link></function> - and <function><link - linkend='API-regulator-disable'>regulator_disable</link> - </function> functions to enable and disable regulators. Calls - to the two functions must be balanced. - </para> - <para> - Note that since multiple consumers may be using a regulator and - machine constraints may not allow the regulator to be disabled - there is no guarantee that calling - <function>regulator_disable</function> will actually cause the - supply provided by the regulator to be disabled. Consumer - drivers should assume that the regulator may be enabled at all - times. - </para> - </sect1> - - <sect1 id="consumer-config"> - <title>Configuration</title> - <para> - Some consumer devices may need to be able to dynamically - configure their supplies. For example, MMC drivers may need to - select the correct operating voltage for their cards. This may - be done while the regulator is enabled or disabled. - </para> - <para> - The <function><link - linkend='API-regulator-set-voltage'>regulator_set_voltage</link> - </function> and <function><link - linkend='API-regulator-set-current-limit' - >regulator_set_current_limit</link> - </function> functions provide the primary interface for this. - Both take ranges of voltages and currents, supporting drivers - that do not require a specific value (eg, CPU frequency scaling - normally permits the CPU to use a wider range of supply - voltages at lower frequencies but does not require that the - supply voltage be lowered). Where an exact value is required - both minimum and maximum values should be identical. - </para> - </sect1> - - <sect1 id="consumer-callback"> - <title>Callbacks</title> - <para> - Callbacks may also be <link - linkend='API-regulator-register-notifier'>registered</link> - for events such as regulation failures. - </para> - </sect1> - </chapter> - - <chapter id="driver"> - <title>Regulator driver interface</title> - <para> - Drivers for regulator chips <link - linkend='API-regulator-register'>register</link> the regulators - with the regulator core, providing operations structures to the - core. A <link - linkend='API-regulator-notifier-call-chain'>notifier</link> interface - allows error conditions to be reported to the core. - </para> - <para> - Registration should be triggered by explicit setup done by the - platform, supplying a <link - linkend='API-struct-regulator-init-data'>struct - regulator_init_data</link> for the regulator containing - <link linkend='machine-constraint'>constraint</link> and - <link linkend='machine-supply'>supply</link> information. - </para> - </chapter> - - <chapter id="machine"> - <title>Machine interface</title> - <para> - This interface provides a way to define how regulators are - connected to consumers on a given system and what the valid - operating parameters are for the system. - </para> - - <sect1 id="machine-supply"> - <title>Supplies</title> - <para> - Regulator supplies are specified using <link - linkend='API-struct-regulator-consumer-supply'>struct - regulator_consumer_supply</link>. This is done at - <link linkend='driver'>driver registration - time</link> as part of the machine constraints. - </para> - </sect1> - - <sect1 id="machine-constraint"> - <title>Constraints</title> - <para> - As well as defining the connections the machine interface - also provides constraints defining the operations that - clients are allowed to perform and the parameters that may be - set. This is required since generally regulator devices will - offer more flexibility than it is safe to use on a given - system, for example supporting higher supply voltages than the - consumers are rated for. - </para> - <para> - This is done at <link linkend='driver'>driver - registration time</link> by providing a <link - linkend='API-struct-regulation-constraints'>struct - regulation_constraints</link>. - </para> - <para> - The constraints may also specify an initial configuration for the - regulator in the constraints, which is particularly useful for - use with static consumers. - </para> - </sect1> - </chapter> - - <chapter id="api"> - <title>API reference</title> - <para> - Due to limitations of the kernel documentation framework and the - existing layout of the source code the entire regulator API is - documented here. - </para> -!Iinclude/linux/regulator/consumer.h -!Iinclude/linux/regulator/machine.h -!Iinclude/linux/regulator/driver.h -!Edrivers/regulator/core.c - </chapter> -</book> diff --git a/Documentation/DocBook/s390-drivers.tmpl b/Documentation/DocBook/s390-drivers.tmpl deleted file mode 100644 index 95bfc12e5439..000000000000 --- a/Documentation/DocBook/s390-drivers.tmpl +++ /dev/null @@ -1,161 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="s390drivers"> - <bookinfo> - <title>Writing s390 channel device drivers</title> - - <authorgroup> - <author> - <firstname>Cornelia</firstname> - <surname>Huck</surname> - <affiliation> - <address> - <email>cornelia.huck@de.ibm.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2007</year> - <holder>IBM Corp.</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="intro"> - <title>Introduction</title> - <para> - This document describes the interfaces available for device drivers that - drive s390 based channel attached I/O devices. This includes interfaces for - interaction with the hardware and interfaces for interacting with the - common driver core. Those interfaces are provided by the s390 common I/O - layer. - </para> - <para> - The document assumes a familarity with the technical terms associated - with the s390 channel I/O architecture. For a description of this - architecture, please refer to the "z/Architecture: Principles of - Operation", IBM publication no. SA22-7832. - </para> - <para> - While most I/O devices on a s390 system are typically driven through the - channel I/O mechanism described here, there are various other methods - (like the diag interface). These are out of the scope of this document. - </para> - <para> - Some additional information can also be found in the kernel source - under Documentation/s390/driver-model.txt. - </para> - </chapter> - <chapter id="ccw"> - <title>The ccw bus</title> - <para> - The ccw bus typically contains the majority of devices available to - a s390 system. Named after the channel command word (ccw), the basic - command structure used to address its devices, the ccw bus contains - so-called channel attached devices. They are addressed via I/O - subchannels, visible on the css bus. A device driver for - channel-attached devices, however, will never interact with the - subchannel directly, but only via the I/O device on the ccw bus, - the ccw device. - </para> - <sect1 id="channelIO"> - <title>I/O functions for channel-attached devices</title> - <para> - Some hardware structures have been translated into C structures for use - by the common I/O layer and device drivers. For more information on - the hardware structures represented here, please consult the Principles - of Operation. - </para> -!Iarch/s390/include/asm/cio.h - </sect1> - <sect1 id="ccwdev"> - <title>ccw devices</title> - <para> - Devices that want to initiate channel I/O need to attach to the ccw bus. - Interaction with the driver core is done via the common I/O layer, which - provides the abstractions of ccw devices and ccw device drivers. - </para> - <para> - The functions that initiate or terminate channel I/O all act upon a - ccw device structure. Device drivers must not bypass those functions - or strange side effects may happen. - </para> -!Iarch/s390/include/asm/ccwdev.h -!Edrivers/s390/cio/device.c -!Edrivers/s390/cio/device_ops.c - </sect1> - <sect1 id="cmf"> - <title>The channel-measurement facility</title> - <para> - The channel-measurement facility provides a means to collect - measurement data which is made available by the channel subsystem - for each channel attached device. - </para> -!Iarch/s390/include/asm/cmb.h -!Edrivers/s390/cio/cmf.c - </sect1> - </chapter> - - <chapter id="ccwgroup"> - <title>The ccwgroup bus</title> - <para> - The ccwgroup bus only contains artificial devices, created by the user. - Many networking devices (e.g. qeth) are in fact composed of several - ccw devices (like read, write and data channel for qeth). The - ccwgroup bus provides a mechanism to create a meta-device which - contains those ccw devices as slave devices and can be associated - with the netdevice. - </para> - <sect1 id="ccwgroupdevices"> - <title>ccw group devices</title> -!Iarch/s390/include/asm/ccwgroup.h -!Edrivers/s390/cio/ccwgroup.c - </sect1> - </chapter> - - <chapter id="genericinterfaces"> - <title>Generic interfaces</title> - <para> - Some interfaces are available to other drivers that do not necessarily - have anything to do with the busses described above, but still are - indirectly using basic infrastructure in the common I/O layer. - One example is the support for adapter interrupts. - </para> -!Edrivers/s390/cio/airq.c - </chapter> - -</book> diff --git a/Documentation/DocBook/scsi.tmpl b/Documentation/DocBook/scsi.tmpl deleted file mode 100644 index 4b9b9b286cea..000000000000 --- a/Documentation/DocBook/scsi.tmpl +++ /dev/null @@ -1,409 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="scsimid"> - <bookinfo> - <title>SCSI Interfaces Guide</title> - - <authorgroup> - <author> - <firstname>James</firstname> - <surname>Bottomley</surname> - <affiliation> - <address> - <email>James.Bottomley@hansenpartnership.com</email> - </address> - </affiliation> - </author> - - <author> - <firstname>Rob</firstname> - <surname>Landley</surname> - <affiliation> - <address> - <email>rob@landley.net</email> - </address> - </affiliation> - </author> - - </authorgroup> - - <copyright> - <year>2007</year> - <holder>Linux Foundation</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License version 2. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - - <toc></toc> - - <chapter id="intro"> - <title>Introduction</title> - <sect1 id="protocol_vs_bus"> - <title>Protocol vs bus</title> - <para> - Once upon a time, the Small Computer Systems Interface defined both - a parallel I/O bus and a data protocol to connect a wide variety of - peripherals (disk drives, tape drives, modems, printers, scanners, - optical drives, test equipment, and medical devices) to a host - computer. - </para> - <para> - Although the old parallel (fast/wide/ultra) SCSI bus has largely - fallen out of use, the SCSI command set is more widely used than ever - to communicate with devices over a number of different busses. - </para> - <para> - The <ulink url='http://www.t10.org/scsi-3.htm'>SCSI protocol</ulink> - is a big-endian peer-to-peer packet based protocol. SCSI commands - are 6, 10, 12, or 16 bytes long, often followed by an associated data - payload. - </para> - <para> - SCSI commands can be transported over just about any kind of bus, and - are the default protocol for storage devices attached to USB, SATA, - SAS, Fibre Channel, FireWire, and ATAPI devices. SCSI packets are - also commonly exchanged over Infiniband, - <ulink url='http://i2o.shadowconnect.com/faq.php'>I20</ulink>, TCP/IP - (<ulink url='https://en.wikipedia.org/wiki/ISCSI'>iSCSI</ulink>), even - <ulink url='http://cyberelk.net/tim/parport/parscsi.html'>Parallel - ports</ulink>. - </para> - </sect1> - <sect1 id="subsystem_design"> - <title>Design of the Linux SCSI subsystem</title> - <para> - The SCSI subsystem uses a three layer design, with upper, mid, and low - layers. Every operation involving the SCSI subsystem (such as reading - a sector from a disk) uses one driver at each of the 3 levels: one - upper layer driver, one lower layer driver, and the SCSI midlayer. - </para> - <para> - The SCSI upper layer provides the interface between userspace and the - kernel, in the form of block and char device nodes for I/O and - ioctl(). The SCSI lower layer contains drivers for specific hardware - devices. - </para> - <para> - In between is the SCSI mid-layer, analogous to a network routing - layer such as the IPv4 stack. The SCSI mid-layer routes a packet - based data protocol between the upper layer's /dev nodes and the - corresponding devices in the lower layer. It manages command queues, - provides error handling and power management functions, and responds - to ioctl() requests. - </para> - </sect1> - </chapter> - - <chapter id="upper_layer"> - <title>SCSI upper layer</title> - <para> - The upper layer supports the user-kernel interface by providing - device nodes. - </para> - <sect1 id="sd"> - <title>sd (SCSI Disk)</title> - <para>sd (sd_mod.o)</para> -<!-- !Idrivers/scsi/sd.c --> - </sect1> - <sect1 id="sr"> - <title>sr (SCSI CD-ROM)</title> - <para>sr (sr_mod.o)</para> - </sect1> - <sect1 id="st"> - <title>st (SCSI Tape)</title> - <para>st (st.o)</para> - </sect1> - <sect1 id="sg"> - <title>sg (SCSI Generic)</title> - <para>sg (sg.o)</para> - </sect1> - <sect1 id="ch"> - <title>ch (SCSI Media Changer)</title> - <para>ch (ch.c)</para> - </sect1> - </chapter> - - <chapter id="mid_layer"> - <title>SCSI mid layer</title> - - <sect1 id="midlayer_implementation"> - <title>SCSI midlayer implementation</title> - <sect2 id="scsi_device.h"> - <title>include/scsi/scsi_device.h</title> - <para> - </para> -!Iinclude/scsi/scsi_device.h - </sect2> - - <sect2 id="scsi.c"> - <title>drivers/scsi/scsi.c</title> - <para>Main file for the SCSI midlayer.</para> -!Edrivers/scsi/scsi.c - </sect2> - <sect2 id="scsicam.c"> - <title>drivers/scsi/scsicam.c</title> - <para> - <ulink url='http://www.t10.org/ftp/t10/drafts/cam/cam-r12b.pdf'>SCSI - Common Access Method</ulink> support functions, for use with - HDIO_GETGEO, etc. - </para> -!Edrivers/scsi/scsicam.c - </sect2> - <sect2 id="scsi_error.c"> - <title>drivers/scsi/scsi_error.c</title> - <para>Common SCSI error/timeout handling routines.</para> -!Edrivers/scsi/scsi_error.c - </sect2> - <sect2 id="scsi_devinfo.c"> - <title>drivers/scsi/scsi_devinfo.c</title> - <para> - Manage scsi_dev_info_list, which tracks blacklisted and whitelisted - devices. - </para> -!Idrivers/scsi/scsi_devinfo.c - </sect2> - <sect2 id="scsi_ioctl.c"> - <title>drivers/scsi/scsi_ioctl.c</title> - <para> - Handle ioctl() calls for SCSI devices. - </para> -!Edrivers/scsi/scsi_ioctl.c - </sect2> - <sect2 id="scsi_lib.c"> - <title>drivers/scsi/scsi_lib.c</title> - <para> - SCSI queuing library. - </para> -!Edrivers/scsi/scsi_lib.c - </sect2> - <sect2 id="scsi_lib_dma.c"> - <title>drivers/scsi/scsi_lib_dma.c</title> - <para> - SCSI library functions depending on DMA - (map and unmap scatter-gather lists). - </para> -!Edrivers/scsi/scsi_lib_dma.c - </sect2> - <sect2 id="scsi_module.c"> - <title>drivers/scsi/scsi_module.c</title> - <para> - The file drivers/scsi/scsi_module.c contains legacy support for - old-style host templates. It should never be used by any new driver. - </para> - </sect2> - <sect2 id="scsi_proc.c"> - <title>drivers/scsi/scsi_proc.c</title> - <para> - The functions in this file provide an interface between - the PROC file system and the SCSI device drivers - It is mainly used for debugging, statistics and to pass - information directly to the lowlevel driver. - - I.E. plumbing to manage /proc/scsi/* - </para> -!Idrivers/scsi/scsi_proc.c - </sect2> - <sect2 id="scsi_netlink.c"> - <title>drivers/scsi/scsi_netlink.c</title> - <para> - Infrastructure to provide async events from transports to userspace - via netlink, using a single NETLINK_SCSITRANSPORT protocol for all - transports. - - See <ulink url='http://marc.info/?l=linux-scsi&m=115507374832500&w=2'>the - original patch submission</ulink> for more details. - </para> -!Idrivers/scsi/scsi_netlink.c - </sect2> - <sect2 id="scsi_scan.c"> - <title>drivers/scsi/scsi_scan.c</title> - <para> - Scan a host to determine which (if any) devices are attached. - - The general scanning/probing algorithm is as follows, exceptions are - made to it depending on device specific flags, compilation options, - and global variable (boot or module load time) settings. - - A specific LUN is scanned via an INQUIRY command; if the LUN has a - device attached, a scsi_device is allocated and setup for it. - - For every id of every channel on the given host, start by scanning - LUN 0. Skip hosts that don't respond at all to a scan of LUN 0. - Otherwise, if LUN 0 has a device attached, allocate and setup a - scsi_device for it. If target is SCSI-3 or up, issue a REPORT LUN, - and scan all of the LUNs returned by the REPORT LUN; else, - sequentially scan LUNs up until some maximum is reached, or a LUN is - seen that cannot have a device attached to it. - </para> -!Idrivers/scsi/scsi_scan.c - </sect2> - <sect2 id="scsi_sysctl.c"> - <title>drivers/scsi/scsi_sysctl.c</title> - <para> - Set up the sysctl entry: "/dev/scsi/logging_level" - (DEV_SCSI_LOGGING_LEVEL) which sets/returns scsi_logging_level. - </para> - </sect2> - <sect2 id="scsi_sysfs.c"> - <title>drivers/scsi/scsi_sysfs.c</title> - <para> - SCSI sysfs interface routines. - </para> -!Edrivers/scsi/scsi_sysfs.c - </sect2> - <sect2 id="hosts.c"> - <title>drivers/scsi/hosts.c</title> - <para> - mid to lowlevel SCSI driver interface - </para> -!Edrivers/scsi/hosts.c - </sect2> - <sect2 id="constants.c"> - <title>drivers/scsi/constants.c</title> - <para> - mid to lowlevel SCSI driver interface - </para> -!Edrivers/scsi/constants.c - </sect2> - </sect1> - - <sect1 id="Transport_classes"> - <title>Transport classes</title> - <para> - Transport classes are service libraries for drivers in the SCSI - lower layer, which expose transport attributes in sysfs. - </para> - <sect2 id="Fibre_Channel_transport"> - <title>Fibre Channel transport</title> - <para> - The file drivers/scsi/scsi_transport_fc.c defines transport attributes - for Fibre Channel. - </para> -!Edrivers/scsi/scsi_transport_fc.c - </sect2> - <sect2 id="iSCSI_transport"> - <title>iSCSI transport class</title> - <para> - The file drivers/scsi/scsi_transport_iscsi.c defines transport - attributes for the iSCSI class, which sends SCSI packets over TCP/IP - connections. - </para> -!Edrivers/scsi/scsi_transport_iscsi.c - </sect2> - <sect2 id="SAS_transport"> - <title>Serial Attached SCSI (SAS) transport class</title> - <para> - The file drivers/scsi/scsi_transport_sas.c defines transport - attributes for Serial Attached SCSI, a variant of SATA aimed at - large high-end systems. - </para> - <para> - The SAS transport class contains common code to deal with SAS HBAs, - an aproximated representation of SAS topologies in the driver model, - and various sysfs attributes to expose these topologies and management - interfaces to userspace. - </para> - <para> - In addition to the basic SCSI core objects this transport class - introduces two additional intermediate objects: The SAS PHY - as represented by struct sas_phy defines an "outgoing" PHY on - a SAS HBA or Expander, and the SAS remote PHY represented by - struct sas_rphy defines an "incoming" PHY on a SAS Expander or - end device. Note that this is purely a software concept, the - underlying hardware for a PHY and a remote PHY is the exactly - the same. - </para> - <para> - There is no concept of a SAS port in this code, users can see - what PHYs form a wide port based on the port_identifier attribute, - which is the same for all PHYs in a port. - </para> -!Edrivers/scsi/scsi_transport_sas.c - </sect2> - <sect2 id="SATA_transport"> - <title>SATA transport class</title> - <para> - The SATA transport is handled by libata, which has its own book of - documentation in this directory. - </para> - </sect2> - <sect2 id="SPI_transport"> - <title>Parallel SCSI (SPI) transport class</title> - <para> - The file drivers/scsi/scsi_transport_spi.c defines transport - attributes for traditional (fast/wide/ultra) SCSI busses. - </para> -!Edrivers/scsi/scsi_transport_spi.c - </sect2> - <sect2 id="SRP_transport"> - <title>SCSI RDMA (SRP) transport class</title> - <para> - The file drivers/scsi/scsi_transport_srp.c defines transport - attributes for SCSI over Remote Direct Memory Access. - </para> -!Edrivers/scsi/scsi_transport_srp.c - </sect2> - </sect1> - - </chapter> - - <chapter id="lower_layer"> - <title>SCSI lower layer</title> - <sect1 id="hba_drivers"> - <title>Host Bus Adapter transport types</title> - <para> - Many modern device controllers use the SCSI command set as a protocol to - communicate with their devices through many different types of physical - connections. - </para> - <para> - In SCSI language a bus capable of carrying SCSI commands is - called a "transport", and a controller connecting to such a bus is - called a "host bus adapter" (HBA). - </para> - <sect2 id="scsi_debug.c"> - <title>Debug transport</title> - <para> - The file drivers/scsi/scsi_debug.c simulates a host adapter with a - variable number of disks (or disk like devices) attached, sharing a - common amount of RAM. Does a lot of checking to make sure that we are - not getting blocks mixed up, and panics the kernel if anything out of - the ordinary is seen. - </para> - <para> - To be more realistic, the simulated devices have the transport - attributes of SAS disks. - </para> - <para> - For documentation see - <ulink url='http://sg.danny.cz/sg/sdebug26.html'>http://sg.danny.cz/sg/sdebug26.html</ulink> - </para> -<!-- !Edrivers/scsi/scsi_debug.c --> - </sect2> - <sect2 id="todo"> - <title>todo</title> - <para>Parallel (fast/wide/ultra) SCSI, USB, SATA, - SAS, Fibre Channel, FireWire, ATAPI devices, Infiniband, - I20, iSCSI, Parallel ports, netlink... - </para> - </sect2> - </sect1> - </chapter> -</book> diff --git a/Documentation/DocBook/sh.tmpl b/Documentation/DocBook/sh.tmpl deleted file mode 100644 index 4a38f604fa66..000000000000 --- a/Documentation/DocBook/sh.tmpl +++ /dev/null @@ -1,105 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="sh-drivers"> - <bookinfo> - <title>SuperH Interfaces Guide</title> - - <authorgroup> - <author> - <firstname>Paul</firstname> - <surname>Mundt</surname> - <affiliation> - <address> - <email>lethal@linux-sh.org</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2008-2010</year> - <holder>Paul Mundt</holder> - </copyright> - <copyright> - <year>2008-2010</year> - <holder>Renesas Technology Corp.</holder> - </copyright> - <copyright> - <year>2010</year> - <holder>Renesas Electronics Corp.</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License version 2 as published by the Free Software Foundation. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="mm"> - <title>Memory Management</title> - <sect1 id="sh4"> - <title>SH-4</title> - <sect2 id="sq"> - <title>Store Queue API</title> -!Earch/sh/kernel/cpu/sh4/sq.c - </sect2> - </sect1> - <sect1 id="sh5"> - <title>SH-5</title> - <sect2 id="tlb"> - <title>TLB Interfaces</title> -!Iarch/sh/mm/tlb-sh5.c -!Iarch/sh/include/asm/tlb_64.h - </sect2> - </sect1> - </chapter> - <chapter id="mach"> - <title>Machine Specific Interfaces</title> - <sect1 id="dreamcast"> - <title>mach-dreamcast</title> -!Iarch/sh/boards/mach-dreamcast/rtc.c - </sect1> - <sect1 id="x3proto"> - <title>mach-x3proto</title> -!Earch/sh/boards/mach-x3proto/ilsel.c - </sect1> - </chapter> - <chapter id="busses"> - <title>Busses</title> - <sect1 id="superhyway"> - <title>SuperHyway</title> -!Edrivers/sh/superhyway/superhyway.c - </sect1> - - <sect1 id="maple"> - <title>Maple</title> -!Edrivers/sh/maple/maple.c - </sect1> - </chapter> -</book> diff --git a/Documentation/DocBook/stylesheet.xsl b/Documentation/DocBook/stylesheet.xsl deleted file mode 100644 index 3bf4ecf3d760..000000000000 --- a/Documentation/DocBook/stylesheet.xsl +++ /dev/null @@ -1,11 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<stylesheet xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0"> -<param name="chunk.quietly">1</param> -<param name="funcsynopsis.style">ansi</param> -<param name="funcsynopsis.tabular.threshold">80</param> -<param name="callout.graphics">0</param> -<!-- <param name="paper.type">A4</param> --> -<param name="generate.consistent.ids">1</param> -<param name="generate.section.toc.level">2</param> -<param name="use.id.as.filename">1</param> -</stylesheet> diff --git a/Documentation/DocBook/tracepoint.tmpl b/Documentation/DocBook/tracepoint.tmpl deleted file mode 100644 index b57a9ede3224..000000000000 --- a/Documentation/DocBook/tracepoint.tmpl +++ /dev/null @@ -1,112 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="Tracepoints"> - <bookinfo> - <title>The Linux Kernel Tracepoint API</title> - - <authorgroup> - <author> - <firstname>Jason</firstname> - <surname>Baron</surname> - <affiliation> - <address> - <email>jbaron@redhat.com</email> - </address> - </affiliation> - </author> - <author> - <firstname>William</firstname> - <surname>Cohen</surname> - <affiliation> - <address> - <email>wcohen@redhat.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - - <toc></toc> - <chapter id="intro"> - <title>Introduction</title> - <para> - Tracepoints are static probe points that are located in strategic points - throughout the kernel. 'Probes' register/unregister with tracepoints - via a callback mechanism. The 'probes' are strictly typed functions that - are passed a unique set of parameters defined by each tracepoint. - </para> - - <para> - From this simple callback mechanism, 'probes' can be used to profile, debug, - and understand kernel behavior. There are a number of tools that provide a - framework for using 'probes'. These tools include Systemtap, ftrace, and - LTTng. - </para> - - <para> - Tracepoints are defined in a number of header files via various macros. Thus, - the purpose of this document is to provide a clear accounting of the available - tracepoints. The intention is to understand not only what tracepoints are - available but also to understand where future tracepoints might be added. - </para> - - <para> - The API presented has functions of the form: - <function>trace_tracepointname(function parameters)</function>. These are the - tracepoints callbacks that are found throughout the code. Registering and - unregistering probes with these callback sites is covered in the - <filename>Documentation/trace/*</filename> directory. - </para> - </chapter> - - <chapter id="irq"> - <title>IRQ</title> -!Iinclude/trace/events/irq.h - </chapter> - - <chapter id="signal"> - <title>SIGNAL</title> -!Iinclude/trace/events/signal.h - </chapter> - - <chapter id="block"> - <title>Block IO</title> -!Iinclude/trace/events/block.h - </chapter> - - <chapter id="workqueue"> - <title>Workqueue</title> -!Iinclude/trace/events/workqueue.h - </chapter> -</book> diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl deleted file mode 100644 index cd0e452dfed5..000000000000 --- a/Documentation/DocBook/uio-howto.tmpl +++ /dev/null @@ -1,1050 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" []> - -<book id="index"> -<bookinfo> -<title>The Userspace I/O HOWTO</title> - -<author> - <firstname>Hans-Jürgen</firstname> - <surname>Koch</surname> - <authorblurb><para>Linux developer, Linutronix</para></authorblurb> - <affiliation> - <orgname> - <ulink url="http://www.linutronix.de">Linutronix</ulink> - </orgname> - - <address> - <email>hjk@hansjkoch.de</email> - </address> - </affiliation> -</author> - -<copyright> - <year>2006-2008</year> - <holder>Hans-Jürgen Koch.</holder> -</copyright> -<copyright> - <year>2009</year> - <holder>Red Hat Inc, Michael S. Tsirkin (mst@redhat.com)</holder> -</copyright> - -<legalnotice> -<para> -This documentation is Free Software licensed under the terms of the -GPL version 2. -</para> -</legalnotice> - -<pubdate>2006-12-11</pubdate> - -<abstract> - <para>This HOWTO describes concept and usage of Linux kernel's - Userspace I/O system.</para> -</abstract> - -<revhistory> - <revision> - <revnumber>0.9</revnumber> - <date>2009-07-16</date> - <authorinitials>mst</authorinitials> - <revremark>Added generic pci driver - </revremark> - </revision> - <revision> - <revnumber>0.8</revnumber> - <date>2008-12-24</date> - <authorinitials>hjk</authorinitials> - <revremark>Added name attributes in mem and portio sysfs directories. - </revremark> - </revision> - <revision> - <revnumber>0.7</revnumber> - <date>2008-12-23</date> - <authorinitials>hjk</authorinitials> - <revremark>Added generic platform drivers and offset attribute.</revremark> - </revision> - <revision> - <revnumber>0.6</revnumber> - <date>2008-12-05</date> - <authorinitials>hjk</authorinitials> - <revremark>Added description of portio sysfs attributes.</revremark> - </revision> - <revision> - <revnumber>0.5</revnumber> - <date>2008-05-22</date> - <authorinitials>hjk</authorinitials> - <revremark>Added description of write() function.</revremark> - </revision> - <revision> - <revnumber>0.4</revnumber> - <date>2007-11-26</date> - <authorinitials>hjk</authorinitials> - <revremark>Removed section about uio_dummy.</revremark> - </revision> - <revision> - <revnumber>0.3</revnumber> - <date>2007-04-29</date> - <authorinitials>hjk</authorinitials> - <revremark>Added section about userspace drivers.</revremark> - </revision> - <revision> - <revnumber>0.2</revnumber> - <date>2007-02-13</date> - <authorinitials>hjk</authorinitials> - <revremark>Update after multiple mappings were added.</revremark> - </revision> - <revision> - <revnumber>0.1</revnumber> - <date>2006-12-11</date> - <authorinitials>hjk</authorinitials> - <revremark>First draft.</revremark> - </revision> -</revhistory> -</bookinfo> - -<chapter id="aboutthisdoc"> -<?dbhtml filename="aboutthis.html"?> -<title>About this document</title> - -<sect1 id="translations"> -<?dbhtml filename="translations.html"?> -<title>Translations</title> - -<para>If you know of any translations for this document, or you are -interested in translating it, please email me -<email>hjk@hansjkoch.de</email>. -</para> -</sect1> - -<sect1 id="preface"> -<title>Preface</title> - <para> - For many types of devices, creating a Linux kernel driver is - overkill. All that is really needed is some way to handle an - interrupt and provide access to the memory space of the - device. The logic of controlling the device does not - necessarily have to be within the kernel, as the device does - not need to take advantage of any of other resources that the - kernel provides. One such common class of devices that are - like this are for industrial I/O cards. - </para> - <para> - To address this situation, the userspace I/O system (UIO) was - designed. For typical industrial I/O cards, only a very small - kernel module is needed. The main part of the driver will run in - user space. This simplifies development and reduces the risk of - serious bugs within a kernel module. - </para> - <para> - Please note that UIO is not an universal driver interface. Devices - that are already handled well by other kernel subsystems (like - networking or serial or USB) are no candidates for an UIO driver. - Hardware that is ideally suited for an UIO driver fulfills all of - the following: - </para> -<itemizedlist> -<listitem> - <para>The device has memory that can be mapped. The device can be - controlled completely by writing to this memory.</para> -</listitem> -<listitem> - <para>The device usually generates interrupts.</para> -</listitem> -<listitem> - <para>The device does not fit into one of the standard kernel - subsystems.</para> -</listitem> -</itemizedlist> -</sect1> - -<sect1 id="thanks"> -<title>Acknowledgments</title> - <para>I'd like to thank Thomas Gleixner and Benedikt Spranger of - Linutronix, who have not only written most of the UIO code, but also - helped greatly writing this HOWTO by giving me all kinds of background - information.</para> -</sect1> - -<sect1 id="feedback"> -<title>Feedback</title> - <para>Find something wrong with this document? (Or perhaps something - right?) I would love to hear from you. Please email me at - <email>hjk@hansjkoch.de</email>.</para> -</sect1> -</chapter> - -<chapter id="about"> -<?dbhtml filename="about.html"?> -<title>About UIO</title> - -<para>If you use UIO for your card's driver, here's what you get:</para> - -<itemizedlist> -<listitem> - <para>only one small kernel module to write and maintain.</para> -</listitem> -<listitem> - <para>develop the main part of your driver in user space, - with all the tools and libraries you're used to.</para> -</listitem> -<listitem> - <para>bugs in your driver won't crash the kernel.</para> -</listitem> -<listitem> - <para>updates of your driver can take place without recompiling - the kernel.</para> -</listitem> -</itemizedlist> - -<sect1 id="how_uio_works"> -<title>How UIO works</title> - <para> - Each UIO device is accessed through a device file and several - sysfs attribute files. The device file will be called - <filename>/dev/uio0</filename> for the first device, and - <filename>/dev/uio1</filename>, <filename>/dev/uio2</filename> - and so on for subsequent devices. - </para> - - <para><filename>/dev/uioX</filename> is used to access the - address space of the card. Just use - <function>mmap()</function> to access registers or RAM - locations of your card. - </para> - - <para> - Interrupts are handled by reading from - <filename>/dev/uioX</filename>. A blocking - <function>read()</function> from - <filename>/dev/uioX</filename> will return as soon as an - interrupt occurs. You can also use - <function>select()</function> on - <filename>/dev/uioX</filename> to wait for an interrupt. The - integer value read from <filename>/dev/uioX</filename> - represents the total interrupt count. You can use this number - to figure out if you missed some interrupts. - </para> - <para> - For some hardware that has more than one interrupt source internally, - but not separate IRQ mask and status registers, there might be - situations where userspace cannot determine what the interrupt source - was if the kernel handler disables them by writing to the chip's IRQ - register. In such a case, the kernel has to disable the IRQ completely - to leave the chip's register untouched. Now the userspace part can - determine the cause of the interrupt, but it cannot re-enable - interrupts. Another cornercase is chips where re-enabling interrupts - is a read-modify-write operation to a combined IRQ status/acknowledge - register. This would be racy if a new interrupt occurred - simultaneously. - </para> - <para> - To address these problems, UIO also implements a write() function. It - is normally not used and can be ignored for hardware that has only a - single interrupt source or has separate IRQ mask and status registers. - If you need it, however, a write to <filename>/dev/uioX</filename> - will call the <function>irqcontrol()</function> function implemented - by the driver. You have to write a 32-bit value that is usually either - 0 or 1 to disable or enable interrupts. If a driver does not implement - <function>irqcontrol()</function>, <function>write()</function> will - return with <varname>-ENOSYS</varname>. - </para> - - <para> - To handle interrupts properly, your custom kernel module can - provide its own interrupt handler. It will automatically be - called by the built-in handler. - </para> - - <para> - For cards that don't generate interrupts but need to be - polled, there is the possibility to set up a timer that - triggers the interrupt handler at configurable time intervals. - This interrupt simulation is done by calling - <function>uio_event_notify()</function> - from the timer's event handler. - </para> - - <para> - Each driver provides attributes that are used to read or write - variables. These attributes are accessible through sysfs - files. A custom kernel driver module can add its own - attributes to the device owned by the uio driver, but not added - to the UIO device itself at this time. This might change in the - future if it would be found to be useful. - </para> - - <para> - The following standard attributes are provided by the UIO - framework: - </para> -<itemizedlist> -<listitem> - <para> - <filename>name</filename>: The name of your device. It is - recommended to use the name of your kernel module for this. - </para> -</listitem> -<listitem> - <para> - <filename>version</filename>: A version string defined by your - driver. This allows the user space part of your driver to deal - with different versions of the kernel module. - </para> -</listitem> -<listitem> - <para> - <filename>event</filename>: The total number of interrupts - handled by the driver since the last time the device node was - read. - </para> -</listitem> -</itemizedlist> -<para> - These attributes appear under the - <filename>/sys/class/uio/uioX</filename> directory. Please - note that this directory might be a symlink, and not a real - directory. Any userspace code that accesses it must be able - to handle this. -</para> -<para> - Each UIO device can make one or more memory regions available for - memory mapping. This is necessary because some industrial I/O cards - require access to more than one PCI memory region in a driver. -</para> -<para> - Each mapping has its own directory in sysfs, the first mapping - appears as <filename>/sys/class/uio/uioX/maps/map0/</filename>. - Subsequent mappings create directories <filename>map1/</filename>, - <filename>map2/</filename>, and so on. These directories will only - appear if the size of the mapping is not 0. -</para> -<para> - Each <filename>mapX/</filename> directory contains four read-only files - that show attributes of the memory: -</para> -<itemizedlist> -<listitem> - <para> - <filename>name</filename>: A string identifier for this mapping. This - is optional, the string can be empty. Drivers can set this to make it - easier for userspace to find the correct mapping. - </para> -</listitem> -<listitem> - <para> - <filename>addr</filename>: The address of memory that can be mapped. - </para> -</listitem> -<listitem> - <para> - <filename>size</filename>: The size, in bytes, of the memory - pointed to by addr. - </para> -</listitem> -<listitem> - <para> - <filename>offset</filename>: The offset, in bytes, that has to be - added to the pointer returned by <function>mmap()</function> to get - to the actual device memory. This is important if the device's memory - is not page aligned. Remember that pointers returned by - <function>mmap()</function> are always page aligned, so it is good - style to always add this offset. - </para> -</listitem> -</itemizedlist> - -<para> - From userspace, the different mappings are distinguished by adjusting - the <varname>offset</varname> parameter of the - <function>mmap()</function> call. To map the memory of mapping N, you - have to use N times the page size as your offset: -</para> -<programlisting format="linespecific"> -offset = N * getpagesize(); -</programlisting> - -<para> - Sometimes there is hardware with memory-like regions that can not be - mapped with the technique described here, but there are still ways to - access them from userspace. The most common example are x86 ioports. - On x86 systems, userspace can access these ioports using - <function>ioperm()</function>, <function>iopl()</function>, - <function>inb()</function>, <function>outb()</function>, and similar - functions. -</para> -<para> - Since these ioport regions can not be mapped, they will not appear under - <filename>/sys/class/uio/uioX/maps/</filename> like the normal memory - described above. Without information about the port regions a hardware - has to offer, it becomes difficult for the userspace part of the - driver to find out which ports belong to which UIO device. -</para> -<para> - To address this situation, the new directory - <filename>/sys/class/uio/uioX/portio/</filename> was added. It only - exists if the driver wants to pass information about one or more port - regions to userspace. If that is the case, subdirectories named - <filename>port0</filename>, <filename>port1</filename>, and so on, - will appear underneath - <filename>/sys/class/uio/uioX/portio/</filename>. -</para> -<para> - Each <filename>portX/</filename> directory contains four read-only - files that show name, start, size, and type of the port region: -</para> -<itemizedlist> -<listitem> - <para> - <filename>name</filename>: A string identifier for this port region. - The string is optional and can be empty. Drivers can set it to make it - easier for userspace to find a certain port region. - </para> -</listitem> -<listitem> - <para> - <filename>start</filename>: The first port of this region. - </para> -</listitem> -<listitem> - <para> - <filename>size</filename>: The number of ports in this region. - </para> -</listitem> -<listitem> - <para> - <filename>porttype</filename>: A string describing the type of port. - </para> -</listitem> -</itemizedlist> - - -</sect1> -</chapter> - -<chapter id="custom_kernel_module" xreflabel="Writing your own kernel module"> -<?dbhtml filename="custom_kernel_module.html"?> -<title>Writing your own kernel module</title> - <para> - Please have a look at <filename>uio_cif.c</filename> as an - example. The following paragraphs explain the different - sections of this file. - </para> - -<sect1 id="uio_info"> -<title>struct uio_info</title> - <para> - This structure tells the framework the details of your driver, - Some of the members are required, others are optional. - </para> - -<itemizedlist> -<listitem><para> -<varname>const char *name</varname>: Required. The name of your driver as -it will appear in sysfs. I recommend using the name of your module for this. -</para></listitem> - -<listitem><para> -<varname>const char *version</varname>: Required. This string appears in -<filename>/sys/class/uio/uioX/version</filename>. -</para></listitem> - -<listitem><para> -<varname>struct uio_mem mem[ MAX_UIO_MAPS ]</varname>: Required if you -have memory that can be mapped with <function>mmap()</function>. For each -mapping you need to fill one of the <varname>uio_mem</varname> structures. -See the description below for details. -</para></listitem> - -<listitem><para> -<varname>struct uio_port port[ MAX_UIO_PORTS_REGIONS ]</varname>: Required -if you want to pass information about ioports to userspace. For each port -region you need to fill one of the <varname>uio_port</varname> structures. -See the description below for details. -</para></listitem> - -<listitem><para> -<varname>long irq</varname>: Required. If your hardware generates an -interrupt, it's your modules task to determine the irq number during -initialization. If you don't have a hardware generated interrupt but -want to trigger the interrupt handler in some other way, set -<varname>irq</varname> to <varname>UIO_IRQ_CUSTOM</varname>. -If you had no interrupt at all, you could set -<varname>irq</varname> to <varname>UIO_IRQ_NONE</varname>, though this -rarely makes sense. -</para></listitem> - -<listitem><para> -<varname>unsigned long irq_flags</varname>: Required if you've set -<varname>irq</varname> to a hardware interrupt number. The flags given -here will be used in the call to <function>request_irq()</function>. -</para></listitem> - -<listitem><para> -<varname>int (*mmap)(struct uio_info *info, struct vm_area_struct -*vma)</varname>: Optional. If you need a special -<function>mmap()</function> function, you can set it here. If this -pointer is not NULL, your <function>mmap()</function> will be called -instead of the built-in one. -</para></listitem> - -<listitem><para> -<varname>int (*open)(struct uio_info *info, struct inode *inode) -</varname>: Optional. You might want to have your own -<function>open()</function>, e.g. to enable interrupts only when your -device is actually used. -</para></listitem> - -<listitem><para> -<varname>int (*release)(struct uio_info *info, struct inode *inode) -</varname>: Optional. If you define your own -<function>open()</function>, you will probably also want a custom -<function>release()</function> function. -</para></listitem> - -<listitem><para> -<varname>int (*irqcontrol)(struct uio_info *info, s32 irq_on) -</varname>: Optional. If you need to be able to enable or disable -interrupts from userspace by writing to <filename>/dev/uioX</filename>, -you can implement this function. The parameter <varname>irq_on</varname> -will be 0 to disable interrupts and 1 to enable them. -</para></listitem> -</itemizedlist> - -<para> -Usually, your device will have one or more memory regions that can be mapped -to user space. For each region, you have to set up a -<varname>struct uio_mem</varname> in the <varname>mem[]</varname> array. -Here's a description of the fields of <varname>struct uio_mem</varname>: -</para> - -<itemizedlist> -<listitem><para> -<varname>const char *name</varname>: Optional. Set this to help identify -the memory region, it will show up in the corresponding sysfs node. -</para></listitem> - -<listitem><para> -<varname>int memtype</varname>: Required if the mapping is used. Set this to -<varname>UIO_MEM_PHYS</varname> if you you have physical memory on your -card to be mapped. Use <varname>UIO_MEM_LOGICAL</varname> for logical -memory (e.g. allocated with <function>kmalloc()</function>). There's also -<varname>UIO_MEM_VIRTUAL</varname> for virtual memory. -</para></listitem> - -<listitem><para> -<varname>phys_addr_t addr</varname>: Required if the mapping is used. -Fill in the address of your memory block. This address is the one that -appears in sysfs. -</para></listitem> - -<listitem><para> -<varname>resource_size_t size</varname>: Fill in the size of the -memory block that <varname>addr</varname> points to. If <varname>size</varname> -is zero, the mapping is considered unused. Note that you -<emphasis>must</emphasis> initialize <varname>size</varname> with zero for -all unused mappings. -</para></listitem> - -<listitem><para> -<varname>void *internal_addr</varname>: If you have to access this memory -region from within your kernel module, you will want to map it internally by -using something like <function>ioremap()</function>. Addresses -returned by this function cannot be mapped to user space, so you must not -store it in <varname>addr</varname>. Use <varname>internal_addr</varname> -instead to remember such an address. -</para></listitem> -</itemizedlist> - -<para> -Please do not touch the <varname>map</varname> element of -<varname>struct uio_mem</varname>! It is used by the UIO framework -to set up sysfs files for this mapping. Simply leave it alone. -</para> - -<para> -Sometimes, your device can have one or more port regions which can not be -mapped to userspace. But if there are other possibilities for userspace to -access these ports, it makes sense to make information about the ports -available in sysfs. For each region, you have to set up a -<varname>struct uio_port</varname> in the <varname>port[]</varname> array. -Here's a description of the fields of <varname>struct uio_port</varname>: -</para> - -<itemizedlist> -<listitem><para> -<varname>char *porttype</varname>: Required. Set this to one of the predefined -constants. Use <varname>UIO_PORT_X86</varname> for the ioports found in x86 -architectures. -</para></listitem> - -<listitem><para> -<varname>unsigned long start</varname>: Required if the port region is used. -Fill in the number of the first port of this region. -</para></listitem> - -<listitem><para> -<varname>unsigned long size</varname>: Fill in the number of ports in this -region. If <varname>size</varname> is zero, the region is considered unused. -Note that you <emphasis>must</emphasis> initialize <varname>size</varname> -with zero for all unused regions. -</para></listitem> -</itemizedlist> - -<para> -Please do not touch the <varname>portio</varname> element of -<varname>struct uio_port</varname>! It is used internally by the UIO -framework to set up sysfs files for this region. Simply leave it alone. -</para> - -</sect1> - -<sect1 id="adding_irq_handler"> -<title>Adding an interrupt handler</title> - <para> - What you need to do in your interrupt handler depends on your - hardware and on how you want to handle it. You should try to - keep the amount of code in your kernel interrupt handler low. - If your hardware requires no action that you - <emphasis>have</emphasis> to perform after each interrupt, - then your handler can be empty.</para> <para>If, on the other - hand, your hardware <emphasis>needs</emphasis> some action to - be performed after each interrupt, then you - <emphasis>must</emphasis> do it in your kernel module. Note - that you cannot rely on the userspace part of your driver. Your - userspace program can terminate at any time, possibly leaving - your hardware in a state where proper interrupt handling is - still required. - </para> - - <para> - There might also be applications where you want to read data - from your hardware at each interrupt and buffer it in a piece - of kernel memory you've allocated for that purpose. With this - technique you could avoid loss of data if your userspace - program misses an interrupt. - </para> - - <para> - A note on shared interrupts: Your driver should support - interrupt sharing whenever this is possible. It is possible if - and only if your driver can detect whether your hardware has - triggered the interrupt or not. This is usually done by looking - at an interrupt status register. If your driver sees that the - IRQ bit is actually set, it will perform its actions, and the - handler returns IRQ_HANDLED. If the driver detects that it was - not your hardware that caused the interrupt, it will do nothing - and return IRQ_NONE, allowing the kernel to call the next - possible interrupt handler. - </para> - - <para> - If you decide not to support shared interrupts, your card - won't work in computers with no free interrupts. As this - frequently happens on the PC platform, you can save yourself a - lot of trouble by supporting interrupt sharing. - </para> -</sect1> - -<sect1 id="using_uio_pdrv"> -<title>Using uio_pdrv for platform devices</title> - <para> - In many cases, UIO drivers for platform devices can be handled in a - generic way. In the same place where you define your - <varname>struct platform_device</varname>, you simply also implement - your interrupt handler and fill your - <varname>struct uio_info</varname>. A pointer to this - <varname>struct uio_info</varname> is then used as - <varname>platform_data</varname> for your platform device. - </para> - <para> - You also need to set up an array of <varname>struct resource</varname> - containing addresses and sizes of your memory mappings. This - information is passed to the driver using the - <varname>.resource</varname> and <varname>.num_resources</varname> - elements of <varname>struct platform_device</varname>. - </para> - <para> - You now have to set the <varname>.name</varname> element of - <varname>struct platform_device</varname> to - <varname>"uio_pdrv"</varname> to use the generic UIO platform device - driver. This driver will fill the <varname>mem[]</varname> array - according to the resources given, and register the device. - </para> - <para> - The advantage of this approach is that you only have to edit a file - you need to edit anyway. You do not have to create an extra driver. - </para> -</sect1> - -<sect1 id="using_uio_pdrv_genirq"> -<title>Using uio_pdrv_genirq for platform devices</title> - <para> - Especially in embedded devices, you frequently find chips where the - irq pin is tied to its own dedicated interrupt line. In such cases, - where you can be really sure the interrupt is not shared, we can take - the concept of <varname>uio_pdrv</varname> one step further and use a - generic interrupt handler. That's what - <varname>uio_pdrv_genirq</varname> does. - </para> - <para> - The setup for this driver is the same as described above for - <varname>uio_pdrv</varname>, except that you do not implement an - interrupt handler. The <varname>.handler</varname> element of - <varname>struct uio_info</varname> must remain - <varname>NULL</varname>. The <varname>.irq_flags</varname> element - must not contain <varname>IRQF_SHARED</varname>. - </para> - <para> - You will set the <varname>.name</varname> element of - <varname>struct platform_device</varname> to - <varname>"uio_pdrv_genirq"</varname> to use this driver. - </para> - <para> - The generic interrupt handler of <varname>uio_pdrv_genirq</varname> - will simply disable the interrupt line using - <function>disable_irq_nosync()</function>. After doing its work, - userspace can reenable the interrupt by writing 0x00000001 to the UIO - device file. The driver already implements an - <function>irq_control()</function> to make this possible, you must not - implement your own. - </para> - <para> - Using <varname>uio_pdrv_genirq</varname> not only saves a few lines of - interrupt handler code. You also do not need to know anything about - the chip's internal registers to create the kernel part of the driver. - All you need to know is the irq number of the pin the chip is - connected to. - </para> -</sect1> - -<sect1 id="using-uio_dmem_genirq"> -<title>Using uio_dmem_genirq for platform devices</title> - <para> - In addition to statically allocated memory ranges, they may also be - a desire to use dynamically allocated regions in a user space driver. - In particular, being able to access memory made available through the - dma-mapping API, may be particularly useful. The - <varname>uio_dmem_genirq</varname> driver provides a way to accomplish - this. - </para> - <para> - This driver is used in a similar manner to the - <varname>"uio_pdrv_genirq"</varname> driver with respect to interrupt - configuration and handling. - </para> - <para> - Set the <varname>.name</varname> element of - <varname>struct platform_device</varname> to - <varname>"uio_dmem_genirq"</varname> to use this driver. - </para> - <para> - When using this driver, fill in the <varname>.platform_data</varname> - element of <varname>struct platform_device</varname>, which is of type - <varname>struct uio_dmem_genirq_pdata</varname> and which contains the - following elements: - </para> - <itemizedlist> - <listitem><para><varname>struct uio_info uioinfo</varname>: The same - structure used as the <varname>uio_pdrv_genirq</varname> platform - data</para></listitem> - <listitem><para><varname>unsigned int *dynamic_region_sizes</varname>: - Pointer to list of sizes of dynamic memory regions to be mapped into - user space. - </para></listitem> - <listitem><para><varname>unsigned int num_dynamic_regions</varname>: - Number of elements in <varname>dynamic_region_sizes</varname> array. - </para></listitem> - </itemizedlist> - <para> - The dynamic regions defined in the platform data will be appended to - the <varname> mem[] </varname> array after the platform device - resources, which implies that the total number of static and dynamic - memory regions cannot exceed <varname>MAX_UIO_MAPS</varname>. - </para> - <para> - The dynamic memory regions will be allocated when the UIO device file, - <varname>/dev/uioX</varname> is opened. - Similar to static memory resources, the memory region information for - dynamic regions is then visible via sysfs at - <varname>/sys/class/uio/uioX/maps/mapY/*</varname>. - The dynamic memory regions will be freed when the UIO device file is - closed. When no processes are holding the device file open, the address - returned to userspace is ~0. - </para> -</sect1> - -</chapter> - -<chapter id="userspace_driver" xreflabel="Writing a driver in user space"> -<?dbhtml filename="userspace_driver.html"?> -<title>Writing a driver in userspace</title> - <para> - Once you have a working kernel module for your hardware, you can - write the userspace part of your driver. You don't need any special - libraries, your driver can be written in any reasonable language, - you can use floating point numbers and so on. In short, you can - use all the tools and libraries you'd normally use for writing a - userspace application. - </para> - -<sect1 id="getting_uio_information"> -<title>Getting information about your UIO device</title> - <para> - Information about all UIO devices is available in sysfs. The - first thing you should do in your driver is check - <varname>name</varname> and <varname>version</varname> to - make sure your talking to the right device and that its kernel - driver has the version you expect. - </para> - <para> - You should also make sure that the memory mapping you need - exists and has the size you expect. - </para> - <para> - There is a tool called <varname>lsuio</varname> that lists - UIO devices and their attributes. It is available here: - </para> - <para> - <ulink url="http://www.osadl.org/projects/downloads/UIO/user/"> - http://www.osadl.org/projects/downloads/UIO/user/</ulink> - </para> - <para> - With <varname>lsuio</varname> you can quickly check if your - kernel module is loaded and which attributes it exports. - Have a look at the manpage for details. - </para> - <para> - The source code of <varname>lsuio</varname> can serve as an - example for getting information about an UIO device. - The file <filename>uio_helper.c</filename> contains a lot of - functions you could use in your userspace driver code. - </para> -</sect1> - -<sect1 id="mmap_device_memory"> -<title>mmap() device memory</title> - <para> - After you made sure you've got the right device with the - memory mappings you need, all you have to do is to call - <function>mmap()</function> to map the device's memory - to userspace. - </para> - <para> - The parameter <varname>offset</varname> of the - <function>mmap()</function> call has a special meaning - for UIO devices: It is used to select which mapping of - your device you want to map. To map the memory of - mapping N, you have to use N times the page size as - your offset: - </para> -<programlisting format="linespecific"> - offset = N * getpagesize(); -</programlisting> - <para> - N starts from zero, so if you've got only one memory - range to map, set <varname>offset = 0</varname>. - A drawback of this technique is that memory is always - mapped beginning with its start address. - </para> -</sect1> - -<sect1 id="wait_for_interrupts"> -<title>Waiting for interrupts</title> - <para> - After you successfully mapped your devices memory, you - can access it like an ordinary array. Usually, you will - perform some initialization. After that, your hardware - starts working and will generate an interrupt as soon - as it's finished, has some data available, or needs your - attention because an error occurred. - </para> - <para> - <filename>/dev/uioX</filename> is a read-only file. A - <function>read()</function> will always block until an - interrupt occurs. There is only one legal value for the - <varname>count</varname> parameter of - <function>read()</function>, and that is the size of a - signed 32 bit integer (4). Any other value for - <varname>count</varname> causes <function>read()</function> - to fail. The signed 32 bit integer read is the interrupt - count of your device. If the value is one more than the value - you read the last time, everything is OK. If the difference - is greater than one, you missed interrupts. - </para> - <para> - You can also use <function>select()</function> on - <filename>/dev/uioX</filename>. - </para> -</sect1> - -</chapter> - -<chapter id="uio_pci_generic" xreflabel="Using Generic driver for PCI cards"> -<?dbhtml filename="uio_pci_generic.html"?> -<title>Generic PCI UIO driver</title> - <para> - The generic driver is a kernel module named uio_pci_generic. - It can work with any device compliant to PCI 2.3 (circa 2002) and - any compliant PCI Express device. Using this, you only need to - write the userspace driver, removing the need to write - a hardware-specific kernel module. - </para> - -<sect1 id="uio_pci_generic_binding"> -<title>Making the driver recognize the device</title> - <para> -Since the driver does not declare any device ids, it will not get loaded -automatically and will not automatically bind to any devices, you must load it -and allocate id to the driver yourself. For example: - <programlisting> - modprobe uio_pci_generic - echo "8086 10f5" > /sys/bus/pci/drivers/uio_pci_generic/new_id - </programlisting> - </para> - <para> -If there already is a hardware specific kernel driver for your device, the -generic driver still won't bind to it, in this case if you want to use the -generic driver (why would you?) you'll have to manually unbind the hardware -specific driver and bind the generic driver, like this: - <programlisting> - echo -n 0000:00:19.0 > /sys/bus/pci/drivers/e1000e/unbind - echo -n 0000:00:19.0 > /sys/bus/pci/drivers/uio_pci_generic/bind - </programlisting> - </para> - <para> -You can verify that the device has been bound to the driver -by looking for it in sysfs, for example like the following: - <programlisting> - ls -l /sys/bus/pci/devices/0000:00:19.0/driver - </programlisting> -Which if successful should print - <programlisting> - .../0000:00:19.0/driver -> ../../../bus/pci/drivers/uio_pci_generic - </programlisting> -Note that the generic driver will not bind to old PCI 2.2 devices. -If binding the device failed, run the following command: - <programlisting> - dmesg - </programlisting> -and look in the output for failure reasons - </para> -</sect1> - -<sect1 id="uio_pci_generic_internals"> -<title>Things to know about uio_pci_generic</title> - <para> -Interrupts are handled using the Interrupt Disable bit in the PCI command -register and Interrupt Status bit in the PCI status register. All devices -compliant to PCI 2.3 (circa 2002) and all compliant PCI Express devices should -support these bits. uio_pci_generic detects this support, and won't bind to -devices which do not support the Interrupt Disable Bit in the command register. - </para> - <para> -On each interrupt, uio_pci_generic sets the Interrupt Disable bit. -This prevents the device from generating further interrupts -until the bit is cleared. The userspace driver should clear this -bit before blocking and waiting for more interrupts. - </para> -</sect1> -<sect1 id="uio_pci_generic_userspace"> -<title>Writing userspace driver using uio_pci_generic</title> - <para> -Userspace driver can use pci sysfs interface, or the -libpci libray that wraps it, to talk to the device and to -re-enable interrupts by writing to the command register. - </para> -</sect1> -<sect1 id="uio_pci_generic_example"> -<title>Example code using uio_pci_generic</title> - <para> -Here is some sample userspace driver code using uio_pci_generic: -<programlisting> -#include <stdlib.h> -#include <stdio.h> -#include <unistd.h> -#include <sys/types.h> -#include <sys/stat.h> -#include <fcntl.h> -#include <errno.h> - -int main() -{ - int uiofd; - int configfd; - int err; - int i; - unsigned icount; - unsigned char command_high; - - uiofd = open("/dev/uio0", O_RDONLY); - if (uiofd < 0) { - perror("uio open:"); - return errno; - } - configfd = open("/sys/class/uio/uio0/device/config", O_RDWR); - if (configfd < 0) { - perror("config open:"); - return errno; - } - - /* Read and cache command value */ - err = pread(configfd, &command_high, 1, 5); - if (err != 1) { - perror("command config read:"); - return errno; - } - command_high &= ~0x4; - - for(i = 0;; ++i) { - /* Print out a message, for debugging. */ - if (i == 0) - fprintf(stderr, "Started uio test driver.\n"); - else - fprintf(stderr, "Interrupts: %d\n", icount); - - /****************************************/ - /* Here we got an interrupt from the - device. Do something to it. */ - /****************************************/ - - /* Re-enable interrupts. */ - err = pwrite(configfd, &command_high, 1, 5); - if (err != 1) { - perror("config write:"); - break; - } - - /* Wait for next interrupt. */ - err = read(uiofd, &icount, 4); - if (err != 4) { - perror("uio read:"); - break; - } - - } - return errno; -} - -</programlisting> - </para> -</sect1> - -</chapter> - -<appendix id="app1"> -<title>Further information</title> -<itemizedlist> - <listitem><para> - <ulink url="http://www.osadl.org"> - OSADL homepage.</ulink> - </para></listitem> - <listitem><para> - <ulink url="http://www.linutronix.de"> - Linutronix homepage.</ulink> - </para></listitem> -</itemizedlist> -</appendix> - -</book> diff --git a/Documentation/DocBook/usb.tmpl b/Documentation/DocBook/usb.tmpl deleted file mode 100644 index 4cd5b2cd0f3d..000000000000 --- a/Documentation/DocBook/usb.tmpl +++ /dev/null @@ -1,980 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="Linux-USB-API"> - <bookinfo> - <title>The Linux-USB Host Side API</title> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - -<chapter id="intro"> - <title>Introduction to USB on Linux</title> - - <para>A Universal Serial Bus (USB) is used to connect a host, - such as a PC or workstation, to a number of peripheral - devices. USB uses a tree structure, with the host as the - root (the system's master), hubs as interior nodes, and - peripherals as leaves (and slaves). - Modern PCs support several such trees of USB devices, usually - one USB 2.0 tree (480 Mbit/sec each) with - a few USB 1.1 trees (12 Mbit/sec each) that are used when you - connect a USB 1.1 device directly to the machine's "root hub". - </para> - - <para>That master/slave asymmetry was designed-in for a number of - reasons, one being ease of use. It is not physically possible to - assemble (legal) USB cables incorrectly: all upstream "to the host" - connectors are the rectangular type (matching the sockets on - root hubs), and all downstream connectors are the squarish type - (or they are built into the peripheral). - Also, the host software doesn't need to deal with distributed - auto-configuration since the pre-designated master node manages all that. - And finally, at the electrical level, bus protocol overhead is reduced by - eliminating arbitration and moving scheduling into the host software. - </para> - - <para>USB 1.0 was announced in January 1996 and was revised - as USB 1.1 (with improvements in hub specification and - support for interrupt-out transfers) in September 1998. - USB 2.0 was released in April 2000, adding high-speed - transfers and transaction-translating hubs (used for USB 1.1 - and 1.0 backward compatibility). - </para> - - <para>Kernel developers added USB support to Linux early in the 2.2 kernel - series, shortly before 2.3 development forked. Updates from 2.3 were - regularly folded back into 2.2 releases, which improved reliability and - brought <filename>/sbin/hotplug</filename> support as well more drivers. - Such improvements were continued in the 2.5 kernel series, where they added - USB 2.0 support, improved performance, and made the host controller drivers - (HCDs) more consistent. They also simplified the API (to make bugs less - likely) and added internal "kerneldoc" documentation. - </para> - - <para>Linux can run inside USB devices as well as on - the hosts that control the devices. - But USB device drivers running inside those peripherals - don't do the same things as the ones running inside hosts, - so they've been given a different name: - <emphasis>gadget drivers</emphasis>. - This document does not cover gadget drivers. - </para> - - </chapter> - -<chapter id="host"> - <title>USB Host-Side API Model</title> - - <para>Host-side drivers for USB devices talk to the "usbcore" APIs. - There are two. One is intended for - <emphasis>general-purpose</emphasis> drivers (exposed through - driver frameworks), and the other is for drivers that are - <emphasis>part of the core</emphasis>. - Such core drivers include the <emphasis>hub</emphasis> driver - (which manages trees of USB devices) and several different kinds - of <emphasis>host controller drivers</emphasis>, - which control individual busses. - </para> - - <para>The device model seen by USB drivers is relatively complex. - </para> - - <itemizedlist> - - <listitem><para>USB supports four kinds of data transfers - (control, bulk, interrupt, and isochronous). Two of them (control - and bulk) use bandwidth as it's available, - while the other two (interrupt and isochronous) - are scheduled to provide guaranteed bandwidth. - </para></listitem> - - <listitem><para>The device description model includes one or more - "configurations" per device, only one of which is active at a time. - Devices that are capable of high-speed operation must also support - full-speed configurations, along with a way to ask about the - "other speed" configurations which might be used. - </para></listitem> - - <listitem><para>Configurations have one or more "interfaces", each - of which may have "alternate settings". Interfaces may be - standardized by USB "Class" specifications, or may be specific to - a vendor or device.</para> - - <para>USB device drivers actually bind to interfaces, not devices. - Think of them as "interface drivers", though you - may not see many devices where the distinction is important. - <emphasis>Most USB devices are simple, with only one configuration, - one interface, and one alternate setting.</emphasis> - </para></listitem> - - <listitem><para>Interfaces have one or more "endpoints", each of - which supports one type and direction of data transfer such as - "bulk out" or "interrupt in". The entire configuration may have - up to sixteen endpoints in each direction, allocated as needed - among all the interfaces. - </para></listitem> - - <listitem><para>Data transfer on USB is packetized; each endpoint - has a maximum packet size. - Drivers must often be aware of conventions such as flagging the end - of bulk transfers using "short" (including zero length) packets. - </para></listitem> - - <listitem><para>The Linux USB API supports synchronous calls for - control and bulk messages. - It also supports asynchronous calls for all kinds of data transfer, - using request structures called "URBs" (USB Request Blocks). - </para></listitem> - - </itemizedlist> - - <para>Accordingly, the USB Core API exposed to device drivers - covers quite a lot of territory. You'll probably need to consult - the USB 2.0 specification, available online from www.usb.org at - no cost, as well as class or device specifications. - </para> - - <para>The only host-side drivers that actually touch hardware - (reading/writing registers, handling IRQs, and so on) are the HCDs. - In theory, all HCDs provide the same functionality through the same - API. In practice, that's becoming more true on the 2.5 kernels, - but there are still differences that crop up especially with - fault handling. Different controllers don't necessarily report - the same aspects of failures, and recovery from faults (including - software-induced ones like unlinking an URB) isn't yet fully - consistent. - Device driver authors should make a point of doing disconnect - testing (while the device is active) with each different host - controller driver, to make sure drivers don't have bugs of - their own as well as to make sure they aren't relying on some - HCD-specific behavior. - (You will need external USB 1.1 and/or - USB 2.0 hubs to perform all those tests.) - </para> - - </chapter> - -<chapter id="types"><title>USB-Standard Types</title> - - <para>In <filename><linux/usb/ch9.h></filename> you will find - the USB data types defined in chapter 9 of the USB specification. - These data types are used throughout USB, and in APIs including - this host side API, gadget APIs, and usbfs. - </para> - -!Iinclude/linux/usb/ch9.h - - </chapter> - -<chapter id="hostside"><title>Host-Side Data Types and Macros</title> - - <para>The host side API exposes several layers to drivers, some of - which are more necessary than others. - These support lifecycle models for host side drivers - and devices, and support passing buffers through usbcore to - some HCD that performs the I/O for the device driver. - </para> - - -!Iinclude/linux/usb.h - - </chapter> - - <chapter id="usbcore"><title>USB Core APIs</title> - - <para>There are two basic I/O models in the USB API. - The most elemental one is asynchronous: drivers submit requests - in the form of an URB, and the URB's completion callback - handle the next step. - All USB transfer types support that model, although there - are special cases for control URBs (which always have setup - and status stages, but may not have a data stage) and - isochronous URBs (which allow large packets and include - per-packet fault reports). - Built on top of that is synchronous API support, where a - driver calls a routine that allocates one or more URBs, - submits them, and waits until they complete. - There are synchronous wrappers for single-buffer control - and bulk transfers (which are awkward to use in some - driver disconnect scenarios), and for scatterlist based - streaming i/o (bulk or interrupt). - </para> - - <para>USB drivers need to provide buffers that can be - used for DMA, although they don't necessarily need to - provide the DMA mapping themselves. - There are APIs to use used when allocating DMA buffers, - which can prevent use of bounce buffers on some systems. - In some cases, drivers may be able to rely on 64bit DMA - to eliminate another kind of bounce buffer. - </para> - -!Edrivers/usb/core/urb.c -!Edrivers/usb/core/message.c -!Edrivers/usb/core/file.c -!Edrivers/usb/core/driver.c -!Edrivers/usb/core/usb.c -!Edrivers/usb/core/hub.c - </chapter> - - <chapter id="hcd"><title>Host Controller APIs</title> - - <para>These APIs are only for use by host controller drivers, - most of which implement standard register interfaces such as - EHCI, OHCI, or UHCI. - UHCI was one of the first interfaces, designed by Intel and - also used by VIA; it doesn't do much in hardware. - OHCI was designed later, to have the hardware do more work - (bigger transfers, tracking protocol state, and so on). - EHCI was designed with USB 2.0; its design has features that - resemble OHCI (hardware does much more work) as well as - UHCI (some parts of ISO support, TD list processing). - </para> - - <para>There are host controllers other than the "big three", - although most PCI based controllers (and a few non-PCI based - ones) use one of those interfaces. - Not all host controllers use DMA; some use PIO, and there - is also a simulator. - </para> - - <para>The same basic APIs are available to drivers for all - those controllers. - For historical reasons they are in two layers: - <structname>struct usb_bus</structname> is a rather thin - layer that became available in the 2.2 kernels, while - <structname>struct usb_hcd</structname> is a more featureful - layer (available in later 2.4 kernels and in 2.5) that - lets HCDs share common code, to shrink driver size - and significantly reduce hcd-specific behaviors. - </para> - -!Edrivers/usb/core/hcd.c -!Edrivers/usb/core/hcd-pci.c -!Idrivers/usb/core/buffer.c - </chapter> - - <chapter id="usbfs"> - <title>The USB Filesystem (usbfs)</title> - - <para>This chapter presents the Linux <emphasis>usbfs</emphasis>. - You may prefer to avoid writing new kernel code for your - USB driver; that's the problem that usbfs set out to solve. - User mode device drivers are usually packaged as applications - or libraries, and may use usbfs through some programming library - that wraps it. Such libraries include - <ulink url="http://libusb.sourceforge.net">libusb</ulink> - for C/C++, and - <ulink url="http://jUSB.sourceforge.net">jUSB</ulink> for Java. - </para> - - <note><title>Unfinished</title> - <para>This particular documentation is incomplete, - especially with respect to the asynchronous mode. - As of kernel 2.5.66 the code and this (new) documentation - need to be cross-reviewed. - </para> - </note> - - <para>Configure usbfs into Linux kernels by enabling the - <emphasis>USB filesystem</emphasis> option (CONFIG_USB_DEVICEFS), - and you get basic support for user mode USB device drivers. - Until relatively recently it was often (confusingly) called - <emphasis>usbdevfs</emphasis> although it wasn't solving what - <emphasis>devfs</emphasis> was. - Every USB device will appear in usbfs, regardless of whether or - not it has a kernel driver. - </para> - - <sect1 id="usbfs-files"> - <title>What files are in "usbfs"?</title> - - <para>Conventionally mounted at - <filename>/proc/bus/usb</filename>, usbfs - features include: - <itemizedlist> - <listitem><para><filename>/proc/bus/usb/devices</filename> - ... a text file - showing each of the USB devices on known to the kernel, - and their configuration descriptors. - You can also poll() this to learn about new devices. - </para></listitem> - <listitem><para><filename>/proc/bus/usb/BBB/DDD</filename> - ... magic files - exposing the each device's configuration descriptors, and - supporting a series of ioctls for making device requests, - including I/O to devices. (Purely for access by programs.) - </para></listitem> - </itemizedlist> - </para> - - <para> Each bus is given a number (BBB) based on when it was - enumerated; within each bus, each device is given a similar - number (DDD). - Those BBB/DDD paths are not "stable" identifiers; - expect them to change even if you always leave the devices - plugged in to the same hub port. - <emphasis>Don't even think of saving these in application - configuration files.</emphasis> - Stable identifiers are available, for user mode applications - that want to use them. HID and networking devices expose - these stable IDs, so that for example you can be sure that - you told the right UPS to power down its second server. - "usbfs" doesn't (yet) expose those IDs. - </para> - - </sect1> - - <sect1 id="usbfs-fstab"> - <title>Mounting and Access Control</title> - - <para>There are a number of mount options for usbfs, which will - be of most interest to you if you need to override the default - access control policy. - That policy is that only root may read or write device files - (<filename>/proc/bus/BBB/DDD</filename>) although anyone may read - the <filename>devices</filename> - or <filename>drivers</filename> files. - I/O requests to the device also need the CAP_SYS_RAWIO capability, - </para> - - <para>The significance of that is that by default, all user mode - device drivers need super-user privileges. - You can change modes or ownership in a driver setup - when the device hotplugs, or maye just start the - driver right then, as a privileged server (or some activity - within one). - That's the most secure approach for multi-user systems, - but for single user systems ("trusted" by that user) - it's more convenient just to grant everyone all access - (using the <emphasis>devmode=0666</emphasis> option) - so the driver can start whenever it's needed. - </para> - - <para>The mount options for usbfs, usable in /etc/fstab or - in command line invocations of <emphasis>mount</emphasis>, are: - - <variablelist> - <varlistentry> - <term><emphasis>busgid</emphasis>=NNNNN</term> - <listitem><para>Controls the GID used for the - /proc/bus/usb/BBB - directories. (Default: 0)</para></listitem></varlistentry> - <varlistentry><term><emphasis>busmode</emphasis>=MMM</term> - <listitem><para>Controls the file mode used for the - /proc/bus/usb/BBB - directories. (Default: 0555) - </para></listitem></varlistentry> - <varlistentry><term><emphasis>busuid</emphasis>=NNNNN</term> - <listitem><para>Controls the UID used for the - /proc/bus/usb/BBB - directories. (Default: 0)</para></listitem></varlistentry> - - <varlistentry><term><emphasis>devgid</emphasis>=NNNNN</term> - <listitem><para>Controls the GID used for the - /proc/bus/usb/BBB/DDD - files. (Default: 0)</para></listitem></varlistentry> - <varlistentry><term><emphasis>devmode</emphasis>=MMM</term> - <listitem><para>Controls the file mode used for the - /proc/bus/usb/BBB/DDD - files. (Default: 0644)</para></listitem></varlistentry> - <varlistentry><term><emphasis>devuid</emphasis>=NNNNN</term> - <listitem><para>Controls the UID used for the - /proc/bus/usb/BBB/DDD - files. (Default: 0)</para></listitem></varlistentry> - - <varlistentry><term><emphasis>listgid</emphasis>=NNNNN</term> - <listitem><para>Controls the GID used for the - /proc/bus/usb/devices and drivers files. - (Default: 0)</para></listitem></varlistentry> - <varlistentry><term><emphasis>listmode</emphasis>=MMM</term> - <listitem><para>Controls the file mode used for the - /proc/bus/usb/devices and drivers files. - (Default: 0444)</para></listitem></varlistentry> - <varlistentry><term><emphasis>listuid</emphasis>=NNNNN</term> - <listitem><para>Controls the UID used for the - /proc/bus/usb/devices and drivers files. - (Default: 0)</para></listitem></varlistentry> - </variablelist> - - </para> - - <para>Note that many Linux distributions hard-wire the mount options - for usbfs in their init scripts, such as - <filename>/etc/rc.d/rc.sysinit</filename>, - rather than making it easy to set this per-system - policy in <filename>/etc/fstab</filename>. - </para> - - </sect1> - - <sect1 id="usbfs-devices"> - <title>/proc/bus/usb/devices</title> - - <para>This file is handy for status viewing tools in user - mode, which can scan the text format and ignore most of it. - More detailed device status (including class and vendor - status) is available from device-specific files. - For information about the current format of this file, - see the - <filename>Documentation/usb/proc_usb_info.txt</filename> - file in your Linux kernel sources. - </para> - - <para>This file, in combination with the poll() system call, can - also be used to detect when devices are added or removed: -<programlisting>int fd; -struct pollfd pfd; - -fd = open("/proc/bus/usb/devices", O_RDONLY); -pfd = { fd, POLLIN, 0 }; -for (;;) { - /* The first time through, this call will return immediately. */ - poll(&pfd, 1, -1); - - /* To see what's changed, compare the file's previous and current - contents or scan the filesystem. (Scanning is more precise.) */ -}</programlisting> - Note that this behavior is intended to be used for informational - and debug purposes. It would be more appropriate to use programs - such as udev or HAL to initialize a device or start a user-mode - helper program, for instance. - </para> - </sect1> - - <sect1 id="usbfs-bbbddd"> - <title>/proc/bus/usb/BBB/DDD</title> - - <para>Use these files in one of these basic ways: - </para> - - <para><emphasis>They can be read,</emphasis> - producing first the device descriptor - (18 bytes) and then the descriptors for the current configuration. - See the USB 2.0 spec for details about those binary data formats. - You'll need to convert most multibyte values from little endian - format to your native host byte order, although a few of the - fields in the device descriptor (both of the BCD-encoded fields, - and the vendor and product IDs) will be byteswapped for you. - Note that configuration descriptors include descriptors for - interfaces, altsettings, endpoints, and maybe additional - class descriptors. - </para> - - <para><emphasis>Perform USB operations</emphasis> using - <emphasis>ioctl()</emphasis> requests to make endpoint I/O - requests (synchronously or asynchronously) or manage - the device. - These requests need the CAP_SYS_RAWIO capability, - as well as filesystem access permissions. - Only one ioctl request can be made on one of these - device files at a time. - This means that if you are synchronously reading an endpoint - from one thread, you won't be able to write to a different - endpoint from another thread until the read completes. - This works for <emphasis>half duplex</emphasis> protocols, - but otherwise you'd use asynchronous i/o requests. - </para> - - </sect1> - - - <sect1 id="usbfs-lifecycle"> - <title>Life Cycle of User Mode Drivers</title> - - <para>Such a driver first needs to find a device file - for a device it knows how to handle. - Maybe it was told about it because a - <filename>/sbin/hotplug</filename> event handling agent - chose that driver to handle the new device. - Or maybe it's an application that scans all the - /proc/bus/usb device files, and ignores most devices. - In either case, it should <function>read()</function> all - the descriptors from the device file, - and check them against what it knows how to handle. - It might just reject everything except a particular - vendor and product ID, or need a more complex policy. - </para> - - <para>Never assume there will only be one such device - on the system at a time! - If your code can't handle more than one device at - a time, at least detect when there's more than one, and - have your users choose which device to use. - </para> - - <para>Once your user mode driver knows what device to use, - it interacts with it in either of two styles. - The simple style is to make only control requests; some - devices don't need more complex interactions than those. - (An example might be software using vendor-specific control - requests for some initialization or configuration tasks, - with a kernel driver for the rest.) - </para> - - <para>More likely, you need a more complex style driver: - one using non-control endpoints, reading or writing data - and claiming exclusive use of an interface. - <emphasis>Bulk</emphasis> transfers are easiest to use, - but only their sibling <emphasis>interrupt</emphasis> transfers - work with low speed devices. - Both interrupt and <emphasis>isochronous</emphasis> transfers - offer service guarantees because their bandwidth is reserved. - Such "periodic" transfers are awkward to use through usbfs, - unless you're using the asynchronous calls. However, interrupt - transfers can also be used in a synchronous "one shot" style. - </para> - - <para>Your user-mode driver should never need to worry - about cleaning up request state when the device is - disconnected, although it should close its open file - descriptors as soon as it starts seeing the ENODEV - errors. - </para> - - </sect1> - - <sect1 id="usbfs-ioctl"><title>The ioctl() Requests</title> - - <para>To use these ioctls, you need to include the following - headers in your userspace program: -<programlisting>#include <linux/usb.h> -#include <linux/usbdevice_fs.h> -#include <asm/byteorder.h></programlisting> - The standard USB device model requests, from "Chapter 9" of - the USB 2.0 specification, are automatically included from - the <filename><linux/usb/ch9.h></filename> header. - </para> - - <para>Unless noted otherwise, the ioctl requests - described here will - update the modification time on the usbfs file to which - they are applied (unless they fail). - A return of zero indicates success; otherwise, a - standard USB error code is returned. (These are - documented in - <filename>Documentation/usb/error-codes.txt</filename> - in your kernel sources.) - </para> - - <para>Each of these files multiplexes access to several - I/O streams, one per endpoint. - Each device has one control endpoint (endpoint zero) - which supports a limited RPC style RPC access. - Devices are configured - by hub_wq (in the kernel) setting a device-wide - <emphasis>configuration</emphasis> that affects things - like power consumption and basic functionality. - The endpoints are part of USB <emphasis>interfaces</emphasis>, - which may have <emphasis>altsettings</emphasis> - affecting things like which endpoints are available. - Many devices only have a single configuration and interface, - so drivers for them will ignore configurations and altsettings. - </para> - - - <sect2 id="usbfs-mgmt"> - <title>Management/Status Requests</title> - - <para>A number of usbfs requests don't deal very directly - with device I/O. - They mostly relate to device management and status. - These are all synchronous requests. - </para> - - <variablelist> - - <varlistentry><term>USBDEVFS_CLAIMINTERFACE</term> - <listitem><para>This is used to force usbfs to - claim a specific interface, - which has not previously been claimed by usbfs or any other - kernel driver. - The ioctl parameter is an integer holding the number of - the interface (bInterfaceNumber from descriptor). - </para><para> - Note that if your driver doesn't claim an interface - before trying to use one of its endpoints, and no - other driver has bound to it, then the interface is - automatically claimed by usbfs. - </para><para> - This claim will be released by a RELEASEINTERFACE ioctl, - or by closing the file descriptor. - File modification time is not updated by this request. - </para></listitem></varlistentry> - - <varlistentry><term>USBDEVFS_CONNECTINFO</term> - <listitem><para>Says whether the device is lowspeed. - The ioctl parameter points to a structure like this: -<programlisting>struct usbdevfs_connectinfo { - unsigned int devnum; - unsigned char slow; -}; </programlisting> - File modification time is not updated by this request. - </para><para> - <emphasis>You can't tell whether a "not slow" - device is connected at high speed (480 MBit/sec) - or just full speed (12 MBit/sec).</emphasis> - You should know the devnum value already, - it's the DDD value of the device file name. - </para></listitem></varlistentry> - - <varlistentry><term>USBDEVFS_GETDRIVER</term> - <listitem><para>Returns the name of the kernel driver - bound to a given interface (a string). Parameter - is a pointer to this structure, which is modified: -<programlisting>struct usbdevfs_getdriver { - unsigned int interface; - char driver[USBDEVFS_MAXDRIVERNAME + 1]; -};</programlisting> - File modification time is not updated by this request. - </para></listitem></varlistentry> - - <varlistentry><term>USBDEVFS_IOCTL</term> - <listitem><para>Passes a request from userspace through - to a kernel driver that has an ioctl entry in the - <emphasis>struct usb_driver</emphasis> it registered. -<programlisting>struct usbdevfs_ioctl { - int ifno; - int ioctl_code; - void *data; -}; - -/* user mode call looks like this. - * 'request' becomes the driver->ioctl() 'code' parameter. - * the size of 'param' is encoded in 'request', and that data - * is copied to or from the driver->ioctl() 'buf' parameter. - */ -static int -usbdev_ioctl (int fd, int ifno, unsigned request, void *param) -{ - struct usbdevfs_ioctl wrapper; - - wrapper.ifno = ifno; - wrapper.ioctl_code = request; - wrapper.data = param; - - return ioctl (fd, USBDEVFS_IOCTL, &wrapper); -} </programlisting> - File modification time is not updated by this request. - </para><para> - This request lets kernel drivers talk to user mode code - through filesystem operations even when they don't create - a character or block special device. - It's also been used to do things like ask devices what - device special file should be used. - Two pre-defined ioctls are used - to disconnect and reconnect kernel drivers, so - that user mode code can completely manage binding - and configuration of devices. - </para></listitem></varlistentry> - - <varlistentry><term>USBDEVFS_RELEASEINTERFACE</term> - <listitem><para>This is used to release the claim usbfs - made on interface, either implicitly or because of a - USBDEVFS_CLAIMINTERFACE call, before the file - descriptor is closed. - The ioctl parameter is an integer holding the number of - the interface (bInterfaceNumber from descriptor); - File modification time is not updated by this request. - </para><warning><para> - <emphasis>No security check is made to ensure - that the task which made the claim is the one - which is releasing it. - This means that user mode driver may interfere - other ones. </emphasis> - </para></warning></listitem></varlistentry> - - <varlistentry><term>USBDEVFS_RESETEP</term> - <listitem><para>Resets the data toggle value for an endpoint - (bulk or interrupt) to DATA0. - The ioctl parameter is an integer endpoint number - (1 to 15, as identified in the endpoint descriptor), - with USB_DIR_IN added if the device's endpoint sends - data to the host. - </para><warning><para> - <emphasis>Avoid using this request. - It should probably be removed.</emphasis> - Using it typically means the device and driver will lose - toggle synchronization. If you really lost synchronization, - you likely need to completely handshake with the device, - using a request like CLEAR_HALT - or SET_INTERFACE. - </para></warning></listitem></varlistentry> - - </variablelist> - - </sect2> - - <sect2 id="usbfs-sync"> - <title>Synchronous I/O Support</title> - - <para>Synchronous requests involve the kernel blocking - until the user mode request completes, either by - finishing successfully or by reporting an error. - In most cases this is the simplest way to use usbfs, - although as noted above it does prevent performing I/O - to more than one endpoint at a time. - </para> - - <variablelist> - - <varlistentry><term>USBDEVFS_BULK</term> - <listitem><para>Issues a bulk read or write request to the - device. - The ioctl parameter is a pointer to this structure: -<programlisting>struct usbdevfs_bulktransfer { - unsigned int ep; - unsigned int len; - unsigned int timeout; /* in milliseconds */ - void *data; -};</programlisting> - </para><para>The "ep" value identifies a - bulk endpoint number (1 to 15, as identified in an endpoint - descriptor), - masked with USB_DIR_IN when referring to an endpoint which - sends data to the host from the device. - The length of the data buffer is identified by "len"; - Recent kernels support requests up to about 128KBytes. - <emphasis>FIXME say how read length is returned, - and how short reads are handled.</emphasis>. - </para></listitem></varlistentry> - - <varlistentry><term>USBDEVFS_CLEAR_HALT</term> - <listitem><para>Clears endpoint halt (stall) and - resets the endpoint toggle. This is only - meaningful for bulk or interrupt endpoints. - The ioctl parameter is an integer endpoint number - (1 to 15, as identified in an endpoint descriptor), - masked with USB_DIR_IN when referring to an endpoint which - sends data to the host from the device. - </para><para> - Use this on bulk or interrupt endpoints which have - stalled, returning <emphasis>-EPIPE</emphasis> status - to a data transfer request. - Do not issue the control request directly, since - that could invalidate the host's record of the - data toggle. - </para></listitem></varlistentry> - - <varlistentry><term>USBDEVFS_CONTROL</term> - <listitem><para>Issues a control request to the device. - The ioctl parameter points to a structure like this: -<programlisting>struct usbdevfs_ctrltransfer { - __u8 bRequestType; - __u8 bRequest; - __u16 wValue; - __u16 wIndex; - __u16 wLength; - __u32 timeout; /* in milliseconds */ - void *data; -};</programlisting> - </para><para> - The first eight bytes of this structure are the contents - of the SETUP packet to be sent to the device; see the - USB 2.0 specification for details. - The bRequestType value is composed by combining a - USB_TYPE_* value, a USB_DIR_* value, and a - USB_RECIP_* value (from - <emphasis><linux/usb.h></emphasis>). - If wLength is nonzero, it describes the length of the data - buffer, which is either written to the device - (USB_DIR_OUT) or read from the device (USB_DIR_IN). - </para><para> - At this writing, you can't transfer more than 4 KBytes - of data to or from a device; usbfs has a limit, and - some host controller drivers have a limit. - (That's not usually a problem.) - <emphasis>Also</emphasis> there's no way to say it's - not OK to get a short read back from the device. - </para></listitem></varlistentry> - - <varlistentry><term>USBDEVFS_RESET</term> - <listitem><para>Does a USB level device reset. - The ioctl parameter is ignored. - After the reset, this rebinds all device interfaces. - File modification time is not updated by this request. - </para><warning><para> - <emphasis>Avoid using this call</emphasis> - until some usbcore bugs get fixed, - since it does not fully synchronize device, interface, - and driver (not just usbfs) state. - </para></warning></listitem></varlistentry> - - <varlistentry><term>USBDEVFS_SETINTERFACE</term> - <listitem><para>Sets the alternate setting for an - interface. The ioctl parameter is a pointer to a - structure like this: -<programlisting>struct usbdevfs_setinterface { - unsigned int interface; - unsigned int altsetting; -}; </programlisting> - File modification time is not updated by this request. - </para><para> - Those struct members are from some interface descriptor - applying to the current configuration. - The interface number is the bInterfaceNumber value, and - the altsetting number is the bAlternateSetting value. - (This resets each endpoint in the interface.) - </para></listitem></varlistentry> - - <varlistentry><term>USBDEVFS_SETCONFIGURATION</term> - <listitem><para>Issues the - <function>usb_set_configuration</function> call - for the device. - The parameter is an integer holding the number of - a configuration (bConfigurationValue from descriptor). - File modification time is not updated by this request. - </para><warning><para> - <emphasis>Avoid using this call</emphasis> - until some usbcore bugs get fixed, - since it does not fully synchronize device, interface, - and driver (not just usbfs) state. - </para></warning></listitem></varlistentry> - - </variablelist> - </sect2> - - <sect2 id="usbfs-async"> - <title>Asynchronous I/O Support</title> - - <para>As mentioned above, there are situations where it may be - important to initiate concurrent operations from user mode code. - This is particularly important for periodic transfers - (interrupt and isochronous), but it can be used for other - kinds of USB requests too. - In such cases, the asynchronous requests described here - are essential. Rather than submitting one request and having - the kernel block until it completes, the blocking is separate. - </para> - - <para>These requests are packaged into a structure that - resembles the URB used by kernel device drivers. - (No POSIX Async I/O support here, sorry.) - It identifies the endpoint type (USBDEVFS_URB_TYPE_*), - endpoint (number, masked with USB_DIR_IN as appropriate), - buffer and length, and a user "context" value serving to - uniquely identify each request. - (It's usually a pointer to per-request data.) - Flags can modify requests (not as many as supported for - kernel drivers). - </para> - - <para>Each request can specify a realtime signal number - (between SIGRTMIN and SIGRTMAX, inclusive) to request a - signal be sent when the request completes. - </para> - - <para>When usbfs returns these urbs, the status value - is updated, and the buffer may have been modified. - Except for isochronous transfers, the actual_length is - updated to say how many bytes were transferred; if the - USBDEVFS_URB_DISABLE_SPD flag is set - ("short packets are not OK"), if fewer bytes were read - than were requested then you get an error report. - </para> - -<programlisting>struct usbdevfs_iso_packet_desc { - unsigned int length; - unsigned int actual_length; - unsigned int status; -}; - -struct usbdevfs_urb { - unsigned char type; - unsigned char endpoint; - int status; - unsigned int flags; - void *buffer; - int buffer_length; - int actual_length; - int start_frame; - int number_of_packets; - int error_count; - unsigned int signr; - void *usercontext; - struct usbdevfs_iso_packet_desc iso_frame_desc[]; -};</programlisting> - - <para> For these asynchronous requests, the file modification - time reflects when the request was initiated. - This contrasts with their use with the synchronous requests, - where it reflects when requests complete. - </para> - - <variablelist> - - <varlistentry><term>USBDEVFS_DISCARDURB</term> - <listitem><para> - <emphasis>TBS</emphasis> - File modification time is not updated by this request. - </para><para> - </para></listitem></varlistentry> - - <varlistentry><term>USBDEVFS_DISCSIGNAL</term> - <listitem><para> - <emphasis>TBS</emphasis> - File modification time is not updated by this request. - </para><para> - </para></listitem></varlistentry> - - <varlistentry><term>USBDEVFS_REAPURB</term> - <listitem><para> - <emphasis>TBS</emphasis> - File modification time is not updated by this request. - </para><para> - </para></listitem></varlistentry> - - <varlistentry><term>USBDEVFS_REAPURBNDELAY</term> - <listitem><para> - <emphasis>TBS</emphasis> - File modification time is not updated by this request. - </para><para> - </para></listitem></varlistentry> - - <varlistentry><term>USBDEVFS_SUBMITURB</term> - <listitem><para> - <emphasis>TBS</emphasis> - </para><para> - </para></listitem></varlistentry> - - </variablelist> - </sect2> - - </sect1> - - </chapter> - -</book> -<!-- vim:syntax=sgml:sw=4 ---> diff --git a/Documentation/DocBook/w1.tmpl b/Documentation/DocBook/w1.tmpl deleted file mode 100644 index b0228d4c81bb..000000000000 --- a/Documentation/DocBook/w1.tmpl +++ /dev/null @@ -1,101 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="w1id"> - <bookinfo> - <title>W1: Dallas' 1-wire bus</title> - - <authorgroup> - <author> - <firstname>David</firstname> - <surname>Fries</surname> - <affiliation> - <address> - <email>David@Fries.net</email> - </address> - </affiliation> - </author> - - </authorgroup> - - <copyright> - <year>2013</year> - <!-- - <holder></holder> - --> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License version 2. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - - <toc></toc> - - <chapter id="w1_internal"> - <title>W1 API internal to the kernel</title> - - <sect1 id="w1_internal_api"> - <title>W1 API internal to the kernel</title> - <sect2 id="w1.h"> - <title>drivers/w1/w1.h</title> - <para>W1 core functions.</para> -!Idrivers/w1/w1.h - </sect2> - - <sect2 id="w1.c"> - <title>drivers/w1/w1.c</title> - <para>W1 core functions.</para> -!Idrivers/w1/w1.c - </sect2> - - <sect2 id="w1_family.h"> - <title>drivers/w1/w1_family.h</title> - <para>Allows registering device family operations.</para> -!Idrivers/w1/w1_family.h - </sect2> - - <sect2 id="w1_family.c"> - <title>drivers/w1/w1_family.c</title> - <para>Allows registering device family operations.</para> -!Edrivers/w1/w1_family.c - </sect2> - - <sect2 id="w1_int.c"> - <title>drivers/w1/w1_int.c</title> - <para>W1 internal initialization for master devices.</para> -!Edrivers/w1/w1_int.c - </sect2> - - <sect2 id="w1_netlink.h"> - <title>drivers/w1/w1_netlink.h</title> - <para>W1 external netlink API structures and commands.</para> -!Idrivers/w1/w1_netlink.h - </sect2> - - <sect2 id="w1_io.c"> - <title>drivers/w1/w1_io.c</title> - <para>W1 input/output.</para> -!Edrivers/w1/w1_io.c -!Idrivers/w1/w1_io.c - </sect2> - - </sect1> - - - </chapter> - -</book> diff --git a/Documentation/DocBook/writing-an-alsa-driver.tmpl b/Documentation/DocBook/writing-an-alsa-driver.tmpl deleted file mode 100644 index a27ab9f53fb6..000000000000 --- a/Documentation/DocBook/writing-an-alsa-driver.tmpl +++ /dev/null @@ -1,6206 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<!-- ****************************************************** --> -<!-- Header --> -<!-- ****************************************************** --> -<book id="Writing-an-ALSA-Driver"> - <bookinfo> - <title>Writing an ALSA Driver</title> - <author> - <firstname>Takashi</firstname> - <surname>Iwai</surname> - <affiliation> - <address> - <email>tiwai@suse.de</email> - </address> - </affiliation> - </author> - - <date>Oct 15, 2007</date> - <edition>0.3.7</edition> - - <abstract> - <para> - This document describes how to write an ALSA (Advanced Linux - Sound Architecture) driver. - </para> - </abstract> - - <legalnotice> - <para> - Copyright (c) 2002-2005 Takashi Iwai <email>tiwai@suse.de</email> - </para> - - <para> - This document is free; you can redistribute it and/or modify it - under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - </para> - - <para> - This document is distributed in the hope that it will be useful, - but <emphasis>WITHOUT ANY WARRANTY</emphasis>; without even the - implied warranty of <emphasis>MERCHANTABILITY or FITNESS FOR A - PARTICULAR PURPOSE</emphasis>. See the GNU General Public License - for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - </legalnotice> - - </bookinfo> - -<!-- ****************************************************** --> -<!-- Preface --> -<!-- ****************************************************** --> - <preface id="preface"> - <title>Preface</title> - <para> - This document describes how to write an - <ulink url="http://www.alsa-project.org/"><citetitle> - ALSA (Advanced Linux Sound Architecture)</citetitle></ulink> - driver. The document focuses mainly on PCI soundcards. - In the case of other device types, the API might - be different, too. However, at least the ALSA kernel API is - consistent, and therefore it would be still a bit help for - writing them. - </para> - - <para> - This document targets people who already have enough - C language skills and have basic linux kernel programming - knowledge. This document doesn't explain the general - topic of linux kernel coding and doesn't cover low-level - driver implementation details. It only describes - the standard way to write a PCI sound driver on ALSA. - </para> - - <para> - If you are already familiar with the older ALSA ver.0.5.x API, you - can check the drivers such as <filename>sound/pci/es1938.c</filename> or - <filename>sound/pci/maestro3.c</filename> which have also almost the same - code-base in the ALSA 0.5.x tree, so you can compare the differences. - </para> - - <para> - This document is still a draft version. Any feedback and - corrections, please!! - </para> - </preface> - - -<!-- ****************************************************** --> -<!-- File Tree Structure --> -<!-- ****************************************************** --> - <chapter id="file-tree"> - <title>File Tree Structure</title> - - <section id="file-tree-general"> - <title>General</title> - <para> - The ALSA drivers are provided in two ways. - </para> - - <para> - One is the trees provided as a tarball or via cvs from the - ALSA's ftp site, and another is the 2.6 (or later) Linux kernel - tree. To synchronize both, the ALSA driver tree is split into - two different trees: alsa-kernel and alsa-driver. The former - contains purely the source code for the Linux 2.6 (or later) - tree. This tree is designed only for compilation on 2.6 or - later environment. The latter, alsa-driver, contains many subtle - files for compiling ALSA drivers outside of the Linux kernel tree, - wrapper functions for older 2.2 and 2.4 kernels, to adapt the latest kernel API, - and additional drivers which are still in development or in - tests. The drivers in alsa-driver tree will be moved to - alsa-kernel (and eventually to the 2.6 kernel tree) when they are - finished and confirmed to work fine. - </para> - - <para> - The file tree structure of ALSA driver is depicted below. Both - alsa-kernel and alsa-driver have almost the same file - structure, except for <quote>core</quote> directory. It's - named as <quote>acore</quote> in alsa-driver tree. - - <example> - <title>ALSA File Tree Structure</title> - <literallayout> - sound - /core - /oss - /seq - /oss - /instr - /ioctl32 - /include - /drivers - /mpu401 - /opl3 - /i2c - /l3 - /synth - /emux - /pci - /(cards) - /isa - /(cards) - /arm - /ppc - /sparc - /usb - /pcmcia /(cards) - /oss - </literallayout> - </example> - </para> - </section> - - <section id="file-tree-core-directory"> - <title>core directory</title> - <para> - This directory contains the middle layer which is the heart - of ALSA drivers. In this directory, the native ALSA modules are - stored. The sub-directories contain different modules and are - dependent upon the kernel config. - </para> - - <section id="file-tree-core-directory-oss"> - <title>core/oss</title> - - <para> - The codes for PCM and mixer OSS emulation modules are stored - in this directory. The rawmidi OSS emulation is included in - the ALSA rawmidi code since it's quite small. The sequencer - code is stored in <filename>core/seq/oss</filename> directory (see - <link linkend="file-tree-core-directory-seq-oss"><citetitle> - below</citetitle></link>). - </para> - </section> - - <section id="file-tree-core-directory-ioctl32"> - <title>core/ioctl32</title> - - <para> - This directory contains the 32bit-ioctl wrappers for 64bit - architectures such like x86-64, ppc64 and sparc64. For 32bit - and alpha architectures, these are not compiled. - </para> - </section> - - <section id="file-tree-core-directory-seq"> - <title>core/seq</title> - <para> - This directory and its sub-directories are for the ALSA - sequencer. This directory contains the sequencer core and - primary sequencer modules such like snd-seq-midi, - snd-seq-virmidi, etc. They are compiled only when - <constant>CONFIG_SND_SEQUENCER</constant> is set in the kernel - config. - </para> - </section> - - <section id="file-tree-core-directory-seq-oss"> - <title>core/seq/oss</title> - <para> - This contains the OSS sequencer emulation codes. - </para> - </section> - - <section id="file-tree-core-directory-deq-instr"> - <title>core/seq/instr</title> - <para> - This directory contains the modules for the sequencer - instrument layer. - </para> - </section> - </section> - - <section id="file-tree-include-directory"> - <title>include directory</title> - <para> - This is the place for the public header files of ALSA drivers, - which are to be exported to user-space, or included by - several files at different directories. Basically, the private - header files should not be placed in this directory, but you may - still find files there, due to historical reasons :) - </para> - </section> - - <section id="file-tree-drivers-directory"> - <title>drivers directory</title> - <para> - This directory contains code shared among different drivers - on different architectures. They are hence supposed not to be - architecture-specific. - For example, the dummy pcm driver and the serial MIDI - driver are found in this directory. In the sub-directories, - there is code for components which are independent from - bus and cpu architectures. - </para> - - <section id="file-tree-drivers-directory-mpu401"> - <title>drivers/mpu401</title> - <para> - The MPU401 and MPU401-UART modules are stored here. - </para> - </section> - - <section id="file-tree-drivers-directory-opl3"> - <title>drivers/opl3 and opl4</title> - <para> - The OPL3 and OPL4 FM-synth stuff is found here. - </para> - </section> - </section> - - <section id="file-tree-i2c-directory"> - <title>i2c directory</title> - <para> - This contains the ALSA i2c components. - </para> - - <para> - Although there is a standard i2c layer on Linux, ALSA has its - own i2c code for some cards, because the soundcard needs only a - simple operation and the standard i2c API is too complicated for - such a purpose. - </para> - - <section id="file-tree-i2c-directory-l3"> - <title>i2c/l3</title> - <para> - This is a sub-directory for ARM L3 i2c. - </para> - </section> - </section> - - <section id="file-tree-synth-directory"> - <title>synth directory</title> - <para> - This contains the synth middle-level modules. - </para> - - <para> - So far, there is only Emu8000/Emu10k1 synth driver under - the <filename>synth/emux</filename> sub-directory. - </para> - </section> - - <section id="file-tree-pci-directory"> - <title>pci directory</title> - <para> - This directory and its sub-directories hold the top-level card modules - for PCI soundcards and the code specific to the PCI BUS. - </para> - - <para> - The drivers compiled from a single file are stored directly - in the pci directory, while the drivers with several source files are - stored on their own sub-directory (e.g. emu10k1, ice1712). - </para> - </section> - - <section id="file-tree-isa-directory"> - <title>isa directory</title> - <para> - This directory and its sub-directories hold the top-level card modules - for ISA soundcards. - </para> - </section> - - <section id="file-tree-arm-ppc-sparc-directories"> - <title>arm, ppc, and sparc directories</title> - <para> - They are used for top-level card modules which are - specific to one of these architectures. - </para> - </section> - - <section id="file-tree-usb-directory"> - <title>usb directory</title> - <para> - This directory contains the USB-audio driver. In the latest version, the - USB MIDI driver is integrated in the usb-audio driver. - </para> - </section> - - <section id="file-tree-pcmcia-directory"> - <title>pcmcia directory</title> - <para> - The PCMCIA, especially PCCard drivers will go here. CardBus - drivers will be in the pci directory, because their API is identical - to that of standard PCI cards. - </para> - </section> - - <section id="file-tree-oss-directory"> - <title>oss directory</title> - <para> - The OSS/Lite source files are stored here in Linux 2.6 (or - later) tree. In the ALSA driver tarball, this directory is empty, - of course :) - </para> - </section> - </chapter> - - -<!-- ****************************************************** --> -<!-- Basic Flow for PCI Drivers --> -<!-- ****************************************************** --> - <chapter id="basic-flow"> - <title>Basic Flow for PCI Drivers</title> - - <section id="basic-flow-outline"> - <title>Outline</title> - <para> - The minimum flow for PCI soundcards is as follows: - - <itemizedlist> - <listitem><para>define the PCI ID table (see the section - <link linkend="pci-resource-entries"><citetitle>PCI Entries - </citetitle></link>).</para></listitem> - <listitem><para>create <function>probe()</function> callback.</para></listitem> - <listitem><para>create <function>remove()</function> callback.</para></listitem> - <listitem><para>create a <structname>pci_driver</structname> structure - containing the three pointers above.</para></listitem> - <listitem><para>create an <function>init()</function> function just calling - the <function>pci_register_driver()</function> to register the pci_driver table - defined above.</para></listitem> - <listitem><para>create an <function>exit()</function> function to call - the <function>pci_unregister_driver()</function> function.</para></listitem> - </itemizedlist> - </para> - </section> - - <section id="basic-flow-example"> - <title>Full Code Example</title> - <para> - The code example is shown below. Some parts are kept - unimplemented at this moment but will be filled in the - next sections. The numbers in the comment lines of the - <function>snd_mychip_probe()</function> function - refer to details explained in the following section. - - <example> - <title>Basic Flow for PCI Drivers - Example</title> - <programlisting> -<![CDATA[ - #include <linux/init.h> - #include <linux/pci.h> - #include <linux/slab.h> - #include <sound/core.h> - #include <sound/initval.h> - - /* module parameters (see "Module Parameters") */ - /* SNDRV_CARDS: maximum number of cards supported by this module */ - static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX; - static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR; - static bool enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP; - - /* definition of the chip-specific record */ - struct mychip { - struct snd_card *card; - /* the rest of the implementation will be in section - * "PCI Resource Management" - */ - }; - - /* chip-specific destructor - * (see "PCI Resource Management") - */ - static int snd_mychip_free(struct mychip *chip) - { - .... /* will be implemented later... */ - } - - /* component-destructor - * (see "Management of Cards and Components") - */ - static int snd_mychip_dev_free(struct snd_device *device) - { - return snd_mychip_free(device->device_data); - } - - /* chip-specific constructor - * (see "Management of Cards and Components") - */ - static int snd_mychip_create(struct snd_card *card, - struct pci_dev *pci, - struct mychip **rchip) - { - struct mychip *chip; - int err; - static struct snd_device_ops ops = { - .dev_free = snd_mychip_dev_free, - }; - - *rchip = NULL; - - /* check PCI availability here - * (see "PCI Resource Management") - */ - .... - - /* allocate a chip-specific data with zero filled */ - chip = kzalloc(sizeof(*chip), GFP_KERNEL); - if (chip == NULL) - return -ENOMEM; - - chip->card = card; - - /* rest of initialization here; will be implemented - * later, see "PCI Resource Management" - */ - .... - - err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops); - if (err < 0) { - snd_mychip_free(chip); - return err; - } - - *rchip = chip; - return 0; - } - - /* constructor -- see "Constructor" sub-section */ - static int snd_mychip_probe(struct pci_dev *pci, - const struct pci_device_id *pci_id) - { - static int dev; - struct snd_card *card; - struct mychip *chip; - int err; - - /* (1) */ - if (dev >= SNDRV_CARDS) - return -ENODEV; - if (!enable[dev]) { - dev++; - return -ENOENT; - } - - /* (2) */ - err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, - 0, &card); - if (err < 0) - return err; - - /* (3) */ - err = snd_mychip_create(card, pci, &chip); - if (err < 0) { - snd_card_free(card); - return err; - } - - /* (4) */ - strcpy(card->driver, "My Chip"); - strcpy(card->shortname, "My Own Chip 123"); - sprintf(card->longname, "%s at 0x%lx irq %i", - card->shortname, chip->ioport, chip->irq); - - /* (5) */ - .... /* implemented later */ - - /* (6) */ - err = snd_card_register(card); - if (err < 0) { - snd_card_free(card); - return err; - } - - /* (7) */ - pci_set_drvdata(pci, card); - dev++; - return 0; - } - - /* destructor -- see the "Destructor" sub-section */ - static void snd_mychip_remove(struct pci_dev *pci) - { - snd_card_free(pci_get_drvdata(pci)); - pci_set_drvdata(pci, NULL); - } -]]> - </programlisting> - </example> - </para> - </section> - - <section id="basic-flow-constructor"> - <title>Constructor</title> - <para> - The real constructor of PCI drivers is the <function>probe</function> callback. - The <function>probe</function> callback and other component-constructors which are called - from the <function>probe</function> callback cannot be used with - the <parameter>__init</parameter> prefix - because any PCI device could be a hotplug device. - </para> - - <para> - In the <function>probe</function> callback, the following scheme is often used. - </para> - - <section id="basic-flow-constructor-device-index"> - <title>1) Check and increment the device index.</title> - <para> - <informalexample> - <programlisting> -<![CDATA[ - static int dev; - .... - if (dev >= SNDRV_CARDS) - return -ENODEV; - if (!enable[dev]) { - dev++; - return -ENOENT; - } -]]> - </programlisting> - </informalexample> - - where enable[dev] is the module option. - </para> - - <para> - Each time the <function>probe</function> callback is called, check the - availability of the device. If not available, simply increment - the device index and returns. dev will be incremented also - later (<link - linkend="basic-flow-constructor-set-pci"><citetitle>step - 7</citetitle></link>). - </para> - </section> - - <section id="basic-flow-constructor-create-card"> - <title>2) Create a card instance</title> - <para> - <informalexample> - <programlisting> -<![CDATA[ - struct snd_card *card; - int err; - .... - err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, - 0, &card); -]]> - </programlisting> - </informalexample> - </para> - - <para> - The details will be explained in the section - <link linkend="card-management-card-instance"><citetitle> - Management of Cards and Components</citetitle></link>. - </para> - </section> - - <section id="basic-flow-constructor-create-main"> - <title>3) Create a main component</title> - <para> - In this part, the PCI resources are allocated. - - <informalexample> - <programlisting> -<![CDATA[ - struct mychip *chip; - .... - err = snd_mychip_create(card, pci, &chip); - if (err < 0) { - snd_card_free(card); - return err; - } -]]> - </programlisting> - </informalexample> - - The details will be explained in the section <link - linkend="pci-resource"><citetitle>PCI Resource - Management</citetitle></link>. - </para> - </section> - - <section id="basic-flow-constructor-main-component"> - <title>4) Set the driver ID and name strings.</title> - <para> - <informalexample> - <programlisting> -<![CDATA[ - strcpy(card->driver, "My Chip"); - strcpy(card->shortname, "My Own Chip 123"); - sprintf(card->longname, "%s at 0x%lx irq %i", - card->shortname, chip->ioport, chip->irq); -]]> - </programlisting> - </informalexample> - - The driver field holds the minimal ID string of the - chip. This is used by alsa-lib's configurator, so keep it - simple but unique. - Even the same driver can have different driver IDs to - distinguish the functionality of each chip type. - </para> - - <para> - The shortname field is a string shown as more verbose - name. The longname field contains the information - shown in <filename>/proc/asound/cards</filename>. - </para> - </section> - - <section id="basic-flow-constructor-create-other"> - <title>5) Create other components, such as mixer, MIDI, etc.</title> - <para> - Here you define the basic components such as - <link linkend="pcm-interface"><citetitle>PCM</citetitle></link>, - mixer (e.g. <link linkend="api-ac97"><citetitle>AC97</citetitle></link>), - MIDI (e.g. <link linkend="midi-interface"><citetitle>MPU-401</citetitle></link>), - and other interfaces. - Also, if you want a <link linkend="proc-interface"><citetitle>proc - file</citetitle></link>, define it here, too. - </para> - </section> - - <section id="basic-flow-constructor-register-card"> - <title>6) Register the card instance.</title> - <para> - <informalexample> - <programlisting> -<![CDATA[ - err = snd_card_register(card); - if (err < 0) { - snd_card_free(card); - return err; - } -]]> - </programlisting> - </informalexample> - </para> - - <para> - Will be explained in the section <link - linkend="card-management-registration"><citetitle>Management - of Cards and Components</citetitle></link>, too. - </para> - </section> - - <section id="basic-flow-constructor-set-pci"> - <title>7) Set the PCI driver data and return zero.</title> - <para> - <informalexample> - <programlisting> -<![CDATA[ - pci_set_drvdata(pci, card); - dev++; - return 0; -]]> - </programlisting> - </informalexample> - - In the above, the card record is stored. This pointer is - used in the remove callback and power-management - callbacks, too. - </para> - </section> - </section> - - <section id="basic-flow-destructor"> - <title>Destructor</title> - <para> - The destructor, remove callback, simply releases the card - instance. Then the ALSA middle layer will release all the - attached components automatically. - </para> - - <para> - It would be typically like the following: - - <informalexample> - <programlisting> -<![CDATA[ - static void snd_mychip_remove(struct pci_dev *pci) - { - snd_card_free(pci_get_drvdata(pci)); - pci_set_drvdata(pci, NULL); - } -]]> - </programlisting> - </informalexample> - - The above code assumes that the card pointer is set to the PCI - driver data. - </para> - </section> - - <section id="basic-flow-header-files"> - <title>Header Files</title> - <para> - For the above example, at least the following include files - are necessary. - - <informalexample> - <programlisting> -<![CDATA[ - #include <linux/init.h> - #include <linux/pci.h> - #include <linux/slab.h> - #include <sound/core.h> - #include <sound/initval.h> -]]> - </programlisting> - </informalexample> - - where the last one is necessary only when module options are - defined in the source file. If the code is split into several - files, the files without module options don't need them. - </para> - - <para> - In addition to these headers, you'll need - <filename><linux/interrupt.h></filename> for interrupt - handling, and <filename><asm/io.h></filename> for I/O - access. If you use the <function>mdelay()</function> or - <function>udelay()</function> functions, you'll need to include - <filename><linux/delay.h></filename> too. - </para> - - <para> - The ALSA interfaces like the PCM and control APIs are defined in other - <filename><sound/xxx.h></filename> header files. - They have to be included after - <filename><sound/core.h></filename>. - </para> - - </section> - </chapter> - - -<!-- ****************************************************** --> -<!-- Management of Cards and Components --> -<!-- ****************************************************** --> - <chapter id="card-management"> - <title>Management of Cards and Components</title> - - <section id="card-management-card-instance"> - <title>Card Instance</title> - <para> - For each soundcard, a <quote>card</quote> record must be allocated. - </para> - - <para> - A card record is the headquarters of the soundcard. It manages - the whole list of devices (components) on the soundcard, such as - PCM, mixers, MIDI, synthesizer, and so on. Also, the card - record holds the ID and the name strings of the card, manages - the root of proc files, and controls the power-management states - and hotplug disconnections. The component list on the card - record is used to manage the correct release of resources at - destruction. - </para> - - <para> - As mentioned above, to create a card instance, call - <function>snd_card_new()</function>. - - <informalexample> - <programlisting> -<![CDATA[ - struct snd_card *card; - int err; - err = snd_card_new(&pci->dev, index, id, module, extra_size, &card); -]]> - </programlisting> - </informalexample> - </para> - - <para> - The function takes six arguments: the parent device pointer, - the card-index number, the id string, the module pointer (usually - <constant>THIS_MODULE</constant>), - the size of extra-data space, and the pointer to return the - card instance. The extra_size argument is used to - allocate card->private_data for the - chip-specific data. Note that these data - are allocated by <function>snd_card_new()</function>. - </para> - - <para> - The first argument, the pointer of struct - <structname>device</structname>, specifies the parent device. - For PCI devices, typically &pci-> is passed there. - </para> - </section> - - <section id="card-management-component"> - <title>Components</title> - <para> - After the card is created, you can attach the components - (devices) to the card instance. In an ALSA driver, a component is - represented as a struct <structname>snd_device</structname> object. - A component can be a PCM instance, a control interface, a raw - MIDI interface, etc. Each such instance has one component - entry. - </para> - - <para> - A component can be created via - <function>snd_device_new()</function> function. - - <informalexample> - <programlisting> -<![CDATA[ - snd_device_new(card, SNDRV_DEV_XXX, chip, &ops); -]]> - </programlisting> - </informalexample> - </para> - - <para> - This takes the card pointer, the device-level - (<constant>SNDRV_DEV_XXX</constant>), the data pointer, and the - callback pointers (<parameter>&ops</parameter>). The - device-level defines the type of components and the order of - registration and de-registration. For most components, the - device-level is already defined. For a user-defined component, - you can use <constant>SNDRV_DEV_LOWLEVEL</constant>. - </para> - - <para> - This function itself doesn't allocate the data space. The data - must be allocated manually beforehand, and its pointer is passed - as the argument. This pointer (<parameter>chip</parameter> in the - above example) is used as the identifier for the instance. - </para> - - <para> - Each pre-defined ALSA component such as ac97 and pcm calls - <function>snd_device_new()</function> inside its - constructor. The destructor for each component is defined in the - callback pointers. Hence, you don't need to take care of - calling a destructor for such a component. - </para> - - <para> - If you wish to create your own component, you need to - set the destructor function to the dev_free callback in - the <parameter>ops</parameter>, so that it can be released - automatically via <function>snd_card_free()</function>. - The next example will show an implementation of chip-specific - data. - </para> - </section> - - <section id="card-management-chip-specific"> - <title>Chip-Specific Data</title> - <para> - Chip-specific information, e.g. the I/O port address, its - resource pointer, or the irq number, is stored in the - chip-specific record. - - <informalexample> - <programlisting> -<![CDATA[ - struct mychip { - .... - }; -]]> - </programlisting> - </informalexample> - </para> - - <para> - In general, there are two ways of allocating the chip record. - </para> - - <section id="card-management-chip-specific-snd-card-new"> - <title>1. Allocating via <function>snd_card_new()</function>.</title> - <para> - As mentioned above, you can pass the extra-data-length - to the 5th argument of <function>snd_card_new()</function>, i.e. - - <informalexample> - <programlisting> -<![CDATA[ - err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, - sizeof(struct mychip), &card); -]]> - </programlisting> - </informalexample> - - struct <structname>mychip</structname> is the type of the chip record. - </para> - - <para> - In return, the allocated record can be accessed as - - <informalexample> - <programlisting> -<![CDATA[ - struct mychip *chip = card->private_data; -]]> - </programlisting> - </informalexample> - - With this method, you don't have to allocate twice. - The record is released together with the card instance. - </para> - </section> - - <section id="card-management-chip-specific-allocate-extra"> - <title>2. Allocating an extra device.</title> - - <para> - After allocating a card instance via - <function>snd_card_new()</function> (with - <constant>0</constant> on the 4th arg), call - <function>kzalloc()</function>. - - <informalexample> - <programlisting> -<![CDATA[ - struct snd_card *card; - struct mychip *chip; - err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, - 0, &card); - ..... - chip = kzalloc(sizeof(*chip), GFP_KERNEL); -]]> - </programlisting> - </informalexample> - </para> - - <para> - The chip record should have the field to hold the card - pointer at least, - - <informalexample> - <programlisting> -<![CDATA[ - struct mychip { - struct snd_card *card; - .... - }; -]]> - </programlisting> - </informalexample> - </para> - - <para> - Then, set the card pointer in the returned chip instance. - - <informalexample> - <programlisting> -<![CDATA[ - chip->card = card; -]]> - </programlisting> - </informalexample> - </para> - - <para> - Next, initialize the fields, and register this chip - record as a low-level device with a specified - <parameter>ops</parameter>, - - <informalexample> - <programlisting> -<![CDATA[ - static struct snd_device_ops ops = { - .dev_free = snd_mychip_dev_free, - }; - .... - snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops); -]]> - </programlisting> - </informalexample> - - <function>snd_mychip_dev_free()</function> is the - device-destructor function, which will call the real - destructor. - </para> - - <para> - <informalexample> - <programlisting> -<![CDATA[ - static int snd_mychip_dev_free(struct snd_device *device) - { - return snd_mychip_free(device->device_data); - } -]]> - </programlisting> - </informalexample> - - where <function>snd_mychip_free()</function> is the real destructor. - </para> - </section> - </section> - - <section id="card-management-registration"> - <title>Registration and Release</title> - <para> - After all components are assigned, register the card instance - by calling <function>snd_card_register()</function>. Access - to the device files is enabled at this point. That is, before - <function>snd_card_register()</function> is called, the - components are safely inaccessible from external side. If this - call fails, exit the probe function after releasing the card via - <function>snd_card_free()</function>. - </para> - - <para> - For releasing the card instance, you can call simply - <function>snd_card_free()</function>. As mentioned earlier, all - components are released automatically by this call. - </para> - - <para> - For a device which allows hotplugging, you can use - <function>snd_card_free_when_closed</function>. This one will - postpone the destruction until all devices are closed. - </para> - - </section> - - </chapter> - - -<!-- ****************************************************** --> -<!-- PCI Resource Management --> -<!-- ****************************************************** --> - <chapter id="pci-resource"> - <title>PCI Resource Management</title> - - <section id="pci-resource-example"> - <title>Full Code Example</title> - <para> - In this section, we'll complete the chip-specific constructor, - destructor and PCI entries. Example code is shown first, - below. - - <example> - <title>PCI Resource Management Example</title> - <programlisting> -<![CDATA[ - struct mychip { - struct snd_card *card; - struct pci_dev *pci; - - unsigned long port; - int irq; - }; - - static int snd_mychip_free(struct mychip *chip) - { - /* disable hardware here if any */ - .... /* (not implemented in this document) */ - - /* release the irq */ - if (chip->irq >= 0) - free_irq(chip->irq, chip); - /* release the I/O ports & memory */ - pci_release_regions(chip->pci); - /* disable the PCI entry */ - pci_disable_device(chip->pci); - /* release the data */ - kfree(chip); - return 0; - } - - /* chip-specific constructor */ - static int snd_mychip_create(struct snd_card *card, - struct pci_dev *pci, - struct mychip **rchip) - { - struct mychip *chip; - int err; - static struct snd_device_ops ops = { - .dev_free = snd_mychip_dev_free, - }; - - *rchip = NULL; - - /* initialize the PCI entry */ - err = pci_enable_device(pci); - if (err < 0) - return err; - /* check PCI availability (28bit DMA) */ - if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 || - pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) { - printk(KERN_ERR "error to set 28bit mask DMA\n"); - pci_disable_device(pci); - return -ENXIO; - } - - chip = kzalloc(sizeof(*chip), GFP_KERNEL); - if (chip == NULL) { - pci_disable_device(pci); - return -ENOMEM; - } - - /* initialize the stuff */ - chip->card = card; - chip->pci = pci; - chip->irq = -1; - - /* (1) PCI resource allocation */ - err = pci_request_regions(pci, "My Chip"); - if (err < 0) { - kfree(chip); - pci_disable_device(pci); - return err; - } - chip->port = pci_resource_start(pci, 0); - if (request_irq(pci->irq, snd_mychip_interrupt, - IRQF_SHARED, KBUILD_MODNAME, chip)) { - printk(KERN_ERR "cannot grab irq %d\n", pci->irq); - snd_mychip_free(chip); - return -EBUSY; - } - chip->irq = pci->irq; - - /* (2) initialization of the chip hardware */ - .... /* (not implemented in this document) */ - - err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops); - if (err < 0) { - snd_mychip_free(chip); - return err; - } - - *rchip = chip; - return 0; - } - - /* PCI IDs */ - static struct pci_device_id snd_mychip_ids[] = { - { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR, - PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, }, - .... - { 0, } - }; - MODULE_DEVICE_TABLE(pci, snd_mychip_ids); - - /* pci_driver definition */ - static struct pci_driver driver = { - .name = KBUILD_MODNAME, - .id_table = snd_mychip_ids, - .probe = snd_mychip_probe, - .remove = snd_mychip_remove, - }; - - /* module initialization */ - static int __init alsa_card_mychip_init(void) - { - return pci_register_driver(&driver); - } - - /* module clean up */ - static void __exit alsa_card_mychip_exit(void) - { - pci_unregister_driver(&driver); - } - - module_init(alsa_card_mychip_init) - module_exit(alsa_card_mychip_exit) - - EXPORT_NO_SYMBOLS; /* for old kernels only */ -]]> - </programlisting> - </example> - </para> - </section> - - <section id="pci-resource-some-haftas"> - <title>Some Hafta's</title> - <para> - The allocation of PCI resources is done in the - <function>probe()</function> function, and usually an extra - <function>xxx_create()</function> function is written for this - purpose. - </para> - - <para> - In the case of PCI devices, you first have to call - the <function>pci_enable_device()</function> function before - allocating resources. Also, you need to set the proper PCI DMA - mask to limit the accessed I/O range. In some cases, you might - need to call <function>pci_set_master()</function> function, - too. - </para> - - <para> - Suppose the 28bit mask, and the code to be added would be like: - - <informalexample> - <programlisting> -<![CDATA[ - err = pci_enable_device(pci); - if (err < 0) - return err; - if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 || - pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) { - printk(KERN_ERR "error to set 28bit mask DMA\n"); - pci_disable_device(pci); - return -ENXIO; - } - -]]> - </programlisting> - </informalexample> - </para> - </section> - - <section id="pci-resource-resource-allocation"> - <title>Resource Allocation</title> - <para> - The allocation of I/O ports and irqs is done via standard kernel - functions. Unlike ALSA ver.0.5.x., there are no helpers for - that. And these resources must be released in the destructor - function (see below). Also, on ALSA 0.9.x, you don't need to - allocate (pseudo-)DMA for PCI like in ALSA 0.5.x. - </para> - - <para> - Now assume that the PCI device has an I/O port with 8 bytes - and an interrupt. Then struct <structname>mychip</structname> will have the - following fields: - - <informalexample> - <programlisting> -<![CDATA[ - struct mychip { - struct snd_card *card; - - unsigned long port; - int irq; - }; -]]> - </programlisting> - </informalexample> - </para> - - <para> - For an I/O port (and also a memory region), you need to have - the resource pointer for the standard resource management. For - an irq, you have to keep only the irq number (integer). But you - need to initialize this number as -1 before actual allocation, - since irq 0 is valid. The port address and its resource pointer - can be initialized as null by - <function>kzalloc()</function> automatically, so you - don't have to take care of resetting them. - </para> - - <para> - The allocation of an I/O port is done like this: - - <informalexample> - <programlisting> -<![CDATA[ - err = pci_request_regions(pci, "My Chip"); - if (err < 0) { - kfree(chip); - pci_disable_device(pci); - return err; - } - chip->port = pci_resource_start(pci, 0); -]]> - </programlisting> - </informalexample> - </para> - - <para> - <!-- obsolete --> - It will reserve the I/O port region of 8 bytes of the given - PCI device. The returned value, chip->res_port, is allocated - via <function>kmalloc()</function> by - <function>request_region()</function>. The pointer must be - released via <function>kfree()</function>, but there is a - problem with this. This issue will be explained later. - </para> - - <para> - The allocation of an interrupt source is done like this: - - <informalexample> - <programlisting> -<![CDATA[ - if (request_irq(pci->irq, snd_mychip_interrupt, - IRQF_SHARED, KBUILD_MODNAME, chip)) { - printk(KERN_ERR "cannot grab irq %d\n", pci->irq); - snd_mychip_free(chip); - return -EBUSY; - } - chip->irq = pci->irq; -]]> - </programlisting> - </informalexample> - - where <function>snd_mychip_interrupt()</function> is the - interrupt handler defined <link - linkend="pcm-interface-interrupt-handler"><citetitle>later</citetitle></link>. - Note that chip->irq should be defined - only when <function>request_irq()</function> succeeded. - </para> - - <para> - On the PCI bus, interrupts can be shared. Thus, - <constant>IRQF_SHARED</constant> is used as the interrupt flag of - <function>request_irq()</function>. - </para> - - <para> - The last argument of <function>request_irq()</function> is the - data pointer passed to the interrupt handler. Usually, the - chip-specific record is used for that, but you can use what you - like, too. - </para> - - <para> - I won't give details about the interrupt handler at this - point, but at least its appearance can be explained now. The - interrupt handler looks usually like the following: - - <informalexample> - <programlisting> -<![CDATA[ - static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id) - { - struct mychip *chip = dev_id; - .... - return IRQ_HANDLED; - } -]]> - </programlisting> - </informalexample> - </para> - - <para> - Now let's write the corresponding destructor for the resources - above. The role of destructor is simple: disable the hardware - (if already activated) and release the resources. So far, we - have no hardware part, so the disabling code is not written here. - </para> - - <para> - To release the resources, the <quote>check-and-release</quote> - method is a safer way. For the interrupt, do like this: - - <informalexample> - <programlisting> -<![CDATA[ - if (chip->irq >= 0) - free_irq(chip->irq, chip); -]]> - </programlisting> - </informalexample> - - Since the irq number can start from 0, you should initialize - chip->irq with a negative value (e.g. -1), so that you can - check the validity of the irq number as above. - </para> - - <para> - When you requested I/O ports or memory regions via - <function>pci_request_region()</function> or - <function>pci_request_regions()</function> like in this example, - release the resource(s) using the corresponding function, - <function>pci_release_region()</function> or - <function>pci_release_regions()</function>. - - <informalexample> - <programlisting> -<![CDATA[ - pci_release_regions(chip->pci); -]]> - </programlisting> - </informalexample> - </para> - - <para> - When you requested manually via <function>request_region()</function> - or <function>request_mem_region</function>, you can release it via - <function>release_resource()</function>. Suppose that you keep - the resource pointer returned from <function>request_region()</function> - in chip->res_port, the release procedure looks like: - - <informalexample> - <programlisting> -<![CDATA[ - release_and_free_resource(chip->res_port); -]]> - </programlisting> - </informalexample> - </para> - - <para> - Don't forget to call <function>pci_disable_device()</function> - before the end. - </para> - - <para> - And finally, release the chip-specific record. - - <informalexample> - <programlisting> -<![CDATA[ - kfree(chip); -]]> - </programlisting> - </informalexample> - </para> - - <para> - We didn't implement the hardware disabling part in the above. - If you need to do this, please note that the destructor may be - called even before the initialization of the chip is completed. - It would be better to have a flag to skip hardware disabling - if the hardware was not initialized yet. - </para> - - <para> - When the chip-data is assigned to the card using - <function>snd_device_new()</function> with - <constant>SNDRV_DEV_LOWLELVEL</constant> , its destructor is - called at the last. That is, it is assured that all other - components like PCMs and controls have already been released. - You don't have to stop PCMs, etc. explicitly, but just - call low-level hardware stopping. - </para> - - <para> - The management of a memory-mapped region is almost as same as - the management of an I/O port. You'll need three fields like - the following: - - <informalexample> - <programlisting> -<![CDATA[ - struct mychip { - .... - unsigned long iobase_phys; - void __iomem *iobase_virt; - }; -]]> - </programlisting> - </informalexample> - - and the allocation would be like below: - - <informalexample> - <programlisting> -<![CDATA[ - if ((err = pci_request_regions(pci, "My Chip")) < 0) { - kfree(chip); - return err; - } - chip->iobase_phys = pci_resource_start(pci, 0); - chip->iobase_virt = ioremap_nocache(chip->iobase_phys, - pci_resource_len(pci, 0)); -]]> - </programlisting> - </informalexample> - - and the corresponding destructor would be: - - <informalexample> - <programlisting> -<![CDATA[ - static int snd_mychip_free(struct mychip *chip) - { - .... - if (chip->iobase_virt) - iounmap(chip->iobase_virt); - .... - pci_release_regions(chip->pci); - .... - } -]]> - </programlisting> - </informalexample> - </para> - - </section> - - <section id="pci-resource-entries"> - <title>PCI Entries</title> - <para> - So far, so good. Let's finish the missing PCI - stuff. At first, we need a - <structname>pci_device_id</structname> table for this - chipset. It's a table of PCI vendor/device ID number, and some - masks. - </para> - - <para> - For example, - - <informalexample> - <programlisting> -<![CDATA[ - static struct pci_device_id snd_mychip_ids[] = { - { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR, - PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, }, - .... - { 0, } - }; - MODULE_DEVICE_TABLE(pci, snd_mychip_ids); -]]> - </programlisting> - </informalexample> - </para> - - <para> - The first and second fields of - the <structname>pci_device_id</structname> structure are the vendor and - device IDs. If you have no reason to filter the matching - devices, you can leave the remaining fields as above. The last - field of the <structname>pci_device_id</structname> struct contains - private data for this entry. You can specify any value here, for - example, to define specific operations for supported device IDs. - Such an example is found in the intel8x0 driver. - </para> - - <para> - The last entry of this list is the terminator. You must - specify this all-zero entry. - </para> - - <para> - Then, prepare the <structname>pci_driver</structname> record: - - <informalexample> - <programlisting> -<![CDATA[ - static struct pci_driver driver = { - .name = KBUILD_MODNAME, - .id_table = snd_mychip_ids, - .probe = snd_mychip_probe, - .remove = snd_mychip_remove, - }; -]]> - </programlisting> - </informalexample> - </para> - - <para> - The <structfield>probe</structfield> and - <structfield>remove</structfield> functions have already - been defined in the previous sections. - The <structfield>name</structfield> - field is the name string of this device. Note that you must not - use a slash <quote>/</quote> in this string. - </para> - - <para> - And at last, the module entries: - - <informalexample> - <programlisting> -<![CDATA[ - static int __init alsa_card_mychip_init(void) - { - return pci_register_driver(&driver); - } - - static void __exit alsa_card_mychip_exit(void) - { - pci_unregister_driver(&driver); - } - - module_init(alsa_card_mychip_init) - module_exit(alsa_card_mychip_exit) -]]> - </programlisting> - </informalexample> - </para> - - <para> - Note that these module entries are tagged with - <parameter>__init</parameter> and - <parameter>__exit</parameter> prefixes. - </para> - - <para> - Oh, one thing was forgotten. If you have no exported symbols, - you need to declare it in 2.2 or 2.4 kernels (it's not necessary in 2.6 kernels). - - <informalexample> - <programlisting> -<![CDATA[ - EXPORT_NO_SYMBOLS; -]]> - </programlisting> - </informalexample> - - That's all! - </para> - </section> - </chapter> - - -<!-- ****************************************************** --> -<!-- PCM Interface --> -<!-- ****************************************************** --> - <chapter id="pcm-interface"> - <title>PCM Interface</title> - - <section id="pcm-interface-general"> - <title>General</title> - <para> - The PCM middle layer of ALSA is quite powerful and it is only - necessary for each driver to implement the low-level functions - to access its hardware. - </para> - - <para> - For accessing to the PCM layer, you need to include - <filename><sound/pcm.h></filename> first. In addition, - <filename><sound/pcm_params.h></filename> might be needed - if you access to some functions related with hw_param. - </para> - - <para> - Each card device can have up to four pcm instances. A pcm - instance corresponds to a pcm device file. The limitation of - number of instances comes only from the available bit size of - the Linux's device numbers. Once when 64bit device number is - used, we'll have more pcm instances available. - </para> - - <para> - A pcm instance consists of pcm playback and capture streams, - and each pcm stream consists of one or more pcm substreams. Some - soundcards support multiple playback functions. For example, - emu10k1 has a PCM playback of 32 stereo substreams. In this case, at - each open, a free substream is (usually) automatically chosen - and opened. Meanwhile, when only one substream exists and it was - already opened, the successful open will either block - or error with <constant>EAGAIN</constant> according to the - file open mode. But you don't have to care about such details in your - driver. The PCM middle layer will take care of such work. - </para> - </section> - - <section id="pcm-interface-example"> - <title>Full Code Example</title> - <para> - The example code below does not include any hardware access - routines but shows only the skeleton, how to build up the PCM - interfaces. - - <example> - <title>PCM Example Code</title> - <programlisting> -<![CDATA[ - #include <sound/pcm.h> - .... - - /* hardware definition */ - static struct snd_pcm_hardware snd_mychip_playback_hw = { - .info = (SNDRV_PCM_INFO_MMAP | - SNDRV_PCM_INFO_INTERLEAVED | - SNDRV_PCM_INFO_BLOCK_TRANSFER | - SNDRV_PCM_INFO_MMAP_VALID), - .formats = SNDRV_PCM_FMTBIT_S16_LE, - .rates = SNDRV_PCM_RATE_8000_48000, - .rate_min = 8000, - .rate_max = 48000, - .channels_min = 2, - .channels_max = 2, - .buffer_bytes_max = 32768, - .period_bytes_min = 4096, - .period_bytes_max = 32768, - .periods_min = 1, - .periods_max = 1024, - }; - - /* hardware definition */ - static struct snd_pcm_hardware snd_mychip_capture_hw = { - .info = (SNDRV_PCM_INFO_MMAP | - SNDRV_PCM_INFO_INTERLEAVED | - SNDRV_PCM_INFO_BLOCK_TRANSFER | - SNDRV_PCM_INFO_MMAP_VALID), - .formats = SNDRV_PCM_FMTBIT_S16_LE, - .rates = SNDRV_PCM_RATE_8000_48000, - .rate_min = 8000, - .rate_max = 48000, - .channels_min = 2, - .channels_max = 2, - .buffer_bytes_max = 32768, - .period_bytes_min = 4096, - .period_bytes_max = 32768, - .periods_min = 1, - .periods_max = 1024, - }; - - /* open callback */ - static int snd_mychip_playback_open(struct snd_pcm_substream *substream) - { - struct mychip *chip = snd_pcm_substream_chip(substream); - struct snd_pcm_runtime *runtime = substream->runtime; - - runtime->hw = snd_mychip_playback_hw; - /* more hardware-initialization will be done here */ - .... - return 0; - } - - /* close callback */ - static int snd_mychip_playback_close(struct snd_pcm_substream *substream) - { - struct mychip *chip = snd_pcm_substream_chip(substream); - /* the hardware-specific codes will be here */ - .... - return 0; - - } - - /* open callback */ - static int snd_mychip_capture_open(struct snd_pcm_substream *substream) - { - struct mychip *chip = snd_pcm_substream_chip(substream); - struct snd_pcm_runtime *runtime = substream->runtime; - - runtime->hw = snd_mychip_capture_hw; - /* more hardware-initialization will be done here */ - .... - return 0; - } - - /* close callback */ - static int snd_mychip_capture_close(struct snd_pcm_substream *substream) - { - struct mychip *chip = snd_pcm_substream_chip(substream); - /* the hardware-specific codes will be here */ - .... - return 0; - - } - - /* hw_params callback */ - static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream, - struct snd_pcm_hw_params *hw_params) - { - return snd_pcm_lib_malloc_pages(substream, - params_buffer_bytes(hw_params)); - } - - /* hw_free callback */ - static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream) - { - return snd_pcm_lib_free_pages(substream); - } - - /* prepare callback */ - static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream) - { - struct mychip *chip = snd_pcm_substream_chip(substream); - struct snd_pcm_runtime *runtime = substream->runtime; - - /* set up the hardware with the current configuration - * for example... - */ - mychip_set_sample_format(chip, runtime->format); - mychip_set_sample_rate(chip, runtime->rate); - mychip_set_channels(chip, runtime->channels); - mychip_set_dma_setup(chip, runtime->dma_addr, - chip->buffer_size, - chip->period_size); - return 0; - } - - /* trigger callback */ - static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream, - int cmd) - { - switch (cmd) { - case SNDRV_PCM_TRIGGER_START: - /* do something to start the PCM engine */ - .... - break; - case SNDRV_PCM_TRIGGER_STOP: - /* do something to stop the PCM engine */ - .... - break; - default: - return -EINVAL; - } - } - - /* pointer callback */ - static snd_pcm_uframes_t - snd_mychip_pcm_pointer(struct snd_pcm_substream *substream) - { - struct mychip *chip = snd_pcm_substream_chip(substream); - unsigned int current_ptr; - - /* get the current hardware pointer */ - current_ptr = mychip_get_hw_pointer(chip); - return current_ptr; - } - - /* operators */ - static struct snd_pcm_ops snd_mychip_playback_ops = { - .open = snd_mychip_playback_open, - .close = snd_mychip_playback_close, - .ioctl = snd_pcm_lib_ioctl, - .hw_params = snd_mychip_pcm_hw_params, - .hw_free = snd_mychip_pcm_hw_free, - .prepare = snd_mychip_pcm_prepare, - .trigger = snd_mychip_pcm_trigger, - .pointer = snd_mychip_pcm_pointer, - }; - - /* operators */ - static struct snd_pcm_ops snd_mychip_capture_ops = { - .open = snd_mychip_capture_open, - .close = snd_mychip_capture_close, - .ioctl = snd_pcm_lib_ioctl, - .hw_params = snd_mychip_pcm_hw_params, - .hw_free = snd_mychip_pcm_hw_free, - .prepare = snd_mychip_pcm_prepare, - .trigger = snd_mychip_pcm_trigger, - .pointer = snd_mychip_pcm_pointer, - }; - - /* - * definitions of capture are omitted here... - */ - - /* create a pcm device */ - static int snd_mychip_new_pcm(struct mychip *chip) - { - struct snd_pcm *pcm; - int err; - - err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm); - if (err < 0) - return err; - pcm->private_data = chip; - strcpy(pcm->name, "My Chip"); - chip->pcm = pcm; - /* set operators */ - snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK, - &snd_mychip_playback_ops); - snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE, - &snd_mychip_capture_ops); - /* pre-allocation of buffers */ - /* NOTE: this may fail */ - snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV, - snd_dma_pci_data(chip->pci), - 64*1024, 64*1024); - return 0; - } -]]> - </programlisting> - </example> - </para> - </section> - - <section id="pcm-interface-constructor"> - <title>Constructor</title> - <para> - A pcm instance is allocated by the <function>snd_pcm_new()</function> - function. It would be better to create a constructor for pcm, - namely, - - <informalexample> - <programlisting> -<![CDATA[ - static int snd_mychip_new_pcm(struct mychip *chip) - { - struct snd_pcm *pcm; - int err; - - err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm); - if (err < 0) - return err; - pcm->private_data = chip; - strcpy(pcm->name, "My Chip"); - chip->pcm = pcm; - .... - return 0; - } -]]> - </programlisting> - </informalexample> - </para> - - <para> - The <function>snd_pcm_new()</function> function takes four - arguments. The first argument is the card pointer to which this - pcm is assigned, and the second is the ID string. - </para> - - <para> - The third argument (<parameter>index</parameter>, 0 in the - above) is the index of this new pcm. It begins from zero. If - you create more than one pcm instances, specify the - different numbers in this argument. For example, - <parameter>index</parameter> = 1 for the second PCM device. - </para> - - <para> - The fourth and fifth arguments are the number of substreams - for playback and capture, respectively. Here 1 is used for - both arguments. When no playback or capture substreams are available, - pass 0 to the corresponding argument. - </para> - - <para> - If a chip supports multiple playbacks or captures, you can - specify more numbers, but they must be handled properly in - open/close, etc. callbacks. When you need to know which - substream you are referring to, then it can be obtained from - struct <structname>snd_pcm_substream</structname> data passed to each callback - as follows: - - <informalexample> - <programlisting> -<![CDATA[ - struct snd_pcm_substream *substream; - int index = substream->number; -]]> - </programlisting> - </informalexample> - </para> - - <para> - After the pcm is created, you need to set operators for each - pcm stream. - - <informalexample> - <programlisting> -<![CDATA[ - snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK, - &snd_mychip_playback_ops); - snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE, - &snd_mychip_capture_ops); -]]> - </programlisting> - </informalexample> - </para> - - <para> - The operators are defined typically like this: - - <informalexample> - <programlisting> -<![CDATA[ - static struct snd_pcm_ops snd_mychip_playback_ops = { - .open = snd_mychip_pcm_open, - .close = snd_mychip_pcm_close, - .ioctl = snd_pcm_lib_ioctl, - .hw_params = snd_mychip_pcm_hw_params, - .hw_free = snd_mychip_pcm_hw_free, - .prepare = snd_mychip_pcm_prepare, - .trigger = snd_mychip_pcm_trigger, - .pointer = snd_mychip_pcm_pointer, - }; -]]> - </programlisting> - </informalexample> - - All the callbacks are described in the - <link linkend="pcm-interface-operators"><citetitle> - Operators</citetitle></link> subsection. - </para> - - <para> - After setting the operators, you probably will want to - pre-allocate the buffer. For the pre-allocation, simply call - the following: - - <informalexample> - <programlisting> -<![CDATA[ - snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV, - snd_dma_pci_data(chip->pci), - 64*1024, 64*1024); -]]> - </programlisting> - </informalexample> - - It will allocate a buffer up to 64kB as default. - Buffer management details will be described in the later section <link - linkend="buffer-and-memory"><citetitle>Buffer and Memory - Management</citetitle></link>. - </para> - - <para> - Additionally, you can set some extra information for this pcm - in pcm->info_flags. - The available values are defined as - <constant>SNDRV_PCM_INFO_XXX</constant> in - <filename><sound/asound.h></filename>, which is used for - the hardware definition (described later). When your soundchip - supports only half-duplex, specify like this: - - <informalexample> - <programlisting> -<![CDATA[ - pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX; -]]> - </programlisting> - </informalexample> - </para> - </section> - - <section id="pcm-interface-destructor"> - <title>... And the Destructor?</title> - <para> - The destructor for a pcm instance is not always - necessary. Since the pcm device will be released by the middle - layer code automatically, you don't have to call the destructor - explicitly. - </para> - - <para> - The destructor would be necessary if you created - special records internally and needed to release them. In such a - case, set the destructor function to - pcm->private_free: - - <example> - <title>PCM Instance with a Destructor</title> - <programlisting> -<![CDATA[ - static void mychip_pcm_free(struct snd_pcm *pcm) - { - struct mychip *chip = snd_pcm_chip(pcm); - /* free your own data */ - kfree(chip->my_private_pcm_data); - /* do what you like else */ - .... - } - - static int snd_mychip_new_pcm(struct mychip *chip) - { - struct snd_pcm *pcm; - .... - /* allocate your own data */ - chip->my_private_pcm_data = kmalloc(...); - /* set the destructor */ - pcm->private_data = chip; - pcm->private_free = mychip_pcm_free; - .... - } -]]> - </programlisting> - </example> - </para> - </section> - - <section id="pcm-interface-runtime"> - <title>Runtime Pointer - The Chest of PCM Information</title> - <para> - When the PCM substream is opened, a PCM runtime instance is - allocated and assigned to the substream. This pointer is - accessible via <constant>substream->runtime</constant>. - This runtime pointer holds most information you need - to control the PCM: the copy of hw_params and sw_params configurations, the buffer - pointers, mmap records, spinlocks, etc. - </para> - - <para> - The definition of runtime instance is found in - <filename><sound/pcm.h></filename>. Here are - the contents of this file: - <informalexample> - <programlisting> -<![CDATA[ -struct _snd_pcm_runtime { - /* -- Status -- */ - struct snd_pcm_substream *trigger_master; - snd_timestamp_t trigger_tstamp; /* trigger timestamp */ - int overrange; - snd_pcm_uframes_t avail_max; - snd_pcm_uframes_t hw_ptr_base; /* Position at buffer restart */ - snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/ - - /* -- HW params -- */ - snd_pcm_access_t access; /* access mode */ - snd_pcm_format_t format; /* SNDRV_PCM_FORMAT_* */ - snd_pcm_subformat_t subformat; /* subformat */ - unsigned int rate; /* rate in Hz */ - unsigned int channels; /* channels */ - snd_pcm_uframes_t period_size; /* period size */ - unsigned int periods; /* periods */ - snd_pcm_uframes_t buffer_size; /* buffer size */ - unsigned int tick_time; /* tick time */ - snd_pcm_uframes_t min_align; /* Min alignment for the format */ - size_t byte_align; - unsigned int frame_bits; - unsigned int sample_bits; - unsigned int info; - unsigned int rate_num; - unsigned int rate_den; - - /* -- SW params -- */ - struct timespec tstamp_mode; /* mmap timestamp is updated */ - unsigned int period_step; - unsigned int sleep_min; /* min ticks to sleep */ - snd_pcm_uframes_t start_threshold; - snd_pcm_uframes_t stop_threshold; - snd_pcm_uframes_t silence_threshold; /* Silence filling happens when - noise is nearest than this */ - snd_pcm_uframes_t silence_size; /* Silence filling size */ - snd_pcm_uframes_t boundary; /* pointers wrap point */ - - snd_pcm_uframes_t silenced_start; - snd_pcm_uframes_t silenced_size; - - snd_pcm_sync_id_t sync; /* hardware synchronization ID */ - - /* -- mmap -- */ - volatile struct snd_pcm_mmap_status *status; - volatile struct snd_pcm_mmap_control *control; - atomic_t mmap_count; - - /* -- locking / scheduling -- */ - spinlock_t lock; - wait_queue_head_t sleep; - struct timer_list tick_timer; - struct fasync_struct *fasync; - - /* -- private section -- */ - void *private_data; - void (*private_free)(struct snd_pcm_runtime *runtime); - - /* -- hardware description -- */ - struct snd_pcm_hardware hw; - struct snd_pcm_hw_constraints hw_constraints; - - /* -- timer -- */ - unsigned int timer_resolution; /* timer resolution */ - - /* -- DMA -- */ - unsigned char *dma_area; /* DMA area */ - dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */ - size_t dma_bytes; /* size of DMA area */ - - struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */ - -#if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE) - /* -- OSS things -- */ - struct snd_pcm_oss_runtime oss; -#endif -}; -]]> - </programlisting> - </informalexample> - </para> - - <para> - For the operators (callbacks) of each sound driver, most of - these records are supposed to be read-only. Only the PCM - middle-layer changes / updates them. The exceptions are - the hardware description (hw) DMA buffer information and the - private data. Besides, if you use the standard buffer allocation - method via <function>snd_pcm_lib_malloc_pages()</function>, - you don't need to set the DMA buffer information by yourself. - </para> - - <para> - In the sections below, important records are explained. - </para> - - <section id="pcm-interface-runtime-hw"> - <title>Hardware Description</title> - <para> - The hardware descriptor (struct <structname>snd_pcm_hardware</structname>) - contains the definitions of the fundamental hardware - configuration. Above all, you'll need to define this in - <link linkend="pcm-interface-operators-open-callback"><citetitle> - the open callback</citetitle></link>. - Note that the runtime instance holds the copy of the - descriptor, not the pointer to the existing descriptor. That - is, in the open callback, you can modify the copied descriptor - (<constant>runtime->hw</constant>) as you need. For example, if the maximum - number of channels is 1 only on some chip models, you can - still use the same hardware descriptor and change the - channels_max later: - <informalexample> - <programlisting> -<![CDATA[ - struct snd_pcm_runtime *runtime = substream->runtime; - ... - runtime->hw = snd_mychip_playback_hw; /* common definition */ - if (chip->model == VERY_OLD_ONE) - runtime->hw.channels_max = 1; -]]> - </programlisting> - </informalexample> - </para> - - <para> - Typically, you'll have a hardware descriptor as below: - <informalexample> - <programlisting> -<![CDATA[ - static struct snd_pcm_hardware snd_mychip_playback_hw = { - .info = (SNDRV_PCM_INFO_MMAP | - SNDRV_PCM_INFO_INTERLEAVED | - SNDRV_PCM_INFO_BLOCK_TRANSFER | - SNDRV_PCM_INFO_MMAP_VALID), - .formats = SNDRV_PCM_FMTBIT_S16_LE, - .rates = SNDRV_PCM_RATE_8000_48000, - .rate_min = 8000, - .rate_max = 48000, - .channels_min = 2, - .channels_max = 2, - .buffer_bytes_max = 32768, - .period_bytes_min = 4096, - .period_bytes_max = 32768, - .periods_min = 1, - .periods_max = 1024, - }; -]]> - </programlisting> - </informalexample> - </para> - - <para> - <itemizedlist> - <listitem><para> - The <structfield>info</structfield> field contains the type and - capabilities of this pcm. The bit flags are defined in - <filename><sound/asound.h></filename> as - <constant>SNDRV_PCM_INFO_XXX</constant>. Here, at least, you - have to specify whether the mmap is supported and which - interleaved format is supported. - When the hardware supports mmap, add the - <constant>SNDRV_PCM_INFO_MMAP</constant> flag here. When the - hardware supports the interleaved or the non-interleaved - formats, <constant>SNDRV_PCM_INFO_INTERLEAVED</constant> or - <constant>SNDRV_PCM_INFO_NONINTERLEAVED</constant> flag must - be set, respectively. If both are supported, you can set both, - too. - </para> - - <para> - In the above example, <constant>MMAP_VALID</constant> and - <constant>BLOCK_TRANSFER</constant> are specified for the OSS mmap - mode. Usually both are set. Of course, - <constant>MMAP_VALID</constant> is set only if the mmap is - really supported. - </para> - - <para> - The other possible flags are - <constant>SNDRV_PCM_INFO_PAUSE</constant> and - <constant>SNDRV_PCM_INFO_RESUME</constant>. The - <constant>PAUSE</constant> bit means that the pcm supports the - <quote>pause</quote> operation, while the - <constant>RESUME</constant> bit means that the pcm supports - the full <quote>suspend/resume</quote> operation. - If the <constant>PAUSE</constant> flag is set, - the <structfield>trigger</structfield> callback below - must handle the corresponding (pause push/release) commands. - The suspend/resume trigger commands can be defined even without - the <constant>RESUME</constant> flag. See <link - linkend="power-management"><citetitle> - Power Management</citetitle></link> section for details. - </para> - - <para> - When the PCM substreams can be synchronized (typically, - synchronized start/stop of a playback and a capture streams), - you can give <constant>SNDRV_PCM_INFO_SYNC_START</constant>, - too. In this case, you'll need to check the linked-list of - PCM substreams in the trigger callback. This will be - described in the later section. - </para> - </listitem> - - <listitem> - <para> - <structfield>formats</structfield> field contains the bit-flags - of supported formats (<constant>SNDRV_PCM_FMTBIT_XXX</constant>). - If the hardware supports more than one format, give all or'ed - bits. In the example above, the signed 16bit little-endian - format is specified. - </para> - </listitem> - - <listitem> - <para> - <structfield>rates</structfield> field contains the bit-flags of - supported rates (<constant>SNDRV_PCM_RATE_XXX</constant>). - When the chip supports continuous rates, pass - <constant>CONTINUOUS</constant> bit additionally. - The pre-defined rate bits are provided only for typical - rates. If your chip supports unconventional rates, you need to add - the <constant>KNOT</constant> bit and set up the hardware - constraint manually (explained later). - </para> - </listitem> - - <listitem> - <para> - <structfield>rate_min</structfield> and - <structfield>rate_max</structfield> define the minimum and - maximum sample rate. This should correspond somehow to - <structfield>rates</structfield> bits. - </para> - </listitem> - - <listitem> - <para> - <structfield>channel_min</structfield> and - <structfield>channel_max</structfield> - define, as you might already expected, the minimum and maximum - number of channels. - </para> - </listitem> - - <listitem> - <para> - <structfield>buffer_bytes_max</structfield> defines the - maximum buffer size in bytes. There is no - <structfield>buffer_bytes_min</structfield> field, since - it can be calculated from the minimum period size and the - minimum number of periods. - Meanwhile, <structfield>period_bytes_min</structfield> and - define the minimum and maximum size of the period in bytes. - <structfield>periods_max</structfield> and - <structfield>periods_min</structfield> define the maximum and - minimum number of periods in the buffer. - </para> - - <para> - The <quote>period</quote> is a term that corresponds to - a fragment in the OSS world. The period defines the size at - which a PCM interrupt is generated. This size strongly - depends on the hardware. - Generally, the smaller period size will give you more - interrupts, that is, more controls. - In the case of capture, this size defines the input latency. - On the other hand, the whole buffer size defines the - output latency for the playback direction. - </para> - </listitem> - - <listitem> - <para> - There is also a field <structfield>fifo_size</structfield>. - This specifies the size of the hardware FIFO, but currently it - is neither used in the driver nor in the alsa-lib. So, you - can ignore this field. - </para> - </listitem> - </itemizedlist> - </para> - </section> - - <section id="pcm-interface-runtime-config"> - <title>PCM Configurations</title> - <para> - Ok, let's go back again to the PCM runtime records. - The most frequently referred records in the runtime instance are - the PCM configurations. - The PCM configurations are stored in the runtime instance - after the application sends <type>hw_params</type> data via - alsa-lib. There are many fields copied from hw_params and - sw_params structs. For example, - <structfield>format</structfield> holds the format type - chosen by the application. This field contains the enum value - <constant>SNDRV_PCM_FORMAT_XXX</constant>. - </para> - - <para> - One thing to be noted is that the configured buffer and period - sizes are stored in <quote>frames</quote> in the runtime. - In the ALSA world, 1 frame = channels * samples-size. - For conversion between frames and bytes, you can use the - <function>frames_to_bytes()</function> and - <function>bytes_to_frames()</function> helper functions. - <informalexample> - <programlisting> -<![CDATA[ - period_bytes = frames_to_bytes(runtime, runtime->period_size); -]]> - </programlisting> - </informalexample> - </para> - - <para> - Also, many software parameters (sw_params) are - stored in frames, too. Please check the type of the field. - <type>snd_pcm_uframes_t</type> is for the frames as unsigned - integer while <type>snd_pcm_sframes_t</type> is for the frames - as signed integer. - </para> - </section> - - <section id="pcm-interface-runtime-dma"> - <title>DMA Buffer Information</title> - <para> - The DMA buffer is defined by the following four fields, - <structfield>dma_area</structfield>, - <structfield>dma_addr</structfield>, - <structfield>dma_bytes</structfield> and - <structfield>dma_private</structfield>. - The <structfield>dma_area</structfield> holds the buffer - pointer (the logical address). You can call - <function>memcpy</function> from/to - this pointer. Meanwhile, <structfield>dma_addr</structfield> - holds the physical address of the buffer. This field is - specified only when the buffer is a linear buffer. - <structfield>dma_bytes</structfield> holds the size of buffer - in bytes. <structfield>dma_private</structfield> is used for - the ALSA DMA allocator. - </para> - - <para> - If you use a standard ALSA function, - <function>snd_pcm_lib_malloc_pages()</function>, for - allocating the buffer, these fields are set by the ALSA middle - layer, and you should <emphasis>not</emphasis> change them by - yourself. You can read them but not write them. - On the other hand, if you want to allocate the buffer by - yourself, you'll need to manage it in hw_params callback. - At least, <structfield>dma_bytes</structfield> is mandatory. - <structfield>dma_area</structfield> is necessary when the - buffer is mmapped. If your driver doesn't support mmap, this - field is not necessary. <structfield>dma_addr</structfield> - is also optional. You can use - <structfield>dma_private</structfield> as you like, too. - </para> - </section> - - <section id="pcm-interface-runtime-status"> - <title>Running Status</title> - <para> - The running status can be referred via <constant>runtime->status</constant>. - This is the pointer to the struct <structname>snd_pcm_mmap_status</structname> - record. For example, you can get the current DMA hardware - pointer via <constant>runtime->status->hw_ptr</constant>. - </para> - - <para> - The DMA application pointer can be referred via - <constant>runtime->control</constant>, which points to the - struct <structname>snd_pcm_mmap_control</structname> record. - However, accessing directly to this value is not recommended. - </para> - </section> - - <section id="pcm-interface-runtime-private"> - <title>Private Data</title> - <para> - You can allocate a record for the substream and store it in - <constant>runtime->private_data</constant>. Usually, this - is done in - <link linkend="pcm-interface-operators-open-callback"><citetitle> - the open callback</citetitle></link>. - Don't mix this with <constant>pcm->private_data</constant>. - The <constant>pcm->private_data</constant> usually points to the - chip instance assigned statically at the creation of PCM, while the - <constant>runtime->private_data</constant> points to a dynamic - data structure created at the PCM open callback. - - <informalexample> - <programlisting> -<![CDATA[ - static int snd_xxx_open(struct snd_pcm_substream *substream) - { - struct my_pcm_data *data; - .... - data = kmalloc(sizeof(*data), GFP_KERNEL); - substream->runtime->private_data = data; - .... - } -]]> - </programlisting> - </informalexample> - </para> - - <para> - The allocated object must be released in - <link linkend="pcm-interface-operators-open-callback"><citetitle> - the close callback</citetitle></link>. - </para> - </section> - - </section> - - <section id="pcm-interface-operators"> - <title>Operators</title> - <para> - OK, now let me give details about each pcm callback - (<parameter>ops</parameter>). In general, every callback must - return 0 if successful, or a negative error number - such as <constant>-EINVAL</constant>. To choose an appropriate - error number, it is advised to check what value other parts of - the kernel return when the same kind of request fails. - </para> - - <para> - The callback function takes at least the argument with - <structname>snd_pcm_substream</structname> pointer. To retrieve - the chip record from the given substream instance, you can use the - following macro. - - <informalexample> - <programlisting> -<![CDATA[ - int xxx() { - struct mychip *chip = snd_pcm_substream_chip(substream); - .... - } -]]> - </programlisting> - </informalexample> - - The macro reads <constant>substream->private_data</constant>, - which is a copy of <constant>pcm->private_data</constant>. - You can override the former if you need to assign different data - records per PCM substream. For example, the cmi8330 driver assigns - different private_data for playback and capture directions, - because it uses two different codecs (SB- and AD-compatible) for - different directions. - </para> - - <section id="pcm-interface-operators-open-callback"> - <title>open callback</title> - <para> - <informalexample> - <programlisting> -<![CDATA[ - static int snd_xxx_open(struct snd_pcm_substream *substream); -]]> - </programlisting> - </informalexample> - - This is called when a pcm substream is opened. - </para> - - <para> - At least, here you have to initialize the runtime->hw - record. Typically, this is done by like this: - - <informalexample> - <programlisting> -<![CDATA[ - static int snd_xxx_open(struct snd_pcm_substream *substream) - { - struct mychip *chip = snd_pcm_substream_chip(substream); - struct snd_pcm_runtime *runtime = substream->runtime; - - runtime->hw = snd_mychip_playback_hw; - return 0; - } -]]> - </programlisting> - </informalexample> - - where <parameter>snd_mychip_playback_hw</parameter> is the - pre-defined hardware description. - </para> - - <para> - You can allocate a private data in this callback, as described - in <link linkend="pcm-interface-runtime-private"><citetitle> - Private Data</citetitle></link> section. - </para> - - <para> - If the hardware configuration needs more constraints, set the - hardware constraints here, too. - See <link linkend="pcm-interface-constraints"><citetitle> - Constraints</citetitle></link> for more details. - </para> - </section> - - <section id="pcm-interface-operators-close-callback"> - <title>close callback</title> - <para> - <informalexample> - <programlisting> -<![CDATA[ - static int snd_xxx_close(struct snd_pcm_substream *substream); -]]> - </programlisting> - </informalexample> - - Obviously, this is called when a pcm substream is closed. - </para> - - <para> - Any private instance for a pcm substream allocated in the - open callback will be released here. - - <informalexample> - <programlisting> -<![CDATA[ - static int snd_xxx_close(struct snd_pcm_substream *substream) - { - .... - kfree(substream->runtime->private_data); - .... - } -]]> - </programlisting> - </informalexample> - </para> - </section> - - <section id="pcm-interface-operators-ioctl-callback"> - <title>ioctl callback</title> - <para> - This is used for any special call to pcm ioctls. But - usually you can pass a generic ioctl callback, - <function>snd_pcm_lib_ioctl</function>. - </para> - </section> - - <section id="pcm-interface-operators-hw-params-callback"> - <title>hw_params callback</title> - <para> - <informalexample> - <programlisting> -<![CDATA[ - static int snd_xxx_hw_params(struct snd_pcm_substream *substream, - struct snd_pcm_hw_params *hw_params); -]]> - </programlisting> - </informalexample> - </para> - - <para> - This is called when the hardware parameter - (<structfield>hw_params</structfield>) is set - up by the application, - that is, once when the buffer size, the period size, the - format, etc. are defined for the pcm substream. - </para> - - <para> - Many hardware setups should be done in this callback, - including the allocation of buffers. - </para> - - <para> - Parameters to be initialized are retrieved by - <function>params_xxx()</function> macros. To allocate - buffer, you can call a helper function, - - <informalexample> - <programlisting> -<![CDATA[ - snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params)); -]]> - </programlisting> - </informalexample> - - <function>snd_pcm_lib_malloc_pages()</function> is available - only when the DMA buffers have been pre-allocated. - See the section <link - linkend="buffer-and-memory-buffer-types"><citetitle> - Buffer Types</citetitle></link> for more details. - </para> - - <para> - Note that this and <structfield>prepare</structfield> callbacks - may be called multiple times per initialization. - For example, the OSS emulation may - call these callbacks at each change via its ioctl. - </para> - - <para> - Thus, you need to be careful not to allocate the same buffers - many times, which will lead to memory leaks! Calling the - helper function above many times is OK. It will release the - previous buffer automatically when it was already allocated. - </para> - - <para> - Another note is that this callback is non-atomic - (schedulable) as default, i.e. when no - <structfield>nonatomic</structfield> flag set. - This is important, because the - <structfield>trigger</structfield> callback - is atomic (non-schedulable). That is, mutexes or any - schedule-related functions are not available in - <structfield>trigger</structfield> callback. - Please see the subsection - <link linkend="pcm-interface-atomicity"><citetitle> - Atomicity</citetitle></link> for details. - </para> - </section> - - <section id="pcm-interface-operators-hw-free-callback"> - <title>hw_free callback</title> - <para> - <informalexample> - <programlisting> -<![CDATA[ - static int snd_xxx_hw_free(struct snd_pcm_substream *substream); -]]> - </programlisting> - </informalexample> - </para> - - <para> - This is called to release the resources allocated via - <structfield>hw_params</structfield>. For example, releasing the - buffer via - <function>snd_pcm_lib_malloc_pages()</function> is done by - calling the following: - - <informalexample> - <programlisting> -<![CDATA[ - snd_pcm_lib_free_pages(substream); -]]> - </programlisting> - </informalexample> - </para> - - <para> - This function is always called before the close callback is called. - Also, the callback may be called multiple times, too. - Keep track whether the resource was already released. - </para> - </section> - - <section id="pcm-interface-operators-prepare-callback"> - <title>prepare callback</title> - <para> - <informalexample> - <programlisting> -<![CDATA[ - static int snd_xxx_prepare(struct snd_pcm_substream *substream); -]]> - </programlisting> - </informalexample> - </para> - - <para> - This callback is called when the pcm is - <quote>prepared</quote>. You can set the format type, sample - rate, etc. here. The difference from - <structfield>hw_params</structfield> is that the - <structfield>prepare</structfield> callback will be called each - time - <function>snd_pcm_prepare()</function> is called, i.e. when - recovering after underruns, etc. - </para> - - <para> - Note that this callback is now non-atomic. - You can use schedule-related functions safely in this callback. - </para> - - <para> - In this and the following callbacks, you can refer to the - values via the runtime record, - substream->runtime. - For example, to get the current - rate, format or channels, access to - runtime->rate, - runtime->format or - runtime->channels, respectively. - The physical address of the allocated buffer is set to - runtime->dma_area. The buffer and period sizes are - in runtime->buffer_size and runtime->period_size, - respectively. - </para> - - <para> - Be careful that this callback will be called many times at - each setup, too. - </para> - </section> - - <section id="pcm-interface-operators-trigger-callback"> - <title>trigger callback</title> - <para> - <informalexample> - <programlisting> -<![CDATA[ - static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd); -]]> - </programlisting> - </informalexample> - - This is called when the pcm is started, stopped or paused. - </para> - - <para> - Which action is specified in the second argument, - <constant>SNDRV_PCM_TRIGGER_XXX</constant> in - <filename><sound/pcm.h></filename>. At least, - the <constant>START</constant> and <constant>STOP</constant> - commands must be defined in this callback. - - <informalexample> - <programlisting> -<![CDATA[ - switch (cmd) { - case SNDRV_PCM_TRIGGER_START: - /* do something to start the PCM engine */ - break; - case SNDRV_PCM_TRIGGER_STOP: - /* do something to stop the PCM engine */ - break; - default: - return -EINVAL; - } -]]> - </programlisting> - </informalexample> - </para> - - <para> - When the pcm supports the pause operation (given in the info - field of the hardware table), the <constant>PAUSE_PUSH</constant> - and <constant>PAUSE_RELEASE</constant> commands must be - handled here, too. The former is the command to pause the pcm, - and the latter to restart the pcm again. - </para> - - <para> - When the pcm supports the suspend/resume operation, - regardless of full or partial suspend/resume support, - the <constant>SUSPEND</constant> and <constant>RESUME</constant> - commands must be handled, too. - These commands are issued when the power-management status is - changed. Obviously, the <constant>SUSPEND</constant> and - <constant>RESUME</constant> commands - suspend and resume the pcm substream, and usually, they - are identical to the <constant>STOP</constant> and - <constant>START</constant> commands, respectively. - See the <link linkend="power-management"><citetitle> - Power Management</citetitle></link> section for details. - </para> - - <para> - As mentioned, this callback is atomic as default unless - <structfield>nonatomic</structfield> flag set, and - you cannot call functions which may sleep. - The trigger callback should be as minimal as possible, - just really triggering the DMA. The other stuff should be - initialized hw_params and prepare callbacks properly - beforehand. - </para> - </section> - - <section id="pcm-interface-operators-pointer-callback"> - <title>pointer callback</title> - <para> - <informalexample> - <programlisting> -<![CDATA[ - static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream) -]]> - </programlisting> - </informalexample> - - This callback is called when the PCM middle layer inquires - the current hardware position on the buffer. The position must - be returned in frames, - ranging from 0 to buffer_size - 1. - </para> - - <para> - This is called usually from the buffer-update routine in the - pcm middle layer, which is invoked when - <function>snd_pcm_period_elapsed()</function> is called in the - interrupt routine. Then the pcm middle layer updates the - position and calculates the available space, and wakes up the - sleeping poll threads, etc. - </para> - - <para> - This callback is also atomic as default. - </para> - </section> - - <section id="pcm-interface-operators-copy-silence"> - <title>copy and silence callbacks</title> - <para> - These callbacks are not mandatory, and can be omitted in - most cases. These callbacks are used when the hardware buffer - cannot be in the normal memory space. Some chips have their - own buffer on the hardware which is not mappable. In such a - case, you have to transfer the data manually from the memory - buffer to the hardware buffer. Or, if the buffer is - non-contiguous on both physical and virtual memory spaces, - these callbacks must be defined, too. - </para> - - <para> - If these two callbacks are defined, copy and set-silence - operations are done by them. The detailed will be described in - the later section <link - linkend="buffer-and-memory"><citetitle>Buffer and Memory - Management</citetitle></link>. - </para> - </section> - - <section id="pcm-interface-operators-ack"> - <title>ack callback</title> - <para> - This callback is also not mandatory. This callback is called - when the appl_ptr is updated in read or write operations. - Some drivers like emu10k1-fx and cs46xx need to track the - current appl_ptr for the internal buffer, and this callback - is useful only for such a purpose. - </para> - <para> - This callback is atomic as default. - </para> - </section> - - <section id="pcm-interface-operators-page-callback"> - <title>page callback</title> - - <para> - This callback is optional too. This callback is used - mainly for non-contiguous buffers. The mmap calls this - callback to get the page address. Some examples will be - explained in the later section <link - linkend="buffer-and-memory"><citetitle>Buffer and Memory - Management</citetitle></link>, too. - </para> - </section> - </section> - - <section id="pcm-interface-interrupt-handler"> - <title>Interrupt Handler</title> - <para> - The rest of pcm stuff is the PCM interrupt handler. The - role of PCM interrupt handler in the sound driver is to update - the buffer position and to tell the PCM middle layer when the - buffer position goes across the prescribed period size. To - inform this, call the <function>snd_pcm_period_elapsed()</function> - function. - </para> - - <para> - There are several types of sound chips to generate the interrupts. - </para> - - <section id="pcm-interface-interrupt-handler-boundary"> - <title>Interrupts at the period (fragment) boundary</title> - <para> - This is the most frequently found type: the hardware - generates an interrupt at each period boundary. - In this case, you can call - <function>snd_pcm_period_elapsed()</function> at each - interrupt. - </para> - - <para> - <function>snd_pcm_period_elapsed()</function> takes the - substream pointer as its argument. Thus, you need to keep the - substream pointer accessible from the chip instance. For - example, define substream field in the chip record to hold the - current running substream pointer, and set the pointer value - at open callback (and reset at close callback). - </para> - - <para> - If you acquire a spinlock in the interrupt handler, and the - lock is used in other pcm callbacks, too, then you have to - release the lock before calling - <function>snd_pcm_period_elapsed()</function>, because - <function>snd_pcm_period_elapsed()</function> calls other pcm - callbacks inside. - </para> - - <para> - Typical code would be like: - - <example> - <title>Interrupt Handler Case #1</title> - <programlisting> -<![CDATA[ - static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id) - { - struct mychip *chip = dev_id; - spin_lock(&chip->lock); - .... - if (pcm_irq_invoked(chip)) { - /* call updater, unlock before it */ - spin_unlock(&chip->lock); - snd_pcm_period_elapsed(chip->substream); - spin_lock(&chip->lock); - /* acknowledge the interrupt if necessary */ - } - .... - spin_unlock(&chip->lock); - return IRQ_HANDLED; - } -]]> - </programlisting> - </example> - </para> - </section> - - <section id="pcm-interface-interrupt-handler-timer"> - <title>High frequency timer interrupts</title> - <para> - This happens when the hardware doesn't generate interrupts - at the period boundary but issues timer interrupts at a fixed - timer rate (e.g. es1968 or ymfpci drivers). - In this case, you need to check the current hardware - position and accumulate the processed sample length at each - interrupt. When the accumulated size exceeds the period - size, call - <function>snd_pcm_period_elapsed()</function> and reset the - accumulator. - </para> - - <para> - Typical code would be like the following. - - <example> - <title>Interrupt Handler Case #2</title> - <programlisting> -<![CDATA[ - static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id) - { - struct mychip *chip = dev_id; - spin_lock(&chip->lock); - .... - if (pcm_irq_invoked(chip)) { - unsigned int last_ptr, size; - /* get the current hardware pointer (in frames) */ - last_ptr = get_hw_ptr(chip); - /* calculate the processed frames since the - * last update - */ - if (last_ptr < chip->last_ptr) - size = runtime->buffer_size + last_ptr - - chip->last_ptr; - else - size = last_ptr - chip->last_ptr; - /* remember the last updated point */ - chip->last_ptr = last_ptr; - /* accumulate the size */ - chip->size += size; - /* over the period boundary? */ - if (chip->size >= runtime->period_size) { - /* reset the accumulator */ - chip->size %= runtime->period_size; - /* call updater */ - spin_unlock(&chip->lock); - snd_pcm_period_elapsed(substream); - spin_lock(&chip->lock); - } - /* acknowledge the interrupt if necessary */ - } - .... - spin_unlock(&chip->lock); - return IRQ_HANDLED; - } -]]> - </programlisting> - </example> - </para> - </section> - - <section id="pcm-interface-interrupt-handler-both"> - <title>On calling <function>snd_pcm_period_elapsed()</function></title> - <para> - In both cases, even if more than one period are elapsed, you - don't have to call - <function>snd_pcm_period_elapsed()</function> many times. Call - only once. And the pcm layer will check the current hardware - pointer and update to the latest status. - </para> - </section> - </section> - - <section id="pcm-interface-atomicity"> - <title>Atomicity</title> - <para> - One of the most important (and thus difficult to debug) problems - in kernel programming are race conditions. - In the Linux kernel, they are usually avoided via spin-locks, mutexes - or semaphores. In general, if a race condition can happen - in an interrupt handler, it has to be managed atomically, and you - have to use a spinlock to protect the critical session. If the - critical section is not in interrupt handler code and - if taking a relatively long time to execute is acceptable, you - should use mutexes or semaphores instead. - </para> - - <para> - As already seen, some pcm callbacks are atomic and some are - not. For example, the <parameter>hw_params</parameter> callback is - non-atomic, while <parameter>trigger</parameter> callback is - atomic. This means, the latter is called already in a spinlock - held by the PCM middle layer. Please take this atomicity into - account when you choose a locking scheme in the callbacks. - </para> - - <para> - In the atomic callbacks, you cannot use functions which may call - <function>schedule</function> or go to - <function>sleep</function>. Semaphores and mutexes can sleep, - and hence they cannot be used inside the atomic callbacks - (e.g. <parameter>trigger</parameter> callback). - To implement some delay in such a callback, please use - <function>udelay()</function> or <function>mdelay()</function>. - </para> - - <para> - All three atomic callbacks (trigger, pointer, and ack) are - called with local interrupts disabled. - </para> - - <para> - The recent changes in PCM core code, however, allow all PCM - operations to be non-atomic. This assumes that the all caller - sides are in non-atomic contexts. For example, the function - <function>snd_pcm_period_elapsed()</function> is called - typically from the interrupt handler. But, if you set up the - driver to use a threaded interrupt handler, this call can be in - non-atomic context, too. In such a case, you can set - <structfield>nonatomic</structfield> filed of - <structname>snd_pcm</structname> object after creating it. - When this flag is set, mutex and rwsem are used internally in - the PCM core instead of spin and rwlocks, so that you can call - all PCM functions safely in a non-atomic context. - </para> - - </section> - <section id="pcm-interface-constraints"> - <title>Constraints</title> - <para> - If your chip supports unconventional sample rates, or only the - limited samples, you need to set a constraint for the - condition. - </para> - - <para> - For example, in order to restrict the sample rates in the some - supported values, use - <function>snd_pcm_hw_constraint_list()</function>. - You need to call this function in the open callback. - - <example> - <title>Example of Hardware Constraints</title> - <programlisting> -<![CDATA[ - static unsigned int rates[] = - {4000, 10000, 22050, 44100}; - static struct snd_pcm_hw_constraint_list constraints_rates = { - .count = ARRAY_SIZE(rates), - .list = rates, - .mask = 0, - }; - - static int snd_mychip_pcm_open(struct snd_pcm_substream *substream) - { - int err; - .... - err = snd_pcm_hw_constraint_list(substream->runtime, 0, - SNDRV_PCM_HW_PARAM_RATE, - &constraints_rates); - if (err < 0) - return err; - .... - } -]]> - </programlisting> - </example> - </para> - - <para> - There are many different constraints. - Look at <filename>sound/pcm.h</filename> for a complete list. - You can even define your own constraint rules. - For example, let's suppose my_chip can manage a substream of 1 channel - if and only if the format is S16_LE, otherwise it supports any format - specified in the <structname>snd_pcm_hardware</structname> structure (or in any - other constraint_list). You can build a rule like this: - - <example> - <title>Example of Hardware Constraints for Channels</title> - <programlisting> -<![CDATA[ - static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params, - struct snd_pcm_hw_rule *rule) - { - struct snd_interval *c = hw_param_interval(params, - SNDRV_PCM_HW_PARAM_CHANNELS); - struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT); - struct snd_interval ch; - - snd_interval_any(&ch); - if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) { - ch.min = ch.max = 1; - ch.integer = 1; - return snd_interval_refine(c, &ch); - } - return 0; - } -]]> - </programlisting> - </example> - </para> - - <para> - Then you need to call this function to add your rule: - - <informalexample> - <programlisting> -<![CDATA[ - snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS, - hw_rule_channels_by_format, NULL, - SNDRV_PCM_HW_PARAM_FORMAT, -1); -]]> - </programlisting> - </informalexample> - </para> - - <para> - The rule function is called when an application sets the PCM - format, and it refines the number of channels accordingly. - But an application may set the number of channels before - setting the format. Thus you also need to define the inverse rule: - - <example> - <title>Example of Hardware Constraints for Formats</title> - <programlisting> -<![CDATA[ - static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params, - struct snd_pcm_hw_rule *rule) - { - struct snd_interval *c = hw_param_interval(params, - SNDRV_PCM_HW_PARAM_CHANNELS); - struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT); - struct snd_mask fmt; - - snd_mask_any(&fmt); /* Init the struct */ - if (c->min < 2) { - fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE; - return snd_mask_refine(f, &fmt); - } - return 0; - } -]]> - </programlisting> - </example> - </para> - - <para> - ...and in the open callback: - <informalexample> - <programlisting> -<![CDATA[ - snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT, - hw_rule_format_by_channels, NULL, - SNDRV_PCM_HW_PARAM_CHANNELS, -1); -]]> - </programlisting> - </informalexample> - </para> - - <para> - I won't give more details here, rather I - would like to say, <quote>Luke, use the source.</quote> - </para> - </section> - - </chapter> - - -<!-- ****************************************************** --> -<!-- Control Interface --> -<!-- ****************************************************** --> - <chapter id="control-interface"> - <title>Control Interface</title> - - <section id="control-interface-general"> - <title>General</title> - <para> - The control interface is used widely for many switches, - sliders, etc. which are accessed from user-space. Its most - important use is the mixer interface. In other words, since ALSA - 0.9.x, all the mixer stuff is implemented on the control kernel API. - </para> - - <para> - ALSA has a well-defined AC97 control module. If your chip - supports only the AC97 and nothing else, you can skip this - section. - </para> - - <para> - The control API is defined in - <filename><sound/control.h></filename>. - Include this file if you want to add your own controls. - </para> - </section> - - <section id="control-interface-definition"> - <title>Definition of Controls</title> - <para> - To create a new control, you need to define the - following three - callbacks: <structfield>info</structfield>, - <structfield>get</structfield> and - <structfield>put</structfield>. Then, define a - struct <structname>snd_kcontrol_new</structname> record, such as: - - <example> - <title>Definition of a Control</title> - <programlisting> -<![CDATA[ - static struct snd_kcontrol_new my_control = { - .iface = SNDRV_CTL_ELEM_IFACE_MIXER, - .name = "PCM Playback Switch", - .index = 0, - .access = SNDRV_CTL_ELEM_ACCESS_READWRITE, - .private_value = 0xffff, - .info = my_control_info, - .get = my_control_get, - .put = my_control_put - }; -]]> - </programlisting> - </example> - </para> - - <para> - The <structfield>iface</structfield> field specifies the control - type, <constant>SNDRV_CTL_ELEM_IFACE_XXX</constant>, which - is usually <constant>MIXER</constant>. - Use <constant>CARD</constant> for global controls that are not - logically part of the mixer. - If the control is closely associated with some specific device on - the sound card, use <constant>HWDEP</constant>, - <constant>PCM</constant>, <constant>RAWMIDI</constant>, - <constant>TIMER</constant>, or <constant>SEQUENCER</constant>, and - specify the device number with the - <structfield>device</structfield> and - <structfield>subdevice</structfield> fields. - </para> - - <para> - The <structfield>name</structfield> is the name identifier - string. Since ALSA 0.9.x, the control name is very important, - because its role is classified from its name. There are - pre-defined standard control names. The details are described in - the <link linkend="control-interface-control-names"><citetitle> - Control Names</citetitle></link> subsection. - </para> - - <para> - The <structfield>index</structfield> field holds the index number - of this control. If there are several different controls with - the same name, they can be distinguished by the index - number. This is the case when - several codecs exist on the card. If the index is zero, you can - omit the definition above. - </para> - - <para> - The <structfield>access</structfield> field contains the access - type of this control. Give the combination of bit masks, - <constant>SNDRV_CTL_ELEM_ACCESS_XXX</constant>, there. - The details will be explained in - the <link linkend="control-interface-access-flags"><citetitle> - Access Flags</citetitle></link> subsection. - </para> - - <para> - The <structfield>private_value</structfield> field contains - an arbitrary long integer value for this record. When using - the generic <structfield>info</structfield>, - <structfield>get</structfield> and - <structfield>put</structfield> callbacks, you can pass a value - through this field. If several small numbers are necessary, you can - combine them in bitwise. Or, it's possible to give a pointer - (casted to unsigned long) of some record to this field, too. - </para> - - <para> - The <structfield>tlv</structfield> field can be used to provide - metadata about the control; see the - <link linkend="control-interface-tlv"> - <citetitle>Metadata</citetitle></link> subsection. - </para> - - <para> - The other three are - <link linkend="control-interface-callbacks"><citetitle> - callback functions</citetitle></link>. - </para> - </section> - - <section id="control-interface-control-names"> - <title>Control Names</title> - <para> - There are some standards to define the control names. A - control is usually defined from the three parts as - <quote>SOURCE DIRECTION FUNCTION</quote>. - </para> - - <para> - The first, <constant>SOURCE</constant>, specifies the source - of the control, and is a string such as <quote>Master</quote>, - <quote>PCM</quote>, <quote>CD</quote> and - <quote>Line</quote>. There are many pre-defined sources. - </para> - - <para> - The second, <constant>DIRECTION</constant>, is one of the - following strings according to the direction of the control: - <quote>Playback</quote>, <quote>Capture</quote>, <quote>Bypass - Playback</quote> and <quote>Bypass Capture</quote>. Or, it can - be omitted, meaning both playback and capture directions. - </para> - - <para> - The third, <constant>FUNCTION</constant>, is one of the - following strings according to the function of the control: - <quote>Switch</quote>, <quote>Volume</quote> and - <quote>Route</quote>. - </para> - - <para> - The example of control names are, thus, <quote>Master Capture - Switch</quote> or <quote>PCM Playback Volume</quote>. - </para> - - <para> - There are some exceptions: - </para> - - <section id="control-interface-control-names-global"> - <title>Global capture and playback</title> - <para> - <quote>Capture Source</quote>, <quote>Capture Switch</quote> - and <quote>Capture Volume</quote> are used for the global - capture (input) source, switch and volume. Similarly, - <quote>Playback Switch</quote> and <quote>Playback - Volume</quote> are used for the global output gain switch and - volume. - </para> - </section> - - <section id="control-interface-control-names-tone"> - <title>Tone-controls</title> - <para> - tone-control switch and volumes are specified like - <quote>Tone Control - XXX</quote>, e.g. <quote>Tone Control - - Switch</quote>, <quote>Tone Control - Bass</quote>, - <quote>Tone Control - Center</quote>. - </para> - </section> - - <section id="control-interface-control-names-3d"> - <title>3D controls</title> - <para> - 3D-control switches and volumes are specified like <quote>3D - Control - XXX</quote>, e.g. <quote>3D Control - - Switch</quote>, <quote>3D Control - Center</quote>, <quote>3D - Control - Space</quote>. - </para> - </section> - - <section id="control-interface-control-names-mic"> - <title>Mic boost</title> - <para> - Mic-boost switch is set as <quote>Mic Boost</quote> or - <quote>Mic Boost (6dB)</quote>. - </para> - - <para> - More precise information can be found in - <filename>Documentation/sound/alsa/ControlNames.txt</filename>. - </para> - </section> - </section> - - <section id="control-interface-access-flags"> - <title>Access Flags</title> - - <para> - The access flag is the bitmask which specifies the access type - of the given control. The default access type is - <constant>SNDRV_CTL_ELEM_ACCESS_READWRITE</constant>, - which means both read and write are allowed to this control. - When the access flag is omitted (i.e. = 0), it is - considered as <constant>READWRITE</constant> access as default. - </para> - - <para> - When the control is read-only, pass - <constant>SNDRV_CTL_ELEM_ACCESS_READ</constant> instead. - In this case, you don't have to define - the <structfield>put</structfield> callback. - Similarly, when the control is write-only (although it's a rare - case), you can use the <constant>WRITE</constant> flag instead, and - you don't need the <structfield>get</structfield> callback. - </para> - - <para> - If the control value changes frequently (e.g. the VU meter), - <constant>VOLATILE</constant> flag should be given. This means - that the control may be changed without - <link linkend="control-interface-change-notification"><citetitle> - notification</citetitle></link>. Applications should poll such - a control constantly. - </para> - - <para> - When the control is inactive, set - the <constant>INACTIVE</constant> flag, too. - There are <constant>LOCK</constant> and - <constant>OWNER</constant> flags to change the write - permissions. - </para> - - </section> - - <section id="control-interface-callbacks"> - <title>Callbacks</title> - - <section id="control-interface-callbacks-info"> - <title>info callback</title> - <para> - The <structfield>info</structfield> callback is used to get - detailed information on this control. This must store the - values of the given struct <structname>snd_ctl_elem_info</structname> - object. For example, for a boolean control with a single - element: - - <example> - <title>Example of info callback</title> - <programlisting> -<![CDATA[ - static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol, - struct snd_ctl_elem_info *uinfo) - { - uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN; - uinfo->count = 1; - uinfo->value.integer.min = 0; - uinfo->value.integer.max = 1; - return 0; - } -]]> - </programlisting> - </example> - </para> - - <para> - The <structfield>type</structfield> field specifies the type - of the control. There are <constant>BOOLEAN</constant>, - <constant>INTEGER</constant>, <constant>ENUMERATED</constant>, - <constant>BYTES</constant>, <constant>IEC958</constant> and - <constant>INTEGER64</constant>. The - <structfield>count</structfield> field specifies the - number of elements in this control. For example, a stereo - volume would have count = 2. The - <structfield>value</structfield> field is a union, and - the values stored are depending on the type. The boolean and - integer types are identical. - </para> - - <para> - The enumerated type is a bit different from others. You'll - need to set the string for the currently given item index. - - <informalexample> - <programlisting> -<![CDATA[ - static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol, - struct snd_ctl_elem_info *uinfo) - { - static char *texts[4] = { - "First", "Second", "Third", "Fourth" - }; - uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED; - uinfo->count = 1; - uinfo->value.enumerated.items = 4; - if (uinfo->value.enumerated.item > 3) - uinfo->value.enumerated.item = 3; - strcpy(uinfo->value.enumerated.name, - texts[uinfo->value.enumerated.item]); - return 0; - } -]]> - </programlisting> - </informalexample> - </para> - - <para> - The above callback can be simplified with a helper function, - <function>snd_ctl_enum_info</function>. The final code - looks like below. - (You can pass ARRAY_SIZE(texts) instead of 4 in the third - argument; it's a matter of taste.) - - <informalexample> - <programlisting> -<![CDATA[ - static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol, - struct snd_ctl_elem_info *uinfo) - { - static char *texts[4] = { - "First", "Second", "Third", "Fourth" - }; - return snd_ctl_enum_info(uinfo, 1, 4, texts); - } -]]> - </programlisting> - </informalexample> - </para> - - <para> - Some common info callbacks are available for your convenience: - <function>snd_ctl_boolean_mono_info()</function> and - <function>snd_ctl_boolean_stereo_info()</function>. - Obviously, the former is an info callback for a mono channel - boolean item, just like <function>snd_myctl_mono_info</function> - above, and the latter is for a stereo channel boolean item. - </para> - - </section> - - <section id="control-interface-callbacks-get"> - <title>get callback</title> - - <para> - This callback is used to read the current value of the - control and to return to user-space. - </para> - - <para> - For example, - - <example> - <title>Example of get callback</title> - <programlisting> -<![CDATA[ - static int snd_myctl_get(struct snd_kcontrol *kcontrol, - struct snd_ctl_elem_value *ucontrol) - { - struct mychip *chip = snd_kcontrol_chip(kcontrol); - ucontrol->value.integer.value[0] = get_some_value(chip); - return 0; - } -]]> - </programlisting> - </example> - </para> - - <para> - The <structfield>value</structfield> field depends on - the type of control as well as on the info callback. For example, - the sb driver uses this field to store the register offset, - the bit-shift and the bit-mask. The - <structfield>private_value</structfield> field is set as follows: - <informalexample> - <programlisting> -<![CDATA[ - .private_value = reg | (shift << 16) | (mask << 24) -]]> - </programlisting> - </informalexample> - and is retrieved in callbacks like - <informalexample> - <programlisting> -<![CDATA[ - static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol, - struct snd_ctl_elem_value *ucontrol) - { - int reg = kcontrol->private_value & 0xff; - int shift = (kcontrol->private_value >> 16) & 0xff; - int mask = (kcontrol->private_value >> 24) & 0xff; - .... - } -]]> - </programlisting> - </informalexample> - </para> - - <para> - In the <structfield>get</structfield> callback, - you have to fill all the elements if the - control has more than one elements, - i.e. <structfield>count</structfield> > 1. - In the example above, we filled only one element - (<structfield>value.integer.value[0]</structfield>) since it's - assumed as <structfield>count</structfield> = 1. - </para> - </section> - - <section id="control-interface-callbacks-put"> - <title>put callback</title> - - <para> - This callback is used to write a value from user-space. - </para> - - <para> - For example, - - <example> - <title>Example of put callback</title> - <programlisting> -<![CDATA[ - static int snd_myctl_put(struct snd_kcontrol *kcontrol, - struct snd_ctl_elem_value *ucontrol) - { - struct mychip *chip = snd_kcontrol_chip(kcontrol); - int changed = 0; - if (chip->current_value != - ucontrol->value.integer.value[0]) { - change_current_value(chip, - ucontrol->value.integer.value[0]); - changed = 1; - } - return changed; - } -]]> - </programlisting> - </example> - - As seen above, you have to return 1 if the value is - changed. If the value is not changed, return 0 instead. - If any fatal error happens, return a negative error code as - usual. - </para> - - <para> - As in the <structfield>get</structfield> callback, - when the control has more than one elements, - all elements must be evaluated in this callback, too. - </para> - </section> - - <section id="control-interface-callbacks-all"> - <title>Callbacks are not atomic</title> - <para> - All these three callbacks are basically not atomic. - </para> - </section> - </section> - - <section id="control-interface-constructor"> - <title>Constructor</title> - <para> - When everything is ready, finally we can create a new - control. To create a control, there are two functions to be - called, <function>snd_ctl_new1()</function> and - <function>snd_ctl_add()</function>. - </para> - - <para> - In the simplest way, you can do like this: - - <informalexample> - <programlisting> -<![CDATA[ - err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip)); - if (err < 0) - return err; -]]> - </programlisting> - </informalexample> - - where <parameter>my_control</parameter> is the - struct <structname>snd_kcontrol_new</structname> object defined above, and chip - is the object pointer to be passed to - kcontrol->private_data - which can be referred to in callbacks. - </para> - - <para> - <function>snd_ctl_new1()</function> allocates a new - <structname>snd_kcontrol</structname> instance, - and <function>snd_ctl_add</function> assigns the given - control component to the card. - </para> - </section> - - <section id="control-interface-change-notification"> - <title>Change Notification</title> - <para> - If you need to change and update a control in the interrupt - routine, you can call <function>snd_ctl_notify()</function>. For - example, - - <informalexample> - <programlisting> -<![CDATA[ - snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer); -]]> - </programlisting> - </informalexample> - - This function takes the card pointer, the event-mask, and the - control id pointer for the notification. The event-mask - specifies the types of notification, for example, in the above - example, the change of control values is notified. - The id pointer is the pointer of struct <structname>snd_ctl_elem_id</structname> - to be notified. - You can find some examples in <filename>es1938.c</filename> or - <filename>es1968.c</filename> for hardware volume interrupts. - </para> - </section> - - <section id="control-interface-tlv"> - <title>Metadata</title> - <para> - To provide information about the dB values of a mixer control, use - on of the <constant>DECLARE_TLV_xxx</constant> macros from - <filename><sound/tlv.h></filename> to define a variable - containing this information, set the<structfield>tlv.p - </structfield> field to point to this variable, and include the - <constant>SNDRV_CTL_ELEM_ACCESS_TLV_READ</constant> flag in the - <structfield>access</structfield> field; like this: - <informalexample> - <programlisting> -<![CDATA[ - static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0); - - static struct snd_kcontrol_new my_control = { - ... - .access = SNDRV_CTL_ELEM_ACCESS_READWRITE | - SNDRV_CTL_ELEM_ACCESS_TLV_READ, - ... - .tlv.p = db_scale_my_control, - }; -]]> - </programlisting> - </informalexample> - </para> - - <para> - The <function>DECLARE_TLV_DB_SCALE</function> macro defines - information about a mixer control where each step in the control's - value changes the dB value by a constant dB amount. - The first parameter is the name of the variable to be defined. - The second parameter is the minimum value, in units of 0.01 dB. - The third parameter is the step size, in units of 0.01 dB. - Set the fourth parameter to 1 if the minimum value actually mutes - the control. - </para> - - <para> - The <function>DECLARE_TLV_DB_LINEAR</function> macro defines - information about a mixer control where the control's value affects - the output linearly. - The first parameter is the name of the variable to be defined. - The second parameter is the minimum value, in units of 0.01 dB. - The third parameter is the maximum value, in units of 0.01 dB. - If the minimum value mutes the control, set the second parameter to - <constant>TLV_DB_GAIN_MUTE</constant>. - </para> - </section> - - </chapter> - - -<!-- ****************************************************** --> -<!-- API for AC97 Codec --> -<!-- ****************************************************** --> - <chapter id="api-ac97"> - <title>API for AC97 Codec</title> - - <section> - <title>General</title> - <para> - The ALSA AC97 codec layer is a well-defined one, and you don't - have to write much code to control it. Only low-level control - routines are necessary. The AC97 codec API is defined in - <filename><sound/ac97_codec.h></filename>. - </para> - </section> - - <section id="api-ac97-example"> - <title>Full Code Example</title> - <para> - <example> - <title>Example of AC97 Interface</title> - <programlisting> -<![CDATA[ - struct mychip { - .... - struct snd_ac97 *ac97; - .... - }; - - static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97, - unsigned short reg) - { - struct mychip *chip = ac97->private_data; - .... - /* read a register value here from the codec */ - return the_register_value; - } - - static void snd_mychip_ac97_write(struct snd_ac97 *ac97, - unsigned short reg, unsigned short val) - { - struct mychip *chip = ac97->private_data; - .... - /* write the given register value to the codec */ - } - - static int snd_mychip_ac97(struct mychip *chip) - { - struct snd_ac97_bus *bus; - struct snd_ac97_template ac97; - int err; - static struct snd_ac97_bus_ops ops = { - .write = snd_mychip_ac97_write, - .read = snd_mychip_ac97_read, - }; - - err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus); - if (err < 0) - return err; - memset(&ac97, 0, sizeof(ac97)); - ac97.private_data = chip; - return snd_ac97_mixer(bus, &ac97, &chip->ac97); - } - -]]> - </programlisting> - </example> - </para> - </section> - - <section id="api-ac97-constructor"> - <title>Constructor</title> - <para> - To create an ac97 instance, first call <function>snd_ac97_bus</function> - with an <type>ac97_bus_ops_t</type> record with callback functions. - - <informalexample> - <programlisting> -<![CDATA[ - struct snd_ac97_bus *bus; - static struct snd_ac97_bus_ops ops = { - .write = snd_mychip_ac97_write, - .read = snd_mychip_ac97_read, - }; - - snd_ac97_bus(card, 0, &ops, NULL, &pbus); -]]> - </programlisting> - </informalexample> - - The bus record is shared among all belonging ac97 instances. - </para> - - <para> - And then call <function>snd_ac97_mixer()</function> with an - struct <structname>snd_ac97_template</structname> - record together with the bus pointer created above. - - <informalexample> - <programlisting> -<![CDATA[ - struct snd_ac97_template ac97; - int err; - - memset(&ac97, 0, sizeof(ac97)); - ac97.private_data = chip; - snd_ac97_mixer(bus, &ac97, &chip->ac97); -]]> - </programlisting> - </informalexample> - - where chip->ac97 is a pointer to a newly created - <type>ac97_t</type> instance. - In this case, the chip pointer is set as the private data, so that - the read/write callback functions can refer to this chip instance. - This instance is not necessarily stored in the chip - record. If you need to change the register values from the - driver, or need the suspend/resume of ac97 codecs, keep this - pointer to pass to the corresponding functions. - </para> - </section> - - <section id="api-ac97-callbacks"> - <title>Callbacks</title> - <para> - The standard callbacks are <structfield>read</structfield> and - <structfield>write</structfield>. Obviously they - correspond to the functions for read and write accesses to the - hardware low-level codes. - </para> - - <para> - The <structfield>read</structfield> callback returns the - register value specified in the argument. - - <informalexample> - <programlisting> -<![CDATA[ - static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97, - unsigned short reg) - { - struct mychip *chip = ac97->private_data; - .... - return the_register_value; - } -]]> - </programlisting> - </informalexample> - - Here, the chip can be cast from ac97->private_data. - </para> - - <para> - Meanwhile, the <structfield>write</structfield> callback is - used to set the register value. - - <informalexample> - <programlisting> -<![CDATA[ - static void snd_mychip_ac97_write(struct snd_ac97 *ac97, - unsigned short reg, unsigned short val) -]]> - </programlisting> - </informalexample> - </para> - - <para> - These callbacks are non-atomic like the control API callbacks. - </para> - - <para> - There are also other callbacks: - <structfield>reset</structfield>, - <structfield>wait</structfield> and - <structfield>init</structfield>. - </para> - - <para> - The <structfield>reset</structfield> callback is used to reset - the codec. If the chip requires a special kind of reset, you can - define this callback. - </para> - - <para> - The <structfield>wait</structfield> callback is used to - add some waiting time in the standard initialization of the codec. If the - chip requires the extra waiting time, define this callback. - </para> - - <para> - The <structfield>init</structfield> callback is used for - additional initialization of the codec. - </para> - </section> - - <section id="api-ac97-updating-registers"> - <title>Updating Registers in The Driver</title> - <para> - If you need to access to the codec from the driver, you can - call the following functions: - <function>snd_ac97_write()</function>, - <function>snd_ac97_read()</function>, - <function>snd_ac97_update()</function> and - <function>snd_ac97_update_bits()</function>. - </para> - - <para> - Both <function>snd_ac97_write()</function> and - <function>snd_ac97_update()</function> functions are used to - set a value to the given register - (<constant>AC97_XXX</constant>). The difference between them is - that <function>snd_ac97_update()</function> doesn't write a - value if the given value has been already set, while - <function>snd_ac97_write()</function> always rewrites the - value. - - <informalexample> - <programlisting> -<![CDATA[ - snd_ac97_write(ac97, AC97_MASTER, 0x8080); - snd_ac97_update(ac97, AC97_MASTER, 0x8080); -]]> - </programlisting> - </informalexample> - </para> - - <para> - <function>snd_ac97_read()</function> is used to read the value - of the given register. For example, - - <informalexample> - <programlisting> -<![CDATA[ - value = snd_ac97_read(ac97, AC97_MASTER); -]]> - </programlisting> - </informalexample> - </para> - - <para> - <function>snd_ac97_update_bits()</function> is used to update - some bits in the given register. - - <informalexample> - <programlisting> -<![CDATA[ - snd_ac97_update_bits(ac97, reg, mask, value); -]]> - </programlisting> - </informalexample> - </para> - - <para> - Also, there is a function to change the sample rate (of a - given register such as - <constant>AC97_PCM_FRONT_DAC_RATE</constant>) when VRA or - DRA is supported by the codec: - <function>snd_ac97_set_rate()</function>. - - <informalexample> - <programlisting> -<![CDATA[ - snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100); -]]> - </programlisting> - </informalexample> - </para> - - <para> - The following registers are available to set the rate: - <constant>AC97_PCM_MIC_ADC_RATE</constant>, - <constant>AC97_PCM_FRONT_DAC_RATE</constant>, - <constant>AC97_PCM_LR_ADC_RATE</constant>, - <constant>AC97_SPDIF</constant>. When - <constant>AC97_SPDIF</constant> is specified, the register is - not really changed but the corresponding IEC958 status bits will - be updated. - </para> - </section> - - <section id="api-ac97-clock-adjustment"> - <title>Clock Adjustment</title> - <para> - In some chips, the clock of the codec isn't 48000 but using a - PCI clock (to save a quartz!). In this case, change the field - bus->clock to the corresponding - value. For example, intel8x0 - and es1968 drivers have their own function to read from the clock. - </para> - </section> - - <section id="api-ac97-proc-files"> - <title>Proc Files</title> - <para> - The ALSA AC97 interface will create a proc file such as - <filename>/proc/asound/card0/codec97#0/ac97#0-0</filename> and - <filename>ac97#0-0+regs</filename>. You can refer to these files to - see the current status and registers of the codec. - </para> - </section> - - <section id="api-ac97-multiple-codecs"> - <title>Multiple Codecs</title> - <para> - When there are several codecs on the same card, you need to - call <function>snd_ac97_mixer()</function> multiple times with - ac97.num=1 or greater. The <structfield>num</structfield> field - specifies the codec number. - </para> - - <para> - If you set up multiple codecs, you either need to write - different callbacks for each codec or check - ac97->num in the callback routines. - </para> - </section> - - </chapter> - - -<!-- ****************************************************** --> -<!-- MIDI (MPU401-UART) Interface --> -<!-- ****************************************************** --> - <chapter id="midi-interface"> - <title>MIDI (MPU401-UART) Interface</title> - - <section id="midi-interface-general"> - <title>General</title> - <para> - Many soundcards have built-in MIDI (MPU401-UART) - interfaces. When the soundcard supports the standard MPU401-UART - interface, most likely you can use the ALSA MPU401-UART API. The - MPU401-UART API is defined in - <filename><sound/mpu401.h></filename>. - </para> - - <para> - Some soundchips have a similar but slightly different - implementation of mpu401 stuff. For example, emu10k1 has its own - mpu401 routines. - </para> - </section> - - <section id="midi-interface-constructor"> - <title>Constructor</title> - <para> - To create a rawmidi object, call - <function>snd_mpu401_uart_new()</function>. - - <informalexample> - <programlisting> -<![CDATA[ - struct snd_rawmidi *rmidi; - snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags, - irq, &rmidi); -]]> - </programlisting> - </informalexample> - </para> - - <para> - The first argument is the card pointer, and the second is the - index of this component. You can create up to 8 rawmidi - devices. - </para> - - <para> - The third argument is the type of the hardware, - <constant>MPU401_HW_XXX</constant>. If it's not a special one, - you can use <constant>MPU401_HW_MPU401</constant>. - </para> - - <para> - The 4th argument is the I/O port address. Many - backward-compatible MPU401 have an I/O port such as 0x330. Or, it - might be a part of its own PCI I/O region. It depends on the - chip design. - </para> - - <para> - The 5th argument is a bitflag for additional information. - When the I/O port address above is part of the PCI I/O - region, the MPU401 I/O port might have been already allocated - (reserved) by the driver itself. In such a case, pass a bit flag - <constant>MPU401_INFO_INTEGRATED</constant>, - and the mpu401-uart layer will allocate the I/O ports by itself. - </para> - - <para> - When the controller supports only the input or output MIDI stream, - pass the <constant>MPU401_INFO_INPUT</constant> or - <constant>MPU401_INFO_OUTPUT</constant> bitflag, respectively. - Then the rawmidi instance is created as a single stream. - </para> - - <para> - <constant>MPU401_INFO_MMIO</constant> bitflag is used to change - the access method to MMIO (via readb and writeb) instead of - iob and outb. In this case, you have to pass the iomapped address - to <function>snd_mpu401_uart_new()</function>. - </para> - - <para> - When <constant>MPU401_INFO_TX_IRQ</constant> is set, the output - stream isn't checked in the default interrupt handler. The driver - needs to call <function>snd_mpu401_uart_interrupt_tx()</function> - by itself to start processing the output stream in the irq handler. - </para> - - <para> - If the MPU-401 interface shares its interrupt with the other logical - devices on the card, set <constant>MPU401_INFO_IRQ_HOOK</constant> - (see <link linkend="midi-interface-interrupt-handler"><citetitle> - below</citetitle></link>). - </para> - - <para> - Usually, the port address corresponds to the command port and - port + 1 corresponds to the data port. If not, you may change - the <structfield>cport</structfield> field of - struct <structname>snd_mpu401</structname> manually - afterward. However, <structname>snd_mpu401</structname> pointer is not - returned explicitly by - <function>snd_mpu401_uart_new()</function>. You need to cast - rmidi->private_data to - <structname>snd_mpu401</structname> explicitly, - - <informalexample> - <programlisting> -<![CDATA[ - struct snd_mpu401 *mpu; - mpu = rmidi->private_data; -]]> - </programlisting> - </informalexample> - - and reset the cport as you like: - - <informalexample> - <programlisting> -<![CDATA[ - mpu->cport = my_own_control_port; -]]> - </programlisting> - </informalexample> - </para> - - <para> - The 6th argument specifies the ISA irq number that will be - allocated. If no interrupt is to be allocated (because your - code is already allocating a shared interrupt, or because the - device does not use interrupts), pass -1 instead. - For a MPU-401 device without an interrupt, a polling timer - will be used instead. - </para> - </section> - - <section id="midi-interface-interrupt-handler"> - <title>Interrupt Handler</title> - <para> - When the interrupt is allocated in - <function>snd_mpu401_uart_new()</function>, an exclusive ISA - interrupt handler is automatically used, hence you don't have - anything else to do than creating the mpu401 stuff. Otherwise, you - have to set <constant>MPU401_INFO_IRQ_HOOK</constant>, and call - <function>snd_mpu401_uart_interrupt()</function> explicitly from your - own interrupt handler when it has determined that a UART interrupt - has occurred. - </para> - - <para> - In this case, you need to pass the private_data of the - returned rawmidi object from - <function>snd_mpu401_uart_new()</function> as the second - argument of <function>snd_mpu401_uart_interrupt()</function>. - - <informalexample> - <programlisting> -<![CDATA[ - snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs); -]]> - </programlisting> - </informalexample> - </para> - </section> - - </chapter> - - -<!-- ****************************************************** --> -<!-- RawMIDI Interface --> -<!-- ****************************************************** --> - <chapter id="rawmidi-interface"> - <title>RawMIDI Interface</title> - - <section id="rawmidi-interface-overview"> - <title>Overview</title> - - <para> - The raw MIDI interface is used for hardware MIDI ports that can - be accessed as a byte stream. It is not used for synthesizer - chips that do not directly understand MIDI. - </para> - - <para> - ALSA handles file and buffer management. All you have to do is - to write some code to move data between the buffer and the - hardware. - </para> - - <para> - The rawmidi API is defined in - <filename><sound/rawmidi.h></filename>. - </para> - </section> - - <section id="rawmidi-interface-constructor"> - <title>Constructor</title> - - <para> - To create a rawmidi device, call the - <function>snd_rawmidi_new</function> function: - <informalexample> - <programlisting> -<![CDATA[ - struct snd_rawmidi *rmidi; - err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi); - if (err < 0) - return err; - rmidi->private_data = chip; - strcpy(rmidi->name, "My MIDI"); - rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT | - SNDRV_RAWMIDI_INFO_INPUT | - SNDRV_RAWMIDI_INFO_DUPLEX; -]]> - </programlisting> - </informalexample> - </para> - - <para> - The first argument is the card pointer, the second argument is - the ID string. - </para> - - <para> - The third argument is the index of this component. You can - create up to 8 rawmidi devices. - </para> - - <para> - The fourth and fifth arguments are the number of output and - input substreams, respectively, of this device (a substream is - the equivalent of a MIDI port). - </para> - - <para> - Set the <structfield>info_flags</structfield> field to specify - the capabilities of the device. - Set <constant>SNDRV_RAWMIDI_INFO_OUTPUT</constant> if there is - at least one output port, - <constant>SNDRV_RAWMIDI_INFO_INPUT</constant> if there is at - least one input port, - and <constant>SNDRV_RAWMIDI_INFO_DUPLEX</constant> if the device - can handle output and input at the same time. - </para> - - <para> - After the rawmidi device is created, you need to set the - operators (callbacks) for each substream. There are helper - functions to set the operators for all the substreams of a device: - <informalexample> - <programlisting> -<![CDATA[ - snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops); - snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops); -]]> - </programlisting> - </informalexample> - </para> - - <para> - The operators are usually defined like this: - <informalexample> - <programlisting> -<![CDATA[ - static struct snd_rawmidi_ops snd_mymidi_output_ops = { - .open = snd_mymidi_output_open, - .close = snd_mymidi_output_close, - .trigger = snd_mymidi_output_trigger, - }; -]]> - </programlisting> - </informalexample> - These callbacks are explained in the <link - linkend="rawmidi-interface-callbacks"><citetitle>Callbacks</citetitle></link> - section. - </para> - - <para> - If there are more than one substream, you should give a - unique name to each of them: - <informalexample> - <programlisting> -<![CDATA[ - struct snd_rawmidi_substream *substream; - list_for_each_entry(substream, - &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams, - list { - sprintf(substream->name, "My MIDI Port %d", substream->number + 1); - } - /* same for SNDRV_RAWMIDI_STREAM_INPUT */ -]]> - </programlisting> - </informalexample> - </para> - </section> - - <section id="rawmidi-interface-callbacks"> - <title>Callbacks</title> - - <para> - In all the callbacks, the private data that you've set for the - rawmidi device can be accessed as - substream->rmidi->private_data. - <!-- <code> isn't available before DocBook 4.3 --> - </para> - - <para> - If there is more than one port, your callbacks can determine the - port index from the struct snd_rawmidi_substream data passed to each - callback: - <informalexample> - <programlisting> -<![CDATA[ - struct snd_rawmidi_substream *substream; - int index = substream->number; -]]> - </programlisting> - </informalexample> - </para> - - <section id="rawmidi-interface-op-open"> - <title><function>open</function> callback</title> - - <informalexample> - <programlisting> -<![CDATA[ - static int snd_xxx_open(struct snd_rawmidi_substream *substream); -]]> - </programlisting> - </informalexample> - - <para> - This is called when a substream is opened. - You can initialize the hardware here, but you shouldn't - start transmitting/receiving data yet. - </para> - </section> - - <section id="rawmidi-interface-op-close"> - <title><function>close</function> callback</title> - - <informalexample> - <programlisting> -<![CDATA[ - static int snd_xxx_close(struct snd_rawmidi_substream *substream); -]]> - </programlisting> - </informalexample> - - <para> - Guess what. - </para> - - <para> - The <function>open</function> and <function>close</function> - callbacks of a rawmidi device are serialized with a mutex, - and can sleep. - </para> - </section> - - <section id="rawmidi-interface-op-trigger-out"> - <title><function>trigger</function> callback for output - substreams</title> - - <informalexample> - <programlisting> -<![CDATA[ - static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up); -]]> - </programlisting> - </informalexample> - - <para> - This is called with a nonzero <parameter>up</parameter> - parameter when there is some data in the substream buffer that - must be transmitted. - </para> - - <para> - To read data from the buffer, call - <function>snd_rawmidi_transmit_peek</function>. It will - return the number of bytes that have been read; this will be - less than the number of bytes requested when there are no more - data in the buffer. - After the data have been transmitted successfully, call - <function>snd_rawmidi_transmit_ack</function> to remove the - data from the substream buffer: - <informalexample> - <programlisting> -<![CDATA[ - unsigned char data; - while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) { - if (snd_mychip_try_to_transmit(data)) - snd_rawmidi_transmit_ack(substream, 1); - else - break; /* hardware FIFO full */ - } -]]> - </programlisting> - </informalexample> - </para> - - <para> - If you know beforehand that the hardware will accept data, you - can use the <function>snd_rawmidi_transmit</function> function - which reads some data and removes them from the buffer at once: - <informalexample> - <programlisting> -<![CDATA[ - while (snd_mychip_transmit_possible()) { - unsigned char data; - if (snd_rawmidi_transmit(substream, &data, 1) != 1) - break; /* no more data */ - snd_mychip_transmit(data); - } -]]> - </programlisting> - </informalexample> - </para> - - <para> - If you know beforehand how many bytes you can accept, you can - use a buffer size greater than one with the - <function>snd_rawmidi_transmit*</function> functions. - </para> - - <para> - The <function>trigger</function> callback must not sleep. If - the hardware FIFO is full before the substream buffer has been - emptied, you have to continue transmitting data later, either - in an interrupt handler, or with a timer if the hardware - doesn't have a MIDI transmit interrupt. - </para> - - <para> - The <function>trigger</function> callback is called with a - zero <parameter>up</parameter> parameter when the transmission - of data should be aborted. - </para> - </section> - - <section id="rawmidi-interface-op-trigger-in"> - <title><function>trigger</function> callback for input - substreams</title> - - <informalexample> - <programlisting> -<![CDATA[ - static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up); -]]> - </programlisting> - </informalexample> - - <para> - This is called with a nonzero <parameter>up</parameter> - parameter to enable receiving data, or with a zero - <parameter>up</parameter> parameter do disable receiving data. - </para> - - <para> - The <function>trigger</function> callback must not sleep; the - actual reading of data from the device is usually done in an - interrupt handler. - </para> - - <para> - When data reception is enabled, your interrupt handler should - call <function>snd_rawmidi_receive</function> for all received - data: - <informalexample> - <programlisting> -<![CDATA[ - void snd_mychip_midi_interrupt(...) - { - while (mychip_midi_available()) { - unsigned char data; - data = mychip_midi_read(); - snd_rawmidi_receive(substream, &data, 1); - } - } -]]> - </programlisting> - </informalexample> - </para> - </section> - - <section id="rawmidi-interface-op-drain"> - <title><function>drain</function> callback</title> - - <informalexample> - <programlisting> -<![CDATA[ - static void snd_xxx_drain(struct snd_rawmidi_substream *substream); -]]> - </programlisting> - </informalexample> - - <para> - This is only used with output substreams. This function should wait - until all data read from the substream buffer have been transmitted. - This ensures that the device can be closed and the driver unloaded - without losing data. - </para> - - <para> - This callback is optional. If you do not set - <structfield>drain</structfield> in the struct snd_rawmidi_ops - structure, ALSA will simply wait for 50 milliseconds - instead. - </para> - </section> - </section> - - </chapter> - - -<!-- ****************************************************** --> -<!-- Miscellaneous Devices --> -<!-- ****************************************************** --> - <chapter id="misc-devices"> - <title>Miscellaneous Devices</title> - - <section id="misc-devices-opl3"> - <title>FM OPL3</title> - <para> - The FM OPL3 is still used in many chips (mainly for backward - compatibility). ALSA has a nice OPL3 FM control layer, too. The - OPL3 API is defined in - <filename><sound/opl3.h></filename>. - </para> - - <para> - FM registers can be directly accessed through the direct-FM API, - defined in <filename><sound/asound_fm.h></filename>. In - ALSA native mode, FM registers are accessed through - the Hardware-Dependent Device direct-FM extension API, whereas in - OSS compatible mode, FM registers can be accessed with the OSS - direct-FM compatible API in <filename>/dev/dmfmX</filename> device. - </para> - - <para> - To create the OPL3 component, you have two functions to - call. The first one is a constructor for the <type>opl3_t</type> - instance. - - <informalexample> - <programlisting> -<![CDATA[ - struct snd_opl3 *opl3; - snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX, - integrated, &opl3); -]]> - </programlisting> - </informalexample> - </para> - - <para> - The first argument is the card pointer, the second one is the - left port address, and the third is the right port address. In - most cases, the right port is placed at the left port + 2. - </para> - - <para> - The fourth argument is the hardware type. - </para> - - <para> - When the left and right ports have been already allocated by - the card driver, pass non-zero to the fifth argument - (<parameter>integrated</parameter>). Otherwise, the opl3 module will - allocate the specified ports by itself. - </para> - - <para> - When the accessing the hardware requires special method - instead of the standard I/O access, you can create opl3 instance - separately with <function>snd_opl3_new()</function>. - - <informalexample> - <programlisting> -<![CDATA[ - struct snd_opl3 *opl3; - snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3); -]]> - </programlisting> - </informalexample> - </para> - - <para> - Then set <structfield>command</structfield>, - <structfield>private_data</structfield> and - <structfield>private_free</structfield> for the private - access function, the private data and the destructor. - The l_port and r_port are not necessarily set. Only the - command must be set properly. You can retrieve the data - from the opl3->private_data field. - </para> - - <para> - After creating the opl3 instance via <function>snd_opl3_new()</function>, - call <function>snd_opl3_init()</function> to initialize the chip to the - proper state. Note that <function>snd_opl3_create()</function> always - calls it internally. - </para> - - <para> - If the opl3 instance is created successfully, then create a - hwdep device for this opl3. - - <informalexample> - <programlisting> -<![CDATA[ - struct snd_hwdep *opl3hwdep; - snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep); -]]> - </programlisting> - </informalexample> - </para> - - <para> - The first argument is the <type>opl3_t</type> instance you - created, and the second is the index number, usually 0. - </para> - - <para> - The third argument is the index-offset for the sequencer - client assigned to the OPL3 port. When there is an MPU401-UART, - give 1 for here (UART always takes 0). - </para> - </section> - - <section id="misc-devices-hardware-dependent"> - <title>Hardware-Dependent Devices</title> - <para> - Some chips need user-space access for special - controls or for loading the micro code. In such a case, you can - create a hwdep (hardware-dependent) device. The hwdep API is - defined in <filename><sound/hwdep.h></filename>. You can - find examples in opl3 driver or - <filename>isa/sb/sb16_csp.c</filename>. - </para> - - <para> - The creation of the <type>hwdep</type> instance is done via - <function>snd_hwdep_new()</function>. - - <informalexample> - <programlisting> -<![CDATA[ - struct snd_hwdep *hw; - snd_hwdep_new(card, "My HWDEP", 0, &hw); -]]> - </programlisting> - </informalexample> - - where the third argument is the index number. - </para> - - <para> - You can then pass any pointer value to the - <parameter>private_data</parameter>. - If you assign a private data, you should define the - destructor, too. The destructor function is set in - the <structfield>private_free</structfield> field. - - <informalexample> - <programlisting> -<![CDATA[ - struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL); - hw->private_data = p; - hw->private_free = mydata_free; -]]> - </programlisting> - </informalexample> - - and the implementation of the destructor would be: - - <informalexample> - <programlisting> -<![CDATA[ - static void mydata_free(struct snd_hwdep *hw) - { - struct mydata *p = hw->private_data; - kfree(p); - } -]]> - </programlisting> - </informalexample> - </para> - - <para> - The arbitrary file operations can be defined for this - instance. The file operators are defined in - the <parameter>ops</parameter> table. For example, assume that - this chip needs an ioctl. - - <informalexample> - <programlisting> -<![CDATA[ - hw->ops.open = mydata_open; - hw->ops.ioctl = mydata_ioctl; - hw->ops.release = mydata_release; -]]> - </programlisting> - </informalexample> - - And implement the callback functions as you like. - </para> - </section> - - <section id="misc-devices-IEC958"> - <title>IEC958 (S/PDIF)</title> - <para> - Usually the controls for IEC958 devices are implemented via - the control interface. There is a macro to compose a name string for - IEC958 controls, <function>SNDRV_CTL_NAME_IEC958()</function> - defined in <filename><include/asound.h></filename>. - </para> - - <para> - There are some standard controls for IEC958 status bits. These - controls use the type <type>SNDRV_CTL_ELEM_TYPE_IEC958</type>, - and the size of element is fixed as 4 bytes array - (value.iec958.status[x]). For the <structfield>info</structfield> - callback, you don't specify - the value field for this type (the count field must be set, - though). - </para> - - <para> - <quote>IEC958 Playback Con Mask</quote> is used to return the - bit-mask for the IEC958 status bits of consumer mode. Similarly, - <quote>IEC958 Playback Pro Mask</quote> returns the bitmask for - professional mode. They are read-only controls, and are defined - as MIXER controls (iface = - <constant>SNDRV_CTL_ELEM_IFACE_MIXER</constant>). - </para> - - <para> - Meanwhile, <quote>IEC958 Playback Default</quote> control is - defined for getting and setting the current default IEC958 - bits. Note that this one is usually defined as a PCM control - (iface = <constant>SNDRV_CTL_ELEM_IFACE_PCM</constant>), - although in some places it's defined as a MIXER control. - </para> - - <para> - In addition, you can define the control switches to - enable/disable or to set the raw bit mode. The implementation - will depend on the chip, but the control should be named as - <quote>IEC958 xxx</quote>, preferably using - the <function>SNDRV_CTL_NAME_IEC958()</function> macro. - </para> - - <para> - You can find several cases, for example, - <filename>pci/emu10k1</filename>, - <filename>pci/ice1712</filename>, or - <filename>pci/cmipci.c</filename>. - </para> - </section> - - </chapter> - - -<!-- ****************************************************** --> -<!-- Buffer and Memory Management --> -<!-- ****************************************************** --> - <chapter id="buffer-and-memory"> - <title>Buffer and Memory Management</title> - - <section id="buffer-and-memory-buffer-types"> - <title>Buffer Types</title> - <para> - ALSA provides several different buffer allocation functions - depending on the bus and the architecture. All these have a - consistent API. The allocation of physically-contiguous pages is - done via - <function>snd_malloc_xxx_pages()</function> function, where xxx - is the bus type. - </para> - - <para> - The allocation of pages with fallback is - <function>snd_malloc_xxx_pages_fallback()</function>. This - function tries to allocate the specified pages but if the pages - are not available, it tries to reduce the page sizes until - enough space is found. - </para> - - <para> - The release the pages, call - <function>snd_free_xxx_pages()</function> function. - </para> - - <para> - Usually, ALSA drivers try to allocate and reserve - a large contiguous physical space - at the time the module is loaded for the later use. - This is called <quote>pre-allocation</quote>. - As already written, you can call the following function at - pcm instance construction time (in the case of PCI bus). - - <informalexample> - <programlisting> -<![CDATA[ - snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV, - snd_dma_pci_data(pci), size, max); -]]> - </programlisting> - </informalexample> - - where <parameter>size</parameter> is the byte size to be - pre-allocated and the <parameter>max</parameter> is the maximum - size to be changed via the <filename>prealloc</filename> proc file. - The allocator will try to get an area as large as possible - within the given size. - </para> - - <para> - The second argument (type) and the third argument (device pointer) - are dependent on the bus. - In the case of the ISA bus, pass <function>snd_dma_isa_data()</function> - as the third argument with <constant>SNDRV_DMA_TYPE_DEV</constant> type. - For the continuous buffer unrelated to the bus can be pre-allocated - with <constant>SNDRV_DMA_TYPE_CONTINUOUS</constant> type and the - <function>snd_dma_continuous_data(GFP_KERNEL)</function> device pointer, - where <constant>GFP_KERNEL</constant> is the kernel allocation flag to - use. - For the PCI scatter-gather buffers, use - <constant>SNDRV_DMA_TYPE_DEV_SG</constant> with - <function>snd_dma_pci_data(pci)</function> - (see the - <link linkend="buffer-and-memory-non-contiguous"><citetitle>Non-Contiguous Buffers - </citetitle></link> section). - </para> - - <para> - Once the buffer is pre-allocated, you can use the - allocator in the <structfield>hw_params</structfield> callback: - - <informalexample> - <programlisting> -<![CDATA[ - snd_pcm_lib_malloc_pages(substream, size); -]]> - </programlisting> - </informalexample> - - Note that you have to pre-allocate to use this function. - </para> - </section> - - <section id="buffer-and-memory-external-hardware"> - <title>External Hardware Buffers</title> - <para> - Some chips have their own hardware buffers and the DMA - transfer from the host memory is not available. In such a case, - you need to either 1) copy/set the audio data directly to the - external hardware buffer, or 2) make an intermediate buffer and - copy/set the data from it to the external hardware buffer in - interrupts (or in tasklets, preferably). - </para> - - <para> - The first case works fine if the external hardware buffer is large - enough. This method doesn't need any extra buffers and thus is - more effective. You need to define the - <structfield>copy</structfield> and - <structfield>silence</structfield> callbacks for - the data transfer. However, there is a drawback: it cannot - be mmapped. The examples are GUS's GF1 PCM or emu8000's - wavetable PCM. - </para> - - <para> - The second case allows for mmap on the buffer, although you have - to handle an interrupt or a tasklet to transfer the data - from the intermediate buffer to the hardware buffer. You can find an - example in the vxpocket driver. - </para> - - <para> - Another case is when the chip uses a PCI memory-map - region for the buffer instead of the host memory. In this case, - mmap is available only on certain architectures like the Intel one. - In non-mmap mode, the data cannot be transferred as in the normal - way. Thus you need to define the <structfield>copy</structfield> and - <structfield>silence</structfield> callbacks as well, - as in the cases above. The examples are found in - <filename>rme32.c</filename> and <filename>rme96.c</filename>. - </para> - - <para> - The implementation of the <structfield>copy</structfield> and - <structfield>silence</structfield> callbacks depends upon - whether the hardware supports interleaved or non-interleaved - samples. The <structfield>copy</structfield> callback is - defined like below, a bit - differently depending whether the direction is playback or - capture: - - <informalexample> - <programlisting> -<![CDATA[ - static int playback_copy(struct snd_pcm_substream *substream, int channel, - snd_pcm_uframes_t pos, void *src, snd_pcm_uframes_t count); - static int capture_copy(struct snd_pcm_substream *substream, int channel, - snd_pcm_uframes_t pos, void *dst, snd_pcm_uframes_t count); -]]> - </programlisting> - </informalexample> - </para> - - <para> - In the case of interleaved samples, the second argument - (<parameter>channel</parameter>) is not used. The third argument - (<parameter>pos</parameter>) points the - current position offset in frames. - </para> - - <para> - The meaning of the fourth argument is different between - playback and capture. For playback, it holds the source data - pointer, and for capture, it's the destination data pointer. - </para> - - <para> - The last argument is the number of frames to be copied. - </para> - - <para> - What you have to do in this callback is again different - between playback and capture directions. In the - playback case, you copy the given amount of data - (<parameter>count</parameter>) at the specified pointer - (<parameter>src</parameter>) to the specified offset - (<parameter>pos</parameter>) on the hardware buffer. When - coded like memcpy-like way, the copy would be like: - - <informalexample> - <programlisting> -<![CDATA[ - my_memcpy(my_buffer + frames_to_bytes(runtime, pos), src, - frames_to_bytes(runtime, count)); -]]> - </programlisting> - </informalexample> - </para> - - <para> - For the capture direction, you copy the given amount of - data (<parameter>count</parameter>) at the specified offset - (<parameter>pos</parameter>) on the hardware buffer to the - specified pointer (<parameter>dst</parameter>). - - <informalexample> - <programlisting> -<![CDATA[ - my_memcpy(dst, my_buffer + frames_to_bytes(runtime, pos), - frames_to_bytes(runtime, count)); -]]> - </programlisting> - </informalexample> - - Note that both the position and the amount of data are given - in frames. - </para> - - <para> - In the case of non-interleaved samples, the implementation - will be a bit more complicated. - </para> - - <para> - You need to check the channel argument, and if it's -1, copy - the whole channels. Otherwise, you have to copy only the - specified channel. Please check - <filename>isa/gus/gus_pcm.c</filename> as an example. - </para> - - <para> - The <structfield>silence</structfield> callback is also - implemented in a similar way. - - <informalexample> - <programlisting> -<![CDATA[ - static int silence(struct snd_pcm_substream *substream, int channel, - snd_pcm_uframes_t pos, snd_pcm_uframes_t count); -]]> - </programlisting> - </informalexample> - </para> - - <para> - The meanings of arguments are the same as in the - <structfield>copy</structfield> - callback, although there is no <parameter>src/dst</parameter> - argument. In the case of interleaved samples, the channel - argument has no meaning, as well as on - <structfield>copy</structfield> callback. - </para> - - <para> - The role of <structfield>silence</structfield> callback is to - set the given amount - (<parameter>count</parameter>) of silence data at the - specified offset (<parameter>pos</parameter>) on the hardware - buffer. Suppose that the data format is signed (that is, the - silent-data is 0), and the implementation using a memset-like - function would be like: - - <informalexample> - <programlisting> -<![CDATA[ - my_memcpy(my_buffer + frames_to_bytes(runtime, pos), 0, - frames_to_bytes(runtime, count)); -]]> - </programlisting> - </informalexample> - </para> - - <para> - In the case of non-interleaved samples, again, the - implementation becomes a bit more complicated. See, for example, - <filename>isa/gus/gus_pcm.c</filename>. - </para> - </section> - - <section id="buffer-and-memory-non-contiguous"> - <title>Non-Contiguous Buffers</title> - <para> - If your hardware supports the page table as in emu10k1 or the - buffer descriptors as in via82xx, you can use the scatter-gather - (SG) DMA. ALSA provides an interface for handling SG-buffers. - The API is provided in <filename><sound/pcm.h></filename>. - </para> - - <para> - For creating the SG-buffer handler, call - <function>snd_pcm_lib_preallocate_pages()</function> or - <function>snd_pcm_lib_preallocate_pages_for_all()</function> - with <constant>SNDRV_DMA_TYPE_DEV_SG</constant> - in the PCM constructor like other PCI pre-allocator. - You need to pass <function>snd_dma_pci_data(pci)</function>, - where pci is the struct <structname>pci_dev</structname> pointer - of the chip as well. - The <type>struct snd_sg_buf</type> instance is created as - substream->dma_private. You can cast - the pointer like: - - <informalexample> - <programlisting> -<![CDATA[ - struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private; -]]> - </programlisting> - </informalexample> - </para> - - <para> - Then call <function>snd_pcm_lib_malloc_pages()</function> - in the <structfield>hw_params</structfield> callback - as well as in the case of normal PCI buffer. - The SG-buffer handler will allocate the non-contiguous kernel - pages of the given size and map them onto the virtually contiguous - memory. The virtual pointer is addressed in runtime->dma_area. - The physical address (runtime->dma_addr) is set to zero, - because the buffer is physically non-contiguous. - The physical address table is set up in sgbuf->table. - You can get the physical address at a certain offset via - <function>snd_pcm_sgbuf_get_addr()</function>. - </para> - - <para> - When a SG-handler is used, you need to set - <function>snd_pcm_sgbuf_ops_page</function> as - the <structfield>page</structfield> callback. - (See <link linkend="pcm-interface-operators-page-callback"> - <citetitle>page callback section</citetitle></link>.) - </para> - - <para> - To release the data, call - <function>snd_pcm_lib_free_pages()</function> in the - <structfield>hw_free</structfield> callback as usual. - </para> - </section> - - <section id="buffer-and-memory-vmalloced"> - <title>Vmalloc'ed Buffers</title> - <para> - It's possible to use a buffer allocated via - <function>vmalloc</function>, for example, for an intermediate - buffer. Since the allocated pages are not contiguous, you need - to set the <structfield>page</structfield> callback to obtain - the physical address at every offset. - </para> - - <para> - The implementation of <structfield>page</structfield> callback - would be like this: - - <informalexample> - <programlisting> -<![CDATA[ - #include <linux/vmalloc.h> - - /* get the physical page pointer on the given offset */ - static struct page *mychip_page(struct snd_pcm_substream *substream, - unsigned long offset) - { - void *pageptr = substream->runtime->dma_area + offset; - return vmalloc_to_page(pageptr); - } -]]> - </programlisting> - </informalexample> - </para> - </section> - - </chapter> - - -<!-- ****************************************************** --> -<!-- Proc Interface --> -<!-- ****************************************************** --> - <chapter id="proc-interface"> - <title>Proc Interface</title> - <para> - ALSA provides an easy interface for procfs. The proc files are - very useful for debugging. I recommend you set up proc files if - you write a driver and want to get a running status or register - dumps. The API is found in - <filename><sound/info.h></filename>. - </para> - - <para> - To create a proc file, call - <function>snd_card_proc_new()</function>. - - <informalexample> - <programlisting> -<![CDATA[ - struct snd_info_entry *entry; - int err = snd_card_proc_new(card, "my-file", &entry); -]]> - </programlisting> - </informalexample> - - where the second argument specifies the name of the proc file to be - created. The above example will create a file - <filename>my-file</filename> under the card directory, - e.g. <filename>/proc/asound/card0/my-file</filename>. - </para> - - <para> - Like other components, the proc entry created via - <function>snd_card_proc_new()</function> will be registered and - released automatically in the card registration and release - functions. - </para> - - <para> - When the creation is successful, the function stores a new - instance in the pointer given in the third argument. - It is initialized as a text proc file for read only. To use - this proc file as a read-only text file as it is, set the read - callback with a private data via - <function>snd_info_set_text_ops()</function>. - - <informalexample> - <programlisting> -<![CDATA[ - snd_info_set_text_ops(entry, chip, my_proc_read); -]]> - </programlisting> - </informalexample> - - where the second argument (<parameter>chip</parameter>) is the - private data to be used in the callbacks. The third parameter - specifies the read buffer size and the fourth - (<parameter>my_proc_read</parameter>) is the callback function, which - is defined like - - <informalexample> - <programlisting> -<![CDATA[ - static void my_proc_read(struct snd_info_entry *entry, - struct snd_info_buffer *buffer); -]]> - </programlisting> - </informalexample> - - </para> - - <para> - In the read callback, use <function>snd_iprintf()</function> for - output strings, which works just like normal - <function>printf()</function>. For example, - - <informalexample> - <programlisting> -<![CDATA[ - static void my_proc_read(struct snd_info_entry *entry, - struct snd_info_buffer *buffer) - { - struct my_chip *chip = entry->private_data; - - snd_iprintf(buffer, "This is my chip!\n"); - snd_iprintf(buffer, "Port = %ld\n", chip->port); - } -]]> - </programlisting> - </informalexample> - </para> - - <para> - The file permissions can be changed afterwards. As default, it's - set as read only for all users. If you want to add write - permission for the user (root as default), do as follows: - - <informalexample> - <programlisting> -<![CDATA[ - entry->mode = S_IFREG | S_IRUGO | S_IWUSR; -]]> - </programlisting> - </informalexample> - - and set the write buffer size and the callback - - <informalexample> - <programlisting> -<![CDATA[ - entry->c.text.write = my_proc_write; -]]> - </programlisting> - </informalexample> - </para> - - <para> - For the write callback, you can use - <function>snd_info_get_line()</function> to get a text line, and - <function>snd_info_get_str()</function> to retrieve a string from - the line. Some examples are found in - <filename>core/oss/mixer_oss.c</filename>, core/oss/and - <filename>pcm_oss.c</filename>. - </para> - - <para> - For a raw-data proc-file, set the attributes as follows: - - <informalexample> - <programlisting> -<![CDATA[ - static struct snd_info_entry_ops my_file_io_ops = { - .read = my_file_io_read, - }; - - entry->content = SNDRV_INFO_CONTENT_DATA; - entry->private_data = chip; - entry->c.ops = &my_file_io_ops; - entry->size = 4096; - entry->mode = S_IFREG | S_IRUGO; -]]> - </programlisting> - </informalexample> - - For the raw data, <structfield>size</structfield> field must be - set properly. This specifies the maximum size of the proc file access. - </para> - - <para> - The read/write callbacks of raw mode are more direct than the text mode. - You need to use a low-level I/O functions such as - <function>copy_from/to_user()</function> to transfer the - data. - - <informalexample> - <programlisting> -<![CDATA[ - static ssize_t my_file_io_read(struct snd_info_entry *entry, - void *file_private_data, - struct file *file, - char *buf, - size_t count, - loff_t pos) - { - if (copy_to_user(buf, local_data + pos, count)) - return -EFAULT; - return count; - } -]]> - </programlisting> - </informalexample> - - If the size of the info entry has been set up properly, - <structfield>count</structfield> and <structfield>pos</structfield> are - guaranteed to fit within 0 and the given size. - You don't have to check the range in the callbacks unless any - other condition is required. - - </para> - - </chapter> - - -<!-- ****************************************************** --> -<!-- Power Management --> -<!-- ****************************************************** --> - <chapter id="power-management"> - <title>Power Management</title> - <para> - If the chip is supposed to work with suspend/resume - functions, you need to add power-management code to the - driver. The additional code for power-management should be - <function>ifdef</function>'ed with - <constant>CONFIG_PM</constant>. - </para> - - <para> - If the driver <emphasis>fully</emphasis> supports suspend/resume - that is, the device can be - properly resumed to its state when suspend was called, - you can set the <constant>SNDRV_PCM_INFO_RESUME</constant> flag - in the pcm info field. Usually, this is possible when the - registers of the chip can be safely saved and restored to - RAM. If this is set, the trigger callback is called with - <constant>SNDRV_PCM_TRIGGER_RESUME</constant> after the resume - callback completes. - </para> - - <para> - Even if the driver doesn't support PM fully but - partial suspend/resume is still possible, it's still worthy to - implement suspend/resume callbacks. In such a case, applications - would reset the status by calling - <function>snd_pcm_prepare()</function> and restart the stream - appropriately. Hence, you can define suspend/resume callbacks - below but don't set <constant>SNDRV_PCM_INFO_RESUME</constant> - info flag to the PCM. - </para> - - <para> - Note that the trigger with SUSPEND can always be called when - <function>snd_pcm_suspend_all</function> is called, - regardless of the <constant>SNDRV_PCM_INFO_RESUME</constant> flag. - The <constant>RESUME</constant> flag affects only the behavior - of <function>snd_pcm_resume()</function>. - (Thus, in theory, - <constant>SNDRV_PCM_TRIGGER_RESUME</constant> isn't needed - to be handled in the trigger callback when no - <constant>SNDRV_PCM_INFO_RESUME</constant> flag is set. But, - it's better to keep it for compatibility reasons.) - </para> - <para> - In the earlier version of ALSA drivers, a common - power-management layer was provided, but it has been removed. - The driver needs to define the suspend/resume hooks according to - the bus the device is connected to. In the case of PCI drivers, the - callbacks look like below: - - <informalexample> - <programlisting> -<![CDATA[ - #ifdef CONFIG_PM - static int snd_my_suspend(struct pci_dev *pci, pm_message_t state) - { - .... /* do things for suspend */ - return 0; - } - static int snd_my_resume(struct pci_dev *pci) - { - .... /* do things for suspend */ - return 0; - } - #endif -]]> - </programlisting> - </informalexample> - </para> - - <para> - The scheme of the real suspend job is as follows. - - <orderedlist> - <listitem><para>Retrieve the card and the chip data.</para></listitem> - <listitem><para>Call <function>snd_power_change_state()</function> with - <constant>SNDRV_CTL_POWER_D3hot</constant> to change the - power status.</para></listitem> - <listitem><para>Call <function>snd_pcm_suspend_all()</function> to suspend the running PCM streams.</para></listitem> - <listitem><para>If AC97 codecs are used, call - <function>snd_ac97_suspend()</function> for each codec.</para></listitem> - <listitem><para>Save the register values if necessary.</para></listitem> - <listitem><para>Stop the hardware if necessary.</para></listitem> - <listitem><para>Disable the PCI device by calling - <function>pci_disable_device()</function>. Then, call - <function>pci_save_state()</function> at last.</para></listitem> - </orderedlist> - </para> - - <para> - A typical code would be like: - - <informalexample> - <programlisting> -<![CDATA[ - static int mychip_suspend(struct pci_dev *pci, pm_message_t state) - { - /* (1) */ - struct snd_card *card = pci_get_drvdata(pci); - struct mychip *chip = card->private_data; - /* (2) */ - snd_power_change_state(card, SNDRV_CTL_POWER_D3hot); - /* (3) */ - snd_pcm_suspend_all(chip->pcm); - /* (4) */ - snd_ac97_suspend(chip->ac97); - /* (5) */ - snd_mychip_save_registers(chip); - /* (6) */ - snd_mychip_stop_hardware(chip); - /* (7) */ - pci_disable_device(pci); - pci_save_state(pci); - return 0; - } -]]> - </programlisting> - </informalexample> - </para> - - <para> - The scheme of the real resume job is as follows. - - <orderedlist> - <listitem><para>Retrieve the card and the chip data.</para></listitem> - <listitem><para>Set up PCI. First, call <function>pci_restore_state()</function>. - Then enable the pci device again by calling <function>pci_enable_device()</function>. - Call <function>pci_set_master()</function> if necessary, too.</para></listitem> - <listitem><para>Re-initialize the chip.</para></listitem> - <listitem><para>Restore the saved registers if necessary.</para></listitem> - <listitem><para>Resume the mixer, e.g. calling - <function>snd_ac97_resume()</function>.</para></listitem> - <listitem><para>Restart the hardware (if any).</para></listitem> - <listitem><para>Call <function>snd_power_change_state()</function> with - <constant>SNDRV_CTL_POWER_D0</constant> to notify the processes.</para></listitem> - </orderedlist> - </para> - - <para> - A typical code would be like: - - <informalexample> - <programlisting> -<![CDATA[ - static int mychip_resume(struct pci_dev *pci) - { - /* (1) */ - struct snd_card *card = pci_get_drvdata(pci); - struct mychip *chip = card->private_data; - /* (2) */ - pci_restore_state(pci); - pci_enable_device(pci); - pci_set_master(pci); - /* (3) */ - snd_mychip_reinit_chip(chip); - /* (4) */ - snd_mychip_restore_registers(chip); - /* (5) */ - snd_ac97_resume(chip->ac97); - /* (6) */ - snd_mychip_restart_chip(chip); - /* (7) */ - snd_power_change_state(card, SNDRV_CTL_POWER_D0); - return 0; - } -]]> - </programlisting> - </informalexample> - </para> - - <para> - As shown in the above, it's better to save registers after - suspending the PCM operations via - <function>snd_pcm_suspend_all()</function> or - <function>snd_pcm_suspend()</function>. It means that the PCM - streams are already stopped when the register snapshot is - taken. But, remember that you don't have to restart the PCM - stream in the resume callback. It'll be restarted via - trigger call with <constant>SNDRV_PCM_TRIGGER_RESUME</constant> - when necessary. - </para> - - <para> - OK, we have all callbacks now. Let's set them up. In the - initialization of the card, make sure that you can get the chip - data from the card instance, typically via - <structfield>private_data</structfield> field, in case you - created the chip data individually. - - <informalexample> - <programlisting> -<![CDATA[ - static int snd_mychip_probe(struct pci_dev *pci, - const struct pci_device_id *pci_id) - { - .... - struct snd_card *card; - struct mychip *chip; - int err; - .... - err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, - 0, &card); - .... - chip = kzalloc(sizeof(*chip), GFP_KERNEL); - .... - card->private_data = chip; - .... - } -]]> - </programlisting> - </informalexample> - - When you created the chip data with - <function>snd_card_new()</function>, it's anyway accessible - via <structfield>private_data</structfield> field. - - <informalexample> - <programlisting> -<![CDATA[ - static int snd_mychip_probe(struct pci_dev *pci, - const struct pci_device_id *pci_id) - { - .... - struct snd_card *card; - struct mychip *chip; - int err; - .... - err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, - sizeof(struct mychip), &card); - .... - chip = card->private_data; - .... - } -]]> - </programlisting> - </informalexample> - - </para> - - <para> - If you need a space to save the registers, allocate the - buffer for it here, too, since it would be fatal - if you cannot allocate a memory in the suspend phase. - The allocated buffer should be released in the corresponding - destructor. - </para> - - <para> - And next, set suspend/resume callbacks to the pci_driver. - - <informalexample> - <programlisting> -<![CDATA[ - static struct pci_driver driver = { - .name = KBUILD_MODNAME, - .id_table = snd_my_ids, - .probe = snd_my_probe, - .remove = snd_my_remove, - #ifdef CONFIG_PM - .suspend = snd_my_suspend, - .resume = snd_my_resume, - #endif - }; -]]> - </programlisting> - </informalexample> - </para> - - </chapter> - - -<!-- ****************************************************** --> -<!-- Module Parameters --> -<!-- ****************************************************** --> - <chapter id="module-parameters"> - <title>Module Parameters</title> - <para> - There are standard module options for ALSA. At least, each - module should have the <parameter>index</parameter>, - <parameter>id</parameter> and <parameter>enable</parameter> - options. - </para> - - <para> - If the module supports multiple cards (usually up to - 8 = <constant>SNDRV_CARDS</constant> cards), they should be - arrays. The default initial values are defined already as - constants for easier programming: - - <informalexample> - <programlisting> -<![CDATA[ - static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX; - static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR; - static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP; -]]> - </programlisting> - </informalexample> - </para> - - <para> - If the module supports only a single card, they could be single - variables, instead. <parameter>enable</parameter> option is not - always necessary in this case, but it would be better to have a - dummy option for compatibility. - </para> - - <para> - The module parameters must be declared with the standard - <function>module_param()()</function>, - <function>module_param_array()()</function> and - <function>MODULE_PARM_DESC()</function> macros. - </para> - - <para> - The typical coding would be like below: - - <informalexample> - <programlisting> -<![CDATA[ - #define CARD_NAME "My Chip" - - module_param_array(index, int, NULL, 0444); - MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard."); - module_param_array(id, charp, NULL, 0444); - MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard."); - module_param_array(enable, bool, NULL, 0444); - MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard."); -]]> - </programlisting> - </informalexample> - </para> - - <para> - Also, don't forget to define the module description, classes, - license and devices. Especially, the recent modprobe requires to - define the module license as GPL, etc., otherwise the system is - shown as <quote>tainted</quote>. - - <informalexample> - <programlisting> -<![CDATA[ - MODULE_DESCRIPTION("My Chip"); - MODULE_LICENSE("GPL"); - MODULE_SUPPORTED_DEVICE("{{Vendor,My Chip Name}}"); -]]> - </programlisting> - </informalexample> - </para> - - </chapter> - - -<!-- ****************************************************** --> -<!-- How To Put Your Driver --> -<!-- ****************************************************** --> - <chapter id="how-to-put-your-driver"> - <title>How To Put Your Driver Into ALSA Tree</title> - <section> - <title>General</title> - <para> - So far, you've learned how to write the driver codes. - And you might have a question now: how to put my own - driver into the ALSA driver tree? - Here (finally :) the standard procedure is described briefly. - </para> - - <para> - Suppose that you create a new PCI driver for the card - <quote>xyz</quote>. The card module name would be - snd-xyz. The new driver is usually put into the alsa-driver - tree, <filename>alsa-driver/pci</filename> directory in - the case of PCI cards. - Then the driver is evaluated, audited and tested - by developers and users. After a certain time, the driver - will go to the alsa-kernel tree (to the corresponding directory, - such as <filename>alsa-kernel/pci</filename>) and eventually - will be integrated into the Linux 2.6 tree (the directory would be - <filename>linux/sound/pci</filename>). - </para> - - <para> - In the following sections, the driver code is supposed - to be put into alsa-driver tree. The two cases are covered: - a driver consisting of a single source file and one consisting - of several source files. - </para> - </section> - - <section> - <title>Driver with A Single Source File</title> - <para> - <orderedlist> - <listitem> - <para> - Modify alsa-driver/pci/Makefile - </para> - - <para> - Suppose you have a file xyz.c. Add the following - two lines - <informalexample> - <programlisting> -<![CDATA[ - snd-xyz-objs := xyz.o - obj-$(CONFIG_SND_XYZ) += snd-xyz.o -]]> - </programlisting> - </informalexample> - </para> - </listitem> - - <listitem> - <para> - Create the Kconfig entry - </para> - - <para> - Add the new entry of Kconfig for your xyz driver. - <informalexample> - <programlisting> -<![CDATA[ - config SND_XYZ - tristate "Foobar XYZ" - depends on SND - select SND_PCM - help - Say Y here to include support for Foobar XYZ soundcard. - - To compile this driver as a module, choose M here: the module - will be called snd-xyz. -]]> - </programlisting> - </informalexample> - - the line, select SND_PCM, specifies that the driver xyz supports - PCM. In addition to SND_PCM, the following components are - supported for select command: - SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART, - SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC. - Add the select command for each supported component. - </para> - - <para> - Note that some selections imply the lowlevel selections. - For example, PCM includes TIMER, MPU401_UART includes RAWMIDI, - AC97_CODEC includes PCM, and OPL3_LIB includes HWDEP. - You don't need to give the lowlevel selections again. - </para> - - <para> - For the details of Kconfig script, refer to the kbuild - documentation. - </para> - - </listitem> - - <listitem> - <para> - Run cvscompile script to re-generate the configure script and - build the whole stuff again. - </para> - </listitem> - </orderedlist> - </para> - </section> - - <section> - <title>Drivers with Several Source Files</title> - <para> - Suppose that the driver snd-xyz have several source files. - They are located in the new subdirectory, - pci/xyz. - - <orderedlist> - <listitem> - <para> - Add a new directory (<filename>xyz</filename>) in - <filename>alsa-driver/pci/Makefile</filename> as below - - <informalexample> - <programlisting> -<![CDATA[ - obj-$(CONFIG_SND) += xyz/ -]]> - </programlisting> - </informalexample> - </para> - </listitem> - - <listitem> - <para> - Under the directory <filename>xyz</filename>, create a Makefile - - <example> - <title>Sample Makefile for a driver xyz</title> - <programlisting> -<![CDATA[ - ifndef SND_TOPDIR - SND_TOPDIR=../.. - endif - - include $(SND_TOPDIR)/toplevel.config - include $(SND_TOPDIR)/Makefile.conf - - snd-xyz-objs := xyz.o abc.o def.o - - obj-$(CONFIG_SND_XYZ) += snd-xyz.o - - include $(SND_TOPDIR)/Rules.make -]]> - </programlisting> - </example> - </para> - </listitem> - - <listitem> - <para> - Create the Kconfig entry - </para> - - <para> - This procedure is as same as in the last section. - </para> - </listitem> - - <listitem> - <para> - Run cvscompile script to re-generate the configure script and - build the whole stuff again. - </para> - </listitem> - </orderedlist> - </para> - </section> - - </chapter> - -<!-- ****************************************************** --> -<!-- Useful Functions --> -<!-- ****************************************************** --> - <chapter id="useful-functions"> - <title>Useful Functions</title> - - <section id="useful-functions-snd-printk"> - <title><function>snd_printk()</function> and friends</title> - <para> - ALSA provides a verbose version of the - <function>printk()</function> function. If a kernel config - <constant>CONFIG_SND_VERBOSE_PRINTK</constant> is set, this - function prints the given message together with the file name - and the line of the caller. The <constant>KERN_XXX</constant> - prefix is processed as - well as the original <function>printk()</function> does, so it's - recommended to add this prefix, e.g. - - <informalexample> - <programlisting> -<![CDATA[ - snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\n"); -]]> - </programlisting> - </informalexample> - </para> - - <para> - There are also <function>printk()</function>'s for - debugging. <function>snd_printd()</function> can be used for - general debugging purposes. If - <constant>CONFIG_SND_DEBUG</constant> is set, this function is - compiled, and works just like - <function>snd_printk()</function>. If the ALSA is compiled - without the debugging flag, it's ignored. - </para> - - <para> - <function>snd_printdd()</function> is compiled in only when - <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is set. Please note - that <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is not set as default - even if you configure the alsa-driver with - <option>--with-debug=full</option> option. You need to give - explicitly <option>--with-debug=detect</option> option instead. - </para> - </section> - - <section id="useful-functions-snd-bug"> - <title><function>snd_BUG()</function></title> - <para> - It shows the <computeroutput>BUG?</computeroutput> message and - stack trace as well as <function>snd_BUG_ON</function> at the point. - It's useful to show that a fatal error happens there. - </para> - <para> - When no debug flag is set, this macro is ignored. - </para> - </section> - - <section id="useful-functions-snd-bug-on"> - <title><function>snd_BUG_ON()</function></title> - <para> - <function>snd_BUG_ON()</function> macro is similar with - <function>WARN_ON()</function> macro. For example, - - <informalexample> - <programlisting> -<![CDATA[ - snd_BUG_ON(!pointer); -]]> - </programlisting> - </informalexample> - - or it can be used as the condition, - <informalexample> - <programlisting> -<![CDATA[ - if (snd_BUG_ON(non_zero_is_bug)) - return -EINVAL; -]]> - </programlisting> - </informalexample> - - </para> - - <para> - The macro takes an conditional expression to evaluate. - When <constant>CONFIG_SND_DEBUG</constant>, is set, if the - expression is non-zero, it shows the warning message such as - <computeroutput>BUG? (xxx)</computeroutput> - normally followed by stack trace. - - In both cases it returns the evaluated value. - </para> - - </section> - - </chapter> - - -<!-- ****************************************************** --> -<!-- Acknowledgments --> -<!-- ****************************************************** --> - <chapter id="acknowledgments"> - <title>Acknowledgments</title> - <para> - I would like to thank Phil Kerr for his help for improvement and - corrections of this document. - </para> - <para> - Kevin Conder reformatted the original plain-text to the - DocBook format. - </para> - <para> - Giuliano Pochini corrected typos and contributed the example codes - in the hardware constraints section. - </para> - </chapter> -</book> diff --git a/Documentation/DocBook/writing_musb_glue_layer.tmpl b/Documentation/DocBook/writing_musb_glue_layer.tmpl deleted file mode 100644 index 837eca77f274..000000000000 --- a/Documentation/DocBook/writing_musb_glue_layer.tmpl +++ /dev/null @@ -1,873 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="Writing-MUSB-Glue-Layer"> - <bookinfo> - <title>Writing an MUSB Glue Layer</title> - - <authorgroup> - <author> - <firstname>Apelete</firstname> - <surname>Seketeli</surname> - <affiliation> - <address> - <email>apelete at seketeli.net</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2014</year> - <holder>Apelete Seketeli</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute it - and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later version. - </para> - - <para> - This documentation is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public License - along with this documentation; if not, write to the Free Software - Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA - 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the Linux kernel source - tree. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="introduction"> - <title>Introduction</title> - <para> - The Linux MUSB subsystem is part of the larger Linux USB - subsystem. It provides support for embedded USB Device Controllers - (UDC) that do not use Universal Host Controller Interface (UHCI) - or Open Host Controller Interface (OHCI). - </para> - <para> - Instead, these embedded UDC rely on the USB On-the-Go (OTG) - specification which they implement at least partially. The silicon - reference design used in most cases is the Multipoint USB - Highspeed Dual-Role Controller (MUSB HDRC) found in the Mentor - Graphics Inventra™ design. - </para> - <para> - As a self-taught exercise I have written an MUSB glue layer for - the Ingenic JZ4740 SoC, modelled after the many MUSB glue layers - in the kernel source tree. This layer can be found at - drivers/usb/musb/jz4740.c. In this documentation I will walk - through the basics of the jz4740.c glue layer, explaining the - different pieces and what needs to be done in order to write your - own device glue layer. - </para> - </chapter> - - <chapter id="linux-musb-basics"> - <title>Linux MUSB Basics</title> - <para> - To get started on the topic, please read USB On-the-Go Basics (see - Resources) which provides an introduction of USB OTG operation at - the hardware level. A couple of wiki pages by Texas Instruments - and Analog Devices also provide an overview of the Linux kernel - MUSB configuration, albeit focused on some specific devices - provided by these companies. Finally, getting acquainted with the - USB specification at USB home page may come in handy, with - practical instance provided through the Writing USB Device Drivers - documentation (again, see Resources). - </para> - <para> - Linux USB stack is a layered architecture in which the MUSB - controller hardware sits at the lowest. The MUSB controller driver - abstract the MUSB controller hardware to the Linux USB stack. - </para> - <programlisting> - ------------------------ - | | <------- drivers/usb/gadget - | Linux USB Core Stack | <------- drivers/usb/host - | | <------- drivers/usb/core - ------------------------ - ⬍ - -------------------------- - | | <------ drivers/usb/musb/musb_gadget.c - | MUSB Controller driver | <------ drivers/usb/musb/musb_host.c - | | <------ drivers/usb/musb/musb_core.c - -------------------------- - ⬍ - --------------------------------- - | MUSB Platform Specific Driver | - | | <-- drivers/usb/musb/jz4740.c - | aka "Glue Layer" | - --------------------------------- - ⬍ - --------------------------------- - | MUSB Controller Hardware | - --------------------------------- - </programlisting> - <para> - As outlined above, the glue layer is actually the platform - specific code sitting in between the controller driver and the - controller hardware. - </para> - <para> - Just like a Linux USB driver needs to register itself with the - Linux USB subsystem, the MUSB glue layer needs first to register - itself with the MUSB controller driver. This will allow the - controller driver to know about which device the glue layer - supports and which functions to call when a supported device is - detected or released; remember we are talking about an embedded - controller chip here, so no insertion or removal at run-time. - </para> - <para> - All of this information is passed to the MUSB controller driver - through a platform_driver structure defined in the glue layer as: - </para> - <programlisting linenumbering="numbered"> -static struct platform_driver jz4740_driver = { - .probe = jz4740_probe, - .remove = jz4740_remove, - .driver = { - .name = "musb-jz4740", - }, -}; - </programlisting> - <para> - The probe and remove function pointers are called when a matching - device is detected and, respectively, released. The name string - describes the device supported by this glue layer. In the current - case it matches a platform_device structure declared in - arch/mips/jz4740/platform.c. Note that we are not using device - tree bindings here. - </para> - <para> - In order to register itself to the controller driver, the glue - layer goes through a few steps, basically allocating the - controller hardware resources and initialising a couple of - circuits. To do so, it needs to keep track of the information used - throughout these steps. This is done by defining a private - jz4740_glue structure: - </para> - <programlisting linenumbering="numbered"> -struct jz4740_glue { - struct device *dev; - struct platform_device *musb; - struct clk *clk; -}; - </programlisting> - <para> - The dev and musb members are both device structure variables. The - first one holds generic information about the device, since it's - the basic device structure, and the latter holds information more - closely related to the subsystem the device is registered to. The - clk variable keeps information related to the device clock - operation. - </para> - <para> - Let's go through the steps of the probe function that leads the - glue layer to register itself to the controller driver. - </para> - <para> - N.B.: For the sake of readability each function will be split in - logical parts, each part being shown as if it was independent from - the others. - </para> - <programlisting linenumbering="numbered"> -static int jz4740_probe(struct platform_device *pdev) -{ - struct platform_device *musb; - struct jz4740_glue *glue; - struct clk *clk; - int ret; - - glue = devm_kzalloc(&pdev->dev, sizeof(*glue), GFP_KERNEL); - if (!glue) - return -ENOMEM; - - musb = platform_device_alloc("musb-hdrc", PLATFORM_DEVID_AUTO); - if (!musb) { - dev_err(&pdev->dev, "failed to allocate musb device\n"); - return -ENOMEM; - } - - clk = devm_clk_get(&pdev->dev, "udc"); - if (IS_ERR(clk)) { - dev_err(&pdev->dev, "failed to get clock\n"); - ret = PTR_ERR(clk); - goto err_platform_device_put; - } - - ret = clk_prepare_enable(clk); - if (ret) { - dev_err(&pdev->dev, "failed to enable clock\n"); - goto err_platform_device_put; - } - - musb->dev.parent = &pdev->dev; - - glue->dev = &pdev->dev; - glue->musb = musb; - glue->clk = clk; - - return 0; - -err_platform_device_put: - platform_device_put(musb); - return ret; -} - </programlisting> - <para> - The first few lines of the probe function allocate and assign the - glue, musb and clk variables. The GFP_KERNEL flag (line 8) allows - the allocation process to sleep and wait for memory, thus being - usable in a blocking situation. The PLATFORM_DEVID_AUTO flag (line - 12) allows automatic allocation and management of device IDs in - order to avoid device namespace collisions with explicit IDs. With - devm_clk_get() (line 18) the glue layer allocates the clock -- the - <literal>devm_</literal> prefix indicates that clk_get() is - managed: it automatically frees the allocated clock resource data - when the device is released -- and enable it. - </para> - <para> - Then comes the registration steps: - </para> - <programlisting linenumbering="numbered"> -static int jz4740_probe(struct platform_device *pdev) -{ - struct musb_hdrc_platform_data *pdata = &jz4740_musb_platform_data; - - pdata->platform_ops = &jz4740_musb_ops; - - platform_set_drvdata(pdev, glue); - - ret = platform_device_add_resources(musb, pdev->resource, - pdev->num_resources); - if (ret) { - dev_err(&pdev->dev, "failed to add resources\n"); - goto err_clk_disable; - } - - ret = platform_device_add_data(musb, pdata, sizeof(*pdata)); - if (ret) { - dev_err(&pdev->dev, "failed to add platform_data\n"); - goto err_clk_disable; - } - - return 0; - -err_clk_disable: - clk_disable_unprepare(clk); -err_platform_device_put: - platform_device_put(musb); - return ret; -} - </programlisting> - <para> - The first step is to pass the device data privately held by the - glue layer on to the controller driver through - platform_set_drvdata() (line 7). Next is passing on the device - resources information, also privately held at that point, through - platform_device_add_resources() (line 9). - </para> - <para> - Finally comes passing on the platform specific data to the - controller driver (line 16). Platform data will be discussed in - <link linkend="device-platform-data">Chapter 4</link>, but here - we are looking at the platform_ops function pointer (line 5) in - musb_hdrc_platform_data structure (line 3). This function - pointer allows the MUSB controller driver to know which function - to call for device operation: - </para> - <programlisting linenumbering="numbered"> -static const struct musb_platform_ops jz4740_musb_ops = { - .init = jz4740_musb_init, - .exit = jz4740_musb_exit, -}; - </programlisting> - <para> - Here we have the minimal case where only init and exit functions - are called by the controller driver when needed. Fact is the - JZ4740 MUSB controller is a basic controller, lacking some - features found in other controllers, otherwise we may also have - pointers to a few other functions like a power management function - or a function to switch between OTG and non-OTG modes, for - instance. - </para> - <para> - At that point of the registration process, the controller driver - actually calls the init function: - </para> - <programlisting linenumbering="numbered"> -static int jz4740_musb_init(struct musb *musb) -{ - musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2); - if (!musb->xceiv) { - pr_err("HS UDC: no transceiver configured\n"); - return -ENODEV; - } - - /* Silicon does not implement ConfigData register. - * Set dyn_fifo to avoid reading EP config from hardware. - */ - musb->dyn_fifo = true; - - musb->isr = jz4740_musb_interrupt; - - return 0; -} - </programlisting> - <para> - The goal of jz4740_musb_init() is to get hold of the transceiver - driver data of the MUSB controller hardware and pass it on to the - MUSB controller driver, as usual. The transceiver is the circuitry - inside the controller hardware responsible for sending/receiving - the USB data. Since it is an implementation of the physical layer - of the OSI model, the transceiver is also referred to as PHY. - </para> - <para> - Getting hold of the MUSB PHY driver data is done with - usb_get_phy() which returns a pointer to the structure - containing the driver instance data. The next couple of - instructions (line 12 and 14) are used as a quirk and to setup - IRQ handling respectively. Quirks and IRQ handling will be - discussed later in <link linkend="device-quirks">Chapter - 5</link> and <link linkend="handling-irqs">Chapter 3</link>. - </para> - <programlisting linenumbering="numbered"> -static int jz4740_musb_exit(struct musb *musb) -{ - usb_put_phy(musb->xceiv); - - return 0; -} - </programlisting> - <para> - Acting as the counterpart of init, the exit function releases the - MUSB PHY driver when the controller hardware itself is about to be - released. - </para> - <para> - Again, note that init and exit are fairly simple in this case due - to the basic set of features of the JZ4740 controller hardware. - When writing an musb glue layer for a more complex controller - hardware, you might need to take care of more processing in those - two functions. - </para> - <para> - Returning from the init function, the MUSB controller driver jumps - back into the probe function: - </para> - <programlisting linenumbering="numbered"> -static int jz4740_probe(struct platform_device *pdev) -{ - ret = platform_device_add(musb); - if (ret) { - dev_err(&pdev->dev, "failed to register musb device\n"); - goto err_clk_disable; - } - - return 0; - -err_clk_disable: - clk_disable_unprepare(clk); -err_platform_device_put: - platform_device_put(musb); - return ret; -} - </programlisting> - <para> - This is the last part of the device registration process where the - glue layer adds the controller hardware device to Linux kernel - device hierarchy: at this stage, all known information about the - device is passed on to the Linux USB core stack. - </para> - <programlisting linenumbering="numbered"> -static int jz4740_remove(struct platform_device *pdev) -{ - struct jz4740_glue *glue = platform_get_drvdata(pdev); - - platform_device_unregister(glue->musb); - clk_disable_unprepare(glue->clk); - - return 0; -} - </programlisting> - <para> - Acting as the counterpart of probe, the remove function unregister - the MUSB controller hardware (line 5) and disable the clock (line - 6), allowing it to be gated. - </para> - </chapter> - - <chapter id="handling-irqs"> - <title>Handling IRQs</title> - <para> - Additionally to the MUSB controller hardware basic setup and - registration, the glue layer is also responsible for handling the - IRQs: - </para> - <programlisting linenumbering="numbered"> -static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci) -{ - unsigned long flags; - irqreturn_t retval = IRQ_NONE; - struct musb *musb = __hci; - - spin_lock_irqsave(&musb->lock, flags); - - musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB); - musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX); - musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX); - - /* - * The controller is gadget only, the state of the host mode IRQ bits is - * undefined. Mask them to make sure that the musb driver core will - * never see them set - */ - musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME | - MUSB_INTR_RESET | MUSB_INTR_SOF; - - if (musb->int_usb || musb->int_tx || musb->int_rx) - retval = musb_interrupt(musb); - - spin_unlock_irqrestore(&musb->lock, flags); - - return retval; -} - </programlisting> - <para> - Here the glue layer mostly has to read the relevant hardware - registers and pass their values on to the controller driver which - will handle the actual event that triggered the IRQ. - </para> - <para> - The interrupt handler critical section is protected by the - spin_lock_irqsave() and counterpart spin_unlock_irqrestore() - functions (line 7 and 24 respectively), which prevent the - interrupt handler code to be run by two different threads at the - same time. - </para> - <para> - Then the relevant interrupt registers are read (line 9 to 11): - </para> - <itemizedlist> - <listitem> - <para> - MUSB_INTRUSB: indicates which USB interrupts are currently - active, - </para> - </listitem> - <listitem> - <para> - MUSB_INTRTX: indicates which of the interrupts for TX - endpoints are currently active, - </para> - </listitem> - <listitem> - <para> - MUSB_INTRRX: indicates which of the interrupts for TX - endpoints are currently active. - </para> - </listitem> - </itemizedlist> - <para> - Note that musb_readb() is used to read 8-bit registers at most, - while musb_readw() allows us to read at most 16-bit registers. - There are other functions that can be used depending on the size - of your device registers. See musb_io.h for more information. - </para> - <para> - Instruction on line 18 is another quirk specific to the JZ4740 - USB device controller, which will be discussed later in <link - linkend="device-quirks">Chapter 5</link>. - </para> - <para> - The glue layer still needs to register the IRQ handler though. - Remember the instruction on line 14 of the init function: - </para> - <programlisting linenumbering="numbered"> -static int jz4740_musb_init(struct musb *musb) -{ - musb->isr = jz4740_musb_interrupt; - - return 0; -} - </programlisting> - <para> - This instruction sets a pointer to the glue layer IRQ handler - function, in order for the controller hardware to call the handler - back when an IRQ comes from the controller hardware. The interrupt - handler is now implemented and registered. - </para> - </chapter> - - <chapter id="device-platform-data"> - <title>Device Platform Data</title> - <para> - In order to write an MUSB glue layer, you need to have some data - describing the hardware capabilities of your controller hardware, - which is called the platform data. - </para> - <para> - Platform data is specific to your hardware, though it may cover a - broad range of devices, and is generally found somewhere in the - arch/ directory, depending on your device architecture. - </para> - <para> - For instance, platform data for the JZ4740 SoC is found in - arch/mips/jz4740/platform.c. In the platform.c file each device of - the JZ4740 SoC is described through a set of structures. - </para> - <para> - Here is the part of arch/mips/jz4740/platform.c that covers the - USB Device Controller (UDC): - </para> - <programlisting linenumbering="numbered"> -/* USB Device Controller */ -struct platform_device jz4740_udc_xceiv_device = { - .name = "usb_phy_gen_xceiv", - .id = 0, -}; - -static struct resource jz4740_udc_resources[] = { - [0] = { - .start = JZ4740_UDC_BASE_ADDR, - .end = JZ4740_UDC_BASE_ADDR + 0x10000 - 1, - .flags = IORESOURCE_MEM, - }, - [1] = { - .start = JZ4740_IRQ_UDC, - .end = JZ4740_IRQ_UDC, - .flags = IORESOURCE_IRQ, - .name = "mc", - }, -}; - -struct platform_device jz4740_udc_device = { - .name = "musb-jz4740", - .id = -1, - .dev = { - .dma_mask = &jz4740_udc_device.dev.coherent_dma_mask, - .coherent_dma_mask = DMA_BIT_MASK(32), - }, - .num_resources = ARRAY_SIZE(jz4740_udc_resources), - .resource = jz4740_udc_resources, -}; - </programlisting> - <para> - The jz4740_udc_xceiv_device platform device structure (line 2) - describes the UDC transceiver with a name and id number. - </para> - <para> - At the time of this writing, note that - "usb_phy_gen_xceiv" is the specific name to be used for - all transceivers that are either built-in with reference USB IP or - autonomous and doesn't require any PHY programming. You will need - to set CONFIG_NOP_USB_XCEIV=y in the kernel configuration to make - use of the corresponding transceiver driver. The id field could be - set to -1 (equivalent to PLATFORM_DEVID_NONE), -2 (equivalent to - PLATFORM_DEVID_AUTO) or start with 0 for the first device of this - kind if we want a specific id number. - </para> - <para> - The jz4740_udc_resources resource structure (line 7) defines the - UDC registers base addresses. - </para> - <para> - The first array (line 9 to 11) defines the UDC registers base - memory addresses: start points to the first register memory - address, end points to the last register memory address and the - flags member defines the type of resource we are dealing with. So - IORESOURCE_MEM is used to define the registers memory addresses. - The second array (line 14 to 17) defines the UDC IRQ registers - addresses. Since there is only one IRQ register available for the - JZ4740 UDC, start and end point at the same address. The - IORESOURCE_IRQ flag tells that we are dealing with IRQ resources, - and the name "mc" is in fact hard-coded in the MUSB core - in order for the controller driver to retrieve this IRQ resource - by querying it by its name. - </para> - <para> - Finally, the jz4740_udc_device platform device structure (line 21) - describes the UDC itself. - </para> - <para> - The "musb-jz4740" name (line 22) defines the MUSB - driver that is used for this device; remember this is in fact - the name that we used in the jz4740_driver platform driver - structure in <link linkend="linux-musb-basics">Chapter - 2</link>. The id field (line 23) is set to -1 (equivalent to - PLATFORM_DEVID_NONE) since we do not need an id for the device: - the MUSB controller driver was already set to allocate an - automatic id in <link linkend="linux-musb-basics">Chapter - 2</link>. In the dev field we care for DMA related information - here. The dma_mask field (line 25) defines the width of the DMA - mask that is going to be used, and coherent_dma_mask (line 26) - has the same purpose but for the alloc_coherent DMA mappings: in - both cases we are using a 32 bits mask. Then the resource field - (line 29) is simply a pointer to the resource structure defined - before, while the num_resources field (line 28) keeps track of - the number of arrays defined in the resource structure (in this - case there were two resource arrays defined before). - </para> - <para> - With this quick overview of the UDC platform data at the arch/ - level now done, let's get back to the MUSB glue layer specific - platform data in drivers/usb/musb/jz4740.c: - </para> - <programlisting linenumbering="numbered"> -static struct musb_hdrc_config jz4740_musb_config = { - /* Silicon does not implement USB OTG. */ - .multipoint = 0, - /* Max EPs scanned, driver will decide which EP can be used. */ - .num_eps = 4, - /* RAMbits needed to configure EPs from table */ - .ram_bits = 9, - .fifo_cfg = jz4740_musb_fifo_cfg, - .fifo_cfg_size = ARRAY_SIZE(jz4740_musb_fifo_cfg), -}; - -static struct musb_hdrc_platform_data jz4740_musb_platform_data = { - .mode = MUSB_PERIPHERAL, - .config = &jz4740_musb_config, -}; - </programlisting> - <para> - First the glue layer configures some aspects of the controller - driver operation related to the controller hardware specifics. - This is done through the jz4740_musb_config musb_hdrc_config - structure. - </para> - <para> - Defining the OTG capability of the controller hardware, the - multipoint member (line 3) is set to 0 (equivalent to false) - since the JZ4740 UDC is not OTG compatible. Then num_eps (line - 5) defines the number of USB endpoints of the controller - hardware, including endpoint 0: here we have 3 endpoints + - endpoint 0. Next is ram_bits (line 7) which is the width of the - RAM address bus for the MUSB controller hardware. This - information is needed when the controller driver cannot - automatically configure endpoints by reading the relevant - controller hardware registers. This issue will be discussed when - we get to device quirks in <link linkend="device-quirks">Chapter - 5</link>. Last two fields (line 8 and 9) are also about device - quirks: fifo_cfg points to the USB endpoints configuration table - and fifo_cfg_size keeps track of the size of the number of - entries in that configuration table. More on that later in <link - linkend="device-quirks">Chapter 5</link>. - </para> - <para> - Then this configuration is embedded inside - jz4740_musb_platform_data musb_hdrc_platform_data structure (line - 11): config is a pointer to the configuration structure itself, - and mode tells the controller driver if the controller hardware - may be used as MUSB_HOST only, MUSB_PERIPHERAL only or MUSB_OTG - which is a dual mode. - </para> - <para> - Remember that jz4740_musb_platform_data is then used to convey - platform data information as we have seen in the probe function - in <link linkend="linux-musb-basics">Chapter 2</link> - </para> - </chapter> - - <chapter id="device-quirks"> - <title>Device Quirks</title> - <para> - Completing the platform data specific to your device, you may also - need to write some code in the glue layer to work around some - device specific limitations. These quirks may be due to some - hardware bugs, or simply be the result of an incomplete - implementation of the USB On-the-Go specification. - </para> - <para> - The JZ4740 UDC exhibits such quirks, some of which we will discuss - here for the sake of insight even though these might not be found - in the controller hardware you are working on. - </para> - <para> - Let's get back to the init function first: - </para> - <programlisting linenumbering="numbered"> -static int jz4740_musb_init(struct musb *musb) -{ - musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2); - if (!musb->xceiv) { - pr_err("HS UDC: no transceiver configured\n"); - return -ENODEV; - } - - /* Silicon does not implement ConfigData register. - * Set dyn_fifo to avoid reading EP config from hardware. - */ - musb->dyn_fifo = true; - - musb->isr = jz4740_musb_interrupt; - - return 0; -} - </programlisting> - <para> - Instruction on line 12 helps the MUSB controller driver to work - around the fact that the controller hardware is missing registers - that are used for USB endpoints configuration. - </para> - <para> - Without these registers, the controller driver is unable to read - the endpoints configuration from the hardware, so we use line 12 - instruction to bypass reading the configuration from silicon, and - rely on a hard-coded table that describes the endpoints - configuration instead: - </para> - <programlisting linenumbering="numbered"> -static struct musb_fifo_cfg jz4740_musb_fifo_cfg[] = { -{ .hw_ep_num = 1, .style = FIFO_TX, .maxpacket = 512, }, -{ .hw_ep_num = 1, .style = FIFO_RX, .maxpacket = 512, }, -{ .hw_ep_num = 2, .style = FIFO_TX, .maxpacket = 64, }, -}; - </programlisting> - <para> - Looking at the configuration table above, we see that each - endpoints is described by three fields: hw_ep_num is the endpoint - number, style is its direction (either FIFO_TX for the controller - driver to send packets in the controller hardware, or FIFO_RX to - receive packets from hardware), and maxpacket defines the maximum - size of each data packet that can be transmitted over that - endpoint. Reading from the table, the controller driver knows that - endpoint 1 can be used to send and receive USB data packets of 512 - bytes at once (this is in fact a bulk in/out endpoint), and - endpoint 2 can be used to send data packets of 64 bytes at once - (this is in fact an interrupt endpoint). - </para> - <para> - Note that there is no information about endpoint 0 here: that one - is implemented by default in every silicon design, with a - predefined configuration according to the USB specification. For - more examples of endpoint configuration tables, see musb_core.c. - </para> - <para> - Let's now get back to the interrupt handler function: - </para> - <programlisting linenumbering="numbered"> -static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci) -{ - unsigned long flags; - irqreturn_t retval = IRQ_NONE; - struct musb *musb = __hci; - - spin_lock_irqsave(&musb->lock, flags); - - musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB); - musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX); - musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX); - - /* - * The controller is gadget only, the state of the host mode IRQ bits is - * undefined. Mask them to make sure that the musb driver core will - * never see them set - */ - musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME | - MUSB_INTR_RESET | MUSB_INTR_SOF; - - if (musb->int_usb || musb->int_tx || musb->int_rx) - retval = musb_interrupt(musb); - - spin_unlock_irqrestore(&musb->lock, flags); - - return retval; -} - </programlisting> - <para> - Instruction on line 18 above is a way for the controller driver to - work around the fact that some interrupt bits used for USB host - mode operation are missing in the MUSB_INTRUSB register, thus left - in an undefined hardware state, since this MUSB controller - hardware is used in peripheral mode only. As a consequence, the - glue layer masks these missing bits out to avoid parasite - interrupts by doing a logical AND operation between the value read - from MUSB_INTRUSB and the bits that are actually implemented in - the register. - </para> - <para> - These are only a couple of the quirks found in the JZ4740 USB - device controller. Some others were directly addressed in the MUSB - core since the fixes were generic enough to provide a better - handling of the issues for others controller hardware eventually. - </para> - </chapter> - - <chapter id="conclusion"> - <title>Conclusion</title> - <para> - Writing a Linux MUSB glue layer should be a more accessible task, - as this documentation tries to show the ins and outs of this - exercise. - </para> - <para> - The JZ4740 USB device controller being fairly simple, I hope its - glue layer serves as a good example for the curious mind. Used - with the current MUSB glue layers, this documentation should - provide enough guidance to get started; should anything gets out - of hand, the linux-usb mailing list archive is another helpful - resource to browse through. - </para> - </chapter> - - <chapter id="acknowledgements"> - <title>Acknowledgements</title> - <para> - Many thanks to Lars-Peter Clausen and Maarten ter Huurne for - answering my questions while I was writing the JZ4740 glue layer - and for helping me out getting the code in good shape. - </para> - <para> - I would also like to thank the Qi-Hardware community at large for - its cheerful guidance and support. - </para> - </chapter> - - <chapter id="resources"> - <title>Resources</title> - <para> - USB Home Page: - <ulink url="http://www.usb.org">http://www.usb.org</ulink> - </para> - <para> - linux-usb Mailing List Archives: - <ulink url="http://marc.info/?l=linux-usb">http://marc.info/?l=linux-usb</ulink> - </para> - <para> - USB On-the-Go Basics: - <ulink url="http://www.maximintegrated.com/app-notes/index.mvp/id/1822">http://www.maximintegrated.com/app-notes/index.mvp/id/1822</ulink> - </para> - <para> - Writing USB Device Drivers: - <ulink url="https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html">https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html</ulink> - </para> - <para> - Texas Instruments USB Configuration Wiki Page: - <ulink url="http://processors.wiki.ti.com/index.php/Usbgeneralpage">http://processors.wiki.ti.com/index.php/Usbgeneralpage</ulink> - </para> - <para> - Analog Devices Blackfin MUSB Configuration: - <ulink url="http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb">http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb</ulink> - </para> - </chapter> - -</book> diff --git a/Documentation/DocBook/writing_usb_driver.tmpl b/Documentation/DocBook/writing_usb_driver.tmpl deleted file mode 100644 index 3210dcf741c9..000000000000 --- a/Documentation/DocBook/writing_usb_driver.tmpl +++ /dev/null @@ -1,412 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="USBDeviceDriver"> - <bookinfo> - <title>Writing USB Device Drivers</title> - - <authorgroup> - <author> - <firstname>Greg</firstname> - <surname>Kroah-Hartman</surname> - <affiliation> - <address> - <email>greg@kroah.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2001-2002</year> - <holder>Greg Kroah-Hartman</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - - <para> - This documentation is based on an article published in - Linux Journal Magazine, October 2001, Issue 90. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="intro"> - <title>Introduction</title> - <para> - The Linux USB subsystem has grown from supporting only two different - types of devices in the 2.2.7 kernel (mice and keyboards), to over 20 - different types of devices in the 2.4 kernel. Linux currently supports - almost all USB class devices (standard types of devices like keyboards, - mice, modems, printers and speakers) and an ever-growing number of - vendor-specific devices (such as USB to serial converters, digital - cameras, Ethernet devices and MP3 players). For a full list of the - different USB devices currently supported, see Resources. - </para> - <para> - The remaining kinds of USB devices that do not have support on Linux are - almost all vendor-specific devices. Each vendor decides to implement a - custom protocol to talk to their device, so a custom driver usually needs - to be created. Some vendors are open with their USB protocols and help - with the creation of Linux drivers, while others do not publish them, and - developers are forced to reverse-engineer. See Resources for some links - to handy reverse-engineering tools. - </para> - <para> - Because each different protocol causes a new driver to be created, I have - written a generic USB driver skeleton, modelled after the pci-skeleton.c - file in the kernel source tree upon which many PCI network drivers have - been based. This USB skeleton can be found at drivers/usb/usb-skeleton.c - in the kernel source tree. In this article I will walk through the basics - of the skeleton driver, explaining the different pieces and what needs to - be done to customize it to your specific device. - </para> - </chapter> - - <chapter id="basics"> - <title>Linux USB Basics</title> - <para> - If you are going to write a Linux USB driver, please become familiar with - the USB protocol specification. It can be found, along with many other - useful documents, at the USB home page (see Resources). An excellent - introduction to the Linux USB subsystem can be found at the USB Working - Devices List (see Resources). It explains how the Linux USB subsystem is - structured and introduces the reader to the concept of USB urbs - (USB Request Blocks), which are essential to USB drivers. - </para> - <para> - The first thing a Linux USB driver needs to do is register itself with - the Linux USB subsystem, giving it some information about which devices - the driver supports and which functions to call when a device supported - by the driver is inserted or removed from the system. All of this - information is passed to the USB subsystem in the usb_driver structure. - The skeleton driver declares a usb_driver as: - </para> - <programlisting> -static struct usb_driver skel_driver = { - .name = "skeleton", - .probe = skel_probe, - .disconnect = skel_disconnect, - .fops = &skel_fops, - .minor = USB_SKEL_MINOR_BASE, - .id_table = skel_table, -}; - </programlisting> - <para> - The variable name is a string that describes the driver. It is used in - informational messages printed to the system log. The probe and - disconnect function pointers are called when a device that matches the - information provided in the id_table variable is either seen or removed. - </para> - <para> - The fops and minor variables are optional. Most USB drivers hook into - another kernel subsystem, such as the SCSI, network or TTY subsystem. - These types of drivers register themselves with the other kernel - subsystem, and any user-space interactions are provided through that - interface. But for drivers that do not have a matching kernel subsystem, - such as MP3 players or scanners, a method of interacting with user space - is needed. The USB subsystem provides a way to register a minor device - number and a set of file_operations function pointers that enable this - user-space interaction. The skeleton driver needs this kind of interface, - so it provides a minor starting number and a pointer to its - file_operations functions. - </para> - <para> - The USB driver is then registered with a call to usb_register, usually in - the driver's init function, as shown here: - </para> - <programlisting> -static int __init usb_skel_init(void) -{ - int result; - - /* register this driver with the USB subsystem */ - result = usb_register(&skel_driver); - if (result < 0) { - err("usb_register failed for the "__FILE__ "driver." - "Error number %d", result); - return -1; - } - - return 0; -} -module_init(usb_skel_init); - </programlisting> - <para> - When the driver is unloaded from the system, it needs to deregister - itself with the USB subsystem. This is done with the usb_deregister - function: - </para> - <programlisting> -static void __exit usb_skel_exit(void) -{ - /* deregister this driver with the USB subsystem */ - usb_deregister(&skel_driver); -} -module_exit(usb_skel_exit); - </programlisting> - <para> - To enable the linux-hotplug system to load the driver automatically when - the device is plugged in, you need to create a MODULE_DEVICE_TABLE. The - following code tells the hotplug scripts that this module supports a - single device with a specific vendor and product ID: - </para> - <programlisting> -/* table of devices that work with this driver */ -static struct usb_device_id skel_table [] = { - { USB_DEVICE(USB_SKEL_VENDOR_ID, USB_SKEL_PRODUCT_ID) }, - { } /* Terminating entry */ -}; -MODULE_DEVICE_TABLE (usb, skel_table); - </programlisting> - <para> - There are other macros that can be used in describing a usb_device_id for - drivers that support a whole class of USB drivers. See usb.h for more - information on this. - </para> - </chapter> - - <chapter id="device"> - <title>Device operation</title> - <para> - When a device is plugged into the USB bus that matches the device ID - pattern that your driver registered with the USB core, the probe function - is called. The usb_device structure, interface number and the interface ID - are passed to the function: - </para> - <programlisting> -static int skel_probe(struct usb_interface *interface, - const struct usb_device_id *id) - </programlisting> - <para> - The driver now needs to verify that this device is actually one that it - can accept. If so, it returns 0. - If not, or if any error occurs during initialization, an errorcode - (such as <literal>-ENOMEM</literal> or <literal>-ENODEV</literal>) - is returned from the probe function. - </para> - <para> - In the skeleton driver, we determine what end points are marked as bulk-in - and bulk-out. We create buffers to hold the data that will be sent and - received from the device, and a USB urb to write data to the device is - initialized. - </para> - <para> - Conversely, when the device is removed from the USB bus, the disconnect - function is called with the device pointer. The driver needs to clean any - private data that has been allocated at this time and to shut down any - pending urbs that are in the USB system. - </para> - <para> - Now that the device is plugged into the system and the driver is bound to - the device, any of the functions in the file_operations structure that - were passed to the USB subsystem will be called from a user program trying - to talk to the device. The first function called will be open, as the - program tries to open the device for I/O. We increment our private usage - count and save a pointer to our internal structure in the file - structure. This is done so that future calls to file operations will - enable the driver to determine which device the user is addressing. All - of this is done with the following code: - </para> - <programlisting> -/* increment our usage count for the module */ -++skel->open_count; - -/* save our object in the file's private structure */ -file->private_data = dev; - </programlisting> - <para> - After the open function is called, the read and write functions are called - to receive and send data to the device. In the skel_write function, we - receive a pointer to some data that the user wants to send to the device - and the size of the data. The function determines how much data it can - send to the device based on the size of the write urb it has created (this - size depends on the size of the bulk out end point that the device has). - Then it copies the data from user space to kernel space, points the urb to - the data and submits the urb to the USB subsystem. This can be seen in - the following code: - </para> - <programlisting> -/* we can only write as much as 1 urb will hold */ -bytes_written = (count > skel->bulk_out_size) ? skel->bulk_out_size : count; - -/* copy the data from user space into our urb */ -copy_from_user(skel->write_urb->transfer_buffer, buffer, bytes_written); - -/* set up our urb */ -usb_fill_bulk_urb(skel->write_urb, - skel->dev, - usb_sndbulkpipe(skel->dev, skel->bulk_out_endpointAddr), - skel->write_urb->transfer_buffer, - bytes_written, - skel_write_bulk_callback, - skel); - -/* send the data out the bulk port */ -result = usb_submit_urb(skel->write_urb); -if (result) { - err("Failed submitting write urb, error %d", result); -} - </programlisting> - <para> - When the write urb is filled up with the proper information using the - usb_fill_bulk_urb function, we point the urb's completion callback to call our - own skel_write_bulk_callback function. This function is called when the - urb is finished by the USB subsystem. The callback function is called in - interrupt context, so caution must be taken not to do very much processing - at that time. Our implementation of skel_write_bulk_callback merely - reports if the urb was completed successfully or not and then returns. - </para> - <para> - The read function works a bit differently from the write function in that - we do not use an urb to transfer data from the device to the driver. - Instead we call the usb_bulk_msg function, which can be used to send or - receive data from a device without having to create urbs and handle - urb completion callback functions. We call the usb_bulk_msg function, - giving it a buffer into which to place any data received from the device - and a timeout value. If the timeout period expires without receiving any - data from the device, the function will fail and return an error message. - This can be shown with the following code: - </para> - <programlisting> -/* do an immediate bulk read to get data from the device */ -retval = usb_bulk_msg (skel->dev, - usb_rcvbulkpipe (skel->dev, - skel->bulk_in_endpointAddr), - skel->bulk_in_buffer, - skel->bulk_in_size, - &count, HZ*10); -/* if the read was successful, copy the data to user space */ -if (!retval) { - if (copy_to_user (buffer, skel->bulk_in_buffer, count)) - retval = -EFAULT; - else - retval = count; -} - </programlisting> - <para> - The usb_bulk_msg function can be very useful for doing single reads or - writes to a device; however, if you need to read or write constantly to a - device, it is recommended to set up your own urbs and submit them to the - USB subsystem. - </para> - <para> - When the user program releases the file handle that it has been using to - talk to the device, the release function in the driver is called. In this - function we decrement our private usage count and wait for possible - pending writes: - </para> - <programlisting> -/* decrement our usage count for the device */ ---skel->open_count; - </programlisting> - <para> - One of the more difficult problems that USB drivers must be able to handle - smoothly is the fact that the USB device may be removed from the system at - any point in time, even if a program is currently talking to it. It needs - to be able to shut down any current reads and writes and notify the - user-space programs that the device is no longer there. The following - code (function <function>skel_delete</function>) - is an example of how to do this: </para> - <programlisting> -static inline void skel_delete (struct usb_skel *dev) -{ - kfree (dev->bulk_in_buffer); - if (dev->bulk_out_buffer != NULL) - usb_free_coherent (dev->udev, dev->bulk_out_size, - dev->bulk_out_buffer, - dev->write_urb->transfer_dma); - usb_free_urb (dev->write_urb); - kfree (dev); -} - </programlisting> - <para> - If a program currently has an open handle to the device, we reset the flag - <literal>device_present</literal>. For - every read, write, release and other functions that expect a device to be - present, the driver first checks this flag to see if the device is - still present. If not, it releases that the device has disappeared, and a - -ENODEV error is returned to the user-space program. When the release - function is eventually called, it determines if there is no device - and if not, it does the cleanup that the skel_disconnect - function normally does if there are no open files on the device (see - Listing 5). - </para> - </chapter> - - <chapter id="iso"> - <title>Isochronous Data</title> - <para> - This usb-skeleton driver does not have any examples of interrupt or - isochronous data being sent to or from the device. Interrupt data is sent - almost exactly as bulk data is, with a few minor exceptions. Isochronous - data works differently with continuous streams of data being sent to or - from the device. The audio and video camera drivers are very good examples - of drivers that handle isochronous data and will be useful if you also - need to do this. - </para> - </chapter> - - <chapter id="Conclusion"> - <title>Conclusion</title> - <para> - Writing Linux USB device drivers is not a difficult task as the - usb-skeleton driver shows. This driver, combined with the other current - USB drivers, should provide enough examples to help a beginning author - create a working driver in a minimal amount of time. The linux-usb-devel - mailing list archives also contain a lot of helpful information. - </para> - </chapter> - - <chapter id="resources"> - <title>Resources</title> - <para> - The Linux USB Project: <ulink url="http://www.linux-usb.org">http://www.linux-usb.org/</ulink> - </para> - <para> - Linux Hotplug Project: <ulink url="http://linux-hotplug.sourceforge.net">http://linux-hotplug.sourceforge.net/</ulink> - </para> - <para> - Linux USB Working Devices List: <ulink url="http://www.qbik.ch/usb/devices">http://www.qbik.ch/usb/devices/</ulink> - </para> - <para> - linux-usb-devel Mailing List Archives: <ulink url="http://marc.theaimsgroup.com/?l=linux-usb-devel">http://marc.theaimsgroup.com/?l=linux-usb-devel</ulink> - </para> - <para> - Programming Guide for Linux USB Device Drivers: <ulink url="http://usb.cs.tum.edu/usbdoc">http://usb.cs.tum.edu/usbdoc</ulink> - </para> - <para> - USB Home Page: <ulink url="http://www.usb.org">http://www.usb.org</ulink> - </para> - </chapter> - -</book> diff --git a/Documentation/DocBook/z8530book.tmpl b/Documentation/DocBook/z8530book.tmpl deleted file mode 100644 index 6f3883be877e..000000000000 --- a/Documentation/DocBook/z8530book.tmpl +++ /dev/null @@ -1,371 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="Z85230Guide"> - <bookinfo> - <title>Z8530 Programming Guide</title> - - <authorgroup> - <author> - <firstname>Alan</firstname> - <surname>Cox</surname> - <affiliation> - <address> - <email>alan@lxorguk.ukuu.org.uk</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2000</year> - <holder>Alan Cox</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="intro"> - <title>Introduction</title> - <para> - The Z85x30 family synchronous/asynchronous controller chips are - used on a large number of cheap network interface cards. The - kernel provides a core interface layer that is designed to make - it easy to provide WAN services using this chip. - </para> - <para> - The current driver only support synchronous operation. Merging the - asynchronous driver support into this code to allow any Z85x30 - device to be used as both a tty interface and as a synchronous - controller is a project for Linux post the 2.4 release - </para> - </chapter> - - <chapter id="Driver_Modes"> - <title>Driver Modes</title> - <para> - The Z85230 driver layer can drive Z8530, Z85C30 and Z85230 devices - in three different modes. Each mode can be applied to an individual - channel on the chip (each chip has two channels). - </para> - <para> - The PIO synchronous mode supports the most common Z8530 wiring. Here - the chip is interface to the I/O and interrupt facilities of the - host machine but not to the DMA subsystem. When running PIO the - Z8530 has extremely tight timing requirements. Doing high speeds, - even with a Z85230 will be tricky. Typically you should expect to - achieve at best 9600 baud with a Z8C530 and 64Kbits with a Z85230. - </para> - <para> - The DMA mode supports the chip when it is configured to use dual DMA - channels on an ISA bus. The better cards tend to support this mode - of operation for a single channel. With DMA running the Z85230 tops - out when it starts to hit ISA DMA constraints at about 512Kbits. It - is worth noting here that many PC machines hang or crash when the - chip is driven fast enough to hold the ISA bus solid. - </para> - <para> - Transmit DMA mode uses a single DMA channel. The DMA channel is used - for transmission as the transmit FIFO is smaller than the receive - FIFO. it gives better performance than pure PIO mode but is nowhere - near as ideal as pure DMA mode. - </para> - </chapter> - - <chapter id="Using_the_Z85230_driver"> - <title>Using the Z85230 driver</title> - <para> - The Z85230 driver provides the back end interface to your board. To - configure a Z8530 interface you need to detect the board and to - identify its ports and interrupt resources. It is also your problem - to verify the resources are available. - </para> - <para> - Having identified the chip you need to fill in a struct z8530_dev, - which describes each chip. This object must exist until you finally - shutdown the board. Firstly zero the active field. This ensures - nothing goes off without you intending it. The irq field should - be set to the interrupt number of the chip. (Each chip has a single - interrupt source rather than each channel). You are responsible - for allocating the interrupt line. The interrupt handler should be - set to <function>z8530_interrupt</function>. The device id should - be set to the z8530_dev structure pointer. Whether the interrupt can - be shared or not is board dependent, and up to you to initialise. - </para> - <para> - The structure holds two channel structures. - Initialise chanA.ctrlio and chanA.dataio with the address of the - control and data ports. You can or this with Z8530_PORT_SLEEP to - indicate your interface needs the 5uS delay for chip settling done - in software. The PORT_SLEEP option is architecture specific. Other - flags may become available on future platforms, eg for MMIO. - Initialise the chanA.irqs to &z8530_nop to start the chip up - as disabled and discarding interrupt events. This ensures that - stray interrupts will be mopped up and not hang the bus. Set - chanA.dev to point to the device structure itself. The - private and name field you may use as you wish. The private field - is unused by the Z85230 layer. The name is used for error reporting - and it may thus make sense to make it match the network name. - </para> - <para> - Repeat the same operation with the B channel if your chip has - both channels wired to something useful. This isn't always the - case. If it is not wired then the I/O values do not matter, but - you must initialise chanB.dev. - </para> - <para> - If your board has DMA facilities then initialise the txdma and - rxdma fields for the relevant channels. You must also allocate the - ISA DMA channels and do any necessary board level initialisation - to configure them. The low level driver will do the Z8530 and - DMA controller programming but not board specific magic. - </para> - <para> - Having initialised the device you can then call - <function>z8530_init</function>. This will probe the chip and - reset it into a known state. An identification sequence is then - run to identify the chip type. If the checks fail to pass the - function returns a non zero error code. Typically this indicates - that the port given is not valid. After this call the - type field of the z8530_dev structure is initialised to either - Z8530, Z85C30 or Z85230 according to the chip found. - </para> - <para> - Once you have called z8530_init you can also make use of the utility - function <function>z8530_describe</function>. This provides a - consistent reporting format for the Z8530 devices, and allows all - the drivers to provide consistent reporting. - </para> - </chapter> - - <chapter id="Attaching_Network_Interfaces"> - <title>Attaching Network Interfaces</title> - <para> - If you wish to use the network interface facilities of the driver, - then you need to attach a network device to each channel that is - present and in use. In addition to use the generic HDLC - you need to follow some additional plumbing rules. They may seem - complex but a look at the example hostess_sv11 driver should - reassure you. - </para> - <para> - The network device used for each channel should be pointed to by - the netdevice field of each channel. The hdlc-> priv field of the - network device points to your private data - you will need to be - able to find your private data from this. - </para> - <para> - The way most drivers approach this particular problem is to - create a structure holding the Z8530 device definition and - put that into the private field of the network device. The - network device fields of the channels then point back to the - network devices. - </para> - <para> - If you wish to use the generic HDLC then you need to register - the HDLC device. - </para> - <para> - Before you register your network device you will also need to - provide suitable handlers for most of the network device callbacks. - See the network device documentation for more details on this. - </para> - </chapter> - - <chapter id="Configuring_And_Activating_The_Port"> - <title>Configuring And Activating The Port</title> - <para> - The Z85230 driver provides helper functions and tables to load the - port registers on the Z8530 chips. When programming the register - settings for a channel be aware that the documentation recommends - initialisation orders. Strange things happen when these are not - followed. - </para> - <para> - <function>z8530_channel_load</function> takes an array of - pairs of initialisation values in an array of u8 type. The first - value is the Z8530 register number. Add 16 to indicate the alternate - register bank on the later chips. The array is terminated by a 255. - </para> - <para> - The driver provides a pair of public tables. The - z8530_hdlc_kilostream table is for the UK 'Kilostream' service and - also happens to cover most other end host configurations. The - z8530_hdlc_kilostream_85230 table is the same configuration using - the enhancements of the 85230 chip. The configuration loaded is - standard NRZ encoded synchronous data with HDLC bitstuffing. All - of the timing is taken from the other end of the link. - </para> - <para> - When writing your own tables be aware that the driver internally - tracks register values. It may need to reload values. You should - therefore be sure to set registers 1-7, 9-11, 14 and 15 in all - configurations. Where the register settings depend on DMA selection - the driver will update the bits itself when you open or close. - Loading a new table with the interface open is not recommended. - </para> - <para> - There are three standard configurations supported by the core - code. In PIO mode the interface is programmed up to use - interrupt driven PIO. This places high demands on the host processor - to avoid latency. The driver is written to take account of latency - issues but it cannot avoid latencies caused by other drivers, - notably IDE in PIO mode. Because the drivers allocate buffers you - must also prevent MTU changes while the port is open. - </para> - <para> - Once the port is open it will call the rx_function of each channel - whenever a completed packet arrived. This is invoked from - interrupt context and passes you the channel and a network - buffer (struct sk_buff) holding the data. The data includes - the CRC bytes so most users will want to trim the last two - bytes before processing the data. This function is very timing - critical. When you wish to simply discard data the support - code provides the function <function>z8530_null_rx</function> - to discard the data. - </para> - <para> - To active PIO mode sending and receiving the <function> - z8530_sync_open</function> is called. This expects to be passed - the network device and the channel. Typically this is called from - your network device open callback. On a failure a non zero error - status is returned. The <function>z8530_sync_close</function> - function shuts down a PIO channel. This must be done before the - channel is opened again and before the driver shuts down - and unloads. - </para> - <para> - The ideal mode of operation is dual channel DMA mode. Here the - kernel driver will configure the board for DMA in both directions. - The driver also handles ISA DMA issues such as controller - programming and the memory range limit for you. This mode is - activated by calling the <function>z8530_sync_dma_open</function> - function. On failure a non zero error value is returned. - Once this mode is activated it can be shut down by calling the - <function>z8530_sync_dma_close</function>. You must call the close - function matching the open mode you used. - </para> - <para> - The final supported mode uses a single DMA channel to drive the - transmit side. As the Z85C30 has a larger FIFO on the receive - channel this tends to increase the maximum speed a little. - This is activated by calling the <function>z8530_sync_txdma_open - </function>. This returns a non zero error code on failure. The - <function>z8530_sync_txdma_close</function> function closes down - the Z8530 interface from this mode. - </para> - </chapter> - - <chapter id="Network_Layer_Functions"> - <title>Network Layer Functions</title> - <para> - The Z8530 layer provides functions to queue packets for - transmission. The driver internally buffers the frame currently - being transmitted and one further frame (in order to keep back - to back transmission running). Any further buffering is up to - the caller. - </para> - <para> - The function <function>z8530_queue_xmit</function> takes a network - buffer in sk_buff format and queues it for transmission. The - caller must provide the entire packet with the exception of the - bitstuffing and CRC. This is normally done by the caller via - the generic HDLC interface layer. It returns 0 if the buffer has been - queued and non zero values for queue full. If the function accepts - the buffer it becomes property of the Z8530 layer and the caller - should not free it. - </para> - <para> - The function <function>z8530_get_stats</function> returns a pointer - to an internally maintained per interface statistics block. This - provides most of the interface code needed to implement the network - layer get_stats callback. - </para> - </chapter> - - <chapter id="Porting_The_Z8530_Driver"> - <title>Porting The Z8530 Driver</title> - <para> - The Z8530 driver is written to be portable. In DMA mode it makes - assumptions about the use of ISA DMA. These are probably warranted - in most cases as the Z85230 in particular was designed to glue to PC - type machines. The PIO mode makes no real assumptions. - </para> - <para> - Should you need to retarget the Z8530 driver to another architecture - the only code that should need changing are the port I/O functions. - At the moment these assume PC I/O port accesses. This may not be - appropriate for all platforms. Replacing - <function>z8530_read_port</function> and <function>z8530_write_port - </function> is intended to be all that is required to port this - driver layer. - </para> - </chapter> - - <chapter id="bugs"> - <title>Known Bugs And Assumptions</title> - <para> - <variablelist> - <varlistentry><term>Interrupt Locking</term> - <listitem> - <para> - The locking in the driver is done via the global cli/sti lock. This - makes for relatively poor SMP performance. Switching this to use a - per device spin lock would probably materially improve performance. - </para> - </listitem></varlistentry> - - <varlistentry><term>Occasional Failures</term> - <listitem> - <para> - We have reports of occasional failures when run for very long - periods of time and the driver starts to receive junk frames. At - the moment the cause of this is not clear. - </para> - </listitem></varlistentry> - </variablelist> - - </para> - </chapter> - - <chapter id="pubfunctions"> - <title>Public Functions Provided</title> -!Edrivers/net/wan/z85230.c - </chapter> - - <chapter id="intfunctions"> - <title>Internal Functions</title> -!Idrivers/net/wan/z85230.c - </chapter> - -</book> |
