firmware_tools/logic_memory_mapper/gen_txt.py

414 lines
17 KiB
Python

# -----------------------------------------------------------------------------
# Title : Text document definition package generator
# Project : Generic FW tools
# -----------------------------------------------------------------------------
# File : gen_cpp.py
# Author : Simon Southwell
# Company : Global Inkjet Systems
# Created : 2017-12-04
# Last update: 2017-12-11
# Platform :
# Standard : Python 3.x
# -----------------------------------------------------------------------------
# Description:
# Definition of class to read JSON register definitions and generate a set
# text document tables for address offsets and field definitions. Inherits
# MemMapperBase for methods to read JSON files and produce a model.
# -----------------------------------------------------------------------------
# Copyright (c) 2017 Global Inkjet Systems
# -----------------------------------------------------------------------------
import os
import sys
import argparse
# Import base class to locate and read JSON files, and present a model
# to derived child class.
import memMapperBase
from memMapperBase import MemMapperBase, attr, regtype
# ---------------------------------------------------------
# Class to generate a text document file with some
# register definitions, from the set of JSON definitions
# for a project.
# ---------------------------------------------------------
class MemMapperTxt(MemMapperBase):
# Define the classes 'constants'
# The list of characters at which a line might be split
splitChars = [' ', '=', '-', '+', ']', ',', '.']
# The widths of the table columns
colWidths = [37, 17, 18, 6, 6, 12, 41]
# The vertical separator specifications
vsepDict = {'topLine': ('+', '+', '=', '=', '=', '=', '=', '+'),
'topData': ('|', '|', '|'),
'regLine': ('+', '+', '+', '+', '+', '+', '+', '+'),
'regData': ('|', '|', '|', '|', '|', '|', '|', '|'),
'fldLine': ('|', '|', '+', '+', '+', '+', '+', '+')}
# The horizontal separator specifications
hsepDict = {'head' : ('=', '=', '=', '=', '=', '=', '='),
'reg' : ('-', '-', '-', '-', '-', '-', '-'),
'field' : (' ', ' ', '-', '-', '-', '-', '-')}
# ---------------------------------------------------------
# Constructor
# ---------------------------------------------------------
def __init__(self) :
print('MemMapperTxt')
# Remember the byte/word address mode
self.__useByteAddrs = False
MemMapperBase.__init__(self)
# ---------------------------------------------------------
# Configure the byte address output mode
# ---------------------------------------------------------
def setByteAddrMode(self, mode) :
self.__useByteAddrs = mode
# ---------------------------------------------------------
# Configure the byte address output mode
# ---------------------------------------------------------
def setRegColWidth(self, width):
self.colWidths[0] = width
# ---------------------------------------------------------
# Tries to break up a line of text into sections that will
# fit into strings less than a given length, returning
# in a list of strings
# ---------------------------------------------------------
@staticmethod
def __breakLine(dataStr, length):
strList = []
# Initially, the remaining string is the whole string
remainStr = dataStr
# Loop until the remaining string is at, or less than,
# the desired length
while len(remainStr) > length :
# Find nearest split point to end of entry width
idx = length
while idx != 0 and not remainStr[idx] in MemMapperTxt.splitChars:
idx -= 1
# Add the string to the list from the beginning up to, and including, the
# split character
strList.append(remainStr[:idx + 1])
# Delete the characters from the beginning to just beyond the split point
remainStr = remainStr[idx + 1:]
# After processing, any remaining string is added to the list
if len(remainStr) != 0 :
strList.append(remainStr)
# Return the list of split strings
return strList
# ---------------------------------------------------------
# Draws a horizontal line to the output stream using
# the specified vertical and horizontal separator specs.
# ---------------------------------------------------------
@staticmethod
def __drawHorizLine(fp=sys.stdout, vsepKey='topLine', hsepKey='head') :
# Go get the separator character lists
vsep = MemMapperTxt.vsepDict[vsepKey]
hsep = MemMapperTxt.hsepDict[hsepKey]
for idx in range(0 , len(vsep)-1) :
fp.write(vsep[idx])
fp.write(hsep[idx] * MemMapperTxt.colWidths[idx])
fp.write(vsep[-1] + '\n')
# ---------------------------------------------------------
# Draws a set of entry columns to the output stream using
# the specified vertical separator spec, and a list
# of strings for the columns.
# ---------------------------------------------------------
def __drawContents(self, fp=sys.stdout, vsepKey='topData', dataList=()) :
vsep = MemMapperTxt.vsepDict[vsepKey]
splitLine = []
for idx in range(0, len(vsep)-1) :
fp.write(vsep[idx])
dataStr = ' ' + dataList[idx]
# Create a list which, by default, has the data string in it, but
# might need splitting if too big for the width of the column
splitLine = [dataStr]
# On the last entry, make the width the sum of all remaining length,
# in case of spanning columns
if idx == len(vsep)-2 :
# Sum all the lengths from this column to the end, plus a space each for the deleted separators
entryLen = sum(MemMapperTxt.colWidths[idx:]) + (len(MemMapperTxt.colWidths) - idx - 1)
# If this last entry is too big for the column, convert it into
# a list if partial strings that will fit.
if len(dataStr) > entryLen :
splitLine = self.__breakLine(dataStr, entryLen-1)
else :
entryLen = MemMapperTxt.colWidths[idx]
# Will always process the first 'chunk', which might be the whole entry
dataStr = splitLine[0]
# Pad the entry string with spaces to make an entryLen sized string
if len(dataStr) < entryLen :
dataStr += ' ' * (entryLen - len(dataStr))
fp.write(dataStr)
fp.write(vsep[-1] + '\n')
# If the last entry was too big, and split up, print out the rest of the chunks.
if len(splitLine) > 1 :
for ix in range (1, len(splitLine)) :
self.__drawContents(fp, 'regData', [' ', ' ', ' ', ' ', ' ', ' ', splitLine[ix]])
# ---------------------------------------------------------
# Open file and print header
# ---------------------------------------------------------
def __openFile(self, jsonPath, jsonDict, opDir, ip, opSuffix, offsetStr) :
# What's the path separator? Usually '\\' for windows, else '/'
sep = os.sep
# Generate specific output in the doc/ directory where the JSON file is located
if opDir == '' :
srcDir = sep.join(jsonPath.split(sep)[:-1])
else :
srcDir = opDir
# Check destination directory exists, and create it if not
if not os.path.exists(srcDir) :
os.makedirs(srcDir)
# Get a camel case version of ip name
# ipNameCamel = self._underScore2CamelCase(ip)
# Construct the write file name (with a .txt suffix) and open it
writeFileName = srcDir + sep + ip + opSuffix + '.txt'
wfp = open(writeFileName, 'w')
# Address column header text dependant on byte/word address mode
if self.__useByteAddrs :
addrBannerStr = 'Byte Addr Offset'
else :
addrBannerStr = 'Word Addr Offset'
if offsetStr != '' :
wfp.write(offsetStr)
# Output a header with the block name and top level description. The description spans
# second column to the end.
self.__drawHorizLine(wfp, 'topLine', 'head')
self.__drawContents (wfp, 'topData', [jsonDict[0][attr.IP_NAME], jsonDict[0][attr.DESCRIPTION]])
self.__drawHorizLine(wfp, 'regLine', 'head')
self.__drawContents (wfp, 'regData', ['Register Name', addrBannerStr, 'Field', 'Bits', 'Type', 'Reset', 'Description'])
self.__drawHorizLine(wfp, 'regLine', 'head')
return wfp
# ---------------------------------------------------------
# Overload virtual function with specific output generation,
# and generate a text document file with some useful
# register definitions in it.
# ---------------------------------------------------------
def genOutput(self, ip, opDir='', opSuffix='') :
# Fetch the JSON path and the dictionary with the parsed data
jsonPath, jsonDict = self._getModel(ip)
# Write file point initialised to nothing (we may not need to output anything)
wfp = None
# If the IP block is listed in sub-block offsets dictionary, extract these offsets
offsetBannerStr = ''
if ip in self.subBlockOffsetsDict :
# Loop through the busses, to check for matches
for jsonBusDict in jsonDict:
# Get the stored data from the dictionary entry
for sbEntry in self.subBlockOffsetsDict[ip] :
offsetStr, bus, parentIp = sbEntry
# If the bus is a match, print the offset information
if bus == jsonBusDict[attr.BUS] :
offsetInt = int(offsetStr, 0)
if self.__useByteAddrs :
offsetInt *= 4
# Accumulate all the entries into a set of test lines
offsetBannerStr += 'Offset in ' + parentIp + ' for bus ' + bus + ' : 0x' + format(offsetInt, '08x') + '\n'
# Iterate through each bus dictionary
for jsonBusDict in jsonDict :
if attr.PROCESS_REGS in jsonBusDict:
if jsonBusDict[attr.PROCESS_REGS] != 'enabled':
continue
# If a pure hierarchy block, skip
if attr.REGISTERS not in jsonBusDict:
continue
# If we haven't opened the file yet, do so now and print header, as we have registers
elif wfp is None :
wfp = self.__openFile(jsonPath, jsonDict, opDir, ip, opSuffix, offsetBannerStr)
# Get the bus name from the dictionary
bus = jsonBusDict[attr.BUS]
# Only process the bus in the bus list
if bus in self.busList:
# Fetch the register diction from the model, and the list of register name keys.
# These were stored in and ordered dictionary, so should iterate in the order
# specified in the JSON files
regDict = jsonBusDict[attr.REGISTERS]
regKeys = regDict.keys()
# Loop through each register
for regName in regKeys :
# Create a camel case version of the register name
# regNameStr = ipNameCamel + self._underScore2CamelCase(regName) + bus.capitalize()
regNameStr = bus.upper() + '_' + ip.upper() + '_' + regName.upper()
# If no type, then type specified in fields, so blank the register type, else fetch it
if attr.TYPE in regDict[regName]:
regType = regDict[regName][attr.TYPE]
else:
regType = ' '
# If no reset, then reset specified in fields, so blank the register reset, else fetch it
if attr.RESET in regDict[regName]:
reset = regDict[regName][attr.RESET]
else:
reset = ' '
# Get the word address value form the dictionary, and convert to an integer value
addrVal = int(str(regDict[regName][attr.ADDRESS]), 0)
# If configured for byte address offset, multiply by 4
if self.__useByteAddrs :
addrVal *= 4
# Generate a hex string for the value (with a leading '0x')
addrStr = '0x' + format(addrVal, 'x')
# Gather together each column's string into a list for this register
entryList = [regNameStr,
addrStr,
' ',
regDict[regName][attr.WIDTH],
regType,
reset,
regDict[regName][attr.DESCRIPTION]]
# Draw the row for the register
self.__drawContents(wfp, 'regData', entryList)
# If there are fields for this register, process them here
if attr.FIELDS in regDict[regName] :
# Extract the fields section from the model
fields = regDict[regName][attr.FIELDS]
bitCount = 0
# Loop through each field entry
for fieldName in fields :
# Draw a horizontal separator line to the sub-field specification
self.__drawHorizLine(wfp, 'fldLine', 'field')
# If a reserved field, then no reset spec. so set a default, else extract from dictionary
if fields[fieldName][attr.TYPE] == regtype.RESERVED :
resetVal = '0'
else :
resetVal = fields[fieldName][attr.RESET]
bitLen = int(fields[fieldName][attr.BIT_LEN], 0)
if bitLen == 1 :
bitStr = str(bitCount)
else:
bitStr = str(bitCount - 1 + bitLen) + ':' + str(bitCount)
# Gather together each column's string into a list for this field
# (first two columns always blank)
entryList = [' ',
' ',
fieldName.upper(),
bitStr,
fields[fieldName][attr.TYPE],
resetVal,
fields[fieldName][attr.DESCRIPTION]
]
# Output the row for this field
self.__drawContents(wfp, 'regData', entryList)
bitCount += int(fields[fieldName][attr.BIT_LEN], 0)
# Output a horizontal separator for the register
self.__drawHorizLine(wfp, 'regLine', 'reg')
# Finish off the document and close the output file
wfp.write('\n')
wfp.close()
# --------------------------------------------------------------
# Parse the command line arguments
#
def processCmdLine() :
# Create a parser object
parser = argparse.ArgumentParser(description='Process command line options.')
# Process common command line options with inherited static base class method
MemMapperTxt.processCmdLine(parser)
# Specific command line options added here
parser.add_argument('-B', '--byte_addrs', dest='byteAddrs', default=False, action='store_true', help='Output uses byte addresses (default word)')
parser.add_argument('-w', '--reg_width', dest='regWidth', default=0, type=int, help='Specify register name column width')
return parser.parse_args()
# ###############################################################
# Only run if not imported (to test)
#
if __name__ == '__main__':
# Create an object for generating text document output
memMap = MemMapperTxt()
# Process the command line options
cmdArgs = processCmdLine()
if cmdArgs.regWidth != 0 :
memMap.setRegColWidth(cmdArgs.regWidth)
# Do initialisation for text object specific configurations
memMap.setByteAddrMode(cmdArgs.byteAddrs)
# Run the processing and generate output
memMap.run(cmdArgs.topBlock, cmdArgs.busList, cmdArgs.repoDir, cmdArgs.opDir, cmdArgs.opFileSuffix, 'txt', cmdArgs.jsonFile, cmdArgs.buildDir, cmdArgs.qsysSuffix)
del memMap