===================
Vector Builtin 関数 
===================

概要
====

NEC C/C++コンパイラのVector Builtin関数は、ベクトル型のデータをVE固有の命令を
用いて処理するための関数群です。VEのベクトルハードウェア命令に対応した関数と
数学関数に対応した関数群です。ベクトル型の各要素をマスク処理するためのベクトル
マスク型も利用できます。


ヘッダファイル
==============

Vector Builtin関数はコンパイラが自動認識しますので、一部の関数を除いて、
その呼び出しの際に特別なヘッダファイルをインクルードする必要はありません。

次の関数を呼び出す際には特別なenum型の値を指定しますので、ヘッダ **_vector.h**
をインクルードするようにしてください。

* :c:func:`__builtin_ve_vrsqrt`
* :c:func:`__builtin_ve_vfix`
* :c:func:`__builtin_ve_vrmax`
* :c:func:`__builtin_ve_vrmin`
* :c:func:`__builtin_ve_vfrmax`
* :c:func:`__builtin_ve_vfrmin`

次の例ではVector Builtin関数__builtin_ve_vfrmax()を使用しているため、
ヘッダ _vector.h をインクルードしています。__builtin_ve_vfrmax()では
_vector.hで定義されたnum型の値_FIRSTを指定しています。

.. code-block:: cpp

  #include <_vector.h>                          // _vector.h をインクルード
  typedef double vf64 __attribute__((ext_vector_type(64)));

  double vfmax(vf64 src, int *pos)
  {
      vf64    dest;

      __builtin_ve_vfrmax(dest, src, _FIRST);   // _FIRST を参照

      *pos = *((long *)(&dest[4]));
      return dest[0];
  }


ベクトルマスク型
================

ベクトルマスク型はNEC C/C++ Compiler独自の組込み型(basic types)の一つです。256個のビット列からなります。1ビット目がベクトル型の1個目の要素に対応します。

Vector Builtin関数でベクトルマスク型の引数指定することで、ベクトル型の特定の要素のみ演算対象とできます。

変数
^^^^

型名である **__vm** に続けて変数名を指定します。

.. code-block:: cpp

 __vm <変数名>


定数
^^^^

ベクトルマスク型は、要素数4の **unsigned** **long** 型のベクトル型として扱います。

.. code-block:: cpp

  __vm mask1 = { 0xFFFFFFFFFFFFFFFFUL, 0xFFFFFFFFFFFFFFFFUL,
                 0xFFFFFFFFFFFFFFFFUL, 0xFFFFFFFFFFFFFFFFUL };
                 // すべてのビットが1
  __vm mask2 = { 0xFFFFFFFFFFFFFFFFUL, 0xFFFFFFFFFFFFFFFFUL };
                 // 先頭128個のビットが1、残りは0
  __vm mask3 = { 0x8000000000000000UL };
                 // 先頭のビットが1、残りは0
                 

注意事項
^^^^^^^^

* ベクトルマスク型の配列は宣言できません。
* ベクトルマスク型の変数はOpenMPの指示句で指定できません。


Vector Builtin関数の利用
========================

Vector Builtin関数はCの関数のように記述します。第一引数、または、返却値が計算結果です。第二引数以降は関数の入力となるオペランドです。追加の引数として、ベクトルマスク型のマスク値、int型のベクトル長を指定できます。この二つの引数は関数によっては省略できることがあります。

.. code-block:: cpp

    typedef double vf64 __attribute__((ext_vector_type(64)));
    vf64    dest, src1;
    double  src2;
    __vm    mask;

    __builtin_ve_vfadd(dest, src1, src2, mask, 32);    // ベクトル加算

上記の Vector Builtin 関数の __builtin_ve_vfadd() の呼出しでは、double型を要素と
するベクトル型 src1 に、スカラ変数で double 型の src2 の値を加算しています。
加算は、ベクトル長が 32 と指定されているためベクトル型の64個の要素のうち
先頭 32 個の要素、mask の指定によりそのうちベクトル型の要素に対応する
ベクトルマスク値が 1 のものに対してのみ行われます。

.. code-block:: cpp

 typedef double vf128 __attribute__((ext_vector_type(128)));
 double sum(vf128 a)
 {
     vf128 result;
     __vm  mask = { 0 };

     mask = ~mask;                              // すべてのビットが値1のベクトルマスクを生成

     __builtin_ve_vfsum(result, a, mask, 128);  // 総和を求めるVector Builtin関数 (1)
     __builtin_ve_vfsum(result, a);             // 総和を求めるVector Builtin関数 (2)
  
     return result[0];
 }

Vector Builtin関数 (1)と(2)の計算対象、計算結果は同じです。マスク、ベクトル長
の引数を省略すると、すべてのビットが値1のマスク値が指定されたものとみなされ、
ベクトル長は引数で指定されたベクトル型の要素数と同じとみなされます。