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
