usb/storage/usb.h

0001 /* SPDX-License-Identifier: GPL-2.0+ */
0002 /*
0003  * Driver for USB Mass Storage compliant devices
0004  * Main Header File
0005  *
0006  * Current development and maintenance by:
0007  *   (c) 1999-2002 Matthew Dharm (mdharm-usb@one-eyed-alien.net)
0008  *
0009  * Initial work by:
0010  *   (c) 1999 Michael Gee (michael@linuxspecific.com)
0011  *
0012  * This driver is based on the 'USB Mass Storage Class' document. This
0013  * describes in detail the protocol used to communicate with such
0014  * devices.  Clearly, the designers had SCSI and ATAPI commands in
0015  * mind when they created this document.  The commands are all very
0016  * similar to commands in the SCSI-II and ATAPI specifications.
0017  *
0018  * It is important to note that in a number of cases this class
0019  * exhibits class-specific exemptions from the USB specification.
0020  * Notably the usage of NAK, STALL and ACK differs from the norm, in
0021  * that they are used to communicate wait, failed and OK on commands.
0022  *
0023  * Also, for certain devices, the interrupt endpoint is used to convey
0024  * status of a command.
0025  */
0026
0027 #ifndef _USB_H_
0028 #define _USB_H_
0029
0030 #include <linux/usb.h>
0031 #include <linux/usb_usual.h>
0032 #include <linux/blkdev.h>
0033 #include <linux/completion.h>
0034 #include <linux/mutex.h>
0035 #include <linux/workqueue.h>
0036 #include <scsi/scsi_host.h>
0037
0038 struct us_data;
0039 struct scsi_cmnd;
0040
0041 /*
0042  * Unusual device list definitions
0043  */
0044
0045 struct us_unusual_dev {
0046     const char* vendorName;
0047     const char* productName;
0048     __u8  useProtocol;
0049     __u8  useTransport;
0050     int (*initFunction)(struct us_data *);
0051 };
0052
0053
0054 /* Dynamic bitflag definitions (us->dflags): used in set_bit() etc. */
0055 #define US_FLIDX_URB_ACTIVE 0   /* current_urb is in use    */
0056 #define US_FLIDX_SG_ACTIVE  1   /* current_sg is in use     */
0057 #define US_FLIDX_ABORTING   2   /* abort is in progress     */
0058 #define US_FLIDX_DISCONNECTING  3   /* disconnect in progress   */
0059 #define US_FLIDX_RESETTING  4   /* device reset in progress */
0060 #define US_FLIDX_TIMED_OUT  5   /* SCSI midlayer timed out  */
0061 #define US_FLIDX_SCAN_PENDING   6   /* scanning not yet done    */
0062 #define US_FLIDX_REDO_READ10    7   /* redo READ(10) command    */
0063 #define US_FLIDX_READ10_WORKED  8   /* previous READ(10) succeeded */
0064
0065 #define USB_STOR_STRING_LEN 32
0066
0067 /*
0068  * We provide a DMA-mapped I/O buffer for use with small USB transfers.
0069  * It turns out that CB[I] needs a 12-byte buffer and Bulk-only needs a
0070  * 31-byte buffer.  But Freecom needs a 64-byte buffer, so that's the
0071  * size we'll allocate.
0072  */
0073
0074 #define US_IOBUF_SIZE       64  /* Size of the DMA-mapped I/O buffer */
0075 #define US_SENSE_SIZE       18  /* Size of the autosense data buffer */
0076
0077 typedef int (*trans_cmnd)(struct scsi_cmnd *, struct us_data*);
0078 typedef int (*trans_reset)(struct us_data*);
0079 typedef void (*proto_cmnd)(struct scsi_cmnd*, struct us_data*);
0080 typedef void (*extra_data_destructor)(void *);  /* extra data destructor */
0081 typedef void (*pm_hook)(struct us_data *, int); /* power management hook */
0082
0083 #define US_SUSPEND  0
0084 #define US_RESUME   1
0085
0086 /* we allocate one of these for every device that we remember */
0087 struct us_data {
0088     /*
0089      * The device we're working with
0090      * It's important to note:
0091      *    (o) you must hold dev_mutex to change pusb_dev
0092      */
0093     struct mutex        dev_mutex;   /* protect pusb_dev */
0094     struct usb_device   *pusb_dev;   /* this usb_device */
0095     struct usb_interface    *pusb_intf;  /* this interface */
0096     const struct us_unusual_dev   *unusual_dev;
0097                         /* device-filter entry     */
0098     unsigned long       fflags;      /* fixed flags from filter */
0099     unsigned long       dflags;      /* dynamic atomic bitflags */
0100     unsigned int        send_bulk_pipe;  /* cached pipe values */
0101     unsigned int        recv_bulk_pipe;
0102     unsigned int        send_ctrl_pipe;
0103     unsigned int        recv_ctrl_pipe;
0104     unsigned int        recv_intr_pipe;
0105
0106     /* information about the device */
0107     char            *transport_name;
0108     char            *protocol_name;
0109     __le32          bcs_signature;
0110     u8          subclass;
0111     u8          protocol;
0112     u8          max_lun;
0113
0114     u8          ifnum;       /* interface number   */
0115     u8          ep_bInterval;    /* interrupt interval */
0116
0117     /* function pointers for this device */
0118     trans_cmnd      transport;   /* transport function     */
0119     trans_reset     transport_reset; /* transport device reset */
0120     proto_cmnd      proto_handler;   /* protocol handler       */
0121
0122     /* SCSI interfaces */
0123     struct scsi_cmnd    *srb;        /* current srb     */
0124     unsigned int        tag;         /* current dCBWTag */
0125     char            scsi_name[32];   /* scsi_host name  */
0126
0127     /* control and bulk communications data */
0128     struct urb      *current_urb;    /* USB requests     */
0129     struct usb_ctrlrequest  *cr;         /* control requests     */
0130     struct usb_sg_request   current_sg;  /* scatter-gather req.  */
0131     unsigned char       *iobuf;      /* I/O buffer       */
0132     dma_addr_t      iobuf_dma;   /* buffer DMA addresses */
0133     struct task_struct  *ctl_thread;     /* the control thread   */
0134
0135     /* mutual exclusion and synchronization structures */
0136     struct completion   cmnd_ready;  /* to sleep thread on      */
0137     struct completion   notify;      /* thread begin/end        */
0138     wait_queue_head_t   delay_wait;  /* wait during reset       */
0139     struct delayed_work scan_dwork;  /* for async scanning      */
0140
0141     /* subdriver information */
0142     void            *extra;      /* Any extra data          */
0143     extra_data_destructor   extra_destructor;/* extra data destructor   */
0144 #ifdef CONFIG_PM
0145     pm_hook         suspend_resume_hook;
0146 #endif
0147
0148     /* hacks for READ CAPACITY bug handling */
0149     int         use_last_sector_hacks;
0150     int         last_sector_retries;
0151 };
0152
0153 /* Convert between us_data and the corresponding Scsi_Host */
0154 static inline struct Scsi_Host *us_to_host(struct us_data *us) {
0155     return container_of((void *) us, struct Scsi_Host, hostdata);
0156 }
0157 static inline struct us_data *host_to_us(struct Scsi_Host *host) {
0158     return (struct us_data *) host->hostdata;
0159 }
0160
0161 /* Function to fill an inquiry response. See usb.c for details */
0162 extern void fill_inquiry_response(struct us_data *us,
0163     unsigned char *data, unsigned int data_len);
0164
0165 /*
0166  * The scsi_lock() and scsi_unlock() macros protect the sm_state and the
0167  * single queue element srb for write access
0168  */
0169 #define scsi_unlock(host)   spin_unlock_irq(host->host_lock)
0170 #define scsi_lock(host)     spin_lock_irq(host->host_lock)
0171
0172 /* General routines provided by the usb-storage standard core */
0173 #ifdef CONFIG_PM
0174 extern int usb_stor_suspend(struct usb_interface *iface, pm_message_t message);
0175 extern int usb_stor_resume(struct usb_interface *iface);
0176 extern int usb_stor_reset_resume(struct usb_interface *iface);
0177 #else
0178 #define usb_stor_suspend    NULL
0179 #define usb_stor_resume     NULL
0180 #define usb_stor_reset_resume   NULL
0181 #endif
0182
0183 extern int usb_stor_pre_reset(struct usb_interface *iface);
0184 extern int usb_stor_post_reset(struct usb_interface *iface);
0185
0186 extern int usb_stor_probe1(struct us_data **pus,
0187         struct usb_interface *intf,
0188         const struct usb_device_id *id,
0189         const struct us_unusual_dev *unusual_dev,
0190         struct scsi_host_template *sht);
0191 extern int usb_stor_probe2(struct us_data *us);
0192 extern void usb_stor_disconnect(struct usb_interface *intf);
0193
0194 extern void usb_stor_adjust_quirks(struct usb_device *dev,
0195         unsigned long *fflags);
0196
0197 #define module_usb_stor_driver(__driver, __sht, __name) \
0198 static int __init __driver##_init(void) \
0199 { \
0200     usb_stor_host_template_init(&(__sht), __name, THIS_MODULE); \
0201     return usb_register(&(__driver)); \
0202 } \
0203 module_init(__driver##_init); \
0204 static void __exit __driver##_exit(void) \
0205 { \
0206     usb_deregister(&(__driver)); \
0207 } \
0208 module_exit(__driver##_exit)
0209
0210 #endif