| 1 |
6 |
jlechner |
; CPU documentation generator, html output
|
| 2 |
|
|
; Copyright (C) 2003, 2009 Doug Evans
|
| 3 |
|
|
; This file is part of CGEN. See file COPYING.CGEN for details.
|
| 4 |
|
|
;
|
| 5 |
|
|
; TODO:
|
| 6 |
|
|
; - assumes names, comments, etc. don't interfere with html.
|
| 7 |
|
|
; Just like in generation of C there are routines to C-ize symbols,
|
| 8 |
|
|
; we need to pass output through an html-izer.
|
| 9 |
|
|
; - make generated html more readable, e.g. more indentation
|
| 10 |
|
|
; - should really print the semantics in pseudo-C, a much better form for
|
| 11 |
|
|
; the intended audience
|
| 12 |
|
|
; - registers that have multiple independent fields (like x86 eflags)
|
| 13 |
|
|
; need to be printed like instruction formats are
|
| 14 |
|
|
; - uses some deprecated html, use css at very least
|
| 15 |
|
|
; - multi-ifields ok?
|
| 16 |
|
|
; - mapping from operands to h/w isn't as clear as it needs to be
|
| 17 |
|
|
; - for insn formats, if field is large consider printing "n ... m",
|
| 18 |
|
|
; would want "n" left justified and "m" right justified though
|
| 19 |
|
|
; - for insn formats, consider printing them better,
|
| 20 |
|
|
; e.g. maybe generate image and include that instead
|
| 21 |
|
|
; - need ability to specify more prose for each architecture
|
| 22 |
|
|
; - assembler support
|
| 23 |
|
|
; - need to add docs to website that can be linked to here, rather than
|
| 24 |
|
|
; including generic cgen documentation here
|
| 25 |
|
|
; - function units, timing, etc.
|
| 26 |
|
|
; - instruction framing
|
| 27 |
|
|
|
| 28 |
|
|
; Specify which application.
|
| 29 |
|
|
|
| 30 |
|
|
; String containing text defining the package we're generating code for.
|
| 31 |
|
|
"\
|
| 32 |
|
|
|
| 33 |
|
|
|
| 34 |
|
|
See the input .cpu file(s) for copyright information.
|
| 35 |
|
|
|
| 36 |
|
|
"; Initialize the options.
|
| 37 |
|
|
; Handle an option passed in from the command line.
|
| 38 |
|
|
|
| 39 |
|
|
; Return COPYRIGHT, with FILE-DESC as the first line
|
| 40 |
|
|
; and PACKAGE as the name of the package which the file belongs in.
|
| 41 |
|
|
; COPYRIGHT is a pair of (header . trailer).
|
| 42 |
|
|
|
| 43 |
|
|
; TODO: Add author arg so all replies for this arch go to right person.
|
| 44 |
|
|
"<!doctype html public \"-//w3c//dtd html 4.0 transitional//en\">\n""<html>\n""<head>\n"" <meta http-equiv=\"Content-Type\" content=\"text/html; charset=iso-8859-1\">\n"" <meta name=\"description\" content=\""" "" Documentation\">\n"" <meta name=\"language\" content=\"en-us\">\n"" <meta name=\"owner\" content=\"dje@sebabeach.org (Doug Evans)\">\n"" <meta name=\"reply-to\" content=\"dje@sebabeach.org (Doug Evans)\">\n"" <title>"" "" Documentation</title>\n""</head>\n""<body bgcolor=\"#F0F0F0\" TEXT=\"#003333\" LINK=\"#FF0000\" VLINK=\"#444444\" alink=\"#000000\">\n""\n""<p><hr><p>\n""This documentation was machine generated from the cgen cpu description\n""files for this architecture.\n""<br>\n""<a href=\"http://sources.redhat.com/cgen/\">http://sources.redhat.com/cgen/</a>\n""</body>\n""</html>\n"; INSN-FILE is the name of the .html file containing instruction definitions.
|
| 45 |
|
|
"<h1>\n"" Architecture Documentation""</h1>\n""\n""<br>\n""DISCLAIMER: This documentation is derived from the cgen cpu description\n""of this architecture, and does not represent official documentation\n""of the chip maker.\n""<p><hr><p>\n""\n""<ul>\n""<li><a href=\"#arch\">Architecture</a></li>\n""<li><a href=\"#machines\">Machine variants</a></li>\n""<li><a href=\"#models\">Model variants</a></li>\n""<li><a href=\"#registers\">Registers</a></li>\n""<li><a href=\"""#insns\">Instructions</a></li>\n""<li><a href=\"""#macro-insns\">Macro instructions</a></li>\n""<li><a href=\"#assembler\">Assembler supplemental</a></li>\n""</ul>\n""<br>\n"; TODO: Move this to the cgen website, and include a link here.
|
| 46 |
|
|
"In cgen-parlance, an architecture consists of machines and models.\n""A `machine' is the specification of a variant of the architecture,\n""and a `model' is the implementation of that specification.\n""Typically there is a one-to-one correspondance between machine and model.\n""The distinction allows for separation of what application programs see\n""(the machine), and how to tune for the chip (what the compiler sees).\n""<br>\n""A \"cpu family\" is a cgen concoction to help organize the generated code.\n""Chip variants that are quite dissimilar can be treated separately by the\n""generated code even though they're both members of the same architecture.\n"; Utility to print a list entry for NAME/COMMENT, kind KIND
|
| 47 |
|
|
|
| 48 |
|
|
; KIND is one of "mach", "model", etc.
|
| 49 |
|
|
|
| 50 |
|
|
; Utility to print the header for the description of TEXT.
|
| 51 |
|
|
"<a name=\"""\"></a>\n""<h3>""</h3>\n"; Cover-fn to gen-doc-header for use with objects.
|
| 52 |
|
|
; KIND is one of "mach", "model", etc.
|
| 53 |
|
|
" - ""-"; Architecture page.
|
| 54 |
|
|
"<li>\n"" - ""\n""<br>\n""<br>\n""Machines:\n""<ul>\n""</ul>\n""</li>\n""<br>\n""<li>\n"" - ""\n""<br>\n""<br>\n""Models:\n""<ul>\n""</ul>\n""</li>\n""<br>\n""<li>\n"" - ""\n""<br>\n""</li>\n""<li>\n"" - ""\n""<br>\n"; FIXME: wip
|
| 55 |
|
|
|
| 56 |
|
|
; feels more appropriate. Having both is excessive.
|
| 57 |
|
|
|
| 58 |
|
|
; I'm leaning toward using the cgen tag here as we'll probably want
|
| 59 |
|
|
; access (via an html tag) to more than one-liner descriptions.
|
| 60 |
|
|
"<ul>\n""<li>default-insn-word-bitsize: ""</li>\n""<br>\n""<li>default-insn-bitsize: ""</li>\n""<br>\n""<li>base-insn-bitsize: ""</li>\n""<br>\n""<li>decode-assist: "" ""</li>\n""<br>\n""<li>decode-splits: "" ""</li>\n""<br>\n""<li>liw-insns: ""</li>\n""<br>\n""""<li>parallel-insns: ""</li>\n""<br>\n""""<li>condition-field: ""</li>\n""<br>\n""<li>condition:\n""<font size=+2>\n""<pre>"; no trailing newline here on purpose
|
| 61 |
|
|
"</pre></font>\n""</li>\n""<br>\n""""<li>setup-semantics:\n""<font size=+2>\n""<pre>"; no trailing newline here on purpose
|
| 62 |
|
|
"</pre></font>\n""</li>\n""<br>\n""""</ul>\n""</li>\n"; NOTE: This includes cpu families.
|
| 63 |
|
|
"\n""<hr>\n""<a name=\"arch\"></a>\n""<h2>"" Architecture</h2>\n""<p>\n""This section describes various things about the cgen description of\n""the "" architecture. Familiarity with cgen cpu descriptions\n""is assumed.\n""<p>\n""Bit number orientation (arch.lsb0?): ""lsb = 0""msb = 0""\n""<p>\n""<h3>ISA description</h3>\n"; NOTE: For the normal case there's only one isa, thus specifying it in
|
| 64 |
|
|
; a list is excessive. Later.
|
| 65 |
|
|
"<p>\n""<ul>\n""</ul>\n""<p>\n""<h3>CPU Families</h3>\n""<ul>\n""</ul>\n"; Machine page.
|
| 66 |
|
|
"mach""<ul>\n""<li>\n""bfd-name: ""\n""</li>\n""<li>\n""isas: "" ""\n""</li>\n""</ul>\n""\n""<hr>\n""<a name=\"machines\"></a>\n""<h2>Machine variants</h2>\n""<ul>\n""mach""</ul>\n"; Model page.
|
| 67 |
|
|
"model""<ul>\n""</ul>\n""\n""<hr>\n""<a name=\"models\"></a>\n""<h2>Model variants</h2>\n""<ul>\n""model""</ul>\n"; Register page.
|
| 68 |
|
|
;
|
| 69 |
|
|
; TODO: Provide tables of regs for each mach.
|
| 70 |
|
|
|
| 71 |
|
|
; Generate a list of names of registers in register array REG.
|
| 72 |
|
|
|
| 73 |
|
|
; We currently only support arrays of rank 1 (vectors).
|
| 74 |
|
|
"gen-pretty-reg-array-names: unsupported rank""<br>\n""names:\n""<br>\n""<table frame=border border=2>\n""<tr>\n""<tr>\n""<td>""</td>\n""<td>""</td>\n""</tr>\n""""reg""<ul>\n""<li>\n""machines: "" ""\n""</li>\n""<li>\n""bitsize: ""\n""</li>\n""<li>\n""array: ""[""]""\n""</li>\n""""</ul>\n""\n""<hr>\n""<a name=\"registers\"></a>\n""<h2>Registers</h2>\n""<ul>\n""reg""</ul>\n"; Instruction page.
|
| 75 |
|
|
; Generate a diagram typically used to display instruction fields.
|
| 76 |
|
|
|
| 77 |
|
|
; or operand names.
|
| 78 |
|
|
"<table frame=border border=2>\n""<tr>\n""<td>\n"" ""\n""</td>\n""</tr>\n""<tr>\n""<td>\n""\n""</td>\n""</tr>\n""<tr>\n""<td>\n""0x""\n""</td>\n""</tr>\n""</table>\n"; Compute the list of field bit-numbers for each field.
|
| 79 |
|
|
; Generate a diagram typically used to display instruction fields.
|
| 80 |
|
|
"insn""<ul>\n""<li>\n""machines: "" ""\n""</li>\n""<br>\n""<li>\n""syntax: ""<tt><font size=+2>""</font></tt>\n""</li>\n""<br>\n""<li>\n""format:\n""</li>\n""<br>\n""<li>\n""instruction field constraint:\n""<font size=+2>\n""<pre>"; no trailing newline here on purpose
|
| 81 |
|
|
"</pre></font>\n""</li>\n""<br>\n""""<li>\n""semantics:\n""<font size=+2>\n""<pre>"; no trailing newline here on purpose
|
| 82 |
|
|
; Print the const-folded semantics, computed in `tmp'.
|
| 83 |
|
|
"</pre></font>\n""</li>\n"; "<br>\n" ; not present on purpose
|
| 84 |
|
|
|
| 85 |
|
|
"</ul>\n""</li>\n""<br>\n""""</ul>\n""<hr>\n"" """""" - ""mach-insns-""-""<ul>\n""insn""</ul>\n"; Return boolean indicating if INSN sets the pc.
|
| 86 |
|
|
; Traverse the semantics of INSN and return a list of symbols
|
| 87 |
|
|
|
| 88 |
|
|
; This is taken from `semantic-attrs' which does the same thing to find the
|
| 89 |
|
|
; CTI attributes.
|
| 90 |
|
|
; The result is list of properties computed from the semantics.
|
| 91 |
|
|
; The possibilities are: MEM, FPU.
|
| 92 |
|
|
; ??? do we need a better context?
|
| 93 |
|
|
; List of attributes computed from SEM-CODE-LIST.
|
| 94 |
|
|
; The first element is just a dummy so that append! always works.
|
| 95 |
|
|
; Called for expressions encountered in SEM-CODE-LIST.
|
| 96 |
|
|
; Don't change to '(MEM), since we use append!.
|
| 97 |
|
|
; Don't change to '(FPU), since we use append!.
|
| 98 |
|
|
; If this is a syntax expression, the operands won't have been
|
| 99 |
|
|
; processed, so tell our caller we want it to by returning #f.
|
| 100 |
|
|
; We do the same for non-syntax expressions to keep things
|
| 101 |
|
|
; simple. This requires collaboration with the traversal
|
| 102 |
|
|
; handlers which are defined to do what we want if we return #f.
|
| 103 |
|
|
; Traverse the expression recording the attributes.
|
| 104 |
|
|
; We just want the side-effects of computing various properties
|
| 105 |
|
|
; so we discard the result.
|
| 106 |
|
|
|
| 107 |
|
|
; Drop dummy first arg and remove duplicates.
|
| 108 |
|
|
; Return boolean indicating if PROPS indicates INSN references memory.
|
| 109 |
|
|
; Return boolean indicating if PROPS indicates INSN uses the fpu.
|
| 110 |
|
|
; Ensure INSN has attribute IDOC.
|
| 111 |
|
|
; If not specified, guess(?).
|
| 112 |
|
|
; Try various heuristics.
|
| 113 |
|
|
; If nothing else works, assume ALU.
|
| 114 |
|
|
; Return subset of insns in IDOC category CAT-NAME.
|
| 115 |
|
|
; CATEGORIES is a list of "enum value" elements for each category.
|
| 116 |
|
|
; See <enum-attribute> for the definition.
|
| 117 |
|
|
; INSNS is already alphabetically sorted and selected for just MACH.
|
| 118 |
|
|
; generate a table of insns for each category
|
| 119 |
|
|
|
| 120 |
|
|
; CATEGORIES is a list of "enum value" elements for each category.
|
| 121 |
|
|
|
| 122 |
|
|
; INSNS is already alphabetically sorted and selected for just MACH.
|
| 123 |
|
|
"<ul>\n""""<li><a href=\"#mach-insns-""-""\">"""""" - ""</a></li>\n""<li><a href=\"#mach-insns-""-""\">alphabetically</a></li>\n""</ul>\n"; ??? There's an inefficiency here, we compute insns for each mach for each
|
| 124 |
|
|
; category twice. Left for later if warranted.
|
| 125 |
|
|
; First simplify the semantics, e.g. do constant folding.
|
| 126 |
|
|
; For insns built up from macros, often this will remove a lot of clutter.
|
| 127 |
|
|
; First, install IDOC attributes for insns that don't specify one.
|
| 128 |
|
|
"\n""<hr>\n""<a name=\"insns\"></a>\n""<h2>Instructions</h2>\n""Instructions for each machine:\n""<ul>\n"; (string-map (lambda (o)
|
| 129 |
|
|
; (gen-obj-list-entry o "mach-insns"))
|
| 130 |
|
|
; machs)
|
| 131 |
|
|
"<li>"" - ""</li>\n""</ul>\n"; (string-list-map (lambda (m)
|
| 132 |
|
|
; (gen-insn-doc-list m insns))
|
| 133 |
|
|
; machs)
|
| 134 |
|
|
"<hr>\n""<h2>Individual instructions descriptions</h2>\n""<br>\n"; Macro-instruction page.
|
| 135 |
|
|
"macro-insn""<ul>\n""<li>\n""syntax: ""<tt><font size=+2>""</font></tt>\n""</li>\n""<br>\n""<li>\n""transformation:\n""<font size=+2>\n""<pre>"; no trailing newline here on purpose
|
| 136 |
|
|
"</pre></font>\n""</li>\n""</ul>\n""mach-macro-insns""<ul>\n""macro-insn""</ul>\n""\n""<hr>\n""<a name=\"macro-insns\"></a>\n""<h2>Macro Instructions</h2>\n""Macro instructions for each machine:\n""<ul>\n""mach-macro-insns""</ul>\n""<p>\n""<h2>Individual macro-instructions descriptions</h2>\n""<br>\n"; Assembler page.
|
| 137 |
|
|
"\n""<hr>\n""<a name=\"assembler\"></a>\n""<h2>Assembler supplemental</h2>\n"; Documentation init,finish,analyzer support.
|
| 138 |
|
|
; Initialize any doc specific things before loading the .cpu file.
|
| 139 |
|
|
; Finish any doc specific things after loading the .cpu file.
|
| 140 |
|
|
; This is separate from analyze-data! as cpu-load performs some
|
| 141 |
|
|
; consistency checks in between.
|
| 142 |
|
|
; Compute various needed globals and assign any computed fields of
|
| 143 |
|
|
; the various objects. This is the standard routine that is called after
|
| 144 |
|
|
; a .cpu file is loaded.
|
| 145 |
|
|
; If the IDOC attribute isn't defined, provide a default one.
|
| 146 |
|
|
"insn kind for documentation""Memory""ALU""FPU""Branch""Miscellaneous"; Initialize the rtl->c translator.
|
| 147 |
|
|
; Only include semantic operands when computing the format tables if we're
|
| 148 |
|
|
; generating operand instance tables.
|
| 149 |
|
|
; ??? Actually, may always be able to exclude the semantic operands.
|
| 150 |
|
|
; Still need to traverse the semantics to derive machine computed attributes.
|
| 151 |
|
|
; include aliases?
|
| 152 |
|
|
; analyze semantics?
|
| 153 |
|
|
; Top level C code generators
|
| 154 |
|
|
; Set by the -N argument.
|
| 155 |
|
|
"unspecified.html""Generating "".html ...\n""Architecture documentation for "".""Architecture""Generating ""-insn.html ...\n""Instruction documentation for "".""Instruction"; For debugging.
|
| 156 |
|
|
|
