BRECIS uClinux Release 2.5 Beta One -- 21 May 2003


INTRODUCTION:
This file contains instructions for
	modifying and building the ramdisk image
	modifying and building the romdisk image
	nfs mount instructions
	setting the time zone
	getting CGI to work with thttpd
	rom file system
	userland information
	using PCI/mini-PCI/Cardbus
	making a clean build

This write-up assumes that:
	the user is using the bash shell
	any example commands are being executed in the appropriate
		directory,
	

Sample FAQ:

  a) Is this based on kernel.org?
        Yes, 2.4.20 from November 28th, 2002, with code from www.uclinux.org.
	In the CHANGES file, there is a list of files and directories added,
	and a list of files changed with a date that the code was compared
	with 2.4.20.  Future work will make this list out-of-date.

  b) What system calls do NOT work?
        The mmap() system call works for normal use.  Anything requiring
        an MMU will not work.  (There are dozens of options to mmap/munmap.)
        Otherwise, please report the failure, as everything should work.
        -- Please see below related question: "What kernel options work?".

  c) What "userland" library and commands comes with this?  How close to
     current i386 RedHat/debian/mandrake are these?
        Currently uC-src is from uClinux -- with fixes and additions.  The
	default libc is from http://uclibc.org snapshot of 2002-09-29.  uclibc
	is a stripped down library designed to make small executables, not be
	completely compatible with glibc.  The uC-src/real has a bunch of
	programs that are "bigger" and more complete.  For a "small" system,
	you may not wish these.

  d) What cross-development platform is needed?
        Brecis supports RedHat 7.1, 7.2, 7.3, and 8.0  We have developers
	using non-linux ("unix-like") systems.  Tools required include:
	bison, gnu sed, gnu make, /bin/bash, /bin/sh (possibly bash compiled
	as sh), lex, m4, and the gnu gcc cross-compiler built for mips.

	NOT SUPPORTED SYSTEM NOTES - FOR BRAVE PEOPLE
	=============================================
	For Mac OS X, environment variable YACC points to "bison -y",
	/usr//bin/gnumake must be installed, and "ln -s gnumake gmake".

  e) Sources provided (kernel, userland, cross-compiling, booting)?
        Everything.  Makefiles, README's, scripts to help, etc.  Building
	the cross-compiling tools are not recommended to be built, and we
	do NOT have the resources to support anyone doing this.

  f) README's?
        Yes, hopefully enough to get started changing things.
        There are RELEASE-NOTES, CHANGE, and README files at the top of
        each release CD. Each of the main components: uClinux, pmon, bbload,
        and open-tools have their own readme's. Also the uClinux/documentation
        directory contains additional useful files.

  g) How do I compile and link a simple hello.c program?
        The cross compiling tools are currently "integrated" with libraries
	and includes.  For hello.c the normal (not recommended way) of
		mips-gcc hello.c
	works and the a.out will work on the Brecis funlinux system.
	The recommended way is to do:
		mips-gcc -c hello.c
		mips-gcc -o hello hello.o
	You may get a smaller executable by stripping in a special way.
	(The relocation symbols must remain, so the default options for
	mips-strip will create an executable that will NOT work.)
		mips-strip -x --strip-unneeded -R .comment -R .pdr -R .note \
			-R .mdebug.abi32 hello
	There is supported a special case of gzip-ped executable that will
	make an even smaller image (for those wishing small flash sizes). 
	The gzipelf.sh script accepts a few of the "install" options and
	is located in the file uClinux/brecis/holes/gzipelf/gzipelf.sh.
	To use gzipelf.sh to create it do something like:
		uClinux/brecis/holes/gzipelf/gzipelf.sh hello hello.gzip
	It uses a small "c" program that creates aunique header for the file
	"ELF.mips32.gzip" (16 bytes, null included) followed by four bytes
	which is the size of the original (non-gzip-ped) executable. Then
	the gzip-ped (-9) image follows.  So, one might undo it via:
		dd if=hello.gzip bs=20 skip=1 of=hello.gz
		gunzip hello.gz

  h) Do I need to be root to compile, link, and install programs?
	For compiling, no.  For linking, no.  For installing, probably yes.
	Using the "compilescripts" directory, there are three ways to do this.
        1) become root, go to uClinux/brecis/compilescripts and type
           "make linuxall".
        2) Be a normal user, and whenever an operation is required to have
           root permissions, type in the password for root (su command).
        3) Set up the "/etc/sudoers" file, and edit uClinux/brecis/build.env
           so that something like the following exists for your user name:
              if ( $USER == sqa ) then
                 if ( $?SU == 0 ) then
                     setenv SU "eval sudo"
                 endif
              endif

           The /etc/sudoers file will look something like the following,
           with the username "sqa" changed to your name, and the path to
           uClinux/brecis/holes/gzipelf/gzipelf.sh is completely specified.

           column 1
           #------------------------------------------------------------------
           User_Alias     BUILDERS = sqa

           Cmnd_Alias     RUNTHIS = \
                   /bin/cp, \
                   /bin/mv, \
                   /bin/rm, \
                   /bin/rmdir, \
                   /bin/ln, \
                   /usr/bin/install, \
                   /home/sqa/uClinux/brecis/holes/gzipelf/gzipelf.sh, \
                   /usr/local/bin/gmake

           BUILDERS     ALL = NOPASSWD: RUNTHIS

  i) Known Issues?
        Are documented in the CHANGES file.

  j) How can I have my own /etc files in the romdisk?
        There are two ways.  a) create uClinux/romdisk/etc and add to that.
        b) environment variable TYPE_SYSTEM.  Additional directories that
        can be overridden in this manner are local, htdocs, and share.
        Please see the CHANGES file for release 1.1 Candiate 1 for environment
        TYPE_SYSTEM usage and setup.

  k) How do I have my own kernel configuration file?
        See above -- the TYPE_SYSTEM environment variable allows a special
        kernel configuration file, and userland programs and files.
        See the comments in uClinux/brecis/compilescripts/Makefile
        for the steps for adding a new kernel and userland configuration.

  l) How do I recompile the linux kernel and userland?
        cd uClinux/brecis/compilescripts ; make linuxall
        If you have your own kernel configuration file, see TYPE_SYSTEM
        environment variable usage in the CHANGES file for release 1.1.

  m) How easy is it to upgrade the kernel?
        The directory linux/mmnommu is a copy and changes added to
        linux/mm.  The directory linux/arch/mipsnommu is a copy with
        many changes for the brecis mips processor.  These two are the
        biggest hurdles.  Otherwise, a cvs diff -u from version 2.4.20
        to whatever version you desire, with a manual patch/check with
        very special attention to the mm and mips directory is what I
        would do.  Having done it three times, I would expect it to take
        about two weeks for me to do it again.  Without familiarity with
        these two directories, I would expect longer for someone else.
	See the CHANGES file for a list of files/directories changed from
	the kernel 2.4.20 on www.kernel.org.

  n) How easy is it to upgrade the C library?
        The MIPS system calls are the hardest part.  The crt0.o is special
        for this system.  Most other things are direct from uclibc.  Several
	routines were added.

  o) How do I do NFS?
  		See Below

  p) How do I do Kernel Loadable Modules?
        Please see the file uClinux/documentation/KernelModels

  q) What are the account and passwords?
        Please see the file uClinux/README.

  r) How can I use KGDB?
        Please see the file uClinux/README.

  s) How can I build the linux system from scratch?
        Please see the file uClinux/README.

  t) Is there any demonstration programs?
        Please see the file uClinux/README.

  u) How can I change the size of the RAMDISK (/var)?
  		See Below

  v) How do I change the timezone?
  		See Below

  w) How can a userland program read flash memory (or other kernel memory)?
        You cannot as released.  You might wish to set up a flash filesystem.
        To allow a user program access to devices uncached memory is probably
        not a good idea.  Yet, if you really wish to have a way to do it, you
        may change the file uClinux/linux/arch/mipsnommu/kernel/unaligned.c
        from looking like:
        #define IS_BRECIS_REG(a) (((a) >= BRECIS_REG_BASE) && \
                ((a) < (BRECIS_REG_BASE+BRECIS_REG_LEN)))
        to something like:
        #define IS_BRECIS_REG(a) ((((a) >= BRECIS_REG_BASE) && \
                 ((a) < (BRECIS_REG_BASE+BRECIS_REG_LEN))) || \
                (((a) >= 0xbfc70000) && ((a) < 0xC0470000)))
        or the specific ranges that you need.
        With the above change, you may run a program like this:
        #include <stdio.h>
        #include <stdio.h>
        #include <stdlib.h>
        int main()
        {
          int i;
          unsigned int *ptr;
          ptr = (unsigned int *)0xbfc70000;
          for (i = 0; i < 10; i++) {
            unsigned int value = *ptr;;
            char c0 = (value >> 8*3) & 0xff;
            char c1 = (value >> 8*2) & 0xff;
            char c2 = (value >> 8*1) & 0xff;
            char c3 = (value >> 8*0) & 0xff;
            printf("%c%c%c%c", c0, c1, c2, c3);
            ptr++;
          }
          exit(0);
        }

        If you wish to allow other than word aligned access, that is
        up to the reader to implement.  NOTE: an exception is taken
        for each address.  This is slow.

  x) How does one use brctl for bridging?
        Example output for brecis 5000 and two ethernets:
        # brctl addbr br0
        # brctl addif br0 eth0
        device eth0 entered promiscuous mode
        # brctl addif br0 eth1
        device eth1 entered promiscuous mode
        # ifconfig eth0 0.0.0.0
        # ifconfig eth1 0.0.0.0
        # ifconfig br0 192.168.1.5
        br0: port 2(eth1) entering listening state
        br0: port 1(eth0) entering listening state
        # br0: port 2(eth1) entering learning state
        br0: port 1(eth0) entering learning state
        br0: port 2(eth1) entering forwarding state
        br0: topology change detected, propagating
        br0: port 1(eth0) entering forwarding state
        br0: topology change detected, propagating

  y) Is SNMP available?
        net-snmp-5.0.1 is provided.  It runs with more than 4MB of ram.
        Create files /share/snmp/snmp.conf and /share/snmp/snmpd.conf.
        See additional documentation in uClinux/documentation/net-snmp.
        Documentation for package is in uClinux/uC-src/real/net-snmp-5.0.1.

  z) How can I separate the file system from the linux kernel?
        There are many ways to do this.  What I would do is the following:
        (Assuming flash chips are at: bfc70000, and be070000)
        1) In file uClinux/linux/arch/mipsnommu/ld.script.in, comment out --
        /*   . = ALIGN(32); */
        /*   .fs : */
        /*   { */
        /*    _romfs = ABSOLUTE (.); */
        /*    . = . + romfs_size; */
        /*   } */
        Add:
           _romfs = ABSOLUTE(0xbe070000;

        2) In file uClinux/linux/arch/mipsnommu/Makefile change:
        image.elf: romdisk linux
                ADDR=0x`$(CROSS_COMPILE)objdump -h linux | grep \.fs | awk ' { print $$4 } '` ; \
                $(CROSS_COMPILE)objcopy --add-section=.romfs=romdisk.img \
                  --adjust-section-vma=.romfs=$$ADDR --no-adjust-warnings \
                  --set-section-flags=.romfs=alloc,load,readonly,data  linux image.elf 2> /dev/null
        To look something like:
        image.elf: romdisk linux
        	ln -sf linux image.elf
        3) load via:
        	image.bin -> cs0 location.
        	romdisk.img -> be070000.
        Now, there is an advantage and disadvantage to this.
        Specifically, the file system exists in rom, and never in memory.
        Of course, memory access to flash is very slow.

        Another way to do it would be to put the _romfs into .bss loader
        section, and ". = . +romfs_size;". Then something needs to copy the
        flash into that memory location.  uClinux/arch/mipsnommu/kernel/head.S,
        in routine "NESTED(kernel_entry, 16, sp)", after the clearing of bss.
        (about 40 lines down, before the "jal init_arch".)

  aa) What kernel options work?
        The following kernel options do not work:
        CONFIG_NCP_FS, requires mmap structures -- 2003-02-10
        CONFIG_PACKET_MMAP, requires mmap structures -- 2003-02-10
        CONFIG_BLK_DEV_FD there is no floppy.

        CONFIG_DEVFS_FS, CONFIG_DEVFS_MOUNT, and CONFIG_DEVFS_DEBUG compile,
	but I do not have things setup to use it.

	CONFIG_BLK_DEV_INITRD compiles, but the initial setup is #ifdef-ed
	out in uClinux/linux/arch/mipsnommu/kernel/setup.c.

        See kernel configuration file "defconfig-brecis.big" for those that
        compile and a kernel is created that boots.  There is not enough
        resources to know if all options work

  ab) I get errors like " ... exceeds local_symtab_size" when loading modules?
        See the module documentation file documentation/KernelModules for
        more information on this

  ac) Where can I find information about the Security Engine API and some
	example code?
	See the files in the directory brecis/secutil/
		MSP_SEC_DEV_API_documentation.txt
		kerntest.c
		secutil.c
		seckerntest.c

	The security driver is in linux/drivers/brecis/brecis_sec.c

  ad) How do ethernet interfaces get configured?
	Ethernet MAC addresses are passed into the uClinux kernel
	from pmon or bbload as environment variables.  ethaddr0 is
	the environment variable for eth0, ethaddr1 is the environment
	varaible for eth1, ethaddr2 is the environment variable for eth2.
	If no ethernet MAC address is given for an ethernet interface,
	uClinux will not touch that ethernet interface.

	The IP address for an ethernet interface can be configured in
	a number of ways:
	1) from the command line that started the uClinux kernel 
		The pmon-script in documentation/pmon-script shows 
		how to set up the command line.
	2) from an ifconfig command placed in a uClinux kernel startup
	   file (such as /etc/rc)
	3) from DHCP using dhcpclient

  ae) How do I configure an ethernet interface for a switch or PHY?
    The pmon-script in documentation/pmon-script shows how to set up
    the interface for a switch or for a PHY

  af) How do I configure the speed and duplex of an ethernet interface?
    The pmon-script in documentation/pmon-script shows how to set up the
    speed and duplex of an ethernet interface

  ag) How do I do RIP or other routing protocols?
      defconfig-brecis.ripospfbgp has been created to configure the
      uClinux kernel for supporting routing protocols.
      RIP requires the uClinux kernel be built with CONFIG_IP_MULTICAST=y.
      To build this uClinux kernel, please go to the directory:
      uClinux/brecis/compilescripts
      and do "make ripospfbgp"

      The source code originated from www.zebra.org can be found in the
      uClinux/uC-src/real/zebra-* directory.
      The following modifications were made:
      1) the location for the config files (zebra.conf, ripd.conf, etc)
         has been changed to be the "/etc/" directory.
      2) The script for doing the ./configure can be found in the
         uClinux/uC-src/real/zebra-*/RUN directory.  This script
         contains many parameter modifications including having
         zebra obtain network information from the /proc file system.
      3) The help information from www.zebra.org can be found in the
         uClinux/uC-src/real/zebra-*/doc directory.
         Please go to this directory and type "info -f zebra"
      4) To start RIP, one needs to do the following commands:
         zebra -d
         ripd -d
         It is assumed one will put these commands in the /etc/rc
         file that is used under uClinux.
      5) Default zebra.conf and ripd.conf files can be found in the
         uClinux/romdisk/romdisk.tgz directory.  It is assumed one
         will customize these files.  It is recommended one change
         the "password zebra" to some less well-known string in both files.

         The ripd.conf configuration file was set up to do RIP 2 traffic
         on ethernet interface eth2, to redistribute all static and connected
         routes.

  ah) What help is there for debugging userland programs?
    1) "fprintf(stderr, ...); sleep(1);"
       The sleep allows the UART to empty it's buffers.
    2) strace command.  Of particular use is "strace -i cat /etc/rc".
       The first number is the "epc" register, which is where the system
       call will return to.  For unified system calls, this is almost
       always the same location.  The second number is the "ra"
       register (jal command sets this by default).
       Example: [01fa2b48, 01fa2b70] ioctl(0, 0x540d, {B57600 opost isig icanon echo ...}) = 0
       By this, one might be able to figure out where this is in the
       program by doing something like:
		mips-objdump -hpdlDrS ssh >> ssh.objdump
      Then looking at the objdump and finding the address of the system
      call.  Once you have the offset (0x01fa0000 in this case), you
      can find all the other program addresses by using this offset.
   3) For more help, you might look at file documentation/Porting-programs.

  ai) VLAN Support (802.11q)
        vlan support is available as an option.  Run make config in uC-src/
        and ensure that 'y' is given to the question for vlan.  802.11Q
        support must be enabled in the kernel.  Documentation for vlan
        configuration is found in uC-src/real/vlan  -- see the files
        vconfig.8 or vlan_manpage.txt.  The vlan configuration program
        vconfig is found in the /bin folder in uClinux.
  	
  aj) How do I add a package to UserLand?
      You will normally place the directory containing the new package
      in the uClinux/uC-src/real directory.

      Let us assume the package is in a directory "new", and is placed
      in the uClinux/uC-src/real directory.

      You will also edit uClinux/uC-src/real/Makefile.  The following
      is complicated so I must explain carefully.
      1) You have two choices for how the new package is made.
         One choice is where the new package contains a Makefile.
         The other choice is where one would normally run a Configure
         script in the new package directory which produces the Makefile
         after which the Makefile is used.
      2) You have a choice of having the new package unconditionally
         built -or- having the option to build the new package based
         on a variable you would set in the uClinux/uC-src/.config file.

      The above gives me a list of 4 ways a package may be made.
      1) package already has a Makefile, built unconditionally
         This is the easiest to set up.  One would add the following
         to uClinux/uC-src/real/Makefile:
         REALSUBDIRS += new

         Please be certain this line is added after the "REALSUBDIRS :=" line
         and before the "all: ${REALSUBDIRS} ${CONFIGDIRS}" line.

      2) package already has a Makefile, built conditionally
         Let us assume the new package should be built when the
         variable, CONFIG_REAL_NEW, is set.

         One would add the following to uClinux/uC-src/real/Makefile:
         REALSUBDIRS-$(CONFIG_REAL_NEW) += new

         Please be certain this line is added after the "REALSUBDIRS :=" line
         and before the "all: ${REALSUBDIRS} ${CONFIGDIRS}" line.

         One would also need to add a line similar to the following to
         uClinux/uC-src/config.in:
         bool 'Include new package' CONFIG_REAL_NEW

         One should also add help information to the file,
         uClinux/uC-src/Documentation/Configure.help
         The format of this file is described in the file,
         uClinux/linux/Documentation/Configure.help

         Finally, one will need to go to the uClinux/uC-src directory
         and do one of the following commands:
         make config -or- make oldconfig -or- make menuconfig -or- make xconfig
         at which time one will need to set "Y" if one wants the new package
         built.

      3) package needs to have a Configure script run, built unconditionally
         One would add the following to uClinux/uC-src/real/Makefile:
         CONFIGDIRS += new

         Please be certain this line is added after the "CONFIGDIRS :=" line
         and before the "all: ${REALSUBDIRS} ${CONFIGDIRS}" line.

         One will need to create scripts in the "new" directory.
         Please see another package which is added to the CONFIGDIRS
         or the CONFIGDIRS-$(CONFIG_REAL_xxx) variable where xxx represents
         part of the variable name for the other package.
         CONFIGDIRS-$(CONFIG_REAL_ZEBRA) is an example.

         The following are the three scripts one would need to create:
         a) RUN
            This script builds the Makefile by setting a bunch of
            variables for the configure script and then calling the
            configure script.

         b) RUN.CLEAN
            This script removes built objects, removes the Makefile,
            and removes other files to get the package directory back
            to an initial state.

         c) RUN.INSTALL
            This script does what is needed to have the binaries and
            other files the package placed in the correct directories
            so those files and binaries become part of the UserLand
            image.

      4) package needs to have a Configure script run, build conditionally
         Let us assume the new package should be built when the
         variable, CONFIG_REAL_NEW, is set.

         One would add the following to uClinux/uC-src/real/Makefile:
         CONFIGDIRS-$(CONFIG_REAL_NEW) += new

         Please be certain this line is added after the "CONFIGDIRS :=" line
         and before the "all: ${REALSUBDIRS} ${CONFIGDIRS}" line.

         One will need to create scripts in the "new" directory.
         Please see another package which is added to the CONFIGDIRS
         or the CONFIGDIRS-$(CONFIG_REAL_xxx) variable where xxx represents
         part of the variable name for the other package.
         CONFIGDIRS-$(CONFIG_REAL_ZEBRA) is an example.

         The following are the three scripts one would need to create:
         a) RUN
            This script builds the Makefile by setting a bunch of
            variables for the configure script and then calling the
            configure script.

         b) RUN.CLEAN
            This script removes built objects, removes the Makefile,
            and removes other files to get the package directory back
            to an initial state.

         c) RUN.INSTALL
            This script does what is needed to have the binaries and
            other files the package placed in the correct directories
            so those files and binaries become part of the UserLand
            image.

         One would also need to add a line similar to the following to
         uClinux/uC-src/config.in:
         bool 'Include new package' CONFIG_REAL_NEW

         One should also add help information to the file,
         uClinux/uC-src/Documentation/Configure.help
         The format of this file is described in the file,
         uClinux/linux/Documentation/Configure.help

         Finally, one will need to go to the uClinux/uC-src directory
         and do one of the following commands:
         make config -or- make oldconfig -or- make menuconfig -or- make xconfig
         at which time will will need to set "Y" if one wants the new package
         built.

  ak) How do I configure which UserLand packages get built?
      If the UserLand package was added in such a way
      to allow the package to be selected for building using
      the uClinux/uC-src/.config file,
      one will need to go to the uClinux/uC-src directory
      and do one of the following commands:
      make config -or- make menuconfig -or- make xconfig
      to select the package.

      If the UserLand package was not added in such a way
      to allow the package to be selected for building using
      the uClinux/uC-src/.config file,
      one will need to edit uClinux/uC-src/real/Makefile
      adding either the line,
      REALSUBDIRS += <package-directory>
      -or-
      CONFIGDIRS += <package-directory>
      as appropriate.  Please see the explanation for adding a new
      package above.

  al) How do I tell if I have pre-alpha voice support and how do I
      use it?

      If pre-alpha voice support is included, the directories
      ${TOPDIR}/linux/drivers/brecis/vpm and ${TOPDIR}/brecis/zsp-ldr
      will be present (and populated).  ${TOPDIR}/linux/drivers/brecis/vpm
      contains the MSP 4000/5000 Voice Engine device driver, and will
      be built (as a module) as part of the uClinux image build,
      assuming CONFIG_BRECIS=y is in ${TOPDIR}/linux/.config.
      CONFIG_BRECIS=y is by default in all BRECIS-supplied
      defconfig-brecis* files (in ${TOPDIR}/linux/arch/mipsnommu).  See
      (k) and (l) for tips on managing kernel configurations.

      ${TOPDIR}/brecis/zsp-ldr contains the ZSP binary code and the source
      for a user program to initialize and load the Voice Engine ZSP.  The
      user program is referred to as the "loader".  There are different
      binary codes for the MSP 4000 and MSP 5000, and the correct one must
      be used for the target hardware.  To build both loaders,
      in ${TOPDIR}/brecis/zsp-ldr do "make clean;make".  This will make
      ldvpm and ldvpm4K, for the MSP 5000 and MSP 4000 respectively.
      This will *not* install any loader in the uClinux image.

      The correct loader executable program, either ldvpm or ldvpm4K,
      must be available at run time, either via a mounted NFS file
      system or by being built into the uClinux image ROM disk.  To
      accomplish this, either ldvpm or ldvpm4K from
      ${TOPDIR}/brecis/zsp-ldr must be copied to somewhere in the
      ROM disk.  Only one of ldvpm or ldvpm4K is needed, depending on
      the target hardware.  See elsewhere in this document for ways
      to add files to the ROM disk.

      The (correct) loader must be run before attempting to use the
      Voice Engine ZSP.  See ${TOPDIR}/brecis/ve-api/demo.c for an
      example of initializing and using the Voice Engine ZSP.

  am) What help is there for debugging the kernel?
      We use printk for most things.  There is a hardware jtag debugger
      available from EPI called MAJIC that works.  See the directory
      uClinux/brecis/majic for a README and some scripts.

  an) How can I create a flash image that has both pmon and funlinux
      combined together, for mass production?

      Here is an example that shows one possible way to do it.
      Note: I happen to like csh... 
      
      #!/bin/csh -x
      @ pmon_script = 458752          # 0x70000
      @ image_bin = 459776            # 0x70400
      @ p_seek_size = ${pmon_script} / 512
      @ i_seek_size = ${image_bin} / 512
      # 16mb flash
      dd if=/dev/zero of=flash bs=1m count=16
      dd if=pmon.bin of=flash conv=notrunc
      dd if=pmon.script of=flash conv=notrunc obs=512 seek=${p_seek_size}
      dd if=image.bin.default of=flash conv=notrunc obs=512 seek=${i_seek_size}

  ao) How can I update the cross-compiling tools?

      If you receive updated tools and wish to use them, place the tarball
      containing the tools into uClinux/brecis/tools and remove the previous
      tarball. In addition, do an "rm -rf mipsisa32-brecis-uclinux" in that
      directory to remove the previous tools. After doing this, performing a
      make linuxall in uClinux/brecis/compilescripts will install the new
      tools and do a full build of the system. It is a good idea to rebuild
      everything after doing something like upgrading cross tools.

  ap) How can I change the system wide PATH definition?

      There are a number of places that the path is set, and it depends on
      which set of tools you are using for your configuration.
      ------------------------------------------------------------------------
      Kernel file for /sbin/modprob linux/kernel/kmod.c:
	static char * envp[] = { "HOME=/", "TERM=linux", "PATH=/sbin:/usr/sbin:/bin:/usr/bin", NULL };
      ------------------------------------------------------------------------
      Files referencing _PATH_DEFPATH are:
	uclibc/include/paths.h:#define       _PATH_DEFPATH   "/usr/bin:/bin"
	uC-src/real/sh-utils-2.0/src/su.c
	uC-src/real/shutils/src/su.c

      "standard linux utilities" util-linux-2.11z does a #undef of it, then:
	uC-src/real/util-linux-2.11z/lib/pathnames.h:
	  #define _PATH_DEFPATH "/usr/local/bin:/bin:/usr/bin"
	uC-src/real/util-linux-2.11z/lib/pathnames.h:
	  #define _PATH_DEFPATH_ROOT "/usr/local/sbin:/usr/local/bin:" SBINDIR ":/bin:" USRSBINDIR ":/usr/bin"
	uC-src/real/util-linux-2.11z/login-utils/login.c:
	  setenv("PATH", _PATH_DEFPATH, 1);
	uC-src/real/util-linux-2.11z/login-utils/login.c:
	  setenv("PATH", _PATH_DEFPATH_ROOT, 1);
      ------------------------------------------------------------------------
      Files referencing _PATH_STDPATH are:
	uclibc/include/paths.h:
	  #define       _PATH_STDPATH   "/usr/bin:/bin"
	./busybox/init.c:
	  #define _PATH_STDPATH   "PATH=/bin:/usr/bin" /* Default path */
	./real/busybox/init.c:
	  #ifndef _PATH_STDPATH
	  #define _PATH_STDPATH     "/usr/bin:/bin:/usr/sbin:/sbin"
	./real/openssh-3.5p1/configure:
	  #ifndef _PATH_STDPATH
	  # define _PATH_STDPATH "/usr/bin:/bin:/usr/sbin:/sbin"
      ------------------------------------------------------------------------
      bash uses this library routine (which might actually be "wrong"):
	uclibc/libc/unistd/confstr.c:#define CS_PATH "/bin:/usr/bin"
      ------------------------------------------------------------------------
      Mount command (uC-src/newmount) has it's own path.
      ------------------------------------------------------------------------
      If login script, uC-src/sh/sh1.c reads file .profile, then /etc/profile.
      (Note: /etc/rc is not a login script.  See below for "init".
      ------------------------------------------------------------------------
      One last place: linux/init/main.c:
	It parses options sent to the kernel when booting and anything with
	an equal (=) sign gets passed to "init" as an environment variable.
	One can add a "PATH=/myplace:/bin" when starting from pmon/bbload.
      ------------------------------------------------------------------------

  ap) CONFIG_IP_PNP must be defined in the current
      uClinux/linux/.config files which are built from
      uClinux/linux/arch/mipsnommu/defconfig-brecis*
      for ethernet.
      



