nix: Update flake inputs

[novaboot.git] / README.pod

diff --git a/README.pod b/README.pod
index 8fcbeaee494394a22bc3139f9ba3bfc2d98abe9c..dff5ae6fb30cf54b1a94b4c7bcb7ccaad464d20b 100644 (file)
--- a/README.pod
+++ b/README.pod
@@ -45,7 +45,7 @@ options. Understanding all these options is not always needed,
 depending on the used setup. The L<figure from the doc directory
 |https://github.com/wentasah/novaboot/blob/master/doc/typical-setups.svg>
 shows different setups that vary in how much effort is needed
 depending on the used setup. The L<figure from the doc directory
 |https://github.com/wentasah/novaboot/blob/master/doc/typical-setups.svg>
 shows different setups that vary in how much effort is needed

-configure novaboot for them. The setups are:
+to configure novaboot for them. The setups are:

 
 =over 3
 
 
 =over 3
 


@@ -54,13 +54,13 @@ configure novaboot for them. The setups are:
 This requires to configure everything on the laptop side, including a
 serial line connection (L</--serial>, L</--remote-cmd>, ...), power
 on/off/reset commands (L</--reset-cmd>, ...), TFTP server
 This requires to configure everything on the laptop side, including a
 serial line connection (L</--serial>, L</--remote-cmd>, ...), power
 on/off/reset commands (L</--reset-cmd>, ...), TFTP server

-(L</--server>, L</--prefix>...), device IP addresses, etc.
+(L</--copy>, L</--prefix>...), device IP addresses, etc.

 
 =item B: Laptop, target device and external TFTP server
 
 Like the previous setup, but the TFTP (and maybe DHCP) configuration
 is handled by a server. Novaboot users need to understand where to
 
 =item B: Laptop, target device and external TFTP server
 
 Like the previous setup, but the TFTP (and maybe DHCP) configuration
 is handled by a server. Novaboot users need to understand where to

-copy their files to the TFTP server (L</--server>) and which IP
+copy their files to the TFTP server (L</--copy>) and which IP

 addresses their target will get, but do not need to configure the
 servers themselves.
 
 addresses their target will get, but do not need to configure the
 servers themselves.
 


@@ -104,7 +104,7 @@ with all other files needed for booting to a remote TFTP server. Then
 use a TCP/IP-controlled relay/serial-to-TCP converter to reset the
 target and receive its serial output.
 
 use a TCP/IP-controlled relay/serial-to-TCP converter to reset the
 target and receive its serial output.
 

- ./mylinux --grub2 --server=192.168.1.1:/tftp --iprelay=192.168.1.2
+ ./mylinux --grub2 --copy=192.168.1.1:/tftp --iprelay=192.168.1.2

 
 Alternatively, you can put these switches to the configuration file
 and run:
 
 Alternatively, you can put these switches to the configuration file
 and run:


@@ -147,7 +147,7 @@ I<script2> configurations.
 
 =back
 
 
 =back
 

-=head1 PHASES AND OPTIONS
+=head1 OPTIONS AND PHASES

 
 Novaboot performs its work in several phases. Command line options
 described bellow influence the execution of each phase or allow their
 
 Novaboot performs its work in several phases. Command line options
 described bellow influence the execution of each phase or allow their


@@ -256,7 +256,7 @@ Configures novaboot to control the target via C<novaboot-shell>
 running remotely via SSH.
 
 Using this option is the same as specifying B<--remote-cmd>,
 running remotely via SSH.
 
 Using this option is the same as specifying B<--remote-cmd>,

-B<--remote-expect>, B<--server> B<--rsync-flags>, B<--prefix> and
+B<--remote-expect>, B<--copy> B<--rsync-flags>, B<--prefix> and

 B<--reset-cmd> manually in a way compatible with C<novaboot-shell>.
 The server can be configured to provide other, safe bootloader-related
 options, to the client. When this happens, novaboot prints them to
 B<--reset-cmd> manually in a way compatible with C<novaboot-shell>.
 The server can be configured to provide other, safe bootloader-related
 options, to the client. When this happens, novaboot prints them to


@@ -371,10 +371,14 @@ Alias for B<--prefix>.
 =item --grub2[=I<filename>]
 
 Generate GRUB2 menu entry in I<filename>. If I<filename> is not
 =item --grub2[=I<filename>]
 
 Generate GRUB2 menu entry in I<filename>. If I<filename> is not

-specified F<grub.cfg> is used. The content of the menu entry can be
+specified F<./boot/grub/grub.cfg> is used. The content of the menu entry can be

 customized with B<--grub-preamble>, B<--grub2-prolog> or
 B<--grub_prefix> options.
 
 customized with B<--grub-preamble>, B<--grub2-prolog> or
 B<--grub_prefix> options.
 

+GRUB2 can boot multiboot-compliant kernels and a few kernels with specific
+support. L</BOOT_METHOD> could be used to specify the command used by GRUB2 to
+load the kernel. See L<GNU GRUB Manual|https://www.gnu.org/software/grub/manual/grub/grub.html#Booting>.
+

 To use the generated menu entry on your development
 machine that uses GRUB2, append the following snippet to
 F</etc/grub.d/40_custom> file and regenerate your grub configuration,
 To use the generated menu entry on your development
 machine that uses GRUB2, append the following snippet to
 F</etc/grub.d/40_custom> file and regenerate your grub configuration,


@@ -550,10 +554,11 @@ Port to run the TFTP server on. Implies B<--tftp>.
 
 =item --netif=I<network interface>
 
 
 =item --netif=I<network interface>
 

