Blackice Mx ebook

[lawrie]

I have started producing a Blackice Mx version of my Programming Open Source FPGAs ebook.

A long way to go yet, so don't rely on its accuracy.

https://lawrie.github.io/blackicemxbook/

Let me know of any chapters or examples you would like to see.

I might add SpinalHDL, migen and nmigen examples.

[Elminster]

Ooh goodie, will have a read. SpinalHDL would be interesting, but in a sort of advanced section perhaps. As would probably just be confusing for a beginner. I,e. Me.

[Elminster]

Also if we spot typos how do you want us report? Could raise issue on github, or fork git and create a merge patch, report on here, or something else?

[lawrie]

I would wait a few days until I have a better version as I am finding issues and fixing them quickly myself at the moment.

Any ideas about what I should include would be appreciated though.

I am putting the examples in this repository - https://github.com/lawrie/blackicemx_examples/tree/master/ebook

[Elminster]

There are quite a few bits an pieces sprinkled around the fourm that would be useful in one place. Things that spring to mind of topics include:

• Other resources (we mentioned these in a thread)
• Tools & IDEs (and just mentioned in a thread)
• Risc V cores
• Upgrading the firmware
• Stuff you can do with the Arm processor, how to talk to it etc

I am sure there are other things but these are things I have either looked at or plan to look at myself, and I guess others would go through the same loop.

[lawrie]

Also if we spot typos how do you want us report? Could raise issue on github, or fork git and create a merge patch, report on here, or something else?

What pages did you find typos etc. on? I have updated a lot of pages this morning, so they might have gone.

[lawrie]

There are quite a few bits an pieces sprinkled around the fourm that would be useful in one place. Things that spring to mind of topics include:

Other resources (we mentioned these in a thread)
Tools & IDEs (and just mentioned in a thread)
Risc V cores
Upgrading the firmware
Stuff you can do with the Arm processor, how to talk to it etc

I am sure there are other things but these are things I have either looked at or plan to look at myself, and I guess others would go through the same loop

Thanks for that. I will add some of those. I

[Elminster]

What pages did you find typos etc. on? I have updated a lot of pages this morning, so they might have gone.

I will re-read it. I didnt note them down as you said you were going to be doing a lot of updates.

[lawrie]

I will re-read it. I didnt note them down as you said you were going to be doing a lot of updates.

I was mainly interested on what pages you were looking at so I could concentrate on those first.

[Aclassifier]

This is so great! Much of what I am after! I agree on the points already mentioned.

• xxMhz → xx MHz
• Navigation: enstead of having to always going down to the bottom then rather having Previous Up Next on the left panel? Always visible
• Or some sort of small Previous Up Next added also on the top.
• The last page has no Previous Up so it looks like I must use the browser's Back arrow
• Maybe some kind of glossary, like I just saw for the first time VSCode. It could have three categories: must have, nice to have and some have and then a dimension with opsys

Thanks for also pointing out the BlackIce wiki.

[Elminster]

I will re-read it. I didnt note them down as you said you were going to be doing a lot of updates.

I was mainly interested in what pages you were looking at so I could concentrate on those first.

Assume you want posted here?

Intro page
the typos all seem fixed.

Hardware pages

This sentence:

There are two PLLs and 960 Programmable Logic Blocks (PLLs) which each consist of a 4 input look-up table (4-LUT) and a 1-bit D flip-flop. There are 32 blocks, each of 512 bytes, giving a total of 16kb of BRAM.

1. Should that read PLB? for Programmable Logic Blocks?
2. I assume that should be 16KB or 16kB as it is bytes and not bits.?

Also, I know you did do the pictures but might be useful to add on either the photo or block diagram, which USB port is which, I know when I started I kept getting them mixed up, and getting a mag glass out to read the writing on the board.

Programming Built in Hardware
Few more in this one (I am being nit-picky but might as well do them, most are just consistent capitalisation of LEDs):

This is because of thec way that the user LEDs are wired on the Blackice Mx iceCore board.

Note that button 1 is wired to the blue user led and button 2 to the green user led, so that thoses LEDs come on when you press the appropriate button.

