Changes to libsframe ABI

Changes to libsframe ABI

[Indu Bhagat]

Hi,

I have been contemplating a change to the libsframe ABI which is 
breaking it in theory, but should be fine in practice. I need some 
inputs on whether this is OK to do.

I would like to make an existing API sframe_get_funcdesc_with_addr () 
static. The interface provided by this function is not a healthy 
abstraction to expose: the return type is sframe_func_desc_entry, which 
is defined in include/sframe.h (the SFrame binary format definition). 
This ties up the library in a undesirable way.  Most importantly, this 
function should technically not be directly necessary for _any_ external 
customer, like a stack tracer.  A stack tracer should only need to do a 
sframe_find_fre ().

I would like to make it static because this API should only be needed 
(and used) internally in the library, at least in the current form.

Is it okay to make such a change ?  The first release of libsframe was 
Binutils 2.40. I do not expect any users of 
sframe_get_funcdesc_with_addr () out there currently. IMO, this is OK to 
do. WDYT ?

A larger question still looms over as well: The library is young at this 
time, and making guarantees of a stable ABI in the current shape looks 
limiting to me. Apart from the above change, I would also like to make 
some further changes to other existing APIs (which will also break the 
ABI). How can this be managed without causing pain ?

Thanks,
Indu

Re: Changes to libsframe ABI

[Nick Clifton]

Hi Indu,

> I would like to make an existing API sframe_get_funcdesc_with_addr () static. The interface provided by this function is not a healthy abstraction to expose: the return 
> type is sframe_func_desc_entry, which is defined in include/sframe.h (the SFrame binary format definition). This ties up the library in a undesirable way.  Most 
> importantly, this function should technically not be directly necessary for _any_ external customer, like a stack tracer.  A stack tracer should only need to do a 
> sframe_find_fre ().
> 
> I would like to make it static because this API should only be needed (and used) internally in the library, at least in the current form.
> 
> Is it okay to make such a change ?  The first release of libsframe was Binutils 2.40. I do not expect any users of sframe_get_funcdesc_with_addr () out there currently. 
> IMO, this is OK to do. WDYT ?

I think that it can be done, but you should allow for the possibility
that there are programs out there that are using the function.  So I
would suggest:

   * Increase the version number of the library (to version N+1).
   * Rename sframe_get_funcdesc_with_addr to something else, such
     as sframe_get_funcdesc_with_addr_internal.  Make this new function
     static, or use the hidden visibility if you need it accessible
     from everywhere inside libsframe.
   * Update all places where the old function name was used in the libsframe
     library.
   * Create a new dummy function called sframe_get_funcdesc_with_addr and
     have it just return null or whatever error value it was supposed to
     return if things went wrong.  Change the return type of the function
     to void *.  Add a comment to the prototype of the function in whichever
     header file documents it.  The comment should indicate that the
     function is deprecated and will be removed in version N+2.
   * Wait a year and release version N+2 without the function...


> A larger question still looms over as well: The library is young at this time, and making guarantees of a stable ABI in the current shape looks limiting to me. Apart from 
> the above change, I would also like to make some further changes to other existing APIs (which will also break the ABI). How can this be managed without causing pain ?

This sounds like a situation where you would want to use symbol versioning.
You could have old and new versions of functions with different ABIs, and
applications can be built to use the version that they prefer.  The glibc
library for example makes extensive use of this feature.

Cheers
   Nick