Using Dynamic Dispatch - 5.2 English - 57404

Building AOCL-BLAS

Dynamic Dispatch must be enabled while building the AOCL-BLAS library. This is done by building the library for amdzen configuration as explained in Build AOCL-BLAS from Source on Linux.

Code Path Information

Dynamic Dispatch can print debugging information on the selected code path. This is enabled by setting the environment variable BLIS_ARCH_DEBUG=1.

Architecture Selection at Runtime

For most use cases, Dynamic Dispatch will detect the underlying architecture and enable appropriate code paths and optimizations. However, AOCL-BLAS can be forced to use a specific architecture by setting either the environment variable AOCL_ENABLE_INSTRUCTIONS or BLIS_ARCH_TYPE as follows:

AOCL_ENABLE_INSTRUCTIONS=value <AOCL-BLAS linked application>

or

BLIS_ARCH_TYPE=value <AOCL-BLAS linked application>

Where, value = {avx512, avx2, zen5, zen4, zen3, zen2, zen, generic} You must note the following:

• The code path names are not case sensitive but the environment variable names are.

• Options for older x86-64 vector ISAs (e.g. avx, sse2) are also supported but in general will correspond to the generic code path.

• In AOCL-BLAS builds with configuration amdzen, avx512 is an alias for zen4 and avx2 is an alias for zen3.

• AOCL_ENABLE_INSTRUCTIONS is intended to become the standard option for controlling dynamic dispatch (where supported) across all the AOCL components.

• BLIS_ARCH_TYPE is specific to the BLIS code used in AOCL-BLAS.

• If both are specified, BLIS_ARCH_TYPE takes precedence and AOCL_ENABLE_INSTRUCTIONS is ignored by AOCL-BLAS. This provides and options of using AOCL_ENABLE_INSTRUCTIONS to control other AOCL libraries but specify different options for AOCL-BLAS using BLIS_ARCH_TYPE.

• The operation of AOCL_ENABLE_INSTRUCTIONS and BLIS_ARCH_TYPE are slightly different:

  • If AOCL_ENABLE_INSTRUCTIONS is in operation, AOCL-BLAS will check if the instruction set required by the code path selected is enabled within the library and supported by the processor. If not, it will use the default choice for that architecture. In other words, AOCL_ENABLE_INSTRUCTIONS should be used to restrict a processor to an earlier instruction set, rather than try to force a later one on an older processor.

  • By contrast, if BLIS_ARCH_TYPE is in operation, that code path will be used irrespective of the compatibility with the processor.

• Specifying a particular code path will completely override the automatic selection and thus, the following scenarios are possible:

  • A code path unavailable in the AOCL-BLAS build is being used. This will result in an error message from the AOCL-BLAS library which will then abort. This only applies when using BLIS_ARCH_TYPE (at AOCL 4.2 it also applied to AOCL_ENABLE_INSTRUCTIONS).

  • A code path executes instructions unavailable on the processor being used, for example, trying to run the AMD “Zen4” code path (which may use AVX512 instructions) on a AMD “Zen3” or older system. If this happens, the program may stop with an “illegal instruction” error. This applies only when BLIS_ARCH_TYPE is used; executing the illegal instruction may be routine and problem size dependent.

In some circumstances, AOCL-BLAS aborting on an error from BLIS_ARCH_TYPE being set incorrectly may not be acceptable. If you are building AOCL-BLAS from source, there are two options to mitigate this issue. One is to change the environment variable used from BLIS_ARCH_TYPE to another name, for example:

$ ./configure --enable-cblas --prefix=<your-install-dir> \
  --rename-blis-arch-type=MY_BLIS_ARCH_TYPE amdzen
... make aocl-blas library
... compile program linking with aocl-blas
$ export BLIS_ARCH_TYPE=zen3
$ export MY_BLIS_ARCH_TYPE=zen2
$ ./program.exe

This will cause program.exe (which uses AOCL-BLAS) to ignore the setting of BLIS_ARCH_TYPE to zen3. Instead, it will take the value of MY_BLIS_ARCH_TYPE and use the zen2 code path. When --rename-blis-arch-type is used, AOCL_ENABLE_INSTRUCTIONS remains enabled in the build, but MY_BLIS_ARCH_TYPE (in this example) would take precedence if both are set.

Alternatively, the mechanism to allow manual selection of code path can be disabled:

$ ./configure --enable-cblas --prefix=<your-install-dir> \
  --disable-blis-arch-type amdzen

In this case, Dynamic Dispatch will still occur among the included code paths, but only by automatic selection based on the processor architecture. Manual selection of code path by both AOCL_ENABLE_INSTRUCTIONS and BLIS_ARCH_TYPE is disabled.

Model Selection at Runtime

Recent AMD “Zen” generations have added more diverse choices of core designs and cache characteristics. For example, Milan and Milan-X variants at AMD “Zen3”; Genoa, Bergamo, and Genoa-X variants at AMD “Zen4”. Some AOCL-BLAS APIs may be tuned differently for these different models. The appropriate model will be selected automatically by Dynamic Dispatch.

However, AOCL can be forced to use a specific model by setting the environment variable BLIS_MODEL_TYPE as follows:

BLIS_MODEL_TYPE=value <AOCL-BLAS linked application>

where value = {Milan, Milan-X, Genoa, Bergamo, Genoa-X, Turin, Turin-Dense} Note the following:

• Different model values correspond to specific BLIS_ARCH_TYPE values (either set automatically or explicitly by the user). Thus, Milan and Milan-X correspond to AMD “Zen3”; Genoa, Bergamo, and Genoa-X correspond to AMD “Zen4”, and Turin and Turin-Dense correspond to AMD “Zen5”.

• Incorrect values of BLIS_MODEL_TYPE do not cause an error, the default model type for the selected architecture will be used.

• The number of APIs that have different optimizations by model type is currently very small. Setting this environment variable may provide consistent results across different models if consistency is a higher priority than best performance.

As with BLIS_ARCH_TYPE, when building BLAS from source, the name of the environment variable used to set the model type can be changed, for example:

$ ./configure --enable-cblas --prefix=<your-install-dir> \
  --rename-blis-model-type=MY_BLIS_MODEL_TYPE amdzen

Disabling the mechanism to allow the manual section of BLAS architecture will also disable the mechanism to allow the manual section of the model.

$ ./configure --enable-cblas --prefix=<your-install-dir> \
  --disable-blis-arch-type amdzen

Setting either of these environment variables makes sense only when using a build of AOCL-BLAS that includes multiple code paths. Thus, AOCL_ENABLE_INSTRUCTIONS and BLIS_ARCH_TYPE are disabled by default in all the builds containing only a single code path.