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:

 o Interpreter
 o Compiler
 o DESCRIBE (describing functions)
 o Macro-expansion (AUTOMATIC-DISPLACE)
 o Debugger / error handler (displaying/modifying frames)
 o Resources (getting arg-lists of parameterizer functions)
 o 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.  (Note
that the current implementation allows at most 63 function arguments.)

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.

	        ARGUMENT DESCRIPTORS -- SYSTEM CONSTANTS

CONSTANT                    VALUE (OCTAL)   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.)   ;HAS EITHER KIND REST ARG

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

%ARG-DESC-INTERPRETED       1000000         ;INTERPRETED FUNCTION, AND/OR
%%ARG-DESC-INTERPRETED      (BYTE 1. 18.)   ; NO INFORMATION AVAILABLE
                                            ; (VALUE=1000077) ***

%ARG-DESC-FEF-BIND-HAIR     400000          ;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
				    ;  (ALL POSITIONAL) ARGS,
                                            ; REST ARGS NOT COUNTED.

*** NOTE: Interpreted functions do not necessarily have this value; indeed,
I have not been able to produce a function that does.  This may be
obsolete.

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 WITH-ARGS-INFO (macro) and functions for getting the args-desc
elements with a single call to ARGS-INFO.

This facility is designed to minimize calls to ARGS-INFO, respecting 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.

There are several advantages to this change:

   a) A uniform, high-level argument descriptor interface is provided;

   b) Only ARGS-INFO will call %ARGS-INFO, and only the new macro
      will call ARGS-INFO;

   c) Only one (centralized) modification should be required
      to make argument descriptors work on the Falcon.  If it
      is determined that a very different argument descriptor
      implementation is needed (or already provided in Falcon
      code), ARGS-INFO "users" (in the system software) will
      not need to be modified.

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.