summaryrefslogtreecommitdiffstats
path: root/Documentation/driver-api
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab+huawei@kernel.org>2020-09-26 09:08:38 +0200
committerMauro Carvalho Chehab <mchehab+huawei@kernel.org>2020-09-30 18:50:20 +0200
commitc3cfc5f484e05e25bf855126bad949078f3dc590 (patch)
treee9bd99b17c56faa93379ba587a7f2f59153e30e0 /Documentation/driver-api
parent181220d469fe8f8c838d2f9d08fe05529fe6f440 (diff)
downloadlinux-c3cfc5f484e05e25bf855126bad949078f3dc590.tar.bz2
media: cec-core.rst: fix warnings with Sphinx 3.0+
The new C domain code on Sphinx 3 is a lot more pedantic. It only accepts real functions declared as c:function. So, declarations like this are not valid: .. c:function:: int (*adap_enable)(struct cec_adapter *adap, bool enable); Also, no blank lines are allowed after ".. c:function:", and continuation lines should be like: .. c:function: int (void foo, \ int bar); Change the logic there, in order to avoid lots of warnings when built with Sphinx 3.x. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Diffstat (limited to 'Documentation/driver-api')
-rw-r--r--Documentation/driver-api/media/cec-core.rst62
1 files changed, 26 insertions, 36 deletions
diff --git a/Documentation/driver-api/media/cec-core.rst b/Documentation/driver-api/media/cec-core.rst
index 3ce26b7c2b2b..03016eeaf8f4 100644
--- a/Documentation/driver-api/media/cec-core.rst
+++ b/Documentation/driver-api/media/cec-core.rst
@@ -36,8 +36,9 @@ The struct cec_adapter represents the CEC adapter hardware. It is created by
calling cec_allocate_adapter() and deleted by calling cec_delete_adapter():
.. c:function::
- struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops, void *priv,
- const char *name, u32 caps, u8 available_las);
+ struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops, \
+ void *priv, const char *name, \
+ u32 caps, u8 available_las);
.. c:function::
void cec_delete_adapter(struct cec_adapter *adap);
@@ -74,7 +75,8 @@ To register the /dev/cecX device node and the remote control device (if
CEC_CAP_RC is set) you call:
.. c:function::
- int cec_register_adapter(struct cec_adapter *adap, struct device *parent);
+ int cec_register_adapter(struct cec_adapter *adap, \
+ struct device *parent);
where parent is the parent device.
@@ -123,9 +125,8 @@ The seven low-level ops deal with various aspects of controlling the CEC adapter
hardware:
-To enable/disable the hardware:
+To enable/disable the hardware::
-.. c:function::
int (*adap_enable)(struct cec_adapter *adap, bool enable);
This callback enables or disables the CEC hardware. Enabling the CEC hardware
@@ -137,9 +138,8 @@ state of the CEC adapter after calling cec_allocate_adapter() is disabled.
Note that adap_enable must return 0 if enable is false.
-To enable/disable the 'monitor all' mode:
+To enable/disable the 'monitor all' mode::
-.. c:function::
int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable);
If enabled, then the adapter should be put in a mode to also monitor messages
@@ -150,9 +150,8 @@ called if the CEC_CAP_MONITOR_ALL capability is set. This callback is optional
Note that adap_monitor_all_enable must return 0 if enable is false.
-To enable/disable the 'monitor pin' mode:
+To enable/disable the 'monitor pin' mode::
-.. c:function::
int (*adap_monitor_pin_enable)(struct cec_adapter *adap, bool enable);
If enabled, then the adapter should be put in a mode to also monitor CEC pin
@@ -163,9 +162,8 @@ the CEC_CAP_MONITOR_PIN capability is set. This callback is optional
Note that adap_monitor_pin_enable must return 0 if enable is false.
-To program a new logical address:
+To program a new logical address::
-.. c:function::
int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr);
If logical_addr == CEC_LOG_ADDR_INVALID then all programmed logical addresses
@@ -177,9 +175,8 @@ can receive directed messages to that address.
Note that adap_log_addr must return 0 if logical_addr is CEC_LOG_ADDR_INVALID.
-To transmit a new message:
+To transmit a new message::
-.. c:function::
int (*adap_transmit)(struct cec_adapter *adap, u8 attempts,
u32 signal_free_time, struct cec_msg *msg);
@@ -196,17 +193,15 @@ The CEC_FREE_TIME_TO_USEC macro can be used to convert signal_free_time to
microseconds (one data bit period is 2.4 ms).
-To log the current CEC hardware status:
+To log the current CEC hardware status::
-.. c:function::
void (*adap_status)(struct cec_adapter *adap, struct seq_file *file);
This optional callback can be used to show the status of the CEC hardware.
The status is available through debugfs: cat /sys/kernel/debug/cec/cecX/status
-To free any resources when the adapter is deleted:
+To free any resources when the adapter is deleted::
-.. c:function::
void (*adap_free)(struct cec_adapter *adap);
This optional callback can be used to free any resources that might have been
@@ -216,15 +211,14 @@ allocated by the driver. It's called from cec_delete_adapter.
Your adapter driver will also have to react to events (typically interrupt
driven) by calling into the framework in the following situations:
-When a transmit finished (successfully or otherwise):
+When a transmit finished (successfully or otherwise)::
-.. c:function::
- void cec_transmit_done(struct cec_adapter *adap, u8 status, u8 arb_lost_cnt,
- u8 nack_cnt, u8 low_drive_cnt, u8 error_cnt);
+ void cec_transmit_done(struct cec_adapter *adap, u8 status,
+ u8 arb_lost_cnt, u8 nack_cnt, u8 low_drive_cnt,
+ u8 error_cnt);
-or:
+or::
-.. c:function::
void cec_transmit_attempt_done(struct cec_adapter *adap, u8 status);
The status can be one of:
@@ -341,17 +335,15 @@ So this must work:
$ cat einj.txt >error-inj
The first callback is called when this file is read and it should show the
-the current error injection state:
+the current error injection state::
-.. c:function::
int (*error_inj_show)(struct cec_adapter *adap, struct seq_file *sf);
It is recommended that it starts with a comment block with basic usage
information. It returns 0 for success and an error otherwise.
-The second callback will parse commands written to the ``error-inj`` file:
+The second callback will parse commands written to the ``error-inj`` file::
-.. c:function::
bool (*error_inj_parse_line)(struct cec_adapter *adap, char *line);
The ``line`` argument points to the start of the command. Any leading
@@ -382,9 +374,8 @@ CEC protocol driven. The following high-level callbacks are available:
};
The received() callback allows the driver to optionally handle a newly
-received CEC message
+received CEC message::
-.. c:function::
int (*received)(struct cec_adapter *adap, struct cec_msg *msg);
If the driver wants to process a CEC message, then it can implement this
@@ -399,15 +390,14 @@ CEC framework functions
CEC Adapter drivers can call the following CEC framework functions:
.. c:function::
- int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg,
- bool block);
+ int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg, \
+ bool block);
Transmit a CEC message. If block is true, then wait until the message has been
transmitted, otherwise just queue it and return.
.. c:function::
- void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr,
- bool block);
+ void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr, bool block);
Change the physical address. This function will set adap->phys_addr and
send an event if it has changed. If cec_s_log_addrs() has been called and
@@ -422,15 +412,15 @@ to another valid physical address, then this function will first set the
address to CEC_PHYS_ADDR_INVALID before enabling the new physical address.
.. c:function::
- void cec_s_phys_addr_from_edid(struct cec_adapter *adap,
- const struct edid *edid);
+ void cec_s_phys_addr_from_edid(struct cec_adapter *adap, \
+ const struct edid *edid);
A helper function that extracts the physical address from the edid struct
and calls cec_s_phys_addr() with that address, or CEC_PHYS_ADDR_INVALID
if the EDID did not contain a physical address or edid was a NULL pointer.
.. c:function::
- int cec_s_log_addrs(struct cec_adapter *adap,
+ int cec_s_log_addrs(struct cec_adapter *adap, \
struct cec_log_addrs *log_addrs, bool block);
Claim the CEC logical addresses. Should never be called if CEC_CAP_LOG_ADDRS