Preliminary asm_xtensa docs

[rkompass]

I wanted to try the CRC algorithms with the @micropython.asm_xtensa assembler and found that information on it is scarse.
So I wrote a preliminary document that I present here.
It's a mix of briefing on instructions (in comments) and test/demonstration code that I used to check the functionality.
You should be able to copy/save and run that.

The last function - which is a loop - seems to reveal a bug. It crashes the system if the loop takes too many iterations.

If someone is interested in transforming this to the official MP documentation I would like to join/collaborate. Perhaps @pythoncoder, who has done much of the docs already?

import array

# Initial info taken from https://github.com/micropython/micropython/commit/f76b1bfa9f59fcfa03837c6934ad51d2db3ff4a3

# Upon entry to the assembly function the registers a0, a12, a13, a14 are
# pushed to the stack and the stack pointer (a1) decreased by 16.  Upon
# exit, these registers and the stack pointer are restored, and ret.n is
# executed to return to the caller (caller address is in a0).
#
# Note that the ABI for the Xtensa emitters is non-windowing.
#
# The ESP8266 has an Xtensa lx106 processor at its core. This is a 32 bit RISC processor with 16 registers.
# This is a load/store machine with either 16 or 24 bit instructions. This leads to higher code density than with
# constant 32 bit encoding. We use only 32 bit instructions ????
#
# Available registers for asm_xtensa programs:
#
#   a2, a3, a4, a5          <--  function arguments
#   a2                      -->  return value
#   a2..a7, a12..a14             for computations
#   a0                           contains return address in subroutines
#   a1                           stack pointer
# 
#  There are no push/pop statements. Does that have to be done manually through a1?
#   -->  Yes. Use s32i and l32i.



#   Register move instructions and load/store from/to memory 
#  ==========================================================


#   Register move instructions
#  ----------------------------

#   mov(Ax, Ay)     Ax = Ay
#   movi(Ax, imm)   Ax = imm       can be full 32-bit, uses l32r if needed

@micropython.asm_xtensa
def ret42():
    movi(a0, 42)       # sets 42 as return value  (move immediate)
    mov(a2, a0)        # a2 is the register holding the return value, so move a0 value to a2
print('ret42: ',ret42())    # --> 42


#   Load register from memory
#  ---------------------------

#   l8ui( Ax, Ay, imm)    Ax = [Ay + imm]   Load a byte
#   l16ui(Ax, Ay, imm)    Ax = [Ay + imm]   Load a 16-bit unsigned half word
#   l16si(Ax, Ay, imm)    Ax = [Ay + imm]   Load a 16-bit signed half word, (extend the sign to 32 bits)
#   l32i( Ax, Ay, imm)    Ax = [Ay + imm]   Load a 32 bit word

ui8_arr  = array.array('B', ( 200,  201,  202,  203,  204))    # array of unsigned 8-bit integers
i8_arr   = array.array('b', (  -2,    -1,   0,    1,    2))    # array of signed 8-bit integers
ui16_arr = array.array('H', (   2,   30,  400, 5000, 60000))   # array of unsigned 16-bit integers
i16_arr  = array.array('h', (   5,    3,    1,   -1,   -3))    # array of signed 16-bit integers
i32_arr  = array.array('i', (  -1,    2,  -5 , 0, -10**9))     # array of 32-bit integers

@micropython.asm_xtensa
def load8ui(a2) -> int:
    l8ui(a4, a2, 1)                  # load the 8-bit byte from memory address (a2 + 1) into register a4
    mov(a2, a4)                      # a2 is return register so move the value to a2

@micropython.asm_xtensa
def load16ui(a2) -> int:
    l16ui(a2, a2, 8)                 # load 16-bit unsigned integer from memory address (a2 + 2*4) into register a4

@micropython.asm_xtensa
def load16si(a2) -> int:
    l16si(a2, a2, 8)                 # load 16-bit integer from memory address (a2 + 2*4) into register a2

