From 2d4106dd06c835de153bf01e74c7699e64037bb4 Mon Sep 17 00:00:00 2001 From: Andi McClure Date: Mon, 27 Mar 2017 17:50:46 -0400 Subject: [PATCH] Correctly document --aot options in man page - Ensure all AOT options are both documented and listed in alphabetical order in both the manpage and --help line - Ensure all exceptoins are commented in the aot-compiler.c source with "intentionally udnocumented" --- man/mono.1 | 118 ++++++++++++++++++++++++++++++--------- mono/mini/aot-compiler.c | 59 ++++++++++++-------- 2 files changed, 130 insertions(+), 47 deletions(-) diff --git a/man/mono.1 b/man/mono.1 index b4663b40458..352c10b6ce6 100644 --- a/man/mono.1 +++ b/man/mono.1 @@ -110,11 +110,6 @@ than one can be specified: .RS .ne 8 .TP -.I autoreg -The AOT compiler will emit a (ELF only) library initializer to automatically -register the aot compiled module with the runtime. This is only useful in static -mode -.TP .I asmonly Instructs the AOT compiler to output assembly code instead of an object file. @@ -124,11 +119,6 @@ object file. If specified, forces the generated AOT files to be bound to the runtime version of the compiling Mono. This will prevent the AOT files from being consumed by a different Mono runtime. -.I full -.Sp -This is currently an experimental feature as it is not complete. -This instructs Mono to precompile code that has historically not been -precompiled with AOT. .TP .I data-outfile=FILE.dll.aotdata .Sp @@ -140,10 +130,59 @@ on demand by using the .I mono_install_load_aot_data_hook method. .TP +.I direct-icalls +.Sp +When this option is specified, icalls (internal calls made from the +standard library into the mono runtime code) are invoked directly +instead of going through the operating system symbol lookup operation. +This requires use of the +.I static +option. +.TP .I direct-pinvoke .Sp When this option is specified, P/Invoke methods are invoked directly instead of going through the operating system symbol lookup operation. +This requires use of the +.I static +option. +.TP +.I dwarfdebug +Instructs the AOT compiler to emit DWARF debugging information. When +used together with the nodebug option, only DWARF debugging +information is emitted, but not the information that can be used at +runtime. +.TP +.I full +.Sp +This creates binaries which can be used with the --full-aot option. This feature is experimental. +.TP +.I hybrid +.Sp +This creates binaries which can be used with the --hybrid-aot option. This feature is experimental. +.TP +.I llvm +AOT will be performed with the LLVM backend instead of the Mono backend where possible. This will be slower to compile but most likely result in a performance improvement. +.TP +.I llvmonly +AOT will be performed with the LLVM backend exclusively and the Mono backend will not be used. The only output in this mode will be the bitcode file normally specified with the +.I llvm-outfile +option. Use of +.I llvmonly +automatically enables the +.I full +and +.I llvm +options. This feature is experimental. +.TP +.I llvm-outfile=[filename] +Gives the path for the temporary LLVM bitcode file created during AOT. +.TP +.I info +Print the architecture the AOT in this copy of Mono targets and quit. +.TP +.I ld-flags +Additional flags to pass to the C linker (if the current AOT mode calls for invoking it). .TP .I llvm-path= Same for the llvm tools 'opt' and 'llc'. @@ -162,7 +201,12 @@ llc compiler. .I nimt-trampolines=[number] When compiling in full aot mode, the IMT trampolines must be precreated in the AOT image. You can add additional method trampolines with this argument. -Defaults to 128. +Defaults to 512. +.TP +.I ngsharedvt-trampolines=[number] +When compiling in full aot mode, the value type generic sharing trampolines must be precreated +in the AOT image. You can add additional method trampolines with this argument. +Defaults to 512. .TP .I nodebug Instructs the AOT compiler to not output any debugging information. @@ -172,23 +216,22 @@ This prevents the AOT compiler from generating a direct calls to a method. The AOT compiler usually generates direct calls for certain methods that do not require going through the PLT (for example, methods that are known to not require a hook like a static -constructor) or call into simple internal calls. -.TP -.I dwarfdebug -Instructs the AOT compiler to emit DWARF debugging information. When -used together with the nodebug option, only DWARF debugging -information is emitted, but not the information that can be used at -runtime. +constructor) or call into simple internal calls. .TP .I nrgctx-trampolines=[number] When compiling in full aot mode, the generic sharing trampolines must be precreated in the AOT image. You can add additional method trampolines with this argument. -Defaults to 1024. +Defaults to 4096. +.TP +.I nrgctx-fetch-trampolines=[number] +When compiling in full aot mode, the generic sharing fetch trampolines must be precreated +in the AOT image. You can add additional method trampolines with this argument. +Defaults to 128. .TP .I ntrampolines=[number] When compiling in full aot mode, the method trampolines must be precreated in the AOT image. You can add additional method trampolines with this argument. -Defaults to 1024. +Defaults to 4096. .TP .I outfile=[filename] Instructs the AOT compiler to save the output to the specified file. @@ -197,6 +240,16 @@ Instructs the AOT compiler to save the output to the specified file. If the AOT compiler cannot compile a method for any reason, enabling this flag will output the skipped methods to the console. .TP +.I profile=[file] +Specify a file to use for profile-guided optimization. See the "AOT PROFILING" section. To specify multiple files, include the +.I profile +option multiple times. +.TP +.I profile-only +AOT *only* the methods described in the files specified with the +.I profile +option. See the "AOT PROFILING" section. +.TP .I readonly-value=namespace.typename.fieldname=type/value Override the value of a static readonly field. Usually, during JIT compilation, the static constructor is ran eagerly, so the value of @@ -209,7 +262,6 @@ Note that signed/unsigned numbers do not matter here, just the storage size. This option can be specified multiple times and it doesn't prevent the static constructor for the type defining the field to execute with the usual rules at runtime (hence possibly computing a different value for the field). - .TP .I save-temps,keep-temps Instructs the AOT compiler to keep temporary files. @@ -238,6 +290,9 @@ mono_aot_register_module (mono_aot_module_hello_info); .I stats Print various stats collected during AOT compilation. .TP +.I temp_path=[path] +Explicitly specify path to store temporary files created during AOT compilation. +.TP .I threads=[number] This is an experimental option for the AOT compiler to use multiple threads when compiling the methods. @@ -247,8 +302,11 @@ Prepends to the name of tools ran by the AOT compiler, i.e. 'as'/'ld'. example, --tool=prefix=arm-linux-gnueabi- will make the AOT compiler run 'arm-linux-gnueabi-as' instead of 'as'. .TP -.I write-symbols -Instructs the AOT compiler to emit debug symbol information. +.I verbose +Prints additional information about type loading failures. +.TP +.I write-symbols,no-write-symbols +Instructs the AOT compiler to emit (or not emit) debug symbol information. .PP For more information about AOT, see: http://www.mono-project.com/docs/advanced/aot/ .RE @@ -326,8 +384,10 @@ collection a bit. \fB--full-aot\fR This is an experimental flag that instructs the Mono runtime to not generate any code at runtime and depend exclusively on the code -generated from using mono --aot=full previously. This is useful for -platforms that do not permit dynamic code generation. +generated from using mono --aot=full previously. This is useful for +platforms that do not permit dynamic code generation, or if you need +to run assemblies that have been stripped of IL (for example using +mono-cil-strip). .Sp Notice that this feature will abort execution at runtime if a codepath in your program, or Mono's class libraries attempts to generate code @@ -357,6 +417,14 @@ will switch to '/bin/mono64' iff '/bin/mono' is a 32-bit build). \fB--help\fR, \fB-h\fR Displays usage instructions. .TP +\fB--hybrid-aot\fR +This is an experimental flag that allows the Mono runtime to run assemblies +that have been stripped of IL, for example using mono-cil-strip. For this to +work, the assembly must have been AOT compiled with --aot=hybrid. + +This flag is similar to --full-aot, but it does not disable the JIT. This means +you can use dynamic features such as System.Reflection.Emit. +.TP \fB--llvm\fR If the Mono runtime has been compiled with LLVM support (not available in all configurations), Mono will use the LLVM optimization and code diff --git a/mono/mini/aot-compiler.c b/mono/mini/aot-compiler.c index 5ef9b025380..d6dfd3b69d2 100644 --- a/mono/mini/aot-compiler.c +++ b/mono/mini/aot-compiler.c @@ -7138,6 +7138,7 @@ mono_aot_parse_options (const char *aot_options, MonoAotOptions *opts) opts->write_symbols = TRUE; } else if (str_begins_with (arg, "no-write-symbols")) { opts->write_symbols = FALSE; + // Intentionally undocumented -- one-off experiment } else if (str_begins_with (arg, "metadata-only")) { opts->metadata_only = TRUE; } else if (str_begins_with (arg, "bind-to-runtime-version")) { @@ -7159,6 +7160,7 @@ mono_aot_parse_options (const char *aot_options, MonoAotOptions *opts) opts->nodebug = TRUE; } else if (str_begins_with (arg, "dwarfdebug")) { opts->dwarf_debug = TRUE; + // Intentionally undocumented -- No one remembers what this does. It appears to be ARM-only } else if (str_begins_with (arg, "nopagetrampolines")) { opts->use_trampolines_page = FALSE; } else if (str_begins_with (arg, "ntrampolines=")) { @@ -7177,6 +7179,7 @@ mono_aot_parse_options (const char *aot_options, MonoAotOptions *opts) opts->ld_flags = g_strdup (arg + strlen ("ld-flags=")); } else if (str_begins_with (arg, "soft-debug")) { opts->soft_debug = TRUE; + // Intentionally undocumented x2-- deprecated } else if (str_begins_with (arg, "gen-seq-points-file=")) { fprintf (stderr, "Mono Warning: aot option gen-seq-points-file= is deprecated.\n"); } else if (str_begins_with (arg, "gen-seq-points-file")) { @@ -7195,8 +7198,10 @@ mono_aot_parse_options (const char *aot_options, MonoAotOptions *opts) opts->print_skipped_methods = TRUE; } else if (str_begins_with (arg, "stats")) { opts->stats = TRUE; + // Intentionally undocumented-- has no known function other than to debug the compiler } else if (str_begins_with (arg, "no-instances")) { opts->no_instances = TRUE; + // Intentionally undocumented x4-- Used for internal debugging of compiler } else if (str_begins_with (arg, "log-generics")) { opts->log_generics = TRUE; } else if (str_begins_with (arg, "log-instances=")) { @@ -7217,8 +7222,10 @@ mono_aot_parse_options (const char *aot_options, MonoAotOptions *opts) } else if (str_begins_with (arg, "info")) { printf ("AOT target setup: %s.\n", AOT_TARGET_STR); exit (0); + // Intentionally undocumented: Used for precise stack maps, which are not available yet } else if (str_begins_with (arg, "gc-maps")) { mini_gc_enable_gc_maps_for_aot (); + // Intentionally undocumented: Used for internal debugging } else if (str_begins_with (arg, "dump")) { opts->dump_json = TRUE; } else if (str_begins_with (arg, "llvmonly")) { @@ -7235,36 +7242,44 @@ mono_aot_parse_options (const char *aot_options, MonoAotOptions *opts) opts->verbose = TRUE; } else if (str_begins_with (arg, "help") || str_begins_with (arg, "?")) { printf ("Supported options for --aot:\n"); - printf (" outfile=\n"); - printf (" llvm-outfile=\n"); - printf (" llvm-path=\n"); - printf (" temp-path=\n"); - printf (" save-temps\n"); - printf (" keep-temps\n"); - printf (" write-symbols\n"); - printf (" metadata-only\n"); + printf (" asmonly\n"); printf (" bind-to-runtime-version\n"); + printf (" bitcode\n"); + printf (" data-outfile=\n"); + printf (" direct-icalls\n"); + printf (" direct-pinvoke\n"); + printf (" dwarfdebug\n"); printf (" full\n"); - printf (" threads=\n"); - printf (" static\n"); - printf (" asmonly\n"); - printf (" asmwriter\n"); + printf (" hybrid\n"); + printf (" info\n"); + printf (" keep-temps\n"); + printf (" llvm\n"); + printf (" llvmonly\n"); + printf (" llvm-outfile=\n"); + printf (" llvm-path=\n"); + printf (" msym-dir=\n"); + printf (" mtriple\n"); + printf (" nimt-trampolines=\n"); printf (" nodebug\n"); - printf (" dwarfdebug\n"); - printf (" ntrampolines=\n"); + printf (" no-direct-calls\n"); + printf (" no-write-symbols\n"); printf (" nrgctx-trampolines=\n"); - printf (" nimt-trampolines=\n"); + printf (" nrgctx-fetch-trampolines=\n"); printf (" ngsharedvt-trampolines=\n"); - printf (" tool-prefix=\n"); + printf (" ntrampolines=\n"); + printf (" outfile=\n"); + printf (" profile=\n"); + printf (" profile-only\n"); + printf (" print-skipped-methods\n"); printf (" readonly-value=\n"); + printf (" save-temps\n"); printf (" soft-debug\n"); - printf (" msym-dir=\n"); - printf (" gc-maps\n"); - printf (" print-skipped\n"); - printf (" no-instances\n"); + printf (" static\n"); printf (" stats\n"); - printf (" dump\n"); - printf (" info\n"); + printf (" temp-path=\n"); + printf (" tool-prefix=\n"); + printf (" threads=\n"); + printf (" write-symbols\n"); printf (" verbose\n"); printf (" help/?\n"); exit (0); -- 2.25.1