> > /**
> > * Deprecated API definitions
> > *
> > * Some API definitions may be deprecated by this or a previous API
> version.
> > * This macro controls if those are enabled (and visible to the
> application)
> > * or disabled.
> > *
> > * * 0: Deprecated API definitions are disabled
> > * * 1: Deprecated API definitions are enabled
> > */
> > #define ODP_DEPRECATED 0
> >
> > If an implementation does not use autotools, it may generate the same
> deprecated.h file with the same content anyway it likes (or hard code the
> file into the repo).
>
> I disagree strongly. Such API header files should contain pure C
> code, and not anything that requires the file to be run through
> autoconf or for people to maintain their own set of API header files.
> Things like @ODP_VERSION_API_GENERATION@ can be defined to a real
> concrete value. Things like ODP_DEPRECATED can also be defined to a
> real value .. conditional on the compiler identification macro.
This is not far from other values being implementation specific. For example,
the API spec defines that there is ODP_QUEUE_INVALID defined, but does not
dictate the value (an ABI spec does when building for ABI compat). An
implementation needs to make sure that application sees the macro through
odp_api.h. So, it needs to have a (build) mechanism for that.
Similarly, API spec defines that ODP_DEPRECATED has value of 1, when deprecated
APIs are present. Implementation needs to make that definition visible
(somehow) through odp_api.h, when those APIs are enabled. Currently, in
odp-linux, we use automake for that.
>
> >
> > Second, this patch does not take any position how long a deprecated API
> remains there. The patch enables application build *with* or *without*
> deprecated APIs, so that it's easy to verify if deprecated APIs are
> (still) used in application or not. For example, I missed couple of those
> in IPSEC example app porting previously, but now with this option those
> were caught.
>
> I am confused again. Use of the compiler's support for "deprecated"
> will cause a warning to be emitted if application code is still
> written to use said deprecated APIs. Are you saying this is not good
> enough? Or, are you trying to create a way to still support some idea
> of "deprecated" in the case that there is no support from the
> compiler?
It's not good enough, and it depends on an non-standard compiler feature when
that dependency is not absolutely mandatory for what we are trying to achieve.
1) New API version. Some definition is now deprecated.
2) By default, --enable-deprecated=no. Old definitions are #ifdef'ed away.
Application build fails if it still uses a deprecated definition.
3.1) Update the application to use new API definitions. This gives best
performance, OR ...
3.2) Don't change application this time, but build it with
--enable-deprecated=yes. Application builds, but may suffer from lower
performance as implementation needs to include both code path the old and the
new. The "new API" is now the default code path. The "old API" is likely to be
less used/tested/supported - it will be removed soon anyway.
4) New API version. The deprecated definition (deprecated in 1) above) may be
now removed for good. All application need to upgrade. Implementation may
delete the #ifdef'ed old code path.
I think this is #if ODP_DEPRECATED is simple and strong way to enforce
deprecation in API ...
+#if ODP_DEPRECATED
/** @deprecated Use aes_cbc instead */
uint32_t aes128_cbc : 1;
/** @deprecated Use aes_gcm instead */
uint32_t aes128_gcm : 1;
+#endif
... and gives implementation chance to optimize for the new API (the new
default).
+#if ODP_DEPRECATED
case ODP_AUTH_ALG_AES128_GCM:
+ if (param->cipher_alg == ODP_CIPHER_ALG_AES128_GCM)
+ aes_gcm = 1;
+ /* Fallthrough */
+#endif
+ case ODP_AUTH_ALG_AES_GCM:
/* AES-GCM requires to do both auth and
* cipher at the same time */
- if (param->cipher_alg == ODP_CIPHER_ALG_AES_GCM ||
- param->cipher_alg == ODP_CIPHER_ALG_AES128_GCM) {
+ if (param->cipher_alg == ODP_CIPHER_ALG_AES_GCM || aes_gcm) {
session->auth.func = null_crypto_routine;
In this example above, #if ODP_DEPRECATED allows implementation to do if(x == y
|| 0), instead of if(x == y || x == z). Effectively, one compare instead of two.
I think it's better to clearly select: either deprecated APIs are enabled or
disabled. So, that both application and implementation know which spec is used
(the old or the new).
-Petri
