libmpathpersist/mpath_persist.h

   1 /* version - 1.0 */
   2
   3 #ifndef MPATH_PERSIST_LIB_H
   4 #define MPATH_PERSIST_LIB_H
   5
   6
   7 #ifdef __cplusplus
   8 extern "C" {
   9 #endif
  10
  11 #include <inttypes.h>
  12
  13 #define MPATH_MAX_PARAM_LEN     8192
  14
  15 #define MPATH_MX_TIDS           32        /* Max number of transport ids"*/
  16 #define MPATH_MX_TID_LEN        256       /* Max length of transport id */
  17
  18 /* PRIN Service Actions */
  19 #define MPATH_PRIN_RKEY_SA      0x00       /* READ KEYS SA*/
  20 #define MPATH_PRIN_RRES_SA      0x01       /* READ RESERVATION  SA*/
  21 #define MPATH_PRIN_RCAP_SA      0x02       /* REPORT CAPABILITIES SA*/
  22 #define MPATH_PRIN_RFSTAT_SA    0x03       /* READ FULL STATUS SA*/
  23
  24 /* PROUT Service Actions */
  25 #define MPATH_PROUT_REG_SA      0x00        /* REGISTER SA */
  26 #define MPATH_PROUT_RES_SA      0x01        /* RESERVE SA*/
  27 #define MPATH_PROUT_REL_SA      0x02        /* RELEASE SA*/
  28 #define MPATH_PROUT_CLEAR_SA    0x03        /* CLEAR SA*/
  29 #define MPATH_PROUT_PREE_SA     0x04        /* PREEMPT SA*/
  30 #define MPATH_PROUT_PREE_AB_SA  0x05        /* PREEMPT AND ABORT SA*/
  31 #define MPATH_PROUT_REG_IGN_SA  0x06        /* REGISTER AND IGNORE EXISTING KEY SA*/
  32 #define MPATH_PROUT_REG_MOV_SA  0x07        /* REGISTER AND MOVE SA*/
  33
  34 #define MPATH_LU_SCOPE          0x00        /* LU_SCOPE */
  35
  36 /* Persistent reservations type */
  37 #define MPATH_PRTPE_WE          0x01        /* Write Exclusive */
  38 #define MPATH_PRTPE_EA          0x03        /* Exclusive Access*/
  39 #define MPATH_PRTPE_WE_RO       0x05        /* WriteExclusive Registrants Only */
  40 #define MPATH_PRTPE_EA_RO       0x06        /* Exclusive Access. Registrants Only*/
  41 #define MPATH_PRTPE_WE_AR       0x07        /* Write Exclusive. All Registrants*/
  42 #define MPATH_PRTPE_EA_AR       0x08        /* Exclusive Access. All Registrants */
  43
  44
  45 /* PR RETURN_STATUS */
  46 #define MPATH_PR_SKIP                   -1  /* skipping this path */
  47 #define MPATH_PR_SUCCESS                0
  48 #define MPATH_PR_SYNTAX_ERROR           1   /*  syntax error or invalid parameter */
  49                                             /* status for check condition */
  50 #define MPATH_PR_SENSE_NOT_READY        2   /*  [sk,asc,ascq: 0x2,*,*] */
  51 #define MPATH_PR_SENSE_MEDIUM_ERROR     3   /*  [sk,asc,ascq: 0x3,*,*] */
  52 #define MPATH_PR_SENSE_HARDWARE_ERROR   4   /*  [sk,asc,ascq: 0x4,*,*] */
  53 #define MPATH_PR_ILLEGAL_REQ            5   /*  [sk,asc,ascq: 0x5,*,*]*/
  54 #define MPATH_PR_SENSE_UNIT_ATTENTION   6   /*  [sk,asc,ascq: 0x6,*,*] */
  55 #define MPATH_PR_SENSE_INVALID_OP       7   /*  [sk,asc,ascq: 0x5,0x20,0x0]*/
  56 #define MPATH_PR_SENSE_ABORTED_COMMAND  8   /*  [sk,asc,ascq: 0xb,*,*] */
  57 #define MPATH_PR_NO_SENSE               9   /*  [sk,asc,ascq: 0x0,*,*] */
  58
  59 #define MPATH_PR_SENSE_MALFORMED        10  /* Response to SCSI command malformed */
  60 #define MPATH_PR_RESERV_CONFLICT        11  /* Reservation conflict on the device */
  61 #define MPATH_PR_FILE_ERROR             12  /* file (device node) problems(e.g. not found)*/
  62 #define MPATH_PR_DMMP_ERROR             13  /* DMMP related error.(e.g Error in getting dm info */
  63 #define MPATH_PR_THREAD_ERROR           14  /* pthreads error (e.g. unable to create new thread) */
  64 #define MPATH_PR_OTHER                  15  /*other error/warning has occurred(transport
  65                                               or driver error) */
  66
  67 /* PR MASK */
  68 #define MPATH_F_APTPL_MASK              0x01    /* APTPL MASK*/
  69 #define MPATH_F_ALL_TG_PT_MASK          0x04    /* ALL_TG_PT MASK*/
  70 #define MPATH_F_SPEC_I_PT_MASK          0x08    /* SPEC_I_PT MASK*/
  71 #define MPATH_PR_TYPE_MASK              0x0f    /* TYPE MASK*/
  72 #define MPATH_PR_SCOPE_MASK             0xf0    /* SCOPE MASK*/
  73
  74 /*Transport ID PROTOCOL IDENTIFIER values */
  75 #define MPATH_PROTOCOL_ID_FC            0x00
  76 #define MPATH_PROTOCOL_ID_ISCSI         0x05
  77 #define MPATH_PROTOCOL_ID_SAS           0x06
  78
  79
  80 /*Transport ID FORMAT CODE */
  81 #define MPATH_WWUI_DEVICE_NAME          0x00    /* World wide unique initiator device name */
  82 #define MPATH_WWUI_PORT_IDENTIFIER      0x40    /* World wide unique initiator port identifier  */
  83
  84
  85
  86 extern unsigned int mpath_mx_alloc_len;
  87
  88
  89
  90 struct prin_readdescr
  91 {
  92         uint32_t prgeneration;
  93         uint32_t additional_length;     /* The value should be either 0 or divisible by 8.
  94                                            0 indicates no registered reservation key. */
  95         uint8_t  key_list[MPATH_MAX_PARAM_LEN];
  96 };
  97
  98 struct prin_resvdescr
  99 {
 100         uint32_t prgeneration;
 101         uint32_t additional_length;     /* The value should be either 0 or 10h. 0 indicates
 102                                            there is no reservation held. 10h indicates the
 103                                            key[8] and scope_type have valid values */
 104         uint8_t  key[8];
 105         uint32_t _obsolete;
 106         uint8_t  _reserved;
 107         uint8_t  scope_type;            /* Use PR SCOPE AND TYPE MASK specified above */
 108         uint16_t _obsolete1;
 109 };
 110
 111 struct prin_capdescr
 112 {
 113         uint16_t length;
 114         uint8_t  flags[2];
 115         uint16_t pr_type_mask;
 116         uint16_t _reserved;
 117 };
 118
 119 struct transportid
 120 {
 121         uint8_t format_code;
 122         uint8_t protocol_id;
 123         union {
 124                 uint8_t n_port_name[8]; /* FC transport*/
 125                 uint8_t sas_address[8]; /* SAS transport */
 126                 uint8_t iscsi_name[256]; /* ISCSI  transport */
 127         };
 128 };
 129
 130 struct prin_fulldescr
 131 {
 132         uint8_t key[8];
 133         uint8_t flag;                   /* All_tg_pt and reservation holder */
 134         uint8_t scope_type;             /* Use PR SCOPE AND TYPE MASK specified above.
 135                                            Meaningful only for reservation holder */
 136         uint16_t rtpi;
 137         struct transportid trnptid;
 138 };
 139
 140 struct print_fulldescr_list
 141 {
 142         uint32_t prgeneration;
 143         uint32_t number_of_descriptor;
 144         uint8_t private_buffer[MPATH_MAX_PARAM_LEN]; /*Private buffer for list storage*/
 145         struct prin_fulldescr *descriptors[];
 146 };
 147
 148 struct prin_resp
 149 {
 150         union
 151         {
 152                 struct prin_readdescr prin_readkeys; /* for PRIN read keys SA*/
 153                 struct prin_resvdescr prin_readresv; /* for PRIN read reservation SA*/
 154                 struct prin_capdescr  prin_readcap;  /* for PRIN Report Capabilities SA*/
 155                 struct print_fulldescr_list prin_readfd;   /* for PRIN read full status SA*/
 156         }prin_descriptor;
 157 };
 158
 159 struct prout_param_descriptor {         /* PROUT parameter descriptor */
 160         uint8_t  key[8];
 161         uint8_t  sa_key[8];
 162         uint32_t _obsolete;
 163         uint8_t  sa_flags;
 164         uint8_t _reserved;
 165         uint16_t _obsolete1;
 166         uint8_t  private_buffer[MPATH_MAX_PARAM_LEN]; /*private buffer for list storage*/
 167         uint32_t num_transportid;       /* Number of Transport ID listed in trnptid_list[]*/
 168         struct transportid *trnptid_list[];
 169 };
 170
 171
 172 /* Function declarations */
 173
 174 /*
 175  * DESCRIPTION :
 176  *      Initialize device mapper multipath configuration. This function must be invoked first
 177  *      before performing reservation management functions.
 178  *      Either this function or mpath_lib_init() may be used.
 179  *      Use this function to work with libmultipath's internal "struct config"
 180  *      and "struct udev". The latter will be initialized automatically.
 181  *      Call libmpathpersist_exit() for cleanup.
 182  * RESTRICTIONS:
 183  *
 184  * RETURNS: 0->Success, 1->Failed.
 185  */
 186 extern int libmpathpersist_init (void);
 187
 188 /*
 189  * DESCRIPTION :
 190  *      Initialize device mapper multipath configuration. This function must be invoked first
 191  *      before performing reservation management functions.
 192  *      Either this function or libmpathpersist_init() may be used.
 193  *      Use this function to work with an application-specific "struct config"
 194  *      and "struct udev". The latter must be initialized by the application.
 195  *      Call mpath_lib_exit() for cleanup.
 196  * RESTRICTIONS:
 197  *
 198  * RETURNS: struct config ->Success, NULL->Failed.
 199  */
 200 extern struct config * mpath_lib_init (void);
 201
 202
 203 /*
 204  * DESCRIPTION :
 205  *      Release device mapper multipath configuration. This function must be invoked after
 206  *      performing reservation management functions.
 207  *      Use this after initialization with mpath_lib_init().
 208  * RESTRICTIONS:
 209  *
 210  * RETURNS: 0->Success, 1->Failed.
 211  */
 212 extern int mpath_lib_exit (struct config *conf);
 213
 214 /*
 215  * DESCRIPTION :
 216  *      Release device mapper multipath configuration a. This function must be invoked after
 217  *      performing reservation management functions.
 218  *      Use this after initialization with libmpathpersist_init().
 219  *      Calling libmpathpersist_init() after libmpathpersist_exit() will fail.
 220  * RESTRICTIONS:
 221  *
 222  * RETURNS: 0->Success, 1->Failed.
 223  */
 224 extern int libmpathpersist_exit (void);
 225
 226
 227 /*
 228  * DESCRIPTION :
 229  * This function sends PRIN command to the DM device and get the response.
 230  *
 231  * @fd: The file descriptor of a multipath device. Input argument.
 232  * @rq_servact: PRIN command service action. Input argument
 233  * @resp: The response from PRIN service action. The resp is a struct specified above. The caller should
 234  *      manage the memory allocation of this struct
 235  * @noisy: Turn on debugging trace: Input argument. 0->Disable, 1->Enable
 236  * @verbose: Set verbosity level. Input argument. value:[0-3]. 0->disabled, 3->Max verbose
 237  *
 238  * RESTRICTIONS:
 239  *
 240  * RETURNS: MPATH_PR_SUCCESS if PR command successful else returns any of the status specified
 241  *       above in RETURN_STATUS.
 242  *
 243  */
 244 extern int mpath_persistent_reserve_in (int fd, int rq_servact, struct prin_resp *resp,
 245                 int noisy, int verbose);
 246
 247 /*
 248  * DESCRIPTION :
 249  * This function is like mpath_persistent_reserve_in(), except that it
 250  * requires mpath_persistent_reserve_init_vecs() to be called before the
 251  * PR call to set up internal variables. These must later be cleanup up
 252  * by calling mpath_persistent_reserve_free_vecs().
 253  *
 254  * RESTRICTIONS:
 255  * This function uses static internal variables, and is not thread-safe.
 256  */
 257 extern int __mpath_persistent_reserve_in(int fd, int rq_servact,
 258                 struct prin_resp *resp, int noisy);
 259
 260 /*
 261  * DESCRIPTION :
 262  * This function sends PROUT command to the DM device and get the response.
 263  *
 264  * @fd: The file descriptor of a multipath device. Input argument.
 265  * @rq_servact: PROUT command service action. Input argument
 266  * @rq_scope: Persistent reservation scope. The value should be always LU_SCOPE (0h).
 267  * @rq_type: Persistent reservation type. The valid values of persistent reservation types are
 268  *      5h (Write exclusive - registrants only)
 269  *      6h (Exclusive access - registrants only)
 270  *      7h (Write exclusive - All registrants)
 271  *      8h (Exclusive access - All registrants).
 272  * @paramp: PROUT command parameter data. The paramp is a struct which describes PROUT
 273  *          parameter list. The caller should manage the memory allocation of this struct.
 274  * @noisy: Turn on debugging trace: Input argument.0->Disable, 1->Enable.
 275  * @verbose: Set verbosity level. Input argument. value:0 to 3. 0->disabled, 3->Max verbose
 276  *
 277  * RESTRICTIONS:
 278  *
 279  * RETURNS: MPATH_PR_SUCCESS if PR command successful else returns any of the status specified
 280  *       above in RETURN_STATUS.
 281  */
 282 extern int mpath_persistent_reserve_out ( int fd, int rq_servact, int rq_scope,
 283                 unsigned int rq_type, struct prout_param_descriptor *paramp, int noisy,
 284                 int verbose);
 285 /*
 286  * DESCRIPTION :
 287  * This function is like mpath_persistent_reserve_out(), except that it
 288  * requires mpath_persistent_reserve_init_vecs() to be called before the
 289  * PR call to set up internal variables. These must later be cleanup up
 290  * by calling mpath_persistent_reserve_free_vecs().
 291  *
 292  * RESTRICTIONS:
 293  * This function uses static internal variables, and is not thread-safe.
 294  */
 295 extern int __mpath_persistent_reserve_out( int fd, int rq_servact, int rq_scope,
 296                 unsigned int rq_type, struct prout_param_descriptor *paramp,
 297                 int noisy);
 298
 299 /*
 300  * DESCRIPTION :
 301  * This function allocates data structures and performs basic initialization and
 302  * device discovery for later calls of __mpath_persistent_reserve_in() or
 303  * __mpath_persistent_reserve_out().
 304  * @verbose: Set verbosity level. Input argument. value:0 to 3. 0->disabled, 3->Max verbose
 305  *
 306  * RESTRICTIONS:
 307  * This function uses static internal variables, and is not thread-safe.
 308  *
 309  * RETURNS: MPATH_PR_SUCCESS if successful else returns any of the status specified
 310  *       above in RETURN_STATUS.
 311  */
 312 int mpath_persistent_reserve_init_vecs(int verbose);
 313
 314 /*
 315  * DESCRIPTION :
 316  * This function frees data structures allocated by
 317  * mpath_persistent_reserve_init_vecs().
 318  *
 319  * RESTRICTIONS:
 320  * This function uses static internal variables, and is not thread-safe.
 321  */
 322 void mpath_persistent_reserve_free_vecs(void);
 323
 324
 325 #ifdef __cplusplus
 326 }
 327 #endif
 328
 329 #endif  /*MPATH_PERSIST_LIB_H*/