[PATCH 0/4] platform/chrome: fix kernel-doc warnings

[PATCH 0/4] platform/chrome: fix kernel-doc warnings

[Tzung-Bi Shih]

The series fixes kernel-doc warnings in various places.

All of them can be squashed into 1 fix actually.  However, I think it would
be more clear to separate the first 2 commits as the patches introduced
the warnings are quite new.

For the 3rd patch, I am not sure if it makes sense to have the Fixes tag.
It is a little bit old (~2019).

Tzung-Bi Shih (4):
  platform/chrome: fix kernel-doc warnings for panic notifier
  platform/chrome: fix kernel-doc warning for suspend_timeout_ms
  platform/chrome: fix kernel-doc warning for last_resume_result
  platform/chrome: fix kernel-doc warnings for cros_ec_command

 drivers/platform/chrome/cros_ec_debugfs.c      |  2 ++
 include/linux/platform_data/cros_ec_commands.h |  6 +++---
 include/linux/platform_data/cros_ec_proto.h    | 10 ++++++++++
 3 files changed, 15 insertions(+), 3 deletions(-)

Cc: Rob Barnes <robbarnes@google.com>
Cc: Evan Green <evgreen@chromium.org>

-- 
2.39.0.314.g84b9a713c41-goog

[PATCH 1/4] platform/chrome: fix kernel-doc warnings for panic notifier

[Tzung-Bi Shih]

Fix the following kernel-doc warnings:

