assemble.py

#
# This file is part of the micropython-esp32-ulp project,
# https://github.com/micropython/micropython-esp32-ulp
#
# SPDX-FileCopyrightText: 2018-2023, the micropython-esp32-ulp authors, see AUTHORS file.
# SPDX-License-Identifier: MIT

"""
ESP32 ULP Co-Processor Assembler
"""

importre
from .nocommentimportremove_commentsasdo_remove_comments
from .utilimportgarbage_collect

TEXT, DATA, BSS='text', 'data', 'bss'

REL, ABS=0, 1


classSymbolTable:
def__init__(self, symbols, bases, globals):
self._symbols=symbols
self._bases=bases
self._globals=globals

defset_bases(self, bases):
self._bases=bases

defset_from(self, from_section, from_offset):
self._from_section, self._from_offset=from_section, from_offset

defget_from(self):
returnself._from_section, self._from_offset

defset_sym(self, symbol, stype, section, value):
entry= (stype, section, value)
ifsymbolinself._symbolsandentry!=self._symbols[symbol]:
raiseException('redefining symbol %s with different value %r -> %r.'% (symbol, self._symbols[symbol], entry))
self._symbols[symbol] =entry

defhas_sym(self, symbol):
returnsymbolinself._symbols

defget_sym(self, symbol):
entry=self._symbols[symbol]
returnentry

defdump(self):
forsymbol, entryinself._symbols.items():
print(symbol, entry)

defexport(self, incl_non_globals=False):
addrs_syms= [(self.resolve_absolute(entry), symbol)
forsymbol, entryinself._symbols.items()
ifincl_non_globalsorsymbolinself._globals]
returnsorted(addrs_syms)

defto_abs_addr(self, section, offset):
base=self._bases[section]
returnbase+offset

defresolve_absolute(self, symbol):
ifisinstance(symbol, str):
stype, section, value=self.get_sym(symbol)
elifisinstance(symbol, tuple):
stype, section, value=symbol
else:
raiseTypeError
ifstype==REL:
returnself.to_abs_addr(section, value)
ifstype==ABS:
returnvalue
raiseTypeError(stype)

defresolve_relative(self, symbol):
ifisinstance(symbol, str):
sym_type, sym_section, sym_value=self.get_sym(symbol)
elifisinstance(symbol, tuple):
sym_type, sym_section, sym_value=symbol
else:
raiseTypeError
ifsym_type==REL:
sym_addr=self.to_abs_addr(sym_section, sym_value)
elifsym_type==ABS:
sym_addr=sym_value
from_addr=self.to_abs_addr(self._from_section, self._from_offset)
returnsym_addr-from_addr

defset_global(self, symbol):
self._globals[symbol] =True
pass


classAssembler:

def__init__(self, cpu='esp32', symbols=None, bases=None, globals=None):
ifcpu=='esp32':
opcode_module='opcodes'
elifcpu=='esp32s2':
opcode_module='opcodes_s2'
else:
raiseValueError('Invalid cpu')

relative_import=1if'/'in__file__else0
self.opcodes=__import__(opcode_module, None, None, [], relative_import)

self.symbols=SymbolTable(symbolsor {}, basesor {}, globalsor {})
self.opcodes.symbols=self.symbols# XXX dirty hack

# regex for parsing assembly lines
# format: [[whitespace]label:][whitespace][opcode[whitespace arg[,arg...]]]
# where [] means optional
# initialised here once, instead of compiling once per line
self.line_regex=re.compile(r'^(\s*([a-zA-Z0-9_$.]+):)?\s*((\S*)\s*(.*))$')

definit(self, a_pass):
self.a_pass=a_pass
self.sections=dict(text=[], data=[])
self.offsets=dict(text=0, data=0, bss=0)
self.section=TEXT

defparse_line(self, line):
"""
 parse one line of assembler into label, opcode, args.
 comments already have been removed by pre-processing.

 a line looks like (label, opcode, args, comment are all optional):

 label: opcode arg1, arg2, ...
 """
ifnotline:
return

matches=self.line_regex.match(line)
label, opcode, args=matches.group(2), matches.group(4), matches.group(5)

label=labeliflabelelseNone# force empty strings to None
opcode=opcodeifopcodeelseNone# force empty strings to None
args=tuple(arg.strip() forarginargs.split(',')) ifargselse ()

returnlabel, opcode, args

defsplit_statements(self, lines):
forlineinlines:
forstatementinline.split(';'):
yieldstatement.rstrip()

defparse(self, lines):
parsed= [self.parse_line(line) forlineinself.split_statements(lines)]
return [pforpinparsedifpisnotNone]


