Study the code from boot() before returning to the beginning.

In Makefile, edparams.c is compiled with the -D option.  (Note that edparams.c is a link to boot.c.)  The -DUNIX option sets UNIX equal to 1 (TRUE).  boot.c, on the other hand, is not compiled with this option (see line 0126 of Makefile). UNIX is therefore undefined and FALSE.

Different sections of code are parsed depending on whether UNIX or BIOS is TRUE.  For example, if BIOS is TRUE, lines 5030-5031 are parsed and lines 5034-5039 are discarded.  If UNIX is TRUE, lines 5034-5039 are parsed and lines 5030-5031 are discarded.  I do not cover sections of code that are specific to UNIX; for example, I do not cover lines 5143-5268.

The string "nil" is used to increase readability.

The POSIX standard was created to improve portability between UNIX systems.  The 12th paragraph of section 2.6.2, lines 01184-011200, and lines 01241-01245 in the minix code in Operating Systems describe the _POSIX_SOURCE and _MINIX macros.

Before compilation begins, the preprocessor replaces any #include <filename.h> statement with the contents of filename.h.  If the filename is enclosed in < and >, the preprocessor searches for the file in a default directory (typically /usr/include) and other directories specified by the -I option of the compiler (see line 5030).  If the filename is quoted (see line 5041), the preprocessor looks for the include file in the same directory that the source file is found.  (In this case, boot.c is the source file and is found in the /usr/src/boot directory.)

As an example, strlen() (see line 5613) is declared in the file string.h (see line 5022).  string.h is located in the directory /usr/include.

Header files, in addition to containing function declarations, also frequently contain #defines.  For example, RATIO (see line 5130) is #defined in boot.h.  Since boot.h is quoted (see line 5044), the preprocessor searches for boot.h in the same directory as boot.c.  Indeed, both files are in the /usr/src/boot directory.

arraysize(a) = sizeof(a)/sizeof(a[0]) = 20/2 = 10

Let's say we have an array of shorts, short_array[], that has 10 elements.  As the above example shows, arraysize(short_array) = 10.  So if the address of the first byte of short_array[] was, for example, 0x1100000, then arraylimit(a) = a + arraysize(a) = 10 = 0x1100000 + 10 = 0x1100000 + 0xA = 0x110000A.  This is incorrect.

Pointer arithmetic can be confusing to the uninitiated.  The following program:

#include <stdio.h>

#define arraysize(a)    (sizeof(a)/sizeof((a)[0]))
#define arraylimit(a)   ((a) + arraysize(a))

int main()
{
  short short_array[5]= {1,2,3,4,5};
  int size_of_array;
  short *short_ptr;

  size_of_array= arraysize(short_array);
  printf("the size of short_array= %d\n", size_of_array);

  short_ptr= arraylimit(short_array);
  printf("the beginning of short_array is %p\n", short_array);
  printf("short_ptr= %p\n", short_ptr);

}

produces the output:

the size of short_array= 5
the beginning of short_array is 0xbffffc50
short_ptr= 0xbffffc5A

short_ptr equals 0xbffffc5A and not 0xbffffc55.  In other words, 0xbffffc50+5 (in this scenario) equals 0xbffffc5A and not 0xbffffc55.  Any value added to a pointer is first multiplied by the size of the type that the pointer references.  A short is 2 bytes and short_array has 5 elements.  So 0xbffffc50+2*5 = 0xbffffc50+10 = 0xbffffc50+0x0A = 0xbffffc5A.

For example, on line 6131, the return value of dev_open() is stored in r.  If an error occurred, r will be nonzero.  On line 6133, bios_err() converts this number to a readable string so that printf() (on the next line:  line 6134) prints something meaningful.

The static declaration has a different meaning for external variables.  The scope of an external static variable is only within the file in which the variable is declared.  Note that "external" variables are variables that are declared outside of all functions.

