world leader in high performance signal processing
Trace: » built-in_functions

Blackfin GCC Built-in Functions

Both VDSP and GCC supports built-in or intrinsic functions to enable efficient use of Blackfin HW resources. For example, complex fractional computing. Here are the current intrinsic functions implemented in GCC:

Fractional Value Built-in Functions in C

fract16 Built-in Functions

All the built-in functions described here are saturating unless otherwise stated. These builtins operate primarily on the fract16 type, although one of the multiplies returns a fract32. All gcc calls are prefixed by __builtin_bfin_

VDSP++ gcc arguments returns Description
add_fr1x16 add_fr1x16 (fract16 f1, fract16 f2) fract16 Performs 16-bit addition of the two input parameters (f1+f2)
sub_fr1x16 sub_fr1x16 (fract16 f1, fract16 f2) fract16 Performs 16-bit subtraction of the two input parameters (f1-f2)
mult_fr1x16 mult_fr1x16 (fract16 f1, fract16 f2) fract16 Performs 16-bit multiplication of the input parameters (f1*f2). The result is truncated to 16 bits.
multr_fr1x16 multr_fr1x16 (fract16 f1, fract16 f2) fract16 Performs a 16-bit fractional multiplication (f1*f2) of the two input parameters. The result is rounded to 16 bits. Whether the rounding is biased or unbiased depends on what the RND_MOD bit in the ASTAT register is set to.
mult_fr1x32 mult_fr1x32 (fract16 f1, fract16 f2) fract32 Performs a fractional multiplication on two 16-bit fractions, returning the 32-bit result. There will be loss of precision.
abs_fr1x16 abs_fr1x16 (fract16 f1) fract16 Returns the 16-bit value that is the absolute value of the input parameter. Where the input is 0x8000, saturation occurs and 0x7fff is returned.
min_fr1x16 min_fr1x16 (fract16 f1, fract16 f2) fract16 Returns the minimum of the two input parameters.
max_fr1x16 max_fr1x16 (fract16 f1, fract16 f2) fract16 Returns the maximum of the two input parameters.
negate_fr1x16 negate_fr1x16 (fract16 f1) fract16 Returns the 16-bit result of the negation of the input parameter (-f1). If the input is 0x8000, saturation occurs and 0x7fff is returned.
shl_fr1x16 shl_fr1x16 (fract16 src, short shft) fract16 Arithmetically shifts the src variable left by shft places. The empty bits are zero-filled. If shft is negative, the shift is to the right by abs(shft) places with sign extension.
shl_fr1x16_clip (fract16 src, short shft) fract16 Arithmetically shifts the src variable left by shft (clipped to 5 bits) places.The empty bits are zero filled. If shft is negative, the shift is to the right by abs(shft) places with sign extension.
shr_fr1x16 (fract16 src, short shft) fract16 Arithmetically shifts the src variable right by shft places with sign extension. If shft is negative, the shift is to the left by abs(shft) places, and the empty bits are zero-filled.
shr_fr1x16_clip (fract16 src, short shft) fract16 Arithmetically shifts the src variable right by shft (clipped to 5 bits) places with sign extension. If shft is negative, the shift is to the left by abs(shft) places, and the empty bits are zero-filled.
shrl_fr1x16 (fract16 src, short shft) fract16 Logically shifts a fract16 right by shft places. There is no sign extension and no saturation – the empty bits are zero-filled.
shrl_fr1x16_clip (fract16 src, short shft) fract16 Logically shifts a fract16 right by shft (clipped to 5 bits) places. There is no sign extension and no saturation – the empty bits are zero-filled.
norm_fr1x16 norm_fr1x16 (fract16 f1) int Returns the number of left shifts required to normalize the input variable so that it is either in the interval 0x4000 to 0x7fff, or in the interval 0x8000 to 0xc000. In other words, fract16 x; shl_fr1x16(x,norm_fr1x16(x)); returns a value in the range 0x4000 to 0x7fff, or in the range 0x8000 to 0xc000.

fract32 Built-in Functions

All the built-in functions described here are saturating unless otherwise stated. These built-in functions operate primarily on the fract32 type, although there are a couple of functions that convert from fract32 to fract16. All gcc calls are prefixed by __builtin_bfin_