defappend_section(self, value, expected_section=None):
s=self.section
ifexpected_sectionisnotNoneandsisnotexpected_section:
raiseTypeError('only allowed in %s section'%expected_section)
ifsisBSS:
ifint.from_bytes(value, 'little') !=0:
raiseValueError('attempt to store non-zero value in section .bss')
# just increase BSS size by length of value
self.offsets[s] +=len(value)
else:
self.sections[s].append(value)
self.offsets[s] +=len(value)

deffinalize_sections(self):
# make sure all sections have a bytelength dividable by 4,
# thus having all sections aligned at 32bit-word boundaries.
forsinlist(self.sections.keys()) + [BSS, ]:
offs=self.offsets[s]
mod=offs%4
ifmod:
fill=int(0).to_bytes(4-mod, 'little')
self.offsets[s] +=len(fill)
ifsisnotBSS:
self.sections[s].append(fill)

defcompute_bases(self):
bases= {}
addr=0
# lay out sections in this order:
forsin [TEXT, DATA, BSS]: # TODO: more flexibility for custom sections
bases[s] =addr
addr+=self.offsets[s] //4# 32bit word addresses
returnbases

defdump(self):
print("Symbols:")
self.symbols.dump()
print("%s section:"%TEXT)
fortinself.sections[TEXT]:
print("%08x"%int.from_bytes(t, 'little'))
print("size: %d"%self.offsets[TEXT])
print("%s section:"%DATA)
fordinself.sections[DATA]:
print("%08x"%int.from_bytes(d, 'little'))
print("size: %d"%self.offsets[DATA])
print("%s section:"%BSS)
print("size: %d"%self.offsets[BSS])

deffetch(self):
defget_bytes(section):
returnb''.join(self.sections[section])

returnget_bytes(TEXT), get_bytes(DATA), self.offsets[BSS]

defd_text(self):
self.section=TEXT

defd_data(self):
self.section=DATA

defd_bss(self):
self.section=BSS

deffill(self, section, amount, fill_byte):
iffill_byteisnotNoneandsectionisBSS:
raiseValueError('fill in bss section not allowed')
ifsectionisTEXT: # TODO: text section should be filled with NOPs
raiseValueError('fill/skip/align in text section not supported')
fill=int(fill_byteor0).to_bytes(1, 'little') *amount
self.offsets[section] +=len(fill)
ifsectionisnotBSS:
self.sections[section].append(fill)

defd_skip(self, amount, fill=None):
amount=int(amount)
self.fill(self.section, amount, fill)

d_space=d_skip

defd_align(self, align=4, fill=None):
align=int(align)
offs=self.offsets[self.section]
mod=offs%align
ifmod:
amount=align-mod
self.fill(self.section, amount, fill)

defd_set(self, symbol, expr):
value=int(self.opcodes.eval_arg(expr))
self.symbols.set_sym(symbol, ABS, None, value)

defd_global(self, symbol):
self.symbols.set_global(symbol)

defappend_data(self, wordlen, args):
data= [int(arg).to_bytes(wordlen, 'little') forarginargs]
self.append_section(b''.join(data))

defd_byte(self, *args):
self.append_data(1, args)

defd_word(self, *args):
self.append_data(2, args)

defd_long(self, *args):
self.d_int(*args)

defd_int(self, *args):
# .long and .int are identical as per GNU assembler documentation
# https://sourceware.org/binutils/docs/as/Long.html
self.append_data(4, args)

defassembler_pass(self, lines):
forlabel, opcode, argsinself.parse(lines):
self.symbols.set_from(self.section, self.offsets[self.section] //4)
iflabelisnotNone:
self.symbols.set_sym(label, REL, *self.symbols.get_from())
ifopcodeisnotNone:
ifopcode[0] =='.':
# assembler directive
func=getattr(self, 'd_'+opcode[1:])
iffuncisnotNone:
result=func(*args)
ifresultisnotNone:
self.append_section(result)
continue
else:
# machine instruction
opcode_lower=opcode.lower()
func=getattr(self.opcodes, 'i_'+opcode_lower, None)
iffuncisnotNone:
ifself.a_pass==1:
# during the first pass, symbols are not all known yet.
# so we add empty instructions to the section, to determine
# section sizes and symbol offsets for pass 2.
result= (0,) *self.opcodes.no_of_instr(opcode_lower, args)
else:
result=func(*args)

ifnotisinstance(result, tuple):
result= (result,)

forinstructioninresult:
self.append_section(instruction.to_bytes(4, 'little'), TEXT)
continue
raiseValueError('Unknown opcode or directive: %s'%opcode)
self.finalize_sections()

defassemble(self, text, remove_comments=True):
lines=do_remove_comments(text) ifremove_commentselsetext.splitlines()
self.init(1) # pass 1 is only to get the symbol table right
self.assembler_pass(lines)
self.symbols.set_bases(self.compute_bases())
garbage_collect('before pass2')
self.init(2) # now we know all symbols and bases, do the real assembler pass, pass 2
self.assembler_pass(lines)
garbage_collect('after pass2')