Annotation of sys/arch/i386/stand/biosboot/biosboot.8, Revision 1.1
1.1 ! nbrk 1: .\" $OpenBSD: biosboot.8,v 1.22 2007/05/31 19:20:03 jmc Exp $
! 2: .\"
! 3: .\" Copyright (c) 2003 Tom Cosgrove <tom.cosgrove@arches-consulting.com>
! 4: .\" Copyright (c) 1997 Michael Shalayeff
! 5: .\" All rights reserved.
! 6: .\"
! 7: .\" Redistribution and use in source and binary forms, with or without
! 8: .\" modification, are permitted provided that the following conditions
! 9: .\" are met:
! 10: .\" 1. Redistributions of source code must retain the above copyright
! 11: .\" notice, this list of conditions and the following disclaimer.
! 12: .\" 2. Redistributions in binary form must reproduce the above copyright
! 13: .\" notice, this list of conditions and the following disclaimer in the
! 14: .\" documentation and/or other materials provided with the distribution.
! 15: .\"
! 16: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
! 17: .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
! 18: .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
! 19: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
! 20: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
! 21: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
! 22: .\" OR SERVICES; LOSS OF MIND, USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
! 23: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
! 24: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
! 25: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
! 26: .\" SUCH DAMAGE.
! 27: .\"
! 28: .Dd $Mdocdate: May 31 2007 $
! 29: .Dt BIOSBOOT 8 i386
! 30: .Os
! 31: .Sh NAME
! 32: .Nm biosboot
! 33: .Nd
! 34: i386-specific first-stage system bootstrap
! 35: .Sh DESCRIPTION
! 36: This small program (roughly 512 bytes of code) is responsible for
! 37: loading the second-stage
! 38: .Xr boot 8
! 39: program (typically /boot), which in turn will load the kernel.
! 40: .Pp
! 41: .Nm
! 42: must be installed by
! 43: .Xr installboot 8 .
! 44: As part of the installation,
! 45: .Xr installboot 8
! 46: patches
! 47: .Nm
! 48: with information about the location of
! 49: .Xr boot 8
! 50: on disk.
! 51: Specifically, it writes the filesystem block number of
! 52: .Xr boot 8 's
! 53: inode,
! 54: the offset within this block of the inode,
! 55: and various filesystem parameters (taken from the superblock)
! 56: required to convert filesystem blocks to disk sectors.
! 57: .Pp
! 58: You must re-run
! 59: .Xr installboot 8
! 60: whenever
! 61: .Xr boot 8
! 62: is changed, as its inode may change.
! 63: While it should not be necessary,
! 64: it may also be advisable to re-run
! 65: .Xr installboot 8
! 66: if you move your disk between machines and/or controllers.
! 67: .Pp
! 68: When
! 69: .Nm
! 70: receives control from either the BIOS or the
! 71: master boot record (MBR) it will print the message:
! 72: .Pp
! 73: .Dl Loading
! 74: .Pp
! 75: followed by a dot for every filesystem block it attempts to load.
! 76: If /boot is loaded successfully,
! 77: .Nm
! 78: will put the cursor on the next line just before
! 79: transferring control to the newly-loaded program.
! 80: .Pp
! 81: If possible,
! 82: .Nm
! 83: will read disk sectors using calls detailed in the Phoenix
! 84: Enhanced Disk Drive Specification (EDD, sometimes known as LBA, reads).
! 85: It will fall back to CHS reads only if EDD calls are not available.
! 86: However, to allow users to boot on hardware that claims LBA capability,
! 87: but which requires CHS reads in order to boot,
! 88: the user may hold down either Shift key during boot.
! 89: If
! 90: .Nm
! 91: detects this, it will force itself to use CHS calls, ignoring
! 92: any LBA capability.
! 93: This will of course prevent booting if /boot lies above the 8 GB
! 94: CHS limit.
! 95: There is an exported symbol
! 96: .Dq force_chs
! 97: of type u_int8_t
! 98: which may be set to 1 to force CHS reads always.
! 99: (However, no tool is currently provided to set this flag.)
! 100: .Sh DIAGNOSTICS
! 101: .Nm
! 102: prints a
! 103: .Sq !\&
! 104: before the
! 105: .Dq Loading
! 106: message if it is being forced to use CHS rather than LBA reads
! 107: (by the user holding down either Shift key during boot,
! 108: or having set the
! 109: .Dq force_chs
! 110: flag in the boot sector).
! 111: .Pp
! 112: .Nm
! 113: prints a
! 114: .Sq ;\&
! 115: after the
! 116: .Dq Loading
! 117: message if it is going to use CHS reads for any reason.
! 118: For example, when booting from floppy or CD-ROM.
! 119: .Pp
! 120: .Nm
! 121: may fail with any of the following error messages:
! 122: .Bl -tag -width ERR_X__
! 123: .It Er ERR I
! 124: Too many indirect blocks.
! 125: .Nm
! 126: is capable of reading the direct blocks in
! 127: .Xr boot 8 's
! 128: inode (the location of which is patched into
! 129: .Nm
! 130: by
! 131: .Xr installboot 8 )
! 132: and the first indirect block,
! 133: but it is not capable of reading further indirect blocks.
! 134: This error indicates that further such indirect blocks were found.
! 135: The system will not be able to boot.
! 136: .Pp
! 137: This is unlikely to ever happen in practice, as
! 138: .Xr boot 8
! 139: has to be quite large for this to be an issue.
! 140: The smallest possible filesystem block size is 512 bytes
! 141: (one sector per filesystem block).
! 142: On such a system, there are 140 filesystem blocks that
! 143: .Nm
! 144: can read, so
! 145: .Xr boot 8
! 146: can be up to 70 KB.
! 147: .Pp
! 148: However, even on floppy disks the filesystem block size is 1024 bytes.
! 149: This allows
! 150: .Xr boot 8
! 151: to occupy up to 268 disk blocks,
! 152: i.e. to be 268 KB.
! 153: On hard disks (default filesystem block size 16 KB)
! 154: 4,108 disk blocks are available, to allow
! 155: .Xr boot 8
! 156: to be over 64 MB in size!
! 157: (Only direct blocks are required for
! 158: .Xr boot 8 s
! 159: of up to 192 KB.)
! 160: .It Er ERR M
! 161: Bad magic.
! 162: The ELF
! 163: .Dq magic number
! 164: \e7fELF in
! 165: .Xr boot 8 's
! 166: header was not found.
! 167: This indicates that the first block of
! 168: .Xr boot 8
! 169: was not read correctly.
! 170: This could be due to disk corruption,
! 171: failing to run
! 172: .Xr installboot 8 ,
! 173: giving an invalid
! 174: .Xr boot 8
! 175: program as the
! 176: .Ar boot
! 177: argument to
! 178: .Xr installboot 8 ,
! 179: or
! 180: incorrect geometry translation.
! 181: .It Er ERR R
! 182: Read error.
! 183: The BIOS returned an error indication when
! 184: .Nm
! 185: attempted to read a disk sector.
! 186: This might be any media error, including bad sectors (common on floppy disks),
! 187: and invalid sectors (can occur with bad geometry translations).
! 188: .Pp
! 189: If this error occurs during an LBA boot (no
! 190: .Sq ;\&
! 191: after
! 192: .Dq Loading ) ,
! 193: then a CHS boot may succeed.
! 194: To do this, you should reboot, then hold down either Shift key
! 195: before
! 196: .Nm
! 197: starts.
! 198: You should see a
! 199: .Sq !\&
! 200: before
! 201: .Dq Loading
! 202: as confirmation that your
! 203: override was accepted.
! 204: .It Er ERR X
! 205: Can't boot.
! 206: Issued when trying to read sectors in CHS mode,
! 207: but the BIOS call
! 208: .Em get\ drive\ parameters
! 209: failed or gave a value of 0 for the number of sectors per track.
! 210: In either case, it is not possible for
! 211: .Nm
! 212: to calculate the (cylinder, head, sector) values required to
! 213: read any sectors.
! 214: .El
! 215: .Sh NOTES
! 216: Using
! 217: .Nm
! 218: as the MBR,
! 219: as has been done in the past,
! 220: is not recommended, and is not supported.
! 221: Instead, create a single
! 222: .Xr fdisk 8
! 223: partition that spans the entire disk.
! 224: .Pp
! 225: Despite the support for
! 226: .Xr boot 8
! 227: over the 8 GB boundary,
! 228: good
! 229: .Xr disklabel 8
! 230: partitioning practices should still be followed.
! 231: .Sh FILES
! 232: .Bl -tag -width /usr/mdec/biosbootxx -compact
! 233: .It Pa /usr/mdec/mbr
! 234: Master Boot Record block
! 235: .It Pa /usr/mdec/biosboot
! 236: primary bootstrap
! 237: .It Pa /boot
! 238: secondary bootstrap
! 239: .It Pa /usr/mdec/pxeboot
! 240: PXE bootstrap
! 241: .It Pa /bsd
! 242: .Ox
! 243: kernel
! 244: .It Pa /bsd.mp
! 245: .Ox
! 246: kernel for multi-processor machines
! 247: .It Pa /bsd.rd
! 248: .Ox
! 249: kernel for installation/recovery
! 250: .El
! 251: .Sh SEE ALSO
! 252: .Xr boot 8 ,
! 253: .Xr boot_i386 8 ,
! 254: .Xr disklabel 8 ,
! 255: .Xr fdisk 8 ,
! 256: .Xr installboot 8 ,
! 257: .Xr pxeboot 8
! 258: .Sh HISTORY
! 259: .Nm
! 260: was originally written by Michael Shalayeff for
! 261: .Ox 2.1 .
! 262: However it was based on bootstrap code from older versions of this
! 263: operating system, other operating systems, other programs, and
! 264: other people's work.
! 265: .Pp
! 266: It was significantly revised in December 2003 by Tom Cosgrove,
! 267: in order to support LBA disk access (via the Phoenix Enhanced Disk
! 268: Drive Specification API).
! 269: At that time the internal table of disk blocks was removed, and
! 270: .Nm
! 271: modified to read filesystem block numbers from the inode.
! 272: .Sh BUGS
! 273: .Nm
! 274: should perform and verify a checksum across the entire loaded
! 275: .Xr boot 8
! 276: image,
! 277: rather than just checking the magic number in the first block.
! 278: .Pp
! 279: There is no BIOS error number reported nor is the location of the error
! 280: reported.
! 281: .Pp
! 282: You can pick your motherboard, and you can pick your BIOS,
! 283: but you can't pick your motherboard's BIOS.
CVSweb