Notice the order of the functions bios_err(), rwerr(), and readerr().  readerr() calls rwerr() which calls bios_err().  A function must be declared or defined before it can be called.  bios_err() is defined (lines 5051-5105) before rwerr() calls it (line 5120) and rwerr() is defined (lines 5117-5121) before readerr() calls it.  The need to carefully order the functions can be avoided if the functions are declared in a header file #included at the beginning of the file.  (In this case, boot.h would be the appropriate header file.)

u32_t mon2abs(void *ptr) converts the offset memory address ptr to an absolute memory address.

RATIO = 2.  Both sectors of blk are read.

Space for 20 char's (20 bytes) is initially allocated.  If this is used up, another 20 bytes are allocated.  If the 40 bytes are used up, 40 additional bytes are allocated.  Each reallocation of memory doubles the total amount of memory allocated.  See lines 5298-5299.

ctrl-U and ctrl-X erase the entire line.

int putch(int c) prints c at the current cursor position.  If c is the bell, the speaker beeps and the cursor doesn't advance.

hd2a> rootdev = hd2a
hd2a> delay 5000
hd2a> dos(d, MS-DOS) { boot hd1 }
hd2a> minix(=, MINIX) { boot }
hd2a> main() { trap 5000 minix; menu }

and here is how the commands are broken up into tokens:

token1    token2     token3    token4
rootdev   =          hd2a      \n

token1    token2     token3
delay     5000       \n

token1    token2     token3    token4    token5    token6
dos       (d,MS-DOS) {         boot      hd1       }
token7
\n

token1    token2     token3    token4    token5    token6
minix     (=,MINIX)  {         boot      }         \n

token1    token2     token3    token4    token5    token6
main      ()         {         trap      5000      minix
token7    token8     token9    token10
;         menu       }          \n

These tokens are chained together with the struct token (lines 5356-5359).

Here is the first command (rootdev = hd2a).

Commands are separated not only by newlines ('\n') but also by semicolons(;).  For example, on lines 5861-5862, the tokens ":", "leader", and "main" are separated by semicolons.

Sector 1 (PARAMSEC) of any bootable partition is the "bootparams sector". (Sector 0 of any bootable partition is the bootblock code.) The PARAMSEC sector contains commands that were previously saved.  Before the boot monitor goes into interactive mode (i.e. before the prompt appears), the bootparams sector is tokenized (see lines 5848-5854) and the commands are processed.  Tokens in the bootparams sector are separated by newlines (see line 5920).

In the function tokenize() (line 5361), line must be advanced in each call to onetoken().  (Note that this refers to the variable line from tokenize(), not the variable line from onetoken().)

Study the following program:

#include <stdio.h>

int main()
{
  int var1 = 5;
  function1(var1);
  printf("var1 is equal to %d.", var1);
}

int function1(int var)
{
  var=3;
}

The output of this program is:
var1 is equal to 5.

The value of var1 cannot be changed by altering the value of var in function1().  The reason var1 can't be changed here is that function arguments in C are passed "by value."  Called functions are given the value of their arguments in temporary variables rather than the originals.  For this reason, changes to var in function1() are not reflected in var1 from main().

However, there is a way to change the value of var1:

#include <stdio.h>

int main()
{
  int var1 = 5;
  function1(&var1);
  printf("var1 is equal to %d." var1);
}

int function1(int *var)
{
  *var=3;
}

The output of this program is:
var1 is equal to 3.

Note that the value of var1 has been changed by passing in the address of var1 rather than var1 itself.  function1() dereferences var to change the value of var1.

Since the function onetoken() must change the value of line (see line 5372), the address of line is passed in rather than line itself.  Note that line from tokenize() is a pointer to a char; therefore a pointer to a pointer to a char is passed in.

When you see a pointer to a pointer as a parameter to a function, check to see if the function changes the value of a pointer by dereferencing the pointer to a pointer.  For example, onetoken() changes the value of line (the variable line from tokenize(), not onetoken()) by dereferencing aline on line 5350.

I understand that this stuff is confusing.  We'll run into this again; I'll continue to give detailed explanations in case you didn't understand it this time.

