diff --git a/fusesoc/cheri-cap-lib-test.core b/fusesoc/cheri-cap-lib-test.core
index ffadd87..48a03bd 100644
--- a/fusesoc/cheri-cap-lib-test.core
+++ b/fusesoc/cheri-cap-lib-test.core
@@ -28,8 +28,12 @@ targets:
   test64:
     description: "Default target that generates 64bit versions"
     default_tool: verilator
+    # this adds a dependency on the generator, so that it appears on the
+    # dependency tree
     filesets:
       - cheri-cap-lib-dep
+    # this invokes the 64bit parameterization of the generator which is
+    # declared above
     generate:
       - cheri-cap-lib-64
   test128:
@@ -44,6 +48,8 @@ targets:
     default_tool: verilator
     filesets:
       - cheri-cap-lib-dep
+    # this invokes both the 64bit and 128bit parameterizations of the generator
+    # which is declared above
     generate:
       - cheri-cap-lib-64
       - cheri-cap-lib-128
diff --git a/readme.adoc b/readme.adoc
index 5dcd9be..d803cef 100644
--- a/readme.adoc
+++ b/readme.adoc
@@ -48,3 +48,22 @@ toc::[]
 == The CHERI CAP LIB API
 
 include::CHERI_CAP_API.adoc[]
+
+== FuseSoC
+
+``cheri-cap-lib`` supports being used as a generator within FuseSoC. The scripts
+and cores for this are within the ``fusesoc`` directory, and the file
+``cheri-cap-lib-test.core`` shows how a core can declare a dependency on and
+use the ``cheri-cap-lib`` generator.
+
+The FuseSoC generator will generate Verilog modules for each of the functions
+in ``CHERICapWrap.bsv``, as well as a SystemVerilog package and module to
+make working with these modules _slightly_ simpler in SystemVerilog.
+
+To generate both the 64bit and 128bit wrappers and packages, run
+``fusesoc --cores-root . run --target test --setup ucam:cheri:cheri-cap-lib-test``
+
+The files will be generated in
+``build/ucam_cheri_cheri-cap-lib-test_0/test-verilator/generated/ucam_cheri_cheri-cap-lib-test-cheri-cap-lib-64_0/``
+and
+``build/ucam_cheri_cheri-cap-lib-test_0/test-verilator/generated/ucam_cheri_cheri-cap-lib-test-cheri-cap-lib-128_0/``