Document preloaded disposables

For: QubesOS/qubes-issues#1512

Author: ben-grande

doc/manpages/qvm-features.rst

@@ -105,7 +105,7 @@ boot-mode.name.\*
 
 The user-visible pretty name for a boot mode. The ID of the boot mode with the
 given pretty name is specified by the last dot-separated word in the feature
-key, while the pretty name is specified by the feature value. 
+key, while the pretty name is specified by the feature value.
 
 gui
 ^^^
@@ -184,8 +184,8 @@ internal
 
 Internal qubes (with this feature set to :py:obj:`True`) are not included in the
 menu, not available in GUI tools (e.g in Global Settings as a default net qube)
-and generally hidden from normal usage. It is not recommended to set this
-feature manually.
+and generally hidden from normal usage (including not showing as a Qrexec target
+for `Ask` rules. It is not recommended to set this feature manually.
 
 Default: not internal VM
 
@@ -422,6 +422,46 @@ calls. Feature value could contain the rationale for the start ban.
 Note: `prohibit-start` for a TemplateVM does not forbid start of AppVMs based
 on it.
 
+preload-dispvm-max
+^^^^^^^^^^^^^^^^^^
+
+Number of disposables to preload, accepts only integers. Only evaluated when set
+on a disposable template.
+
+When set, it will adjust the number of running preloaded disposables to match
+the maximum configured, if there is not enough preloaded disposables, new ones
+will be started, if there are more than enough, the excess will be removed.
+
+There are some cases where a new disposable won't be preloaded, such as when a
+preloaded disposable is killed before being used or when the amount of available
+memory on the system is less than enough to preload a new disposable, it will
+skip creation. It is possible to resume from this state by setting this feature
+again to the same value and it will try to preload the difference.
+
+Default: `0`
+
+preload-dispvm
+^^^^^^^^^^^^^^
+
+Space separated list of preloaded disposables of a disposable template. This
+feature is set automatically after `preload-dispvm-max`, thus not intended to be
+modified manually. Preloaded disposables are disposables that start and run in
+the background waiting for use, when requesting a fresh disposable, there is no
+waiting time for the qube to start.
+
+Preloaded disposables have its GUI applications entries hidden and are paused to
+avoid user mistakes, as it is not intended to use them directly. To use them,
+target the disposable template to start a service in a disposable, instead of
+creating a new disposable, calls will be redirected to the preloaded disposable.
+As soon as the preloaded disposable is requested to be used, it is removed from
+the `preload-dispvm` list, GUI applications entries become visible, followed by
+a new disposable being preloaded.
+
+.. warning::
+
+   Applications configured to autostart by the disposable template or the
+   template itself will be shown before the preloaded disposable can be paused.
+
 custom-persist.*
 ^^^^^^^^^^^^^^^^