From patchwork Mon Jan 31 18:36:34 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Christoph Hellwig X-Patchwork-Id: 12731017 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 A5EA4C4167E for ; Mon, 31 Jan 2022 18:36:56 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1356129AbiAaSgz (ORCPT ); Mon, 31 Jan 2022 13:36:55 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:38002 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1350681AbiAaSgw (ORCPT ); Mon, 31 Jan 2022 13:36:52 -0500 Received: from bombadil.infradead.org (bombadil.infradead.org [IPv6:2607:7c80:54:e::133]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 9CDA9C061714; Mon, 31 Jan 2022 10:36:52 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20210309; h=Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From:Sender :Reply-To:Content-Type:Content-ID:Content-Description; bh=zPUoEqmJ2GXL60y/CrvtI2zBNZa+ALtNejAU2/BtqYs=; b=xLwaKZ+xr7dQLjswBRPgcqIGES FJpEqDzxGsYoOmK5oIBA1qsUmbmiDxipWL5jgNKzFetEEnG/Ty/K8OVd9nEJq8z3yoyQ6R+nVW63M zh+lApHe22pGlYgrtPRXstIbwjHMrtLZP6mvW+WOZnZIzsU1zx4h+XJierw8HIZ4zfVi5xgnER9TY efgSe1UtyWGf84RXuVSIuhQZJt9+QlVp8umHgD7LCilodAyqozgganDhiXBepylxAs8/Y0KNtDXHb wpIZeE0oNXgN+Q5S70BJFnKHZ63YlbGj3Tow5vPHP4uGod1/QYZ3sAenXrhzCQ3aMWjKHlDD9V64F j3M1xg7g==; Received: from [2001:4bb8:191:327d:83ae:cf0e:db3c:eb79] (helo=localhost) by bombadil.infradead.org with esmtpsa (Exim 4.94.2 #2 (Red Hat Linux)) id 1nEbXg-00AOrb-E8; Mon, 31 Jan 2022 18:36:45 +0000 From: Christoph Hellwig To: Jonathan Corbet , Alexei Starovoitov , Daniel Borkmann , Andrii Nakryiko Cc: Martin KaFai Lau , Song Liu , Yonghong Song , John Fastabend , KP Singh , linux-doc@vger.kernel.org, netdev@vger.kernel.org, bpf@vger.kernel.org Subject: [PATCH 1/5] bpf, docs: Document the byte swapping instructions Date: Mon, 31 Jan 2022 19:36:34 +0100 Message-Id: <20220131183638.3934982-2-hch@lst.de> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20220131183638.3934982-1-hch@lst.de> References: <20220131183638.3934982-1-hch@lst.de> MIME-Version: 1.0 X-SRS-Rewrite: SMTP reverse-path rewritten from by bombadil.infradead.org. See http://www.infradead.org/rpr.html Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net Add a section to document the byte swapping instructions. Signed-off-by: Christoph Hellwig --- Documentation/bpf/instruction-set.rst | 44 ++++++++++++++++++++++++--- 1 file changed, 40 insertions(+), 4 deletions(-) diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst index 3704836fe6df6..87f6ad62633a5 100644 --- a/Documentation/bpf/instruction-set.rst +++ b/Documentation/bpf/instruction-set.rst @@ -82,9 +82,9 @@ 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 @@ -98,8 +98,8 @@ The code field encodes the operation as below: BPF_XOR 0xa0 dst ^= src BPF_MOV 0xb0 dst = src BPF_ARSH 0xc0 sign extending shift right - BPF_END 0xd0 endianness conversion - ======== ===== ========================== + BPF_END 0xd0 byte swap operations (see separate section below) + ======== ===== ================================================= BPF_ADD | BPF_X | BPF_ALU means:: @@ -118,6 +118,42 @@ BPF_XOR | BPF_K | BPF_ALU64 means:: src_reg = src_reg ^ imm32 +Byte swap instructions +---------------------- + +The byte swap instructions use an instruction class of ``BFP_ALU`` and a 4-bit +code field of ``BPF_END``. + +The byte swap instructions 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: + + ========= ===== ================================================= + 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 +are supported: 16, 32 and 64. + +Examples: + +``BPF_ALU | BPF_TO_LE | BPF_END`` with imm = 16 means:: + + dst_reg = htole16(dst_reg) + +``BPF_ALU | BPF_TO_BE | BPF_END`` with imm = 64 means:: + + dst_reg = htobe64(dst_reg) + +``BPF_FROM_LE`` and ``BPF_FROM_BE`` exist as aliases for ``BPF_TO_LE`` and +``BPF_TO_LE`` respetively. + + Jump instructions ----------------- From patchwork Mon Jan 31 18:36:35 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Christoph Hellwig X-Patchwork-Id: 12731016 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 75AA1C4167D for ; Mon, 31 Jan 2022 18:36:55 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1355653AbiAaSgy (ORCPT ); Mon, 31 Jan 2022 13:36:54 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:38006 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1350824AbiAaSgw (ORCPT ); Mon, 31 Jan 2022 13:36:52 -0500 Received: from bombadil.infradead.org (bombadil.infradead.org [IPv6:2607:7c80:54:e::133]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id BC408C06173D; Mon, 31 Jan 2022 10:36:52 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20210309; h=Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From:Sender :Reply-To:Content-Type:Content-ID:Content-Description; bh=95lu5RkgfPWM9UeysUZM6t6dw8NZZ00goVWEgHCmKMs=; b=ItaWmoz4PbYdOMsLLyDpOaIvQD NOdtZXydJYk7c8l3pkbwMpupRF9VISOkdds8ZDspyaS+vsfSvythYgl5mZFrBF29MWj1T532+UQOV pwzLy27M5cTsYyVhhvavloPO1YKJuCroorFpuK26xJjwFAvbK4NN/uizmUjIAxb+35cvYEShumIuA SIgL5VXp8BhY1aHLcQfDlApWaf8Hx1TNeRJybZTgsdLR30Iaa1MTJXarzPXPzdkogme9+Jr0Yvp0e oFtoaz7LtF5ekMqiGVWSlPlvzcpFKhn0s1Vb6oRUEzofREE/w+wm7aiYkmMj2hJR7PADztbxeBmcL h8Yi9TDw==; Received: from [2001:4bb8:191:327d:83ae:cf0e:db3c:eb79] (helo=localhost) by bombadil.infradead.org with esmtpsa (Exim 4.94.2 #2 (Red Hat Linux)) id 1nEbXj-00AOsE-5Q; Mon, 31 Jan 2022 18:36:47 +0000 From: Christoph Hellwig To: Jonathan Corbet , Alexei Starovoitov , Daniel Borkmann , Andrii Nakryiko Cc: Martin KaFai Lau , Song Liu , Yonghong Song , John Fastabend , KP Singh , linux-doc@vger.kernel.org, netdev@vger.kernel.org, bpf@vger.kernel.org Subject: [PATCH 2/5] bpf, docs: Better document the regular load and store instructions Date: Mon, 31 Jan 2022 19:36:35 +0100 Message-Id: <20220131183638.3934982-3-hch@lst.de> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20220131183638.3934982-1-hch@lst.de> References: <20220131183638.3934982-1-hch@lst.de> MIME-Version: 1.0 X-SRS-Rewrite: SMTP reverse-path rewritten from by bombadil.infradead.org. See http://www.infradead.org/rpr.html Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net Add a separate section and a little intro blurb for the regular load and store instructions. Signed-off-by: Christoph Hellwig --- Documentation/bpf/instruction-set.rst | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst index 87f6ad62633a5..03da885301722 100644 --- a/Documentation/bpf/instruction-set.rst +++ b/Documentation/bpf/instruction-set.rst @@ -215,23 +215,30 @@ The mode modifier is one of: BPF_IMM 0x00 used for 64-bit mov BPF_ABS 0x20 legacy BPF packet access BPF_IND 0x40 legacy BPF packet access - BPF_MEM 0x60 all normal load and store operations + BPF_MEM 0x60 regular load and store operations BPF_ATOMIC 0xc0 atomic operations ============= ===== ==================================== -BPF_MEM | | BPF_STX means:: + +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_reg + off) = src_reg -BPF_MEM | | BPF_ST means:: +``BPF_MEM | | BPF_ST`` means:: *(size *) (dst_reg + off) = imm32 -BPF_MEM | | BPF_LDX means:: +``BPF_MEM | | BPF_LDX`` means:: dst_reg = *(size *) (src_reg + off) -Where size is one of: BPF_B or BPF_H or BPF_W or BPF_DW. +Where size is one of: ``BPF_B``, ``BPF_H``, ``BPF_W``, or ``BPF_DW``. Atomic operations ----------------- From patchwork Mon Jan 31 18:36:36 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Christoph Hellwig X-Patchwork-Id: 12731018 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 C2251C35268 for ; Mon, 31 Jan 2022 18:36:58 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1356756AbiAaSg5 (ORCPT ); Mon, 31 Jan 2022 13:36:57 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:38020 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1356415AbiAaSgz (ORCPT ); Mon, 31 Jan 2022 13:36:55 -0500 Received: from bombadil.infradead.org (bombadil.infradead.org [IPv6:2607:7c80:54:e::133]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 33A16C061714; Mon, 31 Jan 2022 10:36:55 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20210309; h=Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From:Sender :Reply-To:Content-Type:Content-ID:Content-Description; bh=eQ9pR5g/eaZwRC6wov6WHMP3xNbN9HX9luYppfnhbmY=; b=tT/gDvWqYlJModAOkH63wmGjzZ 0juOmGjCDh+ic0klZx++cILrNAMetf8W166x193ouswWOaR6OJmgrKIyAuv3VHNBZHGRpugjkLu0r gfabiHiVCjoGKb728wvyM94HERnSadKa8TXzkAco6bSzvSAUuF6bBh88ejsgNFtMmoqGgqQy037Yy Hzx6cx/Q+tz2pSszHMnyDIPRW626ZG8Y7DEKi6srbHrLadhbUAjCXw5wirXn2J5cXRGI1PML1LPoL fjlWDxphNdKRPKWQF4ea9UGyamaY7AMm3h6E21xcUAeGa6v8L3y7jx2M7oiptyfUmzr98zpjyCrNk Tu/ZkbRQ==; Received: from [2001:4bb8:191:327d:83ae:cf0e:db3c:eb79] (helo=localhost) by bombadil.infradead.org with esmtpsa (Exim 4.94.2 #2 (Red Hat Linux)) id 1nEbXl-00AOsr-Ry; Mon, 31 Jan 2022 18:36:50 +0000 From: Christoph Hellwig To: Jonathan Corbet , Alexei Starovoitov , Daniel Borkmann , Andrii Nakryiko Cc: Martin KaFai Lau , Song Liu , Yonghong Song , John Fastabend , KP Singh , linux-doc@vger.kernel.org, netdev@vger.kernel.org, bpf@vger.kernel.org Subject: [PATCH 3/5] bpf, docs: Better document the legacy packet access instruction Date: Mon, 31 Jan 2022 19:36:36 +0100 Message-Id: <20220131183638.3934982-4-hch@lst.de> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20220131183638.3934982-1-hch@lst.de> References: <20220131183638.3934982-1-hch@lst.de> MIME-Version: 1.0 X-SRS-Rewrite: SMTP reverse-path rewritten from by bombadil.infradead.org. See http://www.infradead.org/rpr.html Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net Use consistent terminology and structured RST elements to better document these two oddball instructions. Signed-off-by: Christoph Hellwig --- Documentation/bpf/instruction-set.rst | 54 ++++++++++++++++----------- 1 file changed, 32 insertions(+), 22 deletions(-) diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst index 03da885301722..b3c2621216c97 100644 --- a/Documentation/bpf/instruction-set.rst +++ b/Documentation/bpf/instruction-set.rst @@ -213,8 +213,8 @@ The mode modifier is one of: mode modifier value description ============= ===== ==================================== BPF_IMM 0x00 used for 64-bit mov - BPF_ABS 0x20 legacy BPF packet access - BPF_IND 0x40 legacy BPF packet access + 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 ============= ===== ==================================== @@ -294,29 +294,39 @@ eBPF has one 16-byte instruction: ``BPF_LD | BPF_DW | BPF_IMM`` which consists of two consecutive ``struct bpf_insn`` 8-byte blocks and interpreted as single instruction that loads 64-bit immediate value into a dst_reg. -Packet access instructions --------------------------- +Legacy BPF Packet access instructions +------------------------------------- -eBPF has two non-generic instructions: (BPF_ABS | | BPF_LD) and -(BPF_IND | | BPF_LD) which are used to access packet data. +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. -They had to be carried over from classic BPF to have strong performance of -socket filters running in eBPF interpreter. These instructions can only -be used when interpreter context is a pointer to ``struct sk_buff`` and -have seven implicit operands. Register R6 is an implicit input that must -contain pointer to sk_buff. Register R0 is an implicit output which contains -the data fetched from the packet. Registers R1-R5 are scratch registers -and must not be used to store the data across BPF_ABS | BPF_LD or -BPF_IND | BPF_LD instructions. +The instructions come in two forms: ``BPF_ABS | | BPF_LD`` and +``BPF_IND | | BPF_LD``. -These instructions have implicit program exit condition as well. When -eBPF program is trying to access the data beyond the packet boundary, -the interpreter will abort the execution of the program. JIT compilers -therefore must preserve this property. src_reg and imm32 fields are -explicit inputs to these instructions. +These instructions are used to access packet data and can only be used when +the interpreter 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. -For example, BPF_IND | BPF_W | BPF_LD means:: +These instructions have seven implicit operands: - R0 = ntohl(*(u32 *) (((struct sk_buff *) R6)->data + src_reg + imm32)) + * 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 +interpreter will abort the execution of the program. + +``BPF_ABS | BPF_W | BPF_LD`` means:: -and R1 - R5 are clobbered. + 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)) From patchwork Mon Jan 31 18:36:37 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Christoph Hellwig X-Patchwork-Id: 12731020 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 C7D86C43219 for ; Mon, 31 Jan 2022 18:37:13 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1356766AbiAaShM (ORCPT ); Mon, 31 Jan 2022 13:37:12 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:38046 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1355341AbiAaSg7 (ORCPT ); Mon, 31 Jan 2022 13:36:59 -0500 Received: from bombadil.infradead.org (bombadil.infradead.org [IPv6:2607:7c80:54:e::133]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id BF83EC061741; Mon, 31 Jan 2022 10:36:57 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20210309; h=Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From:Sender :Reply-To:Content-Type:Content-ID:Content-Description; bh=65otJvu39ooLKVvhHd+SvuR6Mo3UfWkuAnUb1bbOYag=; b=UeHcL8g4gJ35U3zHmJblK5s1xz Zkhml0kDhnJEYRV4Kzn7ap7nq8UHgXVVeanNobsAbm2lqaOYqSatNUB9qLwIQPoHeo6xuVGJCqLMF qsIj0T5C1f08yYSgqF3d0hOsFaD+KLSONghgJVPoyUoZP/y1f/Dw2GnzoCB9CM0CtY5/ZywIREX3q ZTxuse/WehiBBdMP3js2M+3BhZfZd7QUah9ohHXtIHiKPIZsAQoRKlYzl0OpZiDOLOgn0GvrfI35S hd5mgSPPzL0bh+yCWRyPqdWkQFzZIAkPu5svZ1+owK7JG+Y1cDGuMRJ8NON6aq9M3EIHWTDd2VnU1 IU0463bA==; Received: from [2001:4bb8:191:327d:83ae:cf0e:db3c:eb79] (helo=localhost) by bombadil.infradead.org with esmtpsa (Exim 4.94.2 #2 (Red Hat Linux)) id 1nEbXo-00AOtf-Fm; Mon, 31 Jan 2022 18:36:53 +0000 From: Christoph Hellwig To: Jonathan Corbet , Alexei Starovoitov , Daniel Borkmann , Andrii Nakryiko Cc: Martin KaFai Lau , Song Liu , Yonghong Song , John Fastabend , KP Singh , linux-doc@vger.kernel.org, netdev@vger.kernel.org, bpf@vger.kernel.org Subject: [PATCH 4/5] bpf, docs: Better document the extended instruction format Date: Mon, 31 Jan 2022 19:36:37 +0100 Message-Id: <20220131183638.3934982-5-hch@lst.de> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20220131183638.3934982-1-hch@lst.de> References: <20220131183638.3934982-1-hch@lst.de> MIME-Version: 1.0 X-SRS-Rewrite: SMTP reverse-path rewritten from by bombadil.infradead.org. See http://www.infradead.org/rpr.html Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net In addition to the normal 64-bit instruction encoding, eBPF also has a single instruction that uses a second 64-bit bits for a second immediate value. Instead of only documenting this format deep down in the document mention it in the instruction encoding section. Signed-off-by: Christoph Hellwig --- Documentation/bpf/instruction-set.rst | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst index b3c2621216c97..048aea0952a2e 100644 --- a/Documentation/bpf/instruction-set.rst +++ b/Documentation/bpf/instruction-set.rst @@ -22,7 +22,13 @@ necessary across calls. Instruction encoding ==================== -eBPF uses 64-bit instructions with the following 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 looks as follows: ============= ======= =============== ==================== ============ 32 bits (MSB) 16 bits 4 bits 4 bits 8 bits (LSB) @@ -212,7 +218,7 @@ The mode modifier is one of: ============= ===== ==================================== mode modifier value description ============= ===== ==================================== - BPF_IMM 0x00 used for 64-bit mov + 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 @@ -287,12 +293,18 @@ You may encounter ``BPF_XADD`` - this is a legacy name for ``BPF_ATOMIC``, referring to the exclusive-add operation encoded when the immediate field is zero. -16-byte instructions --------------------- +64-bit immediate instructions +----------------------------- + +Instructions with the ``BPF_IMM`` mode modifier use the wide instruction +encoding for an extra imm64 value. + +There is currently only one such instruction. + +``BPF_LD | BPF_DW | BPF_IMM`` means:: + + dst_reg = imm64 -eBPF has one 16-byte instruction: ``BPF_LD | BPF_DW | BPF_IMM`` which consists -of two consecutive ``struct bpf_insn`` 8-byte blocks and interpreted as single -instruction that loads 64-bit immediate value into a dst_reg. Legacy BPF Packet access instructions ------------------------------------- From patchwork Mon Jan 31 18:36:38 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Christoph Hellwig X-Patchwork-Id: 12731019 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 01B9DC4321E for ; Mon, 31 Jan 2022 18:37:14 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1356737AbiAaShN (ORCPT ); Mon, 31 Jan 2022 13:37:13 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:38106 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1356944AbiAaShH (ORCPT ); Mon, 31 Jan 2022 13:37:07 -0500 Received: from bombadil.infradead.org (bombadil.infradead.org [IPv6:2607:7c80:54:e::133]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id AF961C06173E; Mon, 31 Jan 2022 10:37:00 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20210309; h=Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From:Sender :Reply-To:Content-Type:Content-ID:Content-Description; bh=2moysldpF3D0YrY9nWIgUUodshHFtQk8RLnSpJ4W8gk=; b=R4VYhISoOa7xhPwQXhM5O6QUPn sBWyA1OAHDZAZcX25S6RnLZms7pB4zxmzlGAbH2v615Fyhq7blFxBH5IEQtWYCu0p5epom0MGb+ml jh0aDOdxyTf/cYxhmLTJRjwAPLVfBCgTWvnanY8yuls0mgk7MUv6OUB8hFwaVYjOBGOpC5JIbEkFC 6A4x4rOI2wtW+oEJDFx9w9cn83WZKztl/Rk3ir3zwu9z1nEJOplIg1WfCH6Bz/c8gLJe6hX/zEz5j vE6wCdq8wFMBY+a55ipNumVgQQf423XUoNq43RRAEz7cLA/tWxigJ0jQCDE7qTa46U2h6qBlFvqTk yfndph2w==; Received: from [2001:4bb8:191:327d:83ae:cf0e:db3c:eb79] (helo=localhost) by bombadil.infradead.org with esmtpsa (Exim 4.94.2 #2 (Red Hat Linux)) id 1nEbXr-00AOuy-7n; Mon, 31 Jan 2022 18:36:55 +0000 From: Christoph Hellwig To: Jonathan Corbet , Alexei Starovoitov , Daniel Borkmann , Andrii Nakryiko Cc: Martin KaFai Lau , Song Liu , Yonghong Song , John Fastabend , KP Singh , linux-doc@vger.kernel.org, netdev@vger.kernel.org, bpf@vger.kernel.org Subject: [PATCH 5/5] bpf, docs: Better document the atomic instructions Date: Mon, 31 Jan 2022 19:36:38 +0100 Message-Id: <20220131183638.3934982-6-hch@lst.de> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20220131183638.3934982-1-hch@lst.de> References: <20220131183638.3934982-1-hch@lst.de> MIME-Version: 1.0 X-SRS-Rewrite: SMTP reverse-path rewritten from by bombadil.infradead.org. See http://www.infradead.org/rpr.html Precedence: bulk List-ID: X-Mailing-List: netdev@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net Use proper tables and RST markup to document the atomic instructions in a structured way. Signed-off-by: Christoph Hellwig --- Documentation/bpf/instruction-set.rst | 76 +++++++++++++++++---------- 1 file changed, 49 insertions(+), 27 deletions(-) diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst index 048aea0952a2e..4e79a77febd43 100644 --- a/Documentation/bpf/instruction-set.rst +++ b/Documentation/bpf/instruction-set.rst @@ -249,39 +249,65 @@ Where size is one of: ``BPF_B``, ``BPF_H``, ``BPF_W``, or ``BPF_DW``. Atomic operations ----------------- -eBPF includes atomic operations, which use the immediate field for extra -encoding:: +Atomic operations are operations that operate on memory and can not be +interrupted or corrupted by other access to the same memory region +by other eBPF programs or means outside of this specification. - .imm = BPF_ADD, .code = BPF_ATOMIC | BPF_W | BPF_STX: lock xadd *(u32 *)(dst_reg + off16) += src_reg - .imm = BPF_ADD, .code = BPF_ATOMIC | BPF_DW | BPF_STX: lock xadd *(u64 *)(dst_reg + off16) += src_reg +All atomic operations supported by eBPF are encoded as store operations +that use the ``BPF_ATOMIC`` mode modifier as follows: -The basic atomic operations supported are:: + * ``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_ADD - BPF_AND - BPF_OR - BPF_XOR +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: -Each having equivalent semantics with the ``BPF_ADD`` example, that is: the -memory location addresed by ``dst_reg + off`` is atomically modified, with -``src_reg`` as the other operand. If the ``BPF_FETCH`` flag is set in the -immediate, then these operations also overwrite ``src_reg`` with the -value that was in memory before it was modified. + ======== ===== =========== + imm value description + ======== ===== =========== + BPF_ADD 0x00 atomic add + BPF_OR 0x40 atomic or + BPF_AND 0x50 atomic and + BPF_XOR 0xa0 atomic xor + ======== ===== =========== -The more special operations are:: - BPF_XCHG +``BPF_ATOMIC | BPF_W | BPF_STX`` with imm = BPF_ADD means:: -This atomically exchanges ``src_reg`` with the value addressed by ``dst_reg + -off``. :: + *(u32 *)(dst_reg + off16) += src_reg - BPF_CMPXCHG +``BPF_ATOMIC | BPF_DW | BPF_STX`` with imm = BPF ADD means:: -This atomically compares the value addressed by ``dst_reg + off`` with -``R0``. If they match it is replaced with ``src_reg``. In either case, the -value that was there before is zero-extended and loaded back to ``R0``. + *(u64 *)(dst_reg + off16) += src_reg -Note that 1 and 2 byte atomic operations are not supported. +``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: + + =========== ================ =========================== + 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 +is set, then the operation also overwrites ``src_reg`` 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_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 +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 @@ -289,10 +315,6 @@ 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``. -You may encounter ``BPF_XADD`` - this is a legacy name for ``BPF_ATOMIC``, -referring to the exclusive-add operation encoded when the immediate field is -zero. - 64-bit immediate instructions -----------------------------