)]}'
{
  "commit": "6576bffe6cbbb53c5756b2fccd2593ba69b74cdf",
  "tree": "c3337c121d91e60706e07a0b1fc847c30e751229",
  "parents": [
    "8cb6e17571f3fb66ccd4fa19f881602542cd06fc"
  ],
  "author": {
    "name": "Andrew Burgess",
    "email": "aburgess@redhat.com",
    "time": "Thu Jul 07 13:43:45 2022 +0100"
  },
  "committer": {
    "name": "Andrew Burgess",
    "email": "aburgess@redhat.com",
    "time": "Tue Nov 01 09:32:13 2022 +0000"
  },
  "message": "opcodes/arm: add disassembler styling for arm\n\nThis commit adds disassembler styling for the ARM architecture.\n\nThe ARM disassembler is driven by several instruction tables,\ne.g. cde_opcodes, coprocessor_opcodes, neon_opcodes, etc\n\nThe type for elements in each table can vary, but they all have one\nthing in common, a \u0027const char *assembler\u0027 field.  This field\ncontains a string that describes the assembler syntax of the\ninstruction.\n\nEmbedded within that assembler syntax are various escape characters,\nprefixed with a \u0027%\u0027.  Here\u0027s an example of a very simple instruction\nfrom the arm_opcodes table:\n\n  \"pld\\t%a\"\n\nThe \u0027%a\u0027 indicates a particular type of operand, the function\nprint_insn_arm processes the arm_opcodes table, and includes a switch\nstatement that handles the \u0027%a\u0027 operand, and takes care of printing\nthe correct value for that instruction operand.\n\nIt is worth noting that there are many print_* functions, each\nfunction handles a single *_opcodes table, and includes its own switch\nstatement for operand handling.  As a result, every *_opcodes table\nuses a different mapping for the operand escape sequences.  This means\nthat \u0027%a\u0027 might print an address for one *_opcodes table, but in a\ndifferent *_opcodes table \u0027%a\u0027 might print a register operand.\n\nNotice as well that in our example above, the instruction mnemonic\n\u0027pld\u0027 is embedded within the assembler string.  Some instructions also\ninclude comments within the assembler string, for example, also from\nthe arm_opcodes table:\n\n  \"nop\\t\\t\\t@ (mov r0, r0)\"\n\nhere, everything after the \u0027@\u0027 is a comment that is displayed at the\nend of the instruction disassembly.\n\nThe next complexity is that the meaning of some escape sequences is\nnot necessarily fixed.  Consider these two examples from arm_opcodes:\n\n  \"ldrex%c\\tr%12-15d, [%16-19R]\"\n  \"setpan\\t#%9-9d\"\n\nHere, the \u0027%d\u0027 escape is used with a bitfield modifier, \u0027%12-15d\u0027 in\nthe first instruction, and \u0027%9-9d\u0027 in the second instruction, but,\nboth of these are the \u0027%d\u0027 escape.\n\nHowever, in the first instruction, the \u0027%d\u0027 is used to print a\nregister number, notice the \u0027r\u0027 immediately before the \u0027%d\u0027.  In the\nsecond instruction the \u0027%d\u0027 is used to print an immediate, notice the\n\u0027#\u0027 just before the \u0027%d\u0027.\n\nWe have two problems here, first, the \u0027%d\u0027 needs to know if it should\nuse register style or immediate style, and secondly, the \u0027r\u0027 and \u0027#\u0027\ncharacters also need to be styled appropriately.\n\nThe final thing we must consider is that some escape codes result in\nmore than just a single operand being printed, for example, the \u0027%q\u0027\noperand as used in arm_opcodes ends up calling arm_decode_shift, which\ncan print a register name, a shift type, and a shift amount, this\ncould end up using register, sub-mnemonic, and immediate styles, as\nwell as the text style for things like \u0027,\u0027 between the different\nparts.\n\nI propose a three layer approach to adding styling:\n\n(1) Basic state machine:\n\n    When we start printing an instruction we should maintain the idea\n    of a \u0027base_style\u0027.  Every character from the assembler string will\n    be printed using the base_style.\n\n   The base_style will start as mnemonic, as each instruction starts\n   with an instruction mnemonic.  When we encounter the first \u0027\\t\u0027\n   character, the base_style will change to text.  When we encounter\n   the first \u0027@\u0027 the base_style will change to comment_start.\n\n   This simple state machine ensures that for simple instructions the\n   basic parts, except for the operands themselves, will be printed in\n   the correct style.\n\n(2) Simple operand styling:\n\n    For operands that only have a single meaning, or which expand to\n    multiple parts, all of which have a consistent meaning, then I\n    will simply update the operand printing code to print the operand\n    with the correct style.  This will cover a large number of the\n    operands, and is the most consistent with how styling has been\n    added to previous architectures.\n\n(3) New styling syntax in assembler strings:\n\n    For cases like the \u0027%d\u0027 that I describe above, I propose adding a\n    new extension to the assembler syntax.  This extension will allow\n    me to temporarily change the base_style.  Operands like \u0027%d\u0027, will\n    then print using the base_style rather than using a fixed style.\n\n    Here are the two examples from above that use \u0027%d\u0027, updated with\n    the new syntax extension:\n\n      \"ldrex%c\\t%{R:r%12-15d%}, [%16-19R]\"\n      \"setpan\\t%{I:#%9-9d%}\"\n\n    The syntax has the general form \u0027%{X:....%}\u0027 where the \u0027X\u0027\n    character changes to indicate a different style.  In the first\n    instruction I use \u0027%{R:...%}\u0027 to change base_style to the register\n    style, and in the second \u0027%{I:...%}\u0027 changes base_style to\n    immediate style.\n\n    Notice that the \u0027r\u0027 and \u0027#\u0027 characters are included within the new\n    style group, this ensures that these characters are printed with\n    the correct style rather than as text.\n\n    The function decode_base_style maps from character to style.  I\u0027ve\n    included a character for each style for completeness, though only\n    a small number of styles are currently used.\n\nI have updated arm-dis.c to the above scheme, and checked all of the\ntests in gas/testsuite/gas/arm/, and the styling looks reasonable.\n\nThere are no regressions on the ARM gas/binutils/ld tests that I can\nsee, so I don\u0027t believe I\u0027ve changed the output layout at all.  There\nwere two binutils tests for which I needed to force the disassembler\nstyling off.\n\nI can\u0027t guarantee that I\u0027ve not missed some untested corners of the\ndisassembler, or that I might have just missed some incorrectly styled\noutput when reviewing the test results, but I don\u0027t believe I\u0027ve\nintroduced any changes that could break the disassembler - the worst\nshould be some aspect is not styled correctly.\n",
  "tree_diff": [
    {
      "type": "modify",
      "old_id": "9cd057e60f1e181a6cc6dd8f2c151b101da4899d",
      "old_mode": 33188,
      "old_path": "binutils/testsuite/binutils-all/arm/objdump.exp",
      "new_id": "c667577f19eaf7f22484345f74a9cccf83f35202",
      "new_mode": 33188,
      "new_path": "binutils/testsuite/binutils-all/arm/objdump.exp"
    },
    {
      "type": "modify",
      "old_id": "c73a7447b289860ba47975cb3125cf4ce8d01f2d",
      "old_mode": 33188,
      "old_path": "opcodes/arm-dis.c",
      "new_id": "6d302ec50bab1b54fcd36c32f2957ff770f4bf07",
      "new_mode": 33188,
      "new_path": "opcodes/arm-dis.c"
    },
    {
      "type": "modify",
      "old_id": "79a2f3dabe507e2e6c4f9834be58d390c5ef92e9",
      "old_mode": 33188,
      "old_path": "opcodes/disassemble.c",
      "new_id": "0a8f2da629f3b42a7eee4d2a8eea5d6f5ed6b927",
      "new_mode": 33188,
      "new_path": "opcodes/disassemble.c"
    }
  ]
}