1

VSIPL Forum

Common Programming Pitfalls

Gary BoudreauxAnthony Skjellum

Puri Bangalore

MPI Software Technology Inc.VSI/Pro

2

VSIPL Forum

Overview

• Initialization Errors• Function Naming Errors• VSIPL Structure• Block Errors• Library modes• Data Memory Allocation• Complex Data Storage• Other Issues• VSI/Pro Users Pitfalls

3

VSIPL Forum

Initialization Errors

• VSIPL main header file vsip.h must be included in allprograms using the VSIPL library#include <vsip.h>

• A VSIPL program must initialize the VSIPL library with a callto vsip_init before calling any other VSIPL function, andmust call vsip_finalize before terminating.

• EXAMPLE#include <vsip.h>int main() {

/* No VSIPL calls permitted here….*/vsip_init ((void *)0);/* All VSIPL calls should go here….*/vsip_finalize ((void *)0);/* No VSIPL calls permitted here before another vsip_init */return 0;

}

4

VSIPL Forum

Function Naming Errors

• No user functions named vsip_ or vsipl_• The VSIPL function name consists of the base

name plus a precision affix that specifies the dataprecision

• Example vsip_dsmag_pwhere _p represents the data type and can be anyof the supported data types_f (float) _d(double) _i(integer) _c(char)

• Precision depth qualifiers (real or complex) andshape qualifiers (scalar, vector, matrix, tensor)are placed as a prefix in the front of the root nameexample vsip_cvmag_f

5

VSIPL Forum

VSIPL Program Structure

Many problems occur from not using the proper program structure.

6

VSIPL Forum

Block Errors

• Block - must be valid, array size must be positive• Cblockbind - data1 valid and non-null if data2 is

non-null• Rebind and Release - block not derived from

complex block• Stride, length, and offset must not exceed bounds

of data array• Bind multiple views to a block that overlap and

then use the views at the same time• Letting memory of a block go out of scope or de-

allocating while block is still active

7

VSIPL Forum

VSIPL Program Initialization

Initialize VSIPL library

Create block(s)

Create view(s) & bind view(s) to block(s)

Create object(s) for filter(s), FFT(s), solver(s), etc.

8

VSIPL Forum

VSIPL Program Body

Obtain Data

Bind (or rebind) blocks(s) to data

Admit (or readmit) block to VSIPL data space

Operate on data using views(s)

Release block(s) to user data space

9

VSIPL Forum

VSIPL Program Finalization

Destroy object(s) for filter(s), FFT(s),solver(s), etc.

Destroy view(s)

Release and destroy block(s)

Finalize VSIPL library

1 0

VSIPL Forum

Library Modes

• VSIPL supports two implementation modes

• Performance – production library

• Debug/development – development library

• Link with the appropriate library when building

user applications

1 1

VSIPL Forum

Data Memory Allocation

• Data exits in two logical data spaces

• Admitted – VSIPL space

• You can call VSIPL functions on data that isadmitted to VSIPL (no user access)

• Release – User space

• No VSIPL calls for data released from VSIPLspace (out of VSIPL access)

• Data can be moved between spaces (possibleperformance penalties)

1 2

VSIPL Forum

Complex Data Storage

• Implementation dependent, VSIPL standard supportsboth interleaved and split

• Interleaved: The user data array is contiguousmemory of type vsip_scalar_p. The complex elementis two consecutive elements of type vsip_scalar_p .The first element is the real component and thesecond is the imaginary component

• Split: The user data array consists of two contiguousmemory regions of equal length, each of typevsip_scalar_p. The real and the imaginary region aredetermined when the memory is bound to the block.A complex element consists of correspondingelements from the real and imaginary regions

1 3

VSIPL Forum

Other Issues

• Use vsip_get and vsip_put to access data

• User accesses data in blocks through views

• I/O - INPUT requires the user to first bind the userdata to a block and then admit to VSIPL

• I/O – OUTPUT requires the user to release theblock and then access the user data

1 4

VSIPL Forum

C and Process-Oriented Programming Errors that Impact

VSIPL Programming

• Pointer errors can cause non-local space and time errorsinside the VSIPL implementation

• Large variables on the stack can lead to stack overflows• Explicit coercion of pointers can lead to non-obvious bugs• Because implementations rely on alignment, it is important

to be sure that dynamically created objects meet theminimal alignment requirements, compatible with what thecompiler and VSIPL library require

• Floating point state, exceptions may be assumed by thelibrary; if changed by the user, unpredictable results willgenerally occur

• Multiple compiler binaries may appear to work together, orcross-platform, but may not really be fully compliant

• Floating point support may not work for all tasks in all OS’s(e.g., VxWorks 5.4 / Tornado 2.0)

1 5

VSIPL Forum

Observed Pitfalls From VSI/ProUsers

• No init/finalize -- necessary for VSI/Pro

• Improper destroying of blocks and views

• Compile errors ( ex. –mstrict_align ) mostcommon

• Not stating correct block size -- bind toview then overshoot end block

• Enable Altivec ( board issue)

1 6

VSIPL Forum

Summary

• Proper library initialization• VSIPL naming convention• Proper VSIPL structure• Block and memory allocation• Complex data storage• Users experience compile errors