Update documentation about ARC's extension instructions.

2 files changed, 142 insertions, 11 deletions

diff --git a/gas/ChangeLog b/gas/ChangeLog
index a8b51af..69b6cbc 100644
--- a/gas/ChangeLog
+++ b/gas/ChangeLog
@@ -1,3 +1,8 @@
+2005-02-28  Ramana Radhakrishnan  <ramana.radhakrishnan@codito.com>
+
+	* doc/c-arc.texi: Update documentation about ARC's extension
+	instructions.
+
 2005-02-27  Svein E. Seldal  <svein@dev.seldal.com>
 
 	* config/tc-tic4x.c (tic4x_gen_to_words): Changed mail
diff --git a/gas/doc/c-arc.texi b/gas/doc/c-arc.texi
index 700a01d..f03fa9c 100644
--- a/gas/doc/c-arc.texi
+++ b/gas/doc/c-arc.texi
@@ -1,4 +1,4 @@
-@c Copyright 2000, 2001 Free Software Foundation, Inc.
+@c Copyright 2000, 2001, 2005 Free Software Foundation, Inc.
 @c This is part of the GAS manual.
 @c For copying conditions, see the file as.texinfo.
 
@@ -34,7 +34,7 @@
 
 @cindex @code{-marc[5|6|7|8]} command line option, ARC
 @item -marc[5|6|7|8]
-This option selects the core processor variant. Using
+This option selects the core processor variant.  Using
 @code{-marc} is the same as @code{-marc@value{ARC_CORE_DEFAULT}}, which
 is also the default.
 
@@ -46,10 +46,10 @@ Base instruction set.
 
 @cindex @code{arc6} arc6, ARC
 @item arc6
-Jump-and-link (jl) instruction. No requirement of an instruction between
-setting flags and conditional jump. For example:
+Jump-and-link (jl) instruction.  No requirement of an instruction between
+setting flags and conditional jump.  For example:
 
-@smallexample
+@smallexample @ta
   mov.f r0,r1
   beq   foo
 @end smallexample
@@ -137,36 +137,161 @@ machine directives:
 
 @cindex @code{extAuxRegister} directive, ARC
 @item .extAuxRegister @var{name},@var{address},@var{mode}
-*TODO*
+The ARCtangent A4 has extensible auxiliary register space.  The
+auxiliary registers can be defined in the assembler source code by
+using this directive.  The first parameter is the @var{name} of the
+new auxiallry register.  The second parameter is the @var{address} of
+the register in the auxiliary register memory map for the variant of
+the ARC.  The third parameter specifies the @var{mode} in which the
+register can be operated is and it can be one of: 
+
+@table @code
+@item r          (readonly) 
+@item w          (write only)
+@item r|w        (read or write)
+@end table
+
+For example:
 
 @smallexample
   .extAuxRegister mulhi,0x12,w
 @end smallexample
 
+This specifies an extension auxiliary register called @emph{mulhi}
+which is at address 0x12 in the memory space and which is only
+writable.
+
 @cindex @code{extCondCode} directive, ARC
 @item .extCondCode @var{suffix},@var{value}
-*TODO*
+The condition codes on the ARCtangent A4 are extensible and can be
+specified by means of this assembler directive.  They are specified
+by the suffix and the value for the condition code.  They can be used to
+specify extra condition codes with any values.  For example:
 
 @smallexample
   .extCondCode is_busy,0x14
+  
+   add.is_busy  r1,r2,r3
+   bis_busy     _main
 @end smallexample
 
 @cindex @code{extCoreRegister} directive, ARC
 @item .extCoreRegister @var{name},@var{regnum},@var{mode},@var{shortcut}
-*TODO*
+Specifies an extension core register @var{name} for the application.
+This allows a register @var{name} with a valid @var{regnum} between 0
+and 60, with the following as valid values for @var{mode} 
+
+@table @samp
+@item @emph{r}   (readonly) 
+@item @emph{w}   (write only)
+@item @emph{r|w} (read or write)
+@end table
+
+
+The other parameter gives a description of the register having a
+@var{shortcut} in the pipeline.  The valid values are:
+
+@table @code
+@item can_shortcut
+@item cannot_shortcut
+@end table
+
+For example:
 
 @smallexample
   .extCoreRegister mlo,57,r,can_shortcut
 @end smallexample
 
