mhi.h 23 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740
  1. /* SPDX-License-Identifier: GPL-2.0 */
  2. /*
  3. * Copyright (c) 2018-2020, The Linux Foundation. All rights reserved.
  4. *
  5. */
  6. #ifndef _MHI_H_
  7. #define _MHI_H_
  8. #include <linux/device.h>
  9. #include <linux/dma-direction.h>
  10. #include <linux/mutex.h>
  11. #include <linux/skbuff.h>
  12. #include <linux/slab.h>
  13. #include <linux/spinlock.h>
  14. #include <linux/wait.h>
  15. #include <linux/workqueue.h>
  16. #define MHI_MAX_OEM_PK_HASH_SEGMENTS 16
  17. struct mhi_chan;
  18. struct mhi_event;
  19. struct mhi_ctxt;
  20. struct mhi_cmd;
  21. struct mhi_buf_info;
  22. /**
  23. * enum mhi_callback - MHI callback
  24. * @MHI_CB_IDLE: MHI entered idle state
  25. * @MHI_CB_PENDING_DATA: New data available for client to process
  26. * @MHI_CB_LPM_ENTER: MHI host entered low power mode
  27. * @MHI_CB_LPM_EXIT: MHI host about to exit low power mode
  28. * @MHI_CB_EE_RDDM: MHI device entered RDDM exec env
  29. * @MHI_CB_EE_MISSION_MODE: MHI device entered Mission Mode exec env
  30. * @MHI_CB_SYS_ERROR: MHI device entered error state (may recover)
  31. * @MHI_CB_FATAL_ERROR: MHI device entered fatal error state
  32. * @MHI_CB_BW_REQ: Received a bandwidth switch request from device
  33. */
  34. enum mhi_callback {
  35. MHI_CB_IDLE,
  36. MHI_CB_PENDING_DATA,
  37. MHI_CB_LPM_ENTER,
  38. MHI_CB_LPM_EXIT,
  39. MHI_CB_EE_RDDM,
  40. MHI_CB_EE_MISSION_MODE,
  41. MHI_CB_SYS_ERROR,
  42. MHI_CB_FATAL_ERROR,
  43. MHI_CB_BW_REQ,
  44. };
  45. /**
  46. * enum mhi_flags - Transfer flags
  47. * @MHI_EOB: End of buffer for bulk transfer
  48. * @MHI_EOT: End of transfer
  49. * @MHI_CHAIN: Linked transfer
  50. */
  51. enum mhi_flags {
  52. MHI_EOB = BIT(0),
  53. MHI_EOT = BIT(1),
  54. MHI_CHAIN = BIT(2),
  55. };
  56. /**
  57. * enum mhi_device_type - Device types
  58. * @MHI_DEVICE_XFER: Handles data transfer
  59. * @MHI_DEVICE_CONTROLLER: Control device
  60. */
  61. enum mhi_device_type {
  62. MHI_DEVICE_XFER,
  63. MHI_DEVICE_CONTROLLER,
  64. };
  65. /**
  66. * enum mhi_ch_type - Channel types
  67. * @MHI_CH_TYPE_INVALID: Invalid channel type
  68. * @MHI_CH_TYPE_OUTBOUND: Outbound channel to the device
  69. * @MHI_CH_TYPE_INBOUND: Inbound channel from the device
  70. * @MHI_CH_TYPE_INBOUND_COALESCED: Coalesced channel for the device to combine
  71. * multiple packets and send them as a single
  72. * large packet to reduce CPU consumption
  73. */
  74. enum mhi_ch_type {
  75. MHI_CH_TYPE_INVALID = 0,
  76. MHI_CH_TYPE_OUTBOUND = DMA_TO_DEVICE,
  77. MHI_CH_TYPE_INBOUND = DMA_FROM_DEVICE,
  78. MHI_CH_TYPE_INBOUND_COALESCED = 3,
  79. };
  80. /**
  81. * struct image_info - Firmware and RDDM table
  82. * @mhi_buf: Buffer for firmware and RDDM table
  83. * @entries: # of entries in table
  84. */
  85. struct image_info {
  86. struct mhi_buf *mhi_buf;
  87. /* private: from internal.h */
  88. struct bhi_vec_entry *bhi_vec;
  89. /* public: */
  90. u32 entries;
  91. };
  92. /**
  93. * struct mhi_link_info - BW requirement
  94. * target_link_speed - Link speed as defined by TLS bits in LinkControl reg
  95. * target_link_width - Link width as defined by NLW bits in LinkStatus reg
  96. */
  97. struct mhi_link_info {
  98. unsigned int target_link_speed;
  99. unsigned int target_link_width;
  100. };
  101. /**
  102. * enum mhi_ee_type - Execution environment types
  103. * @MHI_EE_PBL: Primary Bootloader
  104. * @MHI_EE_SBL: Secondary Bootloader
  105. * @MHI_EE_AMSS: Modem, aka the primary runtime EE
  106. * @MHI_EE_RDDM: Ram dump download mode
  107. * @MHI_EE_WFW: WLAN firmware mode
  108. * @MHI_EE_PTHRU: Passthrough
  109. * @MHI_EE_EDL: Embedded downloader
  110. */
  111. enum mhi_ee_type {
  112. MHI_EE_PBL,
  113. MHI_EE_SBL,
  114. MHI_EE_AMSS,
  115. MHI_EE_RDDM,
  116. MHI_EE_WFW,
  117. MHI_EE_PTHRU,
  118. MHI_EE_EDL,
  119. MHI_EE_MAX_SUPPORTED = MHI_EE_EDL,
  120. MHI_EE_DISABLE_TRANSITION, /* local EE, not related to mhi spec */
  121. MHI_EE_NOT_SUPPORTED,
  122. MHI_EE_MAX,
  123. };
  124. /**
  125. * enum mhi_state - MHI states
  126. * @MHI_STATE_RESET: Reset state
  127. * @MHI_STATE_READY: Ready state
  128. * @MHI_STATE_M0: M0 state
  129. * @MHI_STATE_M1: M1 state
  130. * @MHI_STATE_M2: M2 state
  131. * @MHI_STATE_M3: M3 state
  132. * @MHI_STATE_M3_FAST: M3 Fast state
  133. * @MHI_STATE_BHI: BHI state
  134. * @MHI_STATE_SYS_ERR: System Error state
  135. */
  136. enum mhi_state {
  137. MHI_STATE_RESET = 0x0,
  138. MHI_STATE_READY = 0x1,
  139. MHI_STATE_M0 = 0x2,
  140. MHI_STATE_M1 = 0x3,
  141. MHI_STATE_M2 = 0x4,
  142. MHI_STATE_M3 = 0x5,
  143. MHI_STATE_M3_FAST = 0x6,
  144. MHI_STATE_BHI = 0x7,
  145. MHI_STATE_SYS_ERR = 0xFF,
  146. MHI_STATE_MAX,
  147. };
  148. /**
  149. * enum mhi_ch_ee_mask - Execution environment mask for channel
  150. * @MHI_CH_EE_PBL: Allow channel to be used in PBL EE
  151. * @MHI_CH_EE_SBL: Allow channel to be used in SBL EE
  152. * @MHI_CH_EE_AMSS: Allow channel to be used in AMSS EE
  153. * @MHI_CH_EE_RDDM: Allow channel to be used in RDDM EE
  154. * @MHI_CH_EE_PTHRU: Allow channel to be used in PTHRU EE
  155. * @MHI_CH_EE_WFW: Allow channel to be used in WFW EE
  156. * @MHI_CH_EE_EDL: Allow channel to be used in EDL EE
  157. */
  158. enum mhi_ch_ee_mask {
  159. MHI_CH_EE_PBL = BIT(MHI_EE_PBL),
  160. MHI_CH_EE_SBL = BIT(MHI_EE_SBL),
  161. MHI_CH_EE_AMSS = BIT(MHI_EE_AMSS),
  162. MHI_CH_EE_RDDM = BIT(MHI_EE_RDDM),
  163. MHI_CH_EE_PTHRU = BIT(MHI_EE_PTHRU),
  164. MHI_CH_EE_WFW = BIT(MHI_EE_WFW),
  165. MHI_CH_EE_EDL = BIT(MHI_EE_EDL),
  166. };
  167. /**
  168. * enum mhi_er_data_type - Event ring data types
  169. * @MHI_ER_DATA: Only client data over this ring
  170. * @MHI_ER_CTRL: MHI control data and client data
  171. */
  172. enum mhi_er_data_type {
  173. MHI_ER_DATA,
  174. MHI_ER_CTRL,
  175. };
  176. /**
  177. * enum mhi_db_brst_mode - Doorbell mode
  178. * @MHI_DB_BRST_DISABLE: Burst mode disable
  179. * @MHI_DB_BRST_ENABLE: Burst mode enable
  180. */
  181. enum mhi_db_brst_mode {
  182. MHI_DB_BRST_DISABLE = 0x2,
  183. MHI_DB_BRST_ENABLE = 0x3,
  184. };
  185. /**
  186. * struct mhi_channel_config - Channel configuration structure for controller
  187. * @name: The name of this channel
  188. * @num: The number assigned to this channel
  189. * @num_elements: The number of elements that can be queued to this channel
  190. * @local_elements: The local ring length of the channel
  191. * @event_ring: The event rung index that services this channel
  192. * @dir: Direction that data may flow on this channel
  193. * @type: Channel type
  194. * @ee_mask: Execution Environment mask for this channel
  195. * @pollcfg: Polling configuration for burst mode. 0 is default. milliseconds
  196. for UL channels, multiple of 8 ring elements for DL channels
  197. * @doorbell: Doorbell mode
  198. * @lpm_notify: The channel master requires low power mode notifications
  199. * @offload_channel: The client manages the channel completely
  200. * @doorbell_mode_switch: Channel switches to doorbell mode on M0 transition
  201. * @auto_queue: Framework will automatically queue buffers for DL traffic
  202. * @auto_start: Automatically start (open) this channel
  203. * @wake-capable: Channel capable of waking up the system
  204. */
  205. struct mhi_channel_config {
  206. char *name;
  207. u32 num;
  208. u32 num_elements;
  209. u32 local_elements;
  210. u32 event_ring;
  211. enum dma_data_direction dir;
  212. enum mhi_ch_type type;
  213. u32 ee_mask;
  214. u32 pollcfg;
  215. enum mhi_db_brst_mode doorbell;
  216. bool lpm_notify;
  217. bool offload_channel;
  218. bool doorbell_mode_switch;
  219. bool auto_queue;
  220. bool auto_start;
  221. bool wake_capable;
  222. };
  223. /**
  224. * struct mhi_event_config - Event ring configuration structure for controller
  225. * @num_elements: The number of elements that can be queued to this ring
  226. * @irq_moderation_ms: Delay irq for additional events to be aggregated
  227. * @irq: IRQ associated with this ring
  228. * @channel: Dedicated channel number. U32_MAX indicates a non-dedicated ring
  229. * @priority: Priority of this ring. Use 1 for now
  230. * @mode: Doorbell mode
  231. * @data_type: Type of data this ring will process
  232. * @hardware_event: This ring is associated with hardware channels
  233. * @client_managed: This ring is client managed
  234. * @offload_channel: This ring is associated with an offloaded channel
  235. */
  236. struct mhi_event_config {
  237. u32 num_elements;
  238. u32 irq_moderation_ms;
  239. u32 irq;
  240. u32 channel;
  241. u32 priority;
  242. enum mhi_db_brst_mode mode;
  243. enum mhi_er_data_type data_type;
  244. bool hardware_event;
  245. bool client_managed;
  246. bool offload_channel;
  247. };
  248. /**
  249. * struct mhi_controller_config - Root MHI controller configuration
  250. * @max_channels: Maximum number of channels supported
  251. * @timeout_ms: Timeout value for operations. 0 means use default
  252. * @buf_len: Size of automatically allocated buffers. 0 means use default
  253. * @num_channels: Number of channels defined in @ch_cfg
  254. * @ch_cfg: Array of defined channels
  255. * @num_events: Number of event rings defined in @event_cfg
  256. * @event_cfg: Array of defined event rings
  257. * @use_bounce_buf: Use a bounce buffer pool due to limited DDR access
  258. * @m2_no_db: Host is not allowed to ring DB in M2 state
  259. */
  260. struct mhi_controller_config {
  261. u32 max_channels;
  262. u32 timeout_ms;
  263. u32 buf_len;
  264. u32 num_channels;
  265. const struct mhi_channel_config *ch_cfg;
  266. u32 num_events;
  267. const struct mhi_event_config *event_cfg;
  268. bool use_bounce_buf;
  269. bool m2_no_db;
  270. };
  271. /**
  272. * struct mhi_controller - Master MHI controller structure
  273. * @cntrl_dev: Pointer to the struct device of physical bus acting as the MHI
  274. * controller (required)
  275. * @mhi_dev: MHI device instance for the controller
  276. * @debugfs_dentry: MHI controller debugfs directory
  277. * @regs: Base address of MHI MMIO register space (required)
  278. * @bhi: Points to base of MHI BHI register space
  279. * @bhie: Points to base of MHI BHIe register space
  280. * @wake_db: MHI WAKE doorbell register address
  281. * @iova_start: IOMMU starting address for data (required)
  282. * @iova_stop: IOMMU stop address for data (required)
  283. * @fw_image: Firmware image name for normal booting (required)
  284. * @edl_image: Firmware image name for emergency download mode (optional)
  285. * @rddm_size: RAM dump size that host should allocate for debugging purpose
  286. * @sbl_size: SBL image size downloaded through BHIe (optional)
  287. * @seg_len: BHIe vector size (optional)
  288. * @fbc_image: Points to firmware image buffer
  289. * @rddm_image: Points to RAM dump buffer
  290. * @mhi_chan: Points to the channel configuration table
  291. * @lpm_chans: List of channels that require LPM notifications
  292. * @irq: base irq # to request (required)
  293. * @max_chan: Maximum number of channels the controller supports
  294. * @total_ev_rings: Total # of event rings allocated
  295. * @hw_ev_rings: Number of hardware event rings
  296. * @sw_ev_rings: Number of software event rings
  297. * @nr_irqs: Number of IRQ allocated by bus master (required)
  298. * @family_number: MHI controller family number
  299. * @device_number: MHI controller device number
  300. * @major_version: MHI controller major revision number
  301. * @minor_version: MHI controller minor revision number
  302. * @serial_number: MHI controller serial number obtained from BHI
  303. * @oem_pk_hash: MHI controller OEM PK Hash obtained from BHI
  304. * @mhi_event: MHI event ring configurations table
  305. * @mhi_cmd: MHI command ring configurations table
  306. * @mhi_ctxt: MHI device context, shared memory between host and device
  307. * @pm_mutex: Mutex for suspend/resume operation
  308. * @pm_lock: Lock for protecting MHI power management state
  309. * @timeout_ms: Timeout in ms for state transitions
  310. * @pm_state: MHI power management state
  311. * @db_access: DB access states
  312. * @ee: MHI device execution environment
  313. * @dev_state: MHI device state
  314. * @dev_wake: Device wakeup count
  315. * @pending_pkts: Pending packets for the controller
  316. * @M0, M2, M3: Counters to track number of device MHI state changes
  317. * @transition_list: List of MHI state transitions
  318. * @transition_lock: Lock for protecting MHI state transition list
  319. * @wlock: Lock for protecting device wakeup
  320. * @mhi_link_info: Device bandwidth info
  321. * @st_worker: State transition worker
  322. * @state_event: State change event
  323. * @status_cb: CB function to notify power states of the device (required)
  324. * @wake_get: CB function to assert device wake (optional)
  325. * @wake_put: CB function to de-assert device wake (optional)
  326. * @wake_toggle: CB function to assert and de-assert device wake (optional)
  327. * @runtime_get: CB function to controller runtime resume (required)
  328. * @runtime_put: CB function to decrement pm usage (required)
  329. * @map_single: CB function to create TRE buffer
  330. * @unmap_single: CB function to destroy TRE buffer
  331. * @read_reg: Read a MHI register via the physical link (required)
  332. * @write_reg: Write a MHI register via the physical link (required)
  333. * @buffer_len: Bounce buffer length
  334. * @bounce_buf: Use of bounce buffer
  335. * @fbc_download: MHI host needs to do complete image transfer (optional)
  336. * @pre_init: MHI host needs to do pre-initialization before power up
  337. * @wake_set: Device wakeup set flag
  338. *
  339. * Fields marked as (required) need to be populated by the controller driver
  340. * before calling mhi_register_controller(). For the fields marked as (optional)
  341. * they can be populated depending on the usecase.
  342. *
  343. * The following fields are present for the purpose of implementing any device
  344. * specific quirks or customizations for specific MHI revisions used in device
  345. * by the controller drivers. The MHI stack will just populate these fields
  346. * during mhi_register_controller():
  347. * family_number
  348. * device_number
  349. * major_version
  350. * minor_version
  351. */
  352. struct mhi_controller {
  353. struct device *cntrl_dev;
  354. struct mhi_device *mhi_dev;
  355. struct dentry *debugfs_dentry;
  356. void __iomem *regs;
  357. void __iomem *bhi;
  358. void __iomem *bhie;
  359. void __iomem *wake_db;
  360. dma_addr_t iova_start;
  361. dma_addr_t iova_stop;
  362. const char *fw_image;
  363. const char *edl_image;
  364. size_t rddm_size;
  365. size_t sbl_size;
  366. size_t seg_len;
  367. struct image_info *fbc_image;
  368. struct image_info *rddm_image;
  369. struct mhi_chan *mhi_chan;
  370. struct list_head lpm_chans;
  371. int *irq;
  372. u32 max_chan;
  373. u32 total_ev_rings;
  374. u32 hw_ev_rings;
  375. u32 sw_ev_rings;
  376. u32 nr_irqs;
  377. u32 family_number;
  378. u32 device_number;
  379. u32 major_version;
  380. u32 minor_version;
  381. u32 serial_number;
  382. u32 oem_pk_hash[MHI_MAX_OEM_PK_HASH_SEGMENTS];
  383. struct mhi_event *mhi_event;
  384. struct mhi_cmd *mhi_cmd;
  385. struct mhi_ctxt *mhi_ctxt;
  386. struct mutex pm_mutex;
  387. rwlock_t pm_lock;
  388. u32 timeout_ms;
  389. u32 pm_state;
  390. u32 db_access;
  391. enum mhi_ee_type ee;
  392. enum mhi_state dev_state;
  393. atomic_t dev_wake;
  394. atomic_t pending_pkts;
  395. u32 M0, M2, M3;
  396. struct list_head transition_list;
  397. spinlock_t transition_lock;
  398. spinlock_t wlock;
  399. struct mhi_link_info mhi_link_info;
  400. struct work_struct st_worker;
  401. wait_queue_head_t state_event;
  402. void (*status_cb)(struct mhi_controller *mhi_cntrl,
  403. enum mhi_callback cb);
  404. void (*wake_get)(struct mhi_controller *mhi_cntrl, bool override);
  405. void (*wake_put)(struct mhi_controller *mhi_cntrl, bool override);
  406. void (*wake_toggle)(struct mhi_controller *mhi_cntrl);
  407. int (*runtime_get)(struct mhi_controller *mhi_cntrl);
  408. void (*runtime_put)(struct mhi_controller *mhi_cntrl);
  409. int (*map_single)(struct mhi_controller *mhi_cntrl,
  410. struct mhi_buf_info *buf);
  411. void (*unmap_single)(struct mhi_controller *mhi_cntrl,
  412. struct mhi_buf_info *buf);
  413. int (*read_reg)(struct mhi_controller *mhi_cntrl, void __iomem *addr,
  414. u32 *out);
  415. void (*write_reg)(struct mhi_controller *mhi_cntrl, void __iomem *addr,
  416. u32 val);
  417. size_t buffer_len;
  418. bool bounce_buf;
  419. bool fbc_download;
  420. bool pre_init;
  421. bool wake_set;
  422. };
  423. /**
  424. * struct mhi_device - Structure representing an MHI device which binds
  425. * to channels or is associated with controllers
  426. * @id: Pointer to MHI device ID struct
  427. * @name: Name of the associated MHI device
  428. * @mhi_cntrl: Controller the device belongs to
  429. * @ul_chan: UL channel for the device
  430. * @dl_chan: DL channel for the device
  431. * @dev: Driver model device node for the MHI device
  432. * @dev_type: MHI device type
  433. * @ul_chan_id: MHI channel id for UL transfer
  434. * @dl_chan_id: MHI channel id for DL transfer
  435. * @dev_wake: Device wakeup counter
  436. */
  437. struct mhi_device {
  438. const struct mhi_device_id *id;
  439. const char *name;
  440. struct mhi_controller *mhi_cntrl;
  441. struct mhi_chan *ul_chan;
  442. struct mhi_chan *dl_chan;
  443. struct device dev;
  444. enum mhi_device_type dev_type;
  445. int ul_chan_id;
  446. int dl_chan_id;
  447. u32 dev_wake;
  448. };
  449. /**
  450. * struct mhi_result - Completed buffer information
  451. * @buf_addr: Address of data buffer
  452. * @bytes_xferd: # of bytes transferred
  453. * @dir: Channel direction
  454. * @transaction_status: Status of last transaction
  455. */
  456. struct mhi_result {
  457. void *buf_addr;
  458. size_t bytes_xferd;
  459. enum dma_data_direction dir;
  460. int transaction_status;
  461. };
  462. /**
  463. * struct mhi_buf - MHI Buffer description
  464. * @buf: Virtual address of the buffer
  465. * @name: Buffer label. For offload channel, configurations name must be:
  466. * ECA - Event context array data
  467. * CCA - Channel context array data
  468. * @dma_addr: IOMMU address of the buffer
  469. * @len: # of bytes
  470. */
  471. struct mhi_buf {
  472. void *buf;
  473. const char *name;
  474. dma_addr_t dma_addr;
  475. size_t len;
  476. };
  477. /**
  478. * struct mhi_driver - Structure representing a MHI client driver
  479. * @probe: CB function for client driver probe function
  480. * @remove: CB function for client driver remove function
  481. * @ul_xfer_cb: CB function for UL data transfer
  482. * @dl_xfer_cb: CB function for DL data transfer
  483. * @status_cb: CB functions for asynchronous status
  484. * @driver: Device driver model driver
  485. */
  486. struct mhi_driver {
  487. const struct mhi_device_id *id_table;
  488. int (*probe)(struct mhi_device *mhi_dev,
  489. const struct mhi_device_id *id);
  490. void (*remove)(struct mhi_device *mhi_dev);
  491. void (*ul_xfer_cb)(struct mhi_device *mhi_dev,
  492. struct mhi_result *result);
  493. void (*dl_xfer_cb)(struct mhi_device *mhi_dev,
  494. struct mhi_result *result);
  495. void (*status_cb)(struct mhi_device *mhi_dev, enum mhi_callback mhi_cb);
  496. struct device_driver driver;
  497. };
  498. #define to_mhi_driver(drv) container_of(drv, struct mhi_driver, driver)
  499. #define to_mhi_device(dev) container_of(dev, struct mhi_device, dev)
  500. /**
  501. * mhi_alloc_controller - Allocate the MHI Controller structure
  502. * Allocate the mhi_controller structure using zero initialized memory
  503. */
  504. struct mhi_controller *mhi_alloc_controller(void);
  505. /**
  506. * mhi_free_controller - Free the MHI Controller structure
  507. * Free the mhi_controller structure which was previously allocated
  508. */
  509. void mhi_free_controller(struct mhi_controller *mhi_cntrl);
  510. /**
  511. * mhi_register_controller - Register MHI controller
  512. * @mhi_cntrl: MHI controller to register
  513. * @config: Configuration to use for the controller
  514. */
  515. int mhi_register_controller(struct mhi_controller *mhi_cntrl,
  516. const struct mhi_controller_config *config);
  517. /**
  518. * mhi_unregister_controller - Unregister MHI controller
  519. * @mhi_cntrl: MHI controller to unregister
  520. */
  521. void mhi_unregister_controller(struct mhi_controller *mhi_cntrl);
  522. /*
  523. * module_mhi_driver() - Helper macro for drivers that don't do
  524. * anything special other than using default mhi_driver_register() and
  525. * mhi_driver_unregister(). This eliminates a lot of boilerplate.
  526. * Each module may only use this macro once.
  527. */
  528. #define module_mhi_driver(mhi_drv) \
  529. module_driver(mhi_drv, mhi_driver_register, \
  530. mhi_driver_unregister)
  531. /*
  532. * Macro to avoid include chaining to get THIS_MODULE
  533. */
  534. #define mhi_driver_register(mhi_drv) \
  535. __mhi_driver_register(mhi_drv, THIS_MODULE)
  536. /**
  537. * __mhi_driver_register - Register driver with MHI framework
  538. * @mhi_drv: Driver associated with the device
  539. * @owner: The module owner
  540. */
  541. int __mhi_driver_register(struct mhi_driver *mhi_drv, struct module *owner);
  542. /**
  543. * mhi_driver_unregister - Unregister a driver for mhi_devices
  544. * @mhi_drv: Driver associated with the device
  545. */
  546. void mhi_driver_unregister(struct mhi_driver *mhi_drv);
  547. /**
  548. * mhi_set_mhi_state - Set MHI device state
  549. * @mhi_cntrl: MHI controller
  550. * @state: State to set
  551. */
  552. void mhi_set_mhi_state(struct mhi_controller *mhi_cntrl,
  553. enum mhi_state state);
  554. /**
  555. * mhi_notify - Notify the MHI client driver about client device status
  556. * @mhi_dev: MHI device instance
  557. * @cb_reason: MHI callback reason
  558. */
  559. void mhi_notify(struct mhi_device *mhi_dev, enum mhi_callback cb_reason);
  560. /**
  561. * mhi_prepare_for_power_up - Do pre-initialization before power up.
  562. * This is optional, call this before power up if
  563. * the controller does not want bus framework to
  564. * automatically free any allocated memory during
  565. * shutdown process.
  566. * @mhi_cntrl: MHI controller
  567. */
  568. int mhi_prepare_for_power_up(struct mhi_controller *mhi_cntrl);
  569. /**
  570. * mhi_async_power_up - Start MHI power up sequence
  571. * @mhi_cntrl: MHI controller
  572. */
  573. int mhi_async_power_up(struct mhi_controller *mhi_cntrl);
  574. /**
  575. * mhi_sync_power_up - Start MHI power up sequence and wait till the device
  576. * enters valid EE state
  577. * @mhi_cntrl: MHI controller
  578. */
  579. int mhi_sync_power_up(struct mhi_controller *mhi_cntrl);
  580. /**
  581. * mhi_power_down - Start MHI power down sequence
  582. * @mhi_cntrl: MHI controller
  583. * @graceful: Link is still accessible, so do a graceful shutdown process
  584. */
  585. void mhi_power_down(struct mhi_controller *mhi_cntrl, bool graceful);
  586. /**
  587. * mhi_unprepare_after_power_down - Free any allocated memory after power down
  588. * @mhi_cntrl: MHI controller
  589. */
  590. void mhi_unprepare_after_power_down(struct mhi_controller *mhi_cntrl);
  591. /**
  592. * mhi_pm_suspend - Move MHI into a suspended state
  593. * @mhi_cntrl: MHI controller
  594. */
  595. int mhi_pm_suspend(struct mhi_controller *mhi_cntrl);
  596. /**
  597. * mhi_pm_resume - Resume MHI from suspended state
  598. * @mhi_cntrl: MHI controller
  599. */
  600. int mhi_pm_resume(struct mhi_controller *mhi_cntrl);
  601. /**
  602. * mhi_download_rddm_img - Download ramdump image from device for
  603. * debugging purpose.
  604. * @mhi_cntrl: MHI controller
  605. * @in_panic: Download rddm image during kernel panic
  606. */
  607. int mhi_download_rddm_img(struct mhi_controller *mhi_cntrl, bool in_panic);
  608. /**
  609. * mhi_force_rddm_mode - Force device into rddm mode
  610. * @mhi_cntrl: MHI controller
  611. */
  612. int mhi_force_rddm_mode(struct mhi_controller *mhi_cntrl);
  613. /**
  614. * mhi_get_mhi_state - Get MHI state of the device
  615. * @mhi_cntrl: MHI controller
  616. */
  617. enum mhi_state mhi_get_mhi_state(struct mhi_controller *mhi_cntrl);
  618. /**
  619. * mhi_device_get - Disable device low power mode
  620. * @mhi_dev: Device associated with the channel
  621. */
  622. void mhi_device_get(struct mhi_device *mhi_dev);
  623. /**
  624. * mhi_device_get_sync - Disable device low power mode. Synchronously
  625. * take the controller out of suspended state
  626. * @mhi_dev: Device associated with the channel
  627. */
  628. int mhi_device_get_sync(struct mhi_device *mhi_dev);
  629. /**
  630. * mhi_device_put - Re-enable device low power mode
  631. * @mhi_dev: Device associated with the channel
  632. */
  633. void mhi_device_put(struct mhi_device *mhi_dev);
  634. /**
  635. * mhi_prepare_for_transfer - Setup channel for data transfer
  636. * @mhi_dev: Device associated with the channels
  637. */
  638. int mhi_prepare_for_transfer(struct mhi_device *mhi_dev);
  639. /**
  640. * mhi_unprepare_from_transfer - Unprepare the channels
  641. * @mhi_dev: Device associated with the channels
  642. */
  643. void mhi_unprepare_from_transfer(struct mhi_device *mhi_dev);
  644. /**
  645. * mhi_poll - Poll for any available data in DL direction
  646. * @mhi_dev: Device associated with the channels
  647. * @budget: # of events to process
  648. */
  649. int mhi_poll(struct mhi_device *mhi_dev, u32 budget);
  650. /**
  651. * mhi_queue_dma - Send or receive DMA mapped buffers from client device
  652. * over MHI channel
  653. * @mhi_dev: Device associated with the channels
  654. * @dir: DMA direction for the channel
  655. * @mhi_buf: Buffer for holding the DMA mapped data
  656. * @len: Buffer length
  657. * @mflags: MHI transfer flags used for the transfer
  658. */
  659. int mhi_queue_dma(struct mhi_device *mhi_dev, enum dma_data_direction dir,
  660. struct mhi_buf *mhi_buf, size_t len, enum mhi_flags mflags);
  661. /**
  662. * mhi_queue_buf - Send or receive raw buffers from client device over MHI
  663. * channel
  664. * @mhi_dev: Device associated with the channels
  665. * @dir: DMA direction for the channel
  666. * @buf: Buffer for holding the data
  667. * @len: Buffer length
  668. * @mflags: MHI transfer flags used for the transfer
  669. */
  670. int mhi_queue_buf(struct mhi_device *mhi_dev, enum dma_data_direction dir,
  671. void *buf, size_t len, enum mhi_flags mflags);
  672. /**
  673. * mhi_queue_skb - Send or receive SKBs from client device over MHI channel
  674. * @mhi_dev: Device associated with the channels
  675. * @dir: DMA direction for the channel
  676. * @skb: Buffer for holding SKBs
  677. * @len: Buffer length
  678. * @mflags: MHI transfer flags used for the transfer
  679. */
  680. int mhi_queue_skb(struct mhi_device *mhi_dev, enum dma_data_direction dir,
  681. struct sk_buff *skb, size_t len, enum mhi_flags mflags);
  682. #endif /* _MHI_H_ */