* [PATCH bpf-next] bpf, docs: Use RFC 2119 language for ISA requirements
@ 2024-05-17 16:58 ` Dave Thaler
0 siblings, 0 replies; 10+ messages in thread
From: Dave Thaler @ 2024-05-17 16:58 UTC (permalink / raw
To: bpf; +Cc: bpf, Dave Thaler, Dave Thaler
Per IETF convention and discussion at LSF/MM/BPF, use MUST etc.
keywords as requested by IETF Area Director review. Also as
requested, indicate that documenting BTF is out of scope of this
document and will be covered by a separate IETF specification.
Added paragraph about the terminology that is required IETF boilerplate
and must be worded exactly as such.
Signed-off-by: Dave Thaler <dthaler1968@googlemail.com>
---
.../bpf/standardization/instruction-set.rst | 24 ++++++++++++-------
1 file changed, 16 insertions(+), 8 deletions(-)
diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
index 997560aba..eb796ebde 100644
--- a/Documentation/bpf/standardization/instruction-set.rst
+++ b/Documentation/bpf/standardization/instruction-set.rst
@@ -14,6 +14,13 @@ set architecture (ISA).
Documentation conventions
=========================
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
+"OPTIONAL" in this document are to be interpreted as described in
+BCP 14 `<https://www.rfc-editor.org/info/rfc2119>`_
+`RFC8174 <https://www.rfc-editor.org/info/rfc8174>`_
+when, and only when, they appear in all capitals, as shown here.
+
For brevity and consistency, this document refers to families
of types using a shorthand syntax and refers to several expository,
mnemonic functions when describing the semantics of instructions.
@@ -106,9 +113,9 @@ Conformance groups
An implementation does not need to support all instructions specified in this
document (e.g., deprecated instructions). Instead, a number of conformance
-groups are specified. An implementation must support the base32 conformance
-group and may support additional conformance groups, where supporting a
-conformance group means it must support all instructions in that conformance
+groups are specified. An implementation MUST support the base32 conformance
+group and MAY support additional conformance groups, where supporting a
+conformance group means it MUST support all instructions in that conformance
group.
The use of named conformance groups enables interoperability between a runtime
@@ -209,7 +216,7 @@ For example::
07 1 0 00 00 11 22 33 44 r1 += 0x11223344 // big
Note that most instructions do not use all of the fields.
-Unused fields shall be cleared to zero.
+Unused fields SHALL be cleared to zero.
Wide instruction encoding
--------------------------
@@ -373,7 +380,7 @@ interpreted as a 64-bit signed value.
Note that there are varying definitions of the signed modulo operation
when the dividend or divisor are negative, where implementations often
vary by language such that Python, Ruby, etc. differ from C, Go, Java,
-etc. This specification requires that signed modulo use truncated division
+etc. This specification requires that signed modulo MUST use truncated division
(where -13 % 3 == -1) as implemented in C, Go, etc.::
a % n = a - n * trunc(a / n)
@@ -403,7 +410,7 @@ only and do not use a separate source register or immediate value.
For ``ALU``, the 1-bit source operand field in the opcode is used to
select what byte order the operation converts from or to. For
``ALU64``, the 1-bit source operand field in the opcode is reserved
-and must be set to 0.
+and MUST be set to 0.
===== ======== ===== =================================================
class source value description
@@ -514,7 +521,8 @@ for each program type, but static IDs are unique across all program types.
Platforms that support the BPF Type Format (BTF) support identifying
a helper function by a BTF ID encoded in the 'imm' field, where the BTF ID
-identifies the helper name and type.
+identifies the helper name and type. Further documentation of BTF
+is outside the scope of this document and is left for future work.
Program-local functions
~~~~~~~~~~~~~~~~~~~~~~~
@@ -724,5 +732,5 @@ carried over from classic BPF. These instructions used an instruction
class of ``LD``, a size modifier of ``W``, ``H``, or ``B``, and a
mode modifier of ``ABS`` or ``IND``. The 'dst_reg' and 'offset' fields were
set to zero, and 'src_reg' was set to zero for ``ABS``. However, these
-instructions are deprecated and should no longer be used. All legacy packet
+instructions are deprecated and SHOULD no longer be used. All legacy packet
access instructions belong to the "packet" conformance group.
--
2.40.1
^ permalink raw reply related [flat|nested] 10+ messages in thread
* [Bpf] [PATCH bpf-next] bpf, docs: Use RFC 2119 language for ISA requirements
@ 2024-05-17 16:58 ` Dave Thaler
0 siblings, 0 replies; 10+ messages in thread
From: Dave Thaler @ 2024-05-17 16:58 UTC (permalink / raw
To: bpf; +Cc: bpf, Dave Thaler, Dave Thaler
Per IETF convention and discussion at LSF/MM/BPF, use MUST etc.
keywords as requested by IETF Area Director review. Also as
requested, indicate that documenting BTF is out of scope of this
document and will be covered by a separate IETF specification.
Added paragraph about the terminology that is required IETF boilerplate
and must be worded exactly as such.
Signed-off-by: Dave Thaler <dthaler1968@googlemail.com>
---
.../bpf/standardization/instruction-set.rst | 24 ++++++++++++-------
1 file changed, 16 insertions(+), 8 deletions(-)
diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
index 997560aba..eb796ebde 100644
--- a/Documentation/bpf/standardization/instruction-set.rst
+++ b/Documentation/bpf/standardization/instruction-set.rst
@@ -14,6 +14,13 @@ set architecture (ISA).
Documentation conventions
=========================
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
+"OPTIONAL" in this document are to be interpreted as described in
+BCP 14 `<https://www.rfc-editor.org/info/rfc2119>`_
+`RFC8174 <https://www.rfc-editor.org/info/rfc8174>`_
+when, and only when, they appear in all capitals, as shown here.
+
For brevity and consistency, this document refers to families
of types using a shorthand syntax and refers to several expository,
mnemonic functions when describing the semantics of instructions.
@@ -106,9 +113,9 @@ Conformance groups
An implementation does not need to support all instructions specified in this
document (e.g., deprecated instructions). Instead, a number of conformance
-groups are specified. An implementation must support the base32 conformance
-group and may support additional conformance groups, where supporting a
-conformance group means it must support all instructions in that conformance
+groups are specified. An implementation MUST support the base32 conformance
+group and MAY support additional conformance groups, where supporting a
+conformance group means it MUST support all instructions in that conformance
group.
The use of named conformance groups enables interoperability between a runtime
@@ -209,7 +216,7 @@ For example::
07 1 0 00 00 11 22 33 44 r1 += 0x11223344 // big
Note that most instructions do not use all of the fields.
-Unused fields shall be cleared to zero.
+Unused fields SHALL be cleared to zero.
Wide instruction encoding
--------------------------
@@ -373,7 +380,7 @@ interpreted as a 64-bit signed value.
Note that there are varying definitions of the signed modulo operation
when the dividend or divisor are negative, where implementations often
vary by language such that Python, Ruby, etc. differ from C, Go, Java,
-etc. This specification requires that signed modulo use truncated division
+etc. This specification requires that signed modulo MUST use truncated division
(where -13 % 3 == -1) as implemented in C, Go, etc.::
a % n = a - n * trunc(a / n)
@@ -403,7 +410,7 @@ only and do not use a separate source register or immediate value.
For ``ALU``, the 1-bit source operand field in the opcode is used to
select what byte order the operation converts from or to. For
``ALU64``, the 1-bit source operand field in the opcode is reserved
-and must be set to 0.
+and MUST be set to 0.
===== ======== ===== =================================================
class source value description
@@ -514,7 +521,8 @@ for each program type, but static IDs are unique across all program types.
Platforms that support the BPF Type Format (BTF) support identifying
a helper function by a BTF ID encoded in the 'imm' field, where the BTF ID
-identifies the helper name and type.
+identifies the helper name and type. Further documentation of BTF
+is outside the scope of this document and is left for future work.
Program-local functions
~~~~~~~~~~~~~~~~~~~~~~~
@@ -724,5 +732,5 @@ carried over from classic BPF. These instructions used an instruction
class of ``LD``, a size modifier of ``W``, ``H``, or ``B``, and a
mode modifier of ``ABS`` or ``IND``. The 'dst_reg' and 'offset' fields were
set to zero, and 'src_reg' was set to zero for ``ABS``. However, these
-instructions are deprecated and should no longer be used. All legacy packet
+instructions are deprecated and SHOULD no longer be used. All legacy packet
access instructions belong to the "packet" conformance group.
--
2.40.1
--
Bpf mailing list -- bpf@ietf.org
To unsubscribe send an email to bpf-leave@ietf.org
^ permalink raw reply related [flat|nested] 10+ messages in thread
* RE: [PATCH bpf-next] bpf, docs: Use RFC 2119 language for ISA requirements
@ 2024-05-17 17:16 ` dthaler1968=40googlemail.com
0 siblings, 0 replies; 10+ messages in thread
From: dthaler1968 @ 2024-05-17 17:16 UTC (permalink / raw
To: 'Dave Thaler', bpf; +Cc: bpf
[...]
> Platforms that support the BPF Type Format (BTF) support identifying a
helper
> function by a BTF ID encoded in the 'imm' field, where the BTF ID
-identifies the
> helper name and type.
> +identifies the helper name and type. Further documentation of BTF is
> +outside the scope of this document and is left for future work.
Perhaps we should informatively reference
https://www.kernel.org/doc/html/latest/bpf/btf.html for now?
Dave
^ permalink raw reply [flat|nested] 10+ messages in thread
* [Bpf] Re: [PATCH bpf-next] bpf, docs: Use RFC 2119 language for ISA requirements
@ 2024-05-17 17:16 ` dthaler1968=40googlemail.com
0 siblings, 0 replies; 10+ messages in thread
From: dthaler1968=40googlemail.com @ 2024-05-17 17:16 UTC (permalink / raw
To: 'Dave Thaler', bpf; +Cc: bpf
[...]
> Platforms that support the BPF Type Format (BTF) support identifying a
helper
> function by a BTF ID encoded in the 'imm' field, where the BTF ID
-identifies the
> helper name and type.
> +identifies the helper name and type. Further documentation of BTF is
> +outside the scope of this document and is left for future work.
Perhaps we should informatively reference
https://www.kernel.org/doc/html/latest/bpf/btf.html for now?
Dave
--
Bpf mailing list -- bpf@ietf.org
To unsubscribe send an email to bpf-leave@ietf.org
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH bpf-next] bpf, docs: Use RFC 2119 language for ISA requirements
@ 2024-05-20 23:18 ` David Vernet
0 siblings, 0 replies; 10+ messages in thread
From: David Vernet @ 2024-05-20 23:18 UTC (permalink / raw
To: Dave Thaler; +Cc: bpf, bpf, Dave Thaler
[-- Attachment #1: Type: text/plain, Size: 1151 bytes --]
On Fri, May 17, 2024 at 09:58:55AM -0700, Dave Thaler wrote:
> Per IETF convention and discussion at LSF/MM/BPF, use MUST etc.
> keywords as requested by IETF Area Director review. Also as
> requested, indicate that documenting BTF is out of scope of this
> document and will be covered by a separate IETF specification.
>
> Added paragraph about the terminology that is required IETF boilerplate
> and must be worded exactly as such.
>
> Signed-off-by: Dave Thaler <dthaler1968@googlemail.com>
Acked-by: David Vernet <void@manifault.com>
We still have "may" in a couple of places, as in e.g.:
Note that there are two flavors of ``JA`` instructions. The ``JMP``
class permits a 16-bit jump offset specified by the 'offset' field,
whereas the ``JMP32`` class permits a 32-bit jump offset specified by
the 'imm' field. A > 16-bit conditional jump may be converted to a <
16-bit conditional jump plus a 32-bit unconditional jump.
Also in the "Helper functions" and "Maps" sections.
Do we need to fix those as well? Or are they considered semantically
different than how RFC 2119 would define the terms?
Thanks,
David
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]
^ permalink raw reply [flat|nested] 10+ messages in thread
* [Bpf] Re: [PATCH bpf-next] bpf, docs: Use RFC 2119 language for ISA requirements
@ 2024-05-20 23:18 ` David Vernet
0 siblings, 0 replies; 10+ messages in thread
From: David Vernet @ 2024-05-20 23:18 UTC (permalink / raw
To: Dave Thaler; +Cc: bpf, bpf, Dave Thaler
[-- Attachment #1.1: Type: text/plain, Size: 1151 bytes --]
On Fri, May 17, 2024 at 09:58:55AM -0700, Dave Thaler wrote:
> Per IETF convention and discussion at LSF/MM/BPF, use MUST etc.
> keywords as requested by IETF Area Director review. Also as
> requested, indicate that documenting BTF is out of scope of this
> document and will be covered by a separate IETF specification.
>
> Added paragraph about the terminology that is required IETF boilerplate
> and must be worded exactly as such.
>
> Signed-off-by: Dave Thaler <dthaler1968@googlemail.com>
Acked-by: David Vernet <void@manifault.com>
We still have "may" in a couple of places, as in e.g.:
Note that there are two flavors of ``JA`` instructions. The ``JMP``
class permits a 16-bit jump offset specified by the 'offset' field,
whereas the ``JMP32`` class permits a 32-bit jump offset specified by
the 'imm' field. A > 16-bit conditional jump may be converted to a <
16-bit conditional jump plus a 32-bit unconditional jump.
Also in the "Helper functions" and "Maps" sections.
Do we need to fix those as well? Or are they considered semantically
different than how RFC 2119 would define the terms?
Thanks,
David
[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]
[-- Attachment #2: Type: text/plain, Size: 88 bytes --]
--
Bpf mailing list -- bpf@ietf.org
To unsubscribe send an email to bpf-leave@ietf.org
^ permalink raw reply [flat|nested] 10+ messages in thread
* RE: [PATCH bpf-next] bpf, docs: Use RFC 2119 language for ISA requirements
@ 2024-05-20 23:43 ` dthaler1968=40googlemail.com
0 siblings, 0 replies; 10+ messages in thread
From: dthaler1968 @ 2024-05-20 23:43 UTC (permalink / raw
To: 'David Vernet', 'Dave Thaler'; +Cc: bpf, bpf
> -----Original Message-----
> From: David Vernet <void@manifault.com>
> Sent: Monday, May 20, 2024 4:18 PM
> To: Dave Thaler <dthaler1968@googlemail.com>
> Cc: bpf@vger.kernel.org; bpf@ietf.org; Dave Thaler <dthaler1968@gmail.com>
> Subject: Re: [PATCH bpf-next] bpf, docs: Use RFC 2119 language for ISA
> requirements
>
> On Fri, May 17, 2024 at 09:58:55AM -0700, Dave Thaler wrote:
> > Per IETF convention and discussion at LSF/MM/BPF, use MUST etc.
> > keywords as requested by IETF Area Director review. Also as
> > requested, indicate that documenting BTF is out of scope of this
> > document and will be covered by a separate IETF specification.
> >
> > Added paragraph about the terminology that is required IETF
> > boilerplate and must be worded exactly as such.
> >
> > Signed-off-by: Dave Thaler <dthaler1968@googlemail.com>
>
> Acked-by: David Vernet <void@manifault.com>
>
> We still have "may" in a couple of places, as in e.g.:
>
> Note that there are two flavors of ``JA`` instructions. The ``JMP`` class
permits a
> 16-bit jump offset specified by the 'offset' field, whereas the ``JMP32``
class
> permits a 32-bit jump offset specified by the 'imm' field. A > 16-bit
conditional jump
> may be converted to a < 16-bit conditional jump plus a 32-bit
unconditional jump.
>
> Also in the "Helper functions" and "Maps" sections.
>
> Do we need to fix those as well? Or are they considered semantically
different
> than how RFC 2119 would define the terms?
Those are semantically different (i.e., I left them intentionally) as they
are not
normative statements about what an ISA implementer would choose to do or not
do, but rather informative statements to the reader that would be synonymous
with
"can" or "might" in my reading.
Dave
>
> Thanks,
> David
^ permalink raw reply [flat|nested] 10+ messages in thread
* [Bpf] Re: [PATCH bpf-next] bpf, docs: Use RFC 2119 language for ISA requirements
@ 2024-05-20 23:43 ` dthaler1968=40googlemail.com
0 siblings, 0 replies; 10+ messages in thread
From: dthaler1968=40googlemail.com @ 2024-05-20 23:43 UTC (permalink / raw
To: 'David Vernet', 'Dave Thaler'; +Cc: bpf, bpf
> -----Original Message-----
> From: David Vernet <void@manifault.com>
> Sent: Monday, May 20, 2024 4:18 PM
> To: Dave Thaler <dthaler1968@googlemail.com>
> Cc: bpf@vger.kernel.org; bpf@ietf.org; Dave Thaler <dthaler1968@gmail.com>
> Subject: Re: [PATCH bpf-next] bpf, docs: Use RFC 2119 language for ISA
> requirements
>
> On Fri, May 17, 2024 at 09:58:55AM -0700, Dave Thaler wrote:
> > Per IETF convention and discussion at LSF/MM/BPF, use MUST etc.
> > keywords as requested by IETF Area Director review. Also as
> > requested, indicate that documenting BTF is out of scope of this
> > document and will be covered by a separate IETF specification.
> >
> > Added paragraph about the terminology that is required IETF
> > boilerplate and must be worded exactly as such.
> >
> > Signed-off-by: Dave Thaler <dthaler1968@googlemail.com>
>
> Acked-by: David Vernet <void@manifault.com>
>
> We still have "may" in a couple of places, as in e.g.:
>
> Note that there are two flavors of ``JA`` instructions. The ``JMP`` class
permits a
> 16-bit jump offset specified by the 'offset' field, whereas the ``JMP32``
class
> permits a 32-bit jump offset specified by the 'imm' field. A > 16-bit
conditional jump
> may be converted to a < 16-bit conditional jump plus a 32-bit
unconditional jump.
>
> Also in the "Helper functions" and "Maps" sections.
>
> Do we need to fix those as well? Or are they considered semantically
different
> than how RFC 2119 would define the terms?
Those are semantically different (i.e., I left them intentionally) as they
are not
normative statements about what an ISA implementer would choose to do or not
do, but rather informative statements to the reader that would be synonymous
with
"can" or "might" in my reading.
Dave
>
> Thanks,
> David
--
Bpf mailing list -- bpf@ietf.org
To unsubscribe send an email to bpf-leave@ietf.org
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH bpf-next] bpf, docs: Use RFC 2119 language for ISA requirements
2024-05-17 16:58 ` [Bpf] " Dave Thaler
` (2 preceding siblings ...)
(?)
@ 2024-05-25 17:50 ` patchwork-bot+netdevbpf
-1 siblings, 0 replies; 10+ messages in thread
From: patchwork-bot+netdevbpf @ 2024-05-25 17:50 UTC (permalink / raw
To: Dave Thaler; +Cc: bpf, bpf, dthaler1968
Hello:
This patch was applied to bpf/bpf-next.git (master)
by Alexei Starovoitov <ast@kernel.org>:
On Fri, 17 May 2024 09:58:55 -0700 you wrote:
> Per IETF convention and discussion at LSF/MM/BPF, use MUST etc.
> keywords as requested by IETF Area Director review. Also as
> requested, indicate that documenting BTF is out of scope of this
> document and will be covered by a separate IETF specification.
>
> Added paragraph about the terminology that is required IETF boilerplate
> and must be worded exactly as such.
>
> [...]
Here is the summary with links:
- [bpf-next] bpf, docs: Use RFC 2119 language for ISA requirements
https://git.kernel.org/bpf/bpf-next/c/a985fdca5e7e
You are awesome, thank you!
--
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [Bpf] [PATCH bpf-next] bpf, docs: Use RFC 2119 language for ISA requirements
2024-05-17 16:58 ` [Bpf] " Dave Thaler
` (3 preceding siblings ...)
(?)
@ 2024-05-26 9:01 ` Christoph Hellwig
-1 siblings, 0 replies; 10+ messages in thread
From: Christoph Hellwig @ 2024-05-26 9:01 UTC (permalink / raw
To: Dave Thaler; +Cc: bpf, bpf, Dave Thaler, Dave Thaler
Looks good:
Reviewed-by: Christoph Hellwig <hch@lst.de>
^ permalink raw reply [flat|nested] 10+ messages in thread
end of thread, other threads:[~2024-05-26 9:01 UTC | newest]
Thread overview: 10+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2024-05-17 16:58 [PATCH bpf-next] bpf, docs: Use RFC 2119 language for ISA requirements Dave Thaler
2024-05-17 16:58 ` [Bpf] " Dave Thaler
2024-05-17 17:16 ` dthaler1968
2024-05-17 17:16 ` [Bpf] " dthaler1968=40googlemail.com
2024-05-20 23:18 ` David Vernet
2024-05-20 23:18 ` [Bpf] " David Vernet
2024-05-20 23:43 ` dthaler1968
2024-05-20 23:43 ` [Bpf] " dthaler1968=40googlemail.com
2024-05-25 17:50 ` patchwork-bot+netdevbpf
2024-05-26 9:01 ` [Bpf] " Christoph Hellwig
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.