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, and they are used quite widely throughout the system.
Following is a specification of work to be done to modularize the
implementation, thereby facilitating the Falcon port.

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.

A. BACKGROUND - Current Implementation

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.

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, NOT REST) ARGS

*** NOTE: Interpreted functions do not necessarily have this value.

B. SCOPE - 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)

For my own convenience, I assembled a list of functions and files calling
%ARGS-INFO or ARGS-INFO, and collected these definitions (DEFUNs and
fragments thereof) into one file.  I verified this information by doing a
Tags Search on SYSTEM for "%ARG-DESC".

C. PORTABILITY RECOMMENDATIONS

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, a goal of
the existing implementation.

WITH-ARGS-INFO (MACRO): (FUNC VARLIST &BODY BODY)
Executes BODY with the variables listed in VARLIST bound
  to argument information values for function FUNC.
Specify variable names corresponding to the desired argument information;
  use NIL to indicate a value that will not be computed.

The available values, in order, are:
   - MIN-ARGS, the minimum number of positional (required + optional)
               arguments expected by FUNC
   - MAX-ARGS, the maximum number of positional arguments expected by FUNC
   - QUOTED-REST-P, non-NIL if FUNC takes a quoted &REST argument
   - EVALED-REST-P, non-NIL if FUNC takes an evaluated &REST argument
   - ANY-REST-P, non-NIL if FUNC takes either kind of &REST argument
   - INTERPRETED-P, non-NIL in certain cases for interpreted function, or
                    when no information available
   - QUOTE-HAIR-P, caller must check ADL for /"hairy/" quoting information
   - BIND-HAIR-P, caller must check ADL for /"hairy/" binding information

To access the argument information directly, specify FUNC as a list,
  (FUNC INFO):
   - FUNC, the 1st element, a function object or function spec;
   - INFO, the 2nd element, a variable to which argument information is bound.

For example:

   (with-args-info function-spec (min max)
      (format t "~&~A takes from ~D. to ~D. arguments"
              function-spec min max))

3) Replace invocations of ARGS-INFO and %ARGS-INFO in the system with calls
to WITH-ARGS-INFO.  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.