1482580a6SMarc-André Lureau# -*- Mode: Python -*- 2f7160f32SAndrea Bolognani# vim: filetype=python 3482580a6SMarc-André Lureau# 4482580a6SMarc-André Lureau# Copyright (C) 2018 Red Hat, Inc. 5482580a6SMarc-André Lureau# 6482580a6SMarc-André Lureau# Authors: 7482580a6SMarc-André Lureau# Marc-André Lureau <marcandre.lureau@redhat.com> 8482580a6SMarc-André Lureau# 9482580a6SMarc-André Lureau# This work is licensed under the terms of the GNU GPL, version 2 or 10482580a6SMarc-André Lureau# later. See the COPYING file in the top-level directory. 11482580a6SMarc-André Lureau 12482580a6SMarc-André Lureau## 13482580a6SMarc-André Lureau# = vhost user backend discovery & capabilities 14482580a6SMarc-André Lureau## 15482580a6SMarc-André Lureau 16482580a6SMarc-André Lureau## 17482580a6SMarc-André Lureau# @VHostUserBackendType: 18482580a6SMarc-André Lureau# 19482580a6SMarc-André Lureau# List the various vhost user backend types. 20482580a6SMarc-André Lureau# 21482580a6SMarc-André Lureau# @9p: 9p virtio console 22482580a6SMarc-André Lureau# @balloon: virtio balloon 23482580a6SMarc-André Lureau# @block: virtio block 24482580a6SMarc-André Lureau# @caif: virtio caif 25482580a6SMarc-André Lureau# @console: virtio console 26482580a6SMarc-André Lureau# @crypto: virtio crypto 27482580a6SMarc-André Lureau# @gpu: virtio gpu 28482580a6SMarc-André Lureau# @input: virtio input 29482580a6SMarc-André Lureau# @net: virtio net 30482580a6SMarc-André Lureau# @rng: virtio rng 31482580a6SMarc-André Lureau# @rpmsg: virtio remote processor messaging 32482580a6SMarc-André Lureau# @rproc-serial: virtio remoteproc serial link 33482580a6SMarc-André Lureau# @scsi: virtio scsi 34482580a6SMarc-André Lureau# @vsock: virtio vsock transport 3545018fbbSStefan Hajnoczi# @fs: virtio fs (since 4.2) 36482580a6SMarc-André Lureau# 37482580a6SMarc-André Lureau# Since: 4.0 38482580a6SMarc-André Lureau## 39482580a6SMarc-André Lureau{ 40482580a6SMarc-André Lureau 'enum': 'VHostUserBackendType', 41482580a6SMarc-André Lureau 'data': [ 42482580a6SMarc-André Lureau '9p', 43482580a6SMarc-André Lureau 'balloon', 44482580a6SMarc-André Lureau 'block', 45482580a6SMarc-André Lureau 'caif', 46482580a6SMarc-André Lureau 'console', 47482580a6SMarc-André Lureau 'crypto', 48482580a6SMarc-André Lureau 'gpu', 49482580a6SMarc-André Lureau 'input', 50482580a6SMarc-André Lureau 'net', 51482580a6SMarc-André Lureau 'rng', 52482580a6SMarc-André Lureau 'rpmsg', 53482580a6SMarc-André Lureau 'rproc-serial', 54482580a6SMarc-André Lureau 'scsi', 5545018fbbSStefan Hajnoczi 'vsock', 5645018fbbSStefan Hajnoczi 'fs' 57482580a6SMarc-André Lureau ] 58482580a6SMarc-André Lureau} 59482580a6SMarc-André Lureau 60482580a6SMarc-André Lureau## 616620801fSMicky Yun Chan# @VHostUserBackendBlockFeature: 626620801fSMicky Yun Chan# 636620801fSMicky Yun Chan# List of vhost user "block" features. 646620801fSMicky Yun Chan# 656620801fSMicky Yun Chan# @read-only: The --read-only command line option is supported. 666620801fSMicky Yun Chan# @blk-file: The --blk-file command line option is supported. 676620801fSMicky Yun Chan# 686620801fSMicky Yun Chan# Since: 5.0 696620801fSMicky Yun Chan## 706620801fSMicky Yun Chan{ 716620801fSMicky Yun Chan 'enum': 'VHostUserBackendBlockFeature', 726620801fSMicky Yun Chan 'data': [ 'read-only', 'blk-file' ] 736620801fSMicky Yun Chan} 746620801fSMicky Yun Chan 756620801fSMicky Yun Chan## 766620801fSMicky Yun Chan# @VHostUserBackendCapabilitiesBlock: 776620801fSMicky Yun Chan# 786620801fSMicky Yun Chan# Capabilities reported by vhost user "block" backends 796620801fSMicky Yun Chan# 806620801fSMicky Yun Chan# @features: list of supported features. 816620801fSMicky Yun Chan# 826620801fSMicky Yun Chan# Since: 5.0 836620801fSMicky Yun Chan## 846620801fSMicky Yun Chan{ 856620801fSMicky Yun Chan 'struct': 'VHostUserBackendCapabilitiesBlock', 866620801fSMicky Yun Chan 'data': { 876620801fSMicky Yun Chan 'features': [ 'VHostUserBackendBlockFeature' ] 886620801fSMicky Yun Chan } 896620801fSMicky Yun Chan} 906620801fSMicky Yun Chan 916620801fSMicky Yun Chan## 92482580a6SMarc-André Lureau# @VHostUserBackendInputFeature: 93482580a6SMarc-André Lureau# 94482580a6SMarc-André Lureau# List of vhost user "input" features. 95482580a6SMarc-André Lureau# 96482580a6SMarc-André Lureau# @evdev-path: The --evdev-path command line option is supported. 97482580a6SMarc-André Lureau# @no-grab: The --no-grab command line option is supported. 98482580a6SMarc-André Lureau# 99482580a6SMarc-André Lureau# Since: 4.0 100482580a6SMarc-André Lureau## 101482580a6SMarc-André Lureau{ 102482580a6SMarc-André Lureau 'enum': 'VHostUserBackendInputFeature', 103482580a6SMarc-André Lureau 'data': [ 'evdev-path', 'no-grab' ] 104482580a6SMarc-André Lureau} 105482580a6SMarc-André Lureau 106482580a6SMarc-André Lureau## 107482580a6SMarc-André Lureau# @VHostUserBackendCapabilitiesInput: 108482580a6SMarc-André Lureau# 109482580a6SMarc-André Lureau# Capabilities reported by vhost user "input" backends 110482580a6SMarc-André Lureau# 111482580a6SMarc-André Lureau# @features: list of supported features. 112482580a6SMarc-André Lureau# 113482580a6SMarc-André Lureau# Since: 4.0 114482580a6SMarc-André Lureau## 115482580a6SMarc-André Lureau{ 116482580a6SMarc-André Lureau 'struct': 'VHostUserBackendCapabilitiesInput', 117482580a6SMarc-André Lureau 'data': { 118482580a6SMarc-André Lureau 'features': [ 'VHostUserBackendInputFeature' ] 119482580a6SMarc-André Lureau } 120482580a6SMarc-André Lureau} 121482580a6SMarc-André Lureau 122482580a6SMarc-André Lureau## 123482580a6SMarc-André Lureau# @VHostUserBackendGPUFeature: 124482580a6SMarc-André Lureau# 125482580a6SMarc-André Lureau# List of vhost user "gpu" features. 126482580a6SMarc-André Lureau# 127482580a6SMarc-André Lureau# @render-node: The --render-node command line option is supported. 128482580a6SMarc-André Lureau# @virgl: The --virgl command line option is supported. 129482580a6SMarc-André Lureau# 130482580a6SMarc-André Lureau# Since: 4.0 131482580a6SMarc-André Lureau## 132482580a6SMarc-André Lureau{ 133482580a6SMarc-André Lureau 'enum': 'VHostUserBackendGPUFeature', 134482580a6SMarc-André Lureau 'data': [ 'render-node', 'virgl' ] 135482580a6SMarc-André Lureau} 136482580a6SMarc-André Lureau 137482580a6SMarc-André Lureau## 138482580a6SMarc-André Lureau# @VHostUserBackendCapabilitiesGPU: 139482580a6SMarc-André Lureau# 140482580a6SMarc-André Lureau# Capabilities reported by vhost user "gpu" backends. 141482580a6SMarc-André Lureau# 142482580a6SMarc-André Lureau# @features: list of supported features. 143482580a6SMarc-André Lureau# 144482580a6SMarc-André Lureau# Since: 4.0 145482580a6SMarc-André Lureau## 146482580a6SMarc-André Lureau{ 147482580a6SMarc-André Lureau 'struct': 'VHostUserBackendCapabilitiesGPU', 148482580a6SMarc-André Lureau 'data': { 149482580a6SMarc-André Lureau 'features': [ 'VHostUserBackendGPUFeature' ] 150482580a6SMarc-André Lureau } 151482580a6SMarc-André Lureau} 152482580a6SMarc-André Lureau 153482580a6SMarc-André Lureau## 154482580a6SMarc-André Lureau# @VHostUserBackendCapabilities: 155482580a6SMarc-André Lureau# 156482580a6SMarc-André Lureau# Capabilities reported by vhost user backends. 157482580a6SMarc-André Lureau# 158482580a6SMarc-André Lureau# @type: The vhost user backend type. 159482580a6SMarc-André Lureau# 160482580a6SMarc-André Lureau# Since: 4.0 161482580a6SMarc-André Lureau## 162482580a6SMarc-André Lureau{ 163482580a6SMarc-André Lureau 'union': 'VHostUserBackendCapabilities', 164482580a6SMarc-André Lureau 'base': { 'type': 'VHostUserBackendType' }, 165482580a6SMarc-André Lureau 'discriminator': 'type', 166482580a6SMarc-André Lureau 'data': { 167482580a6SMarc-André Lureau 'input': 'VHostUserBackendCapabilitiesInput', 168482580a6SMarc-André Lureau 'gpu': 'VHostUserBackendCapabilitiesGPU' 169482580a6SMarc-André Lureau } 170482580a6SMarc-André Lureau} 171482580a6SMarc-André Lureau 172482580a6SMarc-André Lureau## 173482580a6SMarc-André Lureau# @VhostUserBackend: 174482580a6SMarc-André Lureau# 175482580a6SMarc-André Lureau# Describes a vhost user backend to management software. 176482580a6SMarc-André Lureau# 177482580a6SMarc-André Lureau# It is possible for multiple @VhostUserBackend elements to match the 178482580a6SMarc-André Lureau# search criteria of management software. Applications thus need rules 179482580a6SMarc-André Lureau# to pick one of the many matches, and users need the ability to 180482580a6SMarc-André Lureau# override distro defaults. 181482580a6SMarc-André Lureau# 182482580a6SMarc-André Lureau# It is recommended to create vhost user backend JSON files (each 183482580a6SMarc-André Lureau# containing a single @VhostUserBackend root element) with a 184482580a6SMarc-André Lureau# double-digit prefix, for example "50-qemu-gpu.json", 185482580a6SMarc-André Lureau# "50-crosvm-gpu.json", etc, so they can be sorted in predictable 186482580a6SMarc-André Lureau# order. The backend JSON files should be searched for in three 187482580a6SMarc-André Lureau# directories: 188482580a6SMarc-André Lureau# 189482580a6SMarc-André Lureau# - /usr/share/qemu/vhost-user -- populated by distro-provided 190482580a6SMarc-André Lureau# packages (XDG_DATA_DIRS covers 191482580a6SMarc-André Lureau# /usr/share by default), 192482580a6SMarc-André Lureau# 193482580a6SMarc-André Lureau# - /etc/qemu/vhost-user -- exclusively for sysadmins' local additions, 194482580a6SMarc-André Lureau# 195482580a6SMarc-André Lureau# - $XDG_CONFIG_HOME/qemu/vhost-user -- exclusively for per-user local 196482580a6SMarc-André Lureau# additions (XDG_CONFIG_HOME 197482580a6SMarc-André Lureau# defaults to $HOME/.config). 198482580a6SMarc-André Lureau# 199482580a6SMarc-André Lureau# Top-down, the list of directories goes from general to specific. 200482580a6SMarc-André Lureau# 201482580a6SMarc-André Lureau# Management software should build a list of files from all three 202482580a6SMarc-André Lureau# locations, then sort the list by filename (i.e., basename 203482580a6SMarc-André Lureau# component). Management software should choose the first JSON file on 204482580a6SMarc-André Lureau# the sorted list that matches the search criteria. If a more specific 205482580a6SMarc-André Lureau# directory has a file with same name as a less specific directory, 206482580a6SMarc-André Lureau# then the file in the more specific directory takes effect. If the 207482580a6SMarc-André Lureau# more specific file is zero length, it hides the less specific one. 208482580a6SMarc-André Lureau# 209482580a6SMarc-André Lureau# For example, if a distro ships 210482580a6SMarc-André Lureau# 211482580a6SMarc-André Lureau# - /usr/share/qemu/vhost-user/50-qemu-gpu.json 212482580a6SMarc-André Lureau# 213482580a6SMarc-André Lureau# - /usr/share/qemu/vhost-user/50-crosvm-gpu.json 214482580a6SMarc-André Lureau# 21500ab8cb1SMarc-André Lureau# then the sysadmin can prevent the default QEMU GPU being used at all with 216482580a6SMarc-André Lureau# 217482580a6SMarc-André Lureau# $ touch /etc/qemu/vhost-user/50-qemu-gpu.json 218482580a6SMarc-André Lureau# 21900ab8cb1SMarc-André Lureau# The sysadmin can replace/alter the distro default QEMU GPU with 220482580a6SMarc-André Lureau# 221482580a6SMarc-André Lureau# $ vim /etc/qemu/vhost-user/50-qemu-gpu.json 222482580a6SMarc-André Lureau# 223482580a6SMarc-André Lureau# or they can provide a parallel QEMU GPU with higher priority 224482580a6SMarc-André Lureau# 225482580a6SMarc-André Lureau# $ vim /etc/qemu/vhost-user/10-qemu-gpu.json 226482580a6SMarc-André Lureau# 22700ab8cb1SMarc-André Lureau# or they can provide a parallel QEMU GPU with lower priority 228482580a6SMarc-André Lureau# 229482580a6SMarc-André Lureau# $ vim /etc/qemu/vhost-user/99-qemu-gpu.json 230482580a6SMarc-André Lureau# 231482580a6SMarc-André Lureau# @type: The vhost user backend type. 232482580a6SMarc-André Lureau# 233482580a6SMarc-André Lureau# @description: Provides a human-readable description of the backend. 234482580a6SMarc-André Lureau# Management software may or may not display @description. 235482580a6SMarc-André Lureau# 236482580a6SMarc-André Lureau# @binary: Absolute path to the backend binary. 237482580a6SMarc-André Lureau# 238482580a6SMarc-André Lureau# @tags: An optional list of auxiliary strings associated with the 239482580a6SMarc-André Lureau# backend for which @description is not appropriate, due to the 240482580a6SMarc-André Lureau# latter's possible exposure to the end-user. @tags serves 241482580a6SMarc-André Lureau# development and debugging purposes only, and management 242482580a6SMarc-André Lureau# software shall explicitly ignore it. 243482580a6SMarc-André Lureau# 244482580a6SMarc-André Lureau# Since: 4.0 245482580a6SMarc-André Lureau# 246482580a6SMarc-André Lureau# Example: 247482580a6SMarc-André Lureau# 248482580a6SMarc-André Lureau# { 249482580a6SMarc-André Lureau# "description": "QEMU vhost-user-gpu", 250482580a6SMarc-André Lureau# "type": "gpu", 251482580a6SMarc-André Lureau# "binary": "/usr/libexec/qemu/vhost-user-gpu", 252482580a6SMarc-André Lureau# "tags": [ 253*bc6a3565SAkihiko Odaki# "CONFIG_OPENGL=y", 254*bc6a3565SAkihiko Odaki# "CONFIG_GBM=y" 255482580a6SMarc-André Lureau# ] 256482580a6SMarc-André Lureau# } 257482580a6SMarc-André Lureau# 258482580a6SMarc-André Lureau## 259482580a6SMarc-André Lureau{ 260482580a6SMarc-André Lureau 'struct' : 'VhostUserBackend', 261482580a6SMarc-André Lureau 'data' : { 262482580a6SMarc-André Lureau 'description': 'str', 263482580a6SMarc-André Lureau 'type': 'VHostUserBackendType', 264482580a6SMarc-André Lureau 'binary': 'str', 265482580a6SMarc-André Lureau '*tags': [ 'str' ] 266482580a6SMarc-André Lureau } 267482580a6SMarc-André Lureau} 268