include/linux/soundwire/sdw.h

   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 */