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