Skip to contentSkip to conversation

i2c: designware: Fix the kernel doc description for struct dw_i2c_dev

PATCH Applied Andy Shevchenko 5 participants 10 messages Nov 12, 2021 – Nov 29, 2021

Subsystems (3)
lore
Share & tools
lore

Andy Shevchenko

author reviewer
#0 lore raw

PATCH 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
index 60a2e750cee9..4b26cba40139 100644
@@ -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
Acked-by on v1 1/1
#1 lore raw
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
---
  drivers/i2c/busses/i2c-designware-core.h | 13 +++++++++----
  1 file changed, 9 insertions(+), 4 deletions(-)
#2 lore raw
In reply to Andy Shevchenko
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'

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
index 60a2e750cee9..4b26cba40139 100644
@@ -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
#3 lore raw
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
#4 lore raw
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
#5 lore raw
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
#6 lore raw
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.

Acked-by
#7 lore raw
In reply to Randy Dunlap
Quoted 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
#8 lore raw
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.

Thanks!
Wolfram, can it be applied now or should I resend?

Signature · 2 lines
With Best Regards,
Andy Shevchenko
Applied
#9 lore raw
In reply to Andy Shevchenko
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'

Applied to for-next, thanks!