1 /* 2 * drivers/s390/net/iucv.h 3 * IUCV base support. 4 * 5 * S390 version 6 * Copyright 2000, 2006 IBM Corporation 7 * Author(s):Alan Altmark (Alan_Altmark@us.ibm.com) 8 * Xenia Tkatschow (xenia@us.ibm.com) 9 * Rewritten for af_iucv: 10 * Martin Schwidefsky <schwidefsky@de.ibm.com> 11 * 12 * 13 * Functionality: 14 * To explore any of the IUCV functions, one must first register their 15 * program using iucv_register(). Once your program has successfully 16 * completed a register, it can exploit the other functions. 17 * For furthur reference on all IUCV functionality, refer to the 18 * CP Programming Services book, also available on the web thru 19 * www.vm.ibm.com/pubs, manual # SC24-6084 20 * 21 * Definition of Return Codes 22 * - All positive return codes including zero are reflected back 23 * from CP. The definition of each return code can be found in 24 * CP Programming Services book. 25 * - Return Code of: 26 * -EINVAL: Invalid value 27 * -ENOMEM: storage allocation failed 28 */ 29 30 #include <linux/types.h> 31 #include <asm/debug.h> 32 33 /* 34 * IUCV option flags usable by device drivers: 35 * 36 * IUCV_IPRMDATA Indicates that your program can handle a message in the 37 * parameter list / a message is sent in the parameter list. 38 * Used for iucv_path_accept, iucv_path_connect, 39 * iucv_message_reply, iucv_message_send, iucv_message_send2way. 40 * IUCV_IPQUSCE Indicates that you do not want to receive messages on this 41 * path until an iucv_path_resume is issued. 42 * Used for iucv_path_accept, iucv_path_connect. 43 * IUCV_IPBUFLST Indicates that an address list is used for the message data. 44 * Used for iucv_message_receive, iucv_message_send, 45 * iucv_message_send2way. 46 * IUCV_IPPRTY Specifies that you want to send priority messages. 47 * Used for iucv_path_accept, iucv_path_connect, 48 * iucv_message_reply, iucv_message_send, iucv_message_send2way. 49 * IUCV_IPSYNC Indicates a synchronous send request. 50 * Used for iucv_message_send, iucv_message_send2way. 51 * IUCV_IPANSLST Indicates that an address list is used for the reply data. 52 * Used for iucv_message_reply, iucv_message_send2way. 53 * IUCV_IPLOCAL Specifies that the communication partner has to be on the 54 * local system. If local is specified no target class can be 55 * specified. 56 * Used for iucv_path_connect. 57 * 58 * All flags are defined in the input field IPFLAGS1 of each function 59 * and can be found in CP Programming Services. 60 */ 61 #define IUCV_IPRMDATA 0x80 62 #define IUCV_IPQUSCE 0x40 63 #define IUCV_IPBUFLST 0x40 64 #define IUCV_IPPRTY 0x20 65 #define IUCV_IPANSLST 0x08 66 #define IUCV_IPSYNC 0x04 67 #define IUCV_IPLOCAL 0x01 68 69 /* 70 * iucv_array : Defines buffer array. 71 * Inside the array may be 31- bit addresses and 31-bit lengths. 72 * Use a pointer to an iucv_array as the buffer, reply or answer 73 * parameter on iucv_message_send, iucv_message_send2way, iucv_message_receive 74 * and iucv_message_reply if IUCV_IPBUFLST or IUCV_IPANSLST are used. 75 */ 76 struct iucv_array { 77 u32 address; 78 u32 length; 79 } __attribute__ ((aligned (8))); 80 81 extern struct bus_type iucv_bus; 82 extern struct device *iucv_root; 83 84 /* 85 * struct iucv_path 86 * pathid: 16 bit path identification 87 * msglim: 16 bit message limit 88 * flags: properties of the path: IPRMDATA, IPQUSCE, IPPRTY 89 * handler: address of iucv handler structure 90 * private: private information of the handler associated with the path 91 * list: list_head for the iucv_handler path list. 92 */ 93 struct iucv_path { 94 u16 pathid; 95 u16 msglim; 96 u8 flags; 97 void *private; 98 struct iucv_handler *handler; 99 struct list_head list; 100 }; 101 102 /* 103 * struct iucv_message 104 * id: 32 bit message id 105 * audit: 32 bit error information of purged or replied messages 106 * class: 32 bit target class of a message (source class for replies) 107 * tag: 32 bit tag to be associated with the message 108 * length: 32 bit length of the message / reply 109 * reply_size: 32 bit maximum allowed length of the reply 110 * rmmsg: 8 byte inline message 111 * flags: message properties (IUCV_IPPRTY) 112 */ 113 struct iucv_message { 114 u32 id; 115 u32 audit; 116 u32 class; 117 u32 tag; 118 u32 length; 119 u32 reply_size; 120 u8 rmmsg[8]; 121 u8 flags; 122 }; 123 124 /* 125 * struct iucv_handler 126 * 127 * A vector of functions that handle IUCV interrupts. Each functions gets 128 * a parameter area as defined by the CP Programming Services and private 129 * pointer that is provided by the user of the interface. 130 */ 131 struct iucv_handler { 132 /* 133 * The path_pending function is called after an iucv interrupt 134 * type 0x01 has been received. The base code allocates a path 135 * structure and "asks" the handler if this path belongs to the 136 * handler. To accept the path the path_pending function needs 137 * to call iucv_path_accept and return 0. If the callback returns 138 * a value != 0 the iucv base code will continue with the next 139 * handler. The order in which the path_pending functions are 140 * called is the order of the registration of the iucv handlers 141 * to the base code. 142 */ 143 int (*path_pending)(struct iucv_path *, u8 ipvmid[8], u8 ipuser[16]); 144 /* 145 * The path_complete function is called after an iucv interrupt 146 * type 0x02 has been received for a path that has been established 147 * for this handler with iucv_path_connect and got accepted by the 148 * peer with iucv_path_accept. 149 */ 150 void (*path_complete)(struct iucv_path *, u8 ipuser[16]); 151 /* 152 * The path_severed function is called after an iucv interrupt 153 * type 0x03 has been received. The communication peer shutdown 154 * his end of the communication path. The path still exists and 155 * remaining messages can be received until a iucv_path_sever 156 * shuts down the other end of the path as well. 157 */ 158 void (*path_severed)(struct iucv_path *, u8 ipuser[16]); 159 /* 160 * The path_quiesced function is called after an icuv interrupt 161 * type 0x04 has been received. The communication peer has quiesced 162 * the path. Delivery of messages is stopped until iucv_path_resume 163 * has been called. 164 */ 165 void (*path_quiesced)(struct iucv_path *, u8 ipuser[16]); 166 /* 167 * The path_resumed function is called after an icuv interrupt 168 * type 0x05 has been received. The communication peer has resumed 169 * the path. 170 */ 171 void (*path_resumed)(struct iucv_path *, u8 ipuser[16]); 172 /* 173 * The message_pending function is called after an icuv interrupt 174 * type 0x06 or type 0x07 has been received. A new message is 175 * availabe and can be received with iucv_message_receive. 176 */ 177 void (*message_pending)(struct iucv_path *, struct iucv_message *); 178 /* 179 * The message_complete function is called after an icuv interrupt 180 * type 0x08 or type 0x09 has been received. A message send with 181 * iucv_message_send2way has been replied to. The reply can be 182 * received with iucv_message_receive. 183 */ 184 void (*message_complete)(struct iucv_path *, struct iucv_message *); 185 186 struct list_head list; 187 struct list_head paths; 188 }; 189 190 /** 191 * iucv_register: 192 * @handler: address of iucv handler structure 193 * @smp: != 0 indicates that the handler can deal with out of order messages 194 * 195 * Registers a driver with IUCV. 196 * 197 * Returns 0 on success, -ENOMEM if the memory allocation for the pathid 198 * table failed, or -EIO if IUCV_DECLARE_BUFFER failed on all cpus. 199 */ 200 int iucv_register(struct iucv_handler *handler, int smp); 201 202 /** 203 * iucv_unregister 204 * @handler: address of iucv handler structure 205 * @smp: != 0 indicates that the handler can deal with out of order messages 206 * 207 * Unregister driver from IUCV. 208 */ 209 void iucv_unregister(struct iucv_handler *handle, int smp); 210 211 /** 212 * iucv_path_alloc 213 * @msglim: initial message limit 214 * @flags: initial flags 215 * @gfp: kmalloc allocation flag 216 * 217 * Allocate a new path structure for use with iucv_connect. 218 * 219 * Returns NULL if the memory allocation failed or a pointer to the 220 * path structure. 221 */ 222 static inline struct iucv_path *iucv_path_alloc(u16 msglim, u8 flags, gfp_t gfp) 223 { 224 struct iucv_path *path; 225 226 path = kzalloc(sizeof(struct iucv_path), gfp); 227 if (path) { 228 path->msglim = msglim; 229 path->flags = flags; 230 } 231 return path; 232 } 233 234 /** 235 * iucv_path_free 236 * @path: address of iucv path structure 237 * 238 * Frees a path structure. 239 */ 240 static inline void iucv_path_free(struct iucv_path *path) 241 { 242 kfree(path); 243 } 244 245 /** 246 * iucv_path_accept 247 * @path: address of iucv path structure 248 * @handler: address of iucv handler structure 249 * @userdata: 16 bytes of data reflected to the communication partner 250 * @private: private data passed to interrupt handlers for this path 251 * 252 * This function is issued after the user received a connection pending 253 * external interrupt and now wishes to complete the IUCV communication path. 254 * 255 * Returns the result of the CP IUCV call. 256 */ 257 int iucv_path_accept(struct iucv_path *path, struct iucv_handler *handler, 258 u8 userdata[16], void *private); 259 260 /** 261 * iucv_path_connect 262 * @path: address of iucv path structure 263 * @handler: address of iucv handler structure 264 * @userid: 8-byte user identification 265 * @system: 8-byte target system identification 266 * @userdata: 16 bytes of data reflected to the communication partner 267 * @private: private data passed to interrupt handlers for this path 268 * 269 * This function establishes an IUCV path. Although the connect may complete 270 * successfully, you are not able to use the path until you receive an IUCV 271 * Connection Complete external interrupt. 272 * 273 * Returns the result of the CP IUCV call. 274 */ 275 int iucv_path_connect(struct iucv_path *path, struct iucv_handler *handler, 276 u8 userid[8], u8 system[8], u8 userdata[16], 277 void *private); 278 279 /** 280 * iucv_path_quiesce: 281 * @path: address of iucv path structure 282 * @userdata: 16 bytes of data reflected to the communication partner 283 * 284 * This function temporarily suspends incoming messages on an IUCV path. 285 * You can later reactivate the path by invoking the iucv_resume function. 286 * 287 * Returns the result from the CP IUCV call. 288 */ 289 int iucv_path_quiesce(struct iucv_path *path, u8 userdata[16]); 290 291 /** 292 * iucv_path_resume: 293 * @path: address of iucv path structure 294 * @userdata: 16 bytes of data reflected to the communication partner 295 * 296 * This function resumes incoming messages on an IUCV path that has 297 * been stopped with iucv_path_quiesce. 298 * 299 * Returns the result from the CP IUCV call. 300 */ 301 int iucv_path_resume(struct iucv_path *path, u8 userdata[16]); 302 303 /** 304 * iucv_path_sever 305 * @path: address of iucv path structure 306 * @userdata: 16 bytes of data reflected to the communication partner 307 * 308 * This function terminates an IUCV path. 309 * 310 * Returns the result from the CP IUCV call. 311 */ 312 int iucv_path_sever(struct iucv_path *path, u8 userdata[16]); 313 314 /** 315 * iucv_message_purge 316 * @path: address of iucv path structure 317 * @msg: address of iucv msg structure 318 * @srccls: source class of message 319 * 320 * Cancels a message you have sent. 321 * 322 * Returns the result from the CP IUCV call. 323 */ 324 int iucv_message_purge(struct iucv_path *path, struct iucv_message *msg, 325 u32 srccls); 326 327 /** 328 * iucv_message_receive 329 * @path: address of iucv path structure 330 * @msg: address of iucv msg structure 331 * @flags: flags that affect how the message is received (IUCV_IPBUFLST) 332 * @buffer: address of data buffer or address of struct iucv_array 333 * @size: length of data buffer 334 * @residual: 335 * 336 * This function receives messages that are being sent to you over 337 * established paths. This function will deal with RMDATA messages 338 * embedded in struct iucv_message as well. 339 * 340 * Locking: local_bh_enable/local_bh_disable 341 * 342 * Returns the result from the CP IUCV call. 343 */ 344 int iucv_message_receive(struct iucv_path *path, struct iucv_message *msg, 345 u8 flags, void *buffer, size_t size, size_t *residual); 346 347 /** 348 * __iucv_message_receive 349 * @path: address of iucv path structure 350 * @msg: address of iucv msg structure 351 * @flags: flags that affect how the message is received (IUCV_IPBUFLST) 352 * @buffer: address of data buffer or address of struct iucv_array 353 * @size: length of data buffer 354 * @residual: 355 * 356 * This function receives messages that are being sent to you over 357 * established paths. This function will deal with RMDATA messages 358 * embedded in struct iucv_message as well. 359 * 360 * Locking: no locking. 361 * 362 * Returns the result from the CP IUCV call. 363 */ 364 int __iucv_message_receive(struct iucv_path *path, struct iucv_message *msg, 365 u8 flags, void *buffer, size_t size, 366 size_t *residual); 367 368 /** 369 * iucv_message_reject 370 * @path: address of iucv path structure 371 * @msg: address of iucv msg structure 372 * 373 * The reject function refuses a specified message. Between the time you 374 * are notified of a message and the time that you complete the message, 375 * the message may be rejected. 376 * 377 * Returns the result from the CP IUCV call. 378 */ 379 int iucv_message_reject(struct iucv_path *path, struct iucv_message *msg); 380 381 /** 382 * iucv_message_reply 383 * @path: address of iucv path structure 384 * @msg: address of iucv msg structure 385 * @flags: how the reply is sent (IUCV_IPRMDATA, IUCV_IPPRTY, IUCV_IPBUFLST) 386 * @reply: address of data buffer or address of struct iucv_array 387 * @size: length of reply data buffer 388 * 389 * This function responds to the two-way messages that you receive. You 390 * must identify completely the message to which you wish to reply. ie, 391 * pathid, msgid, and trgcls. Prmmsg signifies the data is moved into 392 * the parameter list. 393 * 394 * Returns the result from the CP IUCV call. 395 */ 396 int iucv_message_reply(struct iucv_path *path, struct iucv_message *msg, 397 u8 flags, void *reply, size_t size); 398 399 /** 400 * iucv_message_send 401 * @path: address of iucv path structure 402 * @msg: address of iucv msg structure 403 * @flags: how the message is sent (IUCV_IPRMDATA, IUCV_IPPRTY, IUCV_IPBUFLST) 404 * @srccls: source class of message 405 * @buffer: address of data buffer or address of struct iucv_array 406 * @size: length of send buffer 407 * 408 * This function transmits data to another application. Data to be 409 * transmitted is in a buffer and this is a one-way message and the 410 * receiver will not reply to the message. 411 * 412 * Locking: local_bh_enable/local_bh_disable 413 * 414 * Returns the result from the CP IUCV call. 415 */ 416 int iucv_message_send(struct iucv_path *path, struct iucv_message *msg, 417 u8 flags, u32 srccls, void *buffer, size_t size); 418 419 /** 420 * __iucv_message_send 421 * @path: address of iucv path structure 422 * @msg: address of iucv msg structure 423 * @flags: how the message is sent (IUCV_IPRMDATA, IUCV_IPPRTY, IUCV_IPBUFLST) 424 * @srccls: source class of message 425 * @buffer: address of data buffer or address of struct iucv_array 426 * @size: length of send buffer 427 * 428 * This function transmits data to another application. Data to be 429 * transmitted is in a buffer and this is a one-way message and the 430 * receiver will not reply to the message. 431 * 432 * Locking: no locking. 433 * 434 * Returns the result from the CP IUCV call. 435 */ 436 int __iucv_message_send(struct iucv_path *path, struct iucv_message *msg, 437 u8 flags, u32 srccls, void *buffer, size_t size); 438 439 /** 440 * iucv_message_send2way 441 * @path: address of iucv path structure 442 * @msg: address of iucv msg structure 443 * @flags: how the message is sent and the reply is received 444 * (IUCV_IPRMDATA, IUCV_IPBUFLST, IUCV_IPPRTY, IUCV_ANSLST) 445 * @srccls: source class of message 446 * @buffer: address of data buffer or address of struct iucv_array 447 * @size: length of send buffer 448 * @ansbuf: address of answer buffer or address of struct iucv_array 449 * @asize: size of reply buffer 450 * 451 * This function transmits data to another application. Data to be 452 * transmitted is in a buffer. The receiver of the send is expected to 453 * reply to the message and a buffer is provided into which IUCV moves 454 * the reply to this message. 455 * 456 * Returns the result from the CP IUCV call. 457 */ 458 int iucv_message_send2way(struct iucv_path *path, struct iucv_message *msg, 459 u8 flags, u32 srccls, void *buffer, size_t size, 460 void *answer, size_t asize, size_t *residual); 461