icd.txt

AutoFPGA does all of its work based upon KEY/VALUE pairs.  Key/value pairs
are organized into a hierarchical, but unordered, structure which is then
referenced by the logic that follows.  The values themselves are either strings
or numbers.

Lines defining keys may begin as:
@KEY=	Defining a given key
@$KEY=	Defines a numeric key value that may need to be evaluated
@KEY+=	Concatenates the following onto the pre-existing string key.  If the
	key does not (yet) exist, it is created and initialized to this value.
@/KEY=	References a global key
@/KEY+=	Concatenates onto a global key


Lines not defining keys are either comment lines (lines beginning with either
## or # and a space), or lines appended to the value of the last key.

AutoFPGA document lines starting with @ specify a key name.  Lines starting with
a @$ specify an integer valued expression.  The key is given by the string
between the @ (or @$) and the ='s (minus any white space at the end, white
space at the beginning is not allowed).  KEYs are case sensitive.  By
convention, KEYs are in all caps, although keys with lower case letters are
allowed and used as names of particular file components.  For the discussion 
below, any keys will be identified by prefixing the key name with an @ sign.

Comments.  Lines beginning with either two hash marks, ##, or a single hash
followed by a space, as in "# ", are comment lines.  Other lines beginning
with "#", such as #define, are not comments, neither do lines containing "#"
in any location other than the first location contain comments.

KEYs are by convention all capitals.  They are also hierarchical.  Hence,
a key BDEFS.IONAME references the BDEFS set of key-value pairs, with the keyname
IONAME within that set.

Every device or bus master *must* contain a @PREFIX key.  This key will be used
as a unique string to identify the device.  As parsing takes place, all of the
keys for a given device will be placed into a key-value set prefixed by the
@PREFIX key.  Hence, for a device with name @PREFIX=uart, a definition such as
@NADDR=4 creates a key named @uart.NADDR and gives it the value 4. 

Keys defined prior to the first @PREFIX key are global keys, and are not given
any @PREFIX in front of them prior to being inserted into the master key-value
mapping.

Key definitions beginning with @$ are integer expressions that will be evaluated
before use.

Further, strings may reference other parts of the key-value mapping by placing
a @$ in front of a key name.  This value will then be replaced by the value
once that value is known.  Expressions may also be used when assigning to
things such as @$KEY, as in ...
@$KEY.EXPR=(1<<20)
@KEY.FORMAT=0x%08x
@KEY.VAL will be created with the calculated value
@KEY.STR will be created with the value formated as desired into a string
Once this expression has a value, a new key will be created, KEY.VAL, having
the integer value of this expression.  This value may be referenced via the
base @KEY.  Further, this value will be substituted wherever @$KEY exists
within any other VALUE's.  Which value it gets, either the number or the
string, is dependent upon the context and how it is referenced.

Peripheral devices *must* also contain a @SLAVE.TYPE key.  This key can have
one of the following values:
	SINGLE	A peripheral with no internal address decoding, but
		whose output value (@PREFIX_data) is valid on any given clock.
		These peripherals are not allowed to stall the bus.
		These peripherals will be collected together.
	DOUBLE	A peripheral with internal address decoding, but no delays.
		Hence, the data value for this peripheral will always be valid
		one clock after the select line goes high.
		These peripherals are not allowed to stall the bus.
		These peripherals will also be collected together.
	MEMORY	A peripheral including information that needs to be placed into
		a linker script.  Examples of MEMORY can be block RAM's,
		SDRAM, or even FLASH.  MEMORY that fits the criteria for DOUBLE
		is also best given the MEMORY attribute instead.
	BUS	This slave is a bus translator.  It acts as a slave on its
		given bus, but has a bus (MASTER) interface beneath it
	OTHER	Any peripheral that doesn't match the above.


Other tags include
ACCESS	This is a STRING that will be turned into a DEFINE and a couple IFDEFs
	in the main.v file.  The idea is, if this string is defined, then the
	components logic will be included, otherwise not.

DEPENDS	If the logic of one component is dependent upon another, set the
	DEPENDS tag to be a list of ACCESS parameters upon which this component
	depends upon.  The ACCESS item for this parameter will then be
	turned off if it's dependencies are not met.

	Dependencies beginning with a "!" are negative dependencies.  Hence, the
	ACCESS tag will only be true if the dependency ifdef is *not* defined.
	(No spaces are allowed between the ! and the dependency ID)

NADDR	The number of uniquely addressable registers/ports this device has
/*
	Future: BUSTYPE, for now the default will be WB-B4/pipeline.
	Future values may include WB/classic, or perhaps even AXI and AXI-lite.
*/
ERROR.WIRE	The name of a wire set by the module, which (if set) will cause
	a bus error.  Components should only set this if they are being
	accessed.

TOP.PORTLIST
	This string gets added into the toplevel( portlist ) declaration,
	allowing each peripheral to control external wires.  If not specified,
	this is given by MAIN.PORTLIST.

TOP.IODECL
	This string includes the declarations for the portlist above, such as
	output wire o_value.  If not specified, this is given by MAIN.IODECL.

