a5e7868b45a93805a135a5ccf3bbb86973a09cfa
[multipath-tools/.git] / 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 lenght 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_SUCCESS                0
47 #define MPATH_PR_SYNTAX_ERROR           1   /*  syntax error or invalid parameter */
48                                             /* status for check condition */
49 #define MPATH_PR_SENSE_NOT_READY        2   /*  [sk,asc,ascq: 0x2,*,*] */
50 #define MPATH_PR_SENSE_MEDIUM_ERROR     3   /*  [sk,asc,ascq: 0x3,*,*] */
51 #define MPATH_PR_SENSE_HARDWARE_ERROR   4   /*  [sk,asc,ascq: 0x4,*,*] */
52 #define MPATH_PR_ILLEGAL_REQ            5   /*  [sk,asc,ascq: 0x5,*,*]*/
53 #define MPATH_PR_SENSE_UNIT_ATTENTION   6   /*  [sk,asc,ascq: 0x6,*,*] */
54 #define MPATH_PR_SENSE_INVALID_OP       7   /*  [sk,asc,ascq: 0x5,0x20,0x0]*/
55 #define MPATH_PR_SENSE_ABORTED_COMMAND  8   /*  [sk,asc,ascq: 0xb,*,*] */
56 #define MPATH_PR_NO_SENSE               9   /*  [sk,asc,ascq: 0x0,*,*] */
57
58 #define MPATH_PR_SENSE_MALFORMED        10  /* Response to SCSI command malformed */
59 #define MPATH_PR_RESERV_CONFLICT        11  /* Reservation conflict on the device */
60 #define MPATH_PR_FILE_ERROR             12  /* file (device node) problems(e.g. not found)*/
61 #define MPATH_PR_DMMP_ERROR             13  /* DMMP related error.(e.g Error in getting dm info */
62 #define MPATH_PR_OTHER                  14  /*other error/warning has occurred(transport
63                                               or driver error) */
64
65 /* PR MASK */
66 #define MPATH_F_APTPL_MASK              0x01    /* APTPL MASK*/
67 #define MPATH_F_ALL_TG_PT_MASK          0x04    /* ALL_TG_PT MASK*/
68 #define MPATH_F_SPEC_I_PT_MASK          0x08    /* SPEC_I_PT MASK*/
69 #define MPATH_PR_TYPE_MASK              0x0f    /* TYPE MASK*/
70 #define MPATH_PR_SCOPE_MASK             0xf0    /* SCOPE MASK*/
71
72 /*Transport ID PROTOCOL IDENTIFIER values */
73 #define MPATH_PROTOCOL_ID_FC            0x00
74 #define MPATH_PROTOCOL_ID_ISCSI         0x05
75 #define MPATH_PROTOCOL_ID_SAS           0x06
76
77
78 /*Transport ID FORMATE CODE */
79 #define MPATH_WWUI_DEVICE_NAME          0x00    /* World wide unique initiator device name */
80 #define MPATH_WWUI_PORT_IDENTIFIER      0x40    /* World wide unique initiator port identifier  */
81
82
83
84
85 struct prin_readdescr
86 {
87         uint32_t prgeneration;
88         uint32_t additional_length;     /* The value should be either 0 or divisible by 8.
89                                            0 indicates no registered reservation key. */
90         uint8_t  key_list[MPATH_MAX_PARAM_LEN];
91 };
92
93 struct prin_resvdescr
94 {
95         uint32_t prgeneration;
96         uint32_t additional_length;     /* The value should be either 0 or 10h. 0 indicates
97                                            there is no reservation held. 10h indicates the
98                                            key[8] and scope_type have valid values */
99         uint8_t  key[8];
100         uint32_t _obsolete;
101         uint8_t  _reserved;
102         uint8_t  scope_type;            /* Use PR SCOPE AND TYPE MASK specified above */
103         uint16_t _obsolete1;
104 };
105
106 struct prin_capdescr
107 {
108         uint16_t length;
109         uint8_t  flags[2];
110         uint16_t pr_type_mask;
111         uint16_t _reserved;
112 };
113
114 struct transportid
115 {
116         uint8_t format_code;
117         uint8_t protocol_id;
118         union {
119                 uint8_t n_port_name[8]; /* FC transport*/
120                 uint8_t sas_address[8]; /* SAS transport */
121                 uint8_t iscsi_name[256]; /* ISCSI  transport */
122         };
123 };
124
125 struct prin_fulldescr
126 {
127         uint8_t key[8];
128         uint8_t flag;                   /* All_tg_pt and reservation holder */
129         uint8_t scope_type;             /* Use PR SCOPE AND TYPE MASK specified above.
130                                            Meaningful only for reservation holder */
131         uint16_t rtpi;
132         struct transportid trnptid;
133 };
134
135 struct print_fulldescr_list
136 {
137         uint32_t prgeneration;
138         uint32_t number_of_descriptor;
139         uint8_t private_buffer[MPATH_MAX_PARAM_LEN]; /*Private buffer for list storage*/
140         struct prin_fulldescr *descriptors[];
141 };
142
143 struct prin_resp
144 {
145         union
146         {
147                 struct prin_readdescr prin_readkeys; /* for PRIN read keys SA*/
148                 struct prin_resvdescr prin_readresv; /* for PRIN read reservation SA*/
149                 struct prin_capdescr  prin_readcap;  /* for PRIN Report Capabilities SA*/
150                 struct print_fulldescr_list prin_readfd;   /* for PRIN read full status SA*/
151         }prin_descriptor;
152 };
153
154 struct prout_param_descriptor {         /* PROUT parameter descriptor */
155         uint8_t  key[8];
156         uint8_t  sa_key[8];
157         uint32_t _obsolete;
158         uint8_t  sa_flags;
159         uint8_t _reserved;
160         uint16_t _obsolete1;
161         uint8_t  private_buffer[MPATH_MAX_PARAM_LEN]; /*private buffer for list storage*/
162         uint32_t num_transportid;       /* Number of Transport ID listed in trnptid_list[]*/
163         struct transportid *trnptid_list[];
164 };
165
166
167 /* Function declarations */
168
169 /*
170  * DESCRIPTION :
171  *      Initialize device mapper multipath configuration. This function must be invoked first
172  *      before performing reservation management functions.
173  * RESTRICTIONS:
174  *
175  * RETURNS: 0->Success, 1->Failed.
176  */
177 extern int mpath_lib_init (struct udev *udev);
178
179
180 /*
181  * DESCRIPTION :
182  *      Release device mapper multipath configuration. This function must be invoked after
183  *      performing reservation management functions.
184  * RESTRICTIONS:
185  *
186  * RETURNS: 0->Success, 1->Failed.
187  */
188 extern int mpath_lib_exit (void );
189
190
191 /*
192  * DESCRIPTION :
193  * This function sends PRIN command to the DM device and get the response.
194  *
195  * @fd: The file descriptor of a multipath device. Input argument.
196  * @rq_servact: PRIN command service action. Input argument
197  * @resp: The response from PRIN service action. The resp is a struct specified above. The caller should
198  *      manage the memory allocation of this struct
199  * @noisy: Turn on debugging trace: Input argument. 0->Disable, 1->Enable
200  * @verbose: Set verbosity level. Input argument. value:[0-3]. 0->disabled, 3->Max verbose
201  *
202  * RESTRICTIONS:
203  *
204  * RETURNS: MPATH_PR_SUCCESS if PR command successful else returns any of the status specified
205  *       above in RETURN_STATUS.
206  *
207  */
208 extern int mpath_persistent_reserve_in (int fd, int rq_servact, struct prin_resp *resp,
209                 int noisy, int verbose);
210
211 /*
212  * DESCRIPTION :
213  * This function sends PROUT command to the DM device and get the response.
214  *
215  * @fd: The file descriptor of a multipath device. Input argument.
216  * @rq_servact: PROUT command service action. Input argument
217  * @rq_scope: Persistent reservation scope. The value should be always LU_SCOPE (0h).
218  * @rq_type: Persistent reservation type. The valid values of persistent reservation types are
219  *      5h (Write exclusive - registrants only)
220  *      6h (Exclusive access - registrants only)
221  *      7h (Write exclusive - All registrants)
222  *      8h (Exclusive access - All registrants).
223  * @paramp: PROUT command parameter data. The paramp is a struct which describes PROUT
224  *          parameter list. The caller should manage the memory allocation of this struct.
225  * @noisy: Turn on debugging trace: Input argument.0->Disable, 1->Enable.
226  * @verbose: Set verbosity level. Input argument. value:0 to 3. 0->disabled, 3->Max verbose
227  *
228  * RESTRICTIONS:
229  *
230  * RETURNS: MPATH_PR_SUCCESS if PR command successful else returns any of the status specified
231  *       above in RETURN_STATUS.
232  */
233 extern int mpath_persistent_reserve_out ( int fd, int rq_servact, int rq_scope,
234                 unsigned int rq_type, struct prout_param_descriptor *paramp, int noisy,
235                 int verbose);
236
237 #ifdef __cplusplus
238 }
239 #endif
240
241 #endif  /*MPATH_PERSIST_LIB_H*/