Minor revisions

substratevm/C-API.md

@@ -1,6 +1,6 @@
 # Substrate VM C API
 
-Substrate VM provides an API for the C language for initializing isolates and attaching threads, complementing the entry point feature that is demonstrated in the [README](README.md). The C API is available when Substrate VM is built as a shared library and is included in the header file that is generated during the build:
+Substrate VM provides an API for the C language for initializing isolates and attaching threads for use with the entry point feature that is demonstrated in the [README](README.md). The C API is available when Substrate VM is built as a shared library and its declarations are included in the header file that is generated during the build:
 
 ```c
 /*
@@ -42,15 +42,16 @@ int graal_create_isolate(graal_create_isolate_params_t* params, graal_isolate_t*
 int graal_attach_thread(graal_isolate_t* isolate, graal_isolatethread_t** thread);
 
 /*
- * Returns the address of the current thread's associated isolate thread structure
- * within the passed isolate. If the current thread is not attached to the passed
- * isolate or if another error occurs, returns NULL.
+ * Given an isolate to which the current thread is attached, returns the address of
+ * the thread's associated isolate thread structure.  If the current thread is not
+ * attached to the passed isolate or if another error occurs, returns NULL.
  */
 graal_isolatethread_t* graal_current_thread(graal_isolate_t* isolate);
 
 /*
- * Determines the isolate to which the passed isolate thread belongs and returns
- * the address of its isolate structure. If an error occurs, returns NULL instead.
+ * Given an isolate thread structure for the current thread, determines to which
+ * isolate it belongs and returns the address of its isolate structure.  If an
+ * error occurs, returns NULL instead.
  */
 graal_isolate_t* graal_current_isolate(graal_isolatethread_t* thread);
 

substratevm/README.md

@@ -29,27 +29,31 @@ Visit the [MX Homepage](https://github.com/graalvm/mx) for more details.
 
 Substrate VM requires a JDK 8 with JVMCI. It is available from [OTN](http://www.oracle.com/technetwork/oracle-labs/program-languages/downloads/index.html).
 
-In the main directory, invoke `mx help` to see the list of commands. Most of the commands are inherited from the Graal and Truffle implementation. The most important commands for the Substrate VM are listed below. More information on the parameters of a command is available by running `mx help <command>`
+In the main directory, invoke `mx help` to see the list of commands. Most of the commands are inherited from the Graal and Truffle code bases. The most important commands for the Substrate VM are listed below. More information on the parameters of a command is available by running `mx help <command>`
 
 * `build`: Compile all Java and native code.
 * `clean`: Remove all compilation artifacts.
 * `ideinit`: Create project files for Eclipse and other common IDEs. See the [documentation on IDE integration](../compiler/docs/IDEs.md) for details.
 
 ## Building images
 
-After running `mx build` you will find the following symlink in your substratevm directory:
+After running `mx build` you will find the following symlink to the `native-image` tool in your `substratevm` directory:
 
     native-image -> svmbuild/native-image-root/linux-amd64/bin/native-image
 
-Use this symlink to build native images. You can specify the main entry point, i.e., the application you want to create the image for. For more information run `./native-image -help`.
+Use this tool to build native images. You can specify the main entry point, i.e., the application you want to create the image for. For more information run `./native-image -help`.
 
-Native image generation is performed by a Java program that runs on JDK 8 with JVMCI. You can debug it with the normal Java debugger. Use `./native-image -debug-attach` to start native image generation so that it waits for a Java debugger to connect. In Eclipse, use the debugging configuration "substratevm-localhost-8000" to attach Eclipse to it. The debugging configuration is automatically generated by `mx ideinit`.
+Native image generation is performed by a Java program that runs on JDK 8 with JVMCI. You can debug it with a regular Java debugger. Use `./native-image -debug-attach` to start native image generation so that it waits for a Java debugger to attach first (by default, at port 8000). In Eclipse, use the debugging configuration "substratevm-localhost-8000" to attach to it. This debugging configuration is automatically generated by `mx ideinit`.
 
-If you find yourself having to debug into the Graal level of SubstrateVM, you should read the Graal [debugging](../compiler/docs/Debugging.md) page.
+If you find yourself having to debug into the Graal level of SubstrateVM, you should read the Graal [debugging](../compiler/docs/Debugging.md) page. You can use Ideal Graph Visualizer to view individual compilation steps:
+```bash
+mx igv &>/dev/null &
+./native-image -no-server HelloWorld -H:Dump= -H:MethodFilter=HelloWorld.*
+```
 
 ## Images and Entry Points
 
-An SVM image can be built as a standalone executable or as a shared library. The kind of image can be selected by passing either `-H:Kind=EXECUTABLE` or `-H:Kind=SHARED_LIBRARY` to `native-image`. For an image to be useful, it needs to have at least one entry point method.
+An SVM image can be built as a standalone executable, which is the default, or as a shared library by passing `-shared` to `native-image`. For an image to be useful, it needs to have at least one entry point method.
 
 For executables, SVM supports Java main methods with a signature that takes the command-line arguments as an array of strings:
 
@@ -65,9 +69,12 @@ For shared libraries, SVM provides the `@CEntryPoint` annotation to specify entr
 }
 ```
 
