File: driver.html

package info (click to toggle)
etherboot 5.4.3%2Bdfsg-0.2
links: PTS
area: main
in suites: lenny
size: 9,844 kB
ctags: 34,534
sloc: ansic: 104,914; asm: 6,606; perl: 2,795; makefile: 1,113; sh: 448; java: 324; xml: 14
file content (725 lines) | stat: -rw-r--r-- 20,920 bytes
parent folder | download | duplicates (3)
<HTML
><HEAD
><TITLE
>Writing an Etherboot Driver</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
REL="HOME"
HREF="t1.html"><LINK
REL="PREVIOUS"
TITLE="Frequently asked questions"
HREF="x295.html"><LINK
REL="NEXT"
TITLE="A potted history of Etherboot"
HREF="x397.html"></HEAD
><BODY
CLASS="sect1"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
></TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="x295.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="x397.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="driver"
></A
>Writing an Etherboot Driver</H1
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="AEN308"
></A
>Preliminaries</H2
><P
>&#13;So Etherboot does not have a driver for your network adapter and you
want to write one. You should have a good grasp of C, especially with
respect to bit operations. You should also understand hardware interfacing
concepts, such as the fact that the x86 architecture has a separate I/O
space and that peripherals are commanded with `out' instructions and
their status read with `in' instructions.  A microprocessor course such
as those taught in engineering or computer science curricula would have
given you the fundamentals. (Note to educators and students in computer
engineering: An Etherboot driver should be feasible as a term project
for a final year undergraduate student. I estimate about 40 hours of
work is required. I am willing to be a source of technical advice.)

</P
><P
>&#13;Next you need a development machine. This can be your normal Linux
machine. You need another test machine, networked to the development
machine. This should be a machine you will not feel upset rebooting very
often. So the reset button should be in working condition. :-) It should
have a floppy drive on it but does not need a hard disk, and in fact a
hard disk will slow down rebooting. Alternatively, it should have
another network adapter which can netboot; see discussion further down.
Needless to say, you need a unit of the adapter you are trying to write
a driver for. You should gather all the documentation you can find for
the hardware, from the manufacturer and other sources.

</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="AEN312"
></A
>Background information</H2
><P
>&#13;There are several types of network adapter architecture. The simplest to
understand is probably programmed I/O. This where the controller reads
incoming packets into memory that resides on the adapter and the driver
uses `in' instructions to extract the packet data, word by word, or
sometimes byte by byte. Similarly, packets are readied for transmission
by writing the data into the adapter's memory using `out' instructions.
This architecture is used on the NE2000 and 3C509. The disadvantage of
this architecture is the load on the CPU imposed by the I/O. However
this is of no import to Etherboot (who cares how loaded the CPU is
during booting), but will be to Linux. Next in the sophistication scale
are shared memory adapters such as the Western Digital or SMC series, of
which the WD8013 is a good example. Here the adapter's memory is also
accessible in the memory space of the main CPU.  Transferring data
between the driver and the adapter is done with memory copy
instructions. Load on the CPU is light. Adapters in this category are
some of the best performers for the ISA bus.  Finally there are bus
mastering cards such as the Lance series for the ISA bus and practically
all good PCI adapters (but not the NE2000 PCI). Here the data is
transferred between the main memory and the adapter controller using
Direct Memory Access. Setting up the transfers usually involves a
sequence of operations with the registers of the controller.

</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="AEN315"
></A
>Structure of the code</H2
><P
>&#13;Examine the file <TT
CLASS="filename"
>skel.c</TT
>, in the src directory,
which is a template for a driver. You may also want to examine a working
driver. You will see that an Etherboot driver requires 4 functions to be
provided:

</P
><P
>&#13;
<P
></P
><UL
><LI
><P
>&#13;A probe routine, that determines if the network adapter is present
on the machine. This is passed a pointer to a `nic' struct, possibly a list of
candidate addresses to probe, and possibly a pointer to a `pci' struct.
This routine should initialise the network adapter if present.  If a
network adapter of the type the driver can handle is found, it should
save the I/O address at which it was found for use by the other
routines. In the case of ISA adapters, it may be passed a list of
addresses to try, or if no list is passed in, it may use an internal
list of candidate addresses. In the case of PCI adapters, the address
has already been found by the PCI support routines. Then it should
determine the Ethernet (MAC) address of the adapter and save it in
nic-&#62;node_addr. It should then initialise the
adapter.  Finally it should fill in the function pointers for the other
routines, and return the `nic' pointer. If it fails to find an adapter,
it should return 0.

</P
><P
>&#13;The field rom_info in the `nic' struct contains, on entry to the probe
routine, a pointer to the structure rom_info, defined in <TT
CLASS="filename"
>etherboot.h</TT
>.
This contains the segment address and length in shorts of the ROM as
detected by the BIOS.  These can be used by the driver to discriminate
between multiple instances of the same network adaptor on the bus, and
choose to activate only the one the ROM is installed on. For example,
the 3c509 hardware has a register indicating what address the ROM is
mapped at. Note that the driver should not reject "ROM segment
addresses" outside 0xC000 to 0xEE00 as this indicates booting from
floppy disk or other non-ROM media.

