Re: First FAQ draft, please read this

[ws%kurt.tools.de@localhost (Wolfgang Solfrank)]

First of all, thank you very much for this effort!  I really appreciate it.


But now :-) some corrections to the text:

> 2.2 Who is working on the port?
> 
> 
> 
>    NetBSD was first ported to the PowerPC by Wolfgang Solfrank
>    <ws%tools.de@localhost>.  Among others, Jason Thorpe contributed to this 
> port.

While I had quite a few discussions with Jason during the late stages of the
port, he didn't contribute to it (yet).

>                     3 WHAT DO I NEED TO RUN NETBSD/PowerPC
> 
> 
> 
>    This chapter describes the hardware related topics of NetBSD. It will
>    explain, what kind of hardware you need to be able to run NetBSD on
>    your PowerPC.
> 
>    In general, there are two major requirements your system must fulfill
>    to be able to run NetBSD. You must have an apropriate CPU and enough
>    memory. To comfortably run NetBSD you should dedicate some
>    harddiskspace to NetBSD.

Should probably mention OpenFirmware here, too.

> 3.1 Which CPU is needed?
> 
> 
> 
>    It depends heavily on the type of CPU your system has, whether or not
>    NetBSD runs on your PowerPC. NetBSD, as any other modern Unix-derivate,
>    too, must have a memory-management-unit (MMU) to be able to run. This
>    is needed as all the programs that run under Unix are separated from
>    each other, so no program can do any harm to any other.
> 
>    You need to have one of the following processors (CPUs) to be able to
>    run NetBSD:
>      * PPC 603
>      * PPC 603e
>      * PPC 604

Most likely 604e and probably 704 should work, too.  On the other hand, I'm
not aware of anyone who tested this on anything but 603 and 604.

>    NetBSD/powerpc does currently not support the 601.
> 
>    Also note, that you currently need a floating-point-unit (FPU) to be
>    able to run NetBSD. The kernel itself, that is the core part of
>    NetBSD, does not need an FPU, but some of the essential utilities do.
>    Other ports of NetBSD on other architectures have an FPU-emulator
>    implemented in the kernel, so they can do without an FPU. So, if
>    someone implements an FPU-emulator for NetBSD on the
>    680x0-architecture, the need for a seperate FPU will eventually
>    vanish, but for now you need an FPU.

All PowerPCs (in question) do have an FPU on chip.

> 3.2 How much memory do I need?
> 
> 
> 
>    Theoretically, you only need 2MB of RAM. It has been tested with as
>    much as 8MB as a minimum.

I don't think that it was tested with 8MB.  I've always run it on 64MB machines,
but I don't know what would be the absolute minimum.

>    Note that the complete GENERIC kernel (including drivers for every
>    device supported) is over 1MB in size; you can't load this kernel with
>    only 1MB of RAM, 2MB is required.

The current NetBSD/powerpc GENERIC kernel is ~760KB text, ~30KB data and ~110KB
bss, so it is below 1MB.  But that's just nitpicking.  I'm pretty sure that
it doesn't boot in 1MB of RAM.

>   3.2.1 NON CONTIGUOUS MEMORY
> 
> 
> 
>    With the PowerPC's architecture being what it is, it is often the case
>    that the memory map will have "holes" in it - say, 1MB of RAM,
>    followed by a gap, 4MB of RAM, a gap, and then in (very) high
>    memory a block of 32bit RAM; this is often the case with machines
>    upgraded with different types of RAM.
> 
>    To use more then one such chunk of memory, you need a kernel that was
>    build with the following line in the config-file (See section 6 How do
>    I build a kernel myself?, for more information on how to compile your
>    own kernel):
> 
>    options MACHINE_NONCONTIG # Non-contiguous memory support

This isn't an option for the PowerPC port.  MACHINE_NONCONTIG, while being
introduced to support machines with non-contiguous memory, defines a somewhat
different internal interface between the machine independent (vm) and the
machine dependent (pmap) routines.  So even on machines with only one chunk
of contiguous memory, it is required to use this options line.

BTW, when I wrote the code that is now #ifdef MACHINE_NONCONTIG, I didn't
intend this as an option.  It should have completely replaced the old system.
However, when I made the changes available to other developers, John Brezak
integrated them with the current #ifdef scheme.  Otherwise we'd probably
still not have these changes in, judging from the ports that still don't
support this option.

> 3.4 What other hardware requirements are there?

...

>    A tape drive is recommended for NetBSD, as for any other operating
>    system, too. You should do regularly backups in order to be able to
>    restore the data you might have accidentially destroyed. Especially
>    when you are doing kernel-development, chances are, that you may trash
>    your harddisk. The system is normally quite stable, so doing backups
>    is not a must but a sensible option.

There currently isn't support for tape drives in NetBSD/powerpc (but it should
be quite easy to integrate it).

