diff --git a/vulkan/README.md b/vulkan/README.md
new file mode 100644
index 0000000..44747fd
--- /dev/null
+++ b/vulkan/README.md
@@ -0,0 +1,28 @@
+# frameworks/native/vulkan
+
+This subdirectory contains Android's Vulkan loader, as well as some Vulkan-related tools useful to platform developers.
+
+## Coding Style
+
+We follow the [Chromium coding style](https://www.chromium.org/developers/coding-style) for naming and formatting, except with four-space indentation instead of two spaces. In general, any C++ features supported by the prebuilt platform toolchain are allowed.
+
+Use "clang-format -style=file" to format all C/C++ code, except code imported verbatim from elsewhere. Setting up git-clang-format in your environment is recommended.
+
+## Code Generation
+
+We generate several parts of the loader and tools from a Vulkan API description file, stored in `api/vulkan.api`. Code generation must be done manually because the generator tools aren't part of the platform toolchain (yet?). Files named `foo_gen.*` are generated from the API file and a template file named `foo.tmpl`.
+
+ To run the generator:
+
+### One-time setup
+- Install [golang](https://golang.org/), if you don't have it already.
+- Create a directory (e.g. `$HOME/lib/go`) for local go sources and binaries and add it to `$GOPATH`.
+- `$ git clone https://android.googlesource.com/platform/tools/gpu $GOPATH/src/android.googlesource.com/platform/tools/gpu`
+- `$ go get android.googlesource.com/platform/tools/gpu/api/...`
+- You should now have `$GOPATH/bin/apic`. You might want to add `$GOPATH/bin` to your `$PATH`.
+
+### Generating code
+To generate `libvulkan/dispatch_gen.*`,
+- `$ cd libvulkan`
+- `$ apic template ../api/vulkan.api dispatch.tmpl`
+Similar for `nulldrv/null_driver_gen.*`.
\ No newline at end of file
diff --git a/vulkan/libvulkan/dispatch.tmpl b/vulkan/libvulkan/dispatch.tmpl
index 0f1194c..054a235 100644
--- a/vulkan/libvulkan/dispatch.tmpl
+++ b/vulkan/libvulkan/dispatch.tmpl
@@ -42,6 +42,8 @@
 •* limitations under the License.
 •*/
 ¶
+// WARNING: This file is generated. See ../README.md for instructions.
+¶
 #define VK_USE_PLATFORM_ANDROID_KHR
 #include <vulkan/vk_android_native_buffer.h>
 #include <vulkan/vk_ext_debug_report.h>
@@ -124,6 +126,8 @@
 •* limitations under the License.
 •*/
 ¶
+// WARNING: This file is generated. See ../README.md for instructions.
+¶
 #include <log/log.h>
 #include <algorithm>
 #include "loader.h"
diff --git a/vulkan/libvulkan/dispatch_gen.cpp b/vulkan/libvulkan/dispatch_gen.cpp
index 60da749..0d2d605 100644
--- a/vulkan/libvulkan/dispatch_gen.cpp
+++ b/vulkan/libvulkan/dispatch_gen.cpp
@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+// WARNING: This file is generated. See ../README.md for instructions.
+
 #include <log/log.h>
 #include <algorithm>
 #include "loader.h"
diff --git a/vulkan/libvulkan/dispatch_gen.h b/vulkan/libvulkan/dispatch_gen.h
index 14c5da8..14a4b95 100644
--- a/vulkan/libvulkan/dispatch_gen.h
+++ b/vulkan/libvulkan/dispatch_gen.h
@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+// WARNING: This file is generated. See ../README.md for instructions.
+
 #define VK_USE_PLATFORM_ANDROID_KHR
 #include <vulkan/vk_android_native_buffer.h>
 #include <vulkan/vk_ext_debug_report.h>
diff --git a/vulkan/nulldrv/null_driver.tmpl b/vulkan/nulldrv/null_driver.tmpl
index 57e72d3..7488692 100644
--- a/vulkan/nulldrv/null_driver.tmpl
+++ b/vulkan/nulldrv/null_driver.tmpl
@@ -43,9 +43,7 @@
 •* limitations under the License.
 •*/
 ¶
-// This file is generated. Do not edit manually!
-// To regenerate: $ apic template ../api/vulkan.api null_driver.tmpl
-// Requires apic from https://android.googlesource.com/platform/tools/gpu/.
+// WARNING: This file is generated. See ../README.md for instructions.
 ¶
 #ifndef NULLDRV_NULL_DRIVER_H
 #define NULLDRV_NULL_DRIVER_H 1
@@ -98,9 +96,7 @@
 •* limitations under the License.
 •*/
 ¶
-// This file is generated. Do not edit manually!
-// To regenerate: $ apic template ../api/vulkan.api null_driver.tmpl
-// Requires apic from https://android.googlesource.com/platform/tools/gpu/.
+// WARNING: This file is generated. See ../README.md for instructions.
 ¶
 #include "null_driver_gen.h"
 #include <algorithm>
diff --git a/vulkan/nulldrv/null_driver_gen.cpp b/vulkan/nulldrv/null_driver_gen.cpp
index c5f42b0..10da993 100644
--- a/vulkan/nulldrv/null_driver_gen.cpp
+++ b/vulkan/nulldrv/null_driver_gen.cpp
@@ -14,9 +14,7 @@
  * limitations under the License.
  */
 
-// This file is generated. Do not edit manually!
-// To regenerate: $ apic template ../api/vulkan.api null_driver.tmpl
-// Requires apic from https://android.googlesource.com/platform/tools/gpu/.
+// WARNING: This file is generated. See ../README.md for instructions.
 
 #include "null_driver_gen.h"
 #include <algorithm>
diff --git a/vulkan/nulldrv/null_driver_gen.h b/vulkan/nulldrv/null_driver_gen.h
index ddf4afb..87ff681 100644
--- a/vulkan/nulldrv/null_driver_gen.h
+++ b/vulkan/nulldrv/null_driver_gen.h
@@ -14,9 +14,7 @@
  * limitations under the License.
  */
 
-// This file is generated. Do not edit manually!
-// To regenerate: $ apic template ../api/vulkan.api null_driver.tmpl
-// Requires apic from https://android.googlesource.com/platform/tools/gpu/.
+// WARNING: This file is generated. See ../README.md for instructions.
 
 #ifndef NULLDRV_NULL_DRIVER_H
 #define NULLDRV_NULL_DRIVER_H 1