x86/Documentation: Make Literal Blocks to follow reStructuredText specification

+162 -165

1 changed file

expand all

Documentation

arch

x86

boot.rst

+162 -165

Documentation/arch/x86/boot.rst

··· 95 95 The traditional memory map for the kernel loader, used for Image or 96 96 zImage kernels, typically looks like:: 97 97 98 - | | 99 - 0A0000 +------------------------+ 100 - | Reserved for BIOS | Do not use. Reserved for BIOS EBDA. 101 - 09A000 +------------------------+ 102 - | Command line | 103 - | Stack/heap | For use by the kernel real-mode code. 104 - 098000 +------------------------+ 105 - | Kernel setup | The kernel real-mode code. 106 - 090200 +------------------------+ 107 - | Kernel boot sector | The kernel legacy boot sector. 108 - 090000 +------------------------+ 109 - | Protected-mode kernel | The bulk of the kernel image. 110 - 010000 +------------------------+ 111 - | Boot loader | <- Boot sector entry point 0000:7C00 112 - 001000 +------------------------+ 113 - | Reserved for MBR/BIOS | 114 - 000800 +------------------------+ 115 - | Typically used by MBR | 116 - 000600 +------------------------+ 117 - | BIOS use only | 118 - 000000 +------------------------+ 98 + | | 99 + 0A0000 +------------------------+ 100 + | Reserved for BIOS | Do not use. Reserved for BIOS EBDA. 101 + 09A000 +------------------------+ 102 + | Command line | 103 + | Stack/heap | For use by the kernel real-mode code. 104 + 098000 +------------------------+ 105 + | Kernel setup | The kernel real-mode code. 106 + 090200 +------------------------+ 107 + | Kernel boot sector | The kernel legacy boot sector. 108 + 090000 +------------------------+ 109 + | Protected-mode kernel | The bulk of the kernel image. 110 + 010000 +------------------------+ 111 + | Boot loader | <- Boot sector entry point 0000:7C00 112 + 001000 +------------------------+ 113 + | Reserved for MBR/BIOS | 114 + 000800 +------------------------+ 115 + | Typically used by MBR | 116 + 000600 +------------------------+ 117 + | BIOS use only | 118 + 000000 +------------------------+ 119 119 120 120 When using bzImage, the protected-mode kernel was relocated to 121 121 0x100000 ("high memory"), and the kernel real-mode block (boot sector, ··· 142 142 For a modern bzImage kernel with boot protocol version >= 2.02, a 143 143 memory layout like the following is suggested:: 144 144 145 - ~ ~ 146 - | Protected-mode kernel | 147 - 100000 +------------------------+ 148 - | I/O memory hole | 149 - 0A0000 +------------------------+ 150 - | Reserved for BIOS | Leave as much as possible unused 151 - ~ ~ 152 - | Command line | (Can also be below the X+10000 mark) 153 - X+10000 +------------------------+ 154 - | Stack/heap | For use by the kernel real-mode code. 155 - X+08000 +------------------------+ 156 - | Kernel setup | The kernel real-mode code. 157 - | Kernel boot sector | The kernel legacy boot sector. 158 - X +------------------------+ 159 - | Boot loader | <- Boot sector entry point 0000:7C00 160 - 001000 +------------------------+ 161 - | Reserved for MBR/BIOS | 162 - 000800 +------------------------+ 163 - | Typically used by MBR | 164 - 000600 +------------------------+ 165 - | BIOS use only | 166 - 000000 +------------------------+ 145 + ~ ~ 146 + | Protected-mode kernel | 147 + 100000 +------------------------+ 148 + | I/O memory hole | 149 + 0A0000 +------------------------+ 150 + | Reserved for BIOS | Leave as much as possible unused 151 + ~ ~ 152 + | Command line | (Can also be below the X+10000 mark) 153 + X+10000 +------------------------+ 154 + | Stack/heap | For use by the kernel real-mode code. 155 + X+08000 +------------------------+ 156 + | Kernel setup | The kernel real-mode code. 157 + | Kernel boot sector | The kernel legacy boot sector. 158 + X +------------------------+ 159 + | Boot loader | <- Boot sector entry point 0000:7C00 160 + 001000 +------------------------+ 161 + | Reserved for MBR/BIOS | 162 + 000800 +------------------------+ 163 + | Typically used by MBR | 164 + 000600 +------------------------+ 165 + | BIOS use only | 166 + 000000 +------------------------+ 167 167 168 168 ... where the address X is as low as the design of the boot loader permits. 169 169 ··· 242 242 the boot protocol version is "old". Loading an old kernel, the 243 243 following parameters should be assumed:: 244 244 245 - Image type = zImage 246 - initrd not supported 247 - Real-mode kernel must be located at 0x90000. 245 + Image type = zImage 246 + initrd not supported 247 + Real-mode kernel must be located at 0x90000. 248 248 249 249 Otherwise, the "version" field contains the protocol version, 250 250 e.g. protocol version 2.01 will contain 0x0201 in this field. When ··· 365 365 Protocol: 2.00+ 366 366 ============ ======= 367 367 368 - Contains the boot protocol version, in (major << 8)+minor format, 368 + Contains the boot protocol version, in (major << 8) + minor format, 369 369 e.g. 0x0204 for version 2.04, and 0x0a11 for a hypothetical version 370 370 10.17. 371 371 ··· 397 397 If set to a nonzero value, contains a pointer to a NUL-terminated 398 398 human-readable kernel version number string, less 0x200. This can 399 399 be used to display the kernel version to the user. This value 400 - should be less than (0x200*setup_sects). 400 + should be less than (0x200 * setup_sects). 401 401 402 402 For example, if this value is set to 0x1c00, the kernel version 403 403 number string can be found at offset 0x1e00 in the kernel file. 404 404 This is a valid value if and only if the "setup_sects" field 405 405 contains the value 15 or higher, as:: 406 406 407 - 0x1c00 < 15*0x200 (= 0x1e00) but 408 - 0x1c00 >= 14*0x200 (= 0x1c00) 407 + 0x1c00 < 15 * 0x200 (= 0x1e00) but 408 + 0x1c00 >= 14 * 0x200 (= 0x1c00) 409 409 410 - 0x1c00 >> 9 = 14, So the minimum value for setup_secs is 15. 410 + 0x1c00 >> 9 = 14, So the minimum value for setup_secs is 15. 411 411 412 412 ============ ================== 413 413 Field name: type_of_loader ··· 427 427 428 428 For example, for T = 0x15, V = 0x234, write:: 429 429 430 - type_of_loader <- 0xE4 431 - ext_loader_type <- 0x05 432 - ext_loader_ver <- 0x23 430 + type_of_loader <- 0xE4 431 + ext_loader_type <- 0x05 432 + ext_loader_ver <- 0x23 433 433 434 434 Assigned boot loader ids (hexadecimal): 435 435 ··· 686 686 If a boot loader makes use of this field, it should update the 687 687 kernel_alignment field with the alignment unit desired; typically:: 688 688 689 - kernel_alignment = 1 << min_alignment 689 + kernel_alignment = 1 << min_alignment; 690 690 691 691 There may be a considerable performance cost with an excessively 692 692 misaligned kernel. Therefore, a loader should typically try each ··· 808 808 parameters passing mechanism. The definition of struct setup_data is 809 809 as follow:: 810 810 811 - struct setup_data { 812 - u64 next; 813 - u32 type; 814 - u32 len; 815 - u8 data[0]; 816 - }; 817 - 811 + struct setup_data { 812 + __u64 next; 813 + __u32 type; 814 + __u32 len; 815 + __u8 data[]; 816 + } 817 + 818 818 Where, the next is a 64-bit physical pointer to the next node of 819 819 linked list, the next field of the last node is 0; the type is used 820 820 to identify the contents of data; the len is the length of data ··· 834 834 Thus setup_indirect struct and SETUP_INDIRECT type were introduced in 835 835 protocol 2.15:: 836 836 837 - struct setup_indirect { 838 - __u32 type; 839 - __u32 reserved; /* Reserved, must be set to zero. */ 840 - __u64 len; 841 - __u64 addr; 842 - }; 837 + struct setup_indirect { 838 + __u32 type; 839 + __u32 reserved; /* Reserved, must be set to zero. */ 840 + __u64 len; 841 + __u64 addr; 842 + }; 843 843 844 844 The type member is a SETUP_INDIRECT | SETUP_* type. However, it cannot be 845 845 SETUP_INDIRECT itself since making the setup_indirect a tree structure ··· 849 849 Let's give an example how to point to SETUP_E820_EXT data using setup_indirect. 850 850 In this case setup_data and setup_indirect will look like this:: 851 851 852 - struct setup_data { 853 - __u64 next = 0 or <addr_of_next_setup_data_struct>; 854 - __u32 type = SETUP_INDIRECT; 855 - __u32 len = sizeof(setup_indirect); 856 - __u8 data[sizeof(setup_indirect)] = struct setup_indirect { 857 - __u32 type = SETUP_INDIRECT | SETUP_E820_EXT; 858 - __u32 reserved = 0; 859 - __u64 len = <len_of_SETUP_E820_EXT_data>; 860 - __u64 addr = <addr_of_SETUP_E820_EXT_data>; 861 - } 862 - } 852 + struct setup_data { 853 + .next = 0, /* or <addr_of_next_setup_data_struct> */ 854 + .type = SETUP_INDIRECT, 855 + .len = sizeof(setup_indirect), 856 + .data[sizeof(setup_indirect)] = (struct setup_indirect) { 857 + .type = SETUP_INDIRECT | SETUP_E820_EXT, 858 + .reserved = 0, 859 + .len = <len_of_SETUP_E820_EXT_data>, 860 + .addr = <addr_of_SETUP_E820_EXT_data>, 861 + }, 862 + } 863 863 864 864 .. note:: 865 865 SETUP_INDIRECT | SETUP_NONE objects cannot be properly distinguished ··· 896 896 897 897 The kernel runtime start address is determined by the following algorithm:: 898 898 899 - if (relocatable_kernel) { 900 - if (load_address < pref_address) 901 - load_address = pref_address; 902 - runtime_start = align_up(load_address, kernel_alignment); 903 - } else { 904 - runtime_start = pref_address; 905 - } 899 + if (relocatable_kernel) { 900 + if (load_address < pref_address) 901 + load_address = pref_address; 902 + runtime_start = align_up(load_address, kernel_alignment); 903 + } else { 904 + runtime_start = pref_address; 905 + } 906 906 907 907 Hence the necessary memory window location and size can be estimated by 908 908 a boot loader as:: 909 909 910 - memory_window_start = runtime_start; 911 - memory_window_size = init_size; 910 + memory_window_start = runtime_start; 911 + memory_window_size = init_size; 912 912 913 913 ============ =============== 914 914 Field name: handover_offset ··· 938 938 =============== 939 939 940 940 The relationships between the headers are analogous to the various data 941 - sections: 941 + sections:: 942 942 943 943 setup_header = .data 944 944 boot_params/setup_data = .bss 945 945 946 - What is missing from the above list? That's right: 946 + What is missing from the above list? That's right:: 947 947 948 948 kernel_info = .rodata 949 949 ··· 975 975 be prefixed with header/magic and its size, e.g.:: 976 976 977 977 kernel_info: 978 - .ascii "LToP" /* Header, Linux top (structure). */ 979 - .long kernel_info_var_len_data - kernel_info 980 - .long kernel_info_end - kernel_info 981 - .long 0x01234567 /* Some fixed size data for the bootloaders. */ 978 + .ascii "LToP" /* Header, Linux top (structure). */ 979 + .long kernel_info_var_len_data - kernel_info 980 + .long kernel_info_end - kernel_info 981 + .long 0x01234567 /* Some fixed size data for the bootloaders. */ 982 982 kernel_info_var_len_data: 983 - example_struct: /* Some variable size data for the bootloaders. */ 984 - .ascii "0123" /* Header/Magic. */ 985 - .long example_struct_end - example_struct 986 - .ascii "Struct" 987 - .long 0x89012345 983 + example_struct: /* Some variable size data for the bootloaders. */ 984 + .ascii "0123" /* Header/Magic. */ 985 + .long example_struct_end - example_struct 986 + .ascii "Struct" 987 + .long 0x89012345 988 988 example_struct_end: 989 - example_strings: /* Some variable size data for the bootloaders. */ 990 - .ascii "ABCD" /* Header/Magic. */ 991 - .long example_strings_end - example_strings 992 - .asciz "String_0" 993 - .asciz "String_1" 989 + example_strings: /* Some variable size data for the bootloaders. */ 990 + .ascii "ABCD" /* Header/Magic. */ 991 + .long example_strings_end - example_strings 992 + .asciz "String_0" 993 + .asciz "String_1" 994 994 example_strings_end: 995 995 kernel_info_end: 996 996 ··· 1139 1139 1140 1140 Such a boot loader should enter the following fields in the header:: 1141 1141 1142 - unsigned long base_ptr; /* base address for real-mode segment */ 1142 + unsigned long base_ptr; /* base address for real-mode segment */ 1143 1143 1144 - if ( setup_sects == 0 ) { 1145 - setup_sects = 4; 1146 - } 1144 + if (setup_sects == 0) 1145 + setup_sects = 4; 1147 1146 1148 - if ( protocol >= 0x0200 ) { 1149 - type_of_loader = <type code>; 1150 - if ( loading_initrd ) { 1151 - ramdisk_image = <initrd_address>; 1152 - ramdisk_size = <initrd_size>; 1153 - } 1147 + if (protocol >= 0x0200) { 1148 + type_of_loader = <type code>; 1149 + if (loading_initrd) { 1150 + ramdisk_image = <initrd_address>; 1151 + ramdisk_size = <initrd_size>; 1152 + } 1154 1153 1155 - if ( protocol >= 0x0202 && loadflags & 0x01 ) 1156 - heap_end = 0xe000; 1157 - else 1158 - heap_end = 0x9800; 1154 + if (protocol >= 0x0202 && loadflags & 0x01) 1155 + heap_end = 0xe000; 1156 + else 1157 + heap_end = 0x9800; 1159 1158 1160 - if ( protocol >= 0x0201 ) { 1161 - heap_end_ptr = heap_end - 0x200; 1162 - loadflags |= 0x80; /* CAN_USE_HEAP */ 1163 - } 1159 + if (protocol >= 0x0201) { 1160 + heap_end_ptr = heap_end - 0x200; 1161 + loadflags |= 0x80; /* CAN_USE_HEAP */ 1162 + } 1164 1163 1165 - if ( protocol >= 0x0202 ) { 1166 - cmd_line_ptr = base_ptr + heap_end; 1167 - strcpy(cmd_line_ptr, cmdline); 1168 - } else { 1169 - cmd_line_magic = 0xA33F; 1170 - cmd_line_offset = heap_end; 1171 - setup_move_size = heap_end + strlen(cmdline)+1; 1172 - strcpy(base_ptr+cmd_line_offset, cmdline); 1173 - } 1174 - } else { 1175 - /* Very old kernel */ 1164 + if (protocol >= 0x0202) { 1165 + cmd_line_ptr = base_ptr + heap_end; 1166 + strcpy(cmd_line_ptr, cmdline); 1167 + } else { 1168 + cmd_line_magic = 0xA33F; 1169 + cmd_line_offset = heap_end; 1170 + setup_move_size = heap_end + strlen(cmdline) + 1; 1171 + strcpy(base_ptr + cmd_line_offset, cmdline); 1172 + } 1173 + } else { 1174 + /* Very old kernel */ 1176 1175 1177 - heap_end = 0x9800; 1176 + heap_end = 0x9800; 1178 1177 1179 - cmd_line_magic = 0xA33F; 1180 - cmd_line_offset = heap_end; 1178 + cmd_line_magic = 0xA33F; 1179 + cmd_line_offset = heap_end; 1181 1180 1182 - /* A very old kernel MUST have its real-mode code 1183 - loaded at 0x90000 */ 1181 + /* A very old kernel MUST have its real-mode code loaded at 0x90000 */ 1182 + if (base_ptr != 0x90000) { 1183 + /* Copy the real-mode kernel */ 1184 + memcpy(0x90000, base_ptr, (setup_sects + 1) * 512); 1185 + base_ptr = 0x90000; /* Relocated */ 1186 + } 1184 1187 1185 - if ( base_ptr != 0x90000 ) { 1186 - /* Copy the real-mode kernel */ 1187 - memcpy(0x90000, base_ptr, (setup_sects+1)*512); 1188 - base_ptr = 0x90000; /* Relocated */ 1189 - } 1188 + strcpy(0x90000 + cmd_line_offset, cmdline); 1190 1189 1191 - strcpy(0x90000+cmd_line_offset, cmdline); 1192 - 1193 - /* It is recommended to clear memory up to the 32K mark */ 1194 - memset(0x90000 + (setup_sects+1)*512, 0, 1195 - (64-(setup_sects+1))*512); 1196 - } 1190 + /* It is recommended to clear memory up to the 32K mark */ 1191 + memset(0x90000 + (setup_sects + 1) * 512, 0, (64 - (setup_sects + 1)) * 512); 1192 + } 1197 1193 1198 1194 1199 1195 Loading The Rest of The Kernel 1200 1196 ============================== 1201 1197 1202 - The 32-bit (non-real-mode) kernel starts at offset (setup_sects+1)*512 1198 + The 32-bit (non-real-mode) kernel starts at offset (setup_sects + 1) * 512 1203 1199 in the kernel file (again, if setup_sects == 0 the real value is 4.) 1204 1200 It should be loaded at address 0x10000 for Image/zImage kernels and 1205 1201 0x100000 for bzImage kernels. ··· 1203 1207 The kernel is a bzImage kernel if the protocol >= 2.00 and the 0x01 1204 1208 bit (LOAD_HIGH) in the loadflags field is set:: 1205 1209 1206 - is_bzImage = (protocol >= 0x0200) && (loadflags & 0x01); 1207 - load_address = is_bzImage ? 0x100000 : 0x10000; 1210 + is_bzImage = (protocol >= 0x0200) && (loadflags & 0x01); 1211 + load_address = is_bzImage ? 0x100000 : 0x10000; 1208 1212 1209 1213 Note that Image/zImage kernels can be up to 512K in size, and thus use 1210 1214 the entire 0x10000-0x90000 range of memory. This means it is pretty ··· 1278 1282 1279 1283 In our example from above, we would do:: 1280 1284 1281 - /* Note: in the case of the "old" kernel protocol, base_ptr must 1282 - be == 0x90000 at this point; see the previous sample code */ 1285 + /* 1286 + * Note: in the case of the "old" kernel protocol, base_ptr must 1287 + * be == 0x90000 at this point; see the previous sample code. 1288 + */ 1289 + seg = base_ptr >> 4; 1283 1290 1284 - seg = base_ptr >> 4; 1291 + cli(); /* Enter with interrupts disabled! */ 1285 1292 1286 - cli(); /* Enter with interrupts disabled! */ 1293 + /* Set up the real-mode kernel stack */ 1294 + _SS = seg; 1295 + _SP = heap_end; 1287 1296 1288 - /* Set up the real-mode kernel stack */ 1289 - _SS = seg; 1290 - _SP = heap_end; 1291 - 1292 - _DS = _ES = _FS = _GS = seg; 1293 - jmp_far(seg+0x20, 0); /* Run the kernel */ 1297 + _DS = _ES = _FS = _GS = seg; 1298 + jmp_far(seg + 0x20, 0); /* Run the kernel */ 1294 1299 1295 1300 If your boot sector accesses a floppy drive, it is recommended to 1296 1301 switch off the floppy motor before running the kernel, since the ··· 1346 1349 boot_params and examined. The end of setup header can be calculated as 1347 1350 follow:: 1348 1351 1349 - 0x0202 + byte value at offset 0x0201 1352 + 0x0202 + byte value at offset 0x0201 1350 1353 1351 1354 In addition to read/modify/write the setup header of the struct 1352 1355 boot_params as that of 16-bit boot protocol, the boot loader should ··· 1382 1385 loaded into struct boot_params and examined. The end of setup header 1383 1386 can be calculated as follows:: 1384 1387 1385 - 0x0202 + byte value at offset 0x0201 1388 + 0x0202 + byte value at offset 0x0201 1386 1389 1387 1390 In addition to read/modify/write the setup header of the struct 1388 1391 boot_params as that of 16-bit boot protocol, the boot loader should ··· 1424 1427 1425 1428 The function prototype for the handover entry point looks like this:: 1426 1429 1427 - efi_stub_entry(void *handle, efi_system_table_t *table, struct boot_params *bp) 1430 + void efi_stub_entry(void *handle, efi_system_table_t *table, struct boot_params *bp); 1428 1431 1429 1432 'handle' is the EFI image handle passed to the boot loader by the EFI 1430 1433 firmware, 'table' is the EFI system table - these are the first two

Configure Feed

Configure Feed