[llvm-experiment] Update README
diff --git a/llvm-codegen/README b/llvm-codegen/README
deleted file mode 100644
index 941abfb..0000000
--- a/llvm-codegen/README
+++ /dev/null
@@ -1,24 +0,0 @@
-A small tutorial on how to use the LLVM code generation tool:
-
-mkdir build
-cd build
-cmake -DTARGET_ARCH=[X64|WASM] ../
-make
-
-Suppose that your dart file is example/main.dart, then run:
-pkg/vm/tool/release_llvm_precompiler example/main
-This will generate a bunch of files in example/:
-main.il -- the serialized IL
-main.llvm -- the LLVM IR in text format
-main.s -- the corresponding assembly
-main.S -- the assembly from the Dart AOT pipeline
-main.dill
-main executable -- the executable from the Dart AOT pipeline
-main.so -- the LLVM executable
-
-Then to run this:
-./out/ReleaseX64/dart_precompiled_runtime --llvm-mode example/main.so
-
-For Wasm running:
-pkg/vm/tool/wasm_precompiler example/main
-Produces a WebAssembly module main.wasm, among other things.
diff --git a/llvm-codegen/README.md b/llvm-codegen/README.md
new file mode 100644
index 0000000..9791035
--- /dev/null
+++ b/llvm-codegen/README.md
@@ -0,0 +1,88 @@
+# How to use LLVM backend
+
+## Prerequisites
+
+You will need LLVM development headers and libraries. Current version of
+the backend is tested to work against `01b595c0cb78764384be769236af2e23cc11ab52` of
+`llvm-project` built and installed globally.
+
+## Building
+
+We are assuming that you have functional Dart SDK checkout, which can be
+obtained by doing `fetch dart` and you checked out `llvm-experiment` branch.
+
+The following targets need to built:
+
+* `vm_platform` - provides Kernel binary with Dart SDK libraries;
+* `gen_snapshot` - provides Dart AOT compiler;
+* `dart_precompiled_runtime` - provides Dart AOT runtime.
+
+```console
+$ tools/build.py -m product -a x64 vm_platform gen_snapshot dart_precompiled_runtime
+```
+
+Note: specifying `product` creates a _product build_ which is considered the
+most minimal runtime environment, excluding features like vmservice, debugging
+and profiling support. You can also use normal `release` and `debug` builds
+for debugging.
+
+Additionally you will need to build LLVM backend, which is currently not
+integrated into GN build:
+
+```console
+$ mkdir out/llvm-codegen
+$ cd out/llvm-codegen
+$ cmake -DTARGET_ARCH=X64 -G Ninja ../../llvm-codegen
+$ ninja
+```
+
+## Testing
+
+Currently LLVM backend supports lowering of a subset of IL instructions
+which Dart VM AOT compiler can generate. Thus is can't yet compile any
+application in its entirety. Instead functions that you would like to
+compile through LLVM backend need to be annotated with `@pragma('vm:llvm')`.
+
+Consider the following input file `/tmp/hello.dart`:
+
+```dart
+@pragma('vm:llvm') // compile this function through LLVM
+@pragma('vm:never-inline') // prevent inlining of this function into main
+int sum(int start, int end) {
+ final list = <int>[];
+ for (var i = start; i < end; i++) list.add(i * i);
+
+ var sum = 0;
+ for (var elem in list) {
+ sum += elem;
+ }
+ return sum;
+}
+
+void main(List<String> args) {
+ final result = sum(int.parse(args[0]), int.parse(args[1]));
+ print('sum: ${result}');
+}
+```
+
+This file can be compiled using `pkg/vm/tool/release_llvm_precompiler` like so:
+
+```console
+$ DART_CONFIGURATION=ProductX64 pkg/vm/tool/release_llvm_precompiler /tmp/hello
+# This would produce /tmp/hello.so which can be run using precompiled runtime
+$ out/ProductX64/dart_precompiled_runtime --llvm-mode /tmp/hello.so
+```
+
+Note: `.dart` is removed.
+
+You can pass `-v` or `--verbose` to see the steps that the script is executing.
+
+Script generates the following interpediate files next to the input file:
+
+* `hello.il` the serialized IL;
+* `hello.llvm` the LLVM IR in text format;
+* `hello.s` the corresponding assembly;
+* `hello.S` the assembly from the Dart AOT pipeline;
+* `hello.dill` Kernel binary (AOT optimized);
+* `hello.so` library that contains all necessary snapshots and code
+
