From nobody Sat Feb 7 15:15:19 2026 Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.15]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 3B79E1BCA0A; Thu, 28 Nov 2024 15:26:24 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=192.198.163.15 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1732807586; cv=none; b=kVT6A6Iib6YoAzVWOhchb0QLCi8SNahRlApf7rTYn57Tw5IqBdRM7i//6x2/jSIALzQpgf5tBB3uHwv3iAFdK4qyEz4sfm67TWrtbkWti7YVYxespHODFk8DzRO8KhcjhsigGRlpF9Vpi3TxDa0L4OHBRXzUk6sGvsLKpEO5T0c= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1732807586; c=relaxed/simple; bh=0aC5cqmO39QiCbyZUhJS3xSoLJpG70kuls+DEfoEVjU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=W9bjb/nkCOcTMsAw398e0Nnyi5mosoeIXv4/FCNp+o2UYiFzKKQNGKVEBkonm4ehCdpHKpf5R+tV0Zz6GB/DOogMlvUneA+aQ7xl3lP1xhvOvlJKt4fTFKZ7gtbC3rArlNE26II/8a+3zGiPyYC32ppOpggZddOBom2S7CI6+bQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linux.intel.com; spf=none smtp.mailfrom=linux.intel.com; dkim=pass (2048-bit key) header.d=intel.com header.i=@intel.com header.b=LCGxc4Fo; arc=none smtp.client-ip=192.198.163.15 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linux.intel.com Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=linux.intel.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=intel.com header.i=@intel.com header.b="LCGxc4Fo" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1732807584; x=1764343584; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=0aC5cqmO39QiCbyZUhJS3xSoLJpG70kuls+DEfoEVjU=; b=LCGxc4Fo8+cx5prat49rxHQjLzkHw5GuJT6riXDCJwi3h37XUEF1Ud3I FRqVz+8lX7Rzwpx2+byAOotjloE76PwbPsWk/+DR6wUGHE++FW0pm+LJB 2xTggvwjUAh6vWa/cs1NqUEUXBOuN5MCqXhoKRn+QaO8eCb0ok3oFK+q1 3yfn2va41wPzxJN6khXkpBurKo5/ZW0AxzOF4el+ejwkn7n2P7nVb96dh byOATvonlUp/ZTqnT5G//8Zu1WLPvQc5rIUI2eiZYgwKeODjK4ShQvPxa cK+JeKaa6akPd47m20oLexZzYYUZSK0XTV2Ib8cgTZN4DBdmvf6dDe1Oj A==; X-CSE-ConnectionGUID: rlukY/tBQx+27DLQuaYAgg== X-CSE-MsgGUID: XXhpaBErRWqVCOkHY70QYg== X-IronPort-AV: E=McAfee;i="6700,10204,11270"; a="33175838" X-IronPort-AV: E=Sophos;i="6.12,192,1728975600"; d="scan'208";a="33175838" Received: from fmviesa009.fm.intel.com ([10.60.135.149]) by fmvoesa109.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 28 Nov 2024 07:25:55 -0800 X-CSE-ConnectionGUID: BIV0s4IDRgmzgMmiloDSXA== X-CSE-MsgGUID: FMoyTApIT6ea9w8QQZRRUA== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.12,192,1728975600"; d="scan'208";a="92730958" Received: from black.fi.intel.com ([10.237.72.28]) by fmviesa009.fm.intel.com with ESMTP; 28 Nov 2024 07:25:51 -0800 Received: by black.fi.intel.com (Postfix, from userid 1003) id 913801BD; Thu, 28 Nov 2024 17:25:50 +0200 (EET) From: Andy Shevchenko To: Andy Shevchenko , linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org Cc: Thomas Gleixner , Ingo Molnar , Borislav Petkov , Dave Hansen , x86@kernel.org, "H. Peter Anvin" , Jonathan Corbet , Ingo Molnar Subject: [PATCH v1 1/3] x86/Documentation: Make Literal Blocks to follow reStructuredText specification Date: Thu, 28 Nov 2024 17:23:38 +0200 Message-ID: <20241128152546.2396782-2-andriy.shevchenko@linux.intel.com> X-Mailer: git-send-email 2.43.0.rc1.1336.g36b5255a03ac In-Reply-To: <20241128152546.2396782-1-andriy.shevchenko@linux.intel.com> References: <20241128152546.2396782-1-andriy.shevchenko@linux.intel.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" The file collects pieces from different epochs and hence has unaligned style of the Literal Blocks (in terms of reStructuredText specification). Make the Literal Blocks to follow the reStructuredText specification While at it, make the C-like code more C and follow the Kernel Coding style in them (after satisfying rST specification). Suggested-by: Ingo Molnar Suggested-by: "H. Peter Anvin" Signed-off-by: Andy Shevchenko Acked-by: Dave Hansen --- Documentation/arch/x86/boot.rst | 327 ++++++++++++++++---------------- 1 file changed, 162 insertions(+), 165 deletions(-) diff --git a/Documentation/arch/x86/boot.rst b/Documentation/arch/x86/boot.= rst index ad2d8ddad27f..17a7da883895 100644 --- a/Documentation/arch/x86/boot.rst +++ b/Documentation/arch/x86/boot.rst @@ -95,27 +95,27 @@ Memory Layout The traditional memory map for the kernel loader, used for Image or zImage kernels, typically looks like:: =20 - | | - 0A0000 +------------------------+ - | Reserved for BIOS | Do not use. Reserved for BIOS EBDA. - 09A000 +------------------------+ - | Command line | - | Stack/heap | For use by the kernel real-mode code. - 098000 +------------------------+ - | Kernel setup | The kernel real-mode code. - 090200 +------------------------+ - | Kernel boot sector | The kernel legacy boot sector. - 090000 +------------------------+ - | Protected-mode kernel | The bulk of the kernel image. - 010000 +------------------------+ - | Boot loader | <- Boot sector entry point 0000:7C00 - 001000 +------------------------+ - | Reserved for MBR/BIOS | - 000800 +------------------------+ - | Typically used by MBR | - 000600 +------------------------+ - | BIOS use only | - 000000 +------------------------+ + | | + 0A0000 +------------------------+ + | Reserved for BIOS | Do not use. Reserved for BIOS EBDA. + 09A000 +------------------------+ + | Command line | + | Stack/heap | For use by the kernel real-mode code. + 098000 +------------------------+ + | Kernel setup | The kernel real-mode code. + 090200 +------------------------+ + | Kernel boot sector | The kernel legacy boot sector. + 090000 +------------------------+ + | Protected-mode kernel | The bulk of the kernel image. + 010000 +------------------------+ + | Boot loader | <- Boot sector entry point 0000:7C00 + 001000 +------------------------+ + | Reserved for MBR/BIOS | + 000800 +------------------------+ + | Typically used by MBR | + 000600 +------------------------+ + | BIOS use only | + 000000 +------------------------+ =20 When using bzImage, the protected-mode kernel was relocated to 0x100000 ("high memory"), and the kernel real-mode block (boot sector, @@ -142,28 +142,28 @@ above the 0x9A000 point; too many BIOSes will break a= bove that point. For a modern bzImage kernel with boot protocol version >=3D 2.02, a memory layout like the following is suggested:: =20 - ~ ~ - | Protected-mode kernel | - 100000 +------------------------+ - | I/O memory hole | - 0A0000 +------------------------+ - | Reserved for BIOS | Leave as much as possible unused - ~ ~ - | Command line | (Can also be below the X+10000 mark) - X+10000 +------------------------+ - | Stack/heap | For use by the kernel real-mode code. - X+08000 +------------------------+ - | Kernel setup | The kernel real-mode code. - | Kernel boot sector | The kernel legacy boot sector. - X +------------------------+ - | Boot loader | <- Boot sector entry point 0000:7C00 - 001000 +------------------------+ - | Reserved for MBR/BIOS | - 000800 +------------------------+ - | Typically used by MBR | - 000600 +------------------------+ - | BIOS use only | - 000000 +------------------------+ + ~ ~ + | Protected-mode kernel | + 100000 +------------------------+ + | I/O memory hole | + 0A0000 +------------------------+ + | Reserved for BIOS | Leave as much as possible unused + ~ ~ + | Command line | (Can also be below the X+10000 mark) + X+10000 +------------------------+ + | Stack/heap | For use by the kernel real-mode code. + X+08000 +------------------------+ + | Kernel setup | The kernel real-mode code. + | Kernel boot sector | The kernel legacy boot sector. + X +------------------------+ + | Boot loader | <- Boot sector entry point 0000:7C00 + 001000 +------------------------+ + | Reserved for MBR/BIOS | + 000800 +------------------------+ + | Typically used by MBR | + 000600 +------------------------+ + | BIOS use only | + 000000 +------------------------+ =20 ... where the address X is as low as the design of the boot loader permi= ts. =20 @@ -242,9 +242,9 @@ If the "HdrS" (0x53726448) magic number is not found at= offset 0x202, the boot protocol version is "old". Loading an old kernel, the following parameters should be assumed:: =20 - Image type =3D zImage - initrd not supported - Real-mode kernel must be located at 0x90000. + Image type =3D zImage + initrd not supported + Real-mode kernel must be located at 0x90000. =20 Otherwise, the "version" field contains the protocol version, e.g. protocol version 2.01 will contain 0x0201 in this field. When @@ -365,7 +365,7 @@ Offset/size: 0x206/2 Protocol: 2.00+ =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D =20 - Contains the boot protocol version, in (major << 8)+minor format, + Contains the boot protocol version, in (major << 8) + minor format, e.g. 0x0204 for version 2.04, and 0x0a11 for a hypothetical version 10.17. =20 @@ -397,17 +397,17 @@ Protocol: 2.00+ If set to a nonzero value, contains a pointer to a NUL-terminated human-readable kernel version number string, less 0x200. This can be used to display the kernel version to the user. This value - should be less than (0x200*setup_sects). + should be less than (0x200 * setup_sects). =20 For example, if this value is set to 0x1c00, the kernel version number string can be found at offset 0x1e00 in the kernel file. This is a valid value if and only if the "setup_sects" field contains the value 15 or higher, as:: =20 - 0x1c00 < 15*0x200 (=3D 0x1e00) but - 0x1c00 >=3D 14*0x200 (=3D 0x1c00) + 0x1c00 < 15 * 0x200 (=3D 0x1e00) but + 0x1c00 >=3D 14 * 0x200 (=3D 0x1c00) =20 - 0x1c00 >> 9 =3D 14, So the minimum value for setup_secs is 15. + 0x1c00 >> 9 =3D 14, So the minimum value for setup_secs is 15. =20 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D Field name: type_of_loader @@ -427,9 +427,9 @@ Protocol: 2.00+ =20 For example, for T =3D 0x15, V =3D 0x234, write:: =20 - type_of_loader <- 0xE4 - ext_loader_type <- 0x05 - ext_loader_ver <- 0x23 + type_of_loader <- 0xE4 + ext_loader_type <- 0x05 + ext_loader_ver <- 0x23 =20 Assigned boot loader ids (hexadecimal): =20 @@ -686,7 +686,7 @@ Protocol: 2.10+ If a boot loader makes use of this field, it should update the kernel_alignment field with the alignment unit desired; typically:: =20 - kernel_alignment =3D 1 << min_alignment + kernel_alignment =3D 1 << min_alignment; =20 There may be a considerable performance cost with an excessively misaligned kernel. Therefore, a loader should typically try each @@ -808,13 +808,13 @@ Protocol: 2.09+ parameters passing mechanism. The definition of struct setup_data is as follow:: =20 - struct setup_data { - u64 next; - u32 type; - u32 len; - u8 data[0]; - }; - + struct setup_data { + __u64 next; + __u32 type; + __u32 len; + __u8 data[]; + } + =20 Where, the next is a 64-bit physical pointer to the next node of linked list, the next field of the last node is 0; the type is used to identify the contents of data; the len is the length of data @@ -834,12 +834,12 @@ Protocol: 2.09+ Thus setup_indirect struct and SETUP_INDIRECT type were introduced in protocol 2.15:: =20 - struct setup_indirect { - __u32 type; - __u32 reserved; /* Reserved, must be set to zero. */ - __u64 len; - __u64 addr; - }; + struct setup_indirect { + __u32 type; + __u32 reserved; /* Reserved, must be set to zero. */ + __u64 len; + __u64 addr; + }; =20 The type member is a SETUP_INDIRECT | SETUP_* type. However, it cannot be SETUP_INDIRECT itself since making the setup_indirect a tree structure @@ -849,17 +849,17 @@ Protocol: 2.09+ Let's give an example how to point to SETUP_E820_EXT data using setup_in= direct. In this case setup_data and setup_indirect will look like this:: =20 - struct setup_data { - __u64 next =3D 0 or ; - __u32 type =3D SETUP_INDIRECT; - __u32 len =3D sizeof(setup_indirect); - __u8 data[sizeof(setup_indirect)] =3D struct setup_indirect { - __u32 type =3D SETUP_INDIRECT | SETUP_E820_EXT; - __u32 reserved =3D 0; - __u64 len =3D ; - __u64 addr =3D ; - } - } + struct setup_data { + .next =3D 0, /* or */ + .type =3D SETUP_INDIRECT, + .len =3D sizeof(setup_indirect), + .data[sizeof(setup_indirect)] =3D (struct setup_indirect) { + .type =3D SETUP_INDIRECT | SETUP_E820_EXT, + .reserved =3D 0, + .len =3D , + .addr =3D , + }, + } =20 .. note:: SETUP_INDIRECT | SETUP_NONE objects cannot be properly distinguished @@ -896,19 +896,19 @@ Offset/size: 0x260/4 =20 The kernel runtime start address is determined by the following algorith= m:: =20 - if (relocatable_kernel) { - if (load_address < pref_address) - load_address =3D pref_address; - runtime_start =3D align_up(load_address, kernel_alignment); - } else { - runtime_start =3D pref_address; - } + if (relocatable_kernel) { + if (load_address < pref_address) + load_address =3D pref_address; + runtime_start =3D align_up(load_address, kernel_alignment); + } else { + runtime_start =3D pref_address; + } =20 Hence the necessary memory window location and size can be estimated by a boot loader as:: =20 - memory_window_start =3D runtime_start; - memory_window_size =3D init_size; + memory_window_start =3D runtime_start; + memory_window_size =3D init_size; =20 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D Field name: handover_offset @@ -938,12 +938,12 @@ The kernel_info =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 The relationships between the headers are analogous to the various data -sections: +sections:: =20 setup_header =3D .data boot_params/setup_data =3D .bss =20 -What is missing from the above list? That's right: +What is missing from the above list? That's right:: =20 kernel_info =3D .rodata =20 @@ -975,22 +975,22 @@ after kernel_info_var_len_data label. Each chunk of v= ariable size data has to be prefixed with header/magic and its size, e.g.:: =20 kernel_info: - .ascii "LToP" /* Header, Linux top (structure). */ - .long kernel_info_var_len_data - kernel_info - .long kernel_info_end - kernel_info - .long 0x01234567 /* Some fixed size data for the bootload= ers. */ + .ascii "LToP" /* Header, Linux top (structure). */ + .long kernel_info_var_len_data - kernel_info + .long kernel_info_end - kernel_info + .long 0x01234567 /* Some fixed size data for the bootloaders. */ kernel_info_var_len_data: - example_struct: /* Some variable size data for the bootl= oaders. */ - .ascii "0123" /* Header/Magic. */ - .long example_struct_end - example_struct - .ascii "Struct" - .long 0x89012345 + example_struct: /* Some variable size data for the bootloaders. */ + .ascii "0123" /* Header/Magic. */ + .long example_struct_end - example_struct + .ascii "Struct" + .long 0x89012345 example_struct_end: - example_strings: /* Some variable size data for the bootl= oaders. */ - .ascii "ABCD" /* Header/Magic. */ - .long example_strings_end - example_strings - .asciz "String_0" - .asciz "String_1" + example_strings: /* Some variable size data for the bootloaders. */ + .ascii "ABCD" /* Header/Magic. */ + .long example_strings_end - example_strings + .asciz "String_0" + .asciz "String_1" example_strings_end: kernel_info_end: =20 @@ -1139,67 +1139,63 @@ mode segment. =20 Such a boot loader should enter the following fields in the header:: =20 - unsigned long base_ptr; /* base address for real-mode segment */ + unsigned long base_ptr; /* base address for real-mode segment */ =20 - if ( setup_sects =3D=3D 0 ) { - setup_sects =3D 4; - } + if (setup_sects =3D=3D 0) + setup_sects =3D 4; =20 - if ( protocol >=3D 0x0200 ) { - type_of_loader =3D ; - if ( loading_initrd ) { - ramdisk_image =3D ; - ramdisk_size =3D ; - } + if (protocol >=3D 0x0200) { + type_of_loader =3D ; + if (loading_initrd) { + ramdisk_image =3D ; + ramdisk_size =3D ; + } =20 - if ( protocol >=3D 0x0202 && loadflags & 0x01 ) - heap_end =3D 0xe000; - else - heap_end =3D 0x9800; + if (protocol >=3D 0x0202 && loadflags & 0x01) + heap_end =3D 0xe000; + else + heap_end =3D 0x9800; =20 - if ( protocol >=3D 0x0201 ) { - heap_end_ptr =3D heap_end - 0x200; - loadflags |=3D 0x80; /* CAN_USE_HEAP */ - } + if (protocol >=3D 0x0201) { + heap_end_ptr =3D heap_end - 0x200; + loadflags |=3D 0x80; /* CAN_USE_HEAP */ + } =20 - if ( protocol >=3D 0x0202 ) { - cmd_line_ptr =3D base_ptr + heap_end; - strcpy(cmd_line_ptr, cmdline); - } else { - cmd_line_magic =3D 0xA33F; - cmd_line_offset =3D heap_end; - setup_move_size =3D heap_end + strlen(cmdline)+1; - strcpy(base_ptr+cmd_line_offset, cmdline); - } - } else { - /* Very old kernel */ + if (protocol >=3D 0x0202) { + cmd_line_ptr =3D base_ptr + heap_end; + strcpy(cmd_line_ptr, cmdline); + } else { + cmd_line_magic =3D 0xA33F; + cmd_line_offset =3D heap_end; + setup_move_size =3D heap_end + strlen(cmdline) + 1; + strcpy(base_ptr + cmd_line_offset, cmdline); + } + } else { + /* Very old kernel */ =20 - heap_end =3D 0x9800; + heap_end =3D 0x9800; =20 - cmd_line_magic =3D 0xA33F; - cmd_line_offset =3D heap_end; + cmd_line_magic =3D 0xA33F; + cmd_line_offset =3D heap_end; =20 - /* A very old kernel MUST have its real-mode code - loaded at 0x90000 */ + /* A very old kernel MUST have its real-mode code loaded at 0x90000 */ + if (base_ptr !=3D 0x90000) { + /* Copy the real-mode kernel */ + memcpy(0x90000, base_ptr, (setup_sects + 1) * 512); + base_ptr =3D 0x90000; /* Relocated */ + } =20 - if ( base_ptr !=3D 0x90000 ) { - /* Copy the real-mode kernel */ - memcpy(0x90000, base_ptr, (setup_sects+1)*512); - base_ptr =3D 0x90000; /* Relocated */ - } + strcpy(0x90000 + cmd_line_offset, cmdline); =20 - strcpy(0x90000+cmd_line_offset, cmdline); - - /* It is recommended to clear memory up to the 32K mark */ - memset(0x90000 + (setup_sects+1)*512, 0, - (64-(setup_sects+1))*512); - } + /* It is recommended to clear memory up to the 32K mark */ + memset(0x90000 + (setup_sects + 1) * 512, 0, (64 - (setup_sects + 1)) *= 512); + } =20 =20 Loading The Rest of The Kernel =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D =20 -The 32-bit (non-real-mode) kernel starts at offset (setup_sects+1)*512 +The 32-bit (non-real-mode) kernel starts at offset (setup_sects + 1) * 512 in the kernel file (again, if setup_sects =3D=3D 0 the real value is 4.) It should be loaded at address 0x10000 for Image/zImage kernels and 0x100000 for bzImage kernels. @@ -1207,8 +1203,8 @@ It should be loaded at address 0x10000 for Image/zIma= ge kernels and The kernel is a bzImage kernel if the protocol >=3D 2.00 and the 0x01 bit (LOAD_HIGH) in the loadflags field is set:: =20 - is_bzImage =3D (protocol >=3D 0x0200) && (loadflags & 0x01); - load_address =3D is_bzImage ? 0x100000 : 0x10000; + is_bzImage =3D (protocol >=3D 0x0200) && (loadflags & 0x01); + load_address =3D is_bzImage ? 0x100000 : 0x10000; =20 Note that Image/zImage kernels can be up to 512K in size, and thus use the entire 0x10000-0x90000 range of memory. This means it is pretty @@ -1282,19 +1278,20 @@ es =3D ss. =20 In our example from above, we would do:: =20 - /* Note: in the case of the "old" kernel protocol, base_ptr must - be =3D=3D 0x90000 at this point; see the previous sample code */ + /* + * Note: in the case of the "old" kernel protocol, base_ptr must + * be =3D=3D 0x90000 at this point; see the previous sample code. + */ + seg =3D base_ptr >> 4; =20 - seg =3D base_ptr >> 4; + cli(); /* Enter with interrupts disabled! */ =20 - cli(); /* Enter with interrupts disabled! */ + /* Set up the real-mode kernel stack */ + _SS =3D seg; + _SP =3D heap_end; =20 - /* Set up the real-mode kernel stack */ - _SS =3D seg; - _SP =3D heap_end; - - _DS =3D _ES =3D _FS =3D _GS =3D seg; - jmp_far(seg+0x20, 0); /* Run the kernel */ + _DS =3D _ES =3D _FS =3D _GS =3D seg; + jmp_far(seg + 0x20, 0); /* Run the kernel */ =20 If your boot sector accesses a floppy drive, it is recommended to switch off the floppy motor before running the kernel, since the @@ -1349,7 +1346,7 @@ from offset 0x01f1 of kernel image on should be loade= d into struct boot_params and examined. The end of setup header can be calculated as follow:: =20 - 0x0202 + byte value at offset 0x0201 + 0x0202 + byte value at offset 0x0201 =20 In addition to read/modify/write the setup header of the struct boot_params as that of 16-bit boot protocol, the boot loader should @@ -1385,7 +1382,7 @@ Then, the setup header at offset 0x01f1 of kernel ima= ge on should be loaded into struct boot_params and examined. The end of setup header can be calculated as follows:: =20 - 0x0202 + byte value at offset 0x0201 + 0x0202 + byte value at offset 0x0201 =20 In addition to read/modify/write the setup header of the struct boot_params as that of 16-bit boot protocol, the boot loader should @@ -1427,7 +1424,7 @@ execution context provided by the EFI firmware. =20 The function prototype for the handover entry point looks like this:: =20 - efi_stub_entry(void *handle, efi_system_table_t *table, struct boot_pa= rams *bp) + void efi_stub_entry(void *handle, efi_system_table_t *table, struct boot= _params *bp); =20 'handle' is the EFI image handle passed to the boot loader by the EFI firmware, 'table' is the EFI system table - these are the first two --=20 2.43.0.rc1.1336.g36b5255a03ac From nobody Sat Feb 7 15:15:19 2026 Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.15]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 045331BBBC4; Thu, 28 Nov 2024 15:26:21 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=192.198.163.15 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1732807583; cv=none; b=pMzh0X4fYjyNx/Fs15YgOf8NurChnzsw6dVcLEcinHXsCw0jvL4Ebv0FMGLWx2d8A7WFi+qnI3LJvrH0x9XZbRz7R8wtoVziHLiV3Wo6VvTR3TmzZjwk0a8fC52QK78G/I0OE2iN8AmxfxC3hpZVk/KeOE1nhIpBhTSAOX9Jq1E= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1732807583; c=relaxed/simple; bh=C2WbLanRa3XQnGIOT8T4PZUgLJotIUflhXkwm+x1xNI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=b0UVtqBeXCqx9y+PrUuATcCoFQgC9tuys1cYcxFYmHZO1Pmse9/pGMRwVrAa+b0SXMfUj+dvRyipcjjZjLejXM7WmatfEW/iwyBS5rFQeTBKDwopYFEyZyySU0OpEsNYC7nhirdbz/35LK32iI6HQz97uYqfbq60x1334S7ile4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linux.intel.com; spf=none smtp.mailfrom=linux.intel.com; dkim=pass (2048-bit key) header.d=intel.com header.i=@intel.com header.b=MWhdI4EN; arc=none smtp.client-ip=192.198.163.15 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linux.intel.com Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=linux.intel.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=intel.com header.i=@intel.com header.b="MWhdI4EN" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1732807582; x=1764343582; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=C2WbLanRa3XQnGIOT8T4PZUgLJotIUflhXkwm+x1xNI=; b=MWhdI4ENasKRPJZPit8+7/J03/mrIt6T3J6OxGYvKzPDT43kL9Mp46B5 NU3yVpcQiS5K1ieswKDzmrF23EBuDnkQ0DGlaRZz3HoYIWDywP1R62dFh HZde/qi8JlyIDG+wy9dc3S42CnjxB51fMUf7ZJgmV4XQEb/sijUu2jCad H5oGBEVzgYIvgnPTsHbJ4XCArWz3ZTTIEt95xFHtmV5SPXGxH4klClz8m FVzk2z8llKYLCVAaW7nWZnMkLFjlbLymKe8INFehP/zWei+ZSGG0oUTg5 wKukx18/xnHdpLECc3WKnYbOo6VXTTWcys/U9MQZ565hW8xYgZvgG2OXV A==; X-CSE-ConnectionGUID: c6HPAiP/TKS1QjsiZdIcvw== X-CSE-MsgGUID: fipFBNlQR3e1Q0Y9bi+Urw== X-IronPort-AV: E=McAfee;i="6700,10204,11270"; a="33175820" X-IronPort-AV: E=Sophos;i="6.12,192,1728975600"; d="scan'208";a="33175820" Received: from fmviesa009.fm.intel.com ([10.60.135.149]) by fmvoesa109.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 28 Nov 2024 07:25:54 -0800 X-CSE-ConnectionGUID: jO2doY9gSx28IFhRjOYgLA== X-CSE-MsgGUID: 1qkhgn/oSS2bgQ30GgDfWw== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.12,192,1728975600"; d="scan'208";a="92730961" Received: from black.fi.intel.com ([10.237.72.28]) by fmviesa009.fm.intel.com with ESMTP; 28 Nov 2024 07:25:51 -0800 Received: by black.fi.intel.com (Postfix, from userid 1003) id A4EF8598; Thu, 28 Nov 2024 17:25:50 +0200 (EET) From: Andy Shevchenko To: Andy Shevchenko , linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org Cc: Thomas Gleixner , Ingo Molnar , Borislav Petkov , Dave Hansen , x86@kernel.org, "H. Peter Anvin" , Jonathan Corbet Subject: [PATCH v1 2/3] x86/Documentation: Align Note Blocks style Date: Thu, 28 Nov 2024 17:23:39 +0200 Message-ID: <20241128152546.2396782-3-andriy.shevchenko@linux.intel.com> X-Mailer: git-send-email 2.43.0.rc1.1336.g36b5255a03ac In-Reply-To: <20241128152546.2396782-1-andriy.shevchenko@linux.intel.com> References: <20241128152546.2396782-1-andriy.shevchenko@linux.intel.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" The file collects pieces from different epochs and hence has unaligned style of the Note Blocks (in terms of reStructuredText specification). Align the style to be the same structured: - start the text under 't' column from '.. note::' directive - convert a couple of plain text notes to use '.. note::' directive Signed-off-by: Andy Shevchenko Acked-by: Dave Hansen --- Documentation/arch/x86/boot.rst | 40 +++++++++++++++++---------------- 1 file changed, 21 insertions(+), 19 deletions(-) diff --git a/Documentation/arch/x86/boot.rst b/Documentation/arch/x86/boot.= rst index 17a7da883895..069073ecc87e 100644 --- a/Documentation/arch/x86/boot.rst +++ b/Documentation/arch/x86/boot.rst @@ -77,7 +77,7 @@ Protocol 2.14 BURNT BY INCORRECT COMMIT Protocol 2.15 (Kernel 5.5) Added the kernel_info and kernel_info.setup_typ= e_max. =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 - .. note:: +.. note:: The protocol version number should be changed only if the setup header is changed. There is no need to update the version number if boot_par= ams or kernel_info are changed. Additionally, it is recommended to use @@ -229,14 +229,14 @@ Offset/Size Proto Name Meaning =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 .. note:: - (1) For backwards compatibility, if the setup_sects field contains 0, the - real value is 4. + (1) For backwards compatibility, if the setup_sects field contains 0, + the real value is 4. =20 - (2) For boot protocol prior to 2.04, the upper two bytes of the syssize - field are unusable, which means the size of a bzImage kernel - cannot be determined. + (2) For boot protocol prior to 2.04, the upper two bytes of the syssi= ze + field are unusable, which means the size of a bzImage kernel + cannot be determined. =20 - (3) Ignored, but safe to set, for boot protocols 2.02-2.09. + (3) Ignored, but safe to set, for boot protocols 2.02-2.09. =20 If the "HdrS" (0x53726448) magic number is not found at offset 0x202, the boot protocol version is "old". Loading an old kernel, the @@ -265,7 +265,7 @@ All general purpose boot loaders should write the field= s marked nonstandard address should fill in the fields marked (reloc); other boot loaders can ignore those fields. =20 -The byte order of all fields is littleendian (this is x86, after all.) +The byte order of all fields is little endian (this is x86, after all.) =20 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D Field name: setup_sects @@ -1206,10 +1206,11 @@ bit (LOAD_HIGH) in the loadflags field is set:: is_bzImage =3D (protocol >=3D 0x0200) && (loadflags & 0x01); load_address =3D is_bzImage ? 0x100000 : 0x10000; =20 -Note that Image/zImage kernels can be up to 512K in size, and thus use -the entire 0x10000-0x90000 range of memory. This means it is pretty -much a requirement for these kernels to load the real-mode part at -0x90000. bzImage kernels allow much more flexibility. +.. note:: + Image/zImage kernels can be up to 512K in size, and thus use the enti= re + 0x10000-0x90000 range of memory. This means it is pretty much a + requirement for these kernels to load the real-mode part at 0x90000. + bzImage kernels allow much more flexibility. =20 Special Command Line Options =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D @@ -1439,12 +1440,13 @@ The boot loader *must* fill out the following field= s in bp:: =20 All other fields should be zero. =20 -NOTE: The EFI Handover Protocol is deprecated in favour of the ordinary PE= /COFF - entry point, combined with the LINUX_EFI_INITRD_MEDIA_GUID based ini= trd - loading protocol (refer to [0] for an example of the bootloader side= of - this), which removes the need for any knowledge on the part of the E= FI - bootloader regarding the internal representation of boot_params or a= ny - requirements/limitations regarding the placement of the command line - and ramdisk in memory, or the placement of the kernel image itself. +.. note:: + The EFI Handover Protocol is deprecated in favour of the ordinary PE/= COFF + entry point, combined with the LINUX_EFI_INITRD_MEDIA_GUID based init= rd + loading protocol (refer to [0] for an example of the bootloader side = of + this), which removes the need for any knowledge on the part of the EFI + bootloader regarding the internal representation of boot_params or any + requirements/limitations regarding the placement of the command line + and ramdisk in memory, or the placement of the kernel image itself. =20 [0] https://github.com/u-boot/u-boot/commit/ec80b4735a593961fe701cc3a5d717= d4739b0fd0 --=20 2.43.0.rc1.1336.g36b5255a03ac From nobody Sat Feb 7 15:15:19 2026 Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.9]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 7060D1B85FA; Thu, 28 Nov 2024 15:26:01 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=192.198.163.9 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1732807566; cv=none; b=cSHrCEgB+u2oN5n7NYJFnM6qCRPXlaa5dZotnoqAOm6oaMe0TXFQyzQCDmxFeMQOwTb1Ov8c3sKRIrvv1HbHeBxtt+DJsoxG51xAdLCNFLpyHC+dC2yd1r2cmjjaijYB/khsq0r1bMLw9+wCRqn46mIFRryxtE8tpoYjkURG/qU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1732807566; c=relaxed/simple; bh=1ZmSgvBb2pwzdo6/2+ajRYrL3ptMyaLsPP92DvTk+ok=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=I8Z5SIOdISKGws4zNyX0O7luZW4Sv4druSfPRUEX/1/GrbcjRZlP3vimRNkJ6R/sb2AituzZeZZGQ1iQ4D5KcDGEyFym8HnEEIOkyvPwKjqOEIdvrBEPkX1qO2/yGLWFFltZRlmD+hf8A1j2zbTui9uNRrwu3qD5pzyBPHM0Yyo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linux.intel.com; spf=none smtp.mailfrom=linux.intel.com; dkim=pass (2048-bit key) header.d=intel.com header.i=@intel.com header.b=U4f2V+0R; arc=none smtp.client-ip=192.198.163.9 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linux.intel.com Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=linux.intel.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=intel.com header.i=@intel.com header.b="U4f2V+0R" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1732807561; x=1764343561; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=1ZmSgvBb2pwzdo6/2+ajRYrL3ptMyaLsPP92DvTk+ok=; b=U4f2V+0RZ8OATVAuG4cwxPVJ8uZpXktAJlK7fjNnO8k28OmaTJK1Ua54 wCdOCoH/ibfv9v275HYJhSDVZOuBbhM5XkjAhmUOro74d9w6QXe9SOSpy oESgMV35UrNpOAGe2iYOcRsCtZjRWzszayMxYDKyU11ZiT1RCAHh4HR7s ZR2BzhBSxErUvVZmq6XXfUvgDfnmdL5V68E4Ioip9QaBrpYFs8cdD/Frr z5oPDnIhhVphN8M9/tijglJe+Tg6ZbTlRTzk9dBVDHhPiHlwhIIsfeEuJ /WYUGVzRuR/u2qG/K41rFJdMlff1qnUIkm2e/eFCvKTqczQwnFjoGUqXd Q==; X-CSE-ConnectionGUID: OimlX63PRTeFSCvzDQwVKQ== X-CSE-MsgGUID: iuRUHS3zSfqalAS8XxNohg== X-IronPort-AV: E=McAfee;i="6700,10204,11270"; a="43711934" X-IronPort-AV: E=Sophos;i="6.12,192,1728975600"; d="scan'208";a="43711934" Received: from orviesa002.jf.intel.com ([10.64.159.142]) by fmvoesa103.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 28 Nov 2024 07:25:55 -0800 X-CSE-ConnectionGUID: Jswr1ClCTRy57oZIJcfozA== X-CSE-MsgGUID: 4top4WzTQCGRgcxwvRhuhw== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.12,192,1728975600"; d="scan'208";a="123119571" Received: from black.fi.intel.com ([10.237.72.28]) by orviesa002.jf.intel.com with ESMTP; 28 Nov 2024 07:25:52 -0800 Received: by black.fi.intel.com (Postfix, from userid 1003) id AFCA94F4; Thu, 28 Nov 2024 17:25:50 +0200 (EET) From: Andy Shevchenko To: Andy Shevchenko , linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org Cc: Thomas Gleixner , Ingo Molnar , Borislav Petkov , Dave Hansen , x86@kernel.org, "H. Peter Anvin" , Jonathan Corbet Subject: [PATCH v1 3/3] x86/Documentation: Elaborate Intel MID device list Date: Thu, 28 Nov 2024 17:23:40 +0200 Message-ID: <20241128152546.2396782-4-andriy.shevchenko@linux.intel.com> X-Mailer: git-send-email 2.43.0.rc1.1336.g36b5255a03ac In-Reply-To: <20241128152546.2396782-1-andriy.shevchenko@linux.intel.com> References: <20241128152546.2396782-1-andriy.shevchenko@linux.intel.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Intel MID includes several SoCs in the family, elaborate this in the respective line of the documentation. Signed-off-by: Andy Shevchenko Acked-by: Dave Hansen --- Documentation/arch/x86/boot.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/arch/x86/boot.rst b/Documentation/arch/x86/boot.= rst index 069073ecc87e..76f53d3450e7 100644 --- a/Documentation/arch/x86/boot.rst +++ b/Documentation/arch/x86/boot.rst @@ -754,7 +754,7 @@ Protocol: 2.07+ 0x00000000 The default x86/PC environment 0x00000001 lguest 0x00000002 Xen - 0x00000003 Moorestown MID + 0x00000003 Intel MID (Moorestown, CloverTrail, Merrifield, Moorefield) 0x00000004 CE4100 TV Platform =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 --=20 2.43.0.rc1.1336.g36b5255a03ac