1 /* 2 * Copyright 2004-2008, Haiku, Inc. All RightsReserved. 3 * Copyright 2002/03, Thomas Kurschel. All rights reserved. 4 * 5 * Distributed under the terms of the MIT License. 6 */ 7 #ifndef _SCSI_PERIPH_H 8 #define _SCSI_PERIPH_H 9 10 /*! Use this module to minimize work required to write a SCSI 11 peripheral driver. 12 13 It takes care of: 14 - error handling 15 - medium changes (including restarting the medium) 16 - detection of medium capacity 17 */ 18 19 20 #include <bus/SCSI.h> 21 #include <scsi_cmds.h> 22 #include <Drivers.h> 23 24 // cookie issued by module per device 25 typedef struct scsi_periph_device_info *scsi_periph_device; 26 // cookie issued by module per file handle 27 typedef struct scsi_periph_handle_info *scsi_periph_handle; 28 29 // "standardized" error code to simplify handling of scsi errors 30 typedef enum { 31 err_act_ok, // executed successfully 32 err_act_retry, // failed, retry 3 times 33 err_act_fail, // failed, don't retry 34 err_act_many_retries, // failed, retry multiple times (currently 10 times) 35 err_act_start, // devices requires a "start" command 36 err_act_invalid_req // request is invalid 37 } err_act; 38 39 // packed scsi command result 40 typedef struct err_res { 41 status_t error_code : 32; // Be error code 42 uint32 action : 8; // err_act code 43 } err_res; 44 45 #define MK_ERROR( aaction, code ) ({ \ 46 err_res res = {error_code: (code), action: (aaction) }; \ 47 res; \ 48 }) 49 50 // cookie issued by driver to identify itself 51 //typedef struct periph_info *periph_cookie; 52 // cookie issued by driver per device 53 typedef struct periph_device_info *periph_device_cookie; 54 // cookie issued by driver per file handle 55 typedef struct periph_handle_info *periph_handle_cookie; 56 57 typedef struct IOOperation io_operation; 58 59 // callbacks to be provided by peripheral driver 60 typedef struct scsi_periph_callbacks { 61 // *** block devices *** 62 // informs of new size of medium 63 // (set to NULL if not a block device) 64 void (*set_capacity)(periph_device_cookie cookie, uint64 capacity, 65 uint32 blockSize); 66 67 // *** removable devices 68 // called when media got changed (can be NULL if medium is not changable) 69 // (you don't need to call periph->media_changed, but it's doesn't if you do) 70 // ccb - request at your disposal 71 void (*media_changed)(periph_device_cookie cookie, scsi_ccb *request); 72 } scsi_periph_callbacks; 73 74 75 // functions provided by this module 76 typedef struct scsi_periph_interface { 77 module_info info; 78 79 // *** init/cleanup *** 80 // preferred_ccb_size - preferred command size; if zero, the shortest is used 81 status_t (*register_device)(periph_device_cookie cookie, 82 scsi_periph_callbacks *callbacks, scsi_device scsiDevice, 83 scsi_device_interface *scsi, device_node *node, bool removable, 84 int preferredCcbSize, scsi_periph_device *driver); 85 status_t (*unregister_device)(scsi_periph_device driver); 86 87 // *** basic command execution *** 88 // exec command, retrying on problems 89 status_t (*safe_exec)(scsi_periph_device periphCookie, scsi_ccb *request); 90 // exec simple command 91 status_t (*simple_exec)(scsi_periph_device device, void *cdb, 92 uint8 cdbLength, void *data, size_t dataLength, int ccbFlags); 93 94 // *** file handling *** 95 // to be called when a new file is opened 96 status_t (*handle_open)(scsi_periph_device device, 97 periph_handle_cookie periph_handle, scsi_periph_handle *_handle); 98 // to be called when a file is closed 99 status_t (*handle_close)(scsi_periph_handle handle); 100 // to be called when a file is freed 101 status_t (*handle_free)(scsi_periph_handle handle); 102 103 // *** default implementation for block devices *** 104 status_t (*read_write)(scsi_periph_device_info *device, scsi_ccb *request, 105 uint64 offset, size_t numBlocks, physical_entry* vecs, size_t vecCount, 106 bool isWrite, size_t* _bytesTransferred); 107 status_t (*io)(scsi_periph_device device, io_operation *operation, 108 size_t *_bytesTransferred); 109 110 // block ioctls 111 status_t (*ioctl)(scsi_periph_handle handle, int op, void *buffer, 112 size_t length); 113 // check medium capacity (calls set_capacity callback on success) 114 // request - ccb for this device; is used to talk to device 115 status_t (*check_capacity)(scsi_periph_device device, scsi_ccb *request); 116 117 // *** removable media *** 118 // to be called when a medium change is detected to block subsequent commands 119 void (*media_changed)(scsi_periph_device device); 120 // convert result of *request to err_res 121 err_res (*check_error)(scsi_periph_device device, scsi_ccb *request); 122 // send start or stop command to device 123 // withLoadEject = true - include loading/ejecting, 124 // false - only do allow/deny 125 err_res (*send_start_stop)(scsi_periph_device device, scsi_ccb *request, 126 bool start, bool withLoadEject); 127 // checks media status and waits for device to become ready 128 // returns: B_OK, B_DEV_MEDIA_CHANGE_REQUESTED, B_NO_MEMORY or 129 // pending error reported by handle_get_error 130 status_t (*get_media_status)(scsi_periph_handle handle); 131 // synchronizes (flush) the device cache 132 err_res(*synchronize_cache)(scsi_periph_device device, scsi_ccb *request); 133 134 // compose device name consisting of prefix and path/target/LUN 135 // (result must be freed by caller) 136 char *(*compose_device_name)(device_node *device_node, const char *prefix); 137 } scsi_periph_interface; 138 139 #define SCSI_PERIPH_MODULE_NAME "generic/scsi_periph/v1" 140 141 #endif /* _SCSI_PERIPH_H */ 142