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 <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 */
iucv_path_alloc(u16 msglim,u8 flags,gfp_t gfp)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 */
iucv_path_free(struct iucv_path * path)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 * Locking: local_bh_enable/local_bh_disable
341 *
342 * Returns the result from the CP IUCV call.
343 */
344 int iucv_message_receive(struct iucv_path *path, struct iucv_message *msg,
345 u8 flags, void *buffer, size_t size, size_t *residual);
346
347 /**
348 * __iucv_message_receive
349 * @path: address of iucv path structure
350 * @msg: address of iucv msg structure
351 * @flags: flags that affect how the message is received (IUCV_IPBUFLST)
352 * @buffer: address of data buffer or address of struct iucv_array
353 * @size: length of data buffer
354 * @residual:
355 *
356 * This function receives messages that are being sent to you over
357 * established paths. This function will deal with RMDATA messages
358 * embedded in struct iucv_message as well.
359 *
360 * Locking: no locking.
361 *
362 * Returns the result from the CP IUCV call.
363 */
364 int __iucv_message_receive(struct iucv_path *path, struct iucv_message *msg,
365 u8 flags, void *buffer, size_t size,
366 size_t *residual);
367
368 /**
369 * iucv_message_reject
370 * @path: address of iucv path structure
371 * @msg: address of iucv msg structure
372 *
373 * The reject function refuses a specified message. Between the time you
374 * are notified of a message and the time that you complete the message,
375 * the message may be rejected.
376 *
377 * Returns the result from the CP IUCV call.
378 */
379 int iucv_message_reject(struct iucv_path *path, struct iucv_message *msg);
380
381 /**
382 * iucv_message_reply
383 * @path: address of iucv path structure
384 * @msg: address of iucv msg structure
385 * @flags: how the reply is sent (IUCV_IPRMDATA, IUCV_IPPRTY, IUCV_IPBUFLST)
386 * @reply: address of data buffer or address of struct iucv_array
387 * @size: length of reply data buffer
388 *
389 * This function responds to the two-way messages that you receive. You
390 * must identify completely the message to which you wish to reply. ie,
391 * pathid, msgid, and trgcls. Prmmsg signifies the data is moved into
392 * the parameter list.
393 *
394 * Returns the result from the CP IUCV call.
395 */
396 int iucv_message_reply(struct iucv_path *path, struct iucv_message *msg,
397 u8 flags, void *reply, size_t size);
398
399 /**
400 * iucv_message_send
401 * @path: address of iucv path structure
402 * @msg: address of iucv msg structure
403 * @flags: how the message is sent (IUCV_IPRMDATA, IUCV_IPPRTY, IUCV_IPBUFLST)
404 * @srccls: source class of message
405 * @buffer: address of data buffer or address of struct iucv_array
406 * @size: length of send buffer
407 *
408 * This function transmits data to another application. Data to be
409 * transmitted is in a buffer and this is a one-way message and the
410 * receiver will not reply to the message.
411 *
412 * Locking: local_bh_enable/local_bh_disable
413 *
414 * Returns the result from the CP IUCV call.
415 */
416 int iucv_message_send(struct iucv_path *path, struct iucv_message *msg,
417 u8 flags, u32 srccls, void *buffer, size_t size);
418
419 /**
420 * __iucv_message_send
421 * @path: address of iucv path structure
422 * @msg: address of iucv msg structure
423 * @flags: how the message is sent (IUCV_IPRMDATA, IUCV_IPPRTY, IUCV_IPBUFLST)
424 * @srccls: source class of message
425 * @buffer: address of data buffer or address of struct iucv_array
426 * @size: length of send buffer
427 *
428 * This function transmits data to another application. Data to be
429 * transmitted is in a buffer and this is a one-way message and the
430 * receiver will not reply to the message.
431 *
432 * Locking: no locking.
433 *
434 * Returns the result from the CP IUCV call.
435 */
436 int __iucv_message_send(struct iucv_path *path, struct iucv_message *msg,
437 u8 flags, u32 srccls, void *buffer, size_t size);
438
439 /**
440 * iucv_message_send2way
441 * @path: address of iucv path structure
442 * @msg: address of iucv msg structure
443 * @flags: how the message is sent and the reply is received
444 * (IUCV_IPRMDATA, IUCV_IPBUFLST, IUCV_IPPRTY, IUCV_ANSLST)
445 * @srccls: source class of message
446 * @buffer: address of data buffer or address of struct iucv_array
447 * @size: length of send buffer
448 * @ansbuf: address of answer buffer or address of struct iucv_array
449 * @asize: size of reply buffer
450 *
451 * This function transmits data to another application. Data to be
452 * transmitted is in a buffer. The receiver of the send is expected to
453 * reply to the message and a buffer is provided into which IUCV moves
454 * the reply to this message.
455 *
456 * Returns the result from the CP IUCV call.
457 */
458 int iucv_message_send2way(struct iucv_path *path, struct iucv_message *msg,
459 u8 flags, u32 srccls, void *buffer, size_t size,
460 void *answer, size_t asize, size_t *residual);
461