$ ./scripts/kernel-doc -none drivers/platform/chrome/*
drivers/platform/chrome/cros_ec_debugfs.c:54: warning: Function
parameter or member 'notifier_panic' not described in 'cros_ec_debugfs'

$ ./scripts/kernel-doc -none include/linux/platform_data/cros_ec_proto.h
include/linux/platform_data/cros_ec_proto.h:187: warning: Function
parameter or member 'panic_notifier' not described in 'cros_ec_device'

Cc: Rob Barnes <robbarnes@google.com>
Fixes: d90fa2c64d59 ("platform/chrome: cros_ec: Poll EC log on EC panic")
Signed-off-by: Tzung-Bi Shih <tzungbi@kernel.org>
---
 drivers/platform/chrome/cros_ec_debugfs.c   | 2 ++
 include/linux/platform_data/cros_ec_proto.h | 1 +
 2 files changed, 3 insertions(+)

diff --git a/drivers/platform/chrome/cros_ec_debugfs.c b/drivers/platform/chrome/cros_ec_debugfs.c
index 34f7b46f8761..a98c529d8c69 100644
--- a/drivers/platform/chrome/cros_ec_debugfs.c
+++ b/drivers/platform/chrome/cros_ec_debugfs.c
@@ -38,6 +38,8 @@ static DECLARE_WAIT_QUEUE_HEAD(cros_ec_debugfs_log_wq);
  * @log_mutex: mutex to protect circular buffer
  * @log_poll_work: recurring task to poll EC for new console log data
  * @panicinfo_blob: panicinfo debugfs blob
+ * @notifier_panic: notifier_block to let kernel to flush buffered log
+ *                  when EC panic
  */
 struct cros_ec_debugfs {
 	struct cros_ec_dev *ec;
diff --git a/include/linux/platform_data/cros_ec_proto.h b/include/linux/platform_data/cros_ec_proto.h
index 017d502ed66e..a4a3fec15504 100644
--- a/include/linux/platform_data/cros_ec_proto.h
+++ b/include/linux/platform_data/cros_ec_proto.h
@@ -140,6 +140,7 @@ struct cros_ec_command {
  *      main EC.
  * @pd: The platform_device used by the mfd driver to interface with the
  *      PD behind an EC.
+ * @panic_notifier: EC panic notifier.
  */
 struct cros_ec_device {
 	/* These are used by other drivers that want to talk to the EC */
-- 
2.39.0.314.g84b9a713c41-goog

Re: [PATCH 1/4] platform/chrome: fix kernel-doc warnings for panic notifier

[Guenter Roeck]

On Tue, Jan 10, 2023 at 9:57 PM Tzung-Bi Shih <tzungbi@kernel.org> wrote:
>
> Fix the following kernel-doc warnings:
>
> $ ./scripts/kernel-doc -none drivers/platform/chrome/*
> drivers/platform/chrome/cros_ec_debugfs.c:54: warning: Function
> parameter or member 'notifier_panic' not described in 'cros_ec_debugfs'
>
> $ ./scripts/kernel-doc -none include/linux/platform_data/cros_ec_proto.h
> include/linux/platform_data/cros_ec_proto.h:187: warning: Function
> parameter or member 'panic_notifier' not described in 'cros_ec_device'
>
> Cc: Rob Barnes <robbarnes@google.com>
> Fixes: d90fa2c64d59 ("platform/chrome: cros_ec: Poll EC log on EC panic")
> Signed-off-by: Tzung-Bi Shih <tzungbi@kernel.org>

Reviewed-by: Guenter Roeck <groweck@chromium.org>

> ---
>  drivers/platform/chrome/cros_ec_debugfs.c   | 2 ++
>  include/linux/platform_data/cros_ec_proto.h | 1 +
>  2 files changed, 3 insertions(+)
>
> diff --git a/drivers/platform/chrome/cros_ec_debugfs.c b/drivers/platform/chrome/cros_ec_debugfs.c
> index 34f7b46f8761..a98c529d8c69 100644
> --- a/drivers/platform/chrome/cros_ec_debugfs.c
> +++ b/drivers/platform/chrome/cros_ec_debugfs.c
> @@ -38,6 +38,8 @@ static DECLARE_WAIT_QUEUE_HEAD(cros_ec_debugfs_log_wq);
>   * @log_mutex: mutex to protect circular buffer
>   * @log_poll_work: recurring task to poll EC for new console log data
>   * @panicinfo_blob: panicinfo debugfs blob
> + * @notifier_panic: notifier_block to let kernel to flush buffered log
> + *                  when EC panic
>   */
>  struct cros_ec_debugfs {
>         struct cros_ec_dev *ec;
> diff --git a/include/linux/platform_data/cros_ec_proto.h b/include/linux/platform_data/cros_ec_proto.h
> index 017d502ed66e..a4a3fec15504 100644
> --- a/include/linux/platform_data/cros_ec_proto.h
> +++ b/include/linux/platform_data/cros_ec_proto.h
> @@ -140,6 +140,7 @@ struct cros_ec_command {
>   *      main EC.
>   * @pd: The platform_device used by the mfd driver to interface with the
>   *      PD behind an EC.
> + * @panic_notifier: EC panic notifier.
>   */
>  struct cros_ec_device {
>         /* These are used by other drivers that want to talk to the EC */
> --
> 2.39.0.314.g84b9a713c41-goog
>

[PATCH 2/4] platform/chrome: fix kernel-doc warning for suspend_timeout_ms

[Tzung-Bi Shih]

Fix the following kernel-doc warning:

$ ./scripts/kernel-doc -none include/linux/platform_data/cros_ec_proto.h
include/linux/platform_data/cros_ec_proto.h:187: warning: Function
parameter or member 'suspend_timeout_ms' not described in 'cros_ec_device'

Cc: Evan Green <evgreen@chromium.org>
Fixes: e8bf17d58a4d ("platform/chrome: cros_ec: Expose suspend_timeout_ms in debugfs")
Signed-off-by: Tzung-Bi Shih <tzungbi@kernel.org>
---
 include/linux/platform_data/cros_ec_proto.h | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/include/linux/platform_data/cros_ec_proto.h b/include/linux/platform_data/cros_ec_proto.h
index a4a3fec15504..805dcb19a36d 100644
--- a/include/linux/platform_data/cros_ec_proto.h
+++ b/include/linux/platform_data/cros_ec_proto.h
@@ -131,6 +131,11 @@ struct cros_ec_command {
  * @event_data: Raw payload transferred with the MKBP event.
  * @event_size: Size in bytes of the event data.
  * @host_event_wake_mask: Mask of host events that cause wake from suspend.
+ * @suspend_timeout_ms: The timeout in milliseconds between when sleep event
+ *                      is received and when the EC will declare sleep
+ *                      transition failure if the sleep signal is not
+ *                      asserted.  See also struct
+ *                      ec_params_host_sleep_event_v1 in cros_ec_commands.h.
  * @last_event_time: exact time from the hard irq when we got notified of
  *     a new event.
  * @notifier_ready: The notifier_block to let the kernel re-query EC
-- 
2.39.0.314.g84b9a713c41-goog

Re: [PATCH 2/4] platform/chrome: fix kernel-doc warning for suspend_timeout_ms

[Guenter Roeck]

On Tue, Jan 10, 2023 at 9:57 PM Tzung-Bi Shih <tzungbi@kernel.org> wrote:
>
> Fix the following kernel-doc warning:
>
> $ ./scripts/kernel-doc -none include/linux/platform_data/cros_ec_proto.h
> include/linux/platform_data/cros_ec_proto.h:187: warning: Function
> parameter or member 'suspend_timeout_ms' not described in 'cros_ec_device'
>
> Cc: Evan Green <evgreen@chromium.org>
> Fixes: e8bf17d58a4d ("platform/chrome: cros_ec: Expose suspend_timeout_ms in debugfs")
> Signed-off-by: Tzung-Bi Shih <tzungbi@kernel.org>

Reviewed-by: Guenter Roeck <groeck@chromium.org>

> ---
>  include/linux/platform_data/cros_ec_proto.h | 5 +++++
>  1 file changed, 5 insertions(+)
>
> diff --git a/include/linux/platform_data/cros_ec_proto.h b/include/linux/platform_data/cros_ec_proto.h
> index a4a3fec15504..805dcb19a36d 100644
> --- a/include/linux/platform_data/cros_ec_proto.h
> +++ b/include/linux/platform_data/cros_ec_proto.h
> @@ -131,6 +131,11 @@ struct cros_ec_command {
>   * @event_data: Raw payload transferred with the MKBP event.
>   * @event_size: Size in bytes of the event data.
>   * @host_event_wake_mask: Mask of host events that cause wake from suspend.
> + * @suspend_timeout_ms: The timeout in milliseconds between when sleep event
> + *                      is received and when the EC will declare sleep
> + *                      transition failure if the sleep signal is not
> + *                      asserted.  See also struct
> + *                      ec_params_host_sleep_event_v1 in cros_ec_commands.h.
>   * @last_event_time: exact time from the hard irq when we got notified of
>   *     a new event.
>   * @notifier_ready: The notifier_block to let the kernel re-query EC
> --
> 2.39.0.314.g84b9a713c41-goog
>

[PATCH 3/4] platform/chrome: fix kernel-doc warning for last_resume_result

[Tzung-Bi Shih]

Fix the following kernel-doc warning:

$ ./scripts/kernel-doc -none include/linux/platform_data/cros_ec_proto.h
include/linux/platform_data/cros_ec_proto.h:187: warning: Function
parameter or member 'last_resume_result' not described in 'cros_ec_device'

Cc: Evan Green <evgreen@chromium.org>
Fixes: 8c3166e17cf1 ("mfd / platform: cros_ec_debugfs: Expose resume result via debugfs")
Signed-off-by: Tzung-Bi Shih <tzungbi@kernel.org>
---
 include/linux/platform_data/cros_ec_proto.h | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/include/linux/platform_data/cros_ec_proto.h b/include/linux/platform_data/cros_ec_proto.h
index 805dcb19a36d..4865c54d4af1 100644
--- a/include/linux/platform_data/cros_ec_proto.h
+++ b/include/linux/platform_data/cros_ec_proto.h
@@ -136,6 +136,10 @@ struct cros_ec_command {
  *                      transition failure if the sleep signal is not
  *                      asserted.  See also struct
  *                      ec_params_host_sleep_event_v1 in cros_ec_commands.h.
+ * @last_resume_result: The number of sleep power signal transitions that
+ *                      occurred since the suspend message. The high bit
+ *                      indicates a timeout occurred.  See also struct
+ *                      ec_response_host_sleep_event_v1 in cros_ec_commands.h.
  * @last_event_time: exact time from the hard irq when we got notified of
  *     a new event.
  * @notifier_ready: The notifier_block to let the kernel re-query EC
-- 
2.39.0.314.g84b9a713c41-goog

Re: [PATCH 3/4] platform/chrome: fix kernel-doc warning for last_resume_result

[Guenter Roeck]

On Tue, Jan 10, 2023 at 9:58 PM Tzung-Bi Shih <tzungbi@kernel.org> wrote:
>
> Fix the following kernel-doc warning:
>
> $ ./scripts/kernel-doc -none include/linux/platform_data/cros_ec_proto.h
> include/linux/platform_data/cros_ec_proto.h:187: warning: Function
> parameter or member 'last_resume_result' not described in 'cros_ec_device'
>
> Cc: Evan Green <evgreen@chromium.org>
> Fixes: 8c3166e17cf1 ("mfd / platform: cros_ec_debugfs: Expose resume result via debugfs")
> Signed-off-by: Tzung-Bi Shih <tzungbi@kernel.org>

Reviewed-by: Guenter Roeck <groeck@chromium.org>

> ---
>  include/linux/platform_data/cros_ec_proto.h | 4 ++++
>  1 file changed, 4 insertions(+)
>
> diff --git a/include/linux/platform_data/cros_ec_proto.h b/include/linux/platform_data/cros_ec_proto.h
> index 805dcb19a36d..4865c54d4af1 100644
> --- a/include/linux/platform_data/cros_ec_proto.h
> +++ b/include/linux/platform_data/cros_ec_proto.h
> @@ -136,6 +136,10 @@ struct cros_ec_command {
>   *                      transition failure if the sleep signal is not
>   *                      asserted.  See also struct
>   *                      ec_params_host_sleep_event_v1 in cros_ec_commands.h.
> + * @last_resume_result: The number of sleep power signal transitions that
> + *                      occurred since the suspend message. The high bit
> + *                      indicates a timeout occurred.  See also struct
> + *                      ec_response_host_sleep_event_v1 in cros_ec_commands.h.
>   * @last_event_time: exact time from the hard irq when we got notified of
>   *     a new event.
>   * @notifier_ready: The notifier_block to let the kernel re-query EC
> --
> 2.39.0.314.g84b9a713c41-goog
>

[PATCH 4/4] platform/chrome: fix kernel-doc warnings for cros_ec_command

[Tzung-Bi Shih]

Fix the following kernel-doc warnings:

$ ./scripts/kernel-doc -none \
	include/linux/platform_data/cros_ec_commands.h
include/linux/platform_data/cros_ec_commands.h:1092: warning: expecting
prototype for struct ec_response_get_cmd_version. Prototype was for
struct ec_response_get_cmd_versions instead
include/linux/platform_data/cros_ec_commands.h:5485: warning: This
comment starts with '/**', but isn't a kernel-doc comment.
include/linux/platform_data/cros_ec_commands.h:5496: warning: This
comment starts with '/**', but isn't a kernel-doc comment.

Signed-off-by: Tzung-Bi Shih <tzungbi@kernel.org>
---
 include/linux/platform_data/cros_ec_commands.h | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/include/linux/platform_data/cros_ec_commands.h b/include/linux/platform_data/cros_ec_commands.h
index 6665e7da6ee2..b9c4a3964247 100644
--- a/include/linux/platform_data/cros_ec_commands.h
+++ b/include/linux/platform_data/cros_ec_commands.h
@@ -1082,7 +1082,7 @@ struct ec_params_get_cmd_versions_v1 {
 } __ec_align2;
 
 /**
- * struct ec_response_get_cmd_version - Response to the get command versions.
+ * struct ec_response_get_cmd_versions - Response to the get command versions.
  * @version_mask: Mask of supported versions; use EC_VER_MASK() to compare with
  *                a desired version.
  */
@@ -5480,7 +5480,7 @@ struct ec_response_rollback_info {
 /* Issue AP reset */
 #define EC_CMD_AP_RESET 0x0125
 
-/**
+/*
  * Get the number of peripheral charge ports
  */
 #define EC_CMD_PCHG_COUNT 0x0134
@@ -5491,7 +5491,7 @@ struct ec_response_pchg_count {
 	uint8_t port_count;
 } __ec_align1;
 
-/**
+/*
  * Get the status of a peripheral charge port
  */
 #define EC_CMD_PCHG 0x0135
-- 
2.39.0.314.g84b9a713c41-goog

Re: [PATCH 4/4] platform/chrome: fix kernel-doc warnings for cros_ec_command

[Guenter Roeck]

On Tue, Jan 10, 2023 at 9:58 PM Tzung-Bi Shih <tzungbi@kernel.org> wrote:
>
> Fix the following kernel-doc warnings:
>
> $ ./scripts/kernel-doc -none \
>         include/linux/platform_data/cros_ec_commands.h
> include/linux/platform_data/cros_ec_commands.h:1092: warning: expecting
> prototype for struct ec_response_get_cmd_version. Prototype was for
> struct ec_response_get_cmd_versions instead
> include/linux/platform_data/cros_ec_commands.h:5485: warning: This
> comment starts with '/**', but isn't a kernel-doc comment.
> include/linux/platform_data/cros_ec_commands.h:5496: warning: This
> comment starts with '/**', but isn't a kernel-doc comment.
>
> Signed-off-by: Tzung-Bi Shih <tzungbi@kernel.org>

Reviewed-by: Guenter Roeck <groeck@chromium.org>

> ---
>  include/linux/platform_data/cros_ec_commands.h | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/include/linux/platform_data/cros_ec_commands.h b/include/linux/platform_data/cros_ec_commands.h
> index 6665e7da6ee2..b9c4a3964247 100644
> --- a/include/linux/platform_data/cros_ec_commands.h
> +++ b/include/linux/platform_data/cros_ec_commands.h
> @@ -1082,7 +1082,7 @@ struct ec_params_get_cmd_versions_v1 {
>  } __ec_align2;
>
>  /**
> - * struct ec_response_get_cmd_version - Response to the get command versions.
> + * struct ec_response_get_cmd_versions - Response to the get command versions.
>   * @version_mask: Mask of supported versions; use EC_VER_MASK() to compare with
>   *                a desired version.
>   */
> @@ -5480,7 +5480,7 @@ struct ec_response_rollback_info {
>  /* Issue AP reset */
>  #define EC_CMD_AP_RESET 0x0125
>
> -/**
> +/*
>   * Get the number of peripheral charge ports
>   */
>  #define EC_CMD_PCHG_COUNT 0x0134
> @@ -5491,7 +5491,7 @@ struct ec_response_pchg_count {
>         uint8_t port_count;
>  } __ec_align1;
>
> -/**
> +/*
>   * Get the status of a peripheral charge port
>   */
>  #define EC_CMD_PCHG 0x0135
> --
> 2.39.0.314.g84b9a713c41-goog
>

Re: [PATCH 0/4] platform/chrome: fix kernel-doc warnings

[patchwork-bot+chrome-platform]

Hello:

This series was applied to chrome-platform/linux.git (for-kernelci)
by Tzung-Bi Shih <tzungbi@kernel.org>:

On Wed, 11 Jan 2023 13:57:24 +0800 you wrote:
> The series fixes kernel-doc warnings in various places.
> 
> All of them can be squashed into 1 fix actually.  However, I think it would
> be more clear to separate the first 2 commits as the patches introduced
> the warnings are quite new.
> 
> For the 3rd patch, I am not sure if it makes sense to have the Fixes tag.
> It is a little bit old (~2019).
> 
> [...]

Here is the summary with links:
  - [1/4] platform/chrome: fix kernel-doc warnings for panic notifier
    https://git.kernel.org/chrome-platform/c/16d73129f1fd
  - [2/4] platform/chrome: fix kernel-doc warning for suspend_timeout_ms
    https://git.kernel.org/chrome-platform/c/20eb556dac27
  - [3/4] platform/chrome: fix kernel-doc warning for last_resume_result
    https://git.kernel.org/chrome-platform/c/212c9b9c395f
  - [4/4] platform/chrome: fix kernel-doc warnings for cros_ec_command
    https://git.kernel.org/chrome-platform/c/5fa1dd818fb4

You are awesome, thank you!
-- 
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html

Re: [PATCH 0/4] platform/chrome: fix kernel-doc warnings

[patchwork-bot+chrome-platform]

Hello:

This series was applied to chrome-platform/linux.git (for-next)
by Tzung-Bi Shih <tzungbi@kernel.org>:

On Wed, 11 Jan 2023 13:57:24 +0800 you wrote:
> The series fixes kernel-doc warnings in various places.
> 
> All of them can be squashed into 1 fix actually.  However, I think it would
> be more clear to separate the first 2 commits as the patches introduced
> the warnings are quite new.
> 
> For the 3rd patch, I am not sure if it makes sense to have the Fixes tag.
> It is a little bit old (~2019).
> 
> [...]

Here is the summary with links:
  - [1/4] platform/chrome: fix kernel-doc warnings for panic notifier
    https://git.kernel.org/chrome-platform/c/16d73129f1fd
  - [2/4] platform/chrome: fix kernel-doc warning for suspend_timeout_ms
    https://git.kernel.org/chrome-platform/c/20eb556dac27
  - [3/4] platform/chrome: fix kernel-doc warning for last_resume_result
    https://git.kernel.org/chrome-platform/c/212c9b9c395f
  - [4/4] platform/chrome: fix kernel-doc warnings for cros_ec_command
    https://git.kernel.org/chrome-platform/c/5fa1dd818fb4

You are awesome, thank you!
-- 
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html