Re: [PATCH v6 07/11] DocBook/media: add CEC documentation

2015-05-08 Thread Hans Verkuil 
Hi Kamil,

A few more comments about the documentation:

First of all you should add some documentation about what the passthrough mode
actually is. Right now all this says is that you can enable or disable it, but
not what it actually does.

And next I have a few small comments about the timestamp documentation:

> 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 000..cbde320
> --- /dev/null
> +++ b/Documentation/DocBook/media/v4l/cec-ioc-g-event.xml
> @@ -0,0 +1,125 @@

...

> +  
> +Description
> +
> +CEC devices can send asynchronous events. These can be retrieved 
> by calling
> +the CEC_G_EVENT 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;.
> +
> +There can be up to 40 events queued up. If more events are added, 
> then the oldest event will be discarded.
> +
> +
> +  struct cec_event
> +  
> + &cs-str;
> + 
> +   
> + __u64
> + ts
> + Timestamp of the event in ns.

"Timestamp of the event in ns. This is based on the monotonic clock. 
Applications
can access this clock using clock_gettime(2) with clock ID
CLOCK_MONOTONIC. To turn this into a struct 
timespec
use:


struct timespec tmspec;

tmspec.tv_sec = ts / 10;
tmspec.tv_nsec = ts % 10;
"

(I hope the docbook syntax for programlisting is correct)



> 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 000..dbec20a
> --- /dev/null
> +++ b/Documentation/DocBook/media/v4l/cec-ioc-receive.xml
> @@ -0,0 +1,185 @@

...

> +
> +  struct cec_msg
> +  
> + &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.

The same timestamp explanation should be given here.

Regards,

Hans
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v6 07/11] DocBook/media: add CEC documentation

2015-05-04 Thread Kamil Debski 
From: Hans Verkuil 

Add DocBook documentation for the CEC API.

Signed-off-by: Hans Verkuil 
[k.deb...@samsung.com: add documentation for passthrough mode]
[k.deb...@samsung.com: minor fixes and change of reserved field sizes]
Signed-off-by: Kamil Debski 
---
 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 |  173 
 .../DocBook/media/v4l/cec-ioc-g-event.xml  |  125 +
 .../DocBook/media/v4l/cec-ioc-g-passthrough.xml|   88 +++
 .../DocBook/media/v4l/cec-ioc-g-vendor-id.xml  |   70 +
 .../DocBook/media/v4l/cec-ioc-receive.xml  |  185 +
 Documentation/DocBook/media_api.tmpl   |6 +-
 16 files changed, 1487 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-passthrough.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

diff --git a/Documentation/DocBook/media/Makefile 
b/Documentation/DocBook/media/Makefile
index 8bf7c61..9650332 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) \
VIDIOC_SUBDEV_G_FRAME_INTERVAL \
VIDIOC_SUBDEV_S_FRAME_INTERVAL \
@@ -98,6 +99,7 @@ STRUCTS = \
$(shell perl -ne 'print "$$1 " if (/^struct\s+([A-Z][^\s]+)\s+/)' 
$(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)
 
@@ -300,7 +302,7 @@ $(MEDIA_OBJ_DIR)/media-entities.tmpl: 
$(MEDIA_OBJ_DIR)/v4l2.xml
@(  \
for ident in $(IOCTLS) ; do \
  entity=`echo $$ident | tr _ -` ;  \
- id=`grep "$$ident" $(MEDIA_OBJ_DIR)/vidioc-*.xml 
$(MEDIA_OBJ_DIR)/media-ioc-*.xml | sed -r s,"^.*/(.*).xml.*","\1",` ; \
+ id=`grep "$$ident" $(MEDIA_OBJ_DIR)/vidioc-*.xml 
$(MEDIA_OBJ_DIR)/media-ioc-*.xml $(MEDIA_OBJ_DIR)/cec-ioc-*.xml | sed -r 
s,"^.*/(.*).xml.*","\1",` ; \
  echo "$$ident\">" \
  >>$@ ;\
diff --git a/Documentation/DocBook/media/v4l/biblio.xml 
b/Documentation/DocBook/media/v4l/biblio.xml
index fdee6b3..bed940b 100644
--- a/Documentation/DocBook/media/v4l/biblio.xml
+++ b/Documentation/DocBook/media/v4l/biblio.xml
@@ -324,6 +324,16 @@ in the frequency range from 87,5 to 108,0 MHz
   Specification Version 1.4a