@@ -64,10 +64,10 @@ Minimizing pathlength in API design involves several considerations:
ODP APIs MAY be implemented as preprocessor macros and/or inline functions.
This is especially true for accessor functions that are designed to provide getters/setters for object meta data.
- Limiting parameter validation and error-checking processing.
- While useful for development and debugging, providing “bullet-proof” APIs that perform extensive parameter validation and error checking is often inappropriate.
+ While useful for development and debugging, providing "bullet-proof" APIs that perform extensive parameter validation and error checking is often inappropriate.
While validations that can be performed statically at compile time or at little to no runtime cost SHOULD be considered, APIs MAY choose to leave behavior as undefined when presented with invalid parameters in the interest of runtime efficiency.
-One of the reasons for using abstract types is to avoid having implementation knowledge “bleed through” the API, leading to possible parameter errors.
+One of the reasons for using abstract types is to avoid having implementation knowledge "bleed through" the API, leading to possible parameter errors.
When one API returns an opaque token to an application it is reasonable to expect that the application can pass that token to subsequent APIs without needing expensive runtime validation.
ODP provides the helper APIs ODP_STATIC_ASSERT(cond,msg) and ODP_ASSERT(cond,msg) that SHOULD be used in implementations for performing appropriate validation.
@@ -114,7 +114,7 @@ static inline odp_foo_t _odp_foo_from_bar(odp_bar_t bar)
ODP APIs typically have prototypes of the form:
@code
-odp_return_type_t odp_api(p1_type p1, p2_type p2, …);
+odp_return_type_t odp_api(p1_type p1, p2_type p2, ...);
@endcode
Where:
@@ -134,7 +134,7 @@ This convention allows callers to easily determine success/failure of a call wit
So, for example, an attempt to allocate a buffer from a buffer pool might return ODP_BUFFER_INVALID if the call was unsuccessful and errno could then be set to an appropriate reason (no storage available (ENOMEM, ENOBUFS), pool not recognized (EINVAL), etc.).
In general APIs are free to define their own errno usage conventions and values or reuse standard errno values when appropriate.
-When “standard” codes exist, implementations SHOULD make use of them so that standard utility functions like perror() can decode them intelligently.
+When "standard" codes exist, implementations SHOULD make use of them so that standard utility functions like perror() can decode them intelligently.
There are, however, a small set of standard codes that are commonly used.
One errno value that MUST be present for all APIs is ODP_FUNCTION_NOT_AVAILABLE.
This special reason code is used to indicate that the underlying implementation does not support the requested API, and SHOULD be equated to ENOSYS.
@@ -168,8 +168,8 @@ When an interface is defined in a header file and is intended to to be reused in
int start_of_function_scope;
...
if (foo == bar) {
- int start_of_block_scope;
- ...
+ int start_of_block_scope;
+ ...
}
}
@endcode
@@ -195,7 +195,7 @@ At the same time, APIs SHOULD reflect essential needs of data plane application
How to draw this line is a judgement call based on experience but API designers MUST take implementation practicalities into consideration when designing APIs to ensure that APIs and features can be implemented efficiently on a wide variety of underlying platforms.
This is one of the reasons why some features MAY be defined as OPTIONAL.
While allowed, the proliferation of OPTIONAL features SHOULD be avoided to enable broad application portability across many implementations.
-At the same time, a “least common denominator” approach MUST NOT be taken as that defeats the purpose of providing higher-level abstractions in APIs.
+At the same time, a "least common denominator" approach MUST NOT be taken as that defeats the purpose of providing higher-level abstractions in APIs.
@subsection odp_deprecated ODP DEPRECATED
A deprecated API will remain marked as such in the public API using #ODP_DEPRECATED for two release cycles for the #ODP_VERSION_API_MAJOR number.
@@ -52,7 +52,7 @@ quality and review new patches to maintain that good quality.
* When Maintainers accept code, they have to deal with it until they die or rip
it out (so its important that they understand what the code does and why they
need it). The contributor shall convince the maintainer to take their code (the
-maintainer should feel like he would be stupid to not accept the code…)
+maintainer should feel like he would be stupid to not accept the code)
=== Release Manager ===
@@ -65,7 +65,7 @@ Release.
The roadmap shall state projected future releases and the expected content.
== Steering Committee (SC)
-* Defining the requirements for the project’s shared resources, email
+* Defining the requirements for the project's shared resources, email
lists and the homepage.
* Speaking on behalf of the project.
* Resolving license disputes regarding products of the project.
@@ -76,24 +76,24 @@ content).
=== Patch approval
Reviewed-by is only replied to the list after inspecting the code. If you have
-review comments they should be constructive and not just saying “no”.
+review comments they should be constructive and not just saying "no".
Reviewed-by and Signed-off-by implies that you are co-responsible for any bugs
found in the code.
-If you don’t respond you are assumed to agree with the patch.
+If you don't respond you are assumed to agree with the patch.
== Voting ==
Voting is necessary if consensus not has been reached. Must have established
quorum.
-* “Yes”, “Agree”,"+1" the action should be performed.
+* "Yes", "Agree","+1" the action should be performed.
In general, this vote also indicates a willingness on the behalf of the voter in
-“making it happen”
+"making it happen"
-* “Abstain” This vote indicates that the voter abstains.
+* "Abstain" This vote indicates that the voter abstains.
The voter has no interest or does not participate in the vote.
-* “No”, “Disagree” "-1" the action should not be performed.
+* "No", "Disagree" "-1" the action should not be performed.
On issues where consensus is required, this vote counts as a veto. All vetoes
must contain an explanation of why the veto is appropriate. Vetoes with no
explanation are void. It may also be appropriate for a -1 vote to include an
@@ -271,9 +271,9 @@ result in faster operation and/or less memory used.
odp_tm_params_init(&tm_params); // <1>
tm_params.pktio = egress_pktio;
- tm = odp_tm_create(“Example TM”, &tm_params);
+ tm = odp_tm_create("Example TM", &tm_params);
-/* create 5 input queues here – two at priority 1 and three at priority 2. */
+/* create 5 input queues here - two at priority 1 and three at priority 2. */
odp_tm_queue_params_init(&queue_params);
queue_params.priority = 1;
@@ -287,7 +287,7 @@ result in faster operation and/or less memory used.
odp_tm_node_params_init(&node_params); // <2>
node_params.level = 1;
- tm_node_1 = odp_tm_node_create(tm, “TmNode1”, &node_params);
+ tm_node_1 = odp_tm_node_create(tm, "TmNode1", &node_params);
odp_tm_queue_connect(tmq_A1, tm_node_1); // <3>
odp_tm_queue_connect(tmq_B1, tm_node_1);
@@ -303,13 +303,13 @@ of common scheduler parameters. NOTE that this uses some pseudocode below
instead of real C code so as to be more concise. */
odp_tm_sched_params_init(&sched_params); // <4>
- sched_params.sched_modes = { ODP_TM_FRAME_BASED_WEIGHTS, … };
- sched_params.sched_weights = { 8, 8, 8, … };
- sched_profile_RR = odp_tm_sched_create(“SchedProfileRR”, &sched_params);
+ sched_params.sched_modes = { ODP_TM_FRAME_BASED_WEIGHTS, ... };
+ sched_params.sched_weights = { 8, 8, 8, ... };
+ sched_profile_RR = odp_tm_sched_create("SchedProfileRR", &sched_params);
- sched_params.sched_modes = { ODP_TM_BYTE_BASED_WEIGHTS, … };
- sched_params.sched_weights = { 8, 8, 8, … };
- sched_profile_FQ = odp_tm_sched_create(“SchedProfileFQ”, &sched_params);
+ sched_params.sched_modes = { ODP_TM_BYTE_BASED_WEIGHTS, ... };
+ sched_params.sched_weights = { 8, 8, 8, ... };
+ sched_profile_FQ = odp_tm_sched_create("SchedProfileFQ", &sched_params);
odp_tm_queue_sched_config(tm_node_1, tmq_A1, sched_profile_RR); // <5>
odp_tm_queue_sched_config(tm_node_1, tmq_B1, sched_profile_RR);
@@ -319,14 +319,14 @@ instead of real C code so as to be more concise. */
odp_tm_node_params_init(&node_params); // <6>
node_params.level = 2;
- tm_node_2 = odp_tm_node_create(tm, “TmNode2”, &node_params);
+ tm_node_2 = odp_tm_node_create(tm, "TmNode2", &node_params);
odp_tm_node_connect(tm_node_1, tm_node_2); // <7>
odp_tm_sched_params_init(&sched_params); // <8>
- sched_params.sched_modes = { ODP_TM_BYTE_BASED_WEIGHTS, … };
- sched_params.sched_weights = { 8, 16, 24, … };
- sched_profile_WFQ = odp_tm_sched_create(“SchedProfileWFQ”, &sched_params);
+ sched_params.sched_modes = { ODP_TM_BYTE_BASED_WEIGHTS, ... };
+ sched_params.sched_weights = { 8, 16, 24, ... };
+ sched_profile_WFQ = odp_tm_sched_create("SchedProfileWFQ", &sched_params);
odp_tm_node_sched_config(tm_node_2, tm_node_1, sched_profile_WFQ); // <9>
----
@@ -334,11 +334,11 @@ instead of real C code so as to be more concise. */
<1> Create a tm system, since that is a precursor to creating tm_queues.
<2> Create a Node #1
<3> Connect the Queue(s) to the Node -> odp_tm_queue_connect()
-<4> Create two sets of scheduler params – one implementing Round Robin (since
-all weights are the same – namely 8) and the second implementing Fair Queuing.
+<4> Create two sets of scheduler params - one implementing Round Robin (since
+all weights are the same - namely 8) and the second implementing Fair Queuing.
<5> Associate the Scheduler to the Node and the Queue(s) -> odp_tm_queue_sched_config()
-Use the Round Robin profile for the priority 1 fan-in’s and Fair Queuing
+Use the Round Robin profile for the priority 1 fan-ins and Fair Queuing
for the priority 2 fan-ins.
<6> Create a second Node #2
Suggested-by: Zoltan Kiss <zoltan.kiss@linaro.org> Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> --- doc/application-api-guide/api_guide_lines.dox | 14 ++++++------ doc/process-guide/bylaws-guide.adoc | 16 +++++++------- doc/users-guide/users-guide-tm.adoc | 32 +++++++++++++-------------- 3 files changed, 31 insertions(+), 31 deletions(-)