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