1/* SPDX-License-Identifier: GPL-2.0-only */
 2/*
 3 * FSI master definitions. These comprise the core <--> master interface,
 4 * to allow the core to interact with the (hardware-specific) masters.
 5 *
 6 * Copyright (C) IBM Corporation 2016
 7 */
 8
 9#ifndef DRIVERS_FSI_MASTER_H
10#define DRIVERS_FSI_MASTER_H
11
12#include <linux/device.h>
13#include <linux/mutex.h>
14
15/* Various protocol delays */
16#define	FSI_ECHO_DELAY_CLOCKS	16	/* Number clocks for echo delay */
17#define	FSI_SEND_DELAY_CLOCKS	16	/* Number clocks for send delay */
18#define	FSI_PRE_BREAK_CLOCKS	50	/* Number clocks to prep for break */
19#define	FSI_BREAK_CLOCKS	256	/* Number of clocks to issue break */
20#define	FSI_POST_BREAK_CLOCKS	16000	/* Number clocks to set up cfam */
21#define	FSI_INIT_CLOCKS		5000	/* Clock out any old data */
22#define	FSI_MASTER_DPOLL_CLOCKS	50      /* < 21 will cause slave to hang */
23#define	FSI_MASTER_EPOLL_CLOCKS	50      /* Number of clocks for E_POLL retry */
24
25/* Various retry maximums */
26#define FSI_CRC_ERR_RETRIES	10
27#define	FSI_MASTER_MAX_BUSY	200
28#define	FSI_MASTER_MTOE_COUNT	1000
29
30/* Command encodings */
31#define	FSI_CMD_DPOLL		0x2
32#define	FSI_CMD_EPOLL		0x3
33#define	FSI_CMD_TERM		0x3f
34#define FSI_CMD_ABS_AR		0x4
35#define FSI_CMD_REL_AR		0x5
36#define FSI_CMD_SAME_AR		0x3	/* but only a 2-bit opcode... */
37
38/* Slave responses */
39#define	FSI_RESP_ACK		0	/* Success */
40#define	FSI_RESP_BUSY		1	/* Slave busy */
41#define	FSI_RESP_ERRA		2	/* Any (misc) Error */
42#define	FSI_RESP_ERRC		3	/* Slave reports master CRC error */
43
44/* Misc */
45#define	FSI_CRC_SIZE		4
46
47/* fsi-master definition and flags */
48#define FSI_MASTER_FLAG_SWCLOCK		0x1
49
50struct fsi_master {
51	struct device	dev;
52	int		idx;
53	int		n_links;
54	int		flags;
55	struct mutex	scan_lock;
56	int		(*read)(struct fsi_master *, int link, uint8_t id,
57				uint32_t addr, void *val, size_t size);
58	int		(*write)(struct fsi_master *, int link, uint8_t id,
59				uint32_t addr, const void *val, size_t size);
60	int		(*term)(struct fsi_master *, int link, uint8_t id);
61	int		(*send_break)(struct fsi_master *, int link);
62	int		(*link_enable)(struct fsi_master *, int link);
63	int		(*link_config)(struct fsi_master *, int link,
64				       u8 t_send_delay, u8 t_echo_delay);
65};
66
67#define dev_to_fsi_master(d) container_of(d, struct fsi_master, dev)
68
69/**
70 * fsi_master registration & lifetime: the fsi_master_register() and
71 * fsi_master_unregister() functions will take ownership of the master, and
72 * ->dev in particular. The registration path performs a get_device(), which
73 * takes the first reference on the device. Similarly, the unregistration path
74 * performs a put_device(), which may well drop the last reference.
75 *
76 * This means that master implementations *may* need to hold their own
77 * reference (via get_device()) on master->dev. In particular, if the device's
78 * ->release callback frees the fsi_master, then fsi_master_unregister will
79 * invoke this free if no other reference is held.
80 *
81 * The same applies for the error path of fsi_master_register; if the call
82 * fails, dev->release will have been invoked.
83 */
84extern int fsi_master_register(struct fsi_master *master);
85extern void fsi_master_unregister(struct fsi_master *master);
86
87extern int fsi_master_rescan(struct fsi_master *master);
88
89#endif /* DRIVERS_FSI_MASTER_H */