From: Bill Fischofer [mailto:[email protected]] Sent: Monday, October 23, 2017 5:55 PM To: Linaro/odp <[email protected]> Cc: Savolainen, Petri (Nokia - FI/Espoo) <[email protected]>; Mention <[email protected]> Subject: Re: [Linaro/odp] [PATCH API-NEXT v1] api: pktio: clarify odp_pktio_config() restrictions (#247)
On Mon, Oct 23, 2017 at 8:00 AM, muvarov <[email protected]> wrote: > From: "Savolainen, Petri (Nokia - FI/Espoo)" > > > > -----Original Message----- > > From: lng-odp [mailto:[email protected]] On Behalf Of > > Github ODP bot > > Sent: Friday, October 20, 2017 5:00 PM > > To: [email protected] > > Subject: [lng-odp] [PATCH API-NEXT v1 1/1] api: pktio: clarify > > odp_pktio_config() restrictions > > > > From: Bill Fischofer > > > > Add clarification that odp_pktio_config() cannot be used to > > configure options that are not supported, as indicated by > > odp_pktio_capability(). > > > > Signed-off-by: Bill Fischofer > > --- > > /** Email created from pull request 247 (Bill-Fischofer-Linaro:pktio- > > config-doc) > > ** https://github.com/Linaro/odp/pull/247 > > ** Patch: https://github.com/Linaro/odp/pull/247.patch > > ** Base sha: e3108af2f0b58c2ceca422b418439bba5de04b11 > > ** Merge commit sha: fc118350c5aa950e860cd53a6104b0571aa2e59b > > **/ > > include/odp/api/spec/packet_io.h | 3 ++- > > 1 file changed, 2 insertions(+), 1 deletion(-) > > > > diff --git a/include/odp/api/spec/packet_io.h > > b/include/odp/api/spec/packet_io.h > > index 52af646a6..48dd76f28 100644 > > --- a/include/odp/api/spec/packet_io.h > > +++ b/include/odp/api/spec/packet_io.h > > @@ -605,7 +605,8 @@ unsigned odp_pktio_max_index(void); > > * interface setup sequence. Use odp_pktio_capability() to query > > configuration > > * capabilities. Use odp_pktio_config_init() to initialize > > * configuration options into their default values. Default values are > > used > > - * when 'config' pointer is NULL. > > + * when 'config' pointer is NULL. Attempting to configure options that > > are > > + * not supported, as indicated by odp_pktio_capability(), will be > > rejected. > > Why not leave this as undefined behavior (as is usual for spec violations)? > This addition would say that it's OK to violate the capability spec, since > params are checked anyway (e.g. not use capability but iterate through param > values until success). > > So are you saying the text should be left as is or that you'd prefer the clarification say explicitly that behavior is undefined in this case? It can be left as is, since we should not repeat on every call that "breaking this spec results undefined behavior". That statement (or entire chapter) could be added to beginning of user guide/ API main page (odp/doc/application-api-guide/output/html/index.html). Something like: API specification principles ---------------------------- Both application and implementation must comply with the API specification. If not otherwise documented, results are undefined if application acts against the specification. For example, if an application passes bad parameters to a function one implementation may report an error, while another would not check those (to maximize performance) but would just crash while using the bad values... So, we'd document those rare cases when API spec guarantees that it's OK to pass bad parameters. By default, it would not be OK and thus application should check capabilities and limit it's requests based on those. -Petri
