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