From patchwork Tue Mar 12 17:03:24 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Richard Henderson X-Patchwork-Id: 160172 Delivered-To: patch@linaro.org Received: by 2002:ac9:18c7:0:0:0:0:0 with SMTP id i7csp13252366oce; Tue, 12 Mar 2019 11:08:36 -0700 (PDT) X-Google-Smtp-Source: APXvYqyS4liROR0l0wJJpu/iUcgGclFHlJ67y9QeLGyFj3/MkBHZmxY68cwGKFYWqktwTESMvyvD X-Received: by 2002:a25:c78e:: with SMTP id w136mr33498792ybe.358.1552414116010; Tue, 12 Mar 2019 11:08:36 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1552414116; cv=none; d=google.com; s=arc-20160816; b=Gi4LmaV3XgIol0T8KwldIUUSwPjEeyDEZA73tev5+PV4ZnnN5z77qLy3QZuANe1UVR t2VHF2ZMskuduM5xy1C2bp7sywVOxvo7R2C9XWFbIkIXlY7PJDMjgCncnDMAuDTn7BXv t2NusJqo6c+NYY7TUz8ewqn7NJJOd/YUyZvb99KcOTvWoaN7BocQYzVRL81Vl9FUsd29 E1cWJ3OO+toE0L6tg5ZuaMU26OWl2dLLFpkYFABpU1ZdigoCgzcCWDmHSTAZ4M68sT4i ccHsM66RTWS/wBsTRkZnliJayCDawJz3ELnHYm5Kun23E62XYEaDFPFdzZvJI5Ipkjjv PXDg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject:references:in-reply-to :message-id:date:to:from:dkim-signature; bh=6ZHAJwXfZDm7adevkZ6nWf5hMn2SlST8Sb6jn0aG3mo=; b=T66VijglOzHZtGSdjoZ8EWisW4Kdt45n+r8UG+KLb6VMI4B/Dggc/5j6Xf5BnBuhdq ORzQprrTlHww5K/2rCkYruT+cr7CtD0TQEkE6n5dKbc0BI4OJhZeka2FyCcANaarHneJ 0UuQDSKFqHz7G4YUBJLwOuFZ4B9Ph5TK/TIeSFaMvmWRveggPc/F7+Xa+1MY1OkFIUHp I8T9Pylsf6EqZMqiz+vMwSQSkZh7kCvOvF1pJVD1jmiuNkptaYQAQLtMtIgmOjep5vZo uDFxZM6daKojWEyog/HCV6Ne2s+uGL1kducrK2WnZuR7uf+M6VFmbhQgOqIR9uqmRmme cx9A== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=cRmdF+L+; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id k141si5367663ybk.488.2019.03.12.11.08.35 for (version=TLS1 cipher=AES128-SHA bits=128/128); Tue, 12 Mar 2019 11:08:35 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=cRmdF+L+; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([127.0.0.1]:57033 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h3lpL-0006zb-Do for patch@linaro.org; Tue, 12 Mar 2019 14:08:35 -0400 Received: from eggs.gnu.org ([209.51.188.92]:51125) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h3l3P-0005kf-1Z for qemu-devel@nongnu.org; Tue, 12 Mar 2019 13:19:06 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1h3koW-00018G-MY for qemu-devel@nongnu.org; Tue, 12 Mar 2019 13:03:42 -0400 Received: from mail-pf1-x42c.google.com ([2607:f8b0:4864:20::42c]:45308) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1h3koW-00017b-C8 for qemu-devel@nongnu.org; Tue, 12 Mar 2019 13:03:40 -0400 Received: by mail-pf1-x42c.google.com with SMTP id v21so2247075pfm.12 for ; Tue, 12 Mar 2019 10:03:40 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=6ZHAJwXfZDm7adevkZ6nWf5hMn2SlST8Sb6jn0aG3mo=; b=cRmdF+L+q8F+BK1dQq1K0SgWZP3V2MguUxNUgKa1JLL3AJC5aUXQm5FScprzrSPENT Eeb+XqiDbi9evMYR2KFn0wxGBewEi02XI8xSx4PUj5tdxNQzYhE2iaydoNdvZ/VqcaZS L+j73c0stuIHEoNiKPtoI3SmlM3lpdzHi3hHSKA8Af4T7O2Mhe7mgO/aETB5d5vKyYQn GTrBd86VT0svRO5R/jaxpp/Vaq5ooucAWbrEfjomR8uPWfNDs8pmyI9d6vQlHo0BiDpj hWZ1PHM/VcSYcnV17pUegIEVlOwbaZa+G5ctPtfh+zdfY8a8BtZCoPJxLKjeMefL4H4S dxww== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=6ZHAJwXfZDm7adevkZ6nWf5hMn2SlST8Sb6jn0aG3mo=; b=Av75dLlDqMxAn4bNAC3etqi+WzsU6yomMZ5o2m3H0HgUvFLqc0OnVZD8L8gjMXiOR7 KC2cZmlmLf92cIx1JEcEWaDqHjssF8yrRF5Hv5Z7vnpw6U4wDovvOpRIJ9o1Yh+AVw0p x5WVGAaiEmzrOoziyyPKT7J4nALSj7S8mwd3StU9RoGGc1T7uYycbVrFOjBYZ3Vpq5zY for+88a4lL5UvB9zlyzqbtcynjbuoKnGTVGUx5CQLq7/2ZFjw6ZNAWRSH4uJmIMHeShK TXSZK7As/KS8zFC1YeWwfoBkd2WyzANsRXoek6fodZbA1Ulu5fwjFKnuMGjhROc2MLCc NQhA== X-Gm-Message-State: APjAAAWbXyKXcr1x9UEzlK0zZWNy3IyrQ8e0CABXLovX9W8qxo1Y3hOE CMEr5J7DQtOZn21POThkBTKNc7RpuKw= X-Received: by 2002:a63:4e1d:: with SMTP id c29mr36447115pgb.433.1552410218683; Tue, 12 Mar 2019 10:03:38 -0700 (PDT) Received: from cloudburst.twiddle.net (97-113-188-82.tukw.qwest.net. [97.113.188.82]) by smtp.gmail.com with ESMTPSA id v22sm17514265pfa.49.2019.03.12.10.03.37 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Tue, 12 Mar 2019 10:03:37 -0700 (PDT) From: Richard Henderson To: qemu-devel@nongnu.org Date: Tue, 12 Mar 2019 10:03:24 -0700 Message-Id: <20190312170334.14005-3-richard.henderson@linaro.org> X-Mailer: git-send-email 2.17.2 In-Reply-To: <20190312170334.14005-1-richard.henderson@linaro.org> References: <20190312170334.14005-1-richard.henderson@linaro.org> X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2607:f8b0:4864:20::42c Subject: [Qemu-devel] [PULL 02/12] decodetree: Move documentation to docs/devel/decodetree.rst X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: peter.maydell@linaro.org Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" One great big block comment isn't the best way to document the syntax of a language. Reviewed-by: Bastian Koppelmann Signed-off-by: Richard Henderson --- MAINTAINERS | 1 + docs/devel/decodetree.rst | 156 ++++++++++++++++++++++++++++++++++++++ docs/devel/index.rst | 2 +- scripts/decodetree.py | 134 +------------------------------- 4 files changed, 159 insertions(+), 134 deletions(-) create mode 100644 docs/devel/decodetree.rst -- 2.17.2 diff --git a/MAINTAINERS b/MAINTAINERS index 3426d3369d..564b8dba6e 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -118,6 +118,7 @@ F: exec.c F: accel/tcg/ F: accel/stubs/tcg-stub.c F: scripts/decodetree.py +F: docs/devel/decodetree.rst F: include/exec/cpu*.h F: include/exec/exec-all.h F: include/exec/helper*.h diff --git a/docs/devel/decodetree.rst b/docs/devel/decodetree.rst new file mode 100644 index 0000000000..d9be30b2db --- /dev/null +++ b/docs/devel/decodetree.rst @@ -0,0 +1,156 @@ +======================== +Decodetree Specification +======================== + +A *decodetree* is built from instruction *patterns*. A pattern may +represent a single architectural instruction or a group of same, depending +on what is convenient for further processing. + +Each pattern has both *fixedbits* and *fixedmask*, the combination of which +describes the condition under which the pattern is matched:: + + (insn & fixedmask) == fixedbits + +Each pattern may have *fields*, which are extracted from the insn and +passed along to the translator. Examples of such are registers, +immediates, and sub-opcodes. + +In support of patterns, one may declare *fields*, *argument sets*, and +*formats*, each of which may be re-used to simplify further definitions. + +Fields +====== + +Syntax:: + + field_def := '%' identifier ( unnamed_field )+ ( !function=identifier )? + unnamed_field := number ':' ( 's' ) number + +For *unnamed_field*, the first number is the least-significant bit position +of the field and the second number is the length of the field. If the 's' is +present, the field is considered signed. If multiple ``unnamed_fields`` are +present, they are concatenated. In this way one can define disjoint fields. + +If ``!function`` is specified, the concatenated result is passed through the +named function, taking and returning an integral value. + +FIXME: the fields of the structure into which this result will be stored +is restricted to ``int``. Which means that we cannot expand 64-bit items. + +Field examples: + ++---------------------------+---------------------------------------------+ +| Input | Generated code | ++===========================+=============================================+ +| %disp 0:s16 | sextract(i, 0, 16) | ++---------------------------+---------------------------------------------+ +| %imm9 16:6 10:3 | extract(i, 16, 6) << 3 | extract(i, 10, 3) | ++---------------------------+---------------------------------------------+ +| %disp12 0:s1 1:1 2:10 | sextract(i, 0, 1) << 11 | | +| | extract(i, 1, 1) << 10 | | +| | extract(i, 2, 10) | ++---------------------------+---------------------------------------------+ +| %shimm8 5:s8 13:1 | expand_shimm8(sextract(i, 5, 8) << 1 | | +| !function=expand_shimm8 | extract(i, 13, 1)) | ++---------------------------+---------------------------------------------+ + +Argument Sets +============= + +Syntax:: + + args_def := '&' identifier ( args_elt )+ ( !extern )? + args_elt := identifier + +Each *args_elt* defines an argument within the argument set. +Each argument set will be rendered as a C structure "arg_$name" +with each of the fields being one of the member arguments. + +If ``!extern`` is specified, the backing structure is assumed +to have been already declared, typically via a second decoder. + +Argument set examples:: + + ®3 ra rb rc + &loadstore reg base offset + + +Formats +======= + +Syntax:: + + fmt_def := '@' identifier ( fmt_elt )+ + fmt_elt := fixedbit_elt | field_elt | field_ref | args_ref + fixedbit_elt := [01.-]+ + field_elt := identifier ':' 's'? number + field_ref := '%' identifier | identifier '=' '%' identifier + args_ref := '&' identifier + +Defining a format is a handy way to avoid replicating groups of fields +across many instruction patterns. + +A *fixedbit_elt* describes a contiguous sequence of bits that must +be 1, 0, or don't care. The difference between '.' and '-' +is that '.' means that the bit will be covered with a field or a +final 0 or 1 from the pattern, and '-' means that the bit is really +ignored by the cpu and will not be specified. + +A *field_elt* describes a simple field only given a width; the position of +the field is implied by its position with respect to other *fixedbit_elt* +and *field_elt*. + +If any *fixedbit_elt* or *field_elt* appear, then all bits must be defined. +Padding with a *fixedbit_elt* of all '.' is an easy way to accomplish that. + +A *field_ref* incorporates a field by reference. This is the only way to +add a complex field to a format. A field may be renamed in the process +via assignment to another identifier. This is intended to allow the +same argument set be used with disjoint named fields. + +A single *args_ref* may specify an argument set to use for the format. +The set of fields in the format must be a subset of the arguments in +the argument set. If an argument set is not specified, one will be +inferred from the set of fields. + +It is recommended, but not required, that all *field_ref* and *args_ref* +appear at the end of the line, not interleaving with *fixedbit_elf* or +*field_elt*. + +Format examples:: + + @opr ...... ra:5 rb:5 ... 0 ....... rc:5 + @opi ...... ra:5 lit:8 1 ....... rc:5 + +Patterns +======== + +Syntax:: + + pat_def := identifier ( pat_elt )+ + pat_elt := fixedbit_elt | field_elt | field_ref | args_ref | fmt_ref | const_elt + fmt_ref := '@' identifier + const_elt := identifier '=' number + +The *fixedbit_elt* and *field_elt* specifiers are unchanged from formats. +A pattern that does not specify a named format will have one inferred +from a referenced argument set (if present) and the set of fields. + +A *const_elt* allows a argument to be set to a constant value. This may +come in handy when fields overlap between patterns and one has to +include the values in the *fixedbit_elt* instead. + +The decoder will call a translator function for each pattern matched. + +Pattern examples:: + + addl_r 010000 ..... ..... .... 0000000 ..... @opr + addl_i 010000 ..... ..... .... 0000000 ..... @opi + +which will, in part, invoke:: + + trans_addl_r(ctx, &arg_opr, insn) + +and:: + + trans_addl_i(ctx, &arg_opi, insn) diff --git a/docs/devel/index.rst b/docs/devel/index.rst index 6b11e49caa..ebbab636ce 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -19,4 +19,4 @@ Contents: migration stable-process testing - + decodetree diff --git a/scripts/decodetree.py b/scripts/decodetree.py index e342d278b8..33e32ee87f 100755 --- a/scripts/decodetree.py +++ b/scripts/decodetree.py @@ -17,139 +17,7 @@ # # Generate a decoding tree from a specification file. -# -# The tree is built from instruction "patterns". A pattern may represent -# a single architectural instruction or a group of same, depending on what -# is convenient for further processing. -# -# Each pattern has "fixedbits" & "fixedmask", the combination of which -# describes the condition under which the pattern is matched: -# -# (insn & fixedmask) == fixedbits -# -# Each pattern may have "fields", which are extracted from the insn and -# passed along to the translator. Examples of such are registers, -# immediates, and sub-opcodes. -# -# In support of patterns, one may declare fields, argument sets, and -# formats, each of which may be re-used to simplify further definitions. -# -# *** Field syntax: -# -# field_def := '%' identifier ( unnamed_field )+ ( !function=identifier )? -# unnamed_field := number ':' ( 's' ) number -# -# For unnamed_field, the first number is the least-significant bit position of -# the field and the second number is the length of the field. If the 's' is -# present, the field is considered signed. If multiple unnamed_fields are -# present, they are concatenated. In this way one can define disjoint fields. -# -# If !function is specified, the concatenated result is passed through the -# named function, taking and returning an integral value. -# -# FIXME: the fields of the structure into which this result will be stored -# is restricted to "int". Which means that we cannot expand 64-bit items. -# -# Field examples: -# -# %disp 0:s16 -- sextract(i, 0, 16) -# %imm9 16:6 10:3 -- extract(i, 16, 6) << 3 | extract(i, 10, 3) -# %disp12 0:s1 1:1 2:10 -- sextract(i, 0, 1) << 11 -# | extract(i, 1, 1) << 10 -# | extract(i, 2, 10) -# %shimm8 5:s8 13:1 !function=expand_shimm8 -# -- expand_shimm8(sextract(i, 5, 8) << 1 -# | extract(i, 13, 1)) -# -# *** Argument set syntax: -# -# args_def := '&' identifier ( args_elt )+ ( !extern )? -# args_elt := identifier -# -# Each args_elt defines an argument within the argument set. -# Each argument set will be rendered as a C structure "arg_$name" -# with each of the fields being one of the member arguments. -# -# If !extern is specified, the backing structure is assumed to -# have been already declared, typically via a second decoder. -# -# Argument set examples: -# -# ®3 ra rb rc -# &loadstore reg base offset -# -# *** Format syntax: -# -# fmt_def := '@' identifier ( fmt_elt )+ -# fmt_elt := fixedbit_elt | field_elt | field_ref | args_ref -# fixedbit_elt := [01.-]+ -# field_elt := identifier ':' 's'? number -# field_ref := '%' identifier | identifier '=' '%' identifier -# args_ref := '&' identifier -# -# Defining a format is a handy way to avoid replicating groups of fields -# across many instruction patterns. -# -# A fixedbit_elt describes a contiguous sequence of bits that must -# be 1, 0, [.-] for don't care. The difference between '.' and '-' -# is that '.' means that the bit will be covered with a field or a -# final [01] from the pattern, and '-' means that the bit is really -# ignored by the cpu and will not be specified. -# -# A field_elt describes a simple field only given a width; the position of -# the field is implied by its position with respect to other fixedbit_elt -# and field_elt. -# -# If any fixedbit_elt or field_elt appear then all bits must be defined. -# Padding with a fixedbit_elt of all '.' is an easy way to accomplish that. -# -# A field_ref incorporates a field by reference. This is the only way to -# add a complex field to a format. A field may be renamed in the process -# via assignment to another identifier. This is intended to allow the -# same argument set be used with disjoint named fields. -# -# A single args_ref may specify an argument set to use for the format. -# The set of fields in the format must be a subset of the arguments in -# the argument set. If an argument set is not specified, one will be -# inferred from the set of fields. -# -# It is recommended, but not required, that all field_ref and args_ref -# appear at the end of the line, not interleaving with fixedbit_elf or -# field_elt. -# -# Format examples: -# -# @opr ...... ra:5 rb:5 ... 0 ....... rc:5 -# @opi ...... ra:5 lit:8 1 ....... rc:5 -# -# *** Pattern syntax: -# -# pat_def := identifier ( pat_elt )+ -# pat_elt := fixedbit_elt | field_elt | field_ref -# | args_ref | fmt_ref | const_elt -# fmt_ref := '@' identifier -# const_elt := identifier '=' number -# -# The fixedbit_elt and field_elt specifiers are unchanged from formats. -# A pattern that does not specify a named format will have one inferred -# from a referenced argument set (if present) and the set of fields. -# -# A const_elt allows a argument to be set to a constant value. This may -# come in handy when fields overlap between patterns and one has to -# include the values in the fixedbit_elt instead. -# -# The decoder will call a translator function for each pattern matched. -# -# Pattern examples: -# -# addl_r 010000 ..... ..... .... 0000000 ..... @opr -# addl_i 010000 ..... ..... .... 0000000 ..... @opi -# -# which will, in part, invoke -# -# trans_addl_r(ctx, &arg_opr, insn) -# and -# trans_addl_i(ctx, &arg_opi, insn) +# See the syntax and semantics in docs/devel/decodetree.rst. # import os