include/spd_bin.h: Add SPD IO layer
[coreboot2.git] / src / include / device / soundwire.h
blob27421dd5a2bd9093c6b6b3e28c62bf2cfb573f8e
1 /* SPDX-License-Identifier: GPL-2.0-only */
3 /*
4 * This header implements structures to describe the properties defined in the
5 * SoundWire Discovery and Configuration (DisCo) Specification Version 1.0.
7 * This is available for non-members after providing a name and email address at
8 * https://resources.mipi.org/disco_soundwire
10 * The structure members mirror the property names defined in the specification,
11 * with the exception that '-' is transformed into '_' for compatible naming.
13 * See Documentation/drivers/soundwire.md for more information.
16 #ifndef __DEVICE_SOUNDWIRE_H__
17 #define __DEVICE_SOUNDWIRE_H__
19 #include <types.h>
21 /**
22 * enum soundwire_limits - Limits on number of SoundWire devices in topology.
23 * @SOUNDWIRE_MAX: Maximum value for lists of configuration values in SoundWire devices.
24 * @SOUNDWIRE_MIN_DPN: Data Port minimum value. DPn range is 1-14.
25 * @SOUNDWIRE_MAX_DPN: Data Port maximum value. DPn range is 1-14.
26 * @SOUNDWIRE_MAX_SLAVE: Maximum number of slave devices that can be attached to one master.
27 * @SOUNDWIRE_MAX_LINK: Maximum number of master link devices that can be on one controller.
28 * @SOUNDWIRE_MAX_LANE: Maximum number of lanes in a multi-lane slave device.
29 * @SOUNDWIRE_MAX_MODE: Maximum number of Audio or Bulk Register Access modes.
31 enum soundwire_limits {
32 SOUNDWIRE_MAX = 32,
33 SOUNDWIRE_MIN_DPN = 1,
34 SOUNDWIRE_MAX_DPN = 14,
35 SOUNDWIRE_MAX_SLAVE = 11,
36 SOUNDWIRE_MAX_LINK = 8,
37 SOUNDWIRE_MAX_LANE = 8,
38 SOUNDWIRE_MAX_MODE = 4
41 /**
42 * enum soundwire_sw_version - Versions of SoundWire Discovery and Configuration Specification.
43 * @SOUNDWIRE_SW_VERSION_1_0: DisCo Specification Version 1.0 released November 2016.
45 enum soundwire_sw_version {
46 SOUNDWIRE_SW_VERSION_1_0 = 0x00010000
49 /**
50 * enum soundwire_version - Versions of SoundWire Specification supported by a device.
51 * @SOUNDWIRE_VERSION_1_0: SoundWire Specification Version 1.0 released January 2015.
52 * @SOUNDWIRE_VERSION_1_1: SoundWire Specification Version 1.1 released June 2016.
53 * @SOUNDWIRE_VERSION_1_2: SoundWire Specification Version 1.2 released April 2019.
55 enum soundwire_version {
56 SOUNDWIRE_VERSION_1_0 = 1,
57 SOUNDWIRE_VERSION_1_1,
58 SOUNDWIRE_VERSION_1_2
61 /**
62 * enum mipi_class - MIPI class encoding.
63 * @MIPI_CLASS_NONE: No further class decoding.
64 * @MIPI_CLASS_SDCA: Device implements SoundWire Device Class for Audio (SDCA).
66 * 0x02-0x7F: Reserved
67 * 0x80-0xFF: MIPI Alliance extended device class
69 enum mipi_class {
70 MIPI_CLASS_NONE,
71 MIPI_CLASS_SDCA
74 /**
75 * struct soundwire_address - SoundWire Device Address Encoding.
76 * @version: SoundWire specification version from &enum soundwire_version.
77 * @link_id: Zero-based SoundWire master link id.
78 * @unique_id: Unique ID for multiple slave devices on the same bus.
79 * @manufacturer_id: Manufacturer ID from include/mipi/ids.h.
80 * @part_id: Vendor defined part ID.
81 * @class: MIPI class encoding in &enum mipi_class.
83 struct soundwire_address {
84 enum soundwire_version version;
85 uint8_t link_id;
86 uint8_t unique_id;
87 uint16_t manufacturer_id;
88 uint16_t part_id;
89 enum mipi_class class;
92 /**
93 * struct soundwire_link - SoundWire master device properties.
94 * @clock_stop_mode0_supported: %true if clock stop mode0 is supported by this device.
95 * @clock_stop_mode1_supported: %true if clock stop mode1 is supported by this device.
96 * @max_clock_frequency: Maximum bus clock for this device in Hz.
97 * @supported_clock_gears_count: Number of entries in supported_clock_gears.
98 * @supported_clock_gears: One entry for each supported clock gear.
99 * @clock_frequencies_supported_count: Number of entries in clock_frequencies_supported.
100 * @clock_frequencies_supported: One entry for each clock frequency supported in Hz.
101 * @default_frame_rate: Controller default frame rate in Hz.
102 * @default_frame_row_size: Number of rows between 48-256.
103 * @default_frame_col_size: Number of columns: 2, 4, 8, 16.
104 * @dynamic_frame_shape: %true if bus driver may change frame shape dynamically.
105 * @command_error_threshold: Number of times that software may retry sending a command.
107 struct soundwire_link {
108 bool clock_stop_mode0_supported;
109 bool clock_stop_mode1_supported;
110 unsigned int max_clock_frequency;
111 size_t supported_clock_gears_count;
112 unsigned int supported_clock_gears[SOUNDWIRE_MAX];
113 size_t clock_frequencies_supported_count;
114 uint64_t clock_frequencies_supported[SOUNDWIRE_MAX];
115 unsigned int default_frame_rate;
116 unsigned int default_frame_row_size;
117 unsigned int default_frame_col_size;
118 bool dynamic_frame_shape;
119 unsigned int command_error_threshold;
123 * struct soundwire_controller - SoundWire controller properties.
124 * @master_count: Number of masters present on this device.
125 * @master_list: One entry for each master device.
127 struct soundwire_controller {
128 unsigned int master_list_count;
129 struct soundwire_link master_list[SOUNDWIRE_MAX_LINK];
132 /* SoundWire port bitmask, used for slave source/sink port list property. */
133 #define SOUNDWIRE_PORT(port) BIT(port)
136 * struct soundwire_slave - SoundWire slave device properties.
137 * @wake_up_unavailable: Wake from this device is not supported or allowed.
138 * @test_mode_supported: %true if test mode is supported by this device.
139 * @clock_stop_mode1_supported: %true if clock stop mode1 is supported by this device.
140 * @simplified_clockstopprepare_sm_supported: %true if slave only supports the simplified
141 * clock stop prepare state machine and will
142 * always be ready for a stop clock transition.
143 * @clockstopprepare_timeout: Slave-specific timeout in milliseconds.
144 * @clockstopprepare_hard_reset_behavior: %true when slave keeps the status of the
145 * StopClockPrepare state machine after exit from
146 * mode1 and must be de-prepared by software.
147 * @slave_channelprepare_timeout: Slave-specific timeout in milliseconds.
148 * @highPHY_capable: %true if device is HighPHY capable.
149 * @paging_supported: %true if device implements paging registers.
150 * @bank_delay_supported: %true if device implements bank delay/bridge registers.
151 * @port15_read_behavior: %true if device supports read to Port15 alias.
152 * @master_count: Number of master links present on this slave.
153 * @source_port_list: Bitmap identifying supported source ports, starting at bit 1.
154 * @sink_port_list: Bitmap identifying supported sink ports, starting at bit 1.
156 struct soundwire_slave {
157 bool wake_up_unavailable;
158 bool test_mode_supported;
159 bool clock_stop_mode1_supported;
160 bool simplified_clockstopprepare_sm_supported;
161 unsigned int clockstopprepare_timeout;
162 bool clockstopprepare_hard_reset_behavior;
163 unsigned int slave_channelprepare_timeout;
164 bool highPHY_capable;
165 bool paging_supported;
166 bool bank_delay_supported;
167 bool port15_read_behavior;
168 size_t master_count;
169 uint32_t source_port_list;
170 uint32_t sink_port_list;
174 * enum soundwire_multilane_dir - Direction of lane in slave multilane device.
175 * @MASTER_LANE: Lane is connected to a master device.
176 * @SLAVE_LINK: Lane is connected to a slave device.
178 enum soundwire_multilane_dir {
179 MASTER_LANE,
180 SLAVE_LINK,
184 * struct soundwire_multilane_map - Pair a soundwire lane with direction.
185 * @lane: Slave device lane number.
186 * @direction: Direction of the slave lane.
187 * @connection: The connection that this lane makes.
189 struct soundwire_multilane_map {
190 unsigned int lane;
191 enum soundwire_multilane_dir direction;
192 union lane_type {
193 unsigned int master_lane;
194 unsigned int slave_link;
195 } connection;
199 * struct soundwire_multilane - Multi-Lane SoundWire slave device.
200 * @lane_mapping_count: Number of entries in lane_mapping.
201 * @lane_mapping: One entry for each lane that is connected to lanes on a master device or
202 * slave devices via a slave link. Lane 0 is always connected to the master
203 * and entry 0 in this array is ignored.
204 * @lane_bus_holder_count: Number of entries in lane_bus_holder.
205 * @lane_bus_holder: One entry for each lane, %true if the device behaves as a bus holder.
207 struct soundwire_multilane {
208 size_t lane_mapping_count;
209 struct soundwire_multilane_map lane_mapping[SOUNDWIRE_MAX_LANE];
210 size_t lane_bus_holder_count;
211 bool lane_bus_holder[SOUNDWIRE_MAX_LANE];
215 * enum soundwire_prepare_channel_behavior - Specifies the dependencies between the
216 * Channel Prepare sequence and bus clock config.
217 * @CHANNEL_PREPARE_ANY_FREQUENCY: Channel Prepare can happen at any bus clock rate.
218 * @CHANNEL_PREPARE_SUPPORTED_FREQUENCY: Channel Prepare sequence shall happen only after
219 * the bus clock is changed to a supported frequency.
221 enum soundwire_prepare_channel_behavior {
222 CHANNEL_PREPARE_ANY_FREQUENCY,
223 CHANNEL_PREPARE_SUPPORTED_FREQUENCY
227 * struct soundwire_audio_mode - Properties for each supported Audio Mode.
228 * @sdw_name: SoundWire device name for this audio mode device instance.
229 * @max_bus_frequency: Maximum bus frequency of this mode in Hz.
230 * @min_bus_frequency: Minimum bus frequency of this mode in Hz.
231 * @bus_frequency_configs_count: Number of entries in bus_frequency_configs.
232 * @bus_frequency_configs: One entry for each supported bus frequency,
233 * if not all values in min to max range are valid.
234 * @max_sampling_frequency: Maximum sampling frequency of this mode in Hz.
235 * @min_sampling_frequency: Minimum sampling frequency of this mode in Hz.
236 * @sampling_frequency_configs_count: Number of entries in sampling_frequency_configs.
237 * @sampling_frequency_configs: One entry for each supported sampling frequency,
238 * if not all values in min to max range are valid.
239 * @prepare_channel_behavior: Dependencies between Channel Prepare and bus clock.
240 * @glitchless_transitions: Bitmap describing possible glitchless transitions from this audio
241 * mode to another audio mode. Not used for only one mode.
243 struct soundwire_audio_mode {
244 unsigned int max_bus_frequency;
245 unsigned int min_bus_frequency;
246 size_t bus_frequency_configs_count;
247 uint64_t bus_frequency_configs[SOUNDWIRE_MAX];
248 unsigned int max_sampling_frequency;
249 unsigned int min_sampling_frequency;
250 size_t sampling_frequency_configs_count;
251 uint64_t sampling_frequency_configs[SOUNDWIRE_MAX];
252 enum soundwire_prepare_channel_behavior prepare_channel_behavior;
253 uint32_t glitchless_transitions;
256 /* Type of SoundWire Data Port supported for this device. */
257 enum soundwire_data_port_type {
258 FULL_DATA_PORT,
259 SIMPLIFIED_DATA_PORT,
260 REDUCED_DATA_PORT
263 /* Number of samples that can be grouped together (0-based count). */
264 enum soundwire_block_group_count {
265 BLOCK_GROUP_COUNT_1,
266 BLOCK_GROUP_COUNT_2,
267 BLOCK_GROUP_COUNT_3,
268 BLOCK_GROUP_COUNT_4
271 /* Bitmap identifying the types of modes supported. */
272 enum soundwire_mode_bitmap {
273 MODE_ISOCHRONOUS = BIT(0),
274 MODE_TX_CONTROLLED = BIT(1),
275 MODE_RX_CONTROLLED = BIT(2),
276 MODE_FULL_ASYNCHRONOUS = BIT(3)
279 /* Bitmap identifying the encoding schemes supported. */
280 enum soundwire_port_encoding_bitmap {
281 ENCODE_TWOS_COMPLEMENT = BIT(0),
282 ENCODE_SIGN_MAGNITUDE = BIT(1),
283 ENCODE_IEEE_32BIT_FP = BIT(2)
287 * struct soundwire_dpn - Configuration properties for SoundWire DPn Data Ports.
288 * @port_max_wordlength: Maximum number of bits in a Payload Channel Sample. (1-64)
289 * @port_min_wordlength: Minimum number of bits in a Payload Channel Sample. (1-64)
290 * @port_wordlength_configs_count: Number of entries in port_wordlength_configs.
291 * @port_wordlength_configs: One entry for each supported wordlength.
292 * Used if only specific wordlength values are allowed.
293 * @data_port_type: Type of data port from &enum soundwire_data_port_type.
294 * @max_grouping_supported: 0-based maximum number of samples that can be grouped for
295 * %FULL_DATA_PORT. The %SIMPLIFIED_DATA_PORT and %REDUCED_DATA_PORT
296 * require 4 samples in a group.
297 * @simplified_channelprepare_sm: %true if the channel prepare sequence is not required,
298 * and the Port Ready interrupt is not supported.
299 * @port_channelprepare_timeout: Port-specific timeout value in milliseconds.
300 * @imp_def_dpn_interrupts_supported: Bitmap for support of implementation-defined interrupts.
301 * @min_channel_number: Minimum channel number supported.
302 * @max_channel_number: Maximum channel number supported.
303 * @channel_number_list_count: Number of entries in channel_number_list.
304 * @channel_number_list: One entry for each available channel number.
305 * Used if only specific channels are available.
306 * @channel_combination_list_count: Number of entries in channel_combination_list.
307 * @channel_combination_list: One bitmap entry for each valid channel combination.
308 * @modes_supported: Bitmap identifying the types of modes supported by the device.
309 * @max_async_buffer: Number of samples that this port can buffer in asynchronous modes.
310 * Only required if the slave implements buffer larger than required.
311 * @block_packing_mode: %true if BlockPackingMode may be configured as BlockPerPort or
312 * BlocKPerChannel. %false if BlockPackingMode must be BlockPerPort.
313 * @port_encoding_type: Bitmap describing the types of Payload Channel Sample encoding
314 * schemes implemented by this port.
315 * @port_audio_mode_count: Number of entries in audio_mode_list.
316 * @port_audio_mode_list: One entry for each supported audio mode id.
318 struct soundwire_dpn {
319 unsigned int port_max_wordlength;
320 unsigned int port_min_wordlength;
321 size_t port_wordlength_configs_count;
322 uint64_t port_wordlength_configs[SOUNDWIRE_MAX];
323 enum soundwire_data_port_type data_port_type;
324 enum soundwire_block_group_count max_grouping_supported;
325 bool simplified_channelprepare_sm;
326 unsigned int port_channelprepare_timeout;
327 uint32_t imp_def_dpn_interrupts_supported;
328 unsigned int min_channel_number;
329 unsigned int max_channel_number;
330 size_t channel_number_list_count;
331 uint64_t channel_number_list[SOUNDWIRE_MAX];
332 size_t channel_combination_list_count;
333 uint64_t channel_combination_list[SOUNDWIRE_MAX];
334 enum soundwire_mode_bitmap modes_supported;
335 unsigned int max_async_buffer;
336 bool block_packing_mode;
337 uint32_t port_encoding_type;
338 size_t port_audio_mode_count;
339 unsigned int port_audio_mode_list[SOUNDWIRE_MAX_MODE];
343 * struct soundwire_bra_mode - Bulk Register Access mode properties.
344 * @max_bus_frequency: Maximum bus frequency of this mode in Hz.
345 * @min_bus_frequency: Minimum bus frequency of this mode in Hz.
346 * @bus_frequency_configs_count: Number of entries in bus_frequency_configs.
347 * @bus_frequency_configs: One entry for each supported bus frequency,
348 * Used if not all values in min to max range are valid.
349 * @max_data_per_frame: Maximum data bytes per frame, excluding header, CRC, and footer.
350 * @min_us_between_transactions: Amount of delay in uS required between transactions.
351 * @max_bandwidth: Maximum bandwidth in bytes per second that can be written/read.
352 * @block_alignment: Size of basic block in bytes.
354 struct soundwire_bra_mode {
355 unsigned int max_bus_frequency;
356 unsigned int min_bus_frequency;
357 size_t bus_frequency_configs_count;
358 uint64_t bus_frequency_configs[SOUNDWIRE_MAX];
359 unsigned int max_data_per_frame;
360 unsigned int min_us_between_transactions;
361 unsigned int max_bandwidth;
362 unsigned int block_alignment;
366 * struct soundwire_dp0 - Configuration properties for SoundWire DP0 Data Port.
367 * @port_max_wordlength: Maximum number of bits in a Payload Channel Sample. (1-64)
368 * @port_min_wordlength: Minimum number of bits in a Payload Channel Sample. (1-64)
369 * @port_wordlength_configs_count: Number of entries in port_wordlength_configs.
370 * @port_wordlength_configs: One entry for each supported wordlength.
371 * Used if only specific wordlength values are allowed.
372 * @bra_flow_controlled: Used if the slave can result in an OK_NotReady response.
373 * @bra_imp_def_response_supported: %true if implementation defined response is supported.
374 * @bra_role_supported: %true if the slave supports initiating BRA transactions.
375 * @simplified_channel_prepare_sm: %true if the channel prepare sequence is not required,
376 * and the Port Ready interrupt is not supported.
377 * @imp_def_dp0_interrupts_supported: If set, each bit corresponds to support for
378 * implementation-defined interrupts ImpDef.
379 * @imp_def_bpt_supported: %true if implementation defined Payload Type is supported.
380 * @bra_mode_count: Number of entries in bra_mode_list.
381 * @bra_mode_list: One entry for each supported Bulk Register Access mode id.
383 struct soundwire_dp0 {
384 unsigned int port_max_wordlength;
385 unsigned int port_min_wordlength;
386 size_t port_wordlength_configs_count;
387 uint64_t port_wordlength_configs[SOUNDWIRE_MAX];
388 bool bra_flow_controlled;
389 bool bra_imp_def_response_supported;
390 bool bra_role_supported;
391 bool simplified_channel_prepare_sm;
392 unsigned int imp_def_dp0_interrupts_supported;
393 bool imp_def_bpt_supported;
394 size_t bra_mode_count;
395 unsigned int bra_mode_list[SOUNDWIRE_MAX_MODE];
399 * struct soundwire_dpn_entry - Full duplex data port properties for DPn 1-14.
400 * @port: DPn data port number, starting at 1.
401 * @source: Source data port properties. (optional)
402 * @sink: Sink data port properties. (optional)
404 struct soundwire_dpn_entry {
405 size_t port;
406 struct soundwire_dpn *source;
407 struct soundwire_dpn *sink;
411 * struct soundwire_codec - Contains all configuration for a SoundWire codec slave device.
412 * @slave: Properties for slave device.
413 * @audio_mode: Properties for audio modes used by DPn data ports 1-14.
414 * @dpn: Properties for DPn data ports 1-14.
415 * @dp0_bra_mode: Properties for Bulk Register Access mode for data port 0. (optional)
416 * @dp0: Properties for data port 0. (optional)
417 * @multilane: Properties for slave multilane device. (optional)
419 struct soundwire_codec {
420 struct soundwire_slave *slave;
421 struct soundwire_audio_mode *audio_mode[SOUNDWIRE_MAX_MODE];
422 struct soundwire_dpn_entry dpn[SOUNDWIRE_MAX_DPN];
423 struct soundwire_bra_mode *dp0_bra_mode[SOUNDWIRE_MAX_MODE];
424 struct soundwire_dp0 *dp0;
425 struct soundwire_multilane *multilane;
428 #endif /* __DEVICE_SOUNDWIRE_H__ */