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
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.
INCLUDEFILE
	Defines a file with default key values within it.  If those key values
	are then not defined in the main file, the include file will be checked
	for default values.  The include path searched can be controlled via
	the '-I' command line option.
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.INCLUDE
	Specicies logic to be placed before module main in main.v
MAIN.PARAM
	Logic placed after the PORTLIST in main.v, used to define parameters
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
	Logic defined after PARAM, PORTLIST, and IODECL.  Used to define
	global registers or wires used by this component
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 (not BDEF.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.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.INCLUDE	Place any #includes here.  #includes will be included before
		anything else
SIM.INIT	If variables need to be initialized when the verilog simulation
		object is initialized, place that initialization code within
		this tag
SIM.CLRRESET	CLRRESET code goes in the same block as the reset method, but
		gets called after the reset tick.
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.
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.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.TICK	If you want your simulation software to be called as part of
		a simulation tick, place that code within this tag

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.
CLOCK.RESET	Optionally contains the name of a reset wire, synchronous to
		the given clock.

SLAVE.TYPE	Indicates the type of peripheral
SLAVE.BUS	Indicates the name of the bus used by this slave
SLAVE.BUS.NAME	An alternate form of entering a SLAVE.BUS.  This version
		allows you to specify other parameters of the SLAVE.BUS at the
		same time.
SLAVE.ORDER	Slaves are naturally ordered from fewest addresses to largest.
		You can use the SLAVE.ORDER to impose a particular order on
		bus slaves going through address assignment.

		This is not the same as creating constant addressing.  Constant
		addresses are not (yet) supported by AutoFPGA.

SLAVE.PREFIX	AutoFPGA will assign a bus prefix to every slave.  Typically
		this will be the slave's name followed by the name of the bus
		(or vice versa).  You can use the SLAVE.PREFIX key to override
		this, or otherwise to know what the value has been set to.
		Bus connections will be made to wires having names of the form,
		@$(SLAVE.PREFIX)_buswire.

(SLAVE.OPTIONS)	(When implemented) will indicate if a slave can be accessed as
		either read-only (RO) or write-only (WO).

SLAVE.PORTLIST	A helper string that you can use (or not) as you prefer.  This
		string is created by the bus logic generator, and contains
		all of the wires you will need to connect to the bus.

SLAVE.ANSIPORTLIST	Same as SLAVE.PORTLIST, but assumes ANSI naming.

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.
	DMA	Has a control SLAVE port, and an unrelated MASTER port--one
		that cannot be accessed through the slave
	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.

	SCRIPT	Doesn't connect to the bus at all, but identifies to the linker
		script generator the bus-master perspective to write the linker
		script from.

MASTER.OPTIONS	A list of options used to describe this master.  Possible
		options include: RO (read only) and WO (write only) currently.

MASTER.PORTLIST	Analogous to SLAVE.PORTLIST, expands into a string describing
		all of the bus connections to be made to a given slave.

MASTER.ANSIPORTLIST	This is the same as MASTER.PORTLIST, save using ANSI
		declarations for the bus port.  Again, this is an optional
		string, generated by the bus compositor, that you may use
		(or not) at your desire.

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

BUS.RESET	The name of a reset wire associated with this bus.

BUS.(OPTIONS)
  BUS.OPT_LOWPOWER	When set, any unused bus wires will be set to zero.
		Since bus wires can potentially have high fan out, this wire
		helps to keep all those wires from toggling if they don't need
		to.  If this isn't set, the crossbar's will be tuned for lowest
		logic, which isn't necessarily lowest power..
  BUS.OPT_LINGER	Used by the AXI-lite master to indicate the number of
		idle clock cycles to wait before releasing the bus.  This will
		potentially speed up a given masters access to the same slave
		over and over again, while slowing down accesses to other
		slaves.
  BUS.OPT_LGMAXBURST	The number of bits necessary to count the maximum number
		of outstanding transactions at any given instant in time.

  BUS.OPT_TIMEOUT	Used by the WB crossbar to indicate a maximum amount
		of time to wait for a given slave.  Set this to zero to ignore
		the timeout, otherwise it defaults to the value in wbxbar.v.

  BUS.OPT_STARVATION_TIMEOUT	(Currently ignored, eventually to be used by
		the Wishbone crossbar to indicate that the OPT_TIMEOUT is to
		be applied to starvation, where the slave is valid and active
		but responding to a different master, as well as slave timeouts)
  BUS.OPT_DBLBUFFER	Used by the wishbone crossbar, wbxbar

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

REGISTER.BUS.NAME	An alternative form of REGISTER.BUS

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