Merge tag 'libnvdimm-for-5.11' of git://git.kernel.org/pub/scm/linux/kernel/git/nvdim...
[platform/kernel/linux-rpi.git] / drivers / slimbus / slimbus.h
1 /* SPDX-License-Identifier: GPL-2.0 */
2 /*
3  * Copyright (c) 2011-2017, The Linux Foundation
4  */
5
6 #ifndef _DRIVERS_SLIMBUS_H
7 #define _DRIVERS_SLIMBUS_H
8 #include <linux/module.h>
9 #include <linux/device.h>
10 #include <linux/mutex.h>
11 #include <linux/completion.h>
12 #include <linux/slimbus.h>
13
14 /* Standard values per SLIMbus spec needed by controllers and devices */
15 #define SLIM_CL_PER_SUPERFRAME          6144
16 #define SLIM_CL_PER_SUPERFRAME_DIV8     (SLIM_CL_PER_SUPERFRAME >> 3)
17
18 /* SLIMbus message types. Related to interpretation of message code. */
19 #define SLIM_MSG_MT_CORE                        0x0
20 #define SLIM_MSG_MT_DEST_REFERRED_USER          0x2
21 #define SLIM_MSG_MT_SRC_REFERRED_USER           0x6
22
23 /*
24  * SLIM Broadcast header format
25  * BYTE 0: MT[7:5] RL[4:0]
26  * BYTE 1: RSVD[7] MC[6:0]
27  * BYTE 2: RSVD[7:6] DT[5:4] PI[3:0]
28  */
29 #define SLIM_MSG_MT_MASK        GENMASK(2, 0)
30 #define SLIM_MSG_MT_SHIFT       5
31 #define SLIM_MSG_RL_MASK        GENMASK(4, 0)
32 #define SLIM_MSG_RL_SHIFT       0
33 #define SLIM_MSG_MC_MASK        GENMASK(6, 0)
34 #define SLIM_MSG_MC_SHIFT       0
35 #define SLIM_MSG_DT_MASK        GENMASK(1, 0)
36 #define SLIM_MSG_DT_SHIFT       4
37
38 #define SLIM_HEADER_GET_MT(b)   ((b >> SLIM_MSG_MT_SHIFT) & SLIM_MSG_MT_MASK)
39 #define SLIM_HEADER_GET_RL(b)   ((b >> SLIM_MSG_RL_SHIFT) & SLIM_MSG_RL_MASK)
40 #define SLIM_HEADER_GET_MC(b)   ((b >> SLIM_MSG_MC_SHIFT) & SLIM_MSG_MC_MASK)
41 #define SLIM_HEADER_GET_DT(b)   ((b >> SLIM_MSG_DT_SHIFT) & SLIM_MSG_DT_MASK)
42
43 /* Device management messages used by this framework */
44 #define SLIM_MSG_MC_REPORT_PRESENT               0x1
45 #define SLIM_MSG_MC_ASSIGN_LOGICAL_ADDRESS       0x2
46 #define SLIM_MSG_MC_REPORT_ABSENT                0xF
47
48 /* Data channel management messages */
49 #define SLIM_MSG_MC_CONNECT_SOURCE              0x10
50 #define SLIM_MSG_MC_CONNECT_SINK                0x11
51 #define SLIM_MSG_MC_DISCONNECT_PORT             0x14
52 #define SLIM_MSG_MC_CHANGE_CONTENT              0x18
53
54 /* Clock pause Reconfiguration messages */
55 #define SLIM_MSG_MC_BEGIN_RECONFIGURATION        0x40
56 #define SLIM_MSG_MC_NEXT_PAUSE_CLOCK             0x4A
57 #define SLIM_MSG_MC_NEXT_DEFINE_CHANNEL          0x50
58 #define SLIM_MSG_MC_NEXT_DEFINE_CONTENT          0x51
59 #define SLIM_MSG_MC_NEXT_ACTIVATE_CHANNEL        0x54
60 #define SLIM_MSG_MC_NEXT_DEACTIVATE_CHANNEL      0x55
61 #define SLIM_MSG_MC_NEXT_REMOVE_CHANNEL          0x58
62 #define SLIM_MSG_MC_RECONFIGURE_NOW              0x5F
63
64 /* Clock pause values per SLIMbus spec */
65 #define SLIM_CLK_FAST                           0
66 #define SLIM_CLK_CONST_PHASE                    1
67 #define SLIM_CLK_UNSPECIFIED                    2
68
69 /* Destination type Values */
70 #define SLIM_MSG_DEST_LOGICALADDR       0
71 #define SLIM_MSG_DEST_ENUMADDR          1
72 #define SLIM_MSG_DEST_BROADCAST         3
73
74 /* Standard values per SLIMbus spec needed by controllers and devices */
75 #define SLIM_MAX_CLK_GEAR               10
76 #define SLIM_MIN_CLK_GEAR               1
77 #define SLIM_SLOT_LEN_BITS              4
78
79 /* Indicate that the frequency of the flow and the bus frequency are locked */
80 #define SLIM_CHANNEL_CONTENT_FL         BIT(7)
81
82 /* Standard values per SLIMbus spec needed by controllers and devices */
83 #define SLIM_CL_PER_SUPERFRAME          6144
84 #define SLIM_SLOTS_PER_SUPERFRAME       (SLIM_CL_PER_SUPERFRAME >> 2)
85 #define SLIM_SL_PER_SUPERFRAME          (SLIM_CL_PER_SUPERFRAME >> 2)
86 /* Manager's logical address is set to 0xFF per spec */
87 #define SLIM_LA_MANAGER 0xFF
88
89 #define SLIM_MAX_TIDS                   256
90 /**
91  * struct slim_framer - Represents SLIMbus framer.
92  * Every controller may have multiple framers. There is 1 active framer device
93  * responsible for clocking the bus.
94  * Manager is responsible for framer hand-over.
95  * @dev: Driver model representation of the device.
96  * @e_addr: Enumeration address of the framer.
97  * @rootfreq: Root Frequency at which the framer can run. This is maximum
98  *      frequency ('clock gear 10') at which the bus can operate.
99  * @superfreq: Superframes per root frequency. Every frame is 6144 bits.
100  */
101 struct slim_framer {
102         struct device           dev;
103         struct slim_eaddr       e_addr;
104         int                     rootfreq;
105         int                     superfreq;
106 };
107
108 #define to_slim_framer(d) container_of(d, struct slim_framer, dev)
109
110 /**
111  * struct slim_msg_txn - Message to be sent by the controller.
112  *                      This structure has packet header,
113  *                      payload and buffer to be filled (if any)
114  * @rl: Header field. remaining length.
115  * @mt: Header field. Message type.
116  * @mc: Header field. LSB is message code for type mt.
117  * @dt: Header field. Destination type.
118  * @ec: Element code. Used for elemental access APIs.
119  * @tid: Transaction ID. Used for messages expecting response.
120  *      (relevant for message-codes involving read operation)
121  * @la: Logical address of the device this message is going to.
122  *      (Not used when destination type is broadcast.)
123  * @msg: Elemental access message to be read/written
124  * @comp: completion if read/write is synchronous, used internally
125  *      for tid based transactions.
126  */
127 struct slim_msg_txn {
128         u8                      rl;
129         u8                      mt;
130         u8                      mc;
131         u8                      dt;
132         u16                     ec;
133         u8                      tid;
134         u8                      la;
135         struct slim_val_inf     *msg;
136         struct  completion      *comp;
137 };
138
139 /* Frequently used message transaction structures */
140 #define DEFINE_SLIM_LDEST_TXN(name, mc, rl, la, msg) \
141         struct slim_msg_txn name = { rl, 0, mc, SLIM_MSG_DEST_LOGICALADDR, 0,\
142                                         0, la, msg, }
143
144 #define DEFINE_SLIM_BCAST_TXN(name, mc, rl, la, msg) \
145         struct slim_msg_txn name = { rl, 0, mc, SLIM_MSG_DEST_BROADCAST, 0,\
146                                         0, la, msg, }
147
148 #define DEFINE_SLIM_EDEST_TXN(name, mc, rl, la, msg) \
149         struct slim_msg_txn name = { rl, 0, mc, SLIM_MSG_DEST_ENUMADDR, 0,\
150                                         0, la, msg, }
151 /**
152  * enum slim_clk_state: SLIMbus controller's clock state used internally for
153  *      maintaining current clock state.
154  * @SLIM_CLK_ACTIVE: SLIMbus clock is active
155  * @SLIM_CLK_ENTERING_PAUSE: SLIMbus clock pause sequence is being sent on the
156  *      bus. If this succeeds, state changes to SLIM_CLK_PAUSED. If the
157  *      transition fails, state changes back to SLIM_CLK_ACTIVE
158  * @SLIM_CLK_PAUSED: SLIMbus controller clock has paused.
159  */
160 enum slim_clk_state {
161         SLIM_CLK_ACTIVE,
162         SLIM_CLK_ENTERING_PAUSE,
163         SLIM_CLK_PAUSED,
164 };
165
166 /**
167  * struct slim_sched: Framework uses this structure internally for scheduling.
168  * @clk_state: Controller's clock state from enum slim_clk_state
169  * @pause_comp: Signals completion of clock pause sequence. This is useful when
170  *      client tries to call SLIMbus transaction when controller is entering
171  *      clock pause.
172  * @m_reconf: This mutex is held until current reconfiguration (data channel
173  *      scheduling, message bandwidth reservation) is done. Message APIs can
174  *      use the bus concurrently when this mutex is held since elemental access
175  *      messages can be sent on the bus when reconfiguration is in progress.
176  */
177 struct slim_sched {
178         enum slim_clk_state     clk_state;
179         struct completion       pause_comp;
180         struct mutex            m_reconf;
181 };
182
183 /**
184  * enum slim_port_direction: SLIMbus port direction
185  *
186  * @SLIM_PORT_SINK: SLIMbus port is a sink
187  * @SLIM_PORT_SOURCE: SLIMbus port is a source
188  */
189 enum slim_port_direction {
190         SLIM_PORT_SINK = 0,
191         SLIM_PORT_SOURCE,
192 };
193 /**
194  * enum slim_port_state: SLIMbus Port/Endpoint state machine
195  *      according to SLIMbus Spec 2.0
196  * @SLIM_PORT_DISCONNECTED: SLIMbus port is disconnected
197  *      entered from Unconfigure/configured state after
198  *      DISCONNECT_PORT or REMOVE_CHANNEL core command
199  * @SLIM_PORT_UNCONFIGURED: SLIMbus port is in unconfigured state.
200  *      entered from disconnect state after CONNECT_SOURCE/SINK core command
201  * @SLIM_PORT_CONFIGURED: SLIMbus port is in configured state.
202  *      entered from unconfigured state after DEFINE_CHANNEL, DEFINE_CONTENT
203  *      and ACTIVATE_CHANNEL core commands. Ready for data transmission.
204  */
205 enum slim_port_state {
206         SLIM_PORT_DISCONNECTED = 0,
207         SLIM_PORT_UNCONFIGURED,
208         SLIM_PORT_CONFIGURED,
209 };
210
211 /**
212  * enum slim_channel_state: SLIMbus channel state machine used by core.
213  * @SLIM_CH_STATE_DISCONNECTED: SLIMbus channel is disconnected
214  * @SLIM_CH_STATE_ALLOCATED: SLIMbus channel is allocated
215  * @SLIM_CH_STATE_ASSOCIATED: SLIMbus channel is associated with port
216  * @SLIM_CH_STATE_DEFINED: SLIMbus channel parameters are defined
217  * @SLIM_CH_STATE_CONTENT_DEFINED: SLIMbus channel content is defined
218  * @SLIM_CH_STATE_ACTIVE: SLIMbus channel is active and ready for data
219  * @SLIM_CH_STATE_REMOVED: SLIMbus channel is inactive and removed
220  */
221 enum slim_channel_state {
222         SLIM_CH_STATE_DISCONNECTED = 0,
223         SLIM_CH_STATE_ALLOCATED,
224         SLIM_CH_STATE_ASSOCIATED,
225         SLIM_CH_STATE_DEFINED,
226         SLIM_CH_STATE_CONTENT_DEFINED,
227         SLIM_CH_STATE_ACTIVE,
228         SLIM_CH_STATE_REMOVED,
229 };
230
231 /**
232  * enum slim_ch_data_fmt: SLIMbus channel data Type identifiers according to
233  *      Table 60 of SLIMbus Spec 1.01.01
234  * @SLIM_CH_DATA_FMT_NOT_DEFINED: Undefined
235  * @SLIM_CH_DATA_FMT_LPCM_AUDIO: LPCM audio
236  * @SLIM_CH_DATA_FMT_IEC61937_COMP_AUDIO: IEC61937 Compressed audio
237  * @SLIM_CH_DATA_FMT_PACKED_PDM_AUDIO: Packed PDM audio
238  */
239 enum slim_ch_data_fmt {
240         SLIM_CH_DATA_FMT_NOT_DEFINED = 0,
241         SLIM_CH_DATA_FMT_LPCM_AUDIO = 1,
242         SLIM_CH_DATA_FMT_IEC61937_COMP_AUDIO = 2,
243         SLIM_CH_DATA_FMT_PACKED_PDM_AUDIO = 3,
244 };
245
246 /**
247  * enum slim_ch_aux_bit_fmt: SLIMbus channel Aux Field format IDs according to
248  *      Table 63 of SLIMbus Spec 2.0
249  * @SLIM_CH_AUX_FMT_NOT_APPLICABLE: Undefined
250  * @SLIM_CH_AUX_FMT_ZCUV_TUNNEL_IEC60958: ZCUV for tunneling IEC60958
251  * @SLIM_CH_AUX_FMT_USER_DEFINED: User defined
252  */
253 enum slim_ch_aux_bit_fmt {
254         SLIM_CH_AUX_FMT_NOT_APPLICABLE = 0,
255         SLIM_CH_AUX_FMT_ZCUV_TUNNEL_IEC60958 = 1,
256         SLIM_CH_AUX_FMT_USER_DEFINED = 0xF,
257 };
258
259 /**
260  * struct slim_channel  - SLIMbus channel, used for state machine
261  *
262  * @id: ID of channel
263  * @prrate: Presense rate of channel from Table 66 of SLIMbus 2.0 Specs
264  * @seg_dist: segment distribution code from Table 20 of SLIMbus 2.0 Specs
265  * @data_fmt: Data format of channel.
266  * @aux_fmt: Aux format for this channel.
267  * @state: channel state machine
268  */
269 struct slim_channel {
270         int id;
271         int prrate;
272         int seg_dist;
273         enum slim_ch_data_fmt data_fmt;
274         enum slim_ch_aux_bit_fmt aux_fmt;
275         enum slim_channel_state state;
276 };
277
278 /**
279  * struct slim_port  - SLIMbus port
280  *
281  * @id: Port id
282  * @direction: Port direction, Source or Sink.
283  * @state: state machine of port.
284  * @ch: channel associated with this port.
285  */
286 struct slim_port {
287         int id;
288         enum slim_port_direction direction;
289         enum slim_port_state state;
290         struct slim_channel ch;
291 };
292
293 /**
294  * enum slim_transport_protocol: SLIMbus Transport protocol list from
295  *      Table 47 of SLIMbus 2.0 specs.
296  * @SLIM_PROTO_ISO: Isochronous Protocol, no flow control as data rate match
297  *              channel rate flow control embedded in the data.
298  * @SLIM_PROTO_PUSH: Pushed Protocol, includes flow control, Used to carry
299  *              data whose rate is equal to, or lower than the channel rate.
300  * @SLIM_PROTO_PULL: Pulled Protocol, similar usage as pushed protocol
301  *              but pull is a unicast.
302  * @SLIM_PROTO_LOCKED: Locked Protocol
303  * @SLIM_PROTO_ASYNC_SMPLX: Asynchronous Protocol-Simplex
304  * @SLIM_PROTO_ASYNC_HALF_DUP: Asynchronous Protocol-Half-duplex
305  * @SLIM_PROTO_EXT_SMPLX: Extended Asynchronous Protocol-Simplex
306  * @SLIM_PROTO_EXT_HALF_DUP: Extended Asynchronous Protocol-Half-duplex
307  */
308 enum slim_transport_protocol {
309         SLIM_PROTO_ISO = 0,
310         SLIM_PROTO_PUSH,
311         SLIM_PROTO_PULL,
312         SLIM_PROTO_LOCKED,
313         SLIM_PROTO_ASYNC_SMPLX,
314         SLIM_PROTO_ASYNC_HALF_DUP,
315         SLIM_PROTO_EXT_SMPLX,
316         SLIM_PROTO_EXT_HALF_DUP,
317 };
318
319 /**
320  * struct slim_stream_runtime  - SLIMbus stream runtime instance
321  *
322  * @name: Name of the stream
323  * @dev: SLIM Device instance associated with this stream
324  * @direction: direction of stream
325  * @prot: Transport protocol used in this stream
326  * @rate: Data rate of samples *
327  * @bps: bits per sample
328  * @ratem: rate multipler which is super frame rate/data rate
329  * @num_ports: number of ports
330  * @ports: pointer to instance of ports
331  * @node: list head for stream associated with slim device.
332  */
333 struct slim_stream_runtime {
334         const char *name;
335         struct slim_device *dev;
336         int direction;
337         enum slim_transport_protocol prot;
338         unsigned int rate;
339         unsigned int bps;
340         unsigned int ratem;
341         int num_ports;
342         struct slim_port *ports;
343         struct list_head node;
344 };
345
346 /**
347  * struct slim_controller  - Controls every instance of SLIMbus
348  *                              (similar to 'master' on SPI)
349  * @dev: Device interface to this driver
350  * @id: Board-specific number identifier for this controller/bus
351  * @name: Name for this controller
352  * @min_cg: Minimum clock gear supported by this controller (default value: 1)
353  * @max_cg: Maximum clock gear supported by this controller (default value: 10)
354  * @clkgear: Current clock gear in which this bus is running
355  * @laddr_ida: logical address id allocator
356  * @a_framer: Active framer which is clocking the bus managed by this controller
357  * @lock: Mutex protecting controller data structures
358  * @devices: Slim device list
359  * @tid_idr: tid id allocator
360  * @txn_lock: Lock to protect table of transactions
361  * @sched: scheduler structure used by the controller
362  * @xfer_msg: Transfer a message on this controller (this can be a broadcast
363  *      control/status message like data channel setup, or a unicast message
364  *      like value element read/write.
365  * @set_laddr: Setup logical address at laddr for the slave with elemental
366  *      address e_addr. Drivers implementing controller will be expected to
367  *      send unicast message to this device with its logical address.
368  * @get_laddr: It is possible that controller needs to set fixed logical
369  *      address table and get_laddr can be used in that case so that controller
370  *      can do this assignment. Use case is when the master is on the remote
371  *      processor side, who is resposible for allocating laddr.
372  * @wakeup: This function pointer implements controller-specific procedure
373  *      to wake it up from clock-pause. Framework will call this to bring
374  *      the controller out of clock pause.
375  * @enable_stream: This function pointer implements controller-specific procedure
376  *      to enable a stream.
377  * @disable_stream: This function pointer implements controller-specific procedure
378  *      to disable stream.
379  *
380  *      'Manager device' is responsible for  device management, bandwidth
381  *      allocation, channel setup, and port associations per channel.
382  *      Device management means Logical address assignment/removal based on
383  *      enumeration (report-present, report-absent) of a device.
384  *      Bandwidth allocation is done dynamically by the manager based on active
385  *      channels on the bus, message-bandwidth requests made by SLIMbus devices.
386  *      Based on current bandwidth usage, manager chooses a frequency to run
387  *      the bus at (in steps of 'clock-gear', 1 through 10, each clock gear
388  *      representing twice the frequency than the previous gear).
389  *      Manager is also responsible for entering (and exiting) low-power-mode
390  *      (known as 'clock pause').
391  *      Manager can do handover of framer if there are multiple framers on the
392  *      bus and a certain usecase warrants using certain framer to avoid keeping
393  *      previous framer being powered-on.
394  *
395  *      Controller here performs duties of the manager device, and 'interface
396  *      device'. Interface device is responsible for monitoring the bus and
397  *      reporting information such as loss-of-synchronization, data
398  *      slot-collision.
399  */
400 struct slim_controller {
401         struct device           *dev;
402         unsigned int            id;
403         char                    name[SLIMBUS_NAME_SIZE];
404         int                     min_cg;
405         int                     max_cg;
406         int                     clkgear;
407         struct ida              laddr_ida;
408         struct slim_framer      *a_framer;
409         struct mutex            lock;
410         struct list_head        devices;
411         struct idr              tid_idr;
412         spinlock_t              txn_lock;
413         struct slim_sched       sched;
414         int                     (*xfer_msg)(struct slim_controller *ctrl,
415                                             struct slim_msg_txn *tx);
416         int                     (*set_laddr)(struct slim_controller *ctrl,
417                                              struct slim_eaddr *ea, u8 laddr);
418         int                     (*get_laddr)(struct slim_controller *ctrl,
419                                              struct slim_eaddr *ea, u8 *laddr);
420         int             (*enable_stream)(struct slim_stream_runtime *rt);
421         int             (*disable_stream)(struct slim_stream_runtime *rt);
422         int                     (*wakeup)(struct slim_controller *ctrl);
423 };
424
425 int slim_device_report_present(struct slim_controller *ctrl,
426                                struct slim_eaddr *e_addr, u8 *laddr);
427 void slim_report_absent(struct slim_device *sbdev);
428 int slim_register_controller(struct slim_controller *ctrl);
429 int slim_unregister_controller(struct slim_controller *ctrl);
430 void slim_msg_response(struct slim_controller *ctrl, u8 *reply, u8 tid, u8 l);
431 int slim_do_transfer(struct slim_controller *ctrl, struct slim_msg_txn *txn);
432 int slim_ctrl_clk_pause(struct slim_controller *ctrl, bool wakeup, u8 restart);
433 int slim_alloc_txn_tid(struct slim_controller *ctrl, struct slim_msg_txn *txn);
434 void slim_free_txn_tid(struct slim_controller *ctrl, struct slim_msg_txn *txn);
435
436 static inline bool slim_tid_txn(u8 mt, u8 mc)
437 {
438         return (mt == SLIM_MSG_MT_CORE &&
439                 (mc == SLIM_MSG_MC_REQUEST_INFORMATION ||
440                  mc == SLIM_MSG_MC_REQUEST_CLEAR_INFORMATION ||
441                  mc == SLIM_MSG_MC_REQUEST_VALUE ||
442                  mc == SLIM_MSG_MC_REQUEST_CHANGE_VALUE));
443 }
444
445 static inline bool slim_ec_txn(u8 mt, u8 mc)
446 {
447         return (mt == SLIM_MSG_MT_CORE &&
448                 ((mc >= SLIM_MSG_MC_REQUEST_INFORMATION &&
449                   mc <= SLIM_MSG_MC_REPORT_INFORMATION) ||
450                  (mc >= SLIM_MSG_MC_REQUEST_VALUE &&
451                   mc <= SLIM_MSG_MC_CHANGE_VALUE)));
452 }
453 #endif /* _LINUX_SLIMBUS_H */