;;; -*- 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)

Supporting detail is listed below, including two different kinds of
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.  ARGS-INFO and %ARGS-INFO are
apparently used interchangeably; both return the arg-desc for a given
function.  The LISP version invokes the microcode "%" version once it
has processed its argument, which ought to be a valid function spec,
into an atom.

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).  Constants with a two
'%%' prefix are byte specifiers for use with LDB or DBP and their
friends (and thus, would have to change for the Falcon); constants with
one '%' prefix are byte values for use with, i.e., LOGAND.  I have
replaced absolute-value byte specs with the equivalent calls to BYTE.

;;; A "Numeric Argument Description" is what %ARGS-INFO and ARGS-INFO return.
;;; Such descriptors can also be hung on symbols' Q-ARGS-PROP properties.
;;; The "fast option Q" of a FEF is stored in this format.
;;; These symbols go in the real machine.

%ARG-DESC-QUOTED-REST	  10000000        ;HAS QUOTED REST ARGUMENT
%%ARG-DESC-QUOTED-REST	  2501	        (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 make porting easier 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 will be
handled for the Falcon system.

2) Define macros for getting the args-desc elements with a single call
to ARGS-INFO.  This has several advantages: 1) a uniform, high-level
interface is provided; 2) nobody but the new macro will call %ARGS-INFO;
3) only one localized modification should be required to port the new
interface for the Falcon.

The facility is designed to minimize calls to ARGS-INFO, reflecting the
existing code.  For example,

(WITH-ARGS-INFO (args-info-var func)
        (ARGS-DESC-MIN-ARGS args-info-var)
        (ARGS-DESC-MAX-ARGS args-info-var)
  ...etc, for ARGS-DESC-QUOTED-REST, -EVALED-REST, -ANY-REST, -INTERPRETED, and -FEF-BIND-HAIR

The code resulting from each ARGS-DESC- macro call checks and (maybe)
modifies its argument, the <args-info-var>.  If it is a fixnum, it is
used to return the corresponding single piece of information; if not, it
is the initial value, <func>, which gets reset to the result of calling
ARGS-INFO on the <func>.  Thus, subsequent calls will not have to get
the ARGS-INFO again.

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
increased modularity compensates for the slight overhead of calls to
ARGS-INFO and 2-3 type checks before %ARGS-INFO gets called.