-Network interface used to deploy files to the target. The default value is
-I<eth0>. This option influences the configuration of the DHCP server started
-by B<--dhcp-tftp> and the value that B<$NB_MYIP> get replaced with during
-U-Boot conversation.
+Network interface used to deploy files to the target. This option
+influences the configuration of the DHCP server started by
+B<--dhcp-tftp> and the value that B<$NB_MYIP> get replaced with during
+U-Boot conversation. The default value is C<$netif> variable from
+configuration files, which defaults to I<eth0>.

 
 =item --iso[=filename]
 
 
 =item --iso[=filename]
 


@@ -563,6 +568,10 @@ of the novaboot script (see also B<--name>).
 
 =item --server[=[[user@]server:]path]
 
 
 =item --server[=[[user@]server:]path]
 

+Alias of B<--copy> (kept for backward compatibility).
+
+=item --copy[=[[user@]server:]path]
+

 Copy all files needed for booting to another location. The files will
 be copied (by B<rsync> tool) to the directory I<path>. If the I<path>
 contains string $NAME, it will be replaced with the name of the
 Copy all files needed for booting to another location. The files will
 be copied (by B<rsync> tool) to the directory I<path>. If the I<path>
 contains string $NAME, it will be replaced with the name of the


@@ -571,13 +580,13 @@ novaboot script (see also B<--name>).
 =item --rsync-flags=I<flags>
 
 Specifies I<flags> to append to F<rsync> command line when
 =item --rsync-flags=I<flags>
 
 Specifies I<flags> to append to F<rsync> command line when

-copying files as a result of I<--server> option.
+copying files as a result of I<--copy> option.

 
 =item --concat
 
 
 =item --concat
 

-If B<--server> is used and its value ends with $NAME, then after
+If B<--copy> is used and its value ends with $NAME, then after

 copying the files, a new bootloader configuration file (e.g. menu.lst)
 copying the files, a new bootloader configuration file (e.g. menu.lst)

-is created at I<path-wo-name>, i.e. the path specified by B<--server>
+is created at I<path-wo-name>, i.e. the path specified by B<--copy>

 with $NAME part removed. The content of the file is created by
 concatenating all files of the same name from all subdirectories of
 I<path-wo-name> found on the "server".
 with $NAME part removed. The content of the file is created by
 concatenating all files of the same name from all subdirectories of
 I<path-wo-name> found on the "server".


@@ -803,9 +812,16 @@ word after C<load> is a file name (relative to the build directory
 (see B<--build-dir>) of the module to load and the remaining words are
 passed to it as the command line parameters.
 
 (see B<--build-dir>) of the module to load and the remaining words are
 passed to it as the command line parameters.
 

+When booting Linux, the first C<load> line usually refers to the
+kernel image and its command line parameters (unless you use some
+special pre-loader). Other C<load> lines may refer to an initramfs
+image and/or a device tree blob. Their order is not important, as the
+device tree is recognized as the file name ending with C<.dtb>.
+

 When the C<load> line ends with "<<WORD" then the subsequent lines
 until the line containing solely WORD are copied literally to the file
 When the C<load> line ends with "<<WORD" then the subsequent lines
 until the line containing solely WORD are copied literally to the file

-named on that line. This is similar to shell's heredoc feature.
+named on that line. This is similar to the heredoc feature of UNIX
+shells.

 
 When the C<load> line ends with "< CMD" then command CMD is executed
 with F</bin/sh> and its standard output is stored in the file named on
 
 When the C<load> line ends with "< CMD" then command CMD is executed
 with F</bin/sh> and its standard output is stored in the file named on


@@ -919,6 +935,11 @@ The following variables are interpreted in the novaboot script:
 
 =over 8
 
 
 =over 8
 

+=item BOOT_METHOD
+
+Specifies the way GRUB2 boots the kernel. For kernels with multiboot
+support use C<multiboot> method (the default). For Linux kernel use C<linux> method.
+

 =item BUILDDIR
 
 Novaboot chdir()s to this directory before file generation phase. The
 =item BUILDDIR
 
 Novaboot chdir()s to this directory before file generation phase. The


@@ -1013,17 +1034,22 @@ Default target (see below) to use when no target is explicitly
 specified with the B<--target> command line option or
 B<NOVABOOT_TARGET> environment variable.
 
 specified with the B<--target> command line option or
 B<NOVABOOT_TARGET> environment variable.
 

+=item $netif
+
+Default value for the B<--netif> option. If not specified, it defaults
+to I<eth0>.
+

 =item %targets
 
 Hash of target definitions to be used with the B<--target> option. The
 key is the identifier of the target, the value is the string with
 command line options. For instance, if the configuration file contains:
 
 =item %targets
 
 Hash of target definitions to be used with the B<--target> option. The
 key is the identifier of the target, the value is the string with
 command line options. For instance, if the configuration file contains:
 

- $targets{'mybox'} = '--server=boot:/tftproot --serial=/dev/ttyUSB0 --grub',
+ $targets{'mybox'} = '--copy=boot:/tftproot --serial=/dev/ttyUSB0 --grub',

 
 then the following two commands are equivalent:
 
 
 then the following two commands are equivalent:
 

- ./myos --server=boot:/tftproot --serial=/dev/ttyUSB0 --grub
+ ./myos --copy=boot:/tftproot --serial=/dev/ttyUSB0 --grub

  ./myos -t mybox
 
 =back
  ./myos -t mybox
 
 =back