@micropython.asm_xtensa
def load32i(a2) -> int:
    l32i(a2, a2, 16)                 # load 32-bit integer from memory address (a2 + 4*4) into register a2

print('load8ui: ',load8ui(ui8_arr))  # --> 201, this is the byte representing 201 in the array with typecode 'B'
print('load8ui: ',load8ui(i8_arr))   # --> 255, this is the byte representing -1 in the array with typecode 'b'
print('load16ui: ',load16ui(ui16_arr))   # --> 60000
print('load16si: ',load16si(i16_arr))   # --> -3, the sign was extended to 32 bits
print('load32i: ',load32i(i32_arr))   # --> -1000000000


#   Store register to memory
#  --------------------------

#   s8i( Ax, Ay, imm)    [Ay + imm] = Ax   Store a byte
#   s16i(Ax, Ay, imm)    [Ay + imm] = Ax   Store a 16 bit half word
#   s32i(Ax, Ay, imm)    [Ay + imm] = Ax   Store a 32 bit word

@micropython.asm_xtensa
def store8i(a2, a3):
    s8i(a2, a3, 1)
store8i(5, i8_arr)                   # store 5 at index 1 into array('b', [-2, -1, 0, 1, 2])
  
@micropython.asm_xtensa
def store16i(a2, a3):
    s16i(a2, a3, 6)
store16i(-5, i16_arr)                # store -5 at index 3 into array('h', [5, 3, 1, -1, -3])

print('store8i: ', i8_arr)           # --> array('b', [-2, 5, 0, 1, 2])
print('store16i: ', i16_arr)         # --> array('h', [5, 3, 1, -5, -3])



#   Logical & bitwise instructions
#  ================================

#   Logical instructions
#  ----------------------

#   and_(Ax, Ay, Az)      Ax = Ay & Az
#   or_(Ax, Ay, Az)       Ax = Ay | Az
#   xor(Ax, Ay, Az)       Ax = Ay ^ Az

@micropython.asm_xtensa
def and_(a2, a3) -> uint:
    and_(a2, a2, a3)

@micropython.asm_xtensa
def or_(a2, a3) -> uint:
    or_(a2, a2, a3)

@micropython.asm_xtensa
def xor(a2) -> uint:
    movi(a3, 0xffffff00)  #  imm value of movi can be full 32-bit, uses l32r if needed
    xor(a2, a2, a3)       #  a2 ^= 0xffff0000, complement upper 24 bits

print('and_:', f'0b{and_(0b000001110101, 0b110011001100):012b}')      # --> 0b000001000100
print(' or_:',  f'0b{or_(0b000001110101, 0b110011001100):012b}')      # --> 0b110011111101
print('xor:', f'0b{xor(0b110011001100):32b}')     # --> 0b11111111111111111111001111001100


#   Shift instructions (not implemented yet, but we may circumvent that)
#  ----------------------------------------------------------------------

#   instruction                                              usage with data() instruction
#
#   ssl(Ax)        L = Ax          Set left shift            data(3, 0x401000 | x<<8)
#   ssr(Ax)        R = Ax          Set right shift           data(3, 0x400000 | x<<8)
#   sll(Ax, Ay)    Ax = Ay << L    Shift left                data(3, 0xa10000 | x<<12 | y<<8)
#   srl(Ax, Ay)    Ax = Ay << R    Logical shift right       data(3, 0x910000 | x<<12 | y<<4)
#   sra(Ax, Ay)    Ax = Ay << R    Arithmetic shift right    data(3, 0xb10000 | x<<12 | y<<4)
#
#   slli(Ax, Ay, imm4)  AX = Ay << imm4  Shift left imm.     data(3, 0x110000 | x<<12 | y<<8 | (16-imm4)<<4)
#      slli(Ax, Ay, imm5) with imm5 > 16 may be coded as     data(3, 0x010000 | x<<12 | y<<8 | (32-imm5)<<4)
#   srli(Ax, Ay, imm4)  AX = Ay >> imm4  L. sh. right imm.   data(3, 0x410000 | x<<12 | y<<4 | imm4<<8)
#   srai(Ax, Ay, imm4)  AX = Ay >> imm4  A. sh. right imm.   data(3, 0x210000 | x<<12 | y<<4 | imm4<<8)
#      srai(Ax, Ay, imm5) with imm5 > 15 may be coded as     data(3, 0x310000 | x<<12 | y<<4 | (imm5-8)<<8)

