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 further 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
86 struct device_driver;
87
88 struct device *iucv_alloc_device(const struct attribute_group **attrs,
89 struct device_driver *driver, void *priv,
90 const char *fmt, ...) __printf(4, 5);
91
92 /*
93 * struct iucv_path
94 * pathid: 16 bit path identification
95 * msglim: 16 bit message limit
96 * flags: properties of the path: IPRMDATA, IPQUSCE, IPPRTY
97 * handler: address of iucv handler structure
98 * private: private information of the handler associated with the path
99 * list: list_head for the iucv_handler path list.
100 */
101 struct iucv_path {
102 u16 pathid;
103 u16 msglim;
104 u8 flags;
105 void *private;
106 struct iucv_handler *handler;
107 struct list_head list;
108 };
109
110 /*
111 * struct iucv_message
112 * id: 32 bit message id
113 * audit: 32 bit error information of purged or replied messages
114 * class: 32 bit target class of a message (source class for replies)
115 * tag: 32 bit tag to be associated with the message
116 * length: 32 bit length of the message / reply
117 * reply_size: 32 bit maximum allowed length of the reply
118 * rmmsg: 8 byte inline message
119 * flags: message properties (IUCV_IPPRTY)
120 */
121 struct iucv_message {
122 u32 id;
123 u32 audit;
124 u32 class;
125 u32 tag;
126 u32 length;
127 u32 reply_size;
128 u8 rmmsg[8];
129 u8 flags;
130 } __packed;
131
132 /*
133 * struct iucv_handler
134 *
135 * A vector of functions that handle IUCV interrupts. Each functions gets
136 * a parameter area as defined by the CP Programming Services and private
137 * pointer that is provided by the user of the interface.
138 */
139 struct iucv_handler {
140 /*
141 * The path_pending function is called after an iucv interrupt
142 * type 0x01 has been received. The base code allocates a path
143 * structure and "asks" the handler if this path belongs to the
144 * handler. To accept the path the path_pending function needs
145 * to call iucv_path_accept and return 0. If the callback returns
146 * a value != 0 the iucv base code will continue with the next
147 * handler. The order in which the path_pending functions are
148 * called is the order of the registration of the iucv handlers
149 * to the base code.
150 */
151 int (*path_pending)(struct iucv_path *, u8 *ipvmid, u8 *ipuser);
152 /*
153 * The path_complete function is called after an iucv interrupt
154 * type 0x02 has been received for a path that has been established
155 * for this handler with iucv_path_connect and got accepted by the
156 * peer with iucv_path_accept.
157 */
158 void (*path_complete)(struct iucv_path *, u8 *ipuser);
159 /*
160 * The path_severed function is called after an iucv interrupt
161 * type 0x03 has been received. The communication peer shutdown
162 * his end of the communication path. The path still exists and
163 * remaining messages can be received until a iucv_path_sever
164 * shuts down the other end of the path as well.
165 */
166 void (*path_severed)(struct iucv_path *, u8 *ipuser);
167 /*
168 * The path_quiesced function is called after an icuv interrupt
169 * type 0x04 has been received. The communication peer has quiesced
170 * the path. Delivery of messages is stopped until iucv_path_resume
171 * has been called.
172 */
173 void (*path_quiesced)(struct iucv_path *, u8 *ipuser);
174 /*
175 * The path_resumed function is called after an icuv interrupt
176 * type 0x05 has been received. The communication peer has resumed
177 * the path.
178 */
179 void (*path_resumed)(struct iucv_path *, u8 *ipuser);
180 /*
181 * The message_pending function is called after an icuv interrupt
182 * type 0x06 or type 0x07 has been received. A new message is
183 * available and can be received with iucv_message_receive.
184 */
185 void (*message_pending)(struct iucv_path *, struct iucv_message *);
186 /*
187 * The message_complete function is called after an icuv interrupt
188 * type 0x08 or type 0x09 has been received. A message send with
189 * iucv_message_send2way has been replied to. The reply can be
190 * received with iucv_message_receive.
191 */
192 void (*message_complete)(struct iucv_path *, struct iucv_message *);
193
194 struct list_head list;
195 struct list_head paths;
196 };
197
198 int iucv_register(struct iucv_handler *handler, int smp);
199 void iucv_unregister(struct iucv_handler *handler, int smp);
200
201 /**
202 * iucv_path_alloc - Allocate a new path structure for use with iucv_connect.
203 * @msglim: initial message limit
204 * @flags: initial flags
205 * @gfp: kmalloc allocation flag
206 *
207 * Returns: NULL if the memory allocation failed or a pointer to the
208 * path structure.
209 */
iucv_path_alloc(u16 msglim,u8 flags,gfp_t gfp)210 static inline struct iucv_path *iucv_path_alloc(u16 msglim, u8 flags, gfp_t gfp)
211 {
212 struct iucv_path *path;
213
214 path = kzalloc_obj(struct iucv_path, gfp);
215 if (path) {
216 path->msglim = msglim;
217 path->flags = flags;
218 }
219 return path;
220 }
221
222 /**
223 * iucv_path_free - Frees a path structure.
224 * @path: address of iucv path structure
225 */
iucv_path_free(struct iucv_path * path)226 static inline void iucv_path_free(struct iucv_path *path)
227 {
228 kfree(path);
229 }
230
231 int iucv_path_accept(struct iucv_path *path, struct iucv_handler *handler,
232 u8 *userdata, void *private);
233
234 int iucv_path_connect(struct iucv_path *path, struct iucv_handler *handler,
235 u8 *userid, u8 *system, u8 *userdata,
236 void *private);
237
238 int iucv_path_quiesce(struct iucv_path *path, u8 *userdata);
239
240 int iucv_path_resume(struct iucv_path *path, u8 *userdata);
241
242 int iucv_path_sever(struct iucv_path *path, u8 *userdata);
243
244 int iucv_message_purge(struct iucv_path *path, struct iucv_message *msg,
245 u32 srccls);
246
247 int iucv_message_receive(struct iucv_path *path, struct iucv_message *msg,
248 u8 flags, void *buffer, size_t size, size_t *residual);
249
250 int __iucv_message_receive(struct iucv_path *path, struct iucv_message *msg,
251 u8 flags, void *buffer, size_t size,
252 size_t *residual);
253
254 int iucv_message_reject(struct iucv_path *path, struct iucv_message *msg);
255
256 int iucv_message_reply(struct iucv_path *path, struct iucv_message *msg,
257 u8 flags, void *reply, size_t size);
258
259 int iucv_message_send(struct iucv_path *path, struct iucv_message *msg,
260 u8 flags, u32 srccls, void *buffer, size_t size);
261
262 int __iucv_message_send(struct iucv_path *path, struct iucv_message *msg,
263 u8 flags, u32 srccls, void *buffer, size_t size);
264
265 int iucv_message_send2way(struct iucv_path *path, struct iucv_message *msg,
266 u8 flags, u32 srccls, void *buffer, size_t size,
267 void *answer, size_t asize, size_t *residual);
268
269 struct iucv_interface {
270 int (*message_receive)(struct iucv_path *path, struct iucv_message *msg,
271 u8 flags, void *buffer, size_t size, size_t *residual);
272 int (*__message_receive)(struct iucv_path *path,
273 struct iucv_message *msg, u8 flags, void *buffer, size_t size,
274 size_t *residual);
275 int (*message_reply)(struct iucv_path *path, struct iucv_message *msg,
276 u8 flags, void *reply, size_t size);
277 int (*message_reject)(struct iucv_path *path, struct iucv_message *msg);
278 int (*message_send)(struct iucv_path *path, struct iucv_message *msg,
279 u8 flags, u32 srccls, void *buffer, size_t size);
280 int (*__message_send)(struct iucv_path *path, struct iucv_message *msg,
281 u8 flags, u32 srccls, void *buffer, size_t size);
282 int (*message_send2way)(struct iucv_path *path,
283 struct iucv_message *msg, u8 flags, u32 srccls, void *buffer,
284 size_t size, void *answer, size_t asize, size_t *residual);
285 int (*message_purge)(struct iucv_path *path, struct iucv_message *msg,
286 u32 srccls);
287 int (*path_accept)(struct iucv_path *path, struct iucv_handler *handler,
288 u8 userdata[16], void *private);
289 int (*path_connect)(struct iucv_path *path,
290 struct iucv_handler *handler,
291 u8 userid[8], u8 system[8], u8 userdata[16], void *private);
292 int (*path_quiesce)(struct iucv_path *path, u8 userdata[16]);
293 int (*path_resume)(struct iucv_path *path, u8 userdata[16]);
294 int (*path_sever)(struct iucv_path *path, u8 userdata[16]);
295 int (*iucv_register)(struct iucv_handler *handler, int smp);
296 void (*iucv_unregister)(struct iucv_handler *handler, int smp);
297 const struct bus_type *bus;
298 struct device *root;
299 };
300
301 extern struct iucv_interface iucv_if;
302