← Back to branch summary

~ubuntu-branches/ubuntu/gutsy/virtualbox-ose/gutsy

« back to all changes in this revision

Viewing changes to src/VBox/Devices/PC/Etherboot-src/README.pixify

  • Committer: Bazaar Package Importer
  • Author(s): Steve Kowalik
  • Date: 2007-09-08 16:44:58 UTC
  • Revision ID: james.westby@ubuntu.com-20070908164458-wao29470vqtr8ksy
Tags: upstream-1.5.0-dfsg2
Import upstream version 1.5.0-dfsg2

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/VBox/Devices/PC/Etherboot-src/README.pixify
 
1
This file documents the driver changes needed to support use as part
 
2
of a PXE stack.
 
3
 
 
4
PROPER WAY
 
5
==========
 
6
 
 
7
1. The probe() routine.
 
8
 
 
9
There are three additional fields that need to be filled in the nic
 
10
structure: ioaddr, irqno and irq.
 
11
 
 
12
  ioaddr is the base I/O address and seems to be for information only;
 
13
  no use will be made of this value other than displaying it on the
 
14
  screen.
 
15
 
 
16
  irqno must be the IRQ number for the NIC.  For PCI NICs this can
 
17
  simply be copied from pci->irq.
 
18
 
 
19
  irq is a function pointer, like poll and transmit.  It must point to
 
20
  the driver's irq() function.
 
21
 
 
22
2. The poll() routine.
 
23
 
 
24
This must take an additional parameter: "int retrieve".  Calling
 
25
poll() with retrieve!=0 should function exactly as before.  Calling
 
26
poll() with retrieve==0 indicates that poll() should check for the
 
27
presence of a packet to read, but must *not* read the packet.  The
 
28
packet will be read by a subsequent call to poll() with retrieve!=0.
 
29
 
 
30
The easiest way to implement this is to insert the line
 
31
  if ( ! retrieve ) return 1;
 
32
between the "is there a packet ready" and the "fetch packet" parts of
 
33
the existing poll() routine.
 
34
 
 
35
Care must be taken that a call to poll() with retrieve==0 does not
 
36
clear the NIC's "packet ready" status indicator, otherwise the
 
37
subsequent call to poll() with retrieve!=0 will fail because it will
 
38
think that there is no packet to read.
 
39
 
 
40
poll() should also acknowledge and clear the NIC's "packet received"
 
41
interrupt.  It does not need to worry about enabling/disabling
 
42
interrupts; this is taken care of by calls to the driver's irq()
 
43
routine.
 
44
 
 
45
Etherboot will forcibly regenerate an interrupt if a packet remains
 
46
pending after all interrupts have been acknowledged.  You can
 
47
therefore get away with having poll() just acknolwedge and clear all
 
48
NIC interrupts, without particularly worrying about exactly when this
 
49
should be done.
 
50
 
 
51
3. The irq() routine.
 
52
 
 
53
This is a new routine, with prototype
 
54
  void DRIVER_irq ( struct nic *nic, irq_action_t action );
 
55
"action" takes one of three possible values: ENABLE, DISABLE or FORCE.
 
56
ENABLE and DISABLE mean to enable/disable the NIC's "packet received"
 
57
interrupt.  FORCE means that the NIC should be forced to generate a
 
58
fake "packet received" interrupt.
 
59
 
 
60
If you are unable to implement FORCE, your NIC will not work when
 
61
being driven via the UNDI interface under heavy network traffic
 
62
conditions.  Since Etherboot's UNDI driver (make bin/undi.zpxe) is the
 
63
only program known to use this interface, it probably doesn't really
 
64
matter.
 
65
 
 
66
 
 
67
QUICK AND DIRTY WAY
 
68
===================
 
69
 
 
70
It is possible to use the system timer interrupt (IRQ 0) rather than a
 
71
genuine NIC interrupt.  Since there is a constant stream of timer
 
72
interrupts, the net upshot is a whole load of spurious "NIC"
 
73
interrupts that have no effect other than to cause unnecessary PXE API
 
74
calls.  It's inefficient but it works.
 
75
 
 
76
To achieve this, simply set nic->irqno=0 in probe() and point nic->irq
 
77
to a dummy routine that does nothing.  Add the line
 
78
  if ( ! retrieve ) return 1;
 
79
at the beginning of poll(), to prevent the packet being read (and
 
80
discarded) when poll() is called with retrieve==0;
 
81
 
 
82
 
 
83
UNCONVERTED DRIVERS
 
84
===================
 
85
 
 
86
Drivers that have not yet been converted should continue to function
 
87
when not used as part of a PXE stack, although there will be a
 
88
harmless compile-time warning about assignment from an incompatible
 
89
pointer type in the probe() function, since the prototype for the
 
90
poll() function is missing the "int retrieve" parameter.