amd/blis
1
0
Fork 0
mirror of https://github.com/amd/blis.git synced 2026-04-20 07:38:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

README.md, typed/object API updates.

Browse Source 
Details:
- Updated the typed and object APIs to include language on the rntm_t
  parameters in the expert interfaces.
- Updated README to include link to object API.
This commit is contained in:
Field G. Van Zee
2018-07-28 16:27:09 -05:00
parent 29c34c4adb
commit b8c7574f84
3 changed files with 33 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
README.md
View File

@@ -158,16 +158,19 @@ drivers via `make check`:
```
$ make check [-j]
```
Please read the output of `./configure --help` for a full list of configure-time
options.
A more detailed walkthrough of the build system can be found in our
[Build System](docs/BuildSystem.md) guide.
If you want to browse a quick-reference guide on user-level BLIS
interfaces, please read the [BLIS Typed API reference](docs/BLISTypedAPI.md).
There you will find a brief description of each operation as well as some more
general information needed when developing an application with BLIS.
We provide comprehensive documentation on BLIS's two primarily APIs:
the [BLIS Object API](docs/BLISTypedAPI.md) and
the [BLIS Typed API](docs/BLISTypedAPI.md).
These documents provide brief descriptions of each operation interface as
well as some more general information needed when developing an application
with BLIS.
If you want to begin using the more advanced object API in BLIS,
If you want to begin using the object API in BLIS,
please step through the example code tutorial in the
[examples/oapi](examples/oapi) directory.
We also have the equivalent code examples for the typed API available in

17
docs/BLISObjectAPI.md
View File