VDSP++ gcc arguments returns Description
add_fr1x32 add_fr1x32 (fract32 f1,fract32 f2) fract32 Performs 32-bit addition of the two input parameters (f1+f2).
sub_fr1x32 sub_fr1x32 (fract32 f1,fract32 f2) fract32 Performs 32-bit subtraction of the two input parameters (f1-f2).
mult_fr1x32x32 mult_fr1x32x32 (fract32 f1,fract32 f2) fract32 Performs 32-bit multiplication of the input parameters (f1*f2). The result (which is calculated internally with an accuracy of 40 bits) is rounded (biased rounding) to 32 bits.
multr_fr1x32x32 (fract32 f1,fract32 f2) fract32 Same as mult_fr1x32x32, but with addition rounding precision
mult_fr1x32x32NS mult_fr1x32x32NS (fract32 f1, fract32 f2) fract32 Performs 32-bit non-saturating multiplication of the input parameters (f1*f2). This is somewhat faster than mult_fr1x32x32. The result (which is calculated internally with an accuracy of 40 bits) is rounded (biased rounding) to 32 bits.
abs_fr1x32 abs_fr1x32 (fract32 f1) fract32 Returns the 32-bit value that is the absolute value of the input parameter. Where the input is 0x80000000, saturation occurs and 0x7fffffff is returned.
min_fr1x32 min_fr1x32 (fract32 f1, fract32 f2) fract32 Returns the minimum of the two input parameters
max_fr1x32 max_fr1x32 (fract32 f1, fract32 f2) fract32 Returns the maximum of the two input parameters
negate_fr1x32 negate_fr1x32 (fract32 f1) fract32 Returns the 32-bit result of the negation of the input parameter (-f1). If the input is 0x80000000, saturation occurs and 0x7fffffff is returned.
shl_fr1x32 shl_fr1x32 (fract32 src, short shft) fract32 Arithmetically shifts the src variable left by shft places. The empty bits are zero filled. If shft is negative, the shift is to the right by abs(shft) places with sign extension.
shl_fr1x32_clip (fract32 src, short shft) fract32 Arithmetically shifts the src variable left by shft (clipped to 6 bits) places. The empty bits are zero filled. If shft is negative, the shift is to the right by abs(shft) places with sign extension.
shr_fr1x32 (fract32 src, short shft) fract32 Arithmetically shifts the src variable right by shft places with sign extension. If shft is negative, the shift is to the left by abs(shft) places, and the empty bits are zero-filled.
shr_fr1x32_clip (fract32 src, short shft) fract32 Arithmetically shifts the src variable right by shft (clipped to 6 bits) places with sign extension. If shft is negative, the shift is to the left by abs(shft) places, and the empty bits are zero-filled.
sat_fr1x32 (fract32 f1) fract16 If f1>0x00007fff, it returns 0x7fff. If f1<0xffff8000, it returns 0x8000. Otherwise, it returns the lower 16 bits of f1.
round_fr1x32 (fract32 f1) fract16 Rounds the 32-bit fract to a 16-bit fract using biased rounding.
norm_fr1x32 norm_fr1x32 (fract32) int Returns the number of left shifts required to normalize the input variable so that it is either in the interval 0x40000000 to 0x7fffffff, or in the interval 0x80000000 to 0xc0000000. In other words, fract32 x; shl_fr1x32(x,norm_fr1x32(x)); returns a value in the range 0x40000000 to 0x7fffffff, or in the range 0x80000000 to 0xc0000000.
trunc_fr1x32 (fract32 f1) fract16 Returns the top 16 bits of f1—it truncates f1 to 16 bits.

fract2x16 Built-in Functions

All built-in functions described here are saturating unless otherwise stated. These built-ins operate primarily on the fract2x16 type, although there are composition and decomposition functions for the fract2x16 type, multiplies that return fract32 results, and operations on a single fract2x16 pair that return fract16 types. The notation used to represent two fract16 values packed into a fract2x16 is {a,b}, where “a” is the fract16 packed into the high half, and “b” is the fract16 packed into the low half. All gcc calls are prefixed by __builtin_bfin_

