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