RAMDISK MODIFICATIONS AND BUILD INSTRUCTIONS:
The script uClinux/brecis/holes/CREATE can used to re-size the ramdisk for
volatile directories and files. Note that before this script can
be successfully used, the filesystem should have been previously
built.

0)	If not previously executed, "make LINUXALL" to set up the initial
	images:
		cd uClinux/brecis/compilescripts
		make LINUXALL

1)	Go to the uClinux/brecis/holes directory and edit the CREATE
	script with the new ram disk size in the count parameter of the dd
	command. The count parameter holds the number of 1K Byte blocks
	available to the ramdisk image.
		cd uClinux/brecis/holes
		vi CREATE
	Also change the kernel configuration variable CONFIG_BLK_DEV_RAM_SIZE
	to the number of 1024-byte blocks that are to be available to the
	ramdisk.

2)	Execute the CREATE script to create a temporary ramdisk
	image. This will be used by builds using the "make LINUX" build
	method. If "make LINUXALL" or "make ROMDISK" are run at this point,
	the ramdisk will be returned to its previous size.
		./CREATE

	NOTE: This script will call for the root password a
		number of times.

3)	To make the change permanent, follow the steps in the comment at
	the bottom of the CREATE script.




ROMDISK MODIFICATIONS AND BUILD INSTRUCTIONS:
To change any file or directory in the rom file system, except the
/bin and /sbin directories:

	1) Go the the uClinux/romdisk directory and extract the minimal
	root (/) directory for the file system (this will not contain the
	/bin or /sbin executables):
		 cd uClinux/romdisk
		 su -m root -c "make root"

	NOTE: This command will call for the root password

	2) Change the uClinux/romdisk/root directory as needed.

	3) Create the new romdisk image with the commands:
		cd uClinux/romdisk
		su -m root -c "make new"

	NOTE: This command will call for the root password

	   "make LINUXALL" uses the resulting romdisk.tgz file to create a
	   clean root directory (/) layout.

	4) if you wish to add a WRITEABLE directory then this directory must
	   be placed under /var (by default).  For example to create a
	   sub-directory /var/tmp, you will need to modify the rc files in the
	   linux directory romdisk/etc.*/rc and add the following
	
	    echo "Create /var/tmp"
		/bin/mkdir /var/tmp
		/bin/chmod 777 /var/tmp
		
	   if you need to add a link to say /var/tmp then follow 1) above
	   and in the directory uClinux/romdisk/root enter the command
	   ln -s /var/tmp mylink.  Now follow 3) to get the change put
	   into the build.




