arch/x86/include/asm/x86_init.h | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-)
Fix most (17) kernel-doc warnings in x86_init.h (except for struct
x86_init_ops). The changes are:
- fix struct member name typos
- add ending ':' to struct member names
- add some missing struct member descriptions
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Ingo Molnar <mingo@redhat.com>
Cc: Borislav Petkov <bp@alien8.de>
Cc: Dave Hansen <dave.hansen@linux.intel.com>
Cc: x86@kernel.org
Cc: "H. Peter Anvin" <hpa@zytor.com>
---
arch/x86/include/asm/x86_init.h | 28 ++++++++++++++++------------
1 file changed, 16 insertions(+), 12 deletions(-)
--- linux-next-20251128.orig/arch/x86/include/asm/x86_init.h
+++ linux-next-20251128/arch/x86/include/asm/x86_init.h
@@ -79,7 +79,7 @@ struct x86_init_paging {
/**
* struct x86_init_timers - platform specific timer setup
- * @setup_perpcu_clockev: set up the per cpu clock event device for the
+ * @setup_percpu_clockev: set up the per cpu clock event device for the
* boot cpu
* @timer_init: initialize the platform timer (default PIT/HPET)
* @wallclock_init: init the wallclock device
@@ -132,7 +132,7 @@ struct x86_hyper_init {
/**
* struct x86_init_acpi - x86 ACPI init functions
- * @set_root_poitner: set RSDP address
+ * @set_root_pointer: set RSDP address
* @get_root_pointer: get RSDP address
* @reduced_hw_early_init: hardware reduced platform early init
*/
@@ -145,14 +145,14 @@ struct x86_init_acpi {
/**
* struct x86_guest - Functions used by misc guest incarnations like SEV, TDX, etc.
*
- * @enc_status_change_prepare Notify HV before the encryption status of a range is changed
- * @enc_status_change_finish Notify HV after the encryption status of a range is changed
- * @enc_tlb_flush_required Returns true if a TLB flush is needed before changing page encryption status
- * @enc_cache_flush_required Returns true if a cache flush is needed before changing page encryption status
- * @enc_kexec_begin Begin the two-step process of converting shared memory back
+ * @enc_status_change_prepare: Notify HV before the encryption status of a range is changed
+ * @enc_status_change_finish: Notify HV after the encryption status of a range is changed
+ * @enc_tlb_flush_required: Returns true if a TLB flush is needed before changing page encryption status
+ * @enc_cache_flush_required: Returns true if a cache flush is needed before changing page encryption status
+ * @enc_kexec_begin: Begin the two-step process of converting shared memory back
* to private. It stops the new conversions from being started
* and waits in-flight conversions to finish, if possible.
- * @enc_kexec_finish Finish the two-step process of converting shared memory to
+ * @enc_kexec_finish: Finish the two-step process of converting shared memory to
* private. All memory is private after the call when
* the function returns.
* It is called on only one CPU while the others are shut down
@@ -229,7 +229,7 @@ struct x86_legacy_devices {
* given platform/subarch.
* @X86_LEGACY_I8042_FIRMWARE_ABSENT: firmware reports that the controller
* is absent.
- * @X86_LEGACY_i8042_EXPECTED_PRESENT: the controller is likely to be
+ * @X86_LEGACY_I8042_EXPECTED_PRESENT: the controller is likely to be
* present, the i8042 driver should probe for controller existence.
*/
enum x86_legacy_i8042_state {
@@ -244,6 +244,8 @@ enum x86_legacy_i8042_state {
* @i8042: indicated if we expect the device to have i8042 controller
* present.
* @rtc: this device has a CMOS real-time clock present
+ * @warm_reset: %1 if platform allows warm reset, else %0
+ * @no_vga: %1 if (FADT.boot_flags & ACPI_FADT_NO_VGA) is set, else %0
* @reserve_bios_regions: boot code will search for the EBDA address and the
* start of the 640k - 1M BIOS region. If false, the platform must
* ensure that its memory map correctly reserves sub-1MB regions as needed.
@@ -290,9 +292,10 @@ struct x86_hyper_runtime {
* @calibrate_tsc: calibrate TSC, if different from CPU
* @get_wallclock: get time from HW clock like RTC etc.
* @set_wallclock: set time back to HW clock
- * @is_untracked_pat_range exclude from PAT logic
- * @nmi_init enable NMI on cpus
- * @get_nmi_reason get the reason an NMI was received
+ * @iommu_shutdown: set by an IOMMU driver for shutdown if necessary
+ * @is_untracked_pat_range: exclude from PAT logic
+ * @nmi_init: enable NMI on cpus
+ * @get_nmi_reason: get the reason an NMI was received
* @save_sched_clock_state: save state for sched_clock() on suspend
* @restore_sched_clock_state: restore state for sched_clock() on resume
* @apic_post_init: adjust apic if needed
@@ -307,6 +310,7 @@ struct x86_hyper_runtime {
* @realmode_reserve: reserve memory for realmode trampoline
* @realmode_init: initialize realmode trampoline
* @hyper: x86 hypervisor specific runtime callbacks
+ * @guest: guest incarnations callbacks
*/
struct x86_platform_ops {
unsigned long (*calibrate_cpu)(void);* Randy Dunlap <rdunlap@infradead.org> wrote: > * @i8042: indicated if we expect the device to have i8042 controller > * present. > * @rtc: this device has a CMOS real-time clock present > + * @warm_reset: %1 if platform allows warm reset, else %0 > + * @no_vga: %1 if (FADT.boot_flags & ACPI_FADT_NO_VGA) is set, else %0 > * @reserve_bios_regions: boot code will search for the EBDA address and the > * start of the 640k - 1M BIOS region. If false, the platform must > * ensure that its memory map correctly reserves sub-1MB regions as needed. What is '%1' and '%0' - literal 1 and 0? That's a really weird way to write them. Thanks, Ingo
On 12/1/25 12:56 PM, Ingo Molnar wrote: > > * Randy Dunlap <rdunlap@infradead.org> wrote: > >> * @i8042: indicated if we expect the device to have i8042 controller >> * present. >> * @rtc: this device has a CMOS real-time clock present >> + * @warm_reset: %1 if platform allows warm reset, else %0 >> + * @no_vga: %1 if (FADT.boot_flags & ACPI_FADT_NO_VGA) is set, else %0 >> * @reserve_bios_regions: boot code will search for the EBDA address and the >> * start of the 640k - 1M BIOS region. If false, the platform must >> * ensure that its memory map correctly reserves sub-1MB regions as needed. > > What is '%1' and '%0' - literal 1 and 0? Yes, kernel-doc notation. > That's a really weird way to write them. OK, they can be removed. Do you want a v2? thanks. -- ~Randy
* Randy Dunlap <rdunlap@infradead.org> wrote: > > > On 12/1/25 12:56 PM, Ingo Molnar wrote: > > > > * Randy Dunlap <rdunlap@infradead.org> wrote: > > > >> * @i8042: indicated if we expect the device to have i8042 controller > >> * present. > >> * @rtc: this device has a CMOS real-time clock present > >> + * @warm_reset: %1 if platform allows warm reset, else %0 > >> + * @no_vga: %1 if (FADT.boot_flags & ACPI_FADT_NO_VGA) is set, else %0 > >> * @reserve_bios_regions: boot code will search for the EBDA address and the > >> * start of the 640k - 1M BIOS region. If false, the platform must > >> * ensure that its memory map correctly reserves sub-1MB regions as needed. > > > > What is '%1' and '%0' - literal 1 and 0? > > Yes, kernel-doc notation. Yeah, so it's not a very widespread usage versus using the literals. I'd go with the plain text literals, especially since they don't cause comment-reading exceptions for the brain, which is always a plus. :) > > That's a really weird way to write them. > > OK, they can be removed. Do you want a v2? No need, I already edited it, just wanted to make sure I haven't missed anything. Thanks, Ingo
On 12/1/25 1:00 PM, Ingo Molnar wrote: > > * Randy Dunlap <rdunlap@infradead.org> wrote: > >> >> >> On 12/1/25 12:56 PM, Ingo Molnar wrote: >>> >>> * Randy Dunlap <rdunlap@infradead.org> wrote: >>> >>>> * @i8042: indicated if we expect the device to have i8042 controller >>>> * present. >>>> * @rtc: this device has a CMOS real-time clock present >>>> + * @warm_reset: %1 if platform allows warm reset, else %0 >>>> + * @no_vga: %1 if (FADT.boot_flags & ACPI_FADT_NO_VGA) is set, else %0 >>>> * @reserve_bios_regions: boot code will search for the EBDA address and the >>>> * start of the 640k - 1M BIOS region. If false, the platform must >>>> * ensure that its memory map correctly reserves sub-1MB regions as needed. >>> >>> What is '%1' and '%0' - literal 1 and 0? >> >> Yes, kernel-doc notation. > > Yeah, so it's not a very widespread usage versus using > the literals. I'd go with the plain text literals, > especially since they don't cause comment-reading > exceptions for the brain, which is always a plus. :) Definitely. >>> That's a really weird way to write them. >> >> OK, they can be removed. Do you want a v2? > > No need, I already edited it, just wanted to make sure > I haven't missed anything. OK, thanks. -- ~Randy
The following commit has been merged into the x86/urgent branch of tip:
Commit-ID: 33b4c26d4d3ccd24d9721a577671f2c73c1a7cd9
Gitweb: https://git.kernel.org/tip/33b4c26d4d3ccd24d9721a577671f2c73c1a7cd9
Author: Randy Dunlap <rdunlap@infradead.org>
AuthorDate: Fri, 28 Nov 2025 16:25:24 -08:00
Committer: Ingo Molnar <mingo@kernel.org>
CommitterDate: Mon, 01 Dec 2025 21:57:16 +01:00
x86/platform: Fix and extend kernel-doc comments in <asm/x86_init.h>
Fix most (17) kernel-doc warnings in x86_init.h (except for struct
x86_init_ops). The changes are:
- fix struct member name typos
- add ending ':' to struct member names
- add some missing struct member descriptions
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
Link: https://patch.msgid.link/20251129002524.1196500-1-rdunlap@infradead.org
---
arch/x86/include/asm/x86_init.h | 28 ++++++++++++++++------------
1 file changed, 16 insertions(+), 12 deletions(-)
diff --git a/arch/x86/include/asm/x86_init.h b/arch/x86/include/asm/x86_init.h
index 36698cc..6c8a6ea 100644
--- a/arch/x86/include/asm/x86_init.h
+++ b/arch/x86/include/asm/x86_init.h
@@ -79,7 +79,7 @@ struct x86_init_paging {
/**
* struct x86_init_timers - platform specific timer setup
- * @setup_perpcu_clockev: set up the per cpu clock event device for the
+ * @setup_percpu_clockev: set up the per cpu clock event device for the
* boot cpu
* @timer_init: initialize the platform timer (default PIT/HPET)
* @wallclock_init: init the wallclock device
@@ -132,7 +132,7 @@ struct x86_hyper_init {
/**
* struct x86_init_acpi - x86 ACPI init functions
- * @set_root_poitner: set RSDP address
+ * @set_root_pointer: set RSDP address
* @get_root_pointer: get RSDP address
* @reduced_hw_early_init: hardware reduced platform early init
*/
@@ -145,14 +145,14 @@ struct x86_init_acpi {
/**
* struct x86_guest - Functions used by misc guest incarnations like SEV, TDX, etc.
*
- * @enc_status_change_prepare Notify HV before the encryption status of a range is changed
- * @enc_status_change_finish Notify HV after the encryption status of a range is changed
- * @enc_tlb_flush_required Returns true if a TLB flush is needed before changing page encryption status
- * @enc_cache_flush_required Returns true if a cache flush is needed before changing page encryption status
- * @enc_kexec_begin Begin the two-step process of converting shared memory back
+ * @enc_status_change_prepare: Notify HV before the encryption status of a range is changed
+ * @enc_status_change_finish: Notify HV after the encryption status of a range is changed
+ * @enc_tlb_flush_required: Returns true if a TLB flush is needed before changing page encryption status
+ * @enc_cache_flush_required: Returns true if a cache flush is needed before changing page encryption status
+ * @enc_kexec_begin: Begin the two-step process of converting shared memory back
* to private. It stops the new conversions from being started
* and waits in-flight conversions to finish, if possible.
- * @enc_kexec_finish Finish the two-step process of converting shared memory to
+ * @enc_kexec_finish: Finish the two-step process of converting shared memory to
* private. All memory is private after the call when
* the function returns.
* It is called on only one CPU while the others are shut down
@@ -229,7 +229,7 @@ struct x86_legacy_devices {
* given platform/subarch.
* @X86_LEGACY_I8042_FIRMWARE_ABSENT: firmware reports that the controller
* is absent.
- * @X86_LEGACY_i8042_EXPECTED_PRESENT: the controller is likely to be
+ * @X86_LEGACY_I8042_EXPECTED_PRESENT: the controller is likely to be
* present, the i8042 driver should probe for controller existence.
*/
enum x86_legacy_i8042_state {
@@ -244,6 +244,8 @@ enum x86_legacy_i8042_state {
* @i8042: indicated if we expect the device to have i8042 controller
* present.
* @rtc: this device has a CMOS real-time clock present
+ * @warm_reset: 1 if platform allows warm reset, else 0
+ * @no_vga: 1 if (FADT.boot_flags & ACPI_FADT_NO_VGA) is set, else 0
* @reserve_bios_regions: boot code will search for the EBDA address and the
* start of the 640k - 1M BIOS region. If false, the platform must
* ensure that its memory map correctly reserves sub-1MB regions as needed.
@@ -290,9 +292,10 @@ struct x86_hyper_runtime {
* @calibrate_tsc: calibrate TSC, if different from CPU
* @get_wallclock: get time from HW clock like RTC etc.
* @set_wallclock: set time back to HW clock
- * @is_untracked_pat_range exclude from PAT logic
- * @nmi_init enable NMI on cpus
- * @get_nmi_reason get the reason an NMI was received
+ * @iommu_shutdown: set by an IOMMU driver for shutdown if necessary
+ * @is_untracked_pat_range: exclude from PAT logic
+ * @nmi_init: enable NMI on cpus
+ * @get_nmi_reason: get the reason an NMI was received
* @save_sched_clock_state: save state for sched_clock() on suspend
* @restore_sched_clock_state: restore state for sched_clock() on resume
* @apic_post_init: adjust apic if needed
@@ -307,6 +310,7 @@ struct x86_hyper_runtime {
* @realmode_reserve: reserve memory for realmode trampoline
* @realmode_init: initialize realmode trampoline
* @hyper: x86 hypervisor specific runtime callbacks
+ * @guest: guest incarnations callbacks
*/
struct x86_platform_ops {
unsigned long (*calibrate_cpu)(void);© 2016 - 2026 Red Hat, Inc.