VDSP++ gcc arguments returns Description
compose_fr2x16 (fract16 f1, fract16 f2) fract2x16 Takes two fract16 values, and returns a fract2x16 value.
high_of_fr2x16 fract2x16 f) fract16 Takes a fract2x16 and returns the “high half” fract16.
low_of_fr2x16 (fract2x16 f) fract16 Takes a fract2x16 and returns the “low half” fract16
add_fr2x16 add_fr2x16 (fract2x16 f1, fract2x16 f2) fract2x16 Adds two packed fracts.
sub_fr2x16 sub_fr2x16 (fract2x16 f1, fract2x16 f2) fract2x16 Subtracts two packed fracts.
mult_fr2x16 mult_fr2x16 (fract2x16 f1, fract2x16 f2) fract2x16 Multiplies two packed fracts. Truncates the results to 16 bits.
multr_fr2x16 multr_fr2x16 (fract2x16 f1, fract2x16 f2) fract2x16 Multiplies two packed fracts. Rounds the result to 16 bits. Whether the rounding is biased or unbiased depends on what the RND_MOD bit in the ASTAT register is set to.
negate_fr2x16 negate_fr2x16 (fract2x16 f1) fract2x16 Negates both 16-bit fracts in the packed fract. If one of the fract16 values is 0x8000, saturation occurs and 0x7fff is the result of the negation.
shl_fr2x16 shl_fr2x16 (fract2x16 f1, short shft) fract2x16 Arithmetically shifts both fract16s in the fract2x16 left by shft places, and returns the packed result. The empty bits are zero-filled. If shft is negative, the shift is to the right by abs(shft) places with sign extension.
shl_fr2x16_clip (fract2x16 f1, short shft) fract2x16 Arithmetically shifts both fract16s in the fract2x16 left by shft (clipped to 5 bits) places, and returns the packed result. The empty bits are zero filled. If shft is negative, the shift is to the right by abs(shft) places with sign extension.
shr_fr2x16 (fract2x16 f1, short shft) fract2x16 Arithmetically shifts both fract16s in the fract2x16 right by shft places with sign extension, and returns the packed result. If shft isnegative, the shift is to the left by abs(shft) places and the empty bits are zero-filled.
shr_fr2x16_clip (fract2x16 f1, short shft) fract2x16 Arithmetically shifts both fract16s in the fract2x16 right by shft (clipped to 5 bits) places with sign extension, and returns the packed result. If shft is negative, the shift is to the left by abs(shft) places and the empty bits are zero-filled.
shrl_fr2x16 (fract2x16 f1, short shft) fract2x16 Logically shifts both fract16s in the fract2x16 right by shft places. There is no sign extension and no saturation – the empty bits are zero-filled.
shrl_fr2x16_clip (fract2x16 f1, short shft) fract2x16 Logically shifts both fract16s in the fract2x16 right by shft places (clipped to 5 bits). There is no sign extension and no saturation – the empty bits are zero-filled.
abs_fr2x16 abs_fr2x16 (fract2x16 f1) fract2x16 Returns the absolute value of both fract16s in the fract2x16.
min_fr2x16 min_fr2x16 (fract2x16 f1, fract2x16 f2) fract2x16 Returns the minimums of the two pairs of fract16s in the two input fract2x16s.
max_fr2x16( max_fr2x16 fract2x16 f1, fract2x16 f2) fract2x16 Returns the maximums of the two pairs of fract16s in the two input fract2x16s.
sum_fr2x16 sum_fr2x16 (fract2x16 f1) fract16 Performs a sideways addition of the two fract16s in f1.
add_as_fr2x16 (fract2x16 f1, fract2x16 f2) fract2x16 Performs a vector add/subtract on the two input fract2x16s.
add_sa_fr2x16( fract2x16 f1, fract2x16 f2) fract2x16 Performs a vector subtract/add on the two input fract2x16s.
diff_hl_fr2x16 diff_hl_fr2x16 (fract2x16 f1) fract16 Takes the difference (high-low) of the two fract16s in the fract2x16.
diff_lh_fr2x16 diff_lh_fr2x16 (fract2x16 f1) fract16 Takes the difference (low-high) of the two fract16s in the fract2x16.
mult_ll_fr2x16 (fract2x16 f1, fract2x16 f2) fract32 Cross-over multiplication. Multiplies the low half of f1 with the low half of f2.
mult_hl_fr2x16 (fract2x16 f1, fract2x16 f2) fract32 Cross-over multiplication. Multiplies the high half of f1 with the low half of f2.
mult_lh_fr2x16 (fract2x16 f1, fract2x16 f2) fract32 Cross-over multiplication. Multiplies the low half of f1 with the high half of f2.
mult_hh_fr2x16 (fract2x16 f1, fract2x16 f2) fract32 Cross-over multiplication. Multiplies the high half of f1 with the high half of f2.

Converting Between Fractional and Floating-Point Values

The VisualDSP++ run-time libraries contain high-level support for converting between fractional and floating-point values. The include file fract2float_conv.h defines functions which perform conversions between fract16, fract32, and float types.

VDSP++ gcc arguments returns Description
fr16_to_fr32 fract16 fract32 Deposits a fract16 to make a fract32
fr32_to_fr16 fract32 fract16 Truncates a fract32 to make a fract16
float_to_fr32 float fract32 Converts a float to fract32
float_to_fr16 float fract16 Converts a float to fract16
fr16_to_float fract16 float Converts a fract16 to float
fr32_to_float fract32 float Converts a fract32 to float

ETSI Support

VisualDSP++ for Blackfin processors provides European Telecommunications Standards Institute (ETSI) support routines in it's libetsi*.dlb library. The GNU Compiler Collection does not support this.

