Refactor config - move templates and template docs to Configurations

Move the documentation of the target configuration form to
Configurations/README.

Move initial assembler object templates to
Configurations/00-BASE-templates.conf.

Furthermore, remove all variables containing the names of the
non-assembler object files and make a BASE template of them instead.
The  values from this templates are used as defaults as is.  The
remaining manipulation of data when assembler modules are used is done
only when $no_asm is false.

While doing this, clean out some other related variables that aren't
used anywhere.

Also, we had to move the resolution of the chosen target a bit, or the
function 'asm' would never catch a true $no_asm...  this hasn't
mattered before we've moved it all to the BASE template, but now it
does.

At the same time, add the default for the 'unistd' key to the BASE
template.

Reviewed-by: Rich Salz <rsalz@openssl.org>

2 files changed, 456 insertions, 0 deletions

diff --git a/Configurations/00-base-templates.conf b/Configurations/00-base-templates.conf
new file mode 100644
index 0000000000..064648f15a
--- /dev/null
+++ b/Configurations/00-base-templates.conf
@@ -0,0 +1,168 @@
+%targets=(
+    BASE => {
+	template	=> 1,
+	cpuid_obj	=> "mem_clr.o",
+	bn_obj		=> "bn_asm.o",
+	ec_obj		=> "",
+	des_obj		=> "des_enc.o fcrypt_b.o",
+	aes_obj		=> "aes_core.o aes_cbc.o",
+	bf_obj		=> "bf_enc.o",
+	md5_obj		=> "",
+	cast_obj	=> "c_enc.o",
+	rc4_obj		=> "rc4_enc.o rc4_skey.o",
+	rmd160_obj	=> "",
+	rc5_obj		=> "rc5_enc.o",
+	wp_obj		=> "wp_block.o",
+	cmll_obj	=> "camellia.o cmll_misc.o cmll_cbc.o",
+	modes_obj	=> "",
+	engines_obj	=> "",
+	chacha_obj	=> "chacha_enc.o",
+	poly1305_obj	=> "",
+
+	unistd		=> "<unistd.h>",
+    },
+
+    x86_asm => {
+	template	=> 1,
+	cpuid_obj	=> "x86cpuid.o",
+	bn_obj		=> "bn-586.o co-586.o x86-mont.o x86-gf2m.o",
+	ec_obj		=> "ecp_nistz256.o ecp_nistz256-x86.o",
+	des_obj		=> "des-586.o crypt586.o",
+	aes_obj		=> "aes-586.o vpaes-x86.o aesni-x86.o",
+	bf_obj		=> "bf-586.o",
+	md5_obj		=> "md5-586.o",
+	sha1_obj	=> "sha1-586.o sha256-586.o sha512-586.o",
+	rc4_obj		=> "rc4-586.o",
+	rmd160_obj	=> "rmd-586.o",
+	rc5_obj		=> "rc5-586.o",
+	wp_obj		=> "wp_block.o wp-mmx.o",
+	cmll_obj	=> "cmll-x86.o",
+	modes_obj	=> "ghash-x86.o",
+	engines_obj	=> "e_padlock-x86.o"
+    },
+    x86_elf_asm => {
+	template	=> 1,
+	inherit_from	=> [ "x86_asm" ],
+	perlasm_scheme	=> "elf"
+    },
+    x86_64_asm => {
+	template	=> 1,
+	cpuid_obj       => "x86_64cpuid.o",
+	bn_obj          => "x86_64-gcc.o x86_64-mont.o x86_64-mont5.o x86_64-gf2m.o rsaz_exp.o rsaz-x86_64.o rsaz-avx2.o",
+	ec_obj          => "ecp_nistz256.o ecp_nistz256-x86_64.o",
+	aes_obj         => "aes-x86_64.o vpaes-x86_64.o bsaes-x86_64.o aesni-x86_64.o aesni-sha1-x86_64.o aesni-sha256-x86_64.o aesni-mb-x86_64.o",
+	md5_obj         => "md5-x86_64.o",
+	sha1_obj        => "sha1-x86_64.o sha256-x86_64.o sha512-x86_64.o sha1-mb-x86_64.o sha256-mb-x86_64.o",
+	rc4_obj         => "rc4-x86_64.o rc4-md5-x86_64.o",
+	wp_obj          => "wp-x86_64.o",
+	cmll_obj        => "cmll-x86_64.o cmll_misc.o",
+	modes_obj       => "ghash-x86_64.o aesni-gcm-x86_64.o",
+	engines_obj     => "e_padlock-x86_64.o"
+    },
+    ia64_asm => {
+	template	=> 1,
+	cpuid_obj       => "ia64cpuid.o",
+	bn_obj          => "bn-ia64.o ia64-mont.o",
+	aes_obj         => "aes_core.o aes_cbc.o aes-ia64.o",
+	md5_obj         => "md5-ia64.o",
+	sha1_obj        => "sha1-ia64.o sha256-ia64.o sha512-ia64.o",
+	rc4_obj         => "rc4-ia64.o rc4_skey.o",
+	modes_obj       => "ghash-ia64.o",
+	perlasm_scheme	=> "void"
+    },
+    sparcv9_asm => {
+	template	=> 1,
+	cpuid_obj       => "sparcv9cap.o sparccpuid.o",
+	bn_obj          => "bn-sparcv9.o sparcv9-mont.o sparcv9a-mont.o vis3-mont.o sparct4-mont.o sparcv9-gf2m.o",
+        ec_obj          => "ecp_nistz256.o ecp_nistz256-sparcv9.o",
+	des_obj         => "des_enc-sparc.o fcrypt_b.o dest4-sparcv9.o",
+	aes_obj         => "aes_core.o aes_cbc.o aes-sparcv9.o aest4-sparcv9.o",
+	md5_obj         => "md5-sparcv9.o",
+	sha1_obj        => "sha1-sparcv9.o sha256-sparcv9.o sha512-sparcv9.o",
+	cmll_obj        => "camellia.o cmll_misc.o cmll_cbc.o cmllt4-sparcv9.o",
+	modes_obj       => "ghash-sparcv9.o",
+	perlasm_scheme	=> "void"
+    },
+    sparcv8_asm => {
+	template	=> 1,
+	cpuid_obj       => "",
+	bn_obj          => "sparcv8.o",
+	des_obj         => "des_enc-sparc.o fcrypt_b.o",
+	perlasm_scheme	=> "void"
+    },
+    alpha_asm => {
+	template	=> 1,
+	cpuid_obj       => "alphacpuid.o",
+	bn_obj          => "bn_asm.o alpha-mont.o",
+	sha1_obj        => "sha1-alpha.o",
+	modes_obj       => "ghash-alpha.o",
+	perlasm_scheme	=> "void"
+    },
+    mips32_asm => {
+	template	=> 1,
+	bn_obj          => "bn-mips.o mips-mont.o",
+	aes_obj         => "aes_cbc.o aes-mips.o",
+	sha1_obj        => "sha1-mips.o sha256-mips.o",
+    },
+    mips64_asm => {
+	inherit_from	=> [ "mips32_asm" ],
+	template	=> 1,
+	sha1_obj        => sub { join(" ", @_, "sha512-mips.o") }
+    },
+    s390x_asm => {
+	template	=> 1,
+	cpuid_obj       => "s390xcap.o s390xcpuid.o",
+	bn_obj          => "bn-s390x.o s390x-mont.o s390x-gf2m.o",
+	aes_obj         => "aes-s390x.o aes-ctr.o aes-xts.o",
+	sha1_obj        => "sha1-s390x.o sha256-s390x.o sha512-s390x.o",
+	rc4_obj         => "rc4-s390x.o",
+	modes_obj       => "ghash-s390x.o",
+    },
+    armv4_asm => {
+	template	=> 1,
+	cpuid_obj       => "armcap.o armv4cpuid.o",
+	bn_obj          => "bn_asm.o armv4-mont.o armv4-gf2m.o",
+	ec_obj          => "ecp_nistz256.o ecp_nistz256-armv4.o",
+	aes_obj         => "aes_cbc.o aes-armv4.o bsaes-armv7.o aesv8-armx.o",
+	sha1_obj        => "sha1-armv4-large.o sha256-armv4.o sha512-armv4.o",
+	modes_obj       => "ghash-armv4.o ghashv8-armx.o",
+	perlasm_scheme	=> "void"
+    },
+    aarch64_asm => {
+	template	=> 1,
+	cpuid_obj       => "armcap.o arm64cpuid.o mem_clr.o",
+	ec_obj          => "ecp_nistz256.o ecp_nistz256-armv8.o",
+	bn_obj          => "bn_asm.o armv8-mont.o",
+	aes_obj         => "aes_core.o aes_cbc.o aesv8-armx.o vpaes-armv8.o",
+	sha1_obj        => "sha1-armv8.o sha256-armv8.o sha512-armv8.o",
+	modes_obj       => "ghashv8-armx.o",
+    },
+    parisc11_asm => {
+	template	=> 1,
+	cpuid_obj       => "pariscid.o",
+	bn_obj          => "bn_asm.o parisc-mont.o",
+	aes_obj         => "aes_core.o aes_cbc.o aes-parisc.o",
+	sha1_obj        => "sha1-parisc.o sha256-parisc.o sha512-parisc.o",
+	rc4_obj         => "rc4-parisc.o",
+	modes_obj       => "ghash-parisc.o",
+	perlasm_scheme	=> "32"
+    },
+    parisc20_64_asm => {
+	template	=> 1,
+	inherit_from	=> [ "parisc11_asm" ],
+	bn_obj          => sub { my $r=join(" ",@_); $r=~s/bn_asm/pa-risc2W/; $r; },
+	perlasm_scheme	=> "64",
+    },
+    ppc64_asm => {
+	template	=> 1,
+	cpuid_obj       => "ppccpuid.o ppccap.o",
+	bn_obj          => "bn-ppc.o ppc-mont.o ppc64-mont.o",
+	aes_obj         => "aes_core.o aes_cbc.o aes-ppc.o vpaes-ppc.o aesp8-ppc.o",
+	sha1_obj        => "sha1-ppc.o sha256-ppc.o sha512-ppc.o sha256p8-ppc.o sha512p8-ppc.o",
+	modes_obj       => "ghashp8-ppc.o",
+    },
+    ppc32_asm => {
+	inherit_from	=> [ "ppc64_asm" ],
+	template	=> 1
+    },
+);
diff --git a/Configurations/README b/Configurations/README
new file mode 100644
index 0000000000..e1327e57f9
--- /dev/null
+++ b/Configurations/README
@@ -0,0 +1,288 @@
+Configurations of OpenSSL target platforms
+------------------------------------------
+
+Target configurations are a collection of facts that we know about
+different platforms and their capabilities.  We organise them in a
+hash table, where each entry represent a specific target.
+
+In each table entry, the following keys are significant:
+
+        inherit_from    => Other targets to inherit values from.
+                           Explained further below. [1]
+        template        => Set to 1 if this isn't really a platform
+                           target.  Instead, this target is a template
+                           upon which other targets can be built.
+                           Explained further below.  [1]
+
+        sys_id          => System identity for systems where that
+                           is difficult to determine automatically.
+
+        cc              => The compiler command, usually one of "cc",
+                           "gcc" or "clang".  This command is normally
+                           also used to link object files and
+                           libraries into the final program.
+        cflags          => Flags that are used at all times when
+                           compiling.
+        debug_cflags    => Extra compilation flags used when making a
+                           debug build (when Configure receives the
+                           --debug option).  Typically something like
+                           "-g -O0".
+        release_cflags  => Extra compilation flags used when making a
+                           release build (when Configure receives the
+                           --release option, or doesn't receive the
+                           --debug option).  Typically something like
+                           "-O" or "-O3".
+        thread_cflags   => Extra compilation flags used when
+                           compiling with threading enabled.
+                           Explained further below.  [2]
+        shared_cflag    => Extra compilation flags used when
+                           compiling for shared libraries, typically
+                           something like "-fPIC".
+
+        ld              => the linker command, usually not defined
+                           (meaning the compiler command is used
+                           instead).
+                           (NOTE: this is here for future use, it's
+                           not implemented yet)
+        lflags          => the flags that are used at all times when
+                           linking.  These can have a % sign in them
+                           showing where the OpenSSL libraries should
+                           appear, otherwise these flags will come
+                           last.  So in a typical links situation,
+                           this is a quick table of results:
+
+                           "-foo%-bar"  > -foo -lssl -lcrypto -bar
+                           "-foo%"      > -foo -lssl -lcrypto
+                           "-foo"       > -lssl -lcrypto -foo
+
+        debug_lflags    => Like debug_cflags, but used when linking.
+        release_lflags  => Like release_cflags, but used when linking.
+        shared_lflags   => Like shared_cflags, but used when linking.
+
+        ar              => The library archive command, the default is
+                           "ar".
+                           (NOTE: this is here for future use, it's
+                           not implemented yet)
+        arflags         => Flags to be used with the library archive
+                           command.
+
+        ranlib          => The library archive indexing command, the
+                           default is 'ranlib' it it exists.
+
+        unistd          => An alternative header to the typical
+                           '<unistd.h>'.  This is very rarely needed.
+
+        shared_extension => File name extension used for shared
+                            libraries. 
+        obj_extension   => File name extension used for object files.
+                           On unix, this defaults to ".o" (NOTE: this
+                           is here for future use, it's not
+                           implemented yet)
+        exe_extension   => File name extension used for executable
+                           files.  On unix, this defaults to "" (NOTE:
+                           this is here for future use, it's not
+                           implemented yet)
+
+        dso_scheme      => The type of dynamic shared objects to build
+                           for.  This mostly comes into play with
+                           engines, but can be used for other purposes
+                           as well.  Valid values are "DLFCN"
+                           (dlopen() et al), "DLFCN_NO_H" (for systems
+                           that use dlopen() et al but do not have
+                           fcntl.h), "DL" (shl_load() et al), "WIN32"
+                           and "VMS".
+        perlasm_scheme  => The perlasm method used to created the
+                           assembler files used when compiling with
+                           assembler implementations.
+        shared_target   => The shared library building method used.
+                           This is a target found in Makefile.shared.
+        build_scheme    => The scheme used to build up a Makefile.
+                           (NOTE: this is here for future use, it's
+                           not implemented yet)
+
+        multilib        => On systems that support having multiple
+                           implementations of a library (typically a
+                           32-bit and a 64-bit variant), this is used
+                           to have the different variants in different
+                           directories.
+
+        bn_ops          => Building options (was just bignum options
+                           in the earlier history of this option,
+                           hence the name).  This a string of words
+                           that describe properties on the designated
+                           target platform, such as the type of
+                           integers used to build up the bitnum,
+                           different ways to implement certain ciphers
+                           and so on.  To fully comprehend the
+                           meaning, the best is to read the affected
+                           source.
+                           The valid words are:
+
+                           DES_PTR      use a pointer to DES_SPtrans
+                                        rather that DES_SPtrans
+                                        directly in D_ENCRYPT.
+                           DES_RISC1    Alternate implementations of
+                           DES_RISC2    D_ENCRYPT for certain RISC
+                                        processors.
+                           DES_UNROLL   do not loop around calls to
+                                        D_ENCRYPT.
+                           DES_INT      have unsigned int as the
+                                        integer type for DES rather
+                                        than unsigned long.
+                           BN_LLONG     use 'unsigned long long' in
+                                        some bignum calculations.
+                                        This has no value when
+                                        SIXTY_FOUR_BIT or
+                                        SIXTY_FOUR_BIT_LONG is given.
+                           RC4_CHAR     makes the basic RC4 unif of
+                                        calculation an unsigned char.
+                           RC4_LONG     makes the basic RC4 unif of
+                                        calculation an unsigned long.
+                           RC4_INDEX    go through input and output
+                                        data by indexing into them
+                                        rather than incrementing the
+                                        pointer.
+                           RC4_CHUNK    sets the chunk type to
+                                        unsigned long.
+                           RC4_CHUNK_LL sets the chunk type to
+                                        unsigned long long.
+                                        both these chunk sizes are for
+                                        handling data in chunks on
+                                        processors that do not have
+                                        byte load/store instructions.
+                           MD2_CHAR     makes the basic MD2 unit of
+                                        calculation an unsigned char.
+                           MD2_LONG     makes the basic MD2 unit of
+                                        calculation an unsigned long.
+                           IDEA_SHORT   makes the basic IDEA unit of
+                                        calculation an unsigned short.
+                           IDEA_LONG    makes the basic IDEA unit of
+                                        calculation an unsigned long.
+                           RC2_SHORT    makes the basic RC2 unit of
+                                        calculation an unsigned short.
+                           RC2_LONG     makes the basic RC2 unit of
+                                        calculation an unsigned long.
+                           BF_PTR       use different pointer based
+                           BF_PTR2      versions of BF_ENC.
+                           SIXTY_FOUR_BIT       processor registers
+                                                are 64 bits, long is
+                                                32 bits, long long is
+                                                64 bits.
+                           SIXTY_FOUR_BIT_LONG  processor registers
+                                                are 64 bits, long is
+                                                64 bits.
+                           THIRTY_TWO_BIT       processor registers
+                                                are 32 bits.
+                           EXPORT_VAR_AS_FN     for shared libraries,
+                                                export vars as
+                                                accessor functions.
+
+        cpuid_obj       => assembler implementation of cpuid code as
+                           well as OPENSSL_cleanse().
+                           Default to mem_clr.o
+        bn_obj          => assembler implementation of core bignum
+                           functions.
+                           Defaults to bn_asm.o
+        ec_obj          => assembler implementation of core EC
+                           functions.
+        des_obj         => assembler implementation of core DES
+                           encryption functions.
+                           Defaults to 'des_enc.o fcrypt_b.o'
+        aes_obj         => assembler implementation of core AES
+                           functions.
+                           Defaults to 'aes_core.o aes_cbc.o'
+        bf_obj          => assembler implementation of core BF
+                           functions.
+                           Defaults to 'bf_enc.o'
+        md5_obj         => assembler implementation of core MD5
+                           functions.
+        sha1_obj        => assembler implementation of core SHA1,
+                           functions, and also possibly SHA256 and
+                           SHA512 ones.
+        cast_obj        => assembler implementation of core BF
+                           functions.
+                           Defaults to 'c_enc.o'
+        rc4_obj         => assembler implementation of core BF
+                           functions.
+                           Defaults to 'rc4_enc.o rc4_skey.o'
+        rmd160_obj      => assembler implementation of core RMD160
+                           functions.
+        rc5_obj         => assembler implementation of core RC4
+                           functions.
+                           Defaults to 'rc5_enc.o'
+        wp_obj          => assembler implementation of core WHIRLPOOL
+                           functions.
+        cmll_obj        => assembler implementation of core CAMELLIA
+                           functions.
+                           Defaults to 'camellia.o cmll_misc.o cmll_cbc.o'
+        modes_obj       => assembler implementation of the
+                           functions gcm_gmult_4bit and gcm_ghash_4bit.
+        engines_obj     => assembler implementation of core parts of
+                           the padlock engine.  This is mandatory on
+                           any platform where the padlock engine might
+                           actually be built.
+
+
+[1] as part of the target configuration, one can have a key called
+    'inherit_from' that indicate what other configurations to inherit
+    data from.  These are resolved recursively.
+
+    Inheritance works as a set of default values that can be overriden
+    by corresponding key values in the inheriting configuration.
+
+    Note 1: any configuration table can be used as a template.
+    Note 2: pure templates have the attribute 'template => 1' and
+            cannot be used as build targets.
+
+    If several configurations are given in the 'inherit_from' array,
+    the values of same attribute are concatenated with space
+    separation.  With this, it's possible to have several smaller
+    templates for different configuration aspects that can be combined
+    into a complete configuration.
+
+    instead of a scalar value or an array, a value can be a code block
+    of the form 'sub { /* your code here */ }'.  This code block will
+    be called with the list of inherited values for that key as
+    arguments.  In fact, the concatenation of strings is really done
+    by using 'sub { join(" ",@_) }' on the list of inherited values.
+
+    An example:
+
+        "foo" => {
+                template => 1,
+                haha => "ha ha",
+                hoho => "ho",
+                ignored => "This should not appear in the end result",
+        },
+        "bar" => {
+                template => 1,
+                haha => "ah",
+                hoho => "haho",
+                hehe => "hehe"
+        },
+        "laughter" => {
+                inherit_from => [ "foo", "bar" ],
+                hehe => sub { join(" ",(@_,"!!!")) },
+                ignored => "",
+        }
+
+        The entry for "laughter" will become as follows after processing:
+
+        "laughter" => {
+                haha => "ha ha ah",
+                hoho => "ho haho",
+                hehe => "hehe !!!",
+                ignored => ""
+        }
+
+[2] OpenSSL is built with threading capabilities unless the user
+    specifies 'no-threads'.  The value of the key 'thread_cflags' may
+    be "(unknown)", in which case the user MUST give some compilation
+    flags to Configure.
+
+
+Historically, the target configurations came in form of a string with
+values separated by colons.  This use is deprecated, although
+currently somewhat supported.  The string form looks like this:
+
+   "target" => "{cc}:{cflags}:{unistd}:{thread_cflag}:{sys_id}:{lflags}:{bn_ops}:{cpuid_obj}:{bn_obj}:{ec_obj}:{des_obj}:{aes_obj}:{bf_obj}:{md5_obj}:{sha1_obj}:{cast_obj}:{rc4_obj}:{rmd160_obj}:{rc5_obj}:{wp_obj}:{cmll_obj}:{modes_obj}:{engines_obj}:{perlasm_scheme}:{dso_scheme}:{shared_target}:{shared_cflag}:{shared_ldflag}:{shared_extension}:{ranlib}:{arflags}:{multilib}"