{"id":29675702,"url":"https://github.com/oxidecomputer/isf","last_synced_at":"2025-07-22T23:38:04.281Z","repository":{"id":264935125,"uuid":"884123678","full_name":"oxidecomputer/isf","owner":"oxidecomputer","description":"ISA Specification Format","archived":false,"fork":false,"pushed_at":"2025-07-16T13:44:29.000Z","size":202,"stargazers_count":5,"open_issues_count":2,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-21T22:54:29.007Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oxidecomputer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-11-06T07:24:43.000Z","updated_at":"2025-07-18T17:48:53.000Z","dependencies_parsed_at":"2024-11-29T01:20:10.483Z","dependency_job_id":null,"html_url":"https://github.com/oxidecomputer/isf","commit_stats":null,"previous_names":["oxidecomputer/isf"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/oxidecomputer/isf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fisf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fisf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fisf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fisf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oxidecomputer","download_url":"https://codeload.github.com/oxidecomputer/isf/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidecomputer%2Fisf/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266591230,"owners_count":23953082,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-22T23:37:58.603Z","updated_at":"2025-07-22T23:38:04.265Z","avatar_url":"https://github.com/oxidecomputer.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ISA Specification Format (ISF)\n\nMany ISA specifications are defined in a collection of PDF documents. End users\nand tooling developers have to pick through the PDF collection to effectively\nwork with the ISA, which is tedious and error prone. Worse, ISA docs are often\nsome combination of incomplete, imprecise or inaccurate. ISF is meant to address\nthese issues.\n\nISF is a DSL with the following goals.\n\n- Completely and unambiguously define an ISA\n- Capture textual assembly and binary machine encodings coherently in one place\n- Generation of assembly and machine code parsers and generators\n- Generation of ISA documentation\n\nISF specifications revolve around instructions. An instruction specification\nis composed of three things\n\n- Fields\n- Assembly representation\n- Machine representation\n\nA simple three-operand add instruction might look like this in ISF.\n\n```isf\n/// Add values from two registers\ninstruction Add {\n  fields:\n    /// The destination register\n    dst: 5,\n    /// The first source register\n    src1: 5,\n    /// The second source register\n    src2: 5,\n    /// Set a flag that sign extends the result\n    sign_extend: 1\n\n  assembly:\n    'add'['.sx' = sign_extend] 'r'dst 'r'src1 'r'src2;\n\n    examples:\n      /// Add the contents of registers 4 and 7 placing the result in\n      /// register 0.\n      add r0 r4 r7;\n\n      /// Add the contents of registers 4 and 7 sign-extending and\n      /// placing the result in register 0.\n      add.sx r0 r4 r7;\n\n  machine:\n    opcode: 7 = 2,\n    sign_extend,\n    dst,\n    _: 3,\n    src1,\n    _: 3,\n    src2,\n    _: 3\n}\n```\n\nInstruction declarations begin with the keyword `instruction` followed by the\nname of the instruction. The body of the instruction is composed of three\nprimary sections `fields`, `assembly` and `machine`. The `fields` section\ndefines all of the _variable_ fields of the instruction. A field definition is\na name and a width in bits. These fields are referenced in the assembly and\nmachine specifications for the instruction in the sections that follow. Fields\nmust have a documentation comment. Documentation comments are a sequence of\nlines that have `///` as the first non-whitespace characters. Documentation\ncomments are _required_ for instructions and fields.\n\nThe `assembly` section describes how an instruction is represented in textual\nassembly language. Quoted strings indicate string literals. Unquoted strings\nmust match a field from the `fields` section. Optional elements are contained\nwithin square brackets. Single bit (boolean) values may be represented as\nstring literals and associated with a field via the `=` assignment operator.\nAssembly specification is terminated wit the `;` operator. The `assembly`\nsection may also contain an `examples` subsection. Examples are a single line\nof assembly. Each example must be directly preceded by a documentation\ncomment.\n\nThe `machine` section describes how an instruction is represented in binary\nmachine language. This is an ordered list of fields. Elements of the list come\nin three forms. 1) The name of a field from the `fields` section. 2) A named\nconstant of the form `name: width = value` where `name` is a string, `width`\nis an unsigned integer specifying the number of bits in the instruction taken\nby the element, and `value` is an unsigned integer specifying the value of the\nfield. 3) An unused series of bits indicated by `_: width`, where `width` is an\nunsigned integer specifying the number of bits.\n\nInstructions can also be parameterized. This is helpful when there is a common\nformat that is used by many instructions. For example, consider a binary\noperation instruction.\n\n```isf\n/// A base instruction for binary arithmetic operations\ninstruction BinOp\u003cname, opcode\u003e {\n  fields:\n    /// The destination register\n    dst: 5,\n    /// The first source register\n    src1: 5,\n    /// The second source register\n    src2: 5,\n    /// Set a flag that sign extends the result\n    sign_extend: 1\n\n  assembly:\n    $name['.sx' = sign_extend] 'r'dst 'r'src1 'r'src2;\n\n  machine:\n    opcode: 7 = $opcode,\n    sign_extend,\n    dst,\n    _: 3,\n    src1,\n    _: 3,\n    src2,\n    _: 3\n}\n```\n\nThis is very similar to the `Add` instruction. It has the same fields, but\nit's parameterized on `name` and `opcode`. Those parameters are used in\nthe `assembly` and `machine` sections to effectively make this a generic\nbinary operation instruction. We can now define concrete instructions in terms\nof this generic instruction.\n\n```isf\n/// Add values from two registers\ninstruction Add: BinOp\u003c'add', 2\u003e {\n  assembly:\n    examples:\n      /// Add the contents of registers 4 and 7 placing the result in\n      /// register 0.\n      add r0 r4 r7;\n\n      /// Add the contents of registers 4 and 7 sign-extending and\n      /// placing the result in register 0.\n      add.sx r0 r4 r7;\n}\n\n/// Subtract values from two registers\ninstruction Sub: BinOp\u003c'sub', 3\u003e {\n  assembly:\n    examples:\n      /// Subtract the contents of registers 4 and 7 placing the result in\n      /// register 0.\n      sub r0 r4 r7;\n\n      /// Subtract the contents of registers 4 and 7 sign-extending and\n      /// placing the result in register 0.\n      sub.sx r0 r4 r7;\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxidecomputer%2Fisf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foxidecomputer%2Fisf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxidecomputer%2Fisf/lists"}