NFS MOUNT INSTRUCTIONS:
The uClinux kernel may mount a remote NFS file system.

1)	On the computer exporting the NFS file system, export
	the directory used for building the uClinux kernel.

		As an example, on Linux, do the following commands as root:
		a) start nfs if necessary,
			/etc/rc.d/init.d/nfs start

		b) Edit the /etc/exports file as necessary.
			The following is an example of what /etc/exports might
			contain:
	/home/sqa/uClinux 192.168.1.88(rw,all_squash,anonuid=500,anongid=100)

		The above exports a directory, uClinux, to the BRECIS MSP EVM
		with IP address 192.168.1.88, granting read/write permission,
		making all accesses come from an account whose uid is 500 and
		gid is 100.  The uClinux directory is the directory where
		uClinux was built.

		c) Type the following command to re-export the NFS file
		systems:
			exportfs -r	

2)	Load the uClinux kernel to the BRECIS MSP EVM board following the
	uClinux LOAD INSTRUCTIONS.  Boot the uClinux kernel to the login
	prompt.

3)	Login using the root account on the uClinux BRECIS MSP EVM board
	and do the following commands:

	a)	Insure the BRECIS MSP EVM board and the host computer can ping
		each other to verify network connectivity.

	b)	Start the portmap program.
		/sbin/portmap &

	c)	Use the command "mount" to mount the NFS file system on
		the /mnt mount point.  In this example, the host computer
		IP address is assumed to be 192.168.1.100.
			mount -n -t nfs 192.168.1.100:/home/sqa/uClinux /mnt

