From 33b4c26d4d3ccd24d9721a577671f2c73c1a7cd9 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Fri, 28 Nov 2025 16:25:24 -0800 Subject: [PATCH 1/3] x86/platform: Fix and extend kernel-doc comments in 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 Signed-off-by: Ingo Molnar 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 36698cc9fb44..6c8a6ead84f6 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); From c7957da77708c74a95d60340c6d3c1a3617cd248 Mon Sep 17 00:00:00 2001 From: Ingo Molnar Date: Wed, 3 Dec 2025 18:25:13 +0100 Subject: [PATCH 2/3] x86/boot/Documentation: Spell 'ID' consistently The bootloader ID specification text uses 2 capitalization variants for the same thing: 'id', 'ids', 'ID' and 'IDs'. Use 'ID/IDs' consistently. Signed-off-by: Ingo Molnar Cc: "H. Peter Anvin" Cc: linux-kernel@vger.kernel.org --- Documentation/arch/x86/boot.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/arch/x86/boot.rst b/Documentation/arch/x86/boot.rst index 77e6163288db..b0f648b5c05b 100644 --- a/Documentation/arch/x86/boot.rst +++ b/Documentation/arch/x86/boot.rst @@ -416,7 +416,7 @@ Offset/size: 0x210/1 Protocol: 2.00+ ============ ================== - If your boot loader has an assigned id (see table below), enter + If your boot loader has an assigned ID (see table below), enter 0xTV here, where T is an identifier for the boot loader and V is a version number. Otherwise, enter 0xFF here. @@ -431,7 +431,7 @@ Protocol: 2.00+ ext_loader_type <- 0x05 ext_loader_ver <- 0x23 - Assigned boot loader ids (hexadecimal): + Assigned boot loader IDs (hexadecimal): == ======================================= 0 LILO From 1c3377bee2127f98f16705376a36326c98113d1c Mon Sep 17 00:00:00 2001 From: Ingo Molnar Date: Wed, 3 Dec 2025 18:29:59 +0100 Subject: [PATCH 3/3] x86/boot/Documentation: Prefix hexadecimal literals with 0x The x86 bootloader ID specification text uses hexadecimal values without a 0x prefix: D kexec-tools E Extended (see ext_loader_type) F Special (0xFF = undefined) 10 Reserved 11 Minimal Linux Bootloader 12 OVMF UEFI virtualization stack 13 barebox Which beyond the ambiguity of '13' in isolation, also made me fail a grep -wi '0xd' when I was looking for the kexec bootloader ID definition and caused quite a bit of head-scratching before I found out why it didn't show up. Furthermore, the actual explanatory text uses the 0x prefix: For boot loader IDs above T = 0xD, write T = 0xE to this field and write the extended ID minus 0x10 to the ext_loader_type field. Similarly, the ext_loader_ver field can be used to provide more than four bits for the bootloader version. So make it all both unambiguous, easy to grep and consistent across the entire documentation by prefixing the IDs with 0x. Signed-off-by: Ingo Molnar Cc: "H. Peter Anvin" Cc: linux-kernel@vger.kernel.org --- Documentation/arch/x86/boot.rst | 46 ++++++++++++++++----------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/Documentation/arch/x86/boot.rst b/Documentation/arch/x86/boot.rst index b0f648b5c05b..42f50fa0ebc3 100644 --- a/Documentation/arch/x86/boot.rst +++ b/Documentation/arch/x86/boot.rst @@ -431,31 +431,31 @@ Protocol: 2.00+ ext_loader_type <- 0x05 ext_loader_ver <- 0x23 - Assigned boot loader IDs (hexadecimal): + Assigned boot loader IDs: == ======================================= - 0 LILO - (0x00 reserved for pre-2.00 bootloader) - 1 Loadlin - 2 bootsect-loader - (0x20, all other values reserved) - 3 Syslinux - 4 Etherboot/gPXE/iPXE - 5 ELILO - 7 GRUB - 8 U-Boot - 9 Xen - A Gujin - B Qemu - C Arcturus Networks uCbootloader - D kexec-tools - E Extended (see ext_loader_type) - F Special (0xFF = undefined) - 10 Reserved - 11 Minimal Linux Bootloader - - 12 OVMF UEFI virtualization stack - 13 barebox + 0x0 LILO + (0x00 reserved for pre-2.00 bootloader) + 0x1 Loadlin + 0x2 bootsect-loader + (0x20, all other values reserved) + 0x3 Syslinux + 0x4 Etherboot/gPXE/iPXE + 0x5 ELILO + 0x7 GRUB + 0x8 U-Boot + 0x9 Xen + 0xA Gujin + 0xB Qemu + 0xC Arcturus Networks uCbootloader + 0xD kexec-tools + 0xE Extended (see ext_loader_type) + 0xF Special (0xFF = undefined) + 0x10 Reserved + 0x11 Minimal Linux Bootloader + + 0x12 OVMF UEFI virtualization stack + 0x13 barebox == ======================================= Please contact if you need a bootloader ID value assigned.