From patchwork Thu Mar 7 18:56:12 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Richard Henderson X-Patchwork-Id: 159919 Delivered-To: patch@linaro.org Received: by 2002:a02:5cc1:0:0:0:0:0 with SMTP id w62csp7812104jad; Thu, 7 Mar 2019 11:26:55 -0800 (PST) X-Google-Smtp-Source: APXvYqwOutpOtVPkLulxpoCJOsmbfn01zU1oP6tN7uZgjv/mkvbPUAS4VJWt2YEFhdM16xOV3UKK X-Received: by 2002:a25:2c58:: with SMTP id s85mr13407096ybs.4.1551986815530; Thu, 07 Mar 2019 11:26:55 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1551986815; cv=none; d=google.com; s=arc-20160816; b=b/u0nXrAUQTZppcHTYXUzmSGzNtHYSAQUF/cm75hUxEPA7WJsf/Klb/PfYEdv1V1j9 c82SrxkjKvgygigJSibMKGe8DBsqNTVzHOD7Jg3a3TpzeWB1z1xAlgcd7892pDOFKPfv QBqn2cqfoU0RV4RFKx6LmqMSLeZtUZR28wboSNGavS4YajEo24KVhGeWi6gakdQv7fxM N4Fge/Zi0EiGV0BMYV8wXgxSbgdFEaprnMoEGk2hVyDolUL4Jv4UvYeSa4BtJJD3cCWx D8iRSDu9UZMFFkYWKgtK0UKoPUp5ZPQwtcqyqqC3xZ3iTn3FptTkWrRS3lSkqxnOiAJi HD7w== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to: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=RtOaFatfBg7bCw1Qa6jeylA0+YO8VNlxQZzt+PR1e9A=; b=nmq2aFHofjJ5kR1L0bmWhO1b/xI5o7dLF1Y+k6bR8z+3q6pUTwDMge8JczMVuCrilC rl/NLeICYAzr3RUy90WTec465lh4Z6LZH+1KwQoLd7OcZD1n543c8ONGxllk2QYlJZHf H1gA/XdlUAOGNS4+m41AuFJDoADLzvqIcG/ykrGKrySJ9wF0Zfzx6XkgSS8xYkmu+eka e/FthZD5svfwzvLbaonHUsRtrQCMXAw0zW0ZO+Xa/CJSwkc7sVZ6vjUL6ljockoJJFjy j5ereTperhKGI5W6GqpMP8Fhx/ShkJU81qT7VsExOhBjTC+KlHzE/QQ7Vwt9KIASMISp PrCg== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=SDjD5jAm; 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 g6si3548166ywc.383.2019.03.07.11.26.55 for (version=TLS1 cipher=AES128-SHA bits=128/128); Thu, 07 Mar 2019 11:26:55 -0800 (PST) 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=SDjD5jAm; 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]:58115 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h1yfO-0001h6-UG for patch@linaro.org; Thu, 07 Mar 2019 14:26:55 -0500 Received: from eggs.gnu.org ([209.51.188.92]:36611) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h1yBz-0001Ck-3O for qemu-devel@nongnu.org; Thu, 07 Mar 2019 13:56:32 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1h1yBx-0002Mi-6g for qemu-devel@nongnu.org; Thu, 07 Mar 2019 13:56:31 -0500 Received: from mail-pg1-x542.google.com ([2607:f8b0:4864:20::542]:41566) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1h1yBw-0002LG-Sz for qemu-devel@nongnu.org; Thu, 07 Mar 2019 13:56:29 -0500 Received: by mail-pg1-x542.google.com with SMTP id k11so10994184pgb.8 for ; Thu, 07 Mar 2019 10:56:28 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:subject:date:message-id:in-reply-to:references; bh=RtOaFatfBg7bCw1Qa6jeylA0+YO8VNlxQZzt+PR1e9A=; b=SDjD5jAmvLIVeTvGJTlyRJDM/uBRrhZB6Bhf35mHsKRyNQHESdnhfi1zqeOsB6rukU bCINjt6doAk6froQWaFlj5gtIUKoIxGt6mBXflf5DxlgzWgdkF4nZRg6WnHiu5tZoS+2 B2UkoPm081EzGU22fJ5ip/+KghEcDR0Hf7bY3sk0FToEbmJU+E0gEL9MyEiYgeNECZvQ 9R7+3UnhfkhP3ozbRxQX/Gt08hnjY50xKrEBhpGmvqmrdj1ovXLFDOb48kOPxC8yw0Vq icv30LeQzwZLRmCW/ZrPEW6Spi4Bh9skGAfTYft9ir0/CjFwdDwqo+3i6C84cyiBe49g p/5w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:subject:date:message-id:in-reply-to :references; bh=RtOaFatfBg7bCw1Qa6jeylA0+YO8VNlxQZzt+PR1e9A=; b=HA4zd3ncx63Wl8O6ymXr3pdzRtkg8zKozoREiuWFENwnAsF8+58Z3GayY87BlldJER 8aBCRyNy45UV2kGNrbhtPbM/KFAt1CTiFr0yEL/nNrm0kPSO04I2BCYTpoMCu78SQBYC W1qs81GhDVirOSOY/kaxUG5nlnz7z441q3RQOqjpRbuThFv7QL73e89QSeaPE0eRcxF7 m5jNvRpnrDul/7gKZCubYVT4rYUq/cPG0imc8sO5UudP4cmMOHGsWyvr/+BYSoN0Dnwr SkJhzCu90ne95v7ZhFUm938pwrPisPkSmYuaTtMtKrHkHfjQWtOGVR61XkGlGnfflCYp 6ABA== X-Gm-Message-State: APjAAAV6mv21j/FGABabpYYKDcqz/qcGhjPuAJzU4MPbaoOXrM+Tp8kz sb6NrsIuxrWLx6b1iQMiOm6AecD1qOk= X-Received: by 2002:a65:5a81:: with SMTP id c1mr12576952pgt.217.1551984987132; Thu, 07 Mar 2019 10:56:27 -0800 (PST) Received: from cloudburst.twiddle.net (97-113-188-82.tukw.qwest.net. [97.113.188.82]) by smtp.gmail.com with ESMTPSA id g12sm8801973pgr.76.2019.03.07.10.56.25 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 07 Mar 2019 10:56:26 -0800 (PST) From: Richard Henderson To: qemu-devel@nongnu.org Date: Thu, 7 Mar 2019 10:56:12 -0800 Message-Id: <20190307185622.29026-3-richard.henderson@linaro.org> X-Mailer: git-send-email 2.17.2 In-Reply-To: <20190307185622.29026-1-richard.henderson@linaro.org> References: <20190307185622.29026-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::542 Subject: [Qemu-devel] [PATCH v3 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: , 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 af1df70be1..820024a808 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 cd0fa6c9ba..6b9a6ba71c 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -18,4 +18,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