You don’t need to use Verilog to set an LED when a button is pressed as the buttons are wired to the blue and green LEDS. But if you wanted to set one of the other two LEDs when the button is prsssed, this is how you do it:

Note that -pullup yes is used in the pcf file for the button. Although the Blackice Mx has a pullup resistor on the button, because of the way the buttons are wired to the blue and green user LEDs, that resistore is not sufficient to get reliable signals from a button press, so the internal resistor needs to be enabled.

Note also that the button signal will be high by default and low when the button is prsssed, and that the user leds are set on when their output signal is low, and off when it is high. So no negation is needed when setting the LED signal from the button signal.

Build and upload in the normal way and you should see the led counter increasing by more than one per press.

When you make and run this you should see the led counter increase by 1 for each button press.

Memory

The internal memory in the Ice40 FPGA is known as Block RAM or BRAM. There is 16kb of it in 32 banks of 512 bytes.

a Verilog module examines the address and decides whether to map it to SDRAM or BRAM or flash memory, or to interpret it as an a read or write to other hardware.

Soft Processors
Not much wrong here that I could see:

There is a professional open source ISA called Risc-V. It is well supported by gnu tool chains and can be considered as an open source alternative to the ARM family of ISAs.

There were just 32 words of 32-but data in the first implementation of the BABy, otherwise known as the Small Scale Experimental Machine.

General
Nice to have: Would be good to repeat the content/topics section from the first page in the sidebar, and for it to high light which one you are on.

But very good. I still have to read the other pages. If only you had converted it two months ago

[Elminster]

This is so great! Much of what I am after! I agree on the points already mentioned.

* xxMhz → xx MHz
* Navigation: enstead of having to always going down to the bottom then rather having Previous Up Next on the left panel? Always visible
* Or some sort of small Previous Up Next added also on the top.
* The last page has no Previous Up so it looks like I must use the browser's Back arrow
* Maybe some kind of glossary, like I just saw for the first time VSCode. It could have three categories: must have, nice to have and some have and then a dimension with opsys

Thanks for also pointing out the BlackIce wiki.

I think only first two pages have the Previous/Up/Next bit. So I would agree outside of the main aim of the context, the next thing would be just to make the navigation a bit easier.

[lawrie]

Navigation: enstead of having to always going down to the bottom then rather having Previous Up Next on the left panel? Always visible
Or some sort of small Previous Up Next added also on the top.
The last page has no Previous Up so it looks like I must use the browser's Back arrow

The Blackice II version did not have any navigation, and I am just experimenting with the best way of doing it. I do plan to add those features. I think I would have to change the theme to put navigation in the side panel, and I am more interested in adding content at the moment rather than experimenting with that, so I will probably add navigation to the top.

[Aclassifier]

Blackice II version

Where is it? Would be nice to know.

[lawrie]

There was the github version, an online Microsoft Word version and a gitbooks version.

[lawrie]

But very good. I still have to read the other pages. If only you had converted it two months ago

Thanks for all those typos. I think I have fixed them. I still need to decide how best to indicate which usb port is which and how to best do the navigation.

I have now moved the examples from the blackice_examples repository into this one.

A lot of the latest pages I have added have only been partially changed from the Blackice II version. I am working on them.

[piers]

I started to look into https://readthedocs.org/ when I couldn't work out how to modify the theme to add navigation (it can use markdown but prefers reStructuredText).

It looks like you have made progress on adding navigation, I found it frustrated progress - modifying the content is much more rewarding!

Theme selection can help greatly here, but modifying a theme you like the look of to incorporate features from another theme requires acquiring yet more threads of knowledge.

Another topic area for your book could be setting up an environment to modify the stm32 code (almost certainly an advanced topic). @Folknology may have some useful info here.

If there are enough parallels between the BlaceIce and BlackIce Mx, could you extend your BlackIce book with sub-sections on some (most?) pages highlighting the differences ... that might make it easier to maintain and perhaps expand as Alan extends the range. If there are too many differences / new ways to do things (and the likelihood of updates to your original work diminish) then creating it as a separate book makes more sense.

If it's in the same repo you might be able to share some pages so more tedious edits (like improving capitalisation consistency) can be reduced ... though if the page names are the same a friendly code monkey with a tiny bit of free time could volunteer to help! (writing this whilst getting my son back to sleep, not sure if that counts as free time ...)

