-
Notifications
You must be signed in to change notification settings - Fork 593
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This is a dummy that can be used as a template and documentation for new HAL drivers and a change detector for HAL APIs. It's also useful as a way to get the minimum size of a HAL driver with default emulation.
- Loading branch information
Showing
32 changed files
with
2,832 additions
and
40 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,50 @@ | ||
| # Copyright 2024 The IREE Authors | ||
| # | ||
| # Licensed under the Apache License v2.0 with LLVM Exceptions. | ||
| # See https://llvm.org/LICENSE.txt for license information. | ||
| # SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception | ||
|
|
||
| load("//build_tools/bazel:build_defs.oss.bzl", "iree_runtime_cc_library") | ||
|
|
||
| package( | ||
| default_visibility = ["//visibility:public"], | ||
| features = ["layering_check"], | ||
| licenses = ["notice"], # Apache 2.0 | ||
| ) | ||
|
|
||
| iree_runtime_cc_library( | ||
| name = "null", | ||
| srcs = [ | ||
| "allocator.c", | ||
| "allocator.h", | ||
| "buffer.c", | ||
| "buffer.h", | ||
| "channel.c", | ||
| "channel.h", | ||
| "command_buffer.c", | ||
| "command_buffer.h", | ||
| "device.c", | ||
| "device.h", | ||
| "driver.c", | ||
| "driver.h", | ||
| "event.c", | ||
| "event.h", | ||
| "executable.c", | ||
| "executable.h", | ||
| "executable_cache.c", | ||
| "executable_cache.h", | ||
| "semaphore.c", | ||
| "semaphore.h", | ||
| ], | ||
| hdrs = [ | ||
| "api.h", | ||
| ], | ||
| deps = [ | ||
| "//runtime/src/iree/base", | ||
| "//runtime/src/iree/base/internal", | ||
| "//runtime/src/iree/hal", | ||
| "//runtime/src/iree/hal/utils:file_transfer", | ||
| "//runtime/src/iree/hal/utils:memory_file", | ||
| "//runtime/src/iree/hal/utils:semaphore_base", | ||
| ], | ||
| ) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,49 @@ | ||
| ################################################################################ | ||
| # Autogenerated by build_tools/bazel_to_cmake/bazel_to_cmake.py from # | ||
| # runtime/src/iree/hal/drivers/null/BUILD.bazel # | ||
| # # | ||
| # Use iree_cmake_extra_content from iree/build_defs.oss.bzl to add arbitrary # | ||
| # CMake-only content. # | ||
| # # | ||
| # To disable autogeneration for this file entirely, delete this header. # | ||
| ################################################################################ | ||
|
|
||
| iree_add_all_subdirs() | ||
|
|
||
| iree_cc_library( | ||
| NAME | ||
| null | ||
| HDRS | ||
| "api.h" | ||
| SRCS | ||
| "allocator.c" | ||
| "allocator.h" | ||
| "buffer.c" | ||
| "buffer.h" | ||
| "channel.c" | ||
| "channel.h" | ||
| "command_buffer.c" | ||
| "command_buffer.h" | ||
| "device.c" | ||
| "device.h" | ||
| "driver.c" | ||
| "driver.h" | ||
| "event.c" | ||
| "event.h" | ||
| "executable.c" | ||
| "executable.h" | ||
| "executable_cache.c" | ||
| "executable_cache.h" | ||
| "semaphore.c" | ||
| "semaphore.h" | ||
| DEPS | ||
| iree::base | ||
| iree::base::internal | ||
| iree::hal | ||
| iree::hal::utils::file_transfer | ||
| iree::hal::utils::memory_file | ||
| iree::hal::utils::semaphore_base | ||
| PUBLIC | ||
| ) | ||
|
|
||
| ### BAZEL_TO_CMAKE_PRESERVES_ALL_CONTENT_BELOW_THIS_LINE ### |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,66 @@ | ||
| # Null HAL Driver (`null`) | ||
|
|
||
| This is a skeleton HAL driver that implements most interfaces needed by a HAL | ||
| driver. It contains notes that can be useful to implementers, stubs for | ||
| easy copy/paste/renaming, and some default behavior in places that many | ||
| implementations can use (such as file queue operations). It doesn't run anything | ||
| and nearly all methods return `UNIMPLEMENTED` errors: this can be used to | ||
| incrementally build a driver by running until you hit an UNIMPLEMENTED, | ||
| implementing it, and running again. Note however that the HAL is fairly regular | ||
| and starting with the files and running down the methods is often much easier | ||
| to do than the trial-and-error approach: if you can implement command buffer | ||
| fill (memset) you can often implement copy (memcpy) as well at the same time. | ||
|
|
||
| ## Instructions for Cloning | ||
|
|
||
| 1. Duplicate the entire directory in your own repository or the IREE | ||
| `experimental/` folder if going in-tree. | ||
| 1. Find/replace `{Null}` with the friendly name of your driver (e.g. `Vulkan`). | ||
| 1. Find/replace `_null_` with the C name of your driver (e.g. `vulkan`). | ||
| 1. Find/replace `// TODO(null):` with your github ID, your driver name, or a | ||
| GitHub issue number tracking driver creation (e.g. `// TODO(#1234):`). | ||
|
|
||
| ## Build Setup | ||
|
|
||
| HAL drivers are setup by adding some specially named cmake variables and then | ||
| pointing the IREE build at them by name. Projects embedding IREE runtime builds | ||
| as a submodule can use the `iree_register_external_hal_driver` cmake function | ||
| to do this, set the variables on the command line during cmake configure, or | ||
| via top-level project `CMakeLists.txt` before adding the IREE subdirectory. | ||
|
|
||
| See [runtime/src/iree/hal/drivers/CMakeLists.txt](runtime/src/iree/hal/drivers/CMakeLists.txt) for more information. | ||
|
|
||
| Example using the helper function: | ||
| ```cmake | ||
| iree_register_external_hal_driver( | ||
| NAME | ||
| webgpu | ||
| SOURCE_DIR | ||
| "${CMAKE_CURRENT_SOURCE_DIR}/experimental/webgpu" | ||
| BINARY_DIR | ||
| "${CMAKE_CURRENT_BINARY_DIR}/experimental/webgpu" | ||
| DRIVER_TARGET | ||
| iree::experimental::webgpu::registration | ||
| REGISTER_FN | ||
| iree_hal_webgpu_driver_module_register | ||
| ) | ||
| set(IREE_EXTERNAL_HAL_DRIVERS my_driver) | ||
| ``` | ||
|
|
||
| Example using the command line: | ||
| ```sh | ||
| cmake ... \ | ||
| -DIREE_EXTERNAL_MY_DRIVER_HAL_DRIVER_TARGET=my_driver_static_library \ | ||
| -DIREE_EXTERNAL_MY_DRIVER_HAL_DRIVER_REGISTER=my_driver_register \ | ||
| -DIREE_EXTERNAL_HAL_DRIVERS=my_driver | ||
| ``` | ||
|
|
||
| ## In-tree Drivers (`iree/hal/drivers/...`) | ||
|
|
||
| IREE is generally conservative about hosting in-tree HAL drivers unless authored | ||
| by the core team or an SLA is in-place and maintained. Any new HAL drivers | ||
| should expect to start in forks or external repositories and not be expected | ||
| to merge without deep involvement with the IREE maintainers. IREE is not a | ||
| monorepo and it's perfectly fine to be out-of-tree. If ergonomics issues are | ||
| encountered with being out of tree please file issues so that support can be | ||
| improved. |
Oops, something went wrong.