>    The reason why OpenFirmware is used, instead of PPC1-Bug or MMCG
>    Firmware is quite an easy one:  OpenFirmeware is part of the
>    PREP-Standard and will be supported by all major key players in the
>    PowerPC-market such as Apple, Be, Motorola, IBM. So the major
>    advantage is that you can program NetBSD for any PowerPC available on
>    the market with just one source tree.

More relevant probably is the fact that OpenFirmware is also part of the
PPCP (aka CHRP) standard, since this is the reason that Be, Motorola and IBM
are working on support for it.

> 3.5 What hardware is supported by NetBSD/powerpc V1.2, anyways?

I'd not call it V1.2, as there isn't a release of NetBSD/powerpc yet.

>    Known Hardware to be able to run NetBSD/powerpc:
> 
>    Motorola Ultra Board
>    Motorola Atlas Board
>    FirePower ES 4000 series

Development of NetBSD/powerpc was on a FirePower MX 4100 machine.

> 3.6 Things currently not supported by NetBSD/powerpc

...

>    It is rumoured that Apple has released OFW for most recent PowerMacs.

The PowerMacs with PCI bus all had OpenFirmware from the very start.

>    It is rumoured that Be's most recent machines will have OFW.

AFAIK they are working on it.

> 4.3 World Wide Web
> 
> 
> 
>    This document is available via the World Wide Web (Mosaic, Netrape,
>    lynx etc.) at
>    http://beaver.teuto.de/netbsd/

Should probably mention http://WWW.NetBSD.ORG.

> 4.6 Useful books

...

>      * Samuel J. Leffer, et al: Design and Implementation of the 4.3BSD
>        Operating System
>        
>        This book is to BSD-Unix what 'Programming Perl' is to the perl
>        programming language and Kernighan/Ritchie's 'C Programming
>        language' is to C. Also based on 4.3BSD, it's still the most
>        comlete description of all the internals of a BSD-favoured unix,
>        from device drivers to interrupt handling and from memory
>        management to the filesystem. This might not be the book you look
>        into when you're about to write 'just' a device driver, but it's
>        certainly of value if you want to understand the relationship
>        between the verious subsystems of the operating system. An 'upate'
>        for 4.4BSD is in the works.

The 4.4 book is out for quite a while now (see below).

>        Contents: [Heh, i don't own that book! Anyone care to give me a
>        summary of the contents? - HF] 

        Contents: History and Goals, Design Overview of 4.3BSD, Kernel
        Services, Process Management, Memory Management, I/O System
        Overview, The Filesystem, Device Drivers, Terminal Handling,
        Interprocess Communication, Network Communication, Network
        Protocols, System Startup

>           + Name: Design and Implementation of the 4.3BSD Operating
>             System
>           + Author(s): Samuel J. Leffler, Marshall Kirk McKusick, Michael
>             J. Karels, John S. Quarterman
>           + Publisher: Addison-Wesley Publishing Company 
>           + ISBN: 0-201-06196-1
>           + Pages: 471

      * Marshall Kirk McKusick, et al.: The Design and Implementation of
        the 4.4BSD Operating System

        Similar to the above, but more related to the newer 4.4 version
        of BSD-Unix (which NetBSD is based on).

        Contents: History and Goals, Design Overview of 4.4BSD, Kernel
        Services, Process Management, Memory Management, I/O System
        Overview, Local Filesystems, Local Filestores, The Network
        Filesystem, Terminal Handling, Interprocess Communication,
        Network Communication, Network Protocols, System Startup

        + Name: The Design and Implementation of the 4.4BSD
                Operating System
        + Author(s): Marshall Kirk McKusick, Keith Bostic,
                Michael J. Karels, John S. Quarterman
        + Publisher: Addison-Wesley Publishing Company
        + ISBN: 0-201-54979-4
        + Pages: 580

>                       6 HOW DO I BUILD A KERNEL MYSELF?
> 
> 6.1 Introduction
> 
> 
> 
>    Theoretically you have two options here. You can build the kernel
>    under PowerPCDOS or under NetBSD itself. Initially NetBSD was compiled
>    under PowerPCDOS, of course, but now everybody works under NetBSD
>    itself. Recent attempts to compile the kernel under PowerPCOS showed
>    that the compiler, assembler, linker etc. have developped differently,
>    and that you can't produce a working kernel under PowerPCOS anymore.

What is PowerPCDOS? PowerPCOS?

Initially NetBSD/powerpc was compiled on SunOS 4.1.3 on a Sun Sparcstation.
I'm still using this setup (actually Solaris 2.5 now) for kernel development
in order to have the kernel with debugging symbols on the Sparcstation for
remote debugging.  Userlevel code is now compiled on NetBSD/powerpc itself.