An introductory section breaking the book into 'getting started / beginner projects', 'more advanced projects', 'softcores and retro computers' and 'beyond verilog - using higher level languages to simplify more complex projects'

Are there any sections that others could write /contribute to? Toolchains / IDEs could be a recently discussed area that others have provided useful explanations of.

[lawrie]

I started to look into https://readthedocs.org/ when I couldn't work out how to modify the theme to add navigation (it can use markdown but prefers reStructuredText).

I will have a look at that.

It looks like you have made progress on adding navigation, I found it frustrated progress - modifying the content is much more rewarding!

Yes, I agree. I prefer to get on with the content rather than wrestle with the tools.

I have found a rather crude way to add some navigation using markdown.

Theme selection can help greatly here, but modifying a theme you like the look of to incorporate features from another theme requires acquiring yet more threads of knowledge.

I tried a few others themes and they looked worse than the Dinky one you used and didn't seem to help with navigation, so I stuck with Dinky.

Another topic area for your book could be setting up an environment to modify the stm32 code (almost certainly an advanced topic). @Folknology may have some useful info here.

Yes, I will add such a section.

If there are enough parallels between the BlaceIce and BlackIce Mx, could you extend your BlackIce book with sub-sections on some (most?) pages highlighting the differences ... that might make it easier to maintain and perhaps expand as Alan extends the range. If there are too many differences / new ways to do things (and the likelihood of updates to your original work diminish) then creating it as a separate book makes more sense.

I am unsure about this as really I would like to extend the book to other boards like the TinyFPGA BX, iCeBreaker etc., as well. As all these open source boards have advantages and disadvantages. But the difference are big enough that a book that covers a lot of them becomes hard to read. The first book on Verilog I read was Simon Monk's book, and that covered three boards (none of them open source), which made it a bit hard to read. Perhaps I need some sort of conditional generation for the book.

An introductory section breaking the book into 'getting started / beginner projects', 'more advanced projects', 'softcores and retro computers' and 'beyond verilog - using higher level languages to simplify more complex projects'

I will think about how to this. I agree the book needs more structure.

Are there any sections that others could write /contribute to? Toolchains / IDEs could be a recently discussed area that others have provided useful explanations of.

There are lots of sections people could contribute.

Some possibilities are:

• Running on Windows, e.g. using apio or WSL
• Running on MAC - e.g. what changes are needed for make files etc.
• Using specific IDEs such as Atom, or Visual Studio
• A repository with examples from Simon Monk's book that run on Blackice Mx
• Using migen and litex and possibly nmigen
• Other HDLs, e,g. clash and Chisel
• Using formal methods
• Using a Wishbone Bus
• Using specific Pmods if people have one that I don't
• Using icestudio
• More detail on how the icestorm tools work
• Using Verilator
• How to access the SDRAM for maximum throughput or lowest latency (really needs an example like @TomV wrote for the Sram on the Blackice II)
• How to make carrier boards (with Kicad examples?)
• How to make Pmods/Mixmods (with Kicad examples)
• Communication between the STM32 and the ice40
• How to avoid design errors in Verilog
• Cross clock domain working

[Elminster]

Obvious we all have time constraints, but assuming people found time how would the contributions be managed. By forking github, or by writing stuff and sending to you? And how would people indicate they were working on something? i.e. dont want 6 people working on the samething at the same time.

Probably useful if I wrote up what I did for Atom Ed. as then if I ever need to rebuild it I have a fighting chance of remembering.

Either way I should have time to read and feedback corrections if nothign else.

[lawrie]

Obvious we all have time constraints, but assuming people found time how would the contributions be managed. By forking github, or by writing stuff and sending to you? And how would people indicate they were working on something? i.e. dont want 6 people working on the samething at the same time.

A fork and a pull request might be easiest. For the moment people could use this thread to indicate what they are working on.

Probably useful if I wrote up what I did for Atom Ed. as then if I ever need to rebuild it I have a fighting chance of remembering

Yes that would be useful. Documenting the stuff for myself is a big part of why I write the ebook.

I am currently working on the audio page and examples.