newlib/libc/sys/sysvnecv70/sysvnecv70.tex

   1 @node syscalls,machine,reentrancy,Top
   2 @chapter NEC V70 system calls
   3
   4 The library needs a certain amount of system-specific support in order
   5 to operate.  These routines have to be written for each unique
   6 target environment.  For testing purposes,
   7 a set of system calls specific to an NEC V70 Unix PC running AT&T Unix
   8 System V R2 are included.  These files are in the @file{sys/sysvnecv70}
   9 directory.
  10
  11 All the calls have to be implemented in order to avoid link time
  12 errors, but the implementation need not include all possible
  13 functionality; in general, for any functionality that isn't
  14 available, returning an error code is sufficient.
  15
  16 @section Input/Output
  17
  18 The V70 target may not have any character I/O devices.
  19 In this case, the @code{fstat}, @code{ioctl}, @code{isatty},
  20 @code{lseek}, @code{read} and @code{write} routines may all return @code{-1},
  21 to signal failure (inspect @file{cerror.s} to see how to do this).
  22
  23 Sometimes it is correct to implement the functions in a very
  24 simple and machine specific way.  For instance, the target board may
  25 have one serial line.
  26
  27 In this case, the @code{write} system call can be ``hard-wired'' to
  28 always print to the serial device, no matter what the supplied file
  29 handle says. Similarly, the other I/O system calls can be written to
  30 take advantage of a known configuration.
  31
  32 Note that the library starts up assuming that three files are already
  33 open.  File handles used are:
  34 @table @code
  35 @item 0
  36 Is used for all input from @code{stdin}.
  37 @item 1
  38 Is used for all output to @code{stdout}.  This includes functions like
  39 @code{putc} and @code{printf}.
  40 @item 2
  41 Is used for all output to @code{stderr}.  The library will use this
  42 file to print error messages from the math functions.  Output can
  43 also be sent to @code{stderr} by @code{fprintf(stderr,@dots{})}
  44 @end table
  45 @section Example @code{write} routine
  46 On a board with a very simple I/O structure, this would be adequate:
  47
  48 @example
  49
  50 @group
  51 char *duart_status = DUART_ADDR;
  52
  53 void poll()
  54 @{
  55    /* Dummy function to fool optimizer */
  56 @}
  57
  58 int write(fd, string, len)
  59 int fd;
  60 char *string;
  61 int len;
  62 @{
  63   int i;
  64
  65   for (i = 0; i < len; i++)
  66   @{
  67     while (*duart_status & DUART_BUSY)
  68      poll();
  69     *duart_port = string[i];
  70   @}
  71   return len;
  72 @}
  73 @end group
  74 @end example
  75
  76 @section Memory allocation
  77
  78 The library allocates memory from the heap either for its own use, or when
  79 you explicitly call @code{malloc}.  It asks the system for
  80 memory by calling the @code{sbrk} function.
  81
  82 On a Unix system, @code{sbrk} keeps track of the heap's extent by keeping a
  83 pointer to the end of the @code{bss} section.  Unix linkers
  84 traditionaly mark the end of @code{bss} by creating a symbol
  85 @code{_end}.  When the library wants more memory, it calls
  86 @code{sbrk} with the size of the request.  @code{sbrk} must then
  87 perform an operation specific to the target environment, and return a pointer
  88 to the new area.  For a simple application, the following fragment may
  89 be sufficient:
  90 @example
  91
  92 @group
  93 char *moving_end = &end;
  94
  95 char *sbrk(request)
  96 int request;
  97 @{
  98   char *return_address;
  99
 100   return_address = moving_end;
 101   moving_end += request;
 102   return return_address;
 103 @}
 104 @end group
 105 @end example
 106
 107 @section Initialization and termination
 108
 109 The system dependent support routines are responsible for
 110 initializing the library for use by an application, and cleaning up
 111 when the application is complete.
 112
 113 This functionality is traditionally provided in @code{crt0} and
 114 @code{_exit}.
 115
 116 The @code{crt0} function usually contains the instructions first run
 117 by the operating system when an application starts.  The
 118 @code{crt0} function can take advantage of this and prepare the way
 119 for the libary.
 120
 121 Another task for @code{crt0} is to call the @code{main} function
 122 provided by the application writer, and also to call @code{exit} if
 123 the main function ever returns.
 124
 125 @code{exit} tells the operating system that the application has
 126 finished.
 127
 128
 129