-@c Copyright 2002 Free Software Foundation, Inc.
+@c Copyright (C) 2002-2020 Free Software Foundation, Inc.
@c This is part of the GAS manual.
@c For copying conditions, see the file as.texinfo.
@ifset GENERIC
* MSP430 Floating Point:: Floating Point
* MSP430 Directives:: MSP 430 Machine Directives
* MSP430 Opcodes:: Opcodes
+* MSP430 Profiling Capability:: Profiling Capability
@end menu
@node MSP430 Options
@section Options
@cindex MSP 430 options (none)
@cindex options for MSP430 (none)
-@code{@value{AS}} has only -m flag which selects the mpu arch. Currently has
-no effect.
+@table @code
+
+@item -mmcu
+selects the mcu architecture. If the architecture is 430Xv2 then this
+also enables NOP generation unless the @option{-mN} is also specified.
+
+@item -mcpu
+selects the cpu architecture. If the architecture is 430Xv2 then this
+also enables NOP generation unless the @option{-mN} is also specified.
+
+@item -msilicon-errata=@var{name}[,@var{name}@dots{}]
+Implements a fixup for named silicon errata. Multiple silicon errata
+can be specified by multiple uses of the @option{-msilicon-errata}
+option and/or by including the errata names, separated by commas, on
+an individual @option{-msilicon-errata} option. Errata names
+currently recognised by the assembler are:
+
+@table @code
+@item cpu4
+@code{PUSH #4} and @option{PUSH #8} need longer encodings on the
+MSP430. This option is enabled by default, and cannot be disabled.
+@item cpu8
+Do not set the @code{SP} to an odd value.
+@item cpu11
+Do not update the @code{SR} and the @code{PC} in the same instruction.
+@item cpu12
+Do not use the @code{PC} in a @code{CMP} or @code{BIT} instruction.
+@item cpu13
+Do not use an arithmetic instruction to modify the @code{SR}.
+@item cpu19
+Insert @code{NOP} after @code{CPUOFF}.
+@end table
+
+@item -msilicon-errata-warn=@var{name}[,@var{name}@dots{}]
+Like the @option{-msilicon-errata} option except that instead of
+fixing the specified errata, a warning message is issued instead.
+This option can be used alongside @option{-msilicon-errata} to
+generate messages whenever a problem is fixed, or on its own in order
+to inspect code for potential problems.
+
+@item -mP
+enables polymorph instructions handler.
+
+@item -mQ
+enables relaxation at assembly time. DANGEROUS!
+
+@item -ml
+indicates that the input uses the large code model.
+
+@item -mn
+enables the generation of a NOP instruction following any instruction
+that might change the interrupts enabled/disabled state. The
+pipelined nature of the MSP430 core means that any instruction that
+changes the interrupt state (@code{EINT}, @code{DINT}, @code{BIC #8,
+SR}, @code{BIS #8, SR} or @code{MOV.W <>, SR}) must be
+followed by a NOP instruction in order to ensure the correct
+processing of interrupts. By default it is up to the programmer to
+supply these NOP instructions, but this command-line option enables
+the automatic insertion by the assembler, if they are missing.
+
+@item -mN
+disables the generation of a NOP instruction following any instruction
+that might change the interrupts enabled/disabled state. This is the
+default behaviour.
+
+@item -my
+tells the assembler to generate a warning message if a NOP does not
+immediately follow an instruction that enables or disables
+interrupts. This is the default.
+
+Note that this option can be stacked with the @option{-mn} option so
+that the assembler will both warn about missing NOP instructions and
+then insert them automatically.
+
+@item -mY
+disables warnings about missing NOP instructions.
+
+@item -md
+mark the object file as one that requires data to copied from ROM to
+RAM at execution startup. Disabled by default.
+
+@item -mdata-region=@var{region}
+Select the region data will be placed in.
+Region placement is performed by the compiler and linker. The only effect this
+option will have on the assembler is that if @var{upper} or @var{either} is
+selected, then the symbols to initialise high data and bss will be defined.
+Valid @var{region} values are:
+@table @code
+@item none
+@item lower
+@item upper
+@item either
+@end table
+
+@end table
@node MSP430 Syntax
@section Syntax
@table @code
-@item llo(exp)
+@item llo(exp)
Extracts least significant word from 32-bit expression 'exp'.
@item lhi(exp)
@item hlo(exp)
Extracts 3rd word from 64-bit expression 'exp'.
-@item hhi(exp)
+@item hhi(exp)
Extracts 4rd word from 64-bit expression 'exp'.
@end table
They normally being used as an immediate source operand.
@smallexample
- mov #llo(1), r10 ; == mov #1, r10
+ mov #llo(1), r10 ; == mov #1, r10
mov #lhi(1), r10 ; == mov #0, r10
@end smallexample
-
+
@node MSP430-Chars
@subsection Special Characters
@cindex line comment character, MSP 430
@cindex MSP 430 line comment character
-@samp{;} is the line comment character.
+A semicolon (@samp{;}) appearing anywhere on a line starts a comment
+that extends to the end of that line.
+
+If a @samp{#} appears as the first character of a line then the whole
+line is treated as a comment, but it can also be a logical line number
+directive (@pxref{Comments}) or a preprocessor control command
+(@pxref{Preprocessing}).
+
+@cindex line separator, MSP 430
+@cindex statement separator, MSP 430
+@cindex MSP 430 line separator
+Multiple statements can appear on the same line provided that they are
+separated by the @samp{@{} character.
@cindex identifiers, MSP 430
@cindex MSP 430 identifiers
-The character @samp{$} in jump instructions indicates current location and
+The character @samp{$} in jump instructions indicates current location and
implemented only for TI syntax compatibility.
@node MSP430-Regs
@end table
+Also, there are some instructions, which cannot be found in other assemblers.
+These are branch instructions, which has different opcodes upon jump distance.
+They all got PC relative addressing mode.
+
+@table @code
+@item beq label
+A polymorph instruction which is @samp{jeq label} in case if jump distance
+within allowed range for cpu's jump instruction. If not, this unrolls into
+a sequence of
+@smallexample
+ jne $+6
+ br label
+@end smallexample
+
+@item bne label
+A polymorph instruction which is @samp{jne label} or @samp{jeq +4; br label}
+
+@item blt label
+A polymorph instruction which is @samp{jl label} or @samp{jge +4; br label}
+
+@item bltn label
+A polymorph instruction which is @samp{jn label} or @samp{jn +2; jmp +4; br label}
+
+@item bltu label
+A polymorph instruction which is @samp{jlo label} or @samp{jhs +2; br label}
+
+@item bge label
+A polymorph instruction which is @samp{jge label} or @samp{jl +4; br label}
+
+@item bgeu label
+A polymorph instruction which is @samp{jhs label} or @samp{jlo +4; br label}
+
+@item bgt label
+A polymorph instruction which is @samp{jeq +2; jge label} or @samp{jeq +6; jl +4; br label}
+
+@item bgtu label
+A polymorph instruction which is @samp{jeq +2; jhs label} or @samp{jeq +6; jlo +4; br label}
+
+@item bleu label
+A polymorph instruction which is @samp{jeq label; jlo label} or @samp{jeq +2; jhs +4; br label}
+
+@item ble label
+A polymorph instruction which is @samp{jeq label; jl label} or @samp{jeq +2; jge +4; br label}
+
+@item jump label
+A polymorph instruction which is @samp{jmp label} or @samp{br label}
+@end table
+
@node MSP430 Floating Point
@section Floating Point
This directive is ignored; it is accepted for compatibility with other
MSP 430 assemblers.
-@cindex @code{sect} directive, MSP 430
+@cindex @code{arch} directive, MSP 430
@item .arch
-Currently this directive is ignored; it is accepted for compatibility with other
-MSP 430 assemblers.
-
+Sets the target microcontroller in the same way as the @option{-mmcu}
+command-line option.
+
+@cindex @code{cpu} directive, MSP 430
+@item .cpu
+Sets the target architecture in the same way as the @option{-mcpu}
+command-line option.
+
+@cindex @code{profiler} directive, MSP 430
+@item .profiler
+This directive instructs assembler to add new profile entry to the object file.
+
+@cindex @code{refsym} directive, MSP 430
+@item .refsym
+This directive instructs assembler to add an undefined reference to
+the symbol following the directive. The maximum symbol name length is
+1023 characters. No relocation is created for this symbol; it will
+exist purely for pulling in object files from archives. Note that
+this reloc is not sufficient to prevent garbage collection; use a
+KEEP() directive in the linker file to preserve such objects.
+
+@cindex @code{mspabi_attribute} directive, MSP430
+@item .mspabi_attribute
+This directive tells the assembler what the MSPABI build attributes for this
+file are. This is used for validating the command line options passed to
+the assembler against the options the original source file was compiled with.
+The expected format is:
+@samp{.mspabi_attribute tag_name, tag_value}
+For example, to set the tag @code{OFBA_MSPABI_Tag_ISA} to @code{MSP430X}:
+@samp{.mspabi_attribute 4, 2}
+
+See the @cite{MSP430 EABI, document slaa534} for the details on tag names and
+values.
@end table
@node MSP430 Opcodes
additional pseudo-instructions are needed on this family.
For information on the 430 machine instruction set, see @cite{MSP430
-User's Manual, document slau049b}, Texas Instrument, Inc.
+User's Manual, document slau049d}, Texas Instrument, Inc.
+
+@node MSP430 Profiling Capability
+@section Profiling Capability
+
+@cindex MSP 430 profiling capability
+@cindex profiling capability for MSP 430
+It is a performance hit to use gcc's profiling approach for this tiny target.
+Even more -- jtag hardware facility does not perform any profiling functions.
+However we've got gdb's built-in simulator where we can do anything.
+
+We define new section @samp{.profiler} which holds all profiling information.
+We define new pseudo operation @samp{.profiler} which will instruct assembler to
+add new profile entry to the object file. Profile should take place at the
+present address.
+
+Pseudo operation format:
+
+@samp{.profiler flags,function_to_profile [, cycle_corrector, extra]}
+
+
+where:
+
+@table @code
+
+@table @code
+
+@samp{flags} is a combination of the following characters:
+
+@item s
+function entry
+@item x
+function exit
+@item i
+function is in init section
+@item f
+function is in fini section
+@item l
+library call
+@item c
+libc standard call
+@item d
+stack value demand
+@item I
+interrupt service routine
+@item P
+prologue start
+@item p
+prologue end
+@item E
+epilogue start
+@item e
+epilogue end
+@item j
+long jump / sjlj unwind
+@item a
+an arbitrary code fragment
+@item t
+extra parameter saved (a constant value like frame size)
+@end table
+
+@item function_to_profile
+a function address
+@item cycle_corrector
+a value which should be added to the cycle counter, zero if omitted.
+@item extra
+any extra parameter, zero if omitted.
+
+@end table
+
+For example:
+@smallexample
+.global fxx
+.type fxx,@@function
+fxx:
+.LFrameOffset_fxx=0x08
+.profiler "scdP", fxx ; function entry.
+ ; we also demand stack value to be saved
+ push r11
+ push r10
+ push r9
+ push r8
+.profiler "cdpt",fxx,0, .LFrameOffset_fxx ; check stack value at this point
+ ; (this is a prologue end)
+ ; note, that spare var filled with
+ ; the farme size
+ mov r15,r8
+...
+.profiler cdE,fxx ; check stack
+ pop r8
+ pop r9
+ pop r10
+ pop r11
+.profiler xcde,fxx,3 ; exit adds 3 to the cycle counter
+ ret ; cause 'ret' insn takes 3 cycles
+@end smallexample