On Mon, Dec 19, 2022 at 11:37:19AM +0100, Thomas Monjalon wrote: > 15/12/2022 14:58, Bruce Richardson: > > On Thu, Dec 15, 2022 at 02:36:51PM +0100, Thomas Monjalon wrote: > > > 15/12/2022 10:44, Bruce Richardson: > > > > On Wed, Dec 14, 2022 at 09:38:45AM -0800, Tyler Retzlaff wrote: > > > > > On Tue, Dec 13, 2022 at 06:27:25PM +0000, Bruce Richardson wrote: > > > > > > For future standardization on the "uint" name for unsigned values > > > > > > rather > > > > > > than the existing "u64" one, we can for now: > > > > > > * rename all internal values to use uint rather than u64 > > > > > > * add new function names to alias the existing u64 ones > > > > > > > > > > > > Suggested-by: Morten Brørup <m...@smartsharesystems.com> > > > > > > Signed-off-by: Bruce Richardson <bruce.richard...@intel.com> > > > > > > > > > > when adding __rte_experimental api i have been asked to add the > > > > > following boilerplate documentation block. i'm not pushing it, just > > > > > recalling it is what i get asked for, so in case it's something we do? > > > > > see lib/eal/include/rte_thread.h as an example > > > > > > > > > > > > > > > ``` > > > > > * @warning > > > > > * @b EXPERIMENTAL: this API may change without prior notice. > > > > > ``` > > > > > > > > > > > > > Ok, thanks for the notice. > > > > > > > > Actually, related to this, since we are adding these functions as > > > > aliases > > > > for existing stable functions, I would like to see these being added > > > > not as > > > > experimental. The reason for that, is that while they are experimental, > > > > we > > > > cannot feasibly mark the old function names as deprecated. :-( > > > > > > > > Adding Thomas and David on CC for their thoughts. > > > > > > Is it related to telemetry? > > > > > > In general, yes we cannot deprecate something if there is no stable > > > replacement. > > > The recommended step is to introduce a new experimental API > > > and deprecate the old one when the new API is stable. > > > > > Yes, understood. > > What we are really trying to do here is to rename an API, by process of > > adding the new API and then marking the old one as deprecated. The small > > issue is that adding the new one it is by default experimental, meaning we > > need to wait for deprecating old one. Ideally, as soon as the new API is > > added, we would like to point people to use that, but can't really do so > > while it is experimental. > > > > --- > > > > By way of explicit detail, Morten pointed out the inconsistency in the > > telemetry APIs and types: > > > > * we have add_*_int, which takes a 32-bit signed value > > * we have add_*_u64 which takes 64-bit unsigned (as name suggests). > > > > The ideal end-state is to always use 64-bit values (since there is no space > > saving from 32-bit as a union is used), and just name everything as "int" > > or "uint" for signed/unsigned. The two big steps here are: > > > > * expanding type of the "int" functions to take 64-bit parameters - this is > > ABI change but not API one, since existing code will happily promote > > values on compile. Therefore, we just use ABI versioning to have a 32-bit > > version for older linked binaries. > > * the rename of the rte_tel_data_add_array_u64 and > > rte_tel_data_add_dict_u64 to *_uint variants. Though keeping > > compatibility is easier, as we can just add new functions, the overall > > process is slower since the new functions technically should be added as > > experimental - hence the email. For the case of function renaming, do we > > still need to have the "renamed" versions as experimental initially? > > If a function is simply renamed, I think there is no need for the > experimental step. > Would we keep an alias with the old name for some time? > Yes, the old name should go through the deprecation process. No hurry with removal.
/Bruce
