1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
# README for the matrix-vector multiplication demo code
## Synopsis
This program implements the multiplication of a matrix and a vector. It is
written in C and has been parallelized using the Pthreads parallel programming
model. Each thread gets assigned a contiguous set of rows of the matrix to
work on and the results are stored in the output vector.
The code initializes the data, executes the matrix-vector multiplication, and
checks the correctness of the results. In case of an error, a message to this
extent is printed and the program aborts. Otherwise it prints a one line
message on the screen.
## About this code
This is a standalone code, not a library. It is meant as a simple example to
experiment with gprofng.
## Directory structure
There are four directories:
1. `bindir` - after the build, it contains the executable.
2. `experiments` - after the installation, it contains the executable and
also has an example profiling script called `profile.sh`.
3. `objects` - after the build, it contains the object files.
4. `src` - contains the source code and the make file to build, install,
and check correct functioning of the executable.
## Code internals
This is the main execution flow:
* Parse the user options.
* Compute the internal settings for the algorithm.
* Initialize the data and compute the reference results needed for the correctness
check.
* Create and execute the threads. Each thread performs the matrix-vector
multiplication on a pre-determined set of rows.
* Verify the results are correct.
* Print statistics and release the allocated memory.
## Installation
The Makefile in the `src` subdirectory can be used to build, install and check the
code.
Use `make` at the command line to (re)build the executable called `mxv-pthreads`. It will be
stored in the directory `bindir`:
```
$ make
gcc -o ../objects/main.o -c -g -O -Wall -Werror=undef -Wstrict-prototypes main.c
gcc -o ../objects/manage_data.o -c -g -O -Wall -Werror=undef -Wstrict-prototypes manage_data.c
gcc -o ../objects/workload.o -c -g -O -Wall -Werror=undef -Wstrict-prototypes workload.c
gcc -o ../objects/mxv.o -c -g -O -Wall -Werror=undef -Wstrict-prototypes mxv.c
gcc -o ../bindir/mxv-pthreads ../objects/main.o ../objects/manage_data.o ../objects/workload.o ../objects/mxv.o -lm -lpthread
ldd ../bindir/mxv-pthreads
linux-vdso.so.1 (0x0000ffff9ea8b000)
libm.so.6 => /lib64/libm.so.6 (0x0000ffff9e9ad000)
libc.so.6 => /lib64/libc.so.6 (0x0000ffff9e7ff000)
/lib/ld-linux-aarch64.so.1 (0x0000ffff9ea4e000)
$
```
The `make install` command installs the executable in directory `experiments`.
```
$ make install
Installed mxv-pthreads in ../experiments
$
```
The `make check` command may be used to verify the program works as expected:
```
$ make check
Running mxv-pthreads in ../experiments
mxv: error check passed - rows = 1000 columns = 1500 threads = 2
$
```
The `make clean` comand removes the object files from the `objects` directory
and the executable from the `bindir` directory.
The `make veryclean` command implies `make clean`, but also removes the
executable from directory `experiments`.
## Usage
The code takes several options, but all have a default value. If the code is
executed without any options, these defaults will be used. To get an overview of
all the options supported, and the defaults, use the `-h` option:
```
$ ./mxv-pthreads -h
Usage: ./mxv-pthreads [-m <number of rows>] [-n <number of columns] [-r <repeat count>] [-t <number of threads] [-v] [-h]
-m - number of rows, default = 2000
-n - number of columns, default = 3000
-r - the number of times the algorithm is repeatedly executed, default = 200
-t - the number of threads used, default = 1
-v - enable verbose mode, off by default
-h - print this usage overview and exit
$
```
For more extensive run time diagnostic messages use the `-v` option.
As an example, these are the options to compute the product of a 2000x1000 matrix
with a vector of length 1000 and use 4 threads. Verbose mode has been enabled:
```
$ ./mxv-pthreads -m 2000 -n 1000 -t 4 -v
Verbose mode enabled
Allocated data structures
Initialized matrix and vectors
Defined workload distribution
Assigned work to threads
Thread 0 has been created
Thread 1 has been created
Thread 2 has been created
Thread 3 has been created
Matrix vector multiplication has completed
Verify correctness of result
Error check passed
mxv: error check passed - rows = 2000 columns = 1000 threads = 4
$
```
## Executing the examples
Directory `experiments` contains the `profile.sh` script. This script
checks if gprofng can be found and for the executable to be installed.
The script will then run a data collection experiment, followed by a series
of invocations of `gprofng display text` to show various views. The results
are printed on stdout.
To include the commands executed in the output of the script, and store the
results in a file called `LOG`, execute the script as follows:
```
$ bash -x ./profile.sh >& LOG
```
## Additional comments
* The reason that compiler based inlining is disabled is to make the call tree
look more interesting. For the same reason, the core multiplication function
`mxv_core` has inlining disabled through the `void __attribute__ ((noinline))`
attribute. Of course you're free to change this. It certainly does not affect
the workings of the code.
* This distribution includes a script called `profile.sh`. It is in the
`experiments` directory and meant as an example for (new) users of gprofng.
It can be used to produce profiles at the command line. It is also suitable
as a starting point to develop your own profiling script(s).
|
