BeagleBoard/GSoC/BeagleWire software support

Proposal template
Beagle Wire (FPGA cape) software support

The Lattice iCE40 is a family of FPGAs with a minimalistic architecture and very regular structure, designed for low-cost, high-volume consumer and system applications. The significance of FPGAs is continuously increasing, as they are more frequently used for supporting work of ARM processors. iCE40 doesn’t require external tools(JTAG) and the whole software is Open Source. iCE40 is an energy saving device thereby allowing to work with small batteries. FPGA cape allows easy and low cost start for beginners who would like to take their first steps regarding FPGAs. The developed software would be an easy and, at the same time, efficient tool for communication with FPGA. At this point FPGA would be able to meet the requirements of even more advanced applications. The BeagleWire cape with iCE40 device will be created soon with Michael Welling and the BeagleBoard.org community. Hardware Skills: Datasheet, Basic knowledge about FPGA devices, Software Skills: C programming/Linux Kernel Programming, HDL language(Verilog or VHDL) Possible Mentors: Michael Welling Upstream Repository: N/A References: icestorm projectlinux fpga subsystem documentation AM335x techincal reference manual Open-Source tools for FPGA development

About me
First name: Patryk Surname: Mężydło E-Mail: mezydlo.p@gmail.com IRC nickname: pmezydlo Programming Languages: C, C++, Python, Verilog, Assembler Interests and hobbies: Electronic, Embedded systems, FPGA, Judo, Walking Native language: Polish Other languages: English Timezone: CET ''GitHub: My Github profile Linkedin: My LinkedIn profile Work hours: 10:00-22:00 (CET) Previous GSoC participation: SPI slave driver implementation Currently I am in my third year of engineering studies at Gdańsk University of Technology in Poland. This is the second edition of GSoC in which I am participating. The first edition gave me the opportunity to gain a lot of valuable experience. I would like to continue my cooperation with BeagleBoard.org community. During the first edition I have been developing SPI_slave_driver_implementation project, which gave me a lot experience in the subject of linux drivers. I hope that this knowledge will prove to be helpful this year.

BeagleWire (FPGA cape)
The BeagleWire is an FPGA development platform that has been designed for use with BeagleBone boards. BeagleWire is a cape on which there is FPGA device - Lattice iCE40HX. The Lattice iCE40 is a family of FPGAs with a minimalistic architecture and very regular structure, designed for low-cost, high-volume consumer and system applications. The significance of FPGAs is continuously increasing, as they are more and more often used for supporting work of ARM processors. BeagleWire does not require external tools (JTAG) and the whole software is Open Source. iCE40 is an energy saving device, allowing to work with small batteries. FPGA cape allows easy and low cost start for beginners who would like to take their first steps in working with FPGAs. The developed software will be an easy and, at the same time, efficient tool for communication with FPGA. At this point FPGA will be able to meet the requirements of even more advanced applications. The BeagleWire creates a powerful and versatile digital cape for users to create their imaginative digital designs. BeagleWire features:
 * FPGA: Lattice iCE40HX4K - TQFP 144 Package,
 * 32 MB SDRAM,
 * BeagleBoard optimized,
 * GPIO,
 * 8x Leds,
 * 50Mhz external clock,
 * 4 layer PCB optimized design to support maximum performance for high bandwidth applications,
 * compatible with BeagleBone Black, BeagleBone Black Wireless, SeeedStudio BeagleBone Green, SeeedStudio BeagleBone Green Wireless, SanCloud BeagleBone Enhanced, element14 BeagleBone Black Industrial,
 * does not require external tools (JTAG),
 * minimalistic architecture and very regular structure,
 * energy saving device allows to work with small batteries,
 * lower application costs,
 * fully open-source toolchain,
 * SPI and GPMC port access from the Beaglebone,

BeagleWire software support
The task is to create software support for FPGA cape (based on iCE40 device). The completed project will provide the BeagleBoard.org community with easy to implement and powerful tools for realization of projects based on Programmable Logic Device(FPGA), which will surely increase the number of applications based on it. Although there already is a cape for BeagleBone involving FPGA device(LOGIBONE), LOGIBONE has several weaknesses which are not the case in FPGA cape based on iCE40 device.



BeagleWire software support project advantages:
 * fully open source software(synthesis HDL language),
 * easy to implement software,
 * many simple and more advanced examples,
 * extensive and comprehensive documentation on how to create application,
 * support for Python scripts (Python extension),
 * support for C application (C library),

