From patchwork Tue Sep 27 18:59:44 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Thaler X-Patchwork-Id: 12991114 X-Patchwork-Delegate: bpf@iogearbox.net Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 04458C6FA83 for ; Tue, 27 Sep 2022 19:00:22 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231222AbiI0TAU (ORCPT ); Tue, 27 Sep 2022 15:00:20 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:52896 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229779AbiI0TAS (ORCPT ); Tue, 27 Sep 2022 15:00:18 -0400 Received: from mail-pj1-x1036.google.com (mail-pj1-x1036.google.com [IPv6:2607:f8b0:4864:20::1036]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 3D5691591C7 for ; Tue, 27 Sep 2022 12:00:17 -0700 (PDT) Received: by mail-pj1-x1036.google.com with SMTP id l9-20020a17090a4d4900b00205e295400eso1583293pjh.4 for ; Tue, 27 Sep 2022 12:00:17 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlemail.com; s=20210112; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date; bh=sH8TUxBxA7sfvMxNoaNLX5BJpgCrsSg83OKotwSQSZk=; b=eiAjzKDxK1gK8dWo2bFxMLFDTCURD7t8kTfaKH8kFTNjJ4mOgdfrqbBWoeS25WVlvg dRKH6Hf8HKDr4Uii1Npi2AP+ZeyGGIgGm6x1ADvsGYwY+zUOAWTu2f+SG7w2Gwf2mYBX koblvjTdTp/77Bb8HY1MUX0lKqe42DnH8C8Um3LFff9CPA8++T57R0Wmr8Cmgn9/TDEk XNaRX4itoccTA/b30wewTJCczrkP1xITv+7xh/c2yeC2W8vjYXzSbrqw+mDeEN3/Yem9 hRLo1peaAiVTmJrFAmMFgcLzqbb73CGontwTo27mFunWCHyEQOLcbx0EKgL7TyNRB1zd AWQg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date; bh=sH8TUxBxA7sfvMxNoaNLX5BJpgCrsSg83OKotwSQSZk=; b=B4XuZpqFvUaJVCoAlh3ICU95PRkKvROg+eviqOK2LeGYGNXxwGkM7gONxS59vwQZYQ h2mgbyFQsPCr1eT+DheIT1rk7r8Q7ZV/X7zBqEC+NEamUPvENirpWnGz74HxRMm/aFml 7uDxt4iKl+Pc4uQcUM/l3vUAm1EugoDd6I3ts4K8zgObLiHfV1LaFgdPcSixqhQrCFBV adGz8T4jqdvBrhWaikqCzj0+lzeSVxtNYTJO7wresTkYOQKm7E2LUxzEjlwzgCecPze0 45BiwkIJbK6Sak268x/Nj91wv2+sMnYEgBsmijezFivlJ55eZf8siWsGENl6uNzkuf32 LzGA== X-Gm-Message-State: ACrzQf2HkOxCBewSxKBQEa/Fcb9RaUPGXDIuvj2xiT2NWZJtIzEl6pC0 ZFM8UYsS5aygMfZdB9xqVs3OjqImDMA= X-Google-Smtp-Source: AMsMyM7H2GUG4Ri4tY5LsVZdqkAGqQPssqHSprsw04GZhiN3xO+2Rh7BBOErrvv1Awlj/7HLnGrq6A== X-Received: by 2002:a17:902:cf4c:b0:179:f440:3284 with SMTP id e12-20020a170902cf4c00b00179f4403284mr2883935plg.24.1664305216242; Tue, 27 Sep 2022 12:00:16 -0700 (PDT) Received: from mariner-vm.. ([131.107.1.181]) by smtp.gmail.com with ESMTPSA id mi9-20020a17090b4b4900b001f8aee0d826sm8737557pjb.53.2022.09.27.12.00.15 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 27 Sep 2022 12:00:15 -0700 (PDT) From: dthaler1968@googlemail.com To: bpf@vger.kernel.org Cc: Dave Thaler Subject: [PATCH 01/15] ebpf-docs: Move legacy packet instructions to a separate file Date: Tue, 27 Sep 2022 18:59:44 +0000 Message-Id: <20220927185958.14995-1-dthaler1968@googlemail.com> X-Mailer: git-send-email 2.33.4 MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Dave Thaler Signed-off-by: Dave Thaler --- Documentation/bpf/instruction-set.rst | 38 ++-------------- Documentation/bpf/linux-notes.rst | 65 +++++++++++++++++++++++++++ 2 files changed, 68 insertions(+), 35 deletions(-) create mode 100644 Documentation/bpf/linux-notes.rst diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst index 1b0e6711d..352f25a1e 100644 --- a/Documentation/bpf/instruction-set.rst +++ b/Documentation/bpf/instruction-set.rst @@ -282,8 +282,6 @@ arithmetic operations in the imm field to encode the atomic operation: *(u64 *)(dst_reg + off16) += src_reg -``BPF_XADD`` is a deprecated name for ``BPF_ATOMIC | BPF_ADD``. - In addition to the simple atomic operations, there also is a modifier and two complex atomic operations: @@ -331,36 +329,6 @@ There is currently only one such instruction. Legacy BPF Packet access instructions ------------------------------------- -eBPF has special instructions for access to packet data that have been -carried over from classic BPF to retain the performance of legacy socket -filters running in the eBPF interpreter. - -The instructions come in two forms: ``BPF_ABS | | BPF_LD`` and -``BPF_IND | | BPF_LD``. - -These instructions are used to access packet data and can only be used when -the program context is a pointer to networking packet. ``BPF_ABS`` -accesses packet data at an absolute offset specified by the immediate data -and ``BPF_IND`` access packet data at an offset that includes the value of -a register in addition to the immediate data. - -These instructions have seven implicit operands: - - * Register R6 is an implicit input that must contain pointer to a - struct sk_buff. - * Register R0 is an implicit output which contains the data fetched from - the packet. - * Registers R1-R5 are scratch registers that are clobbered after a call to - ``BPF_ABS | BPF_LD`` or ``BPF_IND | BPF_LD`` instructions. - -These instructions have an implicit program exit condition as well. When an -eBPF program is trying to access the data beyond the packet boundary, the -program execution will be aborted. - -``BPF_ABS | BPF_W | BPF_LD`` means:: - - R0 = ntohl(*(u32 *) (((struct sk_buff *) R6)->data + imm32)) - -``BPF_IND | BPF_W | BPF_LD`` means:: - - R0 = ntohl(*(u32 *) (((struct sk_buff *) R6)->data + src_reg + imm32)) +eBPF previously introduced special instructions for access to packet data that were +carried over from classic BPF. However, these instructions are +deprecated and should no longer be used. diff --git a/Documentation/bpf/linux-notes.rst b/Documentation/bpf/linux-notes.rst new file mode 100644 index 000000000..93c01386d --- /dev/null +++ b/Documentation/bpf/linux-notes.rst @@ -0,0 +1,65 @@ +.. contents:: +.. sectnum:: + +========================== +Linux implementation notes +========================== + +This document provides more details specific to the Linux kernel implementation of the eBPF instruction set. + +Legacy BPF Packet access instructions +===================================== + +As mentioned in the `ISA standard documentation `_, +Linux has special eBPF instructions for access to packet data that have been +carried over from classic BPF to retain the performance of legacy socket +filters running in the eBPF interpreter. + +The instructions come in two forms: ``BPF_ABS | | BPF_LD`` and +``BPF_IND | | BPF_LD``. + +These instructions are used to access packet data and can only be used when +the program context is a pointer to a networking packet. ``BPF_ABS`` +accesses packet data at an absolute offset specified by the immediate data +and ``BPF_IND`` access packet data at an offset that includes the value of +a register in addition to the immediate data. + +These instructions have seven implicit operands: + +* Register R6 is an implicit input that must contain a pointer to a + struct sk_buff. +* Register R0 is an implicit output which contains the data fetched from + the packet. +* Registers R1-R5 are scratch registers that are clobbered by the + instruction. + +These instructions have an implicit program exit condition as well. If an +eBPF program attempts access data beyond the packet boundary, the +program execution will be aborted. + +``BPF_ABS | BPF_W | BPF_LD`` (0x20) means:: + + R0 = ntohl(*(u32 *) ((struct sk_buff *) R6->data + imm)) + +where ``ntohl()`` converts a 32-bit value from network byte order to host byte order. + +``BPF_IND | BPF_W | BPF_LD`` (0x40) means:: + + R0 = ntohl(*(u32 *) ((struct sk_buff *) R6->data + src + imm)) + +Appendix +======== + +For reference, the following table lists legacy Linux-specific opcodes in order by value. + +====== ==== =================================================== ============= +opcode imm description reference +====== ==== =================================================== ============= +0x20 any dst = ntohl(\*(uint32_t \*)(R6->data + imm)) `Legacy BPF Packet access instructions`_ +0x28 any dst = ntohs(\*(uint16_t \*)(R6->data + imm)) `Legacy BPF Packet access instructions`_ +0x30 any dst = (\*(uint8_t \*)(R6->data + imm)) `Legacy BPF Packet access instructions`_ +0x38 any dst = ntohll(\*(uint64_t \*)(R6->data + imm)) `Legacy BPF Packet access instructions`_ +0x40 any dst = ntohl(\*(uint32_t \*)(R6->data + src + imm)) `Legacy BPF Packet access instructions`_ +0x48 any dst = ntohs(\*(uint16_t \*)(R6->data + src + imm)) `Legacy BPF Packet access instructions`_ +0x50 any dst = \*(uint8_t \*)(R6->data + src + imm)) `Legacy BPF Packet access instructions`_ +0x58 any dst = ntohll(\*(uint64_t \*)(R6->data + src + imm)) `Legacy BPF Packet access instructions`_ From patchwork Tue Sep 27 18:59:45 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Thaler X-Patchwork-Id: 12991113 X-Patchwork-Delegate: bpf@iogearbox.net Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id E2EB5C07E9D for ; Tue, 27 Sep 2022 19:00:20 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230081AbiI0TAT (ORCPT ); Tue, 27 Sep 2022 15:00:19 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:52928 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229907AbiI0TAS (ORCPT ); Tue, 27 Sep 2022 15:00:18 -0400 Received: from mail-pl1-x636.google.com (mail-pl1-x636.google.com [IPv6:2607:f8b0:4864:20::636]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 4D9CE15E4F0 for ; Tue, 27 Sep 2022 12:00:18 -0700 (PDT) Received: by mail-pl1-x636.google.com with SMTP id c24so9918921plo.3 for ; Tue, 27 Sep 2022 12:00:18 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlemail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date; bh=2eM0bW+kJIRaRGmJEv4QVeyfZ5y4avXbADaNHf73UyA=; b=lGismXlQnh1LFstZ4W8ifUrLWtLj6Ec1pjc1w8xbdS0FnTpbCFlTCM/DD9sIy1jAfa sUD3RZ3MdyPCKhUto2NvLsFb03yUvxlPIrYsEpOdX5f4t/Nd1SOhd4iEum/qdC7vf7in yLsBSbiYrVR8RyKbFN1fcJGz24JWOHq4xrkYu448IwJDSS1qLnapRd3GEZMd7bc5kxUI zrBYWwkgcf9vj9ynZ6P+ecUBPVobwnf5Y8nOc/daCL5anAbNYAXR8IXaSfWK8sTjPoCl WRzAySbzbZ1FcdRSV0KJhFuDwVc1hcgZHc0gUy5An6nM719d1m7Fk740JjhUYOaPXuae vtHg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; 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; bh=2eM0bW+kJIRaRGmJEv4QVeyfZ5y4avXbADaNHf73UyA=; b=ENRwhAupjG2TftHYhmDoTf1Iy1048aNyEY/9KhU6rynsFk7toyfn44qZZCNKcjGTEH bBHIZAsNfB3HuIiUh9ZSrq+CT9bOfnTKRyCVmqswvHrpCmbU/Hd9oT4s75fL+buvydI2 P/jRZ30kZJsBVnIdvPrysbsPFfwu9PWPZC6/9CAVvX32+ro/zdfrAGqsje0iCZcugGsN tG4husNgymk7Fio4DcEnpEqT74kE6SgprWOlna97KDM5q7sbzw9tq+DoIa8D2eyEQhYF TqY2yCMmDlalfslha6yJ+7PdirS10/tS1rpTW43xAdZuBghiCUAPKMIEXsunHI1e/x6T 0wFA== X-Gm-Message-State: ACrzQf2pmQxOASSZCkucwWUtp0XiDuSe4UlKs/nouBTjlv8dCfZDN0d7 A+pDZQlcC3hAVqlap5muHxi0yA6Y2iI= X-Google-Smtp-Source: AMsMyM4bxUHQGaA/zWB/KVOssHDvJoKHmLMyfnaq2BB/eINJw8Svd1i4wXhj2ajh92NJz0Wt7qwGeg== X-Received: by 2002:a17:902:c702:b0:178:9fb3:419a with SMTP id p2-20020a170902c70200b001789fb3419amr29115280plp.35.1664305217182; Tue, 27 Sep 2022 12:00:17 -0700 (PDT) Received: from mariner-vm.. ([131.107.1.181]) by smtp.gmail.com with ESMTPSA id mi9-20020a17090b4b4900b001f8aee0d826sm8737557pjb.53.2022.09.27.12.00.16 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 27 Sep 2022 12:00:16 -0700 (PDT) From: dthaler1968@googlemail.com To: bpf@vger.kernel.org Cc: Dave Thaler Subject: [PATCH 02/15] ebpf-docs: Linux byteswap note Date: Tue, 27 Sep 2022 18:59:45 +0000 Message-Id: <20220927185958.14995-2-dthaler1968@googlemail.com> X-Mailer: git-send-email 2.33.4 In-Reply-To: <20220927185958.14995-1-dthaler1968@googlemail.com> References: <20220927185958.14995-1-dthaler1968@googlemail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Dave Thaler Signed-off-by: Dave Thaler --- Documentation/bpf/instruction-set.rst | 4 ---- Documentation/bpf/linux-notes.rst | 5 +++++ 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst index 352f25a1e..1735b91ec 100644 --- a/Documentation/bpf/instruction-set.rst +++ b/Documentation/bpf/instruction-set.rst @@ -156,10 +156,6 @@ Examples: dst_reg = htobe64(dst_reg) -``BPF_FROM_LE`` and ``BPF_FROM_BE`` exist as aliases for ``BPF_TO_LE`` and -``BPF_TO_BE`` respectively. - - Jump instructions ----------------- diff --git a/Documentation/bpf/linux-notes.rst b/Documentation/bpf/linux-notes.rst index 93c01386d..1c31379b4 100644 --- a/Documentation/bpf/linux-notes.rst +++ b/Documentation/bpf/linux-notes.rst @@ -7,6 +7,11 @@ Linux implementation notes This document provides more details specific to the Linux kernel implementation of the eBPF instruction set. +Byte swap instructions +====================== + +``BPF_FROM_LE`` and ``BPF_FROM_BE`` exist as aliases for ``BPF_TO_LE`` and ``BPF_TO_BE`` respectively. + Legacy BPF Packet access instructions ===================================== From patchwork Tue Sep 27 18:59:46 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Thaler X-Patchwork-Id: 12991115 X-Patchwork-Delegate: bpf@iogearbox.net Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 97401C07E9D for ; Tue, 27 Sep 2022 19:00:23 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231148AbiI0TAV (ORCPT ); Tue, 27 Sep 2022 15:00:21 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:53002 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231174AbiI0TAU (ORCPT ); Tue, 27 Sep 2022 15:00:20 -0400 Received: from mail-pf1-x432.google.com (mail-pf1-x432.google.com [IPv6:2607:f8b0:4864:20::432]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 3645515EFB5 for ; Tue, 27 Sep 2022 12:00:19 -0700 (PDT) Received: by mail-pf1-x432.google.com with SMTP id d10so9370065pfh.6 for ; Tue, 27 Sep 2022 12:00:19 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlemail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date; bh=K6vZLe238Y7tE+rPfNhu7j1O8qFZl2EZ8BObf2TsFU4=; b=krw7jRcUX4Bzk62xSG7mUNgEQFKS7NHF9JAwOo2hKsAY7JGKd4jwggrVXf3ioLvS3O 7qjREpZq4+CZUzRCLpVnU/eq0QWEcLX13EITdtsMvbcxHNQtN0AaDUTN5glC5ACwoKL8 t/kAiqYE0LI37KwfKwvd1fseKkRL4nDFjpOjFoOmLXsgUlhLxcXgwKN4WnYU2xeuKWFN d0D86iPujDGUVdwiuJZAaKkZTYPm85tlNzrSCv17/JduLzhtS3cgLO1WfY7P82vnAUj4 DxYyShKzMkAYORCsoZujEWzZXfBPSSvN/FqORa1Ogp43IAio3gsbq+eg7SNaUdrnS4Uo nBPg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; 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; bh=K6vZLe238Y7tE+rPfNhu7j1O8qFZl2EZ8BObf2TsFU4=; b=uzVZdIK16BZWrcKlPqRVnSMmi6HsKtDqj8rtoTa6icPr7uXIwWMb5AMaImN7wb+ifM Eg1g3gV8hpk6UJYgL7P1rOQcsF55va5UZ90ZKJRkr35YTeknTl/q6pJxof6pEvsAENcM zuc+H7kUuKx5WIEciWKUwNcrWmgT6mhqU60PDBk8gcJNzXYDCzOWoNePkRtc79rglQzA XHUTa7+rJFXCXqhylJcaQjQA6Kc01+36bv6iXea5A5YfaW4wQLsjlNeeQ7U6T5SpOyk3 9wMm4Yp5PGe6RActPMTXM6ar1arR1GR9CIX0IIpCbIgp+xkHW8LUZYHiVYu8kA5ObIjY CnsQ== X-Gm-Message-State: ACrzQf1nDC5NWU5AFmrRV3Lipw92zUgXzxIuE5VGV9quSfLz18+AP+8D Tf1YeVeGogqP071TS7CP2WCbWLYquns= X-Google-Smtp-Source: AMsMyM4G57H9loIYcF/uhH7YoEdRMl/MfT8dHUEQecf4V2Yml5bwye020CaY3Mr/y74TGYNjEcMPcQ== X-Received: by 2002:a63:4243:0:b0:439:2031:be87 with SMTP id p64-20020a634243000000b004392031be87mr26089162pga.592.1664305218290; Tue, 27 Sep 2022 12:00:18 -0700 (PDT) Received: from mariner-vm.. ([131.107.1.181]) by smtp.gmail.com with ESMTPSA id mi9-20020a17090b4b4900b001f8aee0d826sm8737557pjb.53.2022.09.27.12.00.17 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 27 Sep 2022 12:00:17 -0700 (PDT) From: dthaler1968@googlemail.com To: bpf@vger.kernel.org Cc: Dave Thaler Subject: [PATCH 03/15] ebpf-docs: Move Clang notes to a separate file Date: Tue, 27 Sep 2022 18:59:46 +0000 Message-Id: <20220927185958.14995-3-dthaler1968@googlemail.com> X-Mailer: git-send-email 2.33.4 In-Reply-To: <20220927185958.14995-1-dthaler1968@googlemail.com> References: <20220927185958.14995-1-dthaler1968@googlemail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Dave Thaler Signed-off-by: Dave Thaler --- Documentation/bpf/clang-notes.rst | 24 ++++++++++++++++++++++++ Documentation/bpf/instruction-set.rst | 6 ------ 2 files changed, 24 insertions(+), 6 deletions(-) create mode 100644 Documentation/bpf/clang-notes.rst diff --git a/Documentation/bpf/clang-notes.rst b/Documentation/bpf/clang-notes.rst new file mode 100644 index 000000000..b15179cb5 --- /dev/null +++ b/Documentation/bpf/clang-notes.rst @@ -0,0 +1,24 @@ +.. contents:: +.. sectnum:: + +========================== +Clang implementation notes +========================== + +This document provides more details specific to the Clang/LLVM implementation of the eBPF instruction set. + +Versions +======== + +Clang defined "CPU" versions, where a CPU version of 3 corresponds to the current eBPF ISA. + +Clang can select the eBPF ISA version using ``-mcpu=v3`` for example to select version 3. + +Atomic operations +================= + +Clang can generate atomic instructions by default when ``-mcpu=v3`` is +enabled. If a lower version for ``-mcpu`` is set, the only atomic instruction +Clang can generate is ``BPF_ADD`` *without* ``BPF_FETCH``. If you need to enable +the atomics features, while keeping a lower ``-mcpu`` version, you can use +``-Xclang -target-feature -Xclang +alu32``. diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst index 1735b91ec..541483118 100644 --- a/Documentation/bpf/instruction-set.rst +++ b/Documentation/bpf/instruction-set.rst @@ -303,12 +303,6 @@ The ``BPF_CMPXCHG`` operation atomically compares the value addressed by value that was at ``dst_reg + off`` before the operation is zero-extended and loaded back to ``R0``. -Clang can generate atomic instructions by default when ``-mcpu=v3`` is -enabled. If a lower version for ``-mcpu`` is set, the only atomic instruction -Clang can generate is ``BPF_ADD`` *without* ``BPF_FETCH``. If you need to enable -the atomics features, while keeping a lower ``-mcpu`` version, you can use -``-Xclang -target-feature -Xclang +alu32``. - 64-bit immediate instructions ----------------------------- From patchwork Tue Sep 27 18:59:47 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Thaler X-Patchwork-Id: 12991116 X-Patchwork-Delegate: bpf@iogearbox.net Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 764B5C6FA82 for ; Tue, 27 Sep 2022 19:00:24 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229950AbiI0TAW (ORCPT ); Tue, 27 Sep 2022 15:00:22 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:53050 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229779AbiI0TAV (ORCPT ); Tue, 27 Sep 2022 15:00:21 -0400 Received: from mail-pf1-x433.google.com (mail-pf1-x433.google.com [IPv6:2607:f8b0:4864:20::433]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 2475D1591C7 for ; Tue, 27 Sep 2022 12:00:20 -0700 (PDT) Received: by mail-pf1-x433.google.com with SMTP id b75so10484398pfb.7 for ; Tue, 27 Sep 2022 12:00:20 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlemail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date; bh=GV1tDUBghRbu5uEg8UnHOOqFcAerIG+mQxzutQ0z+Os=; b=ddRbAX1QtEYosE15vmR/VRMUir+NVNCP9WUEwtQmPzcvJiLt1juNYY5m0gREfU57sY i8IERXm2weMIJ+M/BKFYGLcp2Xx9II1ny1wuxKBhdaUEhnI652zZ+6H1Q24Jopj23lKw KXExY6oYrVnkiZh8abkr9z5wblR3dhfjH2ZpKrGjZenuOqA6BtsEY2bVwpkgOKc4j77p Gifearp+J8S4vI3ScOzuc3ntWWYoWF6z4aXRstfzHA2UV/yJx123Y2L4haRmTatD3cZ5 0MZED7xoWgOw2okmEZGwCnbW2ih1hmBpiVemXHI50vM8z0JDa0iwY80xjt060PO3Q0Ou H5TA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; 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; bh=GV1tDUBghRbu5uEg8UnHOOqFcAerIG+mQxzutQ0z+Os=; b=GFznEfiam1jyb1nSN3V4TeJ+MOrIvZcko1b+CrnMKM1UGS6Hbz5drpqOvTIzfgoh66 3UEroyS6HMwFJ79gX0/WPWMSpBWx7LFYvCygxiMo+9FexO4Y7WEqJm+yuegAq+Oz++bM XHHmpUA3S7zw1EtuE45d/+kKZYOaglF4W3EG7VeCfYzsgMvAxku52mpxS8xoNBJX7kRD ik3rKHFGvLVWKG13DoKK5P/nxY2+knJU7xsPyB/g1HPcLUGQudkWueImRlVMdvVrtGVG F7ELm1sx5kFa7w24PX6inJ1jio8KG+e++u+lgoRw0b+wMawpcDFIcFVhGUxOMjqUYRtS wJhQ== X-Gm-Message-State: ACrzQf18R/vYiunYoYlL6ozbxbVVQxz2uKA+E0JJrJfNdLdX7Vno472y 5uhbw3YYak207dj+d55NvlfZ4dEaoT8= X-Google-Smtp-Source: AMsMyM67dGmsCAxQ7Hq5wYgjAUeh37/mHopfzjcOX9MG/TKJyhRHFAQKZIK4XV95sRUcsudNZ6azbg== X-Received: by 2002:a63:1d22:0:b0:439:3e7c:8af7 with SMTP id d34-20020a631d22000000b004393e7c8af7mr26076920pgd.78.1664305219167; Tue, 27 Sep 2022 12:00:19 -0700 (PDT) Received: from mariner-vm.. ([131.107.1.181]) by smtp.gmail.com with ESMTPSA id mi9-20020a17090b4b4900b001f8aee0d826sm8737557pjb.53.2022.09.27.12.00.18 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 27 Sep 2022 12:00:18 -0700 (PDT) From: dthaler1968@googlemail.com To: bpf@vger.kernel.org Cc: Dave Thaler Subject: [PATCH 04/15] ebpf-docs: Add Clang note about BPF_ALU Date: Tue, 27 Sep 2022 18:59:47 +0000 Message-Id: <20220927185958.14995-4-dthaler1968@googlemail.com> X-Mailer: git-send-email 2.33.4 In-Reply-To: <20220927185958.14995-1-dthaler1968@googlemail.com> References: <20220927185958.14995-1-dthaler1968@googlemail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Dave Thaler Signed-off-by: Dave Thaler --- Documentation/bpf/clang-notes.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Documentation/bpf/clang-notes.rst b/Documentation/bpf/clang-notes.rst index b15179cb5..528feddf2 100644 --- a/Documentation/bpf/clang-notes.rst +++ b/Documentation/bpf/clang-notes.rst @@ -14,6 +14,12 @@ Clang defined "CPU" versions, where a CPU version of 3 corresponds to the curren Clang can select the eBPF ISA version using ``-mcpu=v3`` for example to select version 3. +Arithmetic instructions +======================= + +For CPU versions prior to 3, Clang v7.0 and later can enable ``BPF_ALU`` support with +``-Xclang -target-feature -Xclang +alu32``. In CPU version 3, support is automatically included. + Atomic operations ================= From patchwork Tue Sep 27 18:59:48 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Thaler X-Patchwork-Id: 12991118 X-Patchwork-Delegate: bpf@iogearbox.net Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 685A8C6FA83 for ; Tue, 27 Sep 2022 19:00:27 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231418AbiI0TAZ (ORCPT ); Tue, 27 Sep 2022 15:00:25 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:53212 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231278AbiI0TAX (ORCPT ); Tue, 27 Sep 2022 15:00:23 -0400 Received: from mail-pg1-x533.google.com (mail-pg1-x533.google.com [IPv6:2607:f8b0:4864:20::533]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 325C01591C7 for ; Tue, 27 Sep 2022 12:00:22 -0700 (PDT) Received: by mail-pg1-x533.google.com with SMTP id s26so10214918pgv.7 for ; Tue, 27 Sep 2022 12:00:22 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlemail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date; bh=x0B5em+oByRfQ8P2Ax3jaMNoRGrlSl6+p6th4z5ktMk=; b=ZwPeY/zBK/Gg+tuhI6c1rLfyy9RlUw5HHrewot8Akje3fjkbLPFaVqClT38bR/EOgU KSKnQBAVIF0cpdmKmMQVYYknq8wPI9NNgLpIhmL1yNazHJIFGv/Em75GI2kdGITZm6sN 2iEIq6XXfg/oRQ/s5fucQlvJxMUtT2nWKqneoSeeMubetAt2fQV4Lmk67tehYY13Mp07 kEMP2GB0uclOdqc4Yd2U93jyzLmuhFfee+DtBzW8RkvLCbzkYZlFMVcMqmSoWodw0uo5 F0C6yvHNPBddHl7W9PgtSo+W13eUrRSZrzjKRJLhCzx2anGeisb0KTM1clK74i1jK4ar PfJA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; 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; bh=x0B5em+oByRfQ8P2Ax3jaMNoRGrlSl6+p6th4z5ktMk=; b=RhnQGCwsozKrUf/TywNtTNfdLbwNCdkKkjXeBchPiqsXHd0yRubwXlXvrJcde7EsiQ 8R7oy4EEsADzBsbBtGRUXLSFNIhdyNo+0ces7NWiP5Qi/T3GsUEfIKjnT70yZOg2/J0j QmDe/4B5zA526iqI969OI3xE7Wh9PXjYryjJ05o4WeRKlk4LWjPy+6PPRYUad2nPPOrV FvM9eGBgQYQRKGwI9XV2H+0h3elRWtjNNVcqU4S+YdvZaH0lgcItgBzVsE9KajBfvHdF oOsGHd4bx5IVxUgfER40au1gpC8ZwUvDNaOpXP3djY1B8CJRCGwXVsur636RPmj4E62L qgPg== X-Gm-Message-State: ACrzQf1u6AIRHDv/iTZzc3M1aT/cSh40eaTITG1ed3Q7ahnHMhlLYKS8 sAqt7hZUsmiNHUfXL8hSPL54oRcjYjY= X-Google-Smtp-Source: AMsMyM6x144sc8xIDHEO72HVzQXmGO+Xq7vYZeb0uBqcBIzGhZ+WZJaYyYjqi6+KeYHzEFcc66t9JA== X-Received: by 2002:a63:e105:0:b0:438:b084:78ad with SMTP id z5-20020a63e105000000b00438b08478admr25666503pgh.391.1664305220901; Tue, 27 Sep 2022 12:00:20 -0700 (PDT) Received: from mariner-vm.. ([131.107.1.181]) by smtp.gmail.com with ESMTPSA id mi9-20020a17090b4b4900b001f8aee0d826sm8737557pjb.53.2022.09.27.12.00.19 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 27 Sep 2022 12:00:20 -0700 (PDT) From: dthaler1968@googlemail.com To: bpf@vger.kernel.org Cc: Dave Thaler Subject: [PATCH 05/15] ebpf-docs: Add TOC and fix formatting Date: Tue, 27 Sep 2022 18:59:48 +0000 Message-Id: <20220927185958.14995-5-dthaler1968@googlemail.com> X-Mailer: git-send-email 2.33.4 In-Reply-To: <20220927185958.14995-1-dthaler1968@googlemail.com> References: <20220927185958.14995-1-dthaler1968@googlemail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Dave Thaler Signed-off-by: Dave Thaler --- Documentation/bpf/instruction-set.rst | 268 +++++++++++++------------- 1 file changed, 136 insertions(+), 132 deletions(-) diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst index 541483118..4997d2088 100644 --- a/Documentation/bpf/instruction-set.rst +++ b/Documentation/bpf/instruction-set.rst @@ -1,7 +1,12 @@ +.. contents:: +.. sectnum:: + +======================================== +eBPF Instruction Set Specification, v1.0 +======================================== + +This document specifies version 1.0 of the eBPF instruction set. -==================== -eBPF Instruction Set -==================== Registers and calling convention ================================ @@ -11,10 +16,10 @@ all of which are 64-bits wide. The eBPF calling convention is defined as: - * R0: return value from function calls, and exit value for eBPF programs - * R1 - R5: arguments for function calls - * R6 - R9: callee saved registers that function calls will preserve - * R10: read-only frame pointer to access stack +* R0: return value from function calls, and exit value for eBPF programs +* R1 - R5: arguments for function calls +* R6 - R9: callee saved registers that function calls will preserve +* R10: read-only frame pointer to access stack R0 - R5 are scratch registers and eBPF programs needs to spill/fill them if necessary across calls. @@ -24,17 +29,17 @@ Instruction encoding eBPF has two instruction encodings: - * the basic instruction encoding, which uses 64 bits to encode an instruction - * the wide instruction encoding, which appends a second 64-bit immediate value - (imm64) after the basic instruction for a total of 128 bits. +* the basic instruction encoding, which uses 64 bits to encode an instruction +* the wide instruction encoding, which appends a second 64-bit immediate value + (imm64) after the basic instruction for a total of 128 bits. The basic instruction encoding looks as follows: - ============= ======= =============== ==================== ============ - 32 bits (MSB) 16 bits 4 bits 4 bits 8 bits (LSB) - ============= ======= =============== ==================== ============ - immediate offset source register destination register opcode - ============= ======= =============== ==================== ============ +============= ======= =============== ==================== ============ +32 bits (MSB) 16 bits 4 bits 4 bits 8 bits (LSB) +============= ======= =============== ==================== ============ +immediate offset source register destination register opcode +============= ======= =============== ==================== ============ Note that most instructions do not use all of the fields. Unused fields shall be cleared to zero. @@ -44,30 +49,30 @@ Instruction classes The three LSB bits of the 'opcode' field store the instruction class: - ========= ===== =============================== - class value description - ========= ===== =============================== - BPF_LD 0x00 non-standard load operations - BPF_LDX 0x01 load into register operations - BPF_ST 0x02 store from immediate operations - BPF_STX 0x03 store from register operations - BPF_ALU 0x04 32-bit arithmetic operations - BPF_JMP 0x05 64-bit jump operations - BPF_JMP32 0x06 32-bit jump operations - BPF_ALU64 0x07 64-bit arithmetic operations - ========= ===== =============================== +========= ===== =============================== =================================== +class value description reference +========= ===== =============================== =================================== +BPF_LD 0x00 non-standard load operations `Load and store instructions`_ +BPF_LDX 0x01 load into register operations `Load and store instructions`_ +BPF_ST 0x02 store from immediate operations `Load and store instructions`_ +BPF_STX 0x03 store from register operations `Load and store instructions`_ +BPF_ALU 0x04 32-bit arithmetic operations `Arithmetic and jump instructions`_ +BPF_JMP 0x05 64-bit jump operations `Arithmetic and jump instructions`_ +BPF_JMP32 0x06 32-bit jump operations `Arithmetic and jump instructions`_ +BPF_ALU64 0x07 64-bit arithmetic operations `Arithmetic and jump instructions`_ +========= ===== =============================== =================================== Arithmetic and jump instructions ================================ -For arithmetic and jump instructions (BPF_ALU, BPF_ALU64, BPF_JMP and -BPF_JMP32), the 8-bit 'opcode' field is divided into three parts: +For arithmetic and jump instructions (``BPF_ALU``, ``BPF_ALU64``, ``BPF_JMP`` and +``BPF_JMP32``), the 8-bit 'opcode' field is divided into three parts: - ============== ====== ================= - 4 bits (MSB) 1 bit 3 bits (LSB) - ============== ====== ================= - operation code source instruction class - ============== ====== ================= +============== ====== ================= +4 bits (MSB) 1 bit 3 bits (LSB) +============== ====== ================= +operation code source instruction class +============== ====== ================= The 4th bit encodes the source operand: @@ -84,51 +89,51 @@ The four MSB bits store the operation code. Arithmetic instructions ----------------------- -BPF_ALU uses 32-bit wide operands while BPF_ALU64 uses 64-bit wide operands for +``BPF_ALU`` uses 32-bit wide operands while ``BPF_ALU64`` uses 64-bit wide operands for otherwise identical operations. -The code field encodes the operation as below: - - ======== ===== ================================================= - code value description - ======== ===== ================================================= - BPF_ADD 0x00 dst += src - BPF_SUB 0x10 dst -= src - BPF_MUL 0x20 dst \*= src - BPF_DIV 0x30 dst /= src - BPF_OR 0x40 dst \|= src - BPF_AND 0x50 dst &= src - BPF_LSH 0x60 dst <<= src - BPF_RSH 0x70 dst >>= src - BPF_NEG 0x80 dst = ~src - BPF_MOD 0x90 dst %= src - BPF_XOR 0xa0 dst ^= src - BPF_MOV 0xb0 dst = src - BPF_ARSH 0xc0 sign extending shift right - BPF_END 0xd0 byte swap operations (see separate section below) - ======== ===== ================================================= - -BPF_ADD | BPF_X | BPF_ALU means:: +The 'code' field encodes the operation as below: + +======== ===== ========================================================== +code value description +======== ===== ========================================================== +BPF_ADD 0x00 dst += src +BPF_SUB 0x10 dst -= src +BPF_MUL 0x20 dst \*= src +BPF_DIV 0x30 dst /= src +BPF_OR 0x40 dst \|= src +BPF_AND 0x50 dst &= src +BPF_LSH 0x60 dst <<= src +BPF_RSH 0x70 dst >>= src +BPF_NEG 0x80 dst = ~src +BPF_MOD 0x90 dst %= src +BPF_XOR 0xa0 dst ^= src +BPF_MOV 0xb0 dst = src +BPF_ARSH 0xc0 sign extending shift right +BPF_END 0xd0 byte swap operations (see `Byte swap instructions`_ below) +======== ===== ========================================================== + +``BPF_ADD | BPF_X | BPF_ALU`` means:: dst_reg = (u32) dst_reg + (u32) src_reg; -BPF_ADD | BPF_X | BPF_ALU64 means:: +``BPF_ADD | BPF_X | BPF_ALU64`` means:: dst_reg = dst_reg + src_reg -BPF_XOR | BPF_K | BPF_ALU means:: +``BPF_XOR | BPF_K | BPF_ALU`` means:: src_reg = (u32) src_reg ^ (u32) imm32 -BPF_XOR | BPF_K | BPF_ALU64 means:: +``BPF_XOR | BPF_K | BPF_ALU64`` means:: src_reg = src_reg ^ imm32 Byte swap instructions ----------------------- +~~~~~~~~~~~~~~~~~~~~~~ The byte swap instructions use an instruction class of ``BPF_ALU`` and a 4-bit -code field of ``BPF_END``. +'code' field of ``BPF_END``. The byte swap instructions operate on the destination register only and do not use a separate source register or immediate value. @@ -136,14 +141,14 @@ only and do not use a separate source register or immediate value. The 1-bit source operand field in the opcode is used to to select what byte order the operation convert from or to: - ========= ===== ================================================= - source value description - ========= ===== ================================================= - BPF_TO_LE 0x00 convert between host byte order and little endian - BPF_TO_BE 0x08 convert between host byte order and big endian - ========= ===== ================================================= +========= ===== ================================================= +source value description +========= ===== ================================================= +BPF_TO_LE 0x00 convert between host byte order and little endian +BPF_TO_BE 0x08 convert between host byte order and big endian +========= ===== ================================================= -The imm field encodes the width of the swap operations. The following widths +The 'imm' field encodes the width of the swap operations. The following widths are supported: 16, 32 and 64. Examples: @@ -159,28 +164,28 @@ Examples: Jump instructions ----------------- -BPF_JMP32 uses 32-bit wide operands while BPF_JMP uses 64-bit wide operands for +``BPF_JMP32`` uses 32-bit wide operands while ``BPF_JMP`` uses 64-bit wide operands for otherwise identical operations. -The code field encodes the operation as below: - - ======== ===== ========================= ============ - code value description notes - ======== ===== ========================= ============ - BPF_JA 0x00 PC += off BPF_JMP only - BPF_JEQ 0x10 PC += off if dst == src - BPF_JGT 0x20 PC += off if dst > src unsigned - BPF_JGE 0x30 PC += off if dst >= src unsigned - BPF_JSET 0x40 PC += off if dst & src - BPF_JNE 0x50 PC += off if dst != src - BPF_JSGT 0x60 PC += off if dst > src signed - BPF_JSGE 0x70 PC += off if dst >= src signed - BPF_CALL 0x80 function call - BPF_EXIT 0x90 function / program return BPF_JMP only - BPF_JLT 0xa0 PC += off if dst < src unsigned - BPF_JLE 0xb0 PC += off if dst <= src unsigned - BPF_JSLT 0xc0 PC += off if dst < src signed - BPF_JSLE 0xd0 PC += off if dst <= src signed - ======== ===== ========================= ============ +The 'code' field encodes the operation as below: + +======== ===== ========================= ============ +code value description notes +======== ===== ========================= ============ +BPF_JA 0x00 PC += off BPF_JMP only +BPF_JEQ 0x10 PC += off if dst == src +BPF_JGT 0x20 PC += off if dst > src unsigned +BPF_JGE 0x30 PC += off if dst >= src unsigned +BPF_JSET 0x40 PC += off if dst & src +BPF_JNE 0x50 PC += off if dst != src +BPF_JSGT 0x60 PC += off if dst > src signed +BPF_JSGE 0x70 PC += off if dst >= src signed +BPF_CALL 0x80 function call +BPF_EXIT 0x90 function / program return BPF_JMP only +BPF_JLT 0xa0 PC += off if dst < src unsigned +BPF_JLE 0xb0 PC += off if dst <= src unsigned +BPF_JSLT 0xc0 PC += off if dst < src signed +BPF_JSLE 0xd0 PC += off if dst <= src signed +======== ===== ========================= ============ The eBPF program needs to store the return value into register R0 before doing a BPF_EXIT. @@ -189,14 +194,26 @@ BPF_EXIT. Load and store instructions =========================== -For load and store instructions (BPF_LD, BPF_LDX, BPF_ST and BPF_STX), the +For load and store instructions (``BPF_LD``, ``BPF_LDX``, ``BPF_ST``, and ``BPF_STX``), the 8-bit 'opcode' field is divided as: - ============ ====== ================= - 3 bits (MSB) 2 bits 3 bits (LSB) - ============ ====== ================= - mode size instruction class - ============ ====== ================= +============ ====== ================= +3 bits (MSB) 2 bits 3 bits (LSB) +============ ====== ================= +mode size instruction class +============ ====== ================= + +The mode modifier is one of: + + ============= ===== ==================================== ============= + mode modifier value description reference + ============= ===== ==================================== ============= + BPF_IMM 0x00 64-bit immediate instructions `64-bit immediate instructions`_ + BPF_ABS 0x20 legacy BPF packet access (absolute) `Legacy BPF Packet access instructions`_ + BPF_IND 0x40 legacy BPF packet access (indirect) `Legacy BPF Packet access instructions`_ + BPF_MEM 0x60 regular load and store operations `Regular load and store operations`_ + BPF_ATOMIC 0xc0 atomic operations `Atomic operations`_ + ============= ===== ==================================== ============= The size modifier is one of: @@ -209,19 +226,6 @@ The size modifier is one of: BPF_DW 0x18 double word (8 bytes) ============= ===== ===================== -The mode modifier is one of: - - ============= ===== ==================================== - mode modifier value description - ============= ===== ==================================== - BPF_IMM 0x00 64-bit immediate instructions - BPF_ABS 0x20 legacy BPF packet access (absolute) - BPF_IND 0x40 legacy BPF packet access (indirect) - BPF_MEM 0x60 regular load and store operations - BPF_ATOMIC 0xc0 atomic operations - ============= ===== ==================================== - - Regular load and store operations --------------------------------- @@ -252,42 +256,42 @@ by other eBPF programs or means outside of this specification. All atomic operations supported by eBPF are encoded as store operations that use the ``BPF_ATOMIC`` mode modifier as follows: - * ``BPF_ATOMIC | BPF_W | BPF_STX`` for 32-bit operations - * ``BPF_ATOMIC | BPF_DW | BPF_STX`` for 64-bit operations - * 8-bit and 16-bit wide atomic operations are not supported. +* ``BPF_ATOMIC | BPF_W | BPF_STX`` for 32-bit operations +* ``BPF_ATOMIC | BPF_DW | BPF_STX`` for 64-bit operations +* 8-bit and 16-bit wide atomic operations are not supported. -The imm field is used to encode the actual atomic operation. +The 'imm' field is used to encode the actual atomic operation. Simple atomic operation use a subset of the values defined to encode -arithmetic operations in the imm field to encode the atomic operation: +arithmetic operations in the 'imm' field to encode the atomic operation: - ======== ===== =========== - imm value description - ======== ===== =========== - BPF_ADD 0x00 atomic add - BPF_OR 0x40 atomic or - BPF_AND 0x50 atomic and - BPF_XOR 0xa0 atomic xor - ======== ===== =========== +======== ===== =========== +imm value description +======== ===== =========== +BPF_ADD 0x00 atomic add +BPF_OR 0x40 atomic or +BPF_AND 0x50 atomic and +BPF_XOR 0xa0 atomic xor +======== ===== =========== -``BPF_ATOMIC | BPF_W | BPF_STX`` with imm = BPF_ADD means:: +``BPF_ATOMIC | BPF_W | BPF_STX`` with 'imm' = BPF_ADD means:: *(u32 *)(dst_reg + off16) += src_reg -``BPF_ATOMIC | BPF_DW | BPF_STX`` with imm = BPF ADD means:: +``BPF_ATOMIC | BPF_DW | BPF_STX`` with 'imm' = BPF ADD means:: *(u64 *)(dst_reg + off16) += src_reg In addition to the simple atomic operations, there also is a modifier and two complex atomic operations: - =========== ================ =========================== - imm value description - =========== ================ =========================== - BPF_FETCH 0x01 modifier: return old value - BPF_XCHG 0xe0 | BPF_FETCH atomic exchange - BPF_CMPXCHG 0xf0 | BPF_FETCH atomic compare and exchange - =========== ================ =========================== +=========== ================ =========================== +imm value description +=========== ================ =========================== +BPF_FETCH 0x01 modifier: return old value +BPF_XCHG 0xe0 | BPF_FETCH atomic exchange +BPF_CMPXCHG 0xf0 | BPF_FETCH atomic compare and exchange +=========== ================ =========================== The ``BPF_FETCH`` modifier is optional for simple atomic operations, and always set for the complex atomic operations. If the ``BPF_FETCH`` flag @@ -306,7 +310,7 @@ and loaded back to ``R0``. 64-bit immediate instructions ----------------------------- -Instructions with the ``BPF_IMM`` mode modifier use the wide instruction +Instructions with the ``BPF_IMM`` 'mode' modifier use the wide instruction encoding for an extra imm64 value. There is currently only one such instruction. From patchwork Tue Sep 27 18:59:49 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Thaler X-Patchwork-Id: 12991117 X-Patchwork-Delegate: bpf@iogearbox.net Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 32AE0C07E9D for ; Tue, 27 Sep 2022 19:00:27 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229779AbiI0TAY (ORCPT ); Tue, 27 Sep 2022 15:00:24 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:53214 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231240AbiI0TAX (ORCPT ); Tue, 27 Sep 2022 15:00:23 -0400 Received: from mail-pg1-x533.google.com (mail-pg1-x533.google.com [IPv6:2607:f8b0:4864:20::533]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id A5C3815EFA3 for ; Tue, 27 Sep 2022 12:00:22 -0700 (PDT) Received: by mail-pg1-x533.google.com with SMTP id u69so10235998pgd.2 for ; Tue, 27 Sep 2022 12:00:22 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlemail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date; bh=MoO/Vd3tHUhNgy1Ah7hXRl6Wax5Zfvh8DPFtmIVmBMA=; b=LiRocCVn3n0C08rhsuROJNzmonmZHrZv4RdEaW3nuzRS5VhxUzRmmyLi3ET8BMswBF kKQ0IOhXeG0+BaicYp8HLMdswPISS+kbiCYsmPvrHJ5LBgOP4fYVS/Uz7/JyY5wC8fOx nN0l5D4oT4xaVUDEO9egp8Z0PHbyCGQxolVhdy06RQ105P8+a7oYlnMXz1UFXY2S5o4Z UlnDUjg1CbC4HfosyaZSBDa6ikHdHn7vzKoMzIh0t0KXqMxyyJwfm2rRBYIiA4z5/FLg 2sQy/NIyWxEKBPuZh28YCdkHL095jdoPH1Qlf/0D8YjZN0I2MDCVdPLEBTV6uzl5asT1 krwA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; 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; bh=MoO/Vd3tHUhNgy1Ah7hXRl6Wax5Zfvh8DPFtmIVmBMA=; b=pPr/6e88dSeoTT4/RhZ8Ey6CGa9mIh5hDwvsi4ORaQz4+SvQFtW7ZyeU3uIFV4eoy5 eHcwhrxmliK61H2gCOJMImBn6sgmwZMDo1QyyAStJLcNc4ut71I05ooBZUjkzI/hlTYf G8agZ0TAvY0V2D75aVPsX8dBRXXpZ3bm0e59Jzz2q9Hkg9xp0/o59OgF1hNpS3OzsIXt VreiVMGAtMMYY89XmVVOcmbeAfVTMm76A74guV3Nc1L4DqbbixtVQPVUhXsUpXFBorCA vA4C+J6aSxm+7RKYsmRpiLkfP76c4SFiM50hps4qlZj8vg3rK1ln8aHpm2JOINF51Js0 bMMw== X-Gm-Message-State: ACrzQf2fjJusVgFpD1JD10RvrQ0iR+zTPCYNZaP/g63XmX/UogEoMnW0 dWx6td4jGx9UE3kY4KUo2obviI9RD6g= X-Google-Smtp-Source: AMsMyM5kO6we4jM57grRVtXWNHQ5THdkBY1wGmU3SmeaEl4HkYEUhElhz5c4LsHQGd0QMvOqOt6McQ== X-Received: by 2002:a63:d1b:0:b0:42b:828b:f14a with SMTP id c27-20020a630d1b000000b0042b828bf14amr25935931pgl.235.1664305221720; Tue, 27 Sep 2022 12:00:21 -0700 (PDT) Received: from mariner-vm.. ([131.107.1.181]) by smtp.gmail.com with ESMTPSA id mi9-20020a17090b4b4900b001f8aee0d826sm8737557pjb.53.2022.09.27.12.00.21 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 27 Sep 2022 12:00:21 -0700 (PDT) From: dthaler1968@googlemail.com To: bpf@vger.kernel.org Cc: Dave Thaler Subject: [PATCH 06/15] ebpf-docs: Use standard type convention in standard doc Date: Tue, 27 Sep 2022 18:59:49 +0000 Message-Id: <20220927185958.14995-6-dthaler1968@googlemail.com> X-Mailer: git-send-email 2.33.4 In-Reply-To: <20220927185958.14995-1-dthaler1968@googlemail.com> References: <20220927185958.14995-1-dthaler1968@googlemail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Dave Thaler Signed-off-by: Dave Thaler --- Documentation/bpf/instruction-set.rst | 14 ++++++++++---- Documentation/bpf/linux-notes.rst | 6 ++++++ 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst index 4997d2088..a24bc5d53 100644 --- a/Documentation/bpf/instruction-set.rst +++ b/Documentation/bpf/instruction-set.rst @@ -7,6 +7,10 @@ eBPF Instruction Set Specification, v1.0 This document specifies version 1.0 of the eBPF instruction set. +Documentation conventions +========================= + +This specification uses the standard C types (uint32_t, etc.) in documentation. Registers and calling convention ================================ @@ -114,7 +118,9 @@ BPF_END 0xd0 byte swap operations (see `Byte swap instructions`_ below) ``BPF_ADD | BPF_X | BPF_ALU`` means:: - dst_reg = (u32) dst_reg + (u32) src_reg; + dst_reg = (uint32_t) dst_reg + (uint32_t) src_reg; + +where '(uint32_t)' indicates truncation to 32 bits. ``BPF_ADD | BPF_X | BPF_ALU64`` means:: @@ -122,7 +128,7 @@ BPF_END 0xd0 byte swap operations (see `Byte swap instructions`_ below) ``BPF_XOR | BPF_K | BPF_ALU`` means:: - src_reg = (u32) src_reg ^ (u32) imm32 + src_reg = (uint32_t) src_reg ^ (uint32_t) imm32 ``BPF_XOR | BPF_K | BPF_ALU64`` means:: @@ -276,11 +282,11 @@ BPF_XOR 0xa0 atomic xor ``BPF_ATOMIC | BPF_W | BPF_STX`` with 'imm' = BPF_ADD means:: - *(u32 *)(dst_reg + off16) += src_reg + *(uint32_t *)(dst_reg + off16) += src_reg ``BPF_ATOMIC | BPF_DW | BPF_STX`` with 'imm' = BPF ADD means:: - *(u64 *)(dst_reg + off16) += src_reg + *(uint32_t *)(dst_reg + off16) += src_reg In addition to the simple atomic operations, there also is a modifier and two complex atomic operations: diff --git a/Documentation/bpf/linux-notes.rst b/Documentation/bpf/linux-notes.rst index 1c31379b4..522ebe27d 100644 --- a/Documentation/bpf/linux-notes.rst +++ b/Documentation/bpf/linux-notes.rst @@ -7,6 +7,12 @@ Linux implementation notes This document provides more details specific to the Linux kernel implementation of the eBPF instruction set. +Arithmetic instructions +======================= + +While the eBPF instruction set document uses the standard C terminology as the cross-platform specification, +in the Linux kernel, uint32_t is expressed as u32, uint64_t is expressed as u64, etc. + Byte swap instructions ====================== From patchwork Tue Sep 27 18:59:50 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Thaler X-Patchwork-Id: 12991122 X-Patchwork-Delegate: bpf@iogearbox.net Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id C563BC6FA82 for ; Tue, 27 Sep 2022 19:00:51 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231312AbiI0TAt (ORCPT ); Tue, 27 Sep 2022 15:00:49 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:53602 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231329AbiI0TAc (ORCPT ); Tue, 27 Sep 2022 15:00:32 -0400 Received: from mail-pl1-x62a.google.com (mail-pl1-x62a.google.com [IPv6:2607:f8b0:4864:20::62a]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 5E46D18A4A3 for ; Tue, 27 Sep 2022 12:00:28 -0700 (PDT) Received: by mail-pl1-x62a.google.com with SMTP id f23so9901509plr.6 for ; Tue, 27 Sep 2022 12:00:28 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlemail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date; bh=XxkoEN7lZP3Dtq56SUjv5/hG8wKNzCHhcEcj/U1ulzU=; b=DDCdeVJ7ww8Lrc/EalswqOY30PfAlCZ8IoZiAdrx9UPZpt+DSiu32A+7V3sM7/19A7 8Kmz/L73b/04hJfPbxVCezyd0Jo4RHvbkUDL0J5rpxSIoHRTH2w6mIsXbQWBJzJmQjIF SU8dOw41pwU/RMzvuClNSSsyZf3mgLFlAte9HS9IrBaPMKaoXGw1Krpz85GzKv+oGjAI 2vTdWW9hVDNzmQy1QH/Owjvz4w64sWZ1y+r0cBImNKftTZO55Y9g1oRrprfYB9GvhJGQ CQNpX8hc+2NwX6JiKqWykfHTVD+SG9at179a8/TeyI9IXrRi3sgz3oOMO+bJQ+Q5ENGR YkNA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; 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; bh=XxkoEN7lZP3Dtq56SUjv5/hG8wKNzCHhcEcj/U1ulzU=; b=SMSbDC3hw/KmMsSlqFh/QsR0ltYrFebz7VdqS8tL4nUXYQKWXClAHZui9nifhQAr3V QSDGIBZMKxTvXhSIx6YgvwhpeMUhWFZjX7r2PB0XbcjO9ig2l/rgvS66u7D/5VYSjkll W7bLTtyojjHd/E5ZYcmhpLc1c7aKDz0eeSZb21NIe+JWDqIzIrC7a13riKR8TsSi6ZOm dxEiGG6Rpi7CEiEpgY7kaSLBch72T0bkwoiZ8QcF5BQrtIjG23f5+dX5765sabQY576W IDnceN7oWFKKl9/cLy/6MErv0Nx/scl8EOSnzO1TIKNdeGf8QsieB3FcgxOhmkFVeDYM 9BPA== X-Gm-Message-State: ACrzQf0Rrb4PgDaPVHfozhoVx6vbYeYNLJ0ZAmPh6sTrAHXELw8RrMFa S4+Bjx2+UboqnlZr2br3L0ZiFE2r4j0= X-Google-Smtp-Source: AMsMyM6oQPkHYKJuIt9OoZrZ64Z9+5WAVxfCU6MRKYmkekti6AjyNN4HcvLvQdzDai8kBYH2BMHHOQ== X-Received: by 2002:a17:90a:ba8f:b0:202:f6b1:eebc with SMTP id t15-20020a17090aba8f00b00202f6b1eebcmr6137485pjr.241.1664305222644; Tue, 27 Sep 2022 12:00:22 -0700 (PDT) Received: from mariner-vm.. ([131.107.1.181]) by smtp.gmail.com with ESMTPSA id mi9-20020a17090b4b4900b001f8aee0d826sm8737557pjb.53.2022.09.27.12.00.21 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 27 Sep 2022 12:00:22 -0700 (PDT) From: dthaler1968@googlemail.com To: bpf@vger.kernel.org Cc: Dave Thaler Subject: [PATCH 07/15] ebpf-docs: Fix modulo zero, division by zero, overflow, and underflow Date: Tue, 27 Sep 2022 18:59:50 +0000 Message-Id: <20220927185958.14995-7-dthaler1968@googlemail.com> X-Mailer: git-send-email 2.33.4 In-Reply-To: <20220927185958.14995-1-dthaler1968@googlemail.com> References: <20220927185958.14995-1-dthaler1968@googlemail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Dave Thaler Signed-off-by: Dave Thaler --- Documentation/bpf/instruction-set.rst | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst index a24bc5d53..3c5a63612 100644 --- a/Documentation/bpf/instruction-set.rst +++ b/Documentation/bpf/instruction-set.rst @@ -103,19 +103,26 @@ code value description BPF_ADD 0x00 dst += src BPF_SUB 0x10 dst -= src BPF_MUL 0x20 dst \*= src -BPF_DIV 0x30 dst /= src +BPF_DIV 0x30 dst = (src != 0) ? (dst / src) : 0 BPF_OR 0x40 dst \|= src BPF_AND 0x50 dst &= src BPF_LSH 0x60 dst <<= src BPF_RSH 0x70 dst >>= src BPF_NEG 0x80 dst = ~src -BPF_MOD 0x90 dst %= src +BPF_MOD 0x90 dst = (src != 0) ? (dst % src) : dst BPF_XOR 0xa0 dst ^= src BPF_MOV 0xb0 dst = src BPF_ARSH 0xc0 sign extending shift right BPF_END 0xd0 byte swap operations (see `Byte swap instructions`_ below) ======== ===== ========================================================== +Underflow and overflow are allowed during arithmetic operations, +meaning the 64-bit or 32-bit value will wrap. If +eBPF program execution would result in division by zero, +the destination register is instead set to zero. +If execution would result in modulo by zero, +the destination register is instead left unchanged. + ``BPF_ADD | BPF_X | BPF_ALU`` means:: dst_reg = (uint32_t) dst_reg + (uint32_t) src_reg; @@ -135,6 +142,14 @@ where '(uint32_t)' indicates truncation to 32 bits. src_reg = src_reg ^ imm32 +Also note that the modulo operation often varies by language +when the dividend or divisor are negative, where Python, Ruby, etc. +differ from C, Go, Java, etc. This specification requires that +modulo use truncated division (where -13 % 3 == -1) as implemented +in C, Go, etc.: + + a % n = a - n * trunc(a / n) + Byte swap instructions ~~~~~~~~~~~~~~~~~~~~~~ From patchwork Tue Sep 27 18:59:51 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Thaler X-Patchwork-Id: 12991119 X-Patchwork-Delegate: bpf@iogearbox.net Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id AC52BC07E9D for ; Tue, 27 Sep 2022 19:00:35 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231653AbiI0TAc (ORCPT ); Tue, 27 Sep 2022 15:00:32 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:53564 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231431AbiI0TA2 (ORCPT ); Tue, 27 Sep 2022 15:00:28 -0400 Received: from mail-pg1-x535.google.com (mail-pg1-x535.google.com [IPv6:2607:f8b0:4864:20::535]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 83A041616F6 for ; Tue, 27 Sep 2022 12:00:24 -0700 (PDT) Received: by mail-pg1-x535.google.com with SMTP id c7so10194237pgt.11 for ; Tue, 27 Sep 2022 12:00:24 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlemail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date; bh=Nw/t2m0f2c5hznJWzaS3i9UGa9/OhuZEG5rlsTXfrlU=; b=WDHeQJayoPlcLIAT0PwGLYL28nQ0MlFQ5Prv+X60Be5lkQaSB5Oo/iVR5dwKkQ5qV+ iQR8Ca2xUL/L9dHMxE7slcRCWLMhE60d7GKz8NPXwiTNDN3IhviVwK6Rqjwdg1l4ti5a 9TQospcDvME7NwiFeQl3IxeGtSjjEkI1Dx3FHvIbj818L0GE3KXixqlxvra6pe/68rh1 QZBht+yW3dvSBhG/rJ+WbG6q0TRYaBldecbICX4f4z+iFgkDaefefNmD4lAQuJQ571y9 0yNalVeofJ8zxDRd9K8eVmRhOCs+WI86wFWpEkIt5kauQa1QoBC0/crmixUN1/kuK4jo N2zg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; 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; bh=Nw/t2m0f2c5hznJWzaS3i9UGa9/OhuZEG5rlsTXfrlU=; b=Z1gAm7amFti5CzSxs/FKBulecOBz58r/VhzURdElH4eKXXbn05S7kX9rPDT85LRUdU saaeOVUQtXuha+ugtAeih8utTDnWUWWgYNnI0IZsDRxyHr4lNqiVjQaY6y5G8hgmJasX bfPpXHQhY4I5xDggubbTZgltsghtWA6lgvSJ766S9ovIlwboBd182/rPBZF1XVWaNuVU h/Ti8pp9btn24D3RHH2bt6hXhAI4n6uO3jiYkBHKuR+f/sD4sdEhTvxxIgWNYm445FZB Zn55P21ZiO5eFHXPTe5pWGkNkuLbIGisXLMqV9gc0/lMLNR8zYbg4FrUC6Epa0bkgGZI SyRw== X-Gm-Message-State: ACrzQf0Mi4C2OKHscejmJxj8Ix5mVm4VGIOSDLFLq35njdC2MidWnbQI 44b6T2PH/mFpspMM80SA/cEkiEudRsA= X-Google-Smtp-Source: AMsMyM4rB6rKe31qH8AwaR3lYQWw49W9XWM7CtjjSwe3zGLOo3mSBy9uTfh+DH48YJ/vCYbWvZWmbg== X-Received: by 2002:a63:9d06:0:b0:43a:5cf5:1204 with SMTP id i6-20020a639d06000000b0043a5cf51204mr25449929pgd.557.1664305223538; Tue, 27 Sep 2022 12:00:23 -0700 (PDT) Received: from mariner-vm.. ([131.107.1.181]) by smtp.gmail.com with ESMTPSA id mi9-20020a17090b4b4900b001f8aee0d826sm8737557pjb.53.2022.09.27.12.00.22 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 27 Sep 2022 12:00:23 -0700 (PDT) From: dthaler1968@googlemail.com To: bpf@vger.kernel.org Cc: Dave Thaler Subject: [PATCH 08/15] ebpf-docs: Use consistent names for the same field Date: Tue, 27 Sep 2022 18:59:51 +0000 Message-Id: <20220927185958.14995-8-dthaler1968@googlemail.com> X-Mailer: git-send-email 2.33.4 In-Reply-To: <20220927185958.14995-1-dthaler1968@googlemail.com> References: <20220927185958.14995-1-dthaler1968@googlemail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Dave Thaler Signed-off-by: Dave Thaler --- Documentation/bpf/instruction-set.rst | 107 ++++++++++++++++++-------- 1 file changed, 76 insertions(+), 31 deletions(-) diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst index 3c5a63612..2987234eb 100644 --- a/Documentation/bpf/instruction-set.rst +++ b/Documentation/bpf/instruction-set.rst @@ -34,20 +34,59 @@ Instruction encoding eBPF has two instruction encodings: * the basic instruction encoding, which uses 64 bits to encode an instruction -* the wide instruction encoding, which appends a second 64-bit immediate value - (imm64) after the basic instruction for a total of 128 bits. +* the wide instruction encoding, which appends a second 64-bit immediate (i.e., + constant) value after the basic instruction for a total of 128 bits. -The basic instruction encoding looks as follows: +The basic instruction encoding is as follows, where MSB and LSB mean the most significant +bits and least significant bits, respectively: ============= ======= =============== ==================== ============ 32 bits (MSB) 16 bits 4 bits 4 bits 8 bits (LSB) ============= ======= =============== ==================== ============ -immediate offset source register destination register opcode +imm offset src dst opcode ============= ======= =============== ==================== ============ +imm + signed integer immediate value + +offset + signed integer offset used with pointer arithmetic + +src + the source register number (0-10), except where otherwise specified + (`64-bit immediate instructions`_ reuse this field for other purposes) + +dst + destination register number (0-10) + +opcode + operation to perform + Note that most instructions do not use all of the fields. Unused fields shall be cleared to zero. +As discussed below in `64-bit immediate instructions`_, some +instructions use a 64-bit immediate value that is constructed as follows. +The 64 bits following the basic instruction contain a pseudo instruction +using the same format but with opcode, dst, src, and offset all set to zero, +and imm containing the high 32 bits of the immediate value. + +================= ================== +64 bits (MSB) 64 bits (LSB) +================= ================== +basic instruction pseudo instruction +================= ================== + +Thus the 64-bit immediate value is constructed as follows: + + imm64 = imm + (next_imm << 32) + +where 'next_imm' refers to the imm value of the pseudo instruction +following the basic instruction. + +In the remainder of this document 'src' and 'dst' refer to the values of the source +and destination registers, respectively, rather than the register number. + Instruction classes ------------------- @@ -75,20 +114,24 @@ For arithmetic and jump instructions (``BPF_ALU``, ``BPF_ALU64``, ``BPF_JMP`` an ============== ====== ================= 4 bits (MSB) 1 bit 3 bits (LSB) ============== ====== ================= -operation code source instruction class +code source instruction class ============== ====== ================= -The 4th bit encodes the source operand: +code + the operation code, whose meaning varies by instruction class - ====== ===== ======================================== - source value description - ====== ===== ======================================== - BPF_K 0x00 use 32-bit immediate as source operand - BPF_X 0x08 use 'src_reg' register as source operand - ====== ===== ======================================== +source + the source operand location, which unless otherwise specified is one of: -The four MSB bits store the operation code. + ====== ===== ========================================== + source value description + ====== ===== ========================================== + BPF_K 0x00 use 32-bit 'imm' value as source operand + BPF_X 0x08 use 'src' register value as source operand + ====== ===== ========================================== +instruction class + the instruction class (see `Instruction classes`_) Arithmetic instructions ----------------------- @@ -116,6 +159,8 @@ BPF_ARSH 0xc0 sign extending shift right BPF_END 0xd0 byte swap operations (see `Byte swap instructions`_ below) ======== ===== ========================================================== +where 'src' is the source operand value. + Underflow and overflow are allowed during arithmetic operations, meaning the 64-bit or 32-bit value will wrap. If eBPF program execution would result in division by zero, @@ -125,21 +170,21 @@ the destination register is instead left unchanged. ``BPF_ADD | BPF_X | BPF_ALU`` means:: - dst_reg = (uint32_t) dst_reg + (uint32_t) src_reg; + dst = (uint32_t) (dst + src) where '(uint32_t)' indicates truncation to 32 bits. ``BPF_ADD | BPF_X | BPF_ALU64`` means:: - dst_reg = dst_reg + src_reg + dst = dst + src ``BPF_XOR | BPF_K | BPF_ALU`` means:: - src_reg = (uint32_t) src_reg ^ (uint32_t) imm32 + src = (uint32_t) src ^ (uint32_t) imm ``BPF_XOR | BPF_K | BPF_ALU64`` means:: - src_reg = src_reg ^ imm32 + src = src ^ imm Also note that the modulo operation often varies by language @@ -176,11 +221,11 @@ Examples: ``BPF_ALU | BPF_TO_LE | BPF_END`` with imm = 16 means:: - dst_reg = htole16(dst_reg) + dst = htole16(dst) ``BPF_ALU | BPF_TO_BE | BPF_END`` with imm = 64 means:: - dst_reg = htobe64(dst_reg) + dst = htobe64(dst) Jump instructions ----------------- @@ -255,15 +300,15 @@ instructions that transfer data between a register and memory. ``BPF_MEM | | BPF_STX`` means:: - *(size *) (dst_reg + off) = src_reg + *(size *) (dst + offset) = src_reg ``BPF_MEM | | BPF_ST`` means:: - *(size *) (dst_reg + off) = imm32 + *(size *) (dst + offset) = imm32 ``BPF_MEM | | BPF_LDX`` means:: - dst_reg = *(size *) (src_reg + off) + dst = *(size *) (src + offset) Where size is one of: ``BPF_B``, ``BPF_H``, ``BPF_W``, or ``BPF_DW``. @@ -297,11 +342,11 @@ BPF_XOR 0xa0 atomic xor ``BPF_ATOMIC | BPF_W | BPF_STX`` with 'imm' = BPF_ADD means:: - *(uint32_t *)(dst_reg + off16) += src_reg + *(uint32_t *)(dst + offset) += src ``BPF_ATOMIC | BPF_DW | BPF_STX`` with 'imm' = BPF ADD means:: - *(uint32_t *)(dst_reg + off16) += src_reg + *(uint64_t *)(dst + offset) += src In addition to the simple atomic operations, there also is a modifier and two complex atomic operations: @@ -316,16 +361,16 @@ BPF_CMPXCHG 0xf0 | BPF_FETCH atomic compare and exchange The ``BPF_FETCH`` modifier is optional for simple atomic operations, and always set for the complex atomic operations. If the ``BPF_FETCH`` flag -is set, then the operation also overwrites ``src_reg`` with the value that +is set, then the operation also overwrites ``src`` with the value that was in memory before it was modified. -The ``BPF_XCHG`` operation atomically exchanges ``src_reg`` with the value -addressed by ``dst_reg + off``. +The ``BPF_XCHG`` operation atomically exchanges ``src`` with the value +addressed by ``dst + offset``. The ``BPF_CMPXCHG`` operation atomically compares the value addressed by -``dst_reg + off`` with ``R0``. If they match, the value addressed by -``dst_reg + off`` is replaced with ``src_reg``. In either case, the -value that was at ``dst_reg + off`` before the operation is zero-extended +``dst + offset`` with ``R0``. If they match, the value addressed by +``dst + offset`` is replaced with ``src``. In either case, the +value that was at ``dst + offset`` before the operation is zero-extended and loaded back to ``R0``. 64-bit immediate instructions @@ -338,7 +383,7 @@ There is currently only one such instruction. ``BPF_LD | BPF_DW | BPF_IMM`` means:: - dst_reg = imm64 + dst = imm64 Legacy BPF Packet access instructions From patchwork Tue Sep 27 18:59:52 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Thaler X-Patchwork-Id: 12991120 X-Patchwork-Delegate: bpf@iogearbox.net Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 5379DC6FA82 for ; Tue, 27 Sep 2022 19:00:37 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231431AbiI0TAd (ORCPT ); Tue, 27 Sep 2022 15:00:33 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:53596 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231174AbiI0TA3 (ORCPT ); Tue, 27 Sep 2022 15:00:29 -0400 Received: from mail-pg1-x534.google.com (mail-pg1-x534.google.com [IPv6:2607:f8b0:4864:20::534]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 04E65160E7E for ; Tue, 27 Sep 2022 12:00:25 -0700 (PDT) Received: by mail-pg1-x534.google.com with SMTP id 3so10239697pga.1 for ; Tue, 27 Sep 2022 12:00:25 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlemail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date; bh=j3/b2wUTfsE5qVDAxGn10zca1M0PYuiEt7a+BrViBG4=; b=OVAkg0cO1XTzq99+U5oBUSHN03Zj0ErumSrI2IuBmsIjaQ5OOHnsThBbLIppr/FDwQ v+XlUvYS73fd4unsSFt3SMMlJ3WCXEMNiKzR1YMxIGvMqGNWnPe+68AlLXpeBBI6uHqc DIcLo9nrkLtVrO7B7oLpyG4dVEZSTxGYRANbZgaruEPKnc1pUrJNrarn6yopSEYQz2fJ 1aFfcbohZaXcIebn7E7lAZder+bzDxct41OgxIqhk89uz8TatKf4+xLstWu+J7JNx8tt 4wEpgvxjfQK212Lfa5VAir2C5z7iGAi46rH0XD4bzFJ94DvVhWW6cIgLQox7qTJME2Cg 9evA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; 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; bh=j3/b2wUTfsE5qVDAxGn10zca1M0PYuiEt7a+BrViBG4=; b=aLIcPfytqRZ4k/Uh8xZXkOfJRfda6uBp44RZZFjEpY5LlidJc+66MtvOqkX0EurQYE 4ETo7qG7+jEQ+vQo3RcVe4kG48Bm8atZzPy19gEsDz3MDjgQib96EUnev8F0JcXkBtBh eExgTe7H5xF5sTgJYJP8WV1kmxGV2zhzBTocj5rqe6R0Bp5XoCL3676yfnpH9Ogkw/BO G4xEu8UdgIbp8baJcPT0TjbZM1RyGUknE+drDlYHXXpGCGQV1LgvqSkcs7Fty/tMkNrA WG5LBmiC4oS1tGKMsK0TA1HVHgFiuh+H+AQhvYEqoz9oSppwYmMgtr9Yb2HWcV1iv8sz jZTA== X-Gm-Message-State: ACrzQf1atrvEMeaI+nczGu381O50Q6i7RAyvTLrUAq1k9ueaXTJeCnWU 0dHHtYhPPgl+QjtjZcRYYUjEh0TIRDg= X-Google-Smtp-Source: AMsMyM4cySSzW/ENDiU+zgvY00gEl1adqOicC6QCyKKxeiu4HPRoBkgRMGViby1sCcfLv38MqRn0vg== X-Received: by 2002:a63:4449:0:b0:43c:c1c4:bd54 with SMTP id t9-20020a634449000000b0043cc1c4bd54mr8206042pgk.150.1664305224869; Tue, 27 Sep 2022 12:00:24 -0700 (PDT) Received: from mariner-vm.. ([131.107.1.181]) by smtp.gmail.com with ESMTPSA id mi9-20020a17090b4b4900b001f8aee0d826sm8737557pjb.53.2022.09.27.12.00.23 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 27 Sep 2022 12:00:23 -0700 (PDT) From: dthaler1968@googlemail.com To: bpf@vger.kernel.org Cc: Dave Thaler Subject: [PATCH 09/15] ebpf-docs: Explain helper functions Date: Tue, 27 Sep 2022 18:59:52 +0000 Message-Id: <20220927185958.14995-9-dthaler1968@googlemail.com> X-Mailer: git-send-email 2.33.4 In-Reply-To: <20220927185958.14995-1-dthaler1968@googlemail.com> References: <20220927185958.14995-1-dthaler1968@googlemail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Dave Thaler Signed-off-by: Dave Thaler --- Documentation/bpf/instruction-set.rst | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst index 2987234eb..926957830 100644 --- a/Documentation/bpf/instruction-set.rst +++ b/Documentation/bpf/instruction-set.rst @@ -245,7 +245,7 @@ BPF_JSET 0x40 PC += off if dst & src BPF_JNE 0x50 PC += off if dst != src BPF_JSGT 0x60 PC += off if dst > src signed BPF_JSGE 0x70 PC += off if dst >= src signed -BPF_CALL 0x80 function call +BPF_CALL 0x80 function call see `Helper functions`_ BPF_EXIT 0x90 function / program return BPF_JMP only BPF_JLT 0xa0 PC += off if dst < src unsigned BPF_JLE 0xb0 PC += off if dst <= src unsigned @@ -256,6 +256,22 @@ BPF_JSLE 0xd0 PC += off if dst <= src signed The eBPF program needs to store the return value into register R0 before doing a BPF_EXIT. +Helper functions +~~~~~~~~~~~~~~~~ +Helper functions are a concept whereby BPF programs can call into a +set of function calls exposed by the eBPF runtime. Each helper +function is identified by an integer used in a ``BPF_CALL`` instruction. +The available helper functions may differ for each eBPF program type. + +Conceptually, each helper function is implemented with a commonly shared function +signature defined as: + + uint64_t function(uint64_t r1, uint64_t r2, uint64_t r3, uint64_t r4, uint64_t r5) + +In actuality, each helper function is defined as taking between 0 and 5 arguments, +with the remaining registers being ignored. The definition of a helper function +is responsible for specifying the type (e.g., integer, pointer, etc.) of the value returned, +the number of arguments, and the type of each argument. Load and store instructions =========================== From patchwork Tue Sep 27 18:59:53 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Thaler X-Patchwork-Id: 12991121 X-Patchwork-Delegate: bpf@iogearbox.net Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 45DD5C07E9D for ; Tue, 27 Sep 2022 19:00:50 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229770AbiI0TAs (ORCPT ); Tue, 27 Sep 2022 15:00:48 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:53778 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231650AbiI0TAb (ORCPT ); Tue, 27 Sep 2022 15:00:31 -0400 Received: from mail-pg1-x529.google.com (mail-pg1-x529.google.com [IPv6:2607:f8b0:4864:20::529]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id EF902189395 for ; Tue, 27 Sep 2022 12:00:27 -0700 (PDT) Received: by mail-pg1-x529.google.com with SMTP id f193so10262808pgc.0 for ; Tue, 27 Sep 2022 12:00:27 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlemail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date; bh=XZ+XKQt00DavoiQMa2NSCBNZMRK/jHP2FO1uzN0dL/s=; b=Ey96kWaYML7ccOx7SUkzdrA8QktBiBJNjTsCiIQRUiXzdmc4l84Jgkdp6yos7Dngxq oD8wsmQq2/khBW6pAe5uVtTeNo4P8IiYZdZ6D3OfOoWsCo1Ozf+YAo3njXLrT1wd+7Ql rHfiy2bDiSVKGcFqYpxAGR2jlQengmGUqfhNSTv/0SjKNJxCCckYkYuxbLYa7NCnpZEe 1AnwoGOOgXE0IgxsT+wXWwaZqxOQ9adjbjtvSNVi1fhFN104jnkFDm3+B86CVBf72caC WEFOJf6/aPPAhIhBwlUIzrHusy80QdroOdmZM9nr/0+DIT5gGJjfAfVKkd2zs1BKM7GW LaQw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; 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; bh=XZ+XKQt00DavoiQMa2NSCBNZMRK/jHP2FO1uzN0dL/s=; b=U9Ip7w2oTthto1pfJ3zYySHdSfzQlKOQeP+RKFNaVlwvlyAAVY8FoOG8grSDkB4gXi l6b4lFhVJXJj9OLka5skGhkhNJGHHb6tHQrAw06Mr13EMTOr6l+ow2/gQ/LurPCZpvDX /eu7kY6FJpd3W2t2d+geE1D2S4FxvLsrRwNrnS7brKQSlY+GhVuE+FnmVS522prC2ADp 6syfX7/toVHOsGsyUCnqay/9lQNEcrUnZLIDXctHFmNDB7007hhXEdVK72T8lXSjTA/n GYmjPgc0G61IhoMmOxIIfJmGn0Mi+xANNvuU4Sklyu6g3ANFHwLt7EzTSRw+5UphX2af h0ug== X-Gm-Message-State: ACrzQf1wz7HICxFnxwg+nUAq89rHZOcLTY444fbVgj/fWXX98u/WxPQZ kUFPYNd6w1NKcT0CRfJcmxxRn5Og5a0= X-Google-Smtp-Source: AMsMyM6BNretQuhpSGz0q1tuHHCRcRqY4m8yMK2pChzKktrDPkI/+GDnvFhSSArnytvFYJqI17XovA== X-Received: by 2002:a65:42c8:0:b0:41a:8138:f47f with SMTP id l8-20020a6542c8000000b0041a8138f47fmr25959879pgp.476.1664305226380; Tue, 27 Sep 2022 12:00:26 -0700 (PDT) Received: from mariner-vm.. ([131.107.1.181]) by smtp.gmail.com with ESMTPSA id mi9-20020a17090b4b4900b001f8aee0d826sm8737557pjb.53.2022.09.27.12.00.24 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 27 Sep 2022 12:00:25 -0700 (PDT) From: dthaler1968@googlemail.com To: bpf@vger.kernel.org Cc: Dave Thaler Subject: [PATCH 10/15] ebpf-docs: Add appendix of all opcodes in order Date: Tue, 27 Sep 2022 18:59:53 +0000 Message-Id: <20220927185958.14995-10-dthaler1968@googlemail.com> X-Mailer: git-send-email 2.33.4 In-Reply-To: <20220927185958.14995-1-dthaler1968@googlemail.com> References: <20220927185958.14995-1-dthaler1968@googlemail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Dave Thaler Signed-off-by: Dave Thaler --- Documentation/bpf/instruction-set.rst | 197 ++++++++++++++++++++++++++ 1 file changed, 197 insertions(+) diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst index 926957830..b6f098104 100644 --- a/Documentation/bpf/instruction-set.rst +++ b/Documentation/bpf/instruction-set.rst @@ -408,3 +408,200 @@ Legacy BPF Packet access instructions eBPF previously introduced special instructions for access to packet data that were carried over from classic BPF. However, these instructions are deprecated and should no longer be used. + +Appendix +======== + +For reference, the following table lists opcodes in order by value. + +====== === ==== =================================================== ======================================== +opcode src imm description reference +====== === ==== =================================================== ======================================== +0x00 0x0 any (additional immediate value) `64-bit immediate instructions`_ +0x04 0x0 any dst = (uint32_t)(dst + imm) `Arithmetic instructions`_ +0x05 0x0 0x00 goto +offset `Jump instructions`_ +0x07 0x0 any dst += imm `Arithmetic instructions`_ +0x0c any 0x00 dst = (uint32_t)(dst + src) `Arithmetic instructions`_ +0x0f any 0x00 dst += src `Arithmetic instructions`_ +0x14 0x0 any dst = (uint32_t)(dst - imm) `Arithmetic instructions`_ +0x15 0x0 any if dst == imm goto +offset `Jump instructions`_ +0x16 0x0 any if (uint32_t)dst == imm goto +offset `Jump instructions`_ +0x17 0x0 any dst -= imm `Arithmetic instructions`_ +0x18 0x0 any dst = imm64 `64-bit immediate instructions`_ +0x1c any 0x00 dst = (uint32_t)(dst - src) `Arithmetic instructions`_ +0x1d any 0x00 if dst == src goto +offset `Jump instructions`_ +0x1e any 0x00 if (uint32_t)dst == (uint32_t)src goto +offset `Jump instructions`_ +0x1f any 0x00 dst -= src `Arithmetic instructions`_ +0x20 any any (deprecated, implementation-specific) `Legacy BPF Packet access instructions`_ +0x24 0x0 any dst = (uint32_t)(dst \* imm) `Arithmetic instructions`_ +0x25 0x0 any if dst > imm goto +offset `Jump instructions`_ +0x26 0x0 any if (uint32_t)dst > imm goto +offset `Jump instructions`_ +0x27 0x0 any dst \*= imm `Arithmetic instructions`_ +0x28 any any (deprecated, implementation-specific) `Legacy BPF Packet access instructions`_ +0x2c any 0x00 dst = (uint32_t)(dst \* src) `Arithmetic instructions`_ +0x2d any 0x00 if dst > src goto +offset `Jump instructions`_ +0x2e any 0x00 if (uint32_t)dst > (uint32_t)src goto +offset `Jump instructions`_ +0x2f any 0x00 dst \*= src `Arithmetic instructions`_ +0x30 any any (deprecated, implementation-specific) `Legacy BPF Packet access instructions`_ +0x34 0x0 any dst = (uint32_t)((imm != 0) ? (dst / imm) : 0) `Arithmetic instructions`_ +0x35 0x0 any if dst >= imm goto +offset `Jump instructions`_ +0x36 0x0 any if (uint32_t)dst >= imm goto +offset `Jump instructions`_ +0x37 0x0 any dst = (imm != 0) ? (dst / imm) : 0 `Arithmetic instructions`_ +0x38 any any (deprecated, implementation-specific) `Legacy BPF Packet access instructions`_ +0x3c any 0x00 dst = (uint32_t)((imm != 0) ? (dst / src) : 0) `Arithmetic instructions`_ +0x3d any 0x00 if dst >= src goto +offset `Jump instructions`_ +0x3e any 0x00 if (uint32_t)dst >= (uint32_t)src goto +offset `Jump instructions`_ +0x3f any 0x00 dst = (src !+ 0) ? (dst / src) : 0 `Arithmetic instructions`_ +0x40 any any (deprecated, implementation-specific) `Legacy BPF Packet access instructions`_ +0x44 0x0 any dst = (uint32_t)(dst \| imm) `Arithmetic instructions`_ +0x45 0x0 any if dst & imm goto +offset `Jump instructions`_ +0x46 0x0 any if (uint32_t)dst & imm goto +offset `Jump instructions`_ +0x47 0x0 any dst \|= imm `Arithmetic instructions`_ +0x48 any any (deprecated, implementation-specific) `Legacy BPF Packet access instructions`_ +0x4c any 0x00 dst = (uint32_t)(dst \| src) `Arithmetic instructions`_ +0x4d any 0x00 if dst & src goto +offset `Jump instructions`_ +0x4e any 0x00 if (uint32_t)dst & (uint32_t)src goto +offset `Jump instructions`_ +0x4f any 0x00 dst \|= src `Arithmetic instructions`_ +0x50 any any (deprecated, implementation-specific) `Legacy BPF Packet access instructions`_ +0x54 0x0 any dst = (uint32_t)(dst & imm) `Arithmetic instructions`_ +0x55 0x0 any if dst != imm goto +offset `Jump instructions`_ +0x56 0x0 any if (uint32_t)dst != imm goto +offset `Jump instructions`_ +0x57 0x0 any dst &= imm `Arithmetic instructions`_ +0x58 any any (deprecated, implementation-specific) `Legacy BPF Packet access instructions`_ +0x5c any 0x00 dst = (uint32_t)(dst & src) `Arithmetic instructions`_ +0x5d any 0x00 if dst != src goto +offset `Jump instructions`_ +0x5e any 0x00 if (uint32_t)dst != (uint32_t)src goto +offset `Jump instructions`_ +0x5f any 0x00 dst &= src `Arithmetic instructions`_ +0x61 any 0x00 dst = \*(uint32_t \*)(src + offset) `Load and store instructions`_ +0x62 0x0 any \*(uint32_t \*)(dst + offset) = imm `Load and store instructions`_ +0x63 any 0x00 \*(uint32_t \*)(dst + offset) = src `Load and store instructions`_ +0x64 0x0 any dst = (uint32_t)(dst << imm) `Arithmetic instructions`_ +0x65 0x0 any if dst s> imm goto +offset `Jump instructions`_ +0x66 0x0 any if (int32_t)dst s> (int32_t)imm goto +offset `Jump instructions`_ +0x67 0x0 any dst <<= imm `Arithmetic instructions`_ +0x69 any 0x00 dst = \*(uint16_t \*)(src + offset) `Load and store instructions`_ +0x6a 0x0 any \*(uint16_t \*)(dst + offset) = imm `Load and store instructions`_ +0x6b any 0x00 \*(uint16_t \*)(dst + offset) = src `Load and store instructions`_ +0x6c any 0x00 dst = (uint32_t)(dst << src) `Arithmetic instructions`_ +0x6d any 0x00 if dst s> src goto +offset `Jump instructions`_ +0x6e any 0x00 if (int32_t)dst s> (int32_t)src goto +offset `Jump instructions`_ +0x6f any 0x00 dst <<= src `Arithmetic instructions`_ +0x71 any 0x00 dst = \*(uint8_t \*)(src + offset) `Load and store instructions`_ +0x72 0x0 any \*(uint8_t \*)(dst + offset) = imm `Load and store instructions`_ +0x73 any 0x00 \*(uint8_t \*)(dst + offset) = src `Load and store instructions`_ +0x74 0x0 any dst = (uint32_t)(dst >> imm) `Arithmetic instructions`_ +0x75 0x0 any if dst s>= imm goto +offset `Jump instructions`_ +0x76 0x0 any if (int32_t)dst s>= (int32_t)imm goto +offset `Jump instructions`_ +0x77 0x0 any dst >>= imm `Arithmetic instructions`_ +0x79 any 0x00 dst = \*(uint64_t \*)(src + offset) `Load and store instructions`_ +0x7a 0x0 any \*(uint64_t \*)(dst + offset) = imm `Load and store instructions`_ +0x7b any 0x00 \*(uint64_t \*)(dst + offset) = src `Load and store instructions`_ +0x7c any 0x00 dst = (uint32_t)(dst >> src) `Arithmetic instructions`_ +0x7d any 0x00 if dst s>= src goto +offset `Jump instructions`_ +0x7e any 0x00 if (int32_t)dst s>= (int32_t)src goto +offset `Jump instructions`_ +0x7f any 0x00 dst >>= src `Arithmetic instructions`_ +0x84 0x0 0x00 dst = (uint32_t)-dst `Arithmetic instructions`_ +0x85 0x0 any call helper function imm `Helper functions`_ +0x87 0x0 0x00 dst = -dst `Arithmetic instructions`_ +0x94 0x0 any dst = (uint32_t)((imm != 0) ? (dst % imm) : dst) `Arithmetic instructions`_ +0x95 0x0 0x00 return `Jump instructions`_ +0x97 0x0 any dst = (imm != 0) ? (dst % imm) : dst `Arithmetic instructions`_ +0x9c any 0x00 dst = (uint32_t)((src != 0) ? (dst % src) : dst) `Arithmetic instructions`_ +0x9f any 0x00 dst = (src != 0) ? (dst % src) : dst `Arithmetic instructions`_ +0xa4 0x0 any dst = (uint32_t)(dst ^ imm) `Arithmetic instructions`_ +0xa5 0x0 any if dst < imm goto +offset `Jump instructions`_ +0xa6 0x0 any if (uint32_t)dst < imm goto +offset `Jump instructions`_ +0xa7 0x0 any dst ^= imm `Arithmetic instructions`_ +0xac any 0x00 dst = (uint32_t)(dst ^ src) `Arithmetic instructions`_ +0xad any 0x00 if dst < src goto +offset `Jump instructions`_ +0xae any 0x00 if (uint32_t)dst < (uint32_t)src goto +offset `Jump instructions`_ +0xaf any 0x00 dst ^= src `Arithmetic instructions`_ +0xb4 0x0 any dst = (uint32_t) imm `Arithmetic instructions`_ +0xb5 0x0 any if dst <= imm goto +offset `Jump instructions`_ +0xa6 0x0 any if (uint32_t)dst <= imm goto +offset `Jump instructions`_ +0xb7 0x0 any dst = imm `Arithmetic instructions`_ +0xbc any 0x00 dst = (uint32_t) src `Arithmetic instructions`_ +0xbd any 0x00 if dst <= src goto +offset `Jump instructions`_ +0xbe any 0x00 if (uint32_t)dst <= (uint32_t)src goto +offset `Jump instructions`_ +0xbf any 0x00 dst = src `Arithmetic instructions`_ +0xc3 any 0x00 lock \*(uint32_t \*)(dst + offset) += src `Atomic operations`_ +0xc3 any 0x01 lock:: `Atomic operations`_ + + *(uint32_t *)(dst + offset) += src + src = *(uint32_t *)(dst + offset) +0xc3 any 0x40 \*(uint32_t \*)(dst + offset) \|= src `Atomic operations`_ +0xc3 any 0x41 lock:: `Atomic operations`_ + + *(uint32_t *)(dst + offset) |= src + src = *(uint32_t *)(dst + offset) +0xc3 any 0x50 \*(uint32_t \*)(dst + offset) &= src `Atomic operations`_ +0xc3 any 0x51 lock:: `Atomic operations`_ + + *(uint32_t *)(dst + offset) &= src + src = *(uint32_t *)(dst + offset) +0xc3 any 0xa0 \*(uint32_t \*)(dst + offset) ^= src `Atomic operations`_ +0xc3 any 0xa1 lock:: `Atomic operations`_ + + *(uint32_t *)(dst + offset) ^= src + src = *(uint32_t *)(dst + offset) +0xc3 any 0xe1 lock:: `Atomic operations`_ + + temp = *(uint32_t *)(dst + offset) + *(uint32_t *)(dst + offset) = src + src = temp +0xc3 any 0xf1 lock:: `Atomic operations`_ + + temp = *(uint32_t *)(dst + offset) + if *(uint32_t)(dst + offset) == R0 + *(uint32_t)(dst + offset) = src + R0 = temp +0xc4 0x0 any dst = (uint32_t)(dst s>> imm) `Arithmetic instructions`_ +0xc5 0x0 any if dst s< imm goto +offset `Jump instructions`_ +0xc6 0x0 any if (int32_t)dst s< (int32_t)imm goto +offset `Jump instructions`_ +0xc7 0x0 any dst s>>= imm `Arithmetic instructions`_ +0xcc any 0x00 dst = (uint32_t)(dst s>> src) `Arithmetic instructions`_ +0xcd any 0x00 if dst s< src goto +offset `Jump instructions`_ +0xce any 0x00 if (int32_t)dst s< (int32_t)src goto +offset `Jump instructions`_ +0xcf any 0x00 dst s>>= src `Arithmetic instructions`_ +0xd4 0x0 0x10 dst = htole16(dst) `Byte swap instructions`_ +0xd4 0x0 0x20 dst = htole32(dst) `Byte swap instructions`_ +0xd4 0x0 0x40 dst = htole64(dst) `Byte swap instructions`_ +0xd5 0x0 any if dst s<= imm goto +offset `Jump instructions`_ +0xd6 0x0 any if (int32_t)dst s<= (int32_t)imm goto +offset `Jump instructions`_ +0xdb any 0x00 lock \*(uint64_t \*)(dst + offset) += src `Atomic operations`_ +0xdb any 0x01 lock:: `Atomic operations`_ + + *(uint64_t *)(dst + offset) += src + src = *(uint64_t *)(dst + offset) +0xdb any 0x40 \*(uint64_t \*)(dst + offset) \|= src `Atomic operations`_ +0xdb any 0x41 lock:: `Atomic operations`_ + + *(uint64_t *)(dst + offset) |= src + lock src = *(uint64_t *)(dst + offset) +0xdb any 0x50 \*(uint64_t \*)(dst + offset) &= src `Atomic operations`_ +0xdb any 0x51 lock:: `Atomic operations`_ + + *(uint64_t *)(dst + offset) &= src + src = *(uint64_t *)(dst + offset) +0xdb any 0xa0 \*(uint64_t \*)(dst + offset) ^= src `Atomic operations`_ +0xdb any 0xa1 lock:: `Atomic operations`_ + + *(uint64_t *)(dst + offset) ^= src + src = *(uint64_t *)(dst + offset) +0xdb any 0xe1 lock:: `Atomic operations`_ + + temp = *(uint64_t *)(dst + offset) + *(uint64_t *)(dst + offset) = src + src = temp +0xdb any 0xf1 lock:: `Atomic operations`_ + + temp = *(uint64_t *)(dst + offset) + if *(uint64_t)(dst + offset) == R0 + *(uint64_t)(dst + offset) = src + R0 = temp +0xdc 0x0 0x10 dst = htobe16(dst) `Byte swap instructions`_ +0xdc 0x0 0x20 dst = htobe32(dst) `Byte swap instructions`_ +0xdc 0x0 0x40 dst = htobe64(dst) `Byte swap instructions`_ +0xdd any 0x00 if dst s<= src goto +offset `Jump instructions`_ +0xde any 0x00 if (int32_t)dst s<= (int32_t)src goto +offset `Jump instructions`_ +====== === ==== =================================================== ======================================== From patchwork Tue Sep 27 18:59:54 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Thaler X-Patchwork-Id: 12991127 X-Patchwork-Delegate: bpf@iogearbox.net Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id E1C2EC07E9D for ; Tue, 27 Sep 2022 19:01:00 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231880AbiI0TA7 (ORCPT ); Tue, 27 Sep 2022 15:00:59 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54678 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231666AbiI0TAr (ORCPT ); Tue, 27 Sep 2022 15:00:47 -0400 Received: from mail-pl1-x633.google.com (mail-pl1-x633.google.com [IPv6:2607:f8b0:4864:20::633]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id BDBA91BB20F for ; Tue, 27 Sep 2022 12:00:29 -0700 (PDT) Received: by mail-pl1-x633.google.com with SMTP id d11so9895710pll.8 for ; Tue, 27 Sep 2022 12:00:29 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlemail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date; bh=D9LaGrytoWd6kVpBouFet7qELPwaLytRzvtxPO5gDAM=; b=nYcMmuElMVbadBLaeXmyQ12CdEphsQSgAVdWwFw/LSyFN1ARewL9xFMuu3cDGBj8bn 9pMhOZ1IkSKtrQCw1098VHd3EbSESOxHPtY/Lxu8r4uapzliMV+NyQQUZ2fNyXZZ4ese HE7bh/NOS79Kg6RpnS29HwHatZy0NPfwe+UIi+pbAw0bjI6ipCnuf0/x6IArk27fJWkk oyyCql97RhgyV/dvZRNw44c9rvkGpXh+MA+5HXoFeSXvN57FiSgD7Vw4P3F7db1axYSB G3wl4qMMFwJkLYbhcP0i3dqJ12JklcSZlCaF6NiKsCXFgsNSCAl8h/02AfEdtDP1RWqv kqcQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; 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; bh=D9LaGrytoWd6kVpBouFet7qELPwaLytRzvtxPO5gDAM=; b=bRgn5h2m+OemwMAcIBiR1/6C+j+7qHkAxwey6BK1+m5ZVH3vJxEwQp/1VJmF/m4LcN QtUZqBYr0d7isjgOoLofqvu1N4n+6+WecEfKAeIqtl83QOvHMVyZejxZ9WqY9p/4JhvX 8PK2UKFtzVpCfk6TIb7ezsYKOfmqwW0xMOha2itwcE/E6XdIqFTzRhI6dRHhwDuATKV3 uEmtQPFS9JIytbPE05QGompGF89pGkvexDUZYRKAeZTdtoYcWr6wBOE9frMFUZ/xWPjI Ih+aeJgQTRKc8e46lsVtWP4iqenOEGKfH1FDNR4DOxp7sEG79azTYJnpdw10YyUIrCgr Ndag== X-Gm-Message-State: ACrzQf2IsyuzAAiYvPgjaSKQH3wjzNrpAKQ3DvEHeB+fXBtORwXMrlsh qJUlfWfTDEN1kwWUuL0NzCNsRIkGxSo= X-Google-Smtp-Source: AMsMyM5FK8sovL9Yn9kiJN85XR1G/uwE/UhzXU/JZzezs66MooiMC/aprfq5N34z6wVrg+2kX3ZUNQ== X-Received: by 2002:a17:902:d4cb:b0:178:6e81:35b7 with SMTP id o11-20020a170902d4cb00b001786e8135b7mr28927611plg.108.1664305227788; Tue, 27 Sep 2022 12:00:27 -0700 (PDT) Received: from mariner-vm.. ([131.107.1.181]) by smtp.gmail.com with ESMTPSA id mi9-20020a17090b4b4900b001f8aee0d826sm8737557pjb.53.2022.09.27.12.00.26 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 27 Sep 2022 12:00:27 -0700 (PDT) From: dthaler1968@googlemail.com To: bpf@vger.kernel.org Cc: Dave Thaler Subject: [PATCH 11/15] ebpf-docs: Improve English readability Date: Tue, 27 Sep 2022 18:59:54 +0000 Message-Id: <20220927185958.14995-11-dthaler1968@googlemail.com> X-Mailer: git-send-email 2.33.4 In-Reply-To: <20220927185958.14995-1-dthaler1968@googlemail.com> References: <20220927185958.14995-1-dthaler1968@googlemail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Dave Thaler Signed-off-by: Dave Thaler --- Documentation/bpf/instruction-set.rst | 137 ++++++++++++++++---------- 1 file changed, 87 insertions(+), 50 deletions(-) diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst index b6f098104..328207ff6 100644 --- a/Documentation/bpf/instruction-set.rst +++ b/Documentation/bpf/instruction-set.rst @@ -7,6 +7,9 @@ eBPF Instruction Set Specification, v1.0 This document specifies version 1.0 of the eBPF instruction set. +The eBPF instruction set consists of eleven 64 bit registers, a program counter, +and 512 bytes of stack space. + Documentation conventions ========================= @@ -25,12 +28,24 @@ The eBPF calling convention is defined as: * R6 - R9: callee saved registers that function calls will preserve * R10: read-only frame pointer to access stack -R0 - R5 are scratch registers and eBPF programs needs to spill/fill them if -necessary across calls. +Registers R0 - R5 are scratch registers, meaning the BPF program needs to either +spill them to the BPF stack or move them to callee saved registers if these +arguments are to be reused across multiple function calls. Spilling means +that the value in the register is moved to the BPF stack. The reverse operation +of moving the variable from the BPF stack to the register is called filling. +The reason for spilling/filling is due to the limited number of registers. + +Upon entering execution of an eBPF program, registers R1 - R5 initially can contain +the input arguments for the program (similar to the argc/argv pair for a typical C program). +The actual number of registers used, and their meaning, is defined by the program type; +for example, a networking program might have an argument that includes network packet data +and/or metadata. Instruction encoding ==================== +An eBPF program is a sequence of instructions. + eBPF has two instruction encodings: * the basic instruction encoding, which uses 64 bits to encode an instruction @@ -63,7 +78,7 @@ opcode operation to perform Note that most instructions do not use all of the fields. -Unused fields shall be cleared to zero. +Unused fields must be set to zero. As discussed below in `64-bit immediate instructions`_, some instructions use a 64-bit immediate value that is constructed as follows. @@ -90,7 +105,9 @@ and destination registers, respectively, rather than the register number. Instruction classes ------------------- -The three LSB bits of the 'opcode' field store the instruction class: +The encoding of the 'opcode' field varies and can be determined from +the three least significant bits (LSB) of the 'opcode' field which holds +the "instruction class", as follows: ========= ===== =============================== =================================== class value description reference @@ -136,9 +153,11 @@ instruction class Arithmetic instructions ----------------------- -``BPF_ALU`` uses 32-bit wide operands while ``BPF_ALU64`` uses 64-bit wide operands for +Instruction class ``BPF_ALU`` uses 32-bit wide operands (zeroing the upper 32 bits +of the destination register) while ``BPF_ALU64`` uses 64-bit wide operands for otherwise identical operations. -The 'code' field encodes the operation as below: + +The 4-bit 'code' field encodes the operation as follows: ======== ===== ========================================================== code value description @@ -168,21 +187,23 @@ the destination register is instead set to zero. If execution would result in modulo by zero, the destination register is instead left unchanged. -``BPF_ADD | BPF_X | BPF_ALU`` means:: +Examples: + +``BPF_ADD | BPF_X | BPF_ALU`` (0x0c) means:: dst = (uint32_t) (dst + src) where '(uint32_t)' indicates truncation to 32 bits. -``BPF_ADD | BPF_X | BPF_ALU64`` means:: +``BPF_ADD | BPF_X | BPF_ALU64`` (0x0f) means:: dst = dst + src -``BPF_XOR | BPF_K | BPF_ALU`` means:: +``BPF_XOR | BPF_K | BPF_ALU`` (0xa4) means:: src = (uint32_t) src ^ (uint32_t) imm -``BPF_XOR | BPF_K | BPF_ALU64`` means:: +``BPF_XOR | BPF_K | BPF_ALU64`` (0xa7) means:: src = src ^ imm @@ -204,8 +225,9 @@ The byte swap instructions use an instruction class of ``BPF_ALU`` and a 4-bit The byte swap instructions operate on the destination register only and do not use a separate source register or immediate value. -The 1-bit source operand field in the opcode is used to to select what byte -order the operation convert from or to: +Byte swap instructions use non-default semantics of the 1-bit 'source' field in +the 'opcode' field. Instead of indicating the source operator, it is instead +used to select what byte order the operation converts from or to: ========= ===== ================================================= source value description @@ -215,24 +237,33 @@ BPF_TO_BE 0x08 convert between host byte order and big endian ========= ===== ================================================= The 'imm' field encodes the width of the swap operations. The following widths -are supported: 16, 32 and 64. - -Examples: - -``BPF_ALU | BPF_TO_LE | BPF_END`` with imm = 16 means:: - - dst = htole16(dst) - -``BPF_ALU | BPF_TO_BE | BPF_END`` with imm = 64 means:: - - dst = htobe64(dst) +are supported: 16, 32 and 64. The following table summarizes the resulting +possibilities: + +============================= ========= === ======== ================== +opcode construction opcode imm mnemonic pseudocode +============================= ========= === ======== ================== +BPF_END | BPF_TO_LE | BPF_ALU 0xd4 16 le16 dst dst = htole16(dst) +BPF_END | BPF_TO_LE | BPF_ALU 0xd4 32 le32 dst dst = htole32(dst) +BPF_END | BPF_TO_LE | BPF_ALU 0xd4 64 le64 dst dst = htole64(dst) +BPF_END | BPF_TO_BE | BPF_ALU 0xdc 16 be16 dst dst = htobe16(dst) +BPF_END | BPF_TO_BE | BPF_ALU 0xdc 32 be32 dst dst = htobe32(dst) +BPF_END | BPF_TO_BE | BPF_ALU 0xdc 64 be64 dst dst = htobe64(dst) +============================= ========= === ======== ================== + +where + +* mnenomic indicates a short form that might be displayed by some tools such as disassemblers +* 'htoleNN()' indicates converting a NN-bit value from host byte order to little-endian byte order +* 'htobeNN()' indicates converting a NN-bit value from host byte order to big-endian byte order Jump instructions ----------------- -``BPF_JMP32`` uses 32-bit wide operands while ``BPF_JMP`` uses 64-bit wide operands for +Instruction class ``BPF_JMP32`` uses 32-bit wide operands while ``BPF_JMP`` uses 64-bit wide operands for otherwise identical operations. -The 'code' field encodes the operation as below: + +The 4-bit 'code' field encodes the operation as below, where PC is the program counter: ======== ===== ========================= ============ code value description notes @@ -253,9 +284,6 @@ BPF_JSLT 0xc0 PC += off if dst < src signed BPF_JSLE 0xd0 PC += off if dst <= src signed ======== ===== ========================= ============ -The eBPF program needs to store the return value into register R0 before doing a -BPF_EXIT. - Helper functions ~~~~~~~~~~~~~~~~ Helper functions are a concept whereby BPF programs can call into a @@ -285,7 +313,8 @@ For load and store instructions (``BPF_LD``, ``BPF_LDX``, ``BPF_ST``, and ``BPF_ mode size instruction class ============ ====== ================= -The mode modifier is one of: +mode + one of: ============= ===== ==================================== ============= mode modifier value description reference @@ -297,7 +326,8 @@ The mode modifier is one of: BPF_ATOMIC 0xc0 atomic operations `Atomic operations`_ ============= ===== ==================================== ============= -The size modifier is one of: +size + one of: ============= ===== ===================== size modifier value description @@ -308,25 +338,31 @@ The size modifier is one of: BPF_DW 0x18 double word (8 bytes) ============= ===== ===================== +instruction class + the instruction class (see `Instruction classes`_) + Regular load and store operations --------------------------------- The ``BPF_MEM`` mode modifier is used to encode regular load and store instructions that transfer data between a register and memory. -``BPF_MEM | | BPF_STX`` means:: - - *(size *) (dst + offset) = src_reg - -``BPF_MEM | | BPF_ST`` means:: - - *(size *) (dst + offset) = imm32 - -``BPF_MEM | | BPF_LDX`` means:: - - dst = *(size *) (src + offset) - -Where size is one of: ``BPF_B``, ``BPF_H``, ``BPF_W``, or ``BPF_DW``. +============================= ========= ==================================== +opcode construction opcode pseudocode +============================= ========= ==================================== +BPF_MEM | BPF_B | BPF_LDX 0x71 dst = \*(uint8_t \*) (src + offset) +BPF_MEM | BPF_H | BPF_LDX 0x69 dst = \*(uint16_t \*) (src + offset) +BPF_MEM | BPF_W | BPF_LDX 0x61 dst = \*(uint32_t \*) (src + offset) +BPF_MEM | BPF_DW | BPF_LDX 0x79 dst = \*(uint64_t \*) (src + offset) +BPF_MEM | BPF_B | BPF_ST 0x72 \*(uint8_t \*) (dst + offset) = imm +BPF_MEM | BPF_H | BPF_ST 0x6a \*(uint16_t \*) (dst + offset) = imm +BPF_MEM | BPF_W | BPF_ST 0x62 \*(uint32_t \*) (dst + offset) = imm +BPF_MEM | BPF_DW | BPF_ST 0x7a \*(uint64_t \*) (dst + offset) = imm +BPF_MEM | BPF_B | BPF_STX 0x73 \*(uint8_t \*) (dst + offset) = src +BPF_MEM | BPF_H | BPF_STX 0x6b \*(uint16_t \*) (dst + offset) = src +BPF_MEM | BPF_W | BPF_STX 0x63 \*(uint32_t \*) (dst + offset) = src +BPF_MEM | BPF_DW | BPF_STX 0x7b \*(uint64_t \*) (dst + offset) = src +============================= ========= ==================================== Atomic operations ----------------- @@ -338,9 +374,11 @@ by other eBPF programs or means outside of this specification. All atomic operations supported by eBPF are encoded as store operations that use the ``BPF_ATOMIC`` mode modifier as follows: -* ``BPF_ATOMIC | BPF_W | BPF_STX`` for 32-bit operations -* ``BPF_ATOMIC | BPF_DW | BPF_STX`` for 64-bit operations -* 8-bit and 16-bit wide atomic operations are not supported. +* ``BPF_ATOMIC | BPF_W | BPF_STX`` (0xc3) for 32-bit operations +* ``BPF_ATOMIC | BPF_DW | BPF_STX`` (0xdb) for 64-bit operations + +Note that 8-bit (``BPF_B``) and 16-bit (``BPF_H``) wide atomic operations are not supported, +nor is ``BPF_ATOMIC | | BPF_ST``. The 'imm' field is used to encode the actual atomic operation. Simple atomic operation use a subset of the values defined to encode @@ -355,16 +393,15 @@ BPF_AND 0x50 atomic and BPF_XOR 0xa0 atomic xor ======== ===== =========== - -``BPF_ATOMIC | BPF_W | BPF_STX`` with 'imm' = BPF_ADD means:: +``BPF_ATOMIC | BPF_W | BPF_STX`` (0xc3) with 'imm' = BPF_ADD means:: *(uint32_t *)(dst + offset) += src -``BPF_ATOMIC | BPF_DW | BPF_STX`` with 'imm' = BPF ADD means:: +``BPF_ATOMIC | BPF_DW | BPF_STX`` (0xdb) with 'imm' = BPF ADD means:: *(uint64_t *)(dst + offset) += src -In addition to the simple atomic operations, there also is a modifier and +In addition to the simple atomic operations above, there also is a modifier and two complex atomic operations: =========== ================ =========================== From patchwork Tue Sep 27 18:59:55 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Thaler X-Patchwork-Id: 12991123 X-Patchwork-Delegate: bpf@iogearbox.net Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id E1898C07E9D for ; Tue, 27 Sep 2022 19:00:55 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231784AbiI0TAy (ORCPT ); Tue, 27 Sep 2022 15:00:54 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:53622 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231563AbiI0TAo (ORCPT ); Tue, 27 Sep 2022 15:00:44 -0400 Received: from mail-pj1-x1034.google.com (mail-pj1-x1034.google.com [IPv6:2607:f8b0:4864:20::1034]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 11A68161CC1 for ; Tue, 27 Sep 2022 12:00:30 -0700 (PDT) Received: by mail-pj1-x1034.google.com with SMTP id i15-20020a17090a4b8f00b0020073b4ac27so10887170pjh.3 for ; Tue, 27 Sep 2022 12:00:30 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlemail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date; bh=1IK9f71Lu9DwK4AC/QfvBLYh1EUy09UxmzY/Y/A+poE=; b=hPZ8uChI5QK5l0A+yP+dFDX4k+8nkDCkWY6v1TzPw6f/DKz2o9+gv8Iku4f0vvLs16 HG+VhTt68vDbg2rMarOv0IJ83G6+Pu9WSWr/8feecDc06FNB65yPJL0J3mz/L4Yg84ES ZNQzkXF2UpBDpzOxjnfxbMcqSv+pFZD53JQuL0ytn2O8Hyg/Da9RbN9TFUigLkB2+t3o 4u8NS7yT72oexkyLdIwRhq15N9lx8tUj0W+/rYdwMFtnK7LVSoufDaJQrzu0K33lDP77 /fjb6DfYZqre5WnKt/WC8Dvp2PUZRIWb6SY/0CbLbG6pONxJ3cKIgXNAxkS1zuZGXioO Dfaw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; 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; bh=1IK9f71Lu9DwK4AC/QfvBLYh1EUy09UxmzY/Y/A+poE=; b=vgnKPiOhIKzHhoyeEjisHg47wLfI3IB8HuQoR1iFXQSKjvD3o+T5wrOguga7fbChSG q8iGIn6jGjPl1gUMEqwhdYrJOBBJEMbRxj9g8u+q0k8JWPTiSaxBG4uw+C2zlilVofOD TuPI+QMwei6kSxPapOxQ7z0VkWPJWBqugNFFaRcEERhLZkzZANJTTzNYqrMgf3Cc8kh5 IeDmPJJGHd+UwnAGSAHHF74dsrP6rTtYFl68YAeT6fl7DGKjGXDib6MxAuQaP8+HOqex 3eRuBblH47kiryBzakE/AjZrW/znrBXWOKu0wUvcWvIKId6obp9f7Z3ic6R47l8tRWIs tKeA== X-Gm-Message-State: ACrzQf3CA32dNKqHeancBwIjESzXgKUqo68nmNzaGeiutAAORvQGhQ2K U/UUMa7bxvxoLr1pUW3xzCcNSGN4N64= X-Google-Smtp-Source: AMsMyM4yfPAKnDypkFN7w+FAhRAhhZY9T5gme1lLgR+o9ia7DtK4kxebob0rinByd1CQzLJ0Aztoow== X-Received: by 2002:a17:902:7ed6:b0:178:378a:ebbf with SMTP id p22-20020a1709027ed600b00178378aebbfmr28827436plb.117.1664305228957; Tue, 27 Sep 2022 12:00:28 -0700 (PDT) Received: from mariner-vm.. ([131.107.1.181]) by smtp.gmail.com with ESMTPSA id mi9-20020a17090b4b4900b001f8aee0d826sm8737557pjb.53.2022.09.27.12.00.27 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 27 Sep 2022 12:00:28 -0700 (PDT) From: dthaler1968@googlemail.com To: bpf@vger.kernel.org Cc: Dave Thaler Subject: [PATCH 12/15] ebpf-docs: Add Linux note about register calling convention Date: Tue, 27 Sep 2022 18:59:55 +0000 Message-Id: <20220927185958.14995-12-dthaler1968@googlemail.com> X-Mailer: git-send-email 2.33.4 In-Reply-To: <20220927185958.14995-1-dthaler1968@googlemail.com> References: <20220927185958.14995-1-dthaler1968@googlemail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Dave Thaler Signed-off-by: Dave Thaler --- Documentation/bpf/linux-notes.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Documentation/bpf/linux-notes.rst b/Documentation/bpf/linux-notes.rst index 522ebe27d..0581ba326 100644 --- a/Documentation/bpf/linux-notes.rst +++ b/Documentation/bpf/linux-notes.rst @@ -7,6 +7,12 @@ Linux implementation notes This document provides more details specific to the Linux kernel implementation of the eBPF instruction set. +Registers and calling convention +================================ + +All program types only use R1 which contains the "context", which is typically a structure containing all +the inputs needed, and the exit value for eBPF programs is passed as a 32 bit value. + Arithmetic instructions ======================= From patchwork Tue Sep 27 18:59:56 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Thaler X-Patchwork-Id: 12991126 X-Patchwork-Delegate: bpf@iogearbox.net Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id DEB31C6FA82 for ; Tue, 27 Sep 2022 19:00:59 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231669AbiI0TA5 (ORCPT ); Tue, 27 Sep 2022 15:00:57 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54546 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231627AbiI0TAo (ORCPT ); Tue, 27 Sep 2022 15:00:44 -0400 Received: from mail-pl1-x634.google.com (mail-pl1-x634.google.com [IPv6:2607:f8b0:4864:20::634]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 9AA961BEA79 for ; Tue, 27 Sep 2022 12:00:31 -0700 (PDT) Received: by mail-pl1-x634.google.com with SMTP id d11so9895790pll.8 for ; Tue, 27 Sep 2022 12:00:31 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlemail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date; bh=g7dKqq8ieDPDu8THRlVWwhDbW+P/kY6bJ0OccIy1imM=; b=INMP68CyAxO0YCFoT54yNnMi+M5KW+TWkDOvvYdN/nieXgT2g2+z3BKBCYbw78UK82 /Gn/rxHLSAT22QqC0h9Oor7Z0e2TQfbOhL34eoHL+Ynk0dcCKa+ZJfbss9OX2o5xmxGk O/HlUg8yxCdKHS8MSYqz/xxC66NXrEkvG9iHKDlRonZ2Y6V9lqwdE/e1yH3z/xqFb9Wf OGTzxNYIbpZ1XVjeV1BjXzzJBUKsOlCIvshOcprwfcy8Jg/ykJRAkG2WMhdP8GBui/JA z6wK+EyfA+PrRkRmdJR+tAFYJnj2pFTHzUmaJje6uaL0TJuTQv4rz+EjoSjf1Dc6B0a9 qlzQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; 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; bh=g7dKqq8ieDPDu8THRlVWwhDbW+P/kY6bJ0OccIy1imM=; b=Qsy1MsYNay6xwzcrSO1GhIaWsLpgLBGCrVUplTUYvDqmSWTNsKJ438+zDC7n5wEvUz knnGeCzps2NLzTjAVx9KKVP9V0bYWVjpis+iibj1R36uGedNKNlrdzgYaBh2c0ZQy1rP MUWuljbyedyPHDJfElEYQiUi0SMbN34hb7q9mYgIhf+0KZQ7UVymaEqIQKC+7HPcGiW8 ABYIw6Vdwgyut0ZwSXBv5Io32fI15n2VDUs1VbLS+8IiL+H6tt8CM+X75VLLWyf6urES 3kIkHNAvooFIcUWVJQU7UkK+m7+LGertawf8nU6qdTpoGNvNS80KZyWi0vICKgN8XqcX EBXQ== X-Gm-Message-State: ACrzQf1IqIfg+gNEJoNZpLjuHe09I0IB4pNQG5Czg30xPe9gyAGtublo lOkfEtsm2A/tbigyM+Y+rCIrrcN7Eto= X-Google-Smtp-Source: AMsMyM4n0NaT8JpJuFY/QPaHvxMKgavwypnkaMmOoPR32qTMqAWd6N9UPUt0cJInTDjvdEjWGJ0aZQ== X-Received: by 2002:a17:902:e883:b0:177:f38f:6498 with SMTP id w3-20020a170902e88300b00177f38f6498mr27831948plg.32.1664305230251; Tue, 27 Sep 2022 12:00:30 -0700 (PDT) Received: from mariner-vm.. ([131.107.1.181]) by smtp.gmail.com with ESMTPSA id mi9-20020a17090b4b4900b001f8aee0d826sm8737557pjb.53.2022.09.27.12.00.29 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 27 Sep 2022 12:00:29 -0700 (PDT) From: dthaler1968@googlemail.com To: bpf@vger.kernel.org Cc: Dave Thaler Subject: [PATCH 13/15] ebpf-docs: Add extended 64-bit immediate instructions Date: Tue, 27 Sep 2022 18:59:56 +0000 Message-Id: <20220927185958.14995-13-dthaler1968@googlemail.com> X-Mailer: git-send-email 2.33.4 In-Reply-To: <20220927185958.14995-1-dthaler1968@googlemail.com> References: <20220927185958.14995-1-dthaler1968@googlemail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Dave Thaler Signed-off-by: Dave Thaler --- Documentation/bpf/instruction-set.rst | 54 +++++++++++++++++++++++++-- Documentation/bpf/linux-notes.rst | 10 +++++ 2 files changed, 60 insertions(+), 4 deletions(-) diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst index 328207ff6..667d97715 100644 --- a/Documentation/bpf/instruction-set.rst +++ b/Documentation/bpf/instruction-set.rst @@ -430,14 +430,54 @@ and loaded back to ``R0``. ----------------------------- Instructions with the ``BPF_IMM`` 'mode' modifier use the wide instruction -encoding for an extra imm64 value. +encoding defined in `Instruction encoding`_, and use the 'src' field of the +basic instruction to hold an opcode subtype. + +The following instructions are defined, and use additional concepts defined below: + +========================= ====== === ===================================== =========== ============== +opcode construction opcode src pseudocode imm type dst type +========================= ====== === ===================================== =========== ============== +BPF_IMM | BPF_DW | BPF_LD 0x18 0x0 dst = imm64 integer integer +BPF_IMM | BPF_DW | BPF_LD 0x18 0x1 dst = map_by_fd(imm) map fd map +BPF_IMM | BPF_DW | BPF_LD 0x18 0x2 dst = mva(map_by_fd(imm)) + next_imm map fd data pointer +BPF_IMM | BPF_DW | BPF_LD 0x18 0x3 dst = variable_addr(imm) variable id data pointer +BPF_IMM | BPF_DW | BPF_LD 0x18 0x4 dst = code_addr(imm) integer code pointer +BPF_IMM | BPF_DW | BPF_LD 0x18 0x5 dst = map_by_idx(imm) map index map +BPF_IMM | BPF_DW | BPF_LD 0x18 0x6 dst = mva(map_by_idx(imm)) + next_imm map index data pointer +========================= ====== === ===================================== =========== ============== -There is currently only one such instruction. +where + +* map_by_fd(fd) means to convert a 32-bit POSIX file descriptor into an address of a map object (see `Map objects`_) +* map_by_index(index) means to convert a 32-bit index into an address of a map object +* mva(map) gets the address of the first value in a given map object +* variable_addr(id) gets the address of a variable (see `Variables`_) with a given id +* code_addr(offset) gets the address of the instruction at a specified relative offset in units of 64-bit blocks +* the 'imm type' can be used by disassemblers for display +* the 'dst type' can be used for verification and JIT compilation purposes + +Map objects +~~~~~~~~~~~ + +Maps are shared memory regions accessible by eBPF programs on some platforms, where we use the term "map object" +to refer to an object containing the data and metadata (e.g., size) about the memory region. +A map can have various semantics as defined in a separate document, and may or may not have a single +contiguous memory region, but the 'mva(map)' is currently only defined for maps that do have a single +contiguous memory region. Support for maps is optional. -``BPF_LD | BPF_DW | BPF_IMM`` means:: +Each map object can have a POSIX file descriptor (fd) if supported by the platform, +where 'map_by_fd(fd)' means to get the map with the specified file descriptor. +Each eBPF program can also be defined to use a set of maps associated with the program +at load time, and 'map_by_index(index)' means to get the map with the given index in the set +associated with the eBPF program containing the instruction. - dst = imm64 +Variables +~~~~~~~~~ +Variables are memory regions, identified by integer ids, accessible by eBPF programs on +some platforms. The 'variable_addr(id)' operation means to get the address of the memory region +identified by the given id. Support for such variables is optional. Legacy BPF Packet access instructions ------------------------------------- @@ -465,6 +505,12 @@ opcode src imm description referenc 0x16 0x0 any if (uint32_t)dst == imm goto +offset `Jump instructions`_ 0x17 0x0 any dst -= imm `Arithmetic instructions`_ 0x18 0x0 any dst = imm64 `64-bit immediate instructions`_ +0x18 0x1 any dst = map_by_fd(imm) `64-bit immediate instructions`_ +0x18 0x2 any dst = mva(map_by_fd(imm)) + next_imm `64-bit immediate instructions`_ +0x18 0x3 any dst = variable_addr(imm) `64-bit immediate instructions`_ +0x18 0x4 any dst = code_addr(imm) `64-bit immediate instructions`_ +0x18 0x5 any dst = map_by_idx(imm) `64-bit immediate instructions`_ +0x18 0x6 any dst = mva(map_by_idx(imm)) + next_imm `64-bit immediate instructions`_ 0x1c any 0x00 dst = (uint32_t)(dst - src) `Arithmetic instructions`_ 0x1d any 0x00 if dst == src goto +offset `Jump instructions`_ 0x1e any 0x00 if (uint32_t)dst == (uint32_t)src goto +offset `Jump instructions`_ diff --git a/Documentation/bpf/linux-notes.rst b/Documentation/bpf/linux-notes.rst index 0581ba326..e7f79242c 100644 --- a/Documentation/bpf/linux-notes.rst +++ b/Documentation/bpf/linux-notes.rst @@ -24,6 +24,16 @@ Byte swap instructions ``BPF_FROM_LE`` and ``BPF_FROM_BE`` exist as aliases for ``BPF_TO_LE`` and ``BPF_TO_BE`` respectively. +Map objects +=========== + +Linux only supports the 'mva(map)' operation on array maps with a single element. + +Variables +========= + +Linux uses BTF ids to identify variables. + Legacy BPF Packet access instructions ===================================== From patchwork Tue Sep 27 18:59:57 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Thaler X-Patchwork-Id: 12991125 X-Patchwork-Delegate: bpf@iogearbox.net Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 84E2CC07E9D for ; Tue, 27 Sep 2022 19:00:58 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231628AbiI0TA4 (ORCPT ); Tue, 27 Sep 2022 15:00:56 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:53658 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231654AbiI0TAq (ORCPT ); Tue, 27 Sep 2022 15:00:46 -0400 Received: from mail-pl1-x632.google.com (mail-pl1-x632.google.com [IPv6:2607:f8b0:4864:20::632]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 729CC16F9DF for ; Tue, 27 Sep 2022 12:00:32 -0700 (PDT) Received: by mail-pl1-x632.google.com with SMTP id n7so1169920plp.1 for ; Tue, 27 Sep 2022 12:00:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlemail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date; bh=nEjrRcPm35cMRZBlAK+IjKnNfortptsF04fReDevXm4=; b=BGpGHz/A9P27RBk4VVnWThE/hMbTUkLNtSBHXmDhTUTx7hngbL/nr9RcNgm+FteFkd vSEnpXXMurpPemO6RKNDUJGKCnfORmrr0mTRGnS46/YxYyWAZgLEtcYtLQ2J2WZAUjhj tv+jb0heIHAyD+MeXYnOm2/8USuGHl2sRAlM8rDo12s6P4xlUv8wuZMJpkdxECquB3Rw UhVhxBRyRMvaGI5l15aFsf8yItRS/psqzYu/tV9hRlGQlyqGnHcKMwoA/lqMvqeSfWkC XCWDCDbrDiSXi6VMEV/5mPgQqH9LNlb/iSXf/g9LNDyCT8e/5qhi8/zt7b3fdpkezwYV sr0g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; 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; bh=nEjrRcPm35cMRZBlAK+IjKnNfortptsF04fReDevXm4=; b=6STtTY99OvyFTAcxh8WSSQtRJZIkEKjM4wpKAhyP/rSemduilBEAzIGwJ5TC91D/eq gcHlztRHy3tDo/jGJXdh76idU67M8f9cqAeIQeFKSzSbHxO8c2pHDZtQgi6DJ0UoILWi gpVJbyAud3vLtWZsYqRX3u827aJAmaNO7IJsAT33nDYDNAw9ty/YOkg39+WZ58mFx/gh odLJeqzh3x71JhPZJHszvGnMLp1P/a8+pHHS1BuhxuVgN7lvUUjlJ0lFLxko1ymPyTCJ TwBh1/4oA0/8+0Sgly601wqs1vXKLGzxzPBmrLYVgScUmZsv6jcSJa/dFTmjDQxy8yFU dGdQ== X-Gm-Message-State: ACrzQf3CJHOju5ZwtAq01A/ZZhTa2ekvquU/TRwdAcfM+qJBN5X6l6UN dJvK8zBbERDyBU7kqax3EkRouQWBWUU= X-Google-Smtp-Source: AMsMyM7mW2kDdn10sphoHc1vqzenRI9O39ohJ4Ske+AgHr21qCAmuaUvWYMgSPG/qWX7DPnZXZlPfQ== X-Received: by 2002:a17:902:b089:b0:178:54cf:d692 with SMTP id p9-20020a170902b08900b0017854cfd692mr28093948plr.1.1664305231194; Tue, 27 Sep 2022 12:00:31 -0700 (PDT) Received: from mariner-vm.. ([131.107.1.181]) by smtp.gmail.com with ESMTPSA id mi9-20020a17090b4b4900b001f8aee0d826sm8737557pjb.53.2022.09.27.12.00.30 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 27 Sep 2022 12:00:30 -0700 (PDT) From: dthaler1968@googlemail.com To: bpf@vger.kernel.org Cc: Dave Thaler Subject: [PATCH 14/15] ebpf-docs: Add extended call instructions Date: Tue, 27 Sep 2022 18:59:57 +0000 Message-Id: <20220927185958.14995-14-dthaler1968@googlemail.com> X-Mailer: git-send-email 2.33.4 In-Reply-To: <20220927185958.14995-1-dthaler1968@googlemail.com> References: <20220927185958.14995-1-dthaler1968@googlemail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Dave Thaler Signed-off-by: Dave Thaler --- Documentation/bpf/instruction-set.rst | 52 +++++++++++++++++---------- 1 file changed, 34 insertions(+), 18 deletions(-) diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst index 667d97715..2ac8f0dae 100644 --- a/Documentation/bpf/instruction-set.rst +++ b/Documentation/bpf/instruction-set.rst @@ -265,24 +265,26 @@ otherwise identical operations. The 4-bit 'code' field encodes the operation as below, where PC is the program counter: -======== ===== ========================= ============ -code value description notes -======== ===== ========================= ============ -BPF_JA 0x00 PC += off BPF_JMP only -BPF_JEQ 0x10 PC += off if dst == src -BPF_JGT 0x20 PC += off if dst > src unsigned -BPF_JGE 0x30 PC += off if dst >= src unsigned -BPF_JSET 0x40 PC += off if dst & src -BPF_JNE 0x50 PC += off if dst != src -BPF_JSGT 0x60 PC += off if dst > src signed -BPF_JSGE 0x70 PC += off if dst >= src signed -BPF_CALL 0x80 function call see `Helper functions`_ -BPF_EXIT 0x90 function / program return BPF_JMP only -BPF_JLT 0xa0 PC += off if dst < src unsigned -BPF_JLE 0xb0 PC += off if dst <= src unsigned -BPF_JSLT 0xc0 PC += off if dst < src signed -BPF_JSLE 0xd0 PC += off if dst <= src signed -======== ===== ========================= ============ +======== ===== === ========================== ======================== +code value src description notes +======== ===== === ========================== ======================== +BPF_JA 0x0 0x0 PC += offset BPF_JMP only +BPF_JEQ 0x1 any PC += offset if dst == src +BPF_JGT 0x2 any PC += offset if dst > src unsigned +BPF_JGE 0x3 any PC += offset if dst >= src unsigned +BPF_JSET 0x4 any PC += offset if dst & src +BPF_JNE 0x5 any PC += offset if dst != src +BPF_JSGT 0x6 any PC += offset if dst > src signed +BPF_JSGE 0x7 any PC += offset if dst >= src signed +BPF_CALL 0x8 0x0 call helper function imm see `Helper functions`_ +BPF_CALL 0x8 0x1 call PC += offset see `eBPF functions`_ +BPF_CALL 0x8 0x2 call runtime function imm see `Runtime functions`_ +BPF_EXIT 0x9 0x0 return BPF_JMP only +BPF_JLT 0xa any PC += offset if dst < src unsigned +BPF_JLE 0xb any PC += offset if dst <= src unsigned +BPF_JSLT 0xc any PC += offset if dst < src signed +BPF_JSLE 0xd any PC += offset if dst <= src signed +======== ===== === ========================== ======================== Helper functions ~~~~~~~~~~~~~~~~ @@ -301,6 +303,18 @@ with the remaining registers being ignored. The definition of a helper function is responsible for specifying the type (e.g., integer, pointer, etc.) of the value returned, the number of arguments, and the type of each argument. +Runtime functions +~~~~~~~~~~~~~~~~~ +Runtime functions are like helper functions except that they are not specific +to eBPF programs. They use a different numbering space from helper functions, +but otherwise the same considerations apply. + +eBPF functions +~~~~~~~~~~~~~~ +eBPF functions are functions exposed by the same eBPF program as the caller, +and are referenced by offset from the call instruction, similar to ``BPF_JA``. +A ``BPF_EXIT`` within the eBPF function will return to the caller. + Load and store instructions =========================== @@ -585,6 +599,8 @@ opcode src imm description referenc 0x7f any 0x00 dst >>= src `Arithmetic instructions`_ 0x84 0x0 0x00 dst = (uint32_t)-dst `Arithmetic instructions`_ 0x85 0x0 any call helper function imm `Helper functions`_ +0x85 0x1 any call PC += offset `eBPF functions`_ +0x85 0x2 any call runtime function imm `Runtime functions`_ 0x87 0x0 0x00 dst = -dst `Arithmetic instructions`_ 0x94 0x0 any dst = (uint32_t)((imm != 0) ? (dst % imm) : dst) `Arithmetic instructions`_ 0x95 0x0 0x00 return `Jump instructions`_ From patchwork Tue Sep 27 18:59:58 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Thaler X-Patchwork-Id: 12991124 X-Patchwork-Delegate: bpf@iogearbox.net Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 64EE3C6FA83 for ; Tue, 27 Sep 2022 19:00:57 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231831AbiI0TAz (ORCPT ); Tue, 27 Sep 2022 15:00:55 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54610 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231659AbiI0TAq (ORCPT ); Tue, 27 Sep 2022 15:00:46 -0400 Received: from mail-pg1-x536.google.com (mail-pg1-x536.google.com [IPv6:2607:f8b0:4864:20::536]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id EBA581BF0D6 for ; Tue, 27 Sep 2022 12:00:32 -0700 (PDT) Received: by mail-pg1-x536.google.com with SMTP id bh13so10227003pgb.4 for ; Tue, 27 Sep 2022 12:00:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlemail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date; bh=gajT+qZhqxOHyN30cJ1Tk/WUWyKoP1GuuIXodlFuV/s=; b=LTHZomXONDXGYFZIQzJorvySYU4L1C/V/OSqnvRWuOS8URws2bgDo7VEaVr72zFlvb YUnKf+3Kuatn01uSeoqU2243U6lV3o/adLwNT9Lds7Nd6/hhW5WuSyQ+HGniTUKX+UGI MxwML1W0OqTnWUcXJswPOlUbIeYDMKpJTZf5yj4y+LLuJuAp2nRfdHOq9MQNncxRSJ2X nJVQ1L3tca5nYSxwTTRa5ACs5bUFPgn9V3UDjSA6jFZ4dzJC+NWBojkXQVZ3rHb5/6Aq LPMUbjsegQnzN7mesya4qs1DKuVpyKG4i2/jNFYnoDtgXvqXwmSNOG7cA+21ua1gPnkO ZdFQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; 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; bh=gajT+qZhqxOHyN30cJ1Tk/WUWyKoP1GuuIXodlFuV/s=; b=eW/3Yk2Ada9SluHmPXGjRfJucMHMDfaxAiKQduJTc1l3Ztje3bDigF4eUon7ShUz/y Gzb5xCjlkJogrb8QWAz9cgv7a50yE1R+zucY9vl+FQqPZPjwNlpYelyTRwMqjjOxQFaq S0tHzw2s5vFZgFS2arF2e64JIev4T1tb4f1zpjrLOLwNdcntVbyVvwclagWX1brEXy+G HcrPzoiOnclfV8TfYYRTLtGPBwoOSOUyAel1tJ9D8HRUhYfkf2Xi3Q/K2Sf97ga61VEo HkRcWbPZjDGCp5jKwq5CqLmunzxXbxL9XHzp4F2gvleH/7MqVjlqB0I7spkWhuOzL1W9 tsSQ== X-Gm-Message-State: ACrzQf33A8z/GUr3GPEq3zMh+IiMwbF1Vw4za5dMyllJ6kTgprMdii5S frMX4GQwcr81MMw/el3jSuC8lqnjiY4= X-Google-Smtp-Source: AMsMyM7ZpqLd8FDEZMczpfwsrP9CLTRyyE9/CbnfhrVaTS561LJmN4ax4743q+FyOd9751bhYLn1Nw== X-Received: by 2002:a65:6e89:0:b0:43c:e3d8:49f1 with SMTP id bm9-20020a656e89000000b0043ce3d849f1mr6036597pgb.315.1664305232101; Tue, 27 Sep 2022 12:00:32 -0700 (PDT) Received: from mariner-vm.. ([131.107.1.181]) by smtp.gmail.com with ESMTPSA id mi9-20020a17090b4b4900b001f8aee0d826sm8737557pjb.53.2022.09.27.12.00.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 27 Sep 2022 12:00:31 -0700 (PDT) From: dthaler1968@googlemail.com To: bpf@vger.kernel.org Cc: Dave Thaler Subject: [PATCH 15/15] ebpf-docs: Add note about invalid instruction Date: Tue, 27 Sep 2022 18:59:58 +0000 Message-Id: <20220927185958.14995-15-dthaler1968@googlemail.com> X-Mailer: git-send-email 2.33.4 In-Reply-To: <20220927185958.14995-1-dthaler1968@googlemail.com> References: <20220927185958.14995-1-dthaler1968@googlemail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net From: Dave Thaler Signed-off-by: Dave Thaler --- Documentation/bpf/clang-notes.rst | 5 +++++ Documentation/bpf/instruction-set.rst | 3 +++ 2 files changed, 8 insertions(+) diff --git a/Documentation/bpf/clang-notes.rst b/Documentation/bpf/clang-notes.rst index 528feddf2..3c934421b 100644 --- a/Documentation/bpf/clang-notes.rst +++ b/Documentation/bpf/clang-notes.rst @@ -20,6 +20,11 @@ Arithmetic instructions For CPU versions prior to 3, Clang v7.0 and later can enable ``BPF_ALU`` support with ``-Xclang -target-feature -Xclang +alu32``. In CPU version 3, support is automatically included. +Invalid instructions +==================== + +Clang will generate the invalid ``BPF_CALL | BPF_X | BPF_JMP`` (0x8d) instruction if ``-O0`` is used. + Atomic operations ================= diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst index 2ac8f0dae..af9dc0cc6 100644 --- a/Documentation/bpf/instruction-set.rst +++ b/Documentation/bpf/instruction-set.rst @@ -303,6 +303,9 @@ with the remaining registers being ignored. The definition of a helper function is responsible for specifying the type (e.g., integer, pointer, etc.) of the value returned, the number of arguments, and the type of each argument. +Note that ``BPF_CALL | BPF_X | BPF_JMP`` (0x8d), where the helper function integer +would be read from a specified register, is not currently permitted. + Runtime functions ~~~~~~~~~~~~~~~~~ Runtime functions are like helper functions except that they are not specific