HDMI-CEC proposal, ver 2

Hi

This is an updated version of the proposal for adding an api for HDMI-CEC to V4L2. Main difference is the support of AV.link EN 50157-2-[123]. (thanks to Daniel Glöckner)

Author: Martin Bugge <[email protected]>
Date: Fri, 11th of March 2010
=============================

This is a proposal for adding a Consumer Electronic Control (CEC) API to V4L2. This document describes the changes and new ioctls needed.

Version 1.
Initial version

Version 2.

          Added support for AV.link EN 50157-2-[123].

Background
==========
CEC is a protocol that provides high-level control functions between various audiovisual products. It is an optional supplement to the High-Definition Multimedia Interface Specification (HDMI).

In short: CEC uses pin 13 on the HDMI connector to transmit and receive small data-packets
(maximum 16 bytes including a 1 byte header) at low data
rates (~400 bits/s).

A CEC device may have any of 15 logical addresses (0 - 14). (address 15 is broadcast and some addresses are reserved)

Physical layer is a one-wire bidirectional serial bus that uses the industry-standard AV.link, see [3].
Due to this the proposed ioctls and events are meant to cover expansion for the protocols in [3].

References
==========
[1] High-Definition Multimedia Interface Specification version 1.3a, Supplement 1 Consumer Electronic Control (CEC).
http://www.hdmi.org/manufacturer/specification.aspx

[2] http://www.hdmi.org/pdf/whitepaper/DesigningCECintoYourNextHDMIProduct.pdf

[3] Domestic and similar electronic equipment interconnection requirements

    AV.link. EN 50157-2-[123]

Proposed solution
=================

Two new ioctls:
VIDIOC_AV_LINK_CAP (read)
VIDIOC_AV_LINK_CMD (read/write)

VIDIOC_AV_LINK_CAP:
-------------------------------

#define AV_LINK_CAP_MODE_CEC (1 << 0)

#define AV_LINK_CAP_MODE_1   (1 << 1)
#define AV_LINK_CAP_MODE_2   (1 << 2)
#define AV_LINK_CAP_MODE_3   (1 << 3)

struct vl2_av_link_cap {
       __u32 capabilities;
       __u32 logicaldevices;
       __u32 reserved[14];
};

The capabilities field will indicate which protocols/formats this HW supports.

* AV link mode CEC:

     logicaldevices: 1 -> 14, this HW supports n logical devices 

simultaneously.

* AV link mode 1:
logicaldevices: not used.

* AV link mode 2:
Same as AV link mode CEC.

* AV link mode 3:
logicaldevices: not used.

reserved: for future use.

VIDIOC_AV_LINK_CMD:
-------------------
The command ioctl is used both for configuration and to receive/transmit data.

/* mode 1 */

struct avl_mode1_conf {
       __u32 enable;
       __u32 upstream_Qty;
       __u32 downstream_Qty;
};
struct avl_mode1 {
       __u32 head;
       __u32 Qty;
       __u32 tx_status;
       __u32 tx_status_Qty;
};

/* mode 2, 3 and CEC */

struct avl_conf {
        __u32 enable;
        __u32 index;
        __u32 addr;
};
struct avl {
       __u32 len;
       __u8  msg[16];
       __u32 tx_status;
};

struct v4l2_av_link_cmd {
    __u32 command;
    __u32 mode;
    __u32 reserved[2];
    union {
        struct avl_mode1_conf avlm1_conf;
        struct avl_mode1 avlm1;
        struct avl_conf conf;
        struct avl avl;
        __u32 raw[12];
    };
};

/* command */
#define V4L2_AV_LINK_CMD_CONF (1)
#define V4L2_AV_LINK_CMD_TX (2)
#define V4L2_AV_LINK_CMD_RX (3)

/* mode */
#define AV_LINK_CMD_MODE_CEC (1)

#define AV_LINK_CMD_MODE_1   (2)
#define AV_LINK_CMD_MODE_2   (3)
#define AV_LINK_CMD_MODE_3   (4)

/* Tx status */

#define V4L2_AV_LINK_STAT_TX_OK                 (0)
#define V4L2_AV_LINK_STAT_TX_ARB_LOST           (1)
#define V4L2_AV_LINK_STAT_TX_RETRY_TIMEOUT      (2)
#define V4L2_AV_LINK_STAT_TX_BROADCAST_REJECT   (3)

Not every tx status is applicable for all modes, see table 1.

|-----------------------------------------------------|
|    Av link Mode     |  CEC  |   1   |   2   |   3   |
|-----------------------------------------------------|
|      Status         |       |       |       |       |
|-----------------------------------------------------|
|      TX_OK          |   a   |  n/a  |   a   |  n/a  |
|-----------------------------------------------------|
|  TX_ARB_LOST        |   a   |  n/a  |   a   |   a   |
|-----------------------------------------------------|
| TX_RETRY_TIMEOUT    |   a   |  n/a  |   a   |   a   |
|-----------------------------------------------------|
| TX_BROADCAST_REJECT |   a   |  n/a  |   a   |  n/a  |
|-----------------------------------------------------|

Table 1: tx status versus mode.
a: applicable
n/a: not applicable

