From e92ca73b7057ebdba5ea926f25f51b77b41f6c80 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Wed, 9 Nov 2016 06:00:53 -0200 Subject: [media] cec-core.rst: improve documentation Improve the internal CEC documentation. In particular add a section that specifies that transmit-related interrupts should be processed before receive interrupts. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/cec-core.rst | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/Documentation/media/kapi/cec-core.rst b/Documentation/media/kapi/cec-core.rst index 88c33b53ec13..8a88dd4ce3d4 100644 --- a/Documentation/media/kapi/cec-core.rst +++ b/Documentation/media/kapi/cec-core.rst @@ -106,13 +106,13 @@ your driver: 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); + void (*adap_status)(struct cec_adapter *adap, struct seq_file *file); /* High-level callbacks */ ... }; -The three low-level ops deal with various aspects of controlling the CEC adapter +The five low-level ops deal with various aspects of controlling the CEC adapter hardware: @@ -238,6 +238,18 @@ When a CEC message was received: Speaks for itself. +Implementing the interrupt handler +---------------------------------- + +Typically the CEC hardware provides interrupts that signal when a transmit +finished and whether it was successful or not, and it provides and interrupt +when a CEC message was received. + +The CEC driver should always process the transmit interrupts first before +handling the receive interrupt. The framework expects to see the cec_transmit_done +call before the cec_received_msg call, otherwise it can get confused if the +received message was in reply to the transmitted message. + Implementing the High-Level CEC Adapter --------------------------------------- @@ -247,11 +259,11 @@ CEC protocol driven. The following high-level callbacks are available: .. code-block:: none struct cec_adap_ops { - /\* Low-level callbacks \*/ + /* Low-level callbacks */ ... - /\* High-level CEC message callback \*/ - int (\*received)(struct cec_adapter \*adap, struct cec_msg \*msg); + /* High-level CEC message callback */ + int (*received)(struct cec_adapter *adap, struct cec_msg *msg); }; The received() callback allows the driver to optionally handle a newly @@ -263,7 +275,7 @@ received CEC message If the driver wants to process a CEC message, then it can implement this callback. If it doesn't want to handle this message, then it should return -ENOMSG, otherwise the CEC framework assumes it processed this message and -it will not no anything with it. +it will not do anything with it. CEC framework functions -- cgit v1.2.3