Commit e2460b1d authored by Markus Heiser's avatar Markus Heiser Committed by Mauro Carvalho Chehab
Browse files

[media] doc-rst: linux_tv CEC part, DocBook to reST migration 

This is the reST migration of media's CEC part.  The migration is based
on media_tree's cec branch:

 https://git.linuxtv.org/media_tree.git



 c7169ad5 * cec media_tree/cec [media] DocBook/media: add CEC documentation

Signed-off-by: default avatarMarkus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
parent 4606ce43

Documentation/media/media_uapi.rst

+8 −5
Original line number Diff line number Diff line
@@ -37,21 +37,23 @@ A typical media device hardware is shown at 
    Typical Media Device



The media infrastructure API was designed to control such devices. It is

divided into four parts.

divided into five parts.



The :Ref:`first part <v4l2spec>` covers radio, video capture and output,

The :ref:`first part <v4l2spec>` covers radio, video capture and output,

cameras, analog TV devices and codecs.



The :Ref:`second part <dvbapi>` covers the API used for digital TV and

The :ref:`second part <dvbapi>` 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,

DTMB, etc. The complete list of supported standards can be found at

:ref:`fe-delivery-system-t`.



The :Ref:`third part <remote_controllers>` covers the Remote Controller API.

The :ref:`third part <remote_controllers>` covers the Remote Controller API.



The :Ref:`fourth part <media_controller>` covers the Media Controller API.

The :ref:`fourth part <media_controller>` covers the Media Controller API.



The :ref:`fifth part <cec>` 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
@@ -72,6 +74,7 @@ etc, please mail to: 
    uapi/dvb/dvbapi

    uapi/rc/remote_controllers

    uapi/mediactl/media-controller

    uapi/cec/cec-api

    uapi/gen-errors

    uapi/fdl-appendix

Documentation/media/uapi/cec/cec-api.rst

0 → 100644
+94 −0
Original line number Diff line number Diff line 
.. -*- coding: utf-8; mode: rst -*-



.. _cec:



#######

CEC API

#######



.. _cec-api:



*********************************

CEC: Consumer Electronics Control

*********************************





.. _cec-intro:



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 (:ref:`hdmi`) specification and the

extensions added to CEC version 2.0 are defined in chapter 11 of the

HDMI 2.0 (:ref:`hdmi2`) 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

:ref:`CEC_ADAP_G_CAPS <cec-ioc-adap-g-caps>` ioctl will tell

userspace what it is allowed to do.





.. _cec-user-func:



******************

Function Reference

******************





.. toctree::

    :maxdepth: 1



    cec-func-open

    cec-func-close

    cec-func-ioctl

    cec-func-poll

    cec-ioc-adap-g-caps

    cec-ioc-adap-g-log-addrs

    cec-ioc-adap-g-phys-addr

    cec-ioc-dqevent

    cec-ioc-g-mode

    cec-ioc-receive





**********************

Revision and Copyright

**********************





:author:    Verkuil Hans

:address:   hans.verkuil@cisco.com

:contrib:   Initial version.



**Copyright** 2016 : Hans Verkuil



:revision: 1.0.0 / 2016-03-17 (*hv*)



Initial revision





.. ------------------------------------------------------------------------------

.. This file was automatically converted from DocBook-XML with the dbxml

.. library (https://github.com/return42/sphkerneldoc). The origin XML comes

.. from the linux kernel, refer to:

..

.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook

.. ------------------------------------------------------------------------------

Documentation/media/uapi/cec/cec-func-close.rst

0 → 100644
+57 −0
Original line number Diff line number Diff line 
.. -*- coding: utf-8; mode: rst -*-



.. _cec-func-close:



***********

cec close()

***********



*man cec-close(2)*



Close a cec device





Synopsis

========



.. code-block:: c



    #include <unistd.h>





.. c:function:: int close( int fd )



Arguments

=========



``fd``

    File descriptor returned by :ref:`open() <func-open>`.





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

============



:c:func:`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.





.. ------------------------------------------------------------------------------

.. This file was automatically converted from DocBook-XML with the dbxml

.. library (https://github.com/return42/sphkerneldoc). The origin XML comes

.. from the linux kernel, refer to:

..

.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook

.. ------------------------------------------------------------------------------

Documentation/media/uapi/cec/cec-func-ioctl.rst

0 → 100644
+77 −0
Original line number Diff line number Diff line 
.. -*- coding: utf-8; mode: rst -*-



.. _cec-func-ioctl:



***********

cec ioctl()

***********



*man cec-ioctl(2)*



Control a cec device





Synopsis

========



.. code-block:: c



    #include <sys/ioctl.h>





.. c:function:: int ioctl( int fd, int request, void *argp )



Arguments

=========



``fd``

    File descriptor returned by :ref:`open() <func-open>`.



``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 :c:func:`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

:ref:`cec-user-func`.





Return Value

============



On success 0 is returned, on error -1 and the ``errno`` variable is set

appropriately. The generic error codes are described at the

:ref:`Generic Error Codes <gen-errors>` chapter.



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.





.. ------------------------------------------------------------------------------

.. This file was automatically converted from DocBook-XML with the dbxml

.. library (https://github.com/return42/sphkerneldoc). The origin XML comes

.. from the linux kernel, refer to:

..

.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook

.. ------------------------------------------------------------------------------

Documentation/media/uapi/cec/cec-func-open.rst

0 → 100644
+88 −0
Original line number Diff line number Diff line 
.. -*- coding: utf-8; mode: rst -*-



.. _cec-func-open:



**********

cec open()

**********



*man cec-open(2)*



Open a cec device





Synopsis

========



.. code-block:: c



    #include <fcntl.h>





.. c:function:: 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

    :ref:`CEC_RECEIVE <cec-ioc-receive>` ioctl will return EAGAIN

    error code when no message is available, and the

    :ref:`CEC_TRANSMIT <cec-ioc-receive>`,

    :ref:`CEC_ADAP_S_PHYS_ADDR <cec-ioc-adap-g-phys-addr>` and

    :ref:`CEC_ADAP_S_LOG_ADDRS <cec-ioc-adap-g-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 :c:func:`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

============



:c:func:`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.





.. ------------------------------------------------------------------------------

.. This file was automatically converted from DocBook-XML with the dbxml

.. library (https://github.com/return42/sphkerneldoc). The origin XML comes

.. from the linux kernel, refer to:

..

.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook

.. ------------------------------------------------------------------------------