xref: /openbmc/linux/include/linux/hsi/hsi.h (revision 2b27bdcc)
1 /* SPDX-License-Identifier: GPL-2.0-only */
2 /*
3  * HSI core header file.
4  *
5  * Copyright (C) 2010 Nokia Corporation. All rights reserved.
6  *
7  * Contact: Carlos Chinea <carlos.chinea@nokia.com>
8  */
9 
10 #ifndef __LINUX_HSI_H__
11 #define __LINUX_HSI_H__
12 
13 #include <linux/device.h>
14 #include <linux/mutex.h>
15 #include <linux/scatterlist.h>
16 #include <linux/list.h>
17 #include <linux/module.h>
18 #include <linux/notifier.h>
19 
20 /* HSI message ttype */
21 #define HSI_MSG_READ	0
22 #define HSI_MSG_WRITE	1
23 
24 /* HSI configuration values */
25 enum {
26 	HSI_MODE_STREAM	= 1,
27 	HSI_MODE_FRAME,
28 };
29 
30 enum {
31 	HSI_FLOW_SYNC,	/* Synchronized flow */
32 	HSI_FLOW_PIPE,	/* Pipelined flow */
33 };
34 
35 enum {
36 	HSI_ARB_RR,	/* Round-robin arbitration */
37 	HSI_ARB_PRIO,	/* Channel priority arbitration */
38 };
39 
40 #define HSI_MAX_CHANNELS	16
41 
42 /* HSI message status codes */
43 enum {
44 	HSI_STATUS_COMPLETED,	/* Message transfer is completed */
45 	HSI_STATUS_PENDING,	/* Message pending to be read/write (POLL) */
46 	HSI_STATUS_PROCEEDING,	/* Message transfer is ongoing */
47 	HSI_STATUS_QUEUED,	/* Message waiting to be served */
48 	HSI_STATUS_ERROR,	/* Error when message transfer was ongoing */
49 };
50 
51 /* HSI port event codes */
52 enum {
53 	HSI_EVENT_START_RX,
54 	HSI_EVENT_STOP_RX,
55 };
56 
57 /**
58  * struct hsi_channel - channel resource used by the hsi clients
59  * @id: Channel number
60  * @name: Channel name
61  */
62 struct hsi_channel {
63 	unsigned int	id;
64 	const char	*name;
65 };
66 
67 /**
68  * struct hsi_config - Configuration for RX/TX HSI modules
69  * @mode: Bit transmission mode (STREAM or FRAME)
70  * @channels: Channel resources used by the client
71  * @num_channels: Number of channel resources
72  * @num_hw_channels: Number of channels the transceiver is configured for [1..16]
73  * @speed: Max bit transmission speed (Kbit/s)
74  * @flow: RX flow type (SYNCHRONIZED or PIPELINE)
75  * @arb_mode: Arbitration mode for TX frame (Round robin, priority)
76  */
77 struct hsi_config {
78 	unsigned int		mode;
79 	struct hsi_channel	*channels;
80 	unsigned int		num_channels;
81 	unsigned int		num_hw_channels;
82 	unsigned int		speed;
83 	union {
84 		unsigned int	flow;		/* RX only */
85 		unsigned int	arb_mode;	/* TX only */
86 	};
87 };
88 
89 /**
90  * struct hsi_board_info - HSI client board info
91  * @name: Name for the HSI device
92  * @hsi_id: HSI controller id where the client sits
93  * @port: Port number in the controller where the client sits
94  * @tx_cfg: HSI TX configuration
95  * @rx_cfg: HSI RX configuration
96  * @platform_data: Platform related data
97  * @archdata: Architecture-dependent device data
98  */
99 struct hsi_board_info {
100 	const char		*name;
101 	unsigned int		hsi_id;
102 	unsigned int		port;
103 	struct hsi_config	tx_cfg;
104 	struct hsi_config	rx_cfg;
105 	void			*platform_data;
106 	struct dev_archdata	*archdata;
107 };
108 
109 #ifdef CONFIG_HSI_BOARDINFO
110 extern int hsi_register_board_info(struct hsi_board_info const *info,
111 							unsigned int len);
112 #else
hsi_register_board_info(struct hsi_board_info const * info,unsigned int len)113 static inline int hsi_register_board_info(struct hsi_board_info const *info,
114 							unsigned int len)
115 {
116 	return 0;
117 }
118 #endif /* CONFIG_HSI_BOARDINFO */
119 
120 /**
121  * struct hsi_client - HSI client attached to an HSI port
122  * @device: Driver model representation of the device
123  * @tx_cfg: HSI TX configuration
124  * @rx_cfg: HSI RX configuration
125  */
126 struct hsi_client {
127 	struct device		device;
128 	struct hsi_config	tx_cfg;
129 	struct hsi_config	rx_cfg;
130 	/* private: */
131 	void			(*ehandler)(struct hsi_client *, unsigned long);
132 	unsigned int		pclaimed:1;
133 	struct notifier_block	nb;
134 };
135 
136 #define to_hsi_client(dev) container_of(dev, struct hsi_client, device)
137 
hsi_client_set_drvdata(struct hsi_client * cl,void * data)138 static inline void hsi_client_set_drvdata(struct hsi_client *cl, void *data)
139 {
140 	dev_set_drvdata(&cl->device, data);
141 }
142 
hsi_client_drvdata(struct hsi_client * cl)143 static inline void *hsi_client_drvdata(struct hsi_client *cl)
144 {
145 	return dev_get_drvdata(&cl->device);
146 }
147 
148 int hsi_register_port_event(struct hsi_client *cl,
149 			void (*handler)(struct hsi_client *, unsigned long));
150 int hsi_unregister_port_event(struct hsi_client *cl);
151 
152 /**
153  * struct hsi_client_driver - Driver associated to an HSI client
154  * @driver: Driver model representation of the driver
155  */
156 struct hsi_client_driver {
157 	struct device_driver	driver;
158 };
159 
160 #define to_hsi_client_driver(drv) container_of(drv, struct hsi_client_driver,\
161 									driver)
162 
163 int hsi_register_client_driver(struct hsi_client_driver *drv);
164 
hsi_unregister_client_driver(struct hsi_client_driver * drv)165 static inline void hsi_unregister_client_driver(struct hsi_client_driver *drv)
166 {
167 	driver_unregister(&drv->driver);
168 }
169 
170 /**
171  * struct hsi_msg - HSI message descriptor
172  * @link: Free to use by the current descriptor owner
173  * @cl: HSI device client that issues the transfer
174  * @sgt: Head of the scatterlist array
175  * @context: Client context data associated to the transfer
176  * @complete: Transfer completion callback
177  * @destructor: Destructor to free resources when flushing
178  * @status: Status of the transfer when completed
179  * @actual_len: Actual length of data transferred on completion
180  * @channel: Channel were to TX/RX the message
181  * @ttype: Transfer type (TX if set, RX otherwise)
182  * @break_frame: if true HSI will send/receive a break frame. Data buffers are
183  *		ignored in the request.
184  */
185 struct hsi_msg {
186 	struct list_head	link;
187 	struct hsi_client	*cl;
188 	struct sg_table		sgt;
189 	void			*context;
190 
191 	void			(*complete)(struct hsi_msg *msg);
192 	void			(*destructor)(struct hsi_msg *msg);
193 
194 	int			status;
195 	unsigned int		actual_len;
196 	unsigned int		channel;
197 	unsigned int		ttype:1;
198 	unsigned int		break_frame:1;
199 };
200 
201 struct hsi_msg *hsi_alloc_msg(unsigned int n_frag, gfp_t flags);
202 void hsi_free_msg(struct hsi_msg *msg);
203 
204 /**
205  * struct hsi_port - HSI port device
206  * @device: Driver model representation of the device
207  * @tx_cfg: Current TX path configuration
208  * @rx_cfg: Current RX path configuration
209  * @num: Port number
210  * @shared: Set when port can be shared by different clients
211  * @claimed: Reference count of clients which claimed the port
212  * @lock: Serialize port claim
213  * @async: Asynchronous transfer callback
214  * @setup: Callback to set the HSI client configuration
215  * @flush: Callback to clean the HW state and destroy all pending transfers
216  * @start_tx: Callback to inform that a client wants to TX data
217  * @stop_tx: Callback to inform that a client no longer wishes to TX data
218  * @release: Callback to inform that a client no longer uses the port
219  * @n_head: Notifier chain for signaling port events to the clients.
220  */
221 struct hsi_port {
222 	struct device			device;
223 	struct hsi_config		tx_cfg;
224 	struct hsi_config		rx_cfg;
225 	unsigned int			num;
226 	unsigned int			shared:1;
227 	int				claimed;
228 	struct mutex			lock;
229 	int				(*async)(struct hsi_msg *msg);
230 	int				(*setup)(struct hsi_client *cl);
231 	int				(*flush)(struct hsi_client *cl);
232 	int				(*start_tx)(struct hsi_client *cl);
233 	int				(*stop_tx)(struct hsi_client *cl);
234 	int				(*release)(struct hsi_client *cl);
235 	/* private */
236 	struct blocking_notifier_head	n_head;
237 };
238 
239 #define to_hsi_port(dev) container_of(dev, struct hsi_port, device)
240 #define hsi_get_port(cl) to_hsi_port((cl)->device.parent)
241 
242 int hsi_event(struct hsi_port *port, unsigned long event);
243 int hsi_claim_port(struct hsi_client *cl, unsigned int share);
244 void hsi_release_port(struct hsi_client *cl);
245 
hsi_port_claimed(struct hsi_client * cl)246 static inline int hsi_port_claimed(struct hsi_client *cl)
247 {
248 	return cl->pclaimed;
249 }
250 
hsi_port_set_drvdata(struct hsi_port * port,void * data)251 static inline void hsi_port_set_drvdata(struct hsi_port *port, void *data)
252 {
253 	dev_set_drvdata(&port->device, data);
254 }
255 
hsi_port_drvdata(struct hsi_port * port)256 static inline void *hsi_port_drvdata(struct hsi_port *port)
257 {
258 	return dev_get_drvdata(&port->device);
259 }
260 
261 /**
262  * struct hsi_controller - HSI controller device
263  * @device: Driver model representation of the device
264  * @owner: Pointer to the module owning the controller
265  * @id: HSI controller ID
266  * @num_ports: Number of ports in the HSI controller
267  * @port: Array of HSI ports
268  */
269 struct hsi_controller {
270 	struct device		device;
271 	struct module		*owner;
272 	unsigned int		id;
273 	unsigned int		num_ports;
274 	struct hsi_port		**port;
275 };
276 
277 #define to_hsi_controller(dev) container_of(dev, struct hsi_controller, device)
278 
279 struct hsi_controller *hsi_alloc_controller(unsigned int n_ports, gfp_t flags);
280 void hsi_put_controller(struct hsi_controller *hsi);
281 int hsi_register_controller(struct hsi_controller *hsi);
282 void hsi_unregister_controller(struct hsi_controller *hsi);
283 struct hsi_client *hsi_new_client(struct hsi_port *port,
284 						struct hsi_board_info *info);
285 int hsi_remove_client(struct device *dev, void *data);
286 void hsi_port_unregister_clients(struct hsi_port *port);
287 
288 #ifdef CONFIG_OF
289 void hsi_add_clients_from_dt(struct hsi_port *port,
290 			     struct device_node *clients);
291 #else
hsi_add_clients_from_dt(struct hsi_port * port,struct device_node * clients)292 static inline void hsi_add_clients_from_dt(struct hsi_port *port,
293 					   struct device_node *clients)
294 {
295 	return;
296 }
297 #endif
298 
hsi_controller_set_drvdata(struct hsi_controller * hsi,void * data)299 static inline void hsi_controller_set_drvdata(struct hsi_controller *hsi,
300 								void *data)
301 {
302 	dev_set_drvdata(&hsi->device, data);
303 }
304 
hsi_controller_drvdata(struct hsi_controller * hsi)305 static inline void *hsi_controller_drvdata(struct hsi_controller *hsi)
306 {
307 	return dev_get_drvdata(&hsi->device);
308 }
309 
hsi_find_port_num(struct hsi_controller * hsi,unsigned int num)310 static inline struct hsi_port *hsi_find_port_num(struct hsi_controller *hsi,
311 							unsigned int num)
312 {
313 	return (num < hsi->num_ports) ? hsi->port[num] : NULL;
314 }
315 
316 /*
317  * API for HSI clients
318  */
319 int hsi_async(struct hsi_client *cl, struct hsi_msg *msg);
320 
321 int hsi_get_channel_id_by_name(struct hsi_client *cl, char *name);
322 
323 /**
324  * hsi_id - Get HSI controller ID associated to a client
325  * @cl: Pointer to a HSI client
326  *
327  * Return the controller id where the client is attached to
328  */
hsi_id(struct hsi_client * cl)329 static inline unsigned int hsi_id(struct hsi_client *cl)
330 {
331 	return	to_hsi_controller(cl->device.parent->parent)->id;
332 }
333 
334 /**
335  * hsi_port_id - Gets the port number a client is attached to
336  * @cl: Pointer to HSI client
337  *
338  * Return the port number associated to the client
339  */
hsi_port_id(struct hsi_client * cl)340 static inline unsigned int hsi_port_id(struct hsi_client *cl)
341 {
342 	return	to_hsi_port(cl->device.parent)->num;
343 }
344 
345 /**
346  * hsi_setup - Configure the client's port
347  * @cl: Pointer to the HSI client
348  *
349  * When sharing ports, clients should either relay on a single
350  * client setup or have the same setup for all of them.
351  *
352  * Return -errno on failure, 0 on success
353  */
hsi_setup(struct hsi_client * cl)354 static inline int hsi_setup(struct hsi_client *cl)
355 {
356 	if (!hsi_port_claimed(cl))
357 		return -EACCES;
358 	return	hsi_get_port(cl)->setup(cl);
359 }
360 
361 /**
362  * hsi_flush - Flush all pending transactions on the client's port
363  * @cl: Pointer to the HSI client
364  *
365  * This function will destroy all pending hsi_msg in the port and reset
366  * the HW port so it is ready to receive and transmit from a clean state.
367  *
368  * Return -errno on failure, 0 on success
369  */
hsi_flush(struct hsi_client * cl)370 static inline int hsi_flush(struct hsi_client *cl)
371 {
372 	if (!hsi_port_claimed(cl))
373 		return -EACCES;
374 	return hsi_get_port(cl)->flush(cl);
375 }
376 
377 /**
378  * hsi_async_read - Submit a read transfer
379  * @cl: Pointer to the HSI client
380  * @msg: HSI message descriptor of the transfer
381  *
382  * Return -errno on failure, 0 on success
383  */
hsi_async_read(struct hsi_client * cl,struct hsi_msg * msg)384 static inline int hsi_async_read(struct hsi_client *cl, struct hsi_msg *msg)
385 {
386 	msg->ttype = HSI_MSG_READ;
387 	return hsi_async(cl, msg);
388 }
389 
390 /**
391  * hsi_async_write - Submit a write transfer
392  * @cl: Pointer to the HSI client
393  * @msg: HSI message descriptor of the transfer
394  *
395  * Return -errno on failure, 0 on success
396  */
hsi_async_write(struct hsi_client * cl,struct hsi_msg * msg)397 static inline int hsi_async_write(struct hsi_client *cl, struct hsi_msg *msg)
398 {
399 	msg->ttype = HSI_MSG_WRITE;
400 	return hsi_async(cl, msg);
401 }
402 
403 /**
404  * hsi_start_tx - Signal the port that the client wants to start a TX
405  * @cl: Pointer to the HSI client
406  *
407  * Return -errno on failure, 0 on success
408  */
hsi_start_tx(struct hsi_client * cl)409 static inline int hsi_start_tx(struct hsi_client *cl)
410 {
411 	if (!hsi_port_claimed(cl))
412 		return -EACCES;
413 	return hsi_get_port(cl)->start_tx(cl);
414 }
415 
416 /**
417  * hsi_stop_tx - Signal the port that the client no longer wants to transmit
418  * @cl: Pointer to the HSI client
419  *
420  * Return -errno on failure, 0 on success
421  */
hsi_stop_tx(struct hsi_client * cl)422 static inline int hsi_stop_tx(struct hsi_client *cl)
423 {
424 	if (!hsi_port_claimed(cl))
425 		return -EACCES;
426 	return hsi_get_port(cl)->stop_tx(cl);
427 }
428 #endif /* __LINUX_HSI_H__ */
429