This is ovm.info, produced by makeinfo version 4.6 from ovm.texi. Copyright (C) 2004 Purdue University This document may be used, modified, and redistributed in any way. Some day, later versions of this document may be subject to a license such as the GNU free docuementation license.  File: ovm.info, Node: Top, Next: Overview, Up: (dir) Ovm Users Manual **************** Copyright (C) 2004 Purdue University This document may be used, modified, and redistributed in any way. Some day, later versions of this document may be subject to a license such as the GNU free docuementation license. * Menu: * Overview:: Ovm in a nutshell * gen-ovm Tutorial:: Getting started with Ovm * Invoking gen-ovm:: `gen-ovm' takes many options * Invoking gen-spec-ovm:: `gen-spec-ovm' takes even more * gdb Tutorial:: Using gdb to debug Java programs * Frequently Asked Questions:: with answers * Index::  File: ovm.info, Node: Overview, Next: gen-ovm Tutorial, Prev: Top, Up: Top Overview ******** What is Ovm? ============ Ovm is a tool for generating virtual machines. Ovm includes a variety of compilers, garbage collectors, and threading systems that can be used to create a free-standing VM. This VM can (and currently must) be specialized to a particular application. Ovm is currently able generate virtual machines for ordinary Java programs, and programs written to the Real-time Specification for Java. Note that Ovm is not yet feature-complete and not fully compliant with the JVM specification. Missing features include: * *dynamic loading* - Like many ahead-of-time compilers for real-time/embedded systems, the Ovm does not support dynamic loading of classes. In the future we expect to support this via some form of mixed-mode operation and/or using the JIT compiler. * *weak references and finalization* - There is no support for weak references and heap finalizers are never run. Finalizers for objects allocated in RTSJ scoped memory are run. * *Non-core JDK API's that rely on native code* - Ovm does not support the AWT and other API's that are non-core. Ovm depends on GNU Classpath for all of the JDK API's, but must provide its own special code to replace all native calls. * *JNI support* - Ovm does not support JNI and it is not planned at the present. Much native code is replaced in Ovm by Java code operating in what we term the "executive domain". There are ways to provide additional native code support but there are highly specialized and not intended for general application use. Code using dynamic loading, native calls or finalizers will need to be tweaked adapted to work with Ovm. The implementation of the real-time APIs is also incomplete - see the `package.html' file in `src/syslib/user/ovm_classpath/javax/realtime' for details. This is a BETA release. Ovm still has known bugs that can lead to unexpected behavior, especially when migrating large applications to Ovm. Usage ===== Ovm is regularly tested on Linux/x86, Linux/ppc, and OS X/ppc. The JIT only works on x86. Ovm requires a Sun, IBM, or Apple release of Java 1.4 and gcc 3.x to build. 256 MB of main memory are also required, 1 GB are recommended. In order to run Java applications under Ovm, it is strongly recommended that you compile the applications against Ovm's version of the JDK (which is based on GNU classpath). This is the easiest way to ensure that you do not rely on library functionality that is not available. Instructions on how to compile Java code against the Ovm JDK are in the file TUTORIAL. The TUTORIAL also describes how to run the SPEC JVM and the real-time benchmarks. Also note that all class files must have been compiled to the format defined by the `javac -target 1.1' setting. This restriction will be removed in the future. At this point in time, Ovm always requires whole-world compilation of the application. Ovm has three execution backends, an interpreter, a JIT and J2C which is a front-end to GCC. Both the interpreter and the JIT are intended to be used in conjunction with dynamic loading in the future. At this stage, building Ovm with these configurations is only useful for development purposes. All benchmarking should always be done with the J2C configuration with gcc-3.4. Timer Support ============= OVM uses a default timer interrupt rate of 10ms. This affects all timed operations, such as sleeps, waits, RTSJ periodic thread release, and RTSJ timers. The timer interrupt rate can be set at runtime using the `-period' runtime argument: ./ovm -period=NNN img MAIN CLASS NAME + ARGS where NNN is a value in microseconds. The requested value will be rounded up to a multiple of the supported underlying timer resolution. A warning is printed if you ask for a timer interrupt rate that is shorter than the supported timer resolution, but no warning is printed if the rate needs to be rounded up. OVM reports that actual timer interrupt rate being used at start-up time. On the majority of Linux systems the supported timer resolution is 10ms. This cannot be changed. Apparently in 2.6 kernel Linux systems this will reduce to 1ms. When running on the licensed Timesys Linux RT system a high resolution implementation of the POSIX real-time timers is available, with a resolution of 1us. To use these timers you must ensure that the Timesys library, `librk-rt.a', is available by setting the `LIBRARY_PATH' environment variable when running configure, and when building the OVM and an OVM image. Known Problems ============== The Ovm program (`gen-ovm'), may very rarely hang after calling out to a subprocess. This appears to be a bug in Linux implemenations of Java 1.4, and occurs more frequently with Blackdown Java distributions than Sun. Ovm attempts to detect and work around the problem, but this code is extremely difficult to test. One simple trick that sometimes unhangs things is to stop the process (use `-Z') and then restart it using fg. Hacking Ovm =========== Contributions are welcome, please submit bug reports to . If you have questions or want to contribute, contact us at . Ovm on the web ============== * * *  File: ovm.info, Node: gen-ovm Tutorial, Next: Invoking gen-ovm, Prev: Overview, Up: Top Getting started with Ovm ************************ The following presents a step-by-step explanation of how to compile Ovm, install Ovm to a location of your choice, compile RTSJ code against Ovm's runtime library, and generate a virtual machine containing an RTSJ program (namely `HelloWorld'). In the rest of this example, we will refer to the Ovm's toplevel directory (`OpenVM/') as OVM-DIR. An executable version of this example is available in `OVM-DIR/examples/Makefile'. * Menu: * install:: Compiling and installing the Ovm distribution * compile:: Compiling Realtime Java code for use with Ovm * build:: Generating a virtual machine * run:: Executing `HelloWorld'  File: ovm.info, Node: install, Next: compile, Up: gen-ovm Tutorial Compiling and installing the Ovm distribution ============================================= Choose a directory (OVM-BIN-DIR) under which the built runtime files should be stored. OVM-BIN-DIR can be OVM-DIR if you like. $ cd OVM-BIN-DIR $ OVM-DIR/configure && make You can also install the runtime files by specifying the "install" target to make. By default this will install `gen-ovm' and the runtime files in `/usr/local/ovm'. To change the install location use the `--prefix' option when running `configure', eg: $ cd OVM-BIN_DIR $ OVM-DIR/configure --prefix=$HOME && make all install will install `gen-ovm' into `$HOME/bin'. The value of `--prefix' is the OVM-INSTALL-DIR.  File: ovm.info, Node: compile, Next: build, Prev: install, Up: gen-ovm Tutorial Compiling Realtime Java code for use with Ovm ============================================= Create your Hello World application, i.e. create a file `HelloWorld.java' with: public class HelloWorld { public static void main(String args[]) { System.out.println("Hello, World"); } } Compile HelloWorld.java against the OVM runtime libraries: $ javac -target 1.1 \ -bootclasspath OVM-JAR-DIR/ovm_rt_user.jar \ HelloWorld.java The OVM-JAR-DIR depends on where you built ovm and where you installed it. * If you built, but did not install ovm then OVM-JAR-DIR is: `OVM-BIN-DIR/src/syslib/user'. * If you installed ovm, using `make install' then OVM-JAR-DIR is: `OVM-INSTALL-DIR/ovm/classes'. *NOTE:* It is a current limitation with ovm that all .class files are generated with the format defined by the `javac' `-target 1.1' option. Failure to do this may result in runtime exceptions, or crashes, due to missing fields or methods.  File: ovm.info, Node: build, Next: run, Prev: compile, Up: gen-ovm Tutorial Build an OVM image with the Hello World application inside ========================================================== Choose directory into which the executable and built image should be stored. This is the OVM-EXE-DIR. Again OVM-EXE-DIR could be OVM-DIR. $ cd OVM-EXE-DIR $ OVM-BIN-DIR/bin/gen-ovm -main=HelloWorld \ -classpath=CLASSPATH TO `HELLOWORLD.CLASS' If you installed ovm then you could use OVM-INSTALL-DIR/bin/gen-ovm Have a cup of coffee while the image is built.  File: ovm.info, Node: run, Prev: build, Up: gen-ovm Tutorial Run the executable ================== $ cd OVM-EXE-DIR $ ./ovm img HelloWorld  File: ovm.info, Node: Invoking gen-ovm, Next: Invoking gen-spec-ovm, Prev: gen-ovm Tutorial, Up: Top Invoking `gen-ovm' ****************** Run `gen-ovm -?' for a list of all options.  File: ovm.info, Node: Invoking gen-spec-ovm, Next: gdb Tutorial, Prev: Invoking gen-ovm, Up: Top Invoking `gen-spec-ovm' *********************** gen-spec-ovm OPTION* `--'? GEN-OVM OPTION* `gen-spec-ovm' is a thin wrapper around `gen-ovm' that builds a virtual machine to execute the SPECjvm98 benchmark suite. `gen-spec-ovm' knows the magic incantations needed to compile SPECjvm98 inside Ovm, and achieve the best performance. `gen-spec-ovm' can also pass configuration options on to `gen-ovm'. `gen-spec-ovm' takes three options: `--spec-dir=DIRECTORY' Gives the path to the SPECjvm98 directory.. The default value (`/p/sss/project/SPECjvm98') works within Purdue. `--test=LIST' where LIST is a comma seperated list of benchmarks to compile. By default, all benchmarks are compiled into a single executable, but `gen-spec-ovm --test=javac' only compiles `_213_javac'. `--applive' Invoke `gen-ovm' with `-app-methods-live' rather than `-ud-reflective-methods=...'. Option processing stops after `--', or before the first argument not prefixed by `--', and remaining arguments are passed to `gen-ovm'. The following example, when run from the SPECjvm98 directory, will execute a single iteration of the `_213_javac' benchmark: > mkdir bin > cd bin > gen-spec-ovm --spec-dir=.. > cd .. > ./bin/ovm bin/img SpecApplication -s100 _213_javac  File: ovm.info, Node: gdb Tutorial, Next: Frequently Asked Questions, Prev: Invoking gen-spec-ovm, Up: Top gdb Tutorial ************ j2c is normally run using `./ovm img MAIN'. To run j2c in gdb, the following commands should be used instead: $ gdb ovm (gdb) r img MAIN * Menu: * Using gdb:: Where to learn more * Statics:: Introduction to j2c variable mangling * Breakpoints:: J2c method mangling and gdb * Navigation:: Review of gdb basics * Locals:: More j2c variable mangling and gdb * Core files:: More gdb basics  File: ovm.info, Node: Using gdb, Next: Statics, Up: gdb Tutorial Using gdb ========= Gdb comes with extensive online documentation. Much of the doucmentation is available within gdb itself through the `help' command. J2c defines a couple useful commands that are documented through `help'. `help user-defined' will list them, and `help CMD' will display help for a particular command. While gdb's built-in help can be useful, the reference manual contains more complete documentation, including a breif tutorial. The location and format of the reference manual varies between platforms. On Macs, gdb's online reference manual is available through . The gdb source distribution also includes a double-sided quick reference card, which Apple has been thoughtful enough to package as a `.pdf' in `/Developer/Documentation/DeveloperTools/gdb/refcard.pdf'. Gdb's online reference manual is available on linux boxes through emacs and the standalone `info' command. In emacs, type `-h i', search for gdb, and follow the link by either middle-clicking on the bold text, or hitting return while the cursor is on bold text. Redhat does not seem to install the quick reference card anywhere, but the Apple version is available at `/p/sss/project/apple-gdb-refcard.pdf'.  File: ovm.info, Node: Statics, Next: Breakpoints, Prev: Using gdb, Up: gdb Tutorial Examining static fields ======================= The values of static fields are readily available in gdb, but to find them, you need to understand a little bit about j2c's naming convention. The convention is based on JNI but appropriately extended to handle mulitple domains and classloaders, and to assign names to fields and local variables. The command pstatic e_s3_core_domain_S3Domain prints all static fields of the class `s3.core.domain.S3Domain' defined in the executive domain. Each field's name is prefixed by `ovm_', and some are subject to other mangling. For instance, the java field `globalInstanceCounter_' becomes `ovm_globalInstanceCounter_1' in C++. JNI maps most characters in a Java identifier to the corresponding ascii character, but there are some exceptions: * `.' and `$' become `_' * `_' becomes `_1' * other characters that C does not allow (such as `<', `>', and anything character not present in 7 bit ASCII is encoded as `_' followed by a 5 digit hex string. System classes (including all classes in the executive domain, and classes in the user domain's runtime library) are mapped to C++ structs whose names consist of a domain prefix (`e_' or `u1_'), followed by the JNI encoding of the class name. This convention is not sufficient in the presence of multiple classloaders, so j2c adds a per-classloader suffix to all non-system classes. For example, the fields of an application class named `HelloWorld' would be defined in the C++ structure `u1_HelloWorld_c2', because the application classoader will always be assigned the unique identifier 2.  File: ovm.info, Node: Breakpoints, Next: Navigation, Prev: Statics, Up: gdb Tutorial Breakpoints, ... ================ A breakpoint is set by supplying a C++ function name to the `break' or `b' command. J2c maps a Java method definition to a toplevel C++ function name by JNI encoding the simple name of the method's class, and the method name, choosing a unique integer, and combining all three seperated by underscores. Suppose we wish to set a breakpoint on the executive domain `Object' constructor. Gdb's tab completion can come to our aid. Typing `b Object__' results in the following: (gdb) b Object__0003c Object__0003cclinit_0003e_13477(u1_java_lang_Object_static) Object__0003cclinit_0003e_13477(u1_java_lang_Object_static*) Object__0003cinit_0003e_26(u1_java_lang_Object) Object__0003cinit_0003e_26(u1_java_lang_Object*) Object__0003cinit_0003e_7(e_java_lang_Object) Object__0003cinit_0003e_7(e_java_lang_Object*) (gdb) b Object__0003c Since we don't care about static inintializers or user-domain object, `i7' will complete the method name we care about. It is often useful to break when an exception is raised. This can be done in a number of ways. J2c currently calls the helper function `j2cThrow' each time a java exception is thrown, so setting a breakpoint on this function will break on every exception. `j2cThrow' takes an `Oop' argument (`HEADER *o' in C++), but we generally care `o''s runtime type rather than it's static type. The command `pclass o' will display the runtime type the exception being thrown. If you issue the command `list j2cThrow', you will notice that java exceptions are mapped to C++ by throwing a pointer to the exceptions runtime type. Hence, we can use gdb's C++ exception support to set Java catchpoints. For instance, we can stop on every bad array dereference in the executive domain with catch throw e_java_lang_ArrayIndexOutOfBoundsException *  File: ovm.info, Node: Navigation, Next: Locals, Prev: Breakpoints, Up: gdb Tutorial Navigation ========== Once the program has hit a breakpoint, it can be run step by step using one of the following commands: * `next', also available with the abbreviation `n': executes the program until the next line of the current function. This instruction can take an integer parameter to say how many times we want it to be repeated. For instance, `next 4' will move 4 lines forward in the execution of the program. * `step', or `s': executes the program until the next source line is reached. If a function with debugging information is called, step will descend into this funciton. * `continue', or `cont': continue until the program hits another breakpoint. This command does also take an optional integer argument that tells how many times the commmand should be repeated. * `finish', or `fin': continue until the current function returns to the caller, and show the value returned. Gdb allows you to examine a program's call stack whether the program is stopped due to a breakpoint, stopped in `abort()', or frozen in a core file. * `bt' or `where': print the program's stack trace * `frame' or `f': select a frame within the stack. You can examine local variables within the selected frame using `print'. * `up': selects the frame the previously selected frame was called from * `down': selects the frame the previously selected frame calls.  File: ovm.info, Node: Locals, Next: Core files, Prev: Navigation, Up: gdb Tutorial Examining local variables ========================= In general, j2c is able to preserve java local variable names. These names are mangled in the same manner as fields, so that `this' becomes `ovm_this'. If we are in a call to `S3Domain.makeThrowable' for the user domain, we can examine the receiver like so print *(e_s3_core_domain_S3JavaUserDomain *) ovm_this Note, when precise GC is enabled, reference variables are not stored in C++ local variables, but in a stack-allocated structure called frame, so the above example becomes print *(e_s3_core_domain_S3JavaUserDomain *) frame.ovm_this Sometimes, j2c is unable to map bytecode-level local variable numbers to source level variable names. In these situations, it is useful to look at all C++ variables in the method, and try to guess where a Java variable is hiding. There are differences between Apple gdb v5.3 and FSF gdb v5.3. The most notable Apple extension is `show locals'. This command prints the names and values of all local variables in the current function. You can get similar results under Linux with the command, `show scope CURRENT-LINE-NUMBER'.  File: ovm.info, Node: Core files, Prev: Locals, Up: gdb Tutorial Inspecting a core dump ====================== If j2c segfaults, the resulting core file can be loaded in gdb using the following command: gdb ovm core You will not be able to run the program, but you will be able to see where it crashed and inspect the values that were present in memory at that time.  File: ovm.info, Node: Frequently Asked Questions, Next: Index, Prev: gdb Tutorial, Up: Top Frequently Asked Questions ************************** * Menu: * User FAQ:: Questions frequently asked by Ovm users. * Developer FAQ:: Questions frequently asked by Ovm developers.  File: ovm.info, Node: User FAQ, Next: Developer FAQ, Up: Frequently Asked Questions Questions frequently asked by Ovm users ======================================= * Menu: * Config err:: Why does `gen-ovm' die with `Configuration Error...'? * Abs meth:: Why does `ovm' die with an assertion failure complaining about abstract methods? * Bin compat:: Why does `gen-ovm' report that methods clearly inherited from interfaces are not found? * Unreachable:: Why does `ovm' die with an assertion failure complaining about a `reflective call to `unreachable' method'? * Clinit:: Why doesn't the above work for a method named `CLASS__0003cclinit_0003e_N', and what is this method anyway? * NoClassDef:: Why am I getting `NoClassDefFoundError' for a class that is clearly defined? * Strip:: How can I run `strip' under Darwin? * Timers:: How do I enable fine-grained timers under RTLinux? * librk-rt.a:: OK, how do I link with RTLinux's magic library?  File: ovm.info, Node: Config err, Next: Abs meth, Up: User FAQ Why does `gen-ovm' die with `Configuration Error...'? ----------------------------------------------------- Image building sometimes fails with the error, `Configuration Error: in CALLING-CLASS: invalid configuration of BASE-TYPE: SELECTED-TYPE is not a subtype of NEEDED-TYPE.' This happens when trying to use an incompatible set build options. Code in the OVM (CALLING-CLASS in particular) needs additional features from the implemenation of BASE-TYPE, but these features are not provided by the configured implemenation (SELECTED-TYPE). Common sources of this error include: * Using an RTSJ aware GC without RTSJ threads. This can be fixed by replacing `-model=MostlyCopyingRegions-B_Mf_F_H' with `-model=MostlyCopyingWB-B_Mf_F_H' or another non-realtime allocator. * Using RTSJ threads with a non-RTSJ aware GC. This can be fixed by invoking `gen-ovm' with `-model=MostlyCopyingRegions-B_Mf_F_H' or any other realtime allocator. * Using a precise GC with a compiler that doesn't support it. This can be fixed by selecting an `-engine' that supports precise GC (such as `intepreter' or `j2c', or by selecting a `-model' that does not require stack maps (such as `minimalMM-B_Mf', or one of the `MostlyCopying' allocators). If none of the above apply, your best bet is to grep for BASE-TYPE in the ovm config files. (By default, these files are installed at `/usr/local/ovm/config'.)  File: ovm.info, Node: Abs meth, Next: Bin compat, Prev: Config err, Up: User FAQ Why does `ovm' die with an assertion failure complaining about abstract methods? -------------------------------------------------------------------------------- If such an error occurs at runtime, `gen-ovm' printed a warning at at compile time describing the problem in greater detail. These errors typically occur in application bytecode due to bugs in Ovm's method resolution code (see *Note Bin compat::). Ovm developers encounter these errors more frequently. These errors occur on a call to a VM-internal method that itself calls a method that only exists at image-build time (inside the `gen-ovm' process). Warnings from `gen-ovm' indicate which methods it treats as build time, and the line number of the method's first build-time call.  File: ovm.info, Node: Bin compat, Next: Unreachable, Prev: Abs meth, Up: User FAQ Why does `gen-ovm' report that methods clearly inherited from interfaces are not found? --------------------------------------------------------------------------------------- J2c's compile-time messages sometimes complain that methods in `javax.realtime' can't be found, or that application methods can't be found when said methods are clearly inheritted from interfaces. Both these problems can be avoided by invoking `javac' more carefully. `javac' should always be invoked as follows: javac -bootclasspath /usr/local/ovm/classes/ovm_rt_user.jar \ -target 1.1 \ JAVA-FILES (You may need to change the path to `ovm_rt_user.jar' depending on where, or whether, you chose to install Ovm.) No other definitions of `javax.realtime' should be present in `javac''s `-classpath' or `-bootclasspath' lists. Setting the appropriate `-bootclasspath' ensures that your code is compiled against the Ovm's `javax.realtime' implemenation, rather than code that implements another version of the RTSJ, or no version of the RTSJ at all. Setting `-target' ensures that `javac' will generate class files that Ovm can understand.  File: ovm.info, Node: Unreachable, Next: Clinit, Prev: Bin compat, Up: User FAQ Why does `ovm' dies with an assertion failure complaining about a `reflective call to `unreachable' method'? ------------------------------------------------------------------------------------------------------------ The current version of J2c requires complete knowledge of reflection at image-build time. Every method that is invoked reflectively must be listed in the `-ud-reflective-methods' switch. Building up this list can be extremely tedious, so we provide two alternatives: * The build-time option `-reflective-method-trace=`file'' can be used with the interpreter or simplejit to dump a list all methods invoked reflectively in the named file. When collecting these traces, you should be careful to excersize all code paths that may lead to a reflective all. Once a complete list of reflective method invocations is built, it can be fed back into ovm with `gen-ovm -engine=j2c -ud-reflective-methods=@`file''. A method will only be listed once on each JVM run, but since the OVM appends to this file, one can accumulate a list of methods invoked across multiple runs. When collecting traces across multiple runs, it may be a good idea to run `sort -u'. * `-app-methods-live' forces j2c to treat all methods defined by the application classloader as possible targets of reflective invocation. Since this option increases build time, bloats the boot image, and inhibits optimization, it should be used with caution. *NOTE:* `-app-methods-live' has no effect in combination with `-opt=run'.  File: ovm.info, Node: Clinit, Next: NoClassDef, Prev: Unreachable, Up: User FAQ Why doesn't the above work for a method named `CLASS__0003cclinit_0003e_N', and what is this method anyway? ----------------------------------------------------------------------------------------------------------- The latter question is the key one: `_0003cclinit_0003e_' corresponds to a `' method in Java bytecode, and this method contains CLASS's static initializers.(1) Static initializers are not explicitly invoked through Java reflection, but may be implicitly invoked through `Class.forName()'. See *Note NoClassDef:: for ways to ensure that a class, and its static initializers are included in an Ovm image. ---------- Footnotes ---------- (1) Note the sequence of two `c's. These methods should not be confused with constructors named `CLASS__0003cinit_0003e_N'. See *Note gdb Tutorial:: for a more complete description of j2c's naming conventions.  File: ovm.info, Node: NoClassDef, Next: Strip, Prev: Clinit, Up: User FAQ Why am I getting `NoClassDefFoundError' for a class that is clearly defined? ---------------------------------------------------------------------------- Typically, this error occurs when a class C is only referenced through `Class.forName()' calls or `C.class' expressions, but this error may also come up if the standard library uses `Class.forName()' incorrectly. If `u1_C' does not appear in `structs.hh', gen-ovm must be explicitly told to include C with the `-ud-reflective-classes' option. As with `-ud-reflective-methods', Ovm provides a couple ways to build this list automatically. * `-app-classes-live' forces the OVM to treat all classes defined by the application classloader as possible targets of `forName()' calls. Since this option increases build time, bloats the boot image, and inhibits optimization, it should be used with caution. *NOTE:* `-app-classes-live' has little effect in combination with `-opt=run'. * `-reflective-class-trace=`file'' can be used in combination with `-app-classes-live' to collect a list of class names that are passed to `forName()' at runtime. The complete list can be fed back to `gen-ovm' with `-ud-reflective-classes=@`file''. A class will only be listed once on each JVM run, but since the OVM appends to this file, one can accumulate a list of classes invoked across multiple runs. When collecting traces across multiple runs, it may be a good idea to run `sort -u'.  File: ovm.info, Node: Strip, Next: Timers, Prev: NoClassDef, Up: User FAQ How can I run `strip' under Darwin? ----------------------------------- In some configurations, ovm generates absolute symbols that point into the initial heap image. For some reason, MacOS's ld does not relocate references to these symbols. `strip -ruA' will strip all symbols that are not needed at runtime.  File: ovm.info, Node: Timers, Next: librk-rt.a, Prev: Strip, Up: User FAQ How do I enable fine-grained timers under RTLinux? -------------------------------------------------- OVM uses a default timer interrupt rate of 10ms. This affects all timed operations, such as sleeps, waits, RTSJ periodic thread release, and RTSJ timers. The timer interrupt rate can be set at runtime using the `-period' runtime argument: ./ovm -period=NNN img MAIN CLASS NAME + ARGS where NNN is a value in microseconds. The requested value will be rounded up to a multiple of the supported underlying timer resolution. A warning is printed if you ask for a timer interrupt rate that is shorter than the supported timer resolution, but no warning is printed if the rate needs to be rounded up. OVM reports that actual timer interrupt rate being used at start-up time. On the majority of Linux systems the supported timer resolution is 10ms. This cannot be changed. Apparently in 2.6 kernel Linux systems this will reduce to 1ms. When running on the licensed Timesys Linux RT system a high resolution implementation of the POSIX real-time timers is available, with a resolution of 1us. To use these timers you must ensure that the Timesys library, `librk-rt.a', is available by setting the `LIBRARY_PATH' environment variable when running configure, and when building the OVM and an OVM image.  File: ovm.info, Node: librk-rt.a, Prev: Timers, Up: User FAQ OK, how do I link with RTLinux's magic library? ----------------------------------------------- First you must have the licensed version of Timesys Linux RT, not the GPL version. If you can find `librk-rt.a' then you have the licensed version. Second, `librk-rt.a' must be locatable by `ld' when the `configure' script runs and when building the OVM and any image. To do this either `librk-rt.a' must be in the default location looked in by `ld' (which is `/usr/lib' normally) or you must set the `LIBRARY_PATH' environment variable to point to the directory where `lbrk-rt.a' is located. Check the `config.log' file to see if `ld' was able to find the library when `configure' ran. Check the build output to see if `-lrk-rt' is being passed as a link option. You might be tempted to edit `ld.so.conf' instead of setting `LIBRARY_PATH'. This is a bad idea. `ld.so.conf' tells `ld.so' where to find dynamically loaded libraries at runtime. You need to tell `ld' where to find the statically linked `librk-rt.a' library at link time - the only way to do this (apart from recompiling `ld') is to set the `LIBRARY_PATH' environment variables (*NOTE*: this is not `LD_LIBRARY_PATH' which is again telling `ld.so' how to dynamically load libraries at runtime.)  File: ovm.info, Node: Developer FAQ, Prev: User FAQ, Up: Frequently Asked Questions Questions frequently asked by Ovm developers ============================================ * Menu: * Eclipse:: How can I use Eclipse on Ovm source code? * Quick Test:: How can I run tests manually? * Regression Test:: How are tests run automatically? * Benchmarks:: How are benchmarks run automatically?  File: ovm.info, Node: Eclipse, Next: Quick Test, Up: Developer FAQ How can I use Eclipse on Ovm source code? ----------------------------------------- Go to `src/' within your build directory, and run `make eclipse-dotfiles'. This target will overwrite `.classpath' and `.project' in your toplevel source directory, and allow you to run Eclipse as before. The `make' target is more reliable than the `.classpath' and `.project' files in CVS, because it knows whether a seperate build directory is being used, and it knows whether `sun.tools.javac.Main' is available in `rt.jar'.  File: ovm.info, Node: Quick Test, Next: Regression Test, Prev: Eclipse, Up: Developer FAQ How can I run tests manually? ----------------------------- By running `make' in the test directory, of course. * `make' will compile and run the standard tests in the default configuration * `make ENGINE=E MODEL=M THREADS=T' will compile and run the configuration defined by E, M, and T. * `make regression-test' will run through the entire test suite (which currently includes 19 configurartions).  File: ovm.info, Node: Regression Test, Next: Benchmarks, Prev: Quick Test, Up: Developer FAQ How are tests run automatically? -------------------------------- They are run on `aardvark.cs.purdue.edu' as the `ovm' psuedo-user. If all tests pass, I delete the entire OpenVM tree. Otherwise, I delete the VM-gen directories of all passing configurations. (These img files really eat up space.) If you are Fil and you are lucky (an unlikely combination), some impossible-to-reproduce bug has resulting in a j2c core dump during automated testing. You can now: me@here> ssh aardvark me@aardvark> sudo -u ovm bash password: YOUR OWN PASSWORD ovm@aardvark> cd /scrach/ovm/OpenVM-YYYYMMDDHH00/test/build-FAILED-TEST ovm@aardvark> gdb ovm core.NNNN  File: ovm.info, Node: Benchmarks, Prev: Regression Test, Up: Developer FAQ How are benchmarks run automatically? ------------------------------------- Benchmarks are run on `cordelia' by `RTJUnit'. To get a better idea of what's going on, check out a copy of `RTJUnit' from `/p/sss/cvs', and take a look at `RTJUnit/scripts/'. RTJUnit's cron jobs updated themselves from CVS, so any changes that are committed to the cvs tree will become part of the benchmark run within a day or two.  File: ovm.info, Node: Index, Prev: Frequently Asked Questions, Up: Top Index ***** * Menu: * compiling SPECjvm98: Invoking gen-spec-ovm. * invoking gen-ovm: Invoking gen-ovm.  Tag Table: Node: Top306 Node: Overview1000 Node: gen-ovm Tutorial6493 Node: install7287 Node: compile8084 Node: build9254 Node: run9853 Node: Invoking gen-ovm10010 Node: Invoking gen-spec-ovm10202 Node: gdb Tutorial11649 Node: Using gdb12251 Node: Statics13618 Node: Breakpoints15339 Node: Navigation17332 Node: Locals18871 Node: Core files20110 Node: Frequently Asked Questions20495 Node: User FAQ20793 Node: Config err21881 Node: Abs meth23408 Node: Bin compat24249 Node: Unreachable25543 Node: Clinit27245 Ref: Clinit-Footnote-127999 Node: NoClassDef28215 Node: Strip29826 Node: Timers30221 Node: librk-rt.a31613 Node: Developer FAQ32948 Node: Eclipse33378 Node: Quick Test33967 Node: Regression Test34492 Node: Benchmarks35271 Node: Index35766  End Tag Table