BeagleBoard/GSoC/PRU I2C-SPI master furtherwork - GSoC 2018

= Improvements to the PRU I2C/SPI Master Controller =

Student: Hernan Gonzalez Possible Mentors: Hunyue Yau, Zubeen Tolani Code: https://github.com/hgonzalez234/ Wiki: https://elinux.org/index.php?title=BeagleBoard/GSoC/PRU_I2C-SPI_master_furtherwork_-_GSoC_2018&action=edit

=Status= This project is based mainly on https://github.com/chanakya-vc/PRU-I2C_SPI_master, a 2016 GSoC project. This project is currently just a proposal.

=Proposal= I have completed the requirements listed on the ideas page and created a pull request here.

About me
IRC: hgonzalez Github: https://github.com/hernang234 School: Facultad de Ciencias Exactas, Ingeniería y Agrimensura, UNR, Rosario Country: Argentina Primary language: Spanish, English Typical work hours: 11:00 - 11:00 UTC Previous GSoC participation: This is my first GSoC participation. During my internship at VanguardiaSur, I worked on developing a UART driver for the Sitara platform on a BBB. This experience introduced me to the open source world and made me realize that I want to contribute back to the community and, if possible, make a career out of it. Working on the GSoC would be an ideal starting point.

About the project
Project name: Improve PRU SPI/I2C master controllers and provide a challenging application example

Description
The PRU is a hard realtime co-processor with dedicated realtime pins. Previous GSoC have created an assortment of examples and foundation pieces. One of these projects developed an SPI and an I2C master interfaces that can be bound with another peripheral via DT. However, there are several improvements to add to these drivers. The improvements include: Goal: Extend these drivers functionalities and provide an application example. The application example will be using the PRU as video capture interface and expose it through the v4l2 interface.
 * Multi-Slave Support: This can be achieved by reading from the device-tree and providing multiple CS pins via the num-cs parameter. Dynamic cs would also be nice to implement.
 * DMA data transfers: Currently the drivers implement reading and writing through ioread/iowrite which poses serious limitations to the amount of data that can be transferred from the driver to the firmware. DMA with its own clock would be more efficient and would consume less processor resources.
 * Configurable clock speeds.
 * Interrupts: Currently the driver and firmware are continuously polling flags set up in the shared memory in the PRU-ICSS to know when they should read the data buffer. Implementing interrupts could free the PRU and allow it to do other things.
 * SPI: Improve multibyte transfer: Some work remains to be done on the chip-select subroutine in the firmware so that CS does not toggle from low to high to low again after every 8 bits but after the entire data transfer is complete.
 * I2C: 10 bit addressing mode.
 * I2C: Multi-master support.

Implementation
The project can be divided into the following stages:

Get in-depth knowledge of how these drivers were implemented. They are well documented.
 * Study the old drivers

This shouldn't take too long, giving me time to focus on the application example.
 * Develop the improvements

This is not a simple task, but I consider it as pre-GSoC work. I will start studying it asap.
 * Study de v4l2 interface

I have no previous experience with v4l2, so I am not exactly sure which obstacles I will find on this road. Updates on this wiki will be made as I advance on my study on it. The choice between the SPI or I2C transfers will be done based on the camera available.
 * Write a camera PRU driver for the v4l2 interface

A first stage of the testing will be made when the improvements are finished. The application will require longer testing and debugging.
 * Testing

Extensive documentation of the process and use of the PRU will be written, as one of the goals of this project is to show the capabilities of the PRU. It is hard for someone just starting with the PRU to find and order the existent documentation as there are a lot of outdated examples out there.
 * Documentation & Debugging

Week 1-3: May 14 - June 3

 * Multi-Slave Support.
 * Interrupts.
 * SPI: Improve multibyte transfer.
 * I2C: 10 bit addressing mode.
 * I2C: Multi-master support.
 * DMA data transfers.

Week 4: June 4 - June 10

 * Test the new functionalities.

Weeks 5-8: June 11 - July 8

 * Develop the PRU/v4l2 camera driver.

Week 9-12: July 9 - August 5

 * Testing.
 * Debugging.
 * Cleanup Documentation. (Documentation will be written in parallel to the other activities to make sure that nothing gets forgotten, aiming to develop clear and extensive documentation as this should be accessible to PRU beginners too).
 * Buffer time.

Experience and approach
I am an Electronics Engineering student and, as such, I have coded a lot in Matlab, C and a bit of assembler. During my internship at VanguardiaSur, I worked on developing a UART driver for the Sitara platform, which has improved my C skills considerably and taught me a lot about Linux, Git and tools like Buildroot. For my thesis I am working with OpenCV (C++), gathering new image feature detectors, descriptors and matchers and implementing them - the ones that are not yet - in OpenCV, to try to improve a SLAM algorithm (S-PTAM). You can check some of my code (a couple of tools to test the UART driver) in my github profile. Even though I have been introduced to Linux only a year ago, I have got hugely interested in its inner workings. In that sense, I contributed with some simple patches to mainline Linux with the objective to learn how the process works, I installed Linux From Scratch as a learning experience and explored the Device Tree and the I2C and SPI user APIs on a BeagleBone Black and an Olimex A20-Olinuxino-Micro, getting to read a temperature sensor through I2C and running a small TFT display through SPI. With the display functioning, I got to run 2 simple games: a Game of Life C/SDL implementation and SuperTux. The challenge for the first one was to add it to Buildroot and for the second one, get ALSA working, plus a USB keyboard for both. I really enjoyed these bring-up experiences (short videos of them working ). I also got interested in the PRU when developing the UART driver during my internship, as the client had some realtime constraints. I started studying it and, even though I got some PRU examples working through the remoteproc/RPMsg framework like toggling a GPIO, the project was not long enough for an actual implementation. For these reasons, I would be honored to work with the BeagleBoard organization and I will be really motivated to learn more through this initiative.

Approach
I am currently working on my final thesis so I do not have classes to attend, giving me the opportunity to manage my own schedule. I also finish my internship at the end of March, freeing me to study things for the GSoC. I will have full-time, exclusive dedication to the GSoC during the 3 months that it lasts, working at least 40 hours per week.

Contingency
If I get stuck at some point in the project I will contact the organization administrator and mentors to talk about the issue and make sure the work is not delayed in the meantime by documenting and testing/debugging what has already been done. I also have a really nice relationship with my former employers, so, if really needed, I could ask them for pointers. The mailing lists and IRC channels are always a good place to ask for pointers too.

Benefit
The main objective of this project is to create a PRU soft-peripheral example that shows the PRU capabilities and also provides enough documentation to make similar projects accessible to the community.