Viterbi History and Decoding Functions

VisualDSP++ for Blackfin processors provides four Viterbi functions allowing for left or right shifting. The GNU Compiler Collection does not support this.

Circular Buffer Built-In Functions

The circptr built-in allows the user to implement a circular buffer in C or C++ code using the Blackfin's dedicated circular buffer registers.

VDSP++ gcc arguments returns Description
circptr __builtin_bfin_circptr (void *ptr, long incr, void * base, unsigned long buflen) void* ptr = __builtin_bfin_circptr(ptr, sizeof *ptr, buf, sizeof buf); returns an incremented pointer within the buffer, looping round if the end of the buffer is reached.

Endian-Swapping Intrinsics

The following two intrinsics are available for changing data from big-endian to little-endian, or vice versa.

VDSP++ gcc arguments returns Description
byteswap4 (int) int byteswap4(0x12345678) returns 0x78563412.
byteswap2 (short) short byteswap2(0x1234) returns 0x3412.

System Built-In Functions

The following built-in functions allow access to system facilities on Blackfin processors. All gcc calls are prefixed by __builtin_bfin_

VDSP++ gcc arguments returns Description
idle (void) void Places the processor in idle mode.
csync csync (void) void Processor core-only synchronization — it flushes the pipeline and store buffers.
ssync ssync (void) void System synchronization, and also waits for an ACK instruction from the system bus.

Compiler Performance Built-in Functions

These functions provide the compiler with information about the expected behavior of the program. You can use these built-in functions to tell the compiler which parts of the program are most likely to be executed; the compiler can then arrange for the most common cases to be those that execute most efficiently.

VDSP++ arguments returns gcc arguments returns Description
expected_true (int cond) int __builtin_expect (long exp, long c) long Tell the compiler this part of the program is likely to be executed.
expected_false (int cond) int !__builtin_expect (long exp, long c) long Tell the compiler this part of the program is not likely to be executed.

Packed 16-Bit Integer Built-In Functions

The compiler provides built-in functions that manipulate and perform basic arithmetic functions on two 16-bit integers packed into a single 32-bit type, int2x16. Use of the built-in functions produce optimal code sequences, using vectorised operations where possible.

VDSP++ gcc arguments returns Description
compose_i2x16 compose_2x16 (short _x, short _y) int2x16
high_of_i2x16 extract_hi (int2x16 _x) short
low_of_i2x16 extract_lo (int2x16 _x) short

Complex number Built-In Functions

The following functions are used to do multiplication for complex numbers. The high half of the 2×16 vector argument is assigned to imaginary part, and the low half is assigned to real part. All gcc calls are prefixed by __builtin_bfin_

VDSP++ gcc arguments returns Description
cmlt_fr16 cmplx_mul (fract2x16 f1, fract2x16 f2) fract2x16 Interpret 2×16 vector arguments as complex numbers and multiplies them
cmac_fr16 cmplx_mac (fract2x16 f1, fract2x16 f2, fract2x16 f3) fract2x16 Interpret 2×16 vector arguments as complex numbers, multiply the latter two arguments and plus with the first one
cmsu_fr16 cmplx_msu (fract2x16 f1, fract2x16 f2, fract2x16 f3) fract2x16 Interpret 2×16 vector arguments as complex numbers, multiply the latter two arguments and then be subtracted by the first one

Unknown

gcc built ins that have no VDSP function…

All gcc calls are prefixed by __builtin_bfin_

VDSP++ gcc arguments returns Description
dspaddsubsat (fract2x16 f1, fract2x16 f2) fract2x16 Performs 16-bit addition of the high half of the two input parameters and 16-bit subtraction of the low half of the two input parameters. Saturation applies.
dspsubaddsat (fract2x16 f1, fract2x16 f2) fract2x16 Performs 16-bit subtraction of the high half of the two input parameters and 16-bit addition of the low half of the two input parameters. Saturation applies.
mulhisill (fract2x16 f1, fract2x16 f2) int Performs 16-bit multiplication of the low half of the first parameters and the low half of the second parameters
mulhisihl (fract2x16 f1, fract2x16 f2) int Performs 16-bit multiplication of the high half of the first parameters and the low half of the second parameters
mulhisilh (fract2x16 f1, fract2x16 f2) int Performs 16-bit multiplication of the low half of the first parameters and the high half of the input parameters
mulhisihh (fract2x16 f1, fract2x16 f2) int Performs 16-bit multiplication of the high half of the first parameters and the high half of the input parameters
lshl_fr2x16 (fract2x16 f1, short shft) fract2x16 Vector shift (with ”(V)” modifier), either to the left or to the right.

An example of using these primitives can be applied to optimizing an FFT. example-builtin