URL
https://opencores.org/ocsvn/scarts/scarts/trunk
Subversion Repositories scarts
[/] [scarts/] [trunk/] [toolchain/] [scarts-binutils/] [binutils-2.19.1/] [cgen/] [html.scm] - Rev 7
Go to most recent revision | Compare with Previous | Blame | View Log
; CPU documentation generator, html output ; Copyright (C) 2003, 2009 Doug Evans ; This file is part of CGEN. See file COPYING.CGEN for details. ; ; TODO: ; - assumes names, comments, etc. don't interfere with html. ; Just like in generation of C there are routines to C-ize symbols, ; we need to pass output through an html-izer. ; - make generated html more readable, e.g. more indentation ; - should really print the semantics in pseudo-C, a much better form for ; the intended audience ; - registers that have multiple independent fields (like x86 eflags) ; need to be printed like instruction formats are ; - uses some deprecated html, use css at very least ; - multi-ifields ok? ; - mapping from operands to h/w isn't as clear as it needs to be ; - for insn formats, if field is large consider printing "n ... m", ; would want "n" left justified and "m" right justified though ; - for insn formats, consider printing them better, ; e.g. maybe generate image and include that instead ; - need ability to specify more prose for each architecture ; - assembler support ; - need to add docs to website that can be linked to here, rather than ; including generic cgen documentation here ; - function units, timing, etc. ; - instruction framing ; Global state variables. ; Specify which application. ; String containing copyright text. ; String containing text defining the package we're generating code for. "\ THIS FILE IS MACHINE GENERATED WITH CGEN. See the input .cpu file(s) for copyright information. ""\ "; Initialize the options. ; Handle an option passed in from the command line. "doc""invalid copyright value""cgen""invalid package value""unknown option"; Misc utilities. ; Return COPYRIGHT, with FILE-DESC as the first line ; and PACKAGE as the name of the package which the file belongs in. ; COPYRIGHT is a pair of (header . trailer). "<! ""\n\n""\n""\n""\n>\n\n"; KIND is one of "Architecture" or "Instruction". ; TODO: Add author arg so all replies for this arch go to right person. "<!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. "<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. "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 ; which is a link to the entry's description. ; KIND is one of "mach", "model", etc. "<li>""<a href=\"#""-""\">"" - ""</a>\n""</li>\n"; Cover-fn to gen-list-entry for use with objects. ; Utility to print the header for the description of TEXT. "<a name=\"""\"></a>\n""<h3>""</h3>\n"; Cover-fn to gen-doc-header for use with objects. ; KIND is one of "mach", "model", etc. " - ""-"; Architecture page. "<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 ; I'd like to include the .cpu file tag here, but using English text ; feels more appropriate. Having both is excessive. ; Pick one, and have a link to its description/tag. ; I'm leaning toward using the cgen tag here as we'll probably want ; access (via an html tag) to more than one-liner descriptions. "<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 "</pre></font>\n""</li>\n""<br>\n""""<li>setup-semantics:\n""<font size=+2>\n""<pre>"; no trailing newline here on purpose "</pre></font>\n""</li>\n""<br>\n""""</ul>\n""</li>\n"; NOTE: This includes cpu families. "\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 ; a list is excessive. Later. "<p>\n""<ul>\n""</ul>\n""<p>\n""<h3>CPU Families</h3>\n""<ul>\n""</ul>\n"; Machine page. "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. "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. ; ; TODO: Provide tables of regs for each mach. ; Subroutine of gen-reg-doc-1 to simplify it. ; Generate a list of names of registers in register array REG. ; The catch is that we want to shrink r0,r1,r2,...,r15 to r0...r15. ; We currently only support arrays of rank 1 (vectors). "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. ; Generate a diagram typically used to display instruction fields. ; OPERANDS is a list of numbers (for constant valued ifields) ; or operand names. "<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. ; Generate a diagram typically used to display instruction fields. "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 "</pre></font>\n""</li>\n""<br>\n""""<li>\n""semantics:\n""<font size=+2>\n""<pre>"; no trailing newline here on purpose ; Print the const-folded semantics, computed in `tmp'. "</pre></font>\n""</li>\n"; "<br>\n" ; not present on purpose "<li>\n""execution unit(s):\n""<br>\n""<br>\n""<ul>\n""<li>\n"": "" ""\n""</li>\n"; ignore timings for discarded "</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. ; Traverse the semantics of INSN and return a list of symbols ; indicating various interesting properties we find. ; This is taken from `semantic-attrs' which does the same thing to find the ; CTI attributes. ; The result is list of properties computed from the semantics. ; The possibilities are: MEM, FPU. ; ??? do we need a better context? ; List of attributes computed from SEM-CODE-LIST. ; The first element is just a dummy so that append! always works. ; Called for expressions encountered in SEM-CODE-LIST. ; Don't change to '(MEM), since we use append!. ; Don't change to '(FPU), since we use append!. ; If this is a syntax expression, the operands won't have been ; processed, so tell our caller we want it to by returning #f. ; We do the same for non-syntax expressions to keep things ; simple. This requires collaboration with the traversal ; handlers which are defined to do what we want if we return #f. ; Traverse the expression recording the attributes. ; We just want the side-effects of computing various properties ; so we discard the result. ; Simplified semantics recorded in the `tmp' field. ; Drop dummy first arg and remove duplicates. ; Return boolean indicating if PROPS indicates INSN references memory. ; Return boolean indicating if PROPS indicates INSN uses the fpu. ; Ensure INSN has attribute IDOC. ; If not specified, guess(?). ; Try various heuristics. ; If nothing else works, assume ALU. ; Return subset of insns in IDOC category CAT-NAME. ; CATEGORIES is a list of "enum value" elements for each category. ; See <enum-attribute> for the definition. ; INSNS is already alphabetically sorted and selected for just MACH. ; generate a table of insns for each category ""; lastly, the alphabetical list ; CATEGORIES is a list of "enum value" elements for each category. ; See <enum-attribute> for the definition. ; INSNS is already alphabetically sorted and selected for just MACH. "<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 ; category twice. Left for later if warranted. ; First simplify the semantics, e.g. do constant folding. ; For insns built up from macros, often this will remove a lot of clutter. ; First, install IDOC attributes for insns that don't specify one. "\n""<hr>\n""<a name=\"insns\"></a>\n""<h2>Instructions</h2>\n""Instructions for each machine:\n""<ul>\n"; (string-map (lambda (o) ; (gen-obj-list-entry o "mach-insns")) ; machs) "<li>"" - ""</li>\n""</ul>\n"; (string-list-map (lambda (m) ; (gen-insn-doc-list m insns)) ; machs) "<hr>\n""<h2>Individual instructions descriptions</h2>\n""<br>\n"; Macro-instruction page. "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 "</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. "\n""<hr>\n""<a name=\"assembler\"></a>\n""<h2>Assembler supplemental</h2>\n"; Documentation init,finish,analyzer support. ; Initialize any doc specific things before loading the .cpu file. ; Finish any doc specific things after loading the .cpu file. ; This is separate from analyze-data! as cpu-load performs some ; consistency checks in between. ; Compute various needed globals and assign any computed fields of ; the various objects. This is the standard routine that is called after ; a .cpu file is loaded. ; If the IDOC attribute isn't defined, provide a default one. "insn kind for documentation""Memory""ALU""FPU""Branch""Miscellaneous"; Initialize the rtl->c translator. ; Only include semantic operands when computing the format tables if we're ; generating operand instance tables. ; ??? Actually, may always be able to exclude the semantic operands. ; Still need to traverse the semantics to derive machine computed attributes. ; include aliases? ; analyze semantics? ; Top level C code generators ; Set by the -N argument. "unspecified.html""Generating "".html ...\n""Architecture documentation for "".""Architecture""Generating ""-insn.html ...\n""Instruction documentation for "".""Instruction"; For debugging.
Go to most recent revision | Compare with Previous | Blame | View Log