mirror of
https://github.com/amd/blis.git
synced 2026-05-11 17:50:00 +00:00
More README.md updates to sandbox/c99.
Details: - Added a section that walks the reader through how to configure BLIS to use a gemm sandbox.
This commit is contained in:
@@ -21,6 +21,35 @@ operations are supported with minimal source code). By building a BLIS sandbox,
|
||||
you can experiment (within limits) and still benefit from BLIS's existing
|
||||
build system, testsuite, and toolbox of utility functions.
|
||||
|
||||
## Enabling a sandbox
|
||||
|
||||
To enable a sandbox at configure-time, you simply specify it as an option to
|
||||
`configure`. Either of the following usages are accepted:
|
||||
```
|
||||
$ ./configure --enable-sandbox=c99 auto
|
||||
$ ./configure -s c99 auto
|
||||
```
|
||||
Here, we tell `configure` that we want to use the `c99` sandbox, which
|
||||
corresponds to a sub-directory of `sandbox` named `c99`. (Reminder: the `auto`
|
||||
is simply the configuration target and thus unrelated to sandboxes.) As
|
||||
configure runs, you should get output that includes lines similar to:
|
||||
```
|
||||
configure: configuring for alternate gemm implementation:
|
||||
configure: sandbox/c99
|
||||
```
|
||||
And when you build BLIS, the last files to be compiled will be the source
|
||||
code in the specified sandbox:
|
||||
```
|
||||
Compiling obj/haswell/sandbox/c99/blx_gemm_front.o ('haswell' CFLAGS for sandboxes)
|
||||
Compiling obj/haswell/sandbox/c99/blx_gemm_int.o ('haswell' CFLAGS for sandboxes)
|
||||
Compiling obj/haswell/sandbox/c99/base/blx_blksz.o ('haswell' CFLAGS for sandboxes)
|
||||
Compiling obj/haswell/sandbox/c99/cntl/blx_gemm_cntl.o ('haswell' CFLAGS for sandboxes)
|
||||
...
|
||||
```
|
||||
That's it! After the BLIS library is built, it will contain your chosen
|
||||
sandbox's implementation of `bli_gemmnat()` instead of the default
|
||||
implementation.
|
||||
|
||||
## Sandbox rules
|
||||
|
||||
Like any decent sandbox, there are rules for playing here. Please follow these
|
||||
@@ -32,7 +61,8 @@ BLIS with a sandbox enabled, `make` will scan your directory and compile all
|
||||
of its source code using similar compilation rules as were used for the rest
|
||||
of the framework. In addition, the compilation command line will automatically
|
||||
contain one `-I<includepath>` option for every subdirectory in your sandbox,
|
||||
so it doesn't matter where you place your header files. They will be found!
|
||||
so it doesn't matter where in your sandbox you place your header files. They
|
||||
will be found!
|
||||
|
||||
1. Your sandbox must be written in C99 or C++11. If you write your sandbox in
|
||||
C++11, you must use one of the BLIS-approved file extensions for your source
|
||||
@@ -44,24 +74,23 @@ any issues.
|
||||
|
||||
2. All of your code to replace BLIS's default implementation of `bli_gemmnat()`
|
||||
should reside in the sandbox directory, or some directory therein. (Obviously.)
|
||||
For example, this `README.md` file is located in the **C99** sandbox located in
|
||||
For example, this `README.md` file is located in the C99 sandbox located in
|
||||
`sandbox/c99`. Thus, all of the code associated with this sandbox will be
|
||||
contained within `sandbox/c99`.
|
||||
|
||||
3. The *only* header file that is required of your sandbox is `bli_sandbox.h`.
|
||||
It must be named `bli_sandbox.h` because `blis.h` will `#include` this file
|
||||
when sandboxes are enabled at configure-time.
|
||||
That said, you will probably want to keep the file empty. Why require a file
|
||||
that is supposed to be empty? Well, it doesn't *have* to be empty. Anything
|
||||
placed in this file will be folded into the flattened (monolithic) `blis.h`
|
||||
at compile-time. Therefore, you should only place things (e.g. prototypes or
|
||||
type definitions) in `bli_sandbox.h` if those things would be needed at
|
||||
compile-time by:
|
||||
when the sandbox is enabled at configure-time. That said, you will probably
|
||||
want to keep the file empty. Why require a file that is supposed to be empty?
|
||||
Well, it doesn't *have* to be empty. Anything placed in this file will be
|
||||
folded into the flattened (monolithic) `blis.h` at compile-time. Therefore,
|
||||
you should only place things (e.g. prototypes or type definitions) in
|
||||
`bli_sandbox.h` if those things would be needed at compile-time by:
|
||||
(a) the BLIS framework itself, or
|
||||
(b) an *application* that uses your sandbox-enabled BLIS library.
|
||||
(b) an *application* that calls your sandbox-enabled BLIS library.
|
||||
Usually, neither of these situations will require any of your local definitions
|
||||
since those definitions are only needed to define your sandbox implementation
|
||||
of `bli_gemmnat()`. (Even this function is already prototyped by BLIS.)
|
||||
of `bli_gemmnat()`, and this function is already prototyped by BLIS.
|
||||
|
||||
4. Your definition of `bli_gemmnat()` should be the *only* function you define
|
||||
in your sandbox that begins with `bli_`. If you define other functions that
|
||||
@@ -72,8 +101,8 @@ functions with another prefix. Here, in the C99 sandbox, we use the prefix
|
||||
Also, please avoid the prefix `bla_` since that prefix is also used in BLIS for
|
||||
BLAS compatibility functions.
|
||||
|
||||
If you follow these rules, you will likely have a pleasant experience
|
||||
integrating your BLIS sandbox into the larger framework.
|
||||
If you follow these rules, you will be much more likely to have a pleasant
|
||||
experience integrating your BLIS sandbox into the larger framework.
|
||||
|
||||
## Caveats
|
||||
|
||||
@@ -81,8 +110,8 @@ Notice that the BLIS sandbox is not all-powerful. You are more-or-less stuck
|
||||
working with the existing BLIS infrastructure.
|
||||
|
||||
For example, with a BLIS sandbox you **can** do the following kinds of things:
|
||||
- use a different algorithmic partitioning path from the strategy used by
|
||||
default in BLIS;
|
||||
- use a different gemm algorithmic partitioning path than the default Goto-like
|
||||
algorithm;
|
||||
- experiment with different implementations of `packm` kernels;
|
||||
- try inlining your functions manually;
|
||||
- pivot away from using `obj_t` objects at higher algorithmic level (such as
|
||||
@@ -127,7 +156,7 @@ If you encounter any problems, please open a new
|
||||
|
||||
If you are unsure about how something works, you can still open an issue. Or, you
|
||||
can send a message to
|
||||
[blis-devel mailing list](https://groups.google.com/d/forum/blis-devel).
|
||||
[blis-devel](https://groups.google.com/d/forum/blis-devel) mailing list.
|
||||
|
||||
Happy sandboxing!
|
||||
|
||||
|
||||
Reference in New Issue
Block a user