From nobody Wed Feb 11 12:08:23 2026 Received: from mail-pl1-f202.google.com (mail-pl1-f202.google.com [209.85.214.202]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id B8CCC1FBCB5 for ; Sat, 25 Jan 2025 02:19:48 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.214.202 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1737771590; cv=none; b=Yotz7ueb7WqoAIV95bzWR11Dda/wh2GRgWpoWqKRKbhknwLgwK5YENuGgBEtomod2sWLA0zmDvp/pB6WqGTS6ohsHrsdidi7HtBNcfOC4hLBrIHWu97gxwzmat7CGRVivDyyJ3OV+E1ZRTblDGOFMVUQP15IzCkJyLusCtrHvSw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1737771590; c=relaxed/simple; bh=fwAIKVLFLiF2lkUBIMqPgWM5xGFj0kGqNXQ696QGQxQ=; h=Date:In-Reply-To:Mime-Version:References:Message-ID:Subject:From: To:Cc:Content-Type; b=VuE7J7O72ueLJh3iW5q+kjOic3DldACe6ySBn8MWR4NuwXXrExu+h555rF34XaQJGgaQWUPRR0Zjq0HNNxpId7Ft7t4+u0957GuL1IByAgYx7j4UI9keV1A0Pq5FayC4rQFttmtI8DtDy7ft4RjdW2arDVRMuP2YeuXxEFNnt4I= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=google.com; spf=pass smtp.mailfrom=flex--yepeilin.bounces.google.com; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b=pM0HdtDG; arc=none smtp.client-ip=209.85.214.202 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=google.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=flex--yepeilin.bounces.google.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b="pM0HdtDG" Received: by mail-pl1-f202.google.com with SMTP id d9443c01a7336-21648ddd461so54250775ad.0 for ; Fri, 24 Jan 2025 18:19:48 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20230601; t=1737771588; x=1738376388; darn=vger.kernel.org; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:from:to:cc:subject:date:message-id:reply-to; bh=LoHUEUhOV0x0mPYHihiLdSKtz41TIEtVbSj3jmRsaOk=; b=pM0HdtDGWxprW/V2laO2Dt3hkKHbSeI6uw0nQUA/6BgJ09+gtLHa4xzziDuaW7ibMd 9jahm2pIXYeCqkkFn7pykz0iyiqi7ZaCfEUyzotVRkOux1hvGuL3SAHjAirp+0VFYJL6 8VlAQLBAVnSAoRwDcgDrgH6/gn0MN0r/jXvy3S8TqF5hrZWfL//Jktu/r09SnUfsjJtx 7ZJgg2CEo9WwPuyS+zrwN/ERQ7oUDY8HFFlfDdfHX02OvIUtHLh8fJ/WdZsQDUIqAYh9 fCu21KCpSsa7zAaL9TIJYspEgakGhjAv5gczK7mupW45hQ7nNnM/aiFUxV96jFQHKRxm d6wA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1737771588; x=1738376388; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=LoHUEUhOV0x0mPYHihiLdSKtz41TIEtVbSj3jmRsaOk=; b=mShX/Doypssp4zyjUzp3FIicKxXj9cjyOCD+KegNf3113li4JekZGc7smu8m7c1nmd I+2YovcniRmp+FwIUXDzg28XKp2y+McOxrkC/ZC5N96bcilwOZnytpP2QE+L4mmXghK0 6MIrNGBPvUVY3rk6xfLLABe+dJquT3h+4Yt9SsLtWyirYOfD1dbUbZ1y4RuGOwesGLxB DMtnkMCEGEVtyiylLNFnJKR5dGutPBWN6AsmA6DAhBVs7hKsqTdTmR8AOL9ufpQQ+SUL ytJCseUiVsGCTXlM3Q+EYb26B2xGnCA0mYRqx8+evzuqojYD4i32NSJNqbl568H505a7 MZZw== X-Forwarded-Encrypted: i=1; AJvYcCUvZTAAgNWq66G8d4aR+fWFBsEc3Fe2Dl8S9YUKKUFNnYrBK7XGqHRNDLiU9Ca46/YWwKSgXocFjyfqOjI=@vger.kernel.org X-Gm-Message-State: AOJu0Yw6hSCWZVQsYBWu968miChKGwwqbtL8Qq6PpgkGNqCjoyY2Nxkt Yo+QKvKe76l9PELoapka0MA32upGGkCjNp87h0lWEaeZyXZJWVYB0NswfAcXyy58fCGrZch0vxu iMJ7ht3yHYw== X-Google-Smtp-Source: AGHT+IHGh/EcJQlJc3OUFLXhqDr5SV+ajo77ZpLxRt1CFaw1WVG3Fg0XoLCrcpjLJvkD2sLS2HovJh1AnpwYjQ== X-Received: from plez12.prod.google.com ([2002:a17:902:cccc:b0:215:dbd8:a6e7]) (user=yepeilin job=prod-delivery.src-stubby-dispatcher) by 2002:a17:903:1381:b0:216:361a:783d with SMTP id d9443c01a7336-21c3562097amr541898135ad.28.1737771587999; Fri, 24 Jan 2025 18:19:47 -0800 (PST) Date: Sat, 25 Jan 2025 02:19:39 +0000 In-Reply-To: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: Mime-Version: 1.0 References: X-Mailer: git-send-email 2.48.1.262.g85cc9f2d1e-goog Message-ID: Subject: [PATCH bpf-next v1 8/8] bpf, docs: Update instruction-set.rst for load-acquire and store-release instructions From: Peilin Ye To: bpf@vger.kernel.org, linux-arm-kernel@lists.infradead.org Cc: Peilin Ye , bpf@ietf.org, Xu Kuohai , Eduard Zingerman , David Vernet , Alexei Starovoitov , Daniel Borkmann , Andrii Nakryiko , Martin KaFai Lau , Song Liu , Yonghong Song , John Fastabend , KP Singh , Stanislav Fomichev , Hao Luo , Jiri Olsa , Jonathan Corbet , "Paul E. McKenney" , Puranjay Mohan , Catalin Marinas , Will Deacon , Quentin Monnet , Mykola Lysenko , Shuah Khan , Josh Don , Barret Rhoden , Neel Natu , Benjamin Segall , linux-kernel@vger.kernel.org Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Update documentation for the new load-acquire and store-release instructions. Rename existing atomic operations as "atomic read-modify-write (RMW) operations". Following RFC 9669, section 7.3. "Adding Instructions", create new conformance groups "atomic32v2" and "atomic64v2", where: * atomic32v2: includes all instructions in "atomic32", plus the new 8-bit, 16-bit and 32-bit atomic load-acquire and store-release instructions * atomic64v2: includes all instructions in "atomic64" and "atomic32v2", plus the new 64-bit atomic load-acquire and store-release instructions Cc: bpf@ietf.org Signed-off-by: Peilin Ye --- .../bpf/standardization/instruction-set.rst | 114 +++++++++++++++--- 1 file changed, 98 insertions(+), 16 deletions(-) diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Docume= ntation/bpf/standardization/instruction-set.rst index ab820d565052..86917932e9ef 100644 --- a/Documentation/bpf/standardization/instruction-set.rst +++ b/Documentation/bpf/standardization/instruction-set.rst @@ -139,8 +139,14 @@ This document defines the following conformance groups: specification unless otherwise noted. * base64: includes base32, plus instructions explicitly noted as being in the base64 conformance group. -* atomic32: includes 32-bit atomic operation instructions (see `Atomic ope= rations`_). -* atomic64: includes atomic32, plus 64-bit atomic operation instructions. +* atomic32: includes 32-bit atomic read-modify-write instructions (see + `Atomic operations`_). +* atomic32v2: includes atomic32, plus 8-bit, 16-bit and 32-bit atomic + load-acquire and store-release instructions. +* atomic64: includes atomic32, plus 64-bit atomic read-modify-write + instructions. +* atomic64v2: unifies atomic32v2 and atomic64, plus 64-bit atomic load-acq= uire + and store-release instructions. * divmul32: includes 32-bit division, multiplication, and modulo instructi= ons. * divmul64: includes divmul32, plus 64-bit division, multiplication, and modulo instructions. @@ -653,20 +659,31 @@ Atomic operations are operations that operate on memo= ry and can not be interrupted or corrupted by other access to the same memory region by other BPF programs or means outside of this specification. =20 -All atomic operations supported by BPF are encoded as store operations -that use the ``ATOMIC`` mode modifier as follows: +All atomic operations supported by BPF are encoded as ``STX`` instructions +that use the ``ATOMIC`` mode modifier, with the 'imm' field encoding the +actual atomic operation. These operations are categorized based on the se= cond +lowest nibble (bits 4-7) of the 'imm' field: =20 -* ``{ATOMIC, W, STX}`` for 32-bit operations, which are +* ``ATOMIC_LOAD`` and ``ATOMIC_STORE`` indicate atomic load and store + operations, respectively (see `Atomic load and store operations`_). +* All other defined values indicate an atomic read-modify-write operation,= as + described in the following section. + +Atomic read-modify-write operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The atomic read-modify-write (RMW) operations are encoded as follows: + +* ``{ATOMIC, W, STX}`` for 32-bit RMW operations, which are part of the "atomic32" conformance group. -* ``{ATOMIC, DW, STX}`` for 64-bit operations, which are +* ``{ATOMIC, DW, STX}`` for 64-bit RMW operations, which are part of the "atomic64" conformance group. -* 8-bit and 16-bit wide atomic operations are not supported. +* 8-bit and 16-bit wide atomic RMW operations are not supported. =20 -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: +Simple atomic RMW operation use a subset of the values defined to encode +arithmetic operations in the 'imm' field to encode the atomic RMW operatio= n: =20 -.. table:: Simple atomic operations +.. table:: Simple atomic read-modify-write operations =20 =3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D imm value description @@ -686,10 +703,10 @@ arithmetic operations in the 'imm' field to encode th= e atomic operation: =20 *(u64 *)(dst + offset) +=3D src =20 -In addition to the simple atomic operations, there also is a modifier and -two complex atomic operations: +In addition to the simple atomic RMW operations, there also is a modifier = and +two complex atomic RMW operations: =20 -.. table:: Complex atomic operations +.. table:: Complex atomic read-modify-write operations =20 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D imm value description @@ -699,8 +716,8 @@ two complex atomic operations: CMPXCHG 0xf0 | FETCH atomic compare and exchange =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D =20 -The ``FETCH`` modifier is optional for simple atomic operations, and -always set for the complex atomic operations. If the ``FETCH`` flag +The ``FETCH`` modifier is optional for simple atomic RMW operations, and +always set for the complex atomic RMW operations. If the ``FETCH`` flag is set, then the operation also overwrites ``src`` with the value that was in memory before it was modified. =20 @@ -713,6 +730,71 @@ The ``CMPXCHG`` operation atomically compares the valu= e addressed by value that was at ``dst + offset`` before the operation is zero-extended and loaded back to ``R0``. =20 +Atomic load and store operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To encode an atomic load or store operation, the lowest 8 bits of the 'imm' +field are divided as follows:: + + +-+-+-+-+-+-+-+-+ + | type | order | + +-+-+-+-+-+-+-+-+ + +**type** + The operation type is one of: + +.. table:: Atomic load and store operation types + + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D =3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D + type value description + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D =3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D + ATOMIC_LOAD 0x1 atomic load + ATOMIC_STORE 0x2 atomic store + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D =3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D + +**order** + The memory order is one of: + +.. table:: Memory orders + + =3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + order value description + =3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + RELAXED 0x0 relaxed + ACQUIRE 0x1 acquire + RELEASE 0x2 release + ACQ_REL 0x3 acquire and release + SEQ_CST 0x4 sequentially consistent + =3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Currently the following combinations of ``type`` and ``order`` are allowed: + +.. table:: Atomic load and store operations + + =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + imm value description + =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + LOAD_ACQ 0x11 atomic load-acquire + STORE_REL 0x22 atomic store-release + =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +``{ATOMIC, , STX}`` with 'imm' =3D LOAD_ACQ means:: + + dst =3D load_acquire((unsigned size *)(src + offset)) + +``{ATOMIC, , STX}`` with 'imm' =3D STORE_REL means:: + + store_release((unsigned size *)(dst + offset), src) + +Where '' is one of: ``B``, ``H``, ``W``, or ``DW``, and 'unsigned si= ze' +is one of: u8, u16, u32, or u64. + +8-bit, 16-bit and 32-bit atomic load-acquire and store-release instructions +are part of the "atomic32v2" conformance group. + +64-bit atomic load-acquire and store-release instructions are part of the +"atomic64v2" conformance group. + 64-bit immediate instructions ----------------------------- =20 --=20 2.48.1.262.g85cc9f2d1e-goog