vhost-user.json 6.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267
  1. # -*- Mode: Python -*-
  2. # vim: filetype=python
  3. #
  4. # Copyright (C) 2018 Red Hat, Inc.
  5. #
  6. # Authors:
  7. # Marc-André Lureau <marcandre.lureau@redhat.com>
  8. #
  9. # This work is licensed under the terms of the GNU GPL, version 2 or
  10. # later. See the COPYING file in the top-level directory.
  11. ##
  12. # = vhost user backend discovery & capabilities
  13. ##
  14. ##
  15. # @VHostUserBackendType:
  16. #
  17. # List the various vhost user backend types.
  18. #
  19. # @9p: 9p virtio console
  20. # @balloon: virtio balloon
  21. # @block: virtio block
  22. # @caif: virtio caif
  23. # @console: virtio console
  24. # @crypto: virtio crypto
  25. # @gpu: virtio gpu
  26. # @input: virtio input
  27. # @net: virtio net
  28. # @rng: virtio rng
  29. # @rpmsg: virtio remote processor messaging
  30. # @rproc-serial: virtio remoteproc serial link
  31. # @scsi: virtio scsi
  32. # @vsock: virtio vsock transport
  33. # @fs: virtio fs (since 4.2)
  34. #
  35. # Since: 4.0
  36. ##
  37. {
  38. 'enum': 'VHostUserBackendType',
  39. 'data': [
  40. '9p',
  41. 'balloon',
  42. 'block',
  43. 'caif',
  44. 'console',
  45. 'crypto',
  46. 'gpu',
  47. 'input',
  48. 'net',
  49. 'rng',
  50. 'rpmsg',
  51. 'rproc-serial',
  52. 'scsi',
  53. 'vsock',
  54. 'fs'
  55. ]
  56. }
  57. ##
  58. # @VHostUserBackendBlockFeature:
  59. #
  60. # List of vhost user "block" features.
  61. #
  62. # @read-only: The --read-only command line option is supported.
  63. # @blk-file: The --blk-file command line option is supported.
  64. #
  65. # Since: 5.0
  66. ##
  67. {
  68. 'enum': 'VHostUserBackendBlockFeature',
  69. 'data': [ 'read-only', 'blk-file' ]
  70. }
  71. ##
  72. # @VHostUserBackendCapabilitiesBlock:
  73. #
  74. # Capabilities reported by vhost user "block" backends
  75. #
  76. # @features: list of supported features.
  77. #
  78. # Since: 5.0
  79. ##
  80. {
  81. 'struct': 'VHostUserBackendCapabilitiesBlock',
  82. 'data': {
  83. 'features': [ 'VHostUserBackendBlockFeature' ]
  84. }
  85. }
  86. ##
  87. # @VHostUserBackendInputFeature:
  88. #
  89. # List of vhost user "input" features.
  90. #
  91. # @evdev-path: The --evdev-path command line option is supported.
  92. # @no-grab: The --no-grab command line option is supported.
  93. #
  94. # Since: 4.0
  95. ##
  96. {
  97. 'enum': 'VHostUserBackendInputFeature',
  98. 'data': [ 'evdev-path', 'no-grab' ]
  99. }
  100. ##
  101. # @VHostUserBackendCapabilitiesInput:
  102. #
  103. # Capabilities reported by vhost user "input" backends
  104. #
  105. # @features: list of supported features.
  106. #
  107. # Since: 4.0
  108. ##
  109. {
  110. 'struct': 'VHostUserBackendCapabilitiesInput',
  111. 'data': {
  112. 'features': [ 'VHostUserBackendInputFeature' ]
  113. }
  114. }
  115. ##
  116. # @VHostUserBackendGPUFeature:
  117. #
  118. # List of vhost user "gpu" features.
  119. #
  120. # @render-node: The --render-node command line option is supported.
  121. # @virgl: The --virgl command line option is supported.
  122. #
  123. # Since: 4.0
  124. ##
  125. {
  126. 'enum': 'VHostUserBackendGPUFeature',
  127. 'data': [ 'render-node', 'virgl' ]
  128. }
  129. ##
  130. # @VHostUserBackendCapabilitiesGPU:
  131. #
  132. # Capabilities reported by vhost user "gpu" backends.
  133. #
  134. # @features: list of supported features.
  135. #
  136. # Since: 4.0
  137. ##
  138. {
  139. 'struct': 'VHostUserBackendCapabilitiesGPU',
  140. 'data': {
  141. 'features': [ 'VHostUserBackendGPUFeature' ]
  142. }
  143. }
  144. ##
  145. # @VHostUserBackendCapabilities:
  146. #
  147. # Capabilities reported by vhost user backends.
  148. #
  149. # @type: The vhost user backend type.
  150. #
  151. # Since: 4.0
  152. ##
  153. {
  154. 'union': 'VHostUserBackendCapabilities',
  155. 'base': { 'type': 'VHostUserBackendType' },
  156. 'discriminator': 'type',
  157. 'data': {
  158. 'input': 'VHostUserBackendCapabilitiesInput',
  159. 'gpu': 'VHostUserBackendCapabilitiesGPU'
  160. }
  161. }
  162. ##
  163. # @VhostUserBackend:
  164. #
  165. # Describes a vhost user backend to management software.
  166. #
  167. # It is possible for multiple @VhostUserBackend elements to match the
  168. # search criteria of management software. Applications thus need rules
  169. # to pick one of the many matches, and users need the ability to
  170. # override distro defaults.
  171. #
  172. # It is recommended to create vhost user backend JSON files (each
  173. # containing a single @VhostUserBackend root element) with a
  174. # double-digit prefix, for example "50-qemu-gpu.json",
  175. # "50-crosvm-gpu.json", etc, so they can be sorted in predictable
  176. # order. The backend JSON files should be searched for in three
  177. # directories:
  178. #
  179. # - /usr/share/qemu/vhost-user -- populated by distro-provided
  180. # packages (XDG_DATA_DIRS covers
  181. # /usr/share by default),
  182. #
  183. # - /etc/qemu/vhost-user -- exclusively for sysadmins' local additions,
  184. #
  185. # - $XDG_CONFIG_HOME/qemu/vhost-user -- exclusively for per-user local
  186. # additions (XDG_CONFIG_HOME
  187. # defaults to $HOME/.config).
  188. #
  189. # Top-down, the list of directories goes from general to specific.
  190. #
  191. # Management software should build a list of files from all three
  192. # locations, then sort the list by filename (i.e., basename
  193. # component). Management software should choose the first JSON file on
  194. # the sorted list that matches the search criteria. If a more specific
  195. # directory has a file with same name as a less specific directory,
  196. # then the file in the more specific directory takes effect. If the
  197. # more specific file is zero length, it hides the less specific one.
  198. #
  199. # For example, if a distro ships
  200. #
  201. # - /usr/share/qemu/vhost-user/50-qemu-gpu.json
  202. #
  203. # - /usr/share/qemu/vhost-user/50-crosvm-gpu.json
  204. #
  205. # then the sysadmin can prevent the default QEMU GPU being used at all with
  206. #
  207. # $ touch /etc/qemu/vhost-user/50-qemu-gpu.json
  208. #
  209. # The sysadmin can replace/alter the distro default QEMU GPU with
  210. #
  211. # $ vim /etc/qemu/vhost-user/50-qemu-gpu.json
  212. #
  213. # or they can provide a parallel QEMU GPU with higher priority
  214. #
  215. # $ vim /etc/qemu/vhost-user/10-qemu-gpu.json
  216. #
  217. # or they can provide a parallel QEMU GPU with lower priority
  218. #
  219. # $ vim /etc/qemu/vhost-user/99-qemu-gpu.json
  220. #
  221. # @type: The vhost user backend type.
  222. #
  223. # @description: Provides a human-readable description of the backend.
  224. # Management software may or may not display @description.
  225. #
  226. # @binary: Absolute path to the backend binary.
  227. #
  228. # @tags: An optional list of auxiliary strings associated with the
  229. # backend for which @description is not appropriate, due to the
  230. # latter's possible exposure to the end-user. @tags serves
  231. # development and debugging purposes only, and management
  232. # software shall explicitly ignore it.
  233. #
  234. # Since: 4.0
  235. #
  236. # Example:
  237. #
  238. # {
  239. # "description": "QEMU vhost-user-gpu",
  240. # "type": "gpu",
  241. # "binary": "/usr/libexec/qemu/vhost-user-gpu",
  242. # "tags": [
  243. # "CONFIG_OPENGL=y",
  244. # "CONFIG_GBM=y"
  245. # ]
  246. # }
  247. #
  248. ##
  249. {
  250. 'struct' : 'VhostUserBackend',
  251. 'data' : {
  252. 'description': 'str',
  253. 'type': 'VHostUserBackendType',
  254. 'binary': 'str',
  255. '*tags': [ 'str' ]
  256. }
  257. }