4)	Go to the /mnt directory and create a file and verify the file is
	created.

	cd /mnt
	echo "This is a test" > xxx
	more xxx

	One can also, from the host computer, verify the file was created.

6)	Build the demo application program following the steps under
	DEMO APPLICATION BUILD AND LOAD INSTRUCTIONS.  Instead of
	using ftp to ftp the demo program from the host computer to
	the BRECIS MSP EVM board, go to the directory where the demo
	program was built and execute the demo program.
	cd /mnt/brecis/demo
	./demo




SETTING TIME ZONE:
You must have moved the sources to local disk, as per above.  You should
understand about the different "example" kernel/image layouts that we have.

Two ways to achieve this:
1) Set environment variable TZ for programs. (e.g. setenv TZ CST6CDT)
   a) /etc/rc before any programs in there use it.
   b) /etc/profile when people login.
   This is how the library uclibc routines do it.  Or, you might wish to ...
2) Set file /etc/localtime.  Supposedly this may just be copied from a
   running linux system.  If you wish to use "zic" to create the time zone
   files, please see the kernel "big".  This may be compiled by going to
   directory uClinux/brecis/compilescripts and typing "make big".  You may
   wish to change the file etc.big/rc in directory uClinux/brecis/romdisk.
   The symbolic link etc.big/localtime is created in uClinux/romdisk/Makefile.
   This should point to the new time zone file location.  (for example,
   "ln -sf localtime GMT", if the file GMT happens to be in the etc.big
   directory.)  Or, just make localtime contain the information.

   Programs must be linked with the object modules in uC-src/real/date:
	asctime.o localtime.o strftime.o
   before the "c" library is linked -- as uclibc does not support this.  It
   was determined by the maintainers of uclibc that this is unnecessary bloat.



