Re: [PATCHv16 07/13] cec.txt: add CEC framework documentation

[Mauro Carvalho Chehab]

Em Fri, 17 Jun 2016 09:22:05 +0200
Hans Verkuil  escreveu:

> On 06/16/2016 10:12 PM, Mauro Carvalho Chehab wrote:
> > Em Fri, 29 Apr 2016 15:52:22 +0200
> > Hans Verkuil  escreveu:
> >   
> >> From: Hans Verkuil 
> >>
> >> Document the new HDMI CEC framework.  
> > 
> > As we'll be moving documentation to Sphinx/Rst, it would be good if
> > you could make it work fine with sphinx, as this will likely be needed
> > for Kernel 4.9. Right now it most works, although several warnings are
> > produced:   
> 
> Would it be a problem if this conversion is done later in a separate patch?
> 
> I'm all for it, but I don't have the time at the moment to do this.

No problem. This can be done later.

> 
> Regards,
> 
>   Hans
> 
> > 
> > /devel/v4l/patchwork/tmp/cec.txt:40: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:40: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:40: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:40: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:40: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:42: WARNING: Definition list ends without 
> > a blank line; unexpected unindent.
> > /devel/v4l/patchwork/tmp/cec.txt:42: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:67: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:71: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:92: ERROR: Unexpected indentation.
> > /devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:92: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:93: WARNING: Block quote ends without a 
> > blank line; unexpected unindent.
> > /devel/v4l/patchwork/tmp/cec.txt:93: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:93: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:95: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:97: WARNING: Definition list ends without 
> > a blank line; unexpected unindent.
> > /devel/v4l/patchwork/tmp/cec.txt:105: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:105: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:118: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:118: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:130: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:130: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:144: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:144: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:144: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:161: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:161: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:161: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:173: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:194: WARNING: Inline emphasis start-string 
> > without end-string.
> > /devel/v4l/patchwork/tmp/cec.txt:203: WARNING: Inline emphasis start-string 
> > without end-string.
> > 

Re: [PATCHv16 07/13] cec.txt: add CEC framework documentation

[Hans Verkuil]

On 06/16/2016 10:12 PM, Mauro Carvalho Chehab wrote:
> Em Fri, 29 Apr 2016 15:52:22 +0200
> Hans Verkuil  escreveu:
> 
>> From: Hans Verkuil 
>>
>> Document the new HDMI CEC framework.
> 
> As we'll be moving documentation to Sphinx/Rst, it would be good if
> you could make it work fine with sphinx, as this will likely be needed
> for Kernel 4.9. Right now it most works, although several warnings are
> produced: 

Would it be a problem if this conversion is done later in a separate patch?

I'm all for it, but I don't have the time at the moment to do this.

Regards,

Hans

> 
> /devel/v4l/patchwork/tmp/cec.txt:40: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:40: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:40: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:40: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:40: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:42: WARNING: Definition list ends without a 
> blank line; unexpected unindent.
> /devel/v4l/patchwork/tmp/cec.txt:42: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:67: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:71: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:92: ERROR: Unexpected indentation.
> /devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:92: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:93: WARNING: Block quote ends without a 
> blank line; unexpected unindent.
> /devel/v4l/patchwork/tmp/cec.txt:93: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:93: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:95: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:97: WARNING: Definition list ends without a 
> blank line; unexpected unindent.
> /devel/v4l/patchwork/tmp/cec.txt:105: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:105: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:118: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:118: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:130: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:130: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:144: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:144: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:144: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:161: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:161: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:161: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:173: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:194: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:203: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:203: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:214: WARNING: Inline emphasis start-string 
> without end-string.
> /devel/v4l/patchwork/tmp/cec.txt:217: WARNING: Inline emphasis start-string 
> without end-string.
> 

Re: [PATCHv16 07/13] cec.txt: add CEC framework documentation

[Mauro Carvalho Chehab]

Em Fri, 29 Apr 2016 15:52:22 +0200
Hans Verkuil  escreveu:

> From: Hans Verkuil 
> 
> Document the new HDMI CEC framework.

As we'll be moving documentation to Sphinx/Rst, it would be good if
you could make it work fine with sphinx, as this will likely be needed
for Kernel 4.9. Right now it most works, although several warnings are
produced: 

/devel/v4l/patchwork/tmp/cec.txt:40: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:40: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:40: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:40: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:40: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:42: WARNING: Definition list ends without a 
blank line; unexpected unindent.
/devel/v4l/patchwork/tmp/cec.txt:42: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:67: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:71: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:92: ERROR: Unexpected indentation.
/devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:87: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:92: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:93: WARNING: Block quote ends without a blank 
line; unexpected unindent.
/devel/v4l/patchwork/tmp/cec.txt:93: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:93: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:95: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:97: WARNING: Definition list ends without a 
blank line; unexpected unindent.
/devel/v4l/patchwork/tmp/cec.txt:105: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:105: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:118: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:118: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:130: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:130: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:144: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:144: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:144: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:161: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:161: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:161: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:173: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:194: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:203: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:203: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:214: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:217: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:217: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:217: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:217: WARNING: Inline emphasis start-string 
without end-string.
/devel/v4l/patchwork/tmp/cec.txt:219: WARNING: Definition list ends without a 
blank line; unexpected unindent.
/devel/v4l/patchwork/tmp/cec.txt:224: WARNING: 

