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