For early adopters we introduced support of AVX in Intel® Software Development Emulator [2], it allows you to run and check functional correctness of the code with the actual AVX instructions before hardware is available.

Today we are adding another useful piece to help those who may not be able to use new tools supporting AVX in their current development environment but plan to migrate in the future or are using a software platform which is not supported by Intel SDE. These software developers can still start programming with Intel AVX using intrinsics.

Here we are providing the C and C++ header file which emulates Intel AVX intrinsics. The AVX emulation header file uses intrinsics for the prior Intel instruction set extensions up to Intel SSE4.2. SSE4.2 support in your development environment as well as hardware is required in order to use the AVX emulation header file.

To use simply have this file included:

#include "avxintrin_emu.h"

Instead of usual:

#include <immintrin.h>

One can also create alternative immintrin.h file (which in turn includes avxintrin_emu.h) to avoid an intrusive change to the source base and then simply switch between real AVX code generation and emulation via alternating the path to include directories.

Emulation header is primarily targeting UNIX type of environments, and was tested on such with GCC and Intel C/C++ compilers. We have a strong support with other tools (compilers, assemblers and SDE) on Microsoft Windows platform, but this header file can still be used on Windows, if desired, with Intel Compiler.

Note that the AVX emulation header file is designed to allow functional correctness of an AVX implementation and not recommended for long-term usage or release in a final product. Once your development environment and hardware supports AVX, we recommend that you switch to the real AVX intrinsic header file.

Although we did our best to debug it, this file must not be considered a reference functional implementation of AVX instructions or even bug-free. Please see the current version's limitations and caveats in the beginning of the file. Please let us know about the issues you faced using it.

Example

#include "avxintrin_emu.h"  // #include <immintrin.h>

void saxpy( float a, const float* x, const float* y, float* __restrict z, size_t len )
{
    size_t i = 0;
    __m256 a_ = _mm256_set1_ps( a );

    for ( size_t len16_ = len & -16; i + 16 <= len16_; i += 16 )
    {
        __m256 x1_ = _mm256_loadu_ps( x + i );
        __m256 x2_ = _mm256_loadu_ps( x + i + 8 );

        __m256 y1_ = _mm256_loadu_ps( y + i );
        __m256 y2_ = _mm256_loadu_ps( y + i + 8 );

        x1_ = _mm256_mul_ps( x1_, a_ );
        x2_ = _mm256_mul_ps( x2_, a_ );

        x1_ = _mm256_add_ps( x1_, y1_ );
        x2_ = _mm256_add_ps( x2_, y2_ );

        _mm256_storeu_ps( z + i     , x1_ );
        _mm256_storeu_ps( z + i + 8 , x2_ );
    }

    for ( ; i < len; ++i )
        z[i] = x[i] * a + y[i];
}

References

[1] Intel AVX - http://software.intel.com/en-us/avx/

[2] Intel Software Development Emulator - http://software.intel.com/en-us/articles/intel-software-development-emulator/

Loki Team and OOO "Program Verification Systems".
Andrei Alexandrescu, Andrey Karpov, Evgeniy Ryzhkov, Peter Kümmel, Rich Sposato.

September 2009

Abstract

The article is a report about testing of portability of Loki library with 64-bit systems with the help of Viva64 code analyzer performed by OOO "Program Verification Systems" Company. It contains recommendations for users of the library. The article will be also useful for the users of other libraries built on templates for it describes the peculiarities of analysis of such libraries.

Introduction

Loki library has been developed by Andrei Alexandrescu as part of the highly acclaimed book "Modern C++ Design: Generic Programming and Design Patterns Applied". An abstract of the book declares: "This book introduces the concept of generic components-reusable design templates that produce boilerplate code for compiler consumption-all within C++. Generic components enable an easier and more seamless transition from design to application code, generate code that better expresses the original design intention, and support the reuse of design structures with minimal recoding."

OOO "Program Verification Systems" Company creating Viva64 code analyzer for developing 64-bit applications participates actively in communication with the authors of various software projects. Once one of Loki project administrators, Rich Sposato, asked us to check the code of the library for portability to 64-bit systems with the help of our code analyzer Viva64. The Loki library is known for using the most powerful and up-to-date abilities of C++ language; so if Viva64 managed Loki then it can easily manage simpler projects.