-Both executable images and shared library images can have an arbitrary number of entry points, for example to implement callbacks or APIs.
+Shared library builds generate an additional C header file. This header file contains declarations for the [SVM C API](C-API.md), which allows creating isolates and attaching threads from C code, as well as declarations for each entry point in user code. The generated C declaration for the above example is:
+```c
+int add(graal_isolatethread_t* thread, int a, int b);
+```
 
-Substrate VM further provides a [C API](C-API.md) to initialize isolates and attach threads from C.
+Both executable images and shared library images can have an arbitrary number of entry points, for example to implement callbacks or APIs.
 
 ## Options
 
@@ -79,7 +86,7 @@ The list of projects is defined in a custom format in the file `mx.substratevm/s
 
 ## Code Formatting
 
-Style rules and procedures for checking are described in the [style guide](STYLE.md).
+Style rules and procedures for checking adherence are described in the [style guide](STYLE.md).
 
 ## Troubleshooting Eclipse
 
@@ -93,16 +100,6 @@ Sometimes, Eclipse gives strange error messages, especially after pulling a bigg
 * `mx ideinit`
 * Import all projects into Eclipse again
 
-## Using the Ideal Graph Visualizer (igv)
-
-Occasionally, an image build can fail due to an issue in Graal. Ideal Graph Visualizer can show the individual compilation steps to find the problem:
-```bash
-mx igv &>/dev/null &
-./native-image -no-server HelloWorld -H:Dump= -H:MethodFilter=HelloWorld.*
-```
-
-There is an old users guide in chapter 4 of [Thomas Wuerthinger's master's thesis](http://ssw.jku.at/Research/Papers/Wuerthinger07Master/).
-
 ## License
 
 The Substrate VM is licensed under the [GPL 2](LICENSE.md).

substratevm/STYLE.md

@@ -4,7 +4,7 @@
 
 The IDE projects generated with `mx ideinit` are configured with strict formatting rules. In Eclipse, when a file is saved, it is automatically formatted according to these rules.
 
-The rule set has grown over time and proved to be useful, but rules are open for discussion. The configuration includes special comments which can be used to relax checks in particular regions of code.
+The rule set has grown over time and proved to be useful, but the rules are open for discussion. The configuration includes special comments which can be used to relax checks in particular regions of code.
 
 Source code formatting can be disabled with special comments:
 ```java

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/c/function/CEntryPointActions.java

@@ -142,7 +142,7 @@ private CEntryPointActions() {
      * for situations in which recovery is not possible, or in which reporting a severe error in any
      * other way is not possible. This method does not return.
      * 
-     * @param code An integer representing at the cause (should be non-zero by convention).
+     * @param code An integer representing the cause (should be non-zero by convention).
      * @param message A message describing the cause (may be omitted by passing
      *            {@link Word#nullPointer() null}).
      */

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/c/function/CEntryPointNativeFunctions.java

@@ -93,9 +93,9 @@ public static int attachThread(Isolate isolate, IsolateThreadPointer thread) {
 
     @Uninterruptible(reason = UNINTERRUPTIBLE_REASON)
     @CEntryPoint(name = "current_thread", documentation = {
-                    "Returns the address of the current thread's associated isolate thread structure",
-                    "within the passed isolate. If the current thread is not attached to the passed",
-                    "isolate or if another error occurs, returns NULL."})
+                    "Given an isolate to which the current thread is attached, returns the address of",
+                    "the thread's associated isolate thread structure.  If the current thread is not",
+                    "attached to the passed isolate or if another error occurs, returns NULL."})
     @CEntryPointOptions(prologue = NoPrologue.class, epilogue = NoEpilogue.class, nameTransformation = NameTransformation.class)
     public static IsolateThread getCurrentThread(Isolate isolate) {
         int result = CEntryPointActions.enterIsolate(isolate);
@@ -111,8 +111,9 @@ public static IsolateThread getCurrentThread(Isolate isolate) {
 
     @Uninterruptible(reason = UNINTERRUPTIBLE_REASON)
     @CEntryPoint(name = "current_isolate", documentation = {
-                    "Determines the isolate to which the passed isolate thread belongs and returns",
-                    "the address of its isolate structure. If an error occurs, returns NULL instead."})
+                    "Given an isolate thread structure for the current thread, determines to which",
+                    "isolate it belongs and returns the address of its isolate structure.  If an",
+                    "error occurs, returns NULL instead."})
     @CEntryPointOptions(prologue = NoPrologue.class, epilogue = NoEpilogue.class, nameTransformation = NameTransformation.class)
     public static Isolate getCurrentIsolate(IsolateThread thread) {
         int result = CEntryPointActions.enter(thread);