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 */
25enum {
26	HSI_MODE_STREAM	= 1,
27	HSI_MODE_FRAME,
28};
29
30enum {
31	HSI_FLOW_SYNC,	/* Synchronized flow */
32	HSI_FLOW_PIPE,	/* Pipelined flow */
33};
34
35enum {
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 */
43enum {
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 */
52enum {
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 */
62struct 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 */
77struct 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 */
99struct 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
110extern int hsi_register_board_info(struct hsi_board_info const *info,
111							unsigned int len);
112#else
113static 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 */
126struct 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
138static inline void hsi_client_set_drvdata(struct hsi_client *cl, void *data)
139{
140	dev_set_drvdata(&cl->device, data);
141}
142
143static inline void *hsi_client_drvdata(struct hsi_client *cl)
144{
145	return dev_get_drvdata(&cl->device);
146}
147
148int hsi_register_port_event(struct hsi_client *cl,
149			void (*handler)(struct hsi_client *, unsigned long));
150int 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 */
156struct 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
163int hsi_register_client_driver(struct hsi_client_driver *drv);
164
165static 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 */
185struct 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
201struct hsi_msg *hsi_alloc_msg(unsigned int n_frag, gfp_t flags);
202void 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 */
221struct 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
242int hsi_event(struct hsi_port *port, unsigned long event);
243int hsi_claim_port(struct hsi_client *cl, unsigned int share);
244void hsi_release_port(struct hsi_client *cl);
245
246static inline int hsi_port_claimed(struct hsi_client *cl)
247{
248	return cl->pclaimed;
249}
250
251static inline void hsi_port_set_drvdata(struct hsi_port *port, void *data)
252{
253	dev_set_drvdata(&port->device, data);
254}
255
256static 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 */
269struct 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
279struct hsi_controller *hsi_alloc_controller(unsigned int n_ports, gfp_t flags);
280void hsi_put_controller(struct hsi_controller *hsi);
281int hsi_register_controller(struct hsi_controller *hsi);
282void hsi_unregister_controller(struct hsi_controller *hsi);
283struct hsi_client *hsi_new_client(struct hsi_port *port,
284						struct hsi_board_info *info);
285int hsi_remove_client(struct device *dev, void *data);
286void hsi_port_unregister_clients(struct hsi_port *port);
287
288#ifdef CONFIG_OF
289void hsi_add_clients_from_dt(struct hsi_port *port,
290			     struct device_node *clients);
291#else
292static inline void hsi_add_clients_from_dt(struct hsi_port *port,
293					   struct device_node *clients)
294{
295	return;
296}
297#endif
298
299static inline void hsi_controller_set_drvdata(struct hsi_controller *hsi,
300								void *data)
301{
302	dev_set_drvdata(&hsi->device, data);
303}
304
305static inline void *hsi_controller_drvdata(struct hsi_controller *hsi)
306{
307	return dev_get_drvdata(&hsi->device);
308}
309
310static 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 */
319int hsi_async(struct hsi_client *cl, struct hsi_msg *msg);
320
321int 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 */
329static 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 */
340static 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 */
354static 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 */
370static 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 */
384static 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 */
397static 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 */
409static 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 */
422static 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