diff options
Diffstat (limited to 'include/net/iucv/iucv.h')
| -rw-r--r-- | include/net/iucv/iucv.h | 415 |
1 files changed, 415 insertions, 0 deletions
diff --git a/include/net/iucv/iucv.h b/include/net/iucv/iucv.h new file mode 100644 index 00000000000..746e7416261 --- /dev/null +++ b/include/net/iucv/iucv.h @@ -0,0 +1,415 @@ +/* + * drivers/s390/net/iucv.h + * IUCV base support. + * + * S390 version + * Copyright 2000, 2006 IBM Corporation + * Author(s):Alan Altmark (Alan_Altmark@us.ibm.com) + * Xenia Tkatschow (xenia@us.ibm.com) + * Rewritten for af_iucv: + * Martin Schwidefsky <schwidefsky@de.ibm.com> + * + * + * Functionality: + * To explore any of the IUCV functions, one must first register their + * program using iucv_register(). Once your program has successfully + * completed a register, it can exploit the other functions. + * For furthur reference on all IUCV functionality, refer to the + * CP Programming Services book, also available on the web thru + * www.ibm.com/s390/vm/pubs, manual # SC24-5760 + * + * Definition of Return Codes + * - All positive return codes including zero are reflected back + * from CP. The definition of each return code can be found in + * CP Programming Services book. + * - Return Code of: + * -EINVAL: Invalid value + * -ENOMEM: storage allocation failed + */ + +#include <linux/types.h> +#include <asm/debug.h> + +/* + * IUCV option flags usable by device drivers: + * + * IUCV_IPRMDATA Indicates that your program can handle a message in the + * parameter list / a message is sent in the parameter list. + * Used for iucv_path_accept, iucv_path_connect, + * iucv_message_reply, iucv_message_send, iucv_message_send2way. + * IUCV_IPQUSCE Indicates that you do not want to receive messages on this + * path until an iucv_path_resume is issued. + * Used for iucv_path_accept, iucv_path_connect. + * IUCV_IPBUFLST Indicates that an address list is used for the message data. + * Used for iucv_message_receive, iucv_message_send, + * iucv_message_send2way. + * IUCV_IPPRTY Specifies that you want to send priority messages. + * Used for iucv_path_accept, iucv_path_connect, + * iucv_message_reply, iucv_message_send, iucv_message_send2way. + * IUCV_IPSYNC Indicates a synchronous send request. + * Used for iucv_message_send, iucv_message_send2way. + * IUCV_IPANSLST Indicates that an address list is used for the reply data. + * Used for iucv_message_reply, iucv_message_send2way. + * IUCV_IPLOCAL Specifies that the communication partner has to be on the + * local system. If local is specified no target class can be + * specified. + * Used for iucv_path_connect. + * + * All flags are defined in the input field IPFLAGS1 of each function + * and can be found in CP Programming Services. + */ +#define IUCV_IPRMDATA 0x80 +#define IUCV_IPQUSCE 0x40 +#define IUCV_IPBUFLST 0x40 +#define IUCV_IPPRTY 0x20 +#define IUCV_IPANSLST 0x08 +#define IUCV_IPSYNC 0x04 +#define IUCV_IPLOCAL 0x01 + +/* + * iucv_array : Defines buffer array. + * Inside the array may be 31- bit addresses and 31-bit lengths. + * Use a pointer to an iucv_array as the buffer, reply or answer + * parameter on iucv_message_send, iucv_message_send2way, iucv_message_receive + * and iucv_message_reply if IUCV_IPBUFLST or IUCV_IPANSLST are used. + */ +struct iucv_array { + u32 address; + u32 length; +} __attribute__ ((aligned (8))); + +extern struct bus_type iucv_bus; +extern struct device *iucv_root; + +/* + * struct iucv_path + * pathid: 16 bit path identification + * msglim: 16 bit message limit + * flags: properties of the path: IPRMDATA, IPQUSCE, IPPRTY + * handler: address of iucv handler structure + * private: private information of the handler associated with the path + * list: list_head for the iucv_handler path list. + */ +struct iucv_path { + u16 pathid; + u16 msglim; + u8 flags; + void *private; + struct iucv_handler *handler; + struct list_head list; +}; + +/* + * struct iucv_message + * id: 32 bit message id + * audit: 32 bit error information of purged or replied messages + * class: 32 bit target class of a message (source class for replies) + * tag: 32 bit tag to be associated with the message + * length: 32 bit length of the message / reply + * reply_size: 32 bit maximum allowed length of the reply + * rmmsg: 8 byte inline message + * flags: message properties (IUCV_IPPRTY) + */ +struct iucv_message { + u32 id; + u32 audit; + u32 class; + u32 tag; + u32 length; + u32 reply_size; + u8 rmmsg[8]; + u8 flags; +}; + +/* + * struct iucv_handler + * + * A vector of functions that handle IUCV interrupts. Each functions gets + * a parameter area as defined by the CP Programming Services and private + * pointer that is provided by the user of the interface. + */ +struct iucv_handler { + /* + * The path_pending function is called after an iucv interrupt + * type 0x01 has been received. The base code allocates a path + * structure and "asks" the handler if this path belongs to the + * handler. To accept the path the path_pending function needs + * to call iucv_path_accept and return 0. If the callback returns + * a value != 0 the iucv base code will continue with the next + * handler. The order in which the path_pending functions are + * called is the order of the registration of the iucv handlers + * to the base code. + */ + int (*path_pending)(struct iucv_path *, u8 ipvmid[8], u8 ipuser[16]); + /* + * The path_complete function is called after an iucv interrupt + * type 0x02 has been received for a path that has been established + * for this handler with iucv_path_connect and got accepted by the + * peer with iucv_path_accept. + */ + void (*path_complete)(struct iucv_path *, u8 ipuser[16]); + /* + * The path_severed function is called after an iucv interrupt + * type 0x03 has been received. The communication peer shutdown + * his end of the communication path. The path still exists and + * remaining messages can be received until a iucv_path_sever + * shuts down the other end of the path as well. + */ + void (*path_severed)(struct iucv_path *, u8 ipuser[16]); + /* + * The path_quiesced function is called after an icuv interrupt + * type 0x04 has been received. The communication peer has quiesced + * the path. Delivery of messages is stopped until iucv_path_resume + * has been called. + */ + void (*path_quiesced)(struct iucv_path *, u8 ipuser[16]); + /* + * The path_resumed function is called after an icuv interrupt + * type 0x05 has been received. The communication peer has resumed + * the path. + */ + void (*path_resumed)(struct iucv_path *, u8 ipuser[16]); + /* + * The message_pending function is called after an icuv interrupt + * type 0x06 or type 0x07 has been received. A new message is + * availabe and can be received with iucv_message_receive. + */ + void (*message_pending)(struct iucv_path *, struct iucv_message *); + /* + * The message_complete function is called after an icuv interrupt + * type 0x08 or type 0x09 has been received. A message send with + * iucv_message_send2way has been replied to. The reply can be + * received with iucv_message_receive. + */ + void (*message_complete)(struct iucv_path *, struct iucv_message *); + + struct list_head list; + struct list_head paths; +}; + +/** + * iucv_register: + * @handler: address of iucv handler structure + * @smp: != 0 indicates that the handler can deal with out of order messages + * + * Registers a driver with IUCV. + * + * Returns 0 on success, -ENOMEM if the memory allocation for the pathid + * table failed, or -EIO if IUCV_DECLARE_BUFFER failed on all cpus. + */ +int iucv_register(struct iucv_handler *handler, int smp); + +/** + * iucv_unregister + * @handler: address of iucv handler structure + * @smp: != 0 indicates that the handler can deal with out of order messages + * + * Unregister driver from IUCV. + */ +void iucv_unregister(struct iucv_handler *handle, int smp); + +/** + * iucv_path_alloc + * @msglim: initial message limit + * @flags: initial flags + * @gfp: kmalloc allocation flag + * + * Allocate a new path structure for use with iucv_connect. + * + * Returns NULL if the memory allocation failed or a pointer to the + * path structure. + */ +static inline struct iucv_path *iucv_path_alloc(u16 msglim, u8 flags, gfp_t gfp) +{ + struct iucv_path *path; + + path = kzalloc(sizeof(struct iucv_path), gfp); + if (path) { + path->msglim = msglim; + path->flags = flags; + } + return path; +} + +/** + * iucv_path_free + * @path: address of iucv path structure + * + * Frees a path structure. + */ +static inline void iucv_path_free(struct iucv_path *path) +{ + kfree(path); +} + +/** + * iucv_path_accept + * @path: address of iucv path structure + * @handler: address of iucv handler structure + * @userdata: 16 bytes of data reflected to the communication partner + * @private: private data passed to interrupt handlers for this path + * + * This function is issued after the user received a connection pending + * external interrupt and now wishes to complete the IUCV communication path. + * + * Returns the result of the CP IUCV call. + */ +int iucv_path_accept(struct iucv_path *path, struct iucv_handler *handler, + u8 userdata[16], void *private); + +/** + * iucv_path_connect + * @path: address of iucv path structure + * @handler: address of iucv handler structure + * @userid: 8-byte user identification + * @system: 8-byte target system identification + * @userdata: 16 bytes of data reflected to the communication partner + * @private: private data passed to interrupt handlers for this path + * + * This function establishes an IUCV path. Although the connect may complete + * successfully, you are not able to use the path until you receive an IUCV + * Connection Complete external interrupt. + * + * Returns the result of the CP IUCV call. + */ +int iucv_path_connect(struct iucv_path *path, struct iucv_handler *handler, + u8 userid[8], u8 system[8], u8 userdata[16], + void *private); + +/** + * iucv_path_quiesce: + * @path: address of iucv path structure + * @userdata: 16 bytes of data reflected to the communication partner + * + * This function temporarily suspends incoming messages on an IUCV path. + * You can later reactivate the path by invoking the iucv_resume function. + * + * Returns the result from the CP IUCV call. + */ +int iucv_path_quiesce(struct iucv_path *path, u8 userdata[16]); + +/** + * iucv_path_resume: + * @path: address of iucv path structure + * @userdata: 16 bytes of data reflected to the communication partner + * + * This function resumes incoming messages on an IUCV path that has + * been stopped with iucv_path_quiesce. + * + * Returns the result from the CP IUCV call. + */ +int iucv_path_resume(struct iucv_path *path, u8 userdata[16]); + +/** + * iucv_path_sever + * @path: address of iucv path structure + * @userdata: 16 bytes of data reflected to the communication partner + * + * This function terminates an IUCV path. + * + * Returns the result from the CP IUCV call. + */ +int iucv_path_sever(struct iucv_path *path, u8 userdata[16]); + +/** + * iucv_message_purge + * @path: address of iucv path structure + * @msg: address of iucv msg structure + * @srccls: source class of message + * + * Cancels a message you have sent. + * + * Returns the result from the CP IUCV call. + */ +int iucv_message_purge(struct iucv_path *path, struct iucv_message *msg, + u32 srccls); + +/** + * iucv_message_receive + * @path: address of iucv path structure + * @msg: address of iucv msg structure + * @flags: flags that affect how the message is received (IUCV_IPBUFLST) + * @buffer: address of data buffer or address of struct iucv_array + * @size: length of data buffer + * @residual: + * + * This function receives messages that are being sent to you over + * established paths. This function will deal with RMDATA messages + * embedded in struct iucv_message as well. + * + * Returns the result from the CP IUCV call. + */ +int iucv_message_receive(struct iucv_path *path, struct iucv_message *msg, + u8 flags, void *buffer, size_t size, size_t *residual); + +/** + * iucv_message_reject + * @path: address of iucv path structure + * @msg: address of iucv msg structure + * + * The reject function refuses a specified message. Between the time you + * are notified of a message and the time that you complete the message, + * the message may be rejected. + * + * Returns the result from the CP IUCV call. + */ +int iucv_message_reject(struct iucv_path *path, struct iucv_message *msg); + +/** + * iucv_message_reply + * @path: address of iucv path structure + * @msg: address of iucv msg structure + * @flags: how the reply is sent (IUCV_IPRMDATA, IUCV_IPPRTY, IUCV_IPBUFLST) + * @reply: address of data buffer or address of struct iucv_array + * @size: length of reply data buffer + * + * This function responds to the two-way messages that you receive. You + * must identify completely the message to which you wish to reply. ie, + * pathid, msgid, and trgcls. Prmmsg signifies the data is moved into + * the parameter list. + * + * Returns the result from the CP IUCV call. + */ +int iucv_message_reply(struct iucv_path *path, struct iucv_message *msg, + u8 flags, void *reply, size_t size); + +/** + * iucv_message_send + * @path: address of iucv path structure + * @msg: address of iucv msg structure + * @flags: how the message is sent (IUCV_IPRMDATA, IUCV_IPPRTY, IUCV_IPBUFLST) + * @srccls: source class of message + * @buffer: address of data buffer or address of struct iucv_array + * @size: length of send buffer + * + * This function transmits data to another application. Data to be + * transmitted is in a buffer and this is a one-way message and the + * receiver will not reply to the message. + * + * Returns the result from the CP IUCV call. + */ +int iucv_message_send(struct iucv_path *path, struct iucv_message *msg, + u8 flags, u32 srccls, void *buffer, size_t size); + +/** + * iucv_message_send2way + * @path: address of iucv path structure + * @msg: address of iucv msg structure + * @flags: how the message is sent and the reply is received + * (IUCV_IPRMDATA, IUCV_IPBUFLST, IUCV_IPPRTY, IUCV_ANSLST) + * @srccls: source class of message + * @buffer: address of data buffer or address of struct iucv_array + * @size: length of send buffer + * @ansbuf: address of answer buffer or address of struct iucv_array + * @asize: size of reply buffer + * + * This function transmits data to another application. Data to be + * transmitted is in a buffer. The receiver of the send is expected to + * reply to the message and a buffer is provided into which IUCV moves + * the reply to this message. + * + * Returns the result from the CP IUCV call. + */ +int iucv_message_send2way(struct iucv_path *path, struct iucv_message *msg, + u8 flags, u32 srccls, void *buffer, size_t size, + void *answer, size_t asize, size_t *residual); |