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