Skip to content

Commit 5146bed

Browse files
gregrodgersgregrodgers
committed
revamp of examples. There still is some work todo. But I wanted to get the framework out so we can distribute the work
1 parent 0222a78 commit 5146bed

File tree

131 files changed

+5040
-1186
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

131 files changed

+5040
-1186
lines changed

‎examples/Makefile

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# MIT License
2+
#
3+
# Copyright (c) 2024 Advanced Micro Devices, Inc. All rights reserved.
4+
#
5+
# Permission is hereby granted, free of charge, to any person obtaining a copy
6+
# of this software and associated documentation files (the "Software"), to deal
7+
# in the Software without restriction, including without limitation the rights
8+
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
# copies of the Software, and to permit persons to whom the Software is
10+
# furnished to do so, subject to the following conditions:
11+
#
12+
# The above copyright notice and this permission notice shall be included in all
13+
# copies or substantial portions of the Software.
14+
#
15+
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
# SOFTWARE.
22+
#
23+
mkfile_dir := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))
24+
include $(mkfile_dir)inc/find_gpu_and_install_dir.mk
25+
ifneq ($(CURDIR)/,$(mkfile_dir))
26+
_in_prefix := $(mkfile_dir)
27+
endif
28+
29+
ifeq ($(LLVM_COMPILER_NAME),clang)
30+
CATEGORIES := \
31+
$(_in_prefix)openmp \
32+
$(_in_prefix)fortran \
33+
$(_in_prefix)hipfort \
34+
$(_in_prefix)hip
35+
endif
36+
ifeq ($(LLVM_COMPILER_NAME),AMD)
37+
CATEGORIES := \
38+
$(_in_prefix)openmp \
39+
$(_in_prefix)fortran \
40+
$(_in_prefix)hipfort \
41+
$(_in_prefix)hip \
42+
$(_in_prefix)stdpar
43+
endif
44+
ifeq ($(LLVM_COMPILER_NAME),AOMP)
45+
CATEGORIES := \
46+
$(_in_prefix)openmp \
47+
$(_in_prefix)fortran \
48+
$(_in_prefix)hipfort \
49+
$(_in_prefix)hip \
50+
$(_in_prefix)stdpar
51+
endif
52+
53+
all: $(CATEGORIES)
54+
55+
clean: TARGET=clean
56+
clean: all
57+
run: TARGET=run
58+
run: all
59+
60+
$(CATEGORIES):
61+
@echo
62+
@echo "#--------------------------------------------------------------"
63+
@echo "# ===== START OF COMPILER EXAMPLES CATEGORY $(@) ===== "
64+
@echo "#--------------------------------------------------------------"
65+
ifeq ($(CURDIR)/,$(mkfile_dir))
66+
$(MAKE) --no-print-directory -C $@ $(TARGET)
67+
else
68+
$(MAKE) --no-print-directory -f $@/Makefile $(TARGET)
69+
endif
70+
71+
.PHONY: all clean $(CATEGORIES)

‎examples/README.md

Lines changed: 94 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,79 +1,134 @@
1-
Examples
2-
========
1+
Compiler Examples
2+
=================
33

44
The LLVM compiler supports several accelerated programming models
55
including OpenMP, HIP, opencl, stdpar, hipfort, raja, and kokkos.
66
Acceleration with OpenMP is available for FORTRAN, c, and C++.
7-
These examples demonstrate how to use the LLVM compiler to compile and execute
8-
applications using these different programming models and various utilities to
9-
support development.
7+
These Compiler examples demonstrate how to use the LLVM compiler to compile,
8+
link, and execute applications using different programming models and
9+
various utilities to support development. Each Compiler example uses
10+
'make' to clearly show the full commands to compile, link, and execute
11+
an application. The execution of make will also show any supporting commands
12+
and environment variable settings needed to support the example.
1013

11-
The examples are divided into categories. These categories are:
14+
## Compiler Example Categories
15+
16+
The Compiler examples are divided into categories:
1217

1318
- [OpenMP](openmp/README.md) C++ and c examples of OpenMP target offload
1419
- [FORTRAN](fortran) FORTRAN examples of OpenMP target offload
1520
- [HIP](hip/README.md) Acceleration with HIP
21+
- [stdpar](stdpar) C++ stdpar examples
1622
- [Raja](raja/README.md) Examples that use the RAJA programming model
1723
- [Kokkos](kokkos) Examples that use the kokkos programming model
1824
- [tools](tools) Examples on how to use profiling, debug, and address sanitizer tools
19-
- [stress](stress) Examples that are complex or stress resources
25+
- [stress](stress) Examples that are complex or stress resources. CI is not run on these examples
26+
- [hipfort](hipfort) FORTRAN examples that use FORTRAN HIP bindings
2027

2128
Eventually we will add these categories:
2229

