Home | History | Annotate | Line # | Download | only in man3 
      1 =pod
      2 
      3 =head1 NAME
      4 
      5 OPENSSL_ppccap - the PowerPC processor capabilities vector
      6 
      7 =head1 SYNOPSIS
      8 
      9  env OPENSSL_ppccap=... <application>
     10 
     11 =head1 DESCRIPTION
     12 
     13 libcrypto supports PowerPC instruction set extensions. These extensions are
     14 represented by bits in the PowerPC capabilities vector. When libcrypto
     15 initializes, it stores the results returned by PowerPC CPU capabilities detection
     16 logic in the PowerPC capabilities vector. The CPU capabilities detection methods
     17 are OS-dependent and use a combination of information gathered by the kernel
     18 during boot and probe functions that attempt to execute instructions and trap
     19 illegal instruction signals with a signal handler.
     20 
     21 To override the set of extensions available to an application, you can set the
     22 B<OPENSSL_ppccap> environment variable before you start the application. The
     23 environment variable is assigned a numerical value that denotes the bits in
     24 the PowerPC capabilities vector. The ppc_arch.h header file states that, "Flags'
     25 usage can appear ambiguous, because they are set rather to reflect OpenSSL
     26 performance preferences than actual processor capabilities."
     27 
     28 Multiple extensions are enabled by logically OR-ing the values that represent the
     29 desired extensions.
     30 
     31 B<Notes>: Enabling an extension on a CPU that does not support the extension
     32 will result in a SIGILL crash. On AIX, all vector instructions can be disabled
     33 with the schedo -ro allow_vmx=0 command. DO NOT USE THIS COMMAND to disable
     34 vector instructions in the OS when it is running on a CPU level that supports the
     35 instructions without also disabling them in libcrpto via the OPENSSL_ppccap
     36 environment variable or the application will crash with a SIGILL.
     37 
     38 Currently, the following extensions are defined:
     39 
     40 =over 4
     41 
     42 =item 0x01
     43 
     44 Name: B<PPC_FPU64>
     45 
     46 This flag is obsolete.
     47 
     48 =item 0x02
     49 
     50 Name: B<PPC_ALTIVEC>
     51 
     52 Meaning: Use AltiVec (aka VMX) instructions. In some but not all cases, this
     53 capability gates the use of later ISA vector instructions. The associated probe
     54 instruction is vor (vector logical or).
     55 
     56 Effect: Enables use of vector instructions but does not enable extensions added
     57 at specific ISA levels. However, disabling this capability disables a subset of
     58 vector extensions added at specific ISA levels even if they are otherwise
     59 enabled.
     60 
     61 =item 0x04
     62 
     63 Name: B<PPC_CRYPTO207>
     64 
     65 Meaning: Use instructions added in ISA level 2.07. The associated probe
     66 instruction instruction is vcipher (vector AES cipher round).
     67 
     68 Effect: Enables AES, SHA-2 sigma, and other ISA 2.07 instructions for AES, SHA-2,
     69 GHASH, and Poly1305.
     70 
     71 =item 0x08
     72 
     73 Name: B<PPC_FPU>
     74 
     75 Meaning: Use FPU instructions. The associated probe instruction is fmr (floating
     76 move register).
     77 
     78 Effect: Enables Poly1305 FPU implementation. The PPC_CRYPTO207 capability
     79 overrides this effect.
     80 
     81 =item 0x10
     82 
     83 Name: B<PPC_MADD300>
     84 
     85 Meaning: Use instructions added in ISA level 3.00. The associated probe
     86 instruction is maddhdu (multiply-add high doubleword unsigned).
     87 
     88 Effect: Enables use of the polynomial multiply and other ISA 3.00 instructions
     89 for AES-GCM, P-384, and P-521.
     90 
     91 =item 0x20
     92 
     93 Name: B<PPC_MFTB>
     94 
     95 Meaning: Use the mftb (move from time base) instruction. The associated probe
     96 instruction is mftb.
     97 
     98 Effect: Enables use of the mftb instruction to sample the lower 32 bits of the
     99 CPU time base register in order to acquire entropy. Considered obsolete.  The
    100 PPC_MFSPR268 capability overrides this capability.
    101 
    102 =item 0x40
    103 
    104 Name: B<PPC_MFSPR268>
    105 
    106 Meaning: Use the mfspr (move from special purpose register) instruction to
    107 read SPR 268. The associated probe instruction is mfspr 268.
    108 
    109 Effect: Enables use of the mfspr instruction to sample the lower 32 bits of the
    110 CPU time base register from SPR 268, the TBL (time base lower) register, in order
    111 to acquire entropy.
    112 
    113 =item 0x80
    114 
    115 Name: B<PPC_BRD31>
    116 
    117 Meaning: Use instructions added in ISA level 3.1. The associated probe instruction
    118 is brd (byte-reverse doubleword).
    119 
    120 Effect: Enables use of ISA 3.1 instructions in ChaCha20.
    121 
    122 =back
    123 
    124 =head1 RETURN VALUES
    125 
    126 Not available.
    127 
    128 =head1 EXAMPLES
    129 
    130 Check currently detected capabilities:
    131 
    132  $ openssl info -cpusettings
    133  OPENSSL_ppccap=0x2E
    134 
    135 The detected capabilities in the above example indicate that PPC_MFTB, PPC_FPU,
    136 PPC_CRYPTO207, PPC_MFSPR268, and PPC_ALTIVEC are enabled.
    137 
    138 Disable all instruction set extensions:
    139 
    140  OPENSSL_ppccap=0x00
    141 
    142 Enable base AltiVec extensions:
    143 
    144  OPENSSL_ppccap=0x02
    145 
    146 =head1 COPYRIGHT
    147 
    148 Copyright 2025 The OpenSSL Project Authors. All Rights Reserved.
    149 
    150 Licensed under the Apache License 2.0 (the "License").  You may not use
    151 this file except in compliance with the License.  You can obtain a copy
    152 in the file LICENSE in the source distribution or at
    153 L<https://www.openssl.org/source/license.html>.
    154 
    155 =cut
    156