On line 5348, newlines are replaced with semicolons (;).  Semicolons and newlines have the same meaning here; they are both command separators.

If the first character is a left parenthesis ('('), then the token is something like (d,MS-DOS), (=, MINIX), or () (see comments for line 5307).

Again, we see a function parameter (token **acmds) that is a pointer to a pointer.  We saw this previously with  onetoken() (line 5313).  And again, we wish to change a pointer variable (for example, cmds on line 5854) so we pass in a pointer to this pointer variable.

The pointer manipulations in tokenize() are extremely tricky.  I hope that this slide show helps.  This slide show assumes that a pointer to cmds is passed into acmds.  This is the case if the command chain is empty.  The command chain is empty before the boot parameters from sector PARAMSEC are tokenized (see line 5854).  The command chain is also empty before the boot monitor reads a line and tokenizes it (see lines 6591-6598).

tokenize slide show

token1    token2    token3    token4    token5    token6
rootdev   =         hd2a      ;         menu      ;

poptoken() would remove token1 from the command chain and return a pointer to "rootdev".

In the figure below, note that there are two memory objects, one beginning at address token1 and one beginning at address a (the string).  The two memory objects are independent.  Freeing (i.e. deallocating) the memory object that begins at address token1 does not free the memory object that begins at address a. poptoken() frees the memory for the token.  voidtoken() frees the memory for the token and the string.

Occasionally, the boot monitor needs to check if the ESC (escape) key has been pressed.  The boot monitor allows the delay command (see line 6225) and the menu command (see line 6270) to be escaped (see line 6225).  The delay msec command pauses for msec milliseconds before executing the next command in the command chain.  The menu command shows the selection of kernels that can be booted.  Escaping the menu command sends the user back to the boot monitor prompt.

The command echo \w also calls interrupt(). echo \w waits until the escape key is pressed or a newline is entered (see line 6486).

bootdev is set in initialize() (line 5450). tmpdev is set in name2dev() (line 5979).  name will be something like "fd1" (second floppy drive) or "hd7" (second partition on second hard drive; see line 5549) or "hd3a" (first subpartition on third partition on first hard drive).

device, primary and secondary for "fd1", "hd7", and "hd3a" are:

name= "fd1"
device= 0x01
primary= -1
secondary= -1

name= "hd7"
device= 0x81
primary= 1
secondary= -1

name= "hd3a"
device= 0x80
primary= 2
secondary= 0

An MBR has two parts: the code and the partition table.  The MBR is 1 sector (=512 bytes) long and the partition table starts at byte 0x1BE (=446).  A partition table has 4 entries.  Here is an entry from the partition table:

get_master() copies the entire MBR (code + partition table) from disk into the memory address referenced by master and copies the memory addresses of the 4 partition entries from the partition table into the array referenced by table.  The figure below shows the variables and memory layout after get_parameter() has finished the copy.

get_master() is called on line 5519 and line 6085.  On line 5519, get_master() is called to determine the name of the partition (e.g. "hd2a").  On line 6085, get_master() is called to determine where to find the bootstrap that corresponds to tmpdev (see line 5418).  The code on lines 5519 and 6085 is concerned only with the partition table and ignores the code from the MBR.

u32_t mon2abs(void *ptr) converts the offset memory address ptr to an absolute memory address.

PART_TABLE_OFFSET and NR_PARTITIONS are #defined in <ibm/partition.h>. NR_PARTITIONS = 4.

The for loop fills in the array at address f (see figure above).

The partition table entries are sorted with the bubble sort algorithm.  Here is how the bubble sort algorithm works:

Partition table entry 1 and partition table entry 2 are compared.  If the first entry has a greater lowsec (lowsec is the sector number of the first sector in a partition) or is not being used (sysind=NO_PART), the two entries are swapped.  If the first entry has a lower lowsec and is being used, the first two entries are not swapped.  Entries 2 and 3 are next compared and swapped if entry 2 has a greater lowsec or is not being used.  Entries 3 and 4 are compared and swapped if entry 3 has a greater lowsec or is not being used.  Next, the process starts again and entries 1 and 2 are compared and swapped if appropriate.

