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