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