[PATCHv16 07/13] cec.txt: add CEC framework documentation

[Hans Verkuil]

From: Hans Verkuil 

Document the new HDMI CEC framework.

Signed-off-by: Hans Verkuil 
[k.deb...@samsung.com: add DocBook documentation by Hans Verkuil, with
Signed-off-by: Kamil Debski 
Signed-off-by: Hans Verkuil 
---
 Documentation/cec.txt | 267 ++
 1 file changed, 267 insertions(+)
 create mode 100644 Documentation/cec.txt

diff --git a/Documentation/cec.txt b/Documentation/cec.txt
new file mode 100644
index 000..75155fe
--- /dev/null
+++ b/Documentation/cec.txt
@@ -0,0 +1,267 @@
+CEC Kernel Support
+==
+
+The CEC framework provides a unified kernel interface for use with HDMI CEC
+hardware. It is designed to handle a multiple types of hardware (receivers,
+transmitters, USB dongles). The framework also gives the option to decide
+what to do in the kernel driver and what should be handled by userspace
+applications. In addition it integrates the remote control passthrough
+feature into the kernel's remote control framework.
+
+
+The CEC Protocol
+
+
+The CEC protocol enables consumer electronic devices to communicate with each
+other through the HDMI connection. The protocol uses logical addresses in the
+communication. The logical address is strictly connected with the functionality
+provided by the device. The TV acting as the communication hub is always
+assigned address 0. The physical address is determined by the physical
+connection between devices.
+
+The CEC framework described here is up to date with the CEC 2.0 specification.
+It is documented in the HDMI 1.4 specification with the new 2.0 bits documented
+in the HDMI 2.0 specification. But for most of the features the freely 
available
+HDMI 1.3a specification is sufficient:
+
+http://www.microprocessor.org/HDMISpecification13a.pdf
+
+
+The Kernel Interface
+
+
+CEC Adapter
+---
+
+The struct cec_adapter represents the CEC adapter hardware. It is created by
+calling cec_allocate_adapter() and deleted by calling cec_delete_adapter():
+
+struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops,
+  void *priv, const char *name, u32 caps, u8 available_las,
+  struct device *parent);
+void cec_delete_adapter(struct cec_adapter *adap);
+
+To create an adapter you need to pass the following information:
+
+ops: adapter operations which are called by the CEC framework and that you
+have to implement.
+
+priv: will be stored in adap->priv and can be used by the adapter ops.
+
+name: the name of the CEC adapter. Note: this name will be copied.
+
+caps: capabilities of the CEC adapter. These capabilities determine the
+   capabilities of the hardware and which parts are to be handled
+   by userspace and which parts are handled by kernelspace. The
+   capabilities are returned by CEC_ADAP_G_CAPS.
+
+available_las: the number of simultaneous logical addresses that this
+   adapter can handle. Must be 1 <= available_las <= CEC_MAX_LOG_ADDRS.
+
+parent: the parent device.
+
+
+To register the /dev/cecX device node and the remote control device (if
+CEC_CAP_RC is set) you call:
+
+int cec_register_adapter(struct cec_adapter *adap);
+
+To unregister the devices call:
+
+void cec_unregister_adapter(struct cec_adapter *adap);
+
+Note: if cec_register_adapter() fails, then call cec_delete_adapter() to
+clean up. But if cec_register_adapter() succeeded, then only call
+cec_unregister_adapter() to clean up, never cec_delete_adapter(). The
+unregister function will delete the adapter automatically once the last user
+of that /dev/cecX device has closed its file handle.
+
+
+Implementing the Low-Level CEC Adapter
+--
+
+The following low-level adapter operations have to be implemented in
+your driver:
+
+struct cec_adap_ops {
+   /* Low-level callbacks */
+   int (*adap_enable)(struct cec_adapter *adap, bool enable);
+   int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable);
+   int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr);
+   int (*adap_transmit)(struct cec_adapter *adap, u8 attempts,
+u32 signal_free_time, struct cec_msg *msg);
+   void (*adap_log_status)(struct cec_adapter *adap);
+
+   /* High-level callbacks */
+   ...
+};
+
+The three low-level ops deal with various aspects of controlling the CEC 
adapter
+hardware:
+
+
+To enable/disable the hardware:
+
+   int (*adap_enable)(struct cec_adapter *adap, bool enable);
+
+This callback enables or disables the CEC hardware. Enabling the CEC hardware
+means powering it up in a state where no logical addresses are claimed. This
+op assumes that the physical address (adap->phys_addr) is valid when enable is
+true and will not change while the CEC adapter remains enabled. The initial
+state of the CEC adapter after calling