Missing Documentation Information Re: Adding Bare FPGAs as Options Under [Select] -> [Board]

[albatroxx]

It seems I can't select a bare FPGA chip as a target, only a dev board. In theory it seems like it would be super easy to add support for the bare chips because all of the variants of at least the LP/HX line have been supported for a while. I have found the wiki description for how to add new boards, which is somewhat lacking in terms of describing the file contents/rationale/etc.

I would like to address two related issues.

1. The documentation for adding custom boards does not specify any details about the file formats/options/etc used.
2. Bare chips are not currently permitted as design targets.

If I can get some questions answered about the documentation (first issue) and adding the bare chips is as easy as it seems to be in theory (second issue), then I am happy to put in the work to both improve the documentation and start adding files for the bare chips. And, if all goes well, people will be less intimidated about adding support for their own boards.

Documentation Questions

The following example was put together for the iCE40LP1K with the 49-pin ucBGA package. The info.json, pinout.json, pinout.pcf , and rules.json appear to be in this folder. Please correct me if I am looking in the wrong place.

info.json

{
	"label":"Bare Chip - iCE40LP1K-CM49",
	"datasheet":"https://www.latticesemi.com/view_document?document_id=49312",
	"interface":"FTDI",
	"FPGAResources":{
		"ffs":1280,
		"luts":1280,
		"pios":37,
		"plbs":160,
		"brams":16
	}
}

[ Q1 ] I presume "plbs" refers to programmable logic blocks, but as this figure does not appear on the datasheet, is this always (at least for Lattice parts) just the number of LUTs divided by 8?
[ Q2 ] When calculating the "pios" field in the info.json file, should the null outputs be included in the count? Or does this refer only to the pins labelled as I, O, or I/O on the datasheet (ie. not power pins, not NULL pins).

pinout.json

This file was basically just copied straight from the pinout excel sheets provided by Lattice.

[
	{"type":"inout","name":"IOL_2A","value":"C2"},
	{"type":"inout","name":"IOL_2B","value":"B2"},
	{"type":"inout","name":"IOL_4A","value":"A1"},
	{"type":"inout","name":"IOL_4B","value":"B1"},
	{"type":"inout","name":"IOL_6A","value":"D3"},
	{"type":"input","name":"IOL_6B_GBIN7","value":"D2"},
	{"type":"input","name":"IOL_7A_GBIN6","value":"E2"},
	{"type":"inout","name":"IOL_7B","value":"F2"},
	{"type":"inout","name":"IOL_9A","value":"D1"},
	{"type":"inout","name":"IOL_9B","value":"C1"},
	{"type":"input","name":"IOB_35_GBIN5","value":"G3"},
	{"type":"inout","name":"IOB_34","value":"F3"},
	{"type":"inout","name":"IOB_42_CBSEL0","value":"F4"},
	{"type":"inout","name":"IOB_43_CBSEL1","value":"G4"},
	{"type":"inout","name":"CDONE","value":"D5"},
	{"type":"input","name":"CRESET_B","value":"G5"},
	{"type":"inout","name":"IOB_44_SDO","value":"F5"},
	{"type":"inout","name":"IOB_45_SDI","value":"G6"},
	{"type":"inout","name":"IOB_46_SCK","value":"F6"},
	{"type":"inout","name":"IOB_47_SS","value":"E6"},
	{"type":"inout","name":"IOR_54","value":"E7"},
	{"type":"inout","name":"IOR_55","value":"F7"},
	{"type":"input","name":"IOR_60_GBIN3","value":"D6"},
	{"type":"input","name":"IOR_61_GBIN2","value":"D7"},
	{"type":"inout","name":"IOR_63","value":"C7"},
	{"type":"inout","name":"IOR_64","value":"C6"},
	{"type":"inout","name":"IOR_65","value":"C5"},
	{"type":"inout","name":"IOT_78","value":"A6"},
	{"type":"inout","name":"IOT_79","value":"A5"},
	{"type":"inout","name":"IOT_80","value":"A7"},
	{"type":"inout","name":"IOT_81","value":"A3"},
	{"type":"inout","name":"IOT_82","value":"A4"},
	{"type":"input","name":"IOT_84_GBIN1","value":"C4"},
	{"type":"input","name":"IOT_85_GBIN0","value":"B4"},
	{"type":"inout","name":"IOT_89","value":"D4"},
	{"type":"inout","name":"IOT_90","value":"B3"},
	{"type":"inout","name":"IOT_91","value":"A2"},
	{"type": "output", "name": "NULL", "value": "NULL"},
	{"type": "input", "name": "NULL", "value": "NULL"}
]

