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