We should notice that this article is based on the Loki version of May 2009 (it is more modern than the official version of that time Loki 0.1.7), so the stated problems will be removed in further Loki versions.

So, we downloaded the latest version of Loki from the SVN repository on SourceForge and set to work.

Building of the 64-bit version of Loki in Microsoft Visual Studio 2005

Viva64 code analyzer integrates into Microsoft Visual Studio development environment, that's why it would be sensible to build a version of Loki for this particular environment. Loki package contains ready files of solutions for Visual Studio 2005 and Visual Studio 2008. But now, in May 2009, these solutions contain only 32-bit configurations. That's why we needed to create configurations for x64 platform in Visual Studio. After adding the necessary configurations we could launch compilation of the 64-bit version.

Loki library is intended for operating on many various platforms and is built with the help of many most popular compilers. It explains why the 64-bit Loki version has been compiled nearly at once. The Loki library is actually only one of 20 projects in the most recent version of Loki. The other 19 projects are test programs which exercise various parts of Loki to demonstrate the code compiles and runs correctly. By including so many test programs with Loki, the programmers can provide guarantees for much of Loki's functionality despite the complexity of the Loki source code. Out of 20 projects in the solution only SafeFormat failed to build:

========== Build: 19 succeeded, 1 failed, 0 up-to-date, 0 skipped ==========

------ Build started: Project: SafeFormat, Configuration: Debug x64 ------
Compiling...
main.cpp
.\main.cpp(255) : error C3066: there are multiple ways 
that an object of this type can be called with these arguments
        ..\..\include\loki/SafeFormat.h(109): could be 'Loki::PrintfState<Device,Char> 
&Loki::PrintfState<Device,Char>::operator ()(bool)'
...
        while trying to match the argument list '(UInt)'

The text of the error is abridged a bit for it would take the whole page in a full form. Let's consider the code causing the error:

void test_dword()
{
    typedef signed int Int;
    typedef unsigned int UInt;
    typedef signed long Long;
    typedef unsigned long ULong;
    Int i(0);
    UInt ui(0);
    Long l(0);
    ULong ul(0);
    Printf("%d")(i);
    Printf("%d")(ui); // the problem is in this line
    Printf("%d")(l);
    Printf("%d")(ul);
}

The PrintfState struct uses the LOKI_PRINTF_STATE_FORWARD macro to cast various parameter types to unsigned long. We found one problem here where a 64 bit parameter may get sliced down to 32 bits by this code snippet inside the file SafeFormat.h:

#if (defined(_WIN32) || defined(_WIN64))
        LOKI_PRINTF_STATE_FORWARD(unsigned long)
#else

We recommend using this snippet to avoid slicing 64 bit types:

#if (defined(_WIN32) || defined(_WIN64))
#if (defined(_WIN64))
        LOKI_PRINTF_STATE_FORWARD(unsigned int)
#endif
        LOKI_PRINTF_STATE_FORWARD(unsigned long)
#else

After this single correction the compilation error disappears and all the 20 projects of the library compiled with only some diagnostic warnings. One such warning tells us about a potentially unsafe conversion of size_t type inside typicalUse() function in the file CachedFactoryTest.cpp:

// Registering objects
for(size_t i=0;i<objectKind;i++)
  CC.Register(i, createProductNull);

The control variable (objectKind) of the loop is an unsigned type. After changing the type of the loop counter to unsigned so it matches the type of the control variable, the warning disappears:

 // Registering objects
for(unsigned i=0;i<objectKind;i++)
  CC.Register(i, createProductNull);

After these small corrections the 64-bit library compiles successfully and does not show any diagnostic warnings on 64-bit mode. But is the library's code actually correct? By running the many test projects and seeing no incorrect results or assertion failures, we can confidently say the Loki library is correct. We also used our code analyzer, Viva64, to perform static analysis of Loki.

Testing of the 64-bit Loki version with the help of Viva64

To make sure that Loki is compatible with 64-bit systems, let's perform analysis of the code using Viva64. Viva64 code analyzer is intended for developing new 64-bit applications and porting of existing 32-bit ones on a 64-bit platform.