@@ -9,6 +9,7 @@
* [Global scalar constants](BLISObjectAPI.md#global-scalar-constants)
* [Basic vs expert interfaces](BLISObjectAPI.md#basic-vs-expert-interfaces)
* [Context type](BLISObjectAPI.md#context-type)
* [Runtime type](BLISObjectAPI.md#runtime-type)
* [BLIS header file](BLISObjectAPI.md#blis-header-file)
* [Initialization and cleanup](BLISObjectAPI.md#initialization-and-cleanup)
* **[Object management](BLISObjectAPI.md#object-management)**
@@ -145,7 +146,7 @@ The correct representation is chosen by context, usually by inspecting the datat
## Basic vs expert interfaces
The functions listed in this document belong to the "basic" interface subset of the BLIS object API. There is a companion "expert" interface that mirrors the basic interface, except that it also contains at least one additional parameter that is only of interest to experts and library developers. The expert interfaces use the same name as the basic function names, except for an additional "_ex" suffix. For example, the basic interface for `gemm` is
The functions listed in this document belong to the "basic" interface subset of the BLIS object API. There is a companion "expert" interface that mirrors the basic interface, except that it also contains two additional parameters that are only of interest to experts and library developers. The expert interfaces use the same name as the basic function names, except for an additional "_ex" suffix. For example, the basic interface for `gemm` is
```c
void bli_gemm
(
@@ -165,12 +166,13 @@ void bli_gemm_ex
obj_t* b,
obj_t* beta,
obj_t* c,
cntx_t* cntx
cntx_t* cntx,
rntm_t* rntm
);
```
The expert interface contains an additional `cntx_t*` parameter. Note that calling a function from the expert interface with the `cntx_t*` argument set to `NULL` is equivalent to calling the corresponding basic interface.
The expert interface contains two additional parameters: a `cntx_t*` and `rntm_t*`. Note that calling a function from the expert interface with the `cntx_t*` and `rntm_t*` arguments each set to `NULL` is equivalent to calling the corresponding basic interface.
## Contexts
## Context type
In general, it is permissible to pass in `NULL` for a `cntx_t*` parameter when calling an expert interface such as `bli_gemm_ex()`. However, there are cases where `NULL` values are not accepted and may result in a segmentation fault. Specifically, the `cntx_t*` argument appears in the interfaces to the `gemm`, `trsm`, and `gemmtrsm` [level-3 micro-kernels](KernelsHowTo.md#level-3) along with all [level-1v](KernelsHowTo.md#level-1v) and [level-1f](KernelsHowTo.md#level-1f) kernels. There, as a general rule, a valid pointer must be passed in. Whenever a valid context is needed, the developer may query a default context from the global kernel structure (if a context is not already available in the current scope):
```c
@@ -178,6 +180,13 @@ cntx_t* bli_gks_query_cntx( void );
```
When BLIS is configured to target a configuration family (e.g. `intel64`, `x86_64`), `bli_gks_query_cntx()` will use `cpuid` or an equivalent heuristic to select and and return the appropriate context. When BLIS is configured to target a singleton sub-configuration (e.g. `haswell`, `skx`), `bli_gks_query_cntx()` will unconditionally return a pointer to the context appropriate for the targeted configuration.
## Runtime type
When calling one of the expert interfaces, a `rntm_t` (runtime) object can be used to convey a thread-local request for parallelism to the underlying implementation. Runtime objects are thread-safe by nature when they are declared statically as a stack variable (or allocated via `malloc()`), initialized, and then passed into the expert interface of interest.
Notice that runtime objects have no analogue in most BLAS libraries, where you are forced to specify parallelism at a global level (usually via environment variables).
For more information on using `rntm_t` objects, please read the [Multithreading](docs/Multithreading.md) documentation.
## BLIS header file

14
docs/BLISTypedAPI.md
View File

@@ -118,12 +118,13 @@ void bli_?gemm_ex
ctype* b, inc_t rsb, inc_t csb,
ctype* beta,
ctype* c, inc_t rsc, inc_t csc,
cntx_t* cntx
cntx_t* cntx,
rntm_t* rntm
);
```
The expert interface contains an additional `cntx_t*` parameter. Note that calling a function from the expert interface with the `cntx_t*` argument set to `NULL` is equivalent to calling the corresponding basic interface.
The expert interface contains two additional parameters: a `cntx_t*` and `rntm_t*`. Note that calling a function from the expert interface with the `cntx_t*` and `rntm_t*` arguments each set to `NULL` is equivalent to calling the corresponding basic interface.
### Contexts
## Context type
In general, it is permissible to pass in `NULL` for a `cntx_t*` parameter when calling an expert interface such as `bli_dgemm_ex()`. However, there are cases where `NULL` values are not accepted and may result in a segmentation fault. Specifically, the `cntx_t*` argument appears in the interfaces to the `gemm`, `trsm`, and `gemmtrsm` [level-3 micro-kernels](KernelsHowTo.md#level-3) along with all [level-1v](KernelsHowTo.md#level-1v) and [level-1f](KernelsHowTo.md#level-1f) kernels. There, as a general rule, a valid pointer must be passed in. Whenever a valid context is needed, the developer may query a default context from the global kernel structure (if a context is not already available in the current scope):
```c
@@ -131,6 +132,13 @@ cntx_t* bli_gks_query_cntx( void );
```
When BLIS is configured to target a configuration family (e.g. `intel64`, `x86_64`), `bli_gks_query_cntx()` will use `cpuid` or an equivalent heuristic to select and and return the appropriate context. When BLIS is configured to target a singleton sub-configuration (e.g. `haswell`, `skx`), `bli_gks_query_cntx()` will unconditionally return a pointer to the context appropriate for the targeted configuration.
## Runtime type
When calling one of the expert interfaces, a `rntm_t` (runtime) object can be used to convey a thread-local request for parallelism to the underlying implementation. Runtime objects are thread-safe by nature when they are declared statically as a stack variable (or allocated via `malloc()`), initialized, and then passed into the expert interface of interest.
Notice that runtime objects have no analogue in most BLAS libraries, where you are forced to specify parallelism at a global level (usually via environment variables).
For more information on using `rntm_t` objects, please read the [Multithreading](docs/Multithreading.md) documentation.
## BLIS header file