</P
><P
>&#13;Initialising the adapter means programming the registers so that the
chip is ready to send and receive packets. This includes enabling the
appropriate hardware interface (10B2, 10BT) in the case of adapters with
more than one interface, and setting the right speed (10Mb, 100Mb) if
the hardware does not autosense and set it.  It also includes setting up
any memory buffers needed by the hardware, along with any necessary
pointers.

</P
><P
>&#13;Note that you should program the receiver registers to allow broadcast
Ethernet packets to be received.  This is needed because other IP hosts
will do an ARP request on the diskless computer when it boots.

</P
></LI
><LI
><P
>&#13;A disable routine, which puts the adapter into a disabled state.  This
is passed a pointer to a `nic' struct.  This is needed to leave the
adapter in a suitable state for use by the operating system which will
be run after Etherboot. Some adapters, if left in an active state, may
crash the operating system at boot time, or cannot be found by the
operating system.  This can be called from the probe routine.

</P
></LI
><LI
><P
>&#13;A transmit routine, to send an Ethernet packet. This is passed a
pointer to a `nic' struct, the 6 byte Ethernet address of the destination,
a packet type (IP, ARP, etc), the size of the data payload in bytes, and
a pointer to the data payload. Remember the packet type and length fields
are in x86 byte order (little-endian) and the adapter's byte order may be
the reverse (big-endian). Note that the routine knows nothing about IP
(or any other type) packets, the data payload is assumed to be a filled
in packet, ready to transmit.

