# ----------------------------------------------------------------------------- # 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 = 8 MemMapperBase.__init__(self) # --------------------------------------------------------- # Configure the byte address output mode # --------------------------------------------------------- def setByteAddrMode(self, mode) : self.__useByteAddrs = mode # --------------------------------------------------------- # Configure the datasheet table width # --------------------------------------------------------- def setWidth(self, width): self.__tableWidth = width # --------------------------------------------------------- # Configure the notes width # --------------------------------------------------------- def setNotesWidth(self, width): self.__notesWidth = width # --------------------------------------------------------- # Process a notes string and format to output # --------------------------------------------------------- def __genNotes(self, wfp, notesStr): # Open up a section for notes, and a
section with its own # width and indent paramters wfp.write('

Usage Notes

\n
\n

\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

\n

\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('this link') wfp.write('\n

\n
\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('

 


\n

Copyright © ' + str( now.year) + ' Global Inkjet Systems. ') # Output a 'generated' message with a time stamp wfp.write('Generated by gen_htm.py —' + str(now.year) + '-' + str(now.month) + '-' + str(now.day) + ' ' + format(now.hour, '02d') + ':' + format(now.minute, '02d') + '

\n') # --------------------------------------------------------- # Output a key table defining the register types # --------------------------------------------------------- def __genTypeKey(self) : notesStr = '\n

Register/field type key:

\n\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '\n' notesStr += '' notesStr += '\n' notesStr += '\n' notesStr += '' notesStr += '\n' notesStr += '\n' notesStr += '' notesStr += '\n' notesStr += '
TypeDescription
cConstant, with value defined by "reset" attribute\n' notesStr += '
rsvSame as constant, except no reset value and always 0. Can be mixed with write types.
wWrite 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.
wpWrite 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.
w0Same 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.
rRead only value. Input ports generated for each field (where applicable), and concatenated on returned read data bus.
rpSimilar 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.
rwpSimilar to wp, but also generates a (separate) pulse on a read access to the register
  
SubypeDescription
unsignedRegister/field is specified as an unsigned value.\n
signedRegister/field is specified as a signed value.\n
<blank>Register/field sign status is not explicitly defined and defaults to unsigned.\n
\n' return notesStr # --------------------------------------------------------- # Generates a CSS defining table and paragraph attributes. # Returns a string with the CSS # --------------------------------------------------------- def __genCss(self): cssStr = '' cssStr += '\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('\n') wfp.write('\n\n') wfp.write('\n') wfp.write('\n\n') wfp.write('\n\n') wfp.write('Datasheet for ' + ip.upper() + ' GIS soft IP component\n') wfp.write(self.__genCss() + '\n\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\n\n') wfp.write('

Datasheet for the ' + ip.upper() + ' GIS Soft IP Embedded Logic

\n') wfp.write('

Register Definitions

\n') # If offset data was provided, output it here if offsetStr != '': wfp.write(offsetStr) # Insert the table tag wfp.write('\n\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', 'subtype', '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 \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('\n') fp.write('\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 += '

Offset in ' + parentIp + ' for bus ' + bus.upper() + ' : 0x' + format(offsetInt, '08x') + '

\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 attr.SUBTYPE in regDict[regName] : regSubType = regDict[regName][attr.SUBTYPE] else : regSubType = ' ' # 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, regSubType, 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] if attr.SUBTYPE in fields[fieldName] : regSubType = fields[fieldName][attr.SUBTYPE] else : regSubType = '' 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], regSubType, 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('
instead of , 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('
\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\n\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)') parser.add_argument('-W', '--notes_width', dest='notesWidth', default='800px', action='store', help='Width of HTML notes (default 800px)') 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) memMap.setNotesWidth(cmdArgs.notesWidth) # 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