[PATCH 1/2] media: cec-pin.h: convert comments for cec_pin_state into kernel-doc

[PATCH 1/2] media: cec-pin.h: convert comments for cec_pin_state into kernel-doc

[Mauro Carvalho Chehab]

This enum is already documented, but it is not using a kernel-doc
format. Convert its format, in order to produce documentation.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 include/media/cec-pin.h | 81 +++++++++++++++++++++++++++++++------------------
 1 file changed, 52 insertions(+), 29 deletions(-)

diff --git a/include/media/cec-pin.h b/include/media/cec-pin.h
index f09cc9579d53..3ac0e12ab237 100644
--- a/include/media/cec-pin.h
+++ b/include/media/cec-pin.h
@@ -24,65 +24,88 @@
 #include <linux/atomic.h>
 #include <media/cec.h>
 
+/**
+ * enum cec_pin_state - state of CEC pins
+ * @CEC_ST_OFF:
+ *	CEC is off
+ * @CEC_ST_IDLE:
+ *	CEC is idle, waiting for Rx or Tx
+ * @CEC_ST_TX_WAIT:
+ *	Pending Tx, waiting for Signal Free Time to expire
+ * @CEC_ST_TX_WAIT_FOR_HIGH:
+ *	Low-drive was detected, wait for bus to go high
+ * @CEC_ST_TX_START_BIT_LOW:
+ *	Drive CEC low for the start bit
+ * @CEC_ST_TX_START_BIT_HIGH:
+ *	Drive CEC high for the start bit
+ * @CEC_ST_TX_DATA_BIT_0_LOW:
+ *	Drive CEC low for the 0 bit
+ * @CEC_ST_TX_DATA_BIT_0_HIGH:
+ *	Drive CEC high for the 0 bit
+ * @CEC_ST_TX_DATA_BIT_1_LOW:
+ *	Drive CEC low for the 1 bit
+ * @CEC_ST_TX_DATA_BIT_1_HIGH:
+ *	Drive CEC high for the 1 bit
+ * @CEC_ST_TX_DATA_BIT_1_HIGH_PRE_SAMPLE:
+ *	Wait for start of sample time to check for Ack bit or first
+ *	four initiator bits to check for Arbitration Lost.
+ * @CEC_ST_TX_DATA_BIT_1_HIGH_POST_SAMPLE:
+ *	Wait for end of bit period after sampling
+ * @CEC_ST_RX_START_BIT_LOW:
+ *	Start bit low detected
+ * @CEC_ST_RX_START_BIT_HIGH:
+ *	Start bit high detected
+ * @CEC_ST_RX_DATA_SAMPLE:
+ *	Wait for bit sample time
+ * @CEC_ST_RX_DATA_POST_SAMPLE:
+ *	Wait for earliest end of bit period after sampling
+ * @CEC_ST_RX_DATA_HIGH:
+ *	Wait for CEC to go high (i.e. end of bit period
+ * @CEC_ST_RX_ACK_LOW:
+ *	Drive CEC low to send 0 Ack bit
+ * @CEC_ST_RX_ACK_LOW_POST:
+ *	End of 0 Ack * @time:	 wait for earliest end of bit period
+ * @CEC_ST_RX_ACK_HIGH_POST:
+ *	Wait for CEC to go high (i.e. end of bit period
+ * @CEC_ST_RX_ACK_FINISH:
+ *	Wait for earliest end of bit period and end of message
+ * @CEC_ST_LOW_DRIVE:
+ *	Start low drive
+ * @CEC_ST_RX_IRQ:
+ *	Monitor pin using interrupts
+ * @CEC_PIN_STATES:
+ *	Total number of pin states
+ */
 enum cec_pin_state {
-	/* CEC is off */
 	CEC_ST_OFF,
-	/* CEC is idle, waiting for Rx or Tx */
 	CEC_ST_IDLE,
 
 	/* Tx states */
-
-	/* Pending Tx, waiting for Signal Free Time to expire */
 	CEC_ST_TX_WAIT,
-	/* Low-drive was detected, wait for bus to go high */
 	CEC_ST_TX_WAIT_FOR_HIGH,
-	/* Drive CEC low for the start bit */
 	CEC_ST_TX_START_BIT_LOW,
-	/* Drive CEC high for the start bit */
 	CEC_ST_TX_START_BIT_HIGH,
-	/* Drive CEC low for the 0 bit */
 	CEC_ST_TX_DATA_BIT_0_LOW,
-	/* Drive CEC high for the 0 bit */
 	CEC_ST_TX_DATA_BIT_0_HIGH,
-	/* Drive CEC low for the 1 bit */
 	CEC_ST_TX_DATA_BIT_1_LOW,
-	/* Drive CEC high for the 1 bit */
 	CEC_ST_TX_DATA_BIT_1_HIGH,
-	/*
-	 * Wait for start of sample time to check for Ack bit or first
-	 * four initiator bits to check for Arbitration Lost.
-	 */
 	CEC_ST_TX_DATA_BIT_1_HIGH_PRE_SAMPLE,
-	/* Wait for end of bit period after sampling */
 	CEC_ST_TX_DATA_BIT_1_HIGH_POST_SAMPLE,
 
 	/* Rx states */
-
-	/* Start bit low detected */
 	CEC_ST_RX_START_BIT_LOW,
-	/* Start bit high detected */
 	CEC_ST_RX_START_BIT_HIGH,
-	/* Wait for bit sample time */
 	CEC_ST_RX_DATA_SAMPLE,
-	/* Wait for earliest end of bit period after sampling */
 	CEC_ST_RX_DATA_POST_SAMPLE,
-	/* Wait for CEC to go high (i.e. end of bit period */
 	CEC_ST_RX_DATA_HIGH,
-	/* Drive CEC low to send 0 Ack bit */
 	CEC_ST_RX_ACK_LOW,
-	/* End of 0 Ack time, wait for earliest end of bit period */
 	CEC_ST_RX_ACK_LOW_POST,
-	/* Wait for CEC to go high (i.e. end of bit period */
 	CEC_ST_RX_ACK_HIGH_POST,
-	/* Wait for earliest end of bit period and end of message */
 	CEC_ST_RX_ACK_FINISH,
 
-	/* Start low drive */
 	CEC_ST_LOW_DRIVE,
-	/* Monitor pin using interrupts */
 	CEC_ST_RX_IRQ,
 
-	/* Total number of pin states */
 	CEC_PIN_STATES
 };
 