[ Q3 ] Is this indeed how these files are generated?

rules.json

{
	"input":[
		{"port":"clk","pin":"G3"}
	]
}

I believe what I have written here specifies the input clock coming in on pin G3, and nothing else.
[ Q4 ] Is there anything else that needs to be specified, such as clock speed, programming connections, something to do with interfaces, etc? Or will synthesizing, placing and routing, and timing analyses all work fine leaving it as is?

boards.json

To add support for the board to apio, my understand is that this file requires the following new entry

"Bare Chip - iCE40LP1K-CM49": {
	"name": "Bare Chip - iCE40LP1K-CM49",
	"fpga": "iCE40-LP1K-CM49",
	"programmer": {
		<???>
	}
  },

I am assuming here (please correct me if I am wrong) that a bare chip won't have a USB or FTDI capability, so those should be omitted, but every device lists a programmer so that appears to be required.
[ Q5 ] How do I know what to put in the programmer entry? The various entries in boards.json list 14 different programmers (iceprog, icesprog, iCEburn, iceprogduino, icoprog, litterbox, blackiceprog, icefunprog, tinyfpgab, tinyprog, dfu, fujprog, openfpgaloader_ft2232, and openfpgaloader_usb-blaster, if it matters), but as I am very new to FPGAs I don't really know the difference between the programmers, if it matters, what implications the choice of programmer has, or if anything else needs to be added (like USB or FTDI) based on the choice of programmers.
[ Q6 ] If I am going to make a whole bunch of entries for bare chips so that people can build for chips rather than just dev boards, should I just specify "iceprog" since that appears to be Lattice's programmer and therefore the programmer than off-brand copies are likely to emulate? Or is there a specific dev board I should just copy the entire programmer-usb-ftdi block from?

pinout.pcf

[ Q7] Where can I find any information about this file format? My searches keep turning up unrelated content.

Other Questions

[ Q8 ] The wiki indicates that there is a menu.json file in the same directory as boards.json that needs to be updated, but no such file appears to exist. Am I looking in the wrong spot? Is that no longer the case and it is now automatically assigned?
[ Q9 ] As far as testing goes, I don't have any of these chips and can't physically test them, I imagine that once I have added support for the chips I should be able to successfully compile icestorm, select the chip, synthesize something, and route it, but is there anything else I should test?

[jojo535275]

hello Richard,

If i understood well, about the Fpgaresources in the info.json files, they are not actually been used by icestudio (eg: for the colorligth boards they are not exact and it does cause any problem).
Of course it is always better yo have thinks right ;-)

Q1: ?
Q2: yes ,i think it refer more or less only to the pins labelled as I, O, or I/O on the datasheet ! i think it is the pins thaht we can in icestudio to make our designs (maybe not counting clk)

Q3: the pinout.json file is use to make visible the fpga pins in icestudio ports dropbox:
So in this json file,

• the pins with "type" input will appear in the input port drop-box (when you create an input port in icestudio interface).
• the pins with "type" output will appear in the output port drop-box.
• the pins with "type" inout will appear in the input and in the output port drop-boxes.
  and for every fpga pins, the names that will appear in these drop-boxes is the one set in pinout.json under the "name" fields. So this is the place for "renaming" the fpga pins

