| Message ID | 69eb5f4fbae731f5fc05dea8a5f4b656e0de127f.1693252037.git.manos.pitsidianakis@linaro.org |
|---|---|
| State | New |
| Headers | show |
| Series | Add VIRTIO sound card | expand |
Emmanouil Pitsidianakis <manos.pitsidianakis@linaro.org> writes: > This commit adds basic documentation for using virtio-snd. > > Signed-off-by: Emmanouil Pitsidianakis <manos.pitsidianakis@linaro.org> > --- > docs/system/device-emulation.rst | 1 + > docs/system/devices/virtio-snd.rst | 49 ++++++++++++++++++++++++++++++ > 2 files changed, 50 insertions(+) > create mode 100644 docs/system/devices/virtio-snd.rst > > diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulation.rst > index 4491c4cbf7..dae19446e5 100644 > --- a/docs/system/device-emulation.rst > +++ b/docs/system/device-emulation.rst > @@ -92,6 +92,7 @@ Emulated Devices > devices/usb.rst > devices/vhost-user.rst > devices/virtio-pmem.rst > + devices/virtio-snd.rst > devices/vhost-user-rng.rst > devices/canokey.rst > devices/usb-u2f.rst > diff --git a/docs/system/devices/virtio-snd.rst b/docs/system/devices/virtio-snd.rst > new file mode 100644 > index 0000000000..2a9187fd70 > --- /dev/null > +++ b/docs/system/devices/virtio-snd.rst > @@ -0,0 +1,49 @@ > +virtio sound > +============ > + > +This document explains the setup and usage of the Virtio sound device. > +The Virtio sound device is a paravirtualized sound card device. > + > +Linux kernel support > +-------------------- > + > +Virtio sound requires a guest Linux kernel built with the > +``CONFIG_SND_VIRTIO`` option. > + > +Description > +----------- > + > +Virtio sound implements capture and playback from inside a guest using the > +configured audio backend of the host machine. > + > +Device properties > +----------------- > + > +The Virtio sound device can be configured with the following properties: > + > + * ``jacks`` number of physical jacks (Unimplemented). > + * ``streams`` number of PCM streams. At the moment, no stream configuration is supported: the first one will always be a playback stream, an optional second will always be a capture stream. Adding more will cycle stream directions from playback to capture. > + * ``chmaps`` number of channel maps (Unimplemented). I think you can drop the unimplemented properties from the docs and the code. No point having them if they do nothing and you might change your mind on the name when they are implemented ;-) > + > +All streams are stereo and have the default channel positions ``Front left, right``. > + > +Examples > +-------- > + > +Add an audio device and an audio backend at once with ``-audio`` and ``model=virtio``: > + > + * pulseaudio: ``-audio driver=pa,model=virtio`` > + or ``-audio driver=pa,model=virtio,server=/run/user/1000/pulse/native`` > + * sdl: ``-audio driver=sdl,model=virtio`` > + * coreaudio: ``-audio driver=coreaudio,model=virtio`` > + > +etc. > + > +To specifically add virtualized sound devices, you have to specify a PCI device > +and an audio backend listed with ``-audio driver=help`` that works on your host > +machine, e.g.: I'd be tempted to start with the specific example and then mention the shortcut. I'm curious as to how model= resolves on various platforms or how you would tell from the command line. > + > +:: > + > + -device virtio-sound-pci,audiodev=my_audiodev \ > + -audiodev alsa,id=my_audiodev Otherwise: Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulation.rst index 4491c4cbf7..dae19446e5 100644 --- a/docs/system/device-emulation.rst +++ b/docs/system/device-emulation.rst @@ -92,6 +92,7 @@ Emulated Devices devices/usb.rst devices/vhost-user.rst devices/virtio-pmem.rst + devices/virtio-snd.rst devices/vhost-user-rng.rst devices/canokey.rst devices/usb-u2f.rst diff --git a/docs/system/devices/virtio-snd.rst b/docs/system/devices/virtio-snd.rst new file mode 100644 index 0000000000..2a9187fd70 --- /dev/null +++ b/docs/system/devices/virtio-snd.rst @@ -0,0 +1,49 @@ +virtio sound +============ + +This document explains the setup and usage of the Virtio sound device. +The Virtio sound device is a paravirtualized sound card device. + +Linux kernel support +-------------------- + +Virtio sound requires a guest Linux kernel built with the +``CONFIG_SND_VIRTIO`` option. + +Description +----------- + +Virtio sound implements capture and playback from inside a guest using the +configured audio backend of the host machine. + +Device properties +----------------- + +The Virtio sound device can be configured with the following properties: + + * ``jacks`` number of physical jacks (Unimplemented). + * ``streams`` number of PCM streams. At the moment, no stream configuration is supported: the first one will always be a playback stream, an optional second will always be a capture stream. Adding more will cycle stream directions from playback to capture. + * ``chmaps`` number of channel maps (Unimplemented). + +All streams are stereo and have the default channel positions ``Front left, right``. + +Examples +-------- + +Add an audio device and an audio backend at once with ``-audio`` and ``model=virtio``: + + * pulseaudio: ``-audio driver=pa,model=virtio`` + or ``-audio driver=pa,model=virtio,server=/run/user/1000/pulse/native`` + * sdl: ``-audio driver=sdl,model=virtio`` + * coreaudio: ``-audio driver=coreaudio,model=virtio`` + +etc. + +To specifically add virtualized sound devices, you have to specify a PCI device +and an audio backend listed with ``-audio driver=help`` that works on your host +machine, e.g.: + +:: + + -device virtio-sound-pci,audiodev=my_audiodev \ + -audiodev alsa,id=my_audiodev
This commit adds basic documentation for using virtio-snd. Signed-off-by: Emmanouil Pitsidianakis <manos.pitsidianakis@linaro.org> --- docs/system/device-emulation.rst | 1 + docs/system/devices/virtio-snd.rst | 49 ++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+) create mode 100644 docs/system/devices/virtio-snd.rst