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 struct sdw_bus; 8 struct sdw_slave; 9 10 /* SDW spec defines and enums, as defined by MIPI 1.1. Spec */ 11 12 /* SDW Broadcast Device Number */ 13 #define SDW_BROADCAST_DEV_NUM 15 14 15 /* SDW Enumeration Device Number */ 16 #define SDW_ENUM_DEV_NUM 0 17 18 /* SDW Group Device Numbers */ 19 #define SDW_GROUP12_DEV_NUM 12 20 #define SDW_GROUP13_DEV_NUM 13 21 22 /* SDW Master Device Number, not supported yet */ 23 #define SDW_MASTER_DEV_NUM 14 24 25 #define SDW_NUM_DEV_ID_REGISTERS 6 26 27 #define SDW_MAX_DEVICES 11 28 29 /** 30 * enum sdw_slave_status - Slave status 31 * @SDW_SLAVE_UNATTACHED: Slave is not attached with the bus. 32 * @SDW_SLAVE_ATTACHED: Slave is attached with bus. 33 * @SDW_SLAVE_ALERT: Some alert condition on the Slave 34 * @SDW_SLAVE_RESERVED: Reserved for future use 35 */ 36 enum sdw_slave_status { 37 SDW_SLAVE_UNATTACHED = 0, 38 SDW_SLAVE_ATTACHED = 1, 39 SDW_SLAVE_ALERT = 2, 40 SDW_SLAVE_RESERVED = 3, 41 }; 42 43 /** 44 * enum sdw_command_response - Command response as defined by SDW spec 45 * @SDW_CMD_OK: cmd was successful 46 * @SDW_CMD_IGNORED: cmd was ignored 47 * @SDW_CMD_FAIL: cmd was NACKed 48 * @SDW_CMD_TIMEOUT: cmd timedout 49 * @SDW_CMD_FAIL_OTHER: cmd failed due to other reason than above 50 * 51 * NOTE: The enum is different than actual Spec as response in the Spec is 52 * combination of ACK/NAK bits 53 * 54 * SDW_CMD_TIMEOUT/FAIL_OTHER is defined for SW use, not in spec 55 */ 56 enum sdw_command_response { 57 SDW_CMD_OK = 0, 58 SDW_CMD_IGNORED = 1, 59 SDW_CMD_FAIL = 2, 60 SDW_CMD_TIMEOUT = 3, 61 SDW_CMD_FAIL_OTHER = 4, 62 }; 63 64 /* 65 * SDW properties, defined in MIPI DisCo spec v1.0 66 */ 67 enum sdw_clk_stop_reset_behave { 68 SDW_CLK_STOP_KEEP_STATUS = 1, 69 }; 70 71 /** 72 * enum sdw_p15_behave - Slave Port 15 behaviour when the Master attempts a 73 * read 74 * @SDW_P15_READ_IGNORED: Read is ignored 75 * @SDW_P15_CMD_OK: Command is ok 76 */ 77 enum sdw_p15_behave { 78 SDW_P15_READ_IGNORED = 0, 79 SDW_P15_CMD_OK = 1, 80 }; 81 82 /** 83 * enum sdw_dpn_type - Data port types 84 * @SDW_DPN_FULL: Full Data Port is supported 85 * @SDW_DPN_SIMPLE: Simplified Data Port as defined in spec. 86 * DPN_SampleCtrl2, DPN_OffsetCtrl2, DPN_HCtrl and DPN_BlockCtrl3 87 * are not implemented. 88 * @SDW_DPN_REDUCED: Reduced Data Port as defined in spec. 89 * DPN_SampleCtrl2, DPN_HCtrl are not implemented. 90 */ 91 enum sdw_dpn_type { 92 SDW_DPN_FULL = 0, 93 SDW_DPN_SIMPLE = 1, 94 SDW_DPN_REDUCED = 2, 95 }; 96 97 /** 98 * enum sdw_clk_stop_mode - Clock Stop modes 99 * @SDW_CLK_STOP_MODE0: Slave can continue operation seamlessly on clock 100 * restart 101 * @SDW_CLK_STOP_MODE1: Slave may have entered a deeper power-saving mode, 102 * not capable of continuing operation seamlessly when the clock restarts 103 */ 104 enum sdw_clk_stop_mode { 105 SDW_CLK_STOP_MODE0 = 0, 106 SDW_CLK_STOP_MODE1 = 1, 107 }; 108 109 /** 110 * struct sdw_dp0_prop - DP0 properties 111 * @max_word: Maximum number of bits in a Payload Channel Sample, 1 to 64 112 * (inclusive) 113 * @min_word: Minimum number of bits in a Payload Channel Sample, 1 to 64 114 * (inclusive) 115 * @num_words: number of wordlengths supported 116 * @words: wordlengths supported 117 * @flow_controlled: Slave implementation results in an OK_NotReady 118 * response 119 * @simple_ch_prep_sm: If channel prepare sequence is required 120 * @device_interrupts: If implementation-defined interrupts are supported 121 * 122 * The wordlengths are specified by Spec as max, min AND number of 123 * discrete values, implementation can define based on the wordlengths they 124 * support 125 */ 126 struct sdw_dp0_prop { 127 u32 max_word; 128 u32 min_word; 129 u32 num_words; 130 u32 *words; 131 bool flow_controlled; 132 bool simple_ch_prep_sm; 133 bool device_interrupts; 134 }; 135 136 /** 137 * struct sdw_dpn_audio_mode - Audio mode properties for DPn 138 * @bus_min_freq: Minimum bus frequency, in Hz 139 * @bus_max_freq: Maximum bus frequency, in Hz 140 * @bus_num_freq: Number of discrete frequencies supported 141 * @bus_freq: Discrete bus frequencies, in Hz 142 * @min_freq: Minimum sampling frequency, in Hz 143 * @max_freq: Maximum sampling bus frequency, in Hz 144 * @num_freq: Number of discrete sampling frequency supported 145 * @freq: Discrete sampling frequencies, in Hz 146 * @prep_ch_behave: Specifies the dependencies between Channel Prepare 147 * sequence and bus clock configuration 148 * If 0, Channel Prepare can happen at any Bus clock rate 149 * If 1, Channel Prepare sequence shall happen only after Bus clock is 150 * changed to a frequency supported by this mode or compatible modes 151 * described by the next field 152 * @glitchless: Bitmap describing possible glitchless transitions from this 153 * Audio Mode to other Audio Modes 154 */ 155 struct sdw_dpn_audio_mode { 156 u32 bus_min_freq; 157 u32 bus_max_freq; 158 u32 bus_num_freq; 159 u32 *bus_freq; 160 u32 max_freq; 161 u32 min_freq; 162 u32 num_freq; 163 u32 *freq; 164 u32 prep_ch_behave; 165 u32 glitchless; 166 }; 167 168 /** 169 * struct sdw_dpn_prop - Data Port DPn properties 170 * @num: port number 171 * @max_word: Maximum number of bits in a Payload Channel Sample, 1 to 64 172 * (inclusive) 173 * @min_word: Minimum number of bits in a Payload Channel Sample, 1 to 64 174 * (inclusive) 175 * @num_words: Number of discrete supported wordlengths 176 * @words: Discrete supported wordlength 177 * @type: Data port type. Full, Simplified or Reduced 178 * @max_grouping: Maximum number of samples that can be grouped together for 179 * a full data port 180 * @simple_ch_prep_sm: If the port supports simplified channel prepare state 181 * machine 182 * @ch_prep_timeout: Port-specific timeout value, in milliseconds 183 * @device_interrupts: If set, each bit corresponds to support for 184 * implementation-defined interrupts 185 * @max_ch: Maximum channels supported 186 * @min_ch: Minimum channels supported 187 * @num_ch: Number of discrete channels supported 188 * @ch: Discrete channels supported 189 * @num_ch_combinations: Number of channel combinations supported 190 * @ch_combinations: Channel combinations supported 191 * @modes: SDW mode supported 192 * @max_async_buffer: Number of samples that this port can buffer in 193 * asynchronous modes 194 * @block_pack_mode: Type of block port mode supported 195 * @port_encoding: Payload Channel Sample encoding schemes supported 196 * @audio_modes: Audio modes supported 197 */ 198 struct sdw_dpn_prop { 199 u32 num; 200 u32 max_word; 201 u32 min_word; 202 u32 num_words; 203 u32 *words; 204 enum sdw_dpn_type type; 205 u32 max_grouping; 206 bool simple_ch_prep_sm; 207 u32 ch_prep_timeout; 208 u32 device_interrupts; 209 u32 max_ch; 210 u32 min_ch; 211 u32 num_ch; 212 u32 *ch; 213 u32 num_ch_combinations; 214 u32 *ch_combinations; 215 u32 modes; 216 u32 max_async_buffer; 217 bool block_pack_mode; 218 u32 port_encoding; 219 struct sdw_dpn_audio_mode *audio_modes; 220 }; 221 222 /** 223 * struct sdw_slave_prop - SoundWire Slave properties 224 * @mipi_revision: Spec version of the implementation 225 * @wake_capable: Wake-up events are supported 226 * @test_mode_capable: If test mode is supported 227 * @clk_stop_mode1: Clock-Stop Mode 1 is supported 228 * @simple_clk_stop_capable: Simple clock mode is supported 229 * @clk_stop_timeout: Worst-case latency of the Clock Stop Prepare State 230 * Machine transitions, in milliseconds 231 * @ch_prep_timeout: Worst-case latency of the Channel Prepare State Machine 232 * transitions, in milliseconds 233 * @reset_behave: Slave keeps the status of the SlaveStopClockPrepare 234 * state machine (P=1 SCSP_SM) after exit from clock-stop mode1 235 * @high_PHY_capable: Slave is HighPHY capable 236 * @paging_support: Slave implements paging registers SCP_AddrPage1 and 237 * SCP_AddrPage2 238 * @bank_delay_support: Slave implements bank delay/bridge support registers 239 * SCP_BankDelay and SCP_NextFrame 240 * @p15_behave: Slave behavior when the Master attempts a read to the Port15 241 * alias 242 * @lane_control_support: Slave supports lane control 243 * @master_count: Number of Masters present on this Slave 244 * @source_ports: Bitmap identifying source ports 245 * @sink_ports: Bitmap identifying sink ports 246 * @dp0_prop: Data Port 0 properties 247 * @src_dpn_prop: Source Data Port N properties 248 * @sink_dpn_prop: Sink Data Port N properties 249 */ 250 struct sdw_slave_prop { 251 u32 mipi_revision; 252 bool wake_capable; 253 bool test_mode_capable; 254 bool clk_stop_mode1; 255 bool simple_clk_stop_capable; 256 u32 clk_stop_timeout; 257 u32 ch_prep_timeout; 258 enum sdw_clk_stop_reset_behave reset_behave; 259 bool high_PHY_capable; 260 bool paging_support; 261 bool bank_delay_support; 262 enum sdw_p15_behave p15_behave; 263 bool lane_control_support; 264 u32 master_count; 265 u32 source_ports; 266 u32 sink_ports; 267 struct sdw_dp0_prop *dp0_prop; 268 struct sdw_dpn_prop *src_dpn_prop; 269 struct sdw_dpn_prop *sink_dpn_prop; 270 }; 271 272 /** 273 * struct sdw_master_prop - Master properties 274 * @revision: MIPI spec version of the implementation 275 * @master_count: Number of masters 276 * @clk_stop_mode: Bitmap for Clock Stop modes supported 277 * @max_freq: Maximum Bus clock frequency, in Hz 278 * @num_clk_gears: Number of clock gears supported 279 * @clk_gears: Clock gears supported 280 * @num_freq: Number of clock frequencies supported, in Hz 281 * @freq: Clock frequencies supported, in Hz 282 * @default_frame_rate: Controller default Frame rate, in Hz 283 * @default_row: Number of rows 284 * @default_col: Number of columns 285 * @dynamic_frame: Dynamic frame supported 286 * @err_threshold: Number of times that software may retry sending a single 287 * command 288 * @dpn_prop: Data Port N properties 289 */ 290 struct sdw_master_prop { 291 u32 revision; 292 u32 master_count; 293 enum sdw_clk_stop_mode clk_stop_mode; 294 u32 max_freq; 295 u32 num_clk_gears; 296 u32 *clk_gears; 297 u32 num_freq; 298 u32 *freq; 299 u32 default_frame_rate; 300 u32 default_row; 301 u32 default_col; 302 bool dynamic_frame; 303 u32 err_threshold; 304 struct sdw_dpn_prop *dpn_prop; 305 }; 306 307 int sdw_master_read_prop(struct sdw_bus *bus); 308 int sdw_slave_read_prop(struct sdw_slave *slave); 309 310 /* 311 * SDW Slave Structures and APIs 312 */ 313 314 /** 315 * struct sdw_slave_id - Slave ID 316 * @mfg_id: MIPI Manufacturer ID 317 * @part_id: Device Part ID 318 * @class_id: MIPI Class ID, unused now. 319 * Currently a placeholder in MIPI SoundWire Spec 320 * @unique_id: Device unique ID 321 * @sdw_version: SDW version implemented 322 * 323 * The order of the IDs here does not follow the DisCo spec definitions 324 */ 325 struct sdw_slave_id { 326 __u16 mfg_id; 327 __u16 part_id; 328 __u8 class_id; 329 __u8 unique_id:4; 330 __u8 sdw_version:4; 331 }; 332 333 /** 334 * struct sdw_slave_intr_status - Slave interrupt status 335 * @control_port: control port status 336 * @port: data port status 337 */ 338 struct sdw_slave_intr_status { 339 u8 control_port; 340 u8 port[15]; 341 }; 342 343 /** 344 * struct sdw_slave_ops - Slave driver callback ops 345 * @read_prop: Read Slave properties 346 * @interrupt_callback: Device interrupt notification (invoked in thread 347 * context) 348 * @update_status: Update Slave status 349 */ 350 struct sdw_slave_ops { 351 int (*read_prop)(struct sdw_slave *sdw); 352 int (*interrupt_callback)(struct sdw_slave *slave, 353 struct sdw_slave_intr_status *status); 354 int (*update_status)(struct sdw_slave *slave, 355 enum sdw_slave_status status); 356 }; 357 358 /** 359 * struct sdw_slave - SoundWire Slave 360 * @id: MIPI device ID 361 * @dev: Linux device 362 * @status: Status reported by the Slave 363 * @bus: Bus handle 364 * @ops: Slave callback ops 365 * @prop: Slave properties 366 * @node: node for bus list 367 * @port_ready: Port ready completion flag for each Slave port 368 * @dev_num: Device Number assigned by Bus 369 */ 370 struct sdw_slave { 371 struct sdw_slave_id id; 372 struct device dev; 373 enum sdw_slave_status status; 374 struct sdw_bus *bus; 375 const struct sdw_slave_ops *ops; 376 struct sdw_slave_prop prop; 377 struct list_head node; 378 struct completion *port_ready; 379 u16 dev_num; 380 }; 381 382 #define dev_to_sdw_dev(_dev) container_of(_dev, struct sdw_slave, dev) 383 384 struct sdw_driver { 385 const char *name; 386 387 int (*probe)(struct sdw_slave *sdw, 388 const struct sdw_device_id *id); 389 int (*remove)(struct sdw_slave *sdw); 390 void (*shutdown)(struct sdw_slave *sdw); 391 392 const struct sdw_device_id *id_table; 393 const struct sdw_slave_ops *ops; 394 395 struct device_driver driver; 396 }; 397 398 #define SDW_SLAVE_ENTRY(_mfg_id, _part_id, _drv_data) \ 399 { .mfg_id = (_mfg_id), .part_id = (_part_id), \ 400 .driver_data = (unsigned long)(_drv_data) } 401 402 int sdw_handle_slave_status(struct sdw_bus *bus, 403 enum sdw_slave_status status[]); 404 405 /* 406 * SDW master structures and APIs 407 */ 408 409 struct sdw_msg; 410 411 /** 412 * struct sdw_defer - SDW deffered message 413 * @length: message length 414 * @complete: message completion 415 * @msg: SDW message 416 */ 417 struct sdw_defer { 418 int length; 419 struct completion complete; 420 struct sdw_msg *msg; 421 }; 422 423 /** 424 * struct sdw_master_ops - Master driver ops 425 * @read_prop: Read Master properties 426 * @xfer_msg: Transfer message callback 427 * @xfer_msg_defer: Defer version of transfer message callback 428 * @reset_page_addr: Reset the SCP page address registers 429 */ 430 struct sdw_master_ops { 431 int (*read_prop)(struct sdw_bus *bus); 432 433 enum sdw_command_response (*xfer_msg) 434 (struct sdw_bus *bus, struct sdw_msg *msg); 435 enum sdw_command_response (*xfer_msg_defer) 436 (struct sdw_bus *bus, struct sdw_msg *msg, 437 struct sdw_defer *defer); 438 enum sdw_command_response (*reset_page_addr) 439 (struct sdw_bus *bus, unsigned int dev_num); 440 }; 441 442 /** 443 * struct sdw_bus - SoundWire bus 444 * @dev: Master linux device 445 * @link_id: Link id number, can be 0 to N, unique for each Master 446 * @slaves: list of Slaves on this bus 447 * @assigned: Bitmap for Slave device numbers. 448 * Bit set implies used number, bit clear implies unused number. 449 * @bus_lock: bus lock 450 * @msg_lock: message lock 451 * @ops: Master callback ops 452 * @prop: Master properties 453 * @defer_msg: Defer message 454 * @clk_stop_timeout: Clock stop timeout computed 455 */ 456 struct sdw_bus { 457 struct device *dev; 458 unsigned int link_id; 459 struct list_head slaves; 460 DECLARE_BITMAP(assigned, SDW_MAX_DEVICES); 461 struct mutex bus_lock; 462 struct mutex msg_lock; 463 const struct sdw_master_ops *ops; 464 struct sdw_master_prop prop; 465 struct sdw_defer defer_msg; 466 unsigned int clk_stop_timeout; 467 }; 468 469 int sdw_add_bus_master(struct sdw_bus *bus); 470 void sdw_delete_bus_master(struct sdw_bus *bus); 471 472 /* messaging and data APIs */ 473 474 int sdw_read(struct sdw_slave *slave, u32 addr); 475 int sdw_write(struct sdw_slave *slave, u32 addr, u8 value); 476 int sdw_nread(struct sdw_slave *slave, u32 addr, size_t count, u8 *val); 477 int sdw_nwrite(struct sdw_slave *slave, u32 addr, size_t count, u8 *val); 478 479 #endif /* __SOUNDWIRE_H */ 480