include/net/iucv/iucv.h

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