During the analysis of Loki, Viva64 detected 89 potentially unsafe syntactic constructions. It does not mean Loki projects contain 89 errors related to 64-bit code, but that the developers should review these 89 places should be to understand if these are errors. Of course, we have studied these locations in the code to ascertain if there are actual errors. Many of the 89 locations are inside test projects rather than inside Loki itself.

1 Incorrectly used constant LONG_MIN

Let's begin with an error relating to the incorrectly used constant LONG_MIN in the following function:

char* RenderWithoutSign(LOKI_SAFEFORMAT_SIGNED_LONG n, 
    char* bufLast, unsigned int base, bool uppercase)

It is located in the file SafeFormat.h. The problem is in this line:

if (n != LONG_MIN) {

LOKI_SAFEFORMAT_SIGNED_LONG type is defined as a type capable of storing 64-bit values in a 64-bit system. In Unix-systems (with LP64 data model) long type is used for this purpose. But in 64-bit Windows-systems (LLP64 data model) long type remained 32-bit. That's why LOKI_SAFEFORMAT_SIGNED_LONG type is defined in Loki in this way:

#if defined(_WIN32) || defined(_WIN64)
  #define LOKI_SAFEFORMAT_SIGNED_LONG intptr_t
  #define LOKI_SAFEFORMAT_UNSIGNED_LONG uintptr_t
#else
  #define LOKI_SAFEFORMAT_SIGNED_LONG signed long
  #define LOKI_SAFEFORMAT_UNSIGNED_LONG unsigned long
#endif

As long type remained 32-bit in 64-bit Windows-systems, LONG_MIN constant defines the minimum value of the 32-bit variable. This means that using it is incorrect when operating 64-bit types (in this case intptr_t). A strongly recommended solution is to use your own constant so you can guarantee its value remains the same for all platforms, or so you can control its value per platform rather than relying on the compiler. One possible correction is as follows:

#if defined(_WIN32) || defined(_WIN64)
#  define LOKI_SAFEFORMAT_SIGNED_LONG intptr_t
#if defined(_WIN64)
#  define LOKI_SAFEFORMAT_SIGNED_LONG_MIN_VALUE LLONG_MIN
#  define LOKI_SAFEFORMAT_SIGNED_LONG_MAX_VALUE LLONG_MAX
#else
#  define LOKI_SAFEFORMAT_SIGNED_LONG_MIN_VALUE LONG_MIN
#  define LOKI_SAFEFORMAT_SIGNED_LONG_MAX_VALUE LONG_MAX
#endif
...
#else
#  define LOKI_SAFEFORMAT_SIGNED_LONG signed long
#  define LOKI_SAFEFORMAT_SIGNED_LONG_MIN_VALUE LONG_MIN
#  define LOKI_SAFEFORMAT_SIGNED_LONG_MAX_VALUE LONG_MAX
...
#endif

Consequently, the line

if (n != LONG_MIN) {

must be replaced with

if (n != LOKI_SAFEFORMAT_SIGNED_LONG_MIN_VALUE) {

Fortunately, the creators of Loki library must be praised because this is the only line needing this correction. All the other comments described further may be interesting but they are not important.

2 Some types of magic numbers - errors or not?

Many of the problems detected by the Viva64 analyzer in Loki are because the lines seem to contain magic numbers. From the viewpoint of migration of code from a 32-bit platform on a 64-bit one, some numbers are the most dangerous. Perhaps, a programmer wants to have a definite size of a data type in some code section and this may cause a problem. Those who look through the warnings of the code analyzer often complain that they are irrelevant. Really, why should the code analyzer about number 4 in lines like these?

::Loki::ScopeGuard guard4 = ::Loki::MakeGuard( &HasFour, 1, 2, 3, 4 );
::Loki::ScopeGuard guard5 = ::Loki::MakeGuard( &HasFive, 1, 2, 3, 4, 5 );

Sometimes there appear such constructions that must be studied very thoroughly. For example, in the file SafeFormat\main.cpp we see the code:

case 'X':
    // TestCase(formatSpec, RandomInt(-10000, 10000));
    // don't test negative values on 64bit systems, because 
    // snprintf does not support 64 Bit values
    TestCase(formatSpec, 
        RandomInt( -10000 * (sizeof(size_t)>4 ? 0 : 1) , 10000));   
    break;
case 'e':

Of course, this particular use of a magic number is not an actual problem, but detecting and diagnosing magic numbers helps make the code more portable from one operating system to another and from 32 bits to 64 bits.

3 Addition of int to a pointer as a potential error

The file flex\simplestringstorage.h contains the function:

void resize(size_type newSize, E fill)
{
  const int delta = int(newSize - size());
  if (delta == 0) return;
  if (delta > 0)
  {
    if (newSize > capacity())
    {
      reserve(newSize);
    }
    E* e = &*end();
    flex_string_details::pod_fill(e, e + delta, fill);
  }
  pData_->pEnd_ = pData_->buffer_ + newSize;
}

Viva64 analyzer warns about a potential problem here:

flex_string_details::pod_fill(e, e + delta, fill);

The defect occurs in adding, delta, a variable of int type, to e, a pointer. This is a potential problem since the pod_fill function will not be able to process a data size of more than 2 GB (INT_MAX characters). This particular instance is not a no problem for there are hardly any lines that occupy more than 2 GB. Even so, it is better to change delta from an int type to a ptrdiff_t type:

const ptrdiff_t delta = ptrdiff_t(newSize - size());

4 Using int for indexing arrays is incorrect

To access very large data arrays - more than INT_MAX elements - we recommend using types ptrdiff_t or size_t instead of unsigned int or unsigned long. The file SmallObj\SmallObjBench.cpp contains a large macro LOKI_SMALLOBJ_BENCH_ARRAY in which an int is used to index an array since compilers often use 32 bit variables for ints, but must use an appropriately sized data type for size_t.

5 Right arguments of functions

The file CachedFactory\CachedFactoryTest.cpp contains the following function:

template< class Cache >
milliSec typicalUse(Cache &CC, unsigned objectKind, 
                    unsigned maxObjectCount, unsigned maxIteration)

We recommend using the size_t type for the objectKind parameter, but as this code exists only in a test project, the code does not affect the Loki library itself.

Loki library is compatible with 64-bit systems - does it mean that we can say the same about a program using it?

All the few problems of Loki library described above are easy to correct. Does that mean that if Loki does not contain any 64-bit problems (and this is true) than any application using this library is also safe from the viewpoint of 64-bit code? Unfortunately, it is not!

The point is that Loki library uses templates actively, so when the code analyzer examines a template code sometimes it cannot detect a problem. To be absolutely sure the analyzer needs to perform instancing of template classes and functions.

Let's give an example that does not relate to Loki library. Among other problems Viva64 analyzer can detect non-optimal data structures in code:

template <class T>
struct TClass
{
  int m_a;
  T m_b;
  int m_c;
};

If T has int type here the structure is optimal. But if T has size_t type the structure will occupy 24 bytes instead of possible 16 bytes. When there are many such objects, it is better to rewrite the code in this way:

template <class T>
struct TClass
{
  T m_b;
  int m_a;
  int m_c;
};

But the analyzer can check it only by instancing the template. That is, you cannot detect a problem when there is only definition of a class in the header.

Another example, again not relating to Loki, concerns type conversion:

template<typename T1, typename T2>
class TemplateClass
{
public:
	void test1()
	{
		m_a.m_value = m_b.m_value; // is there an error here?
	}
private:
	T1 m_a;
	T2 m_b;
};

In this code the error of type conversion can or cannot occur depending on the parameters with which instancing of TemplateClass template is performed. Without performing instancing, by simply analyzing the function's code, the analyzer cannot detect an error.

The two examples of template classes described above do not relate to Loki library but they are important for understanding the principles of code analyzers' operation. The peculiarity of template libraries like Loki is that even if a library is completely compatible with 64-bit systems it does not mean that the code using it is correct. This point changes completely the approach to verification of applications. Unlike common (non-template) libraries when complete compatibility with 64-bit systems is enough to make sure that the whole application is correct, in case of template libraries you cannot be sure about it.

All this means that although Loki library does not contain problems relating to 64-bit code, a user application which uses it must be tested by the code analyzer additionally to see if there are such problems, for errors depend on the parameters with which instancing of templates is performed.

Conclusion

The results of testing Loki library on compatibility with 64-bit systems performed by the workers of OOO "Program Verification Systems" Company allowed us to draw the following conclusions:

The library is fully compatible with 64-bit systems and does not contain potential errors. The errors stated in this article are likely to be corrected very easily.

Viva64 code analyzer intended for developing 64-bit applications and porting existing 32-bit ones turned out to be very efficient when testing a complicated template code of the library. It proves a very good quality of the code analyzer.

Although Loki library does not contain 64-bit problems they can occur in user applications using Loki. As the end code depends on the parameters with which templates have been instanced, it is necessary to test user applications with the help of the code analyzer. Only then you can be sure that the user application is compatible with 64-bit systems.

Acknowledgements

We would like to thank the following people who assisted us with our analysis of Loki library, or reviewed our work on Loki:

• We thank Program Verification Systems technical team who reviewed Loki library and carried out verification of its 64-bit compliance: Andrey Karpov and Evgeniy Ryzhkov.
• We thank Loki team: Andrei Alexandrescu, Peter Kümmel, and Rich Sposato for cooperation and for checking our article, editing it and providing valuable advice.
• We are glad that Rich Sposato expressed the will of working together in future and we would like to cooperate in future with the team of Loki developers.

References

1. Loki Library. http://sourceforge.net/projects/loki-lib/.
2. Viva64 Tool. http://www.viva64.com/viva64-tool.

The application ‘ffmpeg’ consist of three executables and 5 libraries. All the sources can be downloaded using the following svn command:

Ø      svn checkout svn://svn.ffmpeg.org/ffmpeg/trunk ffmpeg

 Required patch

One version which I tried ( download: svn checkout svn://svn.ffmpeg.org/ffmpeg/trunk ffmpeg –r 17944)

has a known problem with the sources. If you try to build the code, then you will get a compile time error:

 libswscale/swscale.c:488: error: ‘PIX_FMT_YUV420PLE’ undeclared

The solution is solved by copying the contents of the libswscale directory from .   http://www.ffmpeg.org/releases/ffmpeg-0.5.tar.bz2    (see http://www.ffmpeg.org/download.html)

Please Note, only the libswscale directory should be copied over the top of the existing files.

Build Instructions

Following instructions will help you build ffmpeg under a Linux system assuming that the tar ball from the download is copied to <install_directory>:

 Ø      cd  <install_directory>

 Ø      cd tar xvfz  ffmpeg.tar.gz   #Extract the tar ball to your local directory. You will find a directory tree under the name ffmpeg installed. All the required sources are installed within this tree provided that you are not enabling any additional third party libraries.

 Ø      cd ffmpeg

 Ø      ./configure –help <cr> # to show all the options available to rebuild ffmpeg. For a reference build with gcc there is no need to provide any parameters to configure. However if you would like to enable any third party libraries like ‘libfaad’, ‘libx264’ etc. then you need to add --enable-libfaad --enable-libx264 etc. as parameters to configure. If this is required make sure that you have these sources available on your development environment and that the third party libraries are rebuilt with the selected compiler / compiler options.

 Ø      ./configure <parameters as below>

 Ø      make <cr> #recommended sequence is ‘make clean’ followed by ‘make’. The rebuild will take several minutes (depending on your development environment). Two versions of each executable are produced: ex. ‘ffmpeg’ and ‘ffmpeg_g’. The ‘*_g’ contains the executable with debug information while the ‘*’ is the stripped version. In addition ‘ffplay, ffplay_g, ffserver and ffserver_g’ are produced as executables and libavutil, libavcodec, libavformat, libavdevice and libswscale are rebuilt.

 Icc build:

Depending on what version of icc you are using different configure parameters may be necessary.

 Using icc v10.1.xxx:

 Ø      ./configure cc=icc --extra-cflags=”-xL –O3” --extra-libs=-lsvml <cr> # Without linking in the extra library (libsvml.so) you get several references unresolved.

 Using icc v11.0.xxx:

 Ø      ./configure cc=icc –extra-cflags=”-xSSE3_ATOM –O3” –extra-libs=-lsvml <cr> #  The option –xSSE3_ATOM do require that you run the code on a processor which does support the ‘movbe’ instruction. If you would like to test the code on a processor not supporting the ‘movbe’ instruction you can add the option ‘-minstruction=nomovbe’ in the extra-cflag part of the command line above.
Ø      Make sure that the LD (linker) options do not contain ‘–march=generic’ in the config.mak file. This option causes an error from the compiler.

Using icc v11.1.xxx:

Ø      To avoid a run time erratum following source change is needed:   Open file ./libavcodec/x86/dsputil_mmx.c and on line #2944 insert // before || __ICC > 1100. The line is highlighted below.

Ø      After the change it will look like: #if ARCH_X86_64 || ! ( __ICC) // || __ICC > 1100

Ø      ./configure cc=icc –extra-cflags=”-xSSE3_ATOM –O3” <cr> # This simple configure does work but you get better performance if you also add the ‘--extra-lib=-lsvml’. Additional compiler switches can be used to improve the performance – for example ‘-no-prec-div’, ‘-vec-‘. As the no-prec-div has an effect on the fp calculations please refer to the compiler documentation before it is used. In addition the ‘-xSSE3_ATOM’ switch are no longer requiring a processor with ‘movbe’ support.

 Cross compilation.

It is standard practice to build the library and executables on a development machine and then copy the resultant files to the MOBLIN target.  You can use the option --enable–cross-compile in this case.

Once you have completed the configure stage you can just run the ‘make clean’ followed by ‘make’. You could expect additional warnings produced.

Building ffmpeg with third party libraries:

The application can support 21 different external 3^rd party libraries. Each of those are selected in the configure process by adding the option ‘--enable-<library-name>’.

Below is an example of using some of the different external libraries available:

 Ø      ./configure <other options as above> --enable-libfaac --enable-libfaad --enable-libmp3lame --enable-libtheora --enable-libx264 --enable-libxvid 

The invocation above assumes that you will be using 6 external 3^rd party libraries:

 - libfaac       # for example you can download ‘faac-1.28.tar.gz’ or later version from the web.

 - libfaad       # for example you can download ‘faad2-2.7.tar.gz’ or later version from the web.

 - libmp3lame # for example you can download ‘lame-398-2.tar.gz’ or later version from the web.

 - libtheora    # for example you can download ‘libtheora-1.0.tar.tar’ or later version from the web. Please note that you can not use ICC v 10.1 to rebuild this library due to a compiler issue. This has been fixed with 11.1 version of the compiler.

 - libx264      # for example you can download ‘x264-snapshot-20090117-2245.tar.bz2’ or later version from the web.

 - libxvid      # for example you can download ‘xvidcore-1.2.1.tar.gz’ or later version from the web.

Performance Notes: 

Best option combination for ICC: “-xSSE3_ATOM –O3 –vec- -static –no-prec-div –ansi_alias”. Also make sure you add –extra-libs=-lsvml in your configure invocation.

Two ways of improving the performance of ffmpeg:

1) Use the external 3rd party libraries which are supported – 20+ are available. They are optimized for their specific field. You need to select the suitable library – download the code and build them using the ICC.

2) Use PGO. Here it is important to produce a set of .dyn files for the most common conversion you will be using. The code size improves a bit and the performance also gets a boost provided that you use any of the conversions for which you generated a .dyn file. If you select a totally different conversion you actually could get a slower performance compared to both gcc and icc (general optimized version). For those who are not familiar with the PGO optimization this is a three step procedure:

a. Add the option –prof-gen to the extra-cflags section for the configure generation. Build ffmpeg.

b. Run the resulting binary on your target. Make sure you use representative input files and output formats. You may want to repeat this process several times. For each run you will have a .dyn file generated on the target. Copy these files over to your development system.

c. Now use the options –prof-use and –prof-dir <directory path where you have the .dyn files which you copied in step b> [make sure to remove –prof-gen option]. Generate a new make file with configure and build your ffmpeg. You may see a number of warnings ‘missing .dpi information for <file name.’ This is information only and can be ignored. The finally generated ffmpeg should be both smaller and faster.

Optimization Notice

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice. Notice revision #20110804