This page contains a PicoBSD user/starter FAQ aimed primarily at first-time PicoBSD users who intend to experiment with embedded systems. PicoBSD is a version of FreeBSD built in such a way that it can be useful when you need a ``real'' BSD and TCP/IP stack in a complete system small enough to fit on a floppy. Once booted, PicoBSD runs out of RAM-disk. PicoBSD need not boot from a floppy; it can be used to boot from flash devices, to create a single ``self-contained'' and ``self-extracting'' netbootable file , etc.. PicoBSD is suitable for many PC-based embedded OS projects.

The primary purpose of this FAQ is to describe the PicoBSD build process under FreeBSD 4.3 Stable sufficiently for a new user to build and use PicoBSD for experimental embedded systems. Under different versions of FreeBSD these procedures may differ.

§ Operational tech notes

What is PicoBSD?

Building PicoBSD:
  Quick! How do I build one of the standard PicoBSD systems?
  Quick! How do I build my own version of PicoBSD?
  What are some common errors and how do I deal with them?
  How do I clean-up after a PicoBSD build?
  What is the default PicoBSD root password?

The picobsd build script:
  What is the most current description of the picobsd script command?
  What is the syntax of the picobsd script command?
  What can I do with the script's main interactive dialog menu?
  What vn device housekeeping should I do?

PicoBSD configuration:
  What is in a PicoBSD configuration directory?
  What are the predefined ``reference'' configurations? Which one should I use?

Booting PicoBSD and editing boot scripts:
  How does the PicoBSD rc boot script work?
  How do I edit PicoBSD /etc scripts?
  How do I edit or add new files to an existing floppy image file?

Using PicoBSD:
  What are some command-line differences between FreeBSD and PicoBSD?
  How do I include my own binary application in PicoBSD, that is, include them with the ``crunched'' applications in the kernel file?
  How do I write a binary application that I can download individually to PicoBSD without being ``crunched''?
  How big is PicoBSD?
  Does PicoBSD support hard disks?
  How do I see how much space is used in PicoBSD filesystems?

§ Requirements

What ``host'' environment do I need to do embedded PicoBSD development?
What versions of FreeBSD does picobsd run under?
How do I get PicoBSD (FreeBSD)?

§ Internals and customization

How does the ``picobsd'' script work (how does all this happen)?
What is tinyware?
What is oinit?
Where do the PicoBSD boot files on the floppy come from?
What makefile invokes the actual PicoBSD kernel compile?
How can I build a number of related PicoBSD systems?
How do I make a floppy from an existing PicoBSD floppy image file?

How do I compare FreeBSD and PicoBSD kernel images?
How do I find a string in an ELF kernel section?

§ Older/historical/related tech notes

What's an older way to build PicoBSD?
Can I download a bootable PicoBSD image?
Are there other ways to make small FreeBSD systems?

§ History and some non-tech notes

Who maintains PicoBSD?
Who developed PicoBSD?
What type of license is PicoBSD under?
What should I know about industrial and embedded PCs?
What are some university and academic groups using PicoBSD?

What are some disadvantages of PicoBSD?
What are some advantages of PicoBSD?

§ Documentation and Web resources

What man pages should I read?
Where is the PicoBSD documentation?
How do I subscribe to the freebsd-small@freebsd.org mailing list?
How do I browse the freebsd-small@freebsd.org mailing list archives?
What PicoBSD-related web resources are available?
What are some academic references and web sites that describe research using PicoBSD?

 §  A few useful embedded PicoBSD procedures (most will also work on FreeBSD)

How do I make PicoBSD on a PC run ``headless'' (without monitor and keyboard)?
How do I use PicoBSD to make a cheap diskless web server?
How do I use PicoBSD to make a cheap Internet-enabled instrument?
How do I directly access I/O devices from an application program (use in and out instructions)?
How do I put PicoBSD on a flash disk?
How do I put PicoBSD on a hard disk?
How can I debug kernel code using polled serial I/O?

A PicoBSD build is driven by a private configuration directory which contains a slightly embellished FreeBSD kernel configuration file named PICOBSD. A number of other files in the configuration directory specify device node names, desired filesystem directory structure, script files, and the executable files to be included in the kernel. The build itself is driven by the picobsd master script. The picobsd script copies the PICOBSD configuration file to the configuration directory normally used for FreeBSD x86 kernel compiles, namely /usr/src/sys/i386/conf. (This document assumes the FreeBSD source tree has been installed in /usr, if yours is located elsewhere, adjust accordingly.)

The picobsd script is effectively the definition of PicoBSD. It is located at:

/usr/src/release/picobsd/build/picobsd

The FreeBSD crunchgen program does the ``crunch'' of all application object files; it essentially relabels the main() entry points in all the application's object files and creates a single application main() that dispatches to the required program based on the name by which the program is invoked. All object files are linked together to produce a single ELF executable file.

Virtual filesystems are created using the FreeBSD vn (Virtual Node) driver. The vn driver enables a file to be treated as a device (you can then mount a suitable initialized file). The filesystem created by the picobsd script contains a root directory tree and files as specified by an mtree configuration file and a directory tree rooted in the user's private configuration directory. This virtual filesystem image is copied into a reserved space in the kernel image file.

After the kernel file is created, a second filesystem is created on a virtual device file named ``picobsd.bin''. This file corresponds to a floppy device image. The kernel file is compressed and placed in this filesystem, bootblocks are copied to the floppy image, and the entire floppy image is then physically copied to a floppy.

The FreeBSD boot program (which is really a very small operating system in it's own right) simply scans the root directory of the device it boots from searching for a file named kernel (or a file of another name, if so indicated by the user entering a filename in response to the boot prompt's ``count-down''). This is the file that is loaded (and uncompressed, if necessary). This process is entirely driven by the kernel's filename (there are no hard-coded ``magic pointers'' to the code of the kernel to be loaded and started, although there are hard-coded pointers to the boot system's code).

A number of predefined ``private'' PicoBSD configuration directories are provided which build standard configurations of PicoBSD and serve as examples, templates, and starting points. In this document, these are called reference configurations and reference directories. These directories are used for reference builds, and produce reference PicoBSD systems.

In practice, PicoBSD is often used as a starting point for forking your own custom embedded system projects. That is, rather than simply deploying the predefined standard reference configurations, it may well be that most serious users of PicoBSD historically have been software engineers who have a valid reason to fork their own unique embedded system code-base. This can be a very reasonable thing to do because commercial embedded systems often have very long product lifecycles (decades) while potentially requiring maintenance at any level during the entire deployment of the product. The entire PicoBSD environment is flavored in many ways by this expectation.

There have been numerous custom variations of PicoBSD, and variations on this entire scheme. For instance, you could have more than one file of crunched applications, putting each such file on a seperate floppy image and distributing your system on multiple floppies.

The PicoBSD sources in /usr/src/release/picobsd contain a number of ``preconfigured'' PicoBSD configurations. These configurations each correspond to an existing reference configuration directory. The current reference directories are bridge, custom, net, dial, install, isp, and router. These may not work ``as-is'', so treat them as starter kits (these reference configurations are, however, maintained, so notify the ``freebsd-small@freebsd.org'' mailing list if you encounter a problem).

 *   Assure you are running a version of FreeBSD 4.3 Stable that includes the vn device. Check the current system's kernel configuration file for:

