From patchwork Fri Mar 18 14:07:09 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Hans Verkuil X-Patchwork-Id: 8619571 Return-Path: X-Original-To: patchwork-linux-media@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork2.web.kernel.org (Postfix) with ESMTP id BB20BC0553 for ; Fri, 18 Mar 2016 14:17:57 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 3E18520303 for ; Fri, 18 Mar 2016 14:17:53 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 526D62034B for ; Fri, 18 Mar 2016 14:17:48 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S933364AbcCRORB (ORCPT ); Fri, 18 Mar 2016 10:17:01 -0400 Received: from aer-iport-2.cisco.com ([173.38.203.52]:8541 "EHLO aer-iport-2.cisco.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S932306AbcCROQp (ORCPT ); Fri, 18 Mar 2016 10:16:45 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=cisco.com; i=@cisco.com; l=83399; q=dns/txt; s=iport; t=1458310605; x=1459520205; h=from:to:cc:subject:date:message-id:in-reply-to: references; bh=gke6qtQtOP8lmrBDWA6t3fVgZfyEDHAaPS9o6J+/80E=; b=JbDl+hHa0tOE8G7b0DrBJojVFd2H9liirLwu//6EjVjzEKPKpkpBEzrP foG56+wdaEq/eR54OugMrGoO7XvR5v7IYYkaLskR1/P8odLzN8GL7n9kh s81iPrpfKH7cWm3sX32Re9EwXK2R3YohLwj5M/F7jNkbV4LhcH3QWQ7LO M=; X-IronPort-AV: E=Sophos;i="5.24,355,1454976000"; d="scan'208";a="633534631" Received: from aer-iport-nat.cisco.com (HELO aer-core-1.cisco.com) ([173.38.203.22]) by aer-iport-2.cisco.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 18 Mar 2016 14:06:51 +0000 Received: from cobaltpc1.rd.cisco.com ([10.47.79.81]) (authenticated bits=0) by aer-core-1.cisco.com (8.14.5/8.14.5) with ESMTP id u2IE6jda023128 (version=TLSv1/SSLv3 cipher=AES128-SHA256 bits=128 verify=NO); Fri, 18 Mar 2016 14:06:50 GMT From: Hans Verkuil To: linux-media@vger.kernel.org Cc: dri-devel@lists.freedesktop.org, linux-samsung-soc@vger.kernel.org, linux-input@vger.kernel.org, lars@opdenkamp.eu, linux@arm.linux.org.uk, Hans Verkuil , Kamil Debski , Hans Verkuil Subject: [PATCHv13 10/17] DocBook/media: add CEC documentation Date: Fri, 18 Mar 2016 15:07:09 +0100 Message-Id: <1458310036-19252-11-git-send-email-hans.verkuil@cisco.com> X-Mailer: git-send-email 2.7.0 In-Reply-To: <1458310036-19252-1-git-send-email-hans.verkuil@cisco.com> References: <1458310036-19252-1-git-send-email-hans.verkuil@cisco.com> X-Authenticated-User: hansverk Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Spam-Status: No, score=-14.5 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, RCVD_IN_DNSWL_HI, RP_MATCHES_RCVD, UNPARSEABLE_RELAY, USER_IN_DEF_DKIM_WL autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Add DocBook documentation for the CEC API. Signed-off-by: Hans Verkuil [k.debski@samsung.com: add documentation for passthrough mode] [k.debski@samsung.com: minor fixes and change of reserved field sizes] Signed-off-by: Kamil Debski Signed-off-by: Hans Verkuil --- Documentation/DocBook/device-drivers.tmpl | 3 + Documentation/DocBook/media/Makefile | 2 + Documentation/DocBook/media/v4l/biblio.xml | 10 + Documentation/DocBook/media/v4l/cec-api.xml | 75 +++++ Documentation/DocBook/media/v4l/cec-func-close.xml | 59 ++++ Documentation/DocBook/media/v4l/cec-func-ioctl.xml | 73 +++++ Documentation/DocBook/media/v4l/cec-func-open.xml | 94 +++++++ Documentation/DocBook/media/v4l/cec-func-poll.xml | 89 ++++++ .../DocBook/media/v4l/cec-ioc-adap-g-caps.xml | 174 ++++++++++++ .../DocBook/media/v4l/cec-ioc-adap-g-log-addrs.xml | 306 +++++++++++++++++++++ .../DocBook/media/v4l/cec-ioc-adap-g-phys-addr.xml | 81 ++++++ .../DocBook/media/v4l/cec-ioc-adap-g-state.xml | 88 ++++++ .../DocBook/media/v4l/cec-ioc-adap-g-vendor-id.xml | 71 +++++ .../DocBook/media/v4l/cec-ioc-adap-log-status.xml | 51 ++++ .../DocBook/media/v4l/cec-ioc-dqevent.xml | 280 +++++++++++++++++++ Documentation/DocBook/media/v4l/cec-ioc-g-mode.xml | 286 +++++++++++++++++++ .../DocBook/media/v4l/cec-ioc-receive.xml | 261 ++++++++++++++++++ Documentation/DocBook/media_api.tmpl | 6 +- 18 files changed, 2008 insertions(+), 1 deletion(-) create mode 100644 Documentation/DocBook/media/v4l/cec-api.xml create mode 100644 Documentation/DocBook/media/v4l/cec-func-close.xml create mode 100644 Documentation/DocBook/media/v4l/cec-func-ioctl.xml create mode 100644 Documentation/DocBook/media/v4l/cec-func-open.xml create mode 100644 Documentation/DocBook/media/v4l/cec-func-poll.xml create mode 100644 Documentation/DocBook/media/v4l/cec-ioc-adap-g-caps.xml create mode 100644 Documentation/DocBook/media/v4l/cec-ioc-adap-g-log-addrs.xml create mode 100644 Documentation/DocBook/media/v4l/cec-ioc-adap-g-phys-addr.xml create mode 100644 Documentation/DocBook/media/v4l/cec-ioc-adap-g-state.xml create mode 100644 Documentation/DocBook/media/v4l/cec-ioc-adap-g-vendor-id.xml create mode 100644 Documentation/DocBook/media/v4l/cec-ioc-adap-log-status.xml create mode 100644 Documentation/DocBook/media/v4l/cec-ioc-dqevent.xml create mode 100644 Documentation/DocBook/media/v4l/cec-ioc-g-mode.xml create mode 100644 Documentation/DocBook/media/v4l/cec-ioc-receive.xml diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index cc303a2..9db705d 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -269,6 +269,9 @@ X!Isound/sound_firmware.c !Iinclude/media/media-devnode.h !Iinclude/media/media-entity.h + Consumer Electronics Control devices +!Iinclude/media/cec.h + diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile index 2840ff4..497b57e 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/uapi/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/uapi/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 9beb30f..87f1d24 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 0000000..c344b3a --- /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 + 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 and that allow (or require) userspace to handle CEC + messages and/or configure the CEC adapter 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-adap-g-state; + &sub-cec-ioc-adap-g-vendor-id; + &sub-cec-ioc-adap-log-status; + &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 0000000..c3978af --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-func-close.xml @@ -0,0 +1,59 @@ + + + cec close() + &manvol; + + + + cec-close + Close a cec device + + + + + #include <unistd.h> + + int close + int fd + + + + + + Arguments + + + + fd + + &fd; + + + + + + + Description + + 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 0000000..0480eeb --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-func-ioctl.xml @@ -0,0 +1,73 @@ + + + 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 + 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 0000000..d814847 --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-func-open.xml @@ -0,0 +1,94 @@ + + + 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 either O_RDONLY + or O_RDWR. Other flags have no effect. + + + + + + Description + 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 are: + + + + 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 0000000..6853817 --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-func-poll.xml @@ -0,0 +1,89 @@ + + + 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 + + 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 0000000..0f266e0 --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-caps.xml @@ -0,0 +1,174 @@ + + + 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 + + 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 . + + + __u8 + ninputs + The number of HDMI inputs of this CEC adapter. This may be + 0 if there are no inputs. + + + __u8 + reserved[39] + Reserved for future extensions. Drivers must + set this array to zero. + + + +
+ + + CEC Capabilities Flags + + &cs-def; + + + CEC_CAP_STATE + 0x00000001 + Userspace has to configure the adapter state (enable or disable it) by + calling &CEC-ADAP-S-STATE;. + + + CEC_CAP_PHYS_ADDR + 0x00000002 + Userspace has to configure the physical address by + calling &CEC-ADAP-S-PHYS-ADDR;. + + + CEC_CAP_LOG_ADDRS + 0x00000004 + Userspace has to configure the logical addresses by + calling &CEC-ADAP-S-LOG-ADDRS;. + + + CEC_CAP_TRANSMIT + 0x00000008 + 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. + + + + CEC_CAP_VENDOR_ID + 0x00000010 + Userspace has to configure the vendor ID by + calling &CEC-ADAP-S-VENDOR-ID;. + + + CEC_CAP_PASSTHROUGH + 0x00000020 + Userspace can use the passthrough mode by + calling &CEC-S-MODE;. + + + CEC_CAP_RC + 0x00000040 + This adapter supports the remote control protocol. + + + CEC_CAP_ARC + 0x00000080 + This adapter supports the Audio Return Channel protocol. + + + CEC_CAP_CDC_HPD + 0x00000100 + This adapter supports the hotplug detect protocol over CDC. + + + CEC_CAP_IS_SOURCE + 0x00000200 + This CEC adapter is an HDMI source, &ie; it has an HDMI output + connector. + + + CEC_CAP_MONITOR_ALL + 0x00000400 + 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 0000000..4ae0cb8 --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-log-addrs.xml @@ -0,0 +1,306 @@ + + + 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 + + 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. 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 + 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. + + + __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 + 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. + + + char + osd_name[15] + The On-Screen Display name as is returned by the + CEC_MSG_SET_OSD_NAME message. + + + __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. + + + __u8 + reserved[63] + Reserved for future extensions. Drivers and applications must + set this array to zero. + + + +
+ + + 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 + Fallback if all relevant logical addresses are claimed, or 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 0000000..5f03bf9 --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-phys-addr.xml @@ -0,0 +1,81 @@ + + + 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 + + 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. The physical address +can only be set if the state of the CEC adapter is disabled (&CEC-ADAP-G-STATE; +returns CEC_ADAP_DISABLED). CEC_ADAP_S_PHYS_ADDR +can only be called by a file handle in initiator mode (see &CEC-S-MODE;). + + 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-adap-g-state.xml b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-state.xml new file mode 100644 index 0000000..c68b428 --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-state.xml @@ -0,0 +1,88 @@ + + + ioctl CEC_ADAP_G_STATE, CEC_ADAP_S_STATE + &manvol; + + + + CEC_ADAP_G_STATE + CEC_ADAP_S_STATE + Get or set the adapter state + + + + + + int ioctl + int fd + int request + __u32 *argp + + + + + + Arguments + + + + fd + + File descriptor returned by + open(). + + + + request + + CEC_ADAP_G_STATE, CEC_ADAP_S_STATE + + + + argp + + + + + + + + + Description + + To query the current adapter state applications call the +CEC_ADAP_G_STATE ioctl with a pointer to an __u32 +where the driver stores the state. + + To set the adapter state applications store the CEC adapter state +in an __u32 and call the CEC_ADAP_S_STATE ioctl with a +pointer to this integer. CEC_ADAP_S_STATE is only +available if CEC_CAP_STATE is set. CEC_ADAP_S_STATE +can only be called by a file handle in initiator mode (see &CEC-S-MODE;). + + Available states are: + + + Adapter States + + &cs-def; + + + CEC_ADAP_DISABLED + 0 + The adapter is disabled. + + + CEC_ADAP_ENABLED + 1 + The adapter is enabled. + + + +
+ + + + &return-value; + + diff --git a/Documentation/DocBook/media/v4l/cec-ioc-adap-g-vendor-id.xml b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-vendor-id.xml new file mode 100644 index 0000000..fff3233 --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-vendor-id.xml @@ -0,0 +1,71 @@ + + + ioctl CEC_ADAP_G_VENDOR_ID, CEC_ADAP_S_VENDOR_ID + &manvol; + + + + CEC_ADAP_G_VENDOR_ID + CEC_ADAP_S_VENDOR_ID + Get or set adapter vendor ID + + + + + + int ioctl + int fd + int request + __u32 *argp + + + + + + Arguments + + + + fd + + File descriptor returned by + open(). + + + + request + + CEC_ADAP_G_VENDOR_ID, CEC_ADAP_S_VENDOR_ID + + + + argp + + + + + + + + + Description + + To query the current CEC adapter vendor ID applications call the +CEC_ADAP_G_VENDOR_ID ioctl with a pointer to an __u32 +where the driver stores the vendor ID. + + To set a new CEC adapter vendor ID applications store the vendor ID in +an __u32 and call the CEC_ADAP_S_VENDOR_ID ioctl with a +pointer to this integer. CEC_ADAP_S_VENDOR_ID is only +available if CEC_CAP_VENDOR_ID is set. CEC_ADAP_S_VENDOR_ID +can only be called by a file handle in initiator mode (see &CEC-S-MODE;). + + 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. + + + + &return-value; + + diff --git a/Documentation/DocBook/media/v4l/cec-ioc-adap-log-status.xml b/Documentation/DocBook/media/v4l/cec-ioc-adap-log-status.xml new file mode 100644 index 0000000..c059531 --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-ioc-adap-log-status.xml @@ -0,0 +1,51 @@ + + + ioctl CEC_ADAP_LOG_STATUS + &manvol; + + + + CEC_ADAP_LOG_STATUS + Log CEC adapter status + + + + + + int ioctl + int fd + int request + + + + + + Arguments + + + + fd + + File descriptor returned by + open(). + + + + request + + CEC_ADAP_LOG_STATUS + + + + + + + Description + + When debugging CEC problems it is useful to examine the current +status of the CEC state machine and hardware. When this ioctl is called the +driver will output the current CEC adapter status to the kernel log. + + + + 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 0000000..8f2fc93 --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-ioc-dqevent.xml @@ -0,0 +1,280 @@ + + + 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 + + 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 mean 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; + + + __u8 + state + The state of the CEC adapter, see . + + + +
+ + + struct <structname>cec_event_inputs_change</structname> + + &cs-str; + + + __u16 + connected_inputs + A bitmask that reports which inputs are connected. + If bit X is 1, then HDMI input X is connected. Only the first + ninputs bits (see &CEC-ADAP-G-CAPS;) + are used, the remaining bits are always 0. + + + +
+ + + struct <structname>cec_event_phys_addr_change</structname> + + &cs-str; + + + __u16 + phys_addr + The new physical address. + + + +
+ + + 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. + + + +
+ + + struct <structname>cec_event</structname> + + &cs-str; + + + __u64 + ts + Timestamp of the event in ns. + + + + __u32 + event + The event, see . + + + + __u32 + flags + Event flags, see . + + + + __u32 + reserved[6] + Reserved for future extensions. Drivers must + set this array to zero. + + + + 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_inputs_change + inputs_change + The new set of connected inputs as sent by the CEC_EVENT_INPUTS_CHANGE + event. + + + + struct cec_event_phys_addr_change + phys_addr_change + The new physical address as sent by the CEC_EVENT_PHYS_ADDR_CHANGE + event. + + + + struct cec_event_lost_msgs + lost_msgs + The number of lost messages as sent by the CEC_EVENT_LOST_MSGS + event. + + + +
+ + + CEC Adapter States + + &cs-def; + + + CEC_EVENT_STATE_DISABLED + 0 + The CEC adapter is disabled. + + + CEC_EVENT_STATE_UNCONFIGURED + 1 + The CEC adapter is enabled, but is unconfigured. + + + CEC_EVENT_STATE_CONFIGURING + 2 + The CEC adapter is configuring. + + + CEC_EVENT_STATE_CONFIGURED + 3 + The CEC adapter is configured. + + + +
+ + + CEC Events + + &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_INPUTS_CHANGE + 2 + Generated when the connection state of one or more of the HDMI + inputs changes. When open() is called an initial event will be generated + for that filehandle with the CEC Adapter's connection state at that time. + + + CEC_EVENT_PHYS_ADDR_CHANGE + 3 + Generated when the physical address changes. When open() is called + an initial event will be generated for that filehandle with the CEC + Adapter's physical address at that time. + + + CEC_EVENT_LOST_MSGS + 4 + 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 0000000..de348c7 --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-ioc-g-mode.xml @@ -0,0 +1,286 @@ + + + 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 + + By default any filehandle can use &CEC-TRANSMIT; and &CEC-RECEIVE;, but +in order to prevent applications from stepping on each others toes you want to get +exclusive access to the CEC adapter. This ioctl allows you to try and become the +exclusive initiator and/or follower. 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 our 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. In that +case the follower will have to implement those messages. There are some messages +that the core will always process, regardless of the passthrough mode. + + 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 + 0x0 + This is not a follower (the default when the device is opened). + + + CEC_MODE_FOLLOWER + 0x1 + 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 + 0x2 + 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 + 0x3 + 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 + 0xe + 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. + + + CEC_MODE_MONITOR_ALL + 0xf + 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, and depending on the + hardware, you may have to be root to select this mode. + + + +
+ + Core message processing details: + + + Core Message Processing + + &cs-def; + + + CEC_MSG_INITIATE_ARC + + + + CEC_MSG_TERMINATE_ARC + + + + CEC_MSG_REQUEST_ARC_INITIATION + + + + CEC_MSG_REQUEST_ARC_TERMINATION + + + + CEC_MSG_REPORT_ARC_INITIATED + + + + CEC_MSG_REPORT_ARC_TERMINATED + If CEC_CAP_ARC is not set, then just pass + it on to userspace for processing. However, if CEC_CAP_ARC is + set, then the core framework processes this message and userspace will + not see it, not even in passthrough mode. + + + CEC_MSG_CDC_MESSAGE + If CEC_CAP_CDC_HPD is not set, then just pass + it on to userspace for processing. Do the same if the CDC command is not + one of CEC_MSG_CDC_HPD_REPORT_STATE or + CEC_MSG_CDC_HPD_SET_STATE. Else the core framework + processes this message and userspace will not see it, not even in passthrough + mode. + + + 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-VENDOR-ID;. + + + 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_DEVICE_POWER_STATUS + When in passthrough mode this message has to be handled by userspace, + otherwise the core will return the current power status. + + + 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 0000000..43f6c5d --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-ioc-receive.xml @@ -0,0 +1,261 @@ + + + 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 + + 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 we wait for a message to + be received. If it is set to 0, then we wait indefinitely. + It is ignored by CEC_TRANSMIT. + + + __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. + + + + __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, then don't wait for a reply but return after transmitting the + message. If there was an error as indicated by a non-zero status + field, then reply is set to 0 by the driver. + Ignored by CEC_RECEIVE. + + + __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. + + + __u8 + reserved[33] + Reserved for future extensions. Drivers and applications must + set this array to zero. + + + +
+ + + 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 7b77e0f..a2765d8 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;