From nobody Sat Feb 7 23:11:11 2026 Received: from mail-pl1-f201.google.com (mail-pl1-f201.google.com [209.85.214.201]) (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 8D73B185B73 for ; Fri, 7 Feb 2025 02:06:41 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.214.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738894003; cv=none; b=B+VsiUTP6hmG5xSaS5tFCvmIAM7segn2wyWuU62PfKAk0v3QCdSqfTdLGVIzRin3hGQgyAqHITPkqK5WBhCZOjRFqOmBd1ZrkTZEhOFMLS8CB210dKP9c3dyAzgK4YcZsphGmALv7kBCE5+ng8PIv4CdyOUuhvl/Uz+1kTTdb6o= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738894003; c=relaxed/simple; bh=9TD85PMgpDU5D2oxZLnT8DCFz4XahRBdsQKIng9CEDo=; h=Date:In-Reply-To:Mime-Version:References:Message-ID:Subject:From: To:Cc:Content-Type; b=f32o33h6n3cRc1kYWF3ZJ0IqG/B+Xo27O66yTCboG4p0qumXBGCvjo2B0ii1oHudioQIluKFRXWfLk9fjT99Rf1w+j0JrvczQDrYZ5cs8OreuIEMQEW/az/kZN6qBkXBxs8p7yXdK7uNI9fiGK4RNttVuyTLrI9Zaba3DqTe99I= 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=OBzGFbMN; arc=none smtp.client-ip=209.85.214.201 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="OBzGFbMN" Received: by mail-pl1-f201.google.com with SMTP id d9443c01a7336-21f5060ef10so14450515ad.2 for ; Thu, 06 Feb 2025 18:06:41 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20230601; t=1738894001; x=1739498801; 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=2ep8DalcKj7dauwNLlP5ARZOtPwUTNVJ49jqJ539nuE=; b=OBzGFbMNev6db22Ug6L456fKfc1yLG3P+gqAgn8CV5iTHmJTPa1tTmDdSwYMnSsVun hnEPHNNIyTPpOLqSV7+VfgQWoptvufRmqgGBCPhRVhx4s21e31P1KL5g7C/TjFaos8DA tNrgb9GYPosETBd4T2APpFCoeZwa3B8palTtjZE9Q1l7cGlSldap/VbW8VIphXhUa+8J WUhWh68Zt9QpYrjsK90ep5KXkolMCOHVQ+oKDHHvEejvzUvN0mUj8paarhD4kGVwzK/4 fO+40eg+LFavvjznL/vcFy3DTEm8CS2DpMyb9C5H3FbflV1A0I8AVnakvjSMNyUuZllw jnGA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1738894001; x=1739498801; 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=2ep8DalcKj7dauwNLlP5ARZOtPwUTNVJ49jqJ539nuE=; b=sgHgcp5DeKQ3ykvDc4jB8iBV8JAI5GQ0bkTGF+HFkBNwwpR1de3Td26/NgcgmDqLrr i0E7SjKbjbLqDO2Fa02F1EFMphM4OYOJmqt3MZR68dUgFVRtKbb1191hEBDlmjIBeOfe pmUT9qJCfi5dUHzDwcyBZ97osAsW/PMqudvwZIAKpZDSsuYuWUtPzYSyn87A2QAagSSv HzG/hPy4Lak2A6gf8qsE7kgCe2aBRzsci8HHnh8s57+5H/vbC7ExFGN5nn+d7li7xnXQ 5PtYjIgeFjJvSvDigohZXqWstFpp4b9i2AbY4SlROdn274hCrPJ/fdOSTf9RaECiydd8 1ncQ== X-Forwarded-Encrypted: i=1; AJvYcCX7DJWp9UFRNFi525Is554cd3ZZcn2ezLq6Bfoxeo1izuY/TlGHaIWEr4peUjUD69dytmrYRieQbNIqN4k=@vger.kernel.org X-Gm-Message-State: AOJu0YwD8lhQ5Rc4gpBA4P3WLelTS5GN2iF6cX6u9aP9fgfvd1Njl3bw DruwNmjc0YPggVUc950s+51jIhdpShO2HaO7KwAVXagrIEwPqpuhLUWINTDliTu5aQe4XSabnsg Z2e1S0JgTnQ== X-Google-Smtp-Source: AGHT+IHO+QQmGU+1/m5wHtsMoItJdlgCTFiDvf89nZcXM296VZbNzIAooIz/Ko6Udd05tpk4RbaW4EcMXoxUsg== X-Received: from pfnv19.prod.google.com ([2002:aa7:8513:0:b0:730:5488:ee30]) (user=yepeilin job=prod-delivery.src-stubby-dispatcher) by 2002:a05:6a21:1394:b0:1e0:c77c:450d with SMTP id adf61e73a8af0-1ee03a242cemr2973087637.1.1738894000789; Thu, 06 Feb 2025 18:06:40 -0800 (PST) Date: Fri, 7 Feb 2025 02:06:36 +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.502.g6dc24dfdaf-goog Message-ID: Subject: [PATCH bpf-next v2 9/9] 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 , Ilya Leoshkevich , Heiko Carstens , Vasily Gorbik , Catalin Marinas , Will Deacon , Quentin Monnet , Mykola Lysenko , Shuah Khan , Ihor Solodrai , Yingchi Long , 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.502.g6dc24dfdaf-goog