GETTING CGI TO WORK WITH thttpd:
The "setenv TYPE_SYSTEM .big" kernel has an example of CGI with thttpd.

To run thttpd and verify that a CGI script is running:
a) /etc/inetd.conf must not have httpd in it.  (comment out or delete)
   (You can just kill off inetd if it is running.)
b) You need a place for the documents and CGI's and executables for CGI.
   /htdocs is where our example is located.
c) Example layout of /htdocs (see directory uClinux/romdisk/htdocs.big):
   drwxr-xr-x  3 m4  m4   512 Jul 13 21:00 bin/
   drwxr-xr-x  3 m4  m4   512 Jul 13 21:00 cgi-bin/
   -rw-r--r--  1 m4  m4  3020 May 26 18:43 form.html
   -rw-r--r--  1 m4  m4    19 May 26 18:43 index.html

   ./bin:
   -rwxr-xr-x  1 m4  m4  19197 May 26 18:43 date*
   -rwxr-xr-x  1 m4  m4  17705 May 26 18:43 dd*
   -rwxr-xr-x  1 m4  m4   1440 May 26 18:43 echo*
   -rwxr-xr-x  1 m4  m4   1595 May 26 18:43 printenv*
   -rwxr-xr-x  1 m4  m4  33907 May 26 18:43 sh*

   ./cgi-bin:
   -rw-r--r--  1 m4  m4    27 May 26 18:43 index.html
   -rw-r--r--  1 m4  m4   443 May 26 18:43 printenv.old
   -rwxr-xr-x  1 m4  m4  3550 May 26 18:43 system*
   -rwxr-xr-x  1 m4  m4  8446 May 26 18:43 test-post*
