include/net/iucv/iucv.h

   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);