TOP.DEFNS
	Defines variables in toplevel.v
TOP.MAIN
	This string gets added into the main module instantiation, between
	the ( parentheses ).
TOP.INSERT
	Some peripherals need some cleanup.  Hence, after instantiating main,
	these need to do some logic.  Any variables needed here need to have
	been declared in TOP.DEFNS.

MAIN.PARAM
MAIN.PORTLIST
	Same as TOP.PORTLIST, only as applied to the main.v file
MAIN.IODECL
	Same as TOP.IODECL, only as applied to the main.v file
MAIN.DEFNS
MAIN.INSERT
MAIN.ALT

BASE	(Created and used internally)
	This is the base address of the given peripheral within its current
	bus
REGBASE (Created and used internally)
	This is the base address of the given peripheral from an external
	bus address reference.
MASK	(Created and used internally)
AWID	Address width, in terms of # of address lines, used by this component

REGDEFS.H.INCLUDE	Placed at the top of the regdefs.h file
REGS.NOTE	A comment to be placed at the beginning of the register list
		for this peripheral
REGS.N		The number of registers this peripheral has.  AutoFPGA will then
		look for keys of the form REGS.0 through REGS.(REGS.N-1).
REGS.0...?	Describes a register by name.  The first value is the offset
		within the address space of this device.  The second token
		is a string defining a C #def'd constant.  The third and
		subsequent tokens represent human readable names that may be
		associated with this register.
REGDEFS.H.DEFNS	Placed with other definitions within regdefs.h
REGDEFS.H.INSERT Placed in regdefs.h following all of the definitions
I may change this to the following notation, though:
REGSDEFS.NOTE
REGS.<name>.ADDR	# Offset within the peripheral
REGS.<name>.UNAME(s)	# User-readable name
REGS.<name>.DESC(ription for LaTeX)


BDEF.INCLUDE	Gets placed at the top of the board definitions file, and
		is used to insert references for any particular include files
		into the board file.  Include files are not ordered by
		dependency, so they should either be independent of each other,
		or they should reference any other component they use.

BDEF.DEFN	A list of lines defining anything that needs to be defined
		inside the board component description.  This might include,
		for example, a type for the component or particular defines
		that define things associated with the component
BDEF.IONAME	The name given to this component in the board.h file
BDEF.IOTYPE	The name of a type, describing the structure of the memory
		begin pointed to.
BDEF.OSDEF	Contains the name of a value that will be #define'd if this
		component is included in the design, and not otherwise
BDEF.OSVAL	A definition line, to be placed into the board definitions file,
		that is then used to define a pointer to this type of object
// Likely to default, in the future, to static volatile @BDEF.IOTYPE *const @BDEF.IONAME = &((@BDEF.IOTYPE *)@BASE);
(deprecated) IONAME
(deprecated) CSTRUCT (now BDEF.DEFN)

XDC.FILE	If present, autofpga will open this file and look through it
		for commented lines defining pins that exist in our top
		level port list.  Lines beginning with a #, but not ##, will
		be uncommented and added the build.xdc file.  If no XDC.FILE
		key is given, then the build.xdc file will not be created.
XDC.INSERT	This line, if present, gets inserted verbatim at the bottom of
		the generated XDC file
UCF.FILE	Does the same thing with a UCF file as was done with the
		XDC.FILE, creating a build.ucf file when done.
UCF.INSERT	Adds lines to the UCF file, just as with the XDC.INSERT tag
		does for the XDC file.

PCF.FILE	Does the same thing with a UCF file as was done with the
		XDC.FILE, creating a build.pcf file when done.
PCF.INSERT	Adds lines to the PCF file, just as with the XDC.INSERT tag
		does for the XDC file.

LD.FILE		Name of the linker script to generate.  The linker script
		will reflect memory components found beneath the component
		containing this file.
LD.SCRIPT	Contains a customized script
LD.ENTRY	The name of the entry symbol in the linker script.
LD.DEFNS	(Any definitions to be added to the linker script)

		If the peripheral has an LD.FILE attribute,  the LD.DEFNS
		will not be included in any other linker scripts
LD.PERM		The permissions a memory region has before the linker.
		This is either r, rx, or wx.  See the documentation for
		binutils/ld for more details of this field
LD.NAME		The name of this peripheral, as it appears in the linker script

PIC.BUS		The name of a parameter to hold all of the interrupt wires
PIC.MAX		The maximum number of interrutps this one can have

INT.NAME.WIRE	Specifies that an interrupt with C #define name NAME is
		connected to the internal wire with its name given by this key
INT.NAME.PIC	Identifies which PIC this wire is connected to.  Any particular
		interrupt may be assigned to multipl PICs.  If so, these
		are listed on this line and separated by white space
INT.NAME.ID	Identifies which interrupt wire this device it connected to

OUT.FILE	Creates an output file by this name
OUT.DATA	Places this information within the data file

RTL.MAKE.GROUP	A make variable name which will contain the file list for this
		component
