path: root/scsi/adapters/README

This directory contains various examples of HBA support code,
among them:

 Chip/Board	File		Machine tested		By

 NCR 53C94	scsi_53C94	DecStation 5000		af@cmu
 DEC 7061	scsi_7061	DecStation 3100/2100	af@cmu
 NCR 5380	scsi_5380	VaxStation 3100		af@cmu
 Fujitsu 89352	scsi_89352	Omron Luna88k		danner@cmu
 Adaptec 1542B	scsi_aha15	AT/PC			af@cmu

It should be trivial to modify them for some other machine that uses
the same SCSI chips, hopefully by properly conditionalizing and macroizing
the existing code.

There are various rules and assumptions to keep in mind when designing/coding
the support code for a new HBA, here is a list.  Pls extend this with
anything you find is not openly stated here and made your life miserable
during the port, and send it back to CMU.


AUTOCONF

We assume the structures and procedures defined in chips/busses.*,
e.g. someone will call configure_bus_master to get to our foo_probe()
routine.  This should make up its mind on how many targets it sees
[see later for dynamic reconfig], allocate a descriptor for each
one and leave the driver ready to accept commands (via foo_go()).

	On raw chips you should use a test_unit_ready command,
	selecting without ATN, and timing out on non-existant
	devices. Use LUN 0.
	On boards, there probably is a command to let the board do
	it (see Adaptec), if not do as above.

The typical autoconf descriptor might look like

	caddr_t	foo_std[NFOO] = { 0 };
	struct	bus_device *foo_dinfo[NFOO*8];
	struct	bus_ctlr *foo_minfo[NFOO];
	struct	bus_driver foo_driver = 
	        { foo_probe, scsi_slave, scsi_attach, foo_go, foo_std, "rz",
		  foo_dinfo,  "foo", foo_minfo, BUS_INTR_B4_PROBE};

which indicates that foo_probe() and foo_go() are our interface functions,
and we use the generic scsi_slave() and scsi_attach() for the rest.
Their definition is

	foo_probe(reg, ui)
		vm_offset_t	reg;
		struct bus_ctlr	*ui;

[the "reg" argument might actually be something else on architectures that
 do not use memory mapped I/O]

	aha_go(tgt, cmd_count, in_count, cmd_only)
		target_info_t		*tgt;
		boolean_t		cmd_only;

The foo_go() routine is fairly common across chips, look at any example to
see how to structure it.  Basically, the arguments tell us how much data
to expect in either direction, and whether (cmd_only) we think we should
be selecting with ATN (cmd_only==FALSE) or not.  The only gotcha is cmd_count
actually includes the size of any parameters.

The "go" field of the scsi_softc structure describing your HBA should be
set to your foo_go() routine, by the foo_probe() routine.

DATA DEPENDENCIES

The upper layer assumes that tgt->cmd_ptr is a pointer to good memory
[e.g. no funny padding] where it places the scsi command control blocks
AND small (less than 255 bytes) parameters.  It also expects small results
in there (things like read_capacity, for instance).  I think I cleaned
up all the places that used to assume tgt->cmd_ptr was aligned, but do not
be surprised if I missed one.

It does NOT use the dma_ptr, or any of the transient_state fields.

WATCHDOG

There is an optional MI watchdog facility, which can be used quite simply by
filling in the "watchdog" field of the scsi_softc structure describing
your HBA.  To disable it, leave the field zero (or, dynamically, zero the
timeout value).  You can use a watchdog of your own if you like, or more
likely set this field to point to the MI scsi_watchdog().
This requires that your foo_softc descriptor starts off with a watchdog_t
structure, with the "reset" field pointing to a function that will
reset the SCSI bus should the watchdog expire.

When a new SCSI command is initiated you should 
	if (foo->wd.nactive++ == 0)
		foo->wd.watchdog_state = SCSI_WD_ACTIVE;
to activate the watchdog, on each interrupt [or other signal that all
is proceeding well for the command and it is making progress] you should
	if (foo->wd.nactive)
		foo->wd.watchdog_state = SCSI_WD_ACTIVE;
bump down the watchdog 'trigger level', and when the command terminates
	if (aha->wd.nactive-- == 1)
		aha->wd.watchdog_state = SCSI_WD_INACTIVE;

When you detect a SCSI bus reset (possibly we initiated it) you should
	aha->wd.nactive = 0;
and after cleaning up properly invoke
	scsi_bus_was_reset(sc)
		scsi_softc_t	sc;

The functiona that is invoked on watchdog expiry is
	foo_reset_scsibus(foo)
		register foo_softc_t	foo;

Note that this can be used for dumb chips that do not support select timeouts
in hardware [see the 5380 or 7061 code], but its primary use is to detect
instances where a target is holding on the SCSI bus way too long.

The one drawback of resetting the bus is that some devices (like tapes)
lose status in case of a reset, and the MI code does not (yet?) try to
keep enough information around to be able to recover.  If you want to
add something very useful you might change the rz_tape.c code to do just
that, e.g. on SCSI_RET_ABORTs wait a while for the tape to do whatever,
then rewind, and seek forward where the tape should have been positioned at
the beginning of the command that failed, then reissue the command.
None of the examples so far tries to be 'smart' like making an attempt
to get the bus unstuck without resetting it, send us ideas if you have
some.


DYNAMIC RECONFIG

Your code should be ready to add/remove targets on the fly.  To do so,
notify the upper layer that a target went offline returning
SCSI_RET_DEVICE_DOWN when e.g. the select timed out, and clear out
the tgt->flags field.
To find new devices, define a function

	boolean_t
	foo_probe_target(tgt, ior)
		target_info_t		*tgt;
		io_req_t		ior;

