My opinion is that "undefined behavior" makes sense on the fast processing path (to limit checks, etc.) and makes no sense on slow path, especially on configuration API.
On 24 October 2017 at 11:17, Savolainen, Petri (Nokia - FI/Espoo) <petri.savolai...@nokia.com> wrote: > > > From: Bill Fischofer [mailto:notificati...@github.com] > Sent: Monday, October 23, 2017 5:55 PM > To: Linaro/odp <o...@noreply.github.com> > Cc: Savolainen, Petri (Nokia - FI/Espoo) <petri.savolai...@nokia.com>; > Mention <ment...@noreply.github.com> > 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 <notificati...@github.com> wrote: > >> From: "Savolainen, Petri (Nokia - FI/Espoo)" >> >> >> > -----Original Message----- >> > From: lng-odp [mailto:lng-odp-boun...@lists.linaro.org] On Behalf Of >> > Github ODP bot >> > Sent: Friday, October 20, 2017 5:00 PM >> > To: lng-odp@lists.linaro.org >> > 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 > >