</P
></LI
><LI
><P
>&#13;A poll routine, to check if a packet has been received and ready
for processing. This is passed a pointer to a `nic' struct. If a packet
is available, it should copy the packet from the adapter into the data
area pointed to by nic-&#62;packet, and set nic-&#62;packetlen to the length of
the data, and return 1, otherwise 0.

</P
><P
>&#13;A few Ethernet controller chips will receive packets from itself, as
detected by having a source address of itself. You can throw these out
immediately on reception and not bother the upper layer with them.

</P
></LI
></UL
>
</P
><P
>&#13;No routine needs to be public, all routines should be static and private
to the driver module. Similarly all global data in the driver should be
static and private.

</P
><P
>&#13;If the NIC is a PCI adapter, create a struct pci_driver (as in
<TT
CLASS="filename"
>skel.c</TT
>) and an array of struct pci_id:

<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="programlisting"
>&#13;static struct pci_id skel_nics[] = {
PCI_ROM(0x0000, 0x0000, "skel-pci", "Skeleton PCI Adaptor"),
};
</PRE
></TD
></TR
></TABLE
>

Fill the pci_id array with one entry for each combination of pci vendor
id and pci device id that your driver can handle.  PCI_ROM is a a macro
defined in <TT
CLASS="filename"
>include/pci.h</TT
>.  The arguments have the
following meaning: vendor id, device id, rom name and short description.
Since this information is also used to build the Makefile rules, you
must use the PCI_ROM macro and can't fill in the values directly.  Both
the pci vendor and device id must be given in hex form, no define is
allowed.  Additionally PCI_ROM must occur only once in a line and one
macro call must not span more than one line.  You can obtain the vendor
and device ids from the file
<TT
CLASS="filename"
>/usr/include/linux/pci.h</TT
>. It is also displayed by
PCI BIOSes on bootup, or you can use the <B
CLASS="command"
>lspci</B
>
program from the pciutils package to discover the ids.

</P
><P
>&#13;If the NIC is an ISA adapter, create a struct isa_driver (as in
<TT
CLASS="filename"
>skel.c</TT
>) and one line like the following:

<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="programlisting"
>&#13;ISA_ROM("skel-isa", "Skeleton ISA driver")
</PRE
></TD
></TR
></TABLE
>

in your driver source. The ISA_ROM macro is like the PCI_ROM without the
vendor/device ids. The same rules about formatting as in the PCI case
apply.

</P
><P
>&#13;Only for special cases where the automatic generation of build rules via
the PCI_ROM and ISA_ROM entries does not work, add an entry to the here
document in <TT
CLASS="filename"
>genrules.pl</TT
> so that the build process
will create Makefile rules for it in the file
<TT
CLASS="filename"
>bin/Roms</TT
>.

</P
><P
>&#13;The above mentioned structs and macros hold all information that
etherboot needs about your driver. In case you wonder how this works at
all although everything is declared static: The special build process
that is used by Etherboot (including linker scripts and some Perl magic)
packs the necessary information into public segments.

</P
><P
>&#13;The Etherboot build process places a few restrictions on your driver:
If you need more than one .c file, the main file (that will contain
the PCI_ROM or ISA_ROM macro call) must contain #include directives for
the other files. They must not contain a PCI_ROM or ISA_ROM call.
See <TT
CLASS="filename"
>drivers/net/prism*</TT
> for an example.

</P
><DIV
CLASS="sect3"
><H3
CLASS="sect3"
><A
NAME="AEN350"
></A
>Rom naming rules</H3
><P
>&#13;Currently there is no official rom naming convention in etherboot. Use
some descriptive name, but note that two ore more consecutive hyphens
(like in "my--rom") are not allowed, since "--" is the delimiter sign
for multiple-driver-roms.  Sometimes it is difficult to find a sensible
name, for example for "NICs" that are built in motherboard chipsets or
if you don't know the model name.  In this case we choose to name the
corresponding roms "driver-deviceid", like "eepro100-1035". Of course
you have to make sure that your rom name is unique in etherboot.

</P
></DIV
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="AEN353"
></A
>Booting the code from a floppy</H2
><P
>&#13;Use the rule for bin/driver.fd0 to write another instance of the driver
to the floppy for testing. Use lots of printf statements to track where
execution has reached and to display the status of various variables and
registers in the code.  You should expect to do this dance with the
development machine, floppy disk and target machine many many times.

</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="AEN356"
></A
>Booting the test code with another Etherboot ROM</H2
><P
>&#13;There is another method of testing ROM images that does not involve
walking a floppy disk between the machines and is much nicer. Set up a
supported NIC with a boot ROM. Put the target NIC on the same machine
but at a non-conflicting I/O location. That is to say, your test machine
has two NICs and two connections to the LAN.  Then when you are ready to
test a boot image, use the utility <A
HREF="../mknbi.html"
TARGET="_top"
>mknbi-rom</A
> to create a network bootable image
from the ROM image, and set up bootpd/DHCPD and tftpd to send this over
the when the machine netboots.  Using Etherboot to boot another version
of itself is rather mind-boggling I know.

</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="AEN360"
></A
>Writing the code</H2
><P
>&#13;First set up the various required services, i.e. BOOTP/DHCP, tftp, etc.
on the development machine. You should go through the setup process with
a supported adapter card on a test machine so that you know that the
network services are working and what to expect to see on the test
machine.

</P
><P
>&#13;If you are starting from a Linux driver, usually the hardest part is
filtering out all the things you do not need from the Linux driver. Here
is a non-exhaustive list: You do not use interrupts. You do not need
more than one transmit buffer. You do not need to use the most efficient
method of data transfer. You do not need to implement statistics
counting.  In general it is a good idea to use the latest Linux driver
as base, because it usually supports newer cards and has more bugs fixed
than older versions.  If the driver is written by Donald Becker, it is
probably best to start from the version available on <A
HREF="http://www.scyld.com/page/support/network/"
TARGET="_top"
>this page</A
>,
since the driver in the official kernel may be behind.  See also <A
HREF="driver.html#sync-linux"
>the Section called <I
>Keeping your driver in sync with the Linux version</I
></A
>.

</P
><P
>&#13;Generally speaking, the probe routine is relatively easy to translate
from the Linux driver. The exception is when you need to handle media
and speed switching. The transmit is usually straightforward, and
the receive a bit more difficult. The main problem is that in the Linux
driver, the work is split between routines called from the kernel and
routines triggered by hardware interrupts.  As mentioned before,
Etherboot does not use interrupts so you have to bring the work of
transmitting and receiving back into the main routines. The disable
routine is straightforward if you have the hardware commands.

</P
><P
>&#13;When coding, first get the probe routine working. You will need to refer
to the programmer's guide to the adapter when you do this.  You can also
get some information by reading a Linux or FreeBSD driver. You may also
need to get the disable routine working at this time.

</P
><P
>&#13;Next, get the transmit routine working. To check that packets are going
out on the wire, you can use tcpdump or ethereal on the development
machine to snoop on the Ethernet. The first packet to be sent out by
Etherboot will be a broadcast query packet, on UDP port 67. Note that
you do not need interrupts at all.  You should ensure the packet is
fully transmitted before returning from this routine.  You may also wish
to implement a timeout to make sure the driver doesn't get stuck inside
transmit if it fails to complete. A couple of timer routines are
available for implementing the timeout, see <TT
CLASS="filename"
>timer.h</TT
>.
You use them like this (in pseudo-code):

<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="programlisting"
>&#13;	for (load_timer2(TIMEOUT_VALUE);
		transmitter_busy &#38;&#38; (status = timer2_running()); )
		;
	if (status == 0)
		transmitter_timed_out;
</PRE
></TD
></TR
></TABLE
>

The timeout value should be 1193 per millisecond of wait. The maximum
value is 65535, which is about 54 milliseconds of timeout. If you just
need to delay a short time without needing to do other checks during the
timeout, you can call waiton_timer2(TIMEOUT_VALUE) which will load, then
poll the timer, and return control on timeout.

</P
><P
>&#13;Please do not use counting loops to implement time-sensitive delays.
Such loops are CPU speed dependent and can fail to give the right delay
period when run on a faster machine.

</P
><P
>&#13;Next, get the receive routine working. If you already have the transmit
routine working correctly you should be getting a reply from the
BOOTP/DHCP server. Again, you do not need interrupts, unlike drivers
from Linux and other operating systems. This means you just have to
read the right register on the adapter to see if a packet has arrived.
Note that you should NOT loop in the receive routine until a packet
is received. Etherboot needs to do other things so if you loop in the
poll routine, it will not get a chance to do those tasks. Just return
0 if there is no packet awaiting and the main line will call the poll
routine again later.

</P
><P
>&#13;Finally, get the disable routine working. This may simply be a matter
of turning off something in the adapter.

</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="AEN374"
></A
>Things to watch out for</H2
><P
>&#13;Things that may complicate your coding are constraints imposed by the
hardware. Some adapters require buffers to be on word or doubleword
boundaries. See <TT
CLASS="filename"
>rtl8139.c</TT
> for an example of this.
Some adapters need a wait after certain operations.

</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="AEN378"
></A
>Tidying up</H2
><P
>&#13;When you get something more or less working, release early. People on the
mailing lists can help you find problems or improve the code. Besides
you don't want to get run over by a bus and then the world never gets
to see your masterpiece, do you? :-)

</P
><P
>&#13;Your opus should be released under GPL, BSD or a similar Open Source
license, otherwise people will have problems using your code, as most
of the rest of Etherboot is GPLed.

</P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="sync-linux"
></A
>Keeping your driver in sync with the Linux version</H2
><P
>&#13;Most Etherboot drivers are derived from their Linux counterparts.
Sooner or later the Linux driver where you started from will get
updated.  This may include bugfixes and support for new NICs.
Unfortunately there is no way to keep the Etherboot driver automatically
up to date, but if you keep the following rules in mind while porting it
can be made easier:

<P
></P
><UL
><LI
><P
>&#13;State the version of the Linux driver in a comment in your Etherboot
driver.  This makes it easy to check to which Linux driver the Etherboot
driver corresponds </P
></LI
><LI
><P
>&#13;Etherboot drivers should be small. Often a Linux driver contains way too
much code, but in many cases you can reuse some utility functions from
the Linux driver without blowing up the code size too much. In this
case, keep the order in which they are defined where possible, and avoid
code reformatting in general.  (re-indenting is ok, because
<B
CLASS="command"
>diff</B
> can ignore it with the -b switch). This makes it
easy to compare later versions with utilities like
<B
CLASS="command"
>mgdiff</B
>.

</P
></LI
><LI
><P
>&#13;You can get the pci ids of all NIC drivers of a particular Linux kernel
with the utility <B
CLASS="command"
>get-pci-ids</B
> in
<TT
CLASS="filename"
>util</TT
> and compare them to the entries in
<TT
CLASS="filename"
>bin/NIC</TT
> in order to find out wether the Linux
kernel supports some new NICs.

</P
></LI
></UL
>
</P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="x295.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="t1.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="x397.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Frequently asked questions</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
>&nbsp;</TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>A potted history of Etherboot</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>