23-
- [stdpar](stdpar) C++ stdpar examples
2430
- [opencl](opencl) Examples of offloading with OpenCL
25-
- [hipfort](hipfort) FORTRAN examples that use FORTRAN HIP bindings
2631

2732
Each category is a directory and each example is a subdirectory of the category directory.
28-
Typically there is a Makefile for each example. That Makefile can be executed with either update
29-
access to the example directory or in a different directory since examples typically exist in a
30-
read-only installation directory. These commands show how to run an example from
31-
a writable tmp directory.
33+
34+
35+
## Using Compiler Example Makefiles
36+
37+
There is a Makefile for each Compiler example. The Makefile(s) can be executed
38+
with update access to the example directory where the Makefile and sources are
39+
found, "in-tree", OR from a different directory, "out-of-tree".
40+
These commands demonstrate how to test the example "in-tree":
41+
```
42+
cd openmp/veccopy
43+
make run
44+
45+
```
46+
An "out-of-tree" test is useful when examples are stored in a read-only
47+
directory such as the ROCm installation directory. For example, to run the
48+
veccopy example "out-of-tree" from a new /tmp directory run these commands:
3249
```
3350
mkdir /tmp/demo ; cd /tmp/demo
34-
EXROOT=/opt/rocm/share/openmp-extras/examples # The examples base directory.
51+
EXROOT=/opt/rocm/share/examples/Compiler # The examples base directory.
3552
make -f $EXROOT/openmp/veccopy/Makefile run
3653
```
3754
The above will compile and execute the openmp/veccopy example.
38-
The Makefile will print the compile and execute commands to your console.
55+
The Makefile will print the compile and execute commands to the console.
56+
57+
If you plan to copy the sources for these examples, be sure to copy
58+
the entire Compiler examples directory. For example:
59+
```
60+
EXROOT=/opt/rocm/share/examples/Compiler # The examples base directory.
61+
cp -rp $EXROOT /tmp
62+
cd /tmp/Compiler/openmp/veccopy
63+
make run
64+
```
65+
## Setting LLVM_INSTALL_DIR and LLVM_GPU_ARCH
3966

40-
Each Makefile typically includes the common Makefile helper file
41-
[Makefile.find_gpu_and_install_dir](Makefile.find_gpu_and_install_dir).
42-
This include file finds the LLVM compiler and sets the environment
43-
variable `LLVM_INSTALL_DIR` if not already preset by the user.
44-
If not preset, or the value of `LLVM_INSTALL_DIR` specifies a nonexistant directory,
45-
the Makefile searches this list of directories:
67+
Each Makefile includes the common Makefile helper file
68+
[inc/find_gpu_and_install_dir.mk](inc/find_gpu_and_install_dir.mk).
69+
This "include-file" finds the LLVM compiler and sets environment
70+
variable `LLVM_INSTALL_DIR`, if not already preset by the user.
71+
If not preset, or `LLVM_INSTALL_DIR` specifies a nonexistant directory,
72+
the include-file searches this list of directories to set 'LLVM_INSTALL_DIR':
4673

4774
```
4875
/opt/rocm/lib/llvm /usr/lib/aomp ./../../../llvm ~/rocm/aomp
4976
```
77+
If no LLVM installation is found, all Compile examples will fail.
78+
Therefore, it is recommended that users of these examples preset `LLVM_INSTALL_DIR`
79+
to use a compiler other than the last installed ROCm compiler typically
80+
found at /opt/rocm/lib/llvm.
5081

51-
The Makefile sets `LLVM_INSTALL_DIR` to the first directory it finds in the above list.
52-
It is recommended that users of these examples preset `LLVM_INSTALL_DIR`
53-
if they want to demo the compiler with something other than the last
54-
installed ROCm compiler.
55-
56-
The include file then determines if there is an active GPU and
57-
the GPU architecture (eg. gfx940, sm_70, etc).
58-
It first checks for an active amdgpu kernel module
59-
If there is an active amdgpu kernel, the LLVM compiler utility
60-
`$(LLVM_INSTALL_DIR)/bin/amdgpu-arch` is used to set
61-
the value `LLVM_GPU_ARCH` which instructs the compiler which GPU to compile for.
82+
The include-file then searches for an active GPU to set `LLVM_GPU_ARCH`
83+
(e.g. gfx90a, gfx940, sm_70, etc).
84+
Each example uses the value of `LLVM_GPU_ARCH` to instruct the compiler
85+
which GPU to use for compilation. If `LLVM_GPU_ARCH` is not preset,
86+
the include-file first checks for an active amdgpu kernel module.
87+
If there is an active amdgpu kernel module, the include-file calls the LLVM compiler utility
88+
`$(LLVM_INSTALL_DIR)/bin/amdgpu-arch` to set the value of `LLVM_GPU_ARCH`.
6289
If no active amdgpu kernel module is found, the include file looks for an nvidia PCI
63-
device and then uses the compiler utility `$(LLVM_INSTALL_DIR)/bin/amdgpu-arch`
90+
device and then uses the compiler utility `$(LLVM_INSTALL_DIR)/bin/nvptx-arch`
6491
to set the value `LLVM_GPU_ARCH`.
92+
If there are no active GPUs or the examples are being run for compile-only,
93+
users may preset `LLVM_GPU_ARCH` to avoid this search.
94+
95+
If `LLVM_GPU_ARCH` is not preset and no GPUs are found, all Compile examples will fail.
96+
97+
## Makefile Targets
6598