> 6.2 Getting the kernel source
> 
> 
> 
>    To build the new kernel under NetBSD, make sure you have the compiler
>    package (comp11) and the kernel source tree (ksrc11/*) installed. See
>    section 5 Where to get sources?, for ways to get the kernel source.

xxx11 will never have any NetBSD/powerpc sources.  Even xxx12 won't.

And currently the compiler isn't available yet anyway.  (I need to work out
the way to integrate the PowerPC part of GCC into the automagic conversion
script gcc2netbsd).

> 6.5 Installing your kernel

...

>    Note that this may hang if the new kernel differs substancially from
>    the old one. Just reset your machine (three-finger-salut) and reboot
>    NetBSD via loadbsd instead.

Booting NetBSD/powerpc isn't done via loadbsd, but via boot.ppc.

>    See section 8.3.5 How do I create device files?, for information on
>    how to create device-files, if the file `/dev/reload' doesn't exist.

There isn't something like /dev/reload in NetBSD/powerpc (yet?).

>                        7 NETBSD - LINUX - AMIX - MINIX
> 
> 
> 
>    Currently there are four possibilies to run Unix on the PowerPC.
> 
>    IBM provides AIX for their PowerPC machines. It is likely that it runs
>    only on IBM machines.
> 
>    Sun Software provides Solaris for almost all PowerPC machines. It is
>    rumoured that you can boot Solaris from almost any firmware, of course
>    including OFW.
> 
>    The third available Unix on the PowerPC is Linux . It was first
>    designed to run on Intel-based PCs. However, someone
>    started a major rewrite of the sources so that it is now possible to
>    run Linux on the PowerPC.  The first public kernel release happened
>    around August 1996, a few months after the first Linux 2.0 kernels
>    came out. Linux/powerpc supposeldy runs on Motorola machines with the
>    PPC1-Bug firmware - thus not on PowerMac nor FirePower.
> 
>    The Linux/powerpc FAQ can be found at:
>    http://www.libuxppc.org/

To be complete there is also Linux for Power Macintosh. See for example
http://product.info.apple.com/pr/press.releases/1995/q2/960205.pr.rel.osf.html.

>   8.2.1 HOW DO I GET A SERIAL TERMINAL TO WORK CORRECTLY?

There currently is no support for serial terminals in NetBSD/powerpc (apart
from machines having a serial terminal as console).

>   8.3.3 CAN I ACCESS MS-DOS OR WIN NT FILES FROM NETBSD?
> 
> 
> 
>    The MS-DOS file system driver for NetBSD-PowerPC can currently mount
>    MS-DOS file systems.  For more information on how to mount MS-DOS
>    filesystems, see the `mount' and `mount_msdos' man pages.
> 
>    Currently there is no HPFS driver for NetBSD.

AFAIK HPFS is the filesystem primarily used in OS/2, while NT primarily uses
NTFS instead.  But I don't know enough about those to even decide whether
these might be the same.

>   8.3.9 IS THERE A DEBUGGER FOR NETBSD?
> 
> 
> 
>    The GNU debugger `gdb' is available for NetBSD (it is in the standard
>    comp* distribution package).

Currently gdb isn't supported in NetBSD/powerpc.

>   8.3.10 HOW DO I REPORT BUGS?
> 
> 
> 
>    If you think you have discovered a bug, and you are sure its not your
>    mistake, the best thing to do is to mail on one of the mailing lists
>    (See section 4 Where can I find more information on NetBSD? for
>    details). Try to include as much information as possible - the
>    configuration of your machine, the output you saw, the exact
>    circumstances etc.; if possible try to isolate the bug as far as is
>    possible (ie. don't just say `my machine crashes', try to explain what
>    causes it to crash!).

Bugs should best be reported through the standard NetBSD send-pr mechanism.
This way they get placed in the NetBSD bugs database and can be tracked.
There is even a port-powerpc category in there for you to report bugs against.

>   8.3.11 HOW DO I GET A META-KEY FOR EMACS?
> 
> 
> 
>    Executing the commands `stty cs8 -istrip -parenb' will allow you to
>    use any of the PowerPC keys as a meta-key.

This depends on the keycodes the OpenFirmware console driver delivers for
those meta-keys.

>   8.3.15 WHAT'S ALL THIS STUFF ABOUT BINARY EMULATION?

There isn't anything like binary emulation in NetBSD/powerpc (yet?).

>   8.3.16 HOW CAN I BOOT NETBSD WITHOUT KEEPING AN MS-DOS PARTITION?
> 
> 
> 
>    There is no way to boot NetBSD without having a small MS-DOS
>    partition which holds loadbsd and the kernel:

The boot code is boot.ppc, not loadbsd.


Sorry for the amount of nit-picking, but I wanted to get some things straight.

Again, I really appreciate your effort, and I'd like it if you could maintain
this further.
--
ws%TooLs.DE@localhost     (Wolfgang Solfrank, TooLs GmbH)       +49-228-985800