[PATCH v5 11/11] DocBook/media: add CEC documentation
Hans Verkuil
hverkuil at xs4all.nl
Sun May 3 03:59:17 PDT 2015
Some comments:
On 04/29/2015 12:02 PM, Kamil Debski wrote:
> From: Hans Verkuil <hverkuil at xs4all.nl>
>
> Add DocBook documentation for the CEC API.
>
> Signed-off-by: Hans Verkuil <hansverk at cisco.com>
> [k.debski at samsung.com: add documentation for passthrough mode]
> [k.debski at samsung.com: minor fixes and change of reserved field sizes]
> Signed-off-by: Kamil Debski <k.debski at samsung.com>
> ---
> Documentation/DocBook/media/Makefile | 4 +-
> Documentation/DocBook/media/v4l/biblio.xml | 10 +
> Documentation/DocBook/media/v4l/cec-api.xml | 74 ++++++
> 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-g-adap-log-addrs.xml | 275 ++++++++++++++++++++
> .../DocBook/media/v4l/cec-ioc-g-adap-phys-addr.xml | 78 ++++++
> .../DocBook/media/v4l/cec-ioc-g-adap-state.xml | 87 +++++++
> Documentation/DocBook/media/v4l/cec-ioc-g-caps.xml | 167 ++++++++++++
> .../DocBook/media/v4l/cec-ioc-g-event.xml | 142 ++++++++++
> .../DocBook/media/v4l/cec-ioc-g-vendor-id.xml | 70 +++++
> .../DocBook/media/v4l/cec-ioc-receive.xml | 185 +++++++++++++
> Documentation/DocBook/media_api.tmpl | 6 +-
> 15 files changed, 1410 insertions(+), 3 deletions(-)
> 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-g-adap-log-addrs.xml
> create mode 100644 Documentation/DocBook/media/v4l/cec-ioc-g-adap-phys-addr.xml
> create mode 100644 Documentation/DocBook/media/v4l/cec-ioc-g-adap-state.xml
> create mode 100644 Documentation/DocBook/media/v4l/cec-ioc-g-caps.xml
> create mode 100644 Documentation/DocBook/media/v4l/cec-ioc-g-event.xml
> create mode 100644 Documentation/DocBook/media/v4l/cec-ioc-g-vendor-id.xml
> create mode 100644 Documentation/DocBook/media/v4l/cec-ioc-receive.xml
>
<snip>
> diff --git a/Documentation/DocBook/media/v4l/cec-ioc-g-caps.xml b/Documentation/DocBook/media/v4l/cec-ioc-g-caps.xml
<snip>
> + <table pgwide="1" frame="none" id="cec-capabilities">
> + <title>CEC Capabilities Flags</title>
> + <tgroup cols="3">
> + &cs-def;
> + <tbody valign="top">
> + <row>
> + <entry><constant>CEC_CAP_STATE</constant></entry>
> + <entry>0x00000001</entry>
> + <entry>Userspace has to configure the adapter state (enable or disable it) by
> + calling &CEC-S-ADAP-STATE;.</entry>
> + </row>
> + <row>
> + <entry><constant>CEC_CAP_PHYS_ADDR</constant></entry>
> + <entry>0x00000002</entry>
> + <entry>Userspace has to configure the physical address by
> + calling &CEC-S-ADAP-PHYS-ADDR;.</entry>
> + </row>
> + <row>
> + <entry><constant>CEC_CAP_LOG_ADDRS</constant></entry>
> + <entry>0x00000004</entry>
> + <entry>Userspace has to configure the logical addresses by
> + calling &CEC-S-ADAP-LOG-ADDRS;.</entry>
> + </row>
> + <row>
> + <entry><constant>CEC_CAP_TRANSMIT</constant></entry>
> + <entry>0x00000008</entry>
> + <entry>Userspace can transmit messages by calling &CEC-TRANSMIT;.</entry>
> + </row>
> + <row>
> + <entry><constant>CEC_CAP_RECEIVE</constant></entry>
> + <entry>0x00000010</entry>
> + <entry>Userspace can receive messages by calling &CEC-RECEIVE;.</entry>
> + </row>
> + <row>
> + <entry><constant>CEC_CAP_VENDOR_ID</constant></entry>
> + <entry>0x00000020</entry>
> + <entry>Userspace has to configure the vendor ID by
> + calling &CEC-S-VENDOR-ID;.</entry>
> + </row>
CAP_PASSTHROUGH is missing here.
> + </tbody>
> + </tgroup>
> + </table>
> + </refsect1>
> +
> + <refsect1>
> + &return-value;
> + </refsect1>
> +</refentry>
> diff --git a/Documentation/DocBook/media/v4l/cec-ioc-g-event.xml b/Documentation/DocBook/media/v4l/cec-ioc-g-event.xml
> new file mode 100644
> index 0000000..2b7e8e9
> --- /dev/null
> +++ b/Documentation/DocBook/media/v4l/cec-ioc-g-event.xml
<snip>
> + <refsect1>
> + <title>Description</title>
> +
> + <para>CEC devices can send asynchronous events. These can be retrieved by calling
> + the <constant>CEC_G_EVENT</constant> 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;.</para>
We should add something like this:
<para>There can be up to 16 events queued up. If more events are added, then the oldest
event will be discarded.</para>
I think we should increase the number of events to 40: given the speed of the bus (or lack
thereof) this should be more than sufficient provided the application will check events
at least once per second. The alternative would be to use a framework like v4l2_event, but
that is IMHO overkill for a bus like this.
<snip>
> + <table pgwide="1" frame="none" id="cec-events">
> + <title>CEC Events</title>
> + <tgroup cols="3">
> + &cs-def;
> + <tbody valign="top">
> + <row>
> + <entry><constant>CEC_EVENT_CONNECT</constant></entry>
> + <entry>1</entry>
> + <entry>Generated when the HDMI cable is connected.</entry>
> + </row>
> + <row>
> + <entry><constant>CEC_EVENT_READY</constant></entry>
> + <entry>2</entry>
> + <entry>Generated when all logical addresses are claimed.</entry>
> + </row>
> + <row>
> + <entry><constant>CEC_EVENT_DISCONNECT</constant></entry>
> + <entry>3</entry>
> + <entry>Generated when the HDMI cable is disconnected.</entry>
> + </row>
> + <row>
> + <entry><constant>CEC_EVENT_GOT_REPLY</constant></entry>
> + <entry>4</entry>
> + <entry>Generated when a prely is received for a previously sent
prely -> reply
> + message. Generated only if a reply was requested and only if the
> + message was sent in non-blocking mode.</entry>
Looking at the code in cec.c, cec_received_msg():
if (!is_reply || (is_reply && !dst_data->blocking))
adap->recv_notifier(adap, msg);
if (is_reply)
cec_post_event(adap, CEC_EVENT_GOT_REPLY, msg->sequence);
}
it seems that the event is posted also if dst_data->blocking is true.
That conflicts with the documentation. I think the code should follow the
documentation.
<snip>
Finally, the passthrough documentation is missing, did you forget to do
'git add'?
Regards,
Hans
More information about the dri-devel
mailing list