@micropython.asm_xtensa
def sll(a2, a3) -> int:
    data(3, 0x401000 | 3<<8)            # ssl(a3)      L = a3
    data(3, 0xa10000 | 2<<12 | 2<<8)    # sll(a2, a2)  a2 = a2 << L
@micropython.asm_xtensa
def srl(a2, a3) -> int:                 # a2 << a3  logical shift
    data(3, 0x400000 | 3<<8)            # ssr(a3)      R = a4
    data(3, 0x910000 | 2<<12 | 2<<4)    # srl(a2, a2)  a2 = a2 >> R
@micropython.asm_xtensa
def sra(a2, a3, a4) -> int:             # a3 << a4, arithmetic shift,  (ignore a2)
    data(3, 0x400000 | 4<<8)            # ssr(a4)      R = a4
    data(3, 0xb10000 | 2<<12 | 3<<4)    # sra(a2, a3)  a2 = a3 >> R
@micropython.asm_xtensa
def slli_3(a2) -> int:
    data(3, 0x110000 | 2<<12 | 2<<8 | (16-3)<<4)  # slli(a2, a2, 3)  a2 = a2 << 3
@micropython.asm_xtensa
def slli_17(a2) -> int:
    data(3, 0x010000 | 2<<12 | 2<<8 | (32-17)<<4)  # slli(a2, a2, 3)  a2 = a2 << 17
@micropython.asm_xtensa
def srli_1(a2) -> int:
    data(3, 0x410000 | 2<<12 | 2<<4 | 1<<8)  # srli(a2, a2, 2)  a2 = a2 >> 1
@micropython.asm_xtensa
def srai_1(a2) -> int:
    data(3, 0x210000 | 2<<12 | 2<<4 | 1<<8)  # srai(a2, a2, 1)  a2 = a2 << 3

print('sll:', sll(7, 5))                #  -->   7>>5  =  7*32  =  224
print('srl:', srl(-337, 5))             #  -->  (-337 & 0xffffffff) >> 5 =  134217717
print('sra:', sra(1, -337, 5))          #  -->   -337>>5  =  -337//32  =  -11
print('slli_3:', slli_3(33))            #  -->   33<<3  =  733*8  =  264
print('slli_17:', slli_17(33))          #  -->   33<<17 =  733 * 2**17  = 4325376
print('srli_1:', srli_1(39))            #  -->   39>>1  =  39//2  =  9
print('srai_1:', srai_1(-39))           #  -->  -39>>2  =  -39//2  !=  -20  !!!! arithmetic shift with sign !!!!



#   Arithmetic instructions
#  =========================

#   add(Ax, Ay, Az)       Ax = Ay + Az
#   sub(Ax, Ay, Az)       Ax = Ay - Az
#   mull(Ax, Ay, Az)      Ax = Ay * Az    lower 32 bits, mAy be used for signed and unsigned multiplication
#   addi(Ax, Ay, imm)     Ax = Ay + imm   Addition with immediate value -128 <= imm < 127

@micropython.asm_xtensa
def add(a2, a3) -> int:
    add(a2, a2, a3)

@micropython.asm_xtensa
def sub(a2, a3) -> int:
    sub(a2, a2, a3)

@micropython.asm_xtensa
def mull(a2, a3) -> int:
    mull(a2, a2, a3)

@micropython.asm_xtensa
def addi_n100(a2) -> int:
    addi(a2, a2, -100)

@micropython.asm_xtensa
def addi_p100(a2) -> int:
    addi(a2, a2, 100)

