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