1.\" $NetBSD: altboot.8,v 1.11 2020/08/29 13:32:27 fcambus Exp $ 2.\" 3.\" Copyright (c) 2011 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Tohru Nishimura. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd October 7, 2013 31.Dt ALTBOOT 8 sandpoint 32.Os 33.Sh NAME 34.Nm altboot 35.Nd program to boot 36.Nx 37kernel from disk or network 38.Sh DESCRIPTION 39.Nm 40is a standalone program which works on top of a 41.Tn NAS 42product's bootloader. 43It is capable of loading a 44.Nx 45kernel from an 46.Tn IDE 47or 48.Tn SATA 49disk drive, or via network with 50.Tn NFS 51or 52.Tn TFTP 53protocol. 54.Nm 55can be stored in flash ROM. 56Typically you will first copy it from flash into RAM and then invoke 57it there to boot the 58.Nx 59kernel. 60.Pp 61.Nm 62runs in conjunction with popular 63.Tn U-Boot/PPCBoot 64bootloaders used by 65.Tn NAS 66products. 67With an appropriate boot command line, saved in the environment, 68.Nm 69can load and start a 70.Nx 71kernel without manual intervention. 72The original 73.Tn U-Boot/PPCBoot 74bootloaders remain useful and altboot works as a functional extension 75of them. 76.Sh EXAMPLES 77.Nm 78occupies less than 128KB in volume and can be stored to any vacant 79space of the system's flash. 80It is made to run at RAM address offset 0x0100'0000. 81.Tn U-Boot/PPCboot 82is instructed to copy the program to RAM in this way: 83.Pp 84.Dl => cp.b fffe0000 1000000 20000 85.Pp 86Here 0xfffe'0000 is the flash address where 87.Nm 88is stored while 0x0100'0000 is the RAM address to copy to. 89.Pp 90The invocation syntax is: 91.Pp 92.Dl => go 1000000 Ar ide:N Ar opt1 Ar opt2 ... Ar bootname 93.Bl -tag -width xx 94.It Va ide:N 95where 96.Ar N 97is a string of digits, which defines the number of connected drives on each 98PATA channel. 99This option is useful to avoid the delays, when 100.Nm 101is trying to detect a non-existing drive. 102Examples: 103.Bl -tag -width xx 104.It ide: Ns Ar 10 105A single master drive on the first channel. 106Nothing on the second channel. 107.It ide: Ns Ar 22 108A master and slave drive on both channels of the first controller. 109.It ide: Ns Ar 1111 110A master drive on each channel. 111The first two digits belong to the first 112controller, the last two to the second controller. 113.El 114.Pp 115Unspecified digits will be read as 116.Ar 0 . 117The 118.Ar ide 119option has only a meaning for PATA disks. 120Omitting it makes it default to 121.Ar ide:10 . 122.Pp 123.It Va optN 124multi, auto, ask, single, ddb, userconf, norm, quiet, verb, 125silent, debug 126.Pp 127Omitting optN makes 128.Nm 129default to multi-user mode boot. 130.Pp 131N.B., the maximum number of allowed go command arguments varies 132and depends on the 133.Tn U-Boot/PPCBoot 134buildtime configuration. 135.It Va bootname 136One of the following: 137.Pp 138.Dl nfs: Ns Ar filename 139.Dl nfs: 140.Dl tftp: Ns Ar filename 141.Dl tftp: 142.Dl wd Ns Ar Np : Ns Ar filename 143.Dl wd Ns Ar Np : 144.Dl mem: Ns Ar address 145.Dl net: 146.Pp 147The last one is a synonym for 148.Dq nfs . 149.It nfs: Ns Va filename 150issue a 151.Tn DHCP 152request to determine the 153.Tn IP 154address and download 155.Ar filename 156from the 157.Tn NFS 158server. 159.It nfs: 160target file is determined by 161.Sy filename 162field of 163.Pa /etc/dhcpd.conf 164.It tftp: Ns Va filename 165issue a 166.Tn DHCP 167request to determine 168.Tn IP 169address and download 170.Ar filename 171from the 172.Tn TFTP 173server. 174.It tftp: 175target file is determined by 176.Sy filename 177field of 178.Pa /etc/dhcpd.conf 179.It wd Ns Va Np : Ns Va filename 180load the 181.Tn ELF 182.Nx 183kernel 184.Ar filename 185from an 186.Tn FFSv2 187or 188.Tn FFSv1 189filesystem. 190.Ar N 191is a number to distinguish the target drive. 192.Ar p 193is a partition specifier. 194When omitted, partition 195.Sq a 196is assumed. 197.Dq wd0a 198means partition 199.Sq a 200of the first disk drive. 201.It wd Ns Va Np : 202use filename 203.Dq netbsd 204for booting the 205.Tn ELF 206.Nx 207kernel. 208.It mem: Ns Va address 209boots the 210.Tn ELF 211.Nx 212kernel from any address in memory. 213The 214.Ar address 215argument has to be specified as a hexadecimal number and denotes the 216start address of the 217.Tn ELF 218image in memory. 219.El 220.Pp 221.Nm 222can boot from RAID 1 partitions, but only if the RAID partition is the 223first partition on the disk. 224.Pp 225.Tn U-Boot/PPCBoot 226provides a way to run a short list of commands right after power-on. 227The following is a procedure to setup the system for starting 228.Nx 229after a 5 second delay, allowing the user to break into interactive 230mode. 231Note that a backslashed 232.Sq \&; 233is necessary to enter the script correctly. 234.Bd -literal -offset indent 235=> setenv bootcmd cp.b fffe0000 1000000 20000\e; go 1000000 wd0: 236=> setenv bootdelay 5 237=> saveenv 238.Ed 239.Pp 240When 241.Tn U-Boot/PPCBoot 242is lacking important commands like 243.Tn cp 244or 245.Tn go , 246or is unable to save the environment, then there is still the option to 247replace the 248.Tn Linux 249kernel module by 250.Pa altboot.img 251and save it to the same address in flash ROM. 252In this case you have only two options left to pass arguments: 253.Pp 254.Bl -bullet -compact 255.It 256Enter the interactive command line mode, after 257.Nm 258has started. 259This requires a serial console. 260.It 261Write a fixed command line into flash, replacing the 262.Tn Linux 263initrd image. 264The command line is a normal 265.Tn ASCII 266file, started by the identifier 267.Em altboot: 268and terminated by any control character between 0 and 31. 269Example: 270.Dl altboot:silent ide:1111 wd0:netbsd 271.El 272.Sh SEE ALSO 273.Xr dhcpd 8 , 274.Xr diskless 8 , 275.Xr nfsd 8 , 276.Xr raidctl 8 , 277.Xr tftpd 8 278.Sh HISTORY 279The 280.Nx Ns Tn /sandpoint 281.Nm 282first appeared in 283.Nx 6.0 . 284.Sh BUGS 285The Realtek Gigabit Ethernet driver does not work correctly at 1000 Mbps. 286Another known problem of this driver is that it runs into a timeout after 287a coldstart. 288The system has to be rebooted at least once to make it work. 289