Chapter one
Spontaneous Assembly For C/C++ is designed to be a complete C programming and optimization tool which does not require the direct use of assembly language. However, because assembly is desirable in many applications, complete assembly language documentation, modules, and examples are also provided. This allows the programmer to develop and program in C while providing unrestricted access to the underlying assembly language functions.
Because this manual is intended as a reference work, discussion is kept to a minimum. Pertinent information is usually provided where it is required, even if the information is duplicated elsewhere in the manual. The intent of this approach is to make using Spontaneous Assembly For C/C++ as straightforward as possible.
The first two sections of the manual, Introduction and Using Spontaneous Assembly For C/C++, are introductory in nature. These sections include an overall description of Spontaneous Assembly For C/C++, a detailed description of the library functionality, an explanation of how programs use Spontaneous Assembly For C/C++, and step-by-step instructions describing how to integrate Spontaneous Assembly library functions using inline assembly into existing C programs.
The next three sections of the manual provide detailed reference material for using the Spontaneous Assembly library routines and macros. The technical notes section appears first. This section divides the library functions, macros, and variables into groups of related functions called units. Each unit is documented separately. This documentation includes: a general description of the unit; brief descriptions of each function, macro, and variable in the unit; and notes which explain general requirements, limitations, how related functions coordinate together, and other technical topics which are beyond the scope of the Reference Section.
Primary emphasis is placed on the Reference Section. This section explains every function, macro, and variable in detail, including inputs and outputs, detailed guidelines for use, C and inline assembly examples, warnings, related functions, source files, and more. The entries in this section are arranged alphabetically for quick reference.
Finally, the Appendices contain tables of error codes, keystrokes and keystroke codes, a cross reference for standard C functions and Spontaneous Assembly For C/C++ functions, and a discussion of advanced TSR topics. A thorough Index is also provided.
regular type
In some cases, binders have been provided for assembly language macros (not functions) from the Spontaneous Assembly library. Since macros are not supported in inline assembly, there is no inline assembly equivalent for these C functions. In these cases, "(Not Applicable)" appears where the inline assembly example normally belongs. In addition, "(C Interface Recommended)" appears in cases where there is no significant size or speed advantage to using inline assembly.
Some of the examples in the reference section use heap management functions calls such as malloc and free. These function calls automatically use Spontaneous Assembly For C/C++ heap management functions instead of the standard heap functions if the required installation is performed (see the Memory Management technical notes). However, either heap management system may be successfully used for these examples.
For the sake of simplicity, inline examples are written for the SMALL memory model (near data and near code). Many of these examples may be used in the LARGE memory model (far data or far code) without modification. Most other examples may be modified for LARGE model use simply by setting up far pointers to reference the needed data.
Finally, some examples make use of printf and other examples use the more powerful Spontaneous Assembly scripted I/O functions (e.g., _cput_script and _put_script). While both methods are shown, the scripted I/O functions are recommended in applications where speed, size, and flexibility are important.
Chapter two
At first glance, the use of binders might seem inefficient since the added overhead of a binder can reduce the advantage of calling an assembly language function. However, it turns out that in a complex library where many functions depend on each other, a C binder interface usually provides better optimization than rewriting the library to support a C interface directly! This is true because the assembly parameter-passing convention (parameters in registers, conditions in flags) is inherently more efficient than the C convention (parameters on the stack, conditions in a register). Although binders must convert parameters before calling their assembly counterparts, from that point on all internal function calls use the faster, tighter assembly language convention. This makes the internal library code much more efficient than would otherwise be possible. (Restated, an assembly library written with an external C interface would also be constrained to use an internal C interface. This is due to the fact that the high-level library functions must call the low-level functions using whatever interface is supported by those functions. This would make the library less efficient.)
Furthermore, by providing an optional binder interface, Spontaneous Assembly For C/C++ also allows C binders and inline assembly calls for the same functions to be used interchangeably in the same program. This flexibility would be impossible if the library supported a C interface directly.
Each area of library functionality is described in detail in Chapter 2 of the white Spontaneous Assembly 3.0 manual which accompanies this manual. In addition, Spontaneous Assembly For C/C++ includes a quadword arithmetic class for C++ use. This unit is described below.
While many of the library functions may be useful for protected mode programming, no effort has been made to make them fully protected mode compatible in the current version of the product. Data is never written into the code segment (except for the TSR functions), but some functions perform segment register arithmetic (e.g., _far_malloc) and make use of the SAHF instruction (e.g., _cmp_qq).