libsframe: remove sframe_get_funcdesc_with_addr API

This is an incompatible ABI change in libsframe.

The interface provided by this function is not a healthy abstraction to
expose: the return type 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 a stack tracer.  A
stack tracer will likely only need to do a sframe_find_fre ().

Rename the API to continue to use the functionality internally in the
library.  bfd/linker does not use this function.

Change the return type of the previous definition and make a note about
its planned deprecation.

include/
	* sframe-api.h:  Change return type of sframe_get_funcdesc_with_addr.
	Add comment for intention to deprecate.
libsframe/
	*sframe.c (sframe_get_funcdesc_with_addr): Change return type
	and set error code. This API is deprecated.
        (sframe_get_funcdesc_with_addr_internal): New definition for
	internal use.
	(sframe_find_fre): Use sframe_get_funcdesc_with_addr_internal
	instead.

include/sframe-api.h

@@ -133,10 +133,13 @@ sframe_decoder_get_fixed_fp_offset (sframe_decoder_ctx *dctx);
 extern int8_t
 sframe_decoder_get_fixed_ra_offset (sframe_decoder_ctx *dctx);
 
-/* Find the function descriptor entry which contains the specified address.  */
-extern sframe_func_desc_entry *
-sframe_get_funcdesc_with_addr (sframe_decoder_ctx *dctx,
-			       int32_t addr, int *errp);
+/* Find the function descriptor entry which contains the specified address.
+
+   Note: This function is deprecated and will be removed from future release
+   X+2 of the library.  */
+extern void *
+sframe_get_funcdesc_with_addr (sframe_decoder_ctx *dctx, int32_t addr,
+			       int *errp);
 
 /* Find the SFrame Frame Row Entry which contains the PC.  Returns
    SFRAME_ERR if failure.  */

libsframe/sframe.c

@@ -950,12 +950,24 @@ sframe_decoder_get_fixed_ra_offset (sframe_decoder_ctx *ctx)
   return dhp->sfh_cfa_fixed_ra_offset;
 }
 
+/* Find the function descriptor entry which contains the specified address
+   ADDR.
+   This function is deprecated and will be removed from libsframe.so.2.  */
+
+void *
+sframe_get_funcdesc_with_addr (sframe_decoder_ctx *ctx __attribute__ ((unused)),
+			       int32_t addr __attribute__ ((unused)),
+			       int *errp)
+{
+  return sframe_ret_set_errno (errp, SFRAME_ERR_INVAL);
+}
+
 /* Find the function descriptor entry starting which contains the specified
    address ADDR.  */
 
-sframe_func_desc_entry *
-sframe_get_funcdesc_with_addr (sframe_decoder_ctx *ctx,
-			       int32_t addr, int *errp)
+static sframe_func_desc_entry *
+sframe_get_funcdesc_with_addr_internal (sframe_decoder_ctx *ctx, int32_t addr,
+					int *errp)
 {
   sframe_header *dhp;
   sframe_func_desc_entry *fdp;
@@ -1053,7 +1065,7 @@ sframe_find_fre (sframe_decoder_ctx *ctx, int32_t pc,
     return sframe_set_errno (&err, SFRAME_ERR_INVAL);
 
   /* Find the FDE which contains the PC, then scan its fre entries.  */
-  fdep = sframe_get_funcdesc_with_addr (ctx, pc, &err);
+  fdep = sframe_get_funcdesc_with_addr_internal (ctx, pc, &err);
   if (fdep == NULL || ctx->sfd_fres == NULL)
     return sframe_set_errno (&err, SFRAME_ERR_DCTX_INVAL);