system description

[John Rose]

The output of jextract needs to describe the OS, CPU, and ABI
that libclang was assuming when it processed the header files.

Since we are using JAR files as output, this means we either
use some meta-file, or else we annotate all the top level interfaces.
I think annotations are a good way to go, since they allow jextract
outputs to be combined safely without worrying about meta-files.

Below is a sketch of a way to organize this information.

Influences are Unix /bin/uname, Python's cpuinfo script,
and the porting infrastructure from HotSpot and Maxine.

Comments?

— John

/** An ABI is determined by an OS and a CPU.
 *  Rarely, one or more option settings
 *  may be needed to resolve ambiguity.
 */
@interface ABI {
    /** The operating system where this ABI takes effect. */
    OS os() default @OS(system=SystemFamily.UNKNOWN);
    /** The CPU type on which this ABI takes effect. */
    CPU cpu() default @CPU(arch=CPUArch.UNKNOWN);
    /** What is the byte order for this ABI? */
    ByteOrder order() default ByteOrder.UNKNOWN;
    /** What is the data model for this ABI? */
    DataModel model() default DataModel.UNKNOWN;
    /** Option settings, if any, should be of the form "name=value". */
    String[] options() default {};
}

/** Enumeration of byte orders.
 *  {@code NATIVE} means the byte order of the end-user platform.
 *  @see http://en.wikipedia.org/wiki/Endianness
 */
enum ByteOrder { UNKNOWN, NATIVE, LITTLE, BIG }

/** Enumeration of data models determining the length in bits of C types
 *  {@code int}, {@code long}, {@code long long}, and {@code void*} (pointers).
 *  {@code NATIVE} means the data model of the end-user platform.
 *  @see http://en.wikipedia.org/wiki/64-bit_computing#64-bit_data_models
 */
enum DataModel { UNKNOWN, NATIVE, ILP32, LP64, LLP64, ILP64 }

/** An OS is determined by a system family,
 *  an optional release,
 *  and an optional set of option settings.
 *  The CPU does not need to be specified.
 *  @see http://en.wikipedia.org/wiki/Uname
 */
@interface OS {
    /** System family, as reported by {@code /bin/uname -s}. */
    SystemFamily system();
    /** System release, as reported by {@code /bin/uname -r}. */
    String release() default "";
    /** Option settings, if any, should be of the form "name=value". */
    String[] options() default {};
}

/** Enumeration of system families, as reported by {@code /bin/uname -s}, etc. */
enum SystemFamily { UNKNOWN, LINUX, DARWIN, SOLARIS, WINDOWS }

/** A CPU type as reported by {@code /bin/uname -mpi}.
 *  @see http://en.wikipedia.org/wiki/Uname
 */
@interface CPU {
    CPUArch arch();
    String processor() default ""; // /bin/uname -p
    String platform() default ""; // /bin/uname -i/-m
    String[] options() default {}; // e.g., {"family=6", "model=58", "stepping=9", "brand=Intel(R) Core(TM) i7-3615QM CPU @ 2.30GHz"}
}

/** Enumeration of ISA families, as reported by {@code /bin/uname -m}, etc. */
enum CPUArch { UNKNOWN, X86_64, I386, ARM, SPARC, PPC }


////////////////
// Example use:
@ABI(os=@OS(system=SystemFamily.DARWIN),
     cpu=@CPU(arch=CPUArch.X86_64),
     order=ByteOrder.LITTLE,
     model=DataModel.LP64)
interface mylib { }
////////////////