RTL.MAKE.FILES	The files composing this component
RTL.MAKE.SUBD	The location of the Verilog files for this component

SIM.INCLUDE	Place any #includes here.  #includes will be included before
		anything else
SIM.DEFINES	#define's follow any #includes.  You can place those here.
SIM.DEFNS	Any variables necessary in the Verilog simulation class can
		be defined within this tag.
SIM.INIT	If variables need to be initialized when the verilog simulation
		object is initialized, place that initialization code within
		this tag
SIM.SETRESET	If your component has specific simulation actions that need
		to take place when the reset pin is set high, place that code
		in this block.
SIM.CLRRESET	CLRRESET code goes in the same block as the reset method, but
		gets called after the reset tick.
SIM.TICK	If you want your simulation software to be called as part of
		a simulation tick, place that code within this tag
SIM.DBGCONDITION	If you might need to debug your component, you can
		put a debug condition here.  The condition code should set
		the bool "writeout" to true, or leave it as it is.
SIM.DEBUG	If you are doing debug by printf, place any of your printf
		debug lines in this tag
SIM.LOAD	If your component is a memory that might need to be loaded
		when your program is loaded into the simulation, you'll need
		to define this component.  Your code will be passed a
		"start" offset into your address region, a buffer pointer, buf,
		an "offset" into that buffer, and a length (wlen) to copy
		from the buffer into your memory area.

SIM.METHODS	If your code requires the definition of methods to be used
		within the Verilator simulator class, place those definitions
		here.
SIM.CLOCK	Specifies the clock that is used for the SIM.TICK method.  Only
		one clock is allowed.  If you need another, make another
		component using the other clock.

CLOCK.NAME	A list of the clocks used by this component
CLOCK.WIRE	A list of the clock names used by this component.  These
		names should already be defined in either the main I/O ports
		list, or the main definitions.  If no wire is given for a clock,
		the clock's name with a i_ prepended to the beginning is
		used instead.  For this reason, the CLOCK.WIRE field may not
		be necessary for your application.
CLOCK.FREQUENCY	A list of frequencies in Hz corresponding to each of the clocks
		listed in the CLOCK.NAME tag
CLOCK.CLASS	A list containing the names of clock support classes used for
		these clocks.  If no class is given, TBCLOCK is assumed as a
		default.  The clock class must have a time_to_edge() function,
		an advance(int ps) function, and rising_edge() and
		falling_edge() indicators.  Likewise, an init(ps) function
		will be called to define the period of the clock.

SLAVE.TYPE	Indicates the type of peripheral
SLAVE.BUS	Indicates the name of the bus used by this slave
MASTER.BUS	Indicates that this component acts as a bus master, and
		identifies (names) the bus it is a master of
MASTER.TYPE	One of CPU, HOST, BUS, SUBBUS, ARBITER, or XCLOCK.
	CPU	will cause board.ld to be created.  Depends upon RESET_ADDRESS
		being defined.
	HOST	Controls the bus from an external interface.
	BUS, SUBBUS,
	ARBITER,
	XCLOCK	These define a series of bridges, whereby the master of one
		bus can control another bus.  All of these therefore need to
		have both a master and a slave bus.  Requests come in on the
		slave bus, go out on the master, get returns to the master,
		get sent back out on as returns on the slave bus.

		Many bus masters of type ARBITER can master the same bus.
		In this way, slaves of one bus can also be ARBITER masters
		of another.  Further, some busses may have multiple masters,
		if all of those masters are of type ARBITER.

BUS.NAME	wb - master wishbone bus, dbg the debug port (wbu),
		zip - the ZipCPU bus master
		sdram - the MIG generated bus master
BUS.PREFIX	$(BUS.NAME)_
BUS.TYPE	One of WB, (b4 assumed), WB/B4, WB/B3, WB/C(lassic), or AXI

BUS.WIDTH	32 (common), could also be 8, 16, 64, 128, 256, etc.

BUS.AWID	Width of the address bus, also known as the number of
		address lines used to address items on this bus.  The bus
		can address (2^BUS.AWID)*(BUS.WIDTH/8) bytes of memory.

BUS.NULLSZ	The number of addresses consumed by the null pointer address

BUS.CLOCK	The name of a previously defined clock from which this bus
		runs on
DEFAULT.BUS	The name of the default bus, which we spend most of our time on.
		This bus gets the null device, for example

REGISTER.BUS	The name of the bus global register addresses are calculated
		from


CACHABLE.FILE	Creates a Verilog module of this name containing a
		combinatorial check of whether a given address beneath it is
		a cachable address (i.e., is it a memory or other type of
		peripheral).  Walks the address tree below the containing
		master peripheral to find memories that may be some number
		of arbiters removed from the current file.

.... GOALS ...
Build S/W to collect all busses together
Allow someone to inherit from the arbiters in such a manner that they can
connect busses together simply
Redo the address assignments, so as to be on a bus-by-bus basis
Set the peripherals up in such a way that, if you have to walk from one bus to
  the next, you can still figure out what the adderss of the peripheral is--even
  if it is a couple busses deep