drivers/slimbus/slimbus.h

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