2009-03-25 Craig Howland <howland@LGSInnovations.com>
* libc/include/math.h: (llround, llroundf): Declare.
* libm/common/s_llround.c: New file, implementing llround().
* libm/common/sf_llround.c: New file, implementing llroundf().
* libm/common/sf_lround.c: Remove spurious cast in _DOUBLE_IS_32BITS
version of function.
* libm/common/sf_lrint.c: Ditto.
* libm/common/sf_logb.c: Corrected return for subnormal argument
by replacing existing function with a version created from sf_ilogb.c.
* libm/common/s_logb.c: Ditto, except starting point s_ilogb.c. Also
added documentation for logb() and logbf().
* libm/common/s_signbit.c: Add signbit() documentation.
* libm/common/s_log2.c: Update return values to match what w_log2.c has,
since log2 uses log(); add note about being derived instead of direct.
* libm/common/sf_fma.c: Add casts to attempt to get correct results,
as well as comments pointing out problems with the implementation.
* libm/common/s_fma.c: Add fma() and fmaf() documentation.
* libm/common/sf_remquo.c: Incorrect quotient returns for large values
corrected by discarding existing function and replacing with Sun
verion, with some enhancements.
* libm/common/s_remquo.c: Ditto. Add remquo() and remquof()
documentation.
* libm/common/s_fmax.c: Add fmax() and fmaxf() documentation.
* libm/common/s_fmin.c: Add fmin() and fminf() documentation.
* libm/common/s_fdim.c: Return NAN for NAN arg, add fdim() and fdimf()
documentation.
* libm/common/sf_fdim.c: Return NAN for NAN arg, HUGE_VALF for inf arg.
* libm/common/s_trunc.c: Add trunc() and truncf() documentation.
* libm/common/s_rint.c: Add rint() and rintf() documentation.
* libm/common/s_round.c: Add round() and roundf() documentation.
* libm/common/s_scalbn.c: Add scalbln() and scalblnf() documentation.
* libm/common/s_infinity.c: Add infinity() and infinityf()
documentation.
* libm/common/s_lround.c: Add lround(), lroundf(), llround(), and
llroundf() documentation.
* libm/common/s_lrint.c: Add lrint(), lrintf(), llrint(), and llrintf()
documentation.
* libm/common/isgreater.c: New file for documenting math.h function-like
macros isgreater(), isgreaterequal(), isless(), islessequal(),
islessgreater(), and isunordered().
* libm/common/s_isnan.c: Add documentation for function-like macros
fpclassify(), isfinite(), isinf(), isnan(), and isnormal().
* libm/common/s_nearbyint.c: Add nearbyint() and nearbyintf()
documentation.
* libm/common/Makefile.am: Add s_llround.c (src); sf_llround.c (fsrc);
s_fdim.def, s_fma.def, s_fmax.def, s_fmin.def,
s_logb.def, s_lrint.def, s_lround.def, s_nearbyint.def, s_remquo.def,
s_rint.def, s_round.def, s_signbit.def, s_trunc.def, and
isgreater.def (chobj);
re-name all existing chew files (chobj) to match source file base
names (put in underscores), delete all special targets for chew files
(leaving all to be generated by rule).
* libm/common/Makefile.in: regenerate.
* libm/math/w_exp2.c: Add "base 2" to documentation description (and
delete TRAD_SYNOPSIS).
* libm/math/w_gamma.c: Add tgamma() and tgammaf() documentation, along
with some history behind the function names.
* libm/math/math.tex: Add includes for newly-added documentation (see
.def additions to common/Makefile.am and math/Makefile.am in this
ChangeLog list), adjusted existing .def file names to match source file
base names (added underscores); add mention of HUGE_VALF; rename
"Version of library" section to "Error Handling" and add some text
about floating-point exception; added section "Standards Compliance And
Portability".
* libm/math/Makefile.am: Add w_exp2.def (chobj);
re-name all existing chew files (chobj) to match source file base
names, delete all special targets for chew files (leaving all to be
generated by rule).
* libm/math/Makefile.in: regenerated
* doc/makedoc.c: Change silent ignoring of commands < 5 characters
to a failure when reading macro file for commands < 4 characters;
add -v (verbose) option for printing some debugging information;
get rid of spurious translation of "@*" to "*" (no source files used @*,
so no existing doc pages were affected); clean up some compiler
warnings.
* doc/doc.str: add BUGS and SEEALSO sections (to match texi2pod.pl
which has them); Remove ITEM command (redundant with makedoc built-in
"o", not used in any present source file so nothing is lost, anyway).
* HOWTO: New file to hold information for maintainers regarding how
to do things. Initial sections on documentation and ELIX levels.
This commit is contained in:
Jeff Johnston
parent
139f923bb4
commit
3ed024dcb2
|
|
@ -0,0 +1,117 @@
|
|||
This HOWTO file contains notes for maintainers and contributors to Newlib.
|
||||
For information on using Newlib (building, installing), see README. (In
|
||||
particular, the "Regenerating Configuration Files" section in README is of
|
||||
interest to both users and contributors.)
|
||||
|
||||
(This file could probably use some other "sections" in addition to the
|
||||
initially-provided sections. Please help by adding as appropriate.)
|
||||
|
||||
DOCUMENTATION
|
||||
=============
|
||||
|
||||
All the documentation for Newlib comes as part of the machine-readable
|
||||
distribution. Functions are documented in the source files, although not
|
||||
every file contains documentation, as many functions share manual page
|
||||
information. For example, lround(), lroundf(), llround(), and llroundf()
|
||||
share a single man page, which is in the source for lround(). The documentation
|
||||
is written partially in a custom format and partially in Texinfo format.
|
||||
|
||||
The custom part comprises makedoc.c and doc.str, both of which are in the
|
||||
doc directory. doc.str is a macro file that can be used to define things to
|
||||
be done by makedoc, using building blocks that are built into makedoc.c.
|
||||
The basic function of makedoc is two-fold. First, it recognizes comments in
|
||||
the proper format to pull out of source files. Second, it adds some Texinfo
|
||||
commands as well as translating certain sequences into the appropriate
|
||||
Texinfo commands. Refer to makedoc.c and doc.str for what these are.
|
||||
(makedoc.c is not particularly-well commented.) Another way to see how they
|
||||
work is to simply examine the source files with documentation comments.
|
||||
|
||||
(A couple of examples that use some of the fancier options:
|
||||
libm/common/s_isnan.c ("o+" variable-"bullet" list),
|
||||
libc/stdio/sprintf.c ("O+" bullet list; "." for example code).)
|
||||
|
||||
In addition to the makedoc.c stuff, Texinfo commands can be directly
|
||||
used. Texinfo is a documentation system that uses a single source file to
|
||||
produce both on-line information and a printed manual. You can use one of the
|
||||
Info formatting commands to create the on-line version of the documentation
|
||||
and TeX (or `texi2roff') to typeset the printed version. While Newlib contains
|
||||
a copy of the texinfo package (texinfo.tex), the manual for it is not
|
||||
included. The latest one may be found at
|
||||
|
||||
http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html
|
||||
|
||||
(which could be for a newer version of texinfo.tex than is included in Newlib).
|
||||
|
||||
In addition to Texinfo commands, straight TeX commands can also be used,
|
||||
but these, however, should be carefully limited and be given alternates for
|
||||
when a non-printed manual is produced--such as when info pages are produced.
|
||||
For an example of this kind of usage, see libm/common/s_logb.c.
|
||||
|
||||
Please note that most files with documentation contain both an
|
||||
ANSI_SYNOPSIS and a TRAD_SYNOPSIS section. The TRAD_SYNOPSIS section gets
|
||||
deleted (since at least 2000) by makedoc, so when working on files these
|
||||
can safely be deleted and if you're making a new file, there is no need
|
||||
to add the TRAD_SYNOPSIS section.
|
||||
|
||||
If writing a new function that requires documentation, the required
|
||||
sections are FUNCTION, INDEX, ANSI_SYNOPSIS (or SYNOPSIS), DESCRIPTION, RETURNS,
|
||||
and PORTABILITY. BUGS and SEEALSO should be added as appropriate.
|
||||
|
||||
Source files which contain documentation are processed into ".def"
|
||||
files with the extracted information. These .def files are noted in the
|
||||
makefiles as either CHEWOUT_FILES in the libc makefiles or chobj in the libm
|
||||
makefiles. These .def files need to be included into an appropriate .tex
|
||||
file for inclusion in the manuals (one each for libc and libm). Pay special
|
||||
attention under libc, as the manual is arranged by header file name, but not
|
||||
all header files are represented by directories (e.g. wcsftime.c is found
|
||||
under libc/time, but goes under wchar.h in the manual.)
|
||||
|
||||
In summary, to add new documentation:
|
||||
|
||||
1. Add properly-formatted comments to source file (e.g. src.c);
|
||||
2. add "chewout" file to list in Makefile.am (CHEWOUT_FILES in libc or chobj in
|
||||
libm) (e.g. src.def), re-generate Makefile.in;
|
||||
3. add file to something.tex;
|
||||
4. make ChangeLog entry and generate patch.
|
||||
|
||||
EL/IX (ELIX_LEVEL_n, ELIX_n_SOURCES)
|
||||
====================================
|
||||
|
||||
Some of the Makefiles contain definitions of ELIX_LEVEL_1 ... ELIX_LEVEL_4,
|
||||
and corresponding definitions for ELIX_1_SOURCES ... ELIX_4_SOURCES.
|
||||
These are referring to the EL/IX standards created by Red Hat for the
|
||||
purpose of Linux-based open standards for embedded development. In brief,
|
||||
the intent is to define multiple levels for API functions that allows the
|
||||
user to size the library appropriately for their application--at least in
|
||||
terms of the predefined lists. For full details, refer to the EL/IX home
|
||||
page at http://sources.redhat.com/elix/. The likely best way to tell how to
|
||||
classify any new functions in terms of needing an ELIX level qualification
|
||||
is to ask Jeff Johnston. To see how it works and try classification on your
|
||||
own, refer to the API specification on the web site,
|
||||
|
||||
http://sources.redhat.com/elix/api/current/api.pdf.
|
||||
|
||||
(Unfortunately, it is not complete with respect to either the C99 or POSIX
|
||||
standards, so particular C and POSIX functions may or may not be found.)
|
||||
|
||||
The following definitions of the levels are from the (draft) standard.
|
||||
|
||||
Level 1
|
||||
RTOS compatible layer. Functions available in both Linux and a
|
||||
typical deeply embedded operating system (eCos, RTEMS, VxWorks, pSOS, VRTX32,
|
||||
etc.). Some functions may have reduced or modified semantics.
|
||||
|
||||
Level 2
|
||||
Linux single process only. Includes level 1 plus any functions from Linux
|
||||
that are not easily implemented on an RTOS. Also full implementations of
|
||||
reduced functions in Level 1.
|
||||
|
||||
Level 3
|
||||
Linux multiprocess for embedded applications. This is basically POSIX.1
|
||||
with some of the functions that are obviously not for embedded applications
|
||||
(such as job control) removed.
|
||||
|
||||
Level 4
|
||||
Full POSIX or Linux compliance. Essentially these are functions that are
|
||||
present in a standard Linux kernel but are irrelevant to an embedded system.
|
||||
These functions do not form part of the EL/IX API.
|
||||
|
|
@ -22,10 +22,6 @@
|
|||
quickref
|
||||
;
|
||||
|
||||
|
||||
: ITEM
|
||||
"@item " catstr ;
|
||||
|
||||
: EXAMPLE
|
||||
skip_past_newline
|
||||
|
||||
|
|
@ -55,7 +51,6 @@
|
|||
|
||||
;
|
||||
|
||||
|
||||
: ANSI_SYNOPSIS
|
||||
skip_past_newline
|
||||
"@strong{Synopsis}\n" catstr
|
||||
|
|
@ -137,8 +132,6 @@
|
|||
bodytext
|
||||
;
|
||||
|
||||
|
||||
|
||||
: DESCRIPTION
|
||||
"@strong{Description}@*\n" catstr subhead ;
|
||||
|
||||
|
|
@ -148,31 +141,29 @@
|
|||
: ERRORS
|
||||
"@strong{Errors}@*\n" catstr subhead ;
|
||||
|
||||
|
||||
: PORTABILITY
|
||||
"@strong{Portability}@*\n" catstr subhead ;
|
||||
|
||||
: BUGS
|
||||
"@strong{Bugs}@*\n" catstr subhead ;
|
||||
|
||||
: WARNINGS
|
||||
"@strong{Warnings}@*\n" catstr subhead ;
|
||||
|
||||
|
||||
: SEEALSO
|
||||
"@strong{See Also}@*\n" catstr subhead ;
|
||||
|
||||
: INTERNAL_FUNCTION
|
||||
func ;
|
||||
|
||||
|
||||
: INTERNAL_DEFINITION
|
||||
func ;
|
||||
|
||||
|
||||
: INTERNAL
|
||||
func ;
|
||||
|
||||
: TYPEDEF
|
||||
FUNCTION ;
|
||||
|
||||
|
||||
|
||||
: NEWPAGE
|
||||
"@page\n" catstr subhead ;
|
||||
|
|
|
|||
|
|
@ -39,12 +39,15 @@ There is no
|
|||
#include <stdio.h>
|
||||
#include <stdlib.h>
|
||||
#include <ctype.h>
|
||||
#include <string.h>
|
||||
|
||||
#define DEF_SIZE 5000
|
||||
#define STACK 50
|
||||
#define MIN_CMDLEN 4 /* Minimum length of a command */
|
||||
|
||||
int internal_wanted;
|
||||
int internal_mode;
|
||||
int Verbose=0;
|
||||
|
||||
|
||||
|
||||
|
|
@ -212,7 +215,7 @@ string_type *tos;
|
|||
|
||||
unsigned int idx = 0; /* Pos in input buffer */
|
||||
string_type *ptr; /* and the buffer */
|
||||
typedef void (*stinst_type)();
|
||||
typedef void (*stinst_type)(NOARGS);
|
||||
stinst_type *pc;
|
||||
stinst_type sstack[STACK];
|
||||
stinst_type *ssp = &sstack[0];
|
||||
|
|
@ -234,7 +237,7 @@ struct dict_struct
|
|||
|
||||
};
|
||||
typedef struct dict_struct dict_type;
|
||||
#define WORD(x) static void x()
|
||||
#define WORD(x) static void x(NOARGS)
|
||||
|
||||
static void DEFUN(exec,(word),
|
||||
dict_type *word)
|
||||
|
|
@ -451,7 +454,6 @@ WORD(translatecomments)
|
|||
WORD(quickref)
|
||||
{
|
||||
string_type *nos = tos-1;
|
||||
unsigned int scan=0;
|
||||
unsigned int nosscan = 0;
|
||||
unsigned int idx = 0;
|
||||
|
||||
|
|
@ -487,6 +489,7 @@ WORD(quickref)
|
|||
|
||||
}
|
||||
|
||||
#if 0
|
||||
/* turn everything not starting with a . into a comment */
|
||||
|
||||
WORD(manglecomments)
|
||||
|
|
@ -520,6 +523,7 @@ WORD(manglecomments)
|
|||
pc++;
|
||||
|
||||
}
|
||||
#endif
|
||||
|
||||
/* Mod tos so that only lines with leading dots remain */
|
||||
static void
|
||||
|
|
@ -640,12 +644,15 @@ WORD(courierize)
|
|||
}
|
||||
|
||||
/*
|
||||
bulletize: look for bullet item commands at start of line
|
||||
Bullet list:
|
||||
O+ emit @itemize @bullet
|
||||
OO emit @item
|
||||
o emit @item [note lowercase]
|
||||
O- emit @end itemize
|
||||
|
||||
Variable label list:
|
||||
o+ emit @table @code
|
||||
oo @item
|
||||
o emit @item
|
||||
o- emit @end table
|
||||
*/
|
||||
|
||||
|
|
@ -653,19 +660,10 @@ WORD(courierize)
|
|||
WORD(bulletize)
|
||||
{
|
||||
unsigned int idx = 0;
|
||||
int on = 0;
|
||||
string_type out;
|
||||
init_string(&out);
|
||||
|
||||
while (at(tos, idx)) {
|
||||
if (at(tos, idx) == '@' &&
|
||||
at(tos, idx+1) == '*')
|
||||
{
|
||||
cattext(&out,"*");
|
||||
idx+=2;
|
||||
}
|
||||
|
||||
else
|
||||
if (at(tos, idx) == '\n' && at(tos, idx+1) == 'o')
|
||||
{
|
||||
if (at(tos,idx+2) == '+') {
|
||||
|
|
@ -787,7 +785,10 @@ DEFUN( iscommand,(ptr, idx),
|
|||
}
|
||||
else if(at(ptr,idx) == '\n')
|
||||
{
|
||||
if (len >4) return 1;
|
||||
/* The length check will never fail on a real command
|
||||
* because the commands are screened as the definitions file
|
||||
* is read. */
|
||||
if (len >= MIN_CMDLEN) return 1;
|
||||
return 0;
|
||||
}
|
||||
else return 0;
|
||||
|
|
@ -797,6 +798,7 @@ DEFUN( iscommand,(ptr, idx),
|
|||
}
|
||||
|
||||
|
||||
unsigned int
|
||||
DEFUN(copy_past_newline,(ptr, idx, dst),
|
||||
string_type *ptr AND
|
||||
unsigned int idx AND
|
||||
|
|
@ -833,7 +835,6 @@ WORD(kill_bogus_lines)
|
|||
{
|
||||
int sl ;
|
||||
|
||||
int nl = 0;
|
||||
int idx = 0;
|
||||
int c;
|
||||
int dot = 0 ;
|
||||
|
|
@ -1162,9 +1163,6 @@ static void DEFUN_VOID(perform)
|
|||
/* It's worth looking through the command list */
|
||||
if (iscommand(ptr, idx))
|
||||
{
|
||||
unsigned int i;
|
||||
int found = 0;
|
||||
|
||||
char *next;
|
||||
dict_type *word ;
|
||||
|
||||
|
|
@ -1178,6 +1176,7 @@ static void DEFUN_VOID(perform)
|
|||
|
||||
if (word)
|
||||
{
|
||||
if(Verbose) fprintf(stderr, "CMD '%s'\n", word->word);
|
||||
exec(word);
|
||||
}
|
||||
else
|
||||
|
|
@ -1234,19 +1233,13 @@ return entry->code_end++;
|
|||
void
|
||||
DEFUN(add_intrinsic,(name, func),
|
||||
char *name AND
|
||||
void (*func)())
|
||||
void (*func)(NOARGS))
|
||||
{
|
||||
dict_type *new = newentry(name);
|
||||
add_to_definition(new, func);
|
||||
add_to_definition(new, 0);
|
||||
}
|
||||
|
||||
WORD(push_addr)
|
||||
{
|
||||
|
||||
|
||||
}
|
||||
|
||||
void
|
||||
DEFUN(add_var,(name),
|
||||
char *name)
|
||||
|
|
@ -1261,13 +1254,12 @@ DEFUN(add_var,(name),
|
|||
|
||||
|
||||
|
||||
void
|
||||
int
|
||||
DEFUN(compile, (string),
|
||||
char *string)
|
||||
|
||||
{
|
||||
int jstack[STACK];
|
||||
int *jptr = jstack;
|
||||
int ret=0;
|
||||
/* add words to the dictionary */
|
||||
char *word;
|
||||
string = nextword(string, &word);
|
||||
|
|
@ -1275,18 +1267,24 @@ DEFUN(compile, (string),
|
|||
{
|
||||
if (strcmp(word,"var")==0)
|
||||
{
|
||||
string=nextword(string, &word);
|
||||
string=nextword(string, &word);
|
||||
|
||||
add_var(word);
|
||||
string=nextword(string, &word);
|
||||
string=nextword(string, &word);
|
||||
}
|
||||
else
|
||||
else
|
||||
|
||||
if (word[0] == ':')
|
||||
{
|
||||
dict_type *ptr;
|
||||
/* Compile a word and add to dictionary */
|
||||
string = nextword(string, &word);
|
||||
if(Verbose) fprintf(stderr, "Found command '%s'\n", word);
|
||||
if(strlen(word) < MIN_CMDLEN) {
|
||||
fprintf(stderr, "ERROR: Command '%s' is too short ", word);
|
||||
fprintf(stderr, "(MIN_CMDLEN is %d)\n", MIN_CMDLEN);
|
||||
ret++;
|
||||
}
|
||||
|
||||
ptr = newentry(word);
|
||||
string = nextword(string, &word);
|
||||
|
|
@ -1330,9 +1328,11 @@ else
|
|||
else
|
||||
{
|
||||
fprintf(stderr,"syntax error at %s\n",string-1);
|
||||
ret++;
|
||||
}
|
||||
}
|
||||
|
||||
return(ret);
|
||||
}
|
||||
|
||||
|
||||
|
|
@ -1378,11 +1378,13 @@ static void DEFUN(read_in, (str, file),
|
|||
}
|
||||
|
||||
|
||||
#if 0
|
||||
static void DEFUN_VOID(usage)
|
||||
{
|
||||
fprintf(stderr,"usage: -[d|i|g] <file >file\n");
|
||||
fprintf(stderr,"usage: -[i|v] -f macrofile <file >file\n");
|
||||
exit(33);
|
||||
}
|
||||
#endif
|
||||
|
||||
int DEFUN(main,(ac,av),
|
||||
int ac AND
|
||||
|
|
@ -1446,16 +1448,22 @@ char *av[])
|
|||
fprintf(stderr,"Can't open the input file %s\n",av[i+1]);
|
||||
return 33;
|
||||
}
|
||||
if(Verbose) fprintf(stderr, "Reading -f '%s'\n", av[i+1]);
|
||||
|
||||
|
||||
read_in(&b, f);
|
||||
compile(b.ptr);
|
||||
if( compile(b.ptr) ) { fclose(f); exit(1); }
|
||||
perform();
|
||||
fclose(f);
|
||||
}
|
||||
else if (av[i][1] == 'i')
|
||||
{
|
||||
internal_wanted = 1;
|
||||
}
|
||||
else if (av[i][1] == 'v')
|
||||
{
|
||||
Verbose++;
|
||||
}
|
||||
}
|
||||
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue