1.\" $OpenBSD: ldom.conf.5,v 1.18 2022/10/06 21:35:52 kn Exp $ 2.\" 3.\" Copyright (c) 2012 Mark Kettenis <kettenis@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: October 6 2022 $ 18.Dt LDOM.CONF 5 sparc64 19.Os 20.Sh NAME 21.Nm ldom.conf 22.Nd Logical Domain configuration 23.Sh DESCRIPTION 24.Nm 25is the configuration file to configure logical domains. 26.Pp 27Domains are defined in the following format: 28.Bl -tag -width Ds 29.It Ic domain Ar name Brq ... 30Declare a scope for resources assigned to the specified domain. 31The scope must be opened and closed with curly braces and contains 32one or more of the following keywords, each on a separate line. 33A scope with 34.Ar name 35.Dq primary 36configures resources for the primary domain. 37If no configuration for the primary domain exists, it is assigned 38all CPU and memory resources not used by any guest domains. 39.It Ic vcpu Ar number Ns Op : Ns Ar stride 40Declare the number of virtual CPUs assigned to a domain. 41Optionally a stride can be specified to allocate 42.Ar stride 43VCPUs at a time but assign only 44.Ar number 45VCPUs to the domain. 46This can be used to distribute virtual CPUs over the available CPU cores. 47.It Ic memory Ar bytes 48Declare the amount of memory assigned to a domain, in bytes. 49.Ar bytes 50can be specified with a human-readable scale, using the format described in 51.Xr scan_scaled 3 , 52e.g. 512M. 53.It Ic iodevice Ar device 54Assign the specified PCIe device to the guest domain. 55.Ar device 56may be either a device path 57.Pq Pa /@400/@2/@0/@8 58or a pseudonym 59.Pq Pa /SYS/MB/PCIE0 . 60This keyword can be used multiple times. 61.It Ic variable Ar name Ns = Ns Ar value 62Set the specified NVRAM variable for the domain. 63See 64.Xr eeprom 8 65for a list of OpenPROM variables. 66This keyword can be used multiple times. 67.It Ic vdisk Ar file Op Ar keyword Ns = Ns Ar value ... 68The specified file is used to back a virtual disk of the guest 69domain. 70.Ar file 71can be a block device node or a disk image file created with the 72.Cm create-vdisk 73command. 74This keyword can be used multiple times. 75Unless 76.Ar boot-device 77is set with the 78.Cm variable 79command, the first disk will be the default boot device. 80Valid options are: 81.Bl -tag -width Ds 82.It Ic devalias Ns = Ns Ar name 83Alias the virtual disk as 84.Ar name . 85.El 86.It Ic vnet Op Ar keyword Ns = Ns Ar value ... 87Assign a 88.Xr vnet 4 89network interface to the guest domain. 90This keyword can be used multiple times. 91Valid options are: 92.Bl -tag -width Ds 93.It Ic mac-addr Ns = Ns Ar address 94Configure the MAC address of the interface. 95.It Ic mtu Ns = Ns Ar number 96Configure the MTU of the interface. 97.It Ic devalias Ns = Ns Ar name 98Alias the interface as 99.Ar name . 100.El 101.El 102.Sh EXAMPLES 103Define a domain with 12 virtual cores, 4GB memory, two file based virtual disks 104and one virtual network interface: 105.Bd -literal -offset indent 106domain "puffy" { 107 vcpu 12 108 memory 4G 109 vdisk "/home/puffy/vdisk0" 110 vdisk "/home/puffy/vdisk1" 111 vnet 112} 113.Ed 114.Pp 115Define another one with slightly less resources: 116.Bd -literal -offset indent 117domain "salmah" { 118 vcpu 8 119 memory 2G 120 vdisk "/home/salmah/vdisk0" 121 vdisk "/home/salmah/vdisk1" 122 vnet 123} 124.Ed 125.Pp 126On a machine with 32 cores and 64GB physical memory, this leaves 12 cores and 12758GB memory to the primary domain. 128.Pp 129Use a 130.Ar stride 131step size to distribute VCPUs: 132.Bd -literal -offset indent 133domain "marlus" { 134 vcpu 2:4 135 memory 4G 136 vdisk "/home/marlus/vdisk0" 137} 138.Ed 139.Pp 140On a machine with eight threads per physical core, this allocates two strides 141of four VCPUs each for the guest domain but assigns only two VCPUs to it, i.e.\& 142makes it occupy an entire physical core while running on two threads only. 143.Sh SEE ALSO 144.Xr eeprom 8 , 145.Xr ldomctl 8 , 146.Xr ldomd 8 147.Sh BUGS 148The hypervisor requires a machine dependent amount of physical memory that is 149reserved automatically. 150Although the Physical Resource Inventory 151.Pq PRI 152seems to account for this by presenting less available memory, using the entire 153amount via 154.Ic memory 155is not always successful, e.g. the hypervisor would reject the configuration and 156fallback to 157.Dq factory-default 158upon resetting the machine. 159.Pp 160If in doubt, assign 161.Ic memory 162to the 163.Dq primary 164.Ic domain 165explicitly, 166such that enough memory remains unused for the hypervisor to reserve. 167On T4 based machines, 1024 megabytes has proven to suffice. 168