-- 
2.13.5

[PATCH 2/2] media: rc-core.rst: add an introduction for RC core

[Mauro Carvalho Chehab]

The RC core does several assumptions, but those aren't documented
anywhere, with could make harder for ones that want to understand
what's there.

So, add an introduction explaining the basic concepts of RC and
how they're related to the RC core implementation.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/rc-core.rst | 77 ++++++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)

diff --git a/Documentation/media/kapi/rc-core.rst b/Documentation/media/kapi/rc-core.rst
index a45895886257..355c8ea3ad9f 100644
--- a/Documentation/media/kapi/rc-core.rst
+++ b/Documentation/media/kapi/rc-core.rst
@@ -4,6 +4,83 @@ Remote Controller devices
 Remote Controller core
 ~~~~~~~~~~~~~~~~~~~~~~
 
+The remote controller core implements infrastructure to receive and send
+remote controller keyboard keystrokes and mouse events.
+
+Every time a key is pressed on a remote controller, a scan code is produced.
+Also, on most hardware, keeping a key pressed for more than a few dozens of
+milliseconds produce a repeat key event. That's somewhat similar to what
+a normal keyboard or mouse is handled internally on Linux\ [#f1]_. So, the
+remote controller core is implemented on the top of the linux input/evdev
+interface.
+
+.. [#f1]
+
+   The main difference is that, on keyboard events, the keyboard controller
+   produces one event for a key press and another one for key release. On
+   infrared-based remote controllers, there's no key release event. Instead,
+   an extra code is produced to indicate key repeats.
+
+However, most of the remote controllers use infrared (IR) to transmit signals.
+As there are several protocols used to modulate infrared signals, one
+important part of the core is dedicated to adjust the driver and the core
+system to support the infrared protocol used by the emitter.
+
+The infrared transmission is done by blinking a infrared emitter using a
+carrier. The carrier can be switched on or off by the IR transmitter
+hardware. When the carrier is switched on, it is called *PULSE*.
+When the carrier is switched off, it is called *SPACE*.
+
+In other words, a typical IR transmission can be thinking on a sequence of
+*PULSE* and *SPACE* events, each with a given duration.
+
+The carrier parameters (frequency, duty cycle) and the intervals for
+*PULSE* and *SPACE* events depend on the protocol.
+For example, the NEC protocol uses a carrier of 38kHz, and transmissions
+start with a 9ms *PULSE* and a 4.5ms SPACE. It then transmits 16 bits of
+scan code, being 8 bits for address (usually it is a fixed number for a
+given remote controller), followed by 8 bits of code. A bit "1" is modulated
+with 560µs *PULSE* followed by 1690µs *SPACE* and a bit "0"  is modulated
+with 560µs *PULSE* followed by 560µs *SPACE*.
+
+At receiver, a simple low-pass filter can be used to convert the received
+signal in a sequence of *PULSE/SPACE* events, filtering out the carrier
+frequency. Due to that, the receiver doesn't care about the carrier's
+actual frequency parameters: all it has to do is to measure the amount
+of time it receives *PULSE/SPACE* events.
+So, a simple IR receiver hardware will just provide a sequence of timings
+for those events to the Kernel. The drivers for hardware with such kind of
+receivers are identified by  ``RC_DRIVER_IR_RAW``, as defined by
+:c:type:`rc_driver_type`\ [#f2]_. Other hardware come with a
+microcontroller that decode the *PULSE/SPACE* sequence and return scan
+codes to the Kernel. Such kind of receivers are identified
+by ``RC_DRIVER_SCANCODE``.
+
+.. [#f2]
+
+   The RC core also supports devices that have just IR emitters,
+   without any receivers. Right now, all such devices work only in
+   raw TX mode. Such kind of hardware is identified as
+   ``RC_DRIVER_IR_RAW_TX``.
+
+When the RC core receives events produced by ``RC_DRIVER_IR_RAW`` IR
+receivers, it needs to decode the IR protocol, in order to obtain the
+corresponding scan code. The protocols supported by the RC core are
+defined at enum :c:type:`rc_proto`.
+
+When the RC code receives a scan code (either directly, by a driver
+of the type ``RC_DRIVER_SCANCODE``, or via its IR decoders), it needs
+to convert into a Linux input event code. This is done via a mapping
+table.
+
+The Kernel has support for mapping tables available on most media
+devices. It also supports loading a table in runtime, via some
+sysfs nodes. See the :ref:`RC userspace API <Remote_controllers_Intro>`
+for more details.
+
+Remote controller data structures and functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 .. kernel-doc:: include/media/rc-core.h
 
 .. kernel-doc:: include/media/rc-map.h
-- 
2.13.5

Re: [PATCH 2/2] media: rc-core.rst: add an introduction for RC core

[Sean Young]

On Sat, Sep 23, 2017 at 04:43:34PM -0300, Mauro Carvalho Chehab wrote:
> The RC core does several assumptions, but those aren't documented
> anywhere, with could make harder for ones that want to understand
> what's there.
> 
> So, add an introduction explaining the basic concepts of RC and
> how they're related to the RC core implementation.

Thanks for that -- I hadn't thought of that, but rc-core does really need
an introduction like this.

Just one minor point below, otherwise:

Acked-by: Sean Young <sean@mess.org>

> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  Documentation/media/kapi/rc-core.rst | 77 ++++++++++++++++++++++++++++++++++++
>  1 file changed, 77 insertions(+)
> 
> diff --git a/Documentation/media/kapi/rc-core.rst b/Documentation/media/kapi/rc-core.rst
> index a45895886257..355c8ea3ad9f 100644
> --- a/Documentation/media/kapi/rc-core.rst
> +++ b/Documentation/media/kapi/rc-core.rst
> @@ -4,6 +4,83 @@ Remote Controller devices
>  Remote Controller core
>  ~~~~~~~~~~~~~~~~~~~~~~
>  
> +The remote controller core implements infrastructure to receive and send
> +remote controller keyboard keystrokes and mouse events.
> +
> +Every time a key is pressed on a remote controller, a scan code is produced.
> +Also, on most hardware, keeping a key pressed for more than a few dozens of
> +milliseconds produce a repeat key event. That's somewhat similar to what
> +a normal keyboard or mouse is handled internally on Linux\ [#f1]_. So, the
> +remote controller core is implemented on the top of the linux input/evdev
> +interface.
> +
> +.. [#f1]
> +
> +   The main difference is that, on keyboard events, the keyboard controller
> +   produces one event for a key press and another one for key release. On
> +   infrared-based remote controllers, there's no key release event. Instead,
> +   an extra code is produced to indicate key repeats.
> +
> +However, most of the remote controllers use infrared (IR) to transmit signals.
> +As there are several protocols used to modulate infrared signals, one
> +important part of the core is dedicated to adjust the driver and the core
> +system to support the infrared protocol used by the emitter.
> +
> +The infrared transmission is done by blinking a infrared emitter using a
> +carrier. The carrier can be switched on or off by the IR transmitter
> +hardware. When the carrier is switched on, it is called *PULSE*.
> +When the carrier is switched off, it is called *SPACE*.
> +
> +In other words, a typical IR transmission can be thinking on a sequence of
> +*PULSE* and *SPACE* events, each with a given duration.

This must be of s/thinking on/thought of as/ or something similar. Maybe
viewed is better?

+In other words, a typical IR transmission can be viewed as a sequence of
+*PULSE* and *SPACE* events, each with a given duration.


> +
> +The carrier parameters (frequency, duty cycle) and the intervals for
> +*PULSE* and *SPACE* events depend on the protocol.
> +For example, the NEC protocol uses a carrier of 38kHz, and transmissions
> +start with a 9ms *PULSE* and a 4.5ms SPACE. It then transmits 16 bits of
> +scan code, being 8 bits for address (usually it is a fixed number for a
> +given remote controller), followed by 8 bits of code. A bit "1" is modulated
> +with 560µs *PULSE* followed by 1690µs *SPACE* and a bit "0"  is modulated
> +with 560µs *PULSE* followed by 560µs *SPACE*.
> +
> +At receiver, a simple low-pass filter can be used to convert the received
> +signal in a sequence of *PULSE/SPACE* events, filtering out the carrier
> +frequency. Due to that, the receiver doesn't care about the carrier's
> +actual frequency parameters: all it has to do is to measure the amount
> +of time it receives *PULSE/SPACE* events.
> +So, a simple IR receiver hardware will just provide a sequence of timings
> +for those events to the Kernel. The drivers for hardware with such kind of
> +receivers are identified by  ``RC_DRIVER_IR_RAW``, as defined by
> +:c:type:`rc_driver_type`\ [#f2]_. Other hardware come with a
> +microcontroller that decode the *PULSE/SPACE* sequence and return scan
> +codes to the Kernel. Such kind of receivers are identified
> +by ``RC_DRIVER_SCANCODE``.
> +
> +.. [#f2]
> +
> +   The RC core also supports devices that have just IR emitters,
> +   without any receivers. Right now, all such devices work only in
> +   raw TX mode. Such kind of hardware is identified as
> +   ``RC_DRIVER_IR_RAW_TX``.
> +
> +When the RC core receives events produced by ``RC_DRIVER_IR_RAW`` IR
> +receivers, it needs to decode the IR protocol, in order to obtain the
> +corresponding scan code. The protocols supported by the RC core are
> +defined at enum :c:type:`rc_proto`.
> +
> +When the RC code receives a scan code (either directly, by a driver
> +of the type ``RC_DRIVER_SCANCODE``, or via its IR decoders), it needs
> +to convert into a Linux input event code. This is done via a mapping
> +table.
> +
> +The Kernel has support for mapping tables available on most media
> +devices. It also supports loading a table in runtime, via some
> +sysfs nodes. See the :ref:`RC userspace API <Remote_controllers_Intro>`
> +for more details.
> +
> +Remote controller data structures and functions
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
>  .. kernel-doc:: include/media/rc-core.h
>  
>  .. kernel-doc:: include/media/rc-map.h
> -- 
> 2.13.5