Minki/linux
1
0
Fork 1
mirror of https://github.com/torvalds/linux.git synced 2024-12-31 23:31:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

media: cec-core.rst: fix warnings with Sphinx 3.0+

Browse Source 
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>
This commit is contained in:
Mauro Carvalho Chehab 2020-09-26 09:08:38 +02:00
parent 181220d469
commit c3cfc5f484
1 changed files with 26 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
Documentation/driver-api/media/cec-core.rst
View File

@ -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