d) create romdisk.img and image.bin and download.
e) Start thttpd like:
   /bin/thttpd -r -D -d /htdocs -c '*' -l /var/thttpd.log &
f) netscape http://192.168.1.2/index.html               - only 1 line.
   netscape http://192.168.1.2/cgi-bin/index.html       - only 1 line.
   netscape http://192.168.1.2/form.html                - sample form.

Correct IP addresses, etc., as needed.



ROM FILE SYSTEM:
romdisk.img is the romfs.  /var is a "ramdisk" and created by taking
an ext2fs and using a program called "holes" to compress it down to
3340 bytes, and upon startup /etc/rc executes /sbin/expand to undo it.
The size of the "ram" used for /var can be changed, df shows it to be
"Total bytes: 240640".  /proc works fine.  As does nfs mounting, if
the CONFIGuration options are enabled.




USERLAND INFORMATION:
Userland consists of libc.a and programs.  uclibc is from www.uclibc.org,
and is version 0.9.16 (with patches for our system).  This libc.a
contains the math library internally.  uC-src comes from uClinux, and
has fixes to work with linux 2.4.20 and uclibc.  "flat" binary format
is no longer supported, and neither is PIC.  "elfq" has been chosen
as the Brecis default loading format (add "-q" option to "ld").

We assume that typical libc.a routines are present.  Some commands
like "ls" are stripped of many functions.  There are no man pages for
the "running" commands.  You may be better off taking RedHat's sources,
fixing them and using them.  Note: that these executables will be much
larger than those provided, but will provide the functionality that a
linux "user" might expect.  www.uclibc.org has pointers to programs
designed for embedded systems, that work with the c library.

