README
1OpenPA v1.0.3
2-------------
3
4The goal of this project is to provide an open source, highly-portable
5library that provides atomic primitives (and related constructs) for
6high performance, concurrent software. This project is a collaboration
7between the Mathematics and Computer Science (MCS) division at Argonne
8National Laboratory (ANL) and the HDF Group. The code was originally
9derived from work on the MPICH2 project.
10
11Project documentation and bug tracking can be found at:
12
13 https://trac.mcs.anl.gov/projects/openpa/
14
15If you would like to email questions or discuss topics related to OpenPA
16you can send mail to opa-discuss@lists.mcs.anl.gov.
17
18
19Building
20--------
21
22If you checked out the project from source control then you will need to
23generate configure files and makefiles with autogen.sh:
24
25% ./autogen.sh
26
27Otherwise, the build procedure is basically the same as any other
28autoconfiscated software:
29
30% ./configure [configure_args]
31% make
32% make install
33
34OpenPA does support Microsoft Windows but the build system
35infrastructure is unfortunately not yet in place for general use.
36
37
38Supported Platforms
39-------------------
40
41The following header files in the src/primitives directory support the
42listed platforms:
43opa_gcc_ia64.h - GCC on Intel's IA64 (Itanium) architecture
44opa_gcc_intel_32_64.h - GCC (and some GCC-like compilers) on x86 and
45 x86_64 architectures
46opa_gcc_intrinsics.h - GCC on many other platforms. These use compiler
47 intrinsics which are not always implemented on
48 every platform
49opa_gcc_ppc.h - GCC and IBM's XLC on PowerPC 4xx and 970 systems.
50 Specifically, this supports the modified-PPC440
51 processor in IBM's Blue Gene/P supercomputers and most
52 64-bit PPC machines such as BG/P login nodes and G5
53 Macs.
54opa_gcc_sicortex.h - GCC on SiCortex machines. This is a MIPS 5K based
55 architecture, so it may work on similar platforms.
56opa_nt_intrinsics.h - Windows support. These use compiler intrinsics
57 available in Microsoft's Visual Studio compiler.
58opa_sun_atomic_ops.h - Solaris support. This uses Solaris' built-in
59 atomic operations library. Tested on a Niagara
60 (T5240) machine with Solaris (s10s_u4wos_12b).
61
62We also support two pseudo-platforms:
63
64opa_by_lock.h - Used when you specify "--with-atomic-primitives=no" or when
65 auto-detecting the primitive implementation and lock-based fall
66 back is selected. This uses pthread mutexes to emulate the
67 atomic behavior. This option typically has dramatically slower
68 performance on most platforms where native primitives are
69 available. You should usually only use it for testing or on
70 platforms where pthreads are available but no native primitives
71 are currently implemented. The library initialization function
72 *must* be called when using this primitives implementation.
73opa_unsafe.h - Used when you specify "--with-atomic-primitives=unsafe". This
74 can be used to improve performance in code that uses OPA already
75 and is conditionally compiled to be single-threaded without
76 having to modify said code. It is also potentially useful for
77 meta-testing to ensure that any threading tests you might have
78 will catch bugs when you have a broken atomics implementation.
79 The OPA test suite itself fails spectacularly when compiled this
80 way. This header can also be used by defining the preprocessor
81 macro OPA_USE_UNSAFE_PRIMITIVES prior to including
82 opa_primitives.h.
83
84Known Issues
85------------
86
87* One known issue is that the gcc atomic intrinsics aren't supported by
88 compilers prior to GCC 4.1. In particular the default Mac OS X compiler is
89 gcc 4.0.1 so these result in a linker error when using this set of
90 primitives. The good news is that on OSX/Intel we use native inline
91 assembly anyway, so this isn't a big problem.
92* The PGI compilers currently are not supported. There is at least one known
93 bug in the PGI compiler's handling of of inline assembly for which we are
94 awaiting a fix from PGI. Once a fixed version of the compiler is available
95 this issue should be rectified in an upcoming release.
96* As mentioned earlier, Windows is supported but the build system is not
97 yet present.
98* We've had reports of trouble with older IA64 machines running GCC 3.2.2.
99 Unfortunately we don't have access to a machine with this configuration so we
100 have been unable to debug and fix the problem. Patches and detailed bug
101 reports on this issue are very welcome.
102
103