Liren Large Software Subsidy 7

home *** CD-ROM | disk | FTP | other *** search

/ Liren Large Software Subsidy 7 / 07.iso / c / c221 / 1.ddi / DOC / README.EMB < prev next >

Wrap

Text File | 1992-04-22 | 17.4 KB | 395 lines

Copyright (C) 1992 MetaWare Incorporated; All Rights Reserved. High C/C++ Version 3.0 Globally Optimizing Compiler for Extended DOS 80386/486 and Windows 3.0 April 1992 +-----------------------------+ | Embedded Applications Notes | +-----------------------------+ If you are developing code for use in embedded systems, and you are not writing your own library, use High C 1.x libraries (HCC.LIB or HCE.LIB) instead of the High C/C++ 3.0 libraries. HCC.LIB and HCE.LIB are included in the High C/C++ 3.0 distribution. HCC.LIB and HCE.LIB facilitate making an embedded product because they isolate system dependencies in a few modules. This file describes how to modify MS-DOS-dependent modules. Use this information in addition to the "Embedded Applications" chapter in the High C/C++ Programmer's Guide. No MS-DOS Support ----------------- Systems with no operating-system support are the traditional pattern for embedded systems. A system with no MS-DOS support requires more radical modification of INIT.ASM than systems with partial support. INIT must still be used, however, because some memory management is necessary. Set the conditional assembly for NO_DOS, set Stack_length to a number suitable for your conditions, and create a new INIT.OBJ. Lack of operating-system support severely limits many of the library functions you may have used previously. The High C functions listed in Table 1 require no DOS support. Table 1: Functions Requiring No Operating-System Support abs iscntrl outp _strncat acos isdigit outpw strncmp alloca isgraph perror strncpy asctime islower pow strnicmp asin _isodigit qsort strnset assert isprint rand strpbrk atan ispunct _rmemcpy strrchr atan2 isspace _rotl strrev atexit isupper _rotr strset atof isxdigit _rstrcpy strspn atoi labs _rstrncpy strstr atol ldexp segread strtod bsearch ldiv setjmp strtok cabs localeconv setlocale strtol ceil localtime _setmode strtoul clearerr log sin strupr cos log10 sinh strxfrm cosh longjmp sprintf swab ctime _lrotl sqrt tan difftime _lrotr srand tanh div mblen sscanf tolower errno mbstowcs strcat _tolower exp mbtowc _strcats toupper fabs memccpy strchr _toupper floor memchr strcmp ultoa fmod memcmp strcoll va_arg frexp memcpy strcpy va_end gmtime memicmp strcspn va_list inp memmove strftime va_start inpw memset stricmp vsprintf isalnum mktime strlen wcstombs isalpha modf strlwr wctomb _isascii offsetof strncat Very experienced programmers may wish to modify other source-code modules to use normally DOS-dependent code in a non-DOS environment. Modifying MS-DOS-Dependent Modules ---------------------------------- This section is intended for very experienced programmers only. Deleting or modifying system-level code can result in much smaller executable modules, but the changes must be very carefully prepared. At this level many modules interact, and modifying one may not prove "user friendly" to another. This code was not originally designed for modification by users, and not many programmers will be comfortable modifying it. We provide this facility as a special service to our many expert customers. Only a few modules in the Run-Time Libraries are directly dependent on the MS- DOS operating system. Some dependent modules, such as ENV, are specific to MS-DOS and are not referenced elsewhere in the Run-Time Libraries. Such modules are not of concern for embedded applications, and so are not discussed here. The initialization module INIT must be implemented on any non-MS-DOS system to establish the run-time environment. Several other modules must be ported if any significant portion of any Run-Time Library is used by the application. These modules are: INIT initialize the environment TERM terminate the environment by closing files, and so forth EXIT C functions exit, _exit, and abort SYSTEM low-level system services INTRUP interrupt handling CONSOLE input/output from/to the console The source for the MS-DOS implementations of these modules is provided with the distribution. You should study these files and use them as a guide. Non-assembly source is written in either MetaWare's Professional Pascal or High C. If you want to modify the source, you may need both compilers. Also, the two languages use different calling conventions. To call functions in one language from the other language successfully, the calling module must contain a declaration that appropriately sets the calling convention for the called function. See the Compatibility and Portability chapter in the High C/C++ Programmer's Guide for information about calling conventions. Unless otherwise indicated in the following sections, the object version of each function is aliased to the source name preceded by _mw, to avoid conflict with the Standard C library and likely user-coined names. For example, INIT is known externally -- that is, to the linker -- as _mwINIT. INIT -- Environment Initialization ---------------------------------- INIT is an assembly-language module that contains the function INIT which is the initial entry point of each linked program. INIT establishes the environment in which High C programs are to run. More specifically, this module: * sets up the stack * initializes public variables as required * initializes the floating-point processor * calls a function to set up interrupt vectors * calls a function to initialize the environment table * calls a function to initialize I/O for High C * calls the main program * calls a function to close any open files * terminates the program. Minimum environment. The MS-DOS version of this module is much more involved than is typically required for an embedded application. If your application is completely independent of Library support, INIT need only set up a stack, invoke the main program, and then terminate. I/O initialization. If the High C STDIO module is used, the function cfinit() must be invoked as part of the initialization process to set up various control blocks and buffers. The function cfterm() closes all open files and frees up buffers; this function is called from the TERM module. Main program. The name of the main program of any linked program is main. argc, argv support. If argc and argv are to be used, the public variables arglen and argp must be initialized and the function set_up_args() within INIT must be called prior to calling main(). arglen is a word that is set to the length of the parameter string. argp is set to the address of the first byte of the parameter string. If the program name is to be made available (as the zeroth argument), the variable prognamep must be initialized as well. Program termination. The MS-DOS version of INIT calls Halt. Halt is in the TERM module; see TERM -- Environment Termination. This function closes open files, calls a function to restore interrupt vectors, and then invokes the dos_exit() function to terminate the process. dos_exit(), which is called indirectly by Halt, is in the SYSTEM module. Line-terminator convention. The INIT module initializes the common block that establishes the default line-terminating convention for the host system. Under the MS-DOS operating system, lines are terminated with the two characters CR (13(10)) and LF (10(10)). TERM -- Environment Termination ------------------------------- The TERM module implements the Pascal Halt library routine, called by the C exit() function and by INIT. Halt indirectly calls cfterm to close all open files; restores interrupt vectors to their prior condition; and then calls dos_exit() to terminate. dos_exit() is in the SYSTEM module. EXIT -- Functions exit(), _exit(), and abort() ---------------------------------------------- The EXIT module implements the C functions exit(), _exit(), and abort(). exit() is implemented by calling the Professional Pascal routine Halt. _exit() calls a routine to restore interrupts and calls dos_exit() (in SYSTEM), avoiding a call to cfterm() to terminate the file system. abort() is a synonym for _exit(-1) which produces a return code of 255 under the MS-DOS operating system (return codes are limited to the range 0..255). In simpler environments, the TERM module can be eliminated by implementing exit(), _exit(), and abort() in the SYSTEM module. SYSTEM -- System Services ------------------------- The SYSTEM module typically takes the most work to port to another system. Of course only those functions in SYSTEM that are explicitly referenced elsewhere in the Run-Time Libraries need be ported. Details of those functions are described here. Source files. The implementation of the SYSTEM module under MS-DOS is in a number of files of the form SYSTEM*.P. I/O model. The SYSTEM module models I/O the same way as MS-DOS and UNIX: files are treated as unformatted streams of bytes. Open files are referenced through file handles. A file handle is a small integer value within the range zero to MaxFiles, where MaxFiles+1 is the maximum number of files that can be open at one time. An arbitrary number of bytes can be read from or written to a file with the read and write functions. I/O is device independent. Devices are accessed in exactly the same way as disk files. No file system. Many embedded applications do not support a file system. In such cases, I/O functions within the module can be made to access ports. The "file name" can be used to designate a port address when an open or create operation is performed. Alternatively, file handles can be permanently assigned to specific ports. Standard input/output. File handles 0, 1, and 2 are pre-initialized to standard input, standard output, and standard error output, respectively. The STDIO module relies on this convention in supplying the FILE* variables stdin, stdout, and stderr. Function descriptions. This section describes each function in the SYSTEM module that is referenced elsewhere by other modules in the Run-Time Libraries. No other functions in the SYSTEM module need be implemented unless your program explicitly references them. close(F) Closes the file associated with file handle F. The value of F may be subsequently reassigned in a call to c_open() or c_create(). c_create(Name,Mode) c_create_text(Name,Mode) Creates the file named Name if it does not exist; otherwise the file is truncated to zero bytes. Mode is the set of attributes to be assigned to the file; the interpretation of Mode is system dependent. If Mode is the empty set, a default mode is used that is appropriate for the host system. A file handle is returned that can be used to reference the file. c_create_text() is called to create an ASCII-formatted file. On systems that make no distinction between ASCII and non-ASCII files these two functions can be considered synonymous. dos_exit(RC) Terminates the program with a return code RC. This function is referenced only from the TERM module and need not be implemented if the application has an alternate way of terminating a program. fileclass(F) Returns the type of file associated with file handle F: Console_input, Console_output, or Disk_file. This function is called by the STDIO module to determine whether a file should be buffered. I/O to the console is unbuffered to allow prompting. get_date(Day,Month,Year) get_time(Hrs,Mins,Secs) clock() These are used by those functions that implement the Standard C library functions in header file TIME.H. get_date() returns 1-31 in Day, 1-12 in Month, and 1980-2099 in Year. get_time() returns elapsed wall-clock time: 0-23 in Hrs and 0-59 in Mins and Secs. clock() returns elapsed wall-clock time in hundredths of a second. lseek (F,Loc,Method) lseek_(F,Loc,Method) lseek() repositions the file pointer associated with file handle F so that the next read or write operates on the nth byte of the file (origin at zero) where n is computed as follows: Value of n Value of Method ------------------------------------------ Loc From_beginning Loc+"current position" From_current Loc+"file size" From_end lseek_() performs the same function as lseek(), but lseek_() also returns the new file-pointer position. lseek()/lseek_() need not be implemented unless your program performs random file access via the STDIO function fseek. c_open(Name,Method) c_open_text(Name,Method) Opens the file named Name for input, output, or update. If the file is not found, errno is set to error_file_not_found; otherwise a file handle is returned that can be used to reference the open file. The c_open_text() function is used to open a file that is to be interpreted as an ASCII file with embedded end-of-line characters. On systems that make no distinction between ASCII and non-ASCII files, these two functions can be considered synonymous. Text files need not be supported for update. read(F,BufP,Cnt) Reads Cnt bytes from the file or device associated with file handle F into the buffer with address BufP. Returns the number of bytes actually read, which may be less than Cnt if fewer than Cnt bytes remain in the file or if reading from a line-at-a-time device such as a keyboard. When end-of-file is encountered, read() returns zero. c_unlink(Name) Deletes the file named Name. This function is called when temporary High C files are closed. write (F,BufP,Cnt) write_(F,BufP,Cnt) Writes Cnt bytes to the file or device associated with file handle F from the buffer with address BufP. write() sets errno to error_write_failed if fewer than Cnt bytes were written (often caused by a disk overflow). The function write_() returns the number of bytes actually written and does not indicate an error condition if fewer than Cnt bytes are written. CONSOLE -- Console Input/Output ------------------------------- The CONSOLE module reads strings from the keyboard and writes strings to the screen. Source files. The CONSOLE module under the MS-DOS operating system consists of two source files: KB1.P and KB2.P (KB for keyboard). gets(var S: String) reads a line from the keyboard and stores it in S. If the line is too long to fit in S, the result is unpredictable. This is in accordance with the Standard C gets() function which is inherently dangerous in this respect. S is of the Professional Pascal String type. String s consist of two bytes to hold the current length len of the string, followed by an array of characters, the first len of which make up the string. When a String is passed by var, as S is here, the address of the string is passed, but in addition, the maximum length of the string must be available to the receiving routine; thus, the Professional Pascal compiler passes the maximum length of the string as a hidden parameter. To duplicate the interface in High C, something like the following is needed: pragma Calling_convention(PASCAL); void gets(char *len_and_string, short maxlen) { short s_length; char *s; s_length = *(short *)len_and_string; s = len_and_string+2; ... } puts(const S: String) writes S to the screen, without terminating the line. Again, S is of the Professional Pascal String type. When a String is passed by const, as S is here, the address of the string is passed. The maximum length of the string need not be available to the receiving function, as the meaning of const is that the parameter cannot be modified; no hidden parameters are passed in this case. newline() writes out the necessary characters to the screen to terminate the current line. Under the MS-DOS operating system, file handle 2 is always directed to the screen for output. Thus, puts() and newline() simply write to file handle 2 via the SYSTEM function write. Because standard input is not necessarily from the keyboard, the first call to gets() opens the keyboard for input and invokes read() from the SYSTEM module. The line-termination characters are then stripped from the string read in.