We are working on optionally providing full GNU commands.  See the
directory uClinux/uC-src/real for some examples.  Fileutils-4.1 has
a file RUN that shows what is necessary for "./configure" to work.
The Makefile in uClinux/uC-src/real can be changed to add/delete
directories.  This may not be for the faint of heart.



USING PCI/mini-PCI:
Some new BRECIS MSP parts have support for a PCI bus. A default kernel
configuration is provided (TYPE_SYSTEM=.pci) that turns on PCI support
and builds a few PCI drivers, including a driver for the Intel PRO/100.
That driver supports both the PCI and mini-PCI variants of the card. In
most cases, you should start with the .pci configuration and change it
according to your needs. Turning off drivers that you do not need will
reduce the kernel size.

Note that not all Linux PCI drivers will work without changes. Because the
x86 architecture is cache-coherent, some drivers may not include the calls
necessary to work in non-coherent environments because they simply haven't
been used in such environments. Try any driver you might want to use, but
don't be too surprised if it doesn't work. Often, just a change to not
complain about using irq 0 is all that is needed.

To change PCI slot irq assignment, look at the function pcibios_fixup_irqs
in the file uClinux/linux/arch/mipsnommu/brecis/generic/pci_fixup.c. If your
hardware uses different irqs, this is where to adjust for that.

