File : s-libsin-ada.ads
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT COMPILER COMPONENTS --
4 -- --
5 -- S Y S T E M . L I B M _ S I N G L E --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 2014-2016, Free Software Foundation, Inc. --
10 -- --
11 -- GNAT is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 3, or (at your option) any later ver- --
14 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. --
17 -- --
18 -- --
19 -- --
20 -- --
21 -- --
22 -- You should have received a copy of the GNU General Public License and --
23 -- a copy of the GCC Runtime Library Exception along with this program; --
24 -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
25 -- <http://www.gnu.org/licenses/>. --
26 -- --
27 -- GNAT was originally developed by the GNAT team at New York University. --
28 -- Extensive contributions were provided by Ada Core Technologies Inc. --
29 -- --
30 ------------------------------------------------------------------------------
31
32 -- This is the Ada Cert Math specific version of s-libsin.ads
33
34 with System.Libm_Prefix;
35
36 -- @llrset Libm
37 -- LLR Libm
38 -- ========
39
40 package System.Libm_Single is
41 pragma Pure;
42
43 package SLP renames System.Libm_Prefix;
44
45 -- This package provides an implementation of the various C99 functions
46 -- used in the Ada run time. It is intended to be used for targets that
47 -- do not have a C math library, or where the C math library isn't of
48 -- sufficient quality and accuracy to meet Ada requirements.
49
50 -- In case of error conditions, NaNs or infinities are returned as
51 -- recommended in clause F.9 of the C99 standard. When called from C code,
52 -- the implementation behaves as if the FENV_ACCESS state is off, assuming
53 -- default rounding behavior and exception behavior.
54
55 -- The following C99 elementary functions are provided for single
56 -- precision (with the "f" suffix):
57
58 -- Acos, Acosh, Asin, Asinh, Atan, Atan2, Atanh, Cosh, Exp, Exp2, Log,
59 -- Log1p, Log2, Pow, Sin, Sinh, Tan, Tanh
60
61 -- All functions with a NaN argument return a NaN result, except where
62 -- stated otherwise. Unless otherwise specified, where the symbol +- occurs
63 -- in both an argument and the result, the result has the same sign as
64 -- the argument.
65
66 -- Each function lists C special values, Ada expected values as well as
67 -- Ada accuracy requirements the function meets. For accuracy requirements
68 -- the maximum relative error (abbreviated as MRE) is given, as well as
69 -- the domain for which the accuracy is guaranteed, where applicable.
70 -- The maximum relative error is expressed as multiple of Eps,
71 -- where Eps is Float'Model_Epsilon.
72
73 -- What about principal branch ???
74
75 ----------
76 -- Acos --
77 ----------
78
79 function Acos (X : Float) return Float
80 with Export, Convention => C, External_Name => SLP.Prefix & "acosf";
81 -- @llr acos (Float) Special Values
82 -- The Acos function shall return the following special values:
83 --
84 -- C99 special values:
85 -- Acos (1) = +0
86 -- Acos (x) = NaN if abs (x) > 1
87 --
88 -- Ada expected values:
89 -- Acos (0) = Pi/2.0 (tightly approximated)
90 -- Acos (-1) = Pi (tightly approximated)
91 -- Acos (x) return a result in [0, Pi] radians
92 --
93 -- @llr acos (Float) Accuracy
94 -- The Acos function shall return the inverse cosine of <X> with the
95 -- following accuracy:
96 --
97 -- Ada accuracy requirements:
98 -- MRE <= 4.0 * Eps
99
100 -----------
101 -- Acosh --
102 -----------
103
104 function Acosh (X : Float) return Float
105 with Export, Convention => C, External_Name => SLP.Prefix & "acoshf";
106 -- @llr acosh (Float) Special Values
107 -- The Acosh function shall return the following special values:
108 --
109 -- C99 special values:
110 -- Acosh (1) = +0
111 -- Acosh (x) = NaN if abs X > 1
112 -- Acosh (+INF) = +INF
113 --
114 -- @llr acosh (Float) Accuracy
115 -- The Acosh function shall return the inverse hyperbolic tangent of <X>
116 -- with the following accuracy:
117 --
118 -- Ada accuracy requirements:
119 -- MRE <= 8.0 * Eps
120
121 ----------
122 -- Asin --
123 ----------
124
125 function Asin (X : Float) return Float
126 with Export, Convention => C, External_Name => SLP.Prefix & "asinf";
127 -- @llr asin (Float) Special Values
128 -- The Asin function shall return the following special values:
129 --
130 -- C99 special values:
131 -- Asin (+-0) = +-0
132 -- Asin (x) = NaN if abs (x) > 1
133 --
134 -- Ada expected values:
135 -- Asin (1) = Pi/2.0 (tightly approximated)
136 -- Asin (-1) = -Pi/2 (tightly approximated)
137 -- Asin (x) return a result in [-Pi/2, Pi/2] radians
138 --
139 -- @llr asin (Float) Accuracy
140 -- The Asin function shall return the inverse sine of <X> with the
141 -- following accuracy:
142 --
143 -- Ada accuracy requirements:
144 -- MRE <= 4.0 * Eps
145
146 -----------
147 -- Asinh --
148 -----------
149
150 function Asinh (X : Float) return Float
151 with Export, Convention => C, External_Name => SLP.Prefix & "asinhf";
152 -- @llr asinh (Float) Special Values
153 -- The Asinh function shall return the following special values:
154 --
155 -- C99 special values:
156 -- Asinh (0) = 0
157 -- Asinh (+INF) = +INF
158 --
159 -- @llr asinh (Float) Accuracy
160 -- The Asinh function shall return the inverse hyperbolic sine of <X>
161 -- with the following accuracy:
162 --
163 -- Ada accuracy requirements:
164 -- MRE <= 8.0 * Eps
165
166 ----------
167 -- Atan --
168 ----------
169
170 function Atan (X : Float) return Float
171 with Export, Convention => C, External_Name => SLP.Prefix & "atanf";
172 -- @llr atan (Float) Special Values
173 -- The Atan function shall return the following special values:
174 --
175 -- C99 special values:
176 -- Atan (+-0) = +-Pi
177 -- Atan2 (+-INF) = +-0.5 * Pi
178 --
179 -- C expected values:
180 -- Atan (x) return a result in [-Pi/2, Pi/2]
181
182 -----------
183 -- Atan2 --
184 -----------
185
186 function Atan2 (Y : Float; X : Float) return Float
187 with Export, Convention => C, External_Name => SLP.Prefix & "atan2f";
188 -- @llr atan2 (Float; Float) Special Values
189 -- The Atan2 function shall return the following special values:
190 --
191 -- C99 special values:
192 -- Atan2 (+-0, -0) = +-Pi
193 -- Atan2 (+-0, +0) = +-0
194 -- Atan2 (+-0, x) = +-Pi, if x < 0
195 -- Atan2 (+-0, x) = +-0, if x > 0
196 -- Atan2 (y, +-0) = -0.5 * Pi, if y < 0
197 -- Atan2 (y, +-0) = 0.5 * Pi, if y > 0
198 -- Atan2 (+-y, -INF) = +-Pi, if y > 0 and y is finite
199 -- (tightly approximated)
200 -- Atan2 (+-y, -INF) = +-0, if y < 0 and y is finite
201 -- Atan2 (+-INF, x) = +-0.5 * Pi, if x is finite
202 -- (tightly approximated)
203 -- Atan2 (+-INF, -INF) = +-0.75 * Pi (tightly approximated)
204 -- Atan2 (+-INF, +INF) = +-0.25 * Pi (tightly approximated)
205 --
206 -- Ada expected values:
207 -- Atan2 (y, x) return a result in [-Pi, Pi]
208 --
209 -- @llr atan2 (Float; Float) Accuracy
210 -- The Atan2 function shall return the inverse tangent of <Y> / <X>
211 -- with the following accuracy:
212 --
213 -- Ada accuracy requirements:
214 -- MRE <= 4.0 * Eps
215
216 -----------
217 -- Atanh --
218 -----------
219
220 function Atanh (X : Float) return Float
221 with Export, Convention => C, External_Name => SLP.Prefix & "atanhf";
222 -- @llr atanh (Float) Special Values
223 -- The Atanh function shall return the following special values:
224 --
225 -- C99 special values:
226 -- Atanh (0) = 0
227 -- Atanh (+-1) = +- INF
228 -- Atanh (X) = NaN for abs X > 1
229 --
230 -- @llr atanh (Float) Accuracy
231 -- The Atanh function shall return the inverse hyperbolic tangent of <X>
232 -- with the following accuracy:
233 --
234 -- Ada accuracy requirements:
235 -- MRE <= 8.0 * Eps
236
237 ---------
238 -- Cos --
239 ---------
240
241 function Cos (X : Float) return Float
242 with Export, Convention => C, External_Name => SLP.Prefix & "cosf";
243 -- @llr cos (Float) Special Values
244 -- The Cos function shall return the following special values:
245 --
246 -- C99 special values:
247 -- Cos (+-0) = 1
248 -- Cos (+-INF) = NaN
249 --
250 -- Ada expected values:
251 -- abs (Cos (x)) <= 1
252 --
253 -- @llr cos (Float) Accuracy
254 -- The Cos function shall return the cosine of <X>
255 -- with the following accuracy:
256 --
257 -- Ada accuracy requirements:
258 -- MRE <= 2.0 * Eps
259
260 ----------
261 -- Cosh --
262 ----------
263
264 function Cosh (X : Float) return Float
265 with Export, Convention => C, External_Name => SLP.Prefix & "coshf";
266 -- @llr cosh (Float) Special Values
267 -- The Cosh function shall return the following special values:
268 --
269 -- C99 special values:
270 -- Cosh (+-0) = 1
271 -- Cosh (+-INF) = +INF
272 --
273 -- Ada expected values:
274 -- abs (Cosh (x)) > 1
275 --
276 -- @llr cosh (Float) Accuracy
277 -- The Cosh function shall return the inverse cosine of <X>
278 -- with the following accuracy:
279 --
280 -- Ada accuracy requirements:
281 -- MRE <= 8.0 * Eps
282
283 ---------
284 -- Exp --
285 ---------
286
287 function Exp (X : Float) return Float
288 with Export, Convention => C, External_Name => SLP.Prefix & "expf";
289 -- @llr exp (Float) Special Values
290 -- The Exp function shall return the following special values:
291 --
292 -- C99 special values:
293 -- Exp (+-0) = 1
294 -- Exp (-INF) = +0
295 -- Exp (+INF) = +INF
296 --
297 -- @llr exp (Float) Accuracy
298 -- The Exp function shall return the exponential of <X>
299 -- with the following accuracy:
300 --
301 -- Ada accuracy requirements:
302 -- MRE <= 4.0 * Eps
303
304 ----------
305 -- Exp2 --
306 ----------
307
308 function Exp2 (X : Float) return Float
309 with Export, Convention => C, External_Name => SLP.Prefix & "exp2f";
310 -- @llr exp2 (Float) Special Values
311 -- The Exp2 function shall return the following special values:
312 --
313 -- C99 special values:
314 -- Exp2 (+-0) = 1
315 -- Exp2 (-INF) = +0
316 -- Exp2 (+INF) = +INF
317 --
318 -- @llr exp2 (Float) Accuracy
319 -- The Exp2 function shall return the exponential of <X> in base 2
320 -- with the following accuracy:
321 --
322 -- Accuracy requirements:
323 -- MRE <= 4.0 * Eps
324
325 ---------
326 -- Log --
327 ---------
328
329 function Log (X : Float) return Float
330 with Export, Convention => C, External_Name => SLP.Prefix & "logf";
331 -- @llr log (Float) Special Values
332 -- The Log function shall return the following special values:
333 --
334 -- C99 special values:
335 -- Log (+-0) = -INF
336 -- Log (1) = +0
337 -- Log (x) = NaN if x<0
338 -- Log (+INF) = +INF
339 --
340 -- @llr log (Float) Accuracy
341 -- The Log function shall return the logarithm of <X>
342 -- with the following accuracy:
343 --
344 -- Ada accuracy requirements:
345 -- MRE <= 4.0 * Eps
346
347 -----------
348 -- Log1p --
349 -----------
350
351 function Log1p (X : Float) return Float
352 with Export, Convention => C, External_Name => SLP.Prefix & "log1pf";
353 -- @llr log1p (Float) Special Values:
354 -- The Log1p function shall return the following special values:
355 --
356 -- C99 special values:
357 -- Log1p (+-0) = -INF
358 -- Log1p (1) = +0
359 -- Log1p (x) = NaN if x<0
360 -- Log1p (+INF) = +INF
361 --
362 -- @llr log1p (Float) Accuracy
363 -- The Log1p function shall return the logarithm of <X> + 1
364 -- with the following accuracy:
365 --
366 -- Accuracy requirements:
367 -- MRE <= 4.0 * Eps
368
369 ----------
370 -- Log2 --
371 ----------
372
373 function Log2 (X : Float) return Float
374 with Export, Convention => C, External_Name => SLP.Prefix & "log2f";
375 -- @llr log2 (Float) Special Values
376 -- The Log2 function shall return the following special values:
377 --
378 -- C99 Special values:
379 -- Log2 (+-0) = -INF
380 -- Log2 (1) = +0
381 -- Log2 (x) = NaN if x<0
382 -- Log2 (+INF) = +INF
383 --
384 -- @llr log2 (Float) Accuracy
385 -- The Log function shall return the logarithm of <X> in base 2
386 -- with the following accuracy:
387 --
388 -- Accuracy requirements:
389 -- MRE <= 4.0 * Eps
390
391 ---------
392 -- Pow --
393 ---------
394
395 function Pow (Left, Right : Float) return Float
396 with Export, Convention => C, External_Name => SLP.Prefix & "powf";
397 -- @llr pow (Float; Float) Special Values
398 -- The Pow function shall return the following special values
399 --
400 -- C99 Special values:
401 -- Pow (+-0, y) = +-INF, if y < 0 and y an odd integer
402 -- Pow (+-0, y) = +INF, if y < 0 and y not an odd integer
403 -- Pow (+-0, y) = +-0 if y > 0 and y an odd integer
404 -- Pow (+-0, y) = +0 if y > 0 and y not an odd integer
405 -- Pow (-1, +-INF) = 1
406 -- Pow (1, y) = 1 for any y, even a NaN
407 -- Pow (x, +-0) = 1 for any x, even a NaN
408 -- Pow (x, y) = NaN, if x < 0 and both x and y finite and not integer
409 -- Pow (x, -INF) = +INF if abs (x) < 1
410 -- Pow (x, -INF) = +0 if abs (x) > 1
411 -- Pow (x, +INF) = +0 if abs (x) < 1
412 -- Pow (x, +INF) = +INF if abs (x) > 1
413 -- Pow (-INF, y) = -0 if y < 0 and y an odd integer
414 -- Pow (-INF, y) = +0 if y < 0 and y not an odd integer
415 -- Pow (-INF, y) = -INF if y > 0 and y an odd integer
416 -- Pow (-INF, y) = +INF if y > 0 and y not an odd integer
417 -- Pow (+INF, y) = +0 if y < 0
418 -- Pow (+INF, y) = +INF if y > 0
419 --
420 -- @llr pow (Float; Float) Accuracy
421 -- The Pow function shall return <Left> to the power of <Right>
422 -- with the following accuracy:
423 --
424 -- Ada Accuracy requirements:
425 -- MRE <= (4.0 + abs (x * Log (y)) / 32) * Eps
426
427 ---------
428 -- Sin --
429 ---------
430
431 function Sin (X : Float) return Float
432 with Export, Convention => C, External_Name => SLP.Prefix & "sinf";
433 -- @llr sin (Float) Special Values
434 -- The Sin function shall return the following special values:
435 --
436 -- C99 special values:
437 -- Sin (+-0) = +-0
438 -- Sin (+-INF) = NaN
439 --
440 -- @llr sin (Float) Accuracy
441 -- The Sin function shall return the sine of <X>
442 -- with the following accuracy:
443 --
444 -- Ada accuracy requirements:
445 -- MRE <= 2.0 * Eps
446
447 ----------
448 -- Sinh --
449 ----------
450
451 function Sinh (X : Float) return Float
452 with Export, Convention => C, External_Name => SLP.Prefix & "sinhf";
453 -- @llr sinh (Float) Special Values
454 -- The Sinh function shall return the following special values:
455 --
456 -- C99 Special values:
457 -- Sinh (+-0) = +-0
458 -- Sinh (+-INF) = +-INF
459 --
460 -- @llr sinh (Float) Accuracy
461 -- The Sinh function shall return the hyperbolic sine of <X>
462 -- with the following accuracy:
463 --
464 -- Ada accuracy requirements:
465 -- MRE <= 8.0 * Eps
466
467 ----------
468 -- Sqrt --
469 ----------
470
471 function Sqrt (X : Float) return Float
472 with Convention => C;
473 -- @ignore
474 -- The Sqrt function shall return the following special values:
475 --
476 -- C99 special values:
477 -- Sqrt (+-0) = +-0
478 -- Sqrt (INF) = INF
479 -- Sqrt (X) = NaN, for X < 0.0
480
481 ---------
482 -- Tan --
483 ---------
484
485 function Tan (X : Float) return Float
486 with Export, Convention => C, External_Name => SLP.Prefix & "tanf";
487 -- @llr tan (Float) Special Values
488 -- The Tan function shall return the following special values:
489 --
490 -- C99 special values:
491 -- Tan (+-0) = +0
492 -- Tan (+-INF) = NaN
493 --
494 -- @llr tan (Float) Accuracy
495 -- The Tan function shall return the tangent of <X>
496 -- with the following accuracy:
497 --
498 -- Ada accuracy requirements:
499 -- MRE <= 4.0 * Eps
500
501 ----------
502 -- Tanh --
503 ----------
504
505 function Tanh (X : Float) return Float
506 with Export, Convention => C, External_Name => SLP.Prefix & "tanhf";
507 -- @llr tanh (Float) Special Values
508 -- The Tanh function shall return the following special values:
509 --
510 -- C99 special values:
511 -- Tanh (+-0) = +-0
512 -- Tanh (+-INF) = +-1
513 --
514 -- @llr tanh (Float) Accuracy
515 -- The Tanh function shall return the hyperbolic tangent of <X>
516 -- with the following accuracy:
517 --
518 -- Ada accuracy requirements:
519 -- MRE <= 8.0 * Eps
520
521 private
522 function Identity (X : Float) return Float is (X);
523
524 function Infinity return Float
525 with Import, Convention => Intrinsic, External_Name => "__builtin_inff";
526
527 function NaN return Float is (Infinity - Infinity);
528
529 function Exact (X : Long_Long_Float) return Float is (Float (X));
530
531 function Epsilon return Float is (Float'Model_Epsilon);
532
533 function Maximum_Relative_Error (X : Float) return Float is (0.0 * X);
534
535 end System.Libm_Single;