visorbus.h 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344
  1. // SPDX-License-Identifier: GPL-2.0+
  2. /*
  3. * Copyright (C) 2010 - 2013 UNISYS CORPORATION
  4. * All rights reserved.
  5. */
  6. /*
  7. * This header file is to be included by other kernel mode components that
  8. * implement a particular kind of visor_device. Each of these other kernel
  9. * mode components is called a visor device driver. Refer to visortemplate
  10. * for a minimal sample visor device driver.
  11. *
  12. * There should be nothing in this file that is private to the visorbus
  13. * bus implementation itself.
  14. */
  15. #ifndef __VISORBUS_H__
  16. #define __VISORBUS_H__
  17. #include <linux/device.h>
  18. #define VISOR_CHANNEL_SIGNATURE ('L' << 24 | 'N' << 16 | 'C' << 8 | 'E')
  19. /*
  20. * enum channel_serverstate
  21. * @CHANNELSRV_UNINITIALIZED: Channel is in an undefined state.
  22. * @CHANNELSRV_READY: Channel has been initialized by server.
  23. */
  24. enum channel_serverstate {
  25. CHANNELSRV_UNINITIALIZED = 0,
  26. CHANNELSRV_READY = 1
  27. };
  28. /*
  29. * enum channel_clientstate
  30. * @CHANNELCLI_DETACHED:
  31. * @CHANNELCLI_DISABLED: Client can see channel but is NOT allowed to use it
  32. * unless given TBD* explicit request
  33. * (should actually be < DETACHED).
  34. * @CHANNELCLI_ATTACHING: Legacy EFI client request for EFI server to attach.
  35. * @CHANNELCLI_ATTACHED: Idle, but client may want to use channel any time.
  36. * @CHANNELCLI_BUSY: Client either wants to use or is using channel.
  37. * @CHANNELCLI_OWNED: "No worries" state - client can access channel
  38. * anytime.
  39. */
  40. enum channel_clientstate {
  41. CHANNELCLI_DETACHED = 0,
  42. CHANNELCLI_DISABLED = 1,
  43. CHANNELCLI_ATTACHING = 2,
  44. CHANNELCLI_ATTACHED = 3,
  45. CHANNELCLI_BUSY = 4,
  46. CHANNELCLI_OWNED = 5
  47. };
  48. /*
  49. * Values for VISOR_CHANNEL_PROTOCOL.Features: This define exists so that
  50. * a guest can look at the FeatureFlags in the io channel, and configure the
  51. * driver to use interrupts or not based on this setting. All feature bits for
  52. * all channels should be defined here. The io channel feature bits are defined
  53. * below.
  54. */
  55. #define VISOR_DRIVER_ENABLES_INTS (0x1ULL << 1)
  56. #define VISOR_CHANNEL_IS_POLLING (0x1ULL << 3)
  57. #define VISOR_IOVM_OK_DRIVER_DISABLING_INTS (0x1ULL << 4)
  58. #define VISOR_DRIVER_DISABLES_INTS (0x1ULL << 5)
  59. #define VISOR_DRIVER_ENHANCED_RCVBUF_CHECKING (0x1ULL << 6)
  60. /*
  61. * struct channel_header - Common Channel Header
  62. * @signature: Signature.
  63. * @legacy_state: DEPRECATED - being replaced by.
  64. * @header_size: sizeof(struct channel_header).
  65. * @size: Total size of this channel in bytes.
  66. * @features: Flags to modify behavior.
  67. * @chtype: Channel type: data, bus, control, etc..
  68. * @partition_handle: ID of guest partition.
  69. * @handle: Device number of this channel in client.
  70. * @ch_space_offset: Offset in bytes to channel specific area.
  71. * @version_id: Struct channel_header Version ID.
  72. * @partition_index: Index of guest partition.
  73. * @zone_uuid: Guid of Channel's zone.
  74. * @cli_str_offset: Offset from channel header to null-terminated
  75. * ClientString (0 if ClientString not present).
  76. * @cli_state_boot: CHANNEL_CLIENTSTATE of pre-boot EFI client of this
  77. * channel.
  78. * @cmd_state_cli: CHANNEL_COMMANDSTATE (overloaded in Windows drivers, see
  79. * ServerStateUp, ServerStateDown, etc).
  80. * @cli_state_os: CHANNEL_CLIENTSTATE of Guest OS client of this channel.
  81. * @ch_characteristic: CHANNEL_CHARACTERISTIC_<xxx>.
  82. * @cmd_state_srv: CHANNEL_COMMANDSTATE (overloaded in Windows drivers, see
  83. * ServerStateUp, ServerStateDown, etc).
  84. * @srv_state: CHANNEL_SERVERSTATE.
  85. * @cli_error_boot: Bits to indicate err states for boot clients, so err
  86. * messages can be throttled.
  87. * @cli_error_os: Bits to indicate err states for OS clients, so err
  88. * messages can be throttled.
  89. * @filler: Pad out to 128 byte cacheline.
  90. * @recover_channel: Please add all new single-byte values below here.
  91. */
  92. struct channel_header {
  93. u64 signature;
  94. u32 legacy_state;
  95. /* SrvState, CliStateBoot, and CliStateOS below */
  96. u32 header_size;
  97. u64 size;
  98. u64 features;
  99. guid_t chtype;
  100. u64 partition_handle;
  101. u64 handle;
  102. u64 ch_space_offset;
  103. u32 version_id;
  104. u32 partition_index;
  105. guid_t zone_guid;
  106. u32 cli_str_offset;
  107. u32 cli_state_boot;
  108. u32 cmd_state_cli;
  109. u32 cli_state_os;
  110. u32 ch_characteristic;
  111. u32 cmd_state_srv;
  112. u32 srv_state;
  113. u8 cli_error_boot;
  114. u8 cli_error_os;
  115. u8 filler[1];
  116. u8 recover_channel;
  117. } __packed;
  118. #define VISOR_CHANNEL_ENABLE_INTS (0x1ULL << 0)
  119. /*
  120. * struct signal_queue_header - Subheader for the Signal Type variation of the
  121. * Common Channel.
  122. * @version: SIGNAL_QUEUE_HEADER Version ID.
  123. * @chtype: Queue type: storage, network.
  124. * @size: Total size of this queue in bytes.
  125. * @sig_base_offset: Offset to signal queue area.
  126. * @features: Flags to modify behavior.
  127. * @num_sent: Total # of signals placed in this queue.
  128. * @num_overflows: Total # of inserts failed due to full queue.
  129. * @signal_size: Total size of a signal for this queue.
  130. * @max_slots: Max # of slots in queue, 1 slot is always empty.
  131. * @max_signals: Max # of signals in queue (MaxSignalSlots-1).
  132. * @head: Queue head signal #.
  133. * @num_received: Total # of signals removed from this queue.
  134. * @tail: Queue tail signal.
  135. * @reserved1: Reserved field.
  136. * @reserved2: Reserved field.
  137. * @client_queue:
  138. * @num_irq_received: Total # of Interrupts received. This is incremented by the
  139. * ISR in the guest windows driver.
  140. * @num_empty: Number of times that visor_signal_remove is called and
  141. * returned Empty Status.
  142. * @errorflags: Error bits set during SignalReinit to denote trouble with
  143. * client's fields.
  144. * @filler: Pad out to 64 byte cacheline.
  145. */
  146. struct signal_queue_header {
  147. /* 1st cache line */
  148. u32 version;
  149. u32 chtype;
  150. u64 size;
  151. u64 sig_base_offset;
  152. u64 features;
  153. u64 num_sent;
  154. u64 num_overflows;
  155. u32 signal_size;
  156. u32 max_slots;
  157. u32 max_signals;
  158. u32 head;
  159. /* 2nd cache line */
  160. u64 num_received;
  161. u32 tail;
  162. u32 reserved1;
  163. u64 reserved2;
  164. u64 client_queue;
  165. u64 num_irq_received;
  166. u64 num_empty;
  167. u32 errorflags;
  168. u8 filler[12];
  169. } __packed;
  170. /* VISORCHANNEL Guids */
  171. /* {414815ed-c58c-11da-95a9-00e08161165f} */
  172. #define VISOR_VHBA_CHANNEL_GUID \
  173. GUID_INIT(0x414815ed, 0xc58c, 0x11da, \
  174. 0x95, 0xa9, 0x0, 0xe0, 0x81, 0x61, 0x16, 0x5f)
  175. #define VISOR_VHBA_CHANNEL_GUID_STR \
  176. "414815ed-c58c-11da-95a9-00e08161165f"
  177. struct visorchipset_state {
  178. u32 created:1;
  179. u32 attached:1;
  180. u32 configured:1;
  181. u32 running:1;
  182. /* Remaining bits in this 32-bit word are reserved. */
  183. };
  184. /**
  185. * struct visor_device - A device type for things "plugged" into the visorbus
  186. * bus
  187. * @visorchannel: Points to the channel that the device is
  188. * associated with.
  189. * @channel_type_guid: Identifies the channel type to the bus driver.
  190. * @device: Device struct meant for use by the bus driver
  191. * only.
  192. * @list_all: Used by the bus driver to enumerate devices.
  193. * @timer: Timer fired periodically to do interrupt-type
  194. * activity.
  195. * @being_removed: Indicates that the device is being removed from
  196. * the bus. Private bus driver use only.
  197. * @visordriver_callback_lock: Used by the bus driver to lock when adding and
  198. * removing devices.
  199. * @pausing: Indicates that a change towards a paused state.
  200. * is in progress. Only modified by the bus driver.
  201. * @resuming: Indicates that a change towards a running state
  202. * is in progress. Only modified by the bus driver.
  203. * @chipset_bus_no: Private field used by the bus driver.
  204. * @chipset_dev_no: Private field used the bus driver.
  205. * @state: Used to indicate the current state of the
  206. * device.
  207. * @inst: Unique GUID for this instance of the device.
  208. * @name: Name of the device.
  209. * @pending_msg_hdr: For private use by bus driver to respond to
  210. * hypervisor requests.
  211. * @vbus_hdr_info: A pointer to header info. Private use by bus
  212. * driver.
  213. * @partition_guid: Indicates client partion id. This should be the
  214. * same across all visor_devices in the current
  215. * guest. Private use by bus driver only.
  216. */
  217. struct visor_device {
  218. struct visorchannel *visorchannel;
  219. guid_t channel_type_guid;
  220. /* These fields are for private use by the bus driver only. */
  221. struct device device;
  222. struct list_head list_all;
  223. struct timer_list timer;
  224. bool timer_active;
  225. bool being_removed;
  226. struct mutex visordriver_callback_lock; /* synchronize probe/remove */
  227. bool pausing;
  228. bool resuming;
  229. u32 chipset_bus_no;
  230. u32 chipset_dev_no;
  231. struct visorchipset_state state;
  232. guid_t inst;
  233. u8 *name;
  234. struct controlvm_message_header *pending_msg_hdr;
  235. void *vbus_hdr_info;
  236. guid_t partition_guid;
  237. struct dentry *debugfs_dir;
  238. struct dentry *debugfs_bus_info;
  239. };
  240. #define to_visor_device(x) container_of(x, struct visor_device, device)
  241. typedef void (*visorbus_state_complete_func) (struct visor_device *dev,
  242. int status);
  243. /*
  244. * This struct describes a specific visor channel, by providing its GUID, name,
  245. * and sizes.
  246. */
  247. struct visor_channeltype_descriptor {
  248. const guid_t guid;
  249. const char *name;
  250. u64 min_bytes;
  251. u32 version;
  252. };
  253. /**
  254. * struct visor_driver - Information provided by each visor driver when it
  255. * registers with the visorbus driver
  256. * @name: Name of the visor driver.
  257. * @owner: The module owner.
  258. * @channel_types: Types of channels handled by this driver, ending with
  259. * a zero GUID. Our specialized BUS.match() method knows
  260. * about this list, and uses it to determine whether this
  261. * driver will in fact handle a new device that it has
  262. * detected.
  263. * @probe: Called when a new device comes online, by our probe()
  264. * function specified by driver.probe() (triggered
  265. * ultimately by some call to driver_register(),
  266. * bus_add_driver(), or driver_attach()).
  267. * @remove: Called when a new device is removed, by our remove()
  268. * function specified by driver.remove() (triggered
  269. * ultimately by some call to device_release_driver()).
  270. * @channel_interrupt: Called periodically, whenever there is a possiblity
  271. * that "something interesting" may have happened to the
  272. * channel.
  273. * @pause: Called to initiate a change of the device's state. If
  274. * the return valu`e is < 0, there was an error and the
  275. * state transition will NOT occur. If the return value
  276. * is >= 0, then the state transition was INITIATED
  277. * successfully, and complete_func() will be called (or
  278. * was just called) with the final status when either the
  279. * state transition fails or completes successfully.
  280. * @resume: Behaves similar to pause.
  281. * @driver: Private reference to the device driver. For use by bus
  282. * driver only.
  283. */
  284. struct visor_driver {
  285. const char *name;
  286. struct module *owner;
  287. struct visor_channeltype_descriptor *channel_types;
  288. int (*probe)(struct visor_device *dev);
  289. void (*remove)(struct visor_device *dev);
  290. void (*channel_interrupt)(struct visor_device *dev);
  291. int (*pause)(struct visor_device *dev,
  292. visorbus_state_complete_func complete_func);
  293. int (*resume)(struct visor_device *dev,
  294. visorbus_state_complete_func complete_func);
  295. /* These fields are for private use by the bus driver only. */
  296. struct device_driver driver;
  297. };
  298. #define to_visor_driver(x) (container_of(x, struct visor_driver, driver))
  299. int visor_check_channel(struct channel_header *ch, struct device *dev,
  300. const guid_t *expected_uuid, char *chname,
  301. u64 expected_min_bytes, u32 expected_version,
  302. u64 expected_signature);
  303. int visorbus_register_visor_driver(struct visor_driver *drv);
  304. void visorbus_unregister_visor_driver(struct visor_driver *drv);
  305. int visorbus_read_channel(struct visor_device *dev,
  306. unsigned long offset, void *dest,
  307. unsigned long nbytes);
  308. int visorbus_write_channel(struct visor_device *dev,
  309. unsigned long offset, void *src,
  310. unsigned long nbytes);
  311. int visorbus_enable_channel_interrupts(struct visor_device *dev);
  312. void visorbus_disable_channel_interrupts(struct visor_device *dev);
  313. int visorchannel_signalremove(struct visorchannel *channel, u32 queue,
  314. void *msg);
  315. int visorchannel_signalinsert(struct visorchannel *channel, u32 queue,
  316. void *msg);
  317. bool visorchannel_signalempty(struct visorchannel *channel, u32 queue);
  318. const guid_t *visorchannel_get_guid(struct visorchannel *channel);
  319. #define BUS_ROOT_DEVICE UINT_MAX
  320. struct visor_device *visorbus_get_device_by_id(u32 bus_no, u32 dev_no,
  321. struct visor_device *from);
  322. #endif