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.

I suspect that Lambda argument descriptors are just the tip of this
particular iceberg.  there are many related parts of the system that use
system constants and microcode routines, and they may be handled in a
similar fashion.