1 | /* SPDX-License-Identifier: GPL-2.0 */ |
2 | /* |
3 | * drivers/s390/net/iucv.h |
4 | * IUCV base support. |
5 | * |
6 | * S390 version |
7 | * Copyright 2000, 2006 IBM Corporation |
8 | * Author(s):Alan Altmark (Alan_Altmark@us.ibm.com) |
9 | * Xenia Tkatschow (xenia@us.ibm.com) |
10 | * Rewritten for af_iucv: |
11 | * Martin Schwidefsky <schwidefsky@de.ibm.com> |
12 | * |
13 | * |
14 | * Functionality: |
15 | * To explore any of the IUCV functions, one must first register their |
16 | * program using iucv_register(). Once your program has successfully |
17 | * completed a register, it can exploit the other functions. |
18 | * For furthur reference on all IUCV functionality, refer to the |
19 | * CP Programming Services book, also available on the web thru |
20 | * www.vm.ibm.com/pubs, manual # SC24-6084 |
21 | * |
22 | * Definition of Return Codes |
23 | * - All positive return codes including zero are reflected back |
24 | * from CP. The definition of each return code can be found in |
25 | * CP Programming Services book. |
26 | * - Return Code of: |
27 | * -EINVAL: Invalid value |
28 | * -ENOMEM: storage allocation failed |
29 | */ |
30 | |
31 | #include <linux/types.h> |
32 | #include <linux/slab.h> |
33 | #include <asm/debug.h> |
34 | |
35 | /* |
36 | * IUCV option flags usable by device drivers: |
37 | * |
38 | * IUCV_IPRMDATA Indicates that your program can handle a message in the |
39 | * parameter list / a message is sent in the parameter list. |
40 | * Used for iucv_path_accept, iucv_path_connect, |
41 | * iucv_message_reply, iucv_message_send, iucv_message_send2way. |
42 | * IUCV_IPQUSCE Indicates that you do not want to receive messages on this |
43 | * path until an iucv_path_resume is issued. |
44 | * Used for iucv_path_accept, iucv_path_connect. |
45 | * IUCV_IPBUFLST Indicates that an address list is used for the message data. |
46 | * Used for iucv_message_receive, iucv_message_send, |
47 | * iucv_message_send2way. |
48 | * IUCV_IPPRTY Specifies that you want to send priority messages. |
49 | * Used for iucv_path_accept, iucv_path_connect, |
50 | * iucv_message_reply, iucv_message_send, iucv_message_send2way. |
51 | * IUCV_IPSYNC Indicates a synchronous send request. |
52 | * Used for iucv_message_send, iucv_message_send2way. |
53 | * IUCV_IPANSLST Indicates that an address list is used for the reply data. |
54 | * Used for iucv_message_reply, iucv_message_send2way. |
55 | * IUCV_IPLOCAL Specifies that the communication partner has to be on the |
56 | * local system. If local is specified no target class can be |
57 | * specified. |
58 | * Used for iucv_path_connect. |
59 | * |
60 | * All flags are defined in the input field IPFLAGS1 of each function |
61 | * and can be found in CP Programming Services. |
62 | */ |
63 | #define IUCV_IPRMDATA 0x80 |
64 | #define IUCV_IPQUSCE 0x40 |
65 | #define IUCV_IPBUFLST 0x40 |
66 | #define IUCV_IPPRTY 0x20 |
67 | #define IUCV_IPANSLST 0x08 |
68 | #define IUCV_IPSYNC 0x04 |
69 | #define IUCV_IPLOCAL 0x01 |
70 | |
71 | /* |
72 | * iucv_array : Defines buffer array. |
73 | * Inside the array may be 31- bit addresses and 31-bit lengths. |
74 | * Use a pointer to an iucv_array as the buffer, reply or answer |
75 | * parameter on iucv_message_send, iucv_message_send2way, iucv_message_receive |
76 | * and iucv_message_reply if IUCV_IPBUFLST or IUCV_IPANSLST are used. |
77 | */ |
78 | struct iucv_array { |
79 | u32 address; |
80 | u32 length; |
81 | } __attribute__ ((aligned (8))); |
82 | |
83 | extern struct bus_type iucv_bus; |
84 | extern struct device *iucv_root; |
85 | |
86 | /* |
87 | * struct iucv_path |
88 | * pathid: 16 bit path identification |
89 | * msglim: 16 bit message limit |
90 | * flags: properties of the path: IPRMDATA, IPQUSCE, IPPRTY |
91 | * handler: address of iucv handler structure |
92 | * private: private information of the handler associated with the path |
93 | * list: list_head for the iucv_handler path list. |
94 | */ |
95 | struct iucv_path { |
96 | u16 pathid; |
97 | u16 msglim; |
98 | u8 flags; |
99 | void *private; |
100 | struct iucv_handler *handler; |
101 | struct list_head list; |
102 | }; |
103 | |
104 | /* |
105 | * struct iucv_message |
106 | * id: 32 bit message id |
107 | * audit: 32 bit error information of purged or replied messages |
108 | * class: 32 bit target class of a message (source class for replies) |
109 | * tag: 32 bit tag to be associated with the message |
110 | * length: 32 bit length of the message / reply |
111 | * reply_size: 32 bit maximum allowed length of the reply |
112 | * rmmsg: 8 byte inline message |
113 | * flags: message properties (IUCV_IPPRTY) |
114 | */ |
115 | struct iucv_message { |
116 | u32 id; |
117 | u32 audit; |
118 | u32 class; |
119 | u32 tag; |
120 | u32 length; |
121 | u32 reply_size; |
122 | u8 rmmsg[8]; |
123 | u8 flags; |
124 | } __packed; |
125 | |
126 | /* |
127 | * struct iucv_handler |
128 | * |
129 | * A vector of functions that handle IUCV interrupts. Each functions gets |
130 | * a parameter area as defined by the CP Programming Services and private |
131 | * pointer that is provided by the user of the interface. |
132 | */ |
133 | struct iucv_handler { |
134 | /* |
135 | * The path_pending function is called after an iucv interrupt |
136 | * type 0x01 has been received. The base code allocates a path |
137 | * structure and "asks" the handler if this path belongs to the |
138 | * handler. To accept the path the path_pending function needs |
139 | * to call iucv_path_accept and return 0. If the callback returns |
140 | * a value != 0 the iucv base code will continue with the next |
141 | * handler. The order in which the path_pending functions are |
142 | * called is the order of the registration of the iucv handlers |
143 | * to the base code. |
144 | */ |
145 | int (*path_pending)(struct iucv_path *, u8 *ipvmid, u8 *ipuser); |
146 | /* |
147 | * The path_complete function is called after an iucv interrupt |
148 | * type 0x02 has been received for a path that has been established |
149 | * for this handler with iucv_path_connect and got accepted by the |
150 | * peer with iucv_path_accept. |
151 | */ |
152 | void (*path_complete)(struct iucv_path *, u8 *ipuser); |
153 | /* |
154 | * The path_severed function is called after an iucv interrupt |
155 | * type 0x03 has been received. The communication peer shutdown |
156 | * his end of the communication path. The path still exists and |
157 | * remaining messages can be received until a iucv_path_sever |
158 | * shuts down the other end of the path as well. |
159 | */ |
160 | void (*path_severed)(struct iucv_path *, u8 *ipuser); |
161 | /* |
162 | * The path_quiesced function is called after an icuv interrupt |
163 | * type 0x04 has been received. The communication peer has quiesced |
164 | * the path. Delivery of messages is stopped until iucv_path_resume |
165 | * has been called. |
166 | */ |
167 | void (*path_quiesced)(struct iucv_path *, u8 *ipuser); |
168 | /* |
169 | * The path_resumed function is called after an icuv interrupt |
170 | * type 0x05 has been received. The communication peer has resumed |
171 | * the path. |
172 | */ |
173 | void (*path_resumed)(struct iucv_path *, u8 *ipuser); |
174 | /* |
175 | * The message_pending function is called after an icuv interrupt |
176 | * type 0x06 or type 0x07 has been received. A new message is |
177 | * available and can be received with iucv_message_receive. |
178 | */ |
179 | void (*message_pending)(struct iucv_path *, struct iucv_message *); |
180 | /* |
181 | * The message_complete function is called after an icuv interrupt |
182 | * type 0x08 or type 0x09 has been received. A message send with |
183 | * iucv_message_send2way has been replied to. The reply can be |
184 | * received with iucv_message_receive. |
185 | */ |
186 | void (*message_complete)(struct iucv_path *, struct iucv_message *); |
187 | |
188 | struct list_head list; |
189 | struct list_head paths; |
190 | }; |
191 | |
192 | /** |
193 | * iucv_register: |
194 | * @handler: address of iucv handler structure |
195 | * @smp: != 0 indicates that the handler can deal with out of order messages |
196 | * |
197 | * Registers a driver with IUCV. |
198 | * |
199 | * Returns 0 on success, -ENOMEM if the memory allocation for the pathid |
200 | * table failed, or -EIO if IUCV_DECLARE_BUFFER failed on all cpus. |
201 | */ |
202 | int iucv_register(struct iucv_handler *handler, int smp); |
203 | |
204 | /** |
205 | * iucv_unregister |
206 | * @handler: address of iucv handler structure |
207 | * @smp: != 0 indicates that the handler can deal with out of order messages |
208 | * |
209 | * Unregister driver from IUCV. |
210 | */ |
211 | void iucv_unregister(struct iucv_handler *handle, int smp); |
212 | |
213 | /** |
214 | * iucv_path_alloc |
215 | * @msglim: initial message limit |
216 | * @flags: initial flags |
217 | * @gfp: kmalloc allocation flag |
218 | * |
219 | * Allocate a new path structure for use with iucv_connect. |
220 | * |
221 | * Returns NULL if the memory allocation failed or a pointer to the |
222 | * path structure. |
223 | */ |
224 | static inline struct iucv_path *iucv_path_alloc(u16 msglim, u8 flags, gfp_t gfp) |
225 | { |
226 | struct iucv_path *path; |
227 | |
228 | path = kzalloc(size: sizeof(struct iucv_path), flags: gfp); |
229 | if (path) { |
230 | path->msglim = msglim; |
231 | path->flags = flags; |
232 | } |
233 | return path; |
234 | } |
235 | |
236 | /** |
237 | * iucv_path_free |
238 | * @path: address of iucv path structure |
239 | * |
240 | * Frees a path structure. |
241 | */ |
242 | static inline void iucv_path_free(struct iucv_path *path) |
243 | { |
244 | kfree(objp: path); |
245 | } |
246 | |
247 | /** |
248 | * iucv_path_accept |
249 | * @path: address of iucv path structure |
250 | * @handler: address of iucv handler structure |
251 | * @userdata: 16 bytes of data reflected to the communication partner |
252 | * @private: private data passed to interrupt handlers for this path |
253 | * |
254 | * This function is issued after the user received a connection pending |
255 | * external interrupt and now wishes to complete the IUCV communication path. |
256 | * |
257 | * Returns the result of the CP IUCV call. |
258 | */ |
259 | int iucv_path_accept(struct iucv_path *path, struct iucv_handler *handler, |
260 | u8 *userdata, void *private); |
261 | |
262 | /** |
263 | * iucv_path_connect |
264 | * @path: address of iucv path structure |
265 | * @handler: address of iucv handler structure |
266 | * @userid: 8-byte user identification |
267 | * @system: 8-byte target system identification |
268 | * @userdata: 16 bytes of data reflected to the communication partner |
269 | * @private: private data passed to interrupt handlers for this path |
270 | * |
271 | * This function establishes an IUCV path. Although the connect may complete |
272 | * successfully, you are not able to use the path until you receive an IUCV |
273 | * Connection Complete external interrupt. |
274 | * |
275 | * Returns the result of the CP IUCV call. |
276 | */ |
277 | int iucv_path_connect(struct iucv_path *path, struct iucv_handler *handler, |
278 | u8 *userid, u8 *system, u8 *userdata, |
279 | void *private); |
280 | |
281 | /** |
282 | * iucv_path_quiesce: |
283 | * @path: address of iucv path structure |
284 | * @userdata: 16 bytes of data reflected to the communication partner |
285 | * |
286 | * This function temporarily suspends incoming messages on an IUCV path. |
287 | * You can later reactivate the path by invoking the iucv_resume function. |
288 | * |
289 | * Returns the result from the CP IUCV call. |
290 | */ |
291 | int iucv_path_quiesce(struct iucv_path *path, u8 *userdata); |
292 | |
293 | /** |
294 | * iucv_path_resume: |
295 | * @path: address of iucv path structure |
296 | * @userdata: 16 bytes of data reflected to the communication partner |
297 | * |
298 | * This function resumes incoming messages on an IUCV path that has |
299 | * been stopped with iucv_path_quiesce. |
300 | * |
301 | * Returns the result from the CP IUCV call. |
302 | */ |
303 | int iucv_path_resume(struct iucv_path *path, u8 *userdata); |
304 | |
305 | /** |
306 | * iucv_path_sever |
307 | * @path: address of iucv path structure |
308 | * @userdata: 16 bytes of data reflected to the communication partner |
309 | * |
310 | * This function terminates an IUCV path. |
311 | * |
312 | * Returns the result from the CP IUCV call. |
313 | */ |
314 | int iucv_path_sever(struct iucv_path *path, u8 *userdata); |
315 | |
316 | /** |
317 | * iucv_message_purge |
318 | * @path: address of iucv path structure |
319 | * @msg: address of iucv msg structure |
320 | * @srccls: source class of message |
321 | * |
322 | * Cancels a message you have sent. |
323 | * |
324 | * Returns the result from the CP IUCV call. |
325 | */ |
326 | int iucv_message_purge(struct iucv_path *path, struct iucv_message *msg, |
327 | u32 srccls); |
328 | |
329 | /** |
330 | * iucv_message_receive |
331 | * @path: address of iucv path structure |
332 | * @msg: address of iucv msg structure |
333 | * @flags: flags that affect how the message is received (IUCV_IPBUFLST) |
334 | * @buffer: address of data buffer or address of struct iucv_array |
335 | * @size: length of data buffer |
336 | * @residual: |
337 | * |
338 | * This function receives messages that are being sent to you over |
339 | * established paths. This function will deal with RMDATA messages |
340 | * embedded in struct iucv_message as well. |
341 | * |
342 | * Locking: local_bh_enable/local_bh_disable |
343 | * |
344 | * Returns the result from the CP IUCV call. |
345 | */ |
346 | int iucv_message_receive(struct iucv_path *path, struct iucv_message *msg, |
347 | u8 flags, void *buffer, size_t size, size_t *residual); |
348 | |
349 | /** |
350 | * __iucv_message_receive |
351 | * @path: address of iucv path structure |
352 | * @msg: address of iucv msg structure |
353 | * @flags: flags that affect how the message is received (IUCV_IPBUFLST) |
354 | * @buffer: address of data buffer or address of struct iucv_array |
355 | * @size: length of data buffer |
356 | * @residual: |
357 | * |
358 | * This function receives messages that are being sent to you over |
359 | * established paths. This function will deal with RMDATA messages |
360 | * embedded in struct iucv_message as well. |
361 | * |
362 | * Locking: no locking. |
363 | * |
364 | * Returns the result from the CP IUCV call. |
365 | */ |
366 | int __iucv_message_receive(struct iucv_path *path, struct iucv_message *msg, |
367 | u8 flags, void *buffer, size_t size, |
368 | size_t *residual); |
369 | |
370 | /** |
371 | * iucv_message_reject |
372 | * @path: address of iucv path structure |
373 | * @msg: address of iucv msg structure |
374 | * |
375 | * The reject function refuses a specified message. Between the time you |
376 | * are notified of a message and the time that you complete the message, |
377 | * the message may be rejected. |
378 | * |
379 | * Returns the result from the CP IUCV call. |
380 | */ |
381 | int iucv_message_reject(struct iucv_path *path, struct iucv_message *msg); |
382 | |
383 | /** |
384 | * iucv_message_reply |
385 | * @path: address of iucv path structure |
386 | * @msg: address of iucv msg structure |
387 | * @flags: how the reply is sent (IUCV_IPRMDATA, IUCV_IPPRTY, IUCV_IPBUFLST) |
388 | * @reply: address of data buffer or address of struct iucv_array |
389 | * @size: length of reply data buffer |
390 | * |
391 | * This function responds to the two-way messages that you receive. You |
392 | * must identify completely the message to which you wish to reply. ie, |
393 | * pathid, msgid, and trgcls. Prmmsg signifies the data is moved into |
394 | * the parameter list. |
395 | * |
396 | * Returns the result from the CP IUCV call. |
397 | */ |
398 | int iucv_message_reply(struct iucv_path *path, struct iucv_message *msg, |
399 | u8 flags, void *reply, size_t size); |
400 | |
401 | /** |
402 | * iucv_message_send |
403 | * @path: address of iucv path structure |
404 | * @msg: address of iucv msg structure |
405 | * @flags: how the message is sent (IUCV_IPRMDATA, IUCV_IPPRTY, IUCV_IPBUFLST) |
406 | * @srccls: source class of message |
407 | * @buffer: address of data buffer or address of struct iucv_array |
408 | * @size: length of send buffer |
409 | * |
410 | * This function transmits data to another application. Data to be |
411 | * transmitted is in a buffer and this is a one-way message and the |
412 | * receiver will not reply to the message. |
413 | * |
414 | * Locking: local_bh_enable/local_bh_disable |
415 | * |
416 | * Returns the result from the CP IUCV call. |
417 | */ |
418 | int iucv_message_send(struct iucv_path *path, struct iucv_message *msg, |
419 | u8 flags, u32 srccls, void *buffer, size_t size); |
420 | |
421 | /** |
422 | * __iucv_message_send |
423 | * @path: address of iucv path structure |
424 | * @msg: address of iucv msg structure |
425 | * @flags: how the message is sent (IUCV_IPRMDATA, IUCV_IPPRTY, IUCV_IPBUFLST) |
426 | * @srccls: source class of message |
427 | * @buffer: address of data buffer or address of struct iucv_array |
428 | * @size: length of send buffer |
429 | * |
430 | * This function transmits data to another application. Data to be |
431 | * transmitted is in a buffer and this is a one-way message and the |
432 | * receiver will not reply to the message. |
433 | * |
434 | * Locking: no locking. |
435 | * |
436 | * Returns the result from the CP IUCV call. |
437 | */ |
438 | int __iucv_message_send(struct iucv_path *path, struct iucv_message *msg, |
439 | u8 flags, u32 srccls, void *buffer, size_t size); |
440 | |
441 | /** |
442 | * iucv_message_send2way |
443 | * @path: address of iucv path structure |
444 | * @msg: address of iucv msg structure |
445 | * @flags: how the message is sent and the reply is received |
446 | * (IUCV_IPRMDATA, IUCV_IPBUFLST, IUCV_IPPRTY, IUCV_ANSLST) |
447 | * @srccls: source class of message |
448 | * @buffer: address of data buffer or address of struct iucv_array |
449 | * @size: length of send buffer |
450 | * @ansbuf: address of answer buffer or address of struct iucv_array |
451 | * @asize: size of reply buffer |
452 | * |
453 | * This function transmits data to another application. Data to be |
454 | * transmitted is in a buffer. The receiver of the send is expected to |
455 | * reply to the message and a buffer is provided into which IUCV moves |
456 | * the reply to this message. |
457 | * |
458 | * Returns the result from the CP IUCV call. |
459 | */ |
460 | int iucv_message_send2way(struct iucv_path *path, struct iucv_message *msg, |
461 | u8 flags, u32 srccls, void *buffer, size_t size, |
462 | void *answer, size_t asize, size_t *residual); |
463 | |
464 | struct iucv_interface { |
465 | int (*message_receive)(struct iucv_path *path, struct iucv_message *msg, |
466 | u8 flags, void *buffer, size_t size, size_t *residual); |
467 | int (*__message_receive)(struct iucv_path *path, |
468 | struct iucv_message *msg, u8 flags, void *buffer, size_t size, |
469 | size_t *residual); |
470 | int (*message_reply)(struct iucv_path *path, struct iucv_message *msg, |
471 | u8 flags, void *reply, size_t size); |
472 | int (*message_reject)(struct iucv_path *path, struct iucv_message *msg); |
473 | int (*message_send)(struct iucv_path *path, struct iucv_message *msg, |
474 | u8 flags, u32 srccls, void *buffer, size_t size); |
475 | int (*__message_send)(struct iucv_path *path, struct iucv_message *msg, |
476 | u8 flags, u32 srccls, void *buffer, size_t size); |
477 | int (*message_send2way)(struct iucv_path *path, |
478 | struct iucv_message *msg, u8 flags, u32 srccls, void *buffer, |
479 | size_t size, void *answer, size_t asize, size_t *residual); |
480 | int (*message_purge)(struct iucv_path *path, struct iucv_message *msg, |
481 | u32 srccls); |
482 | int (*path_accept)(struct iucv_path *path, struct iucv_handler *handler, |
483 | u8 userdata[16], void *private); |
484 | int (*path_connect)(struct iucv_path *path, |
485 | struct iucv_handler *handler, |
486 | u8 userid[8], u8 system[8], u8 userdata[16], void *private); |
487 | int (*path_quiesce)(struct iucv_path *path, u8 userdata[16]); |
488 | int (*path_resume)(struct iucv_path *path, u8 userdata[16]); |
489 | int (*path_sever)(struct iucv_path *path, u8 userdata[16]); |
490 | int (*iucv_register)(struct iucv_handler *handler, int smp); |
491 | void (*iucv_unregister)(struct iucv_handler *handler, int smp); |
492 | struct bus_type *bus; |
493 | struct device *root; |
494 | }; |
495 | |
496 | extern struct iucv_interface iucv_if; |
497 | |