1 /* SPDX-License-Identifier: GPL-2.0-only */ 2 3 /* 4 * This header implements structures to describe the properties defined in the 5 * SoundWire Discovery and Configuration (DisCo) Specification Version 1.0. 6 * 7 * This is available for non-members after providing a name and email address at 8 * https://resources.mipi.org/disco_soundwire 9 * 10 * The structure members mirror the property names defined in the specification, 11 * with the exception that '-' is transformed into '_' for compatible naming. 12 * 13 * See Documentation/drivers/soundwire.md for more information. 14 */ 15 16 #ifndef __DEVICE_SOUNDWIRE_H__ 17 #define __DEVICE_SOUNDWIRE_H__ 18 19 #include <types.h> 20 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. 30 */ 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 39 }; 40 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. 44 */ 45 enum soundwire_sw_version { 46 SOUNDWIRE_SW_VERSION_1_0 = 0x00010000 47 }; 48 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. 54 */ 55 enum soundwire_version { 56 SOUNDWIRE_VERSION_1_0 = 1, 57 SOUNDWIRE_VERSION_1_1, 58 SOUNDWIRE_VERSION_1_2 59 }; 60 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). 65 * 66 * 0x02-0x7F: Reserved 67 * 0x80-0xFF: MIPI Alliance extended device class 68 */ 69 enum mipi_class { 70 MIPI_CLASS_NONE, 71 MIPI_CLASS_SDCA 72 }; 73 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. 82 */ 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; 90 }; 91 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. 106 */ 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; 120 }; 121 122 /** 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. 126 */ 127 struct soundwire_controller { 128 unsigned int master_list_count; 129 struct soundwire_link master_list[SOUNDWIRE_MAX_LINK]; 130 }; 131 132 /* SoundWire port bitmask, used for slave source/sink port list property. */ 133 #define SOUNDWIRE_PORT(port) BIT(port) 134 135 /** 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. 155 */ 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; 171 }; 172 173 /** 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. 177 */ 178 enum soundwire_multilane_dir { 179 MASTER_LANE, 180 SLAVE_LINK, 181 }; 182 183 /** 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. 188 */ 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; 196 }; 197 198 /** 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. 206 */ 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]; 212 }; 213 214 /** 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. 220 */ 221 enum soundwire_prepare_channel_behavior { 222 CHANNEL_PREPARE_ANY_FREQUENCY, 223 CHANNEL_PREPARE_SUPPORTED_FREQUENCY 224 }; 225 226 /** 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. 242 */ 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; 254 }; 255 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 261 }; 262 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 269 }; 270 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) 277 }; 278 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) 284 }; 285 286 /** 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. 317 */ 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]; 340 }; 341 342 /** 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. 353 */ 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; 363 }; 364 365 /** 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. 382 */ 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]; 396 }; 397 398 /** 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) 403 */ 404 struct soundwire_dpn_entry { 405 size_t port; 406 struct soundwire_dpn *source; 407 struct soundwire_dpn *sink; 408 }; 409 410 /** 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) 418 */ 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; 426 }; 427 428 #endif /* __DEVICE_SOUNDWIRE_H__ */ 429