From 500cbce69dee527babd6a9472643ebde5b7adb1e Mon Sep 17 00:00:00 2001 From: bryan newbold Date: Wed, 26 Feb 2014 13:16:42 -0500 Subject: commit WIP to date --- .gitignore | 1 + example.csv | 17 +++ output/.stub | 0 pack_array.v | 16 +++ parse.py | 280 ++++++++++++++++++++++++++++++++++++++++++++ syntax.rst | 38 ++++++ templates/minimal.html.tmpl | 41 +++++++ templates/minimal.rst.tmpl | 23 ++++ 8 files changed, 416 insertions(+) create mode 100644 example.csv create mode 100644 output/.stub create mode 100644 pack_array.v create mode 100755 parse.py create mode 100644 syntax.rst create mode 100644 templates/minimal.html.tmpl create mode 100644 templates/minimal.rst.tmpl diff --git a/.gitignore b/.gitignore index f466019..bce1b0d 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,4 @@ .* *.tmp *.old +output/ diff --git a/example.csv b/example.csv new file mode 100644 index 0000000..24445bf --- /dev/null +++ b/example.csv @@ -0,0 +1,17 @@ +word_index,bits,mode,section,slug,default,description +0,32,p,meta,magic,0x0002_1EAF,Core-Specific Magic Number (0x0002_1EAF) +1,32,p,meta,version,0,Core version number +2,32,p,meta,feature_flags,0,Feature flags (or zero) +3,32,p,meta,git_hash,0,"HDL Git commit hash stub, or 0 (32bits)" +4,64,p,meta,build_time,0,UNIX time of build +1024,1,rw,general,enable,, +1025,1,rw,general,output_en,, +1026,1,b,general,ring,,Doorbell +1027,16,rw,general,ring_count,,Count of doorbell rings +1028,16,r,general,ring_counta,,Count of doorbell rings +1029,16,r,general,ring_countb,,Count of doorbell rings +,,m,general,,, +,32,p,general,PARAM,100, +,20,rw,general,,, +,,brw,general,secret,,Value with a doorbell +4096,18,rwm,table,row[256],, diff --git a/output/.stub b/output/.stub new file mode 100644 index 0000000..e69de29 diff --git a/pack_array.v b/pack_array.v new file mode 100644 index 0000000..26e6049 --- /dev/null +++ b/pack_array.v @@ -0,0 +1,16 @@ + +`define PACK_ARRAY(PK_WIDTH,PK_LEN,PK_SRC,PK_DEST) genvar pk_idx; generate for (pk_idx=0; pk_idx<(PK_LEN); pk_idx=pk_idx+1) begin; assign PK_DEST[((PK_WIDTH)*pk_idx+((PK_WIDTH)-1)):((PK_WIDTH)*pk_idx)] = PK_SRC[pk_idx][((PK_WIDTH)-1):0]; end; endgenerate + +`define UNPACK_ARRAY(PK_WIDTH,PK_LEN,PK_DEST,PK_SRC) genvar unpk_idx; generate for (unpk_idx=0; unpk_idx<(PK_LEN); unpk_idx=unpk_idx+1) begin; assign PK_DEST[unpk_idx][((PK_WIDTH)-1):0] = PK_SRC[((PK_WIDTH)*unpk_idx+(PK_WIDTH-1)):((PK_WIDTH)*unpk_idx)]; end; endgenerate + + +module example ( + input [63:0] pack_4_16_in, + output [31:0] pack_16_2_out + ); + +wire [3:0] in [0:15]; +`UNPACK_ARRAY(4,16,in,pack_4_16_in) + +wire [15:0] out [0:1]; +`PACK_ARRAY(16,2,in,pack_16_2_out) diff --git a/parse.py b/parse.py new file mode 100755 index 0000000..c404d97 --- /dev/null +++ b/parse.py @@ -0,0 +1,280 @@ +#!/usr/bin/env python +""" + +TODO: +- values should only parse as section if XYZ??? +- whitespace control + http://jinja.pocoo.org/docs/templates/#whitespace-control +- disable HTML safety for non-html documents? +""" + +from __future__ import print_function + +import sys +import csv +import time +import os + +import jinja2 + +AXI_ADDR_BITS = 16 +WORD_BITS = 32 + +def parse_slug(s): + pre = s.split('[')[0] + post = None + assert(pre == filter(lambda x: x.isalnum() or x is '_', pre)) + assert(len(pre) >= 1 and pre[0] != '_') + if '[' in s: + assert(s.count('[') == 1) + assert(s.count(']') == 1 and s[-1] == ']') + post = int(s.split('[')[1][:-1]) + assert(post >= 0) + return (pre, post) + +def str2val(s, bits): + """ + Strip '_' characters (eg, 0x1111_2222). + Allow 0x and 0b prefixes. + """ + v = None + s = s.lower().replace('_', '') + if s.count("'") is 1: + raise NotImplementedError("Can't handle verilog-style constants yet") + if s.startswith('0b'): + v = int(s[2:], 2) + if s.startswith('0x'): + v = int(s[2:], 16) + else: # fallback + v = int(s) + assert(v >= 0 and v < 2**bits) + return v + +class Value(): + index = None + bits = None + section = None + section_index = None + slug = None + slug_index = None + default = None + description = None + mode = None + addr = None + + def offset(self, offset): + self.addr = offset + (4 * self.index) + + def addr_pp(self): + return "0x%08X" % self.addr + + def __init__(self, word_index=None, bits=None, section=None, slug=None, + default=None, description=None, mode=None): + # TODO: input validation/transforms + self.index = int(word_index) + assert(self.index >= 0) + assert(self.index <= (2**AXI_ADDR_BITS - 1)) + + if bits in [None, '']: + raise ValueError("Bits not defined") + self.bits = str2val(bits, 9) + assert(self.bits >= 1) + assert(self.bits <= 128) + + if section is None: + (self.section, self.section_index) = ('top_level', None) + else: + (self.section, self.section_index) = parse_slug(section) + + if slug is None: + (self.slug, self.slug_index) = (None, None) + else: + (self.slug, self.slug_index) = parse_slug(slug) + + if default not in [None, '']: + self.default = str2val(default, self.bits) + else: + self.default = 0 + self.description = description + self.mode = mode + + def __str__(self): + return "" % str(self.__dict__) + +class Register(Value): + read = False + write = False + +class Parameter(Value): + pass + +def check_overlaps(l): + rangelist = [] + for val in l: + # TODO: also handle larger ranges + this = (val.index, val.index + ((val.bits-1)/WORD_BITS)) + inserted = False + for i in range(len(rangelist)): + that = rangelist[i] + if ((that[0] <= this[0] <= that[1]) + or (that[0] <= this[1] <= that[1])): + raise ValueError("Overlapping memory ranges: %s and %s" % + (this, that)) + if this[0] < that[0]: + rangelist.insert(i, this) + inserted = True + break + if not inserted: + rangelist.append(this) + +def check_names(l): + names = [] + n = None + for val in l: + if val.section: + n = "%s.%s" % (val.section, val.slug) + else: + n = val.slug + if n in names: + raise ValueError("Dupliate name: %s" % n) + names.append(n) + +def error(s="unspecified"): + sys.stderr.write(str(s) + '\n') + sys.exit(-1) + +class Repeated(): + section = None + + def __init__(self, word_index, slug): + self.index = int(word_index) + assert(self.index >= 0) + assert(self.index <= (2**AXI_ADDR_BITS - 1)) + + if self.section is '': + self.section = '' + self.section_index = None + else: + (self.section, self.section_index) = parse_slug(section) + + +req = ('word_index', 'bits', 'mode', 'section', 'slug', 'default', + 'description') + +print("------- START READ") +f = open('example.csv', 'r') +reader = csv.DictReader(f) + +registers = [] +parameters = [] +mode = None + +for line in reader: + if reader.line_num is 0: + # validate fields just once + for field in req: + if not field in reader.fields: + error("Missing column: %s" % field) + + # skip lines w/o + if line['word_index'] in [None, '']: + print("Skipping line %d (no index)" % reader.line_num) + continue + + mode = line['mode'] + try: + if mode.lower() == 'p': + p = Parameter(**line) + parameters.append(p) + elif mode.lower() == 'r': + r = Register(**line) + r.read = True + registers.append(r) + else: + #error("Unknown mode: %s" % mode) + print("Skipping line %d (unknown mode %s)" % (reader.line_num, + mode)) + pass + except (AttributeError, TypeError, ValueError), e: + error("Syntax error parsing line %d: %s" % (reader.line_num, e)) + sys.stdout.write(".") +print('') +f.close() + +print("Registers:\t%d" % len(registers)) +print("Parameters:\t%d" % len(parameters)) + +offset = 0x0 +for r in registers: + r.offset(offset) +for p in parameters: + p.offset(offset) + +check_overlaps(registers + parameters) +check_names(registers + parameters) +sections = {} +for val in (registers + parameters): + if not val.section in sections.keys(): + sections[val.section] = [] + sections[val.section].append(val) + +for key, sec in sections.iteritems(): + sections[key] = sorted(sec, key=lambda x: x.index) + +print("------- END READ") + +# TODO: process into sections; sort; apply offsets + +context = dict(registers=registers, + parameters=parameters, + name="example", + now=time.strftime("%Y-%m-%d %H:%M:%S UTC", time.gmtime()), + attribution="Generated by AXI-Lite Generator", + whoami=os.getenv('USER'), + sections=sections) + +# TODO: +# jinja2.ChoiceLoader +# jinja2.PackageLoader +env = jinja2.Environment(loader=jinja2.FileSystemLoader('templates')) +#print("------- START PYTHON") +""" +params: single helper to dump them all +registers: + helper get/set by string (eg, get("meta.magic")) + module cmd to dump them all + module+slug cmd to get/set +
. getter/setter functions +""" +#print("------- END PYTHON") + +#print("------- START HDL") +""" +wrapper stub also. +params: passed all around +registers: just one place +""" +#print("------- END HDL") + +#print("------- START C_HEADER") +""" +just structs for parameters/registers +""" +#print("------- END C_HEADER") + +print("------- START HTML") +t = env.get_template('minimal.html.tmpl') +out_f = open('output/example.html', 'w') +out_f.write(t.render(**context)) +out_f.close() +print("------- END HTML") + +print("------- START RST") +t = env.get_template('minimal.rst.tmpl') +out_f = open('output/example.rst', 'w') +out_f.write(t.render(**context)) +out_f.close() +print("------- END RST") + +print("------- DONE!") + diff --git a/syntax.rst b/syntax.rst new file mode 100644 index 0000000..27ab499 --- /dev/null +++ b/syntax.rst @@ -0,0 +1,38 @@ + +Repetition +----------------------- +Repeated sections use array ([n]) syntax for the section name. The [0] section +should be complete, all the other repetitions should only have the word_index +set. + +UNIMPLEMENTED: repeated sections could be packed/unpacked automatically (see +pack_array for macros) + +HDL: Variables and Storage +------------------------------------- +Read-only nets are implemented + +Mode Flags +---------------------- + +**r: Read** + +**w: Write** + +**p: Parameter** + A special read-only mode for compile-time constants. The slug name is + capitalized for HDL but lower case in other contexts. + +**b: Doorbell** + UNIMPLEMENTED. + A new net with "_trig" suffix is created which is triggered on every write + transaction. + +**m: Memory Block** + UNIMPLEMENTED. + Uses an address mask to read/write, eg, a BRAM or regfile instead of + exposing many individual registers. + +**f: FIFO** + UNIMPLEMENTED. + Sets up a read or write FIFO. diff --git a/templates/minimal.html.tmpl b/templates/minimal.html.tmpl new file mode 100644 index 0000000..98042ee --- /dev/null +++ b/templates/minimal.html.tmpl @@ -0,0 +1,41 @@ + +{{ name }} Memory Map Documentation + + + + +

+{{ name }} Memory Map Documentation

 + +{% for section in sections.keys() %} +{{section}} - +{% endfor %} +Last updated [{{ now }}] by {{ whoami }} +
+

+ +{% for sec_name, sec_values in sections.iteritems() %} +

{{ sec_name }}

+ +
Memory Address + Bits + Mode + Shortname + What +{% for val in sec_values %} +
{{ val.addr_pp() }} + {{ val.bits }} + {{ val.mode }} + {{ val.slug }} + {{ val.description }} +{% endfor %} +
{% endfor %} + + diff --git a/templates/minimal.rst.tmpl b/templates/minimal.rst.tmpl new file mode 100644 index 0000000..0ad74df --- /dev/null +++ b/templates/minimal.rst.tmpl @@ -0,0 +1,23 @@ +========================================================================= +{{name}} Memory Map +========================================================================= + +{% for sec_name, sec_values in sections.iteritems() %} +{{sec_name}} +--------------------------------------------------------- + +.. list-table:: + :widths: 10 5 5 15 55 + :header-rows: 1 + + * - Address + - Bits + - Mode + - Shortname + - What {% for val in sec_values %} + * - ``{{ val.addr_pp() }}`` + - {{ val.bits }} + - ``{{ val.mode }}`` + - {{ val.slug }} + - {{ val.description }} {% endfor %} +{% endfor %} -- cgit v1.2.3