fma functions

["Howland Craig D (Craig)" <howland at LGSInnovations dot com>]

The libm fma and fmaf functions (libm/common/s_fma.c and sf_fma.c) do
not provide the required function.
 
double fma(double x, double y, double z);
 
They are supposed to return the value (x * y) + z calculated as if to
infinite precision and then rounded according to the current rounding
direction.  However, all they do is "return (x * y) + z;", not at all
attempting to provide the special service that is the reason for
their existence.  ("Let the implementation handle this.", says
sf_fma.c!)
 
I noticed this because they are among the functions that are missing
their documentation, which I have been working to add to make
the libm docs complete.
 
I see two possible approaches to take with respect to this problem:
1)  Remove the functions (until adequate replacements can be found).
2)  Point out their shortcomings in the documentation and recommend
that they not be used.
 
You might ask why I did not list the obvious third alternative of
fixing them now.  The easy reason is that I don't think that we can.
FreeBSD has an fmal() function that does what is required, but it
makes use of fenv calls (e.g. fegetround()) to make the answer come
out right.  Since Newlib does not currently have the fenv functions,
we could not borrow the FreeBSD code unless we also got fenv stuff.
Adding fenv will be much work because of the many supported platforms,
so I don't view it as a viable short-term solution.
  
Personally, I prefer the first approach.  It is bad for someone to
fool themselves by using a function that does not do what it is
supposed to.  Sure, it does the basic * and +, but the only reason
somebody would bother to call the function instead of putting
"(x * y) + z;" straight into their code is that they needed the LSb
to come out just right.  Providing a function that does not do what
is expected is very bad.  Additionally, having a hole that needs to
be filled is more likely to get someone to fix it than hoping that
someone notices the bug report line in the file.  Lastly, removing it
would be a good thing, as anyone actually using it would be forced to
notice when they updated versions.  If they wanted and did not mind
the bad behavior, they could easily (albeit manually) add the old
versions in to keep using them.
 
So finally to the approach question:  should the functions be
removed, or should they be kept with the BUG being documented?
(I suppose that a variation is to add keep the C files in CVS, adding
the bug report--which I already have, by the way--but removing them
from the makefiles so that a user would need to consciously add them.)
 
Craig