david/ipxe
david
/
ipxe
Archived
1
0
Fork 0
This repository has been archived on 2020-12-06. You can view files and clone it, but cannot push or open issues or pull requests.
ipxe/src
Michael Brown 0f8d7d705d Rename .cvsignore files to .gitignore 2007-06-09 22:57:00 +01:00
..
arch/i386 pkbuff->iobuf changeover 2007-05-19 18:39:40 +00:00
bin Rename .cvsignore files to .gitignore 2007-06-09 22:57:00 +01:00
config Rename .cvsignore files to .gitignore 2007-06-09 22:57:00 +01:00
core Added missing va_end() 2007-06-03 02:11:25 +00:00
crypto Conflicts with native asn1.c 2007-06-08 12:37:35 +00:00
doc Documented the link stages 2005-05-20 13:35:39 +00:00
drivers Update email addresses in drivers 2007-06-09 15:23:17 -04:00
hci Added EPIPE description. 2007-05-26 15:05:31 +00:00
image Actually, the initrd image should be architecture-independent. 2007-01-14 15:07:11 +00:00
include Rename .cvsignore files to .gitignore 2007-06-09 22:57:00 +01:00
interface/pxe Updated to use POSIX-style file I/O layer. 2007-05-18 14:33:20 +00:00
net Move [v]ssnprintf() from iscsi.c into vsprintf.c; we need them 2007-05-31 13:26:50 +00:00
proto A working DNS resolver (not yet tied in to anything) 2007-01-15 17:31:35 +00:00
tests Add a couple of tests for the URI parsing and resolving code. 2007-06-03 02:15:00 +00:00
usr hoffmeis: Preparations for syslog support (LOGSERVER in DHCP, linewise 2007-04-09 18:01:43 +00:00
util Rename .cvsignore files to .gitignore 2007-06-09 22:57:00 +01:00
.gitignore Rename .cvsignore files to .gitignore 2007-06-09 22:57:00 +01:00
Config Removed vestigal FILO code 2006-06-29 18:07:02 +00:00
Makefile Add warning about formats that are not working until we fix them 2007-03-02 16:25:42 +00:00
Makefile.housekeeping Add gpxe-tarball target to create clean release tarballs 2007-03-02 16:28:04 +00:00
README.cvs Merged this file into HEAD 2005-03-24 13:54:46 +00:00
README.pixify Initial revision 2005-03-08 18:53:11 +00:00
config.h A working name resolution framework 2007-01-18 22:38:13 +00:00
doxygen.cfg Remove uIP; we haven't used it for quite some time now. 2007-01-10 02:52:58 +00:00

README.pixify

This file documents the driver changes needed to support use as part
of a PXE stack.

PROPER WAY
==========

1. The probe() routine.

There are three additional fields that need to be filled in the nic
structure: ioaddr, irqno and irq.

  ioaddr is the base I/O address and seems to be for information only;
  no use will be made of this value other than displaying it on the
  screen.

  irqno must be the IRQ number for the NIC.  For PCI NICs this can
  simply be copied from pci->irq.

  irq is a function pointer, like poll and transmit.  It must point to
  the driver's irq() function.

2. The poll() routine.

This must take an additional parameter: "int retrieve".  Calling
poll() with retrieve!=0 should function exactly as before.  Calling
poll() with retrieve==0 indicates that poll() should check for the
presence of a packet to read, but must *not* read the packet.  The
packet will be read by a subsequent call to poll() with retrieve!=0.

The easiest way to implement this is to insert the line
  if ( ! retrieve ) return 1;
between the "is there a packet ready" and the "fetch packet" parts of
the existing poll() routine.

Care must be taken that a call to poll() with retrieve==0 does not
clear the NIC's "packet ready" status indicator, otherwise the
subsequent call to poll() with retrieve!=0 will fail because it will
think that there is no packet to read.

poll() should also acknowledge and clear the NIC's "packet received"
interrupt.  It does not need to worry about enabling/disabling
interrupts; this is taken care of by calls to the driver's irq()
routine.

Etherboot will forcibly regenerate an interrupt if a packet remains
pending after all interrupts have been acknowledged.  You can
therefore get away with having poll() just acknolwedge and clear all
NIC interrupts, without particularly worrying about exactly when this
should be done.

3. The irq() routine.

This is a new routine, with prototype
  void DRIVER_irq ( struct nic *nic, irq_action_t action );
"action" takes one of three possible values: ENABLE, DISABLE or FORCE.
ENABLE and DISABLE mean to enable/disable the NIC's "packet received"
interrupt.  FORCE means that the NIC should be forced to generate a
fake "packet received" interrupt.

If you are unable to implement FORCE, your NIC will not work when
being driven via the UNDI interface under heavy network traffic
conditions.  Since Etherboot's UNDI driver (make bin/undi.zpxe) is the
only program known to use this interface, it probably doesn't really
matter.


QUICK AND DIRTY WAY
===================

It is possible to use the system timer interrupt (IRQ 0) rather than a
genuine NIC interrupt.  Since there is a constant stream of timer
interrupts, the net upshot is a whole load of spurious "NIC"
interrupts that have no effect other than to cause unnecessary PXE API
calls.  It's inefficient but it works.

To achieve this, simply set nic->irqno=0 in probe() and point nic->irq
to a dummy routine that does nothing.  Add the line
  if ( ! retrieve ) return 1;
at the beginning of poll(), to prevent the packet being read (and
discarded) when poll() is called with retrieve==0;


UNCONVERTED DRIVERS
===================

Drivers that have not yet been converted should continue to function
when not used as part of a PXE stack, although there will be a
harmless compile-time warning about assignment from an incompatible
pointer type in the probe() function, since the prototype for the
poll() function is missing the "int retrieve" parameter.