ARG-DESC.TEXT ;;; -*- Mode:Text; Package:SYSTEM-INTERNALS; Tab-Width:10 -*-

		     ARGUMENT DESCRIPTORS 

Argument descriptors have been implemented on the Lambda in a processor-
dependent fashion, but they are used quite widely throughout the system.
Following is a specification of work to be done to reduce the occurrence of
this processor-dependent code, facilitating the Falcon port.

A. Where Argument Descriptors are Used

The modules that utilize argument descriptors include:

 1) Interpreter
 2) Compiler
 3) DESCRIBE (describing functions)
 4) Macro-expansion (AUTOMATIC-DISPLACE)
 5) Debugger / error handler (displaying/modifying frames)
 6) Resources (getting arg-lists of parameterizer functions)
 7) Function typing (FUNCTIONP)

To organize this effort I have assembled the required information:

 1) Lists of functions and files calling %ARGS-INFO or ARGS-INFO

 2) Definitions (e.g. DEFUNs or fragments thereof) found by doing a
    Tags Search on SYSTEM for "%ARG-DESC", which found references to
    constants (byte specs and offsets) pertaining to argument
    descriptors.

B. Functional Requirements

An argument descriptor is a fixnum which is packed with information
describing how a function takes arguments.  The most common use is to get
the minimum and maximum number of arguments accepted by a function.

ARGS-INFO and %ARGS-INFO are both used in system code; both return the
numeric argument descriptor for a given function.  The LISP version accepts
function specs and invokes the microcode "%" version once it has processed
its argument.

The following table of byte specs and bit field values is taken from
SYS:COLD;QCOM.LISP, which defines these constants for the processor (they
are loaded during the cold system build and are used by microcode
routines).  Constants with two percent signs prefixed (%%) are byte
specifiers for use with, e.g., LDB or DBP (and thus would have to change
for the Falcon).  Constants with one percent sign prefixed (%) are bit
field values for use with, e.g., LOGAND.

CONSTANT                        VALUE           COMMENTS
-------------------------       -------------   -------------------------------------------

%ARG-DESC-QUOTED-REST           10000000        ;HAS QUOTED REST ARGUMENT
%%ARG-DESC-QUOTED-REST          (BYTE 1. 21.)

%ARG-DESC-EVALED-REST           4000000         ;HAS EVALUATED REST ARGUMENT
%%ARG-DESC-EVALED-REST          (BYTE 1. 20.)
                                             
%%ARG-DESC-ANY-REST             (BYTE 2. 20.)   ;NON-ZERO IF HAS EITHER KIND OF REST ARG

%ARG-DESC-FEF-QUOTE-HAIR        2000000         ;MACRO COMPILED FCN WITH HAIRY QUOTING,
%%ARG-DESC-FEF-QUOTE-HAIR       (BYTE 1. 19.)   ;  CALLER MUST CHECK A-D-L FOR FULL INFO

%ARG-DESC-INTERPRETED           1000000         ;THIS IS INTERPRETED FUNCTION, 
%%ARG-DESC-INTERPRETED          (BYTE 1. 18.)   ; NO INFORMATION AVAILABLE (VAL=1000077)

%ARG-DESC-FEF-BIND-HAIR         400000          ;MACRO COMPILED FCN WITH HAIRY BINDING,
%%ARG-DESC-FEF-BIND-HAIR        (BYTE 1. 17.)   ; LINEAR ENTER MUST CHECK A-D-L

%%ARG-DESC-MIN-ARGS             (BYTE 6. 6.)    ;MINIMUM NUMBER OF REQUIRED ARGS
%%ARG-DESC-MAX-ARGS             (BYTE 6. 0.)    ;MAXIMUM NUMBER OF REQUIRED+OPTIONAL (positional) ARGS,
                                                ; REST ARGS NOT COUNTED.

C. Portability Recommendations

Here are my recommendations to facilitate porting argument descriptors in
the future:

1) Fix QCOM to compute these values by calls to BYTE, if possible.  This
requires that a decision be made how QCOM type definitions (and cold
loading generally) will be handled for the Falcon system.

2) Define a WITH-ARGS-INFO macro and functions for getting the args-desc
elements with a single call to ARGS-INFO.  This has several advantages:

   a) A uniform, high-level interface is provided;
   b) Only the new macro will call %ARGS-INFO
   c) Only one (centralized) modification should be required
      to port the new interface for the Falcon.  If it should
      develop that a very different argument descriptor
      implementation is needed (or already provided in Falcon
      code), none of the modules that now use ARGS-INFO will be
      affected.

This facility is designed to minimize calls to ARGS-INFO, reflecting the
existing code.  For example,

(WITH-ARGS-INFO (args-info-var func)
  (ARGS-INFO-MIN-ARGS args-info-var)
  (ARGS-INFO-MAX-ARGS args-info-var)
  (ARGS-INFO-QUOTED-REST-P args-info-var)
                :

...etc, for -EVALED-REST-P, -ANY-REST-P,  -INTERPRETED-P,
-FEF-QUOTE-HAIR-P, and -FEF-BIND-HAIR-P.

3) Replace invocations of ARGS-INFO and %ARGS-INFO in the system with calls
as above.  Where %ARGS-INFO is being called directly now, the call to
ARGS-INFO will require 2 additional type checks; the increased portability
compensates for the slight overhead.