libvirt/docs/schemas/capability.rng

522 lines
12 KiB
Plaintext
Raw Normal View History

<?xml version="1.0"?>
<!-- A Relax NG schema for the libvirt capabilities XML format -->
<grammar xmlns="http://relaxng.org/ns/structure/1.0"
datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
<include href='basictypes.rng'/>
<start>
<ref name='capabilities'/>
</start>
<define name='capabilities'>
<element name='capabilities'>
<ref name='hostcaps'/>
<zeroOrMore>
<ref name='guestcaps'/>
</zeroOrMore>
</element>
</define>
<define name='hostcaps'>
<element name='host'>
<optional>
<element name='uuid'>
<ref name='UUID'/>
</element>
</optional>
<element name='cpu'>
<element name='arch'>
<ref name='archnames'/>
</element>
<optional>
<ref name='cpufeatures'/>
</optional>
<optional>
<ref name='cpuspec'/>
</optional>
</element>
<optional>
<ref name='power_management'/>
</optional>
<optional>
<ref name='iommu_support'/>
</optional>
<optional>
<ref name='migration'/>
</optional>
<optional>
<ref name='topology'/>
</optional>
<optional>
<ref name='cache'/>
</optional>
<zeroOrMore>
<ref name='secmodel'/>
</zeroOrMore>
</element>
</define>
<define name='secmodel'>
<element name='secmodel'>
<interleave>
<element name='model'>
<text/>
</element>
<element name='doi'>
<text/>
</element>
<zeroOrMore>
<element name='baselabel'>
<attribute name='type'>
<text/>
</attribute>
<text/>
</element>
</zeroOrMore>
</interleave>
</element>
</define>
<define name='cpufeatures'>
<element name='features'>
<optional>
<element name='pae'><empty/></element>
</optional>
<optional>
<element name='nonpae'><empty/></element>
</optional>
<optional>
<element name='vmx'><empty/></element>
</optional>
<optional>
<element name='svm'><empty/></element>
</optional>
</element>
</define>
XML schema for CPU flags XML schema for CPU flags Firstly, CPU topology and model with optional features have to be advertised in host capabilities: <host> <cpu> <arch>ARCHITECTURE</arch> <features> <!-- old-style features are here --> </features> <model>NAME</model> <topology sockets="S" cores="C" threads="T"/> <feature name="NAME"/> </cpu> ... </host> Secondly, drivers which support detailed CPU specification have to advertise it in guest capabilities: <guest> ... <features> <cpuselection/> </features> </guest> And finally, CPU may be configured in domain XML configuration: <domain> ... <cpu match="MATCH"> <model>NAME</model> <topology sockets="S" cores="C" threads="T"/> <feature policy="POLICY" name="NAME"/> </cpu> </domain> Where MATCH can be one of: - 'minimum' specified CPU is the minimum requested CPU - 'exact' disable all additional features provided by host CPU - 'strict' fail if host CPU doesn't exactly match POLICY can be one of: - 'force' turn on the feature, even if host doesn't have it - 'require' fail if host doesn't have the feature - 'optional' match host - 'disable' turn off the feature, even if host has it - 'forbid' fail if host has the feature 'force' and 'disable' policies turn on/off the feature regardless of its availability on host. 'force' is unlikely to be used but its there for completeness since Xen and VMWare allow it. 'require' and 'forbid' policies prevent a guest from being started on a host which doesn't/does have the feature. 'forbid' is for cases where you disable the feature but a guest may still try to access it anyway and you don't want it to succeed. 'optional' policy sets the feature according to its availability on host. When a guest is booted on a host that has the feature and then migrated to another host, the policy changes to 'require' as we can't take the feature away from a running guest. Default policy for features provided by host CPU but not specified in domain configuration is set using match attribute of cpu tag. If 'minimum' match is requested, additional features will be treated as if they were specified with 'optional' policy. 'exact' match implies 'disable' policy and 'strict' match stands for 'forbid' policy. * docs/schemas/capability.rng docs/schemas/domain.rng: extend the RelaxNG schemas to add CPU flags support
2009-12-18 13:37:09 +00:00
<define name='cpuspec'>
<element name='model'>
<text/>
</element>
<optional>
<element name='vendor'>
<text/>
</element>
</optional>
<optional>
<element name='microcode'>
<attribute name='version'>
<ref name='positiveInteger'/>
</attribute>
</element>
</optional>
XML schema for CPU flags XML schema for CPU flags Firstly, CPU topology and model with optional features have to be advertised in host capabilities: <host> <cpu> <arch>ARCHITECTURE</arch> <features> <!-- old-style features are here --> </features> <model>NAME</model> <topology sockets="S" cores="C" threads="T"/> <feature name="NAME"/> </cpu> ... </host> Secondly, drivers which support detailed CPU specification have to advertise it in guest capabilities: <guest> ... <features> <cpuselection/> </features> </guest> And finally, CPU may be configured in domain XML configuration: <domain> ... <cpu match="MATCH"> <model>NAME</model> <topology sockets="S" cores="C" threads="T"/> <feature policy="POLICY" name="NAME"/> </cpu> </domain> Where MATCH can be one of: - 'minimum' specified CPU is the minimum requested CPU - 'exact' disable all additional features provided by host CPU - 'strict' fail if host CPU doesn't exactly match POLICY can be one of: - 'force' turn on the feature, even if host doesn't have it - 'require' fail if host doesn't have the feature - 'optional' match host - 'disable' turn off the feature, even if host has it - 'forbid' fail if host has the feature 'force' and 'disable' policies turn on/off the feature regardless of its availability on host. 'force' is unlikely to be used but its there for completeness since Xen and VMWare allow it. 'require' and 'forbid' policies prevent a guest from being started on a host which doesn't/does have the feature. 'forbid' is for cases where you disable the feature but a guest may still try to access it anyway and you don't want it to succeed. 'optional' policy sets the feature according to its availability on host. When a guest is booted on a host that has the feature and then migrated to another host, the policy changes to 'require' as we can't take the feature away from a running guest. Default policy for features provided by host CPU but not specified in domain configuration is set using match attribute of cpu tag. If 'minimum' match is requested, additional features will be treated as if they were specified with 'optional' policy. 'exact' match implies 'disable' policy and 'strict' match stands for 'forbid' policy. * docs/schemas/capability.rng docs/schemas/domain.rng: extend the RelaxNG schemas to add CPU flags support
2009-12-18 13:37:09 +00:00
<element name='topology'>
<attribute name='sockets'>
<ref name='positiveInteger'/>
</attribute>
<attribute name='cores'>
<ref name='positiveInteger'/>
</attribute>
<attribute name='threads'>
<ref name='positiveInteger'/>
</attribute>
</element>
<zeroOrMore>
<element name='feature'>
<attribute name='name'>
<ref name='featureName'/>
</attribute>
<empty/>
</element>
</zeroOrMore>
<zeroOrMore>
<ref name='pagesHost'/>
</zeroOrMore>
XML schema for CPU flags XML schema for CPU flags Firstly, CPU topology and model with optional features have to be advertised in host capabilities: <host> <cpu> <arch>ARCHITECTURE</arch> <features> <!-- old-style features are here --> </features> <model>NAME</model> <topology sockets="S" cores="C" threads="T"/> <feature name="NAME"/> </cpu> ... </host> Secondly, drivers which support detailed CPU specification have to advertise it in guest capabilities: <guest> ... <features> <cpuselection/> </features> </guest> And finally, CPU may be configured in domain XML configuration: <domain> ... <cpu match="MATCH"> <model>NAME</model> <topology sockets="S" cores="C" threads="T"/> <feature policy="POLICY" name="NAME"/> </cpu> </domain> Where MATCH can be one of: - 'minimum' specified CPU is the minimum requested CPU - 'exact' disable all additional features provided by host CPU - 'strict' fail if host CPU doesn't exactly match POLICY can be one of: - 'force' turn on the feature, even if host doesn't have it - 'require' fail if host doesn't have the feature - 'optional' match host - 'disable' turn off the feature, even if host has it - 'forbid' fail if host has the feature 'force' and 'disable' policies turn on/off the feature regardless of its availability on host. 'force' is unlikely to be used but its there for completeness since Xen and VMWare allow it. 'require' and 'forbid' policies prevent a guest from being started on a host which doesn't/does have the feature. 'forbid' is for cases where you disable the feature but a guest may still try to access it anyway and you don't want it to succeed. 'optional' policy sets the feature according to its availability on host. When a guest is booted on a host that has the feature and then migrated to another host, the policy changes to 'require' as we can't take the feature away from a running guest. Default policy for features provided by host CPU but not specified in domain configuration is set using match attribute of cpu tag. If 'minimum' match is requested, additional features will be treated as if they were specified with 'optional' policy. 'exact' match implies 'disable' policy and 'strict' match stands for 'forbid' policy. * docs/schemas/capability.rng docs/schemas/domain.rng: extend the RelaxNG schemas to add CPU flags support
2009-12-18 13:37:09 +00:00
</define>
<define name='power_management'>
<element name='power_management'>
<interleave>
<optional>
<element name='suspend_mem'>
<empty/>
</element>
</optional>
<optional>
<element name='suspend_disk'>
<empty/>
</element>
</optional>
<optional>
<element name='suspend_hybrid'>
<empty/>
</element>
</optional>
</interleave>
</element>
</define>
<define name='iommu_support'>
<element name='iommu'>
<optional>
<attribute name='support'>
<ref name='virYesNo'/>
</attribute>
</optional>
</element>
</define>
<define name='migration'>
<element name='migration_features'>
<optional>
<element name='live'>
<empty/>
</element>
</optional>
<optional>
<element name='uri_transports'>
<oneOrMore>
<element name='uri_transport'>
<choice>
<value>vpxmigr</value>
<value>tcp</value>
<value>rdma</value>
<value>vzmigr</value>
</choice>
</element>
</oneOrMore>
</element>
</optional>
</element>
</define>
<define name='topology'>
<element name='topology'>
<element name='cells'>
<attribute name='num'>
<ref name='unsignedInt'/>
</attribute>
<oneOrMore>
<ref name='cell'/>
</oneOrMore>
</element>
</element>
</define>
<define name='cell'>
<element name='cell'>
<attribute name='id'>
<ref name='unsignedInt'/>
</attribute>
<optional>
<ref name='memory'/>
</optional>
<zeroOrMore>
<ref name='pagesNuma'/>
</zeroOrMore>
<optional>
<element name='distances'>
<zeroOrMore>
<element name='sibling'>
<attribute name='id'>
<ref name='unsignedInt'/>
</attribute>
<attribute name='value'>
<ref name='unsignedInt'/>
</attribute>
</element>
</zeroOrMore>
</element>
</optional>
<optional>
<element name='cpus'>
<attribute name='num'>
<ref name='unsignedInt'/>
</attribute>
<oneOrMore>
<ref name='cpu'/>
</oneOrMore>
</element>
</optional>
</element>
</define>
<define name='memory'>
<element name='memory'>
<ref name='scaledInteger'/>
</element>
</define>
<define name='cpu'>
<element name='cpu'>
<attribute name='id'>
<ref name='unsignedInt'/>
</attribute>
schemas: Add schemas for more CPU topology information in the caps XML This patch adds RNG schemas for adding more information in the topology output of the NUMA section in the capabilities XML. The added elements are designed to provide more information about the placement and topology of the processors in the system to management applications. A demonstration of supported XML added by this patch: <capabilities> <host> <topology> <cells num='3'> <cell id='0'> <cpus num='4'> <!-- this is node with Hyperthreading --> <cpu id='0' socket_id='0' core_id='0' siblings='0-1'/> <cpu id='1' socket_id='0' core_id='0' siblings='0-1'/> <cpu id='2' socket_id='0' core_id='1' siblings='2-3'/> <cpu id='3' socket_id='0' core_id='1' siblings='2-3'/> </cpus> </cell> <cell id='1'> <cpus num='4'> <!-- this is node with modules (Bulldozer) --> <cpu id='4' socket_id='0' core_id='2' siblings='4-5'/> <cpu id='5' socket_id='0' core_id='3' siblings='4-5'/> <cpu id='6' socket_id='0' core_id='4' siblings='6-7'/> <cpu id='7' socket_id='0' core_id='5' siblings='6-7'/> </cpus> </cell> <cell id='2'> <cpus num='4'> <!-- this is a normal multi-core node --> <cpu id='8' socket_id='1' core_id='0' siblings='8'/> <cpu id='9' socket_id='1' core_id='1' siblings='9'/> <cpu id='10' socket_id='1' core_id='2' siblings='10'/> <cpu id='11' socket_id='1' core_id='3' siblings='11'/> </cpus> </cell> </cells> </topology> </host> </capabilities> The socket_id field represents identification of the physical socket the CPU is plugged in. This ID may not be identical to the physical socket ID reported by the kernel. The core_id identifies a core within a socket. Also this field may not accurately represent physical ID's. The core_id is guaranteed to be unique within a cell and a socket. There may be duplicates between sockets. Only cores sharing core_id within one cell and one socket can be considered as threads. Cores sharing core_id within sparate cells are distinct cores. The siblings field is a list of CPU id's the cpu id's the CPU is sibling with - thus a thread. The list is in the cpuset format.
2013-01-18 18:30:00 +00:00
<optional>
<attribute name='socket_id'>
<ref name='unsignedInt'/>
</attribute>
<attribute name='core_id'>
<ref name='unsignedInt'/>
</attribute>
<attribute name='siblings'>
<ref name='cpuset'/>
</attribute>
</optional>
</element>
</define>
<define name='cache'>
<element name='cache'>
<oneOrMore>
<element name='bank'>
<attribute name='id'>
<ref name='unsignedInt'/>
</attribute>
<attribute name='level'>
<ref name='unsignedInt'/>
</attribute>
<ref name='cacheType'/>
<attribute name='size'>
<ref name='unsignedInt'/>
</attribute>
<attribute name='unit'>
<ref name='unit'/>
</attribute>
<attribute name='cpus'>
<ref name='cpuset'/>
</attribute>
<zeroOrMore>
<element name='control'>
<attribute name='granularity'>
<ref name='unsignedInt'/>
</attribute>
<optional>
<attribute name='min'>
<ref name='unsignedInt'/>
</attribute>
</optional>
<attribute name='unit'>
<ref name='unit'/>
</attribute>
<ref name='cacheType'/>
<attribute name='maxAllocs'>
<ref name='unsignedInt'/>
</attribute>
</element>
</zeroOrMore>
</element>
</oneOrMore>
</element>
</define>
<define name='cacheType'>
<attribute name='type'>
<choice>
<value>both</value>
<value>code</value>
<value>data</value>
</choice>
</attribute>
</define>
<define name='guestcaps'>
<element name='guest'>
<ref name='ostype'/>
<ref name='arch'/>
<optional>
<ref name='features'/>
</optional>
</element>
</define>
<define name='ostype'>
<element name='os_type'>
<choice>
<value>xen</value> <!-- Xen 3.0 pv -->
<value>linux</value> <!-- same as 'xen' - meant to be legacy,
but is also used by phyp driver -->
<value>hvm</value> <!-- unmodified OS -->
<value>exe</value> <!-- For container based virt -->
<value>uml</value> <!-- user mode linux -->
</choice>
</element>
</define>
<define name='arch'>
<element name='arch'>
<attribute name='name'>
<ref name='archnames'/>
</attribute>
<ref name='wordsize'/>
<optional>
<ref name='emulator'/>
</optional>
<optional>
<ref name='loader'/>
</optional>
<zeroOrMore>
<ref name='machine'/>
</zeroOrMore>
<oneOrMore>
<ref name='domain'/>
</oneOrMore>
</element>
</define>
<define name='emulator'>
<element name='emulator'>
<ref name='absFilePath'/>
</element>
</define>
<define name='loader'>
<element name='loader'>
<ref name='absFilePath'/>
</element>
</define>
<define name='wordsize'>
<element name='wordsize'>
<choice>
<value>31</value>
<value>32</value>
<value>64</value>
</choice>
</element>
</define>
<define name='machine'>
<element name='machine'>
<optional>
<attribute name='canonical'>
<text/>
</attribute>
</optional>
<optional>
<attribute name='maxCpus'>
<ref name='unsignedInt'/>
</attribute>
</optional>
<text/>
</element>
</define>
<define name='domain'>
<element name='domain'>
<attribute name='type'>
<choice>
<value>qemu</value>
<value>kqemu</value>
<value>kvm</value>
<value>xen</value>
<value>uml</value>
<value>lxc</value>
<value>openvz</value>
<value>test</value>
</choice>
</attribute>
<optional>
<ref name='emulator'/>
</optional>
<zeroOrMore>
<ref name='machine'/>
</zeroOrMore>
</element>
</define>
<define name='features'>
<element name='features'>
<interleave>
<optional>
<element name='pae'>
<empty/>
</element>
</optional>
<optional>
<element name='nonpae'>
<empty/>
</element>
</optional>
<optional>
<element name='ia64_be'>
<empty/>
</element>
</optional>
<optional>
<element name='acpi'>
<ref name='featuretoggle'/>
<empty/>
</element>
</optional>
<optional>
<element name='apic'>
<ref name='featuretoggle'/>
<empty/>
</element>
</optional>
<optional>
<element name='cpuselection'>
<empty/>
</element>
</optional>
<optional>
<element name='deviceboot'>
<empty/>
</element>
</optional>
<optional>
<element name='disksnapshot'>
<ref name='featuretoggle'/>
<empty/>
</element>
</optional>
</interleave>
</element>
</define>
<define name='featuretoggle'>
<attribute name='toggle'>
<ref name="virYesNo"/>
</attribute>
<attribute name='default'>
<ref name="virOnOff"/>
</attribute>
</define>
XML schema for CPU flags XML schema for CPU flags Firstly, CPU topology and model with optional features have to be advertised in host capabilities: <host> <cpu> <arch>ARCHITECTURE</arch> <features> <!-- old-style features are here --> </features> <model>NAME</model> <topology sockets="S" cores="C" threads="T"/> <feature name="NAME"/> </cpu> ... </host> Secondly, drivers which support detailed CPU specification have to advertise it in guest capabilities: <guest> ... <features> <cpuselection/> </features> </guest> And finally, CPU may be configured in domain XML configuration: <domain> ... <cpu match="MATCH"> <model>NAME</model> <topology sockets="S" cores="C" threads="T"/> <feature policy="POLICY" name="NAME"/> </cpu> </domain> Where MATCH can be one of: - 'minimum' specified CPU is the minimum requested CPU - 'exact' disable all additional features provided by host CPU - 'strict' fail if host CPU doesn't exactly match POLICY can be one of: - 'force' turn on the feature, even if host doesn't have it - 'require' fail if host doesn't have the feature - 'optional' match host - 'disable' turn off the feature, even if host has it - 'forbid' fail if host has the feature 'force' and 'disable' policies turn on/off the feature regardless of its availability on host. 'force' is unlikely to be used but its there for completeness since Xen and VMWare allow it. 'require' and 'forbid' policies prevent a guest from being started on a host which doesn't/does have the feature. 'forbid' is for cases where you disable the feature but a guest may still try to access it anyway and you don't want it to succeed. 'optional' policy sets the feature according to its availability on host. When a guest is booted on a host that has the feature and then migrated to another host, the policy changes to 'require' as we can't take the feature away from a running guest. Default policy for features provided by host CPU but not specified in domain configuration is set using match attribute of cpu tag. If 'minimum' match is requested, additional features will be treated as if they were specified with 'optional' policy. 'exact' match implies 'disable' policy and 'strict' match stands for 'forbid' policy. * docs/schemas/capability.rng docs/schemas/domain.rng: extend the RelaxNG schemas to add CPU flags support
2009-12-18 13:37:09 +00:00
<define name='featureName'>
<data type='string'>
<param name='pattern'>[a-zA-Z0-9\-_]+</param>
</data>
</define>
<define name='pagesHost'>
<element name='pages'>
<ref name='pagesElem'/>
</element>
</define>
<define name='pagesNuma'>
<element name='pages'>
<ref name='pagesElem'/>
<ref name='unsignedInt'/>
</element>
</define>
<define name='pagesElem'>
<optional>
<attribute name='unit'>
<ref name='unit'/>
</attribute>
</optional>
<attribute name='size'>
<ref name='unsignedInt'/>
</attribute>
</define>
</grammar>