import newlib-2000-02-17 snapshot

1 files changed, 129 insertions, 0 deletions

diff --git a/newlib/libc/sys/sysvnecv70/sysvnecv70.tex b/newlib/libc/sys/sysvnecv70/sysvnecv70.tex
new file mode 100644
index 000000000..c2d038aec
--- /dev/null
+++ b/newlib/libc/sys/sysvnecv70/sysvnecv70.tex
@@ -0,0 +1,129 @@
+@node syscalls,machine,reentrancy,Top
+@chapter NEC V70 system calls
+
+The library needs a certain amount of system-specific support in order
+to operate.  These routines have to be written for each unique
+target environment.  For testing purposes,
+a set of system calls specific to an NEC V70 Unix PC running AT&T Unix
+System V R2 are included.  These files are in the @file{sys/sysvnecv70}
+directory.
+
+All the calls have to be implemented in order to avoid link time
+errors, but the implementation need not include all possible
+functionality; in general, for any functionality that isn't
+available, returning an error code is sufficient.
+
+@section Input/Output
+
+The V70 target may not have any character I/O devices.
+In this case, the @code{fstat}, @code{ioctl}, @code{isatty},
+@code{lseek}, @code{read} and @code{write} routines may all return @code{-1},
+to signal failure (inspect @file{cerror.s} to see how to do this).
+
+Sometimes it is correct to implement the functions in a very
+simple and machine specific way.  For instance, the target board may
+have one serial line.
+
+In this case, the @code{write} system call can be ``hard-wired'' to
+always print to the serial device, no matter what the supplied file
+handle says. Similarly, the other I/O system calls can be written to
+take advantage of a known configuration.
+
+Note that the library starts up assuming that three files are already
+open.  File handles used are:
+@table @code
+@item 0
+Is used for all input from @code{stdin}.
+@item 1
+Is used for all output to @code{stdout}.  This includes functions like
+@code{putc} and @code{printf}.
+@item 2
+Is used for all output to @code{stderr}.  The library will use this
+file to print error messages from the math functions.  Output can
+also be sent to @code{stderr} by @code{fprintf(stderr,@dots{})}
+@end table
+@section Example @code{write} routine
+On a board with a very simple I/O structure, this would be adequate:
+
+@example
+
+@group
+char *duart_status = DUART_ADDR;
+
+void poll()
+@{
+   /* Dummy function to fool optimizer */
+@}				       
+
+int write(fd, string, len)
+int fd;
+char *string;
+int len;				       
+@{
+  int i;
+      
+  for (i = 0; i < len; i++) 
+  @{
+    while (*duart_status & DUART_BUSY)
+     poll();
+    *duart_port = string[i];
+  @}
+  return len;
+@}
+@end group				       
+@end example
+
+@section Memory allocation
+
+The library allocates memory from the heap either for its own use, or when
+you explicitly call @code{malloc}.  It asks the system for
+memory by calling the @code{sbrk} function.  
+
+On a Unix system, @code{sbrk} keeps track of the heap's extent by keeping a
+pointer to the end of the @code{bss} section.  Unix linkers
+traditionaly mark the end of @code{bss} by creating a symbol
+@code{_end}.  When the library wants more memory, it calls
+@code{sbrk} with the size of the request.  @code{sbrk} must then
+perform an operation specific to the target environment, and return a pointer
+to the new area.  For a simple application, the following fragment may
+be sufficient:
+@example
+
+@group
+char *moving_end = &end;
+
+char *sbrk(request)
+int request;
+@{
+  char *return_address;
+
+  return_address = moving_end;
+  moving_end += request;
+  return return_address;
+@}
+@end group
+@end example
+
+@section Initialization and termination
+
+The system dependent support routines are responsible for
+initializing the library for use by an application, and cleaning up
+when the application is complete.
+
+This functionality is traditionally provided in @code{crt0} and
+@code{_exit}.  
+
+The @code{crt0} function usually contains the instructions first run
+by the operating system when an application starts.  The
+@code{crt0} function can take advantage of this and prepare the way
+for the libary.
+
+Another task for @code{crt0} is to call the @code{main} function
+provided by the application writer, and also to call @code{exit} if
+the main function ever returns.
+
+@code{exit} tells the operating system that the application has
+finished.
+
+
+