1 /* SPDX-License-Identifier: (GPL-2.0 OR BSD-3-Clause) */
2 /* Copyright(c) 2015-17 Intel Corporation. */
3 
4 #ifndef __SOUNDWIRE_H
5 #define __SOUNDWIRE_H
6 
7 #include <linux/mod_devicetable.h>
8 #include <linux/bitfield.h>
9 
10 struct sdw_bus;
11 struct sdw_slave;
12 
13 /* SDW spec defines and enums, as defined by MIPI 1.1. Spec */
14 
15 /* SDW Broadcast Device Number */
16 #define SDW_BROADCAST_DEV_NUM		15
17 
18 /* SDW Enumeration Device Number */
19 #define SDW_ENUM_DEV_NUM		0
20 
21 /* SDW Group Device Numbers */
22 #define SDW_GROUP12_DEV_NUM		12
23 #define SDW_GROUP13_DEV_NUM		13
24 
25 /* SDW Master Device Number, not supported yet */
26 #define SDW_MASTER_DEV_NUM		14
27 
28 #define SDW_NUM_DEV_ID_REGISTERS	6
29 /* frame shape defines */
30 
31 /*
32  * Note: The maximum row define in SoundWire spec 1.1 is 23. In order to
33  * fill hole with 0, one more dummy entry is added
34  */
35 #define SDW_FRAME_ROWS		24
36 #define SDW_FRAME_COLS		8
37 #define SDW_FRAME_ROW_COLS		(SDW_FRAME_ROWS * SDW_FRAME_COLS)
38 
39 #define SDW_FRAME_CTRL_BITS		48
40 #define SDW_MAX_DEVICES			11
41 
42 #define SDW_MAX_PORTS			15
43 #define SDW_VALID_PORT_RANGE(n)		((n) < SDW_MAX_PORTS && (n) >= 1)
44 
45 enum {
46 	SDW_PORT_DIRN_SINK = 0,
47 	SDW_PORT_DIRN_SOURCE,
48 	SDW_PORT_DIRN_MAX,
49 };
50 
51 /*
52  * constants for flow control, ports and transport
53  *
54  * these are bit masks as devices can have multiple capabilities
55  */
56 
57 /*
58  * flow modes for SDW port. These can be isochronous, tx controlled,
59  * rx controlled or async
60  */
61 #define SDW_PORT_FLOW_MODE_ISOCH	0
62 #define SDW_PORT_FLOW_MODE_TX_CNTRL	BIT(0)
63 #define SDW_PORT_FLOW_MODE_RX_CNTRL	BIT(1)
64 #define SDW_PORT_FLOW_MODE_ASYNC	GENMASK(1, 0)
65 
66 /* sample packaging for block. It can be per port or per channel */
67 #define SDW_BLOCK_PACKG_PER_PORT	BIT(0)
68 #define SDW_BLOCK_PACKG_PER_CH		BIT(1)
69 
70 /**
71  * enum sdw_slave_status - Slave status
72  * @SDW_SLAVE_UNATTACHED: Slave is not attached with the bus.
73  * @SDW_SLAVE_ATTACHED: Slave is attached with bus.
74  * @SDW_SLAVE_ALERT: Some alert condition on the Slave
75  * @SDW_SLAVE_RESERVED: Reserved for future use
76  */
77 enum sdw_slave_status {
78 	SDW_SLAVE_UNATTACHED = 0,
79 	SDW_SLAVE_ATTACHED = 1,
80 	SDW_SLAVE_ALERT = 2,
81 	SDW_SLAVE_RESERVED = 3,
82 };
83 
84 /**
85  * enum sdw_clk_stop_type: clock stop operations
86  *
87  * @SDW_CLK_PRE_PREPARE: pre clock stop prepare
88  * @SDW_CLK_POST_PREPARE: post clock stop prepare
89  * @SDW_CLK_PRE_DEPREPARE: pre clock stop de-prepare
90  * @SDW_CLK_POST_DEPREPARE: post clock stop de-prepare
91  */
92 enum sdw_clk_stop_type {
93 	SDW_CLK_PRE_PREPARE = 0,
94 	SDW_CLK_POST_PREPARE,
95 	SDW_CLK_PRE_DEPREPARE,
96 	SDW_CLK_POST_DEPREPARE,
97 };
98 
99 /**
100  * enum sdw_command_response - Command response as defined by SDW spec
101  * @SDW_CMD_OK: cmd was successful
102  * @SDW_CMD_IGNORED: cmd was ignored
103  * @SDW_CMD_FAIL: cmd was NACKed
104  * @SDW_CMD_TIMEOUT: cmd timedout
105  * @SDW_CMD_FAIL_OTHER: cmd failed due to other reason than above
106  *
107  * NOTE: The enum is different than actual Spec as response in the Spec is
108  * combination of ACK/NAK bits
109  *
110  * SDW_CMD_TIMEOUT/FAIL_OTHER is defined for SW use, not in spec
111  */
112 enum sdw_command_response {
113 	SDW_CMD_OK = 0,
114 	SDW_CMD_IGNORED = 1,
115 	SDW_CMD_FAIL = 2,
116 	SDW_CMD_TIMEOUT = 3,
117 	SDW_CMD_FAIL_OTHER = 4,
118 };
119 
120 /* block group count enum */
121 enum sdw_dpn_grouping {
122 	SDW_BLK_GRP_CNT_1 = 0,
123 	SDW_BLK_GRP_CNT_2 = 1,
124 	SDW_BLK_GRP_CNT_3 = 2,
125 	SDW_BLK_GRP_CNT_4 = 3,
126 };
127 
128 /* block packing mode enum */
129 enum sdw_dpn_pkg_mode {
130 	SDW_BLK_PKG_PER_PORT = 0,
131 	SDW_BLK_PKG_PER_CHANNEL = 1
132 };
133 
134 /**
135  * enum sdw_stream_type: data stream type
136  *
137  * @SDW_STREAM_PCM: PCM data stream
138  * @SDW_STREAM_PDM: PDM data stream
139  *
140  * spec doesn't define this, but is used in implementation
141  */
142 enum sdw_stream_type {
143 	SDW_STREAM_PCM = 0,
144 	SDW_STREAM_PDM = 1,
145 };
146 
147 /**
148  * enum sdw_data_direction: Data direction
149  *
150  * @SDW_DATA_DIR_RX: Data into Port
151  * @SDW_DATA_DIR_TX: Data out of Port
152  */
153 enum sdw_data_direction {
154 	SDW_DATA_DIR_RX = 0,
155 	SDW_DATA_DIR_TX = 1,
156 };
157 
158 /**
159  * enum sdw_port_data_mode: Data Port mode
160  *
161  * @SDW_PORT_DATA_MODE_NORMAL: Normal data mode where audio data is received
162  * and transmitted.
163  * @SDW_PORT_DATA_MODE_PRBS: Test mode which uses a PRBS generator to produce
164  * a pseudo random data pattern that is transferred
165  * @SDW_PORT_DATA_MODE_STATIC_0: Simple test mode which uses static value of
166  * logic 0. The encoding will result in no signal transitions
167  * @SDW_PORT_DATA_MODE_STATIC_1: Simple test mode which uses static value of
168  * logic 1. The encoding will result in signal transitions at every bitslot
169  * owned by this Port
170  */
171 enum sdw_port_data_mode {
172 	SDW_PORT_DATA_MODE_NORMAL = 0,
173 	SDW_PORT_DATA_MODE_PRBS = 1,
174 	SDW_PORT_DATA_MODE_STATIC_0 = 2,
175 	SDW_PORT_DATA_MODE_STATIC_1 = 3,
176 };
177 
178 /*
179  * SDW properties, defined in MIPI DisCo spec v1.0
180  */
181 enum sdw_clk_stop_reset_behave {
182 	SDW_CLK_STOP_KEEP_STATUS = 1,
183 };
184 
185 /**
186  * enum sdw_p15_behave - Slave Port 15 behaviour when the Master attempts a
187  * read
188  * @SDW_P15_READ_IGNORED: Read is ignored
189  * @SDW_P15_CMD_OK: Command is ok
190  */
191 enum sdw_p15_behave {
192 	SDW_P15_READ_IGNORED = 0,
193 	SDW_P15_CMD_OK = 1,
194 };
195 
196 /**
197  * enum sdw_dpn_type - Data port types
198  * @SDW_DPN_FULL: Full Data Port is supported
199  * @SDW_DPN_SIMPLE: Simplified Data Port as defined in spec.
200  * DPN_SampleCtrl2, DPN_OffsetCtrl2, DPN_HCtrl and DPN_BlockCtrl3
201  * are not implemented.
202  * @SDW_DPN_REDUCED: Reduced Data Port as defined in spec.
203  * DPN_SampleCtrl2, DPN_HCtrl are not implemented.
204  */
205 enum sdw_dpn_type {
206 	SDW_DPN_FULL = 0,
207 	SDW_DPN_SIMPLE = 1,
208 	SDW_DPN_REDUCED = 2,
209 };
210 
211 /**
212  * enum sdw_clk_stop_mode - Clock Stop modes
213  * @SDW_CLK_STOP_MODE0: Slave can continue operation seamlessly on clock
214  * restart
215  * @SDW_CLK_STOP_MODE1: Slave may have entered a deeper power-saving mode,
216  * not capable of continuing operation seamlessly when the clock restarts
217  */
218 enum sdw_clk_stop_mode {
219 	SDW_CLK_STOP_MODE0 = 0,
220 	SDW_CLK_STOP_MODE1 = 1,
221 };
222 
223 /**
224  * struct sdw_dp0_prop - DP0 properties
225  * @max_word: Maximum number of bits in a Payload Channel Sample, 1 to 64
226  * (inclusive)
227  * @min_word: Minimum number of bits in a Payload Channel Sample, 1 to 64
228  * (inclusive)
229  * @num_words: number of wordlengths supported
230  * @words: wordlengths supported
231  * @BRA_flow_controlled: Slave implementation results in an OK_NotReady
232  * response
233  * @simple_ch_prep_sm: If channel prepare sequence is required
234  * @imp_def_interrupts: If set, each bit corresponds to support for
235  * implementation-defined interrupts
236  *
237  * The wordlengths are specified by Spec as max, min AND number of
238  * discrete values, implementation can define based on the wordlengths they
239  * support
240  */
241 struct sdw_dp0_prop {
242 	u32 max_word;
243 	u32 min_word;
244 	u32 num_words;
245 	u32 *words;
246 	bool BRA_flow_controlled;
247 	bool simple_ch_prep_sm;
248 	bool imp_def_interrupts;
249 };
250 
251 /**
252  * struct sdw_dpn_audio_mode - Audio mode properties for DPn
253  * @bus_min_freq: Minimum bus frequency, in Hz
254  * @bus_max_freq: Maximum bus frequency, in Hz
255  * @bus_num_freq: Number of discrete frequencies supported
256  * @bus_freq: Discrete bus frequencies, in Hz
257  * @min_freq: Minimum sampling frequency, in Hz
258  * @max_freq: Maximum sampling bus frequency, in Hz
259  * @num_freq: Number of discrete sampling frequency supported
260  * @freq: Discrete sampling frequencies, in Hz
261  * @prep_ch_behave: Specifies the dependencies between Channel Prepare
262  * sequence and bus clock configuration
263  * If 0, Channel Prepare can happen at any Bus clock rate
264  * If 1, Channel Prepare sequence shall happen only after Bus clock is
265  * changed to a frequency supported by this mode or compatible modes
266  * described by the next field
267  * @glitchless: Bitmap describing possible glitchless transitions from this
268  * Audio Mode to other Audio Modes
269  */
270 struct sdw_dpn_audio_mode {
271 	u32 bus_min_freq;
272 	u32 bus_max_freq;
273 	u32 bus_num_freq;
274 	u32 *bus_freq;
275 	u32 max_freq;
276 	u32 min_freq;
277 	u32 num_freq;
278 	u32 *freq;
279 	u32 prep_ch_behave;
280 	u32 glitchless;
281 };
282 
283 /**
284  * struct sdw_dpn_prop - Data Port DPn properties
285  * @num: port number
286  * @max_word: Maximum number of bits in a Payload Channel Sample, 1 to 64
287  * (inclusive)
288  * @min_word: Minimum number of bits in a Payload Channel Sample, 1 to 64
289  * (inclusive)
290  * @num_words: Number of discrete supported wordlengths
291  * @words: Discrete supported wordlength
292  * @type: Data port type. Full, Simplified or Reduced
293  * @max_grouping: Maximum number of samples that can be grouped together for
294  * a full data port
295  * @simple_ch_prep_sm: If the port supports simplified channel prepare state
296  * machine
297  * @ch_prep_timeout: Port-specific timeout value, in milliseconds
298  * @imp_def_interrupts: If set, each bit corresponds to support for
299  * implementation-defined interrupts
300  * @max_ch: Maximum channels supported
301  * @min_ch: Minimum channels supported
302  * @num_channels: Number of discrete channels supported
303  * @channels: Discrete channels supported
304  * @num_ch_combinations: Number of channel combinations supported
305  * @ch_combinations: Channel combinations supported
306  * @modes: SDW mode supported
307  * @max_async_buffer: Number of samples that this port can buffer in
308  * asynchronous modes
309  * @block_pack_mode: Type of block port mode supported
310  * @read_only_wordlength: Read Only wordlength field in DPN_BlockCtrl1 register
311  * @port_encoding: Payload Channel Sample encoding schemes supported
312  * @audio_modes: Audio modes supported
313  */
314 struct sdw_dpn_prop {
315 	u32 num;
316 	u32 max_word;
317 	u32 min_word;
318 	u32 num_words;
319 	u32 *words;
320 	enum sdw_dpn_type type;
321 	u32 max_grouping;
322 	bool simple_ch_prep_sm;
323 	u32 ch_prep_timeout;
324 	u32 imp_def_interrupts;
325 	u32 max_ch;
326 	u32 min_ch;
327 	u32 num_channels;
328 	u32 *channels;
329 	u32 num_ch_combinations;
330 	u32 *ch_combinations;
331 	u32 modes;
332 	u32 max_async_buffer;
333 	bool block_pack_mode;
334 	bool read_only_wordlength;
335 	u32 port_encoding;
336 	struct sdw_dpn_audio_mode *audio_modes;
337 };
338 
339 /**
340  * struct sdw_slave_prop - SoundWire Slave properties
341  * @mipi_revision: Spec version of the implementation
342  * @wake_capable: Wake-up events are supported
343  * @test_mode_capable: If test mode is supported
344  * @clk_stop_mode1: Clock-Stop Mode 1 is supported
345  * @simple_clk_stop_capable: Simple clock mode is supported
346  * @clk_stop_timeout: Worst-case latency of the Clock Stop Prepare State
347  * Machine transitions, in milliseconds
348  * @ch_prep_timeout: Worst-case latency of the Channel Prepare State Machine
349  * transitions, in milliseconds
350  * @reset_behave: Slave keeps the status of the SlaveStopClockPrepare
351  * state machine (P=1 SCSP_SM) after exit from clock-stop mode1
352  * @high_PHY_capable: Slave is HighPHY capable
353  * @paging_support: Slave implements paging registers SCP_AddrPage1 and
354  * SCP_AddrPage2
355  * @bank_delay_support: Slave implements bank delay/bridge support registers
356  * SCP_BankDelay and SCP_NextFrame
357  * @p15_behave: Slave behavior when the Master attempts a read to the Port15
358  * alias
359  * @lane_control_support: Slave supports lane control
360  * @master_count: Number of Masters present on this Slave
361  * @source_ports: Bitmap identifying source ports
362  * @sink_ports: Bitmap identifying sink ports
363  * @dp0_prop: Data Port 0 properties
364  * @src_dpn_prop: Source Data Port N properties
365  * @sink_dpn_prop: Sink Data Port N properties
366  * @scp_int1_mask: SCP_INT1_MASK desired settings
367  * @quirks: bitmask identifying deltas from the MIPI specification
368  * @is_sdca: the Slave supports the SDCA specification
369  */
370 struct sdw_slave_prop {
371 	u32 mipi_revision;
372 	bool wake_capable;
373 	bool test_mode_capable;
374 	bool clk_stop_mode1;
375 	bool simple_clk_stop_capable;
376 	u32 clk_stop_timeout;
377 	u32 ch_prep_timeout;
378 	enum sdw_clk_stop_reset_behave reset_behave;
379 	bool high_PHY_capable;
380 	bool paging_support;
381 	bool bank_delay_support;
382 	enum sdw_p15_behave p15_behave;
383 	bool lane_control_support;
384 	u32 master_count;
385 	u32 source_ports;
386 	u32 sink_ports;
387 	struct sdw_dp0_prop *dp0_prop;
388 	struct sdw_dpn_prop *src_dpn_prop;
389 	struct sdw_dpn_prop *sink_dpn_prop;
390 	u8 scp_int1_mask;
391 	u32 quirks;
392 	bool is_sdca;
393 };
394 
395 #define SDW_SLAVE_QUIRKS_INVALID_INITIAL_PARITY	BIT(0)
396 
397 /**
398  * struct sdw_master_prop - Master properties
399  * @revision: MIPI spec version of the implementation
400  * @clk_stop_modes: Bitmap, bit N set when clock-stop-modeN supported
401  * @max_clk_freq: Maximum Bus clock frequency, in Hz
402  * @num_clk_gears: Number of clock gears supported
403  * @clk_gears: Clock gears supported
404  * @num_clk_freq: Number of clock frequencies supported, in Hz
405  * @clk_freq: Clock frequencies supported, in Hz
406  * @default_frame_rate: Controller default Frame rate, in Hz
407  * @default_row: Number of rows
408  * @default_col: Number of columns
409  * @dynamic_frame: Dynamic frame shape supported
410  * @err_threshold: Number of times that software may retry sending a single
411  * command
412  * @mclk_freq: clock reference passed to SoundWire Master, in Hz.
413  * @hw_disabled: if true, the Master is not functional, typically due to pin-mux
414  * @quirks: bitmask identifying optional behavior beyond the scope of the MIPI specification
415  */
416 struct sdw_master_prop {
417 	u32 revision;
418 	u32 clk_stop_modes;
419 	u32 max_clk_freq;
420 	u32 num_clk_gears;
421 	u32 *clk_gears;
422 	u32 num_clk_freq;
423 	u32 *clk_freq;
424 	u32 default_frame_rate;
425 	u32 default_row;
426 	u32 default_col;
427 	bool dynamic_frame;
428 	u32 err_threshold;
429 	u32 mclk_freq;
430 	bool hw_disabled;
431 	u64 quirks;
432 };
433 
434 /* Definitions for Master quirks */
435 
436 /*
437  * In a number of platforms bus clashes are reported after a hardware
438  * reset but without any explanations or evidence of a real problem.
439  * The following quirk will discard all initial bus clash interrupts
440  * but will leave the detection on should real bus clashes happen
441  */
442 #define SDW_MASTER_QUIRKS_CLEAR_INITIAL_CLASH	BIT(0)
443 
444 /*
445  * Some Slave devices have known issues with incorrect parity errors
446  * reported after a hardware reset. However during integration unexplained
447  * parity errors can be reported by Slave devices, possibly due to electrical
448  * issues at the Master level.
449  * The following quirk will discard all initial parity errors but will leave
450  * the detection on should real parity errors happen.
451  */
452 #define SDW_MASTER_QUIRKS_CLEAR_INITIAL_PARITY	BIT(1)
453 
454 int sdw_master_read_prop(struct sdw_bus *bus);
455 int sdw_slave_read_prop(struct sdw_slave *slave);
456 
457 /*
458  * SDW Slave Structures and APIs
459  */
460 
461 #define SDW_IGNORED_UNIQUE_ID 0xFF
462 
463 /**
464  * struct sdw_slave_id - Slave ID
465  * @mfg_id: MIPI Manufacturer ID
466  * @part_id: Device Part ID
467  * @class_id: MIPI Class ID (defined starting with SoundWire 1.2 spec)
468  * @unique_id: Device unique ID
469  * @sdw_version: SDW version implemented
470  *
471  * The order of the IDs here does not follow the DisCo spec definitions
472  */
473 struct sdw_slave_id {
474 	__u16 mfg_id;
475 	__u16 part_id;
476 	__u8 class_id;
477 	__u8 unique_id;
478 	__u8 sdw_version:4;
479 };
480 
481 /*
482  * Helper macros to extract the MIPI-defined IDs
483  *
484  * Spec definition
485  *   Register		Bit	Contents
486  *   DevId_0 [7:4]	47:44	sdw_version
487  *   DevId_0 [3:0]	43:40	unique_id
488  *   DevId_1		39:32	mfg_id [15:8]
489  *   DevId_2		31:24	mfg_id [7:0]
490  *   DevId_3		23:16	part_id [15:8]
491  *   DevId_4		15:08	part_id [7:0]
492  *   DevId_5		07:00	class_id
493  *
494  * The MIPI DisCo for SoundWire defines in addition the link_id as bits 51:48
495  */
496 #define SDW_DISCO_LINK_ID_MASK	GENMASK_ULL(51, 48)
497 #define SDW_VERSION_MASK	GENMASK_ULL(47, 44)
498 #define SDW_UNIQUE_ID_MASK	GENMASK_ULL(43, 40)
499 #define SDW_MFG_ID_MASK		GENMASK_ULL(39, 24)
500 #define SDW_PART_ID_MASK	GENMASK_ULL(23, 8)
501 #define SDW_CLASS_ID_MASK	GENMASK_ULL(7, 0)
502 
503 #define SDW_DISCO_LINK_ID(addr)	FIELD_GET(SDW_DISCO_LINK_ID_MASK, addr)
504 #define SDW_VERSION(addr)	FIELD_GET(SDW_VERSION_MASK, addr)
505 #define SDW_UNIQUE_ID(addr)	FIELD_GET(SDW_UNIQUE_ID_MASK, addr)
506 #define SDW_MFG_ID(addr)	FIELD_GET(SDW_MFG_ID_MASK, addr)
507 #define SDW_PART_ID(addr)	FIELD_GET(SDW_PART_ID_MASK, addr)
508 #define SDW_CLASS_ID(addr)	FIELD_GET(SDW_CLASS_ID_MASK, addr)
509 
510 /**
511  * struct sdw_slave_intr_status - Slave interrupt status
512  * @sdca_cascade: set if the Slave device reports an SDCA interrupt
513  * @control_port: control port status
514  * @port: data port status
515  */
516 struct sdw_slave_intr_status {
517 	bool sdca_cascade;
518 	u8 control_port;
519 	u8 port[15];
520 };
521 
522 /**
523  * sdw_reg_bank - SoundWire register banks
524  * @SDW_BANK0: Soundwire register bank 0
525  * @SDW_BANK1: Soundwire register bank 1
526  */
527 enum sdw_reg_bank {
528 	SDW_BANK0,
529 	SDW_BANK1,
530 };
531 
532 /**
533  * struct sdw_bus_conf: Bus configuration
534  *
535  * @clk_freq: Clock frequency, in Hz
536  * @num_rows: Number of rows in frame
537  * @num_cols: Number of columns in frame
538  * @bank: Next register bank
539  */
540 struct sdw_bus_conf {
541 	unsigned int clk_freq;
542 	unsigned int num_rows;
543 	unsigned int num_cols;
544 	unsigned int bank;
545 };
546 
547 /**
548  * struct sdw_prepare_ch: Prepare/De-prepare Data Port channel
549  *
550  * @num: Port number
551  * @ch_mask: Active channel mask
552  * @prepare: Prepare (true) /de-prepare (false) channel
553  * @bank: Register bank, which bank Slave/Master driver should program for
554  * implementation defined registers. This is always updated to next_bank
555  * value read from bus params.
556  *
557  */
558 struct sdw_prepare_ch {
559 	unsigned int num;
560 	unsigned int ch_mask;
561 	bool prepare;
562 	unsigned int bank;
563 };
564 
565 /**
566  * enum sdw_port_prep_ops: Prepare operations for Data Port
567  *
568  * @SDW_OPS_PORT_PRE_PREP: Pre prepare operation for the Port
569  * @SDW_OPS_PORT_PREP: Prepare operation for the Port
570  * @SDW_OPS_PORT_POST_PREP: Post prepare operation for the Port
571  */
572 enum sdw_port_prep_ops {
573 	SDW_OPS_PORT_PRE_PREP = 0,
574 	SDW_OPS_PORT_PREP = 1,
575 	SDW_OPS_PORT_POST_PREP = 2,
576 };
577 
578 /**
579  * struct sdw_bus_params: Structure holding bus configuration
580  *
581  * @curr_bank: Current bank in use (BANK0/BANK1)
582  * @next_bank: Next bank to use (BANK0/BANK1). next_bank will always be
583  * set to !curr_bank
584  * @max_dr_freq: Maximum double rate clock frequency supported, in Hz
585  * @curr_dr_freq: Current double rate clock frequency, in Hz
586  * @bandwidth: Current bandwidth
587  * @col: Active columns
588  * @row: Active rows
589  * @s_data_mode: NORMAL, STATIC or PRBS mode for all Slave ports
590  * @m_data_mode: NORMAL, STATIC or PRBS mode for all Master ports. The value
591  * should be the same to detect transmission issues, but can be different to
592  * test the interrupt reports
593  */
594 struct sdw_bus_params {
595 	enum sdw_reg_bank curr_bank;
596 	enum sdw_reg_bank next_bank;
597 	unsigned int max_dr_freq;
598 	unsigned int curr_dr_freq;
599 	unsigned int bandwidth;
600 	unsigned int col;
601 	unsigned int row;
602 	int s_data_mode;
603 	int m_data_mode;
604 };
605 
606 /**
607  * struct sdw_slave_ops: Slave driver callback ops
608  *
609  * @read_prop: Read Slave properties
610  * @interrupt_callback: Device interrupt notification (invoked in thread
611  * context)
612  * @update_status: Update Slave status
613  * @bus_config: Update the bus config for Slave
614  * @port_prep: Prepare the port with parameters
615  * @clk_stop: handle imp-def sequences before and after prepare and de-prepare
616  */
617 struct sdw_slave_ops {
618 	int (*read_prop)(struct sdw_slave *sdw);
619 	int (*interrupt_callback)(struct sdw_slave *slave,
620 				  struct sdw_slave_intr_status *status);
621 	int (*update_status)(struct sdw_slave *slave,
622 			     enum sdw_slave_status status);
623 	int (*bus_config)(struct sdw_slave *slave,
624 			  struct sdw_bus_params *params);
625 	int (*port_prep)(struct sdw_slave *slave,
626 			 struct sdw_prepare_ch *prepare_ch,
627 			 enum sdw_port_prep_ops pre_ops);
628 	int (*clk_stop)(struct sdw_slave *slave,
629 			enum sdw_clk_stop_mode mode,
630 			enum sdw_clk_stop_type type);
631 
632 };
633 
634 /**
635  * struct sdw_slave - SoundWire Slave
636  * @id: MIPI device ID
637  * @dev: Linux device
638  * @status: Status reported by the Slave
639  * @bus: Bus handle
640  * @prop: Slave properties
641  * @debugfs: Slave debugfs
642  * @node: node for bus list
643  * @port_ready: Port ready completion flag for each Slave port
644  * @m_port_map: static Master port map for each Slave port
645  * @dev_num: Current Device Number, values can be 0 or dev_num_sticky
646  * @dev_num_sticky: one-time static Device Number assigned by Bus
647  * @probed: boolean tracking driver state
648  * @enumeration_complete: completion utility to control potential races
649  * on startup between device enumeration and read/write access to the
650  * Slave device
651  * @initialization_complete: completion utility to control potential races
652  * on startup between device enumeration and settings being restored
653  * @unattach_request: mask field to keep track why the Slave re-attached and
654  * was re-initialized. This is useful to deal with potential race conditions
655  * between the Master suspending and the codec resuming, and make sure that
656  * when the Master triggered a reset the Slave is properly enumerated and
657  * initialized
658  * @first_interrupt_done: status flag tracking if the interrupt handling
659  * for a Slave happens for the first time after enumeration
660  * @is_mockup_device: status flag used to squelch errors in the command/control
661  * protocol for SoundWire mockup devices
662  * @sdw_dev_lock: mutex used to protect callbacks/remove races
663  */
664 struct sdw_slave {
665 	struct sdw_slave_id id;
666 	struct device dev;
667 	enum sdw_slave_status status;
668 	struct sdw_bus *bus;
669 	struct sdw_slave_prop prop;
670 #ifdef CONFIG_DEBUG_FS
671 	struct dentry *debugfs;
672 #endif
673 	struct list_head node;
674 	struct completion port_ready[SDW_MAX_PORTS];
675 	unsigned int m_port_map[SDW_MAX_PORTS];
676 	u16 dev_num;
677 	u16 dev_num_sticky;
678 	bool probed;
679 	struct completion enumeration_complete;
680 	struct completion initialization_complete;
681 	u32 unattach_request;
682 	bool first_interrupt_done;
683 	bool is_mockup_device;
684 	struct mutex sdw_dev_lock; /* protect callbacks/remove races */
685 };
686 
687 #define dev_to_sdw_dev(_dev) container_of(_dev, struct sdw_slave, dev)
688 
689 /**
690  * struct sdw_master_device - SoundWire 'Master Device' representation
691  * @dev: Linux device for this Master
692  * @bus: Bus handle shortcut
693  */
694 struct sdw_master_device {
695 	struct device dev;
696 	struct sdw_bus *bus;
697 };
698 
699 #define dev_to_sdw_master_device(d)	\
700 	container_of(d, struct sdw_master_device, dev)
701 
702 struct sdw_driver {
703 	const char *name;
704 
705 	int (*probe)(struct sdw_slave *sdw,
706 			const struct sdw_device_id *id);
707 	int (*remove)(struct sdw_slave *sdw);
708 	void (*shutdown)(struct sdw_slave *sdw);
709 
710 	const struct sdw_device_id *id_table;
711 	const struct sdw_slave_ops *ops;
712 
713 	struct device_driver driver;
714 };
715 
716 #define SDW_SLAVE_ENTRY_EXT(_mfg_id, _part_id, _version, _c_id, _drv_data) \
717 	{ .mfg_id = (_mfg_id), .part_id = (_part_id),		\
718 	  .sdw_version = (_version), .class_id = (_c_id),	\
719 	  .driver_data = (unsigned long)(_drv_data) }
720 
721 #define SDW_SLAVE_ENTRY(_mfg_id, _part_id, _drv_data)	\
722 	SDW_SLAVE_ENTRY_EXT((_mfg_id), (_part_id), 0, 0, (_drv_data))
723 
724 int sdw_handle_slave_status(struct sdw_bus *bus,
725 			enum sdw_slave_status status[]);
726 
727 /*
728  * SDW master structures and APIs
729  */
730 
731 /**
732  * struct sdw_port_params: Data Port parameters
733  *
734  * @num: Port number
735  * @bps: Word length of the Port
736  * @flow_mode: Port Data flow mode
737  * @data_mode: Test modes or normal mode
738  *
739  * This is used to program the Data Port based on Data Port stream
740  * parameters.
741  */
742 struct sdw_port_params {
743 	unsigned int num;
744 	unsigned int bps;
745 	unsigned int flow_mode;
746 	unsigned int data_mode;
747 };
748 
749 /**
750  * struct sdw_transport_params: Data Port Transport Parameters
751  *
752  * @blk_grp_ctrl_valid: Port implements block group control
753  * @num: Port number
754  * @blk_grp_ctrl: Block group control value
755  * @sample_interval: Sample interval
756  * @offset1: Blockoffset of the payload data
757  * @offset2: Blockoffset of the payload data
758  * @hstart: Horizontal start of the payload data
759  * @hstop: Horizontal stop of the payload data
760  * @blk_pkg_mode: Block per channel or block per port
761  * @lane_ctrl: Data lane Port uses for Data transfer. Currently only single
762  * data lane is supported in bus
763  *
764  * This is used to program the Data Port based on Data Port transport
765  * parameters. All these parameters are banked and can be modified
766  * during a bank switch without any artifacts in audio stream.
767  */
768 struct sdw_transport_params {
769 	bool blk_grp_ctrl_valid;
770 	unsigned int port_num;
771 	unsigned int blk_grp_ctrl;
772 	unsigned int sample_interval;
773 	unsigned int offset1;
774 	unsigned int offset2;
775 	unsigned int hstart;
776 	unsigned int hstop;
777 	unsigned int blk_pkg_mode;
778 	unsigned int lane_ctrl;
779 };
780 
781 /**
782  * struct sdw_enable_ch: Enable/disable Data Port channel
783  *
784  * @num: Port number
785  * @ch_mask: Active channel mask
786  * @enable: Enable (true) /disable (false) channel
787  */
788 struct sdw_enable_ch {
789 	unsigned int port_num;
790 	unsigned int ch_mask;
791 	bool enable;
792 };
793 
794 /**
795  * struct sdw_master_port_ops: Callback functions from bus to Master
796  * driver to set Master Data ports.
797  *
798  * @dpn_set_port_params: Set the Port parameters for the Master Port.
799  * Mandatory callback
800  * @dpn_set_port_transport_params: Set transport parameters for the Master
801  * Port. Mandatory callback
802  * @dpn_port_prep: Port prepare operations for the Master Data Port.
803  * @dpn_port_enable_ch: Enable the channels of Master Port.
804  */
805 struct sdw_master_port_ops {
806 	int (*dpn_set_port_params)(struct sdw_bus *bus,
807 			struct sdw_port_params *port_params,
808 			unsigned int bank);
809 	int (*dpn_set_port_transport_params)(struct sdw_bus *bus,
810 			struct sdw_transport_params *transport_params,
811 			enum sdw_reg_bank bank);
812 	int (*dpn_port_prep)(struct sdw_bus *bus,
813 			struct sdw_prepare_ch *prepare_ch);
814 	int (*dpn_port_enable_ch)(struct sdw_bus *bus,
815 			struct sdw_enable_ch *enable_ch, unsigned int bank);
816 };
817 
818 struct sdw_msg;
819 
820 /**
821  * struct sdw_defer - SDW deffered message
822  * @length: message length
823  * @complete: message completion
824  * @msg: SDW message
825  */
826 struct sdw_defer {
827 	int length;
828 	struct completion complete;
829 	struct sdw_msg *msg;
830 };
831 
832 /**
833  * struct sdw_master_ops - Master driver ops
834  * @read_prop: Read Master properties
835  * @override_adr: Override value read from firmware (quirk for buggy firmware)
836  * @xfer_msg: Transfer message callback
837  * @xfer_msg_defer: Defer version of transfer message callback
838  * @reset_page_addr: Reset the SCP page address registers
839  * @set_bus_conf: Set the bus configuration
840  * @pre_bank_switch: Callback for pre bank switch
841  * @post_bank_switch: Callback for post bank switch
842  * @read_ping_status: Read status from PING frames, reported with two bits per Device.
843  * Bits 31:24 are reserved.
844  */
845 struct sdw_master_ops {
846 	int (*read_prop)(struct sdw_bus *bus);
847 	u64 (*override_adr)
848 			(struct sdw_bus *bus, u64 addr);
849 	enum sdw_command_response (*xfer_msg)
850 			(struct sdw_bus *bus, struct sdw_msg *msg);
851 	enum sdw_command_response (*xfer_msg_defer)
852 			(struct sdw_bus *bus, struct sdw_msg *msg,
853 			struct sdw_defer *defer);
854 	enum sdw_command_response (*reset_page_addr)
855 			(struct sdw_bus *bus, unsigned int dev_num);
856 	int (*set_bus_conf)(struct sdw_bus *bus,
857 			struct sdw_bus_params *params);
858 	int (*pre_bank_switch)(struct sdw_bus *bus);
859 	int (*post_bank_switch)(struct sdw_bus *bus);
860 	u32 (*read_ping_status)(struct sdw_bus *bus);
861 
862 };
863 
864 /**
865  * struct sdw_bus - SoundWire bus
866  * @dev: Shortcut to &bus->md->dev to avoid changing the entire code.
867  * @md: Master device
868  * @link_id: Link id number, can be 0 to N, unique for each Master
869  * @id: bus system-wide unique id
870  * @slaves: list of Slaves on this bus
871  * @assigned: Bitmap for Slave device numbers.
872  * Bit set implies used number, bit clear implies unused number.
873  * @bus_lock: bus lock
874  * @msg_lock: message lock
875  * @compute_params: points to Bus resource management implementation
876  * @ops: Master callback ops
877  * @port_ops: Master port callback ops
878  * @params: Current bus parameters
879  * @prop: Master properties
880  * @m_rt_list: List of Master instance of all stream(s) running on Bus. This
881  * is used to compute and program bus bandwidth, clock, frame shape,
882  * transport and port parameters
883  * @debugfs: Bus debugfs
884  * @defer_msg: Defer message
885  * @clk_stop_timeout: Clock stop timeout computed
886  * @bank_switch_timeout: Bank switch timeout computed
887  * @multi_link: Store bus property that indicates if multi links
888  * are supported. This flag is populated by drivers after reading
889  * appropriate firmware (ACPI/DT).
890  * @hw_sync_min_links: Number of links used by a stream above which
891  * hardware-based synchronization is required. This value is only
892  * meaningful if multi_link is set. If set to 1, hardware-based
893  * synchronization will be used even if a stream only uses a single
894  * SoundWire segment.
895  * @dev_num_ida_min: if set, defines the minimum values for the IDA
896  * used to allocate system-unique device numbers. This value needs to be
897  * identical across all SoundWire bus in the system.
898  */
899 struct sdw_bus {
900 	struct device *dev;
901 	struct sdw_master_device *md;
902 	unsigned int link_id;
903 	int id;
904 	struct list_head slaves;
905 	DECLARE_BITMAP(assigned, SDW_MAX_DEVICES);
906 	struct mutex bus_lock;
907 	struct mutex msg_lock;
908 	int (*compute_params)(struct sdw_bus *bus);
909 	const struct sdw_master_ops *ops;
910 	const struct sdw_master_port_ops *port_ops;
911 	struct sdw_bus_params params;
912 	struct sdw_master_prop prop;
913 	struct list_head m_rt_list;
914 #ifdef CONFIG_DEBUG_FS
915 	struct dentry *debugfs;
916 #endif
917 	struct sdw_defer defer_msg;
918 	unsigned int clk_stop_timeout;
919 	u32 bank_switch_timeout;
920 	bool multi_link;
921 	int hw_sync_min_links;
922 	int dev_num_ida_min;
923 };
924 
925 int sdw_bus_master_add(struct sdw_bus *bus, struct device *parent,
926 		       struct fwnode_handle *fwnode);
927 void sdw_bus_master_delete(struct sdw_bus *bus);
928 
929 void sdw_show_ping_status(struct sdw_bus *bus, bool sync_delay);
930 
931 /**
932  * sdw_port_config: Master or Slave Port configuration
933  *
934  * @num: Port number
935  * @ch_mask: channels mask for port
936  */
937 struct sdw_port_config {
938 	unsigned int num;
939 	unsigned int ch_mask;
940 };
941 
942 /**
943  * sdw_stream_config: Master or Slave stream configuration
944  *
945  * @frame_rate: Audio frame rate of the stream, in Hz
946  * @ch_count: Channel count of the stream
947  * @bps: Number of bits per audio sample
948  * @direction: Data direction
949  * @type: Stream type PCM or PDM
950  */
951 struct sdw_stream_config {
952 	unsigned int frame_rate;
953 	unsigned int ch_count;
954 	unsigned int bps;
955 	enum sdw_data_direction direction;
956 	enum sdw_stream_type type;
957 };
958 
959 /**
960  * sdw_stream_state: Stream states
961  *
962  * @SDW_STREAM_ALLOCATED: New stream allocated.
963  * @SDW_STREAM_CONFIGURED: Stream configured
964  * @SDW_STREAM_PREPARED: Stream prepared
965  * @SDW_STREAM_ENABLED: Stream enabled
966  * @SDW_STREAM_DISABLED: Stream disabled
967  * @SDW_STREAM_DEPREPARED: Stream de-prepared
968  * @SDW_STREAM_RELEASED: Stream released
969  */
970 enum sdw_stream_state {
971 	SDW_STREAM_ALLOCATED = 0,
972 	SDW_STREAM_CONFIGURED = 1,
973 	SDW_STREAM_PREPARED = 2,
974 	SDW_STREAM_ENABLED = 3,
975 	SDW_STREAM_DISABLED = 4,
976 	SDW_STREAM_DEPREPARED = 5,
977 	SDW_STREAM_RELEASED = 6,
978 };
979 
980 /**
981  * sdw_stream_params: Stream parameters
982  *
983  * @rate: Sampling frequency, in Hz
984  * @ch_count: Number of channels
985  * @bps: bits per channel sample
986  */
987 struct sdw_stream_params {
988 	unsigned int rate;
989 	unsigned int ch_count;
990 	unsigned int bps;
991 };
992 
993 /**
994  * sdw_stream_runtime: Runtime stream parameters
995  *
996  * @name: SoundWire stream name
997  * @params: Stream parameters
998  * @state: Current state of the stream
999  * @type: Stream type PCM or PDM
1000  * @master_list: List of Master runtime(s) in this stream.
1001  * master_list can contain only one m_rt per Master instance
1002  * for a stream
1003  * @m_rt_count: Count of Master runtime(s) in this stream
1004  */
1005 struct sdw_stream_runtime {
1006 	const char *name;
1007 	struct sdw_stream_params params;
1008 	enum sdw_stream_state state;
1009 	enum sdw_stream_type type;
1010 	struct list_head master_list;
1011 	int m_rt_count;
1012 };
1013 
1014 struct sdw_stream_runtime *sdw_alloc_stream(const char *stream_name);
1015 void sdw_release_stream(struct sdw_stream_runtime *stream);
1016 
1017 int sdw_compute_params(struct sdw_bus *bus);
1018 
1019 int sdw_stream_add_master(struct sdw_bus *bus,
1020 		struct sdw_stream_config *stream_config,
1021 		struct sdw_port_config *port_config,
1022 		unsigned int num_ports,
1023 		struct sdw_stream_runtime *stream);
1024 int sdw_stream_add_slave(struct sdw_slave *slave,
1025 		struct sdw_stream_config *stream_config,
1026 		struct sdw_port_config *port_config,
1027 		unsigned int num_ports,
1028 		struct sdw_stream_runtime *stream);
1029 int sdw_stream_remove_master(struct sdw_bus *bus,
1030 		struct sdw_stream_runtime *stream);
1031 int sdw_stream_remove_slave(struct sdw_slave *slave,
1032 		struct sdw_stream_runtime *stream);
1033 int sdw_startup_stream(void *sdw_substream);
1034 int sdw_prepare_stream(struct sdw_stream_runtime *stream);
1035 int sdw_enable_stream(struct sdw_stream_runtime *stream);
1036 int sdw_disable_stream(struct sdw_stream_runtime *stream);
1037 int sdw_deprepare_stream(struct sdw_stream_runtime *stream);
1038 void sdw_shutdown_stream(void *sdw_substream);
1039 int sdw_bus_prep_clk_stop(struct sdw_bus *bus);
1040 int sdw_bus_clk_stop(struct sdw_bus *bus);
1041 int sdw_bus_exit_clk_stop(struct sdw_bus *bus);
1042 
1043 /* messaging and data APIs */
1044 
1045 int sdw_read(struct sdw_slave *slave, u32 addr);
1046 int sdw_write(struct sdw_slave *slave, u32 addr, u8 value);
1047 int sdw_write_no_pm(struct sdw_slave *slave, u32 addr, u8 value);
1048 int sdw_read_no_pm(struct sdw_slave *slave, u32 addr);
1049 int sdw_nread(struct sdw_slave *slave, u32 addr, size_t count, u8 *val);
1050 int sdw_nwrite(struct sdw_slave *slave, u32 addr, size_t count, const u8 *val);
1051 int sdw_update(struct sdw_slave *slave, u32 addr, u8 mask, u8 val);
1052 int sdw_update_no_pm(struct sdw_slave *slave, u32 addr, u8 mask, u8 val);
1053 
1054 int sdw_compare_devid(struct sdw_slave *slave, struct sdw_slave_id id);
1055 void sdw_extract_slave_id(struct sdw_bus *bus, u64 addr, struct sdw_slave_id *id);
1056 
1057 #endif /* __SOUNDWIRE_H */
1058