Move configuration format into ldom.conf(5)

ldomctl(8) contains the entire format describing logical domain
configurations loaded with that tool.  Entangle control commands and config
options by putting the latter into its own page.

The config options' descriptions stayed the same, only the EXAMPLE section
gained a bit wording.

Convert mdoc(7) macros `Ic =' to `Ns = Ns' and `Ic \&{ ... Ic \&}' to
`Brq ...' while here.

More improvements will follow in-tree.

OK deraadt

4 files changed, 108 insertions, 68 deletions

diff --git a/usr.sbin/ldomctl/ldomctl.8 b/usr.sbin/ldomctl/ldomctl.8
index 2ed0e4a327c..c921e4bfe5c 100644
--- a/usr.sbin/ldomctl/ldomctl.8
+++ b/usr.sbin/ldomctl/ldomctl.8
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: ldomctl.8,v 1.11 2018/09/16 14:27:32 kettenis Exp $
+.\"     $OpenBSD: ldomctl.8,v 1.12 2019/07/27 09:55:46 kn Exp $
 .\"
 .\" Copyright (c) 2012 Mark Kettenis <kettenis@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: September 16 2018 $
+.Dd $Mdocdate: July 27 2019 $
 .Dt LDOMCTL 8 sparc64
 .Os
 .Sh NAME
@@ -50,50 +50,11 @@ The download is aborted if a configuration with the same name already exists.
 Dump the current configuration from non-volatile storage into the current
 working directory.
 .It Cm init-system Ar file
-Generates files describing a logical domain configuration.
-The generated files are written to the current working directory.
-The provided
+Generate files in the current working directory for a logical domain
+configuration
 .Ar file
-describes resources assigned to logical domains in a plain text format
-with the following syntax:
-.Bl -tag -width Ds
-.It Ic domain Ar name Ic \&{ Ar resource ... Ic \&}
-Declares a scope for resources assigned to the specified domain.
-The scope must be opened and closed with curly braces and contains
-one or more of the following keywords, each on a separate line.
-A scope with
-.Ar name
-"primary" configures resources for the primary domain.
-If no configuration for the primary domain exists it is assigned
-all CPU and memory resources not used by any guest domains.
-.It Ic vcpu Ar number
-Declares the number of virtual CPUs assigned to a domain.
-.It Ic memory Ar number Ns Op Ar unit
-Declares the amount of memory assigned to a domain, in bytes.
-Optionally, the units 'K', 'M', or 'G', for kilo-, mega-, and gigabytes
-can be used.
-.It Ic variable Ar name Ic = Ar value
-Sets the specified NVRAM variable for the domain.
-.It Ic vdisk Ar file
-The specified file is used to back a virtual disk of the guest
-domain.
-.Ar file
-can be a block device node or a disk image file created with
-.Xr dd 1 .
-This keyword can be used multiple times.
-.It Ic vnet Op Ic \&{ Ar keyword Ic = Ar value ... Ic \&}
-Assign a
-.Xr vnet 4
-network interface to the guest domain.
-This keyword can be used multiple times.
-The curly braces are optional and can contain the following keywords:
-.Bl -tag -width Ds
-.It Ic mac-addr Ar address
-Configures the MAC address of the interface.
-.It Ic mtu Ar number
-Configures the MTU of the interface.
-.El
-.El
+as described in
+.Xr ldom.conf 5 .
 .It Cm list
 List configurations stored in non-volatile storage.
 Indicate the currently running configuration,
@@ -135,25 +96,8 @@ Create a new configuration based on the defaults:
 # cd openbsd
 .Ed
 .Pp
-A file describing the desired configuration must be created:
-.Bd -literal -offset indent
-# cat ldom.conf
-domain puffy {
-	vcpu 12
-	memory 4G
-	vdisk "/home/puffy/vdisk0"
-	vdisk "/home/puffy/vdisk1"
-	vnet
-}
-
-domain salmah {
-	vcpu 8
-	memory 2G
-	vdisk "/home/salmah/vdisk0"
-	vdisk "/home/salmah/vdisk1"
-	vnet
-}
-.Ed
+A file describing the desired configuration must be created, see
+Xr. ldom.conf 5 .
 .Pp
 Generate a set of configuration files and download to non-volatile storage.
 If a configuration with the same name already exists, it must be removed first:
@@ -223,6 +167,7 @@ ok boot disk1
 .Xr dd 1 ,
 .Xr ddb 4 ,
 .Xr vnet 4 ,
+.Xr ldom.conf 5 ,
 .Xr ldomd 8
 .Sh HISTORY
 The
diff --git a/usr.sbin/ldomd/Makefile b/usr.sbin/ldomd/Makefile
index ac48ed8669b..8a182189b06 100644
--- a/usr.sbin/ldomd/Makefile
+++ b/usr.sbin/ldomd/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.3 2012/10/27 20:03:24 kettenis Exp $
+#	$OpenBSD: Makefile,v 1.4 2019/07/27 09:55:46 kn Exp $
 
 .if ${MACHINE} == "sparc64"
 
@@ -16,7 +16,7 @@ NOPROG=	yes
 
 .endif
 
-MAN=	ldomd.8
+MAN=	ldomd.8 ldom.conf.5
 MANSUBDIR=sparc64
 
 .include <bsd.prog.mk>
diff --git a/usr.sbin/ldomd/ldom.conf.5 b/usr.sbin/ldomd/ldom.conf.5
new file mode 100644
index 00000000000..6ce1f628b9b
--- /dev/null
+++ b/usr.sbin/ldomd/ldom.conf.5
@@ -0,0 +1,94 @@
+.\" $OpenBSD: ldom.conf.5,v 1.1 2019/07/27 09:55:46 kn Exp $
+.\"
+.\" Copyright (c) 2012 Mark Kettenis <kettenis@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: July 27 2019 $
+.Dt LDOM.CONF 5 sparc64
+.Os
+.Sh NAME
+.Nm ldom.conf
+.Nd Logical Domain configuration
+.Sh DESCRIPTION
+.Nm
+is the configuration file to configure logical domains.
+.Pp
+Domains are defined in following format:
+.Bl -tag -width Ds
+.It Ic domain Ar name Brq ...
+Declares a scope for resources assigned to the specified domain.
+The scope must be opened and closed with curly braces and contains
+one or more of the following keywords, each on a separate line.
+A scope with
+.Ar name
+"primary" configures resources for the primary domain.
+If no configuration for the primary domain exists it is assigned
+all CPU and memory resources not used by any guest domains.
+.It Ic vcpu Ar number
+Declares the number of virtual CPUs assigned to a domain.
+.It Ic memory Ar number Ns Op Ar unit
+Declares the amount of memory assigned to a domain, in bytes.
+Optionally, the units 'K', 'M', or 'G', for kilo-, mega-, and gigabytes
+can be used.
+.It Ic variable Ar name Ns = Ns Ar value
+Sets the specified NVRAM variable for the domain.
+.It Ic vdisk Ar file
+The specified file is used to back a virtual disk of the guest
+domain.
+.Ar file
+can be a block device node or a disk image file created with
+.Xr dd 1 .
+This keyword can be used multiple times.
+.It Ic vnet Op Brq Ar keyword Ns = Ns Ar value ...
+Assign a
+.Xr vnet 4
+network interface to the guest domain.
+This keyword can be used multiple times.
+The curly braces are optional and can contain the following keywords:
+.Bl -tag -width Ds
+.It Ic mac-addr Ar address
+Configures the MAC address of the interface.
+.It Ic mtu Ar number
+Configures the MTU of the interface.
+.El
+.El
+.Sh EXAMPLES
+Define a domain with 12 virtual cores, 1GB memory, two file based virtual disks
+and one virtual network interface:
+.Bd -literal -offset indent
+domain "puffy" {
+	vcpu 12
+	memory 4G
+	vdisk "/home/puffy/vdisk0"
+	vdisk "/home/puffy/vdisk1"
+	vnet
+}
+.Ed
+.Pp
+Define another one with slightly less resources:
+.Bd -literal -offset indent
+domain "salmah" {
+	vcpu 8
+	memory 2G
+	vdisk "/home/salmah/vdisk0"
+	vdisk "/home/salmah/vdisk1"
+	vnet
+}
+.Ed
+.Pp
+On a machine with 32 cores and 64GB physical memory, this leaves 12 cores and
+58GB memory to the primary domain.
+.Sh SEE ALSO
+.Xr ldomctl 8 ,
+.Xr ldomd 8
diff --git a/usr.sbin/ldomd/ldomd.8 b/usr.sbin/ldomd/ldomd.8
index e622e4c755e..d6b36bf2f4a 100644
--- a/usr.sbin/ldomd/ldomd.8
+++ b/usr.sbin/ldomd/ldomd.8
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: ldomd.8,v 1.5 2019/07/11 05:42:41 jmc Exp $
+.\"     $OpenBSD: ldomd.8,v 1.6 2019/07/27 09:55:46 kn Exp $
 .\"
 .\" Copyright (c) 2012 Mark Kettenis <kettenis@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: July 11 2019 $
+.Dd $Mdocdate: July 27 2019 $
 .Dt LDOMD 8 sparc64
 .Os
 .Sh NAME
@@ -43,6 +43,7 @@ will run in the foreground and log to
 .El
 .Sh SEE ALSO
 .Xr vldc 4 ,
+.Xr ldom.conf 5 ,
 .Xr ldomctl 8
 .Sh HISTORY
 The