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
  21 /*
  22  * SLIM Broadcast header format
  23  * BYTE 0: MT[7:5] RL[4:0]
  24  * BYTE 1: RSVD[7] MC[6:0]
  25  * BYTE 2: RSVD[7:6] DT[5:4] PI[3:0]
  26  */
  27 #define SLIM_MSG_MT_MASK        GENMASK(2, 0)
  28 #define SLIM_MSG_MT_SHIFT       5
  29 #define SLIM_MSG_RL_MASK        GENMASK(4, 0)
  30 #define SLIM_MSG_RL_SHIFT       0
  31 #define SLIM_MSG_MC_MASK        GENMASK(6, 0)
  32 #define SLIM_MSG_MC_SHIFT       0
  33 #define SLIM_MSG_DT_MASK        GENMASK(1, 0)
  34 #define SLIM_MSG_DT_SHIFT       4
  35
  36 #define SLIM_HEADER_GET_MT(b)   ((b >> SLIM_MSG_MT_SHIFT) & SLIM_MSG_MT_MASK)
  37 #define SLIM_HEADER_GET_RL(b)   ((b >> SLIM_MSG_RL_SHIFT) & SLIM_MSG_RL_MASK)
  38 #define SLIM_HEADER_GET_MC(b)   ((b >> SLIM_MSG_MC_SHIFT) & SLIM_MSG_MC_MASK)
  39 #define SLIM_HEADER_GET_DT(b)   ((b >> SLIM_MSG_DT_SHIFT) & SLIM_MSG_DT_MASK)
  40
  41 /* Device management messages used by this framework */
  42 #define SLIM_MSG_MC_REPORT_PRESENT               0x1
  43 #define SLIM_MSG_MC_ASSIGN_LOGICAL_ADDRESS       0x2
  44 #define SLIM_MSG_MC_REPORT_ABSENT                0xF
  45
  46 /* Clock pause Reconfiguration messages */
  47 #define SLIM_MSG_MC_BEGIN_RECONFIGURATION        0x40
  48 #define SLIM_MSG_MC_NEXT_PAUSE_CLOCK             0x4A
  49 #define SLIM_MSG_MC_RECONFIGURE_NOW              0x5F
  50
  51 /* Clock pause values per SLIMbus spec */
  52 #define SLIM_CLK_FAST                           0
  53 #define SLIM_CLK_CONST_PHASE                    1
  54 #define SLIM_CLK_UNSPECIFIED                    2
  55
  56 /* Destination type Values */
  57 #define SLIM_MSG_DEST_LOGICALADDR       0
  58 #define SLIM_MSG_DEST_ENUMADDR          1
  59 #define SLIM_MSG_DEST_BROADCAST         3
  60
  61 /* Standard values per SLIMbus spec needed by controllers and devices */
  62 #define SLIM_MAX_CLK_GEAR               10
  63 #define SLIM_MIN_CLK_GEAR               1
  64
  65 /* Manager's logical address is set to 0xFF per spec */
  66 #define SLIM_LA_MANAGER 0xFF
  67
  68 #define SLIM_MAX_TIDS                   256
  69 /**
  70  * struct slim_framer - Represents SLIMbus framer.
  71  * Every controller may have multiple framers. There is 1 active framer device
  72  * responsible for clocking the bus.
  73  * Manager is responsible for framer hand-over.
  74  * @dev: Driver model representation of the device.
  75  * @e_addr: Enumeration address of the framer.
  76  * @rootfreq: Root Frequency at which the framer can run. This is maximum
  77  *      frequency ('clock gear 10') at which the bus can operate.
  78  * @superfreq: Superframes per root frequency. Every frame is 6144 bits.
  79  */
  80 struct slim_framer {
  81         struct device           dev;
  82         struct slim_eaddr       e_addr;
  83         int                     rootfreq;
  84         int                     superfreq;
  85 };
  86
  87 #define to_slim_framer(d) container_of(d, struct slim_framer, dev)
  88
  89 /**
  90  * struct slim_msg_txn - Message to be sent by the controller.
  91  *                      This structure has packet header,
  92  *                      payload and buffer to be filled (if any)
  93  * @rl: Header field. remaining length.
  94  * @mt: Header field. Message type.
  95  * @mc: Header field. LSB is message code for type mt.
  96  * @dt: Header field. Destination type.
  97  * @ec: Element code. Used for elemental access APIs.
  98  * @tid: Transaction ID. Used for messages expecting response.
  99  *      (relevant for message-codes involving read operation)
 100  * @la: Logical address of the device this message is going to.
 101  *      (Not used when destination type is broadcast.)
 102  * @msg: Elemental access message to be read/written
 103  * @comp: completion if read/write is synchronous, used internally
 104  *      for tid based transactions.
 105  */
 106 struct slim_msg_txn {
 107         u8                      rl;
 108         u8                      mt;
 109         u8                      mc;
 110         u8                      dt;
 111         u16                     ec;
 112         u8                      tid;
 113         u8                      la;
 114         struct slim_val_inf     *msg;
 115         struct  completion      *comp;
 116 };
 117
 118 /* Frequently used message transaction structures */
 119 #define DEFINE_SLIM_LDEST_TXN(name, mc, rl, la, msg) \
 120         struct slim_msg_txn name = { rl, 0, mc, SLIM_MSG_DEST_LOGICALADDR, 0,\
 121                                         0, la, msg, }
 122
 123 #define DEFINE_SLIM_BCAST_TXN(name, mc, rl, la, msg) \
 124         struct slim_msg_txn name = { rl, 0, mc, SLIM_MSG_DEST_BROADCAST, 0,\
 125                                         0, la, msg, }
 126
 127 #define DEFINE_SLIM_EDEST_TXN(name, mc, rl, la, msg) \
 128         struct slim_msg_txn name = { rl, 0, mc, SLIM_MSG_DEST_ENUMADDR, 0,\
 129                                         0, la, msg, }
 130 /**
 131  * enum slim_clk_state: SLIMbus controller's clock state used internally for
 132  *      maintaining current clock state.
 133  * @SLIM_CLK_ACTIVE: SLIMbus clock is active
 134  * @SLIM_CLK_ENTERING_PAUSE: SLIMbus clock pause sequence is being sent on the
 135  *      bus. If this succeeds, state changes to SLIM_CLK_PAUSED. If the
 136  *      transition fails, state changes back to SLIM_CLK_ACTIVE
 137  * @SLIM_CLK_PAUSED: SLIMbus controller clock has paused.
 138  */
 139 enum slim_clk_state {
 140         SLIM_CLK_ACTIVE,
 141         SLIM_CLK_ENTERING_PAUSE,
 142         SLIM_CLK_PAUSED,
 143 };
 144
 145 /**
 146  * struct slim_sched: Framework uses this structure internally for scheduling.
 147  * @clk_state: Controller's clock state from enum slim_clk_state
 148  * @pause_comp: Signals completion of clock pause sequence. This is useful when
 149  *      client tries to call SLIMbus transaction when controller is entering
 150  *      clock pause.
 151  * @m_reconf: This mutex is held until current reconfiguration (data channel
 152  *      scheduling, message bandwidth reservation) is done. Message APIs can
 153  *      use the bus concurrently when this mutex is held since elemental access
 154  *      messages can be sent on the bus when reconfiguration is in progress.
 155  */
 156 struct slim_sched {
 157         enum slim_clk_state     clk_state;
 158         struct completion       pause_comp;
 159         struct mutex            m_reconf;
 160 };
 161
 162 /**
 163  * struct slim_controller  - Controls every instance of SLIMbus
 164  *                              (similar to 'master' on SPI)
 165  * @dev: Device interface to this driver
 166  * @id: Board-specific number identifier for this controller/bus
 167  * @name: Name for this controller
 168  * @min_cg: Minimum clock gear supported by this controller (default value: 1)
 169  * @max_cg: Maximum clock gear supported by this controller (default value: 10)
 170  * @clkgear: Current clock gear in which this bus is running
 171  * @laddr_ida: logical address id allocator
 172  * @a_framer: Active framer which is clocking the bus managed by this controller
 173  * @lock: Mutex protecting controller data structures
 174  * @devices: Slim device list
 175  * @tid_idr: tid id allocator
 176  * @txn_lock: Lock to protect table of transactions
 177  * @sched: scheduler structure used by the controller
 178  * @xfer_msg: Transfer a message on this controller (this can be a broadcast
 179  *      control/status message like data channel setup, or a unicast message
 180  *      like value element read/write.
 181  * @set_laddr: Setup logical address at laddr for the slave with elemental
 182  *      address e_addr. Drivers implementing controller will be expected to
 183  *      send unicast message to this device with its logical address.
 184  * @get_laddr: It is possible that controller needs to set fixed logical
 185  *      address table and get_laddr can be used in that case so that controller
 186  *      can do this assignment. Use case is when the master is on the remote
 187  *      processor side, who is resposible for allocating laddr.
 188  * @wakeup: This function pointer implements controller-specific procedure
 189  *      to wake it up from clock-pause. Framework will call this to bring
 190  *      the controller out of clock pause.
 191  *
 192  *      'Manager device' is responsible for  device management, bandwidth
 193  *      allocation, channel setup, and port associations per channel.
 194  *      Device management means Logical address assignment/removal based on
 195  *      enumeration (report-present, report-absent) of a device.
 196  *      Bandwidth allocation is done dynamically by the manager based on active
 197  *      channels on the bus, message-bandwidth requests made by SLIMbus devices.
 198  *      Based on current bandwidth usage, manager chooses a frequency to run
 199  *      the bus at (in steps of 'clock-gear', 1 through 10, each clock gear
 200  *      representing twice the frequency than the previous gear).
 201  *      Manager is also responsible for entering (and exiting) low-power-mode
 202  *      (known as 'clock pause').
 203  *      Manager can do handover of framer if there are multiple framers on the
 204  *      bus and a certain usecase warrants using certain framer to avoid keeping
 205  *      previous framer being powered-on.
 206  *
 207  *      Controller here performs duties of the manager device, and 'interface
 208  *      device'. Interface device is responsible for monitoring the bus and
 209  *      reporting information such as loss-of-synchronization, data
 210  *      slot-collision.
 211  */
 212 struct slim_controller {
 213         struct device           *dev;
 214         unsigned int            id;
 215         char                    name[SLIMBUS_NAME_SIZE];
 216         int                     min_cg;
 217         int                     max_cg;
 218         int                     clkgear;
 219         struct ida              laddr_ida;
 220         struct slim_framer      *a_framer;
 221         struct mutex            lock;
 222         struct list_head        devices;
 223         struct idr              tid_idr;
 224         spinlock_t              txn_lock;
 225         struct slim_sched       sched;
 226         int                     (*xfer_msg)(struct slim_controller *ctrl,
 227                                             struct slim_msg_txn *tx);
 228         int                     (*set_laddr)(struct slim_controller *ctrl,
 229                                              struct slim_eaddr *ea, u8 laddr);
 230         int                     (*get_laddr)(struct slim_controller *ctrl,
 231                                              struct slim_eaddr *ea, u8 *laddr);
 232         int                     (*wakeup)(struct slim_controller *ctrl);
 233 };
 234
 235 int slim_device_report_present(struct slim_controller *ctrl,
 236                                struct slim_eaddr *e_addr, u8 *laddr);
 237 void slim_report_absent(struct slim_device *sbdev);
 238 int slim_register_controller(struct slim_controller *ctrl);
 239 int slim_unregister_controller(struct slim_controller *ctrl);
 240 void slim_msg_response(struct slim_controller *ctrl, u8 *reply, u8 tid, u8 l);
 241 int slim_do_transfer(struct slim_controller *ctrl, struct slim_msg_txn *txn);
 242 int slim_ctrl_clk_pause(struct slim_controller *ctrl, bool wakeup, u8 restart);
 243
 244 static inline bool slim_tid_txn(u8 mt, u8 mc)
 245 {
 246         return (mt == SLIM_MSG_MT_CORE &&
 247                 (mc == SLIM_MSG_MC_REQUEST_INFORMATION ||
 248                  mc == SLIM_MSG_MC_REQUEST_CLEAR_INFORMATION ||
 249                  mc == SLIM_MSG_MC_REQUEST_VALUE ||
 250                  mc == SLIM_MSG_MC_REQUEST_CLEAR_INFORMATION));
 251 }
 252
 253 static inline bool slim_ec_txn(u8 mt, u8 mc)
 254 {
 255         return (mt == SLIM_MSG_MT_CORE &&
 256                 ((mc >= SLIM_MSG_MC_REQUEST_INFORMATION &&
 257                   mc <= SLIM_MSG_MC_REPORT_INFORMATION) ||
 258                  (mc >= SLIM_MSG_MC_REQUEST_VALUE &&
 259                   mc <= SLIM_MSG_MC_CHANGE_VALUE)));
 260 }
 261 #endif /* _LINUX_SLIMBUS_H */