pseudo-device vn

You may have to recompile the FreeBSD kernel and possibly rebuild the ``/dev/vn*'' device nodes (Use MAKEDEV. This is normally not required.)

 *   Verify that you have a free vn device using:

#mount

If you see a mounted filesystem of the form ``/dev/vn0c on /tmp/picobsd.c2OlSJv7sk'', it is likely that a previous build of picobsd has failed. See the section on freeing a vn device that has been left in an in-use state.

 *   You will need a formatted blank floppy for a standard PicoBSD build. Insert the floppy in the drive, but do not mount the floppy.

 *   Select which configuration you want to build. The attributes of the various configurations are explained in more detail in the section that discusses the predefined reference configurations.

 *   Copy the PicoBSD build script /usr/src/release/picobsd/build/picobsd into your path, for instance, into /usr/bin or /usr/local/bin:

#su
#cp /usr/src/release/picobsd/build/picobsd /usr/local/sbin
#rehash

Obviously, you only need to do this step once.

 *   Build your selected configuration. For instance, to build the PicoBSD router reference system located in /usr/src/release/picobsd/router, do the following in the directory that you want to become the ``root'' of your PicoBSD work:

#su
#picobsd router


You have to be root to run the picobsd script. At the start of the script's execution, you will be prompted by a dialog menu. Hit return to continue. A FreeBSD kernel-build will then occur, followed by object file crunching. Finally a second menu will appear. Assure the floppy is physically inserted and hit return to write the floppy with a bootable image.

 *   Take the floppy to the system on which you want to run PicoBSD, and boot the floppy (or reboot the running system, if you want to simply bring up a sample PicoBSD). You do not have to umount the floppy. Be sure to check the machine's BIOS settings and assure that it is set to boot from the floppy.

That's it... After a successful PicoBSD build, in addition to putting a bootable image on the floppy, there will be a bootable file named kernel in the build directory located in the directory in which the picobsd script was run. For instance, if a router configuration build was done, the directory build_dir-router will exist in the directory from which you ran picobsd. A binary image of the bootable floppy, named ``picobsd.bin'', will also exist in this build_dir-router directory. The complete directory name depends on the name of your configuration (in this case, router). If you [Cancel] from the last menu (use Tab to select the [Cancel] button and then press Enter), the kernel and ``picobsd.bin'' files will both be created but the floppy will not be written.

#mount

If you see a mounted filesystem of the form ``/dev/vn0c on /tmp/picobsd.c2OlSJv7sk'', it is likely that a previous build of picobsd has failed. See the section on freeing a vn device that has been left in an in-use state.

 §   Assure the picobsd script is in your path.

Copy the PicoBSD build script /usr/src/release/picobsd/build/picobsd into your path, for instance, into /usr/bin or /usr/local/bin:

#su
#cp /usr/src/release/picobsd/build/picobsd /usr/local/sbin
#rehash


 §   Create your own PicoBSD configuration directory.

To work with your own configuration of PicoBSD, you need your own private configuration directory. Using FreeBSD 4.3 and later versions, this ``config'' directory can be anywhere. In previous versions, you created this directory as root in /usr/src/release/picobsd. You can still use this older style. The remainder of this section assumes a post-4.3 build. See the following section for pre-4.3 instructions.

Create your new configuration directory somewhere with the name you want to give your custom PicoBSD configuration. It is useful to base the initial contents of this configuration directory on one of the standard reference directories. For instance, to create a configuration directory named mysys, based on the bridge reference configuration, use:

#cp -R /usr/src/release/picobsd/bridge mysys

The reference configurations are directories located in /usr/src/release/picobsd. The current reference configurations are bridge, custom, net, dial, install, isp, and router. These may not work ``as-is'', so treat them as starter kits (these reference configurations are, however, maintained, so notify the ``freebsd-small@freebsd.org'' mailing list if you encounter a problem).

 §   Build PicoBSD using the picobsd script.

Before modifying your initial configuration, you may want to do a test-build with it as-is.

To do a complete PicoBSD build, you need a formatted and verified floppy. Assure that the floppy device (/dev/fd0c) is not mounted, as the script writes ``raw'' to the floppy using dd. You have to be root to run the picobsd script.

Assume you have created a work directory that you want to make the ``root'' of your PicoBSD work. In this directory you have created a directory called mysys that contains a copy of one of the standard PicoBSD configurations. To build your mysys configuration, cd to the work directory and do the following:

#su
#picobsd mysys

At the start of the script's execution, you will be prompted by a dialog menu. Hit return to continue. A FreeBSD kernel-build will then occur, followed by object file crunching. Finally a second menu will appear. Insert a floppy and hit return to write the floppy with a bootable image. Take the floppy to the system on which you want to run PicoBSD, and boot the floppy (or reboot the running system). Be sure to check the machine's BIOS settings and assure that it is set to boot from the floppy.

After the PicoBSD script completes, the floppy contains a mountable and bootable filesystem. You might want to mount it for verification. Once PicoBSD has booted from the floppy on the target machine and completed its rc boot script, the floppy will not be mounted. On the reference systems, you can interactively mount the floppy when PicoBSD is running on the target.

Results of the example build are left in the ``./build_dir-mysys'' directory automatically created in the directory in which you ran picobsd. After a successful PicoBSD build, in addition to putting a bootable image on the floppy, there will be a bootable file named kernel in this build directory. A binary image of the bootable floppy, named ``picobsd.bin'', will also exist in this build directory. The complete name of the build directory depends on the name of your configuration directory (in this case, mysys). If you [Cancel] from the last menu (use Tab to select the [Cancel] button and then press Enter), the kernel and ``picobsd.bin'' files will both be created but the floppy will not be written.

The picobsd script puts all executables and an image of a RAM-based root filesystem into the single kernel file. The kernel file in the floppy image is compressed (the kernel will be uncompressed at boot-time). The kernel file in the build_dir directory is not compressed. You can explicitly compress the kernel file using the kgzip utility.

The picobsd script looks for a configuration directory with a name that matches its argument. It first looks in the current directory. It then looks for a directory with matching name in ``$PICO_TREE''. If undefined, $PICO_TREE'' defaults to ``/usr/src/release/picobsd/''. For example, ``picobsd mysys'' would first look for ``./mysys'', then for ``/usr/src/release/picobsd/mysys''. Once a directory is found, it is assumed to be a PicoBSD configuration directory if a PICOBSD configuration file is present.

§ Customize your PicoBSD configuration.

In your private configuration directory:

 *   Edit the PICOBSD kernel configuration file to contain your desired FreeBSD kernel options and device support.

 *   In file config, add your desired /dev device nodes.

 *   In file ``crunch.conf'' specify the executables and libraries that you want to include, and the ``link names'' that you want to assign your executables. You also need to specify the directories containing your binary program Makefiles.

 *   Put the script files to include in your system in a directory tree named ``floppy.tree'' rooted in your configuration directory. You may have to create this directory. You can also put in your configuration directory a file called ``floppy.tree.exclude'' which specifies what files are to be eliminated from the default in `` /usr/src/release/picobsd/floppy.tree''.

