include/scsi/scsi_host.h

   1 #ifndef _SCSI_SCSI_HOST_H
   2 #define _SCSI_SCSI_HOST_H
   3
   4 #include <linux/device.h>
   5 #include <linux/list.h>
   6 #include <linux/types.h>
   7
   8 struct block_device;
   9 struct module;
  10 struct scsi_cmnd;
  11 struct scsi_device;
  12 struct Scsi_Host;
  13 struct scsi_host_cmd_pool;
  14 struct scsi_transport_template;
  15
  16
  17 /*
  18  * The various choices mean:
  19  * NONE: Self evident.  Host adapter is not capable of scatter-gather.
  20  * ALL:  Means that the host adapter module can do scatter-gather,
  21  *       and that there is no limit to the size of the table to which
  22  *       we scatter/gather data.
  23  * Anything else:  Indicates the maximum number of chains that can be
  24  *       used in one scatter-gather request.
  25  */
  26 #define SG_NONE 0
  27 #define SG_ALL 0xff
  28
  29
  30 #define DISABLE_CLUSTERING 0
  31 #define ENABLE_CLUSTERING 1
  32
  33
  34 struct scsi_host_template {
  35         struct module *module;
  36         const char *name;
  37
  38         /*
  39          * Used to initialize old-style drivers.  For new-style drivers
  40          * just perform all work in your module initialization function.
  41          *
  42          * Status:  OBSOLETE
  43          */
  44         int (* detect)(struct scsi_host_template *);
  45
  46         /*
  47          * Used as unload callback for hosts with old-style drivers.
  48          *
  49          * Status: OBSOLETE
  50          */
  51         int (* release)(struct Scsi_Host *);
  52
  53         /*
  54          * The info function will return whatever useful information the
  55          * developer sees fit.  If not provided, then the name field will
  56          * be used instead.
  57          *
  58          * Status: OPTIONAL
  59          */
  60         const char *(* info)(struct Scsi_Host *);
  61
  62         /*
  63          * Ioctl interface
  64          *
  65          * Status: OPTIONAL
  66          */
  67         int (* ioctl)(struct scsi_device *dev, int cmd, void *arg);
  68
  69         /*
  70          * The queuecommand function is used to queue up a scsi
  71          * command block to the LLDD.  When the driver finished
  72          * processing the command the done callback is invoked.
  73          *
  74          * If queuecommand returns 0, then the HBA has accepted the
  75          * command.  The done() function must be called on the command
  76          * when the driver has finished with it. (you may call done on the
  77          * command before queuecommand returns, but in this case you
  78          * *must* return 0 from queuecommand).
  79          *
  80          * Queuecommand may also reject the command, in which case it may
  81          * not touch the command and must not call done() for it.
  82          *
  83          * There are two possible rejection returns:
  84          *
  85          *   SCSI_MLQUEUE_DEVICE_BUSY: Block this device temporarily, but
  86          *   allow commands to other devices serviced by this host.
  87          *
  88          *   SCSI_MLQUEUE_HOST_BUSY: Block all devices served by this
  89          *   host temporarily.
  90          *
  91          * For compatibility, any other non-zero return is treated the
  92          * same as SCSI_MLQUEUE_HOST_BUSY.
  93          *
  94          * NOTE: "temporarily" means either until the next command for#
  95          * this device/host completes, or a period of time determined by
  96          * I/O pressure in the system if there are no other outstanding
  97          * commands.
  98          *
  99          * STATUS: REQUIRED
 100          */
 101         int (* queuecommand)(struct scsi_cmnd *,
 102                              void (*done)(struct scsi_cmnd *));
 103
 104         /*
 105          * This is an error handling strategy routine.  You don't need to
 106          * define one of these if you don't want to - there is a default
 107          * routine that is present that should work in most cases.  For those
 108          * driver authors that have the inclination and ability to write their
 109          * own strategy routine, this is where it is specified.  Note - the
 110          * strategy routine is *ALWAYS* run in the context of the kernel eh
 111          * thread.  Thus you are guaranteed to *NOT* be in an interrupt
 112          * handler when you execute this, and you are also guaranteed to
 113          * *NOT* have any other commands being queued while you are in the
 114          * strategy routine. When you return from this function, operations
 115          * return to normal.
 116          *
 117          * See scsi_error.c scsi_unjam_host for additional comments about
 118          * what this function should and should not be attempting to do.
 119          *
 120          * Status: REQUIRED     (at least one of them)
 121          */
 122         int (* eh_strategy_handler)(struct Scsi_Host *);
 123         int (* eh_abort_handler)(struct scsi_cmnd *);
 124         int (* eh_device_reset_handler)(struct scsi_cmnd *);
 125         int (* eh_bus_reset_handler)(struct scsi_cmnd *);
 126         int (* eh_host_reset_handler)(struct scsi_cmnd *);
 127
 128         /*
 129          * Old EH handlers, no longer used. Make them warn the user of old
 130          * drivers by using a wrong type
 131          *
 132          * Status: MORE THAN OBSOLETE
 133          */
 134         int (* abort)(int);
 135         int (* reset)(int, int);
 136
 137         /*
 138          * Before the mid layer attempts to scan for a new device where none
 139          * currently exists, it will call this entry in your driver.  Should
 140          * your driver need to allocate any structs or perform any other init
 141          * items in order to send commands to a currently unused target/lun
 142          * combo, then this is where you can perform those allocations.  This
 143          * is specifically so that drivers won't have to perform any kind of
 144          * "is this a new device" checks in their queuecommand routine,
 145          * thereby making the hot path a bit quicker.
 146          *
 147          * Return values: 0 on success, non-0 on failure
 148          *
 149          * Deallocation:  If we didn't find any devices at this ID, you will
 150          * get an immediate call to slave_destroy().  If we find something
 151          * here then you will get a call to slave_configure(), then the
 152          * device will be used for however long it is kept around, then when
 153          * the device is removed from the system (or * possibly at reboot
 154          * time), you will then get a call to slave_detach().  This is
 155          * assuming you implement slave_configure and slave_destroy.
 156          * However, if you allocate memory and hang it off the device struct,
 157          * then you must implement the slave_destroy() routine at a minimum
 158          * in order to avoid leaking memory
 159          * each time a device is tore down.
 160          *
 161          * Status: OPTIONAL
 162          */
 163         int (* slave_alloc)(struct scsi_device *);
 164
 165         /*
 166          * Once the device has responded to an INQUIRY and we know the
 167          * device is online, we call into the low level driver with the
 168          * struct scsi_device *.  If the low level device driver implements
 169          * this function, it *must* perform the task of setting the queue
 170          * depth on the device.  All other tasks are optional and depend
 171          * on what the driver supports and various implementation details.
 172          *
 173          * Things currently recommended to be handled at this time include:
 174          *
 175          * 1.  Setting the device queue depth.  Proper setting of this is
 176          *     described in the comments for scsi_adjust_queue_depth.
 177          * 2.  Determining if the device supports the various synchronous
 178          *     negotiation protocols.  The device struct will already have
 179          *     responded to INQUIRY and the results of the standard items
 180          *     will have been shoved into the various device flag bits, eg.
 181          *     device->sdtr will be true if the device supports SDTR messages.
 182          * 3.  Allocating command structs that the device will need.
 183          * 4.  Setting the default timeout on this device (if needed).
 184          * 5.  Anything else the low level driver might want to do on a device
 185          *     specific setup basis...
 186          * 6.  Return 0 on success, non-0 on error.  The device will be marked
 187          *     as offline on error so that no access will occur.  If you return
 188          *     non-0, your slave_detach routine will never get called for this
 189          *     device, so don't leave any loose memory hanging around, clean
 190          *     up after yourself before returning non-0
 191          *
 192          * Status: OPTIONAL
 193          */
 194         int (* slave_configure)(struct scsi_device *);
 195
 196         /*
 197          * Immediately prior to deallocating the device and after all activity
 198          * has ceased the mid layer calls this point so that the low level
 199          * driver may completely detach itself from the scsi device and vice
 200          * versa.  The low level driver is responsible for freeing any memory
 201          * it allocated in the slave_alloc or slave_configure calls.
 202          *
 203          * Status: OPTIONAL
 204          */
 205         void (* slave_destroy)(struct scsi_device *);
 206
 207         /*
 208          * This function determines the bios parameters for a given
 209          * harddisk.  These tend to be numbers that are made up by
 210          * the host adapter.  Parameters:
 211          * size, device, list (heads, sectors, cylinders)
 212          *
 213          * Status: OPTIONAL
 214          */
 215         int (* bios_param)(struct scsi_device *, struct block_device *,
 216                         sector_t, int []);
 217
 218         /*
 219          * Can be used to export driver statistics and other infos to the
 220          * world outside the kernel ie. userspace and it also provides an
 221          * interface to feed the driver with information.
 222          *
 223          * Status: OBSOLETE
 224          */
 225         int (*proc_info)(struct Scsi_Host *, char *, char **, off_t, int, int);
 226
 227         /*
 228          * Name of proc directory
 229          */
 230         char *proc_name;
 231
 232         /*
 233          * Used to store the procfs directory if a driver implements the
 234          * proc_info method.
 235          */
 236         struct proc_dir_entry *proc_dir;
 237
 238         /*
 239          * This determines if we will use a non-interrupt driven
 240          * or an interrupt driven scheme,  It is set to the maximum number
 241          * of simultaneous commands a given host adapter will accept.
 242          */
 243         int can_queue;
 244
 245         /*
 246          * In many instances, especially where disconnect / reconnect are
 247          * supported, our host also has an ID on the SCSI bus.  If this is
 248          * the case, then it must be reserved.  Please set this_id to -1 if
 249          * your setup is in single initiator mode, and the host lacks an
 250          * ID.
 251          */
 252         int this_id;
 253
 254         /*
 255          * This determines the degree to which the host adapter is capable
 256          * of scatter-gather.
 257          */
 258         unsigned short sg_tablesize;
 259
 260         /*
 261          * If the host adapter has limitations beside segment count
 262          */
 263         unsigned short max_sectors;
 264
 265         /*
 266          * dma scatter gather segment boundary limit. a segment crossing this
 267          * boundary will be split in two.
 268          */
 269         unsigned long dma_boundary;
 270
 271         /*
 272          * This specifies "machine infinity" for host templates which don't
 273          * limit the transfer size.  Note this limit represents an absolute
 274          * maximum, and may be over the transfer limits allowed for
 275          * individual devices (e.g. 256 for SCSI-1)
 276          */
 277 #define SCSI_DEFAULT_MAX_SECTORS        1024
 278
 279         /*
 280          * True if this host adapter can make good use of linked commands.
 281          * This will allow more than one command to be queued to a given
 282          * unit on a given host.  Set this to the maximum number of command
 283          * blocks to be provided for each device.  Set this to 1 for one
 284          * command block per lun, 2 for two, etc.  Do not set this to 0.
 285          * You should make sure that the host adapter will do the right thing
 286          * before you try setting this above 1.
 287          */
 288         short cmd_per_lun;
 289
 290         /*
 291          * present contains counter indicating how many boards of this
 292          * type were found when we did the scan.
 293          */
 294         unsigned char present;
 295
 296         /*
 297          * true if this host adapter uses unchecked DMA onto an ISA bus.
 298          */
 299         unsigned unchecked_isa_dma:1;
 300
 301         /*
 302          * true if this host adapter can make good use of clustering.
 303          * I originally thought that if the tablesize was large that it
 304          * was a waste of CPU cycles to prepare a cluster list, but
 305          * it works out that the Buslogic is faster if you use a smaller
 306          * number of segments (i.e. use clustering).  I guess it is
 307          * inefficient.
 308          */
 309         unsigned use_clustering:1;
 310
 311         /*
 312          * True for emulated SCSI host adapters (e.g. ATAPI)
 313          */
 314         unsigned emulated:1;
 315
 316         /*
 317          * Countdown for host blocking with no commands outstanding
 318          */
 319         unsigned int max_host_blocked;
 320
 321         /*
 322          * Default value for the blocking.  If the queue is empty,
 323          * host_blocked counts down in the request_fn until it restarts
 324          * host operations as zero is reached.
 325          *
 326          * FIXME: This should probably be a value in the template
 327          */
 328 #define SCSI_DEFAULT_HOST_BLOCKED       7
 329
 330         /*
 331          * Pointer to the sysfs class properties for this host, NULL terminated.
 332          */
 333         struct class_device_attribute **shost_attrs;
 334
 335         /*
 336          * Pointer to the SCSI device properties for this host, NULL terminated.
 337          */
 338         struct device_attribute **sdev_attrs;
 339
 340         /*
 341          * List of hosts per template.
 342          *
 343          * This is only for use by scsi_module.c for legacy templates.
 344          * For these access to it is synchronized implicitly by
 345          * module_init/module_exit.
 346          */
 347         struct list_head legacy_hosts;
 348 };
 349
 350 /*
 351  * shost states
 352  */
 353 enum {
 354         SHOST_ADD,
 355         SHOST_DEL,
 356         SHOST_CANCEL,
 357         SHOST_RECOVERY,
 358 };
 359
 360 struct Scsi_Host {
 361         /*
 362          * __devices is protected by the host_lock, but you should
 363          * usually use scsi_device_lookup / shost_for_each_device
 364          * to access it and don't care about locking yourself.
 365          * In the rare case of beeing in irq context you can use
 366          * their __ prefixed variants with the lock held. NEVER
 367          * access this list directly from a driver.
 368          */
 369         struct list_head        __devices;
 370
 371         struct scsi_host_cmd_pool *cmd_pool;
 372         spinlock_t              free_list_lock;
 373         struct list_head        free_list; /* backup store of cmd structs */
 374         struct list_head        starved_list;
 375
 376         spinlock_t              default_lock;
 377         spinlock_t              *host_lock;
 378
 379         struct semaphore        scan_mutex;/* serialize scanning activity */
 380
 381         struct list_head        eh_cmd_q;
 382         struct task_struct    * ehandler;  /* Error recovery thread. */
 383         struct semaphore      * eh_wait;   /* The error recovery thread waits
 384                                               on this. */
 385         struct completion     * eh_notify; /* wait for eh to begin or end */
 386         struct semaphore      * eh_action; /* Wait for specific actions on the
 387                                           host. */
 388         unsigned int            eh_active:1; /* Indicates the eh thread is awake and active if
 389                                           this is true. */
 390         unsigned int            eh_kill:1; /* set when killing the eh thread */
 391         wait_queue_head_t       host_wait;
 392         struct scsi_host_template *hostt;
 393         struct scsi_transport_template *transportt;
 394         volatile unsigned short host_busy;   /* commands actually active on low-level */
 395         volatile unsigned short host_failed; /* commands that failed. */
 396
 397         unsigned short host_no;  /* Used for IOCTL_GET_IDLUN, /proc/scsi et al. */
 398         int resetting; /* if set, it means that last_reset is a valid value */
 399         unsigned long last_reset;
 400
 401         /*
 402          * These three parameters can be used to allow for wide scsi,
 403          * and for host adapters that support multiple busses
 404          * The first two should be set to 1 more than the actual max id
 405          * or lun (i.e. 8 for normal systems).
 406          */
 407         unsigned int max_id;
 408         unsigned int max_lun;
 409         unsigned int max_channel;
 410
 411         /*
 412          * This is a unique identifier that must be assigned so that we
 413          * have some way of identifying each detected host adapter properly
 414          * and uniquely.  For hosts that do not support more than one card
 415          * in the system at one time, this does not need to be set.  It is
 416          * initialized to 0 in scsi_register.
 417          */
 418         unsigned int unique_id;
 419
 420         /*
 421          * The maximum length of SCSI commands that this host can accept.
 422          * Probably 12 for most host adapters, but could be 16 for others.
 423          * For drivers that don't set this field, a value of 12 is
 424          * assumed.  I am leaving this as a number rather than a bit
 425          * because you never know what subsequent SCSI standards might do
 426          * (i.e. could there be a 20 byte or a 24-byte command a few years
 427          * down the road?).
 428          */
 429         unsigned char max_cmd_len;
 430
 431         int this_id;
 432         int can_queue;
 433         short cmd_per_lun;
 434         short unsigned int sg_tablesize;
 435         short unsigned int max_sectors;
 436         unsigned long dma_boundary;
 437
 438         unsigned unchecked_isa_dma:1;
 439         unsigned use_clustering:1;
 440         unsigned use_blk_tcq:1;
 441
 442         /*
 443          * Host has requested that no further requests come through for the
 444          * time being.
 445          */
 446         unsigned host_self_blocked:1;
 447
 448         /*
 449          * Host uses correct SCSI ordering not PC ordering. The bit is
 450          * set for the minority of drivers whose authors actually read
 451          * the spec ;)
 452          */
 453         unsigned reverse_ordering:1;
 454
 455         /*
 456          * Host has rejected a command because it was busy.
 457          */
 458         unsigned int host_blocked;
 459
 460         /*
 461          * Value host_blocked counts down from
 462          */
 463         unsigned int max_host_blocked;
 464
 465         /* legacy crap */
 466         unsigned long base;
 467         unsigned long io_port;
 468         unsigned char n_io_port;
 469         unsigned char dma_channel;
 470         unsigned int  irq;
 471
 472
 473         unsigned long shost_state;
 474
 475         /* ldm bits */
 476         struct device           shost_gendev;
 477         struct class_device     shost_classdev;
 478
 479         /*
 480          * List of hosts per template.
 481          *
 482          * This is only for use by scsi_module.c for legacy templates.
 483          * For these access to it is synchronized implicitly by
 484          * module_init/module_exit.
 485          */
 486         struct list_head sht_legacy_list;
 487
 488         /*
 489          * We should ensure that this is aligned, both for better performance
 490          * and also because some compilers (m68k) don't automatically force
 491          * alignment to a long boundary.
 492          */
 493         unsigned long hostdata[0]  /* Used for storage of host specific stuff */
 494                 __attribute__ ((aligned (sizeof(unsigned long))));
 495 };
 496 #define         dev_to_shost(d)         \
 497         container_of(d, struct Scsi_Host, shost_gendev)
 498 #define         class_to_shost(d)       \
 499         container_of(d, struct Scsi_Host, shost_classdev)
 500
 501 extern struct Scsi_Host *scsi_host_alloc(struct scsi_host_template *, int);
 502 extern int scsi_add_host(struct Scsi_Host *, struct device *);
 503 extern void scsi_scan_host(struct Scsi_Host *);
 504 extern void scsi_remove_host(struct Scsi_Host *);
 505 extern struct Scsi_Host *scsi_host_get(struct Scsi_Host *);
 506 extern void scsi_host_put(struct Scsi_Host *t);
 507 extern struct Scsi_Host *scsi_host_lookup(unsigned short);
 508
 509 extern u64 scsi_calculate_bounce_limit(struct Scsi_Host *);
 510
 511 static inline void scsi_assign_lock(struct Scsi_Host *shost, spinlock_t *lock)
 512 {
 513         shost->host_lock = lock;
 514 }
 515
 516 static inline void scsi_set_device(struct Scsi_Host *shost,
 517                                    struct device *dev)
 518 {
 519         shost->shost_gendev.parent = dev;
 520 }
 521
 522 static inline struct device *scsi_get_device(struct Scsi_Host *shost)
 523 {
 524         return shost->shost_gendev.parent;
 525 }
 526
 527 extern void scsi_unblock_requests(struct Scsi_Host *);
 528 extern void scsi_block_requests(struct Scsi_Host *);
 529
 530 /*
 531  * These two functions are used to allocate and free a pseudo device
 532  * which will connect to the host adapter itself rather than any
 533  * physical device.  You must deallocate when you are done with the
 534  * thing.  This physical pseudo-device isn't real and won't be available
 535  * from any high-level drivers.
 536  */
 537 extern void scsi_free_host_dev(struct scsi_device *);
 538 extern struct scsi_device *scsi_get_host_dev(struct Scsi_Host *);
 539
 540 /* legacy interfaces */
 541 extern struct Scsi_Host *scsi_register(struct scsi_host_template *, int);
 542 extern void scsi_unregister(struct Scsi_Host *);
 543
 544 #endif /* _SCSI_SCSI_HOST_H */