66-
If no LLVM installation or GPU could be found, the example Makefile will fail.
67-
So if you want to demo the compiler with something other than the last
68-
installed ROCm compiler (which is typically found at /opt/rocm/lib/llvm),
69-
then it is recommended that users preset LLVM_INSTALL_DIR.
99+
The default for each Makefile is to compile and link the example binary.
100+
The target "run" will compile, link, and execute the example.
101+
The target "clean" will remove all generated files by the Makefile.
70102

71-
There are often other make targets to show different ways to build the binary.
103+
There are often other make targets. To show different ways to build the binary.
72104
E.g. to run with some debug output set `OFFLOAD_DEBUG` variable:
73105

74106
```
75107
env OFFLOAD_DEBUG=1 make
76108
env OFFLOAD_DEBUG=1 make run
77109
```
78110

79-
Run ```make help``` to see all the possible demos of each example.
111+
Run ```make help``` to see various demos of each example.
112+
113+
## Hierarchical Makefiles
114+
115+
Each category has a Makefile that will build and run all the examples for that category.
116+
For example the Makefile for openmp is [openmp/Makefile](here).
117+
To test all the openmp examples with the AOMP compiler run these commands:
118+
```
119+
EXROOT=~/git/rocm-examples/Compiler # The examples base directory.
120+
cd $EXROOT/openmp
121+
env LLVM_INSTALL_DIR=$AOMP make run
122+
```
123+
The Compiler Examples has a root [Makefile](Makefile) that can be used to build and run all examples.
124+
To test all Compiler Examples with the AOMP compiler run these commands:
125+
```
126+
EXROOT=~/git/rocm-examples/Compiler # The examples base directory.
127+
cd $EXROOT
128+
env LLVM_INSTALL_DIR=$AOMP make run
129+
```
130+
131+
132+
## Contributions
133+
134+
If you want to contribute a Compiler example, please read these [rules](inc/contribute_rules.md).

‎examples/fortran/Makefile

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# License
2+
#
3+
# Copyright (c) 2024 Advanced Micro Devices, Inc. All rights reserved.
4+
#
5+
# Permission is hereby granted, free of charge, to any person obtaining a copy
6+
# of this software and associated documentation files (the "Software"), to deal
7+
# in the Software without restriction, including without limitation the rights
8+
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
# copies of the Software, and to permit persons to whom the Software is
10+
# furnished to do so, subject to the following conditions:
11+
#
12+
# The above copyright notice and this permission notice shall be included in all
13+
# copies or substantial portions of the Software.
14+
#
15+
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
# SOFTWARE.
22+
#
23+
mkfile_dir := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))
24+
include $(mkfile_dir)../inc/find_gpu_and_install_dir.mk
25+
ifneq ($(CURDIR)/,$(mkfile_dir))
26+
_in_prefix := $(mkfile_dir)
27+
endif
28+
29+
ifeq ($(LLVM_COMPILER_NAME),clang)
30+
fortran_examples := \
31+
$(_in_prefix)bigloop \
32+
$(_in_prefix)helloworld \
33+
$(_in_prefix)helloAcceptance \
34+
$(_in_prefix)gdb_simple \
35+
$(_in_prefix)simple_offload
36+
$(info TRUNK DOES NOT YET SUPPORT EXAMPLE declare_target )
37+
$(info TRUNK DOES NOT YET SUPPORT EXAMPLE fortran_hip_interop)
38+
else
39+
fortran_examples := \
40+
$(_in_prefix)bigloop \
41+
$(_in_prefix)helloworld \
42+
$(_in_prefix)helloAcceptance \
43+
$(_in_prefix)gdb_simple \
44+
$(_in_prefix)simple_offload
45+
endif
46+
47+
all: $(fortran_examples)
48+
49+
clean: TARGET=clean
50+
clean: all
51+
run: TARGET=run
52+
run: all
53+
54+
$(fortran_examples):
55+
@echo
56+
@echo "# ========> Compiler example: $@"
57+
ifeq ($(CURDIR)/,$(mkfile_dir))
58+
$(MAKE) --no-print-directory -C $@ $(TARGET)
59+
else
60+
$(MAKE) --no-print-directory -f $@/Makefile $(TARGET)
61+
endif
62+
63+
.PHONY: all clean $(fortran_examples)

0 commit comments

Comments
 (0)