NOTE: The script files typically included in the ``floppy.tree'' have traditionally been those files that you might want to edit after your system is operational. If you want to edit all these files on the floppy, you do not want these files built into the single kernel file, but rather want to put them in a /etc directory tree on the floppy. The files inside the compressed kernel image on the floppy cannot readily be accessed directly by standard tools (a copy of these file can be edited on the RAM-disk when the system is running, which means you can then copy them to a directory on the floppy). The current default behavior of the picobsd script is not to put the ``floppy.tree'' on the floppy, but rather to put all the contents of the ``floppy.tree'' into the kernel file, and then use a PicoBSD rc boot script that copies, prior to most boot script processing, any files in /etc on the floppy over the files in /etc in the memory filesystem. In this scheme there initially is no /etc directory on the floppy. To change this default behavior and put the ``floppy.tree'' on the floppy, edit the picobsd script and, near the top, change the first line in init_vars() from:

INCLUDE_FLOPPY_IN_MFS="yes"

To:

INCLUDE_FLOPPY_IN_MFS="no"

The default ``floppy.tree'' is located in the `` /usr/src/release/picobsd/floppy.tree'' directory. This tree forms the ``base'' floppy script collection. Files that you define in the ``floppy.tree'' directory within your private configuration directory will override or extend the base collection. You do not need a private ``floppy.tree'' directory. You can exclude files in the base collection using a file in your configuration directory named ``floppy.tree.exclude''.

 *   The files included in the /usr/src/release/picobsd/mfs_tree directory tree are the initial files included in the root file system built into the kernel file. Note that if the ``floppy.tree'' is included in the MFS, as described above, floppy files will override files with the same name in mfs_tree.

You can specify a complete directory tree structure for the root file system using a ``mfs.mtree'' file in your configuration directory This is optional, and can be used to create empty directories in addition to those populated by mfs_tree and ``floppy.tree'' files.

After customization, rebuild your PicoBSD system as described in the previous section on building PicoBSD using the picobsd script.

After most errors that abort the picobsd script, it is usually worth completely cleaning up the build that was aborted as described in the section ``How do I clean-up after a PicoBSD build?''. Also, use mount to check if any vn pseudo-devices are still mounted and configured.

Some common errors are:

 §   After a kernel link in the picobsd script, an error of the following form appears:

disklabel: /dev/vn1: No such file or directory
---> fail: Error <4> error code


vn device house-cleaning:

It is a good idea to clean up the remains of the PicoBSD build that died before attempting another picobsd build. When is starts, the picobsd script tries to locate an unused vn device, which is why in the above example error it complains about vn1 even though it was vn0 that was not properly unmounted and unconfigured (the system on which this error occurred only had a single vn device configured).

You should check the vn devices in this manner whenever the picobsd script fails for any reason.

 §   If an error message such as the following occurs that involves a binary included in PicoBSD, the pathname in the relevant ``crunch.conf'' referencing the binary file is probably inconsistent with the real directory structure:

