15a61ef74SNicholas Piggin*** NOTE *** 25a61ef74SNicholas PigginThis document is copied from OPAL firmware 35a61ef74SNicholas Piggin(skiboot/doc/device-tree/ibm,powerpc-cpu-features/binding.txt) 45a61ef74SNicholas Piggin 55a61ef74SNicholas PigginThere is more complete overview and documentation of features in that 65a61ef74SNicholas Pigginsource tree. All patches and modifications should go there. 75a61ef74SNicholas Piggin************ 85a61ef74SNicholas Piggin 95a61ef74SNicholas Pigginibm,powerpc-cpu-features binding 105a61ef74SNicholas Piggin================================ 115a61ef74SNicholas Piggin 125a61ef74SNicholas PigginThis device tree binding describes CPU features available to software, with 135a61ef74SNicholas Pigginenablement, privilege, and compatibility metadata. 145a61ef74SNicholas Piggin 155a61ef74SNicholas PigginMore general description of design and implementation of this binding is 165a61ef74SNicholas Pigginfound in design.txt, which also points to documentation of specific features. 175a61ef74SNicholas Piggin 185a61ef74SNicholas Piggin 195a61ef74SNicholas Piggin/cpus/ibm,powerpc-cpu-features node binding 205a61ef74SNicholas Piggin------------------------------------------- 215a61ef74SNicholas Piggin 225a61ef74SNicholas PigginNode: ibm,powerpc-cpu-features 235a61ef74SNicholas Piggin 245a61ef74SNicholas PigginDescription: Container of CPU feature nodes. 255a61ef74SNicholas Piggin 265a61ef74SNicholas PigginThe node name must be "ibm,powerpc-cpu-features". 275a61ef74SNicholas Piggin 285a61ef74SNicholas PigginIt is implemented as a child of the node "/cpus", but this must not be 295a61ef74SNicholas Pigginassumed by parsers. 305a61ef74SNicholas Piggin 315a61ef74SNicholas PigginThe node is optional but should be provided by new OPAL firmware. 325a61ef74SNicholas Piggin 335a61ef74SNicholas PigginProperties: 345a61ef74SNicholas Piggin 355a61ef74SNicholas Piggin- compatible 365a61ef74SNicholas Piggin Usage: required 375a61ef74SNicholas Piggin Value type: string 385a61ef74SNicholas Piggin Definition: "ibm,powerpc-cpu-features" 395a61ef74SNicholas Piggin 405a61ef74SNicholas Piggin This compatibility refers to backwards compatibility of the overall 415a61ef74SNicholas Piggin design with parsers that behave according to these guidelines. This can 425a61ef74SNicholas Piggin be extended in a backward compatible manner which would not warrant a 435a61ef74SNicholas Piggin revision of the compatible property. 445a61ef74SNicholas Piggin 455a61ef74SNicholas Piggin- isa 465a61ef74SNicholas Piggin Usage: required 475a61ef74SNicholas Piggin Value type: <u32> 485a61ef74SNicholas Piggin Definition: 495a61ef74SNicholas Piggin 505a61ef74SNicholas Piggin isa that the CPU is currently running in. This provides instruction set 515a61ef74SNicholas Piggin compatibility, less the individual feature nodes. For example, an ISA v3.0 525a61ef74SNicholas Piggin implementation that lacks the "transactional-memory" cpufeature node 535a61ef74SNicholas Piggin should not use transactional memory facilities. 545a61ef74SNicholas Piggin 555a61ef74SNicholas Piggin Value corresponds to the "Power ISA Version" multiplied by 1000. 565a61ef74SNicholas Piggin For example, <3000> corresponds to Version 3.0, <2070> to Version 2.07. 575a61ef74SNicholas Piggin The minor digit is available for revisions. 585a61ef74SNicholas Piggin 595a61ef74SNicholas Piggin- display-name 605a61ef74SNicholas Piggin Usage: optional 615a61ef74SNicholas Piggin Value type: string 625a61ef74SNicholas Piggin Definition: 635a61ef74SNicholas Piggin 645a61ef74SNicholas Piggin A human readable name for the CPU. 655a61ef74SNicholas Piggin 665a61ef74SNicholas Piggin/cpus/ibm,powerpc-cpu-features/example-feature node bindings 675a61ef74SNicholas Piggin---------------------------------------------------------------- 685a61ef74SNicholas Piggin 695a61ef74SNicholas PigginEach child node of cpu-features represents a CPU feature / capability. 705a61ef74SNicholas Piggin 715a61ef74SNicholas PigginNode: A string describing an architected CPU feature, e.g., "floating-point". 725a61ef74SNicholas Piggin 735a61ef74SNicholas PigginDescription: A feature or capability supported by the CPUs. 745a61ef74SNicholas Piggin 755a61ef74SNicholas PigginThe name of the node is a human readable string that forms the interface 765a61ef74SNicholas Pigginused to describe features to software. Features are currently documented 775a61ef74SNicholas Pigginin the code where they are implemented in skiboot/core/cpufeatures.c 785a61ef74SNicholas Piggin 795a61ef74SNicholas PigginPresence of the node indicates the feature is available. 805a61ef74SNicholas Piggin 815a61ef74SNicholas PigginProperties: 825a61ef74SNicholas Piggin 835a61ef74SNicholas Piggin- isa 845a61ef74SNicholas Piggin Usage: required 855a61ef74SNicholas Piggin Value type: <u32> 865a61ef74SNicholas Piggin Definition: 875a61ef74SNicholas Piggin 885a61ef74SNicholas Piggin First level of the Power ISA that the feature appears in. 895a61ef74SNicholas Piggin Software should filter out features when constraining the 905a61ef74SNicholas Piggin environment to a particular ISA version. 915a61ef74SNicholas Piggin 925a61ef74SNicholas Piggin Value is defined similarly to /cpus/features/isa 935a61ef74SNicholas Piggin 945a61ef74SNicholas Piggin- usable-privilege 955a61ef74SNicholas Piggin Usage: required 965a61ef74SNicholas Piggin Value type: <u32> bit mask 975a61ef74SNicholas Piggin Definition: 985a61ef74SNicholas Piggin Bit numbers are LSB0 995a61ef74SNicholas Piggin bit 0 - PR (problem state / user mode) 1005a61ef74SNicholas Piggin bit 1 - OS (privileged state) 1015a61ef74SNicholas Piggin bit 2 - HV (hypervisor state) 1025a61ef74SNicholas Piggin All other bits reserved and should be zero. 1035a61ef74SNicholas Piggin 1045a61ef74SNicholas Piggin This property describes the privilege levels and/or software components 1055a61ef74SNicholas Piggin that can use the feature. 1065a61ef74SNicholas Piggin 1075a61ef74SNicholas Piggin If bit 0 is set, then the hwcap-bit-nr property will exist. 1085a61ef74SNicholas Piggin 1095a61ef74SNicholas Piggin 1105a61ef74SNicholas Piggin- hv-support 1115a61ef74SNicholas Piggin Usage: optional 1125a61ef74SNicholas Piggin Value type: <u32> bit mask 1135a61ef74SNicholas Piggin Definition: 1145a61ef74SNicholas Piggin Bit numbers are LSB0 1155a61ef74SNicholas Piggin bit 0 - HFSCR 1165a61ef74SNicholas Piggin All other bits reserved and should be zero. 1175a61ef74SNicholas Piggin 1185a61ef74SNicholas Piggin This property describes the HV privilege support required to enable the 1195a61ef74SNicholas Piggin feature to lesser privilege levels. If the property does not exist then no 1205a61ef74SNicholas Piggin support is required. 1215a61ef74SNicholas Piggin 1225a61ef74SNicholas Piggin If no bits are set, the hypervisor must have explicit/custom support for 1235a61ef74SNicholas Piggin this feature. 1245a61ef74SNicholas Piggin 1255a61ef74SNicholas Piggin If the HFSCR bit is set, then the hfscr-bit-nr property will exist and 1265a61ef74SNicholas Piggin the feature may be enabled by setting this bit in the HFSCR register. 1275a61ef74SNicholas Piggin 1285a61ef74SNicholas Piggin 1295a61ef74SNicholas Piggin- os-support 1305a61ef74SNicholas Piggin Usage: optional 1315a61ef74SNicholas Piggin Value type: <u32> bit mask 1325a61ef74SNicholas Piggin Definition: 1335a61ef74SNicholas Piggin Bit numbers are LSB0 1345a61ef74SNicholas Piggin bit 0 - FSCR 1355a61ef74SNicholas Piggin All other bits reserved and should be zero. 1365a61ef74SNicholas Piggin 1375a61ef74SNicholas Piggin This property describes the OS privilege support required to enable the 1385a61ef74SNicholas Piggin feature to lesser privilege levels. If the property does not exist then no 1395a61ef74SNicholas Piggin support is required. 1405a61ef74SNicholas Piggin 1415a61ef74SNicholas Piggin If no bits are set, the operating system must have explicit/custom support 1425a61ef74SNicholas Piggin for this feature. 1435a61ef74SNicholas Piggin 1445a61ef74SNicholas Piggin If the FSCR bit is set, then the fscr-bit-nr property will exist and 1455a61ef74SNicholas Piggin the feature may be enabled by setting this bit in the FSCR register. 1465a61ef74SNicholas Piggin 1475a61ef74SNicholas Piggin 1485a61ef74SNicholas Piggin- hfscr-bit-nr 1495a61ef74SNicholas Piggin Usage: optional 1505a61ef74SNicholas Piggin Value type: <u32> 1515a61ef74SNicholas Piggin Definition: HFSCR bit position (LSB0) 1525a61ef74SNicholas Piggin 1535a61ef74SNicholas Piggin This property exists when the hv-support property HFSCR bit is set. This 1545a61ef74SNicholas Piggin property describes the bit number in the HFSCR register that the 1555a61ef74SNicholas Piggin hypervisor must set in order to enable this feature. 1565a61ef74SNicholas Piggin 1575a61ef74SNicholas Piggin This property also exists if an HFSCR bit corresponds with this feature. 1585a61ef74SNicholas Piggin This makes CPU feature parsing slightly simpler. 1595a61ef74SNicholas Piggin 1605a61ef74SNicholas Piggin 1615a61ef74SNicholas Piggin- fscr-bit-nr 1625a61ef74SNicholas Piggin Usage: optional 1635a61ef74SNicholas Piggin Value type: <u32> 1645a61ef74SNicholas Piggin Definition: FSCR bit position (LSB0) 1655a61ef74SNicholas Piggin 1665a61ef74SNicholas Piggin This property exists when the os-support property FSCR bit is set. This 1675a61ef74SNicholas Piggin property describes the bit number in the FSCR register that the 1685a61ef74SNicholas Piggin operating system must set in order to enable this feature. 1695a61ef74SNicholas Piggin 1705a61ef74SNicholas Piggin This property also exists if an FSCR bit corresponds with this feature. 1715a61ef74SNicholas Piggin This makes CPU feature parsing slightly simpler. 1725a61ef74SNicholas Piggin 1735a61ef74SNicholas Piggin 1745a61ef74SNicholas Piggin- hwcap-bit-nr 1755a61ef74SNicholas Piggin Usage: optional 1765a61ef74SNicholas Piggin Value type: <u32> 1775a61ef74SNicholas Piggin Definition: Linux ELF AUX vector bit position (LSB0) 1785a61ef74SNicholas Piggin 1795a61ef74SNicholas Piggin This property may exist when the usable-privilege property value has PR bit set. 1805a61ef74SNicholas Piggin This property describes the bit number that should be set in the ELF AUX 1815a61ef74SNicholas Piggin hardware capability vectors in order to advertise this feature to userspace. 1825a61ef74SNicholas Piggin Bits 0-31 correspond to bits 0-31 in AT_HWCAP vector. Bits 32-63 correspond 1835a61ef74SNicholas Piggin to 0-31 in AT_HWCAP2 vector, and so on. Missing AT_HWCAPx vectors implies 1845a61ef74SNicholas Piggin that the feature is not enabled or can not be advertised. Operating systems 1855a61ef74SNicholas Piggin may provide a number of unassigned hardware capability bits to allow for new 1865a61ef74SNicholas Piggin features to be advertised. 1875a61ef74SNicholas Piggin 1885a61ef74SNicholas Piggin Some properties representing features created before this binding are 1895a61ef74SNicholas Piggin advertised to userspace without a one-to-one hwcap bit number may not specify 1905a61ef74SNicholas Piggin this bit. Operating system will handle those bits specifically. All new 1915a61ef74SNicholas Piggin features usable by userspace will have a hwcap-bit-nr property. 1925a61ef74SNicholas Piggin 1935a61ef74SNicholas Piggin 1945a61ef74SNicholas Piggin- dependencies 1955a61ef74SNicholas Piggin Usage: optional 1965a61ef74SNicholas Piggin Value type: <prop-encoded-array> 1975a61ef74SNicholas Piggin Definition: 1985a61ef74SNicholas Piggin 1995a61ef74SNicholas Piggin If this property exists then it is a list of phandles to cpu feature 2005a61ef74SNicholas Piggin nodes that must be enabled for this feature to be enabled. 2015a61ef74SNicholas Piggin 2025a61ef74SNicholas Piggin 2035a61ef74SNicholas PigginExample 2045a61ef74SNicholas Piggin------- 2055a61ef74SNicholas Piggin 2065a61ef74SNicholas Piggin /cpus/ibm,powerpc-cpu-features { 2075a61ef74SNicholas Piggin compatible = "ibm,powerpc-cpu-features"; 2085a61ef74SNicholas Piggin 2095a61ef74SNicholas Piggin isa = <3020>; 2105a61ef74SNicholas Piggin 2115a61ef74SNicholas Piggin darn { 2125a61ef74SNicholas Piggin isa = <3000>; 2135a61ef74SNicholas Piggin usable-privilege = <1 | 2 | 4>; 2145a61ef74SNicholas Piggin hwcap-bit-nr = <xx>; 2155a61ef74SNicholas Piggin }; 2165a61ef74SNicholas Piggin 2175a61ef74SNicholas Piggin scv { 2185a61ef74SNicholas Piggin isa = <3000>; 2195a61ef74SNicholas Piggin usable-privilege = <1 | 2>; 2205a61ef74SNicholas Piggin os-support = <0>; 2215a61ef74SNicholas Piggin hwcap-bit-nr = <xx>; 2225a61ef74SNicholas Piggin }; 2235a61ef74SNicholas Piggin 2245a61ef74SNicholas Piggin stop { 2255a61ef74SNicholas Piggin isa = <3000>; 2265a61ef74SNicholas Piggin usable-privilege = <2 | 4>; 2275a61ef74SNicholas Piggin hv-support = <0>; 2285a61ef74SNicholas Piggin os-support = <0>; 2295a61ef74SNicholas Piggin }; 2305a61ef74SNicholas Piggin 2315a61ef74SNicholas Piggin vsx2 (hypothetical) { 2325a61ef74SNicholas Piggin isa = <3010>; 2335a61ef74SNicholas Piggin usable-privilege = <1 | 2 | 4>; 2345a61ef74SNicholas Piggin hv-support = <0>; 2355a61ef74SNicholas Piggin os-support = <0>; 2365a61ef74SNicholas Piggin hwcap-bit-nr = <xx>; 2375a61ef74SNicholas Piggin }; 2385a61ef74SNicholas Piggin 2395a61ef74SNicholas Piggin vsx2-newinsns { 2405a61ef74SNicholas Piggin isa = <3020>; 2415a61ef74SNicholas Piggin usable-privilege = <1 | 2 | 4>; 2425a61ef74SNicholas Piggin os-support = <1>; 2435a61ef74SNicholas Piggin fscr-bit-nr = <xx>; 2445a61ef74SNicholas Piggin hwcap-bit-nr = <xx>; 2455a61ef74SNicholas Piggin dependencies = <&vsx2>; 2465a61ef74SNicholas Piggin }; 2475a61ef74SNicholas Piggin 2485a61ef74SNicholas Piggin }; 249