git.ozlabs.org Git - ccan/blob - ccan/iscsi/iscsi.h

   1 /*
   2    Copyright (C) 2010 by Ronnie Sahlberg <ronniesahlberg@gmail.com>
   3
   4    This program is free software; you can redistribute it and/or modify
   5    it under the terms of the GNU General Public License as published by
   6    the Free Software Foundation; either version 3 of the License, or
   7    (at your option) any later version.
   8
   9    This program is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12    GNU General Public License for more details.
  13
  14    You should have received a copy of the GNU General Public License
  15    along with this program; if not, see <http://www.gnu.org/licenses/>.
  16 */
  17 #ifndef CCAN_ISCSI_H
  18 #define CCAN_ISCSI_H
  19
  20 struct iscsi_context;
  21 struct sockaddr;
  22
  23
  24 /*
  25  * Returns the file descriptor that libiscsi uses.
  26  */
  27 int iscsi_get_fd(struct iscsi_context *iscsi);
  28
  29 /*
  30  * Returns which events that we need to poll for for the iscsi file descriptor.
  31  */
  32 int iscsi_which_events(struct iscsi_context *iscsi);
  33
  34 /*
  35  * Called to process the events when events become available for the iscsi file descriptor.
  36  */
  37 int iscsi_service(struct iscsi_context *iscsi, int revents);
  38
  39
  40
  41 /*
  42  * Create a context for an ISCSI session.
  43  * Initiator_name is the iqn name we want to identify to the target as.
  44  *
  45  * Returns:
  46  *  0: success
  47  * <0: error
  48  */
  49 struct iscsi_context *iscsi_create_context(const char *initiator_name);
  50
  51 /*
  52  * Destroy an existing ISCSI context and tear down any existing connection.
  53  * Callbacks for any command in flight will be invoked with ISCSI_STATUS_CANCELLED.
  54  *
  55  * Returns:
  56  *  0: success
  57  * <0: error
  58  */
  59 int iscsi_destroy_context(struct iscsi_context *iscsi);
  60
  61 /*
  62  * Set an optional alias name to identify with when connecting to the target
  63  *
  64  * Returns:
  65  *  0: success
  66  * <0: error
  67  */
  68 int iscsi_set_alias(struct iscsi_context *iscsi, const char *alias);
  69
  70 /*
  71  * Set the iqn name of the taqget to login to.
  72  * The target name must be set before a normal-login can be initiated.
  73  * Only discovery-logins are possible without setting the target iqn name.
  74  *
  75  * Returns:
  76  *  0: success
  77  * <0: error
  78  */
  79 int iscsi_set_targetname(struct iscsi_context *iscsi, const char *targetname);
  80
  81
  82 /* Types of icsi sessions. Discovery sessions are used to query for what targets exist behind
  83  * the portal connected to. Normal sessions are used to log in and do I/O to the SCSI LUNs
  84  */
  85 enum iscsi_session_type {ISCSI_SESSION_DISCOVERY=1, ISCSI_SESSION_NORMAL=2};
  86
  87 /*
  88  * Set the session type for a scsi context.
  89  * Session type can only be set/changed while the iscsi context is not logged in to
  90  * a target.
  91  *
  92  * Returns:
  93  *  0: success
  94  * <0: error
  95  */
  96 int iscsi_set_session_type(struct iscsi_context *iscsi, enum iscsi_session_type session_type);
  97
  98
  99 /* ISCSI_STATUS_GOOD must map to SCSI_STATUS_GOOD
 100  * and ISCSI_STATUS_CHECK_CONDITION must map to SCSI_STATUS_CHECK_CONDITION
 101  */
 102 enum icsi_status { ISCSI_STATUS_GOOD            =0,
 103                    ISCSI_STATUS_CHECK_CONDITION =2,
 104                    ISCSI_STATUS_CANCELLED       =0x0f000000,
 105                    ISCSI_STATUS_ERROR           =0x0f000001 };
 106
 107
 108 /*
 109  * Generic callback for completion of iscsi_*_async().
 110  * command_data depends on status.
 111  */
 112 typedef void (*iscsi_command_cb)(struct iscsi_context *iscsi, int status, void *command_data, void *private_data);
 113
 114
 115 /*
 116  * Asynchronous call to connect a TCP connection to the target-host/port
 117  *
 118  * Returns:
 119  *  0 if the call was initiated and a connection will be attempted. Result of the connection will be reported
 120  *    through the callback function.
 121  * <0 if there was an error. The callback function will not be invoked.
 122  *
 123  * This command is unique in that the callback can be invoked twice.
 124  *
 125  * Callback parameters :
 126  * status can be either of :
 127  *    ISCSI_STATUS_GOOD     : Connection was successful. Command_data is NULL.
 128  *                            In this case the callback will be invoked a second time once the connection
 129  *                            is torn down.
 130  *
 131  *    ISCSI_STATUS_ERROR    : Either failed to establish the connection, or an already established connection
 132  *                            has failed with an error.
 133  *
 134  * The callback will NOT be invoked if the session is explicitely torn down through a call to
 135  * iscsi_disconnect() or iscsi_destroy_context().
 136  */
 137 int iscsi_connect_async(struct iscsi_context *iscsi, const char *target, iscsi_command_cb cb, void *private_data);
 138
 139 /*
 140  * Disconnect a connection to a target.
 141  * You can not disconnect while being logged in to a target.
 142  *
 143  * Returns:
 144  *  0 disconnect was successful
 145  * <0 error
 146  */
 147 int iscsi_disconnect(struct iscsi_context *iscsi);
 148
 149 /*
 150  * Asynchronous call to perform an ISCSI login.
 151  *
 152  * Returns:
 153  *  0 if the call was initiated and a login will be attempted. Result of the login will be reported
 154  *    through the callback function.
 155  * <0 if there was an error. The callback function will not be invoked.
 156  *
 157  * Callback parameters :
 158  * status can be either of :
 159  *    ISCSI_STATUS_GOOD     : login was successful. Command_data is always NULL.
 160  *    ISCSI_STATUS_CANCELLED: login was aborted. Command_data is NULL.
 161  *    ISCSI_STATUS_ERROR    : login failed. Command_data is NULL.
 162  */
 163 int iscsi_login_async(struct iscsi_context *iscsi, iscsi_command_cb cb, void *private_data);
 164
 165
 166 /*
 167  * Asynchronous call to perform an ISCSI logout.
 168  *
 169  * Returns:
 170  *  0 if the call was initiated and a logout will be attempted. Result of the logout will be reported
 171  *    through the callback function.
 172  * <0 if there was an error. The callback function will not be invoked.
 173  *
 174  * Callback parameters :
 175  * status can be either of :
 176  *    ISCSI_STATUS_GOOD     : logout was successful. Command_data is always NULL.
 177  *    ISCSI_STATUS_CANCELLED: logout was aborted. Command_data is NULL.
 178  */
 179 int iscsi_logout_async(struct iscsi_context *iscsi, iscsi_command_cb cb, void *private_data);
 180
 181
 182 /*
 183  * Asynchronous call to perform an ISCSI discovery.
 184  *
 185  * discoveries can only be done on connected and logged in discovery sessions.
 186  *
 187  * Returns:
 188  *  0 if the call was initiated and a discovery  will be attempted. Result of the logout will be reported
 189  *    through the callback function.
 190  * <0 if there was an error. The callback function will not be invoked.
 191  *
 192  * Callback parameters :
 193  * status can be either of :
 194  *    ISCSI_STATUS_GOOD     : Discovery was successful. Command_data is a pointer to a
 195  *                            iscsi_discovery_address list of structures.
 196  *                            This list of structures is only valid for the duration of the
 197  *                            callback and all data will be freed once the callback returns.
 198  *    ISCSI_STATUS_CANCELLED: Discovery was aborted. Command_data is NULL.
 199  */
 200 int iscsi_discovery_async(struct iscsi_context *iscsi, iscsi_command_cb cb, void *private_data);
 201
 202 struct iscsi_discovery_address {
 203        struct iscsi_discovery_address *next;
 204        const char *target_name;
 205        const char *target_address;
 206 };
 207
 208 /*
 209  * Asynchronous call to perform an ISCSI NOP-OUT call
 210  *
 211  * Returns:
 212  *  0 if the call was initiated and a nop-out will be attempted. Result will be reported
 213  *    through the callback function.
 214  * <0 if there was an error. The callback function will not be invoked.
 215  *
 216  * Callback parameters :
 217  * status can be either of :
 218  *    ISCSI_STATUS_GOOD     : NOP-OUT was successful and the server responded with a NOP-IN
 219  *                            callback_data is a iscsi_data structure containing the data returned from
 220  *                            the server.
 221  *    ISCSI_STATUS_CANCELLED: Discovery was aborted. Command_data is NULL.
 222  */
 223 int iscsi_nop_out_async(struct iscsi_context *iscsi, iscsi_command_cb cb, unsigned char *data, int len, void *private_data);
 224
 225
 226 /* These are the possible status values for the callbacks for scsi commands.
 227  * The content of command_data depends on the status type.
 228  *
 229  * status :
 230  *   ISCSI_STATUS_GOOD the scsi command completed successfullt on the target.
 231  *   If this scsi command returns DATA-IN, that data is stored in an scsi_task structure
 232  *   returned in the command_data parameter. This buffer will be automatically freed once the callback
 233  *   returns.
 234  *
 235  *   ISCSI_STATUS_CHECK_CONDITION the scsi command failed with a scsi sense.
 236  *   Command_data contains a struct scsi_task. When the callback returns, this buffer
 237  *   will automatically become freed.
 238  *
 239  *   ISCSI_STATUS_CANCELLED the scsi command was aborted. Command_data is NULL.
 240  *
 241  *   ISCSI_STATUS_ERROR the command failed. Command_data is NULL.
 242  */
 243
 244
 245
 246 struct iscsi_data {
 247        int size;
 248        unsigned char *data;
 249 };
 250
 251
 252 /*
 253  * Async commands for SCSI
 254  */
 255 int iscsi_reportluns_async(struct iscsi_context *iscsi, iscsi_command_cb cb, int report_type, int alloc_len, void *private_data);
 256 int iscsi_testunitready_async(struct iscsi_context *iscsi, int lun, iscsi_command_cb cb, void *private_data);
 257 int iscsi_inquiry_async(struct iscsi_context *iscsi, int lun, iscsi_command_cb cb, int evpd, int page_code, int maxsize, void *private_data);
 258 int iscsi_readcapacity10_async(struct iscsi_context *iscsi, int lun, iscsi_command_cb cb, int lba, int pmi, void *private_data);
 259 int iscsi_read10_async(struct iscsi_context *iscsi, int lun, iscsi_command_cb cb, int lba, int datalen, int blocksize, void *private_data);
 260 int iscsi_write10_async(struct iscsi_context *iscsi, int lun, iscsi_command_cb cb, unsigned char *data, int datalen, int lba, int fua, int fuanv, int blocksize, void *private_data);
 261 int iscsi_modesense6_async(struct iscsi_context *iscsi, int lun, iscsi_command_cb cb, int dbd, int pc, int page_code, int sub_page_code, unsigned char alloc_len, void *private_data);
 262
 263
 264 #endif /* CCAN_ISCSI_H */