Project implementation
Main Goals:
 * 1) Create the lowest layer of bridge driver,
 * 2) Create Verilog bridge module allowing to connect user's Verilog module with ARM processor,
 * 3) Support for IRQ signals in both directions (from and to FPGA),
 * 4) Integration of open source programming tools (iCE40 programming driver) with BeagleBone linux images (BeagleBone automatically loaded required DTS, EEPROM Cape, porting the icestorm toolchain to the BeagleBone Black),
 * 5) Create a TestBench files for bridge module using IceTime,
 * 6) Python Extension and C Library which allows easy to develop application using the FPGA (copying memory blocks, capture interrupts, etc),
 * 7) Verilog examples with testbenches,
 * 8) Extensive documentation,

Detailed description of each goal: 1. Create the lowest layer of bridge driver For communication between FPGA and ARM, I plan to use the GPMC. GPMC controller is configured from the DTS file. This is an easy and efficient solution. Gpmc pins are brought out to BeagleBone P8/P9 headers. AM335x datasheets: The general-purpose memory controller (GPMC)[1] is a unified memory controller dedicated to interfacing external memory devices: SRAM-like memories and application-specific integrated circuit (ASIC) devices, asynchronous, synchronous, and page mode (only available in non-multiplexed mode) burst NOR flash devices, NAND Flash, Pseudo-SRAM devices.

Connecting BeagleWire with BeagleBone:



Communication is going to be mapped in processor’s memory, thus allowing an easy access using simple read and write operations. Bridge device will be described in DTS file. The next task is to write kernel driver which will be connected to FPGA kernel subsystem(FPGA subsystem). After compiling an image with added modules (config file) and loading DTS, communication with FPGA is like a typical operation on a file (/dev/FPGA).

2.Create Verilog bridge module allowing to connect user's Verilog module with ARM processor The task is to create a module which is able to read GPMC interface signals, providing an easy way to the exchange of data with user's logic. I intended to create two different solutions. Unfortunately, the amount of logic in iCE40 is not too big, as in the largest version it is only 8000 LUTs. Solutions should be as optimal as possible, because I would not like to create a bridge module that would take up more than 10% of the FPGA logic.

First solution: The first solution involves mapping the external memory (SRAM or SDRAM) to ARM processor's memory. Bridge module receives signals from the GPMC interfaces and writes or reads data to external memory. User logic is given access to signals which enable reading and writing to external memory.

Second solution: The second solution uses much less logic than the previous solution. It consists of exchanging data directly from the GPMC bus. In this solution, we bypass the address. Coupled with the interrupt, this solution can work efficiently. The choice of solution depends on the user. They state it in DTS. 3.Support for IRQ signals in both directions (from and to FPGA) Two GPIOs from BeagleBone are intended for interrupts. Interrupts are receiving or generating from the userspace on ARM. IRQ signals will be connected directly to the user's logic and are reserved exclusively for user. During GSoC I do not plan to create additional modules generating interrupts, except if necessary.

4.Integration of open source programming tools (iCE40 programming driver) with BeagleBone linux images (BeagleBone automatically loads required DTS, EEPROM Cape, porting the IceStorm toolchain to the BeagleBone Black) All tools needed in order to work with iCE40 are Open Source, which is a great advantage. The process of generating a binary file for iCE40 consists of several steps. One stage is called RTL synthesis - with the use of Yosys, a blif file is generated from Verilog code. Arachne-pnr implements the place and route step of the hardware compilation process for FPGAs. Project IceStorm provides simple tools for analyzing and creating bitstream files. In this part of the project I intend to write a script which will help in the installation and use of the above mentioned tools. I think that the synthesis will be also possible on the ARM processor. BeagleWire has EEPROM memory which stores identification data. One of the integration steps is to create binary file for EEPROM. The cape EEPROM is being read by the BeagleBone Black during boot. This registration allows them to upload your settings to the latest operating system available. This removes the need for users to setup their board to use the cape.

5.Create a TestBench for bridge module using Icarus Verilog Each expensive verilog module has to be well proven. Verilog coding standard allows to create testbench files. Testbench’s great advantage is that it shows signal’s value as a function of time. There is an open source software which allows to create a timing analysis - it is a Icarus Verilog project. One of the project’s elements should be testbench files which will check if the bridge module works.

6.Python Extension and C Library enabling easier development of applications using the FPGA (copying memory blocks, capture interrupts, etc) C API is necessary for optimal use of the bridge and capturing or generating interrupts. However, I currently do not know which functions will be implemented. Easy to implement Python application is a great advantage of BeagleBoard platform. One of the goals is to create Python extension which would make it simpler to use the FPGA.

