1MI 5380 driver
2==============
3
4(What?  Documentation?  Is this guy nuts? :-)
5
6Reselection
7-----------
8
9This driver will permit reselection on non-polled commands if
10sc->sc_flags & NCR5380_PERMIT_RESELECT is 1.  This permits enabling of
11reselection on a per-device basis.
12
13Disconnect/reselect is never permitted for polled commands.
14
15
16
17Interfacing the driver to MD code
18---------------------------------
19
20/sys/dev/ic/ncr5380.c is now stand-alone.  DON'T include it after your
21MD stuff!
22
23This allows for more than one 5380-based SCSI board in your system.  This is
24a real possibility for Amiga generic kernels.
25
26Your driver's softc structure must have an instance of struct ncr5380_softc
27as the first thing in the structure.  The MD code must initialize the
28following:
29
30sci_*: pointers to the 5380 registers.  All accesses are done through
31  these pointers.  This indirection allows the driver to work with
32  boards that map the 5380 on even addresses only or do other
33  weirdnesses.
34
35int (*sc_pio_out)(sc, phase, datalen, data)
36int (*sc_pio_in)(sc, phase, datalen, data)
37  These point to functions that do programmed I/O transfers to the bus and
38  from the bus, respectively.  Arguments:
39
40  sc            points to the softc
41  phase         the current SCSI bus phase
42  datalen       length of data to transfer
43  data          pointer to the buffer
44
45  Both functions must return the number of bytes successfully transferred.
46  A transfer operation must be aborted if the target requests a different
47  phase before the transfer completes.
48
49  If you have no special requirements, you can point these to
50  ncr5380_pio_out() and ncr5380_pio_in() respectively.  If your board
51  can do pseudo-DMA, then you might want to point these to functions
52  that use this feature.
53
54void (*sc_dma_alloc)(sc)
55  This function is called to set up a DMA transfer.  You must create and
56  return a "DMA handle" in sc->sc_dma_hand which identifies the DMA transfer.
57  The driver will pass you your DMA handle in sc->sc_dma_hand for future
58  operations.  The contents of the DMA handle are immaterial to the MI
59  code - the DMA handle is for your bookkeeping only.  Usually, you
60  create a structure and point to it here.
61
62  For example, you can record the mapped and unmapped addresses of the
63  buffer.  The Sun driver places an Am9516 UDC control block in the DMA
64  handle.
65
66  If for some reason you decide not to do DMA for the transfer, make
67  sc->sc_dma_hand NULL.  This might happen if the proposed transfer is
68  misaligned, or in the wrong type of memory, or...
69
70void (*sc_dma_start)(sc)
71  This function starts the transfer.
72
73void (*sc_dma_stop)(sc)
74  This function stops a transfer.  sc->sc_datalen and sc->sc_dataptr must
75  be updated to reflect the portion of the DMA already done.
76
77void (*sc_dma_eop)(sc)
78  This function is called when the 5380 signals EOP.  Either continue
79  the DMA or stop the DMA.
80
81void (*sc_dma_free)(sc)
82  This function frees the current DMA handle.
83
84u_char *sc_dataptr;
85int sc_datalen;
86  These variables form the active SCSI data pointer.  DMA code must start
87  DMA at the location given, and update the pointer/length in response to
88  DMA operations.
89
90u_short sc_dma_flags;
91  See ncr5380var.h
92
93
94
95Writing your DMA code
96---------------------
97
98DMA on a system with protected or virtual memory is always a problem.  Even
99though a disk transfer may be logically contiguous, the physical pages backing
100the transfer may not be.  There are two common solutions to this problem:
101
102DMA chains: the DMA is broken up into a list of contiguous segments.  The first
103segment is submitted to the DMA controller, and when it completes, the second
104segment is submitted, without stopping the 5380.  This is what the sc_dma_eop()
105function can do efficiently - if you have a DMA chain, it can quickly load up
106the next link in the chain.  The sc_dma_alloc() function builds the chain and
107sc_dma_free() releases any resources you used to build it.
108
109DVMA: Direct Virtual Memory Access.  In this scheme, DMA requests go through
110the MMU.  Although you can't page fault, you can program the MMU to remap
111things so the DMA controller sees contiguous data.  In this mode, sc_dma_alloc()
112is used to map the transfer into the address space reserved for DVMA and
113sc_dma_free() is used to unmap it.
114
115
116Interrupts
117----------
118
119ncr5380_sbc_intr() must be called when the 5380 interrupts the host.
120
121You must write an interrupt routine pretty much from scratch to check for
122things generated by MD hardware.
123
124
125Known problems
126--------------
127
128I'm getting this out now so that other ports can hack on it and integrate it.
129
130The sun3, DMA/Interrupt appears to be working now, but needs testing.
131
132Polled commands submitted while non-polled commands are in progress are not
133handled correctly.  This can happen if reselection is enabled and a new disk
134is mounted while an I/O is in progress on another disk.
135
136The problem is: what to do if you get reselected while doing the selection
137for the polled command?  Currently, the driver busy waits for the non-polled
138command to complete, but this is bogus.  I need to complete the non-polled
139command in polled mode, then do the polled command.
140
141
142Timeouts in the driver are EXTREMELY sensitive to the characteristics of the
143local implementation of delay().  The Sun3 version delays for a minimum of 5us.
144However, the driver must assume that delay(1) will delay only 1us.  For this
145reason, performance on the Sun3 sucks in some places.
146
147