have doc here

5 files changed, 380 insertions, 0 deletions

diff --git a/mdk-stage1/doc/HACKING b/mdk-stage1/doc/HACKING
new file mode 100644
index 000000000..d196c8010
--- /dev/null
+++ b/mdk-stage1/doc/HACKING
@@ -0,0 +1,31 @@
+If you have to boot pretty often, you'll appreciate to speed the things up
+a little.
+
+Here's what we use: the GRUB feature to boot from the network using the
+DHCP protocol and the TFTP protocol.
+
+Here's the "menu.lst" to do that:
+
+-=-=--
+
+timeout 0
+
+title linux
+dhcp
+tftpserver 192.168.1.17
+kernel (nd)/tftpboot/gc/vmlinuz ramdisk=32000 vga=788
+initrd (nd)/tftpboot/gc/network.rdz
+
+-=-=--
+
+
+The option "tftpserver" is used to override the tftpserver address given
+as an answer by the DHCP server. That way, you'll not need to bother your
+system administrator to modify his dhcp server configuration.
+
+The directory /tftpboot seems to be the only one defaultly accepted by the
+server, and its subdirs.
+
+
+Of course, your GRUB needs to be compiled with the specific code for your
+network card; use ./configure --help in the GRUB build dir for more infos.
diff --git a/mdk-stage1/doc/README b/mdk-stage1/doc/README
new file mode 100644
index 000000000..e3747cf30
--- /dev/null
+++ b/mdk-stage1/doc/README
@@ -0,0 +1,185 @@
+-------------------------------------------------------
+*  Stage1 of the Linux-Mandrake installation program  *
+-------------------------------------------------------
+
+
+[ Author ]
+
+	Guillaume Cottenceau (gc@mandrakesoft.com)
+
+
+[ Copyright ]
+
+	Copyright 2000 MandrakeSoft
+
+	Partially inspired by Redhat stuff (install from 5.x and 7.x) copyright
+	Red Hat Software, and Debian stuff (boot-floppies) copyright by their
+	respective holders.
+
+
+[ Licence ]
+
+	This program is free software; you can redistribute it and/or modify
+	it under the terms of the GNU General Public License as published by
+	the Free Software Foundation; either version 2 of the License, or
+	(at your option) any later version.
+	
+	This program is distributed in the hope that it will be useful,
+	but WITHOUT ANY WARRANTY; without even the implied warranty of
+	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+	GNU General Public License for more details.
+	
+	You should have received a copy of the GNU General Public License
+	along with this program; if not, write to the Free Software
+	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
+
+
+	*** WARNING! ***
+
+	This General Public License does not permit incorporating any part
+	of this program as a library into proprietary programs.
+
+
+[ Online ]
+
+	http://us.mandrakesoft.com/~gc/html/stage1.html
+
+
+[ Purpose ]
+
+	This code will take the control of the computer after that Linux
+	kernel booted properly, and will try to run the main installer
+	(also known as "stage 2") from a series of different media
+	including harddrive, cdrom, and network.
+
+	Use the source, Luke.
+
+
+
+
+                -=-=-- Okay, now, more details --=-=-
+
+
+	[ Installing Linux-Mandrake ]
+
+Per default, just insert your Linux-Mandrake Installation CD into your
+CDROM tray, be sure your system BIOS is configured to boot on your CDROM,
+and that's all.
+
+If you have multiple CDROM drives and the installer can't autodetect in
+which CDROM drive is the disc, it may ask you to choose the correct drive,
+between your CDROM drives.
+
+Also, if you want to install from an SCSI CDROM, the installer should
+detect your SCSI adapter; if it fails you may have to select the right
+driver and/or supply additional parameters.
+
+
+        [ Position of the problem ]
+
+The need for alternate installation methods come with more specific
+hardware configuration and/or need for frequent updates of the Installer
+software.
+
+All of these methods will require to use a special boot disk. The method
+is to download it and then to copy it "physically" to a floppy with the
+command:
+
+# dd if=<boot-disk> of=/dev/fd0
+
+Our boot disks are called "cdrom.img", "network.img", etc.
+
+
+        [ Installation from CDROM ]
+
+The first situation you may encounter is an old BIOS which does not permit
+you to boot from your CDROM drive.
+
+In that case, you'll need to use the "cdrom.img" image file. The steps are
+the same as with CDROM boot, and everything should be automatic.
+
+
+        [ Installation from DISK ]
+
+If you like trying occasionnally our development version, the Cooker, one
+of the easiest way is to grab a local copy of the Distribution on one of
+your local hard drives, and to install from that location.
+
+At present time, you can install from IDE or SCSI drives, from Linux
+(ext2), Windows (vfat) or Reiserfs partition.
+
+In that case, you'll need to use the "hd.img" image file. The dialogs will
+ask you to choose the DISK drive to use to install from, then the
+partition on which you copied the Distribution, then the location
+(directory) in which you copied the Distribution.
+
+
+        [ Installation from NETWORK ]
+
+For convenience, you can also install from a NFS volume, from a FTP
+server, or from a HTTP server. NFS installs are maybe the fastest
+and most convenient possible, so if you need to do frequent and/or
+multiple installs, you may like this option.
+
+In that case, you'll need to use the "network.img" image file. If you have
+PCI network card(s), you'll probably have to only setup your network
+options. If not, you'll have to choose the appropriate driver(s) and/or
+optional parameters. Supported network configurations include static IP
+allocation and DHCP automatic configuration.
+
+
+        [ Installation from PCMCIA ]
+
+If you want to perform an installation on your laptop that is not based on
+local IDE CDROM or DISK, nor on built-in network card, but on PCMCIA
+extension (probably a network adapter or CDROM drive), you'll need the
+"pcmcia.img" image file.
+
+PCMCIA services should automatically start and be transparent to you.
+Then, you'll follow the instructions according to your preferred
+installation method.
+
+
+	[ Monitoring a stage1 session ]
+
+Linux supports virtual consoles. You can switch between them by issueing
+Ctrl+Alt+Fx key, in which 'x' is the number of the console. Here's console
+occupancy during stage1.
+
+(#1) The user-interface of the stage1 is on the first console. In case of
+newt interaction, it's provided with a neat blue and black color scheme,
+and nice widgets. In case of stdio interaction (cdrom and disk installs),
+it's more basic but still usable :-).
+
+(#2) A shell is provided on second console in some cases (you need to
+compile it with -DSPAWN_SHELL and you need to provide a valid shell in the
+initrd) and of course it's not in, in image files of Linux-Mandrake
+releases because it's too much diskspace.
+
+(#3) The log is printed out on the third console. This is the location
+where you can find most valuable information, prefixed by a '*'. See
+"log.h" for calls that print things out to the log.
+
+(#4) The kernel messages are printed on the fourth console. There is a
+process forked very early in the init (the program before the stage1)
+which monitors /proc/kmsg for new kernel messages. Also, syslog stuff (the
+logs commited by the programs) should appear on the /dev/log Unix socket,
+this is also printed on this console.
+
+(#5) Former place for the stderr of insmod calls. It's not used anymore.
+
+(#6) Place where a trivial interactive communication with the stage1 is
+set up if the parameter -DSPAWN_INTERACTIVE is compiled in. Basically, you
+can set switches such as "expert" and "rescue" on the fly with this
+feature. It's implemented with a fork and a Unix pipe.
+
+
+        [ Rescueing a system ]
+
+Since Linux-Mandrake 7.1, we provide a rescue system through each of the
+previously described methods. You don't need a special "rescue.img" file.
+Just hit "F1" at boot time, type in "rescue", and follow the first steps
+of the installation according to the method you chose (choose
+disks/partitions for disk method, network parameters for network method,
+etc). Then, you'll end up with a workable system, very useful to rescue a
+damaged system, or do other basic actions.
diff --git a/mdk-stage1/doc/TECH-INFOS b/mdk-stage1/doc/TECH-INFOS
new file mode 100644
index 000000000..563b97ee1
--- /dev/null
+++ b/mdk-stage1/doc/TECH-INFOS
@@ -0,0 +1,45 @@
+
+| (*) Automatic install
+\----------------------
+
+This feature is used to replace redhat kickstart. I use the kernel
+parameter "automatic" with the following keywords:
+
+from list:
+	method          nfs, ftp, http, cdrom, disk
+	network         static, dhcp
+	interface	eth0, eth1, ..
+
+giving (string) values:
+    (static IP infos)
+	ip
+	dns
+	gateway
+	netmask
+
+    (2nd step network config)
+	hostname
+	domain
+
+    (3rd step nfs, ftp, http installs)
+	server
+	directory
+
+    (3rd step ftp only)
+	user
+	pass
+
+    (2nd step disk install)
+	disk
+
+    (3rd step disk install)
+	partition
+
+    (4th step disk install)
+	directory
+
+
+Keywords must be passed with commas and colons, that is for example:
+
+	automatic=method:nfs,network:static,ip:192.168.1.24,server:192.168.1.7,directory:/stable/i586
+
diff --git a/mdk-stage1/doc/WHY-DIETLIBC b/mdk-stage1/doc/WHY-DIETLIBC
new file mode 100644
index 000000000..e7c526b49
--- /dev/null
+++ b/mdk-stage1/doc/WHY-DIETLIBC
@@ -0,0 +1,50 @@
+(the dietlibc is a replacement for the glibc, which aim is to produce
+smaller statically linked binaries)
+
+
+The use for dietlibc in the stage1 was clear because currently used
+install process on x86 is from a 1.44 Mbytes floppy. On this floppy we
+need to fit the kernel, modules (scsi and network access), and the code to
+do the basic things to load the stage2. The only part on which we could
+progress was the code.
+
+As always, figures demonstrate evidences. Here are the size of the
+binaries used for the cdrom, disk, network and full floppy installs, using
+newt as the UI library:
+
+	- with glibc
+
+-rwxr-xr-x    1 gc       gc         569448 May 15 15:29 stage1-cdrom
+-rwxr-xr-x    1 gc       gc         572264 May 15 15:29 stage1-disk
+-rwxr-xr-x    1 gc       gc         624712 May 15 15:30 stage1-network
+-rwxr-xr-x    1 gc       gc         720360 May 15 15:29 stage1-full
+
+	- with dietlibc
+
+-rwxr-xr-x    1 gc       gc         169332 May 15 14:26 stage1-cdrom
+-rwxr-xr-x    1 gc       gc         172180 May 15 14:26 stage1-disk
+-rwxr-xr-x    1 gc       gc         198612 May 15 14:26 stage1-network
+-rwxr-xr-x    1 gc       gc         251764 May 15 14:26 stage1-full
+
+
+The `stage1-full' binary has code for many things, most notably: data
+decrunching (bzlib), archive extraction (in-house format), module loading
+(insmod from busybox), PCI detection, ide and scsi handling,
+cdrom/disk/loopback mounting, DHCP client negociation (redhat+grub), NFS
+mounting (util-linux), FTP and HTTP transmission (redhat), pcmcia
+initializing (pcmcia-cs), UI interaction (slang/newt); with use of the
+dietlibc, the binary is only 250 kbytes!
+
+
+Due to the modular coding, it is also possible to choose to not use
+slang/newt as the UI, but a stdio-only UI. In that case, the binaries get
+even smaller:
+
+-rwxr-xr-x    1 gc       gc         104500 May 15 15:46 stage1-cdrom*
+-rwxr-xr-x    1 gc       gc         107348 May 15 15:46 stage1-disk*
+-rwxr-xr-x    1 gc       gc         133972 May 15 15:47 stage1-network*
+-rwxr-xr-x    1 gc       gc         187348 May 15 15:46 stage1-full*
+
+
+
+gc [Tue May 15 15:58:34 2001]
\ No newline at end of file
diff --git a/mdk-stage1/doc/documented..frontend.h b/mdk-stage1/doc/documented..frontend.h
new file mode 100644
index 000000000..10417ef3b
--- /dev/null
+++ b/mdk-stage1/doc/documented..frontend.h
@@ -0,0 +1,69 @@
+/*
+ * Guillaume Cottenceau (gc@mandrakesoft.com)
+ *
+ * Copyright 2000 MandrakeSoft
+ *
+ * This software may be freely redistributed under the terms of the GNU
+ * public license.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+ *
+ */
+
+/*
+ * Using high-level UI.
+ *
+ * These functions are frontend-independant: your program won't know each
+ * `frontend' (e.g. each way to grab user input) will be used.
+ *
+ * Then you may link your binary against any `frontend' that implement all
+ * these functions (and possibly necessary libraries).
+ */
+
+
+#ifndef _FRONTEND_H_
+#define _FRONTEND_H_
+
+/* this must be called before anything else */
+void init_frontend(void);
+
+/* this must be called before exit of program */
+void finish_frontend(void);
+
+
+void info_message(char *msg, ...) __attribute__ ((format (printf, 1, 2))); /* (blocks program) */
+
+void error_message(char *msg, ...) __attribute__ ((format (printf, 1, 2))); /* (blocks program) */
+
+/* (doesn't block program) 
+ * (this is not necessarily stackable, e.g. only one wait_message at a time) */
+void wait_message(char *msg, ...) __attribute__ ((format (printf, 1, 2)));
+
+/* call this to finish the wait on wait_message */
+void remove_wait_message(void);
+
+/* monitor progression of something (downloading a file, etc)
+ * if size of progression is unknown, use `0' */
+void init_progression(char *msg, int size);
+void update_progression(int current_size);
+void end_progression(void);
+
+enum frontend_return { RETURN_OK, RETURN_BACK, RETURN_ERROR };
+
+/* Yes == RETURN_OK    No == RETURN_ERROR    Back == RETURN_BACK */
+enum frontend_return ask_yes_no(char *msg);
+
+/* [elems] NULL terminated array of char*
+ * [choice] address of a (unitialized) char* */
+enum frontend_return ask_from_list(char *msg, char ** elems, char ** choice);
+
+enum frontend_return ask_from_list_comments(char *msg, char ** elems, char ** elems_comments, char ** choice);
+
+/* [questions] NULL terminated array of char*
+ * [answers] address of a (unitialized) char**, will contain a non-NULL terminated array of char*
+ * [callback_func] function called at most when the answers change; it can examine the array of char* and assign some new char* */
+enum frontend_return ask_from_entries(char *msg, char ** questions, char *** answers, int entry_size, void (*callback_func)(char ** strings));
+
+#endif