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