7.Verilog examples Basic applications like “Hello World” might be a good option for creating examples which in a simple way show how to use API. The level of each example will be different. Each example will contain the code in verilog and C or Python, description and testbench. List of examples:
 * 1) Blink leds (only Verilog),
 * 2) Blink leds controlled from userspace,
 * 3) GPIO control from userspace,
 * 4) External memory (only Verilog),
 * 5) Generating and receiving interrupts,
 * 6) Sharing SRAM or SDRAM memory,
 * 7) use of iCE40 PLL,
 * PWN,

Development timeline
Each week I will devote a few hours to write the documentation. 0. Before the first week (26 May - 28 May) 1. Week 1(6 June - 13 June) 2. Week 2(13 June - 20 June) 3. Week 3(20 June - 27 June) 4. Week 4(27 June - 4 July) 5. Week 5(4 July - 11 July) 6. Week 6(11 July - 18 July) 7. Week 7(18 July - 25 July) 8. Week 8(25 July - 1 August) 9. Week 9(1 August - 8 August) 10. Week 10(8 July - 15 August) 11. Week 11(15 August - 22 August) If time allows, these are the optional goals to realize during GSoC or after it has ended. After GSoC I will continue to develop the project.
 * create a GitHub repository,
 * prepare a few sd card with a Firmware Images,
 * installation of necessary software,
 * build a custom kernel image with iCE40-mgr driver,
 * create DTS file for programming interface,
 * write PCF file for BeagleWire,
 * form first verilog example(blink led),
 * first configuration of FPGA devices,
 * create script for installing toolchains on x86 and BeagleBone,
 * port the icestorm toolchain to BeagleBone,
 * begin work on GPMC configuration(DTS file),
 * all assumptions about the way of programming are ready
 * further work on GPMC configuration,
 * understand the GPMC signals
 * begin work on bridge module,
 * work on the second bridge module solution(described in detail above),
 * first bridge test using “/dev/mem/”
 * create SDRAM module
 * work on the first bridge module solutions(described in detail above),
 * final work on bridge,
 * test and debug bridge,
 * optimize performance bridge module (in terms of speed and LUTs use)
 * begin work on bridge driver,
 * improve and optimize bridge
 * final work on bridge driver,
 * create Makefile for bridge driver,
 * build own kernel version with fpga-bridge menager,
 * register own bridge,
 * create Kconfig for bridge driver,
 * add support for IRQ signals in both direction(fpga and arm),
 * begin work on C API,
 * create Python Extension,
 * create setup script,
 * work on examples,
 * gpio, pll, irq examples are ready,
 * further work on examples,
 * write bridge driver documentation,
 * release of the final version,
 * final work on documentation,
 * optimization of bridge module,
 * DMA support,
 * more examples,

What will help me in completion of the project
To successfully accomplish the project, I will do my best to thoroughly study the subject. More difficult parts of the project, such as, for instance, operating McSPI, can be made easier by maintaining a good contact with a mentor, regular commits and familiarizing with the documentation and ready solutions. Digital oscilloscope capable of decoding signals will help me in the process of debugging. '''I spent the last two years familiarizing myself with BeagleBone. During this time I was able to do the following:'''
 * compile the kernel, bootloader and device tree
 * submit compiled parts
 * eMMC and SD flash
 * write LKMs (kernel threads, interrupts, linux headers)
 * LKMs mechanism, kobjects, gpio, memory allocation,
 * write assembler and C code for PRU,
 * familiarize myself with remoteproc,
 * project some BeagleBone cape,
 * more, more...

Thoughts on the project, misc
FPGA board is rather expensive, as it requires the use of professional tools which price reaches up to $200. With the use of FPGA based on BeagleWire, the costs could be reduced by several times. I believe that reducing the costs will positively influence the community, as the board could be accessed by beginner programmers. Each project gives valuable experience to the BeagleBone community in the form of code, that, if well described, provides plenty of examples and ready solutions for other beginner programmers. If I encounter a problem and my mentor would be unavailable at the moment, the first thing I would do would be to try to find the reason behind this problem. Then I would try to do something else. The project consists of several components, so if I get stuck in one place, I will be able to continue work in another place. BeagleBoard is a large community, bringing together a large group of professionals with extensive experience. The other mentors could help me with solving a difficult problem in case if my mentor would not be available.