Remark: for now, we should not rename a pin with a name include in another pin! Because one of the two pins will

eg: the two following lines will be problematic.
{"type":"inout","name":"IOL_1","value":"C2"},
{"type":"inout","name":"IOL_16","value":"B2"},

as you see the string "IOL_1" is also included in the string "IOL_16"

@ Carlos/Charliva: i just saw that same problem on the workshop badge board created yesterday!
Lcd_rs is not visible because of this two lines in the pinout.json

{"name":"lcd_rst_n","value":"36","type":"output"},
{"name":"lcd_rs","value":"11","type":"output"},

You can change the "lcd_rs" to "lcd_rs_"

Q9: No, the wiki indicates, correctly, thaht menu.json is in folder resources/boards/menu.json

Some food and, will continue to reply to Q4..Q8 later ;-) ....

[cavearr]

hi! ireply you in the afternoon with calm. But important thing is that pinout.json could be generated from pcf with the python script utility located in the same directory that boards definition.

You should complete the pcf file and then execute:

python generator.py name_of_the_board

name_of_the_board is the folder with the board definition. This scripts generate pinout.json

In rules.json, for the moment, the only important thing is indicate as input the clk line and named it clk, if you put other name icestudio dont recognize it for this important function.

about the IOL_1 and _16 is the same as the rs and rst and this is a bug! thanks i'll fix this afternoon and try to documented better this process.

@jojo535275 try to help to @albatroxx and in this way we could take advantage of this issue to documented very well this process.

Thanks a lot!

[jojo535275]

Thank Carlos for the .pcf precisions, it is true that for the colorligth board, Benitos and myself went directly to a manual edition of the pinout.json file (without creating any pcf files!)!

Let us continue with Richard questions,

Q4: about rules.json, Cavear replied on his above post

The think is that icestudio is made for drawing a design, build-it (synthesys+routing) and also loading it in our fpga! And for that last action, as you mentioned a programmer is needed (they are never included in any fpga chip).
remark: on most of the colorligth fpga boards there is no programmer included! and we have to use an external programmer! That is why you can see 3 different entries on the board list (for the exact same colorligth board):
"ColorLight-i5-v7.0_(FT2232H)",
"ColorLight-i5-v7.0_(FT232H)",
"ColorLight-i5-v7.0_(USB-Blaster)",

Q5: in theory, if you just want to compile (generate a bitstream file), i suppose, you can just let the programmer field empty! And you will just not be able to run the upload function!
For consistency, i think it is better having all the icestudio available boards programmable with the upload button.
So i do not know if it is a very good idea to add an simple fpga (without a programmer)!
To be discussed!

Q7: PCF = Physical Constraint File for lattice chips. Basically, it defines how your top-level signals attach to fpga pins, and has lines like this:

set_io clk 78
set_io LED0 98
set_io LED1 99

a bit more info here: https://forum.mystorm.uk/t/syntax-of-pcf-file/383/5

Q8: No, the wiki indicates, correctly, thaht menu.json is in folder resources/boards/menu.json
Q9: Again without the hardware connected, you can do everything from synthesis,.., routing,... up to the bit-stream generation (.bit file)! Then you are stuck!
My advice, just get a board and play a bit with-it ! It is fun and motivating to see the result of our work on the real hardware! ;-)

Have a nice evening

[cavearr]

Hi @albatroxx ! i'm focusing in your issue i think with your help is a good moment to put on the top of the todo list this task that is stopped for a long time and every day is more important. Thanks a lot!

I dont have any bare fpga chip and i need your help to try and give us your feedback

Give me a little to return the source that i've been starting to code few months ago and i stopped to prioritize other tasks.

While i rescue it, i need some things for you:

1. Now you could synthetize your verilog with yosys suite? What commands do you use?
2. I don't understand well if you could upload bitstreams or you dont know how to do it. Could you clear it?