[S390]: Rewrite of the IUCV base code, part 2
[linux-2.6.git] / 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.ibm.com/s390/vm/pubs, manual # SC24-5760
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);