diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl
index de79efdad46c..a20a45b45c30 100644
--- a/Documentation/DocBook/device-drivers.tmpl
+++ b/Documentation/DocBook/device-drivers.tmpl
@@ -272,6 +272,9 @@ X!Isound/sound_firmware.c
!Iinclude/media/media-devnode.h
!Iinclude/media/media-entity.h
+ Consumer Electronics Control devices
+!Iinclude/media/cec-edid.h
+
diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile
index 2840ff483d5a..fdc138624800 100644
--- a/Documentation/DocBook/media/Makefile
+++ b/Documentation/DocBook/media/Makefile
@@ -64,6 +64,7 @@ IOCTLS = \
$(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/linux/cec.h) \
$(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/v4l2-subdev.h) \
DEFINES = \
@@ -100,6 +101,7 @@ STRUCTS = \
$(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/linux/cec.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)
diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml
index 9beb30f0071b..87f1d24958aa 100644
--- a/Documentation/DocBook/media/v4l/biblio.xml
+++ b/Documentation/DocBook/media/v4l/biblio.xml
@@ -342,6 +342,16 @@ in the frequency range from 87,5 to 108,0 MHz
Specification Version 1.4a
+
+ HDMI2
+
+ HDMI Licensing LLC
+(http://www.hdmi.org)
+
+ High-Definition Multimedia Interface
+ Specification Version 2.0
+
+
DP
diff --git a/Documentation/DocBook/media/v4l/cec-api.xml b/Documentation/DocBook/media/v4l/cec-api.xml
new file mode 100644
index 000000000000..7062c1fa4904
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/cec-api.xml
@@ -0,0 +1,75 @@
+
+
+
+ Hans
+ Verkuil
+ hans.verkuil@cisco.com
+ Initial version.
+
+
+
+ 2016
+ Hans Verkuil
+
+
+
+
+
+ 1.0.0
+ 2016-03-17
+ hv
+ Initial revision
+
+
+
+
+CEC API
+
+
+ CEC: Consumer Electronics Control
+
+
+ Introduction
+
+ Note: this documents the proposed CEC API. This API is not yet finalized and
+ is currently only available as a staging kernel module.
+
+ HDMI connectors provide a single pin for use by the Consumer Electronics
+ Control protocol. This protocol allows different devices connected by an HDMI cable
+ to communicate. The protocol for CEC version 1.4 is defined in supplements 1 (CEC)
+ and 2 (HEAC or HDMI Ethernet and Audio Return Channel) of the HDMI 1.4a
+ () specification and the extensions added to CEC version 2.0
+ are defined in chapter 11 of the HDMI 2.0 () specification.
+
+
+ The bitrate is very slow (effectively no more than 36 bytes per second) and
+ is based on the ancient AV.link protocol used in old SCART connectors. The protocol
+ closely resembles a crazy Rube Goldberg contraption and is an unholy mix of low and
+ high level messages. Some messages, especially those part of the HEAC protocol layered
+ on top of CEC, need to be handled by the kernel, others can be handled either by the
+ kernel or by userspace.
+
+ In addition, CEC can be implemented in HDMI receivers, transmitters and in USB
+ devices that have an HDMI input and an HDMI output and that control just the CEC pin.
+
+ Drivers that support CEC will create a CEC device node (/dev/cecX)
+ to give userspace access to the CEC adapter. The &CEC-ADAP-G-CAPS; ioctl will tell userspace
+ what it is allowed to do.
+
+
+
+
+ Function Reference
+
+ &sub-cec-func-open;
+ &sub-cec-func-close;
+ &sub-cec-func-ioctl;
+ &sub-cec-func-poll;
+
+ &sub-cec-ioc-adap-g-caps;
+ &sub-cec-ioc-adap-g-log-addrs;
+ &sub-cec-ioc-adap-g-phys-addr;
+ &sub-cec-ioc-dqevent;
+ &sub-cec-ioc-g-mode;
+ &sub-cec-ioc-receive;
+
diff --git a/Documentation/DocBook/media/v4l/cec-func-close.xml b/Documentation/DocBook/media/v4l/cec-func-close.xml
new file mode 100644
index 000000000000..0812c8cd9634
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/cec-func-close.xml
@@ -0,0 +1,64 @@
+
+
+ cec close()
+ &manvol;
+
+
+
+ cec-close
+ Close a cec device
+
+
+
+
+ #include <unistd.h>
+
+ int close
+ int fd
+
+
+
+
+
+ Arguments
+
+
+
+ fd
+
+ &fd;
+
+
+
+
+
+
+ Description
+
+
+ Note: this documents the proposed CEC API. This API is not yet finalized and
+ is currently only available as a staging kernel module.
+
+
+ Closes the cec device. Resources associated with the file descriptor
+ are freed. The device configuration remain unchanged.
+
+
+
+ Return Value
+
+ close returns 0 on success. On error, -1 is
+ returned, and errno is set appropriately. Possible error
+ codes are:
+
+
+
+ EBADF
+
+ fd is not a valid open file descriptor.
+
+
+
+
+
+
diff --git a/Documentation/DocBook/media/v4l/cec-func-ioctl.xml b/Documentation/DocBook/media/v4l/cec-func-ioctl.xml
new file mode 100644
index 000000000000..f92817a2dc80
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/cec-func-ioctl.xml
@@ -0,0 +1,78 @@
+
+
+ cec ioctl()
+ &manvol;
+
+
+
+ cec-ioctl
+ Control a cec device
+
+
+
+
+ #include <sys/ioctl.h>
+
+ int ioctl
+ int fd
+ int request
+ void *argp
+
+
+
+
+
+ Arguments
+
+
+
+ fd
+
+ &fd;
+
+
+
+ request
+
+ CEC ioctl request code as defined in the cec.h header file,
+ for example CEC_ADAP_G_CAPS.
+
+
+
+ argp
+
+ Pointer to a request-specific structure.
+
+
+
+
+
+
+ Description
+
+ Note: this documents the proposed CEC API. This API is not yet finalized and
+ is currently only available as a staging kernel module.
+
+
+ The ioctl() function manipulates cec device
+ parameters. The argument fd must be an open file
+ descriptor.
+ The ioctl request code specifies the cec
+ 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
+ argp in bytes.
+ Macros and structures definitions specifying cec ioctl requests and
+ their parameters are located in the cec.h header file. All cec ioctl
+ requests, their respective function and parameters are specified in
+ .
+
+
+
+ &return-value;
+
+ Request-specific error codes are listed in the
+ individual requests descriptions.
+ When an ioctl that takes an output or read/write parameter fails,
+ the parameter remains unmodified.
+
+
diff --git a/Documentation/DocBook/media/v4l/cec-func-open.xml b/Documentation/DocBook/media/v4l/cec-func-open.xml
new file mode 100644
index 000000000000..2edc5555b81a
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/cec-func-open.xml
@@ -0,0 +1,104 @@
+
+
+ cec open()
+ &manvol;
+
+
+
+ cec-open
+ Open a cec device
+
+
+
+
+ #include <fcntl.h>
+
+ int open
+ const char *device_name
+ int flags
+
+
+
+
+
+ Arguments
+
+
+
+ device_name
+
+ Device to be opened.
+
+
+
+ flags
+
+ Open flags. Access mode must be O_RDWR.
+
+ When the O_NONBLOCK flag is
+given, the &CEC-RECEIVE; ioctl will return &EAGAIN; when no message is
+available, and the &CEC-TRANSMIT;, &CEC-ADAP-S-PHYS-ADDR; and
+&CEC-ADAP-S-LOG-ADDRS; ioctls all act in non-blocking mode.
+ Other flags have no effect.
+
+
+
+
+
+ Description
+
+ Note: this documents the proposed CEC API. This API is not yet finalized and
+ is currently only available as a staging kernel module.
+
+
+ To open a cec device applications call open()
+ with the desired device name. The function has no side effects; the device
+ configuration remain unchanged.
+ When the device is opened in read-only mode, attempts to modify its
+ configuration will result in an error, and errno will be
+ set to EBADF.
+
+
+ Return Value
+
+ open returns the new file descriptor on success.
+ On error, -1 is returned, and errno is set appropriately.
+ Possible error codes include:
+
+
+
+ EACCES
+
+ The requested access to the file is not allowed.
+
+
+
+ EMFILE
+
+ The process already has the maximum number of files open.
+
+
+
+
+ ENFILE
+
+ The system limit on the total number of open files has been
+ reached.
+
+
+
+ ENOMEM
+
+ Insufficient kernel memory was available.
+
+
+
+ ENXIO
+
+ No device corresponding to this device special file exists.
+
+
+
+
+
+
diff --git a/Documentation/DocBook/media/v4l/cec-func-poll.xml b/Documentation/DocBook/media/v4l/cec-func-poll.xml
new file mode 100644
index 000000000000..1bddbde0142d
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/cec-func-poll.xml
@@ -0,0 +1,94 @@
+
+
+ cec poll()
+ &manvol;
+
+
+
+ cec-poll
+ Wait for some event on a file descriptor
+
+
+
+
+ #include <sys/poll.h>
+
+ int poll
+ struct pollfd *ufds
+ unsigned int nfds
+ int timeout
+
+
+
+
+
+ Description
+
+
+ Note: this documents the proposed CEC API. This API is not yet finalized and
+ is currently only available as a staging kernel module.
+
+
+ With the poll() function applications
+can wait for CEC events.
+
+ On success poll() returns the number of
+file descriptors that have been selected (that is, file descriptors
+for which the revents field of the
+respective pollfd structure is non-zero).
+CEC devices set the POLLIN and
+POLLRDNORM flags in the
+revents field if there are messages in the
+receive queue. If the transmit queue has room for new messages, the
+POLLOUT and POLLWRNORM
+flags are set. If there are events in the event queue, then the
+POLLPRI flag is set.
+When the function timed out it returns a value of zero, on
+failure it returns -1 and the
+errno variable is set appropriately.
+
+
+ For more details see the
+poll() manual page.
+
+
+
+ Return Value
+
+ On success, poll() returns the number
+structures which have non-zero revents
+fields, or zero if the call timed out. On error
+-1 is returned, and the
+errno variable is set appropriately:
+
+
+
+ EBADF
+
+ One or more of the ufds members
+specify an invalid file descriptor.
+
+
+
+ EFAULT
+
+ ufds references an inaccessible
+memory area.
+
+
+
+ EINTR
+
+ The call was interrupted by a signal.
+
+
+
+ EINVAL
+
+ The nfds argument is greater
+than OPEN_MAX.
+
+
+
+
+
diff --git a/Documentation/DocBook/media/v4l/cec-ioc-adap-g-caps.xml b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-caps.xml
new file mode 100644
index 000000000000..3523ef2259b1
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-caps.xml
@@ -0,0 +1,151 @@
+
+
+ ioctl CEC_ADAP_G_CAPS
+ &manvol;
+
+
+
+ CEC_ADAP_G_CAPS
+ Query device capabilities
+
+
+
+
+
+ int ioctl
+ int fd
+ int request
+ struct cec_caps *argp
+
+
+
+
+
+ Arguments
+
+
+
+ fd
+
+ File descriptor returned by
+ open().
+
+
+
+ request
+
+ CEC_ADAP_G_CAPS
+
+
+
+ argp
+
+
+
+
+
+
+
+
+ Description
+
+
+ Note: this documents the proposed CEC API. This API is not yet finalized and
+ is currently only available as a staging kernel module.
+
+
+ All cec devices must support the CEC_ADAP_G_CAPS
+ ioctl. To query device information, applications call the ioctl with a
+ pointer to a &cec-caps;. The driver fills the structure and returns
+ the information to the application.
+ The ioctl never fails.
+
+
+ struct <structname>cec_caps</structname>
+
+ &cs-str;
+
+
+ char
+ driver[32]
+ The name of the cec adapter driver.
+
+
+ char
+ name[32]
+ The name of this CEC adapter. The combination driver
+ and name must be unique.
+
+
+ __u32
+ capabilities
+ The capabilities of the CEC adapter, see .
+
+
+ __u32
+ version
+ CEC Framework API version, formatted with the
+ KERNEL_VERSION() macro.
+
+
+
+
+
+
+ CEC Capabilities Flags
+
+ &cs-def;
+
+
+ CEC_CAP_PHYS_ADDR
+ 0x00000001
+ Userspace has to configure the physical address by
+ calling &CEC-ADAP-S-PHYS-ADDR;. If this capability isn't set,
+ then setting the physical address is handled by the kernel
+ whenever the EDID is set (for an HDMI receiver) or read (for
+ an HDMI transmitter).
+
+
+ CEC_CAP_LOG_ADDRS
+ 0x00000002
+ Userspace has to configure the logical addresses by
+ calling &CEC-ADAP-S-LOG-ADDRS;. If this capability isn't set,
+ then the kernel will have configured this.
+
+
+ CEC_CAP_TRANSMIT
+ 0x00000004
+ Userspace can transmit CEC messages by calling &CEC-TRANSMIT;. This
+ implies that userspace can be a follower as well, since being able to
+ transmit messages is a prerequisite of becoming a follower. If this
+ capability isn't set, then the kernel will handle all CEC transmits
+ and process all CEC messages it receives.
+
+
+
+ CEC_CAP_PASSTHROUGH
+ 0x00000008
+ Userspace can use the passthrough mode by
+ calling &CEC-S-MODE;.
+
+
+ CEC_CAP_RC
+ 0x00000010
+ This adapter supports the remote control protocol.
+
+
+ CEC_CAP_MONITOR_ALL
+ 0x00000020
+ The CEC hardware can monitor all messages, not just directed and
+ broadcast messages.
+
+
+
+
+
+
+
+ &return-value;
+
+
diff --git a/Documentation/DocBook/media/v4l/cec-ioc-adap-g-log-addrs.xml b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-log-addrs.xml
new file mode 100644
index 000000000000..302b8294f7fc
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-log-addrs.xml
@@ -0,0 +1,329 @@
+
+
+ ioctl CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS
+ &manvol;
+
+
+
+ CEC_ADAP_G_LOG_ADDRS
+ CEC_ADAP_S_LOG_ADDRS
+ Get or set the logical addresses
+
+
+
+
+
+ int ioctl
+ int fd
+ int request
+ struct cec_log_addrs *argp
+
+
+
+
+
+ Arguments
+
+
+
+ fd
+
+ File descriptor returned by
+ open().
+
+
+
+ request
+
+ CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS
+
+
+
+ argp
+
+
+
+
+
+
+
+
+ Description
+
+
+ Note: this documents the proposed CEC API. This API is not yet finalized and
+ is currently only available as a staging kernel module.
+
+
+ To query the current CEC logical addresses, applications call the
+CEC_ADAP_G_LOG_ADDRS ioctl with a pointer to a
+cec_log_addrs structure where the drivers stores the
+logical addresses.
+
+ To set new logical addresses, applications fill in struct cec_log_addrs
+and call the CEC_ADAP_S_LOG_ADDRS ioctl with a pointer to this struct.
+The CEC_ADAP_S_LOG_ADDRS ioctl is only available if
+CEC_CAP_LOG_ADDRS is set (&ENOTTY; is returned otherwise). This ioctl will block until all
+requested logical addresses have been claimed. CEC_ADAP_S_LOG_ADDRS
+can only be called by a file handle in initiator mode (see &CEC-S-MODE;).
+
+
+ struct <structname>cec_log_addrs</structname>
+
+ &cs-str;
+
+
+ __u8
+ log_addr[CEC_MAX_LOG_ADDRS]
+ The actual logical addresses that were claimed. This is set by the
+ driver. If no logical address could be claimed, then it is set to
+ CEC_LOG_ADDR_INVALID. If this adapter is Unregistered,
+ then log_addr[0] is set to 0xf and all others to
+ CEC_LOG_ADDR_INVALID.
+
+
+ __u16
+ log_addr_mask
+ The bitmask of all logical addresses this adapter has claimed.
+ If this adapter is Unregistered then log_addr_mask
+ sets bit 15 and clears all other bits. If this adapter is not configured at all, then
+ log_addr_mask is set to 0. Set by the driver.
+
+
+ __u8
+ cec_version
+ The CEC version that this adapter shall use. See
+ .
+ Used to implement the CEC_MSG_CEC_VERSION and
+ CEC_MSG_REPORT_FEATURES messages. Note that
+ CEC_OP_CEC_VERSION_1_3A is not allowed
+ by the CEC framework.
+
+
+
+ __u8
+ num_log_addrs
+ Number of logical addresses to set up. Must be ≤
+ available_log_addrs as returned by
+ &CEC-ADAP-G-CAPS;. All arrays in this structure are only filled up to
+ index available_log_addrs-1. The remaining
+ array elements will be ignored. Note that the CEC 2.0 standard allows
+ for a maximum of 2 logical addresses, although some hardware has support
+ for more. CEC_MAX_LOG_ADDRS is 4. The driver will
+ return the actual number of logical addresses it could claim, which may
+ be less than what was requested. If this field is set to 0, then the
+ CEC adapter shall clear all claimed logical addresses and all other
+ fields will be ignored.
+
+
+ __u32
+ vendor_id
+ The vendor ID is a 24-bit number that identifies the specific
+ vendor or entity. Based on this ID vendor specific commands may be
+ defined. If you do not want a vendor ID then set it to
+ CEC_VENDOR_ID_NONE.
+
+
+ __u32
+ flags
+ Flags. No flags are defined yet, so set this to 0.
+
+
+ char
+ osd_name[15]
+ The On-Screen Display name as is returned by the
+ CEC_MSG_SET_OSD_NAME message.
+
+
+ __u8
+ primary_device_type[CEC_MAX_LOG_ADDRS]
+ Primary device type for each logical address. See
+ for possible types.
+
+
+ __u8
+ log_addr_type[CEC_MAX_LOG_ADDRS]
+ Logical address types. See for
+ possible types. The driver will update this with the actual logical address
+ type that it claimed (e.g. it may have to fallback to
+ CEC_LOG_ADDR_TYPE_UNREGISTERED).
+
+
+ __u8
+ all_device_types[CEC_MAX_LOG_ADDRS]
+ CEC 2.0 specific: all device types. See .
+ Used to implement the CEC_MSG_REPORT_FEATURES message.
+ This field is ignored if cec_version <
+ CEC_OP_CEC_VERSION_2_0.
+
+
+ __u8
+ features[CEC_MAX_LOG_ADDRS][12]
+ Features for each logical address. Used to implement the
+ CEC_MSG_REPORT_FEATURES message. The 12 bytes include
+ both the RC Profile and the Device Features.
+ This field is ignored if cec_version <
+ CEC_OP_CEC_VERSION_2_0.
+
+
+
+
+
+
+ CEC Versions
+
+ &cs-def;
+
+
+ CEC_OP_CEC_VERSION_1_3A
+ 4
+ CEC version according to the HDMI 1.3a standard.
+
+
+ CEC_OP_CEC_VERSION_1_4B
+ 5
+ CEC version according to the HDMI 1.4b standard.
+
+
+ CEC_OP_CEC_VERSION_2_0
+ 6
+ CEC version according to the HDMI 2.0 standard.
+
+
+
+
+
+
+ CEC Primary Device Types
+
+ &cs-def;
+
+
+ CEC_OP_PRIM_DEVTYPE_TV
+ 0
+ Use for a TV.
+
+
+ CEC_OP_PRIM_DEVTYPE_RECORD
+ 1
+ Use for a recording device.
+
+
+ CEC_OP_PRIM_DEVTYPE_TUNER
+ 3
+ Use for a device with a tuner.
+
+
+ CEC_OP_PRIM_DEVTYPE_PLAYBACK
+ 4
+ Use for a playback device.
+
+
+ CEC_OP_PRIM_DEVTYPE_AUDIOSYSTEM
+ 5
+ Use for an audio system (e.g. an audio/video receiver).
+
+
+ CEC_OP_PRIM_DEVTYPE_SWITCH
+ 6
+ Use for a CEC switch.
+
+
+ CEC_OP_PRIM_DEVTYPE_VIDEOPROC
+ 7
+ Use for a video processor device.
+
+
+
+
+
+
+ CEC Logical Address Types
+
+ &cs-def;
+
+
+ CEC_LOG_ADDR_TYPE_TV
+ 0
+ Use for a TV.
+
+
+ CEC_LOG_ADDR_TYPE_RECORD
+ 1
+ Use for a recording device.
+
+
+ CEC_LOG_ADDR_TYPE_TUNER
+ 2
+ Use for a tuner device.
+
+
+ CEC_LOG_ADDR_TYPE_PLAYBACK
+ 3
+ Use for a playback device.
+
+
+ CEC_LOG_ADDR_TYPE_AUDIOSYSTEM
+ 4
+ Use for an audio system device.
+
+
+ CEC_LOG_ADDR_TYPE_SPECIFIC
+ 5
+ Use for a second TV or for a video processor device.
+
+
+ CEC_LOG_ADDR_TYPE_UNREGISTERED
+ 6
+ Use this if you just want to remain unregistered.
+ Used for pure CEC switches or CDC-only devices (CDC:
+ Capability Discovery and Control).
+
+
+
+
+
+
+ CEC All Device Types Flags
+
+ &cs-def;
+
+
+ CEC_OP_ALL_DEVTYPE_TV
+ 0x80
+ This supports the TV type.
+
+
+ CEC_OP_ALL_DEVTYPE_RECORD
+ 0x40
+ This supports the Recording type.
+
+
+ CEC_OP_ALL_DEVTYPE_TUNER
+ 0x20
+ This supports the Tuner type.
+
+
+ CEC_OP_ALL_DEVTYPE_PLAYBACK
+ 0x10
+ This supports the Playback type.
+
+
+ CEC_OP_ALL_DEVTYPE_AUDIOSYSTEM
+ 0x08
+ This supports the Audio System type.
+
+
+ CEC_OP_ALL_DEVTYPE_SWITCH
+ 0x04
+ This supports the CEC Switch or Video Processing type.
+
+
+
+
+
+
+
+ &return-value;
+
+
diff --git a/Documentation/DocBook/media/v4l/cec-ioc-adap-g-phys-addr.xml b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-phys-addr.xml
new file mode 100644
index 000000000000..d95f1785080c
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-phys-addr.xml
@@ -0,0 +1,86 @@
+
+
+ ioctl CEC_ADAP_G_PHYS_ADDR, CEC_ADAP_S_PHYS_ADDR
+ &manvol;
+
+
+
+ CEC_ADAP_G_PHYS_ADDR
+ CEC_ADAP_S_PHYS_ADDR
+ Get or set the physical address
+
+
+
+
+
+ int ioctl
+ int fd
+ int request
+ __u16 *argp
+
+
+
+
+
+ Arguments
+
+
+
+ fd
+
+ File descriptor returned by
+ open().
+
+
+
+ request
+
+ CEC_ADAP_G_PHYS_ADDR, CEC_ADAP_S_PHYS_ADDR
+
+
+
+ argp
+
+
+
+
+
+
+
+
+ Description
+
+
+ Note: this documents the proposed CEC API. This API is not yet finalized and
+ is currently only available as a staging kernel module.
+
+
+ To query the current physical address applications call the
+CEC_ADAP_G_PHYS_ADDR ioctl with a pointer to an __u16
+where the driver stores the physical address.
+
+ To set a new physical address applications store the physical address in
+an __u16 and call the CEC_ADAP_S_PHYS_ADDR ioctl with a
+pointer to this integer. CEC_ADAP_S_PHYS_ADDR is only
+available if CEC_CAP_PHYS_ADDR is set (&ENOTTY; will be returned
+otherwise). CEC_ADAP_S_PHYS_ADDR
+can only be called by a file handle in initiator mode (see &CEC-S-MODE;), if not
+&EBUSY; will be returned.
+
+ The physical address is a 16-bit number where each group of 4 bits
+represent a digit of the physical address a.b.c.d where the most significant
+4 bits represent 'a'. The CEC root device (usually the TV) has address 0.0.0.0.
+Every device that is hooked up to an input of the TV has address a.0.0.0 (where
+'a' is ≥ 1), devices hooked up to those in turn have addresses a.b.0.0, etc.
+So a topology of up to 5 devices deep is supported. The physical address a
+device shall use is stored in the EDID of the sink.
+
+For example, the EDID for each HDMI input of the TV will have a different
+physical address of the form a.0.0.0 that the sources will read out and use as
+their physical address.
+
+
+
+ &return-value;
+
+
diff --git a/Documentation/DocBook/media/v4l/cec-ioc-dqevent.xml b/Documentation/DocBook/media/v4l/cec-ioc-dqevent.xml
new file mode 100644
index 000000000000..697dde575cd4
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/cec-ioc-dqevent.xml
@@ -0,0 +1,202 @@
+
+
+ ioctl CEC_DQEVENT
+ &manvol;
+
+
+
+ CEC_DQEVENT
+ Dequeue a CEC event
+
+
+
+
+
+ int ioctl
+ int fd
+ int request
+ struct cec_event *argp
+
+
+
+
+
+ Arguments
+
+
+
+ fd
+
+ File descriptor returned by
+ open().
+
+
+
+ request
+
+ CEC_DQEVENT
+
+
+
+ argp
+
+
+
+
+
+
+
+
+ Description
+
+
+ Note: this documents the proposed CEC API. This API is not yet finalized and
+ is currently only available as a staging kernel module.
+
+
+ CEC devices can send asynchronous events. These can be retrieved by calling
+ the CEC_DQEVENT ioctl. If the file descriptor is in non-blocking
+ mode and no event is pending, then it will return -1 and set errno to the &EAGAIN;.
+
+ The internal event queues are per-filehandle and per-event type. If there is
+ no more room in a queue then the last event is overwritten with the new one. This
+ means that intermediate results can be thrown away but that the latest event is always
+ available. This also means that is it possible to read two successive events that have
+ the same value (e.g. two CEC_EVENT_STATE_CHANGE events with the same state). In that
+ case the intermediate state changes were lost but it is guaranteed that the state
+ did change in between the two events.
+
+
+ struct <structname>cec_event_state_change</structname>
+
+ &cs-str;
+
+
+ __u16
+ phys_addr
+ The current physical address.
+
+
+ __u16
+ log_addr_mask
+ The current set of claimed logical addresses.
+
+
+
+
+
+
+ struct <structname>cec_event_lost_msgs</structname>
+
+ &cs-str;
+
+
+ __u32
+ lost_msgs
+ Set to the number of lost messages since the filehandle
+ was opened or since the last time this event was dequeued for
+ this filehandle. The messages lost are the oldest messages. So
+ when a new message arrives and there is no more room, then the
+ oldest message is discarded to make room for the new one. The
+ internal size of the message queue guarantees that all messages
+ received in the last two seconds will be stored. Since messages
+ should be replied to within a second according to the CEC
+ specification, this is more than enough.
+
+
+
+
+
+
+
+ struct <structname>cec_event</structname>
+
+ &cs-str;
+
+
+ __u64
+ ts
+ Timestamp of the event in ns.
+
+
+
+ __u32
+ event
+ The CEC event type, see .
+
+
+
+ __u32
+ flags
+ Event flags, see .
+
+
+
+ union
+ (anonymous)
+
+
+
+
+
+ struct cec_event_state_change
+ state_change
+ The new adapter state as sent by the CEC_EVENT_STATE_CHANGE
+ event.
+
+
+
+ struct cec_event_lost_msgs
+ lost_msgs
+ The number of lost messages as sent by the CEC_EVENT_LOST_MSGS
+ event.
+
+
+
+
+
+
+ CEC Events Types
+
+ &cs-def;
+
+
+ CEC_EVENT_STATE_CHANGE
+ 1
+ Generated when the CEC Adapter's state changes. When open() is
+ called an initial event will be generated for that filehandle with the
+ CEC Adapter's state at that time.
+
+
+
+ CEC_EVENT_LOST_MSGS
+ 2
+ Generated if one or more CEC messages were lost because the
+ application didn't dequeue CEC messages fast enough.
+
+
+
+
+
+
+ CEC Event Flags
+
+ &cs-def;
+
+
+ CEC_EVENT_FL_INITIAL_VALUE
+ 1
+ Set for the initial events that are generated when the device is
+ opened. See the table above for which events do this. This allows
+ applications to learn the initial state of the CEC adapter at open()
+ time.
+
+
+
+
+
+
+
+ &return-value;
+
+
diff --git a/Documentation/DocBook/media/v4l/cec-ioc-g-mode.xml b/Documentation/DocBook/media/v4l/cec-ioc-g-mode.xml
new file mode 100644
index 000000000000..26b4282ad134
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/cec-ioc-g-mode.xml
@@ -0,0 +1,255 @@
+
+
+ ioctl CEC_G_MODE, CEC_S_MODE
+ &manvol;
+
+
+
+ CEC_G_MODE
+ CEC_S_MODE
+ Get or set exclusive use of the CEC adapter
+
+
+
+
+
+ int ioctl
+ int fd
+ int request
+ __u32 *argp
+
+
+
+
+
+ Arguments
+
+
+
+ fd
+
+ File descriptor returned by
+ open().
+
+
+
+ request
+
+ CEC_G_MODE, CEC_S_MODE
+
+
+
+ argp
+
+
+
+
+
+
+
+
+ Description
+
+
+ Note: this documents the proposed CEC API. This API is not yet finalized and
+ is currently only available as a staging kernel module.
+
+
+ By default any filehandle can use &CEC-TRANSMIT; and &CEC-RECEIVE;, but
+in order to prevent applications from stepping on each others toes it must be possible
+to obtain exclusive access to the CEC adapter. This ioctl sets the filehandle
+to initiator and/or follower mode which can be exclusive depending on the chosen
+mode. The initiator is the filehandle that is used
+to initiate messages, i.e. it commands other CEC devices. The follower is the filehandle
+that receives messages sent to the CEC adapter and processes them. The same filehandle
+can be both initiator and follower, or this role can be taken by two different
+filehandles.
+
+ When a CEC message is received, then the CEC framework will decide how
+it will be processed. If the message is a reply to an earlier transmitted message,
+then the reply is sent back to the filehandle that is waiting for it. In addition
+the CEC framework will process it.
+
+ If the message is not a reply, then the CEC framework will process it
+first. If there is no follower, then the message is just discarded and a feature
+abort is sent back to the initiator if the framework couldn't process it. If there
+is a follower, then the message is passed on to the follower who will use
+&CEC-RECEIVE; to dequeue the new message. The framework expects the follower to
+make the right decisions.
+
+ The CEC framework will process core messages unless requested otherwise
+by the follower. The follower can enable the passthrough mode. In that case, the
+CEC framework will pass on most core messages without processing them and
+the follower will have to implement those messages. There are some messages
+that the core will always process, regardless of the passthrough mode. See
+ for details.
+
+ If there is no initiator, then any CEC filehandle can use &CEC-TRANSMIT;.
+If there is an exclusive initiator then only that initiator can call &CEC-TRANSMIT;.
+The follower can of course always call &CEC-TRANSMIT;.
+
+ Available initiator modes are:
+
+
+ Initiator Modes
+
+ &cs-def;
+
+
+ CEC_MODE_NO_INITIATOR
+ 0x0
+ This is not an initiator, i.e. it cannot transmit CEC messages
+ or make any other changes to the CEC adapter.
+
+
+ CEC_MODE_INITIATOR
+ 0x1
+ This is an initiator (the default when the device is opened) and it
+ can transmit CEC messages and make changes to the CEC adapter, unless there
+ is an exclusive initiator.
+
+
+ CEC_MODE_EXCL_INITIATOR
+ 0x2
+ This is an exclusive initiator and this file descriptor is the only one
+ that can transmit CEC messages and make changes to the CEC adapter. If someone
+ else is already the exclusive initiator then an attempt to become one will return
+ the &EBUSY; error.
+
+
+
+
+
+ Available follower modes are:
+
+
+ Follower Modes
+
+ &cs-def;
+
+
+ CEC_MODE_NO_FOLLOWER
+ 0x00
+ This is not a follower (the default when the device is opened).
+
+
+ CEC_MODE_FOLLOWER
+ 0x10
+ This is a follower and it will receive CEC messages unless there is
+ an exclusive follower. You cannot become a follower if CEC_CAP_TRANSMIT
+ is not set or if CEC_MODE_NO_INITIATOR was specified,
+ &EINVAL; is returned in that case.
+
+
+ CEC_MODE_EXCL_FOLLOWER
+ 0x20
+ This is an exclusive follower and only this file descriptor will receive
+ CEC messages for processing. If someone else is already the exclusive follower
+ then an attempt to become one will return the &EBUSY; error. You cannot become
+ a follower if CEC_CAP_TRANSMIT is not set or if
+ CEC_MODE_NO_INITIATOR was specified, &EINVAL; is returned
+ in that case.
+
+
+ CEC_MODE_EXCL_FOLLOWER_PASSTHRU
+ 0x30
+ This is an exclusive follower and only this file descriptor will receive
+ CEC messages for processing. In addition it will put the CEC device into
+ passthrough mode, allowing the exclusive follower to handle most core messages
+ instead of relying on the CEC framework for that. If someone else is already the
+ exclusive follower then an attempt to become one will return the &EBUSY; error.
+ You cannot become a follower if CEC_CAP_TRANSMIT
+ is not set or if CEC_MODE_NO_INITIATOR was specified,
+ &EINVAL; is returned in that case.
+
+
+ CEC_MODE_MONITOR
+ 0xe0
+ Put the file descriptor into monitor mode. Can only be used in combination
+ with CEC_MODE_NO_INITIATOR, otherwise &EINVAL; will be
+ returned. In monitor mode all messages this CEC device transmits and all messages
+ it receives (both broadcast messages and directed messages for one its logical
+ addresses) will be reported. This is very useful for debugging. This is only
+ allowed if the process has the CAP_NET_ADMIN
+ capability. If that is not set, then &EPERM; is returned.
+
+
+ CEC_MODE_MONITOR_ALL
+ 0xf0
+ Put the file descriptor into 'monitor all' mode. Can only be used in combination
+ with CEC_MODE_NO_INITIATOR, otherwise &EINVAL; will be
+ returned. In 'monitor all' mode all messages this CEC device transmits and all messages
+ it receives, including directed messages for other CEC devices will be reported. This
+ is very useful for debugging, but not all devices support this. This mode requires that
+ the CEC_CAP_MONITOR_ALL capability is set, otherwise &EINVAL; is
+ returned. This is only allowed if the process has the CAP_NET_ADMIN
+ capability. If that is not set, then &EPERM; is returned.
+
+
+
+
+
+ Core message processing details:
+
+
+ Core Message Processing
+
+ &cs-def;
+
+
+ CEC_MSG_GET_CEC_VERSION
+ When in passthrough mode this message has to be handled by userspace,
+ otherwise the core will return the CEC version that was set with &CEC-ADAP-S-LOG-ADDRS;.
+
+
+ CEC_MSG_GIVE_DEVICE_VENDOR_ID
+ When in passthrough mode this message has to be handled by userspace,
+ otherwise the core will return the vendor ID that was set with &CEC-ADAP-S-LOG-ADDRS;.
+
+
+ CEC_MSG_ABORT
+ When in passthrough mode this message has to be handled by userspace,
+ otherwise the core will return a feature refused message as per the specification.
+
+
+ CEC_MSG_GIVE_PHYSICAL_ADDR
+ When in passthrough mode this message has to be handled by userspace,
+ otherwise the core will report the current physical address.
+
+
+ CEC_MSG_GIVE_OSD_NAME
+ When in passthrough mode this message has to be handled by userspace,
+ otherwise the core will report the current OSD name as was set with
+ &CEC-ADAP-S-LOG-ADDRS;.
+
+
+ CEC_MSG_GIVE_FEATURES
+ When in passthrough mode this message has to be handled by userspace,
+ otherwise the core will report the current features as was set with
+ &CEC-ADAP-S-LOG-ADDRS; or the message is ignore if the CEC version was
+ older than 2.0.
+
+
+ CEC_MSG_USER_CONTROL_PRESSED
+ If CEC_CAP_RC is set, then generate a remote control
+ key press. This message is always passed on to userspace.
+
+
+ CEC_MSG_USER_CONTROL_RELEASED
+ If CEC_CAP_RC is set, then generate a remote control
+ key release. This message is always passed on to userspace.
+
+
+ CEC_MSG_REPORT_PHYSICAL_ADDR
+ The CEC framework will make note of the reported physical address
+ and then just pass the message on to userspace.
+
+
+
+
+
+
+
+ &return-value;
+
+
diff --git a/Documentation/DocBook/media/v4l/cec-ioc-receive.xml b/Documentation/DocBook/media/v4l/cec-ioc-receive.xml
new file mode 100644
index 000000000000..fde9f8678e67
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/cec-ioc-receive.xml
@@ -0,0 +1,274 @@
+
+
+ ioctl CEC_RECEIVE, CEC_TRANSMIT
+ &manvol;
+
+
+
+ CEC_RECEIVE
+ CEC_TRANSMIT
+ Receive or transmit a CEC message
+
+
+
+
+
+ int ioctl
+ int fd
+ int request
+ struct cec_msg *argp
+
+
+
+
+
+ Arguments
+
+
+
+ fd
+
+ File descriptor returned by
+ open().
+
+
+
+ request
+
+ CEC_RECEIVE, CEC_TRANSMIT
+
+
+
+ argp
+
+
+
+
+
+
+
+
+ Description
+
+
+ Note: this documents the proposed CEC API. This API is not yet finalized and
+ is currently only available as a staging kernel module.
+
+
+ To receive a CEC message the application has to fill in the
+ cec_msg structure and pass it to the
+ CEC_RECEIVE ioctl. CEC_RECEIVE is
+ only available if CEC_CAP_RECEIVE is set. If the
+ file descriptor is in non-blocking mode and there are no received
+ messages pending, then it will return -1 and set errno to the &EAGAIN;.
+ If the file descriptor is in blocking mode and timeout
+ is non-zero and no message arrived within timeout
+ milliseconds, then it will return -1 and set errno to the &ETIMEDOUT;.
+
+ To send a CEC message the application has to fill in the
+ cec_msg structure and pass it to the
+ CEC_TRANSMIT ioctl. CEC_TRANSMIT is
+ only available if CEC_CAP_TRANSMIT is set.
+ If there is no more room in the transmit queue, then it will return
+ -1 and set errno to the &EBUSY;.
+
+
+ struct <structname>cec_msg</structname>
+
+ &cs-str;
+
+
+ __u64
+ ts
+ Timestamp of when the message was transmitted in ns in the case
+ of CEC_TRANSMIT with reply
+ set to 0, or the timestamp of the received message in all other cases.
+
+
+ __u32
+ len
+ The length of the message. For CEC_TRANSMIT this
+ is filled in by the application. The driver will fill this in for
+ CEC_RECEIVE and for CEC_TRANSMIT
+ it will be filled in with the length of the reply message if
+ reply was set.
+
+
+ __u32
+ timeout
+ The timeout in milliseconds. This is the time the device will wait for a message to
+ be received before timing out. If it is set to 0, then it will wait indefinitely when it
+ is called by CEC_RECEIVE. If it is 0 and it is called by
+ CEC_TRANSMIT, then it will be replaced by 1000 if the
+ reply is non-zero or ignored if reply
+ is 0.
+
+
+ __u32
+ sequence
+ The sequence number is automatically assigned by the CEC
+ framework for all transmitted messages. It can be later used by the
+ framework to generate an event if a reply for a message was
+ requested and the message was transmitted in a non-blocking mode.
+
+
+
+ __u32
+ flags
+ Flags. No flags are defined yet, so set this to 0.
+
+
+ __u8
+ rx_status
+ The status bits of the received message. See
+ for the possible status values. It is 0 if this message was transmitted, not
+ received, unless this is the reply to a transmitted message. In that case both
+ rx_status and tx_status
+ are set.
+
+
+ __u8
+ tx_status
+ The status bits of the transmitted message. See
+ for the possible status values. It is 0 if this messages was received, not
+ transmitted.
+
+
+ __u8
+ msg[16]
+ The message payload. For CEC_TRANSMIT this
+ is filled in by the application. The driver will fill this in for
+ CEC_RECEIVE and for CEC_TRANSMIT
+ it will be filled in with the payload of the reply message if
+ reply was set.
+
+
+ __u8
+ reply
+ Wait until this message is replied. If reply
+ is 0 and the timeout is 0, then don't wait for a reply but
+ return after transmitting the message. If there was an error as indicated by a non-zero
+ tx_status field, then reply and
+ timeout are both set to 0 by the driver. Ignored by
+ CEC_RECEIVE. The case where reply is 0
+ (this is the opcode for the Feature Abort message) and timeout
+ is non-zero is specifically allowed to send a message and wait up to timeout
+ milliseconds for a Feature Abort reply. In this case rx_status
+ will either be set to CEC_RX_STATUS_TIMEOUT or
+ CEC_RX_STATUS_FEATURE_ABORT.
+
+
+ __u8
+ tx_arb_lost_cnt
+ A counter of the number of transmit attempts that resulted in the
+ Arbitration Lost error. This is only set if the hardware supports this, otherwise
+ it is always 0. This counter is only valid if the CEC_TX_STATUS_ARB_LOST
+ status bit is set.
+
+
+ __u8
+ tx_nack_cnt
+ A counter of the number of transmit attempts that resulted in the
+ Not Acknowledged error. This is only set if the hardware supports this, otherwise
+ it is always 0. This counter is only valid if the CEC_TX_STATUS_NACK
+ status bit is set.
+
+
+ __u8
+ tx_low_drive_cnt
+ A counter of the number of transmit attempts that resulted in the
+ Arbitration Lost error. This is only set if the hardware supports this, otherwise
+ it is always 0. This counter is only valid if the CEC_TX_STATUS_LOW_DRIVE
+ status bit is set.
+
+
+ __u8
+ tx_error_cnt
+ A counter of the number of transmit errors other than Arbitration Lost
+ or Not Acknowledged. This is only set if the hardware supports this, otherwise
+ it is always 0. This counter is only valid if the CEC_TX_STATUS_ERROR
+ status bit is set.
+
+
+
+
+
+
+ CEC Transmit Status
+
+ &cs-def;
+
+
+ CEC_TX_STATUS_OK
+ 0x01
+ The message was transmitted successfully. This is mutually exclusive with
+ CEC_TX_STATUS_MAX_RETRIES. Other bits can still be set if
+ earlier attempts met with failure before the transmit was eventually successful.
+
+
+ CEC_TX_STATUS_ARB_LOST
+ 0x02
+ CEC line arbitration was lost.
+
+
+ CEC_TX_STATUS_NACK
+ 0x04
+ Message was not acknowledged.
+
+
+ CEC_TX_STATUS_LOW_DRIVE
+ 0x08
+ Low drive was detected on the CEC bus. This indicates that a follower
+ detected an error on the bus and requests a retransmission.
+
+
+ CEC_TX_STATUS_ERROR
+ 0x10
+ Some error occurred. This is used for any errors that do not
+ fit the previous two, either because the hardware could not tell
+ which error occurred, or because the hardware tested for other conditions
+ besides those two.
+
+
+ CEC_TX_STATUS_MAX_RETRIES
+ 0x20
+ The transmit failed after one or more retries. This status bit is mutually
+ exclusive with CEC_TX_STATUS_OK. Other bits can still be set
+ to explain which failures were seen.
+
+
+
+
+
+
+ CEC Receive Status
+
+ &cs-def;
+
+
+ CEC_RX_STATUS_OK
+ 0x01
+ The message was received successfully.
+
+
+ CEC_RX_STATUS_TIMEOUT
+ 0x02
+ The reply to an earlier transmitted message timed out.
+
+
+ CEC_RX_STATUS_FEATURE_ABORT
+ 0x04
+ The message was received successfully but the reply was
+ CEC_MSG_FEATURE_ABORT. This status is only
+ set if this message was the reply to an earlier transmitted
+ message.
+
+
+
+
+
+
+
+ &return-value;
+
+
diff --git a/Documentation/DocBook/media_api.tmpl b/Documentation/DocBook/media_api.tmpl
index 7b77e0f7b87d..a2765d8ad05c 100644
--- a/Documentation/DocBook/media_api.tmpl
+++ b/Documentation/DocBook/media_api.tmpl
@@ -75,7 +75,7 @@
The media infrastructure API was designed to control such
- devices. It is divided into four parts.
+ devices. It is divided into five parts.
The first part covers radio, video capture and output,
cameras, analog TV devices and codecs.The second part covers the
@@ -87,6 +87,7 @@
.The third part covers the Remote Controller API.The fourth part covers the Media Controller API.
+ The fifth part covers the CEC (Consumer Electronics Control) API.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.
@@ -107,6 +108,9 @@
&sub-media-controller;
+
+&sub-cec-api;
+
&sub-gen-errors;