print('add:', add(7, 5))                #  -->  7 + 5 =  12
print('sub:', sub(7, -68))              #  -->  7 - (-68) = 75
print('mull:', mull(7, 8))              #  -->  7 * 8 = 56
print('mull:', mull(-7, 8))             #  -->  (-7) * 8 = -56
print('mull:', mull(-7, -52))           #  -->  (-7) * (-5) = 364
print('addi_n100:', addi_n100(-7))      #  -->  (-7) -100 = -107
print('addi_p100:', addi_p100(-7))      #  -->  (-7) +100 = 93



#   Jump and branch instructions
#  ==============================

#   label(LABEL)              Defines a label within the assember code, LABEL is a string without quotes
#   j(LABEL)                  Unconditional jump to the label LABEL
#   jx(Ax)                    Unconditional jump to the address in register Ax

@micropython.asm_xtensa
def j_label() -> int:
    movi(a2, 42)
    j(over)                   # comment jump out --> 52
    addi(a2, a2, 10)
    label(over)

print('j_label:', j_label())


#   beqz(Ax, label)           If Ax == 0  branch to label 
#   bnez(Ax, label)           If Ax != 0  branch to label
#   bgez(Ax, label)           If Ax >= 0 branch to label     <---- this is missing yet, unfortunately

#   beq(Ax, Ay, label)        If Ax == Ay  branch to label
#   bne(Ax, Ay, label)        If Ax != Ay  branch to label
#   bge(Ax, Ay, label)        If As >= Ay  branch to label   (twos complement)
#   bgeu(Ax, Ay, label)       If As >= Ay  branch to label   (unsigned)
#   blt(Ax, Ay, label)        If As <  Ay  branch to label   (twos complement)

#   ball(Ax, Ay, label)       If Ax & Ay == Ay branch to label     (all bits specified by mask Ay are set in Ax)
#   bnall(Ax, Ay, label)      If Ax & Ay < Ay  branch to label     (any bit spec. by mask Ay is not set in Ax)
#   bany(Ax, Ay, label)       If Ax & Ay > 0   branch to label     (any bit specified by mask Ay is set in Ax)
#   bnone(Ax, Ay, label)      If Ax & Ay == 0  branch to label     (no bit specified by mask Ay is set in Ax)
#   bbs(Ax, Ay, label)        If Ax & (1<<Ay) > 0  branch to label  (the bit at position Ay is set in Ax)
#   bbc(Ax, Ay, label)        If Ax & (1<<Ay) == 0 branch to label  (the bit at position Ay is clear in Ax)


@micropython.asm_xtensa
def bany(a2) -> int:
    movi(a3, 1)
    bany(a2, a3, set2)
    movi(a2, 3)
    j(end)
    label(set2)
    movi(a2, 2)
    label(end)

@micropython.asm_xtensa
def bbs(a2) -> int:
    movi(a3, 1)
    bbs(a2, a3, set2)
    movi(a2, 3)
    j(end)
    label(set2)
    movi(a2, 2)
    label(end)
    
@micropython.asm_xtensa
def loop_mul(a2, a3) -> int:
    movi(a4, 0)
    label(loop)
    add(a4, a4, a3)
    addi(a2, a2, -1)    # a2 -= 1
    bnez(a2, loop)  # if a2 != 0 loop  , crashes if a2 >> 40_000_000
    mov(a2, a4)

print('bany:', [bany(i) for i in range(10)])   # --> [3, 2, 3, 2, 3, 2, 3, 2, 3, 2]
print('bbs:', [bbs(i) for i in range(10)])     # --> [3, 3, 2, 2, 3, 3, 2, 2, 3, 3]
print('loop_mul:', loop_mul(38_000_000, 9))    # --> 342000000, o.k., but sometimes crashes

#   Subroutine call and return
#  ============================

#   call(label)       Direct call to subroutine at label  <---- this is missing yet, unfortunately
#   callx0(Ax)        Call subroutine at address [Ax]   (the PC will be saved in a0)
#   ret_n()           Return from subroutine, same as jx(a0), but is a 16-bit instead of 24-bit instruction