+This defines an extension core register mlo with the value 57 which
+can shortcut the pipeline.
+
 @cindex @code{extInstruction} directive, ARC
 @item .extInstruction @var{name},@var{opcode},@var{subopcode},@var{suffixclass},@var{syntaxclass}
-*TODO*
+The ARCtangent A4 allows the user to specify extension instructions.
+The extension instructions are not macros.  The assembler creates
+encodings for use of these instructions according to the specification
+by the user.  The parameters are:
+
+@table @bullet
+@item @var{name}
+Name of the extension instruction 
+
+@item @var{opcode}
+Opcode to be used. (Bits 27:31 in the encoding).  Valid values
+0x10-0x1f or 0x03
+
+@item @var{subopcode}
+Subopcode to be used.  Valid values are from 0x09-0x3f.  However the
+correct value also depends on @var{syntaxclass}
+
+@item @var{suffixclass}
+Determines the kinds of suffixes to be allowed.  Valid values are
+@code{SUFFIX_NONE}, @code{SUFFIX_COND}, 
+@code{SUFFIX_FLAG} which indicates the absence or presence of
+conditional suffixes and flag setting by the extension instruction.
+It is also possible to specify that an instruction sets the flags and
+is conditional by using @code{SUFFIX_CODE} | @code{SUFFIX_FLAG}.
+
+@item @var{syntaxclass}
+Determines the syntax class for the instruction.  It can have the
+following values:
+
+@table @code
+@item{SYNTAX_2OP}:
+2 Operand Instruction 
+@item{SYNTAX_3OP}:
+3 Operand Instruction 
+@end table
+
+In addition there could be modifiers for the syntax class as described
+below:
+
+@itemize @minus
+Syntax Class Modifiers are:
+
+@item @code{OP1_MUST_BE_IMM}:
+Modifies syntax class SYNTAX_3OP,  specifying that the first operand
+of a three-operand instruction must be an immediate (i.e. the result
+is discarded).  OP1_MUST_BE_IMM is used by bitwise ORing it with
+SYNTAX_3OP as given in the example below.  This could usually be used
+to set the flags using specific instructions and not retain results. 
+
+@item @code{OP1_IMM_IMPLIED}:
+Modifies syntax class SYNTAX_20P, it specifies that there is an
+implied immediate destination operand which does not appear in the
+syntax.  For example, if the source code contains an instruction like:
 
 @smallexample
-  .extInstruction mul64,0x14,0x0,SUFFIX_COND,SYNTAX_3OP|OP1_MUST_BE_IMM
+inst r1,r2 
 @end smallexample
 
+it really means that the first argument is an implied immediate (that
+is, the result is discarded).  This is the same as though the source
+code were: inst 0,r1,r2.  You use OP1_IMM_IMPLIED by bitwise ORing it
+with SYNTAX_20P.
+
+@end itemize 
+@end table
+
+For example, defining 64-bit multiplier with immediate operands:
+
+@smallexample
+.extInstruction mp64,0x14,0x0,SUFFIX_COND | SUFFIX_FLAG ,
+                SYNTAX_3OP|OP1_MUST_BE_IMM
+@end smallexample
+
+The above specifies an extension instruction called mp64 which has 3 operands,
+sets the flags, can be used with a condition code, for which the
+first operand is an immediate.  (Equivalent to discarding the result 
+of the operation).
+
+@smallexample
+ .extInstruction mul64,0x14,0x00,SUFFIX_COND, SYNTAX_2OP|OP1_IMM_IMPLIED
+@end smallexample
+
+This describes a 2 operand instruction with an implicit first
+immediate operand.  The result of this operation would be discarded.
+
 @cindex @code{half} directive, ARC
 @item .half @var{expressions}
 *TODO*
@@ -204,4 +329,5 @@ between the two - even for the implicit default core version
 @cindex opcodes for ARC
 
 For information on the ARC instruction set, see @cite{ARC Programmers
-Reference Manual}, ARC Cores Ltd.
+Reference Manual}, ARC International (www.arc.com)
+