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:
Field G. Van Zee
2018-05-26 15:51:08 -05:00
parent 2bad97f6bd
commit 3a4603858e

View File

@@ -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!