[peterhinch]

Congratulations on this. Documentation on the xtensa assembler would be great.

The last function - which is a loop - seems to reveal a bug. It crashes the system if the loop takes too many iterations.

I'm guessing here but I believe the MicroPython runtime yields periodically to FreeRTOS. Is it possible that the loop is simply blocking for too long? This could be verified (or otherwise) by running other blocking loops in assembler or C.

Re collaboration I don't think I'm your man. I did write most of the ARMV7 inline assembler docs but I did this from a position of some knowledge: I'd studied the ARM Assembler manual, I'd written inline assembler code and knew the C code of the MP asm emitter. By contrast my knowledge of the ESPx architecture is minimal, having only coded for it in Python.

I hope someone steps up who can bring some relevant knowledge and experience to this worthwhile task.

[rkompass]

Re collaboration I don't think I'm your man.

I thought you were :-). Thank you anyway.
Someone with better knowledge of the ESP32 certainly would be helpful. asm_xtensa seems not to work reliably there. At least I saw such a statement in an older conversation.

[Josverl]

Recently I created an initial POC for stubs/documentation for the rp2 asm_pio emitter. That works reasonably well.

I know @jimmo was working on using stubs as the source for generating documentation.

Combining these approaches might also work for the extensa emitter.
That would allow for the documentation to be written once in Python / machine readable format, and also converted into sphinx online documentation.

I could help on the approach, structure and format, not so much on the esp32 parts

[rkompass]

Hello Jos,

interesting idea. I'm not familiar with that concept though.

Recently I created an initial POC for stubs/documentation for the rp2 asm_pio emitter. That works reasonably well.

Do you have a pointer to that code and the resulting documentation?
Atm I cannot judge what the advantages are. Having everything in one place should be an advantage. Other arguments?

[Josverl]

I posted in the rp2 topic https://github.com/orgs/micropython/discussions/12944

And the POC is here https://github.com/Josverl/PIO_ASM_typing

I've not tried generating the content yet,

[rkompass]

That seems a bit complicated for me. I will see that I get a pull request for the docs finished in the future.

[rkompass]

Update: Also a viper loop of a few seconds blocks the FreeRTOS and leads to a crash.
Adding print statements inside the viper code doesn't help.
But calling a time.sleep_us(1) periodically inside the viper code does help and apparently allows for the pending (soft??) interrupts to get processed.

As it is related to the state of the docs I present some investigations of the generated assembler code.
This inspect function works well on the 8266 too:

# Code originally from dhylands: https://forum.micropython.org/viewtopic.php?f=2&t=1295&p=7901

import machine
from array import array

@micropython.asm_xtensa
def asm_ret123():
    movi(a2, 123)        # 0x7b

@micropython.viper
def vip_ret123() -> int:
    return 123       # 0x7b

@micropython.asm_xtensa
def asm_add_43981(a2):
    movi(a12, 43981)
    add(a2, a2, a12)      # 0xabcd

def inspect(f, nbytes=80):
    import machine
    import array
    import ubinascii
    @micropython.asm_xtensa
    def dummy_asm():
        pass
    @micropython.viper
    def dummy_vip() -> int:
        return 0
    if type(f) == type(dummy_asm):
        offs = 0
    elif type(f) == type(dummy_vip):
        offs = 4
    else:
        raise ValueError('expecting an asm_thumb or viper function')
    baddr = bytes(array.array('O', [f]))
    addr = int.from_bytes(baddr, 'little')
    print('{:s} function object at: 0x{:08x}'.format(('asm_thumb' if offs==0 else 'viper'), addr))
    print('number of args: %u' % machine.mem32[addr + offs + 4])   # don't rely on this
    code_addr = machine.mem32[addr + offs+ 8]     # good for asm_xtensa, and for viper in uPy 1.21, esp8266
    print('machine code at: 0x%08x' % code_addr)  # seems to fit even with viper : code begins with 'FE B5' and ends with 'FE BD'
    print('-- code --')
    for i in range(nbytes):
        print('%02x' % machine.mem8[code_addr + i], end='')
    print('\n----------')

