binutils-gdb/gas/doc/c-msp430.texi

@c Copyright (C) 2002-2024 Free Software Foundation, Inc.
@c This is part of the GAS manual.
@c For copying conditions, see the file as.texinfo.
@ifset GENERIC
@page
@node MSP430-Dependent
@chapter MSP 430 Dependent Features
@end ifset
@ifclear GENERIC
@node Machine Dependencies
@chapter MSP 430 Dependent Features
@end ifclear

@cindex MSP 430 support
@cindex 430 support
@menu
* MSP430 Options::              Options
* MSP430 Syntax::               Syntax
* 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)
@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
@menu
* MSP430-Macros::		Macros
* MSP430-Chars::                Special Characters
* MSP430-Regs::                 Register Names
* MSP430-Ext::			Assembler Extensions
@end menu

@node MSP430-Macros
@subsection Macros

@cindex Macros, MSP 430
@cindex MSP 430 macros
The macro syntax used on the MSP 430 is like that described in the MSP
430 Family Assembler Specification.  Normal @code{@value{AS}}
macros should still work.

Additional built-in macros are:

@table @code

@item llo(exp)
Extracts least significant word from 32-bit expression 'exp'.

@item lhi(exp)
Extracts most significant word from 32-bit expression 'exp'.

@item hlo(exp)
Extracts 3rd word from 64-bit expression 'exp'.

@item 	hhi(exp)
Extracts 4th 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	#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
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
implemented only for TI syntax compatibility.

@node MSP430-Regs
@subsection Register Names

@cindex MSP 430 register names
@cindex register names, MSP 430
General-purpose registers are represented by predefined symbols of the
form @samp{r@var{N}} (for global registers), where @var{N} represents
a number between @code{0} and @code{15}.  The leading
letters may be in either upper or lower case; for example, @samp{r13}
and @samp{R7} are both valid register names.

@cindex special purpose registers, MSP 430
Register names @samp{PC}, @samp{SP} and @samp{SR} cannot be used as register names
and will be treated as variables. Use @samp{r0}, @samp{r1}, and @samp{r2} instead.


@node MSP430-Ext
@subsection Assembler Extensions
@cindex MSP430 Assembler Extensions

@table @code

@item @@rN
As destination operand being treated as @samp{0(rn)}

@item 0(rN)
As source operand being treated as @samp{@@rn}

@item jCOND +N
Skips next N bytes followed by jump instruction and equivalent to
@samp{jCOND $+N+2}

@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

@cindex floating point, MSP 430 (@sc{ieee})
@cindex MSP 430 floating point (@sc{ieee})
The MSP 430 family uses @sc{ieee} 32-bit floating-point numbers.

@node MSP430 Directives
@section MSP 430 Machine Directives

@cindex machine directives, MSP 430
@cindex MSP 430 machine directives
@table @code
@cindex @code{file} directive, MSP 430
@item .file
This directive is ignored; it is accepted for compatibility with other
MSP 430 assemblers.

@quotation
@emph{Warning:} in other versions of the @sc{gnu} assembler, @code{.file} is
used for the directive called @code{.app-file} in the MSP 430 support.
@end quotation

@cindex @code{line} directive, MSP 430
@item .line
This directive is ignored; it is accepted for compatibility with other
MSP 430 assemblers.

@cindex @code{arch} directive, MSP 430
@item .arch
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
@section Opcodes

@cindex MSP 430 opcodes
@cindex opcodes for MSP 430
@code{@value{AS}} implements all the standard MSP 430 opcodes.  No
additional pseudo-instructions are needed on this family.

For information on the 430 machine instruction set, see @cite{MSP430
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