1
0

9boot 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538
  1. .TH 9BOOT 8
  2. .SH NAME
  3. 9boot, 9bootpbs, 9load, 9loadusb, pbs \- PC bootstrap programs
  4. .SH SYNOPSIS
  5. .I none
  6. .SH DESCRIPTION
  7. .I 9boot
  8. is a specialized Plan 9 kernel loaded by
  9. the PXE download (BOOTP/DHCP followed by TFTP)
  10. found in any reasonable Ethernet card's BIOS; it bootstraps Plan 9 by using
  11. PXE to load another
  12. .B 386
  13. or
  14. .B amd64
  15. kernel and start it.
  16. .PP
  17. .IR 9bootpbs ,
  18. .I 9load
  19. and
  20. .I 9loadusb
  21. are less-commonly-used variants
  22. that reside in a FAT file system under the name
  23. .L 9load
  24. and bootstrap Plan 9.
  25. .I 9bootpbs
  26. is like
  27. .I 9boot
  28. but it can be started by a partition boot sector (PBS),
  29. as can
  30. .I 9load
  31. and
  32. .IR 9loadusb .
  33. It is intended to PXE boot older machines without working PXE ROMs.
  34. .I 9load
  35. and
  36. .I 9loadusb
  37. read FAT file systems.
  38. .I 9loadusb
  39. will use only the BIOS's device drivers,
  40. and thus can load from FAT file systems on USB devices.
  41. In contrast,
  42. .I 9load
  43. will
  44. .I not
  45. use BIOS device drivers and cannot read USB devices.
  46. .PP
  47. This profusion of loaders is unfortunate, but at least they
  48. are compiled from the same source.
  49. The division into separate programs is dictated by the need to fit
  50. within the first 640K of memory
  51. and the need to avoid intermixing BIOS and non-BIOS disk access.
  52. .PP
  53. These programs are run automatically by the boot procedures described below;
  54. they cannot be run directly by hand.
  55. There are two bootstrap sequences:
  56. .IP \- 3
  57. PXE BIOS,
  58. .IR 9boot ,
  59. kernel
  60. .IP \-
  61. BIOS, MBR, disk partition PBS,
  62. .IR 9load ,
  63. kernel
  64. .\" .IP \-
  65. .\" BIOS, floppy PBS,
  66. .\" .IR 9load ,
  67. .\" kernel
  68. .PP
  69. In summary,
  70. Plan 9 is usually booted on a PC
  71. by using a PXE-capable BIOS to boot
  72. .I 9boot
  73. directly over the ethernet.
  74. File servers that must be able to boot when other machines are down
  75. boot directly from a Plan 9 disk partition
  76. .\" or boot floppy
  77. prepared using
  78. .B format
  79. to install the appropriate files and bootstrap sectors
  80. (see
  81. .IR prep (8)).
  82. .PP
  83. Details follow.
  84. .SS Kernel loading
  85. .I 9boot
  86. is a bootstrap program that loads and starts a program,
  87. typically the kernel, on a PC.
  88. It is run by the PXE boot ROM of a PC,
  89. which loads
  90. .I 9boot
  91. at physical address
  92. .B 0x7C00
  93. (31K).
  94. When it starts running,
  95. it switches to 32-bit mode.
  96. It then double maps the first 16Mb of physical memory to
  97. virtual addresses
  98. .B 0
  99. and
  100. .BR 0x80000000 .
  101. Only devices which can be automatically configured,
  102. e.g. most PCI ethernet adapters,
  103. will be recognised.
  104. If the file
  105. .BI /cfg/pxe/ ether
  106. can be located via a DHCP server,
  107. where
  108. .I ether
  109. is the lower-case MAC address of a recognised ethernet adapter,
  110. the contents are obtained by TFTP and used as a
  111. .IR plan9.ini (8).
  112. .I 9boot
  113. then loads the
  114. .I bootfile
  115. named within via TFTP,
  116. trying each ethernet in sequence,
  117. at the entry address specified by the kernel executable's header,
  118. usually virtual
  119. .BR 0xF0100020 .
  120. After loading,
  121. .I 9boot
  122. creates a Gnu Multiboot header in low memory for
  123. the benefit of the loaded kernel
  124. and
  125. control is passed to the entry location
  126. in 32-bit protected mode, even for 64-bit kernels.
  127. So far, only
  128. .B amd64
  129. kernels expect Multiboot headers.
  130. .PP
  131. Some options in
  132. .B plan9.ini
  133. are used by
  134. .IR 9boot :
  135. .TF bootfile=manual
  136. .TP
  137. .B console
  138. .TP
  139. .B baud
  140. Specifies the console device and baud rate if not a display.
  141. .TP
  142. .BI ether n
  143. Ethernet interfaces. These can be used to load the
  144. .I bootfile
  145. over a network.
  146. .TP
  147. .BI bootfile= bootfile
  148. Specifies the
  149. .IR bootfile .
  150. .ig
  151. .TP
  152. .B bootfile=auto
  153. Default.
  154. .TP
  155. .B bootfile=local
  156. Like
  157. .IR auto ,
  158. but do not attempt to load over the network.
  159. ..
  160. .TP
  161. .B bootfile=manual
  162. After determining which devices are available for loading from,
  163. enter prompt mode.
  164. .PD
  165. .PP
  166. .I 9load
  167. is a similar bootstrap program,
  168. loaded by the PC partition boot sector program (PBS),
  169. which usually resides in the first
  170. sector of the active disk partition.
  171. It is initially loaded at physical address
  172. .BR 0x10000 (64K);
  173. it begins execution at virtual address
  174. .BR 0x80010000 .
  175. In order to find configuration information,
  176. .I 9load
  177. searches all units on devices
  178. .\" .BR fd
  179. .\" and
  180. .B sd?[0-9]*
  181. (all
  182. .B sd
  183. devices),
  184. for a file called
  185. .\" .B plan9\eplan9.ini
  186. .\" or
  187. .B plan9.ini
  188. (see
  189. .IR plan9.ini (8))
  190. on a FAT partition named
  191. .B dos
  192. or
  193. .BR 9fat .
  194. If one is found, searching stops and the file is read into memory
  195. at physical address
  196. .B 0x1200
  197. where it can be found later by any loaded
  198. .IR bootfile .
  199. .PP
  200. When the search for
  201. .B plan9.ini
  202. is done,
  203. .I 9load
  204. proceeds to determine which bootfile to load.
  205. If there was no
  206. .I bootfile
  207. option,
  208. .I 9load
  209. searches
  210. .B sd?[0-9]*
  211. FAT partitions for a kernel
  212. (any file named
  213. .BR 9pc* ,
  214. .B 9k8*
  215. or
  216. .BR 9k10* )
  217. and if it finds exactly one kernel in a given FAT partition,
  218. chooses it.
  219. .I 9load
  220. then attempts to load the
  221. .IR bootfile .
  222. .ig
  223. unless
  224. the
  225. .B bootfile=manual
  226. option was given, in which case prompt mode is entered immediately.
  227. ..
  228. .ig
  229. If the default device is
  230. .BR fd ,
  231. .I 9load
  232. will prompt the user for input before proceeding with the
  233. default bootfile load after 5 seconds;
  234. this prompt is omitted if a
  235. .I bootfile
  236. option
  237. was given.
  238. ..
  239. .PP
  240. .I 9load
  241. prints the list of available
  242. .IR device s
  243. and
  244. enters prompt mode on encountering any error
  245. or if directed to do so by a
  246. .B bootfile=manual
  247. option.
  248. In prompt mode, the user is required to type
  249. a
  250. .IB bootfile
  251. in response to the
  252. .L Boot
  253. .L from:
  254. prompt.
  255. .br
  256. .ne 4
  257. .SS Bootfile
  258. The
  259. .I bootfile
  260. can be specified to these programs as a
  261. .B bootfile=
  262. entry in
  263. .IR plan9.ini ,
  264. or if booting from the ethernet, by a BOOTP server
  265. (see
  266. .B Kernel
  267. .B loading
  268. below).
  269. If loading with
  270. .IR 9load ,
  271. the
  272. .I bootfile
  273. may be a Plan 9 boot image compressed with
  274. .IR gzip (1).
  275. In all cases,
  276. the uncompressed kernel must be in Plan 9 boot image, ELF or ELF64 format.
  277. If the
  278. .B plan9.ini
  279. file contains multiple
  280. .B bootfile=
  281. entries,
  282. these programs will present a numerical menu of the choices; type
  283. the corresponding number to select an entry.
  284. .PP
  285. The format of the
  286. .I bootfile
  287. name is
  288. .IB device ! file
  289. or
  290. .IB device ! partition ! file\f1.
  291. If
  292. .BI ! file
  293. is omitted, the default for the particular
  294. .I device
  295. is used.
  296. Supported
  297. .I devices
  298. are
  299. .TF \fLethern
  300. .PD
  301. .TP
  302. .BI ether n
  303. Ethernet,
  304. .I 9boot
  305. only.
  306. .I N
  307. specifies the Ethernet device number.
  308. If a
  309. .I partition
  310. is specified, it is taken to be the name of a host machine
  311. from which to load the kernel.
  312. .TP
  313. .BI sd Cn
  314. Normal disk,
  315. .I 9load
  316. only.
  317. The device name format is described in
  318. .IR sd (3).
  319. A
  320. .I partition
  321. must be given and must normally
  322. name a partition containing a FAT file system.
  323. .\" The name
  324. .\" .B dos
  325. .\" refers to the first DOS partition on a given device.
  326. It is common for Plan 9 partitions to contain a small
  327. FAT file system for configuration.
  328. By convention, this partition is called
  329. .BR 9fat .
  330. There is no default partition,
  331. but if
  332. .I file
  333. is omitted,
  334. .I 9load
  335. will load a kernel directly from the named partition
  336. without any interpretation of a file system.
  337. .
  338. .ig
  339. .TP
  340. .BI fd n
  341. An MS-DOS floppy disk,
  342. .I 9load
  343. only.
  344. .I N
  345. specifies the floppy drive, either
  346. 0 or 1.
  347. The
  348. .I bootfile
  349. is the contents of the MS-DOS
  350. .IR file .
  351. There is no default file.
  352. For compatibility with normal disks, a
  353. .I partition
  354. may be given, but only
  355. .B dos
  356. is recognized:
  357. .BI fd0!dos! file\f1.
  358. ..
  359. .
  360. .TP
  361. .BI bios n
  362. USB or other BIOS device,
  363. .IR 9loadusb
  364. only.
  365. .I 9load
  366. loads from a FAT file system on
  367. the first LBA device
  368. in the BIOS's list of devices to try to boot from,
  369. using the BIOS INT 13 calls also used by
  370. .IR pbslba .
  371. It does not understand any form of partition table;
  372. see the
  373. .B EXAMPLES
  374. in
  375. .IR prep (8)
  376. for how to format such a device.
  377. .TP
  378. .BI sdB n
  379. USB or other BIOS device's partition,
  380. .IR 9loadusb
  381. only.
  382. A special case of
  383. .BI sd Cn
  384. that uses
  385. .BI bios n
  386. to read from a FAT file system.
  387. .SS Boot Sectors
  388. A copy of the Plan 9 PBS is kept in
  389. .BR /386/pbs ,
  390. but due to the ``cylinder-head-sector'' (CHS) addressing mode of old BIOSes, it can only
  391. operate up to 8.5GB into the disk.
  392. Plan 9 partitions further into the disk
  393. can only be booted using
  394. .BR /386/pbslba ,
  395. and then only if the machine's BIOS supports
  396. linear block addressing (LBA) mode for disk transfers.
  397. .PP
  398. When booting from disk,
  399. .\" or floppy,
  400. the BIOS loads the
  401. first sector of the medium at location
  402. .BR 0x7C00 .
  403. In the case of a disk, it is the master boot record (MBR).
  404. .\" In the case of a floppy, this is the PBS.
  405. The MBR copies itself to address
  406. .BR 0x600 ,
  407. finds the active partition and loads its PBS at address
  408. .BR 0x7C00 .
  409. A copy of the Plan 9 MBR is kept in
  410. .BR /386/mbr ;
  411. some commercial MBRs cannot read sectors
  412. past 2GB.
  413. The Plan 9 MBR can read sectors up to 8.5GB into
  414. the disk, and further if the BIOS supports LBA.
  415. The single file
  416. .B /386/mbr
  417. detects whether the BIOS supports LBA and
  418. acts appropriately, defaulting to CHS mode
  419. when LBA is not present.
  420. The PBSs cannot do this due to code size limitations.
  421. The Plan 9 MBR is suitable for booting non-Plan-9
  422. operating systems,
  423. and (modulo the large disk constraints just described)
  424. non-Plan-9 MBRs are suitable for booting Plan 9.
  425. .br
  426. .ne 4
  427. .SS Other facilities and caveats
  428. .I 9load
  429. parses the master boot record and Plan 9 partition tables
  430. (see
  431. .IR prep (8)),
  432. leaving partitioning information appended to the
  433. in-memory contents of
  434. .I plan9.ini
  435. for the
  436. .IR bootfile .
  437. This is used by
  438. .IR sd (3)
  439. to initialize partitions so that
  440. may be read for NVRAM contents or
  441. .IR fossil (4)
  442. or
  443. .IR kfs (4)
  444. file systems can be mounted as the root file system.
  445. On ISO 9660 CDs,
  446. .I 9load
  447. treats the contents of a file named
  448. .B /bootdisk.img
  449. as a
  450. .B 9fat
  451. partition,
  452. and it is assumed to contain the image of a FAT file system.
  453. A more extensive partitioning is typically done by
  454. .I fdisk
  455. and
  456. .I prep
  457. as part of
  458. .I termrc
  459. or
  460. .I cpurc
  461. (see
  462. .IR cpurc (8)).
  463. .I 9boot
  464. cannot parse partition tables,
  465. as it lacks disk drivers, so add
  466. .L readparts=
  467. to the machine's
  468. .B /cfg/pxe
  469. file, per
  470. .IR plan9.ini (8),
  471. if needed.
  472. .PP
  473. A
  474. control-P
  475. character typed at any time on the console causes
  476. .B 9boot
  477. to perform a hardware reset
  478. (Ctrl-Alt-Del can also be used on a PC keyboard).
  479. .PP
  480. .I 9load
  481. must be contiguously allocated on
  482. the disk.
  483. See
  484. .IR dossrv (4)
  485. for information on ensuring this.
  486. .SH FILES
  487. .TF /cfg/pxe
  488. .TP
  489. .B /386
  490. these programs reside here
  491. .TP
  492. .BI /cfg/pxe
  493. directory of configuration
  494. .RI ( plan9.ini )
  495. files on your TFTP server
  496. .PP
  497. .IB "FAT-filesystem" :\e9load
  498. .br
  499. .IB "FAT-filesystem" :\eplan9.ini
  500. .\" .br
  501. .\" .IB "FAT-filesystem" :\eplan9\eplan9.ini
  502. .SH SOURCE
  503. .TF "/sys/src/9/^(pc port ip)"
  504. .PD 0
  505. .TP
  506. .B /sys/src/boot/pc
  507. first-stage disk boot sectors (MBR, PBS)
  508. .TP
  509. .B /sys/src/9/pcboot
  510. PC-bootstrap-specific source
  511. .TP
  512. .B /sys/src/9/^(pc port ip)
  513. common kernel source
  514. .PD
  515. .SH "SEE ALSO"
  516. .IR 8l (1),
  517. .IR cons (3),
  518. .IR booting (8),
  519. .IR dhcpd (8),
  520. .IR fshalt (8),
  521. .IR mkusbboot (8),
  522. .IR plan9.ini (8),
  523. .IR prep (8)
  524. .SH BUGS
  525. Some of the work done by
  526. .I 9boot
  527. is duplicated by the loaded kernel,
  528. but usually by the same source code.
  529. .PP
  530. .B bios
  531. and
  532. .B sdB
  533. usually only work on the first LBA device in the BIOS's list of boot devices,
  534. if they work at all.
  535. .PP
  536. USB keyboards will only work with
  537. .I 9boot
  538. if the BIOS emulates a PS/2 keyboard (and that is enabled).