`../../tinyware' is not a directory, skipping it

Perhaps things have moved. Perhaps the ``crunch.conf'' file assumes it is in the /usr/src/release/picobsd tree. The fix is to set the path correctly. An absolute path for your current development system should work.

 §   The build displays the following error toward the end of the script's execution:

MFS filesystem signature not found in kernel

The MFS filesystem image is too big to fit into the kernel. The size of the MFS is specified either interactively via the main dialog or as the first argument to the #PICOBSD comment in the relevant PICOBSD kernel configuration file. The comment above the argument line in the #PIOCBSD file indicates that this argument is named ``dev_sz''. When this argument changes, you need to also change the kernel MD_ROOT_SIZE option in the PICOBSD file to have the same value. Indeed, a mismatch between these values may be the cause of the error. A typical option line is:

options MD_ROOT_SIZE=2200 # same as def_sz

This error may also indicate a missing ``options MD_ROOT_SIZE'' statement or a MD_ROOT_SIZE parse error, resulting in no MFS space at all being configured into the kernel.

 §   An error message is displayed on the console at boot-time (or spotted later by dmesg) with the form:

pid 8 (cp), uid 0 on /: out of inodes

Unless you are trying to include way to many files, you can often fix this by increasing the size of the static inode array in the MFS. This will decrease the amount of available free space that remains in the MFS for file data.

You can increase the number of inodes either interactively, via the first picobsd menu, or by editing the PICOBSD file in the relevant configuration directory and changing the third argument in the #PicoBSD line (the comment on the previous line of the PICOBSD file indicates this is named the ``MFS_inodes'' argument). The fraction of space dedicated in a filesystem to inodes instead of data is ultimately specified as an argument to newfs, the utility that creates a new filesystem. The form of this argument is not a direct specifier, but rather indicates the number of bytes per inode, which is roughly the average file size you expect in the file system. Thus, to increase the number of inodes, you should decrease the existing MFS_inodes value.

The layout of the MFS filesystem is reported by picobsd near the end of the script before the second menu. It has an appearance such as the following:

Filesystem  1K-blocks     Used    Avail Capacity iused   ifree  %iused  Mounted on
/dev/vn0c        2103     1600      503    76%     308     202    60%   /var/vartmp/picobsd.9QsMbDpD3K

This indicates that 308 inodes are in use and 202 are free, so newfs calculated that it should allocate 510 inodes. Again, you only indirectly control this allocation, but a little experimentation will result in your ability to partition the filesystem as you desire.

 §   You ftp a binary program to a PicoBSD system, try to run it, and get the error message:

ELF interpreter /usr/libexec/ld-elf.so.1 not found
Abort trap

The program was linked assuming that it could link to a loaded library at run-time using dynamic linking, but the specified library (ld-elf.so.1) was not found. See the section on writing a statically-linked application for PicoBSD.

 §   The first thing PicoBSD prints when it boots is:

No /boot/loader

Is this an error? No. This indicates that the interactive FICL loader is not present (by design). The bootstrap will procede to directly boot the /kernel PicoBSD file.

 §   Attempting to mount a PicoBSD floppy on PicoBSD or FreeBSD always produces an error (on any machine) similar to:

mount: /dev/fd0c: Operation not permitted

If this message occurs with a PicoBSD floppy whenever you attempt to mount the floppy, the floppy has likely, at some point, either (1) been mounted when it was physically removed from a drive without a umount being performed, or (2) it was mounted when the power was turned off. Use the dmesg command to display the system error log and search for a message such as the following (the /mnt will correspond to whatever directory you tried to use as a mount-point for the floppy):

WARNING: R/W mount of /mnt denied. Filesystem is not clean - run fsck

Either run fsck against the floppy (``fsck /dev/fd0'') or, if you are absolutely certain of the machine from which you just ``popped'' it out without unmounting, put the floppy back in the drive and umount it before physically removing it again.

This is not a PicoBSD error per se, but can easily occur when you are working with a PicoBSD floppy, for instance, editing scripts or copying static applications. Note that a FreeBSD-formatted *ix floppy ``knows'' if, after being mounted, it has been cleanly unmounted via a umount.

Under PicoBSD, the boot floppy can be in this unmountable state, that is, it may not be possible to mount the boot floppy if it was explicitly mounted when a power-off occured (or it was popped out and moved). This does not interfere with the ability to boot the floppy, only the ability to mount it. Because not all configurations include fsck, it may be necessary to take the floppy to another FreeBSD or PicoBSD machine to run fsck. The router and net reference configurations do not include fsck.

Specify your accounts and passwords by directly editing the relevant ``etc/master.passwd'' file. Depending on your PicoBSD configuration tree, this file could be in `` /usr/src/release/picobsd/floppy.tree/etc/master.passwd'', a ``floppy.tree/etc/master.passwd'' in your configuration directory, or, also in your configuration directory, a ``floppy.tree.$SITE_NAME/etc/master.passwd'' subconfiguration directory corresponding to your subconfiguration $SITE_NAME (which is specified as the optional second argument to picobsd, see the section on the syntax of the picobsd command).

You can change a password on a PicoBSD floppy using the procedures described to edit PicoBSD /etc scripts or to edit or add a file to an existing floppy image.

# picobsd [options] floppy_type site_name
#
# Where floppy_type is a directory where the picobsd config info
# is held, and ${floppy_type}/floppy.tree.${site_name} contains
# optional site-specific configuration.
#
# For Options, see the bottom of the file where the processing is
# done... so
#
# This script depends on the following files:
#
# in ${PICO_TREE} :
#   Makefile.conf       Makefile used to build the kernel
#   config              shell variables, sourced here.
#   mfs.mtree           mtree config file
#
#   floppy.tree/        files which go on the floppy
#   mfs_tree/           files which go onto the mfs
#
# in ${MY_TREE} :
#   PICOBSD             kernel config file
#   config              shell variables, sourced here.
#   crunch.conf         crunchgen configuration
#   floppy.tree.exclude files from floppy.tree/ which we do not need here.
#   floppy.tree/        local additions to the floppy.tree
#   floppy.tree.${site}/ same as above, site specific.

In the above, ${PICO_TREE} is the root of your PicoBSD source tree, for instance, /usr/src/release/picobsd. The ${MY_TREE} directory is usually either one of the reference configuration directories, such as /usr/src/release/picobsd/router, or your own private configuration directory, which can be located anywhere. You do not explictly set ${MY_TREE}. The picobsd script first looks for a directory with the same name as it's floppy_type argument in the directory from which you ran the script, and then looks for a subdirectory with that name in ${PICO_TREE}, which defaults to ``/usr/src/release/picobsd''.

The floppy_type argument specifies the name of an existing PicoBSD configuration directory. The picobsd script will look for a directory with this name first in the current directory and then in the directory specified by the $PICO_TREE environment variable. If you have not set this variable, it defaults to ``/usr/src/release/picobsd/''.

The optional site_name argument specifies the name of a ``subconfiguration'' within the configuration directory specified by floppy_type. The subconfiguration will itself be a directory, with a name of the form ``floppy.tree.$site_name''. This subconfiguration directory should contain a /etc directory containing scripts and files which you want to replace those with the same names in the ``floppy.tree/etc'' directory in the same configuration directory (that is, the directory corresponding to floppy_type).

Thus, the command ``picobsd my_486 old_isa_486'' would first try to use the configuration directory ``./my_486'' and subconfiguration scripts in ``./my_486/floppy.tree.old_isa_486/etc''. If no ``./my_486'' configuration directory was found, picobsd would try to use /usr/src/release/picobsd/my_486/ and ``/usr/src/release/picobsd/my_486/floppy.tree.old_isa_486/etc''.

The command options are:

 

--floppy_type n
The size of the bootable floppy image is set to ``n'' KBytes. The default is 1440, the size of a standard 3.5 inch floppy.

 

-n
Do not display the first interactive menu. The final interactive dialog, which prompts for permission to write to the floppy will occur, so this switch does not allow complete ``batch'' mode execution.

 

-clean
Delete the build_dir directory before starting. This directory will have a name of the form build_dir-mysys, where mysys is the name of your PicoBSD configuration directory, as specified by argument floppy_type.

 

-verbose
This option makes the script enter a semi-interactive trace mode. It produces various output displays as it runs and stops after each display until user confirmation is recieved. This provides insight into the action taken by the script at each major step.

$INCLUDE_FLOPPY_IN_MFS
In addition to the command-line arguments, there is an important environment variable set at the start of the picobsd script. This variable, ``INCLUDE_FLOPPY_IN_MFS'', should be set to ``yes'' if you want the contents of your ``floppy.tree'' to be placed, gzipped, into the /fd directory in the MFS filesystem (the RAM-filesystem) built into the kernel. The files will be uncompressed and copied to your RAM-based /etc directory at boot, that is, they will be copied over the files originating in the /usr/src/release/picobsd/mfs_tree/etc directory. If INCLUDE_FLOPPY_IN_MFS is not ``yes'', the files in your floppy tree will be placed on the floppy in /etc. From here they will also be copied over the memory-resident /etc. Note that even if you specify INCLUDE_FLOPPY_IN_MFS="yes", you can later create a /etc on your floppy and put updated startup script files on the floppy. These files will be copied into /etc before other boot-time script processing occurs.

The default is INCLUDE_FLOPPY_IN_MFS="yes".

$SRC
The location of your FreeBSD source tree.

$OBJ
The location of the object tree. This is normally ``/usr/obj-pico''.

$PICO_TREE
The directory containing the picobsd source tree. This includes the reference directory configurations, and the build directory that contains the picobsd script. This defaults to ``/usr/src/release/picobsd''.

$FLOPPY_SIZE
The size of the floppy image file in Kbytes. This size should match the size of the device you intend to write. The $FLOPPY_SIZE environment variable defaults to 1440 Kbytes, the size of the most common 3.5 inch floppy. The current picobsd script writes to a ``floppy device'' using a device node of ``dev/rfd0.${FLOPPY_SIZE}''.

Results:

The principal outputs of the picobsd script are (1) a bootable floppy, (2) an image of the floppy saved in file ``picobsd.bin'', and (3) a bootable kernel file. The two files are in the build_dir-$floppy_type directory (which itself will be located in the directory in which you executed the picobsd command).

Unless you change the INCLUDE_FLOPPY_IN_MFS default, the floppy and floppy image will only contain the bootable kernel file.

If you [Cancel] out of the last menu dialog in the picobsd script, the two files will be created, but the ``picobsd.bin'' file will not be written to the floppy, which is useful if you are booting the kernel over a network, from flash, etc..

N  --> READY, build it <---
T  Type: my_486 name my_486
K  edit Kernel config file
E  Edit crunch.conf file
S  MFS Size: 2200kB
I  Init type: init
F  Floppy size: 1440kB
M  MFS bytes per inode: 5000
U  UFS bytes per inode: 32768
$  Site-info:
Q  Quit

[  OK  ]       Cancel 

 *  Select ``I Init type: init'' to select the program to run as your ``init'' program (Process 1). A dialog will appear which allows you to select the normal FreeBSD init program, or the PicoBSD oinit program in the /usr/src/release/picobsd/tinyware collection. The oinit program contains a small built-in shell that can only handle simple command lines, not the normal sh syntax. If oinit is used the technique of updating files in /etc cannot be used, unless you write your own simple etc/rc or ``etc/oinit.rc'' to do so (see the section on oinit).

 *  Select ``F Floppy size: 1440kB'' to select the size of the ``picobsd.bin'' image that is produced. A dialog will appear with 4 standard sizes that correspond to various devices (the largest is 4 Mbytes). Typically this is the image that you would write to a floppy boot disk, but at the end of the script if you cancel from the floppy-write menu, the output file image will be left in the build_dir-$floppy_type directory of the configuration directory.

 *  Select ``M MFS bytes per inode: 5000'' to specify the fraction of the MFS (the in-kernel RAM-filesystem) you want to devote to inodes. This is the average file size you expect in the ``fully-loaded'' MFS, with some pad. Set this with respect to the ``MFS Size'' option that was previously set. To increase the number of inodes (that is, the number of files that can exist), you need to decrease this value.

 *  Select ``U UFS bytes per inode: 32768'' to specify the fraction of the floppy filesystem you want to devote to inodes. Actually, the ``floppy'' need not be a floppy, and so you want to select this size in conjunction with the ``Floppy size'' option. Again, this is the average file size you expect when the floppy is fully loaded. The newfs utility will figure out how many inodes this requires. To increase the number of inodes, you need to decrease this value.

After the picobsd script has finished, a new boot floppy will only have two used inodes - the root directory and the /kernel file (assuming the MFS is in the kernel).

 §   Unlike some toolsets, you are not required to go through the menu to edit the files in your configuration directory. There is no reason why you cannot edit the files in your configuration directory directly using any editor of your choice. If you are in a repetitive developmnet and debugging cycle, it is often easiest to simply leave all relevant files open in an editor and skip the use of the menus.

There is no way from the menu to edit the config file, which specifies your desired device nodes. You have to do this directly.

The PICOBSD file is a normal FreeBSD kernel configuration file with the addition of a comment line that starts with ``#PicoBSD''. This comment line supplies arguments to the picobsd script.

Edit the PICOBSD file to include your desired FreeBSD kernel options. In particular, you often will want to specify drivers (devices).

Edit the #PIOCBSD comment/argument line to change the size of MFS RAM-disk, the number of inodes in either the MFS or on the floppy, or the ``init'' program. An example of the #PIOCBSD comment/argument line (from /usr/src/release/picobsd/router/PICOBSD) is:

#Line starting with #PicoBSD contains PicoBSD build parameters
#marker        def_sz  init    MFS_inodes      floppy_inodes
#PicoBSD       1200     oinit   3072            32768
options MD_ROOT_SIZE=1200

 *   The first argument in the ``#PicoBSD'' comment indicates the size in 1Kbyte blocks of the MFS filesystem (this argument is passed as the ``count='' argument to the dd command that creates the file backing the MFS image, using bs=1k).

 *   The second argument specifies the program to be run as the init process, that is, Process 1. This program is ultimately responsible for activating all other processes, so changing this argument can totally change the nature of the system you build. The oinit program in the above example is a tiny ``template starter'' alternate to the traditional FreeBSD init program. See the section on oinit.

 *   The third argument is the ``-i avg_bytes_per_file'' value passed to the newfs invocation that creates the filesystem on the MFS. This indirectly specifies the number of inodes, that is, the maximum number of files that you expect to fit on the filesystem of size ``def_sz''.

 *   The fourth argument is the ``-i avg_bytes_per_file'' value passed to the newfs invocation that creates the floppy image filesystem. This indirectly specifies the number of inodes, that is, the number of files that you expect to fit on a filesystem of $FLOPPY_SIZE. The $FLOPPY_SIZE environment variable defaults to 1440 Kbytes, the size of the most common 3.5 inch floppy.

 §   config

The config file lists all the device nodes that are to be created in ``/dev''. Edit this file and add any device node names you need to the MY_DEVS string. There is only a single line in the typical config file. An example of this line (from the bridge configuration) is:

MY_DEVS="std tun2 vty10 fd0 ad0 pty0 cuaa0 cuaa1 bpf0 bpf1 bpf2"

Any number of environment variables that you decided to use could be defined in your config file.

 §   crunch.conf

The ``crunch.conf'' file controls the application crunchgen, that is, it indicates which executables to link into the single executable ELF file.

Edit ``crunch.conf'' and add srcdirs, progs, and libs statements as needed. The progs statements specify the pathnames of the executables that you require. The srcdirs specify the pathnames of the directories containing the Makefiles that correspond to the executables. Note that crunchgen requires a special ``makefile format'' (a FreeBSD standard), but you can easily create a pseudo-makefile with this format if required.

The crunchgen program, in effect, renames all program main() routines and creates a single main() with a little stub code that dispatches to the real entry-point based on the arg0 command-line name. Because of this, ``links'' are important in the PicoBSD file tree (so as to provide desired names). You specify your desired link names in the ``crunch.conf'' file using the ln command.

See ``man crunchgen'' for the syntax of the statements in the ``crunch.conf'' file. Also see the comments included in the ``crunch.conf'' files in the reference directories.

 §   floppy.tree (optional)

Each configuration directory can root its own ``floppy.tree'' directory tree. If it exists, the ``floppy.tree'' directory normally contains a /etc directory which includes the /etc/rc script and other scripts that you want to build into the kernel, such as ``/etc/rc.firewall''. Create and edit files, directories, scripts and configuration files in the ``floppy.tree'' directory tree as required.

The files in the floppy tree are typically the files that you might want (potentially) to edit on the floppy. The default behavior of the current PicoBSD is not to put these files on the floppy outside the kernel file, but to include them directly in a /fd directory in the MFS RAM-disk built into the kernel (see the section on INCLUDE_FLOPPY_IN_MFS to change this behavior).

The directory `` /usr/src/release/picobsd/floppy.tree'' contains a ``base collection'' of scripts and other /etc files that will be included in PicoBSD. In the kernel you build, the version of these files in your ``floppy.tree'' is copied over the files in this tree.

 §   floppy.tree.exclude (optional)

Each configuration directory can optionally contain a ``floppy.tree.exclude'' file. Each line in this file contains the pathname of a file in the ``base collection'' in ``/usr/src/release/picobsd/floppy.tree'' that is not to be included in the PicoBSD system that you build. An example exclude file, from the bridge collection, is `` /usr/src/release/picobsd/bridge/floppy.tree.exclude''.

 §   mfs.mtree (optional)

Each configuration directory can contain a ``mfs.mtree'' file which specifies, in the format used by the mtree utility, a map of the directory structure you want to create in the RAM-based file system. You do not need to define a ``mfs.mtree'' directory structure if you do not need any directories other than those included in /usr/src/release/picobsd/mfs_tree.

See /etc/mtree for examples of mtree specification files.

The current reference configuration directories are located in directory ``/usr/src/release/picobsd''. Start with the system closest to your needs and adapt it to your circumstances. The following briefly describes these reference configurations:

 §   bridge   ( /usr/src/release/picobsd/bridge)
This PicoBSD system includes the ipfw firewall, dummynet, and bridge. Dummynet is software that enhances the ipfw firewall code with the ability to do bandwidth limiting and a wide variety of other features of interest to network researchers and technical ISPs (traffic shaping and generation). The bridge facility permits a PC to operate as a software ``bridge'', where ``bridge'' is used in the hardware sense, that is, as a repeater-style connection that allows two Ethernet cables to appear to be a single Ethernet cable. The FreeBSD maxusers kernel-sizing estimate is set to 20. See ``man dummynet'' and ``man bridge''.

 §   custom   ( /usr/src/release/picobsd/custom)
Although this directory at one time apparently supported custom builds, currently it apparently contains an (older) experimental Makefile that was intended to replace the picobsd script. This was apparently written at a time when a PicoBSD system required two floppies.

 §   dial   ( /usr/src/release/picobsd/dial)
This is basically a minimal end-user system that could be used on a low-end PC to connect to an ISP using ppp over a dial-in connection. It does not contain any firewall code. The FreeBSD maxusers kernel-sizing estimate is set to 3.

 §   install   ( /usr/src/release/picobsd/install)
This appears to be a simple PicoBSD-based install system. This PicoBSD system contains a script, ``floppy.tree/etc/doinstall'', that does a network fetch to install a FreeBSD system. What is the status of this kit?

 §   isp   ( /usr/src/release/picobsd/isp)
This system is intended to be operated as an ISP modem-server supporting 8 serial ppp connections. It includes the ipfw firewall and Dummynet code. This system defines no scripts or configuration files of its own, and thus is entirely dependent on the scripts in the ``base collection'' in the /usr/src/release/picobsd directory ( mfs_tree and floppy_tree). The FreeBSD maxusers kernel-sizing estimate is set to 20.

 §   net   ( /usr/src/release/picobsd/net)
This is a generic network ``end node''. It does not include Dummynet, but does support ipfw and ppp. The FreeBSD maxusers kernel-sizing estimate is set to 10.

 §   router   ( /usr/src/release/picobsd/router)
This system is similar to the ISP system but it does not support any special serial devices or ppp, it does not include Dummynet, and it contains no special applications. Basically this system is intended to be a running TCP/IP stack in an Ethernet networked environment. It includes ipfw firewall support. This system defines no scripts or configuration files of its own, and thus is entirely dependent on the scripts in the ``base collection'' in the /usr/src/release/picobsd directory ( mfs_tree and floppy_tree). The FreeBSD maxusers kernel-sizing estimate is set to 10.

An important operational characteristic of the router system is that it runs the minimal oinit version of the Process 1 init program. Presumably a system that is being used as a dedicated network router/firewall does not want to waste memory on a user shell. The source to this program is in ``/usr/src/release/picobsd/tinyware/oinit/''. An important implication of this is that the scheme for overwriting and updating the files in /etc is not supported by the router configuration. It runs a minimal rc script consisting only of simple command lines.

Because of the aformentioned use of oinit, for a typical PicoBSD router-style deployment, the ``full-blown'' bridge configuration is probably recommended.

The PicoBSD /etc/rc boot script is different than that used in FreeBSD. The FreeBSD ``/etc/rc.conf'' scheme, in which the boot sequence is controlled by overriding default shell variables, is not used in PicoBSD due to size. PicoBSD does, however, use a ``/etc/rc.conf'' file in which shell variables are set. In addition, PicoBSD uses a somewhat subtle initial rc scheme that involves uncompressing and merging multiple /etc directories and which always overwrites the initial rc script, /usr/src/release/picobsd/mfs_tree/etc/rc, while it executes.

When the floppy tree is built into the kernel, the floppy /etc files are put in MFS filesystem directory ``/fd/etc''. All files in /fd/etc are compressed (gzipped, that is, are ``.gz'' files).

The files that you want to statically include in the MFS RAM-filesystem are located at /usr/src/release/picobsd/mfs_tree in the source directory tree. This directory, in the running system, will be rooted at ``/''. These statically included files are primarily small versions of script files that rarely change, such as disktab, protocols, services, shells, and termcap.

The mfs_tree contains a very simple /etc/rc script (located in /usr/src/release/picobsd/mfs_tree/etc). This is the initial script executed upon boot. It:

 *   Enters the /fd directory and recursively copies the /fd/etc/ tree to /etc. This merges etc files defined in mfs_tree/etc with any gzipped files from ``floppy.tree/etc'' included in the kernel due to INCLUDE_FLOPPY_IN_MFS="yes".

 *   The rc script then returns to ``/'', and mounts the floppy disk (/dev/fd0c) on /fd.

 *   It then repeats the process of copying all files from /fd/etc into /etc and then dismounts the floppy. This will copy any files into /etc that were put on the floppy using ``floppy.tree'' and INCLUDE_FLOPPY_IN_MFS="no", or which you have manually edited on the floppy (perhaps using a host machine or PicoBSD). At build time, the original ``floppy.tree'' sources may be located either in a private ``floppy.tree/etc'' configuration directory, or in the base ``/usr/src/release/picobsd/floppy.tree/etc''.

 *   The rc script then enters /etc and scans the directory for all files for which a gzipped version also exists, and it deletes the non-gzipped files (that is, for all files where foo.gz exists, foo is deleted). This means that if you want to overwrite a file that exists in a floppy tree built into the kernel image (that is, in /fd) with a new file that is actually located on the floppy, the new file must be gzipped.

 *   All gzipped files in /etc are unzipped.

 *   The pwd_mkdb utility processes the ``master.passwd'' file to create a valid binary password ``database''.

 *   Finally, the initial /etc/rc script executes the script /etc/rc, that is, itself. However, the previous steps assure that the /etc/rc file will have been overwritten. The source to the new /etc/rc can come from a number of original locations. It may have come from the default ``base'' rc script defined in the ``/usr/src/release/picobsd/floppy.tree/etc''. It may be a script defined in the ``floppy.tree/etc'' directory of a PicoBSD configuration directory, if such a file exists. Finally, it will be the gzipped script located in ``/etc/rc.gz'' on the boot floppy, if such a file exists.

Because of its self-modifying behavior, it is important that the initial mfs_tree/etc/rc script remain less than 1K.

Note that the gzipped /fd/etc files are not by default deleted from the RAM-disk, which typically uses up some 20K of memory.

Once the system boots, the RAM-filesystem is volatile and files can be edited, etc... Such modifications will be lost, of course, upon reboot. There is no easy way to permanently edit a file included in the kernel image, however, the process described in the previous section on the boot rc script explains how a file to be updated can be overwritten at boot time by new files placed on the floppy. To create a new /etc file, the floppy can be mounted as a normal filesystem (either from a host or from PicoBSD after PicoBSD boots).

The procedure to update a /etc script is: (1) edit copies of the script files you want to update, (2) gzip the files, (3) mount the PicoBSD floppy, (4) create a /etc directory, if it does not exist, on the PicoBSD floppy, and (5) put the updated and gzipped script files in /etc on the floppy. The new files will then overwrite the original files at boot time.

For instance, to change the motd ``message of the day'' login file using a PicoBSD system built with ed and gzip:

 #mount /dev/fd0 /mnt
 #cd /mnt
 #mkdir etc
 #cd etc
 #ed motd
  H
  P
  a
  *** Hello there, world!!!!***
  .
  wq
 #cat motd
 #gzip motd
 #ls
 #
 #cd
 #umount /mnt
 #reboot
 #

In the above, a ``mount /dev/fd0c /mnt'' should work as well. Note that a floppy ``knows'' if, after being mounted, it has been cleanly unmounted via a umount. If you get persistent ``mount: /dev/fd0c: Operation not permitted'' errors while attempting to mount a floppy, check with dmesg for ``run fsck'' warnings - the floppy was likely ``popped'' out without a manual umount.

The procedure described in this section enables persistent (re)editing of startup scripts (put ed in your ``crunch.conf'' if you are a minimalist, or try ee). The script /usr/src/release/picobsd/mfs_tree/stand/update automates this process, including saving an updated password file.

Beware that the procedure described here does not work for the router configuration because it uses oinit, which requires either a minimal commands-only rc file, or (depending on a #define), its own ``etc/oinit.rc'' file. If ``oinit.rc'' is used, all its lines must either be comments that start with a #, or valid executable command-lines.

Suppose you want to edit a new version of a /etc script file. You can mount the floppy (``mount /dev/fd0 /mnt'') and put the gzipped file in the /etc directory on the floppy, as described in the section on updating a script file. Alternatively, you can mount the ``picobsd.bin'' floppy image file, and put the new gzipped file in the /etc directory in the image file. You can then create as many floppies as you like that include your new file by using dd to copy the ``picobsd.bin'' image file to a real floppy. For example, to add a new rc file to a floppy image named ``my_old_picobsd.bin'' in the current directory:

 #su
 #mount
 #vnconfig -c -s labels vn0 my_old_picobsd.bin
 #mount /dev/vn0c /mnt
 #mount
 #cd /mnt
 #
 #echo Create a new etc, or gunzip and edit existing files...
 #
 #mkdir etc
 #cd etc
 #cp /tmp/my_new_rc rc
 #
 #gzip rc
 #
 #cd
 #umount /mnt
 #vnconfig -u vn0

Now you can write the image file to a boot floppy.

The first vnconfig configures (``-c'') the /dev/vn0 device and sets a flag to use the diskslice label on the device (``-s labels'') This means the existing ``disk'' label, which contains the *ix partition information, is respected. After this command, the device /dev/vn0 is accessible. The bytes of the device are the bytes contained in file ``my_old_picobsd.bin''. At this point the /dev/vn0 device can be mounted and unmounted as if it were any block device. The final vnconfig command unconfigures (``-u'') device /dev/vn0. Be sure to do this, as the picobsd script needs a free vn device. After the unconfigure, the mapping between the device and file no longer exists; /dev/vn0 can no longer be accessed as a device.

Note that the gzip step is not optional if the configuration has previously used a ``floppy.tree/etc/rc'' script! This is because the ``first-level'' rc script (source in `` /usr/src/release/picobsd/mfs_tree/etc/rc'') deletes all the files in /etc that have a corresponding gzipped version. If the new file is not gzipped, this will delete your new version of the rc file that came from the floppy, leaving the old gzipped rc from /fd/etc/rc to become the executing rc.

An advantage of this style is that you can edit startup scripts on a large host with your favorite visual editor at normal I/O speed (not floppy-speed!).

Often, it is almost just as fast to do a rebuild of PicoBSD. However, this procedure may be useful if you can no longer build PicoBSD, for instance, you no longer have the FreeBSD source installed.

The netstat utility in FreeBSD is a stripped-down version named ns. A link exists with the name netstat. Not all changes are simple ``throw-outs'', for instance, PicoBSD's ``netstat -w 1'' assumes a CRT.

Instead of using dmesg to redisplay console messages (such as the driver boot probe messages), PicoBSD uses the msg utility (also linked to the dmesg name).

PicoBSD uses a stripped-down version of vmstat called vm. It automatically enters a loop with a display in the ``-w 5'' style.

If oinit is used (currently it is only used for the router reference configuration), the user's ``shell environment'' is quite different than for the other systems, which use sh as the shell. Because oinit does not parse command lines it is used with either a minimal line-at-a-time rc file or it's own ``etc/oinit.rc'' file. The default rc file in this case do not support the scheme for updating /etc files by replacing them with updated versions from the floppy.

Some versions of PicoBSD may use stripped-down versions of ps (the source is in picobsd/tinyware).

None of the standard PicoBSD builds include any version of more, probably due to its size (more is really a complete old-fashioned text-browser).

PicoBSD does support virtual consoles, which can be accessed using <alt>-F1, <alt>-F2, ..., <alt>-F8.

When running X-windows on FreeBSD, you cannot reboot by pressing <ctl>-<alt>-<del> (which otherwise works on both). The standard PicoBSD reference configurations do not include shutdown. They do include reboot.

Many FreeBSD executable applications are linked assuming they can dynamically link to loadable libraries. Attempting to run such a binary on a PicoBSD system will fail because the shared library will not be found. To get around this problem, either statically link the application as described in the section on static linking, or ``crunch'' your application using crunchgen into the binary file included in the filesystem contained in the system image. Using crunchgen requires some commands in the ``crunch.conf'' file and at least a minimal Makefile in your application directory. The crunchgen utility requires a standard FreeBSD Makefile. From ``man crunchgen'':

"...the Makefile must contain the target depend, and it must define all object files..."

#
#
# Makefile for picobsd crunchgen
#
PROG=my_serv
SRCS= my_serv.c my_lib.c
OBJS= my_serv.o my_lib.o
NOMAN=yes

.include <bsd.prog.mk>

Assuming the above Makefile and C code is in directory /usr/my/demo/code, in your PicoBSD configuration directory, edit the ``crunch.conf'' file to contain the lines:

srcdirs /usr/my/demo/code

progs my_serv
special my_serv objvar OBJS
special my_serv srcdir /usr/my/demo/code
special my_serv objdir /usr/my/demo/code

When using this pseudo-Makefile, the ``.o'' files will need to exist in ``/usr/my/demo/code'' before the picobsd script executes. If you are compiling files by hand, you can generate the ``.o'' files for my_serv using:

#gcc -c my_serv.c
#gcc -c my_lib.c

Rebuild your version of PicoBSD, and test your application.

Depending on your environment, you may need to include such utilities as fdisk and disklabel in your PicoBSD configuration.

Filesystem  1K-blocks     Used    Avail Capacity iused   ifree  %iused  Mounted on
/dev/vn0c        2103     1600      503    76%     308     202    60%   /var/vartmp/picobsd.ObsQn6JZW8

 The build process was completed successfuly.
 Filesystem  1K-blocks     Used    Avail Capacity iused   ifree  %iuse
 /dev/vn0c        1403     1268      135    90%       2      60     3%

Well, FreeBSD, naturally, since FreeBSD and PicoBSD are really the same thing. The most up-to-date PicoBSD development environment as of this date (June-2001) is FreeBSD 4.3 Stable. PicoBSD may not build under FreeBSD Current (this may change by the time you read this). Beware that PicoBSD procedures (such as those described in this document) can change significantly between FreeBSD versions, so check the freebsd-small@freebsd.org e-mail list archives.

To get PicoBSD, obtain FreeBSD with sources. Once FreeBSD is installed, assuming the sources are in the default /usr/src directory, the PicoBSD sources are in ``/usr/src/release/picobsd''.

There are a number of ways to get FreeBSD with sources and keep it up-to-date. You can subscribe to one of the commercial services that ship FreeBSD on CD-ROM or DVD. You can download FreeBSD CD-ROM images over the Internet and burn a bootable CD. You can ftp the sources from one of the FreeBSD source mirror sites. You can use cvs or cvsup to obtain sources from a FreeBSD CVS repository. You can use ctm to get sources and source diffs via e-mail.

The CVS system is used by the FreeBSD project to manage the source code tree. In practice, once you have installed a source kit (perhaps from a CD-ROM image), most FreeBSD developers seem to use cvsup. The cvsup system runs on top of CVS and, in effect, only updates files in your source tree from the repository that a hash indicates have changed.

The /usr/src/release/picobsd/build/picobsd script is PicoBSD. Read this script file for the ``real'' documentation. The header of the picobsd script file contains usage notes. This script is, among other things, a wrapper for a FreeBSD kernel build. It creates a ``virtual disk device'' using a file and makes this (file) a bootable FreeBSD (PicoBSD) disk image by putting in the disk image: (1) a root file system, (2) boot blocks, and (3) a bootable kernel in the ``/'' directory. Startup scripts are included in the memory-based filesystem included internal to the kernel file itself.

You have to be root to run the picobsd script because it needs to mount the virtual devices and write raw to the floppy.

In earlier versions of PicoBSD, the picobsd script was named build.

The PicoBSD build cycle builds the floppy ``disk image'' file and then at the very end does a block-block copy of this image to floppy, using dd (Device Dup). You do not need to build or use the floppy image. You can just netboot the kernel file, boot it from flash, etc..

In the typical development cycle in which you are editing source code files, after the first PicoBSD build following builds will go much faster (only the files you have changed will be recompiled).

The overall steps performed by the picobsd script are now outlined, using a sort-of shell-command pseudo-code and noting the names of relevant shell script routines.

 §   Setup variables and do the initial setup menu dialog (init_vars(), main_dialog()).

 §   Build the kernel (build_image()). The build_image() routine is the main driver for building the kernelfile and putting the MFS and floppy tree inside it. The steps performed by build_image() are now described.

 

 §   Read in the config file (init_stage1()).

 

 §   Build the initial kernel file and copy it to a work directory (do_kernel()). The actual kernel compile is driven by make using
`` /usr/src/release/picobsd/build/Makefile.conf''.

#make
#cp
#strip


 

 §   Create the floppy filesystem in a work directory (populate_floppy_fs()). This is done before creating the memory filesystem so that the floppy filesystem can be copied into the memory filesystem, if desired.

#tar
#gzip etc/*


 

 §   Create the memory filesystem (MFS) (create_mfs(), init_fs_image()).

#dd an image of the size specified in the PICOBSD file.
#dd boot1 to make it bootable.
#vnconfig the image (make it accessible as a device).
#disklabel to create a *ix disk partition table (disk label).
#newfs to create the filesystem.
#mount to make it accessible for normal utilities.

 

 §   Populate the MFS file system (populate_mfs()).

#cd into the configuration directory.
#mtree to create the MFS directory structure.
#ln
#MAKEDEV to create device nodes.
#crunchgen crunch.mk to preprocess the applications to crunch.
#make crunch.mk to crunch the onjects into crunch1.
#mv to put crunch1 in /stand/crunch in the MFS filesystem.
#tar to copy mfs_tree files from configuration directories to the MFS filesystem.
#cp -R floppy.tree into /fd in the MFS if INCLUDE_FLOPPY_IN_MFS="yes".
#umount virtual MFS device.
#fsck
#vnconfig -u, which returns the file to ``normal'' (not a device).

All binary executable files are actually in a single file, /stand/crunch. The /stand directory contains links which refer to all binaries, and directories such as /bin and /sbin are simply links to /stand.

 

 §   Create ``picobsd.bin'', the floppy disk image (fill_floppy_image() (Part I)).

#dd a file to floppy size.
#dd boot1 to make the file bootable.
#vnconfig to make the file accessible as a device.
#disklabel to write boot records (and create a single partition disk).
#newfs to create a filesystem in the file.
#mount to make the filesystem accessible.

 §   Copy the MFS to the kernel, compress the kernel, and copy it to the floppy image. (fill_floppy_image() (Part II)).

#cc write_mfs_in_kernel.c
#write_mfs_in_kernel to actually put the MFS in the kernel.
#kgzip the kernel.
#cp the kernel to /kernel in the floppy tree.

The file ``/usr/src/release/write_mfs_in_kernel.c'' is a little program compiled every execution of the picobsd script. It ``zaps'' the MFS filesystem image into the kernel image at a location it finds by scanning the kernel file for a byte string literal ``MFS Filesystem goes here''. Note ``write_mfs_in_kernel.c'' is not in the PicoBSD tree (it has other uses as well). If your MFS filesystem becomes too large to fit in the kernel, the error ``MFS Filesystem signature not found'' will likely occur. Increase the MD_ROOT_SIZE specified via the second argument in your PICOBSD configuration file. This may result in a kernel too large to fit on the floppy.

 §   Put the ``floppy.tree'' in the floppy image, if needed (fill_floppy_image() (Part III)).

#cp the ``floppy.tree'' into the floppy image if it was not already copied into the MFS (that is, if it is not already inside the compressed kernel file).

 

 

 §   This completes the build_image() routine.

 §   Write the floppy image to the floppy disk (do_install()).

#dialog to display the confirmation dialog.
#dd picobsd.bin -> /dev/rfd0 to write the floppy.

http://people.freebsd.org/~picobsd/tinyware

The tinyware directory in /usr/src/release/picobsd/tinyware contains small versions of a few standard system utilities, in particular vmstat and netstat. These are smaller than their FreeBSD counterparts and are the versions typically used with PicoBSD.

      /usr/src/release/picobsd/mfs_tree/etc    (top, base-class, super-class)
      /usr/src/release/picobsd/floppy.tree/etc
      $CONF_DIR/floppy.tree/etc
      $CONF_DIR/floppy.tree.$SITE_NAME/etc