To enable debug messages (during PCI development) change
#define DEBUG 0
to 
#define DEBUG 1
in the file uClinux/linux/arch/mipsnommu/kernel/pci_auto.c


USING Intersil 38xx wireless boards:
To begin to use wireless networking, it is necessary to configure a kernel
with the appropriate driver. Up to this point, only the Intersil 38xx
driver has been used. When configuring that driver, be sure to also include
the firmware for the card you are using. There are separate configuration
options for 3877 firmware and 3890 firmware. This driver can function without
being a module. When built in that way, the firmware can be in the driver,
and yet the memory it occupies can be reclaimed after initialization. If built
as a module, the space occupied by the firmware cannot be reclaimed.

Configuring the kernel is only part of the job, however. It is also necessary
to configure userland to include the wireless utilities. These are listed
along with all of the other userland items and included in the same manner
as other things described above. These utilities including the important
iwconfig utility which can assign essid's and such.

The current driver is built with WIRELESS_EVENTS, WIRELESS_IOCTLS and WDS_LINKS
turned on. You can change the driver options via the kernel configuration
process, either make config, make menuconfig or make xconfig. More wireless
capability will be added in a future release.

A kernel and userland will be built for testing the Intersil driver
by doing make wireless -or- make wireless.nat


KERNEL STACK overflows: 

Detecting a kernel stack overflow is not easy.  Currently, the kernel
stack must be in the same piece of memory (same allocation) as the
task structure.  Because of this, a kernel stack overflow will likely
cause overwriting of variables in the task structure, resulting in a
hang or system crash.

Changing the kernel stack size is not to be taken lightly.  The memory
block must be a power of two in length.  If it's currently 8K, and you
want to make it bigger, the next available option is 16K.  That's 8k
more, and one kernel stack gets allocated per process, so that's
increasing your RAM footprint by 8k * the number of processes in your
system.  

You should therefore first try to find out what's taking the space on
the stack, and consider either moving it to static storeage, or using
kmalloc/kfree for the large pieces.  Only after finding that these
options are unacceptable should you consider making the kernel stack
larger.

If you do decide to change the stack size, read the comment near the
define for KERNEL_STACK_SIZE in linux/include/asm-mipsnommu/processor.h
for information on how to proceed.


HOW DO I MAKE A CLEAN BUILD:

The command "make clean" removes the files associated with a defined
configuration as set up by the .config files in uClinux/Linux and
uClinux/uC-src.  The .config files are created from the defconfig files
used to build the kernel and libraries.  When a configuration is changed
the associated uC-src/.config information needs to be removed and this file
must be removed.  In brecis/compilescripts use the command "make distclean"
rather than "make clean".  Then set the appropriate TYPE_SYSTEM, then do
the appropriate make (eg "make linuxall") to build the system.
