firmware_tools/logic_memory_mapper/gen_htm.py

570 lines
25 KiB
Python

# -----------------------------------------------------------------------------
# Title : HTML document definition package generator
# Project : Generic FW tools
# -----------------------------------------------------------------------------
# File : gen_htm.py
# Author : Simon Southwell
# Company : Global Inkjet Systems
# Created : 2018-03-21
# Last update: 2018-03-21
# Platform :
# Standard : Python 3.x
# -----------------------------------------------------------------------------
# Description:
# Definition of class to read JSON register definitions and generate a set
# of HTML document tables for address offsets and field definitions. Inherits
# MemMapperBase for methods to read JSON files and produce a model.
# -----------------------------------------------------------------------------
# Copyright (c) 2018 Global Inkjet Systems
# -----------------------------------------------------------------------------
import os
import sys
import argparse
import datetime
import base64
# 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 MemMapperHtm(MemMapperBase):
# Define the classes 'constants'
# ---------------------------------------------------------
# Constructor
# ---------------------------------------------------------
def __init__(self) :
print('MemMapperHtm')
# Remember the byte/word address mode
self.__useByteAddrs = False
# Definitions for the look-and-feel of the HTML output
self.__textFontSize = '10pt'
self.__tableMargin = '20px'
self.__tableWidth = '850px'
self.__notesWidth = '800px'
self.__notesMargin = '30px'
self.__keyHdrMargin = '20px'
self.__keyMargin = '30px'
self.__keyWidth = '500px'
self.__textFont = 'Helvetica, Arial, sans-serif'
self.__codeFont = '"Lucida Console", Monaco, monospace'
self.__lineColour = '#80c0c0'
self.__gisColour = '#009ab0'
# Size of image data in the HTML after which a newline is inserted
# (has no affect on the viewed HTML, only the source)
self.__imagePrintWidth = 128
# The number of columns in the register table
self.__numOfCols = 7
MemMapperBase.__init__(self)
# ---------------------------------------------------------
# Configure the byte address output mode
# ---------------------------------------------------------
def setByteAddrMode(self, mode) :
self.__useByteAddrs = mode
# ---------------------------------------------------------
# Configure the byte address output mode
# ---------------------------------------------------------
def setWidth(self, width):
self.__tableWidth = width
# ---------------------------------------------------------
# Process a notes string and format to output
# ---------------------------------------------------------
def __genNotes(self, wfp, notesStr):
# Open up a section for notes, and a <div> section with its own
# width and indent paramters
wfp.write('<h2>Usage Notes</b></h2>\n<div style="width:' + self.__notesWidth + '">\n<p style="margin-left:' +
self.__notesMargin + '">\n ')
# Create a flag to indicate that an HTTP link is being scanned
httpPending = False
# Loop through the notes string printing out the characters, and doing look-ahead
# for paragraph indicatores ('. ') and HTTP links.
for idx in range(len(notesStr)) :
# Output the currently indexed character
wfp.write(notesStr[idx])
# Look ahead for the paragraph marker ('. ') and insert tags to close
# current paragraph and open a new one.
if idx < len(notesStr)-3 and notesStr[idx:idx+3] == '. ' :
wfp.write('\n</p>\n<p style="margin-left:' + self.__notesMargin + '">\n')
# Look ahead for an http reference and insert tags to open up an anchor with
# an href to the link. Flag that an HTTP is pending
if idx < len(notesStr)-8 and (notesStr[idx+1:idx+8] == 'http://' or notesStr[idx+1:idx+8] == 'https:/'):
wfp.write('<a href="')
httpPending = True
# If an HTTP is pending, look ahead for termination markers, such as the end of the string,
# or a space, comma or full-stop followed by a space. When terminated, clear httpPending, and
# insert the end of the anchor tag, add some text ('this link') and a close anchor tag.
if httpPending and (idx == len(notesStr)-1 or notesStr[idx+1] == ' ' or notesStr[idx+1] == ',' or notesStr[idx+1] == ')' or notesStr[idx+1:idx+3] == '. '):
httpPending = False
wfp.write('">this link</a>')
wfp.write('\n</p>\n</div>\n')
# ----------------------------------------------------------
# Generate a copyright message and a timestamp
# ----------------------------------------------------------
@staticmethod
def __genCopyright(wfp):
# Get the data and output a copyright message for the current year
now = datetime.datetime.now()
# Output a horizontal rule and a copright messsage with this year's value
wfp.write('<p>&nbsp;</p><hr>\n<p style="font-style:italic">Copyright &copy; ' + str(
now.year) + ' Global Inkjet Systems. ')
# Output a 'generated' message with a time stamp
wfp.write('Generated by gen_htm.py &mdash;' + str(now.year) + '-' + str(now.month) + '-' + str(now.day) + ' ' +
format(now.hour, '02d') + ':' + format(now.minute, '02d') + '</p>\n')
# ---------------------------------------------------------
# Output a key table defining the register types
# ---------------------------------------------------------
def __genTypeKey(self) :
notesStr = '\n<p style="margin-left:' + self.__keyHdrMargin + '"><i>Register/field type key:</i></p>\n\n'
notesStr += '<table id="key" style="margin-left:' + self.__keyMargin + '">\n'
notesStr += '<tr>\n'
notesStr += '<th>Type</th><th>Description</th>\n'
notesStr += '</tr>\n'
notesStr += '<tr>\n'
notesStr += '<td>c</td><td>Constant, with value defined by "reset" attribute\n'
notesStr += '</tr>\n'
notesStr += '<tr>\n'
notesStr += '<td>rsv</td><td>Same as constant, except no reset value and always 0. Can be mixed with write types.</td>\n'
notesStr += '</tr>\n'
notesStr += '<tr>\n'
notesStr += '<td>w</td><td>Write register (and read—no write only type). Register defined in register block and reset to "reset" attribute value. Split into fields (if applicable) for signalling and output, where attribute associated with fields, not register.</td>\n'
notesStr += '</tr>\n'
notesStr += '<tr>\n'
notesStr += '<td>wp</td><td>Write with pulse. Register is not declared in block, but write bus split into fields as output port signals, and a pulse generated on write to register address. Register reads back 0. The "reset" attribute is for documentation only, as set externally.</td>\n'
notesStr += '</tr>\n'
notesStr += '<tr>\n'
notesStr += '<td>w0</td><td>Same as w, but auto-clears to 0 (and thus always reads as 0). At output port, signal will go high for one cycle when bit is written with a 1 (no effect if written to a 0). No "reset" attribute, as must always be 0.</td>\n'
notesStr += '</tr>\n'
notesStr += '<tr>\n'
notesStr += '<td>r</td><td>Read only value. Input ports generated for each field (where applicable), and concatenated on returned read data bus.</td>\n'
notesStr += '</tr>\n'
notesStr += '<tr>\n'
notesStr += '<td>rp</td><td>Similar to r, but a pulse generated on a read access to the register address to allow peripheral logic to update value. The "reset" attribute is for documentation only, as set externally.</td>\n'
notesStr += '</tr>\n'
notesStr += '<tr>\n'
notesStr += '<td>rwp</td><td>Similar to wp, but also generates a (separate) pulse on a read access to the register</td>\n'
notesStr += '</tr>\n'
notesStr += '</table>\n'
return notesStr
# ---------------------------------------------------------
# Generates a CSS defining table and paragraph attributes.
# Returns a string with the CSS
# ---------------------------------------------------------
def __genCss(self):
cssStr = ''
cssStr += '<style>\n'
cssStr += 'h1, h2, h3, h4 {\n'
cssStr += ' font-family: ' + self.__textFont + ';\n'
cssStr += '}\n'
cssStr += 'p {\n'
cssStr += ' font-family: ' + self.__textFont + ';\n'
cssStr += ' font-size: ' + self.__textFontSize + ';\n'
cssStr += ' text-justify: auto;\n'
cssStr += '}\n'
cssStr += 'table#main {\n'
cssStr += ' font-family: ' + self.__textFont + ';\n'
cssStr += ' font-size: 11px;\n'
cssStr += ' border-collapse: collapse;\n'
cssStr += ' width: ' + self.__tableWidth + ';\n'
cssStr += ' border: 3px solid ' + self.__gisColour + ';\n'
cssStr += '}\n'
cssStr += 'table#main td {\n'
cssStr += ' border: 1px solid ' + self.__lineColour + ';\n'
cssStr += ' text-align: left;\n'
cssStr += ' padding: 5px;\n'
cssStr += ' font-family: ' + self.__codeFont + ';\n'
cssStr += '}\n'
cssStr += 'table#main th {\n'
cssStr += ' border: 1px solid #dddddd;\n'
cssStr += ' text-align: left;\n'
cssStr += ' background-color: ' + self.__gisColour + ';\n'
cssStr += ' color: #ffffff;\n'
cssStr += ' padding: 5px;\n'
cssStr += '}\n'
cssStr += 'table#key {\n'
cssStr += ' font-family: ' + self.__textFont + ';\n'
cssStr += ' font-size: 8pt;\n'
cssStr += ' border-collapse: collapse;\n'
cssStr += ' width: ' + self.__keyWidth + ';\n'
cssStr += ' border: 0px;\n'
cssStr += '}\n'
cssStr += 'table#key td, th {\n'
cssStr += ' text-align: left;\n'
cssStr += ' padding: 5px;\n'
cssStr += ' vertical-align: top;'
cssStr += '}\n'
cssStr += '</style>\n'
return cssStr
# ---------------------------------------------------------
# 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)
# Construct the write file name (with a .htm suffix) and open it
writeFileName = srcDir + sep + ip + opSuffix + '.htm'
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'
# Output the opening HTML tags, including the CSS data
wfp.write('<!DOCTYPE html>\n')
wfp.write('\n<!-- ********************************************* -->\n')
wfp.write('<!-- * AUTO-GENERATED BY gen_htm.py. DO NOT EDIT * -->\n')
wfp.write('<!-- ********************************************* -->\n\n')
wfp.write('<html lang="en-GB">\n<head>\n')
wfp.write('<title>Datasheet for ' + ip.upper() + ' GIS soft IP component</title>\n')
wfp.write(self.__genCss() + '</head>\n<body>\n')
# Get the path to the logo image
logoFname = os.path.dirname(sys.argv[0]) + sep + 'templates' + sep + 'gis_logo.png'
# Convert the image data to base64 and turn into a string
encoded = str(base64.b64encode(open(logoFname, "rb").read()))
# Insert the image tag, indicating embedded base64 data
wfp.write('\n<img src="data:image/png;base64,\n')
# Insert the image data, with newline every 128 characters. The first two characters
# are deleted (a tag for byte data---"b'") and the last character (')
for idx in range(2, len(encoded)-1) :
wfp.write(encoded[idx])
if (idx-2) % self.__imagePrintWidth == self.__imagePrintWidth-1 :
wfp.write('\n')
# Finish off the image tag
wfp.write('"\nalt="gis_logo.png">\n\n')
wfp.write('<h1>Datasheet for the ' + ip.upper() + ' GIS Soft IP Embedded Logic</h1>\n')
wfp.write('<h2>Register Definitions</h2>\n')
# If offset data was provided, output it here
if offsetStr != '':
wfp.write(offsetStr)
# Insert the table tag
wfp.write('\n<table id="main" style="margin-left:' + self.__tableMargin + '">\n')
# Output a header with the block name and top level description. The description spans
# second column to the end.
self.__drawContents([jsonDict[0][attr.IP_NAME], jsonDict[0][attr.DESCRIPTION]], wfp, True)
# Output the column header
self.__drawContents(['Register Name', addrBannerStr, 'Field', 'Bits', 'Type', 'Reset', 'Description'], wfp, True)
return wfp
# ---------------------------------------------------------
# Draw the contents of a row from the dataList to the file
# in fp. The output is affected by the isHeader flag to
# use <th> instead of <td>, and the rwoSpan argument
# specifies the number of rows to span. The bottom line
# style can be influenced by the booleans thickLine and
# lastEntry, where lastEntry overrides thickLine to force
# false.
# ---------------------------------------------------------
def __drawContents(self, dataList, fp = sys.stdout, isHeader = False, rowSpan = 1, thickLine = False, lastEntry = False) :
dataLen = len(dataList)
if isHeader :
cellStr = 'th'
else :
cellStr = 'td'
fp.write('<tr>\n')
for idx in range(len(dataList)) :
# If a row span entry and index is 0 or 1, add the rowspan tag for the specified number of rows
if idx <= 1 and rowSpan > 1:
rowSpanStr = ' valign="top" rowspan=' + str(rowSpan)
else:
rowSpanStr = ''
# If the last column (i.e. the description) the use the font for normal text
if idx == dataLen - 1 :
fontStr = 'font-family: ' + self.__textFont + ';'
else :
fontStr = ''
# If a thick line requested, or for the first two columns of a rowspan row,
# add a thick line tag, unless the last entry in a table
if not lastEntry and (thickLine or (rowSpan > 1 and idx < 2)) :
borderBottomStr = 'border-bottom: 2px solid ' + self.__lineColour
else:
borderBottomStr = ''
# Construct a style string
styleStr = fontStr + borderBottomStr
if styleStr != '' :
styleStr = ' style="' + styleStr + '"'
# For a header entry, uf the last entry and the number of entries is less than the number of columns
# add a colspan tag to span all the remaining columns
if isHeader and idx == dataLen - 1 and dataLen != self.__numOfCols :
fp.write(' <' + cellStr + ' colspan="' + str(self.__numOfCols - idx) + '" ' + styleStr + fontStr + '>')
else :
fp.write(' <' + cellStr + rowSpanStr + styleStr + '>')
fp.write(dataList[idx])
fp.write('</' + cellStr + '>\n')
fp.write('</tr>\n')
# ---------------------------------------------------------
# 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 += '<p style="text-indent:' + self.__tableMargin + '">Offset in ' + parentIp + ' for bus ' + bus.upper() + ' : 0x' + format(offsetInt, '08x') + '</p>\n'
# Iterate through each bus dictionary
for jsonBusDict in jsonDict :
# Don't process the registers if the 'process_reg' attribute is present
# and not set to 'enabled'
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()
regCount = 0
# Loop through each register
for regName in regKeys :
regCount += 1
lastReg = regCount == len(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]]
rowSpan = 1
hasFields = attr.FIELDS in regDict[regName]
if hasFields :
fields = regDict[regName][attr.FIELDS]
rowSpan = len(fields) + 1
# Draw the row for the register
self.__drawContents(entryList, wfp, False, rowSpan, not hasFields, lastReg)
# If there are fields for this register, process them here
if hasFields :
# Keep a count of the bit position and the number of fields processed
bitCount = 0
fieldCount = 1
# Loop through each field entry
for fieldName in fields :
# 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 not needed as row spanned)
entryList = [fieldName.upper(),
bitStr,
fields[fieldName][attr.TYPE],
resetVal,
fields[fieldName][attr.DESCRIPTION]
]
# Output the row for this field
self.__drawContents(entryList, wfp, False, 1, fieldCount == len(fields), lastReg)
fieldCount += 1
# Update the bit position count
bitCount += int(fields[fieldName][attr.BIT_LEN], 0)
# Finish off the document and close the output file
wfp.write('</table>\n')
# Output the register type key
wfp.write(self.__genTypeKey())
# If there is a notes attribute defined, process it here
if 'notes' in jsonBusDict:
self.__genNotes(wfp, jsonBusDict['notes'])
# Generate a copyright message and a timetsamp
self.__genCopyright(wfp)
# Close off the HTML document
wfp.write('\n</body>\n</html>\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
MemMapperHtm.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', '--width', dest='width', default='850px', action='store', help='Width of HTML table (default 850px)')
return parser.parse_args()
# ###############################################################
# Only run if not imported (to test)
#
if __name__ == '__main__':
# Create an object for generating text document output
memMap = MemMapperHtm()
# Process the command line options
cmdArgs = processCmdLine()
# Do initialisation for text object specific configurations
memMap.setByteAddrMode(cmdArgs.byteAddrs)
memMap.setWidth(cmdArgs.width)
# 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