1
0
Files
irix-657m-src/stand/x86/ffsc/html/building.html
2022-09-29 17:59:04 +03:00

792 lines
20 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<title>Notes on Building FFSC Software</title>
</head>
<body
alink="#cc3232"
vlink="#93db70"
link="#ffff00"
bgcolor="#42426f"
text="#ffffff">
<h1 align="center">Notes on Building FFSC Software</h1>
<p>
The software for the Lego/SN0/Origin2000 Full-Featured System
Controller runs under the VxWorks real-time operating system on
a x86-based single board computer built by Computer Dynamics
Inc. (CDI).
Currently, there is no way to cross-compile VxWorks or its
applications under IRIX, so actually building FFSC software
images must be done on a PC using the tools provided by Wind
River (the makers of VxWorks) and optionally their development
environment, Tornado.
Unfortunately, this doesn't mesh well with the standard SGI
build environment and source control tools.
This document describes what I have done to get Tornado and IRIX
to coexist fairly peacefully and how to build FFSC images in
this environment.
</p>
<p>
Rob Bradshaw<br>
rdb@engr<br>
September 1996<br>
</p>
<hr>
<h3>The Tornado Environment</h3>
<p>
The initial batch of FFSC software has been built using the Wind
River Tornado 1.0 product, which incorporates VxWorks 5.3.
Tornado runs on a standard PC running Windows 95.
</p>
<p>
The PC's that we have been using have 133MHz Pentium CPUs, 32MB
of memory, 1-2GB of disk, an ethernet interface and one serial
port.
TCP/IP should be installed on Windows and the PC should be
attached to the corporate network.
For working with multiple FFSC's, I have found it necessary to
add a second ethernet interface (to sit on a private network
with the FFSC's) and at least two additional serial ports (one
for each FFSC plus a "spare").
</p>
<p>
The Tornado software should be installed according to the usual
directions, though some directories can be removed later on,
since they are not needed for our purposes.
After installation, you should have a directory tree that
includes the following:
</p>
<table>
<tr>
<td valign="top"><tt>C:\TORNADO\HOST\X86-WIN32\BIN<tt></td>
<td>Build tools</td>
</tr>
<tr>
<td valign="top"><tt>C:\TORNADO\SHARE\SRC</tt></td>
<td>Certain source files needed for debugger support</td>
</tr>
<tr>
<td valign="top"><tt>C:\TORNADO\TARGET\CONFIG\PC486</tt></td>
<td>Source files for configuring VxWorks on x86 platforms</td>
</tr>
<tr>
<td valign="top"><tt>C:\TORNADO\TARGET\CONFIG\ALL</tt></td>
<td>Platform-independent source files for configuring VxWorks</td>
</tr>
<tr>
<td valign="top"><tt>C:\TORNADO\TARGET\H</tt></td>
<td>Header files for VxWorks</td>
</tr>
<tr>
<td valign="top"><tt>C:\TORNADO\TARGET\H\MAKE</tt></td>
<td>Makefiles for VxWorks</td>
</tr>
<tr>
<td valign="top"><tt>C:\TORNADO\TARGET\LIB\OBJI80486GNUVX</tt></td>
<td>VxWorks libraries for x86</td>
</tr>
<tr>
<td valign="top"><tt>C:\TORNADO\TARGET\SRC\CONFIG</tt></td>
<td>Modifiable source code for configuring VxWorks</td>
</tr>
<tr>
<td valign="top"><tt>C:\TORNADO\TARGET\SRC\DRV</tt></td>
<td>User-modifiable source code for VxWorks device drivers</td>
</tr>
</table>
<p>
The portions of the <tt>SHARE\SRC</tt>,
<tt>TARGET\CONFIG</tt>, <tt>TARGET\H</tt> and
<tt>TARGET\SRC</tt> directories that are relevant to the FFSC
are maintained in an <em>IRIX</em> source tree and can be
deleted or renamed on the PC if desired.
The <tt>HOST</tt> and <tt>TARGET\LIB</tt> directories are
<em>not</em> maintained under IRIX and should be retained on
the PC.
I suspect that the remaining directories could be removed as
well, but I haven't tried that yet.
</p>
<h3>The IRIX Environment</h3>
<p>
As alluded to above, all modifiable source code, including
source code provided by Wind River (VxWorks) and CDI, are
maintained in a standard ptools workarea under IRIX.
The source tree lives in the "x86/ffsc" subdirectory of the
"stand" ism of the current OS release:
</p>
<listing>
/proj/ficus/isms/stand/x86/ffsc
</listing>
<p>
and consists of these main subtrees:
</p>
<table align="center">
<tr>
<td valign="top"><tt>wind</tt></td>
<td>
Wind River source code for VxWorks.
This consists mainly of clones of the relevant portions of
the <tt>C:\TORNADO\TARGET</tt> and
<tt>C:\TORNADO\SHARE</tt> directory trees from the Tornado
distribution.
</td>
</tr>
<tr>
<td valign="top"><tt>cdi</tt></td>
<td>
Source code and other files provided by CDI for the
FFSC hardware itself.
</td>
</tr>
<tr>
<td valign="top"><tt>sgi</tt></td>
<td>
SGI-generated source code for the FFSC.
</td>
</tr>
</table>
<p>
Most of the files in these directories are in Unix, as opposed
to DOS, format which implies that CR-LF pairs have been
converted to single LF's and trailing EOF characters (if
present) have been removed.
The Tornado tools are capable of dealing with Unix format
files, though ordinary Windows tools (e.g. notepad, edit) are
not.
IRIX has two tools, <tt>to_unix</tt> and <tt>to_dos</tt>, for
converting between the two formats if necessary.
Files that are checked into the source tree should generally
be in unix format.
Note that while the Tornado editor can read unix format files,
it always writes DOS format files, so if you edit source files
under Tornado, it will be necessary to run <tt>to_unix</tt>
against those files before checking your changes into the
source tree.
</p>
<h3>Sharing Files Between Windows and IRIX</h3>
<p>
If the source code lives on an IRIX system and the build tools
are hosted under Windows/DOS, then the immediate question is
how to get files from one platform to the other.
There are NFS packages available for Windows 95, though
generally for a fee.
A cheaper solution is Samba, a freeware implementation of the
Windows SMB protocol that allows IRIX to import and export
Windows "shares" (i.e. directories and other resources, such
as printers).
For IRIX 6.2, a working implementation of Samba can be
installed from:
<listing>
/hosts/dist/released/6.2/products/freeware-2.0/fw_samba
</listing>
</p>
<h4>Setting up Samba</h4>
<p>
To make an IRIX directory available to Windows, add a section
like this to the <tt>smb.conf</tt> file (in
<tt>/usr/freeware/lib/samba</tt> with the above distribution):
<listing>
[ffsc]
comment = FFSC workarea
path = /d/backup/workareas/ficus/stand/x86/ffsc
read only = no
create mode = 0644
writeable = yes
browseable = yes
user = rdbpw
</listing>
</p>
<p>
The path should (obviously) be changed to correspond to your
own FFSC workarea directory.
The user should be a user in your <tt>/etc/passwd</tt> file
<i>that has a password</i> Windows actually matches a user
based on their password, not their user name, so it cannot
handle a password-less user.
If you don't normally maintain a password on your IRIX system,
then add a second entry to <tt>/etc/passwd</tt> with your UID
and GID, but then set a password for it.
</p>
<h4>Accessing Files With Samba</h4>
<p>
Once you have added an appropriate section to
<tt>smb.conf</tt> and (re)started samba on your system, you
should be able to access the directory specified by
<tt>path</tt> and any subdirectories as:
<listing>
\\<i>hostname</i>\ffsc\<i>subdir</i>\<i>subdir</i>...
</listing>
from your PC.
For example, in the above configuration the IRIX file
<tt>/d/backup/workareas/ficus/stand/x86/ffsc/sgi/makefile</tt>
on host <tt>uniscan</tt> can be accessed from Windows as
<tt>\\uniscan\ffsc\sgi\makefile</tt>.
</p>
<p>
One major problem with Samba (at this time, anyway) is that it
cannot handle mixed-case filenames: all filenames are
converted to lower case.
This is not normally a problem with Windows/DOS, since
filenames are not case sensitive.
However, this can cause trouble with makefile dependencies
(which are case sensitive), so all #include's in source files
should use lower-case filenames.
The files in the <tt>.../wind</tt> and <tt>.../cdi</tt>
directories of the source tree have already been converted
accordingly.
</p>
<h4>Caching Files on the PC</h4>
<p>
Another problem with Samba is that it is not terribly fast, so
compile times will tend to suffer if the source code lives
entirely under IRIX.
To speed things up somewhat, you may want to cache local
copies of the <tt>.../wind</tt> and <tt>.../cdi</tt> subtrees
on the PC, since the contents of these directories probably
won't change very often.
The makefiles for the FFSC software obtain the locations of
the top-level subtrees (wind, sgi, cdi) from environment
variables (see below) so it is possible to do this without
having to modify any makefiles.
</p>
<p>
In addition, Windows 95 provides a "briefcase" tool that can
make it fairly easy to update these directories on the rare
occasions that changes do occur.
Rather than creating a directory on the PC to hold a
cached subtree, create a new briefcase instead, then use
Explorer to drag the contents of the IRIX directory to the
briefcase.
Later on, if a change is made in either directory,
select the briefcase in Explorer and do an "Update All".
Windows will detect what files have changed and offer to copy
the newer file onto the older one.
</p>
<h3>Making FFSC Software Images</h3>
<p>
The VxWorks makefiles have been rewritten to cope with
multiple source directories and to allow building different
targets without having to clobber an older target first.
In addition, limited-functionality IRIX makefiles are also
provided, mainly for the sake of cleanup operations such as
"clean" and "clobber".
The IRIX makefiles (typically named "Makefile.sgi") are
automatically invoked by the VxWorks makefiles when you run
"make" under IRIX.
</p>
<h4>Setting MS-DOS Environment Variables</h4>
<p>
Both the Tornado tools and the various makefiles depend on a
number of environment variables being set to function
properly.
These include:
</p>
<table>
<tr>
<td valign="top"><tt>WIND_BASE</tt></td>
<td>
The top-level Tornado directory, typically
<tt>C:\TORNADO</tt>
</td>
</tr>
<tr>
<td valign="top"><tt>WIND_UNC</tt></td>
<td>
The top-level Tornado directory in &quot;UNC&quot; format,
i.e. <tt>\\<i>host</i>\<i>share</i>\<i>dir</i>...</tt>.
For a PC named <tt>USPC</tt>, with its <tt>C:</tt> drive
shared with the name <tt>CDRV</tt>, this would be
<tt>\\USPC\CDRV\TORNADO</tt>
</td>
</tr>
<tr>
<td valign="top"><tt>UNIX_UNC</tt></td>
<td>
The UNC path of the FFSC workarea on an IRIX workstation.
In the Samba configuration from above, this would be
<tt>\\UNISCAN\FFSC</tt>.
</td>
</tr>
<tr>
<td valign="top"><tt>VX_SRC</tt></td>
<td>
The UNC path of the <tt>wind</tt> subtree in the FFSC
workarea.
In the above example, this would be
<tt>\\UNISCAN\FFSC\WIND</tt>, or from a BAT file,
<tt>%UNIX_UNC%\WIND</tt>.
</td>
</tr>
<tr>
<td valign="top"><tt>VX_LIB</tt></td>
<td>
The UNC path of the VxWorks libraries.
These are usually in <tt>C:\TORNADO\TARGET\LIB</tt>, so in
UNC format <TT>\\USPC\CDRV\TORNADO\TARGET\LIB</TT> or simply
<TT>%WIND_UNC%\TARGET\LIB</TT>.
</td>
</tr>
<tr>
<td valign="top"><tt>CDI_SRC</tt></td>
<td>
The UNC path of the CDI source subtree.
<TT>\\UNISCAN\FFSC\CDI</TT> in this example.
</td>
</tr>
<tr>
<td valign="top"><tt>SGI_SRC</tt></td>
<td>
The UNC path of the SGI source subtree.
<TT>\\UNISCAN\FFSC\SGI</TT> in this example.
</td>
</tr>
<tr>
<td valign="top"><tt>BUILD_DIR</tt></td>
<td>
The UNC path of a directory in which object directories
and final images should be stored.
This would typically be the <tt>$WORKAREA</tt> directory
under IRIX though for performance purposes you may want to
cache this on the PC and copy over the top-level makefile
from IRIX.
</td>
</tr>
<tr>
<td valign="top"><tt>WIND_REGISTRY</tt></td>
<td>
The TCP/IP hostname of a PC running the Wind River
registry server.
Normally, this would be your PC.
</td>
</tr>
<tr>
<td valign="top"><tt>GCC_EXEC_PREFIX</tt></td>
<td>
Required by the Tornado build tools.
This should always be
<tt>C:\TORNADO\HOST\X86-WIN32\LIB\GCC-LIB</tt>
</td>
</tr>
<tr>
<td valign="top"><tt>WIND_HOST_TYPE</tt></td>
<td>
Also used by the Tornado build tools.
This should always be <tt>x86-win32</tt>.
</td>
</tr>
</table>
<p>
A batch file that sets all of these variables can be found in
the IRIX source tree in <tt>protoffscvars.bat</tt>.
Copy this file to a convenient location on your PC (perhaps
renaming it to <tt>ffscvars.bat</tt>) and edit it to match
your configuration.
You may want to CALL it from your AUTOEXEC.BAT file; if not,
you will need to run it before invoking Tornado.
</p>
<p>
Unfortunately, this many environment variables may cause
Windows to generate "Out of Environment Space" errors.
If that happens, it will be necessary to increase the size of
your environment space by adding the option <tt>/E:1024</tt>
to the <tt>COMMAND.COM</tt> command line.
(&quot;Consult your owner's manual for details.&quot;)
</p>
<h4>Make Targets</h4>
<p>
From the top-level FFSC directory, the default make target is
to build an FFSC software image of some kind.
The exact kind of image that is built depends on the settings
of several MAKE variables, which would typically be set on the
command line that invokes make:
</p>
<table>
<tr>
<td valign="top"><i>no variables set</i></td>
<td>
Build a normal network-bootable VxWorks image and separate
symbol file.
</td>
</tr>
<tr>
<td valign="top"><tt>STANDALONE=1</tt></td>
<td>
Build a standalone VxWorks image, with the symbol table
built in to the image itself.
This is *not* a network-bootable image; it must be flashed
onto the FFSC.
</td>
</tr>
<tr>
<td valign="top"><tt>STANDALONE=1 NETBOOT=1</tt></td>
<td>
Build a network-bootable standalone VxWorks image.
The symbol table is built into the image itself, but the
load address is set so that the image can be booted over
the network.
</td>
</tr>
<tr>
<td valign="top"><tt>PRODUCTION=1</tt></td>
<td>
Build a production version of the FFSC firmware image.
This is similar to a STANDALONE image, except that the
symbol table and other debugging features (e.g. the target
shell) have been removed so that the image is smaller.
</td>
</tr>
<tr>
<td valign="top"><tt>BOOTROM=1</tt></td>
<td>
Build a bootrom image.
Once this image is flashed into the FFSC, the FFSC will
try to boot the actual VxWorks image over the network.
</td>
</tr>
<tr>
<td valign="top"><tt>BOOTROM=1 FFSC_NUM=<i>num</i></tt></td>
<td>
Build a bootrom image for a specific FFSC.
This simply changes the naming convention for the object
directory and final image of the bootrom, though it can
also be used to tweak the bootline parameters if desired
(see below for info on the <tt>bootdefs</tt> file).
</td>
</tr>
</table>
<p>
There are a number of specific targets that can be invoked as well:
</p>
<table>
<tr>
<td valign="top"><tt>vxworks</tt></td>
<td>Same as <tt>make default</tt></td>
</tr>
<tr>
<td valign="top"><tt>vxworks.st</tt></td>
<td>Same as <tt>make STANDALONE=1</tt></td>
</tr>
<tr>
<td valign="top"><tt>bootrom_uncmp</tt></td>
<td>Same as <tt>make BOOTROM=1</tt></td>
</tr>
<tr>
<td valign="top"><tt>depend</tt></td>
<td>Generate dependencies for the selected image</td>
</tr>
<tr>
<td valign="top"><tt>dependall</tt></td>
<td>
Generate dependencies for all known images (i.e. all
6 of the images described above)
</td>
</tr>
<tr>
<td valign="top"><tt>clean</tt></td>
<td>Clean up object files and generated source files</td>
</tr>
<tr>
<td valign="top"><tt>clobber</tt></td>
<td>
same as clean, but also deletes final targets and
dependency files
</td>
</tr>
<tr>
<td valign="top"><tt>deltree</tt></td>
<td>delete the object directory</td>
</tr>
<tr>
<td valign="top"><tt>rmtarget</tt></td>
<td>remove the final target file(s) only</td>
</tr>
<tr>
<td valign="top"><tt>srcclean</tt></td>
<td>erase cruft (such as *~ files) from *source* directories</td>
</tr>
<tr>
<td valign="top"><tt>sterile</tt></td>
<td>
like srcclean followed by a clobber and rmdir of each
possible object directory.
</td>
</tr>
</table>
<p>
After a <tt>make sterile</tt> a <tt>p_check -w</tt> should
only show <tt>bootdefs</tt> and <tt>ffscvars.bat</tt> (if present)
</p>
<h3>The bootdefs File</h3>
<p>
Building a bootrom image requires a fair amount of information
about the current environment, such as the name and address of
the host PC and the path name of the VxWorks image on the host
machine.
This information is obtained from a file called
<tt>bootdefs</tt> in the top-level directory of the workarea.
To create a bootdefs file, simply copy the template file
<tt>protobootdefs</tt> (which is part of the source tree) to
<tt>bootdefs</tt> and edit it to match your current
configuration.
If you are working with two or more FFSC's, you can examine
the contents of the FFSC_NUM variable and adjust several of
the values (such as the target IP address) using the GNUmake
<tt>ifeq</tt> command.
</p>
<h3>Building a formal production image</h3>
<p>
Because the FFSC firmware is not built under IRIX, it cannot
be formally built for releases by the build group.
Instead, an Official Production Image is built and checked
into the appropriate irix source tree in uuencoded form.
The standard irix build process can then take over and
include a binary version of the image in the standard irix
distributions (typically in /usr/cpu/firmware/ffscfw.bin).
</p>
<p>
The steps required to do all of this are split up between
the PC and a standard ptools workarea under unix:
</p>
<ol>
<li>
UNIX: p_tupdate everything
</li>
<p>
<li>
PC: update briefcases
</li>
<p>
<li>
PC: Roll the version number in the FFSC_VERSION #define at the
top of <tt>sgi/src/sgiversion.c</tt>
</li>
<p>
<li>
PC: <tt>make PRODUCTION=1 clobber</tt>
</li>
<p>
<li>
PC: <tt>make PRODUCTION=1 depend</tt>
</li>
<p>
<li>
PC: <tt>make PRODUCTION=1</tt>
</li>
<p>
<li>
Copy the resulting vxworks.st file to your unix workarea as
<tt>$WORKAREA/stand/x86/ffsc/vxworks.st</tt>.
</li>
<p>
<li>
UNIX: in $WORKAREA/stand/x86/ffsc,
<tt>p_modify ffscfw.bin.uu</tt>
</li>
<p>
<li>
UNIX (same directory): <tt>make</tt>
<br>
(this will uuencode vxworks.st into ffscfw.bin.uu, then
uudecode ffscfw.bin.uu into ffscfw.bin)
</li>
<p>
<li>
UNIX: if you are paranoid,
<tt>diff&nbsp;ffscfw.bin&nbsp;vxworks.st</tt> to make sure
everything went OK.
</li>
<p>
<li>
UNIX: check-in ffscfw.bin.uu to bonnie for safe keeping
</li>
</ol>
<hr>
<p>
<a href="index.html">up a level</a><br>
</p>
<p>
<address>
<a href="mailto:rdb@uniscan.engr.sgi.com">Rob Bradshaw</a>
</address>
</p>
<!-- Created: Sat Sep 7 11:36:12 PDT 1996 -->
<!-- hhmts start -->
Last modified: Thu Oct 3 23:29:55 PDT
<!-- hhmts end -->
</body>
</html>