| Message ID | 1412789478-38353-1-git-send-email-mike.holmes@linaro.org |
|---|---|
| State | Not Applicable |
| Headers | show |
+1 On Wed, Oct 8, 2014 at 12:31 PM, Mike Holmes <mike.holmes@linaro.org> wrote: > We only need one copy of the requirements terminology > > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> > Reviewed-by: Bill Fischofer <bill.fischofer@linaro.org> > --- > boilerplate.dox | 15 +++++++++++++++ > classification_design.dox | 3 +-- > crypto_design.dox | 3 +-- > 3 files changed, 17 insertions(+), 4 deletions(-) > create mode 100644 boilerplate.dox > > diff --git a/boilerplate.dox b/boilerplate.dox > new file mode 100644 > index 0000000..5ac1616 > --- /dev/null > +++ b/boilerplate.dox > @@ -0,0 +1,15 @@ > +/* Copyright (c) 2014, Linaro Limited > + * All rights reserved > + * > + * SPDX-License-Identifier: BSD-3-Clause > + */ > + > +/** > +@page odp_definitions Definitions > + > +@tableofcontents > + > +@section use_of_terms Requirement terminology > +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", > "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this > document are to be interpreted as described in [RFC 2119]( > https://tools.ietf.org/html/rfc2119). > + > +*/ > diff --git a/classification_design.dox b/classification_design.dox > index db0b273..8733144 100644 > --- a/classification_design.dox > +++ b/classification_design.dox > @@ -15,8 +15,7 @@ This document defines the Classification APIs supported > by ODP. > Classification is logically composed of two stages: Parsing and Rule > Matching. > Parsing takes a raw packet and validates its structure and identifies > fields of interest in the various headers that comprise the layers of the > packet. > Rule Matching, in turn, takes the result of parsing and sorts packets > into Classes of Service (CoS) based on application-defined rule sets. > -@subsection use_of_terms Use of Terms > -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", > "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this > document are to be interpreted as described in [RFC 2119]( > https://tools.ietf.org/html/rfc21199). > +@ref use_of_terms > @subsection purpose Purpose > ODP is a framework for software-based packet forwarding/filtering > applications, and the purpose of the Packet Classifier API is to enable > applications to program the platform hardware or software implementation to > assist in prioritization, classification and scheduling of each packet, so > that the software application can run faster, scale better and adhere to > QoS requirements. > The following API abstraction are not modelled after any existing product > implementation, but is instead defined in terms of what a typical > data-plane application may require from such a platform, without > sacrificing simplicity and avoiding ambiguity. > diff --git a/crypto_design.dox b/crypto_design.dox > index d0f016b..ed9166d 100644 > --- a/crypto_design.dox > +++ b/crypto_design.dox > @@ -15,8 +15,7 @@ This document describes the ODP Crypto API. > Cryptography is an important part of data plane processing as many > communication protocols make use of cryptographic functions. > Moreover, many SoCs incorporate cryptographic hardware that can > significantly accelerate these operations compared to their software > equivalents as well as provide validated hardware functional correctness > and security boundaries necessary for system-level security certifications > such as FIPS-140 Level 2 and above. > @section requirements Requirements > -@subsection use_of_terms Use of Terms > -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", > "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this > document are to be interpreted as described in [RFC 2119]( > https://tools.ietf.org/html/rfc2119). > +@ref use_of_terms > @subsection uses_of_cryptography Uses of Cryptography > Crypto functions cover a range of uses and capabilities designed to > support data security, integrity, authentication, and non-repudiation. > @subsubsection data_security Data Security > -- > 1.9.1 > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp >
On 8 October 2014 19:31, Mike Holmes <mike.holmes@linaro.org> wrote: > We only need one copy of the requirements terminology > > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> > --- > boilerplate.dox | 15 +++++++++++++++ > classification_design.dox | 3 +-- > crypto_design.dox | 3 +-- > 3 files changed, 17 insertions(+), 4 deletions(-) > create mode 100644 boilerplate.dox > > diff --git a/boilerplate.dox b/boilerplate.dox > new file mode 100644 > index 0000000..5ac1616 > --- /dev/null > +++ b/boilerplate.dox > @@ -0,0 +1,15 @@ > +/* Copyright (c) 2014, Linaro Limited > + * All rights reserved > + * > + * SPDX-License-Identifier: BSD-3-Clause > + */ > + > +/** > +@page odp_definitions Definitions > + > +@tableofcontents > + > +@section use_of_terms Requirement terminology > +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", > "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this > document are to be interpreted as described in [RFC 2119]( > https://tools.ietf.org/html/rfc2119). > Why do we need this at all in ODP? Either a vendor supports ODP version X or not right? If he can be half ODP complient how can we write portable code then? If I write my application against ODP version X from vendor A that have implemented all must and two may... then I will port my app to vendor B and he has only implemented all must, will my app work or not? =) Cheers, Anders > + > +*/ > diff --git a/classification_design.dox b/classification_design.dox > index db0b273..8733144 100644 > --- a/classification_design.dox > +++ b/classification_design.dox > @@ -15,8 +15,7 @@ This document defines the Classification APIs supported > by ODP. > Classification is logically composed of two stages: Parsing and Rule > Matching. > Parsing takes a raw packet and validates its structure and identifies > fields of interest in the various headers that comprise the layers of the > packet. > Rule Matching, in turn, takes the result of parsing and sorts packets > into Classes of Service (CoS) based on application-defined rule sets. > -@subsection use_of_terms Use of Terms > -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", > "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this > document are to be interpreted as described in [RFC 2119]( > https://tools.ietf.org/html/rfc21199). > +@ref use_of_terms > @subsection purpose Purpose > ODP is a framework for software-based packet forwarding/filtering > applications, and the purpose of the Packet Classifier API is to enable > applications to program the platform hardware or software implementation to > assist in prioritization, classification and scheduling of each packet, so > that the software application can run faster, scale better and adhere to > QoS requirements. > The following API abstraction are not modelled after any existing product > implementation, but is instead defined in terms of what a typical > data-plane application may require from such a platform, without > sacrificing simplicity and avoiding ambiguity. > diff --git a/crypto_design.dox b/crypto_design.dox > index d0f016b..ed9166d 100644 > --- a/crypto_design.dox > +++ b/crypto_design.dox > @@ -15,8 +15,7 @@ This document describes the ODP Crypto API. > Cryptography is an important part of data plane processing as many > communication protocols make use of cryptographic functions. > Moreover, many SoCs incorporate cryptographic hardware that can > significantly accelerate these operations compared to their software > equivalents as well as provide validated hardware functional correctness > and security boundaries necessary for system-level security certifications > such as FIPS-140 Level 2 and above. > @section requirements Requirements > -@subsection use_of_terms Use of Terms > -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", > "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this > document are to be interpreted as described in [RFC 2119]( > https://tools.ietf.org/html/rfc2119). > +@ref use_of_terms > @subsection uses_of_cryptography Uses of Cryptography > Crypto functions cover a range of uses and capabilities designed to > support data security, integrity, authentication, and non-repudiation. > @subsubsection data_security Data Security > -- > 1.9.1 > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp >
On 11 October 2014 16:32, Anders Roxell <anders.roxell@linaro.org> wrote: > > > On 8 October 2014 19:31, Mike Holmes <mike.holmes@linaro.org> wrote: > >> We only need one copy of the requirements terminology >> >> Signed-off-by: Mike Holmes <mike.holmes@linaro.org> >> --- >> boilerplate.dox | 15 +++++++++++++++ >> classification_design.dox | 3 +-- >> crypto_design.dox | 3 +-- >> 3 files changed, 17 insertions(+), 4 deletions(-) >> create mode 100644 boilerplate.dox >> >> diff --git a/boilerplate.dox b/boilerplate.dox >> new file mode 100644 >> index 0000000..5ac1616 >> --- /dev/null >> +++ b/boilerplate.dox >> @@ -0,0 +1,15 @@ >> +/* Copyright (c) 2014, Linaro Limited >> + * All rights reserved >> + * >> + * SPDX-License-Identifier: BSD-3-Clause >> + */ >> + >> +/** >> +@page odp_definitions Definitions >> + >> +@tableofcontents >> + >> +@section use_of_terms Requirement terminology >> +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", >> "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this >> document are to be interpreted as described in [RFC 2119]( >> https://tools.ietf.org/html/rfc2119). >> > > Why do we need this at all in ODP? > I assume you mean all the actual uses of MUST etc in the document. As an incremental improvement on the doc we have now, I think this is valid because that text is duplicated. We struggle reviewing large docs, they get out of step with the code development, but maybe we can nows make many small improvements ? > Either a vendor supports ODP version X or not right? > > If he can be half ODP complient how can we write portable code then? > As for whether all the statements saying MUST etc are correct I don't know, but assuming they are valid we should be able to map the musts to unit test cases and find the truth about how portable an application is across all the implementations. > If I write my application against ODP version X from vendor A that have > implemented all must and two may... then I will port my app to vendor B > and he has only implemented all must, will my app work or not? =) > > I do feel the current ARCH doc has data that would fit better as pages supplementing the API doc, the current arch doc is more of a collection of design docs. We also know we need a guide for a new application writers and a guide for a new implementers IMHO, we have had folks ask questions on the list that should have been answered in such docs. My one big concern is that we have found that doc writing takes a long time and I don't think we have a lot of time for before 1.0 so we don't want to get too distracted. Cheers, > Anders > > > >> + >> +*/ >> diff --git a/classification_design.dox b/classification_design.dox >> index db0b273..8733144 100644 >> --- a/classification_design.dox >> +++ b/classification_design.dox >> @@ -15,8 +15,7 @@ This document defines the Classification APIs supported >> by ODP. >> Classification is logically composed of two stages: Parsing and Rule >> Matching. >> Parsing takes a raw packet and validates its structure and identifies >> fields of interest in the various headers that comprise the layers of the >> packet. >> Rule Matching, in turn, takes the result of parsing and sorts packets >> into Classes of Service (CoS) based on application-defined rule sets. >> -@subsection use_of_terms Use of Terms >> -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", >> "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this >> document are to be interpreted as described in [RFC 2119]( >> https://tools.ietf.org/html/rfc21199). >> +@ref use_of_terms >> @subsection purpose Purpose >> ODP is a framework for software-based packet forwarding/filtering >> applications, and the purpose of the Packet Classifier API is to enable >> applications to program the platform hardware or software implementation to >> assist in prioritization, classification and scheduling of each packet, so >> that the software application can run faster, scale better and adhere to >> QoS requirements. >> The following API abstraction are not modelled after any existing >> product implementation, but is instead defined in terms of what a typical >> data-plane application may require from such a platform, without >> sacrificing simplicity and avoiding ambiguity. >> diff --git a/crypto_design.dox b/crypto_design.dox >> index d0f016b..ed9166d 100644 >> --- a/crypto_design.dox >> +++ b/crypto_design.dox >> @@ -15,8 +15,7 @@ This document describes the ODP Crypto API. >> Cryptography is an important part of data plane processing as many >> communication protocols make use of cryptographic functions. >> Moreover, many SoCs incorporate cryptographic hardware that can >> significantly accelerate these operations compared to their software >> equivalents as well as provide validated hardware functional correctness >> and security boundaries necessary for system-level security certifications >> such as FIPS-140 Level 2 and above. >> @section requirements Requirements >> -@subsection use_of_terms Use of Terms >> -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", >> "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this >> document are to be interpreted as described in [RFC 2119]( >> https://tools.ietf.org/html/rfc2119). >> +@ref use_of_terms >> @subsection uses_of_cryptography Uses of Cryptography >> Crypto functions cover a range of uses and capabilities designed to >> support data security, integrity, authentication, and non-repudiation. >> @subsubsection data_security Data Security >> -- >> 1.9.1 >> >> >> _______________________________________________ >> lng-odp mailing list >> lng-odp@lists.linaro.org >> http://lists.linaro.org/mailman/listinfo/lng-odp >> > >
On 2014-10-08 13:31, Mike Holmes wrote: > We only need one copy of the requirements terminology > > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> Applied. Thanks Anders > --- > boilerplate.dox | 15 +++++++++++++++ > classification_design.dox | 3 +-- > crypto_design.dox | 3 +-- > 3 files changed, 17 insertions(+), 4 deletions(-) > create mode 100644 boilerplate.dox > > diff --git a/boilerplate.dox b/boilerplate.dox > new file mode 100644 > index 0000000..5ac1616 > --- /dev/null > +++ b/boilerplate.dox > @@ -0,0 +1,15 @@ > +/* Copyright (c) 2014, Linaro Limited > + * All rights reserved > + * > + * SPDX-License-Identifier: BSD-3-Clause > + */ > + > +/** > +@page odp_definitions Definitions > + > +@tableofcontents > + > +@section use_of_terms Requirement terminology > +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). > + > +*/ > diff --git a/classification_design.dox b/classification_design.dox > index db0b273..8733144 100644 > --- a/classification_design.dox > +++ b/classification_design.dox > @@ -15,8 +15,7 @@ This document defines the Classification APIs supported by ODP. > Classification is logically composed of two stages: Parsing and Rule Matching. > Parsing takes a raw packet and validates its structure and identifies fields of interest in the various headers that comprise the layers of the packet. > Rule Matching, in turn, takes the result of parsing and sorts packets into Classes of Service (CoS) based on application-defined rule sets. > -@subsection use_of_terms Use of Terms > -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc21199). > +@ref use_of_terms > @subsection purpose Purpose > ODP is a framework for software-based packet forwarding/filtering applications, and the purpose of the Packet Classifier API is to enable applications to program the platform hardware or software implementation to assist in prioritization, classification and scheduling of each packet, so that the software application can run faster, scale better and adhere to QoS requirements. > The following API abstraction are not modelled after any existing product implementation, but is instead defined in terms of what a typical data-plane application may require from such a platform, without sacrificing simplicity and avoiding ambiguity. > diff --git a/crypto_design.dox b/crypto_design.dox > index d0f016b..ed9166d 100644 > --- a/crypto_design.dox > +++ b/crypto_design.dox > @@ -15,8 +15,7 @@ This document describes the ODP Crypto API. > Cryptography is an important part of data plane processing as many communication protocols make use of cryptographic functions. > Moreover, many SoCs incorporate cryptographic hardware that can significantly accelerate these operations compared to their software equivalents as well as provide validated hardware functional correctness and security boundaries necessary for system-level security certifications such as FIPS-140 Level 2 and above. > @section requirements Requirements > -@subsection use_of_terms Use of Terms > -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). > +@ref use_of_terms > @subsection uses_of_cryptography Uses of Cryptography > Crypto functions cover a range of uses and capabilities designed to support data security, integrity, authentication, and non-repudiation. > @subsubsection data_security Data Security > -- > 1.9.1 > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp
diff --git a/boilerplate.dox b/boilerplate.dox new file mode 100644 index 0000000..5ac1616 --- /dev/null +++ b/boilerplate.dox @@ -0,0 +1,15 @@ +/* Copyright (c) 2014, Linaro Limited + * All rights reserved + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** +@page odp_definitions Definitions + +@tableofcontents + +@section use_of_terms Requirement terminology +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). + +*/ diff --git a/classification_design.dox b/classification_design.dox index db0b273..8733144 100644 --- a/classification_design.dox +++ b/classification_design.dox @@ -15,8 +15,7 @@ This document defines the Classification APIs supported by ODP. Classification is logically composed of two stages: Parsing and Rule Matching. Parsing takes a raw packet and validates its structure and identifies fields of interest in the various headers that comprise the layers of the packet. Rule Matching, in turn, takes the result of parsing and sorts packets into Classes of Service (CoS) based on application-defined rule sets. -@subsection use_of_terms Use of Terms -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc21199). +@ref use_of_terms @subsection purpose Purpose ODP is a framework for software-based packet forwarding/filtering applications, and the purpose of the Packet Classifier API is to enable applications to program the platform hardware or software implementation to assist in prioritization, classification and scheduling of each packet, so that the software application can run faster, scale better and adhere to QoS requirements. The following API abstraction are not modelled after any existing product implementation, but is instead defined in terms of what a typical data-plane application may require from such a platform, without sacrificing simplicity and avoiding ambiguity. diff --git a/crypto_design.dox b/crypto_design.dox index d0f016b..ed9166d 100644 --- a/crypto_design.dox +++ b/crypto_design.dox @@ -15,8 +15,7 @@ This document describes the ODP Crypto API. Cryptography is an important part of data plane processing as many communication protocols make use of cryptographic functions. Moreover, many SoCs incorporate cryptographic hardware that can significantly accelerate these operations compared to their software equivalents as well as provide validated hardware functional correctness and security boundaries necessary for system-level security certifications such as FIPS-140 Level 2 and above. @section requirements Requirements -@subsection use_of_terms Use of Terms -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). +@ref use_of_terms @subsection uses_of_cryptography Uses of Cryptography Crypto functions cover a range of uses and capabilities designed to support data security, integrity, authentication, and non-repudiation. @subsubsection data_security Data Security
We only need one copy of the requirements terminology Signed-off-by: Mike Holmes <mike.holmes@linaro.org> --- boilerplate.dox | 15 +++++++++++++++ classification_design.dox | 3 +-- crypto_design.dox | 3 +-- 3 files changed, 17 insertions(+), 4 deletions(-) create mode 100644 boilerplate.dox