def test():
    inspect(vip_ret123)

test()

The resulting hexadecimal code from e.g.

viper function object at: 0x3ffef500
number of args: 0
machine code at: 0x401079e8
-- code --
0600000012c1e00901c911d921e931f941f812f83ff85f2d033d04ed0556530042a00047120842a000022f2cc0000022a07b32a002084fc00000c6fffff841e831d821c811080112c1200df006010000
----------

may be put into a hex editor (I used bless) to save it to a file and then from the sdk/toolchain one may use the xtensa version of objdump to disassemble the code. (I did not find an online disassembler).
Assuming the hex code file is insp.bin a suitable command is
xtensa-lx106-elf-objdump -b binary -m xtensa --adjust-vma 0x40107a54 -D insp.bin.

Now the results (after some editing):

# We investigate the assembly of:

@micropython.asm_xtensa
def asm_ret123():
    movi(a2, 123)          #  hex(123) = 0x7b

Upon entry to the assembly function the registers a0, a12, a13, a14 and 15 are
pushed to the stack and the stack pointer (a1) decreased by 32.  Upon
exit, these registers and the stack pointer are restored, and ret.n is
executed to return to the caller (caller address is in a0).

401079c0:   060100     j  0x401079c8              # jump over to actual program start
401079c3:   00                                    # probably just an align to 32 bits
401079c4:   7b000000                              <-- the value 123 = 0x0000007b

401079c8:   12c1e0       addi     a1, a1, -32     # actual program start: stack pointer a1 is decreased by 32
401079cb:   0901         s32i.n   a0, a1, 0       # the registers a0, a12, a13, a14 and a15 are pushed on the stack
401079cd:   c911         s32i.n   a12, a1, 4      # there is room for another three 32-bit values left
401079cf:   d921         s32i.n   a13, a1, 8
401079d1:   e931         s32i.n   a14, a1, 12
401079d3:   f941         s32i.n   a15, a1, 16
401079d5:   21fbff       l32r     a2, 0x401079c4    <-- the asm_xtensa movi instr. uses the l32r load32 bit relative.
401079d8:   f841         l32i.n   a15, a1, 16     # finish: restore registers 15, a14, 13, 
401079da:   e831         l32i.n   a14, a1, 12
401079dc:   d821         l32i.n   a13, a1, 8
401079de:   c811         l32i.n   a12, a1, 4
401079e0:   0801         l32i.n   a0, a1, 0
401079e2:   12c120       addi     a1, a1, 32      # and increase the stack pointer by 32 to its old value
401079e5:   0df0         ret.n                    # return to the caller (a0 --> next PC)

############################################

@micropython.asm_xtensa
def asm_add_43981(a2):
    movi(a12, 0xabcd)        # hex(43981) = 0xabcd
    add(a2, a2, a12)

40107a54:   060100           j   0x40107a5c
40107a57:   00
40107a58:   cdab0000                                <-- the value 43981 = 0x0000abcd  (bytes:  cd ab 00 00)
40107a5c:   12c1e0       addi     a1, a1, -32       # actual program start: stack pointer a1 is decreased by 32
40107a5d:   0901         s32i.n   a0, a1, 0         # the registers a0, a12, a13, a14 and a15 are pushed on the stack
40107a60:   c911         s32i.n   a12, a1, 4        # there is room for another three 32-bit values left
40107a63:   d921         s32i.n   a13, a1, 8
40107a65:   e931         s32i.n   a14, a1, 12
40107a67:   f941         s32i.n   a15, a1, 16
40107a69:   c1fbff       l32r     a12, 0x40107a58   <-- load a12 with value 0x0000abcd at this address
40107a6c:   c02280       add      a2, a2, a12       <-- and add to a2
40107a6f:   f841         l32i.n   a15, a1, 16
40107a71:   e831         l32i.n   a14, a1, 12
40107a73:   d821         l32i.n   a13, a1, 8
40107a75:   c811         l32i.n   a12, a1, 4
40107a77:   0801         l32i.n   a0, a1, 0
40107a79:   12c120       addi   a1, a1, 32
40107a7c:   0df0         ret.n

