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