1 // SPDX-License-Identifier: GPL-2.0 2 /* 3 * Copyright (c) 2011-2017, The Linux Foundation 4 */ 5 6 #ifndef _DRIVERS_SLIMBUS_H 7 #define _DRIVERS_SLIMBUS_H 8 #include <linux/module.h> 9 #include <linux/device.h> 10 #include <linux/mutex.h> 11 #include <linux/completion.h> 12 #include <linux/slimbus.h> 13 14 /* Standard values per SLIMbus spec needed by controllers and devices */ 15 #define SLIM_CL_PER_SUPERFRAME 6144 16 #define SLIM_CL_PER_SUPERFRAME_DIV8 (SLIM_CL_PER_SUPERFRAME >> 3) 17 18 /* SLIMbus message types. Related to interpretation of message code. */ 19 #define SLIM_MSG_MT_CORE 0x0 20 #define SLIM_MSG_MT_DEST_REFERRED_USER 0x2 21 #define SLIM_MSG_MT_SRC_REFERRED_USER 0x6 22 23 /* 24 * SLIM Broadcast header format 25 * BYTE 0: MT[7:5] RL[4:0] 26 * BYTE 1: RSVD[7] MC[6:0] 27 * BYTE 2: RSVD[7:6] DT[5:4] PI[3:0] 28 */ 29 #define SLIM_MSG_MT_MASK GENMASK(2, 0) 30 #define SLIM_MSG_MT_SHIFT 5 31 #define SLIM_MSG_RL_MASK GENMASK(4, 0) 32 #define SLIM_MSG_RL_SHIFT 0 33 #define SLIM_MSG_MC_MASK GENMASK(6, 0) 34 #define SLIM_MSG_MC_SHIFT 0 35 #define SLIM_MSG_DT_MASK GENMASK(1, 0) 36 #define SLIM_MSG_DT_SHIFT 4 37 38 #define SLIM_HEADER_GET_MT(b) ((b >> SLIM_MSG_MT_SHIFT) & SLIM_MSG_MT_MASK) 39 #define SLIM_HEADER_GET_RL(b) ((b >> SLIM_MSG_RL_SHIFT) & SLIM_MSG_RL_MASK) 40 #define SLIM_HEADER_GET_MC(b) ((b >> SLIM_MSG_MC_SHIFT) & SLIM_MSG_MC_MASK) 41 #define SLIM_HEADER_GET_DT(b) ((b >> SLIM_MSG_DT_SHIFT) & SLIM_MSG_DT_MASK) 42 43 /* Device management messages used by this framework */ 44 #define SLIM_MSG_MC_REPORT_PRESENT 0x1 45 #define SLIM_MSG_MC_ASSIGN_LOGICAL_ADDRESS 0x2 46 #define SLIM_MSG_MC_REPORT_ABSENT 0xF 47 48 /* Data channel management messages */ 49 #define SLIM_MSG_MC_CONNECT_SOURCE 0x10 50 #define SLIM_MSG_MC_CONNECT_SINK 0x11 51 #define SLIM_MSG_MC_DISCONNECT_PORT 0x14 52 #define SLIM_MSG_MC_CHANGE_CONTENT 0x18 53 54 /* Clock pause Reconfiguration messages */ 55 #define SLIM_MSG_MC_BEGIN_RECONFIGURATION 0x40 56 #define SLIM_MSG_MC_NEXT_PAUSE_CLOCK 0x4A 57 #define SLIM_MSG_MC_NEXT_DEFINE_CHANNEL 0x50 58 #define SLIM_MSG_MC_NEXT_DEFINE_CONTENT 0x51 59 #define SLIM_MSG_MC_NEXT_ACTIVATE_CHANNEL 0x54 60 #define SLIM_MSG_MC_NEXT_DEACTIVATE_CHANNEL 0x55 61 #define SLIM_MSG_MC_NEXT_REMOVE_CHANNEL 0x58 62 #define SLIM_MSG_MC_RECONFIGURE_NOW 0x5F 63 64 /* 65 * Clock pause flag to indicate that the reconfig message 66 * corresponds to clock pause sequence 67 */ 68 #define SLIM_MSG_CLK_PAUSE_SEQ_FLG (1U << 8) 69 70 /* Clock pause values per SLIMbus spec */ 71 #define SLIM_CLK_FAST 0 72 #define SLIM_CLK_CONST_PHASE 1 73 #define SLIM_CLK_UNSPECIFIED 2 74 75 /* Destination type Values */ 76 #define SLIM_MSG_DEST_LOGICALADDR 0 77 #define SLIM_MSG_DEST_ENUMADDR 1 78 #define SLIM_MSG_DEST_BROADCAST 3 79 80 /* Standard values per SLIMbus spec needed by controllers and devices */ 81 #define SLIM_MAX_CLK_GEAR 10 82 #define SLIM_MIN_CLK_GEAR 1 83 #define SLIM_SLOT_LEN_BITS 4 84 85 /* Indicate that the frequency of the flow and the bus frequency are locked */ 86 #define SLIM_CHANNEL_CONTENT_FL BIT(7) 87 88 /* Standard values per SLIMbus spec needed by controllers and devices */ 89 #define SLIM_CL_PER_SUPERFRAME 6144 90 #define SLIM_SLOTS_PER_SUPERFRAME (SLIM_CL_PER_SUPERFRAME >> 2) 91 #define SLIM_SL_PER_SUPERFRAME (SLIM_CL_PER_SUPERFRAME >> 2) 92 /* Manager's logical address is set to 0xFF per spec */ 93 #define SLIM_LA_MANAGER 0xFF 94 95 #define SLIM_MAX_TIDS 256 96 /** 97 * struct slim_framer - Represents SLIMbus framer. 98 * Every controller may have multiple framers. There is 1 active framer device 99 * responsible for clocking the bus. 100 * Manager is responsible for framer hand-over. 101 * @dev: Driver model representation of the device. 102 * @e_addr: Enumeration address of the framer. 103 * @rootfreq: Root Frequency at which the framer can run. This is maximum 104 * frequency ('clock gear 10') at which the bus can operate. 105 * @superfreq: Superframes per root frequency. Every frame is 6144 bits. 106 */ 107 struct slim_framer { 108 struct device dev; 109 struct slim_eaddr e_addr; 110 int rootfreq; 111 int superfreq; 112 }; 113 114 #define to_slim_framer(d) container_of(d, struct slim_framer, dev) 115 116 /** 117 * struct slim_msg_txn - Message to be sent by the controller. 118 * This structure has packet header, 119 * payload and buffer to be filled (if any) 120 * @rl: Header field. remaining length. 121 * @mt: Header field. Message type. 122 * @mc: Header field. LSB is message code for type mt. 123 * @dt: Header field. Destination type. 124 * @ec: Element code. Used for elemental access APIs. 125 * @tid: Transaction ID. Used for messages expecting response. 126 * (relevant for message-codes involving read operation) 127 * @la: Logical address of the device this message is going to. 128 * (Not used when destination type is broadcast.) 129 * @msg: Elemental access message to be read/written 130 * @comp: completion if read/write is synchronous, used internally 131 * for tid based transactions. 132 */ 133 struct slim_msg_txn { 134 u8 rl; 135 u8 mt; 136 u8 mc; 137 u8 dt; 138 u16 ec; 139 u8 tid; 140 u8 la; 141 struct slim_val_inf *msg; 142 struct completion *comp; 143 }; 144 145 /* Frequently used message transaction structures */ 146 #define DEFINE_SLIM_LDEST_TXN(name, mc, rl, la, msg) \ 147 struct slim_msg_txn name = { rl, 0, mc, SLIM_MSG_DEST_LOGICALADDR, 0,\ 148 0, la, msg, } 149 150 #define DEFINE_SLIM_BCAST_TXN(name, mc, rl, la, msg) \ 151 struct slim_msg_txn name = { rl, 0, mc, SLIM_MSG_DEST_BROADCAST, 0,\ 152 0, la, msg, } 153 154 #define DEFINE_SLIM_EDEST_TXN(name, mc, rl, la, msg) \ 155 struct slim_msg_txn name = { rl, 0, mc, SLIM_MSG_DEST_ENUMADDR, 0,\ 156 0, la, msg, } 157 /** 158 * enum slim_clk_state: SLIMbus controller's clock state used internally for 159 * maintaining current clock state. 160 * @SLIM_CLK_ACTIVE: SLIMbus clock is active 161 * @SLIM_CLK_ENTERING_PAUSE: SLIMbus clock pause sequence is being sent on the 162 * bus. If this succeeds, state changes to SLIM_CLK_PAUSED. If the 163 * transition fails, state changes back to SLIM_CLK_ACTIVE 164 * @SLIM_CLK_PAUSED: SLIMbus controller clock has paused. 165 */ 166 enum slim_clk_state { 167 SLIM_CLK_ACTIVE, 168 SLIM_CLK_ENTERING_PAUSE, 169 SLIM_CLK_PAUSED, 170 }; 171 172 /** 173 * struct slim_sched: Framework uses this structure internally for scheduling. 174 * @clk_state: Controller's clock state from enum slim_clk_state 175 * @pause_comp: Signals completion of clock pause sequence. This is useful when 176 * client tries to call SLIMbus transaction when controller is entering 177 * clock pause. 178 * @m_reconf: This mutex is held until current reconfiguration (data channel 179 * scheduling, message bandwidth reservation) is done. Message APIs can 180 * use the bus concurrently when this mutex is held since elemental access 181 * messages can be sent on the bus when reconfiguration is in progress. 182 */ 183 struct slim_sched { 184 enum slim_clk_state clk_state; 185 struct completion pause_comp; 186 struct mutex m_reconf; 187 }; 188 189 /** 190 * enum slim_port_direction: SLIMbus port direction 191 * 192 * @SLIM_PORT_SINK: SLIMbus port is a sink 193 * @SLIM_PORT_SOURCE: SLIMbus port is a source 194 */ 195 enum slim_port_direction { 196 SLIM_PORT_SINK = 0, 197 SLIM_PORT_SOURCE, 198 }; 199 /** 200 * enum slim_port_state: SLIMbus Port/Endpoint state machine 201 * according to SLIMbus Spec 2.0 202 * @SLIM_PORT_DISCONNECTED: SLIMbus port is disconnected 203 * entered from Unconfigure/configured state after 204 * DISCONNECT_PORT or REMOVE_CHANNEL core command 205 * @SLIM_PORT_UNCONFIGURED: SLIMbus port is in unconfigured state. 206 * entered from disconnect state after CONNECT_SOURCE/SINK core command 207 * @SLIM_PORT_CONFIGURED: SLIMbus port is in configured state. 208 * entered from unconfigured state after DEFINE_CHANNEL, DEFINE_CONTENT 209 * and ACTIVATE_CHANNEL core commands. Ready for data transmission. 210 */ 211 enum slim_port_state { 212 SLIM_PORT_DISCONNECTED = 0, 213 SLIM_PORT_UNCONFIGURED, 214 SLIM_PORT_CONFIGURED, 215 }; 216 217 /** 218 * enum slim_channel_state: SLIMbus channel state machine used by core. 219 * @SLIM_CH_STATE_DISCONNECTED: SLIMbus channel is disconnected 220 * @SLIM_CH_STATE_ALLOCATED: SLIMbus channel is allocated 221 * @SLIM_CH_STATE_ASSOCIATED: SLIMbus channel is associated with port 222 * @SLIM_CH_STATE_DEFINED: SLIMbus channel parameters are defined 223 * @SLIM_CH_STATE_CONTENT_DEFINED: SLIMbus channel content is defined 224 * @SLIM_CH_STATE_ACTIVE: SLIMbus channel is active and ready for data 225 * @SLIM_CH_STATE_REMOVED: SLIMbus channel is inactive and removed 226 */ 227 enum slim_channel_state { 228 SLIM_CH_STATE_DISCONNECTED = 0, 229 SLIM_CH_STATE_ALLOCATED, 230 SLIM_CH_STATE_ASSOCIATED, 231 SLIM_CH_STATE_DEFINED, 232 SLIM_CH_STATE_CONTENT_DEFINED, 233 SLIM_CH_STATE_ACTIVE, 234 SLIM_CH_STATE_REMOVED, 235 }; 236 237 /** 238 * enum slim_ch_data_fmt: SLIMbus channel data Type identifiers according to 239 * Table 60 of SLIMbus Spec 1.01.01 240 * @SLIM_CH_DATA_FMT_NOT_DEFINED: Undefined 241 * @SLIM_CH_DATA_FMT_LPCM_AUDIO: LPCM audio 242 * @SLIM_CH_DATA_FMT_IEC61937_COMP_AUDIO: IEC61937 Compressed audio 243 * @SLIM_CH_DATA_FMT_PACKED_PDM_AUDIO: Packed PDM audio 244 */ 245 enum slim_ch_data_fmt { 246 SLIM_CH_DATA_FMT_NOT_DEFINED = 0, 247 SLIM_CH_DATA_FMT_LPCM_AUDIO = 1, 248 SLIM_CH_DATA_FMT_IEC61937_COMP_AUDIO = 2, 249 SLIM_CH_DATA_FMT_PACKED_PDM_AUDIO = 3, 250 }; 251 252 /** 253 * enum slim_ch_aux_fmt: SLIMbus channel Aux Field format IDs according to 254 * Table 63 of SLIMbus Spec 2.0 255 * @SLIM_CH_AUX_FMT_NOT_APPLICABLE: Undefined 256 * @SLIM_CH_AUX_FMT_ZCUV_TUNNEL_IEC60958: ZCUV for tunneling IEC60958 257 * @SLIM_CH_AUX_FMT_USER_DEFINED: User defined 258 */ 259 enum slim_ch_aux_bit_fmt { 260 SLIM_CH_AUX_FMT_NOT_APPLICABLE = 0, 261 SLIM_CH_AUX_FMT_ZCUV_TUNNEL_IEC60958 = 1, 262 SLIM_CH_AUX_FMT_USER_DEFINED = 0xF, 263 }; 264 265 /** 266 * struct slim_channel - SLIMbus channel, used for state machine 267 * 268 * @id: ID of channel 269 * @prrate: Presense rate of channel from Table 66 of SLIMbus 2.0 Specs 270 * @seg_dist: segment distribution code from Table 20 of SLIMbus 2.0 Specs 271 * @data_fmt: Data format of channel. 272 * @aux_fmt: Aux format for this channel. 273 * @state: channel state machine 274 */ 275 struct slim_channel { 276 int id; 277 int prrate; 278 int seg_dist; 279 enum slim_ch_data_fmt data_fmt; 280 enum slim_ch_aux_bit_fmt aux_fmt; 281 enum slim_channel_state state; 282 }; 283 284 /** 285 * struct slim_port - SLIMbus port 286 * 287 * @id: Port id 288 * @direction: Port direction, Source or Sink. 289 * @state: state machine of port. 290 * @ch: channel associated with this port. 291 */ 292 struct slim_port { 293 int id; 294 enum slim_port_direction direction; 295 enum slim_port_state state; 296 struct slim_channel ch; 297 }; 298 299 /** 300 * enum slim_transport_protocol: SLIMbus Transport protocol list from 301 * Table 47 of SLIMbus 2.0 specs. 302 * @SLIM_PROTO_ISO: Isochronous Protocol, no flow control as data rate match 303 * channel rate flow control embedded in the data. 304 * @SLIM_PROTO_PUSH: Pushed Protocol, includes flow control, Used to carry 305 * data whose rate is equal to, or lower than the channel rate. 306 * @SLIM_PROTO_PULL: Pulled Protocol, similar usage as pushed protocol 307 * but pull is a unicast. 308 * @SLIM_PROTO_LOCKED: Locked Protocol 309 * @SLIM_PROTO_ASYNC_SMPLX: Asynchronous Protocol-Simplex 310 * @SLIM_PROTO_ASYNC_HALF_DUP: Asynchronous Protocol-Half-duplex 311 * @SLIM_PROTO_EXT_SMPLX: Extended Asynchronous Protocol-Simplex 312 * @SLIM_PROTO_EXT_HALF_DUP: Extended Asynchronous Protocol-Half-duplex 313 */ 314 enum slim_transport_protocol { 315 SLIM_PROTO_ISO = 0, 316 SLIM_PROTO_PUSH, 317 SLIM_PROTO_PULL, 318 SLIM_PROTO_LOCKED, 319 SLIM_PROTO_ASYNC_SMPLX, 320 SLIM_PROTO_ASYNC_HALF_DUP, 321 SLIM_PROTO_EXT_SMPLX, 322 SLIM_PROTO_EXT_HALF_DUP, 323 }; 324 325 /** 326 * struct slim_stream_runtime - SLIMbus stream runtime instance 327 * 328 * @name: Name of the stream 329 * @dev: SLIM Device instance associated with this stream 330 * @direction: direction of stream 331 * @prot: Transport protocol used in this stream 332 * @rate: Data rate of samples * 333 * @bps: bits per sample 334 * @ratem: rate multipler which is super frame rate/data rate 335 * @num_ports: number of ports 336 * @ports: pointer to instance of ports 337 * @node: list head for stream associated with slim device. 338 */ 339 struct slim_stream_runtime { 340 const char *name; 341 struct slim_device *dev; 342 int direction; 343 enum slim_transport_protocol prot; 344 unsigned int rate; 345 unsigned int bps; 346 unsigned int ratem; 347 int num_ports; 348 struct slim_port *ports; 349 struct list_head node; 350 }; 351 352 /** 353 * struct slim_controller - Controls every instance of SLIMbus 354 * (similar to 'master' on SPI) 355 * @dev: Device interface to this driver 356 * @id: Board-specific number identifier for this controller/bus 357 * @name: Name for this controller 358 * @min_cg: Minimum clock gear supported by this controller (default value: 1) 359 * @max_cg: Maximum clock gear supported by this controller (default value: 10) 360 * @clkgear: Current clock gear in which this bus is running 361 * @laddr_ida: logical address id allocator 362 * @a_framer: Active framer which is clocking the bus managed by this controller 363 * @lock: Mutex protecting controller data structures 364 * @devices: Slim device list 365 * @tid_idr: tid id allocator 366 * @txn_lock: Lock to protect table of transactions 367 * @sched: scheduler structure used by the controller 368 * @xfer_msg: Transfer a message on this controller (this can be a broadcast 369 * control/status message like data channel setup, or a unicast message 370 * like value element read/write. 371 * @set_laddr: Setup logical address at laddr for the slave with elemental 372 * address e_addr. Drivers implementing controller will be expected to 373 * send unicast message to this device with its logical address. 374 * @get_laddr: It is possible that controller needs to set fixed logical 375 * address table and get_laddr can be used in that case so that controller 376 * can do this assignment. Use case is when the master is on the remote 377 * processor side, who is resposible for allocating laddr. 378 * @wakeup: This function pointer implements controller-specific procedure 379 * to wake it up from clock-pause. Framework will call this to bring 380 * the controller out of clock pause. 381 * @enable_stream: This function pointer implements controller-specific procedure 382 * to enable a stream. 383 * @disable_stream: This function pointer implements controller-specific procedure 384 * to disable stream. 385 * 386 * 'Manager device' is responsible for device management, bandwidth 387 * allocation, channel setup, and port associations per channel. 388 * Device management means Logical address assignment/removal based on 389 * enumeration (report-present, report-absent) of a device. 390 * Bandwidth allocation is done dynamically by the manager based on active 391 * channels on the bus, message-bandwidth requests made by SLIMbus devices. 392 * Based on current bandwidth usage, manager chooses a frequency to run 393 * the bus at (in steps of 'clock-gear', 1 through 10, each clock gear 394 * representing twice the frequency than the previous gear). 395 * Manager is also responsible for entering (and exiting) low-power-mode 396 * (known as 'clock pause'). 397 * Manager can do handover of framer if there are multiple framers on the 398 * bus and a certain usecase warrants using certain framer to avoid keeping 399 * previous framer being powered-on. 400 * 401 * Controller here performs duties of the manager device, and 'interface 402 * device'. Interface device is responsible for monitoring the bus and 403 * reporting information such as loss-of-synchronization, data 404 * slot-collision. 405 */ 406 struct slim_controller { 407 struct device *dev; 408 unsigned int id; 409 char name[SLIMBUS_NAME_SIZE]; 410 int min_cg; 411 int max_cg; 412 int clkgear; 413 struct ida laddr_ida; 414 struct slim_framer *a_framer; 415 struct mutex lock; 416 struct list_head devices; 417 struct idr tid_idr; 418 spinlock_t txn_lock; 419 struct slim_sched sched; 420 int (*xfer_msg)(struct slim_controller *ctrl, 421 struct slim_msg_txn *tx); 422 int (*set_laddr)(struct slim_controller *ctrl, 423 struct slim_eaddr *ea, u8 laddr); 424 int (*get_laddr)(struct slim_controller *ctrl, 425 struct slim_eaddr *ea, u8 *laddr); 426 int (*enable_stream)(struct slim_stream_runtime *rt); 427 int (*disable_stream)(struct slim_stream_runtime *rt); 428 int (*wakeup)(struct slim_controller *ctrl); 429 }; 430 431 int slim_device_report_present(struct slim_controller *ctrl, 432 struct slim_eaddr *e_addr, u8 *laddr); 433 void slim_report_absent(struct slim_device *sbdev); 434 int slim_register_controller(struct slim_controller *ctrl); 435 int slim_unregister_controller(struct slim_controller *ctrl); 436 void slim_msg_response(struct slim_controller *ctrl, u8 *reply, u8 tid, u8 l); 437 int slim_do_transfer(struct slim_controller *ctrl, struct slim_msg_txn *txn); 438 int slim_ctrl_clk_pause(struct slim_controller *ctrl, bool wakeup, u8 restart); 439 int slim_alloc_txn_tid(struct slim_controller *ctrl, struct slim_msg_txn *txn); 440 void slim_free_txn_tid(struct slim_controller *ctrl, struct slim_msg_txn *txn); 441 442 static inline bool slim_tid_txn(u8 mt, u8 mc) 443 { 444 return (mt == SLIM_MSG_MT_CORE && 445 (mc == SLIM_MSG_MC_REQUEST_INFORMATION || 446 mc == SLIM_MSG_MC_REQUEST_CLEAR_INFORMATION || 447 mc == SLIM_MSG_MC_REQUEST_VALUE || 448 mc == SLIM_MSG_MC_REQUEST_CLEAR_INFORMATION)); 449 } 450 451 static inline bool slim_ec_txn(u8 mt, u8 mc) 452 { 453 return (mt == SLIM_MSG_MT_CORE && 454 ((mc >= SLIM_MSG_MC_REQUEST_INFORMATION && 455 mc <= SLIM_MSG_MC_REPORT_INFORMATION) || 456 (mc >= SLIM_MSG_MC_REQUEST_VALUE && 457 mc <= SLIM_MSG_MC_CHANGE_VALUE))); 458 } 459 #endif /* _LINUX_SLIMBUS_H */ 460