i2c: designware: Fix the kernel doc description for struct dw_i2c_dev
Subsystems (3)
Andy Shevchenko
reviewerPATCH 1/1 i2c: designware: Fix the kernel doc description for struct dw_i2c_dev
$ scripts/kernel-doc -none drivers/i2c/busses/i2c-designware-core.h warning: Function parameter or member 'rst' not described in 'dw_i2c_dev' warning: Function parameter or member 'get_clk_rate_khz' not described in 'dw_i2c_dev' warning: Function parameter or member 'flags' not described in 'dw_i2c_dev' warning: Function parameter or member 'functionality' not described in 'dw_i2c_dev' warning: Function parameter or member 'master_cfg' not described in 'dw_i2c_dev' warning: Function parameter or member 'set_sda_hold_time' not described in 'dw_i2c_dev' warning: Function parameter or member 'rinfo' not described in 'dw_i2c_dev'
--- drivers/i2c/busses/i2c-designware-core.h | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-)
drivers/i2c/busses/i2c-designware-core.h +9 -4
@@ -191,23 +191,26 @@ struct reset_control;* @cmd_complete: tx completion indicator * @clk: input reference clock * @pclk: clock required to access the registers +* @rst: optional reset for the controller * @slave: represent an I2C slave device +* @get_clk_rate_khz: callback to retrieve IP specific bus speed * @cmd_err: run time hadware error code * @msgs: points to an array of messages currently being transferred * @msgs_num: the number of elements in msgs -* @msg_write_idx: the element index of the current tx message in the msgs -* array +* @msg_write_idx: the element index of the current tx message in the msgs array * @tx_buf_len: the length of the current tx buffer * @tx_buf: the current tx buffer -* @msg_read_idx: the element index of the current rx message in the msgs -* array +* @msg_read_idx: the element index of the current rx message in the msgs array * @rx_buf_len: the length of the current rx buffer * @rx_buf: the current rx buffer * @msg_err: error status of the current transfer * @status: i2c master status, one of STATUS_* * @abort_source: copy of the TX_ABRT_SOURCE register * @irq: interrupt number for the i2c master +* @flags: platform specific flags like type of IO accessors or model * @adapter: i2c subsystem adapter node +* @functionality: I2C_FUNC_* ORed bits to reflect what controller does support +* @master_cfg: configuration for the master device * @slave_cfg: configuration for the slave device * @tx_fifo_depth: depth of the hardware tx fifo * @rx_fifo_depth: depth of the hardware rx fifo
@@ -228,7 +231,9 @@ struct reset_control;* @disable: function to disable the controller * @disable_int: function to disable all interrupts * @init: function to initialize the I2C hardware +* @set_sda_hold_time: callback to retrieve IP specific SDA hold timing * @mode: operation mode - DW_IC_MASTER or DW_IC_SLAVE +* @rinfo: I²C GPIO recovery information * @suspended: set to true if the controller is suspended * * HCNT and LCNT parameters can be used if the platform knows more accurate
Signature · 1 line
2.33.0
Quoted 9 lines · Andy Shevchenko
$ scripts/kernel-doc -none drivers/i2c/busses/i2c-designware-core.h warning: Function parameter or member 'rst' not described in 'dw_i2c_dev' warning: Function parameter or member 'get_clk_rate_khz' not described in 'dw_i2c_dev' warning: Function parameter or member 'flags' not described in 'dw_i2c_dev' warning: Function parameter or member 'functionality' not described in 'dw_i2c_dev' warning: Function parameter or member 'master_cfg' not described in 'dw_i2c_dev' warning: Function parameter or member 'set_sda_hold_time' not described in 'dw_i2c_dev' warning: Function parameter or member 'rinfo' not described in 'dw_i2c_dev'
Quoted 5 lines
Signed-off-by Andy Shevchenko <[email protected]>--- drivers/i2c/busses/i2c-designware-core.h | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-)
Quoted 10 lines · Andy Shevchenko
$ scripts/kernel-doc -none drivers/i2c/busses/i2c-designware-core.h warning: Function parameter or member 'rst' not described in 'dw_i2c_dev' warning: Function parameter or member 'get_clk_rate_khz' not described in 'dw_i2c_dev' warning: Function parameter or member 'flags' not described in 'dw_i2c_dev' warning: Function parameter or member 'functionality' not described in 'dw_i2c_dev' warning: Function parameter or member 'master_cfg' not described in 'dw_i2c_dev' warning: Function parameter or member 'set_sda_hold_time' not described in 'dw_i2c_dev' warning: Function parameter or member 'rinfo' not described in 'dw_i2c_dev'Signed-off-by Andy Shevchenko <[email protected]>
Hi Andy,
Thanks for the kernel-doc fixes.
Quoted 40 lines
--- drivers/i2c/busses/i2c-designware-core.h | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-)drivers/i2c/busses/i2c-designware-core.h +7
-4@@ -191,23 +191,26 @@ struct reset_control;* @cmd_complete: tx completion indicator * @clk: input reference clock * @pclk: clock required to access the registers +* @rst: optional reset for the controller * @slave: represent an I2C slave device +* @get_clk_rate_khz: callback to retrieve IP specific bus speed * @cmd_err: run time hadware error code * @msgs: points to an array of messages currently being transferred * @msgs_num: the number of elements in msgs -* @msg_write_idx: the element index of the current tx message in the msgs -* array +* @msg_write_idx: the element index of the current tx message in the msgs array * @tx_buf_len: the length of the current tx buffer * @tx_buf: the current tx buffer -* @msg_read_idx: the element index of the current rx message in the msgs -* array +* @msg_read_idx: the element index of the current rx message in the msgs array * @rx_buf_len: the length of the current rx buffer * @rx_buf: the current rx buffer * @msg_err: error status of the current transfer * @status: i2c master status, one of STATUS_* * @abort_source: copy of the TX_ABRT_SOURCE register * @irq: interrupt number for the i2c master +* @flags: platform specific flags like type of IO accessors or model * @adapter: i2c subsystem adapter node +* @functionality: I2C_FUNC_* ORed bits to reflect what controller does support +* @master_cfg: configuration for the master device * @slave_cfg: configuration for the slave device * @tx_fifo_depth: depth of the hardware tx fifo * @rx_fifo_depth: depth of the hardware rx fifo
drivers/i2c/busses/i2c-designware-core.h struct reset_control; · line 236
Quoted 6 lines
drivers/i2c/busses/i2c-designware-core.h +2
-0@@ -228,7 +231,9 @@ struct reset_control;* @disable: function to disable the controller * @disable_int: function to disable all interrupts * @init: function to initialize the I2C hardware +* @set_sda_hold_time: callback to retrieve IP specific SDA hold timing * @mode: operation mode - DW_IC_MASTER or DW_IC_SLAVE +* @rinfo: I²C GPIO recovery information
Preferably: "I2C"
like it is in thousands of places in the kernel source tree.
Quoted 4 lines
drivers/i2c/busses/i2c-designware-core.h +0
-0* @suspended: set to true if the controller is suspended * * HCNT and LCNT parameters can be used if the platform knows more accurate
Signature · 1 line
~Randy
Quoted 1 line · Randy Dunlap
On 11/12/21 4:34 AM, Andy Shevchenko wrote:
...
Quoted 3 lines
Quoted 1 line
+ * @rinfo: I²C GPIO recovery information
Preferably: "I2C"
Why?
Quoted 1 line
like it is in thousands of places in the kernel source tree.
UTF-8 has been established for more than a decade. I prefer to use the proper form of the abbreviation (*).
*) Check UM10204.pdf.
Signature · 2 lines
With Best Regards, Andy Shevchenko
Quoted 10 lines · Andy Shevchenko
Quoted 1 line · Randy Dunlap
On 11/12/21 4:34 AM, Andy Shevchenko wrote:
...
Quoted 3 lines
Quoted 1 line
+ * @rinfo: I²C GPIO recovery information
Preferably: "I2C"
Why?
See below vvvvvvvvvvvvvvvvv:
Quoted 8 lines
Quoted 1 line
like it is in thousands of places in the kernel source tree.
UTF-8 has been established for more than a decade. I prefer to use the proper form of the abbreviation (*).
*) Check UM10204.pdf.
Yes, I am aware of what is in the spec.
thanks.
Signature · 1 line
~Randy
Quoted 3 lines · Randy Dunlap
Quoted 2 lines · Andy Shevchenko
Quoted 1 line · Randy Dunlap
On 11/12/21 4:34 AM, Andy Shevchenko wrote:
...
Quoted 8 lines
Quoted 5 lines
Quoted 3 lines
Quoted 1 line
+ * @rinfo: I²C GPIO recovery information
Preferably: "I2C"
Why?
See below vvvvvvvvvvvvvvvvv:
Quoted 1 line
Quoted 1 line
like it is in thousands of places in the kernel source tree.
When is it good point to start following the spec?
Quoted 6 lines
Quoted 4 lines
UTF-8 has been established for more than a decade. I prefer to use the proper form of the abbreviation (*).
*) Check UM10204.pdf.
Yes, I am aware of what is in the spec.
Wolfram, what do you prefer?
Signature · 2 lines
With Best Regards, Andy Shevchenko
Quoted 4 lines
Quoted 2 lines
Yes, I am aware of what is in the spec.
Wolfram, what do you prefer?
I prefer I2C. But it is more a reading habit. I would neither enforce I2C nor I²C.
Randy Dunlap
Acked-byQuoted 22 lines · Randy Dunlap
Quoted 10 lines · Andy Shevchenko
Quoted 1 line · Randy Dunlap
On 11/12/21 4:34 AM, Andy Shevchenko wrote:
...
Quoted 3 lines
Quoted 1 line
+ * @rinfo: I²C GPIO recovery information
Preferably: "I2C"
Why?
See below vvvvvvvvvvvvvvvvv:
Quoted 7 lines
Quoted 1 line
like it is in thousands of places in the kernel source tree.
UTF-8 has been established for more than a decade. I prefer to use the proper form of the abbreviation (*).
*) Check UM10204.pdf.
Quoted 6 lines
Quoted 1 line
Yes, I am aware of what is in the spec.
Wolfram, what do you prefer?
I prefer I2C. But it is more a reading habit. I would neither enforce I2C nor I²C.
OK, let's leave it as Andy sent it then.
Signature · 1 line
~Randy
Quoted 25 lines · Randy Dunlap
Quoted 24 lines · Randy Dunlap
Quoted 10 lines · Andy Shevchenko
Quoted 1 line · Randy Dunlap
On 11/12/21 4:34 AM, Andy Shevchenko wrote:
...
Quoted 3 lines
Quoted 1 line
+ * @rinfo: I²C GPIO recovery information
Preferably: "I2C"
Why?
See below vvvvvvvvvvvvvvvvv:
Quoted 10 lines
Quoted 1 line
like it is in thousands of places in the kernel source tree.
UTF-8 has been established for more than a decade. I prefer to use the proper form of the abbreviation (*).
*) Check UM10204.pdf.
Yes, I am aware of what is in the spec.
Quoted 8 lines
Quoted 4 lines
Wolfram, what do you prefer?
I prefer I2C. But it is more a reading habit. I would neither enforce I2C nor I²C.
OK, let's leave it as Andy sent it then.
Acked-by Randy Dunlap <[email protected]>
Thanks!
Wolfram, can it be applied now or should I resend?
Signature · 2 lines
With Best Regards, Andy Shevchenko
Wolfram Sang
AppliedQuoted 10 lines · Andy Shevchenko
$ scripts/kernel-doc -none drivers/i2c/busses/i2c-designware-core.h warning: Function parameter or member 'rst' not described in 'dw_i2c_dev' warning: Function parameter or member 'get_clk_rate_khz' not described in 'dw_i2c_dev' warning: Function parameter or member 'flags' not described in 'dw_i2c_dev' warning: Function parameter or member 'functionality' not described in 'dw_i2c_dev' warning: Function parameter or member 'master_cfg' not described in 'dw_i2c_dev' warning: Function parameter or member 'set_sda_hold_time' not described in 'dw_i2c_dev' warning: Function parameter or member 'rinfo' not described in 'dw_i2c_dev'Signed-off-by Andy Shevchenko <[email protected]>
Applied to for-next, thanks!