Here is a figure that describes the entire sorting process.  Four partitions with lowsec's of 1, 509, 890, and 1500 are sorted.  The partition with a lowsec of 890 is not being used (NP).

1)  Relocates the boot monitor to the upper end of low memory.  Low memory is memory that is under 640KB.

2)  Removes the boot monitor from the memory map that is passed to the kernel.  This prevents the kernel from allocating the memory that the boot monitor occupies.

3)  Initializes bootdev (see comments for line 5418).

caddr, daddr and runsize are also declared in boot.h and initialized in boothead.s .  caddr is the absolute memory address of the beginning of the boot monitor.  Since the boot monitor is relocated to the upper end of low memory, caddr will change (see line 5473).  daddr is the absolute memory address of the beginning of the data segment of the boot monitor.  runsize is the size (in bytes) of the boot monitor.

Since memend and runsize are 32-bit values, newaddr = (memend-runsize) & ~0x000FL will be on a 16-byte boundary.  Since the boot monitor runs in real mode, the beginning of a segment (in this case, the code segment) must be on a 16-byte boundary.

The figure below demonstrates the scenario that we wish to avoid.

(daddr-caddr) is the size of the code segment.  Since newaddr + (size of code segment) < dma64k (and therefore the data segment crosses a 64KB boundary) in the figure above, an adjustment is necessary. The figure below shows the adjustment.

I don't understand why the data segment of the boot monitor isn't allowed to cross a 64KB boundary.  If you understand why the data segment isn't allowed to cross a 64KB boundary, please submit a comment to the site which will be displayed below.

If a return to the boot monitor (to either bios13 or int86) from the kernel is made in order to make a bios interrupt call, the bios interrupt vectors must be at memory locations 0x0000-0x03FF and the bios data area  must be at 0x0400-0x04FF.  This accounts for 1.25K.  I don't know about the next .25K and I'm not really sure why .5K is reserved for older a.out headers.  If you understand why the last .75K is reserved, please submit a comment to the site which will be displayed below.

name= "fd1"
device= 0x01
primary= -1
secondary= -1

name= "hd7"
device= 0x81
primary= 1
secondary= -1

name= "hd3a"
device= 0x80
primary= 2
secondary= 0

void raw_copy(u32_t dstaddr, u32_t srcaddr, u32_t count) copies count bytes from absolute memory address srcaddr to absolute memory address dstaddr.

u32_t mon2abs(void *ptr) converts the offset memory address ptr to an absolute memory address.

int offsetof(struct struct1, field) returns the offset of field within struct1.  part_entry is shown on line 04104 in the book.  Since lowsec is the 9th field after 8 fields of type unsigned char, offsetof(struct part_entry, lowsec) returns 8.  (An unsigned char is 1 byte.)

Since lowsec has type u32_t, sizeof(lowsec) returns 4.

In order to determine the partition (or subpartition) number, the partition table is copied from the master boot record (MBR) on device's sector 0 and lowsec is compared with the lowsec field of the partition table entries.  If the active partition is subpartitioned, the partition table from the MBR on the first sector of the active partition must also be analyzed.

1)  lowsec == table[p]->lowsec

The partition or subpartition has been found (see line 5528).

2)  lowsec > table[p]->lowsec

table[p] points to the partition table entry whose partition contains the booted subpartition (i.e. the subpartition with a lowest sector of lowsec).

name= "hd7"
device= 0x81
primary= 1
secondary= -1

name= "hd3a"
device= 0x80
primary= 2
secondary= 0

NR_PARTITIONS (=4) is declared in <ibm/partition.h>.

char *strcat(s1, s2) concatenates string s2 to the end of string s1 and returns s1.  strcat() is declared in <string.h>.

char *ul2a10(u32_t n) (line 5746) converts n (an unsigned long) to an ascii string (base 10).