From patchwork Sat Aug 5 03:09:18 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Will Hawkins X-Patchwork-Id: 13342470 X-Patchwork-Delegate: bpf@iogearbox.net Received: from lindbergh.monkeyblade.net (lindbergh.monkeyblade.net [23.128.96.19]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id D083315A6 for ; Sat, 5 Aug 2023 03:09:52 +0000 (UTC) Received: from mail-qk1-x729.google.com (mail-qk1-x729.google.com [IPv6:2607:f8b0:4864:20::729]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 297E25259 for ; Fri, 4 Aug 2023 20:09:28 -0700 (PDT) Received: by mail-qk1-x729.google.com with SMTP id af79cd13be357-7672303c831so211717585a.2 for ; Fri, 04 Aug 2023 20:09:28 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=obs-cr.20221208.gappssmtp.com; s=20221208; t=1691204967; x=1691809767; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=Fojs37CSusgXFNPD59YqeUvU0yZC7xWXLmI6cdbNptY=; b=sV1kI8ksyHQpK3WcPSE+nvxe7gI/zDfgwmmUmn5e8JbvxhdJJ0sYwUddlhL7zX9nBr TMWbvzubRuW4oNXhazswuCjRyGZlftC+CCx4e66FfMCjYroEN6rK+A+vCqEqonj9HgFB bswjyW690vhfnLslpF8dDv7xDZh5/xfmQeFAprrvxZINmaLvazojm/Kt45kAg/Ws+nZH gFCNFNXo2mxWUCMtlsFcshjfHvH4ts+byDAfnSDWsof6YrvbaPLECIDiwM92uNwRRseC QpEgTmfOCsBBqPytSnPmcENmr/+k62vG9bZCkYYN4NwBXO+3en/7ql3UBTUIOWf2Sl0s 6ySQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1691204967; x=1691809767; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=Fojs37CSusgXFNPD59YqeUvU0yZC7xWXLmI6cdbNptY=; b=efCHOIu3PN5fIX1heM5KEWZz6hXfEFret6ZA34xOzev867eaIK24nWsfoABWSWStRl Zs/uABSUpg/FjmOlyQpr6sscq8pIkLyxttuye06LD5G4XymwLIBzzgcev1mHSS7S7iXr FcXnaLtN2tp7TwkNm7ffjoHP5uUf5E4gXwh5BjFUJfv9lU5g6YMHb6oX+6LZvJSRfUGI XhAvb7kYzwgukJMxif45S+eQrS1X9maD1Gc3lKuJHNb6WhVGO+xJGvYYXSFQeHttxeJ1 tvt7YQz3QwvBHF13YKpgeGSjglOvgXyn6qMJx68Q1aQHo6Y2ITKosJXACeXwXbQaaq5Q vifQ== X-Gm-Message-State: AOJu0YzODTUBtzuJo7poKcHw05ovFVJdACqV2XpFnsix6S409jTl+R0B C6j6IUzgiEtw7aQst5zwd/uWWbn5vhyHkhS8od0= X-Google-Smtp-Source: AGHT+IFBiNl4C+J7kd1Kc65O3k0MhQqLgt17VqLzK6MSi/9z00IjFUygbdYd/BVaVW+tmCz957UKHg== X-Received: by 2002:a05:620a:31a9:b0:76c:bd05:f81f with SMTP id bi41-20020a05620a31a900b0076cbd05f81fmr4181660qkb.63.1691204967036; Fri, 04 Aug 2023 20:09:27 -0700 (PDT) Received: from borderland.rhod.uc.edu ([129.137.96.2]) by smtp.gmail.com with ESMTPSA id k20-20020a0cf594000000b0063cbb29731dsm1124501qvm.66.2023.08.04.20.09.26 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 04 Aug 2023 20:09:26 -0700 (PDT) From: Will Hawkins To: bpf@vger.kernel.org, bpf@ietf.org Cc: Will Hawkins Subject: [PATCH v3 1/2] bpf, docs: Formalize type notation and function semantics in ISA standard Date: Fri, 4 Aug 2023 23:09:18 -0400 Message-ID: <20230805030921.52035-1-hawkinsw@obs.cr> X-Mailer: git-send-email 2.41.0 Precedence: bulk X-Mailing-List: bpf@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,RCVD_IN_DNSWL_BLOCKED,SPF_HELO_NONE,SPF_NONE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net X-Patchwork-Delegate: bpf@iogearbox.net Give a single place where the shorthand for types are defined, the semantics of helper functions are described, and certain terms can be defined. Signed-off-by: Will Hawkins --- .../bpf/standardization/instruction-set.rst | 79 +++++++++++++++++-- 1 file changed, 71 insertions(+), 8 deletions(-) Changelog: v1 -> v2: - Remove change to Sphinx version - Address David's comments - Address Dave's comments v2 -> v3: - Add information about sign extending diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst index 655494ac7af6..fe296f35e5a7 100644 --- a/Documentation/bpf/standardization/instruction-set.rst +++ b/Documentation/bpf/standardization/instruction-set.rst @@ -10,9 +10,68 @@ This document specifies version 1.0 of the eBPF instruction set. Documentation conventions ========================= -For brevity, this document uses the type notion "u64", "u32", etc. -to mean an unsigned integer whose width is the specified number of bits, -and "s32", etc. to mean a signed integer of the specified number of bits. +For brevity and consistency, this document refers to families +of types using a shorthand syntax and refers to several expository, +mnemonic functions when describing the semantics of opcodes. The range +of valid values for those types and the semantics of those functions +are defined in the following subsections. + +Types +----- +This document refers to integer types with a notation of the form `SN` +that succinctly defines whether their values are signed or unsigned +numbers and the bit widths: + +=== ======= +`S` Meaning +=== ======= +`u` unsigned +`s` signed +=== ======= + +===== ========= +`N` Bit width +===== ========= +`8` 8 bits +`16` 16 bits +`32` 32 bits +`64` 64 bits +`128` 128 bits +===== ========= + +For example, `u32` is a type whose valid values are all the 32-bit unsigned +numbers and `s16` is a types whose valid values are all the 16-bit signed +numbers. + +Functions +--------- +* `htobe16`: Takes an unsigned 16-bit number in host-endian format and + returns the equivalent number as an unsigned 16-bit number in big-endian + format. +* `htobe32`: Takes an unsigned 32-bit number in host-endian format and + returns the equivalent number as an unsigned 32-bit number in big-endian + format. +* `htobe64`: Takes an unsigned 64-bit number in host-endian format and + returns the equivalent number as an unsigned 64-bit number in big-endian + format. +* `htole16`: Takes an unsigned 16-bit number in host-endian format and + returns the equivalent number as an unsigned 16-bit number in little-endian + format. +* `htole32`: Takes an unsigned 32-bit number in host-endian format and + returns the equivalent number as an unsigned 32-bit number in little-endian + format. +* `htole64`: Takes an unsigned 64-bit number in host-endian format and + returns the equivalent number as an unsigned 64-bit number in little-endian + format. +* `bswap16`: Takes an unsigned 16-bit number in either big- or little-endian + format and returns the equivalent number with the same bit width but + opposite endianness. +* `bswap32`: Takes an unsigned 32-bit number in either big- or little-endian + format and returns the equivalent number with the same bit width but + opposite endianness. +* `bswap64`: Takes an unsigned 64-bit number in either big- or little-endian + format and returns the equivalent number with the same bit width but + opposite endianness. Registers and calling convention ================================ @@ -252,19 +311,23 @@ are supported: 16, 32 and 64. Examples: -``BPF_ALU | BPF_TO_LE | BPF_END`` with imm = 16 means:: +``BPF_ALU | BPF_TO_LE | BPF_END`` with imm = 16/32/64 means:: dst = htole16(dst) + dst = htole32(dst) + dst = htole64(dst) -``BPF_ALU | BPF_TO_BE | BPF_END`` with imm = 64 means:: +``BPF_ALU | BPF_TO_BE | BPF_END`` with imm = 16/32/64 means:: + dst = htobe16(dst) + dst = htobe32(dst) dst = htobe64(dst) ``BPF_ALU64 | BPF_TO_LE | BPF_END`` with imm = 16/32/64 means:: - dst = bswap16 dst - dst = bswap32 dst - dst = bswap64 dst + dst = bswap16(dst) + dst = bswap32(dst) + dst = bswap64(dst) Jump instructions ----------------- From patchwork Sat Aug 5 03:09:19 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Will Hawkins X-Patchwork-Id: 13342471 X-Patchwork-Delegate: bpf@iogearbox.net Received: from lindbergh.monkeyblade.net (lindbergh.monkeyblade.net [23.128.96.19]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id C3A911851 for ; Sat, 5 Aug 2023 03:09:53 +0000 (UTC) Received: from mail-qv1-xf32.google.com (mail-qv1-xf32.google.com [IPv6:2607:f8b0:4864:20::f32]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id F315E4EFF for ; Fri, 4 Aug 2023 20:09:30 -0700 (PDT) Received: by mail-qv1-xf32.google.com with SMTP id 6a1803df08f44-63d23473ed5so16198986d6.1 for ; Fri, 04 Aug 2023 20:09:30 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=obs-cr.20221208.gappssmtp.com; s=20221208; t=1691204970; x=1691809770; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=amt6f6/FgCcgvOgQNxpLD0P8oG8ReutuJ8nyhf1LrBE=; b=tXHlw2yJ+8k/V/OAWXj9OHXpcPCetNaBoqcYqfOE+b5I+3DrpWxH99dEzEF3lZ1I5P qnksgKijML7LccpwMcByUPu1KhgHlUJHDf2VbTCjOYZRAKG+yfSyNqalv/Vhsm6ABJE6 PjNBHkhTQ9dCHgynl0aBkafnBq0bnvBkGbiphVGnrzFa243UIGoCTK6vrnuyfwPkYSIs 4drIkkqyo365+kibMB1X469/CfzlCYMQYuZv1rJ9VhU6a1hbk0QmlREgvGk+P1dYFpMe 0UTUygxfJiLjgu9LgxsVYSuCqUXM6O2nW0bi6ZPop+N8MlHgOHdTYh2JjOATPMkkCA8T nwDQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1691204970; x=1691809770; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=amt6f6/FgCcgvOgQNxpLD0P8oG8ReutuJ8nyhf1LrBE=; b=cK01ucT2cp8qI0UYo1juhbpKFJapLJadD2bKIdN57C8ZdHh+c1V1sk97dZ500IbIj1 gu7xgiw2Vjn9DCl/g413LAUg3nLOZCnsfWQbB6JolDhUXx1Ad41T3Hk3cV/yygcG3qAm uZ0ifIf5zbQghLiyrgxffE9BrY/AaX8sHQGzGi3NKayRhx/DN6+YpevCRCyean8/MUA9 0z9mi9bog00wHTi2IpxynCTFNYK9iTwinjaYeGuwJBEDiiW+c6AlrAZZ+vXn4p6H4fT5 QtS/3XoT4YCb52mNMXLGhQYG//fwDONfWP/g7gWhstO5JNDkmasKKCG8ZzhnCvmVJB8c M9zw== X-Gm-Message-State: AOJu0YwwGQ6++/E0gd+xt8M/r/g+C2YZgDXf+7jp1/KoEgNFvIqrgQIw SdQ1jvfAf+PSP/yPf/fbar5nPMpxq+ikdc/3keI= X-Google-Smtp-Source: AGHT+IE1pg65MnSF3gWfkSMHnSrm5658vv5iU6p7qtqY4H7dqd90NDxjyNxtzlak+tyFqnZSS8HZGQ== X-Received: by 2002:ad4:4506:0:b0:62d:fe06:3e17 with SMTP id k6-20020ad44506000000b0062dfe063e17mr3611044qvu.22.1691204969880; Fri, 04 Aug 2023 20:09:29 -0700 (PDT) Received: from borderland.rhod.uc.edu ([129.137.96.2]) by smtp.gmail.com with ESMTPSA id k20-20020a0cf594000000b0063cbb29731dsm1124501qvm.66.2023.08.04.20.09.29 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 04 Aug 2023 20:09:29 -0700 (PDT) From: Will Hawkins To: bpf@vger.kernel.org, bpf@ietf.org Cc: Will Hawkins Subject: [PATCH v3 2/2] bpf, docs: Fix small typo and define semantics of sign extension Date: Fri, 4 Aug 2023 23:09:19 -0400 Message-ID: <20230805030921.52035-2-hawkinsw@obs.cr> X-Mailer: git-send-email 2.41.0 In-Reply-To: <20230805030921.52035-1-hawkinsw@obs.cr> References: <20230805030921.52035-1-hawkinsw@obs.cr> Precedence: bulk X-Mailing-List: bpf@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,RCVD_IN_DNSWL_BLOCKED,SPF_HELO_NONE,SPF_NONE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net X-Patchwork-Delegate: bpf@iogearbox.net Signed-off-by: Will Hawkins --- .../bpf/standardization/instruction-set.rst | 31 ++++++++++++++++--- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst index fe296f35e5a7..6f3b34ef7b7c 100644 --- a/Documentation/bpf/standardization/instruction-set.rst +++ b/Documentation/bpf/standardization/instruction-set.rst @@ -73,6 +73,27 @@ Functions format and returns the equivalent number with the same bit width but opposite endianness. + +Definitions +----------- + +.. glossary:: + + Sign Extend + To `sign extend an` ``X`` `-bit number, A, to a` ``Y`` `-bit number, B ,` means to + + #. Copy all ``X`` bits from `A` to the lower ``X`` bits of `B`. + #. Set the value of the remaining ``Y`` - ``X`` bits of `B` to the value of + the most-significant bit of `A`. + +.. admonition:: Example + + Sign extend an 8-bit number ``A`` to a 16-bit number ``B`` on a big-endian platform: + :: + + A: 10000110 + B: 11111111 10000110 + Registers and calling convention ================================ @@ -263,17 +284,17 @@ where '(u32)' indicates that the upper 32 bits are zeroed. Note that most instructions have instruction offset of 0. Only three instructions (``BPF_SDIV``, ``BPF_SMOD``, ``BPF_MOVSX``) have a non-zero offset. -The devision and modulo operations support both unsigned and signed flavors. +The division and modulo operations support both unsigned and signed flavors. For unsigned operations (``BPF_DIV`` and ``BPF_MOD``), for ``BPF_ALU``, 'imm' is interpreted as a 32-bit unsigned value. For ``BPF_ALU64``, -'imm' is first sign extended from 32 to 64 bits, and then interpreted as -a 64-bit unsigned value. +'imm' is first :term:`sign extended` from 32 to 64 bits, and then +interpreted as a 64-bit unsigned value. For signed operations (``BPF_SDIV`` and ``BPF_SMOD``), for ``BPF_ALU``, 'imm' is interpreted as a 32-bit signed value. For ``BPF_ALU64``, 'imm' -is first sign extended from 32 to 64 bits, and then interpreted as a -64-bit signed value. +is first :term:`sign extended` from 32 to 64 bits, and then +interpreted as a 64-bit signed value. The ``BPF_MOVSX`` instruction does a move operation with sign extension. ``BPF_ALU | BPF_MOVSX`` sign extends 8-bit and 16-bit operands into 32