############################################

@micropython.viper
def vip_ret123() -> int:
    return 123       # 0x7b

40107a54:   060000       j   0x40107a58
40107a57:   00
40107a58:   12c1e0       addi     a1, a1, -32       # actual program start: stack pointer a1 is decreased by 32
40107a5a:   0901         s32i.n   a0, a1, 0         # the registers a0, a12, a13, a14 and a15 are pushed on the stack
40107a5d:   c911         s32i.n   a12, a1, 4
40107a5f:   d921         s32i.n   a13, a1, 8
40107a61:   e931         s32i.n   a14, a1, 12
40107a63:   f941         s32i.n   a15, a1, 16
40107a65:   f812         l32i.n   a15, a2, 4        # a15 = [a2+4]          pointer lookup, use a2 for that
40107a67:   f83f         l32i.n   a15, a15, 12      # a15 = [[a2+4]+12]
40107a69:   f85f         l32i.n   a15, a15, 20      # a15 = [[[a2+4]+12]+20]
40107a6b:   2d03         mov.n    a2, a3            # a3, a4, a5   --> a2, a3, a14
40107a6d:   3d04         mov.n    a3, a4
40107a6f:   ed05         mov.n    a14, a5
40107a71:   565300       bnez   a3, 0x40107a7a    
40107a74:   42a000       movi   a4, 0
40107a77:   471208       beq   a2, a4, 0x40107a83
40107a7a:   42a000       movi   a4, 0
40107a7d:   022f2c       l32i   a0, a15, 176
40107a80:   c00000       callx0   a0
40107a83:   22a07b       movi   a2, 123            <-- the return value
40107a86:   32a002       movi   a3, 2
40107a89:   084f         l32i.n   a0, a15, 16
40107a8b:   c00000       callx0   a0
40107a8e:   c6ffff       j   0x40107a91            <-- jump to register pop from stack
40107a91:   f841         l32i.n   a15, a1, 16
40107a93:   e831         l32i.n   a14, a1, 12
40107a95:   d821         l32i.n   a13, a1, 8
40107a97:   c811         l32i.n   a12, a1, 4
40107a99:   0801         l32i.n   a0, a1, 0
40107a9b:   12c120       addi     a1, a1, 32
40107a9e:   0df0         ret.n

These examples nicely demonstrate how registers are pushed to and popped from the stack --> needs to go into the docs too.
Also the asm_xtensa code seems absolutely unbloated. In the viper code there is nested pointer lookup and register checks (for number and type of arguments perhaps).

[jonnor]

This documentation seems very relevant. Thanks a lot for doing the research. Right now there is not even a mention of the existence of asm_xtensa in the MicroPython documentation, so it is impossible for people to get started with it. From this perspective, almost any addition to the documentation would be a good step forward.

[jonnor]

Related, I also note that there are no automated tests for asm_xtensa. So it would be really great to have at least some basic test coverage for this feature. At least running on ESP32, which is a very popular port. For asm_thumb there is a good startingpoint under the tests/inlineasm directory.

[rkompass]

Thanks for the feedback.
Are you aware that asm_xtensa only works on the esp8266? For esp32 we have the same instructions but a windowing schema of register usage. So someone would have to figure out how to enable asm_xtensawin.
Given that may be achieved I would suggest to complete the missing instruction set, which seems simple. Also a universal assembler option is thinkable, as the xtensa and arm instructions are basically the same. I guess the RISC instructions (and x64??) are too.
So from a programmers perspective it would be a huge gain to be able to code certain routines with pointers operating over arrays regardless of the underlying architecture yet faster than with viper.
At present this may be the most important limiting factor for the use of asm_...

[jonnor]

No, I was not aware of that, that is a good clarification. So it sounds like getting assembler to work on ESP32 will require a fair bit of work, not just documenting and testing.