Configuration command:
----------------------

* AV link mode CEC:
Must be done for each logical device address which is to be enabled on this HW. Maximum number of logical devices is found with the capability ioctl.
conf:
index: 0 -> number_of_logical_devices-1
enable: true/false
addr: logical address

* AV link mode 1:
In mode 1 the frame length is fixed to 21 bits (including the
start sequence).
Some of these bits (Qty 1 - 6) can be arbitrated by the receiver
to signal

     supported formats/standards.
     conf:
         enable: true/false
         upstream_Qty: QTY bits 1-6
         downstream_Qty: QTY bits 1-6
             |------------------------------------------------|
             | Bits:     | 31 - 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
             |------------------------------------------------|
             | Qty bits  |   x    | x | 6 | 5 | 4 | 3 | 2 | 1 |
             |------------------------------------------------|
             Qty bits 1-6 mapping (x: not used)

* AV link mode 2:
Same as AV link mode CEC.

* AV link mode 3: TBD. Chances are that nobody ever used this conf:
index: 0 (not used)
enable: true/false
addr: 0 (not used)

Tx/Rx command:
--------------

* AV link mode CEC:
len: length of message in bytes (data + header).
msg: the raw message received/transmitted.
tx_status: tx status in blocking mode.

* AV link mode 1:

     Frame received/transmitted:
     head:
         |-------------------------------------------------|
         | Bits:       | 31 - 4 |  3  |   2  |   1  |  0   |
         |-------------------------------------------------|
         | head bits:  |    x   | DIR | /PAS | /NAS | /DES |
         |-------------------------------------------------|
     Qty: Quality bits 1 - 16;
         |---------------------------------------|
         | Bits:     | 31 - 16 | 15 | 14 - 1 | 0 |
         |---------------------------------------|
         | Qty bits  |    x    | 16 | 15 - 2 | 1 |
         |---------------------------------------|
         x: not used

     In blocking mode only:
        tx_status: tx status.
        tx_status_Qty: which Qty bits 1 - 6 bits was arbitrated during 

transmit.

* AV link mode 2:
len: length of message in bytes (data + command block).
msg: the raw message received/transmitted (without the start
sequence).
tx_status: tx status in blocking mode.

* AV link mode 3: TBD. Chances are that nobody ever used this
len: length of message in bits, maximum 96 bits.
msg: the raw message received/transmitted. (without the start
sequence).
tx_status: tx status in blocking mode.

Events
------

In the case of non-blocking mode the driver will issue the following events:

V4L2_EVENT_AV_LINK_TX
V4L2_EVENT_AV_LINK_RX

V4L2_EVENT_AV_LINK_TX
-----------------
* transmit is complete with the following status:
Add an additional struct to the struct v4l2_event

struct v4l2_event_av_link_tx {
       __u32 status;
       __u32 tx_status_mode1_Qty;
};

* The status field is the same as in blocking mode described above.
* tx_status_mode1_Qty apply only to mode 1.

V4L2_EVENT_AV_LINK_RX
-----------------
* received a complete message
Use the VIDIOC_AV_LINK_CMD to read the message.

Comments ?

Martin Bugge

--
Martin Bugge - Tandberg (now a part of Cisco)
--

Hi Martin,

TX_ARB_LOST is applicable to mode 1.
Arbitration loss will also be caused by receivers detecting a bad pulse.

If the Linux system is a video source, it must stop arbitrating those Qty bits as soon as another video source wants to become active. As this includes the message where the new source announces itself, this can't be handled by reconfiguration after reception of the message.

If the Linux system is a video sink, the announcement of a new source should not affect the Qty bits to arbitrate.

And don't get me startet about systems capable of being a video source and sink at the same time, capturing their own signal until a new source becomes active...

Is Qty-1 or Qty-16 the bit sent after /DES?

It may be interesting to know what other devices did to the /PAS and /DES bits when they were sent as 1.

Google turned up this:
http://fmt.cs.utwente.nl/publications/files/111_heerink.pdf
It suggests that at least Philips' variant of AV.link mode 3 - EasyLink - is even closer to CEC than mode 2.

Daniel

Hi Daniel and thank you,

You are correct, a typo.
However, it looks like also TX_OK will be used for Mode 3. And maybe also TX_BROADCAST_REJECT.
In particular with reference to your link in below.

I assume this must be handled by logic in the driver if it supports this mode.

Even though I find it a bit confusing in the standard, the plan was to send Qty-1 just after the /DES bit.

It was an attempt to make the configuration and status the same. Such that we could use the same bit masks.

Maybe I should change this such that we actually send up the whole frame as tx_status. In that way we will avoid the confusion of the Qty bit orders also.

But then this should apply to the configuration as well.

Yes I see that. However CEC don't have the start sequence (to differenciate between mode 1 - 3), and the application id.
In addition can't I see that mode 3 describe the ACK and EOM bits.
It might be difficult to "force" easylink into the mode 3 as it is.

If we could use the application id it might be possible for the driver to change behaviour.

Or we will end up with
#define AV_LINK_CAP_MODE_EASY_LINK (1 << 4)
And so on, which might be ok also.

Martin