and install it in the "probe" field of the scsi_softc_t structure describing
the HBA to the upper layer.  This function should finalize all HBA-specific
info in the target_info structure, then do a scsi_inquiry and check the
return code.  If this is not SCSI_RET_DEVICE_DOWN the target should be
marked TGT_ALIVE.


COMMAND TERMINATION

Generally, command termination should be reported to the upper layers
by setting the tgt->done field to the proper value [it should remain
SCSI_RET_IN_PROGRESS while the command is executing] and invoking the
target's completion routine, like:
	if (tgt->ior) {
		LOG(0xA,"ops->restart");
		(*tgt->dev_ops->restart)( tgt, TRUE);
	}
Note that early on some commands will actually wait for completion
by spinning on the tgt->done value, because autoconf happens when
threads and the scheduler are not working.

Return SCSI_RET_RETRY if the target was busy, the command will be retried
as appropriate.

Check the completion routines [in rz_disk.c and rz_tape.c for instance]
if you are not sure what to return in a troubled case.

HBA CHIPS GOTCHAS

All of the examples so far use the idea of 'scripts': the interrupt routine
matches the chip state with what is expected and if this is ok (it is
in the common important case) it just calls a prepackaged function.
We have found this to be _extremely_ simpler than using a state machine
of various ridiculous and erroneous sorts, and much more handy for debugging
also. Not to mention the saving on code.
Nonetheless, there really are no restrictions on how to structure the HBA
code, if you prefer state machines go ahead and use them!

Scheduling of the bus among competing targets is one of the major missing
pieces for simple HBAs.  A winning strategy used so far is as follows.
Allocate a queue_head_t of waiting_targets in your foo_softc, and two
target_info_t pointers next_target and active_target. A three-valued
state field is also needed.  If you enter the foo_go() routine
and find the state&BUSY simply enqueue_tail() your tgt on the waiting_targets
queue.  Otherwise mark the bus BUSY, set next_target to tgt, and proceed
to a selection attempt.
Note that the attempt might fail and a reselection win over it, therefore
the attempt_selection() routine should just retrieve the next_target
and install it in active_target, start the selection and let the interrupt
routine take care of the rest [see scsi_5380 for a different setup].
If a reselection wins we should note that we had a COLLISION in the state
field, install the reconecting target and proceed to completion.
When either a command is complete or a target disconnects you should invoke
a foo_release_bus() routine, which might look like:

boolean_t
foo_release_bus(foo)
	register foo_softc_t	foo;
{
	boolean_t	ret = TRUE;

	LOG(9,"release");
	if (foo->state & FOO_STATE_COLLISION) {

		LOG(0xB,"collided");
		foo->state &= ~FOO_STATE_COLLISION;
		foo_attempt_selection(foo);

	} else if (queue_empty(&foo->waiting_targets)) {

		foo->state &= ~FOO_STATE_BUSY;
		foo->active_target = 0;
		foo->script = 0;
		ret = FALSE;

	} else {

		LOG(0xC,"dequeue");
		foo->next_target = (target_info_t *)
				dequeue_head(&foo->waiting_targets);
		foo_attempt_selection(foo);
	}
	return ret;
}

which indicates whether the bus has been handed off to a new target or not.
This provides the desired FIFO scheduling of the bus and gives maximum
parallelism when targets are allowed to (and infact do) disconnect.

An area where there are problems most times is how to minimize the
interaction of selections and reselections in, e.g. foo_attempt_selection().
This is very much chip specific, but sneaking on the SCSI bus should
be a viable alternative in most cases.  Check in the specs what happens
if you send a command while there is already a reselection pending:
a well behaved chip would ignore the command and not screwup its status.
[Keep in mind that even if _now_ there is no reselection indication
 on the next cycle there might be and you won't see it!]

RANDOM GOTCHAS

A number of workstations do not provide real DMA support [do not ask me why]
but rather a special 'buffer' more or less wide where you have to copy
data to and from.  This has been handled, see esp the 52C94 code which has
even the extreme optimization of issuing the send command even before
the data has been copied into the buffer!   We have handled even machines
where no DMA at all was provided.

Speaking of DMA.. many of these chips 'prefetch' data, or have a FIFO
on board (they have to if they do synch xfers), and when the target
disconnects it is always a pain to find out how many bytes exactly did we
xfer. Be advised that this hurdle exists, and that the best way to
debug your code here is to use a tape.  A safe way is to initially
disable disconnects [so that you can get the system up from disk]
and enable them only on the tape unit that you are using for testing.
Later on enable disks but make sure you have some way to recover from
a zapped disk !

MOVING TO USER SPACE

All examples have hooks for user-space versions of the driver, the
ones for 54C94 and 7061 actually do work.  Look in mapped_scsi.c
for how this is done, it is fairly simple as far as the kernel is 
concerned.  To keep the option of mapping to user space open you 
should structure your interrupt routine such that it does all the
state gathering and clearing of the interrupt right away.  This
scheme gives you some assurance that your code will keep on working
when the interrupt processing is actually delayed and you recover
the interrupt state from the saved structure in the mapped area.


IMPROVEMENTS

There are a variety of things to be done still, for instance:

- rewrite scsi_slave() and scsi_attach() to be fully SCSI-II compliant.
  There are only comments right now as to how that should be done.

- add enough machinery to the tape code to be able to recover from
  bus resets.  Do so in such a way that other devices might use the ideas.

- add more devices, like printers scanners modems etc that are currently
  missing

- add a 'generic' set_status flavor which simply executes a scsi command
  passed in from user.  This seems the way many vendors and other people
  have strutured their drivers, it would make it possible to have a common
  user-level program to do special maintainance work like, for instance,
  reformatting of disks.